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 .\" 4. 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 $
30 .\" $DragonFly: src/lib/libc/net/gethostbyname.3,v 1.3 2006/11/17 23:01:21 swildner Exp $
44 .Nd get network host entry
51 .Fn gethostbyname "const char *name"
53 .Fn gethostbyname2 "const char *name" "int af"
55 .Fn gethostbyaddr "const void *addr" "socklen_t len" "int type"
59 .Fn sethostent "int stayopen"
63 .Fn herror "const char *string"
65 .Fn hstrerror "int err"
72 functions are preferred over the
86 each return a pointer to an object with the
87 following structure describing an internet host
88 referenced by name or by address, respectively.
97 .Dv NUL Ns -terminated
103 should point to an address which is
107 (i.e., not an IP address in human readable
112 argument specifies the address family
114 .Dv AF_INET , AF_INET6 ,
115 etc.) of this address.
117 The structure returned contains either the information obtained from the name
120 broken-out fields from a line in
122 or database entries supplied by the
125 The order of the lookups is controlled by the
128 .Xr nsswitch.conf 5 .
131 char *h_name; /* official name of host */
132 char **h_aliases; /* alias list */
133 int h_addrtype; /* host address type */
134 int h_length; /* length of address */
135 char **h_addr_list; /* list of addresses from name server */
137 #define h_addr h_addr_list[0] /* address, for backward compatibility */
140 The members of this structure are:
141 .Bl -tag -width h_addr_list
143 Official name of the host.
146 .Dv NULL Ns -terminated
147 array of alternate names for the host.
149 The type of address being returned; usually
152 The length, in bytes, of the address.
155 .Dv NULL Ns -terminated
156 array of network addresses for the host.
157 Host addresses are returned in network byte order.
161 this is for backward compatibility.
164 When using the nameserver,
168 will search for the named host in the current domain and its parents
169 unless the name ends in a dot.
170 If the name contains no dot, and if the environment variable
172 contains the name of an alias file, the alias file will first be searched
173 for an alias matching the input name.
176 for the domain search procedure and the alias file format.
180 function is an evolution of
182 which is intended to allow lookups in address families other than
190 may be used to request the use of a connected
196 this sets the option to send all queries to the name server using
198 and to retain the connection after each call to
203 Otherwise, queries are performed using
216 function writes a message to the diagnostic output consisting of the
221 and a message corresponding to the value of
226 function returns a string which is the message text corresponding to the
231 .Bl -tag -width /etc/nsswitch.conf -compact
233 .It Pa /etc/nsswitch.conf
234 .It Pa /etc/resolv.conf
237 Print out the hostname associated with a specific IP address:
238 .Bd -literal -offset indent
239 const char *ipstr = "127.0.0.1";
243 if (!inet_aton(ipstr, &ip))
244 errx(1, "can't parse IP address %s", ipstr);
246 if ((hp = gethostbyaddr((const void *)&ip,
247 sizeof ip, AF_INET)) == NULL)
248 errx(1, "no name associated with %s", ipstr);
250 printf("name associated with %s is %s\en", ipstr, hp->h_name);
253 Error return status from
258 is indicated by return of a
263 may then be checked to see whether this is a temporary failure
264 or an invalid or unknown host.
267 can be used to print an error message describing the failure.
272 it is printed, followed by a colon and a space.
273 The error message is printed with a trailing newline.
277 can have the following values:
278 .Bl -tag -width HOST_NOT_FOUND
279 .It Dv HOST_NOT_FOUND
280 No such host is known.
282 This is usually a temporary error
283 and means that the local server did not receive
284 a response from an authoritative server.
285 A retry at some later time may succeed.
287 Some unexpected server failure was encountered.
288 This is a non-recoverable error.
290 The requested name is valid but does not have an IP address;
291 this is not a temporary error.
292 This means that the name is known to the name server but there is no address
293 associated with this name.
294 Another type of request to the name server using this domain name
295 will result in an answer;
296 for example, a mail-forwarder may be registered for this domain.
317 is built to use only the routines to lookup in
319 and not the name server.
324 reads the next line of
326 opening the file if necessary.
331 opens and/or rewinds the file
335 argument is non-zero,
336 the file will not be closed after each call to
358 functions appeared in
362 function first appeared in
366 These functions use a thread-specific data storage;
367 if the data is needed for future use, it should be
368 copied before any subsequent calls overwrite it.
370 Though these functions are thread-safe,
371 still it is recommended to use the
373 family of functions, instead.
376 address format is currently understood.