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