diff options
Diffstat (limited to 'upstream/opensuse-tumbleweed/man3/gethostbyname.3')
| -rw-r--r-- | upstream/opensuse-tumbleweed/man3/gethostbyname.3 | 553 |
1 files changed, 553 insertions, 0 deletions
diff --git a/upstream/opensuse-tumbleweed/man3/gethostbyname.3 b/upstream/opensuse-tumbleweed/man3/gethostbyname.3 new file mode 100644 index 00000000..620d492c --- /dev/null +++ b/upstream/opensuse-tumbleweed/man3/gethostbyname.3 @@ -0,0 +1,553 @@ +'\" 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-07-20 "Linux man-pages 6.05.01" +.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> +.PP +.BI "void sethostent(int " stayopen ); +.B void endhostent(void); +.PP +.B [[deprecated]] extern int h_errno; +.PP +.BI "[[deprecated]] struct hostent *gethostbyname(const char *" name ); +.BI "[[deprecated]] struct hostent *gethostbyaddr(const void " addr [. len ], +.BI " socklen_t " len ", int " type ); +.PP +.BI "[[deprecated]] void herror(const char *" s ); +.BI "[[deprecated]] const char *hstrerror(int " err ); +.PP +/* System V/POSIX extension */ +.B struct hostent *gethostent(void); +.PP +/* GNU extensions */ +.B [[deprecated]] +.BI "struct hostent *gethostbyname2(const char *" name ", int " af ); +.PP +.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 ); +.PP +.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 +.PP +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.PP +.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 +.PP +.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 +.PP +.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. +.PP +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. +.PP +The +.BR endhostent () +function ends the use of a TCP connection for name +server queries. +.PP +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. +.PP +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 . +.PP +The (obsolete) +.BR herror () +function prints the error message associated +with the current value of \fIh_errno\fP on \fIstderr\fP. +.PP +The (obsolete) +.BR hstrerror () +function takes an error number +(typically \fIh_errno\fP) and returns the corresponding message string. +.PP +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. +.PP +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)). +.PP +The \fIhostent\fP structure is defined in \fI<netdb.h>\fP as follows: +.PP +.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 +.PP +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 +.sp 1 +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. +.PP +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). +.PP +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. +.PP +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) |