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 $
43 .Nd get network host entry
50 .Fn gethostbyname "const char *name"
52 .Fn gethostbyname2 "const char *name" "int af"
54 .Fn gethostbyaddr "const void *addr" "socklen_t len" "int type"
58 .Fn sethostent "int stayopen"
62 .Fn herror "const char *string"
64 .Fn hstrerror "int err"
71 functions are preferred over the
85 each return a pointer to an object with the
86 following structure describing an internet host
87 referenced by name or by address, respectively.
96 .Dv NUL Ns -terminated
102 should point to an address which is
106 (i.e., not an IP address in human readable
111 argument specifies the address family
113 .Dv AF_INET , AF_INET6 ,
114 etc.) of this address.
116 The structure returned contains either the information obtained from the name
119 broken-out fields from a line in
121 or database entries supplied by the
124 The order of the lookups is controlled by the
127 .Xr nsswitch.conf 5 .
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 from name server */
136 #define h_addr h_addr_list[0] /* address, for backward compatibility */
139 The members of this structure are:
140 .Bl -tag -width ".Fa h_addr_list"
142 Official name of the host.
145 .Dv NULL Ns -terminated
146 array of alternate names for the host.
148 The type of address being returned; usually
151 The length, in bytes, of the address.
154 .Dv NULL Ns -terminated
155 array of network addresses for the host.
156 Host addresses are returned in network byte order.
160 this is for backward compatibility.
163 When using the nameserver,
167 will search for the named host in the current domain and its parents
168 unless the name ends in a dot.
169 If the name contains no dot, and if the environment variable
171 contains the name of an alias file, the alias file will first be searched
172 for an alias matching the input name.
175 for the domain search procedure and the alias file format.
179 function is an evolution of
181 which is intended to allow lookups in address families other than
189 may be used to request the use of a connected
195 this sets the option to send all queries to the name server using
197 and to retain the connection after each call to
202 Otherwise, queries are performed using
215 function writes a message to the diagnostic output consisting of the
220 and a message corresponding to the value of
225 function returns a string which is the message text corresponding to the
230 .Bl -tag -width ".Pa /etc/nsswitch.conf" -compact
232 .It Pa /etc/nsswitch.conf
233 .It Pa /etc/resolv.conf
236 Print out the hostname associated with a specific IP address:
237 .Bd -literal -offset indent
238 const char *ipstr = "127.0.0.1";
242 if (!inet_aton(ipstr, &ip))
243 errx(1, "can't parse IP address %s", ipstr);
245 if ((hp = gethostbyaddr((const void *)&ip,
246 sizeof ip, AF_INET)) == NULL)
247 errx(1, "no name associated with %s", ipstr);
249 printf("name associated with %s is %s\en", ipstr, hp->h_name);
252 Error return status from
257 is indicated by return of a
262 may then be checked to see whether this is a temporary failure
263 or an invalid or unknown host.
266 can be used to print an error message describing the failure.
271 it is printed, followed by a colon and a space.
272 The error message is printed with a trailing newline.
276 can have the following values:
277 .Bl -tag -width ".Dv HOST_NOT_FOUND"
278 .It Dv HOST_NOT_FOUND
279 No such host is known.
281 This is usually a temporary error
282 and means that the local server did not receive
283 a response from an authoritative server.
284 A retry at some later time may succeed.
286 Some unexpected server failure was encountered.
287 This is a non-recoverable error.
289 The requested name is valid but does not have an IP address;
290 this is not a temporary error.
291 This means that the name is known to the name server but there is no address
292 associated with this name.
293 Another type of request to the name server using this domain name
294 will result in an answer;
295 for example, a mail-forwarder may be registered for this domain.
316 is built to use only the routines to lookup in
318 and not the name server.
323 reads the next line of
325 opening the file if necessary.
330 opens and/or rewinds the file
334 argument is non-zero,
335 the file will not be closed after each call to
357 functions appeared in
361 function first appeared in
365 These functions use a thread-specific data storage;
366 if the data is needed for future use, it should be
367 copied before any subsequent calls overwrite it.
369 Though these functions are thread-safe,
370 still it is recommended to use the
372 family of functions, instead.
375 address format is currently understood.