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                         The message size to be advertized in EDNS; only takes
149                         effect if the ARES_FLAG_EDNS flag is set.
150
151       ARES_OPT_RESOLVCONF
152                         char *resolvconf_path;
153                         The path to use for reading the resolv.conf file. The
154                         resolvconf_path should be set to a path  string,  and
155                         will be honoured on *nix like systems. The default is
156                         /etc/resolv.conf
157
158       The optmask parameter also includes  options  without  a  corresponding
159       field in the ares_options structure, as follows:
160
161       ARES_OPT_ROTATE        Perform round-robin selection of the nameservers
162                              configured for the channel for each resolution.
163
164       ARES_OPT_NOROTATE      Do not perform round-robin nameserver selection;
165                              always  use  the list of nameservers in the same
166                              order.
167
168       The flags field should be the bitwise or of some subset of the  follow‐
169       ing values:
170
171       ARES_FLAG_USEVC        Always  use  TCP queries (the "virtual circuit")
172                              instead of UDP queries.  Normally, TCP  is  only
173                              used if a UDP query yields a truncated result.
174
175       ARES_FLAG_PRIMARY      Only  query  the  first  server  in  the list of
176                              servers to query.
177
178       ARES_FLAG_IGNTC        If a  truncated  response  to  a  UDP  query  is
179                              received,  do  not fall back to TCP; simply con‐
180                              tinue on with the truncated response.
181
182       ARES_FLAG_NORECURSE    Do not set the "recursion desired" bit on outgo‐
183                              ing  queries, so that the name server being con‐
184                              tacted will not try to  fetch  the  answer  from
185                              other  servers  if  it  doesn't  know the answer
186                              locally. Be aware that  ares  will  not  do  the
187                              recursion for you.  Recursion must be handled by
188                              the application calling ares if  ARES_FLAG_NORE‐
189                              CURSE is set.
190
191       ARES_FLAG_STAYOPEN     Do  not  close  communications  sockets when the
192                              number of active queries drops to zero.
193
194       ARES_FLAG_NOSEARCH     Do not use  the  default  search  domains;  only
195                              query hostnames as-is or as aliases.
196
197       ARES_FLAG_NOALIASES    Do  not  honor the HOSTALIASES environment vari‐
198                              able, which normally specifies a file  of  host‐
199                              name translations.
200
201       ARES_FLAG_NOCHECKRESP  Do  not  discard  responses  with  the SERVFAIL,
202                              NOTIMP, or REFUSED response  code  or  responses
203                              whose questions don't match the questions in the
204                              request.  Primarily useful for  writing  clients
205                              which  might  be  used  to  test  or  debug name
206                              servers.
207
208       ARES_FLAG_EDNS         Include  an  EDNS  pseudo-resource  record  (RFC
209                              2671) in generated requests.
210

RETURN VALUES

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

NOTES

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

SEE ALSO

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

AUTHOR

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