diff options
author | peter <peter@FreeBSD.org> | 1996-08-29 22:13:00 +0000 |
---|---|---|
committer | peter <peter@FreeBSD.org> | 1996-08-29 22:13:00 +0000 |
commit | 89e21d41bf7f5ae4a5a040cfd3f5391657956a2d (patch) | |
tree | efd22ab091f05c17f90dcbb1401a1b87835f7277 | |
parent | 286c357861cb82b1749ee01b91f8c2377d97b7c6 (diff) | |
download | FreeBSD-src-89e21d41bf7f5ae4a5a040cfd3f5391657956a2d.zip FreeBSD-src-89e21d41bf7f5ae4a5a040cfd3f5391657956a2d.tar.gz |
The last commit failed part-way through, re-add the generated
resolver man pages.
-rw-r--r-- | lib/libc/net/gethostbyname.3 | 226 | ||||
-rw-r--r-- | lib/libc/net/getnetent.3 | 133 | ||||
-rw-r--r-- | lib/libc/net/resolver.3 | 339 |
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 |