library init: be recursive

[platform/upstream/c-ares.git] / ares_init.3

diff --git a/ares_init.3 b/ares_init.3
index f7a7b4a..fb25306 100644 (file)
--- a/ares_init.3
+++ b/ares_init.3
@@ -1,7 +1,6 @@
-.\" $Id$
 .\"
 .\" Copyright 1998 by the Massachusetts Institute of Technology.
-.\" Copyright (C) 2007-2008 by Daniel Stenberg
+.\" Copyright (C) 2004-2010 by Daniel Stenberg
 .\"
 .\" Permission to use, copy, modify, and distribute this
 .\" software and its documentation for any purpose and without
@@ -15,15 +14,15 @@
 .\" this software for any purpose.  It is provided "as is"
 .\" without express or implied warranty.
 .\"
-.TH ARES_INIT 3 "13 May 2008"
+.TH ARES_INIT 3 "5 March 2010"
 .SH NAME
 ares_init, ares_init_options \- Initialize a resolver channel
 .SH SYNOPSIS
 .nf
 .B #include <ares.h>
 .PP
-.B int ares_init(ares_channel *\fIchannel\fP)
-.B int ares_init_options(ares_channel *\fIchannel\fP,
+.B int ares_init(ares_channel *\fIchannelptr\fP)
+.B int ares_init_options(ares_channel *\fIchannelptr\fP,
 .B     struct ares_options *\fIoptions\fP, int \fIoptmask\fP)
 .PP
 .B cc file.c -lcares
@@ -31,7 +30,7 @@ ares_init, ares_init_options \- Initialize a resolver channel
 .SH DESCRIPTION
 The \fBares_init\fP function initializes a communications channel for name
 service lookups.  If it returns successfully, \fBares_init\fP will set the
-variable pointed to by \fIchannel\fP to a handle used to identify the name
+variable pointed to by \fIchannelptr\fP to a handle used to identify the name
 service channel.  The caller should invoke
 .BR ares_destroy (3)
 on the handle when the channel is no longer needed.
@@ -93,8 +92,11 @@ service port.
 .br
 .B int \fInservers\fP;
 .br
-The list of servers to contact, instead of the servers specified in
-resolv.conf or the local named.
+The list of IPv4 servers to contact, instead of the servers specified in
+resolv.conf or the local named. In order to allow specification of either
+IPv4 or IPv6 name servers, the
+.BR ares_set_servers(3)
+function must be used instead.
 .TP 18
 .B ARES_OPT_DOMAINS
 .B char **\fIdomains\fP;
@@ -107,7 +109,7 @@ or the domain derived from the kernel hostname variable.
 .B ARES_OPT_LOOKUPS
 .B char *\fIlookups\fP;
 .br
-The lookups to perform for host queries.  
+The lookups to perform for host queries.
 .I lookups
 should be set to a string of the characters "b" or "f", where "b"
 indicates a DNS lookup and "f" indicates a lookup in the hosts file.
@@ -184,10 +186,38 @@ A configuration file could not be read.
 .TP 14
 .B ARES_ENOMEM
 The process's available memory was exhausted.
+.TP 14
+.B ARES_ENOTINITIALIZED
+c-ares library initialization not yet performed.
+.SH NOTES
+When initializing from
+.B /etc/resolv.conf,
+.BR ares_init (3)
+reads the
+.I domain
+and
+.I search
+directives to allow lookups of short names relative to the domains
+specified. The
+.I domain
+and
+.I search
+directives override one another. If more that one instance of either
+.I domain
+or
+.I search
+directives is specified, the last occurence wins. For more information,
+please see the
+.BR resolv.conf (5)
+manual page.
 .SH SEE ALSO
 .BR ares_destroy(3),
-.BR ares_dup(3)
+.BR ares_dup(3),
+.BR ares_library_init(3),
+.BR ares_set_servers(3)
 .SH AUTHOR
 Greg Hudson, MIT Information Systems
 .br
 Copyright 1998 by the Massachusetts Institute of Technology.
+.br
+Copyright (C) 2004-2010 by Daniel Stenberg.