BSD 4_4 release

[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 659c0a8..0292f7b 100644 (file)
--- a/usr/src/lib/libc/net/gethostbyname.3
+++ b/usr/src/lib/libc/net/gethostbyname.3
@@ -1,134 +1,249 @@
-.\" 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, 1991, 1993
+.\"    The Regents of the University of California.  All rights reserved.

 .\"
 .\"

-.\"    @(#)gethostbyname.3     6.2 (Berkeley) %G%
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\" 3. All advertising materials mentioning features or use of this software
+.\"    must display the following acknowledgement:
+.\"    This product includes software developed by the University of
+.\"    California, Berkeley and its contributors.
+.\" 4. 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.

 .\"
 .\"

-.TH GETHOSTENT 3N ""
-.UC 5
-.SH NAME
-gethostent, gethostbyaddr, gethostbyname, sethostent, endhostent, sethostfile \- get network host entry
-.SH SYNOPSIS
-.B "#include <netdb.h>
-.PP
-.B "struct hostent *gethostent()
-.PP
-.B "struct hostent *gethostbyname(name)
-.br
-.B "char *name;
-.PP
-.B "struct hostent *gethostbyaddr(addr, len, type)
-.br
-.B "char *addr; int len, type;
-.PP
-.B "sethostent(stayopen)
-.br
-.B "int stayopen;
-.PP
-.B "endhostent()
-.PP
-.B "sethostfile(name)
-.br
-.B "char *name;
-.SH DESCRIPTION
-.IR Gethostent ,
-.IR gethostbyname ,
+.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
+.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
+.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+.\" SUCH DAMAGE.
+.\"
+.\"     @(#)gethostbyname.3    8.1 (Berkeley) 6/4/93
+.\"
+.Dd June 4, 1993
+.Dt GETHOSTBYNAME 3
+.Os BSD 4.2
+.Sh NAME
+.Nm gethostbyname ,
+.Nm gethostbyaddr ,
+.Nm gethostent ,
+.Nm sethostent ,
+.Nm endhostent ,
+.Nm herror
+.Nd get network host entry
+.Sh SYNOPSIS
+.Fd #include <netdb.h>
+.Fd extern struct h_errno;
+.Ft struct hostent *
+.Fn gethostbyname "char *name"
+.Ft struct hostent *
+.Fn gethostbyaddr "char *addr" "int len" "int type"
+.Ft struct hostent *
+.Fn gethostent void
+.Fn sethostent "int stayopen"
+.Fn endhostent void
+.Fn herror "char *string"
+.Sh DESCRIPTION
+The
+.Fn gethostbyname

 and
 and

-.I gethostbyaddr
+.Fn gethostbyaddr
+functions

 each return a pointer to an object with the
 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,
-.IR /etc/hosts .
-.RS
-.PP
-.nf
+following structure describing an internet host
+referenced by name or by address, respectively.
+This structure contains either the information obtained from the name server,
+.Xr named 8 ,
+or broken-out fields from a line in 
+.Pa /etc/hosts .
+If the local name server is not running these routines do a lookup in
+.Pa /etc/hosts .
+.Bd -literal

 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 */

 };
 };

-.ft R
-.ad
-.fi
-.RE
-.PP
+#define        h_addr  h_addr_list[0]  /* address, for backward compatibility */
+.Ed
+.Pp

 The members of this structure are:
 The members of this structure are:

-.TP \w'h_addrtype'u+2n
-h_name
+.Bl -tag -width h_addr_list
+.It Fa h_name

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

-.TP \w'h_addrtype'u+2n
-h_aliases
+.It Fa h_aliases

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

-.TP \w'h_addrtype'u+2n
-h_addrtype
-The type of address being returned; currently always AF_INET.
-.TP \w'h_addrtype'u+2n
-h_length
+.It Fa h_addrtype
+The type of address being returned; currently always
+.Dv AF_INET .
+.It Fa h_length

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

