summaryrefslogtreecommitdiffstats
path: root/man3/gethostbyname.3
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--man3/gethostbyname.3553
1 files changed, 553 insertions, 0 deletions
diff --git a/man3/gethostbyname.3 b/man3/gethostbyname.3
new file mode 100644
index 0000000..620d492
--- /dev/null
+++ b/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)
generated by cgit v1.2.3 (git 2.39.1) at 2024-11-12 22:11:47 +0000