summaryrefslogtreecommitdiffstats
path: root/man3/gethostbyname.3
diff options
context:
space:
mode:
Diffstat (limited to 'man3/gethostbyname.3')
-rw-r--r--man3/gethostbyname.3553
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)