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