date and time created 91/04/12 13:40:31 by bostic

[unix-history] / usr / src / lib / libc / net / gethostbyname.3

diff --git a/usr/src/lib/libc/net/gethostbyname.3 b/usr/src/lib/libc/net/gethostbyname.3
index ae7fa39..aefdf29 100644 (file)
--- a/usr/src/lib/libc/net/gethostbyname.3
+++ b/usr/src/lib/libc/net/gethostbyname.3
@@ -1,17 +1,18 @@
-.\" Copyright (c) 1983 Regents of the University of California.
-.\" All rights reserved.  The Berkeley software License Agreement
-.\" specifies the terms and conditions for redistribution.
+.\" Copyright (c) 1983, 1987 The Regents of the University of California.
+.\" All rights reserved.

 .\"
 .\"

-.\"    @(#)gethostbyname.3     5.1 (Berkeley) %G%
+.\" %sccs.include.redist.man%

 .\"
 .\"

-.TH GETHOSTENT 3N "9 February 1983"
+.\"    @(#)gethostbyname.3     6.12 (Berkeley) %G%
+.\"
+.TH GETHOSTBYNAME 3 ""

 .UC 5
 .SH NAME
 .UC 5
 .SH NAME

-gethostent, gethostbyaddr, gethostbyname, sethostent, endhostent \- get network host entry
+gethostbyname, gethostbyaddr, gethostent, sethostent, endhostent, herror \- get network host entry

 .SH SYNOPSIS
 .B "#include <netdb.h>
 .PP
 .SH SYNOPSIS
 .B "#include <netdb.h>
 .PP

-.B "struct hostent *gethostent()
+.B "extern int h_errno;

 .PP
 .B "struct hostent *gethostbyname(name)
 .br
 .PP
 .B "struct hostent *gethostbyname(name)
 .br


@@ -21,20 +22,30 @@ gethostent, gethostbyaddr, gethostbyname, sethostent, endhostent \- get network
 .br
 .B "char *addr; int len, type;
 .PP
 .br
 .B "char *addr; int len, type;
 .PP

+.B "struct hostent *gethostent()
+.PP

 .B "sethostent(stayopen)
 .br
 .B "sethostent(stayopen)
 .br

-.B "int stayopen
+.B "int stayopen;

 .PP
 .B "endhostent()
 .PP
 .B "endhostent()

+.PP
+.B "herror(string)
+.br
+.B "char *string;
+.PP

 .SH DESCRIPTION
 .SH DESCRIPTION

-.IR Gethostent ,
-.IR gethostbyname ,
+.I Gethostbyname

 and
 .I gethostbyaddr
 each return a pointer to an object with the
 and
 .I gethostbyaddr
 each return a pointer to an object with the

-following structure
-containing the broken-out
-fields of a line in the network host data base,
+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
 .IR /etc/hosts .
 .RS
 .PP


@@ -42,65 +53,136 @@ fields of a line in the network host data base,
 struct hostent {
        char    *h_name;        /* official name of host */
        char    **h_aliases;    /* alias list */
 struct hostent {
        char    *h_name;        /* official name of host */
        char    **h_aliases;    /* alias list */

-       int     h_addrtype;     /* address type */
+       int     h_addrtype;     /* host address type */

        int     h_length;       /* length of address */
        int     h_length;       /* length of address */

-       char    *h_addr;        /* 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:
 .ft R
 .ad
 .fi
 .RE
 .PP
 The members of this structure are:

-.TP \w'h_addrtype'u+2n
+.TP \w'h_addr_list'u+2n

 h_name
 Official name of the host.
 h_name
 Official name of the host.

-.TP \w'h_addrtype'u+2n
+.TP \w'h_addr_list'u+2n

 h_aliases
 A zero terminated array of alternate names for the host.
 h_aliases
 A zero terminated array of alternate names for the host.

-.TP \w'h_addrtype'u+2n
+.TP \w'h_addr_list'u+2n

 h_addrtype
 The type of address being returned; currently always AF_INET.
 h_addrtype
 The type of address being returned; currently always AF_INET.

-.TP \w'h_addrtype'u+2n
+.TP \w'h_addr_list'u+2n

 h_length
 The length, in bytes, of the address.
 h_length
 The length, in bytes, of the address.

-.TP \w'h_addrtype'u+2n
+.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
 h_addr

-A pointer to the network address for the host.
-Host addresses are returned
-in network byte order.
+The first address in h_addr_list; this is for backward compatiblity.

 .PP
 .PP

-.I Gethostent
-reads the next line of the file, opening the file if necessary.
+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 Sethostent
 .PP
 .I Sethostent

-opens and rewinds the file.  If the
+may be used to request the use of a connected TCP socket for queries.
+If the

 .I stayopen
 flag is non-zero,
 .I stayopen
 flag is non-zero,

-the host data base will not be closed after each call to 
-.I gethostent
-(either directly, or indirectly through one of the other
-\*(lqgethost\*(rq calls).
+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
 .PP
 .I Endhostent

-closes the file.
+closes the TCP connection.
+.SH DIAGNOSTICS

 .PP
 .PP

-.I Gethostbyname
+Error return status from 
+.I gethostbyname

 and
 .I gethostbyaddr
 and
 .I gethostbyaddr

-sequentially search from the beginning
-of the file until a matching
-host name or
-host address is found,
-or until EOF is encountered.
-Host addresses are supplied in network order.
+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 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"
 .SH FILES
 /etc/hosts
 .SH "SEE ALSO"

-hosts(5)
-.SH DIAGNOSTICS
-Null pointer
-(0) returned on EOF or error.
+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
 .SH BUGS
 All information
 is contained in a static area