.\" Modified 2002-08-05, Michael Kerrisk
.\" Modified 2004-10-31, Andries Brouwer
.\"
-.TH GETHOSTBYNAME 3 2015-04-19 "" "Linux Programmer's Manual"
+.TH GETHOSTBYNAME 3 2017-09-15 "" "Linux Programmer's Manual"
.SH NAME
gethostbyname, gethostbyaddr, sethostent, gethostent, endhostent,
h_errno,
.nf
.B #include <netdb.h>
.B extern int h_errno;
-.sp
+.PP
.BI "struct hostent *gethostbyname(const char *" name );
-.sp
+
.BR "#include <sys/socket.h>" " /* for AF_INET */"
.BI "struct hostent *gethostbyaddr(const void *" addr ,
.BI " socklen_t " len ", int " type );
-.sp
+.PP
.BI "void sethostent(int " stayopen );
-.sp
+.PP
.B void endhostent(void);
-.sp
+.PP
.BI "void herror(const char *" s );
-.sp
+.PP
.BI "const char *hstrerror(int " err );
-.sp
+.PP
/* System V/POSIX extension */
-.br
.B struct hostent *gethostent(void);
-.sp
+.PP
/* GNU extensions */
-.br
.BI "struct hostent *gethostbyname2(const char *" name ", int " af );
-.sp
+.PP
.B "int gethostent_r("
.BI " struct hostent *" ret ", char *" buf ", size_t " buflen ,
.BI " struct hostent **" result ", int *" h_errnop );
-.sp
+.PP
.BI "int gethostbyaddr_r(const void *" addr ", socklen_t " len ", int " type ,
.BI " struct hostent *" ret ", char *" buf ", size_t " buflen ,
.BI " struct hostent **" result ", int *" h_errnop );
-.sp
+.PP
.BI "int gethostbyname_r(const char *" name ,
.BI " struct hostent *" ret ", char *" buf ", size_t " buflen ,
.BI " struct hostent **" result ", int *" h_errnop );
-.sp
+.PP
.BI "int gethostbyname2_r(const char *" name ", int " af,
.BI " struct hostent *" ret ", char *" buf ", size_t " buflen ,
.BI " struct hostent **" result ", int *" h_errnop );
.fi
-.sp
+.PP
.in -4n
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.in
-.sp
+.PP
.PD 0
.ad l
.BR gethostbyname2 (),
.BR gethostbyname_r (),
.BR gethostbyname2_r ():
.RS 4
+.TP 4
+Since glibc 2.19:
+_DEFAULT_SOURCE
+.TP 4
+Glibc versions up to and including 2.19:
_BSD_SOURCE || _SVID_SOURCE
.RE
-
+.PD
+.PP
+.PD 0
.BR herror (),
.BR hstrerror ():
.RS 4
.TP 4
-Since glibc 2.8:
+Since glibc 2.19:
+_DEFAULT_SOURCE
+.TP 4
+Glibc 2.8 to 2.19:
_BSD_SOURCE || _SVID_SOURCE
.TP
Before glibc 2.8:
none
.RE
-
+.PD
+.PP
+.PD 0
.BR h_errno :
.RS 4
.TP 4
-Since glibc 2.12:
-_BSD_SOURCE || _SVID_SOURCE ||
- (_POSIX_C_SOURCE < 200809L && _XOPEN_SOURCE < 700)
+Since glibc 2.19
+_DEFAULT_SOURCE || _POSIX_C_SOURCE < 200809L
+.TP 4
+Glibc 2.12 to 2.19:
+_BSD_SOURCE || _SVID_SOURCE || _POSIX_C_SOURCE < 200809L
.TP
Before glibc 2.12:
none
and
.BR gai_strerror (3)
instead.
-
+.PP
The
.BR gethostbyname ()
function returns a structure of type
.IR name .
Here
.I name
-is either a hostname, or an IPv4 address in standard dot notation (as for
-.BR inet_addr (3)),
-or an IPv6 address in colon (and possibly dot) notation.
-(See RFC\ 1884 for the description of IPv6 addresses.)
+is either a hostname or an IPv4 address in standard dot notation (as for
+.BR inet_addr (3)).
If
.I name
-is an IPv4 or IPv6 address, no lookup is performed and
+is an IPv4 address, no lookup is performed and
.BR gethostbyname ()
simply copies
.I name
.BR gethostbyname ()
and
.BR gethostbyaddr ()
-use a combination of any or all of the Name Service Switch
+rely on the Name Service Switch
.RB ( nsswitch.conf (5))
-configured sources, name servers in \fI/etc/resolv.conf\fP
-.RB ( resolv.conf (5)),
-a local name server
-.RB ( named (8)),
-a broken-out line from
-.IR /etc/hosts
-.RB ( hosts (5)),
-and the Network
-Information Service (NIS or YP), depending on the contents of the
-\fIorder\fP line in
-.IR /etc/host.conf .
+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, followed by a local name server
+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
+.IR /etc/host.conf
+.RB ( host.conf (5)).
+.PP
.PP
The \fIhostent\fP structure is defined in \fI<netdb.h>\fP as follows:
-.sp
+.PP
.in +4n
-.nf
-.ne 7
+.EX
struct hostent {
char *h_name; /* official name of host */
char **h_aliases; /* alias list */
char **h_addr_list; /* list of addresses */
}
#define h_addr h_addr_list[0] /* for backward compatibility */
-.fi
+.EE
.in
.PP
The members of the \fIhostent\fP structure are:
.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 (3),
-.BR gethostent (3),
-.BR gethostent_r (3),
+.BR sethostent (),
+.BR gethostent (),
+.BR gethostent_r (),
or
-.BR endhostent (3)
+.BR endhostent ()
are used in parallel in different threads of a program,
then data races could occur.
.SH CONFORMING TO
Copying the
.I struct hostent
does not suffice, since it contains pointers; a deep copy is required.
-.LP
+.PP
In the original BSD implementation the
.I len
argument
which is OK.)
See also
.BR accept (2).
-.LP
+.PP
The BSD prototype for
.BR gethostbyaddr ()
uses
.SS System V/POSIX extension
POSIX requires the
.BR gethostent ()
-call, that should return the next entry in the host data base.
+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
+On many systems, a routine of this name reads
from the file
.IR /etc/hosts .
.\" e.g., Linux, FreeBSD, UnixWare, HP-UX
that works like
.BR gethostbyname (),
but permits to specify the address family to which the address must belong.
-.LP
+.PP
Glibc2 also has reentrant versions
.BR gethostent_r (),
.BR gethostbyaddr_r (),