1ARES_INIT(3) Library Functions Manual ARES_INIT(3)
2
6 ares_init, ares_init_options - Initialize a resolver channel
7
9 #include <ares.h>
10 int ares_init(ares_channel *channel)
12 int ares_init_options(ares_channel *channel,
13 struct ares_options *options, int optmask)
14 cc file.c -lcares
16
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 channel 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 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 ARES_OPT_FLAGS int flags;
30 Flags controlling the behavior of the resolver. See
31 below for a description of possible flag values.
32 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.
39 ARES_OPT_TRIES int tries;
41 The number of tries the resolver will try contacting
42 each name server before giving up. The default is
43 four tries.
44 ARES_OPT_NDOTS int ndots;
46 The number of dots which must be present in a domain
47 name for it to be queried for "as is" prior to query‐
48 ing for it with the default domain extensions
49 appended. The default value is 1 unless set other‐
50 wise by resolv.conf or the RES_OPTIONS environment
51 variable.
52 ARES_OPT_PORT unsigned short port;
54 The port to use for queries (both TCP and UDP), in
55 network byte order. The default value is 53 (in net‐
56 work byte order), the standard name service port.
57 ARES_OPT_SERVERS struct in_addr *servers;
59 int nservers;
60 The list of servers to contact, instead of the
61 servers specified in resolv.conf or the local named.
62 ARES_OPT_DOMAINS char **domains;
64 int ndomains;
65 The domains to search, instead of the domains speci‐
66 fied in resolv.conf or the domain derived from the
67 kernel hostname variable.
68 ARES_OPT_LOOKUPS char *lookups;
70 The lookups to perform for host queries. lookups
71 should be set to a string of the characters "b" or
72 "f", where "b" indicates a DNS lookup and "f" indi‐
73 cates a lookup in the hosts file.
74 ARES_OPT_SOCK_STATE_CB
76 void (*sock_state_cb)(void *data, int s, int read,
77 int write);
78 void *sock_state_cb_data;
79 A callback function to be invoked when a socket
80 changes state. s will be passed the socket whose
81 state has changed; read will be set to true if the
82 socket should listen for read events, and write will
83 be set to true if the socket should listen for write
84 events. The value of sock_state_cb_data will be
85 passed as the data argument.
86 The flags field should be the bitwise or of some subset of the follow‐
88 ing values:
89 ARES_FLAG_USEVC Always use TCP queries (the "virtual circuit")
91 instead of UDP queries. Normally, TCP is only
92 used if a UDP query yields a truncated result.
93 ARES_FLAG_PRIMARY Only query the first server in the list of
95 servers to query.
96 ARES_FLAG_IGNTC If a truncated response to a UDP query is
98 received, do not fall back to TCP; simply con‐
99 tinue on with the truncated response.
100 ARES_FLAG_NORECURSE Do not set the "recursion desired" bit on outgo‐
102 ing queries, so that the name server being con‐
103 tacted will not try to fetch the answer from
104 other servers if it doesn't know the answer
105 locally. Be aware that ares will not do the
106 recursion for you. Recursion must be handled by
107 the application calling ares if ARES_FLAG_NORE‐
108 CURSE is set.
109 ARES_FLAG_STAYOPEN Do not close communciations sockets when the
111 number of active queries drops to zero.
112 ARES_FLAG_NOSEARCH Do not use the default search domains; only
114 query hostnames as-is or as aliases.
115 ARES_FLAG_NOALIASES Do not honor the HOSTALIASES environment vari‐
117 able, which normally specifies a file of host‐
118 name translations.
119 ARES_FLAG_NOCHECKRESP Do not discard responses with the SERVFAIL,
121 NOTIMP, or REFUSED response code or responses
122 whose questions don't match the questions in the
123 request. Primarily useful for writing clients
124 which might be used to test or debug name
125 servers.
126
128 ares_init or ares_init_options can return any of the following values:
129 ARES_SUCCESS Initialization succeeded.
131 ARES_EFILE A configuration file could not be read.
133 ARES_ENOMEM The process's available memory was exhausted.
135
137 ares_destroy(3)
138
140 Greg Hudson, MIT Information Systems
141 Copyright 1998 by the Massachusetts Institute of Technology.
142 7 December 2004 ARES_INIT(3)