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
41 .Nm gethostbyname2_r ,
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 af"
58 .Fn sethostent "int stayopen"
62 .Fn herror "const char *string"
64 .Fn hstrerror "int err"
66 .Fn gethostbyname_r "const char *name" "struct hostent *he" "char *buffer" "size_t buflen" "struct hostent **result" "int *h_errnop"
68 .Fn gethostbyname2_r "const char *name" "int af" "struct hostent *he" "char *buffer" "size_t buflen" "struct hostent **result" "int *h_errnop"
70 .Fn gethostbyaddr_r "const void *addr" "socklen_t len" "int af" "struct hostent *hp" "char *buf" "size_t buflen" "struct hostent **result" "int *h_errno"p
77 functions are preferred over the
91 each return a pointer to an object with the
92 following structure describing an internet host
93 referenced by name or by address, respectively.
102 .Dv NUL Ns -terminated
108 should point to an address which is
112 (i.e., not an IP address in human readable
117 argument specifies the address family
119 .Dv AF_INET , AF_INET6 ,
120 etc.) of this address.
122 The structure returned contains either the information obtained from the name
123 server, broken-out fields from a line in
125 or database entries supplied by the
128 The order of the lookups is controlled by the
131 .Xr nsswitch.conf 5 .
134 char *h_name; /* official name of host */
135 char **h_aliases; /* alias list */
136 int h_addrtype; /* host address type */
137 int h_length; /* length of address */
138 char **h_addr_list; /* list of addresses from name server */
140 #define h_addr h_addr_list[0] /* address, for backward compatibility */
143 The members of this structure are:
144 .Bl -tag -width h_addr_list
146 Official name of the host.
149 .Dv NULL Ns -terminated
150 array of alternate names for the host.
152 The type of address being returned; usually
155 The length, in bytes, of the address.
158 .Dv NULL Ns -terminated
159 array of network addresses for the host.
160 Host addresses are returned in network byte order.
164 this is for backward compatibility.
167 When using the nameserver,
171 will search for the named host in the current domain and its parents
172 unless the name ends in a dot.
173 If the name contains no dot, and if the environment variable
175 contains the name of an alias file, the alias file will first be searched
176 for an alias matching the input name.
179 for the domain search procedure and the alias file format.
183 function is an evolution of
185 which is intended to allow lookups in address families other than
193 may be used to request the use of a connected
196 Queries will by default use
203 connection to the name server will be used.
204 It will remain open after calls to
220 function writes a message to the diagnostic output consisting of the
225 and a message corresponding to the value of
230 function returns a string which is the message text corresponding to the
237 suffix provide reentrant versions of their respective counterparts.
238 The caller must supply five additional parameters: a
240 variable to be filled on success, a
247 variable that will point to the result on success or be set to
249 on failure or if the name is not found.
252 variable will be filled with the error code if any.
253 All these functions return 0 on success.
255 .Bl -tag -width /etc/nsswitch.conf -compact
257 .It Pa /etc/nsswitch.conf
258 .It Pa /etc/resolv.conf
261 Print out the hostname associated with a specific IP address:
262 .Bd -literal -offset indent
263 const char *ipstr = "127.0.0.1";
267 if (!inet_aton(ipstr, &ip))
268 errx(1, "can't parse IP address %s", ipstr);
270 if ((hp = gethostbyaddr((const void *)&ip,
271 sizeof ip, AF_INET)) == NULL)
272 errx(1, "no name associated with %s", ipstr);
274 printf("name associated with %s is %s\en", ipstr, hp->h_name);
277 Error return status from
282 is indicated by return of a
287 may then be checked to see whether this is a temporary failure
288 or an invalid or unknown host.
291 can be used to print an error message describing the failure.
296 it is printed, followed by a colon and a space.
297 The error message is printed with a trailing newline.
301 can have the following values:
302 .Bl -tag -width HOST_NOT_FOUND
303 .It Dv HOST_NOT_FOUND
304 No such host is known.
306 This is usually a temporary error
307 and means that the local server did not receive
308 a response from an authoritative server.
309 A retry at some later time may succeed.
311 Some unexpected server failure was encountered.
312 This is a non-recoverable error.
314 The requested name is valid but does not have an IP address;
315 this is not a temporary error.
316 This means that the name is known to the name server but there is no address
317 associated with this name.
318 Another type of request to the name server using this domain name
319 will result in an answer;
320 for example, a mail-forwarder may be registered for this domain.
341 functions appeared in
345 function first appeared in
350 function first appeared in
363 is built to use only the routines to lookup in
365 and not the name server.
370 reads the next line of
372 opening the file if necessary.
377 opens and/or rewinds the file
381 argument is non-zero,
382 the file will not be closed after each call to
393 These functions use a thread-specific data storage;
394 if the data is needed for future use, it should be
395 copied before any subsequent calls overwrite it.
397 Though these functions are thread-safe,
398 still it is recommended to use the
400 family of functions, instead.
403 address format is currently understood.