.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved 
.TH "GETHOSTBYADDR" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
.\" gethostbyaddr 
.SH NAME
gethostbyaddr, gethostbyname \- network host database functions
.SH SYNOPSIS
.LP
\fB#include <netdb.h>
.br
.sp
\fP
.LP
\fBstruct hostent *gethostbyaddr(const void *\fP\fIaddr\fP\fB, socklen_t\fP
\fIlen\fP\fB,
.br
\ \ \ \ \ \  int\fP \fItype\fP\fB);
.br
struct hostent *gethostbyname(const char *\fP\fIname\fP\fB); \fP
\fB
.br
\fP
.SH DESCRIPTION
.LP
These functions shall retrieve information about hosts. This information
is considered to be stored in a database that can be
accessed sequentially or randomly. Implementation of this database
is unspecified. 
.TP 7
\fBNote:\fP
In many cases it is implemented by the Domain Name System, as documented
in RFC\ 1034, RFC\ 1035, and
RFC\ 1886.
.sp
.LP
Entries shall be returned in \fBhostent\fP structures.
.LP
The \fIgethostbyaddr\fP() function shall return an entry containing
addresses of address family \fItype\fP for the host with
address \fIaddr\fP. The \fIlen\fP argument contains the length of
the address pointed to by \fIaddr\fP. The
\fIgethostbyaddr\fP() function need not be reentrant. A function that
is not required to be reentrant is not required to be
thread-safe.
.LP
The \fIgethostbyname\fP() function shall return an entry containing
addresses of address family AF_INET for the host with name
\fIname\fP. The \fIgethostbyname\fP() function need not be reentrant.
A function that is not required to be reentrant is not
required to be thread-safe.
.LP
The \fIaddr\fP argument of \fIgethostbyaddr\fP() shall be an \fBin_addr\fP
structure when \fItype\fP is AF_INET. It contains
a binary format (that is, not null-terminated) address in network
byte order. The \fIgethostbyaddr\fP() function is not guaranteed
to return addresses of address families other than AF_INET, even when
such addresses exist in the database.
.LP
If \fIgethostbyaddr\fP() returns successfully, then the \fIh_addrtype\fP
field in the result shall be the same as the
\fItype\fP argument that was passed to the function, and the \fIh_addr_list\fP
field shall list a single address that is a copy
of the \fIaddr\fP argument that was passed to the function.
.LP
The \fIname\fP argument of \fIgethostbyname\fP() shall be a node name;
the behavior of \fIgethostbyname\fP() when passed a
numeric address string is unspecified. For IPv4, a numeric address
string shall be in the dotted-decimal notation described in \fIinet_addr\fP()
\&.
.LP
If \fIname\fP is not a numeric address string and is an alias for
a valid host name, then \fIgethostbyname\fP() shall return
information about the host name to which the alias refers, and \fIname\fP
shall be included in the list of aliases returned.
.SH RETURN VALUE
.LP
Upon successful completion, these functions shall return a pointer
to a \fBhostent\fP structure if the requested entry was
found, and a null pointer if the end of the database was reached or
the requested entry was not found.
.LP
Upon unsuccessful completion, \fIgethostbyaddr\fP() and \fIgethostbyname\fP()
shall set \fIh_errno\fP to indicate the
error.
.SH ERRORS
.LP
These functions shall fail in the following cases. The \fIgethostbyaddr\fP()
and \fIgethostbyname\fP() functions shall set
\fIh_errno\fP to the value shown in the list below. Any changes to
\fIerrno\fP are unspecified.
.TP 7
.B HOST_NOT_FOUND
.sp
No such host is known.
.TP 7
.B NO_DATA
The server recognized the request and the name, but no address is
available. Another type of request to the name server for the
domain might return an answer.
.TP 7
.B NO_RECOVERY
.sp
An unexpected server failure occurred which cannot be recovered.
.TP 7
.B TRY_AGAIN
A temporary and possibly transient error occurred, such as a failure
of a server to respond.
.sp
.LP
\fIThe following sections are informative.\fP
.SH EXAMPLES
.LP
None.
.SH APPLICATION USAGE
.LP
The \fIgethostbyaddr\fP() and \fIgethostbyname\fP() functions may
return pointers to static data, which may be overwritten by
subsequent calls to any of these functions.
.LP
The \fIgetaddrinfo\fP() and \fIgetnameinfo\fP() functions are preferred
over the \fIgethostbyaddr\fP() and
\fIgethostbyname\fP() functions.
.SH RATIONALE
.LP
None.
.SH FUTURE DIRECTIONS
.LP
The \fIgethostbyaddr\fP() and \fIgethostbyname\fP() functions may
be withdrawn in a future version.
.SH SEE ALSO
.LP
\fIendhostent\fP() , \fIendservent\fP() , \fIgai_strerror\fP() , \fIgetaddrinfo\fP()
, \fIh_errno\fP() , \fIinet_addr\fP() , the Base Definitions volume
of
IEEE\ Std\ 1003.1-2001, \fI<netdb.h>\fP
.SH COPYRIGHT
Portions of this text are reprinted and reproduced in electronic form
from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
-- Portable Operating System Interface (POSIX), The Open Group Base
Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
Electrical and Electronics Engineers, Inc and The Open Group. In the
event of any discrepancy between this version and the original IEEE and
The Open Group Standard, the original IEEE and The Open Group Standard
is the referee document. The original Standard can be obtained online at
http://www.opengroup.org/unix/online.html .