mirror of https://github.com/mkerrisk/man-pages
150 lines
5.3 KiB
Plaintext
150 lines
5.3 KiB
Plaintext
.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved
|
|
.TH "GETHOSTBYADDR" 3P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
|
|
.\" gethostbyaddr
|
|
.SH PROLOG
|
|
This manual page is part of the POSIX Programmer's Manual.
|
|
The Linux implementation of this interface may differ (consult
|
|
the corresponding Linux manual page for details of Linux behavior),
|
|
or the interface may not be implemented on Linux.
|
|
.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 .
|