ares_init.3

   1 .\" $Id$
   2 .\"
   3 .\" Copyright 1998 by the Massachusetts Institute of Technology.
   4 .\" Copyright (C) 2004-2009 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 "26 May 2009"
  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 *\fIchannel\fP)
  26 .B int ares_init_options(ares_channel *\fIchannel\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 \fIchannel\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 servers to contact, instead of the servers specified in
  97 resolv.conf or the local named.
  98 .TP 18
  99 .B ARES_OPT_DOMAINS
 100 .B char **\fIdomains\fP;
 101 .br
 102 .B int \fIndomains\fP;
 103 .br
 104 The domains to search, instead of the domains specified in resolv.conf
 105 or the domain derived from the kernel hostname variable.
 106 .TP 18
 107 .B ARES_OPT_LOOKUPS
 108 .B char *\fIlookups\fP;
 109 .br
 110 The lookups to perform for host queries.
 111 .I lookups
 112 should be set to a string of the characters "b" or "f", where "b"
 113 indicates a DNS lookup and "f" indicates a lookup in the hosts file.
 114 .TP 18
 115 .B ARES_OPT_SOCK_STATE_CB
 116 .B void (*\fIsock_state_cb\fP)(void *data, int s, int read, int write);
 117 .br
 118 .B void *\fIsock_state_cb_data\fP;
 119 .br
 120 A callback function to be invoked when a socket changes state.
 121 .I s
 122 will be passed the socket whose state has changed;
 123 .I read
 124 will be set to true if the socket should listen for read events, and
 125 .I write
 126 will be set to true if the socket should listen for write events.
 127 The value of
 128 .I sock_state_cb_data
 129 will be passed as the
 130 .I data
 131 argument.
 132 .PP
 133 The
 134 .I flags
 135 field should be the bitwise or of some subset of the following values:
 136 .TP 23
 137 .B ARES_FLAG_USEVC
 138 Always use TCP queries (the "virtual circuit") instead of UDP
 139 queries.  Normally, TCP is only used if a UDP query yields a truncated
 140 result.
 141 .TP 23
 142 .B ARES_FLAG_PRIMARY
 143 Only query the first server in the list of servers to query.
 144 .TP 23
 145 .B ARES_FLAG_IGNTC
 146 If a truncated response to a UDP query is received, do not fall back
 147 to TCP; simply continue on with the truncated response.
 148 .TP 23
 149 .B ARES_FLAG_NORECURSE
 150 Do not set the "recursion desired" bit on outgoing queries, so that the name
 151 server being contacted will not try to fetch the answer from other servers if
 152 it doesn't know the answer locally. Be aware that ares will not do the
 153 recursion for you.  Recursion must be handled by the application calling ares
 154 if \fIARES_FLAG_NORECURSE\fP is set.
 155 .TP 23
 156 .B ARES_FLAG_STAYOPEN
 157 Do not close communications sockets when the number of active queries
 158 drops to zero.
 159 .TP 23
 160 .B ARES_FLAG_NOSEARCH
 161 Do not use the default search domains; only query hostnames as-is or
 162 as aliases.
 163 .TP 23
 164 .B ARES_FLAG_NOALIASES
 165 Do not honor the HOSTALIASES environment variable, which normally
 166 specifies a file of hostname translations.
 167 .TP 23
 168 .B ARES_FLAG_NOCHECKRESP
 169 Do not discard responses with the SERVFAIL, NOTIMP, or REFUSED
 170 response code or responses whose questions don't match the questions
 171 in the request.  Primarily useful for writing clients which might be
 172 used to test or debug name servers.
 173 .SH RETURN VALUES
 174 .I ares_init
 175 or
 176 .I ares_init_options
 177 can return any of the following values:
 178 .TP 14
 179 .B ARES_SUCCESS
 180 Initialization succeeded.
 181 .TP 14
 182 .B ARES_EFILE
 183 A configuration file could not be read.
 184 .TP 14
 185 .B ARES_ENOMEM
 186 The process's available memory was exhausted.
 187 .TP 14
 188 .B ARES_ENOTINITIALIZED
 189 c-ares library initialization not yet performed.
 190 .SH SEE ALSO
 191 .BR ares_destroy(3),
 192 .BR ares_dup(3),
 193 .BR ares_library_init(3)
 194 .SH AUTHOR
 195 Greg Hudson, MIT Information Systems
 196 .br
 197 Copyright 1998 by the Massachusetts Institute of Technology.
 198 .br
 199 Copyright (C) 2004-2009 by Daniel Stenberg.