diff options
Diffstat (limited to 'man3p/gethostbyname.3p')
| -rw-r--r-- | man3p/gethostbyname.3p | 144 |
1 files changed, 144 insertions, 0 deletions
diff --git a/man3p/gethostbyname.3p b/man3p/gethostbyname.3p new file mode 100644 index 000000000..8c5daaad8 --- /dev/null +++ b/man3p/gethostbyname.3p @@ -0,0 +1,144 @@ +.\" 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 . |