1ARES_INIT(3)               Library Functions Manual               ARES_INIT(3)
2
3
4

NAME

6       ares_init_options - Initialize a resolver channel
7

SYNOPSIS

9       #include <ares.h>
10
11       struct ares_options {
12         int flags;
13         int timeout; /* in seconds or milliseconds, depending on options */
14         int tries;
15         int ndots;
16         unsigned short udp_port;
17         unsigned short tcp_port;
18         int socket_send_buffer_size;
19         int socket_receive_buffer_size;
20         struct in_addr *servers;
21         int nservers;
22         char **domains;
23         int ndomains;
24         char *lookups;
25         ares_sock_state_cb sock_state_cb;
26         void *sock_state_cb_data;
27         struct apattern *sortlist;
28         int nsort;
29         int ednspsz;
30         char *resolvconf_path;
31       };
32
33       int ares_init_options(ares_channel *channelptr,
34                             struct ares_options *options,
35                             int optmask)
36

DESCRIPTION

38       The  ares_init_options(3) function initializes a communications channel
39       for   name   service   lookups.    If    it    returns    successfully,
40       ares_init_options(3)  will set the variable pointed to by channelptr to
41       a handle used to identify the name service channel.  The caller  should
42       invoke  ares_destroy(3)  on  the  handle  when the channel is no longer
43       needed.
44
45       The optmask parameter generally specifies which fields in the structure
46       pointed to by options are set, as follows:
47
48       ARES_OPT_FLAGS    int flags;
49                         Flags  controlling the behavior of the resolver.  See
50                         below for a description of possible flag values.
51
52       ARES_OPT_TIMEOUT  int timeout;
53                         The number of seconds each name server  is  given  to
54                         respond  to  a  query  on  the first try.  (After the
55                         first try, the timeout algorithm becomes more compli‐
56                         cated,  but  scales  linearly with the value of time‐
57                         out.)  The default is five seconds.  This  option  is
58                         being deprecated by ARES_OPT_TIMEOUTMS starting in c-
59                         ares 1.5.2.
60
61       ARES_OPT_TIMEOUTMS
62                         int timeout;
63                         The number of milliseconds each name server is  given
64                         to  respond  to a query on the first try.  (After the
65                         first try, the timeout algorithm becomes more compli‐
66                         cated,  but  scales  linearly with the value of time‐
67                         out.)  The default is five seconds.  Note  that  this
68                         option is specified with the same struct field as the
69                         former ARES_OPT_TIMEOUT, it is but  the  option  bits
70                         that  tell  c-ares  how to interpret the number. This
71                         option was added in c-ares 1.5.2.
72
73       ARES_OPT_TRIES    int tries;
74                         The number of tries the resolver will try  contacting
75                         each  name  server  before giving up.  The default is
76                         four tries.
77
78       ARES_OPT_NDOTS    int ndots;
79                         The number of dots which must be present in a  domain
80                         name for it to be queried for "as is" prior to query‐
81                         ing  for  it  with  the  default  domain   extensions
82                         appended.   The  default value is 1 unless set other‐
83                         wise by resolv.conf or  the  RES_OPTIONS  environment
84                         variable.
85
86       ARES_OPT_UDP_PORT unsigned short udp_port;
87                         The port to use for queries over UDP, in network byte
88                         order.  The default value  is  53  (in  network  byte
89                         order), the standard name service port.
90
91       ARES_OPT_TCP_PORT unsigned short tcp_port;
92                         The port to use for queries over TCP, in network byte
93                         order.  The default value  is  53  (in  network  byte
94                         order), the standard name service port.
95
96       ARES_OPT_SERVERS  struct in_addr *servers;
97                         int nservers;
98                         The  list  of IPv4 servers to contact, instead of the
99                         servers specified in resolv.conf or the local  named.
100                         In  order  to  allow  specification of either IPv4 or
101                         IPv6 name servers, the  ares_set_servers(3)  function
102                         must be used instead.
103
104       ARES_OPT_DOMAINS  char **domains;
105                         int ndomains;
106                         The  domains to search, instead of the domains speci‐
107                         fied in resolv.conf or the domain  derived  from  the
108                         kernel hostname variable.
109
110       ARES_OPT_LOOKUPS  char *lookups;
111                         The  lookups  to  perform  for host queries.  lookups
112                         should be set to a string of the  characters  "b"  or
113                         "f",  where  "b" indicates a DNS lookup and "f" indi‐
114                         cates a lookup in the hosts file.
115
116       ARES_OPT_SOCK_STATE_CB
117                         void   (*sock_state_cb)(void   *data,   ares_socket_t
118                         socket_fd, int readable, int writable);
119                         void *sock_state_cb_data;
120                         A  callback  function  to  be  invoked  when a socket
121                         changes state.  socket_fd will be passed  the  socket
122                         whose state has changed; readable will be set to true
123                         if the socket should  listen  for  read  events,  and
124                         writable  will  be  set  to true if the socket should
125                         listen   for   write   events.     The    value    of
126                         sock_state_cb_data  will  be passed as the data argu‐
127                         ment.
128
129       ARES_OPT_SORTLIST struct apattern *sortlist;
130                         int nsort;
131                         A list of IP address ranges that specifies the  order
132                         of  preference  that  results from ares_gethostbyname
133                         should be returned in.  Note that this  can  only  be
134                         used     with     a     sortlist     retrieved    via
135                         ares_save_options(3)  (because  struct  apattern   is
136                         opaque);    to   set   a   fresh   sort   list,   use
137                         ares_set_sortlist(3).
138
139       ARES_OPT_SOCK_SNDBUF
140                         int socket_send_buffer_size;
141                         The send buffer size to set for the socket.
142
143       ARES_OPT_SOCK_RCVBUF
144                         int socket_receive_buffer_size;
145                         The receive buffer size to set for the socket.
146
147       ARES_OPT_EDNSPSZ  int ednspsz;
148
149       ARES_OPT_RESOLVCONF
150                         char *resolvconf_path; The path to  use  for  reading
151                         the  resolv.conf  file. The resolvconf_path should be
152                         set to a path string, and will be  honoured  on  *nix
153                         like systems. The default is /etc/resolv.conf
154                         The message size to be advertized in EDNS; only takes
155                         effect if the ARES_FLAG_EDNS flag is set.
156
157       The optmask parameter also includes  options  without  a  corresponding
158       field in the ares_options structure, as follows:
159
160       ARES_OPT_ROTATE        Perform round-robin selection of the nameservers
161                              configured for the channel for each resolution.
162
163       ARES_OPT_NOROTATE      Do not perform round-robin nameserver selection;
164                              always  use  the list of nameservers in the same
165                              order.
166
167       The flags field should be the bitwise or of some subset of the  follow‐
168       ing values:
169
170       ARES_FLAG_USEVC        Always  use  TCP queries (the "virtual circuit")
171                              instead of UDP queries.  Normally, TCP  is  only
172                              used if a UDP query yields a truncated result.
173
174       ARES_FLAG_PRIMARY      Only  query  the  first  server  in  the list of
175                              servers to query.
176
177       ARES_FLAG_IGNTC        If a  truncated  response  to  a  UDP  query  is
178                              received,  do  not fall back to TCP; simply con‐
179                              tinue on with the truncated response.
180
181       ARES_FLAG_NORECURSE    Do not set the "recursion desired" bit on outgo‐
182                              ing  queries, so that the name server being con‐
183                              tacted will not try to  fetch  the  answer  from
184                              other  servers  if  it  doesn't  know the answer
185                              locally. Be aware that  ares  will  not  do  the
186                              recursion for you.  Recursion must be handled by
187                              the application calling ares if  ARES_FLAG_NORE‐
188                              CURSE is set.
189
190       ARES_FLAG_STAYOPEN     Do  not  close  communications  sockets when the
191                              number of active queries drops to zero.
192
193       ARES_FLAG_NOSEARCH     Do not use  the  default  search  domains;  only
194                              query hostnames as-is or as aliases.
195
196       ARES_FLAG_NOALIASES    Do  not  honor the HOSTALIASES environment vari‐
197                              able, which normally specifies a file  of  host‐
198                              name translations.
199
200       ARES_FLAG_NOCHECKRESP  Do  not  discard  responses  with  the SERVFAIL,
201                              NOTIMP, or REFUSED response  code  or  responses
202                              whose questions don't match the questions in the
203                              request.  Primarily useful for  writing  clients
204                              which  might  be  used  to  test  or  debug name
205                              servers.
206
207       ARES_FLAG_EDNS         Include  an  EDNS  pseudo-resource  record  (RFC
208                              2671) in generated requests.
209

