The last commit failed part-way through, re-add the generated

resolver man pages.

3 files changed, 698 insertions, 0 deletions

diff --git a/lib/libc/net/gethostbyname.3 b/lib/libc/net/gethostbyname.3
new file mode 100644
index 0000000..e1d5050
--- /dev/null
+++ b/lib/libc/net/gethostbyname.3
@@ -0,0 +1,226 @@
+.\" Copyright (c) 1983, 1987 The Regents of the University of California.
+.\" All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms are permitted provided
+.\" that: (1) source distributions retain this entire copyright notice and
+.\" comment, and (2) distributions including binaries display the following
+.\" acknowledgement:  ``This product includes software developed by the
+.\" University of California, Berkeley and its contributors'' in the
+.\" documentation or other materials provided with the distribution and in
+.\" all advertising materials mentioning features or use of this software.
+.\" Neither the name of the University nor the names of its contributors may
+.\" be used to endorse or promote products derived from this software without
+.\" specific prior written permission.
+.\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR IMPLIED
+.\" WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
+.\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
+.\"
+.\"	@(#)gethostbyname.3	6.12 (Berkeley) 6/23/90
+.\"
+.TH GETHOSTBYNAME 3 "June 23, 1990"
+.UC 5
+.SH NAME
+gethostbyname, gethostbyaddr, gethostent, sethostent, endhostent, herror \- get network host entry
+.SH SYNOPSIS
+.B "#include <netdb.h>
+.PP
+.B "extern int h_errno;
+.PP
+.B "struct hostent *gethostbyname(name)
+.br
+.B "char *name;
+.PP
+.B "struct hostent *gethostbyname2(name, af)
+.br
+.B "char *name; int af;
+.PP
+.B "struct hostent *gethostbyaddr(addr, len, type)
+.br
+.B "char *addr; int len, type;
+.PP
+.B "struct hostent *gethostent()
+.PP
+.B "sethostent(stayopen)
+.br
+.B "int stayopen;
+.PP
+.B "endhostent()
+.PP
+.B "herror(string)
+.br
+.B "char *string;
+.PP
+.SH DESCRIPTION
+.IR Gethostbyname ,
+.IR gethostbyname2 ,
+and
+.I gethostbyaddr
+each return a pointer to an object with the
+following structure describing an internet host
+referenced by name or by address, respectively.
+This structure contains either the information obtained from the name server,
+.IR named (8),
+or broken-out fields from a line in 
+.IR /etc/hosts .
+If the local name server is not running these routines do a lookup in
+.IR /etc/hosts .
+.RS
+.PP
+.nf
+struct	hostent {
+	char	*h_name;	/* official name of host */
+	char	**h_aliases;	/* alias list */
+	int	h_addrtype;	/* host address type */
+	int	h_length;	/* length of address */
+	char	**h_addr_list;	/* list of addresses from name server */
+};
+#define	h_addr  h_addr_list[0]	/* address, for backward compatibility */
+.ft R
+.ad
+.fi
+.RE
+.PP
+The members of this structure are:
+.TP \w'h_addr_list'u+2n
+h_name
+Official name of the host.
+.TP \w'h_addr_list'u+2n
+h_aliases
+A zero terminated array of alternate names for the host.
+.TP \w'h_addr_list'u+2n
+h_addrtype
+The type of address being returned; usually AF_INET.
+.TP \w'h_addr_list'u+2n
+h_length
+The length, in bytes, of the address.
+.TP \w'h_addr_list'u+2n
+h_addr_list
+A zero terminated array of network addresses for the host.
+Host addresses are returned in network byte order.
+.TP \w'h_addr_list'u+2n
+h_addr
+The first address in h_addr_list; this is for backward compatibility.
+.PP
+When using the nameserver,
+.I gethostbyname
+will search for the named host in the current domain and its parents
+unless the name ends in a dot.
+If the name contains no dot, and if the environment variable ``HOSTALAIASES''
+contains the name of an alias file, the alias file will first be searched
+for an alias matching the input name.
+See
+.IR hostname (7)
+for the domain search procedure and the alias file format.
+.PP
+.I Gethostbyname2
+is an evolution of
+.I gethostbyname
+intended to allow lookups in address families other than AF_INET, for example
+AF_INET6.  Currently the
+.I af
+argument must be specified as
+.I AF_INET
+else the function will return \s-2NULL\s+2 after having set
+.I h_errno
+to \s-2NETDB_INTERNAL\s+2.
+.PP
+.I Sethostent
+may be used to request the use of a connected TCP socket for queries.
+If the
+.I stayopen
+flag is non-zero,
+this sets the option to send all queries to the name server using TCP
+and to retain the connection after each call to 
+.I gethostbyname
+or
+.IR gethostbyaddr .
+Otherwise, queries are performed using UDP datagrams.
+.PP
+.I Endhostent
+closes the TCP connection.
+.SH DIAGNOSTICS
+.PP
+Error return status from 
+.I gethostbyname
+and
+.I gethostbyaddr
+is indicated by return of a null pointer.
+The external integer
+.IR h_errno
+may then be checked to see whether this is a temporary failure
+or an invalid or unknown host.
+The routine
+.I herror
+can be used to print an error message describing the failure.
+If its argument
+.I string
+is non-NULL, it is printed, followed by a colon and a space.
+The error message is printed with a trailing newline.
+.PP
+.IR h_errno
+can have the following values:
+.RS
+.IP NETDB_INTERNAL \w'HOST_NOT_FOUND'u+2n
+This indicates an internal error in the library, unrelated to the network
+or name service.
+.I errno
+will be valid in this case; see
+.IR perror (3).
+.IP HOST_NOT_FOUND \w'HOST_NOT_FOUND'u+2n
+No such host is known.
+.IP TRY_AGAIN \w'HOST_NOT_FOUND'u+2n
+This is usually a temporary error
+and means that the local server did not receive
+a response from an authoritative server.
+A retry at some later time may succeed.
+.IP NO_RECOVERY \w'HOST_NOT_FOUND'u+2n
+Some unexpected server failure was encountered.
+This is a non-recoverable error.
+.IP NO_DATA \w'HOST_NOT_FOUND'u+2n
+The requested name is valid but does not have an IP address; 
+this is not a temporary error.  
+This means that the name is known to the name server but there is no address
+associated with this name.
+Another type of request to the name server using this domain name
+will result in an answer;
+for example, a mail-forwarder may be registered for this domain.
+.RE
+.SH FILES
+/etc/hosts
+.SH "SEE ALSO"
+resolver(3), hosts(5), hostname(7), named(8)
+.SH CAVEAT
+.PP
+.I Gethostent
+is defined, and
+.I sethostent
+and
+.I endhostent
+are redefined,
+when
+.IR libc
+is built to use only the routines to lookup in
+.IR /etc/hosts 
+and not the name server.
+.PP
+.I Gethostent
+reads the next line of
+.IR /etc/hosts ,
+opening the file if necessary.
+.PP
+.I Sethostent 
+is redefined to open and rewind the file.  If the
+.I stayopen
+argument is non-zero,
+the hosts data base will not be closed after each call to
+.I gethostbyname
+or
+.IR gethostbyaddr .
+.I Endhostent
+is redefined to close the file.
+.SH BUGS
+All information
+is contained in a static area
+so it must be copied if it is
+to be saved.  Only the Internet
+address format is currently understood.
diff --git a/lib/libc/net/getnetent.3 b/lib/libc/net/getnetent.3
new file mode 100644
index 0000000..c02b4b8
--- /dev/null
+++ b/lib/libc/net/getnetent.3
@@ -0,0 +1,133 @@
+.\" $Id: getnetent.3,v 8.2 1996/05/09 05:59:10 vixie Exp $
+.TH getnetent 3
+.SH NAME
+getnetent, getnetbyaddr, getnetbyname, setnetent, endnetent \- get networks
+entry
+.SH SYNTAX
+.nf
+.B #include <netdb.h>
+.PP
+.B struct netent *getnetent()
+.PP
+.B struct netent *getnetbyname(\fIname\fP)
+.B char *\fIname\fP;
+.PP
+.B struct netent *getnetbyaddr(\fInet\fP, \fItype\fP)
+.B unsigned long \fInet\fP; int \fItype\fP;
+.PP
+.B void setnetent(\fIstayopen\fP)
+.B int \fIstayopen\fP;
+.PP
+.B void endnetent()
+.fi
+.SH DESCRIPTION
+The
+.IR getnetent ,
+.IR getnetbyname ,
+and
+.I getnetbyaddr
+subroutines
+each return a pointer to an object with the
+following structure
+containing the broken-out
+fields of a line in the 
+.I networks 
+database.
+.RS
+.PP
+.nf
+struct	netent {
+	char	*n_name;	/* official name of net */
+	char	**n_aliases;	/* alias list */
+	int	n_addrtype;	/* net number type */
+	long	n_net;		/* net number */
+};
+.ft R
+.ad
+.fi
+.RE
+.PP
+The members of this structure are:
+.TP \w'n_addrtype'u+2n
+n_name
+The official name of the network.
+.TP \w'n_addrtype'u+2n
+n_aliases
+A zero terminated list of alternate names for the network.
+.TP \w'n_addrtype'u+2n
+n_addrtype
+The type of the network number returned: AF_INET.
+.TP \w'n_addrtype'u+2n
+n_net
+The network number.  Network numbers are returned in machine byte
+order.
+.PP
+If the
+.I stayopen
+flag on a 
+.I setnetent
+subroutine is NULL, the
+.I networks
+database is opened.  Otherwise the
+.I setnetent
+has the effect of rewinding the 
+.I networks 
+database.
+The
+.I endnetent
+may be called to
+close the 
+.I networks 
+database when processing is complete.
+.PP
+The
+.I getnetent
+subroutine simply reads the next
+line while
+.I getnetbyname
+and
+.I getnetbyaddr
+search until a matching
+.I name
+or
+.I net
+number is found
+(or until EOF is encountered).  The \fItype\fP must be AF_INET.
+The
+.I getnetent
+subroutine keeps a pointer in the database, allowing
+successive calls to be used 
+to search the entire file.
+.PP
+A call to
+.I setnetent
+must be made before a
+.I while
+loop using
+.I getnetent
+in order to perform initialization and an
+.I endnetent
+must be used after the loop.  Both
+.I getnetbyname
+and
+.I getnetbyaddr
+make calls to
+.I setnetent
+and
+.I endnetent .
+.SH FILES
+.I /etc/networks
+.SH DIAGNOSTICS
+Null pointer (0) returned on EOF or error.
+.SH SEE ALSO
+.nf
+networks(5)
+RFC 1101
+.SH HISTORY
+The getnetent(), getnetbyaddr(), getnetbyname(), setnetent(), and
+endnetent() functions appeared in 4.2BSD.
+.SH BUGS
+The data space used by these functions is static; if future use requires the
+data, it should be copied before any subsequent calls to these functions
+overwrite it.  Only Internet network numbers are currently understood.
+Expecting network numbers to fit in no more than 32 bits is probably naive.
diff --git a/lib/libc/net/resolver.3 b/lib/libc/net/resolver.3
new file mode 100644
index 0000000..a0713a2
--- /dev/null
+++ b/lib/libc/net/resolver.3
@@ -0,0 +1,339 @@
+.\" Copyright (c) 1985, 1995 The Regents of the University of California.
+.\" All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms are permitted provided
+.\" that: (1) source distributions retain this entire copyright notice and
+.\" comment, and (2) distributions including binaries display the following
+.\" acknowledgement:  ``This product includes software developed by the
+.\" University of California, Berkeley and its contributors'' in the
+.\" documentation or other materials provided with the distribution and in
+.\" all advertising materials mentioning features or use of this software.
+.\" Neither the name of the University nor the names of its contributors may
+.\" be used to endorse or promote products derived from this software without
+.\" specific prior written permission.
+.\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR IMPLIED
+.\" WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
+.\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
+.\"
+.\"	@(#)resolver.3	6.5 (Berkeley) 6/23/90
+.\"	$Id: resolver.3,v 8.4 1996/05/09 05:59:10 vixie Exp $
+.\"
+.TH RESOLVER 3 "December 11, 1995
+.UC 4
+.SH NAME
+res_query, res_search, res_mkquery, res_send, res_init, dn_comp, dn_expand \- resolver routines
+.SH SYNOPSIS
+.B #include <sys/types.h>
+.br
+.B #include <netinet/in.h>
+.br
+.B #include <arpa/nameser.h>
+.br
+.B #include <resolv.h>
+.PP
+.B "res_query(dname, class, type, answer, anslen)"
+.br
+.B const char *dname;
+.br
+.B int class, type;
+.br
+.B u_char *answer;
+.br
+.B int anslen;
+.PP
+.B "res_search(dname, class, type, answer, anslen)"
+.br
+.B const char *dname;
+.br
+.B int class, type;
+.br
+.B u_char *answer;
+.br
+.B int anslen;
+.PP
+.B "res_mkquery(op, dname, class, type, data, datalen, newrr, buf, buflen)"
+.br
+.B int op;
+.br
+.B const char *dname;
+.br
+.B int class, type;
+.br
+.B const char *data;
+.br
+.B int datalen;
+.br
+.B struct rrec *newrr;
+.br
+.B u_char *buf;
+.br
+.B int buflen;
+.PP
+.B res_send(msg, msglen, answer, anslen)
+.br
+.B const u_char *msg;
+.br
+.B int msglen;
+.br
+.B u_char *answer;
+.br
+.B int anslen;
+.PP
+.B res_init()
+.PP
+.B dn_comp(exp_dn, comp_dn, length, dnptrs, lastdnptr)
+.br
+.B const char *exp_dn;
+.br
+.B u_char *comp_dn;
+.br
+.B int length;
+.br
+.B u_char **dnptrs, **lastdnptr;
+.PP
+.B dn_expand(msg, eomorig, comp_dn, exp_dn, length)
+.br
+.B const u_char *msg, *eomorig, *comp_dn;
+.br
+.B char *exp_dn;
+.br
+.B int  length;
+.PP
+.B herror(const char *s)
+.PP
+.B hstrerror(int err)
+.SH DESCRIPTION
+These routines are used for making, sending and interpreting
+query and reply messages with Internet domain name servers.
+.PP
+Global configuration and state information that is used by the
+resolver routines is kept in the structure
+.IR _res .
+Most of the values have reasonable defaults and can be ignored.
+Options
+stored in
+.I _res.options
+are defined in
+.I resolv.h
+and are as follows.
+Options are stored as a simple bit mask containing the bitwise ``or''
+of the options enabled.
+.IP RES_INIT
+True if the initial name server address and default domain name are
+initialized (i.e.,
+.I res_init
+has been called).
+.IP RES_DEBUG
+Print debugging messages.
+.IP RES_AAONLY
+Accept authoritative answers only.
+With this option,
+.I res_send
+should continue until it finds an authoritative answer or finds an error.
+Currently this is not implemented.
+.IP RES_USEVC
+Use TCP connections for queries instead of UDP datagrams.
+.IP RES_STAYOPEN
+Used with RES_USEVC to keep the TCP connection open between
+queries.
+This is useful only in programs that regularly do many queries.
+UDP should be the normal mode used.
+.IP RES_IGNTC
+Unused currently (ignore truncation errors, i.e., don't retry with TCP).
+.IP RES_RECURSE
+Set the recursion-desired bit in queries.
+This is the default.
+(\c
+.I res_send
+does not do iterative queries and expects the name server
+to handle recursion.)
+.IP RES_DEFNAMES
+If set,
+.I res_search
+will append the default domain name to single-component names
+(those that do not contain a dot).
+This option is enabled by default.
+.IP RES_DNSRCH
+If this option is set,
+.I res_search
+will search for host names in the current domain and in parent domains; see
+.IR hostname (7).
+This is used by the standard host lookup routine
+.IR gethostbyname (3).
+This option is enabled by default.
+.IP RES_NOALIASES
+This option turns off the user level aliasing feature controlled by
+the HOSTALIASES environment variable.  Network daemons should set this option.
+.PP
+The
+.I res_init
+routine
+reads the configuration file (if any; see
+.IR resolver (5))
+to get the default domain name,
+search list and
+the Internet address of the local name server(s).
+If no server is configured, the host running
+the resolver is tried.
+The current domain name is defined by the hostname
+if not specified in the configuration file;
+it can be overridden by the environment variable LOCALDOMAIN.
+This environment variable may contain several blank-separated
+tokens if you wish to override the
+.I "search list"
+on a per-process basis.  This is similar to the
+.I search
+command in the configuration file.
+Another environment variable (``RES_OPTIONS'') can be set to
+override certain internal resolver options which are otherwise
+set by changing fields in the
+.I _res
+structure or are inherited from the configuration file's
+.I options
+command.  The syntax of the ``RES_OPTIONS'' environment variable
+is explained in
+.IR resolver (5).
+Initialization normally occurs on the first call
+to one of the other resolver routines.
+.PP
+The
+.I res_query
+function provides an interface to the server query mechanism.
+It constructs a query, sends it to the local server,
+awaits a response, and makes preliminary checks on the reply.
+The query requests information of the specified
+.I type
+and
+.I class
+for the specified fully-qualified domain name
+.I dname .
+The reply message is left in the
+.I answer
+buffer with length
+.I anslen
+supplied by the caller.
+.PP
+The
+.I res_search
+routine makes a query and awaits a response like
+.IR res_query ,
+but in addition, it implements the default and search rules
+controlled by the RES_DEFNAMES and RES_DNSRCH options.
+It returns the first successful reply.
+.PP
+The remaining routines are lower-level routines used by
+.IR res_query .
+The
+.I res_mkquery
+function
+constructs a standard query message and places it in
+.IR buf .
+It returns the size of the query, or \-1 if the query is
+larger than
+.IR buflen .
+The query type
+.I op
+is usually QUERY, but can be any of the query types defined in
+.IR <arpa/nameser.h> .
+The domain name for the query is given by
+.IR dname .
+.I Newrr
+is currently unused but is intended for making update messages.
+.PP
+The
+.I res_send
+routine
+sends a pre-formatted query and returns an answer.
+It will call
+.I res_init
+if RES_INIT is not set, send the query to the local name server, and
+handle timeouts and retries.
+The length of the reply message is returned, or
+\-1 if there were errors.
+.PP
+The
+.I dn_comp
+function
+compresses the domain name
+.I exp_dn
+and stores it in
+.IR comp_dn .
+The size of the compressed name is returned or \-1 if there were errors.
+The size of the array pointed to by
+.I comp_dn
+is given by
+.IR length .
+The compression uses
+an array of pointers
+.I dnptrs
+to previously-compressed names in the current message.
+The first pointer points to
+to the beginning of the message and the list ends with NULL.
+The limit to the array is specified by
+.IR lastdnptr .
+A side effect of
+.I dn_comp
+is to update the list of pointers for
+labels inserted into the message
+as the name is compressed.
+If
+.I dnptr
+is NULL, names are not compressed.
+If
+.I lastdnptr
+is NULL, the list of labels is not updated.
+.PP
+The
+.I dn_expand
+entry
+expands the compressed domain name
+.I comp_dn
+to a full domain name
+The compressed name is contained in a query or reply message;
+.I msg
+is a pointer to the beginning of the message.
+The uncompressed name is placed in the buffer indicated by
+.I exp_dn
+which is of size
+.IR length .
+The size of compressed name is returned or \-1 if there was an error.
+.PP
+The external variable
+.B h_errno
+is set whenever an error occurs during resolver operation.  The following
+definitions are given in
+.BR <netdb.h> :
+.PP
+.nf
+#define NETDB_INTERNAL -1  /* see errno */
+#define NETDB_SUCCESS  0   /* no problem */
+#define HOST_NOT_FOUND 1   /* Authoritative Answer Host not found */
+#define TRY_AGAIN      2   /* Non-Authoritive not found, or SERVFAIL */
+#define NO_RECOVERY    3   /* Nonrecoverable: FORMERR, REFUSED, NOTIMP */
+#define NO_DATA        4   /* Valid name, no data for requested type */
+.ft R
+.ad
+.fi
+.PP
+The
+.B herror
+function writes a message to the diagnostic output consisting of the string
+parameter
+.BR s ,
+the constant string ": ", and a message corresponding to the value of
+.BR h_errno .
+.PP
+The
+.B hstrerror
+function returns a string which is the message text corresponding to the
+value of the
+.B err
+parameter.
+.SH FILES
+/etc/resolv.conf	see resolver(5)
+.SH "SEE ALSO"
+gethostbyname(3), named(8), resolver(5), hostname(7),
+.br
+RFC1032, RFC1033, RFC1034, RFC1035, RFC974, 
+.br
+SMM:11 Name Server Operations Guide for BIND