1 .\" Copyright (c) 1983, 1987, 1991, 1993
2 .\" The Regents of the University of California. All rights reserved.
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
7 .\" 1. Redistributions of source code must retain the above copyright
8 .\" notice, this list of conditions and the following disclaimer.
9 .\" 2. Redistributions in binary form must reproduce the above copyright
10 .\" notice, this list of conditions and the following disclaimer in the
11 .\" documentation and/or other materials provided with the distribution.
12 .\" 3. Neither the name of the University nor the names of its contributors
13 .\" may be used to endorse or promote products derived from this software
14 .\" without specific prior written permission.
16 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
17 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
19 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
20 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
21 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
22 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
23 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
24 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
25 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
28 .\" From: @(#)gethostbyname.3 8.4 (Berkeley) 5/25/95
29 .\" $FreeBSD: src/lib/libc/net/gethostbyname.3,v 1.38 2007/01/09 00:28:02 imp Exp $
38 .Nm gethostbyname2_r ,
47 .Nd get network host entry
54 .Fn gethostbyname "const char *name"
56 .Fn gethostbyname_r "const char *name" "struct hostent *he" "char *buffer" "size_t buflen" "struct hostent **result" "int *h_errnop"
58 .Fn gethostbyname2 "const char *name" "int af"
60 .Fn gethostbyname2_r "const char *name" "int af" "struct hostent *he" "char *buffer" "size_t buflen" "struct hostent **result" "int *h_errnop"
62 .Fn gethostbyaddr "const void *addr" "socklen_t len" "int type"
64 .Fn gethostbyaddr_r "const void *addr" "socklen_t len" "int af" "struct hostent *he" "char *buffer" "size_t buflen" "struct hostent **result" "int *h_errnop"
68 .Fn gethostent_r "struct hostent *he" "char *buffer" "size_t buflen" "struct hostent **result" "int *h_errnop"
70 .Fn sethostent "int stayopen"
74 .Fn herror "const char *string"
76 .Fn hstrerror "int err"
83 functions are preferred over the
97 each return a pointer to an object with the
98 following structure describing an internet host
99 referenced by name or by address, respectively.
108 .Dv NUL Ns -terminated
114 should point to an address which is
118 (i.e., not an IP address in human readable
123 argument specifies the address family
125 .Dv AF_INET , AF_INET6 ,
126 etc.) of this address.
128 The structure returned contains either the information obtained from the name
131 broken-out fields from a line in
133 or database entries supplied by the
136 The order of the lookups is controlled by the
139 .Xr nsswitch.conf 5 .
142 char *h_name; /* official name of host */
143 char **h_aliases; /* alias list */
144 int h_addrtype; /* host address type */
145 int h_length; /* length of address */
146 char **h_addr_list; /* list of addresses from name server */
148 #define h_addr h_addr_list[0] /* address, for backward compatibility */
151 The members of this structure are:
152 .Bl -tag -width ".Fa h_addr_list"
154 Official name of the host.
157 .Dv NULL Ns -terminated
158 array of alternate names for the host.
160 The type of address being returned; usually
163 The length, in bytes, of the address.
166 .Dv NULL Ns -terminated
167 array of network addresses for the host.
168 Host addresses are returned in network byte order.
172 this is for backward compatibility.
175 When using the nameserver,
179 will search for the named host in the current domain and its parents
180 unless the name ends in a dot.
181 If the name contains no dot, and if the environment variable
183 contains the name of an alias file, the alias file will first be searched
184 for an alias matching the input name.
187 for the domain search procedure and the alias file format.
191 function is an evolution of
193 which is intended to allow lookups in address families other than
201 may be used to request the use of a connected
207 this sets the option to send all queries to the name server using
209 and to retain the connection after each call to
214 Otherwise, queries are performed using
227 function writes a message to the diagnostic output consisting of the
232 and a message corresponding to the value of
237 function returns a string which is the message text corresponding to the
244 .Fn gethostbyaddr_r ,
245 .Fn gethostbyname_r ,
248 functions are reentrant versions of the above functions that take a
251 structure which is used to store state information.
252 The structure must be zero-filled before it is used
253 and should be considered opaque for the sake of portability.
254 These functions also take a pointer to another
256 structure which is used to store the results of the database lookup.
258 Error return status from
263 is indicated by return of a
268 may then be checked to see whether this is a temporary failure
269 or an invalid or unknown host.
272 can be used to print an error message describing the failure.
277 it is printed, followed by a colon and a space.
278 The error message is printed with a trailing newline.
282 .Fn gethostbyaddr_r ,
283 .Fn gethostbyname_r ,
286 functions return 0 on success or \-1 if end-of-file
287 is reached or an error occurs.
289 .Bl -tag -width ".Pa /etc/nsswitch.conf" -compact
291 .It Pa /etc/nsswitch.conf
292 .It Pa /etc/resolv.conf
295 Print out the hostname associated with a specific IP address:
296 .Bd -literal -offset indent
297 const char *ipstr = "127.0.0.1";
301 if (!inet_aton(ipstr, &ip))
302 errx(1, "can't parse IP address %s", ipstr);
304 if ((hp = gethostbyaddr((const void *)&ip,
305 sizeof ip, AF_INET)) == NULL)
306 errx(1, "no name associated with %s", ipstr);
308 printf("name associated with %s is %s\en", ipstr, hp->h_name);
313 can have the following values:
314 .Bl -tag -width ".Dv HOST_NOT_FOUND"
315 .It Dv HOST_NOT_FOUND
316 No such host is known.
318 This is usually a temporary error
319 and means that the local server did not receive
320 a response from an authoritative server.
321 A retry at some later time may succeed.
323 Some unexpected server failure was encountered.
324 This is a non-recoverable error.
326 The requested name is valid but does not have an IP address;
327 this is not a temporary error.
328 This means that the name is known to the name server but there is no address
329 associated with this name.
330 Another type of request to the name server using this domain name
331 will result in an answer;
332 for example, a mail-forwarder may be registered for this domain.
353 .Fn gethostbyaddr_r ,
355 .Fn gethostbyname_r ,
357 .Fn gethostbyname2_r ,
360 functions are not currently standardized.
372 is built to use only the routines to lookup in
374 and not the name server.
379 reads the next line of
381 opening the file if necessary.
386 opens and/or rewinds the file
390 argument is non-zero,
391 the file will not be closed after each call to
413 functions appeared in
417 function first appeared in
423 .Fn gethostbyaddr_r ,
426 .Fn gethostbyname2_r ,
427 functions appeared in
430 These functions use a thread-specific data storage;
431 if the data is needed for future use, it should be
432 copied before any subsequent calls overwrite it.
434 Though these functions are thread-safe,
435 still it is recommended to use the
437 family of functions, instead.
440 address format is currently understood.