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           Since glibc 2.19:
55               _DEFAULT_SOURCE
56           Glibc versions up to and including 2.19:
57               _BSD_SOURCE || _SVID_SOURCE
58
59       herror(), hstrerror():
60           Since glibc 2.19:
61               _DEFAULT_SOURCE
62           Glibc 2.8 to 2.19:
63               _BSD_SOURCE || _SVID_SOURCE
64           Before glibc 2.8:
65               none
66
67       h_errno:
68           Since glibc 2.19
69               _DEFAULT_SOURCE || _POSIX_C_SOURCE < 200809L
70           Glibc 2.12 to 2.19:
71               _BSD_SOURCE || _SVID_SOURCE || _POSIX_C_SOURCE < 200809L
72           Before glibc 2.12:
73               none
74

DESCRIPTION

76       The gethostbyname*(), gethostbyaddr*(), herror(), and hstrerror() func‐
77       tions  are  obsolete.  Applications should use getaddrinfo(3), getname‐
78       info(3), and gai_strerror(3) instead.
79
80       The gethostbyname() function returns a structure of  type  hostent  for
81       the given host name.  Here name is either a hostname or an IPv4 address
82       in standard dot notation (as for inet_addr(3)).  If  name  is  an  IPv4
83       address,  no lookup is performed and gethostbyname() simply copies name
84       into the h_name field  and  its  struct  in_addr  equivalent  into  the
85       h_addr_list[0]  field  of  the  returned  hostent  structure.   If name
86       doesn't end in a dot and the environment variable HOSTALIASES  is  set,
87       the  alias  file  pointed  to by HOSTALIASES will first be searched for
88       name (see hostname(7) for the file format).  The current domain and its
89       parents are searched unless name ends in a dot.
90
91       The  gethostbyaddr()  function  returns a structure of type hostent for
92       the given host address addr of length len and address type type.  Valid
93       address types are AF_INET and AF_INET6.  The host address argument is a
94       pointer to a struct of a type depending on the address type, for  exam‐
95       ple  a  struct in_addr * (probably obtained via a call to inet_addr(3))
96       for address type AF_INET.
97
98       The sethostent() function specifies, if stayopen is true  (1),  that  a
99       connected  TCP  socket  should  be used for the name server queries and
100       that the connection should remain open during successive queries.  Oth‐
101       erwise, name server queries will use UDP datagrams.
102
103       The  endhostent()  function  ends  the use of a TCP connection for name
104       server queries.
105
106       The (obsolete) herror() function prints the  error  message  associated
107       with the current value of h_errno on stderr.
108
109       The  (obsolete)  hstrerror()  function takes an error number (typically
110       h_errno) and returns the corresponding message string.
111
112       The domain name queries carried out  by  gethostbyname()  and  gethost‐
113       byaddr()  rely on the Name Service Switch (nsswitch.conf(5)) configured
114       sources or a local name server (named(8)).  The default  action  is  to
115       query  the  Name  Service Switch (nsswitch.conf(5)) configured sources,
116       failing that, a local name server (named(8)).
117
118   Historical
119       The nsswitch.conf(5) file is the modern way of controlling the order of
120       host lookups.
121
122       In  glibc  2.4  and  earlier, the order keyword was used to control the
123       order of host lookups as defined in /etc/host.conf (host.conf(5)).
124
125       The hostent structure is defined in <netdb.h> as follows:
126
127           struct hostent {
128               char  *h_name;            /* official name of host */
129               char **h_aliases;         /* alias list */
130               int    h_addrtype;        /* host address type */
131               int    h_length;          /* length of address */
132               char **h_addr_list;       /* list of addresses */
133           }
134           #define h_addr h_addr_list[0] /* for backward compatibility */
135
136       The members of the hostent structure are:
137
138       h_name The official name of the host.
139
140       h_aliases
141              An array of alternative names for the host, terminated by a null
142              pointer.
143
144       h_addrtype
145              The type of address; always AF_INET or AF_INET6 at present.
146
147       h_length
148              The length of the address in bytes.
149
150       h_addr_list
151              An  array of pointers to network addresses for the host (in net‐
152              work byte order), terminated by a null pointer.
153
154       h_addr The first address in h_addr_list for backward compatibility.
155

RETURN VALUE

157       The gethostbyname() and gethostbyaddr() functions  return  the  hostent
158       structure  or a null pointer if an error occurs.  On error, the h_errno
159       variable holds an error number.  When non-NULL, the  return  value  may
160       point at static data, see the notes below.
161

ERRORS

163       The variable h_errno can have the following values:
164
165       HOST_NOT_FOUND
166              The specified host is unknown.
167
168       NO_DATA
169              The  requested  name  is  valid but does not have an IP address.
170              Another type of request to the name server for this  domain  may
171              return  an  answer.   The  constant  NO_ADDRESS is a synonym for
172              NO_DATA.
173
174       NO_RECOVERY
175              A nonrecoverable name server error occurred.
176
177       TRY_AGAIN
178              A temporary error occurred on an authoritative name server.  Try
179              again later.
180

FILES

182       /etc/host.conf
183              resolver configuration file
184
185       /etc/hosts
186              host database file
187
188       /etc/nsswitch.conf
189              name service switch configuration
190

ATTRIBUTES

