diff options
Diffstat (limited to 'man3/gethostbyname.3')
| -rw-r--r-- | man3/gethostbyname.3 | 553 |
1 files changed, 0 insertions, 553 deletions
diff --git a/man3/gethostbyname.3 b/man3/gethostbyname.3 deleted file mode 100644 index 01cc0f7..0000000 --- a/man3/gethostbyname.3 +++ /dev/null @@ -1,553 +0,0 @@ -'\" t -.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) -.\" -.\" SPDX-License-Identifier: Linux-man-pages-copyleft -.\" -.\" References consulted: -.\" Linux libc source code -.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) -.\" 386BSD man pages -.\" Modified 1993-05-22, David Metcalfe -.\" Modified 1993-07-25, Rik Faith (faith@cs.unc.edu) -.\" Modified 1997-02-16, Andries Brouwer (aeb@cwi.nl) -.\" Modified 1998-12-21, Andries Brouwer (aeb@cwi.nl) -.\" Modified 2000-08-12, Andries Brouwer (aeb@cwi.nl) -.\" Modified 2001-05-19, Andries Brouwer (aeb@cwi.nl) -.\" Modified 2002-08-05, Michael Kerrisk -.\" Modified 2004-10-31, Andries Brouwer -.\" -.TH gethostbyname 3 2023-10-31 "Linux man-pages 6.7" -.SH NAME -gethostbyname, gethostbyaddr, sethostent, gethostent, endhostent, -h_errno, -herror, hstrerror, -gethostbyaddr_r, -gethostbyname2, gethostbyname2_r, gethostbyname_r, -gethostent_r \- get network host entry -.SH LIBRARY -Standard C library -.RI ( libc ", " \-lc ) -.SH SYNOPSIS -.nf -.B #include <netdb.h> -.P -.BI "void sethostent(int " stayopen ); -.B void endhostent(void); -.P -.B [[deprecated]] extern int h_errno; -.P -.BI "[[deprecated]] struct hostent *gethostbyname(const char *" name ); -.BI "[[deprecated]] struct hostent *gethostbyaddr(const void " addr [. len ], -.BI " socklen_t " len ", int " type ); -.P -.BI "[[deprecated]] void herror(const char *" s ); -.BI "[[deprecated]] const char *hstrerror(int " err ); -.P -/* System V/POSIX extension */ -.B struct hostent *gethostent(void); -.P -/* GNU extensions */ -.B [[deprecated]] -.BI "struct hostent *gethostbyname2(const char *" name ", int " af ); -.P -.BI "int gethostent_r(struct hostent *restrict " ret , -.BI " char " buf "[restrict ." buflen "], size_t " buflen , -.BI " struct hostent **restrict " result , -.BI " int *restrict " h_errnop ); -.P -.B [[deprecated]] -.BI "int gethostbyaddr_r(const void " addr "[restrict ." len "], socklen_t " len , -.BI " int " type , -.BI " struct hostent *restrict " ret , -.BI " char " buf "[restrict ." buflen "], size_t " buflen , -.BI " struct hostent **restrict " result , -.BI " int *restrict " h_errnop ); -.B [[deprecated]] -.BI "int gethostbyname_r(const char *restrict " name , -.BI " struct hostent *restrict " ret , -.BI " char " buf "[restrict ." buflen "], size_t " buflen , -.BI " struct hostent **restrict " result , -.BI " int *restrict " h_errnop ); -.B [[deprecated]] -.BI "int gethostbyname2_r(const char *restrict " name ", int " af, -.BI " struct hostent *restrict " ret , -.BI " char " buf "[restrict ." buflen "], size_t " buflen , -.BI " struct hostent **restrict " result , -.BI " int *restrict " h_errnop ); -.fi -.P -.RS -4 -Feature Test Macro Requirements for glibc (see -.BR feature_test_macros (7)): -.RE -.P -.BR gethostbyname2 (), -.BR gethostent_r (), -.BR gethostbyaddr_r (), -.BR gethostbyname_r (), -.BR gethostbyname2_r (): -.nf - Since glibc 2.19: - _DEFAULT_SOURCE - glibc up to and including 2.19: - _BSD_SOURCE || _SVID_SOURCE -.fi -.P -.BR herror (), -.BR hstrerror (): -.nf - Since glibc 2.19: - _DEFAULT_SOURCE - glibc 2.8 to glibc 2.19: - _BSD_SOURCE || _SVID_SOURCE - Before glibc 2.8: - none -.fi -.P -.BR h_errno : -.nf - Since glibc 2.19 - _DEFAULT_SOURCE || _POSIX_C_SOURCE < 200809L - glibc 2.12 to glibc 2.19: - _BSD_SOURCE || _SVID_SOURCE || _POSIX_C_SOURCE < 200809L - Before glibc 2.12: - none -.fi -.SH DESCRIPTION -The -.BR gethostbyname* (), -.BR gethostbyaddr* (), -.BR herror (), -and -.BR hstrerror () -functions are obsolete. -Applications should use -.BR getaddrinfo (3), -.BR getnameinfo (3), -and -.BR gai_strerror (3) -instead. -.P -The -.BR sethostent () -function specifies, if \fIstayopen\fP is true (1), -that a connected TCP socket should be used for the name server queries and -that the connection should remain open during successive queries. -Otherwise, name server queries will use UDP datagrams. -.P -The -.BR endhostent () -function ends the use of a TCP connection for name -server queries. -.P -The -.BR gethostbyname () -function returns a structure of type -.I hostent -for the given host -.IR name . -Here -.I name -is either a hostname or an IPv4 address in standard dot notation (as for -.BR inet_addr (3)). -If -.I name -is an IPv4 address, no lookup is performed and -.BR gethostbyname () -simply copies -.I name -into the -.I h_name -field and its -.I struct in_addr -equivalent into the -.I h_addr_list[0] -field of the returned -.I hostent -structure. -If -.I name -doesn't end in a dot and the environment variable -.B HOSTALIASES -is set, the alias file pointed to by -.B HOSTALIASES -will first be searched for -.I name -(see -.BR hostname (7) -for the file format). -The current domain and its parents are searched unless \fIname\fP -ends in a dot. -.P -The -.BR gethostbyaddr () -function returns a structure of type \fIhostent\fP -for the given host address \fIaddr\fP of length \fIlen\fP and address type -\fItype\fP. -Valid address types are -.B AF_INET -and -.B AF_INET6 -(defined in -.IR <sys/socket.h> ). -The host address argument is a pointer to a struct of a type depending -on the address type, for example a \fIstruct in_addr *\fP (probably -obtained via a call to -.BR inet_addr (3)) -for address type -.BR AF_INET . -.P -The (obsolete) -.BR herror () -function prints the error message associated -with the current value of \fIh_errno\fP on \fIstderr\fP. -.P -The (obsolete) -.BR hstrerror () -function takes an error number -(typically \fIh_errno\fP) and returns the corresponding message string. -.P -The domain name queries carried out by -.BR gethostbyname () -and -.BR gethostbyaddr () -rely on the Name Service Switch -.RB ( nsswitch.conf (5)) -configured sources or a local name server -.RB ( named (8)). -The default action is to query the Name Service Switch -.RB ( nsswitch.conf (5)) -configured sources, failing that, a local name server -.RB ( named (8)). -.\" -.SS Historical -The -.BR nsswitch.conf (5) -file is the modern way of controlling the order of host lookups. -.P -In glibc 2.4 and earlier, the -.I order -keyword was used to control the order of host lookups as defined in -.I /etc/host.conf -.RB ( host.conf (5)). -.P -The \fIhostent\fP structure is defined in \fI<netdb.h>\fP as follows: -.P -.in +4n -.EX -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 */ -} -#define h_addr h_addr_list[0] /* for backward compatibility */ -.EE -.in -.P -The members of the \fIhostent\fP structure are: -.TP -.I h_name -The official name of the host. -.TP -.I h_aliases -An array of alternative names for the host, terminated by a null pointer. -.TP -.I h_addrtype -The type of address; always -.B AF_INET -or -.B AF_INET6 -at present. -.TP -.I h_length -The length of the address in bytes. -.TP -.I h_addr_list -An array of pointers to network addresses for the host (in network byte -order), terminated by a null pointer. -.TP -.I h_addr -The first address in \fIh_addr_list\fP for backward compatibility. -.SH RETURN VALUE -The -.BR gethostbyname () -and -.BR gethostbyaddr () -functions return the -.I hostent -structure or a null pointer if an error occurs. -On error, the -.I h_errno -variable holds an error number. -When non-NULL, the return value may point at static data, see the notes below. -.SH ERRORS -The variable \fIh_errno\fP can have the following values: -.TP -.B HOST_NOT_FOUND -The specified host is unknown. -.TP -.B NO_DATA -The requested name is valid but does not have an IP address. -Another type of request to the name server for this domain -may return an answer. -The constant -.B NO_ADDRESS -is a synonym for -.BR NO_DATA . -.TP -.B NO_RECOVERY -A nonrecoverable name server error occurred. -.TP -.B TRY_AGAIN -A temporary error occurred on an authoritative name server. -Try again later. -.SH FILES -.TP -.I /etc/host.conf -resolver configuration file -.TP -.I /etc/hosts -host database file -.TP -.I /etc/nsswitch.conf -name service switch configuration -.SH ATTRIBUTES -For an explanation of the terms used in this section, see -.BR attributes (7). -.TS -allbox; -lb lb lbx -l l l. -Interface Attribute Value -T{ -.na -.nh -.BR gethostbyname () -T} Thread safety T{ -.na -.nh -MT-Unsafe race:hostbyname env -locale -T} -T{ -.na -.nh -.BR gethostbyaddr () -T} Thread safety T{ -.na -.nh -MT-Unsafe race:hostbyaddr env -locale -T} -T{ -.na -.nh -.BR sethostent (), -.BR endhostent (), -.BR gethostent_r () -T} Thread safety T{ -.na -.nh -MT-Unsafe race:hostent env -locale -T} -T{ -.na -.nh -.BR herror (), -.BR hstrerror () -T} Thread safety MT-Safe -T{ -.na -.nh -.BR gethostent () -T} Thread safety T{ -.na -.nh -MT-Unsafe race:hostent -race:hostentbuf env locale -T} -T{ -.na -.nh -.BR gethostbyname2 () -T} Thread safety T{ -.na -.nh -MT-Unsafe race:hostbyname2 -env locale -T} -T{ -.na -.nh -.BR gethostbyaddr_r (), -.BR gethostbyname_r (), -.BR gethostbyname2_r () -T} Thread safety MT-Safe env locale -.TE -.P -In the above table, -.I hostent -in -.I race:hostent -signifies that if any of the functions -.BR sethostent (), -.BR gethostent (), -.BR gethostent_r (), -or -.BR \%endhostent () -are used in parallel in different threads of a program, -then data races could occur. -.SH STANDARDS -.TP -.BR sethostent () -.TQ -.BR endhostent () -.TQ -.BR gethostent () -POSIX.1-2008. -.TP -.BR gethostent_r () -GNU. -.TP -Others: -None. -.SH HISTORY -.TP -.BR sethostent () -.TQ -.BR endhostent () -.TQ -.BR gethostent () -POSIX.1-2001. -.TP -.BR gethostbyname () -.TQ -.BR gethostbyaddr () -.TQ -.I h_errno -Marked obsolescent in POSIX.1-2001. -Removed in POSIX.1-2008, -recommending the use of -.BR getaddrinfo (3) -and -.BR getnameinfo (3) -instead. -.SH NOTES -The functions -.BR gethostbyname () -and -.BR gethostbyaddr () -may return pointers to static data, which may be overwritten by -later calls. -Copying the -.I struct hostent -does not suffice, since it contains pointers; a deep copy is required. -.P -In the original BSD implementation the -.I len -argument -of -.BR gethostbyname () -was an -.IR int . -The SUSv2 standard is buggy and declares the -.I len -argument of -.BR gethostbyaddr () -to be of type -.IR size_t . -(That is wrong, because it has to be -.IR int , -and -.I size_t -is not. -POSIX.1-2001 makes it -.IR socklen_t , -which is OK.) -See also -.BR accept (2). -.P -The BSD prototype for -.BR gethostbyaddr () -uses -.I "const char\ *" -for the first argument. -.SS System V/POSIX extension -POSIX requires the -.BR gethostent () -call, which should return the next entry in the host data base. -When using DNS/BIND this does not make much sense, but it may -be reasonable if the host data base is a file that can be read -line by line. -On many systems, a routine of this name reads -from the file -.IR /etc/hosts . -.\" e.g., Linux, FreeBSD, UnixWare, HP-UX -It may be available only when the library was built without DNS support. -.\" e.g., FreeBSD, AIX -The glibc version will ignore ipv6 entries. -This function is not reentrant, -and glibc adds a reentrant version -.BR gethostent_r (). -.SS GNU extensions -glibc2 also has a -.BR gethostbyname2 () -that works like -.BR gethostbyname (), -but permits to specify the address family to which the address must belong. -.P -glibc2 also has reentrant versions -.BR gethostent_r (), -.BR gethostbyaddr_r (), -.BR gethostbyname_r (), -and -.BR gethostbyname2_r (). -The caller supplies a -.I hostent -structure -.I ret -which will be filled in on success, and a temporary work buffer -.I buf -of size -.IR buflen . -After the call, -.I result -will point to the result on success. -In case of an error -or if no entry is found -.I result -will be NULL. -The functions return 0 on success and a nonzero error number on failure. -In addition to the errors returned by the nonreentrant -versions of these functions, if -.I buf -is too small, the functions will return -.BR ERANGE , -and the call should be retried with a larger buffer. -The global variable -.I h_errno -is not modified, but the address of a variable in which to store error numbers -is passed in -.IR h_errnop . -.SH BUGS -.BR gethostbyname () -does not recognize components of a dotted IPv4 address string -that are expressed in hexadecimal. -.\" http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=482973 -.SH SEE ALSO -.BR getaddrinfo (3), -.\" .BR getipnodebyaddr (3), -.\" .BR getipnodebyname (3), -.BR getnameinfo (3), -.BR inet (3), -.BR inet_ntop (3), -.BR inet_pton (3), -.BR resolver (3), -.BR hosts (5), -.BR nsswitch.conf (5), -.BR hostname (7), -.BR named (8) -.\" .BR resolv+ (8) |