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

NAME

6       ares_init, ares_init_options - Initialize a resolver channel
7

SYNOPSIS

9       #include <ares.h>
10
11       int ares_init(ares_channel *channelptr)
12       int ares_init_options(ares_channel *channelptr,
13            struct ares_options *options, int optmask)
14
15       cc file.c -lcares
16

DESCRIPTION

18       The  ares_init  function  initializes a communications channel for name
19       service lookups.  If it returns successfully, ares_init  will  set  the
20       variable pointed to by channelptr to a handle used to identify the name
21       service channel.  The caller should invoke ares_destroy(3) on the  han‐
22       dle when the channel is no longer needed.
23
24       The ares_init_options function also initializes a name service channel,
25       with additional options useful for applications requiring more  control
26       over  name service configuration. The optmask parameter specifies which
27       fields in the structure pointed to by options are set, as follows:
28
29       ARES_OPT_FLAGS    int flags;
30                         Flags controlling the behavior of the resolver.   See
31                         below for a description of possible flag values.
32
33       ARES_OPT_TIMEOUT  int timeout;
34                         The  number  of  seconds each name server is given to
35                         respond to a query on  the  first  try.   (After  the
36                         first try, the timeout algorithm becomes more compli‐
37                         cated, but scales linearly with the  value  of  time‐
38                         out.)   The  default  is five seconds. This option is
39                         being deprecated by ARES_OPT_TIMEOUTMS starting in c-
40                         ares 1.5.2.
41
42       ARES_OPT_TIMEOUTMS
43                         int timeout;
44                         The  number of milliseconds each name server is given
45                         to respond to a query on the first try.   (After  the
46                         first try, the timeout algorithm becomes more compli‐
47                         cated, but scales linearly with the  value  of  time‐
48                         out.)   The  default  is five seconds. Note that this
49                         option is specified with the same struct field as the
50                         former  ARES_OPT_TIMEOUT,  it  is but the option bits
51                         that tell c-ares how to interpret  the  number.  This
52                         option was added in c-ares 1.5.2.
53
54       ARES_OPT_TRIES    int tries;
55                         The  number of tries the resolver will try contacting
56                         each name server before giving up.   The  default  is
57                         four tries.
58
59       ARES_OPT_NDOTS    int ndots;
60                         The  number of dots which must be present in a domain
61                         name for it to be queried for "as is" prior to query‐
62                         ing   for  it  with  the  default  domain  extensions
63                         appended.  The default value is 1 unless  set  other‐
64                         wise  by  resolv.conf  or the RES_OPTIONS environment
65                         variable.
66
67       ARES_OPT_PORT     unsigned short port;
68                         The port to use for queries (both TCP  and  UDP),  in
69                         network byte order.  The default value is 53 (in net‐
70                         work byte order), the standard name service port.
71
72       ARES_OPT_SERVERS  struct in_addr *servers;
73                         int nservers;
74                         The list of IPv4 servers to contact, instead  of  the
75                         servers  specified in resolv.conf or the local named.
76                         In order to allow specification  of  either  IPv4  or
77                         IPv6  name  servers, the ares_set_servers(3) function
78                         must be used instead.
79
80       ARES_OPT_DOMAINS  char **domains;
81                         int ndomains;
82                         The domains to search, instead of the domains  speci‐
83                         fied  in  resolv.conf  or the domain derived from the
84                         kernel hostname variable.
85
86       ARES_OPT_LOOKUPS  char *lookups;
87                         The lookups to perform  for  host  queries.   lookups
88                         should  be  set  to a string of the characters "b" or
89                         "f", where "b" indicates a DNS lookup and  "f"  indi‐
90                         cates a lookup in the hosts file.
91
92       ARES_OPT_SOCK_STATE_CB
93                         void  (*sock_state_cb)(void  *data,  int s, int read,
94                         int write);
95                         void *sock_state_cb_data;
96                         A callback function  to  be  invoked  when  a  socket
97                         changes  state.   s  will  be passed the socket whose
98                         state has changed; read will be set to  true  if  the
99                         socket  should listen for read events, and write will
100                         be set to true if the socket should listen for  write
101                         events.   The  value  of  sock_state_cb_data  will be
102                         passed as the data argument.
103
104       The flags field should be the bitwise or of some subset of the  follow‐
105       ing values:
106
107       ARES_FLAG_USEVC        Always  use  TCP queries (the "virtual circuit")
108                              instead of UDP queries.  Normally, TCP  is  only
109                              used if a UDP query yields a truncated result.
110
111       ARES_FLAG_PRIMARY      Only  query  the  first  server  in  the list of
112                              servers to query.
113
114       ARES_FLAG_IGNTC        If a  truncated  response  to  a  UDP  query  is
115                              received,  do  not fall back to TCP; simply con‐
116                              tinue on with the truncated response.
117
118       ARES_FLAG_NORECURSE    Do not set the "recursion desired" bit on outgo‐
119                              ing  queries, so that the name server being con‐
120                              tacted will not try to  fetch  the  answer  from
121                              other  servers  if  it  doesn't  know the answer
122                              locally. Be aware that  ares  will  not  do  the
123                              recursion for you.  Recursion must be handled by
124                              the application calling ares if  ARES_FLAG_NORE‐
125                              CURSE is set.
126
127       ARES_FLAG_STAYOPEN     Do  not  close  communications  sockets when the
128                              number of active queries drops to zero.
129
130       ARES_FLAG_NOSEARCH     Do not use  the  default  search  domains;  only
131                              query hostnames as-is or as aliases.
132
133       ARES_FLAG_NOALIASES    Do  not  honor the HOSTALIASES environment vari‐
134                              able, which normally specifies a file  of  host‐
135                              name translations.
136
137       ARES_FLAG_NOCHECKRESP  Do  not  discard  responses  with  the SERVFAIL,
138                              NOTIMP, or REFUSED response  code  or  responses
139                              whose questions don't match the questions in the
140                              request.  Primarily useful for  writing  clients
141                              which  might  be  used  to  test  or  debug name
142                              servers.
143

RETURN VALUES

145       ares_init or ares_init_options can return any of the following values:
146
147       ARES_SUCCESS  Initialization succeeded.
148
149       ARES_EFILE    A configuration file could not be read.
150
151       ARES_ENOMEM   The process's available memory was exhausted.
152
153       ARES_ENOTINITIALIZED
154                     c-ares library initialization not yet performed.
155

NOTES

157       When initializing from /etc/resolv.conf, ares_init(3) reads the  domain
158       and  search  directives to allow lookups of short names relative to the
159       domains specified.  The  domain  and  search  directives  override  one
160       another.  If  more  that one instance of either domain or search direc‐
161       tives is specified, the last  occurence  wins.  For  more  information,
162       please see the resolv.conf(5) manual page.
163

SEE ALSO

165       ares_destroy(3), ares_dup(3), ares_library_init(3), ares_set_servers(3)
166

AUTHOR

168       Greg Hudson, MIT Information Systems
169       Copyright 1998 by the Massachusetts Institute of Technology.
170       Copyright (C) 2004-2010 by Daniel Stenberg.
171
172
173
174                                 5 March 2010                     ARES_INIT(3)
Impressum