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

NAME

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

SYNOPSIS

11       #include <netdb.h>
12
13       extern int h_errno;
14
15       struct hostent *gethostbyname(const char *name);
16       struct hostent *gethostbyaddr(const void *addr,
17                                     socklen_t len, int type);
18
19       void sethostent(int stayopen);
20       void endhostent(void);
21
22       void herror(const char *s);
23       const char *hstrerror(int err);
24
25       /* System V/POSIX extension */
26       struct hostent *gethostent(void);
27
28       /* GNU extensions */
29       struct hostent *gethostbyname2(const char *name, int af);
30
31       int gethostent_r(struct hostent *restrict ret,
32                        char *restrict buf, size_t buflen,
33                        struct hostent **restrict result,
34                        int *restrict h_errnop);
35
36       int gethostbyaddr_r(const void *restrict addr, socklen_t len, int type,
37                        struct hostent *restrict ret,
38                        char *restrict buf, size_t buflen,
39                        struct hostent **restrict result,
40                        int *restrict h_errnop);
41       int gethostbyname_r(const char *restrict name,
42                        struct hostent *restrict ret,
43                        char *restrict buf, size_t buflen,
44                        struct hostent **restrict result,
45                        int *restrict h_errnop);
46       int gethostbyname2_r(const char *restrict name, int af,
47                        struct hostent *restrict ret,
48                        char *restrict buf, size_t buflen,
49                        struct hostent **restrict result,
50                        int *restrict h_errnop);
51
52   Feature Test Macro Requirements for glibc (see feature_test_macros(7)):
53
54       gethostbyname2(), gethostent_r(), gethostbyaddr_r(), gethostbyname_r(),
55       gethostbyname2_r():
56           Since glibc 2.19:
57               _DEFAULT_SOURCE
58           Glibc up to and including 2.19:
59               _BSD_SOURCE || _SVID_SOURCE
60
61       herror(), hstrerror():
62           Since glibc 2.19:
63               _DEFAULT_SOURCE
64           Glibc 2.8 to 2.19:
65               _BSD_SOURCE || _SVID_SOURCE
66           Before glibc 2.8:
67               none
68
69       h_errno:
70           Since glibc 2.19
71               _DEFAULT_SOURCE || _POSIX_C_SOURCE < 200809L
72           Glibc 2.12 to 2.19:
73               _BSD_SOURCE || _SVID_SOURCE || _POSIX_C_SOURCE < 200809L
74           Before glibc 2.12:
75               none
76

DESCRIPTION

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

RETURN VALUE

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

ERRORS

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

FILES

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

ATTRIBUTES

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

CONFORMING TO

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

NOTES

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

BUGS

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

SEE ALSO

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

COLOPHON

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