mirror of
https://git.FreeBSD.org/src.git
synced 2024-12-03 09:00:21 +00:00
pull this in to avoid fixing these twice
This commit is contained in:
Peter Wemm
parent
069428af6d
commit
d4c31a75a3
Notes:
svn2git
2020-12-20 02:59:44 +00:00
svn path=/vendor/CSRG/dist/; revision=17961
250
lib/libc/net/gethostbyname.3
Normal file
250
lib/libc/net/gethostbyname.3
Normal file
@ -0,0 +1,250 @@
|
||||
.\" 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. 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.
|
||||
.\"
|
||||
.\" 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.4 (Berkeley) 5/25/95
|
||||
.\"
|
||||
.Dd May 25, 1995
|
||||
.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 int 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
|
||||
.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,
|
||||
.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 */
|
||||
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; currently always
|
||||
.Dv AF_INET .
|
||||
.It Fa h_length
|
||||
The length, in bytes, of the address.
|
||||
.It Fa h_addr_list
|
||||
A NULL-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
|
||||
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,
|
||||
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
|
||||
.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.
|
||||
Loading…
Reference in New Issue
Block a user