\"      $NetBSD: gethostbyname.3,v 1.30 2022/12/04 01:29:32 uwe 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 August 19, 2013
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 void *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 RETURN VALUES
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.

You are viewing proxied material from ftp.icm.edu.pl. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.