man-pages/man3/gethostbyname.3.html
2021-03-31 01:06:50 +01:00

777 lines
16 KiB
HTML

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<HTML><HEAD><TITLE>Man page of GETHOSTBYNAME</TITLE>
</HEAD><BODY>
<H1>GETHOSTBYNAME</H1>
Section: Linux Programmer's Manual (3)<BR>Updated: 2017-09-15<BR><A HREF="#index">Index</A>
<A HREF="/cgi-bin/man/man2html">Return to Main Contents</A><HR>
<A NAME="lbAB">&nbsp;</A>
<H2>NAME</H2>
gethostbyname, gethostbyaddr, sethostent, gethostent, endhostent,
h_errno,
herror, hstrerror,
gethostbyaddr_r,
gethostbyname2, gethostbyname2_r, gethostbyname_r,
gethostent_r - get network host entry
<A NAME="lbAC">&nbsp;</A>
<H2>SYNOPSIS</H2>
<PRE>
<B>#include &lt;<A HREF="file:///usr/include/netdb.h">netdb.h</A>&gt;</B>
<B>extern int h_errno;</B>
<B>struct hostent *gethostbyname(const char *</B><I>name</I><B>);</B>
<B>#include &lt;<A HREF="file:///usr/include/sys/socket.h">sys/socket.h</A>&gt;</B> /* for AF_INET */
<B>struct hostent *gethostbyaddr(const void *</B><I>addr</I><B>,</B>
<B> socklen_t </B><I>len</I><B>, int </B><I>type</I><B>);</B>
<B>void sethostent(int </B><I>stayopen</I><B>);</B>
<B>void endhostent(void);</B>
<B>void herror(const char *</B><I>s</I><B>);</B>
<B>const char *hstrerror(int </B><I>err</I><B>);</B>
/* System V/POSIX extension */
<B>struct hostent *gethostent(void);</B>
/* GNU extensions */
<B>struct hostent *gethostbyname2(const char *</B><I>name</I><B>, int </B><I>af</I><B>);</B>
<B>int gethostent_r(</B>
<B> struct hostent *</B><I>ret</I><B>, char *</B><I>buf</I><B>, size_t </B><I>buflen</I><B>,</B>
<B> struct hostent **</B><I>result</I><B>, int *</B><I>h_errnop</I><B>);</B>
<B>int gethostbyaddr_r(const void *</B><I>addr</I><B>, socklen_t </B><I>len</I><B>, int </B><I>type</I><B>,</B>
<B> struct hostent *</B><I>ret</I><B>, char *</B><I>buf</I><B>, size_t </B><I>buflen</I><B>,</B>
<B> struct hostent **</B><I>result</I><B>, int *</B><I>h_errnop</I><B>);</B>
<B>int gethostbyname_r(const char *</B><I>name</I><B>,</B>
<B> struct hostent *</B><I>ret</I><B>, char *</B><I>buf</I><B>, size_t </B><I>buflen</I><B>,</B>
<B> struct hostent **</B><I>result</I><B>, int *</B><I>h_errnop</I><B>);</B>
<B>int gethostbyname2_r(const char *</B><I>name</I><B>, int </B><I>af,</I>
<B> struct hostent *</B><I>ret</I><B>, char *</B><I>buf</I><B>, size_t </B><I>buflen</I><B>,</B>
<B> struct hostent **</B><I>result</I><B>, int *</B><I>h_errnop</I><B>);</B>
</PRE>
<P>
Feature Test Macro Requirements for glibc (see
<B><A HREF="/cgi-bin/man/man2html?7+feature_test_macros">feature_test_macros</A></B>(7)):
<P>
<B>gethostbyname2</B>(),
<B>gethostent_r</B>(),
<B>gethostbyaddr_r</B>(),
<B>gethostbyname_r</B>(),
<B>gethostbyname2_r</B>():
<DL COMPACT><DT id="1"><DD>
<DL COMPACT>
<DT id="2">Since glibc 2.19:<DD>
_DEFAULT_SOURCE
<DT id="3">Glibc versions up to and including 2.19:<DD>
_BSD_SOURCE || _SVID_SOURCE
</DL>
</DL>
<P>
<B>herror</B>(),
<B>hstrerror</B>():
<DL COMPACT><DT id="4"><DD>
<DL COMPACT>
<DT id="5">Since glibc 2.19:<DD>
_DEFAULT_SOURCE
<DT id="6">Glibc 2.8 to 2.19:<DD>
_BSD_SOURCE || _SVID_SOURCE
<DT id="7">Before glibc 2.8:<DD>
none
</DL>
</DL>
<P>
<B>h_errno</B>:
<DL COMPACT><DT id="8"><DD>
<DL COMPACT>
<DT id="9">Since glibc 2.19<DD>
_DEFAULT_SOURCE || _POSIX_C_SOURCE &lt; 200809L
<DT id="10">Glibc 2.12 to 2.19:<DD>
_BSD_SOURCE || _SVID_SOURCE || _POSIX_C_SOURCE &lt; 200809L
<DT id="11">Before glibc 2.12:<DD>
none
</DL>
</DL>
<A NAME="lbAD">&nbsp;</A>
<H2>DESCRIPTION</H2>
The
<B>gethostbyname*</B>(),
<B>gethostbyaddr*</B>(),
<B>herror</B>(),
and
<B>hstrerror</B>()
functions are obsolete.
Applications should use
<B><A HREF="/cgi-bin/man/man2html?3+getaddrinfo">getaddrinfo</A></B>(3),
<B><A HREF="/cgi-bin/man/man2html?3+getnameinfo">getnameinfo</A></B>(3),
and
<B><A HREF="/cgi-bin/man/man2html?3+gai_strerror">gai_strerror</A></B>(3)
instead.
<P>
The
<B>gethostbyname</B>()
function returns a structure of type
<I>hostent</I>
for the given host
<I>name</I>.
Here
<I>name</I>
is either a hostname or an IPv4 address in standard dot notation (as for
<B><A HREF="/cgi-bin/man/man2html?3+inet_addr">inet_addr</A></B>(3)).
If
<I>name</I>
is an IPv4 address, no lookup is performed and
<B>gethostbyname</B>()
simply copies
<I>name</I>
into the
<I>h_name</I>
field and its
<I>struct in_addr</I>
equivalent into the
<I>h_addr_list[0]</I>
field of the returned
<I>hostent</I>
structure.
If
<I>name</I>
doesn't end in a dot and the environment variable
<B>HOSTALIASES</B>
is set, the alias file pointed to by
<B>HOSTALIASES</B>
will first be searched for
<I>name</I>
(see
<B><A HREF="/cgi-bin/man/man2html?7+hostname">hostname</A></B>(7)
for the file format).
The current domain and its parents are searched unless <I>name</I>
ends in a dot.
<P>
The
<B>gethostbyaddr</B>()
function returns a structure of type <I>hostent</I>
for the given host address <I>addr</I> of length <I>len</I> and address type
<I>type</I>.
Valid address types are
<B>AF_INET</B>
and
<B>AF_INET6</B>.
The host address argument is a pointer to a struct of a type depending
on the address type, for example a <I>struct in_addr *</I> (probably
obtained via a call to
<B><A HREF="/cgi-bin/man/man2html?3+inet_addr">inet_addr</A></B>(3))
for address type
<B>AF_INET</B>.
<P>
The
<B>sethostent</B>()
function specifies, if <I>stayopen</I> 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
<B>endhostent</B>()
function ends the use of a TCP connection for name
server queries.
<P>
The (obsolete)
<B>herror</B>()
function prints the error message associated
with the current value of <I>h_errno</I> on <I>stderr</I>.
<P>
The (obsolete)
<B>hstrerror</B>()
function takes an error number
(typically <I>h_errno</I>) and returns the corresponding message string.
<P>
The domain name queries carried out by
<B>gethostbyname</B>()
and
<B>gethostbyaddr</B>()
rely on the Name Service Switch
(<B><A HREF="/cgi-bin/man/man2html?5+nsswitch.conf">nsswitch.conf</A></B>(5))
configured sources or a local name server
(<B><A HREF="/cgi-bin/man/man2html?8+named">named</A></B>(8)).
The default action is to query the Name Service Switch
(<B><A HREF="/cgi-bin/man/man2html?5+nsswitch.conf">nsswitch.conf</A>(5))</B>
configured sources, failing that, a local name server
(<B><A HREF="/cgi-bin/man/man2html?8+named">named</A></B>(8)).
<A NAME="lbAE">&nbsp;</A>
<H3>Historical</H3>
The
<B><A HREF="/cgi-bin/man/man2html?5+nsswitch.conf">nsswitch.conf</A></B>(5)
file is the modern way of controlling the order of host lookups.
<P>
In glibc 2.4 and earlier, the
<I>order</I>
keyword was used to control the order of host lookups as defined in
<I>/etc/host.conf</I>
(<B><A HREF="/cgi-bin/man/man2html?5+host.conf">host.conf</A></B>(5)).
<P>
<P>
The <I>hostent</I> structure is defined in <I>&lt;<A HREF="file:///usr/include/netdb.h">netdb.h</A>&gt;</I> as follows:
<P>
struct hostent {
<BR>&nbsp;&nbsp;&nbsp;&nbsp;char&nbsp;&nbsp;*h_name;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;/*&nbsp;official&nbsp;name&nbsp;of&nbsp;host&nbsp;*/
<BR>&nbsp;&nbsp;&nbsp;&nbsp;char&nbsp;**h_aliases;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;/*&nbsp;alias&nbsp;list&nbsp;*/
<BR>&nbsp;&nbsp;&nbsp;&nbsp;int&nbsp;&nbsp;&nbsp;&nbsp;h_addrtype;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;/*&nbsp;host&nbsp;address&nbsp;type&nbsp;*/
<BR>&nbsp;&nbsp;&nbsp;&nbsp;int&nbsp;&nbsp;&nbsp;&nbsp;h_length;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;/*&nbsp;length&nbsp;of&nbsp;address&nbsp;*/
<BR>&nbsp;&nbsp;&nbsp;&nbsp;char&nbsp;**h_addr_list;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;/*&nbsp;list&nbsp;of&nbsp;addresses&nbsp;*/
}
#define h_addr h_addr_list[0] /* for backward compatibility */
<P>
The members of the <I>hostent</I> structure are:
<DL COMPACT>
<DT id="12"><I>h_name</I>
<DD>
The official name of the host.
<DT id="13"><I>h_aliases</I>
<DD>
An array of alternative names for the host, terminated by a null pointer.
<DT id="14"><I>h_addrtype</I>
<DD>
The type of address; always
<B>AF_INET</B>
or
<B>AF_INET6</B>
at present.
<DT id="15"><I>h_length</I>
<DD>
The length of the address in bytes.
<DT id="16"><I>h_addr_list</I>
<DD>
An array of pointers to network addresses for the host (in network byte
order), terminated by a null pointer.
<DT id="17"><I>h_addr</I>
<DD>
The first address in <I>h_addr_list</I> for backward compatibility.
</DL>
<A NAME="lbAF">&nbsp;</A>
<H2>RETURN VALUE</H2>
The
<B>gethostbyname</B>()
and
<B>gethostbyaddr</B>()
functions return the
<I>hostent</I>
structure or a null pointer if an error occurs.
On error, the
<I>h_errno</I>
variable holds an error number.
When non-NULL, the return value may point at static data, see the notes below.
<A NAME="lbAG">&nbsp;</A>
<H2>ERRORS</H2>
The variable <I>h_errno</I> can have the following values:
<DL COMPACT>
<DT id="18"><B>HOST_NOT_FOUND</B>
<DD>
The specified host is unknown.
<DT id="19"><B>NO_DATA</B>
<DD>
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</B>
is a synonym for
<B>NO_DATA</B>.
<DT id="20"><B>NO_RECOVERY</B>
<DD>
A nonrecoverable name server error occurred.
<DT id="21"><B>TRY_AGAIN</B>
<DD>
A temporary error occurred on an authoritative name server.
Try again later.
</DL>
<A NAME="lbAH">&nbsp;</A>
<H2>FILES</H2>
<DL COMPACT>
<DT id="22"><I>/etc/host.conf</I>
<DD>
resolver configuration file
<DT id="23"><I>/etc/hosts</I>
<DD>
host database file
<DT id="24"><I>/etc/nsswitch.conf</I>
<DD>
name service switch configuration
</DL>
<A NAME="lbAI">&nbsp;</A>
<H2>ATTRIBUTES</H2>
For an explanation of the terms used in this section, see
<B><A HREF="/cgi-bin/man/man2html?7+attributes">attributes</A></B>(7).
<TABLE BORDER>
<TR VALIGN=top><TD><B>Interface</B></TD><TD><B>Attribute</B></TD><TD><B>Value</B><BR></TD></TR>
<TR VALIGN=top><TD>
<B>gethostbyname</B>()
</TD><TD>Thread safety</TD><TD>
MT-Unsafe race:hostbyname env
<BR>
locale
<BR></TD></TR>
<TR VALIGN=top><TD>
<B>gethostbyaddr</B>()
</TD><TD>Thread safety</TD><TD>
MT-Unsafe race:hostbyaddr env
<BR>
locale
<BR></TD></TR>
<TR VALIGN=top><TD>
<B>sethostent</B>(),
<BR>
<B>endhostent</B>(),
<BR>
<B>gethostent_r</B>()
</TD><TD>Thread safety</TD><TD>
MT-Unsafe race:hostent env
<BR>
locale
<BR></TD></TR>
<TR VALIGN=top><TD>
<B>herror</B>(),
<BR>
<B>hstrerror</B>()
</TD><TD>Thread safety</TD><TD>MT-Safe<BR></TD></TR>
<TR VALIGN=top><TD>
<B>gethostent</B>()
</TD><TD>Thread safety</TD><TD>
MT-Unsafe race:hostent
<BR>
race:hostentbuf env locale
<BR></TD></TR>
<TR VALIGN=top><TD>
<B>gethostbyname2</B>()
</TD><TD>Thread safety</TD><TD>
MT-Unsafe race:hostbyname2
<BR>
env locale
<BR></TD></TR>
<TR VALIGN=top><TD>
<B>gethostbyaddr_r</B>(),
<B>gethostbyname_r</B>(),
<B>gethostbyname2_r</B>()
</TD><TD>Thread safety</TD><TD>MT-Safe env locale<BR></TD></TR>
</TABLE>
<P>
In the above table,
<I>hostent</I>
in
<I>race:hostent</I>
signifies that if any of the functions
<B>sethostent</B>(),
<B>gethostent</B>(),
<B>gethostent_r</B>(),
or
<B>endhostent</B>()
are used in parallel in different threads of a program,
then data races could occur.
<A NAME="lbAJ">&nbsp;</A>
<H2>CONFORMING TO</H2>
POSIX.1-2001 specifies
<B>gethostbyname</B>(),
<B>gethostbyaddr</B>(),
<B>sethostent</B>(),
<B>endhostent</B>(),
<B>gethostent</B>(),
and
<I>h_errno</I>;
<B>gethostbyname</B>(),
<B>gethostbyaddr</B>(),
and
<I>h_errno</I>
are marked obsolescent in that standard.
POSIX.1-2008 removes the specifications of
<B>gethostbyname</B>(),
<B>gethostbyaddr</B>(),
and
<I>h_errno</I>,
recommending the use of
<B><A HREF="/cgi-bin/man/man2html?3+getaddrinfo">getaddrinfo</A></B>(3)
and
<B><A HREF="/cgi-bin/man/man2html?3+getnameinfo">getnameinfo</A></B>(3)
instead.
<A NAME="lbAK">&nbsp;</A>
<H2>NOTES</H2>
The functions
<B>gethostbyname</B>()
and
<B>gethostbyaddr</B>()
may return pointers to static data, which may be overwritten by
later calls.
Copying the
<I>struct hostent</I>
does not suffice, since it contains pointers; a deep copy is required.
<P>
In the original BSD implementation the
<I>len</I>
argument
of
<B>gethostbyname</B>()
was an
<I>int</I>.
The SUSv2 standard is buggy and declares the
<I>len</I>
argument of
<B>gethostbyaddr</B>()
to be of type
<I>size_t</I>.
(That is wrong, because it has to be
<I>int</I>,
and
<I>size_t</I>
is not.
POSIX.1-2001 makes it
<I>socklen_t</I>,
which is OK.)
See also
<B><A HREF="/cgi-bin/man/man2html?2+accept">accept</A></B>(2).
<P>
The BSD prototype for
<B>gethostbyaddr</B>()
uses
<I>const char&nbsp;*</I>
for the first argument.
<A NAME="lbAL">&nbsp;</A>
<H3>System V/POSIX extension</H3>
POSIX requires the
<B>gethostent</B>()
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
<I>/etc/hosts</I>.
It may be available only when the library was built without DNS support.
The glibc version will ignore ipv6 entries.
This function is not reentrant,
and glibc adds a reentrant version
<B>gethostent_r</B>().
<A NAME="lbAM">&nbsp;</A>
<H3>GNU extensions</H3>
Glibc2 also has a
<B>gethostbyname2</B>()
that works like
<B>gethostbyname</B>(),
but permits to specify the address family to which the address must belong.
<P>
Glibc2 also has reentrant versions
<B>gethostent_r</B>(),
<B>gethostbyaddr_r</B>(),
<B>gethostbyname_r</B>()
and
<B>gethostbyname2_r</B>().
The caller supplies a
<I>hostent</I>
structure
<I>ret</I>
which will be filled in on success, and a temporary work buffer
<I>buf</I>
of size
<I>buflen</I>.
After the call,
<I>result</I>
will point to the result on success.
In case of an error
or if no entry is found
<I>result</I>
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</I>
is too small, the functions will return
<B>ERANGE</B>,
and the call should be retried with a larger buffer.
The global variable
<I>h_errno</I>
is not modified, but the address of a variable in which to store error numbers
is passed in
<I>h_errnop</I>.
<A NAME="lbAN">&nbsp;</A>
<H2>BUGS</H2>
<B>gethostbyname</B>()
does not recognize components of a dotted IPv4 address string
that are expressed in hexadecimal.
<A NAME="lbAO">&nbsp;</A>
<H2>SEE ALSO</H2>
<B><A HREF="/cgi-bin/man/man2html?3+getaddrinfo">getaddrinfo</A></B>(3),
<B><A HREF="/cgi-bin/man/man2html?3+getnameinfo">getnameinfo</A></B>(3),
<B><A HREF="/cgi-bin/man/man2html?3+inet">inet</A></B>(3),
<B><A HREF="/cgi-bin/man/man2html?3+inet_ntop">inet_ntop</A></B>(3),
<B><A HREF="/cgi-bin/man/man2html?3+inet_pton">inet_pton</A></B>(3),
<B><A HREF="/cgi-bin/man/man2html?3+resolver">resolver</A></B>(3),
<B><A HREF="/cgi-bin/man/man2html?5+hosts">hosts</A></B>(5),
<B><A HREF="/cgi-bin/man/man2html?5+nsswitch.conf">nsswitch.conf</A></B>(5),
<B><A HREF="/cgi-bin/man/man2html?7+hostname">hostname</A></B>(7),
<B><A HREF="/cgi-bin/man/man2html?8+named">named</A></B>(8)
<A NAME="lbAP">&nbsp;</A>
<H2>COLOPHON</H2>
This page is part of release 5.05 of the Linux
<I>man-pages</I>
project.
A description of the project,
information about reporting bugs,
and the latest version of this page,
can be found at
<A HREF="https://www.kernel.org/doc/man-pages/.">https://www.kernel.org/doc/man-pages/.</A>
<P>
<HR>
<A NAME="index">&nbsp;</A><H2>Index</H2>
<DL>
<DT id="25"><A HREF="#lbAB">NAME</A><DD>
<DT id="26"><A HREF="#lbAC">SYNOPSIS</A><DD>
<DT id="27"><A HREF="#lbAD">DESCRIPTION</A><DD>
<DL>
<DT id="28"><A HREF="#lbAE">Historical</A><DD>
</DL>
<DT id="29"><A HREF="#lbAF">RETURN VALUE</A><DD>
<DT id="30"><A HREF="#lbAG">ERRORS</A><DD>
<DT id="31"><A HREF="#lbAH">FILES</A><DD>
<DT id="32"><A HREF="#lbAI">ATTRIBUTES</A><DD>
<DT id="33"><A HREF="#lbAJ">CONFORMING TO</A><DD>
<DT id="34"><A HREF="#lbAK">NOTES</A><DD>
<DL>
<DT id="35"><A HREF="#lbAL">System V/POSIX extension</A><DD>
<DT id="36"><A HREF="#lbAM">GNU extensions</A><DD>
</DL>
<DT id="37"><A HREF="#lbAN">BUGS</A><DD>
<DT id="38"><A HREF="#lbAO">SEE ALSO</A><DD>
<DT id="39"><A HREF="#lbAP">COLOPHON</A><DD>
</DL>
<HR>
This document was created by
<A HREF="/cgi-bin/man/man2html">man2html</A>,
using the manual pages.<BR>
Time: 00:05:44 GMT, March 31, 2021
</BODY>
</HTML>