1 files changed, 297 insertions, 0 deletions

diff --git a/src/lib/libc/net/gethostbyname.3 b/src/lib/libc/net/gethostbyname.3
new file mode 100644
index 0000000000..1a627f403b
--- /dev/null
+++ b/src/lib/libc/net/gethostbyname.3
@@ -0,0 +1,297 @@
+.\"     $OpenBSD: gethostbyname.3,v 1.20 2003/06/30 16:54:53 millert Exp $
+.\"
+.\" Copyright (c) 1983, 1987, 1991, 1993
+.\"     The Regents of the University of California.  All rights reserved.
+.\"
+.\" 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. 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 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.
+.\"
+.Dd March 13, 1997
+.Dt GETHOSTBYNAME 3
+.Os
+.Sh NAME
+.Nm gethostbyname ,
+.Nm gethostbyname2 ,
+.Nm gethostbyaddr ,
+.Nm gethostent ,
+.Nm sethostent ,
+.Nm endhostent ,
+.Nm hstrerror ,
+.Nm herror
+.Nd get network host entry
+.Sh SYNOPSIS
+.Fd #include <netdb.h>
+.Fd extern int h_errno;
+.Ft struct hostent *
+.Fn gethostbyname "const char *name"
+.Ft struct hostent *
+.Fn gethostbyname2 "const char *name" "int af"
+.Ft struct hostent *
+.Fn gethostbyaddr "const char *addr" "int len" "int af"
+.Ft struct hostent *
+.Fn gethostent void
+.Ft void
+.Fn sethostent "int stayopen"
+.Ft void
+.Fn endhostent void
+.Ft void
+.Fn herror "const char *string"
+.Ft const char *
+.Fn hstrerror "int err"
+.Sh DESCRIPTION
+The
+.Fn gethostbyname ,
+.Fn gethostbyname2
+and
+.Fn gethostbyaddr
+functions 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 information obtained from the name server (i.e.,
+.Xr resolver 3
+and
+.Xr named 8 ) ,
+broken-out fields from a line in
+.Pa /etc/hosts ,
+or database entries supplied by the
+.Xr yp 8
+system.
+.Xr resolv.conf 5
+describes how the particular database is chosen.
+.Bd -literal
+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 */
+.Ed
+.Pp
+The members of this structure are:
+.Bl -tag -width h_addr_list
+.It Fa h_name
+Official name of the host.
+.It Fa h_aliases
+A NULL-terminated array of alternate names for the host.
+.It Fa h_addrtype
+The type of address being returned.
+.It Fa h_length
+The length, in bytes, of the address.
+.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 compatibility.
+.El
+.Pp
+The function
+.Fn gethostbyname
+will search for the named host in the current domain and its parents
+using the search lookup semantics detailed in
+.Xr resolv.conf 5
+and
+.Xr hostname 7 .
+.Pp
+.Fn gethostbyname2
+is an advanced form of
+.Fn gethostbyname
+which allows lookups in address families other than
+.Dv AF_INET .
+Currently, the only supported address family besides
+.Dv AF_INET
+is
+.Dv AF_INET6 .
+.Pp
+The
+.Fn gethostbyaddr
+function will search for the specified address of length
+.Fa len
+in the address family
+.Fa af .
+The only address family currently supported is
+.Dv AF_INET .
+.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,
+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.
+.Pp
+The
+.Fn herror
+function prints an error message describing the failure.
+If its argument
+.Fa string
+is non-null,
+it is prepended to the message string and separated from it by a colon
+.Pq Ql \&:
+and a space.
+The error message is printed with a trailing newline.
+The contents of the error message is the same as that returned by
+.Fn hstrerror
+with argument
+.Fa h_errno .
+.Sh ENVIRONMENT
+.Bl -tag -width HOSTALIASES
+.It HOSTALIASES
+A file containing local host aliases.
+See
+.Xr hostname 7
+for more information.
+.It RES_OPTIONS
+A list of options to override the resolver's internal defaults.
+See
+.Xr resolver 3
+for more information.
+.El
+.Sh FILES
+.Bl -tag -width /etc/resolv.conf -compact
+.It Pa /etc/hosts
+.It Pa /etc/resolv.conf
+.El
+.Sh DIAGNOSTICS
+Error return status from
+.Fn gethostbyname ,
+.Fn gethostbyname2 ,
+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.
+.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.
+.It Dv NETDB_INTERNAL
+An internal error occurred.
+This may occurs when an address family other than
+.It Dv AF_INET
+or
+.It Dv AF_INET6
+is specified or when a resource is unable to be allocated.
+the 
+.It Dv NETDB_SUCCESS
+The function completed successfully.
+.El
+.Sh SEE ALSO
+.Xr getaddrinfo 3 ,
+.Xr getnameinfo 3 ,
+.Xr resolver 3 ,
+.Xr hosts 5 ,
+.Xr resolv.conf 5 ,
+.Xr hostname 7 ,
+.Xr named 8
+.Sh HISTORY
+The
+.Fn herror
+function appeared in
+.Bx 4.3 .
+The
+.Fn endhostent ,
+.Fn gethostbyaddr ,
+.Fn gethostbyname ,
+.Fn gethostent ,
+and
+.Fn sethostent
+functions appeared in
+.Bx 4.2 .
+.Sh CAVEATS
+If the search routines in
+.Xr resolv.conf 5
+decide to read the
+.Pa /etc/hosts
+file,
+.Fn gethostent
+and other functions will
+read the next line of the file,
+re-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 ,
+.Fn gethostbyname2 ,
+or
+.Fn gethostbyaddr .
+.Pp
+The
+.Fn endhostent
+function closes the file.
+.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 formats are currently understood.
+.Pp
+YP does not support any address families other than
+.Dv AF_INET
+and uses
+the traditional database format.