192       For   an   explanation   of   the  terms  used  in  this  section,  see
193       attributes(7).
194
195       ┌───────────────────┬───────────────┬───────────────────────────────┐
196Interface          Attribute     Value                         
197       ├───────────────────┼───────────────┼───────────────────────────────┤
198gethostbyname()    │ Thread safety │ MT-Unsafe race:hostbyname env │
199       │                   │               │ locale                        │
200       ├───────────────────┼───────────────┼───────────────────────────────┤
201gethostbyaddr()    │ Thread safety │ MT-Unsafe race:hostbyaddr env │
202       │                   │               │ locale                        │
203       ├───────────────────┼───────────────┼───────────────────────────────┤
204sethostent(),      │ Thread safety │ MT-Unsafe race:hostent env    │
205endhostent(),      │               │ locale                        │
206gethostent_r()     │               │                               │
207       ├───────────────────┼───────────────┼───────────────────────────────┤
208herror(),          │ Thread safety │ MT-Safe                       │
209hstrerror()        │               │                               │
210       ├───────────────────┼───────────────┼───────────────────────────────┤
211gethostent()       │ Thread safety │ MT-Unsafe race:hostent        │
212       │                   │               │ race:hostentbuf env locale    │
213       ├───────────────────┼───────────────┼───────────────────────────────┤
214gethostbyname2()   │ Thread safety │ MT-Unsafe race:hostbyname2    │
215       │                   │               │ env locale                    │
216       ├───────────────────┼───────────────┼───────────────────────────────┤
217gethostbyaddr_r(), │ Thread safety │ MT-Safe env locale            │
218gethostbyname_r(), │               │                               │
219gethostbyname2_r() │               │                               │
220       └───────────────────┴───────────────┴───────────────────────────────┘
221       In the above table, hostent in race:hostent signifies that  if  any  of
222       the  functions  sethostent(),  gethostent(), gethostent_r(), or endhos‐
223       tent() are used in parallel in different threads  of  a  program,  then
224       data races could occur.
225

CONFORMING TO

227       POSIX.1-2001  specifies gethostbyname(), gethostbyaddr(), sethostent(),
228       endhostent(),  gethostent(),  and  h_errno;  gethostbyname(),  gethost‐
229       byaddr(),   and  h_errno  are  marked  obsolescent  in  that  standard.
230       POSIX.1-2008 removes the specifications  of  gethostbyname(),  gethost‐
231       byaddr(),  and h_errno, recommending the use of getaddrinfo(3) and get‐
232       nameinfo(3) instead.
233

NOTES

235       The functions gethostbyname() and gethostbyaddr() may  return  pointers
236       to  static  data, which may be overwritten by later calls.  Copying the
237       struct hostent does not suffice, since it  contains  pointers;  a  deep
238       copy is required.
239
240       In  the original BSD implementation the len argument of gethostbyname()
241       was an int.  The SUSv2 standard is buggy and declares the len  argument
242       of  gethostbyaddr()  to  be of type size_t.  (That is wrong, because it
243       has to be int, and size_t is not.   POSIX.1-2001  makes  it  socklen_t,
244       which is OK.)  See also accept(2).
245
246       The  BSD  prototype for gethostbyaddr() uses const char * for the first
247       argument.
248
249   System V/POSIX extension
250       POSIX requires the gethostent() call,  which  should  return  the  next
251       entry  in  the  host data base.  When using DNS/BIND this does not make
252       much sense, but it may be reasonable if the host data base  is  a  file
253       that can be read line by line.  On many systems, a routine of this name
254       reads from the file /etc/hosts.  It may  be  available  only  when  the
255       library  was  built without DNS support.  The glibc version will ignore
256       ipv6 entries.  This function is not reentrant, and glibc adds  a  reen‐
257       trant version gethostent_r().
258
259   GNU extensions
260       Glibc2 also has a gethostbyname2() that works like gethostbyname(), but
261       permits to specify the address family to which the address must belong.
262
263       Glibc2 also has reentrant versions  gethostent_r(),  gethostbyaddr_r(),
264       gethostbyname_r()  and  gethostbyname2_r().  The caller supplies a hos‐
265       tent structure ret which will be filled in on success, and a  temporary
266       work  buffer  buf of size buflen.  After the call, result will point to
267       the result on success.  In case of an error or if  no  entry  is  found
268       result  will  be NULL.  The functions return 0 on success and a nonzero
269       error number on failure.  In addition to the  errors  returned  by  the
270       nonreentrant  versions  of  these  functions,  if buf is too small, the
271       functions will return ERANGE, and the call should  be  retried  with  a
272       larger  buffer.   The  global variable h_errno is not modified, but the
273       address of a variable in which to store  error  numbers  is  passed  in
274       h_errnop.
275

BUGS

277       gethostbyname()  does not recognize components of a dotted IPv4 address
278       string that are expressed in hexadecimal.
279

SEE ALSO

281       getaddrinfo(3), getnameinfo(3),  inet(3),  inet_ntop(3),  inet_pton(3),
282       resolver(3), hosts(5), nsswitch.conf(5), hostname(7), named(8)
283

COLOPHON

285       This  page  is  part of release 4.15 of the Linux man-pages project.  A
286       description of the project, information about reporting bugs,  and  the
287       latest     version     of     this    page,    can    be    found    at
288       https://www.kernel.org/doc/man-pages/.
289
290
291
292                                  2017-09-15                  GETHOSTBYNAME(3)
Impressum