aboutsummaryrefslogtreecommitdiffstats
path: root/lib/libc/net/gethostbyname.3
diff options
context:
space:
mode:
authorPeter Wemm <peter@FreeBSD.org>1996-08-30 19:40:05 +0000
committerPeter Wemm <peter@FreeBSD.org>1996-08-30 19:40:05 +0000
commitbc7413d0a305014fc9a952e793296db2fddfc1bb (patch)
treea8bc6b155fd1945e0f70be176512096e41a3ec2d /lib/libc/net/gethostbyname.3
parent1133312c37e854019422d2ec2408781bee1830d1 (diff)
downloadsrc-bc7413d0a305014fc9a952e793296db2fddfc1bb.tar.gz
src-bc7413d0a305014fc9a952e793296db2fddfc1bb.zip
back out last two changes, this caused the mandoc pages to be replaced by
man pages. I'll fold in the real changes in a seperate commit.
Notes
Notes: svn path=/head/; revision=17955
Diffstat (limited to 'lib/libc/net/gethostbyname.3')
-rw-r--r--lib/libc/net/gethostbyname.3333
1 files changed, 178 insertions, 155 deletions
diff --git a/lib/libc/net/gethostbyname.3 b/lib/libc/net/gethostbyname.3
index e1d5050b1da3..702a116d52f5 100644
--- a/lib/libc/net/gethostbyname.3
+++ b/lib/libc/net/gethostbyname.3
@@ -1,72 +1,75 @@
-.\" Copyright (c) 1983, 1987 The Regents of the University of California.
-.\" All rights reserved.
+.\" Copyright (c) 1983, 1987, 1991, 1993
+.\" 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.
+.\" 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.
.\"
-.\" @(#)gethostbyname.3 6.12 (Berkeley) 6/23/90
+.\" 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.
.\"
-.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 ,
+.\" @(#)gethostbyname.3 8.2 (Berkeley) 4/19/94
+.\"
+.Dd April 19, 1994
+.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
-.I gethostbyaddr
+.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 the information obtained from the name server,
-.IR named (8),
+.Xr named 8 ,
or broken-out fields from a line in
-.IR /etc/hosts .
+.Pa /etc/hosts .
If the local name server is not running these routines do a lookup in
-.IR /etc/hosts .
-.RS
-.PP
-.nf
+.Pa /etc/hosts .
+.Bd -literal
struct hostent {
char *h_name; /* official name of host */
char **h_aliases; /* alias list */
@@ -75,108 +78,103 @@ struct hostent {
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
+.Ed
+.Pp
The members of this structure are:
-.TP \w'h_addr_list'u+2n
-h_name
+.Bl -tag -width h_addr_list
+.It Fa h_name
Official name of the host.
-.TP \w'h_addr_list'u+2n
-h_aliases
+.It Fa 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
+.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.
-.TP \w'h_addr_list'u+2n
-h_addr_list
+.It Fa 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
+.It Fa h_addr
+The first address in
+.Fa h_addr_list ;
+this is for backward compatibility.
+.Pp
When using the nameserver,
-.I gethostbyname
+.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 ``HOSTALAIASES''
+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
-.IR hostname (7)
+.Xr 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.
+.Pp
+The
+.Fn sethostent
+function
+may be used to request the use of a connected
+.Tn TCP
+socket for queries.
If the
-.I stayopen
+.Fa stayopen
flag is non-zero,
-this sets the option to send all queries to the name server using TCP
+this sets the option to send all queries to the name server using
+.Tn TCP
and to retain the connection after each call to
-.I gethostbyname
+.Fn gethostbyname
or
-.IR gethostbyaddr .
-Otherwise, queries are performed using UDP datagrams.
-.PP
-.I Endhostent
-closes the TCP connection.
-.SH DIAGNOSTICS
-.PP
+.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
-.I gethostbyname
+.Fn gethostbyname
and
-.I gethostbyaddr
+.Fn gethostbyaddr
is indicated by return of a null pointer.
The external integer
-.IR h_errno
+.Va h_errno
may then be checked to see whether this is a temporary failure
or an invalid or unknown host.
The routine
-.I herror
+.Fn 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.
+.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
-.IR h_errno
+.Pp
+The variable
+.Va 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
+.Bl -tag -width HOST_NOT_FOUND
+.It Dv HOST_NOT_FOUND
No such host is known.
-.IP TRY_AGAIN \w'HOST_NOT_FOUND'u+2n
+.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.
-.IP NO_RECOVERY \w'HOST_NOT_FOUND'u+2n
+.It Dv NO_RECOVERY
Some unexpected server failure was encountered.
This is a non-recoverable error.
-.IP NO_DATA \w'HOST_NOT_FOUND'u+2n
+.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
@@ -184,43 +182,68 @@ 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
+.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
-.I sethostent
+.Fn sethostent
and
-.I endhostent
+.Fn endhostent
are redefined,
when
-.IR libc
+.Xr libc 3
is built to use only the routines to lookup in
-.IR /etc/hosts
+.Pa /etc/hosts
and not the name server.
-.PP
-.I Gethostent
+.Pp
+The
+.Fn gethostent
+function
reads the next line of
-.IR /etc/hosts ,
+.Pa /etc/hosts ,
opening the file if necessary.
-.PP
-.I Sethostent
-is redefined to open and rewind the file. If the
-.I stayopen
+.Pp
+The
+.Fn sethostent
+function
+opens and/or rewinds the file
+.Pa /etc/hosts .
+If the
+.Fa stayopen
argument is non-zero,
-the hosts data base will not be closed after each call to
-.I gethostbyname
+the file will not be closed after each call to
+.Fn 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
+.Fn gethostbyaddr .
+.Pp
+The
+.Fn endhostent
+function
+closes the file.
+.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 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.