Print this page
4023 - Typo in file(1) manpage and various others
Split |
Close |
Expand all |
Collapse all |
--- old/usr/src/man/man3socket/getipnodebyname.3socket
+++ new/usr/src/man/man3socket/getipnodebyname.3socket
1 1 '\" te
2 2 .\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved.
3 3 .\" 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.
4 4 .\" 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.
5 5 .\" 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]
6 -.TH GETIPNODEBYNAME 3SOCKET "Aug 22, 2007"
6 +.TH GETIPNODEBYNAME 3SOCKET "Sep 10, 2013"
7 7 .SH NAME
8 8 getipnodebyname, getipnodebyaddr, freehostent \- get IP node entry
9 9 .SH SYNOPSIS
10 10 .LP
11 11 .nf
12 12 \fBcc\fR [ \fIflag\fR... ] \fIfile\fR... \fB-lsocket\fR \fB -lnsl \fR [ \fIlibrary\fR... ]
13 13 #include <sys/socket.h>
14 14 #include <netdb.h>
15 15
16 16 \fBstruct hostent *\fR\fBgetipnodebyname\fR(\fBconst char *\fR\fIname\fR, \fBint\fR \fIaf\fR,
17 17 \fBint\fR \fIflags\fR, \fBint *\fR\fIerror_num\fR);
18 18 .fi
19 19
20 20 .LP
21 21 .nf
22 22 \fBstruct hostent *\fR\fBgetipnodebyaddr\fR(\fBconst void *\fR\fIsrc\fR, \fBsize_t\fR \fIlen\fR,
23 23 \fBint\fR \fIaf\fR, \fBint *\fR\fIerror_num\fR);
24 24 .fi
25 25
26 26 .LP
27 27 .nf
28 28 \fBvoid\fR \fBfreehostent\fR(\fBstruct hostent *\fR\fIptr\fR);
29 29 .fi
30 30
31 31 .SH PARAMETERS
32 32 .sp
33 33 .ne 2
34 34 .na
35 35 \fB\fIaf\fR\fR
36 36 .ad
37 37 .RS 13n
38 38 Address family
39 39 .RE
40 40
41 41 .sp
42 42 .ne 2
43 43 .na
44 44 \fB\fIflags\fR\fR
45 45 .ad
46 46 .RS 13n
47 47 Various flags
48 48 .RE
49 49
50 50 .sp
51 51 .ne 2
52 52 .na
53 53 \fB\fIname\fR\fR
54 54 .ad
55 55 .RS 13n
56 56 Name of host
57 57 .RE
58 58
59 59 .sp
60 60 .ne 2
61 61 .na
62 62 \fB\fIerror_num\fR\fR
63 63 .ad
64 64 .RS 13n
65 65 Error storage
66 66 .RE
67 67
68 68 .sp
69 69 .ne 2
70 70 .na
71 71 \fB\fIsrc\fR\fR
72 72 .ad
73 73 .RS 13n
74 74 Address for lookup
75 75 .RE
76 76
77 77 .sp
78 78 .ne 2
79 79 .na
80 80 \fB\fIlen\fR\fR
81 81 .ad
82 82 .RS 13n
83 83 Length of address
84 84 .RE
85 85
86 86 .sp
87 87 .ne 2
88 88 .na
89 89 \fB\fIptr\fR\fR
90 90 .ad
91 91 .RS 13n
92 92 Pointer to \fBhostent\fR structure
93 93 .RE
94 94
95 95 .SH DESCRIPTION
96 96 .sp
97 97 .LP
98 98 The \fBgetipnodebyname()\fR function searches the \fBipnodes\fR database from
99 99 the beginning. The function finds the first \fBh_name\fR member that matches
100 100 the hostname specified by \fIname\fR. The function takes an \fIaf\fR argument
101 101 that specifies the address family. The address family can be \fBAF_INET\fR for
102 102 IPv4 addresses or \fBAF_INET6\fR for IPv6 addresses. The \fIflags\fR argument
103 103 determines what results are returned based on the value of \fIflags\fR. If the
104 104 \fIflags\fR argument is set to \fB0\fR (zero), the default operation of the
105 105 function is specified as follows:
106 106 .RS +4
107 107 .TP
108 108 .ie t \(bu
109 109 .el o
110 110 If the \fIaf\fR argument is \fBAF_INET\fR, a query is made for an IPv4 address.
111 111 If successful, IPv4 addresses are returned and the \fBh_length\fR member of the
112 112 \fBhostent\fR structure is 4. Otherwise, the function returns a \fINULL\fR
113 113 pointer.
114 114 .RE
115 115 .RS +4
116 116 .TP
117 117 .ie t \(bu
118 118 .el o
119 119 If the \fIaf\fR argument is \fBAF_INET6\fR, a query is made for an IPv6
120 120 address. If successful, IPv6 addresses are returned and the \fBh_length\fR
121 121 member of the \fBhostent\fR structure is 16. Otherwise, the function returns a
122 122 \fINULL\fR pointer.
123 123 .RE
124 124 .sp
125 125 .LP
126 126 The \fIflags\fR argument changes the default actions of the function. Set the
127 127 \fIflags\fR argument with a logical \fBOR\fR operation on any of combination of
128 128 the following values:
129 129 .RS +4
130 130 .TP
131 131 .ie t \(bu
132 132 .el o
133 133 \fBAI_V4MAPPED\fR
134 134 .RE
135 135 .RS +4
136 136 .TP
137 137 .ie t \(bu
138 138 .el o
139 139 \fBAI_ALL\fR
140 140 .RE
141 141 .RS +4
142 142 .TP
143 143 .ie t \(bu
144 144 .el o
145 145 \fBAI_ADDRCONFIG\fR
146 146 .RE
147 147 .sp
148 148 .LP
149 149 The special flags value, \fBAI_DEFAULT\fR, should handle most applications.
150 150 Porting simple applications to use IPv6 replaces the call
151 151 .sp
152 152 .in +2
153 153 .nf
154 154 hptr = gethostbyname(name);
155 155 .fi
156 156 .in -2
157 157
158 158 .sp
159 159 .LP
160 160 with
161 161 .sp
162 162 .in +2
163 163 .nf
164 164 hptr = getipnodebyname(name, AF_INET6, AI_DEFAULT, &error_num);
165 165 .fi
166 166 .in -2
167 167
168 168 .sp
169 169 .LP
170 170 The \fIflags\fR value \fB0\fR (zero) implies a strict interpretation of the
171 171 \fIaf\fR argument:
172 172 .RS +4
173 173 .TP
174 174 .ie t \(bu
175 175 .el o
176 176 If \fIflags\fR is \fB0\fR and \fIaf\fR is \fBAF_INET\fR, the caller wants only
177 177 IPv4 addresses. A query is made for \fBA\fR records. If successful, IPv4
178 178 addresses are returned and the \fBh_length\fR member of the \fBhostent\fR
179 179 structure is 4. Otherwise, the function returns a \fINULL\fR pointer.
180 180 .RE
181 181 .RS +4
182 182 .TP
183 183 .ie t \(bu
184 184 .el o
185 185 If \fIflags\fR is \fB0\fR and \fIaf\fR is \fBAF_INET6\fR, the caller wants only
186 186 IPv6 addresses. A query is made for \fBAAAA\fR records. If successful, IPv6
187 187 addresses are returned and the \fBh_length\fR member of the \fBhostent\fR
188 188 structure is 16. Otherwise, the function returns a \fINULL\fR pointer.
189 189 .RE
190 190 .sp
191 191 .LP
192 192 Logically \fBOR\fR other constants into the \fIflags\fR argument to modify the
193 193 behavior of the \fBgetipnodebyname()\fR function.
194 194 .RS +4
195 195 .TP
196 196 .ie t \(bu
197 197 .el o
198 198 If the \fBAI_V4MAPPED\fR flag is specified with \fIaf\fR set to \fBAF_INET6\fR,
199 199 the caller can accept IPv4-mapped IPv6 addresses. If no \fBAAAA\fR records are
200 200 found, a query is made for \fBA\fR records. Any \fBA\fR records found are
201 201 returned as IPv4-mapped IPv6 addresses and the \fBh_length\fR is 16. The
202 202 \fBAI_V4MAPPED\fR flag is ignored unless \fIaf\fR equals \fBAF_INET6\fR.
203 203 .RE
204 204 .RS +4
205 205 .TP
206 206 .ie t \(bu
207 207 .el o
208 208 The \fBAI_ALL\fR flag is used in conjunction with the \fBAI_V4MAPPED\fR flag,
209 209 exclusively with the IPv6 address family. When \fBAI_ALL\fR is logically
210 210 \fBOR\fRed with \fBAI_V4MAPPED\fR flag, the caller wants all addresses: IPv6
211 211 and IPv4-mapped IPv6 addresses. A query is first made for \fBAAAA\fR records
212 212 and, if successful, IPv6 addresses are returned. Another query is then made for
213 213 \fBA\fR records. Any \fBA\fR records found are returned as IPv4-mapped IPv6
214 214 addresses and the \fBh_length\fR is 16. Only when both queries fail does the
215 215 function return a \fINULL\fR pointer. The \fBAI_ALL\fR flag is ignored unless
216 216 \fIaf\fR is set to \fBAF_INET6\fR.
217 217 .RE
218 218 .RS +4
219 219 .TP
220 220 .ie t \(bu
221 221 .el o
222 222 The \fBAI_ADDRCONFIG\fR flag specifies that a query for \fBAAAA\fR records
223 223 should occur only when the node is configured with at least one IPv6 source
224 224 address. A query for \fBA\fR records should occur only when the node is
225 225 configured with at least one IPv4 source address. For example, if a node is
226 226 configured with no IPv6 source addresses, \fIaf\fR equals \fBAF_INET6\fR, and
227 227 the node name queried has both \fBAAAA\fR and \fBA\fR records, then:
228 228 .RS +4
229 229 .TP
230 230 .ie t \(bu
231 231 .el o
232 232 A \fINULL\fR pointer is returned when only the \fBAI_ADDRCONFIG\fR value is
233 233 specified.
234 234 .RE
235 235 .RS +4
236 236 .TP
237 237 .ie t \(bu
238 238 .el o
239 239 The \fBA\fR records are returned as IPv4-mapped IPv6 addresses when the
240 240 \fBAI_ADDRCONFIG\fR and \fBAI_V4MAPPED\fR values are specified.
241 241 .RE
242 242 .RE
243 243 .sp
244 244 .LP
245 245 The special flags value, \fBAI_DEFAULT\fR, is defined as
246 246 .sp
247 247 .in +2
248 248 .nf
249 249 #define AI_DEFAULT (AI_V4MAPPED | AI_ADDRCONFIG)
250 250 .fi
251 251 .in -2
252 252
253 253 .sp
254 254 .LP
255 255 The \fBgetipnodebyname()\fR function allows the \fIname\fR argument to be a
256 256 node name or a literal address string: a dotted-decimal IPv4 address or an IPv6
257 257 hex address. Applications do not have to call \fBinet_pton\fR(3SOCKET) to
258 258 handle literal address strings.
259 259 .sp
260 260 .LP
261 261 Four scenarios arise based on the type of literal address string and the value
262 262 of the \fIaf\fR argument. The two simple cases occur when \fIname\fR is a
263 263 dotted-decimal IPv4 address and \fIaf\fR equals \fBAF_INET\fR and when
264 264 \fIname\fR is an IPv6 hex address and \fIaf\fR equals \fBAF_INET6\fR. The
265 265 members of the returned \fBhostent\fR structure are:
266 266 .sp
267 267 .ne 2
268 268 .na
269 269 \fB\fBh_name\fR\fR
270 270 .ad
271 271 .RS 15n
272 272 Pointer to a copy of the name argument
273 273 .RE
274 274
275 275 .sp
276 276 .ne 2
277 277 .na
278 278 \fB\fBh_aliases\fR\fR
279 279 .ad
280 280 .RS 15n
281 281 \fINULL\fR pointer.
282 282 .RE
283 283
284 284 .sp
285 285 .ne 2
286 286 .na
287 287 \fB\fBh_addrtype\fR\fR
288 288 .ad
289 289 .RS 15n
290 290 Copy of the \fIaf\fR argument.
291 291 .RE
292 292
293 293 .sp
294 294 .ne 2
295 295 .na
296 296 \fB\fBh_length\fR\fR
297 297 .ad
298 298 .RS 15n
299 299 4 for \fBAF_INET\fR or 16 for \fBAF_INET6\fR.
300 300 .RE
301 301
302 302 .sp
303 303 .ne 2
304 304 .na
305 305 \fB\fBh_addr_list\fR\fR
306 306 .ad
307 307 .RS 15n
308 308 Array of pointers to 4-byte or 16-byte binary addresses. The array is
309 309 terminated by a \fINULL\fR pointer.
310 310 .RE
311 311
312 312 .SH RETURN VALUES
313 313 .sp
314 314 .LP
315 315 Upon successful completion, \fBgetipnodebyname()\fR and \fBgetipnodebyaddr()\fR
316 316 return a \fBhostent\fR structure. Otherwise they return \fINULL\fR.
317 317 .sp
318 318 .LP
319 319 The \fBhostent\fR structure does not change from the existing definition when
320 320 used with \fBgethostbyname\fR(3NSL). For example, host entries are represented
321 321 by the \fBstruct hostent\fR structure defined in <\fBnetdb.h\fR>:
322 322 .sp
323 323 .in +2
324 324 .nf
325 325 struct hostent {
326 326 char *h_name; /* canonical name of host */
327 327 char **h_aliases; /* alias list */
328 328 int h_addrtype; /* host address type */
329 329 int h_length; /* length of address */
330 330 char **h_addr_list; /* list of addresses */
331 331 };
332 332 .fi
333 333 .in -2
334 334
335 335 .sp
336 336 .LP
337 337 An error occurs when \fIname\fR is an IPv6 hex address and \fIaf\fR equals
338 338 \fBAF_INET\fR. The return value of the function is a \fINULL\fR pointer and
339 339 \fBerror_num\fR equals \fBHOST_NOT_FOUND\fR.
340 340 .sp
341 341 .LP
342 342 The \fBgetipnodebyaddr()\fR function has the same arguments as the existing
343 343 \fBgethostbyaddr\fR(3NSL) function, but adds an error number. As with
344 344 \fBgetipnodebyname()\fR, \fBgetipnodebyaddr()\fR is thread-safe. The
345 345 \fBerror_num\fR value is returned to the caller with the appropriate error code
346 346 to support thread-safe error code returns. The following error conditions can
347 347 be returned for \fBerror_num\fR:
348 348 .sp
349 349 .ne 2
350 350 .na
351 351 \fB\fBHOST_NOT_FOUND\fR\fR
352 352 .ad
353 353 .RS 18n
354 354 Host is unknown.
355 355 .RE
356 356
357 357 .sp
358 358 .ne 2
359 359 .na
360 360 \fB\fBNO_DATA\fR\fR
361 361 .ad
362 362 .RS 18n
363 363 No address is available for the \fIname\fR specified in the server request.
364 364 This error is not a soft error. Another type of \fIname\fR server request might
365 365 be successful.
366 366 .RE
367 367
368 368 .sp
369 369 .ne 2
370 370 .na
371 371 \fB\fBNO_RECOVERY\fR\fR
372 372 .ad
373 373 .RS 18n
374 374 An unexpected server failure occurred, which is a non-recoverable error.
375 375 .RE
376 376
377 377 .sp
378 378 .ne 2
379 379 .na
380 380 \fB\fBTRY_AGAIN\fR\fR
381 381 .ad
382 382 .RS 18n
383 383 This error is a soft error that indicates that the local server did not receive
384 384 a response from an authoritative server. A retry at some later time might be
385 385 successful.
386 386 .RE
387 387
388 388 .sp
389 389 .LP
390 390 One possible source of confusion is the handling of IPv4-mapped IPv6 addresses
391 391 and IPv4-compatible IPv6 addresses, but the following logic should apply:
392 392 .RS +4
393 393 .TP
394 394 1.
395 395 If \fIaf\fR is \fBAF_INET6\fR, and if \fIlen\fR equals 16, and if the IPv6
396 396 address is an IPv4-mapped IPv6 address or an IPv4-compatible IPv6 address, then
397 397 skip over the first 12 bytes of the IPv6 address, set \fIaf\fR to
398 398 \fBAF_INET\fR, and set \fIlen\fR to 4.
399 399 .RE
400 400 .RS +4
401 401 .TP
402 402 2.
403 403 If \fIaf\fR is \fBAF_INET\fR, lookup the \fIname\fR for the given IPv4
404 404 address.
405 405 .RE
406 406 .RS +4
407 407 .TP
408 408 3.
409 409 If \fIaf\fR is \fBAF_INET6\fR, lookup the \fIname\fR for the given IPv6
410 410 address.
411 411 .RE
412 412 .RS +4
413 413 .TP
414 414 4.
415 415 If the function is returning success, then the single address that is
416 416 returned in the \fBhostent\fR structure is a copy of the first argument to the
417 417 function with the same address family that was passed as an argument to this
418 418 function.
419 419 .RE
420 420 .sp
421 421 .LP
422 422 All four steps listed are performed in order.
423 423 .sp
424 424 .LP
425 425 This structure, and the information pointed to by this structure, are
426 426 dynamically allocated by \fBgetipnodebyname()\fR and \fBgetipnodebyaddr()\fR.
427 427 The \fBfreehostent()\fR function frees this memory.
428 428 .SH EXAMPLES
429 429 .LP
430 430 \fBExample 1 \fRGetting the Canonical Name, Aliases, and Internet IP Addresses
431 431 for a Given Hostname
432 432 .sp
433 433 .LP
434 434 The following is a sample program that retrieves the canonical name, aliases,
435 435 and all Internet IP addresses, both version 6 and version 4, for a given
436 436 hostname.
437 437
438 438 .sp
439 439 .in +2
440 440 .nf
441 441 #include <stdio.h>
442 442 #include <string.h>
443 443 #include <sys/types.h>
444 444 #include <sys/socket.h>
445 445 #include <netinet/in.h>
446 446 #include <arpa/inet.h>
↓ open down ↓ |
430 lines elided |
↑ open up ↑ |
447 447 #include <netdb.h>
448 448
449 449 main(int argc, const char **argv)
450 450 {
451 451 char abuf[INET6_ADDRSTRLEN];
452 452 int error_num;
453 453 struct hostent *hp;
454 454 char **p;
455 455
456 456 if (argc != 2) {
457 - (void) printf("usage: %s hostname\n", argv[0]);
457 + (void) printf("usage: %s hostname\en", argv[0]);
458 458 exit (1);
459 459 }
460 460
461 461 /* argv[1] can be a pointer to a hostname or literal IP address */
462 462 hp = getipnodebyname(argv[1], AF_INET6, AI_ALL | AI_ADDRCONFIG |
463 463 AI_V4MAPPED, &error_num);
464 464 if (hp == NULL) {
465 465 if (error_num == TRY_AGAIN) {
466 466 printf("%s: unknown host or invalid literal address "
467 - "(try again later)\n", argv[1]);
467 + "(try again later)\en", argv[1]);
468 468 } else {
469 - printf("%s: unknown host or invalid literal address\n",
469 + printf("%s: unknown host or invalid literal address\en",
470 470 argv[1]);
471 471 }
472 472 exit (1);
473 473 }
474 474 for (p = hp->h_addr_list; *p != 0; p++) {
475 475 struct in6_addr in6;
476 476 char **q;
477 477
478 478 bcopy(*p, (caddr_t)&in6, hp->h_length);
479 479 (void) printf("%s\t%s", inet_ntop(AF_INET6, (void *)&in6,
480 480 abuf, sizeof(abuf)), hp->h_name);
481 481 for (q = hp->h_aliases; *q != 0; q++)
482 482 (void) printf(" %s", *q);
483 - (void) putchar('\n');
483 + (void) putchar('\en');
484 484 }
485 485 freehostent(hp);
486 486 exit (0);
487 487 }
488 488 .fi
489 489 .in -2
490 490
491 491 .SH ATTRIBUTES
492 492 .sp
493 493 .LP
494 494 See \fBattributes\fR(5) for descriptions of the following attributes:
495 495 .sp
496 496
497 497 .sp
498 498 .TS
499 499 box;
500 500 c | c
501 501 l | l .
502 502 ATTRIBUTE TYPE ATTRIBUTE VALUE
503 503 _
504 504 Interface Stability Committed
505 505 _
506 506 MT-Level Safe
507 507 .TE
508 508
509 509 .SH SEE ALSO
510 510 .sp
511 511 .LP
512 512 \fBgetaddrinfo\fR(3SOCKET), \fBgethostbyname\fR(3NSL), \fBhtonl\fR(3SOCKET),
513 513 \fBinet\fR(3SOCKET), \fBnetdb.h\fR(3HEAD), \fBhosts\fR(4),
514 514 \fBnsswitch.conf\fR(4), \fBattributes\fR(5)
515 515 .SH NOTES
516 516 .sp
517 517 .LP
518 518 No enumeration functions are provided for IPv6. Existing enumeration functions
519 519 such as \fBsethostent\fR(3NSL) do not work in combination with the
520 520 \fBgetipnodebyname()\fR and \fBgetipnodebyaddr()\fR functions.
521 521 .sp
522 522 .LP
523 523 All the functions that return a \fBstruct hostent\fR must always return the
524 524 canonical in the \fBh_name\fR field. This name, by definition, is the
525 525 well-known and official hostname shared between all aliases and all addresses.
526 526 The underlying source that satisfies the request determines the mapping of the
527 527 input name or address into the set of names and addresses in \fBhostent\fR.
528 528 Different sources might make such as determination in different ways. If more
529 529 than one alias and more than one address in \fBhostent\fR exist, no pairing is
530 530 implied between the alias and address.
531 531 .sp
532 532 .LP
533 533 The current implementations of these functions return or accept only addresses
534 534 for the Internet address family (type \fBAF_INET\fR) or the Internet address
535 535 family Version 6 (type \fBAF_INET6\fR).
536 536 .sp
537 537 .LP
538 538 IPv4-mapped addresses are not recommended. The \fBgetaddrinfo\fR(3SOCKET)
539 539 function is preferred over \fBgetipnodebyaddr()\fR because it allows
540 540 applications to lookup IPv4 and IPv6 addresses without relying on IPv4-mapped
541 541 addresses.
542 542 .sp
543 543 .LP
544 544 The form for an address of type \fBAF_INET\fR is a \fBstruct in_addr\fR defined
545 545 in <\fBnetinet/in.h\fR>. The form for an address of type \fBAF_INET6\fR is a
546 546 \fBstruct in6_addr\fR, also defined in <\fBnetinet/in.h\fR>. The functions
547 547 described in \fBinet_ntop\fR(3SOCKET) and \fBinet_pton\fR(3SOCKET) that are
548 548 illustrated in the EXAMPLES section are helpful in constructing and
549 549 manipulating addresses in either of these forms.
↓ open down ↓ |
56 lines elided |
↑ open up ↑ |
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX