2fe8fb192f
There is important information about booting non-ack images in docs/UPDATING. ack/aout-format images can't be built any more, and booting clang/ELF-format ones is a little different. Updating to the new boot monitor is recommended. Changes in this commit: . drop boot monitor -> allowing dropping ack support . facility to copy ELF boot files to /boot so that old boot monitor can still boot fairly easily, see UPDATING . no more ack-format libraries -> single-case libraries . some cleanup of OBJECT_FMT, COMPILER_TYPE, etc cases . drop several ack toolchain commands, but not all support commands (e.g. aal is gone but acksize is not yet). . a few libc files moved to netbsd libc dir . new /bin/date as minix date used code in libc/ . test compile fix . harmonize includes . /usr/lib is no longer special: without ack, /usr/lib plays no kind of special bootstrapping role any more and bootstrapping is done exclusively through packages, so releases depend even less on the state of the machine making them now. . rename nbsd_lib* to lib* . reduce mtree
333 lines
8.3 KiB
Groff
333 lines
8.3 KiB
Groff
.\" $NetBSD: gethostbyname.3,v 1.28 2006/10/07 21:30:39 apb 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.
|
|
.\"
|
|
.\" @(#)gethostbyname.3 8.4 (Berkeley) 5/25/95
|
|
.\"
|
|
.Dd October 7, 2006
|
|
.Dt GETHOSTBYNAME 3
|
|
.Os
|
|
.Sh NAME
|
|
.Nm gethostbyname ,
|
|
.Nm gethostbyname2 ,
|
|
.Nm gethostbyaddr ,
|
|
.Nm gethostent ,
|
|
.Nm sethostent ,
|
|
.Nm endhostent ,
|
|
.Nm herror ,
|
|
.Nm hstrerror
|
|
.Nd get network host entry
|
|
.Sh LIBRARY
|
|
.Lb libc
|
|
.Sh SYNOPSIS
|
|
.In 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" "socklen_t len" "int type"
|
|
.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.
|
|
.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 alternative 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
|
|
In the case of
|
|
.Fn gethostbyname
|
|
and
|
|
.Fn gethostbyname2 ,
|
|
the host is specified by name,
|
|
or using a string representation of a numeric address.
|
|
In the case of
|
|
.Fn gethostbyaddr ,
|
|
the host is specified using a binary representation of an address.
|
|
.Pp
|
|
The returned
|
|
.Ft "struct hostent"
|
|
structure may contain
|
|
the result of a simple string to binary conversion,
|
|
information obtained from the domain name resolver (see
|
|
.Xr resolver 3 ) ,
|
|
broken-out fields from a line in
|
|
.Pa /etc/hosts ,
|
|
or database entries supplied by the
|
|
.Xr yp 8
|
|
system.
|
|
The order of the lookups is controlled by the
|
|
.Sq hosts
|
|
entry in
|
|
.Xr nsswitch.conf 5 .
|
|
.Pp
|
|
When using the domain name resolver,
|
|
.Fn gethostbyname
|
|
and
|
|
.Fn gethostbyname2
|
|
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 gethostbyname2
|
|
function is an evolution of
|
|
.Fn gethostbyname
|
|
which is intended to allow lookups in address families other than
|
|
.Dv AF_INET ,
|
|
for example
|
|
.Dv AF_INET6 .
|
|
Currently the
|
|
.Fa af
|
|
argument must be specified as
|
|
.Dv AF_INET
|
|
or
|
|
.Dv AF_INET6 ,
|
|
else the function will return
|
|
.Dv NULL
|
|
after having set
|
|
.Va h_errno
|
|
to
|
|
.Dv NETDB_INTERNAL .
|
|
.Pp
|
|
The
|
|
.Fn gethostent
|
|
function
|
|
reads the next line of the
|
|
.Pa /etc/hosts
|
|
file, opening the file if necessary.
|
|
.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 ,
|
|
.Fn gethostbyname2 ,
|
|
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 writes a message to the diagnostic output consisting of the
|
|
string parameter
|
|
.Fa s ,
|
|
the constant string ": ", and a message corresponding to the value of
|
|
.Va h_errno .
|
|
.Pp
|
|
The
|
|
.Fn hstrerror
|
|
function returns a string which is the message text corresponding to the
|
|
value of the
|
|
.Fa err
|
|
parameter.
|
|
.Sh FILES
|
|
.Bl -tag -width /etc/hosts -compact
|
|
.It Pa /etc/hosts
|
|
.El
|
|
.Sh DIAGNOSTICS
|
|
Error return status from
|
|
.Fn gethostbyent ,
|
|
.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.
|
|
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 nsswitch.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 .
|
|
The
|
|
.Fn gethostbyname2
|
|
function first appeared in bind-4.9.4.
|
|
IPv6 support was implemented in WIDE Hydrangea IPv6 protocol stack kit.
|
|
.Sh CAVEATS
|
|
If the search routines specified in
|
|
.Xr nsswitch.conf 5
|
|
decide to read the
|
|
.Pa /etc/hosts
|
|
file,
|
|
.Fn gethostbyname ,
|
|
.Fn gethostbyname2 ,
|
|
and
|
|
.Fn gethostbyaddr
|
|
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 ,
|
|
.Fn gethostbyaddr ,
|
|
or
|
|
.Fn gethostent .
|
|
.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 format is currently understood.
|
|
.Pp
|
|
The
|
|
.Fn gethostent
|
|
does not currently follow the search order specified in
|
|
.Xr nsswitch.conf 5
|
|
and only reads the
|
|
.Pa /etc/hosts
|
|
file.
|