.\" $OpenBSD: gethostbyname.3,v 1.16 2000/12/24 00:30:56 aaron Exp $
|
.\" $OpenBSD: gethostbyname.3,v 1.16 2000/12/24 00:30:56 aaron Exp $
|
.\"
|
.\"
|
.\" Copyright (c) 1983, 1987, 1991, 1993
|
.\" Copyright (c) 1983, 1987, 1991, 1993
|
.\" The Regents of the University of California. All rights reserved.
|
.\" The Regents of the University of California. All rights reserved.
|
.\"
|
.\"
|
.\" Redistribution and use in source and binary forms, with or without
|
.\" Redistribution and use in source and binary forms, with or without
|
.\" modification, are permitted provided that the following conditions
|
.\" modification, are permitted provided that the following conditions
|
.\" are met:
|
.\" are met:
|
.\" 1. Redistributions of source code must retain the above copyright
|
.\" 1. Redistributions of source code must retain the above copyright
|
.\" notice, this list of conditions and the following disclaimer.
|
.\" notice, this list of conditions and the following disclaimer.
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
.\" notice, this list of conditions and the following disclaimer in the
|
.\" notice, this list of conditions and the following disclaimer in the
|
.\" documentation and/or other materials provided with the distribution.
|
.\" documentation and/or other materials provided with the distribution.
|
.\" 3. All advertising materials mentioning features or use of this software
|
.\" 3. All advertising materials mentioning features or use of this software
|
.\" must display the following acknowledgement:
|
.\" must display the following acknowledgement:
|
.\" This product includes software developed by the University of
|
.\" This product includes software developed by the University of
|
.\" California, Berkeley and its contributors.
|
.\" California, Berkeley and its contributors.
|
.\" 4. Neither the name of the University nor the names of 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
|
.\" may be used to endorse or promote products derived from this software
|
.\" without specific prior written permission.
|
.\" without specific prior written permission.
|
.\"
|
.\"
|
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
|
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
|
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
|
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
|
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
|
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
|
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
|
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
|
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
|
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
|
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
|
.\" 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
|
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
|
.\" SUCH DAMAGE.
|
.\" SUCH DAMAGE.
|
.\"
|
.\"
|
.Dd March 13, 1997
|
.Dd March 13, 1997
|
.Dt GETHOSTBYNAME 3
|
.Dt GETHOSTBYNAME 3
|
.Os
|
.Os
|
.Sh NAME
|
.Sh NAME
|
.Nm gethostbyname ,
|
.Nm gethostbyname ,
|
.Nm gethostbyname2 ,
|
.Nm gethostbyname2 ,
|
.Nm gethostbyaddr ,
|
.Nm gethostbyaddr ,
|
.Nm gethostent ,
|
.Nm gethostent ,
|
.Nm sethostent ,
|
.Nm sethostent ,
|
.Nm endhostent ,
|
.Nm endhostent ,
|
.Nm hstrerror ,
|
.Nm hstrerror ,
|
.Nm herror
|
.Nm herror
|
.Nd get network host entry
|
.Nd get network host entry
|
.Sh SYNOPSIS
|
.Sh SYNOPSIS
|
.Fd #include
|
.Fd #include
|
.Fd extern int h_errno;
|
.Fd extern int h_errno;
|
.Ft struct hostent *
|
.Ft struct hostent *
|
.Fn gethostbyname "const char *name"
|
.Fn gethostbyname "const char *name"
|
.Ft struct hostent *
|
.Ft struct hostent *
|
.Fn gethostbyname2 "const char *name" "int af"
|
.Fn gethostbyname2 "const char *name" "int af"
|
.Ft struct hostent *
|
.Ft struct hostent *
|
.Fn gethostbyaddr "const char *addr" "int len" "int af"
|
.Fn gethostbyaddr "const char *addr" "int len" "int af"
|
.Ft struct hostent *
|
.Ft struct hostent *
|
.Fn gethostent void
|
.Fn gethostent void
|
.Ft void
|
.Ft void
|
.Fn sethostent "int stayopen"
|
.Fn sethostent "int stayopen"
|
.Ft void
|
.Ft void
|
.Fn endhostent void
|
.Fn endhostent void
|
.Ft void
|
.Ft void
|
.Fn herror "const char *string"
|
.Fn herror "const char *string"
|
.Ft const char *
|
.Ft const char *
|
.Fn hstrerror "int err"
|
.Fn hstrerror "int err"
|
.Sh DESCRIPTION
|
.Sh DESCRIPTION
|
The
|
The
|
.Fn gethostbyname
|
.Fn gethostbyname
|
and
|
and
|
.Fn gethostbyaddr
|
.Fn gethostbyaddr
|
functions each return a pointer to an object with the following structure
|
functions each return a pointer to an object with the following structure
|
describing an internet host referenced by name or by address, respectively.
|
describing an internet host referenced by name or by address, respectively.
|
This structure contains either information obtained from the name server (i.e.,
|
This structure contains either information obtained from the name server (i.e.,
|
.Xr resolver 3
|
.Xr resolver 3
|
and
|
and
|
.Xr named 8 ) ,
|
.Xr named 8 ) ,
|
broken-out fields from a line in
|
broken-out fields from a line in
|
.Pa /etc/hosts ,
|
.Pa /etc/hosts ,
|
or database entries supplied by the
|
or database entries supplied by the
|
.Xr yp 8
|
.Xr yp 8
|
system.
|
system.
|
.Xr resolv.conf 5
|
.Xr resolv.conf 5
|
describes how the particular database is chosen.
|
describes how the particular database is chosen.
|
.Bd -literal
|
.Bd -literal
|
struct hostent {
|
struct hostent {
|
char *h_name; /* official name of host */
|
char *h_name; /* official name of host */
|
char **h_aliases; /* alias list */
|
char **h_aliases; /* alias list */
|
int h_addrtype; /* host address type */
|
int h_addrtype; /* host address type */
|
int h_length; /* length of address */
|
int h_length; /* length of address */
|
char **h_addr_list; /* list of addresses from name server */
|
char **h_addr_list; /* list of addresses from name server */
|
};
|
};
|
#define h_addr h_addr_list[0] /* address, for backward compatibility */
|
#define h_addr h_addr_list[0] /* address, for backward compatibility */
|
.Ed
|
.Ed
|
.Pp
|
.Pp
|
The members of this structure are:
|
The members of this structure are:
|
.Bl -tag -width h_addr_list
|
.Bl -tag -width h_addr_list
|
.It Fa h_name
|
.It Fa h_name
|
Official name of the host.
|
Official name of the host.
|
.It Fa h_aliases
|
.It Fa h_aliases
|
A zero-terminated array of alternate names for the host.
|
A zero-terminated array of alternate names for the host.
|
.It Fa h_addrtype
|
.It Fa h_addrtype
|
The type of address being returned.
|
The type of address being returned.
|
.It Fa h_length
|
.It Fa h_length
|
The length, in bytes, of the address.
|
The length, in bytes, of the address.
|
.It Fa h_addr_list
|
.It Fa h_addr_list
|
A zero-terminated array of network addresses for the host.
|
A zero-terminated array of network addresses for the host.
|
Host addresses are returned in network byte order.
|
Host addresses are returned in network byte order.
|
.It Fa h_addr
|
.It Fa h_addr
|
The first address in
|
The first address in
|
.Fa h_addr_list ;
|
.Fa h_addr_list ;
|
this is for backward compatibility.
|
this is for backward compatibility.
|
.El
|
.El
|
.Pp
|
.Pp
|
The function
|
The function
|
.Fn gethostbyname
|
.Fn gethostbyname
|
will search for the named host in the current domain and its parents
|
will search for the named host in the current domain and its parents
|
using the search lookup semantics detailed in
|
using the search lookup semantics detailed in
|
.Xr resolv.conf 5
|
.Xr resolv.conf 5
|
and
|
and
|
.Xr hostname 7 .
|
.Xr hostname 7 .
|
.Pp
|
.Pp
|
.Fn gethostbyname2
|
.Fn gethostbyname2
|
is an advanced form of
|
is an advanced form of
|
.Fn gethostbyname
|
.Fn gethostbyname
|
which allows lookups in address families other than
|
which allows lookups in address families other than
|
.Dv AF_INET ,
|
.Dv AF_INET ,
|
for example
|
for example
|
.Dv AF_INET6 .
|
.Dv AF_INET6 .
|
.Pp
|
.Pp
|
The
|
The
|
.Fn gethostbyaddr
|
.Fn gethostbyaddr
|
function will search for the specified address of length
|
function will search for the specified address of length
|
.Fa len
|
.Fa len
|
in the address family
|
in the address family
|
.Fa af .
|
.Fa af .
|
The only address family currently supported is
|
The only address family currently supported is
|
.Dv AF_INET .
|
.Dv AF_INET .
|
.Pp
|
.Pp
|
The
|
The
|
.Fn sethostent
|
.Fn sethostent
|
function may be used to request the use of a connected
|
function may be used to request the use of a connected
|
.Tn TCP
|
.Tn TCP
|
socket for queries.
|
socket for queries.
|
If the
|
If the
|
.Fa stayopen
|
.Fa stayopen
|
flag is non-zero,
|
flag is non-zero,
|
this sets the option to send all queries to the name server using
|
this sets the option to send all queries to the name server using
|
.Tn TCP
|
.Tn TCP
|
and to retain the connection after each call to
|
and to retain the connection after each call to
|
.Fn gethostbyname
|
.Fn gethostbyname
|
or
|
or
|
.Fn gethostbyaddr .
|
.Fn gethostbyaddr .
|
Otherwise, queries are performed using
|
Otherwise, queries are performed using
|
.Tn UDP
|
.Tn UDP
|
datagrams.
|
datagrams.
|
.Pp
|
.Pp
|
The
|
The
|
.Fn endhostent
|
.Fn endhostent
|
function closes the
|
function closes the
|
.Tn TCP
|
.Tn TCP
|
connection.
|
connection.
|
.Pp
|
.Pp
|
The
|
The
|
.Fn herror
|
.Fn herror
|
function prints an error message describing the failure.
|
function prints an error message describing the failure.
|
If its argument
|
If its argument
|
.Fa string
|
.Fa string
|
is non-null,
|
is non-null,
|
it is prepended to the message string and separated from it by a colon
|
it is prepended to the message string and separated from it by a colon
|
.Pq Ql \&:
|
.Pq Ql \&:
|
and a space.
|
and a space.
|
The error message is printed with a trailing newline.
|
The error message is printed with a trailing newline.
|
The contents of the error message is the same as that returned by
|
The contents of the error message is the same as that returned by
|
.Fn hstrerror
|
.Fn hstrerror
|
with argument
|
with argument
|
.Fa h_errno .
|
.Fa h_errno .
|
.Sh FILES
|
.Sh FILES
|
.Bl -tag -width /etc/resolv.conf -compact
|
.Bl -tag -width /etc/resolv.conf -compact
|
.It Pa /etc/hosts
|
.It Pa /etc/hosts
|
.It Pa /etc/resolv.conf
|
.It Pa /etc/resolv.conf
|
.El
|
.El
|
.Sh DIAGNOSTICS
|
.Sh DIAGNOSTICS
|
Error return status from
|
Error return status from
|
.Fn gethostbyname ,
|
.Fn gethostbyname ,
|
.Fn gethostbyname2 ,
|
.Fn gethostbyname2 ,
|
and
|
and
|
.Fn gethostbyaddr
|
.Fn gethostbyaddr
|
is indicated by return of a null pointer.
|
is indicated by return of a null pointer.
|
The external integer
|
The external integer
|
.Va h_errno
|
.Va h_errno
|
may then be checked to see whether this is a temporary failure
|
may then be checked to see whether this is a temporary failure
|
or an invalid or unknown host.
|
or an invalid or unknown host.
|
.Pp
|
.Pp
|
The variable
|
The variable
|
.Va h_errno
|
.Va h_errno
|
can have the following values:
|
can have the following values:
|
.Bl -tag -width HOST_NOT_FOUND
|
.Bl -tag -width HOST_NOT_FOUND
|
.It Dv HOST_NOT_FOUND
|
.It Dv HOST_NOT_FOUND
|
No such host is known.
|
No such host is known.
|
.It Dv TRY_AGAIN
|
.It Dv TRY_AGAIN
|
This is usually a temporary error
|
This is usually a temporary error
|
and means that the local server did not receive
|
and means that the local server did not receive
|
a response from an authoritative server.
|
a response from an authoritative server.
|
A retry at some later time may succeed.
|
A retry at some later time may succeed.
|
.It Dv NO_RECOVERY
|
.It Dv NO_RECOVERY
|
Some unexpected server failure was encountered.
|
Some unexpected server failure was encountered.
|
This is a non-recoverable error.
|
This is a non-recoverable error.
|
.It Dv NO_DATA
|
.It Dv NO_DATA
|
The requested name is valid but does not have an IP address;
|
The requested name is valid but does not have an IP address;
|
this is not a temporary error.
|
this is not a temporary error.
|
This means that the name is known to the name server but there is no address
|
This means that the name is known to the name server but there is no address
|
associated with this name.
|
associated with this name.
|
Another type of request to the name server using this domain name
|
Another type of request to the name server using this domain name
|
will result in an answer;
|
will result in an answer;
|
for example, a mail-forwarder may be registered for this domain.
|
for example, a mail-forwarder may be registered for this domain.
|
.El
|
.El
|
.Sh SEE ALSO
|
.Sh SEE ALSO
|
.Xr resolver 3 ,
|
.Xr resolver 3 ,
|
.Xr getaddrinfo 3 ,
|
.Xr getaddrinfo 3 ,
|
.Xr getnameinfo 3 ,
|
.Xr getnameinfo 3 ,
|
.Xr hosts 5 ,
|
.Xr hosts 5 ,
|
.Xr resolv.conf 5 ,
|
.Xr resolv.conf 5 ,
|
.Xr hostname 7 ,
|
.Xr hostname 7 ,
|
.Xr named 8
|
.Xr named 8
|
.Sh CAVEAT
|
.Sh CAVEAT
|
If the search routines in
|
If the search routines in
|
.Xr resolv.conf 5
|
.Xr resolv.conf 5
|
decide to read the
|
decide to read the
|
.Pa /etc/hosts
|
.Pa /etc/hosts
|
file,
|
file,
|
.Fn gethostent
|
.Fn gethostent
|
and other functions will
|
and other functions will
|
read the next line of the file,
|
read the next line of the file,
|
re-opening the file if necessary.
|
re-opening the file if necessary.
|
.Pp
|
.Pp
|
The
|
The
|
.Fn sethostent
|
.Fn sethostent
|
function opens and/or rewinds the file
|
function opens and/or rewinds the file
|
.Pa /etc/hosts .
|
.Pa /etc/hosts .
|
If the
|
If the
|
.Fa stayopen
|
.Fa stayopen
|
argument is non-zero, the file will not be closed after each call to
|
argument is non-zero, the file will not be closed after each call to
|
.Fn gethostbyname ,
|
.Fn gethostbyname ,
|
.Fn gethostbyname2 ,
|
.Fn gethostbyname2 ,
|
or
|
or
|
.Fn gethostbyaddr .
|
.Fn gethostbyaddr .
|
.Pp
|
.Pp
|
The
|
The
|
.Fn endhostent
|
.Fn endhostent
|
function closes the file.
|
function closes the file.
|
.Sh HISTORY
|
.Sh HISTORY
|
The
|
The
|
.Fn herror
|
.Fn herror
|
function appeared in
|
function appeared in
|
.Bx 4.3 .
|
.Bx 4.3 .
|
The
|
The
|
.Fn endhostent ,
|
.Fn endhostent ,
|
.Fn gethostbyaddr ,
|
.Fn gethostbyaddr ,
|
.Fn gethostbyname ,
|
.Fn gethostbyname ,
|
.Fn gethostent ,
|
.Fn gethostent ,
|
and
|
and
|
.Fn sethostent
|
.Fn sethostent
|
functions appeared in
|
functions appeared in
|
.Bx 4.2 .
|
.Bx 4.2 .
|
.Sh BUGS
|
.Sh BUGS
|
These functions use static data storage;
|
These functions use static data storage;
|
if the data is needed for future use, it should be
|
if the data is needed for future use, it should be
|
copied before any subsequent calls overwrite it.
|
copied before any subsequent calls overwrite it.
|
Only the Internet
|
Only the Internet
|
address formats are currently understood.
|
address formats are currently understood.
|
.Pp
|
.Pp
|
YP does not support any address families other than
|
YP does not support any address families other than
|
.Dv AF_INET
|
.Dv AF_INET
|
and uses
|
and uses
|
the traditional database format.
|
the traditional database format.
|
|
|
