ares_init.3

   1 .\"
   2 .\" Copyright 1998 by the Massachusetts Institute of Technology.
   3 .\" Copyright (C) 2004-2010 by Daniel Stenberg
   4 .\"
   5 .\" Permission to use, copy, modify, and distribute this
   6 .\" software and its documentation for any purpose and without
   7 .\" fee is hereby granted, provided that the above copyright
   8 .\" notice appear in all copies and that both that copyright
   9 .\" notice and this permission notice appear in supporting
  10 .\" documentation, and that the name of M.I.T. not be used in
  11 .\" advertising or publicity pertaining to distribution of the
  12 .\" software without specific, written prior permission.
  13 .\" M.I.T. makes no representations about the suitability of
  14 .\" this software for any purpose.  It is provided "as is"
  15 .\" without express or implied warranty.
  16 .\"
  17 .TH ARES_INIT 3 "5 March 2010"
  18 .SH NAME
  19 ares_init, ares_init_options \- Initialize a resolver channel
  20 .SH SYNOPSIS
  21 .nf
  22 .B #include <ares.h>
  23 .PP
  24 .B int ares_init(ares_channel *\fIchannelptr\fP)
  25 .B int ares_init_options(ares_channel *\fIchannelptr\fP,
  26 .B      struct ares_options *\fIoptions\fP, int \fIoptmask\fP)
  27 .PP
  28 .B cc file.c -lcares
  29 .fi
  30 .SH DESCRIPTION
  31 The \fBares_init\fP function initializes a communications channel for name
  32 service lookups.  If it returns successfully, \fBares_init\fP will set the
  33 variable pointed to by \fIchannelptr\fP to a handle used to identify the name
  34 service channel.  The caller should invoke
  35 .BR ares_destroy (3)
  36 on the handle when the channel is no longer needed.
  37 .PP
  38 The \fBares_init_options\fP function also initializes a name service channel,
  39 with additional options useful for applications requiring more control over
  40 name service configuration. The \fIoptmask\fP parameter specifies which fields
  41 in the structure pointed to by \fIoptions\fP are set, as follows:
  42 .TP 18
  43 .B ARES_OPT_FLAGS
  44 .B int \fIflags\fP;
  45 .br
  46 Flags controlling the behavior of the resolver.  See below for a
  47 description of possible flag values.
  48 .TP 18
  49 .B ARES_OPT_TIMEOUT
  50 .B int \fItimeout\fP;
  51 .br
  52 The number of seconds each name server is given to respond to a query on the
  53 first try.  (After the first try, the timeout algorithm becomes more
  54 complicated, but scales linearly with the value of \fItimeout\fP.)  The
  55 default is five seconds. This option is being deprecated by
  56 \fIARES_OPT_TIMEOUTMS\fP starting in c-ares 1.5.2.
  57 .TP 18
  58 .B ARES_OPT_TIMEOUTMS
  59 .B int \fItimeout\fP;
  60 .br
  61 The number of milliseconds each name server is given to respond to a query on
  62 the first try.  (After the first try, the timeout algorithm becomes more
  63 complicated, but scales linearly with the value of \fItimeout\fP.)  The
  64 default is five seconds. Note that this option is specified with the same
  65 struct field as the former \fIARES_OPT_TIMEOUT\fP, it is but the option bits
  66 that tell c-ares how to interpret the number. This option was added in c-ares
  67 1.5.2.
  68 .TP 18
  69 .B ARES_OPT_TRIES
  70 .B int \fItries\fP;
  71 .br
  72 The number of tries the resolver will try contacting each name server
  73 before giving up.  The default is four tries.
  74 .TP 18
  75 .B ARES_OPT_NDOTS
  76 .B int \fIndots\fP;
  77 .br
  78 The number of dots which must be present in a domain name for it to be
  79 queried for "as is" prior to querying for it with the default domain
  80 extensions appended.  The default value is 1 unless set otherwise by
  81 resolv.conf or the RES_OPTIONS environment variable.
  82 .TP 18
  83 .B ARES_OPT_PORT
  84 .B unsigned short \fIport\fP;
  85 .br
  86 The port to use for queries (both TCP and UDP), in network byte order.
  87 The default value is 53 (in network byte order), the standard name
  88 service port.
  89 .TP 18
  90 .B ARES_OPT_SERVERS
  91 .B struct in_addr *\fIservers\fP;
  92 .br
  93 .B int \fInservers\fP;
  94 .br
  95 The list of IPv4 servers to contact, instead of the servers specified in
  96 resolv.conf or the local named. In order to allow specification of either
  97 IPv4 or IPv6 name servers, the
  98 .BR ares_set_servers(3)
  99 function must be used instead.
 100 .TP 18
 101 .B ARES_OPT_DOMAINS
 102 .B char **\fIdomains\fP;
 103 .br
 104 .B int \fIndomains\fP;
 105 .br
 106 The domains to search, instead of the domains specified in resolv.conf
 107 or the domain derived from the kernel hostname variable.
 108 .TP 18
 109 .B ARES_OPT_LOOKUPS
 110 .B char *\fIlookups\fP;
 111 .br
 112 The lookups to perform for host queries.
 113 .I lookups
 114 should be set to a string of the characters "b" or "f", where "b"
 115 indicates a DNS lookup and "f" indicates a lookup in the hosts file.
 116 .TP 18
 117 .B ARES_OPT_SOCK_STATE_CB
 118 .B void (*\fIsock_state_cb\fP)(void *data, int s, int read, int write);
 119 .br
 120 .B void *\fIsock_state_cb_data\fP;
 121 .br
 122 A callback function to be invoked when a socket changes state.
 123 .I s
 124 will be passed the socket whose state has changed;
 125 .I read
 126 will be set to true if the socket should listen for read events, and
 127 .I write
 128 will be set to true if the socket should listen for write events.
 129 The value of
 130 .I sock_state_cb_data
 131 will be passed as the
 132 .I data
 133 argument.
 134 .PP
 135 The
 136 .I flags
 137 field should be the bitwise or of some subset of the following values:
 138 .TP 23
 139 .B ARES_FLAG_USEVC
 140 Always use TCP queries (the "virtual circuit") instead of UDP
 141 queries.  Normally, TCP is only used if a UDP query yields a truncated
 142 result.
 143 .TP 23
 144 .B ARES_FLAG_PRIMARY
 145 Only query the first server in the list of servers to query.
 146 .TP 23
 147 .B ARES_FLAG_IGNTC
 148 If a truncated response to a UDP query is received, do not fall back
 149 to TCP; simply continue on with the truncated response.
 150 .TP 23
 151 .B ARES_FLAG_NORECURSE
 152 Do not set the "recursion desired" bit on outgoing queries, so that the name
 153 server being contacted will not try to fetch the answer from other servers if
 154 it doesn't know the answer locally. Be aware that ares will not do the
 155 recursion for you.  Recursion must be handled by the application calling ares
 156 if \fIARES_FLAG_NORECURSE\fP is set.
 157 .TP 23
 158 .B ARES_FLAG_STAYOPEN
 159 Do not close communications sockets when the number of active queries
 160 drops to zero.
 161 .TP 23
 162 .B ARES_FLAG_NOSEARCH
 163 Do not use the default search domains; only query hostnames as-is or
 164 as aliases.
 165 .TP 23
 166 .B ARES_FLAG_NOALIASES
 167 Do not honor the HOSTALIASES environment variable, which normally
 168 specifies a file of hostname translations.
 169 .TP 23
 170 .B ARES_FLAG_NOCHECKRESP
 171 Do not discard responses with the SERVFAIL, NOTIMP, or REFUSED
 172 response code or responses whose questions don't match the questions
 173 in the request.  Primarily useful for writing clients which might be
 174 used to test or debug name servers.
 175 .SH RETURN VALUES
 176 .I ares_init
 177 or
 178 .I ares_init_options
 179 can return any of the following values:
 180 .TP 14
 181 .B ARES_SUCCESS
 182 Initialization succeeded.
 183 .TP 14
 184 .B ARES_EFILE
 185 A configuration file could not be read.
 186 .TP 14
 187 .B ARES_ENOMEM
 188 The process's available memory was exhausted.
 189 .TP 14
 190 .B ARES_ENOTINITIALIZED
 191 c-ares library initialization not yet performed.
 192 .SH NOTES
 193 When initializing from
 194 .B /etc/resolv.conf,
 195 .BR ares_init (3)
 196 reads the
 197 .I domain
 198 and
 199 .I search
 200 directives to allow lookups of short names relative to the domains
 201 specified. The
 202 .I domain
 203 and
 204 .I search
 205 directives override one another. If more that one instance of either
 206 .I domain
 207 or
 208 .I search
 209 directives is specified, the last occurence wins. For more information,
 210 please see the
 211 .BR resolv.conf (5)
 212 manual page.
 213 .SH SEE ALSO
 214 .BR ares_destroy(3),
 215 .BR ares_dup(3),
 216 .BR ares_library_init(3),
 217 .BR ares_set_servers(3)
 218 .SH AUTHOR
 219 Greg Hudson, MIT Information Systems
 220 .br
 221 Copyright 1998 by the Massachusetts Institute of Technology.
 222 .br
 223 Copyright (C) 2004-2010 by Daniel Stenberg.