1GETHOSTBYNAME(3)           Linux Programmer's Manual          GETHOSTBYNAME(3)
2
3
4

NAME

6       gethostbyname,   gethostbyaddr,   sethostent,  gethostent,  endhostent,
7       h_errno, herror, hstrerror, gethostbyaddr_r, gethostbyname2, gethostby‐
8       name2_r, gethostbyname_r, gethostent_r - get network host entry
9

SYNOPSIS

11       #include <netdb.h>
12       extern int h_errno;
13
14       struct hostent *gethostbyname(const char *name);
15
16       #include <sys/socket.h>       /* for AF_INET */
17       struct hostent *gethostbyaddr(const void *addr,
18                                     socklen_t len, int type);
19
20       void sethostent(int stayopen);
21
22       void endhostent(void);
23
24       void herror(const char *s);
25
26       const char *hstrerror(int err);
27
28       /* System V/POSIX extension */
29       struct hostent *gethostent(void);
30
31       /* GNU extensions */
32       struct hostent *gethostbyname2(const char *name, int af);
33
34       int gethostent_r(
35               struct hostent *ret, char *buf, size_t buflen,
36               struct hostent **result, int *h_errnop);
37
38       int gethostbyaddr_r(const void *addr, socklen_t len, int type,
39               struct hostent *ret, char *buf, size_t buflen,
40               struct hostent **result, int *h_errnop);
41
42       int gethostbyname_r(const char *name,
43               struct hostent *ret, char *buf, size_t buflen,
44               struct hostent **result, int *h_errnop);
45
46       int gethostbyname2_r(const char *name, int af,
47               struct hostent *ret, char *buf, size_t buflen,
48               struct hostent **result, int *h_errnop);
49
50   Feature Test Macro Requirements for glibc (see feature_test_macros(7)):
51
52       gethostbyname2(), gethostent_r(), gethostbyaddr_r(), gethostbyname_r(),
53       gethostbyname2_r():
54           _BSD_SOURCE || _SVID_SOURCE
55
56       herror(), hstrerror():
57           Since glibc 2.8:
58               _BSD_SOURCE || _SVID_SOURCE || _GNU_SOURCE
59           Before glibc 2.8:
60               none
61

DESCRIPTION

63       The  gethostbyname*()  and  gethostbyaddr*()  functions  are  obsolete.
64       Applications should use getaddrinfo(3) and getnameinfo(3) instead.
65
66       The  gethostbyname()  function  returns a structure of type hostent for
67       the given host name.  Here name  is  either  a  hostname,  or  an  IPv4
68       address  in  standard  dot  notation  (as for inet_addr(3)), or an IPv6
69       address in colon (and possibly dot) notation.  (See  RFC 1884  for  the
70       description of IPv6 addresses.)  If name is an IPv4 or IPv6 address, no
71       lookup is performed and gethostbyname() simply  copies  name  into  the
72       h_name  field and its struct in_addr equivalent into the h_addr_list[0]
73       field of the returned hostent structure.  If name doesn't end in a  dot
74       and the environment variable HOSTALIASES is set, the alias file pointed
75       to by HOSTALIASES will first be searched for name (see hostname(7)  for
76       the  file  format).   The  current  domain and its parents are searched
77       unless name ends in a dot.
78
79       The gethostbyaddr() function returns a structure of  type  hostent  for
80       the given host address addr of length len and address type type.  Valid
81       address types are AF_INET and AF_INET6.  The host address argument is a
82       pointer  to a struct of a type depending on the address type, for exam‐
83       ple a struct in_addr * (probably obtained via a call  to  inet_addr(3))
84       for address type AF_INET.
85
86       The  sethostent()  function  specifies, if stayopen is true (1), that a
87       connected TCP socket should be used for the  name  server  queries  and
88       that the connection should remain open during successive queries.  Oth‐
89       erwise, name server queries will use UDP datagrams.
90
91       The endhostent() function ends the use of a  TCP  connection  for  name
92       server queries.
93
94       The  (obsolete)  herror()  function prints the error message associated
95       with the current value of h_errno on stderr.
96
97       The (obsolete) hstrerror() function takes an  error  number  (typically
98       h_errno) and returns the corresponding message string.
99
100       The  domain  name  queries  carried out by gethostbyname() and gethost‐
101       byaddr() use a combination of any or all of the name server named(8), a
102       broken  out  line  from /etc/hosts, and the Network Information Service
103       (NIS or  YP),  depending  upon  the  contents  of  the  order  line  in
104       /etc/host.conf.   The  default action is to query named(8), followed by
105       /etc/hosts.
106
107       The hostent structure is defined in <netdb.h> as follows:
108
109           struct hostent {
110               char  *h_name;            /* official name of host */
111               char **h_aliases;         /* alias list */
112               int    h_addrtype;        /* host address type */
113               int    h_length;          /* length of address */
114               char **h_addr_list;       /* list of addresses */
115           }
116           #define h_addr h_addr_list[0] /* for backward compatibility */
117
118       The members of the hostent structure are:
119
120       h_name The official name of the host.
121
122       h_aliases
123              An array of alternative names for the host, terminated by a NULL
124              pointer.
125
126       h_addrtype
127              The type of address; always AF_INET or AF_INET6 at present.
128
129       h_length
130              The length of the address in bytes.
131
132       h_addr_list
133              An  array of pointers to network addresses for the host (in net‐
134              work byte order), terminated by a NULL pointer.
135
136       h_addr The first address in h_addr_list for backward compatibility.
137

