ares 1.1.1 with collected applied patches

1 files changed, 170 insertions, 0 deletions

diff --git a/ares_init.3 b/ares_init.3
new file mode 100644
index 0000000..58e44bb
--- /dev/null
+++ b/ares_init.3
@@ -0,0 +1,170 @@
+.\" $Id$
+.\"
+.\" Copyright 1998 by the Massachusetts Institute of Technology.
+.\"
+.\" Permission to use, copy, modify, and distribute this
+.\" software and its documentation for any purpose and without
+.\" fee is hereby granted, provided that the above copyright
+.\" notice appear in all copies and that both that copyright
+.\" notice and this permission notice appear in supporting
+.\" documentation, and that the name of M.I.T. not be used in
+.\" advertising or publicity pertaining to distribution of the
+.\" software without specific, written prior permission.
+.\" M.I.T. makes no representations about the suitability of
+.\" this software for any purpose.  It is provided "as is"
+.\" without express or implied warranty.
+.\"
+.TH ARES_INIT 3 "21 July 1998"
+.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 	struct ares_options *\fIoptions\fP, int \fIoptmask\fP)
+.PP
+.B cc file.c -lares
+.fi
+.SH DESCRIPTION
+The
+.B ares_init
+function initializes a communications channel for name service
+lookups.  If it returns successfully,
+.B ares_init
+will set the variable pointed to by
+.I channel
+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.
+.PP
+The
+.B ares_init_options
+function also initializes a name service channel, with additional
+options useful for applications requiring more control over name
+service configuration.  The
+.I optmask
+parameter specifies which fields in the structure pointed to by
+.I options
+are set, as follows:
+.PP
+.TP 18
+.B ARES_OPT_FLAGS
+.B int \fIflags\fP;
+.br
+Flags controlling the behavior of the resolver.  See below for a
+description of possible flag values.
+.TP 18
+.B ARES_OPT_TIMEOUT
+.B int \fItimeout\fP;
+.br
+The number of seconds each name server is given to respond to a query
+on the first try.  (After the first try, the timeout algorithm becomes
+more complicated, but scales linearly with the value of
+\fItimeout\fP.)  The default is five seconds.
+.TP 18
+.B ARES_OPT_TRIES
+.B int \fItries\fP;
+.br
+The number of tries the resolver will try contacting each name server
+before giving up.  The default is four tries.
+.TP 18
+.B ARES_OPT_NDOTS
+.B int \fIndots\fP;
+.br
+The number of dots which must be present in a domain name for it to be
+queried for "as is" prior to querying for it with the default domain
+extensions appended.  The default value is 1 unless set otherwise by
+resolv.conf or the RES_OPTIONS environment variable.
+.TP 18
+.B ARES_OPT_PORT
+.B unsigned short \fIport\fP;
+.br
+The port to use for queries (both TCP and UDP), in network byte order.
+The default value is 53 (in network byte order), the standard name
+service port.
+.TP 18
+.B ARES_OPT_SERVERS
+.B struct in_addr *\fIservers\fP;
+.br
+.B int \fInservers\fP;
+.br
+The list of servers to contact, instead of the servers specified in
+resolv.conf or the local named.
+.TP 18
+.B ARES_OPT_DOMAINS
+.B char **\fIdomains\fP;
+.br
+.B int \fIndomains\fP;
+.br
+The domains to search, instead of the domains specified in resolv.conf
+or the domain derived from the kernel hostname variable.
+.TP 18
+.B ARES_OPT_LOOKUPS
+.B char *\fIlookups\fP;
+.br
+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.
+.PP
+The
+.I flags
+field should be the bitwise or of some subset of the following values:
+.TP 23
+.B ARES_FLAG_USEVC
+Always use TCP queries (the "virtual circuit") instead of UDP
+queries.  Normally, TCP is only used if a UDP query yields a truncated
+result.
+.TP 23
+.B ARES_FLAG_PRIMARY
+Only query the first server in the list of servers to query.
+.TP 23
+.B ARES_FLAG_IGNTC
+If a truncated response to a UDP query is received, do not fall back
+to TCP; simply continue on with the truncated response.
+.TP 23
+.B ARES_FLAG_NORECURSE
+Do not set the "recursion desired" bit on outgoing queries, so that
+the name server being contacted will not try to fetch the answer from
+other servers if it doesn't know the answer locally.
+.TP 23
+.B ARES_FLAG_STAYOPEN
+Do not close communciations sockets when the number of active queries
+drops to zero.
+.TP 23
+.B ARES_FLAG_NOSEARCH
+Do not use the default search domains; only query hostnames as-is or
+as aliases.
+.TP 23
+.B ARES_FLAG_NOALIASES
+Do not honor the HOSTALIASES environment variable, which normally
+specifies a file of hostname translations.
+.TP 23
+.B ARES_FLAG_NOCHECKRESP
+Do not discard responses with the SERVFAIL, NOTIMP, or REFUSED
+response code or responses whose questions don't match the questions
+in the request.  Primarily useful for writing clients which might be
+used to test or debug name servers.
+.SH RETURN VALUES
+.I ares_init
+or
+.I ares_init_options
+can return any of the following values:
+.TP 14
+.B ARES_SUCCESS
+Initialization succeeded.
+.TP 14
+.B ARES_EFILE
+A configuration file could not be read.
+.TP 14
+.B ARES_ENOMEM
+The process's available memory was exhausted.
+.SH SEE ALSO
+.BR ares_destroy (3)
+.SH AUTHOR
+Greg Hudson, MIT Information Systems
+.br
+Copyright 1998 by the Massachusetts Institute of Technology.