-.TP \w'h_addrtype'u+2n
-h_addr
-A pointer to the network address for the host.
-Host addresses are returned
-in network byte order.
-.PP
-.I Gethostent
-reads the next line of the file, opening the file if necessary.
-.PP
-.I Sethostent
-opens and rewinds the file.  If the
-.I stayopen
+.It Fa h_addr_list
+A zero terminated array of network addresses for the host.
+Host addresses are returned in network byte order.
+.It Fa h_addr
+The first address in
+.Fa h_addr_list ;
+this is for backward compatiblity.
+.Pp
+When using the nameserver,
+.Fn 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
+.Dq Ev HOSTALIASES
+contains the name of an alias file, the alias file will first be searched
+for an alias matching the input name.
+See
+.Xr hostname 7
+for the domain search procedure and the alias file format.
+.Pp
+The
+.Fn sethostent
+function
+may be used to request the use of a connected
+.Tn TCP
+socket for queries.
+If the
+.Fa stayopen

 flag is non-zero,
 flag is non-zero,

-the host data base will not be closed after each call to 
-.I gethosbyname
+this sets the option to send all queries to the name server using
+.Tn TCP
+and to retain the connection after each call to 
+.Fn gethostbyname
+or
+.Fn gethostbyaddr .
+Otherwise, queries are performed using
+.Tn UDP
+datagrams.
+.Pp
+The
+.Fn endhostent
+function
+closes the
+.Tn TCP
+connection.
+.Sh FILES
+.Bl -tag -width /etc/hosts -compact
+.It Pa /etc/hosts
+.El
+.Sh DIAGNOSTICS
+Error return status from 
+.Fn gethostbyname
+and
+.Fn gethostbyaddr
+is indicated by return of a null pointer.
+The external integer
+.Va h_errno
+may then be checked to see whether this is a temporary failure
+or an invalid or unknown host.
+The routine
+.Fn herror
+can be used to print an error message describing the failure.
+If its argument
+.Fa string
+is
+.Pf non Dv -NULL ,
+it is printed, followed by a colon and a space.
+The error message is printed with a trailing newline.
+.Pp
+The variable
+.Va h_errno
+can have the following values:
+.Bl -tag -width HOST_NOT_FOUND
+.It Dv HOST_NOT_FOUND
+No such host is known.
+.It Dv TRY_AGAIN
+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.
+.It Dv NO_RECOVERY
+Some unexpected server failure was encountered.
+This is a non-recoverable error.
+.It Dv NO_DATA
+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.
+.El
+.Sh SEE ALSO
+.Xr resolver 3 ,
+.Xr hosts 5 ,
+.Xr hostname 7 ,
+.Xr named 8
+.Sh CAVEAT
+The
+.Fn gethostent
+function
+is defined, and
+.Fn sethostent
+and
+.Fn endhostent
+are redefined,
+when
+.Xr libc 3
+is built to use only the routines to lookup in
+.Pa /etc/hosts
+and not the name server.
+.Pp
+The
+.Fn gethostent
+function
+reads the next line of
+.Pa /etc/hosts ,
+opening the file if necessary.
+.Pp
+The
+.Fn sethostent
+function
+opens and/or rewinds the file
+.Pa /etc/hosts .
+If the
+.Fa stayopen
+argument is non-zero,
+the file will not be closed after each call to
+.Fn gethostbyname

 or
 or

-.IR gethostbyaddr .
-.PP
-.I Endhostent
+.Fn gethostbyaddr .
+.Pp
+The
+.Fn endhostent
+function

 closes the file.
 closes the file.

-.PP
-.I Sethostfile
-changes the default host table file to
-.I name
-thus allowing these routines to be used with alternate host tables.
-Note that it does
-.I not 
-close the previous file.
-If this is desired,
-.I endhostent
-should be called prior to it.
-.PP
-.I Gethostbyname
+.Sh HISTORY
+The
+.Fn herror
+function appeared in 
+.Bx 4.3 .
+The
+.Fn endhostent ,
+.Fn gethostbyaddr ,
+.Fn gethostbyname ,
+.Fn gethostent ,

 and
 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.
-.SH FILES
-/etc/hosts
-.SH "SEE ALSO"
-hosts(5), resolver(3), named(8)
-.SH DIAGNOSTICS
-Null pointer
-(0) returned on EOF or error.
-.SH BUGS
-All information
-is contained in a static area
-so it must be copied if it is
-to be saved.  Only the Internet
+.Fn sethostent
+functions appeared in
+.Bx 4.2 .
+.Sh BUGS
+These functions use static data storage;
+if the data is needed for future use, it should be
+copied before any subsequent calls overwrite it.
+Only the Internet

 address format is currently understood.
 address format is currently understood.

-.PP
-On sites configured to use the name server
-.IR named (8)
-instead of 
-.IR /etc/hosts ,
-.I gethostent
-is not available
-and
-.I sethostfile
-is a no-op.