RETURN VALUE

139       The gethostbyname() and gethostbyaddr() functions  return  the  hostent
140       structure  or a NULL pointer if an error occurs.  On error, the h_errno
141       variable holds an error number.  When non-NULL, the  return  value  may
142       point at static data, see the notes below.
143

ERRORS

145       The variable h_errno can have the following values:
146
147       HOST_NOT_FOUND
148              The specified host is unknown.
149
150       NO_ADDRESS or NO_DATA
151              The requested name is valid but does not have an IP address.
152
153       NO_RECOVERY
154              A nonrecoverable name server error occurred.
155
156       TRY_AGAIN
157              A temporary error occurred on an authoritative name server.  Try
158              again later.
159

FILES

161       /etc/host.conf
162              resolver configuration file
163
164       /etc/hosts
165              host database file
166
167       /etc/nsswitch.conf
168              name service switch configuration
169

CONFORMING TO

171       POSIX.1-2001 specifies gethostbyname(), gethostbyaddr(),  sethostent(),
172       endhostent(),  gethostent(),  and  h_errno;  gethostbyname(),  gethost‐
173       byaddr(),  and  h_errno  are  marked  obsolescent  in  that   standard.
174       POSIX.1-2008  removes  the  specifications of gethostbyname(), gethost‐
175       byaddr(), and h_errno, recommending the use of getaddrinfo(3) and  get‐
176       nameinfo(3) instead.
177

NOTES

179       The  functions  gethostbyname() and gethostbyaddr() may return pointers
180       to static data, which may be overwritten by later calls.   Copying  the
181       struct  hostent  does  not  suffice, since it contains pointers; a deep
182       copy is required.
183
184       In the original BSD implementation the len argument of  gethostbyname()
185       was  an int.  The SUSv2 standard is buggy and declares the len argument
186       of gethostbyaddr() to be of type size_t.  (That is  wrong,  because  it
187       has  to  be  int,  and size_t is not.  POSIX.1-2001 makes it socklen_t,
188       which is OK.)  See also accept(2).
189
190       The BSD prototype for gethostbyaddr() uses const char * for  the  first
191       argument.
192
193   System V/POSIX extension
194       POSIX requires the gethostent() call, that should return the next entry
195       in the host data base.  When using DNS/BIND this  does  not  make  much
196       sense,  but  it  may be reasonable if the host data base is a file that
197       can be read line by line.  On many systems a routine of this name reads
198       from  the  file  /etc/hosts.  It may be available only when the library
199       was built without DNS support.  The  glibc  version  will  ignore  ipv6
200       entries.   This  function  is not reentrant, and glibc adds a reentrant
201       version gethostent_r().
202
203   GNU extensions
204       Glibc2 also has a gethostbyname2() that works like gethostbyname(), but
205       permits to specify the address family to which the address must belong.
206
207       Glibc2  also  has reentrant versions gethostent_r(), gethostbyaddr_r(),
208       gethostbyname_r() and gethostbyname2_r().  The caller supplies  a  hos‐
209       tent  structure ret which will be filled in on success, and a temporary
210       work buffer buf of size buflen.  After the call, result will  point  to
211       the  result  on  success.   In case of an error or if no entry is found
212       result will be NULL.  The functions return 0 on success and  a  nonzero
213       error  number  on  failure.   In addition to the errors returned by the
214       nonreentrant versions of these functions, if  buf  is  too  small,  the
215       functions  will  return  ERANGE,  and the call should be retried with a
216       larger buffer.  The global variable h_errno is not  modified,  but  the
217       address  of  a  variable  in  which to store error numbers is passed in
218       h_errnop.
219

BUGS

221       gethostbyname() does not recognize components of a dotted IPv4  address
222       string that are expressed in hexadecimal.
223

SEE ALSO

225       getaddrinfo(3),  getnameinfo(3),  inet(3),  inet_ntop(3), inet_pton(3),
226       resolver(3), hosts(5), nsswitch.conf(5), hostname(7), named(8)
227

COLOPHON

229       This page is part of release 3.53 of the Linux  man-pages  project.   A
230       description  of  the project, and information about reporting bugs, can
231       be found at http://www.kernel.org/doc/man-pages/.
232
233
234
235                                  2010-10-04                  GETHOSTBYNAME(3)
Impressum