1 '\" te
2 .\" Copyright (C) 2008, Sun Microsystems, Inc. All Rights Reserved.
3 .\" Copyright 1989 AT&T.
4 .\" Portions Copyright (c) 1992, X/Open Company Limited. All Rights Reserved
5 .\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at
6 .\" http://www.opengroup.org/bookstore/.
7 .\" The Institute of Electrical and Electronics Engineers and The Open Group, have given us permission to reprint portions of their documentation. In the following statement, the phrase "this text" refers to portions of the system documentation. Portions of this text are reprinted and reproduced in electronic form in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html.
8 .\" This notice shall appear on any product containing this material.
9 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
10 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
11 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
12 .TH GETHOSTBYNAME 3NSL "Sep 10, 2013"
13 .SH NAME
14 gethostbyname, gethostbyname_r, gethostbyaddr, gethostbyaddr_r, gethostent,
15 gethostent_r, sethostent, endhostent \- get network host entry
16 .SH SYNOPSIS
17 .LP
18 .nf
19 \fBcc\fR [ \fIflag\fR... ] \fIfile\fR... \fB-lnsl\fR [ \fIlibrary\fR... ]
20 #include <netdb.h>
21
22 \fBstruct hostent *\fR\fBgethostbyname\fR(\fBconst char *\fR\fIname\fR);
23 .fi
24
25 .LP
26 .nf
27 \fBstruct hostent *\fR\fBgethostbyname_r\fR(\fBconst char *\fR\fIname\fR,
28 \fBstruct hostent *\fR\fIresult\fR, \fBchar *\fR\fIbuffer\fR, \fBint\fR \fIbuflen\fR,
29 \fBint *\fR\fIh_errnop\fR);
30 .fi
31
32 .LP
33 .nf
34 \fBstruct hostent *\fR\fBgethostbyaddr\fR(\fBconst char *\fR\fIaddr\fR, \fBint\fR \fIlen\fR,
35 \fBint\fR \fItype\fR);
36 .fi
37
38 .LP
39 .nf
40 \fBstruct hostent *\fR\fBgethostbyaddr_r\fR(\fBconst char *\fR\fIaddr\fR, \fBint\fR \fIlength\fR,
41 \fBint\fR \fItype\fR, \fBstruct hostent *\fR\fIresult\fR, \fBchar *\fR\fIbuffer\fR,
42 \fBint\fR \fIbuflen\fR, \fBint *\fR\fIh_errnop\fR);
43 .fi
44
45 .LP
46 .nf
47 \fBstruct hostent *\fR\fBgethostent\fR(\fBvoid\fR);
48 .fi
49
50 .LP
51 .nf
52 \fBstruct hostent *\fR\fBgethostent_r\fR(\fBstruct hostent *\fR\fIresult\fR,
53 \fBchar *\fR\fIbuffer\fR, \fBint\fR \fIbuflen\fR, \fBint *\fR\fIh_errnop\fR);
54 .fi
55
56 .LP
57 .nf
58 \fBint\fR \fBsethostent\fR(\fBint\fR \fIstayopen\fR);
59 .fi
60
61 .LP
62 .nf
63 \fBint\fR \fBendhostent\fR(\fBvoid\fR);
64 .fi
65
66 .SH DESCRIPTION
67 .sp
68 .LP
69 These functions are used to obtain entries describing hosts. An entry can come
70 from any of the sources for \fBhosts\fR specified in the
71 \fB/etc/nsswitch.conf\fR file. See \fBnsswitch.conf\fR(4). These functions have
72 been superseded by \fBgetipnodebyname\fR(3SOCKET),
73 \fBgetipnodebyaddr\fR(3SOCKET), and \fBgetaddrinfo\fR(3SOCKET), which provide
74 greater portability to applications when multithreading is performed or
75 technologies such as IPv6 are used. For example, the functions described in the
76 following cannot be used with applications targeted to work with IPv6.
77 .sp
78 .LP
79 The \fBgethostbyname()\fR function searches for information for a host with the
80 hostname specified by the character-string parameter \fIname\fR.
81 .sp
82 .LP
83 The \fBgethostbyaddr()\fR function searches for information for a host with a
84 given host address. The parameter \fBtype\fR specifies the family of the
85 address. This should be one of the address families defined in
86 \fB<sys/socket.h>\fR\&. See the \fBNOTES\fR section for more information. Also
87 see the \fBEXAMPLES\fR section for information on how to convert an Internet
88 \fBIP\fR address notation that is separated by periods (.) into an \fIaddr\fR
89 parameter. The parameter \fIlen\fR specifies the length of the buffer indicated
90 by \fIaddr\fR.
91 .sp
92 .LP
93 All addresses are returned in network order. In order to interpret the
94 addresses, \fBbyteorder\fR(3SOCKET) must be used for byte order conversion.
95 .sp
96 .LP
97 The \fBsethostent()\fR, \fBgethostent()\fR, and \fBendhostent()\fR functions
98 are used to enumerate host entries from the database.
99 .sp
100 .LP
101 The \fBsethostent()\fR function sets or resets the enumeration to the beginning
102 of the set of host entries. This function should be called before the first
103 call to \fBgethostent()\fR. Calls to \fBgethostbyname()\fR and
104 \fBgethostbyaddr()\fR leave the enumeration position in an indeterminate state.
105 If the \fIstayopen\fR flag is non-zero, the system can keep allocated resources
106 such as open file descriptors until a subsequent call to \fBendhostent()\fR.
107 .sp
108 .LP
109 Successive calls to the \fBgethostent()\fR function return either successive
110 entries or \fINULL,\fR indicating the end of the enumeration.
111 .sp
112 .LP
113 The \fBendhostent()\fR function can be called to indicate that the caller
114 expects to do no further host entry retrieval operations; the system can then
115 deallocate resources it was using. It is still allowed, but possibly less
116 efficient, for the process to call more host retrieval functions after calling
117 \fBendhostent()\fR.
118 .SS "Reentrant Interfaces"
119 .sp
120 .LP
121 The \fBgethostbyname()\fR, \fBgethostbyaddr()\fR, and \fBgethostent()\fR
122 functions use static storage that is reused in each call, making these
123 functions unsafe for use in multithreaded applications.
124 .sp
125 .LP
126 The \fBgethostbyname_r()\fR, \fBgethostbyaddr_r()\fR, and \fBgethostent_r()\fR
127 functions provide reentrant interfaces for these operations.
128 .sp
129 .LP
130 Each reentrant interface performs the same operation as its non-reentrant
131 counterpart, named by removing the \fB_r\fR suffix. The reentrant interfaces,
132 however, use buffers supplied by the caller to store returned results and the
133 interfaces are safe for use in both single-threaded and multithreaded
134 applications.
135 .sp
136 .LP
137 Each reentrant interface takes the same parameters as its non-reentrant
138 counterpart, as well as the following additional parameters. The parameter
139 \fIresult\fR must be a pointer to a \fBstruct hostent\fR structure allocated by
140 the caller. On successful completion, the function returns the host entry in
141 this structure. The parameter \fIbuffer\fR must be a pointer to a buffer
142 supplied by the caller. This buffer is used as storage space for the host data.
143 All of the pointers within the returned \fBstruct hostent\fR \fIresult\fR point
144 to data stored within this buffer. See the \fBRETURN VALUES\fR section for more
145 information. The buffer must be large enough to hold all of the data associated
146 with the host entry. The parameter \fIbuflen\fR should give the size in bytes
147 of the buffer indicated by \fIbuffer\fR. The parameter \fIh_errnop\fR should be
148 a pointer to an integer. An integer error status value is stored there on
149 certain error conditions. See the \fBERRORS\fR section for more information.
150 .sp
151 .LP
152 For enumeration in multithreaded applications, the position within the
153 enumeration is a process-wide property shared by all threads. The
154 \fBsethostent()\fR function can be used in a multithreaded application but
155 resets the enumeration position for all threads. If multiple threads interleave
156 calls to \fBgethostent_r()\fR, the threads will enumerate disjoint subsets of
157 the host database.
158 .sp
159 .LP
160 Like their non-reentrant counterparts, \fBgethostbyname_r()\fR and
161 \fBgethostbyaddr_r()\fR leave the enumeration position in an indeterminate
162 state.
163 .SH RETURN VALUES
164 .sp
165 .LP
166 Host entries are represented by the \fBstruct hostent\fR structure defined in
167 \fB<netdb.h>\fR:
168 .sp
169 .in +2
170 .nf
171 struct hostent {
172 char *h_name; /* canonical name of host */
173 char **h_aliases; /* alias list */
174 int h_addrtype; /* host address type */
175 int h_length; /* length of address */
176 char **h_addr_list; /* list of addresses */
177 };
178 .fi
179 .in -2
180
181 .sp
182 .LP
183 See the \fBEXAMPLES\fR section for information about how to retrieve a ``.''
184 separated Internet \fBIP\fR address string from the \fIh_addr_list\fR field of
185 \fBstruct hostent\fR.
186 .sp
187 .LP
188 The \fBgethostbyname()\fR, \fBgethostbyname_r()\fR, \fBgethostbyaddr()\fR, and
189 \fBgethostbyaddr_r()\fR functions each return a pointer to a \fBstruct
190 hostent\fR if they successfully locate the requested entry; otherwise they
191 return \fINULL\fR.
192 .sp
193 .LP
194 The \fBgethostent()\fR and \fBgethostent_r()\fR functions each return a pointer
195 to a \fBstruct hostent\fR if they successfully enumerate an entry; otherwise
196 they return \fINULL\fR, indicating the end of the enumeration.
197 .sp
198 .LP
199 The \fBgethostbyname()\fR, \fBgethostbyaddr()\fR, and \fBgethostent()\fR
200 functions use static storage, so returned data must be copied before a
201 subsequent call to any of these functions if the data is to be saved.
202 .sp
203 .LP
204 When the pointer returned by the reentrant functions \fBgethostbyname_r()\fR,
205 \fBgethostbyaddr_r()\fR, and \fBgethostent_r()\fR is not \fINULL\fR, it is
206 always equal to the \fIresult\fR pointer that was supplied by the caller.
207 .sp
208 .LP
209 The \fBsethostent()\fR and \fBendhostent()\fR functions return \fB0\fR on
210 success.
211 .SH ERRORS
212 .sp
213 .LP
214 The reentrant functions \fBgethostbyname_r()\fR, \fBgethostbyaddr_r()\fR, and
215 \fBgethostent_r()\fR will return \fINULL\fR and set \fIerrno\fR to \fBERANGE\fR
216 if the length of the buffer supplied by caller is not large enough to store the
217 result. See \fBIntro\fR(2) for the proper usage and interpretation of
218 \fBerrno\fR in multithreaded applications.
219 .sp
220 .LP
221 The reentrant functions \fBgethostbyname_r()\fR and \fBgethostbyaddr_r()\fR set
222 the integer pointed to by \fIh_errnop\fR to one of these values in case of
223 error.
224 .sp
225 .LP
226 On failures, the non-reentrant functions \fBgethostbyname()\fR and
227 \fBgethostbyaddr()\fR set a global integer \fIh_errno\fR to indicate one of
228 these error codes (defined in \fB<netdb.h>\fR): \fBHOST_NOT_FOUND\fR,
229 \fBTRY_AGAIN\fR, \fBNO_RECOVERY\fR, \fBNO_DATA\fR, and \fBNO_ADDRESS\fR.
230 .sp
231 .LP
232 If a resolver is provided with a malformed address, or if any other error
233 occurs before \fBgethostbyname()\fR is resolved, then \fBgethostbyname()\fR
234 returns an internal error with a value of \(mi1.
235 .sp
236 .LP
237 The \fBgethostbyname()\fR function will set \fIh_errno\fR to
238 \fBNETDB_INTERNAL\fR when it returns a \fINULL\fR value.
239 .SH EXAMPLES
240 .LP
241 \fBExample 1 \fRUsing \fBgethostbyaddr()\fR
242 .sp
243 .LP
244 Here is a sample program that gets the canonical name, aliases, and ``.''
245 separated Internet \fBIP\fR addresses for a given ``.'' separated \fBIP\fR
246 address:
247
248 .sp
249 .in +2
250 .nf
251 #include <stdio.h>
252 #include <stdlib.h
253 #include <string.h>
254 #include <sys/types.h>
255 #include <sys/socket.h>
256 #include <netinet/in.h>
257 #include <arpa/inet.h>
258 #include <netdb.h>
259 int main(int argc, const char **argv)
260 {
261 in_addr_t addr;
262 struct hostent *hp;
263 char **p;
264 if (argc != 2) {
265 (void) printf("usage: %s IP-address\en", argv[0]);
266 exit (1);
267 }
268 if ((int)(addr = inet_addr(argv[1])) == -1) {
269 (void) printf("IP-address must be of the form a.b.c.d\en");
270 exit (2);
271 }
272 hp = gethostbyaddr((char *)&addr, 4, AF_INET);
273 if (hp == NULL) {
274 (void) printf("host information for %s not found\en", argv[1]);
275 exit (3);
276 }
277 for (p = hp->h_addr_list; *p != 0; p++) {
278 struct in_addr in;
279 char **q;
280 (void) memcpy(&in.s_addr, *p, sizeof (in.s_addr));
281 (void) printf("%s\t%s", inet_ntoa(in), hp\(mi>h_name);
282 for (q = hp->h_aliases; *q != 0; q++)
283 (void) printf(" %s", *q);
284 (void) putchar('\en');
285 }
286 exit (0);
287 }
288 .fi
289 .in -2
290
291 .sp
292 .LP
293 Note that the preceding sample program is unsafe for use in multithreaded
294 applications.
295
296 .SH FILES
297 .sp
298 .ne 2
299 .na
300 \fB\fB/etc/hosts\fR\fR
301 .ad
302 .RS 22n
303 hosts file that associates the names of hosts with their Internet Protocol (IP)
304 addresses
305 .RE
306
307 .sp
308 .ne 2
309 .na
310 \fB\fB/etc/netconfig\fR\fR
311 .ad
312 .RS 22n
313 network configuration database
314 .RE
315
316 .sp
317 .ne 2
318 .na
319 \fB\fB/etc/nsswitch.conf\fR\fR
320 .ad
321 .RS 22n
322 configuration file for the name service switch
323 .RE
324
325 .SH ATTRIBUTES
326 .sp
327 .LP
328 See \fBattributes\fR(5) for descriptions of the following attributes:
329 .sp
330
331 .sp
332 .TS
333 box;
334 c | c
335 l | l .
336 ATTRIBUTE TYPE ATTRIBUTE VALUE
337 _
338 MT-Level T{
339 See \fBReentrant Interfaces\fR in the \fBDESCRIPTION\fR section.
340 T}
341 .TE
342
343 .SH SEE ALSO
344 .sp
345 .LP
346 \fBIntro\fR(2), \fBIntro\fR(3), \fBbyteorder\fR(3SOCKET), \fBinet\fR(3SOCKET),
347 \fBnetdb.h\fR(3HEAD), \fBnetdir\fR(3NSL), \fBhosts\fR(4), \fBnetconfig\fR(4),
348 \fBnss\fR(4), \fBnsswitch.conf\fR(4), \fBattributes\fR(5)
349 .SH WARNINGS
350 .sp
351 .LP
352 The reentrant interfaces \fBgethostbyname_r()\fR, \fBgethostbyaddr_r()\fR, and
353 \fBgethostent_r()\fR are included in this release on an uncommitted basis only
354 and are subject to change or removal in future minor releases.
355 .SH NOTES
356 .sp
357 .LP
358 To ensure that they all return consistent results, \fBgethostbyname()\fR,
359 \fBgethostbyname_r()\fR, and \fBnetdir_getbyname()\fR are implemented in terms
360 of the same internal library function. This function obtains the system-wide
361 source lookup policy based on the \fBinet\fR family entries in
362 \fBnetconfig\fR(4) and the \fBhosts:\fR entry in \fBnsswitch.conf\fR(4).
363 Similarly, \fBgethostbyaddr()\fR, \fBgethostbyaddr_r()\fR, and
364 \fBnetdir_getbyaddr()\fR are implemented in terms of the same internal library
365 function. If the \fBinet\fR family entries in \fBnetconfig\fR(4) have a ``-''
366 in the last column for \fBnametoaddr\fR libraries, then the entry for
367 \fBhosts\fR in \fBnsswitch.conf\fR will be used; \fBnametoaddr\fR libraries in
368 that column will be used, and \fBnsswitch.conf\fR will not be consulted.
369 .sp
370 .LP
371 There is no analogue of \fBgethostent()\fR and \fBgethostent_r()\fR in the
372 netdir functions, so these enumeration functions go straight to the \fBhosts\fR
373 entry in \fBnsswitch.conf\fR. Thus enumeration can return results from a
374 different source than that used by \fBgethostbyname()\fR,
375 \fBgethostbyname_r()\fR, \fBgethostbyaddr()\fR, and \fBgethostbyaddr_r()\fR.
376 .sp
377 .LP
378 All the functions that return a \fBstruct hostent\fR must always return the
379 \fIcanonical name\fR in the \fIh_name\fR field. This name, by definition, is
380 the well-known and official hostname shared between all aliases and all
381 addresses. The underlying source that satisfies the request determines the
382 mapping of the input name or address into the set of names and addresses in
383 \fBhostent\fR. Different sources might do that in different ways. If there is
384 more than one alias and more than one address in \fBhostent\fR, no pairing is
385 implied between them.
386 .sp
387 .LP
388 The system attempts to put those addresses that are on the same subnet as the
389 caller before addresses that are on different subnets. However, if address
390 sorting is disabled by setting \fBSORT_ADDRS\fR to FALSE in the
391 \fB/etc/default/nss\fR file, the system does not put the local subnet addresses
392 first. See \fBnss\fR(4) for more information.
393 .sp
394 .LP
395 When compiling multithreaded applications, see \fBIntro\fR(3), \fBMULTITHREADED
396 APPLICATIONS\fR, for information about the use of the \fB_REENTRANT\fR flag.
397 .sp
398 .LP
399 Use of the enumeration interfaces \fBgethostent()\fR and \fBgethostent_r()\fR
400 is discouraged; enumeration might not be supported for all database sources.
401 The semantics of enumeration are discussed further in \fBnsswitch.conf\fR(4).
402 .sp
403 .LP
404 The current implementations of these functions only return or accept addresses
405 for the Internet address family (type \fBAF_INET\fR).
406 .sp
407 .LP
408 The form for an address of type \fBAF_INET\fR is a \fBstruct in_addr\fR defined
409 in <\fBnetinet/in.h\fR>. The functions described in \fBinet\fR(3SOCKET), and
410 illustrated in the \fBEXAMPLES\fR section, are helpful in constructing and
411 manipulating addresses in this form.
|
1 .\" Copyright 2014 Garrett D'Amore <garrett@damore.org>
2 .\" Copyright (C) 2008, Sun Microsystems, Inc. All Rights Reserved.
3 .\" Copyright 1989 AT&T.
4 .\" Portions Copyright (c) 1992, X/Open Company Limited. All Rights Reserved
5 .\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at
6 .\" http://www.opengroup.org/bookstore/.
7 .\" The Institute of Electrical and Electronics Engineers and The Open Group, have given us permission to reprint portions of their documentation. In the following statement, the phrase "this text" refers to portions of the system documentation. Portions of this text are reprinted and reproduced in electronic form in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html.
8 .\" This notice shall appear on any product containing this material.
9 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
10 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
11 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
12 .Dd Jul 22, 2014
13 .Dt GETHOSTBYNAME 3NSL
14 .Os
15 .Sh NAME
16 .Nm gethostbyname ,
17 .Nm gethostbyname_r ,
18 .Nm gethostbyaddr ,
19 .Nm gethostbyaddr_r
20 .Nd lookup network host entry
21 .Sh SYNOPSIS
22 .Ic cc
23 .Op Ar flag No Ns ...
24 .Ar file No Ns ...
25 .Fl lnsl
26 .Op Ar library No Ns ...
27 .Lp
28 .In netdb.h
29 .Ft "struct hostent *"
30 .Fn gethostbyname "const char *name"
31 .Ft "struct hostent *"
32 .Fo gethostbyname_r
33 .Fa "const char *name"
34 .Fa "struct hostent *result"
35 .Fa "char *buffer"
36 .Fa "int buflen"
37 .Fa "int *h_errnop"
38 .Fc
39 .Ft "struct hostent *"
40 .Fo gethostbyaddr
41 .Fa "const char *addr"
42 .Fa "socklen_t len"
43 .Fa "int type"
44 .Fc
45 .Ft "struct hostent *"
46 .Fo gethostbyaddr_r
47 .Fa "const char *addr"
48 .Fa "int length"
49 .Fa "int type"
50 .Fa "struct hostent *result"
51 .Fa "char *buffer"
52 .Fa "int buflen"
53 .Fa "int *h_errnop"
54 .Fc
55 .Sh DESCRIPTION
56 These functions are used to obtain entries describing hosts. An entry can come
57 from any of the sources for
58 .Sy hosts
59 specified in the
60 .Pa /etc/nsswitch.conf
61 file. See
62 .Xr nsswitch.conf 4 .
63 These functions have been superseded by
64 .Xr getipnodebyname 3SOCKET ,
65 .Xr getipnodebyaddr 3SOCKET ,
66 and
67 .Xr getaddrinfo 3SOCKET ,
68 which provide
69 greater portability to applications when multithreading is performed or
70 technologies such as IPv6 are used. For example, the functions described in the
71 following cannot be used with applications targeted to work with IPv6.
72 .Lp
73 The
74 .Fn gethostbyname
75 function searches for information for a host with the
76 hostname specified by the character-string parameter
77 .Fa name .
78 .Lp
79 The
80 .Fn gethostbyaddr
81 function searches for information for a host with a
82 given host address. The parameter
83 .Fa type
84 specifies the family of the
85 address. This should be one of the address families defined in
86 .In sys/socket.h .
87 See the
88 .Sx NOTES
89 section for more information. Also
90 see the
91 .Sx EXAMPLES
92 section for information on how to convert an Internet
93 Protocol address notation that is separated by periods (.) into an
94 .Fa addr
95 parameter. The parameter
96 .Fa len
97 specifies the length of the buffer indicated
98 by
99 .Fa addr .
100 .Lp
101 All addresses are returned in network order. In order to interpret the
102 addresses,
103 .Xr byteorder 3SOCKET
104 must be used for byte order conversion.
105 .Ss "Reentrant Interfaces"
106 The
107 .Fn gethostbyname
108 and
109 .Fn gethostbyaddr
110 functions use static storage that is reused in each call, making these
111 functions unsafe for use in multithreaded applications.
112 .Lp
113 The
114 .Fn gethostbyname_r
115 and
116 .Fn gethostbyaddr_r
117 functions provide reentrant interfaces for these operations.
118 .Lp
119 Each reentrant interface performs the same operation as its non-reentrant
120 counterpart, named by removing the
121 .Sy _r
122 suffix. The reentrant interfaces,
123 however, use buffers supplied by the caller to store returned results and the
124 interfaces are safe for use in both single-threaded and multithreaded
125 applications.
126 .Lp
127 Each reentrant interface takes the same parameters as its non-reentrant
128 counterpart, as well as the following additional parameters. The parameter
129 .Fa result
130 must be a pointer to a
131 .Vt "struct hostent"
132 structure allocated by
133 the caller. On successful completion, the function returns the host entry in
134 this structure. The parameter
135 .Fa buffer
136 must be a pointer to a buffer
137 supplied by the caller. This buffer is used as storage space for the host data.
138 All of the pointers within the returned
139 .Vt "struct hostent"
140 point to data stored within this buffer. See the
141 .Sx RETURN VALUES
142 section for more
143 information. The buffer must be large enough to hold all of the data associated
144 with the host entry. The parameter
145 .Fa buflen
146 should give the size in bytes
147 of the buffer indicated by
148 .Fa buffer .
149 The parameter
150 .Fa h_errnop
151 should be
152 a pointer to an integer. An integer error status value is stored there on
153 certain error conditions. See the
154 .Sx ERRORS
155 section for more information.
156 .Sh RETURN VALUES
157 Host entries are represented by the
158 .Vt "struct hostent"
159 structure defined in
160 .In netdb.h :
161 .Bd -literal -offset indent
162 struct hostent {
163 char *h_name; /* canonical name of host */
164 char **h_aliases; /* alias list */
165 int h_addrtype; /* host address type */
166 int h_length; /* length of address */
167 char **h_addr_list; /* list of addresses */
168 };
169 .Ed
170 .Lp
171 See the
172 .Sx EXAMPLES
173 section for information about how to retrieve a
174 .Sq \&.
175 separated Internet Protocol address string from the
176 .Fa h_addr_list
177 field of
178 .Vt "struct hostent" .
179 .Lp
180 The
181 .Fn gethostbyname ,
182 .Fn gethostbyname_r ,
183 .Fn gethostbyaddr ,
184 and
185 .Fn gethostbyaddr_r
186 functions each return a pointer to a
187 .Vt "struct hostent"
188 if they successfully locate the requested entry; otherwise they
189 return
190 .Dv NULL .
191 .Lp
192 The
193 .Fn gethostbyname
194 and
195 .Fn gethostbyaddr
196 functions use static storage, so returned data must be copied before a
197 subsequent call to any of these functions if the data is to be saved.
198 .Lp
199 When the pointer returned by the reentrant functions
200 .Fn gethostbyname_r
201 and
202 .Fn gethostbyaddr_r
203 is not
204 .Dv NULL ,
205 it is always equal to the
206 .Fa result
207 pointer that was supplied by the caller.
208 .Sh FILES
209 .Bl -tag -width Pa
210 .It Pa /etc/hosts
211 hosts file that associates the names of hosts with their Internet Protocol (IP)
212 addresses
213 .It Pa /etc/nsswitch.conf
214 configuration file for the name service switch
215 .El
216 .Sh EXAMPLES
217 .Ss Example 1 Using gethostbyaddr()
218 Here is a sample program that gets the canonical name, aliases, and ``.''
219 separated Internet Protocol addresses for a given ``.'' separated IP
220 address:
221 .Bd -literal -offset indent
222 #include <stdio.h>
223 #include <stdlib.h
224 #include <string.h>
225 #include <sys/types.h>
226 #include <sys/socket.h>
227 #include <netinet/in.h>
228 #include <arpa/inet.h>
229 #include <netdb.h>
230 int main(int argc, const char **argv)
231 {
232 in_addr_t addr;
233 struct hostent *hp;
234 char **p;
235 if (argc != 2) {
236 (void) printf("usage: %s IP-address\en", argv[0]);
237 exit (1);
238 }
239 if ((int)(addr = inet_addr(argv[1])) == -1) {
240 (void) printf("IP-address must be of form a.b.c.d\en");
241 exit (2);
242 }
243 hp = gethostbyaddr((char *)&addr, 4, AF_INET);
244 if (hp == NULL) {
245 (void) printf("host %s not found\en", argv[1]);
246 exit (3);
247 }
248 for (p = hp->h_addr_list; *p != 0; p++) {
249 struct in_addr in;
250 char **q;
251 (void) memcpy(&in.s_addr, *p, sizeof (in.s_addr));
252 (void) printf("%s\t%s", inet_ntoa(in), hp\(mi>h_name);
253 for (q = hp->h_aliases; *q != 0; q++)
254 (void) printf(" %s", *q);
255 (void) putchar('\en');
256 }
257 exit (0);
258 }
259 .Ed
260 .Lp
261 Note that the preceding sample program is unsafe for use in multithreaded
262 applications.
263 .Sh ERRORS
264 The reentrant functions
265 .Fn gethostbyname_r
266 and
267 .Fn gethostbyaddr_r
268 will return
269 .Dv NULL
270 and set
271 .Va errno
272 to
273 .Er ERANGE
274 if the length of the buffer supplied by caller is not large enough to store the
275 result. See
276 .Xr Intro 2
277 for the proper usage and interpretation of
278 .Va errno
279 in multithreaded applications.
280 .Lp
281 The reentrant functions
282 .Fn gethostbyname_r
283 and
284 .Fn gethostbyaddr_r
285 set the integer pointed to by
286 .Fa h_errnop
287 to one of these values in case of error.
288 .Lp
289 On failures, the non-reentrant functions
290 .Fn gethostbyname
291 and
292 .Fn gethostbyaddr
293 set a global integer
294 .Va h_errno
295 to indicate one of
296 these error codes
297 .Po defined in
298 .In netdb.h Pc :
299 .Dv HOST_NOT_FOUND ,
300 .Dv TRY_AGAIN ,
301 .Dv NO_RECOVERY ,
302 .Dv NO_DATA ,
303 and
304 .Dv NO_ADDRESS .
305 .Lp
306 If a resolver is provided with a malformed address, or if any other error
307 occurs before
308 .Fn gethostbyname
309 is resolved, then
310 .Fn gethostbyname
311 returns an internal error with a value of \(mi1.
312 .Lp
313 The
314 .Fn gethostbyname
315 function will set
316 .Va h_errno
317 to
318 .Dv NETDB_INTERNAL
319 when it returns a
320 .Dv NULL
321 value.
322 .Sh INTERFACE STABILITY
323 The
324 .Fn gethostbyname
325 and
326 .Fn gethostbyaddr
327 functions are
328 .Sy Obsolete Standard .
329 .Lp
330 The
331 .Fn gethostbyname_r
332 and
333 .Fn gethostbyaddr_r
334 functions are
335 .Sy Obsolete Uncommitted .
336 .Sh MT-LEVEL
337 The
338 .Fn gethostbyname
339 and
340 .Fn gethostbyaddr
341 functions are
342 .Sy Unsafe .
343 .Lp
344 The
345 .Fn gethostbyname_r
346 and
347 .Fn gethostbyaddr_r
348 functions are
349 .Sy Safe .
350 .Sh SEE ALSO
351 .Xr Intro 2 ,
352 .Xr netdb.h 3HEAD ,
353 .Xr netdir 3NSL ,
354 .Xr byteorder 3SOCKET,
355 .Xr getaddrinfo 3SOCKET
356 .Xr getnameinfo 3SOCKET
357 .Xr inet 3SOCKET ,
358 .Xr hosts 4 ,
359 .Xr nss 4 ,
360 .Xr nsswitch.conf 4 ,
361 .Xr standards 5
362 .Sh NOTES
363 The reentrant interfaces
364 .Fn gethostbyname_r
365 and
366 .Fn gethostbyaddr_r
367 are included in this release on an uncommitted basis only
368 and are subject to change or removal in future minor releases.
369 .Lp
370 To ensure that they all return consistent results,
371 .Fn gethostbyname ,
372 .Fn gethostbyname_r ,
373 and
374 .Xr netdir_getbyname 3NSL
375 are implemented in terms
376 of the same internal library function. This function obtains the system-wide
377 source lookup policy based on the
378 .Sy hosts:
379 entry in
380 .Xr nsswitch.conf 4 .
381 Similarly,
382 .Fn gethostbyaddr ,
383 .Fn gethostbyaddr_r ,
384 and
385 .Xr netdir_getbyaddr 3NSL
386 are implemented in terms of the same internal library
387 function, which also is driven by the
388 .Sy hosts:
389 entry in
390 .Xr nsswitch.conf 4 .
391 .Lp
392 These functions must always return the
393 .Em canonical name
394 in the
395 .Fa h_name
396 field. This name, by definition, is
397 the well-known and official hostname shared between all aliases and all
398 addresses. The underlying source that satisfies the request determines the
399 mapping of the input name or address into the set of names and addresses in
400 .Fa hostent .
401 Different sources might do that in different ways. If there is
402 more than one alias and more than one address in
403 .Fa hostent ,
404 no pairing is
405 implied between them.
406 .Lp
407 The system attempts to put those addresses that are on the same subnet as the
408 caller before addresses that are on different subnets. However, if address
409 sorting is disabled by setting
410 .Sy SORT_ADDRS
411 to
412 .Sy FALSE
413 in the
414 .Pa /etc/default/nss
415 file, the system does not put the local subnet addresses
416 first. See
417 .Xr nss 4
418 for more information.
419 .Lp
420 The current implementations of these functions only return or accept addresses
421 for the Internet address family
422 .Po type Dv AF_INET Pc .
423 .Lp
424 The form for an address of type
425 .Dv AF_INET
426 is a
427 .Vt "struct in_addr"
428 defined
429 .In netinet/in.h .
430 The functions described in
431 .Xr inet 3SOCKET ,
432 and illustrated in the
433 .Sx EXAMPLES
434 section, are helpful in constructing and
435 manipulating addresses in this form.
436 .Sh STANDARDS
437 The
438 .Fn gethostbyaddr
439 and
440 .Fn gethostbyname
441 functions were introduced in
442 .Bx 4.2 ,
443 and standardized in
444 .St -xns5.2
445 and
446 .St -p1003.1-2001 .
447 They were subsequently removed from
448 .St -p1003.1-2008 .
|