ares_init.3

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