RETURN VALUES

211       ares_init_options(3) can return any of the following values:
212
213       ARES_SUCCESS  Initialization succeeded.
214
215       ARES_EFILE    A configuration file could not be read.
216
217       ARES_ENOMEM   The process's available memory was exhausted.
218
219       ARES_ENOTINITIALIZED
220                     c-ares library initialization not yet performed.
221

NOTES

223       When initializing from /etc/resolv.conf, (or, alternatively when speci‐
224       fied by the resolvconf_path path location)  ares_init_options(3)  reads
225       the  domain and search directives to allow lookups of short names rela‐
226       tive to the domains specified. The domain and search  directives  over‐
227       ride  one another. If more that one instance of either domain or search
228       directives is specified, the last occurrence wins.  For  more  informa‐
229       tion, please see the resolv.conf(5) manual page.
230

SEE ALSO

232       ares_init(3),   ares_destroy(3),   ares_dup(3),   ares_library_init(3),
233       ares_save_options(3), ares_set_servers(3), ares_set_sortlist(3)
234

AUTHOR

236       Greg Hudson, MIT Information Systems
237       Copyright 1998 by the Massachusetts Institute of Technology.
238       Copyright (C) 2004-2010 by Daniel Stenberg.
239
240
241
242                                 5 March 2010                     ARES_INIT(3)
Impressum