lib/libc/net/getipnodebyname.3

   1 .\"     $KAME: getipnodebyname.3,v 1.6 2000/08/09 21:16:17 itojun Exp $
   2 .\"
   3 .\" Copyright (c) 1983, 1987, 1991, 1993
   4 .\"     The Regents of the University of California.  All rights reserved.
   5 .\"
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that the following conditions
   8 .\" are met:
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer in the
  13 .\"    documentation and/or other materials provided with the distribution.
  14 .\" 3. All advertising materials mentioning features or use of this software
  15 .\"    must display the following acknowledgement:
  16 .\"     This product includes software developed by the University of
  17 .\"     California, Berkeley and its contributors.
  18 .\" 4. Neither the name of the University nor the names of its contributors
  19 .\"    may be used to endorse or promote products derived from this software
  20 .\"    without specific prior written permission.
  21 .\"
  22 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  23 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  24 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  25 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  26 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  27 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  28 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  29 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  30 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  31 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  32 .\" SUCH DAMAGE.
  33 .\"
  34 .\"     From: @(#)gethostbyname.3       8.4 (Berkeley) 5/25/95
  35 .\" $FreeBSD$
  36 .\"
  37 .Dd August 6, 2004
  38 .Dt GETIPNODEBYNAME 3
  39 .Os
  40 .\"
  41 .Sh NAME
  42 .Nm getipnodebyname ,
  43 .Nm getipnodebyaddr ,
  44 .Nm freehostent
  45 .Nd nodename-to-address and address-to-nodename translation
  46 .\"
  47 .Sh LIBRARY
  48 .Lb libc
  49 .Sh SYNOPSIS
  50 .In sys/types.h
  51 .In sys/socket.h
  52 .In netdb.h
  53 .Ft "struct hostent *"
  54 .Fn getipnodebyname "const char *name" "int af" "int flags" "int *error_num"
  55 .Ft "struct hostent *"
  56 .Fn getipnodebyaddr "const void *src" "size_t len" "int af" "int *error_num"
  57 .Ft void
  58 .Fn freehostent "struct hostent *ptr"
  59 .\"
  60 .Sh DESCRIPTION
  61 The
  62 .Fn getipnodebyname
  63 and
  64 .Fn getipnodebyaddr
  65 functions are very similar to
  66 .Xr gethostbyname 3 ,
  67 .Xr gethostbyname2 3
  68 and
  69 .Xr gethostbyaddr 3 .
  70 The functions cover all the functionalities provided by the older ones,
  71 and provide better interface to programmers.
  72 The functions require additional arguments,
  73 .Fa af ,
  74 and
  75 .Fa flags ,
  76 for specifying address family and operation mode.
  77 The additional arguments allow programmer to get address for a nodename,
  78 for specific address family
  79 (such as
  80 .Dv AF_INET
  81 or
  82 .Dv AF_INET6 ) .
  83 The functions also require an additional pointer argument,
  84 .Fa error_num
  85 to return the appropriate error code,
  86 to support thread safe error code returns.
  87 .Pp
  88 The type and usage of the return value,
  89 .Li "struct hostent"
  90 is described in
  91 .Xr gethostbyname 3 .
  92 .Pp
  93 For
  94 .Fn getipnodebyname ,
  95 the
  96 .Fa name
  97 argument can be either a node name or a numeric address
  98 string
  99 (i.e., a dotted-decimal IPv4 address or an IPv6 hex address).
 100 The
 101 .Fa af
 102 argument specifies the address family, either
 103 .Dv AF_INET
 104 or
 105 .Dv AF_INET6 .
 106 The
 107 .Fa flags
 108 argument specifies the types of addresses that are searched for,
 109 and the types of addresses that are returned.
 110 We note that a special flags value of
 111 .Dv AI_DEFAULT
 112 (defined below)
 113 should handle most applications.
 114 That is, porting simple applications to use IPv6 replaces the call
 115 .Bd -literal -offset
 116    hptr = gethostbyname(name);
 117 .Ed
 118 .Pp
 119 with
 120 .Bd -literal -offset
 121    hptr = getipnodebyname(name, AF_INET6, AI_DEFAULT, &error_num);
 122 .Ed
 123 .Pp
 124 Applications desiring finer control over the types of addresses
 125 searched for and returned, can specify other combinations of the
 126 .Fa flags
 127 argument.
 128 .Pp
 129 A
 130 .Fa flags
 131 of
 132 .Li 0
 133 implies a strict interpretation of the
 134 .Fa af
 135 argument:
 136 .Bl -bullet
 137 .It
 138 If
 139 .Fa flags
 140 is 0 and
 141 .Fa af
 142 is
 143 .Dv AF_INET ,
 144 then the caller wants only IPv4 addresses.
 145 A query is made for
 146 .Li A
 147 records.
 148 If successful, the IPv4 addresses are returned and the
 149 .Li h_length
 150 member of the
 151 .Li hostent
 152 structure will be 4, else the function returns a
 153 .Dv NULL
 154 pointer.
 155 .It
 156 If
 157 .Fa flags
 158 is 0 and if
 159 .Fa af
 160 is
 161 .Li AF_INET6 ,
 162 then the caller wants only IPv6 addresses.
 163 A query is made for
 164 .Li AAAA
 165 records.
 166 If successful, the IPv6 addresses are returned and the
 167 .Li h_length
 168 member of the
 169 .Li hostent
 170 structure will be 16, else the function returns a
 171 .Dv NULL
 172 pointer.
 173 .El
 174 .Pp
 175 Other constants can be logically-ORed into the
 176 .Fa flags
 177 argument, to modify the behavior of the function.
 178 .Bl -bullet
 179 .It
 180 If the
 181 .Dv AI_V4MAPPED
 182 flag is specified along with an
 183 .Fa af
 184 of
 185 .Dv AF_INET6 ,
 186 then the caller will accept IPv4-mapped IPv6 addresses.
 187 That is, if no
 188 .Li AAAA
 189 records are found then a query is made for
 190 .Li A
 191 records and any found are returned as IPv4-mapped IPv6 addresses
 192 .Li ( h_length
 193 will be 16).
 194 The
 195 .Dv AI_V4MAPPED
 196 flag is ignored unless
 197 .Fa af
 198 equals
 199 .Dv AF_INET6 .
 200 .It
 201 The
 202 .Dv AI_V4MAPPED_CFG
 203 flag is exact same as the
 204 .Dv AI_V4MAPPED
 205 flag only if the kernel supports IPv4-mapped IPv6 address.
 206 .It
 207 If the
 208 .Dv AI_ALL
 209 flag is used in conjunction with the
 210 .Dv AI_V4MAPPED
 211 flag, and only used with the IPv6 address family.
 212 When
 213 .Dv AI_ALL
 214 is logically or'd with
 215 .Dv AI_V4MAPPED
 216 flag then the caller wants all addresses: IPv6 and IPv4-mapped IPv6.
 217 A query is first made for
 218 .Li AAAA
 219 records and if successful, the
 220 IPv6 addresses are returned.
 221 Another query is then made for
 222 .Li A
 223 records and any found are returned as IPv4-mapped IPv6 addresses.
 224 .Li h_length
 225 will be 16.
 226 Only if both queries fail does the function
 227 return a
 228 .Dv NULL
 229 pointer.
 230 This flag is ignored unless af equals
 231 AF_INET6.
 232 If both
 233 .Dv AI_ALL
 234 and
 235 .Dv AI_V4MAPPED
 236 are specified,
 237 .Dv AI_ALL
 238 takes precedence.
 239 .It
 240 The
 241 .Dv AI_ADDRCONFIG
 242 flag specifies that a query for
 243 .Li AAAA
 244 records
 245 should occur only if the node has at least one IPv6 source
 246 address configured and a query for
 247 .Li A
 248 records should occur only if the node has at least one IPv4 source address
 249 configured.
 250 .Pp
 251 For example, if the node has no IPv6 source addresses configured,
 252 and
 253 .Fa af
 254 equals AF_INET6, and the node name being looked up has both
 255 .Li AAAA
 256 and
 257 .Li A
 258 records, then:
 259 (a) if only
 260 .Dv AI_ADDRCONFIG
 261 is
 262 specified, the function returns a
 263 .Dv NULL
 264 pointer;
 265 (b) if
 266 .Dv AI_ADDRCONFIG
 267 |
 268 .Dv AI_V4MAPPED
 269 is specified, the
 270 .Li A
 271 records are returned as IPv4-mapped IPv6 addresses;
 272 .El
 273 .Pp
 274 The special flags value of
 275 .Dv AI_DEFAULT
 276 is defined as
 277 .Bd -literal -offset
 278    #define  AI_DEFAULT  (AI_V4MAPPED_CFG | AI_ADDRCONFIG)
 279 .Ed
 280 .Pp
 281 We noted that the
 282 .Fn getipnodebyname
 283 function must allow the
 284 .Fa name
 285 argument to be either a node name or a literal address string
 286 (i.e., a dotted-decimal IPv4 address or an IPv6 hex address).
 287 This saves applications from having to call
 288 .Xr inet_pton 3
 289 to handle literal address strings.
 290 When the
 291 .Fa name
 292 argument is a literal address string,
 293 the
 294 .Fa flags
 295 argument is always ignored.
 296 .Pp
 297 There are four scenarios based on the type of literal address string
 298 and the value of the
 299 .Fa af
 300 argument.
 301 The two simple cases are when
 302 .Fa name
 303 is a dotted-decimal IPv4 address and
 304 .Fa af
 305 equals
 306 .Dv AF_INET ,
 307 or when
 308 .Fa name
 309 is an IPv6 hex address and
 310 .Fa af
 311 equals
 312 .Dv AF_INET6 .
 313 The members of the
 314 returned hostent structure are:
 315 .Li h_name
 316 points to a copy of the
 317 .Fa name
 318 argument,
 319 .Li h_aliases
 320 is a
 321 .Dv NULL
 322 pointer,
 323 .Li h_addrtype
 324 is a copy of the
 325 .Fa af
 326 argument,
 327 .Li h_length
 328 is either 4
 329 (for
 330 .Dv AF_INET )
 331 or 16
 332 (for
 333 .Dv AF_INET6 ) ,
 334 .Li h_addr_list[0]
 335 is a pointer to the 4-byte or 16-byte binary address,
 336 and
 337 .Li h_addr_list[1]
 338 is a
 339 .Dv NULL
 340 pointer.
 341 .Pp
 342 When
 343 .Fa name
 344 is a dotted-decimal IPv4 address and
 345 .Fa af
 346 equals
 347 .Dv AF_INET6 ,
 348 and
 349 .Dv AI_V4MAPPED
 350 is specified,
 351 an IPv4-mapped IPv6 address is returned:
 352 .Li h_name
 353 points to an IPv6 hex address containing the IPv4-mapped IPv6 address,
 354 .Li h_aliases
 355 is a
 356 .Dv NULL
 357 pointer,
 358 .Li h_addrtype
 359 is
 360 .Dv AF_INET6 ,
 361 .Li h_length
 362 is 16,
 363 .Li h_addr_list[0]
 364 is a pointer to the 16-byte binary address, and
 365 .Li h_addr_list[1]
 366 is a
 367 .Dv NULL
 368 pointer.
 369 .Pp
 370 It is an error when
 371 .Fa name
 372 is an IPv6 hex address and
 373 .Fa af
 374 equals
 375 .Dv AF_INET .
 376 The function's return value is a
 377 .Dv NULL
 378 pointer and the value pointed to by
 379 .Fa error_num
 380 equals
 381 .Dv HOST_NOT_FOUND .
 382 .Pp
 383 The
 384 .Fn getipnodebyaddr
 385 function
 386 takes almost the same argument as
 387 .Xr gethostbyaddr 3 ,
 388 but adds a pointer to return an error number.
 389 Additionally it takes care of IPv4-mapped IPv6 addresses,
 390 and IPv4-compatible IPv6 addresses.
 391 .Pp
 392 The
 393 .Fn getipnodebyname
 394 and
 395 .Fn getipnodebyaddr
 396 functions
 397 dynamically allocate the structure to be returned to the caller.
 398 The
 399 .Fn freehostent
 400 function
 401 reclaims memory region allocated and returned by
 402 .Fn getipnodebyname
 403 or
 404 .Fn getipnodebyaddr .
 405 .\"
 406 .Sh FILES
 407 .Bl -tag -width /etc/nsswitch.conf -compact
 408 .It Pa /etc/hosts
 409 .It Pa /etc/nsswitch.conf
 410 .It Pa /etc/resolv.conf
 411 .El
 412 .\"
 413 .Sh DIAGNOSTICS
 414 The
 415 .Fn getipnodebyname
 416 and
 417 .Fn getipnodebyaddr
 418 functions
 419 returns
 420 .Dv NULL
 421 on errors.
 422 The integer values pointed to by
 423 .Fa error_num
 424 may then be checked to see whether this is a temporary failure
 425 or an invalid or unknown host.
 426 The meanings of each error code are described in
 427 .Xr gethostbyname 3 .
 428 .\"
 429 .Sh SEE ALSO
 430 .Xr getaddrinfo 3 ,
 431 .Xr gethostbyaddr 3 ,
 432 .Xr gethostbyname 3 ,
 433 .Xr getnameinfo 3 ,
 434 .Xr hosts 5 ,
 435 .Xr nsswitch.conf 5 ,
 436 .Xr services 5 ,
 437 .Xr hostname 7 ,
 438 .Xr named 8
 439 .Pp
 440 .Rs
 441 .%A R. Gilligan
 442 .%A S. Thomson
 443 .%A J. Bound
 444 .%A W. Stevens
 445 .%T Basic Socket Interface Extensions for IPv6
 446 .%R RFC2553
 447 .%D March 1999
 448 .Re
 449 .\"
 450 .Sh STANDARDS
 451 The
 452 .Fn getipnodebyname
 453 and
 454 .Fn getipnodebyaddr
 455 functions
 456 are documented in
 457 .Dq Basic Socket Interface Extensions for IPv6
 458 (RFC2553).
 459 .\"
 460 .Sh HISTORY
 461 The implementation first appeared in KAME advanced networking kit.
 462 .\"
 463 .Sh BUGS
 464 The
 465 .Fn getipnodebyname
 466 and
 467 .Fn getipnodebyaddr
 468 functions
 469 do not handle scoped IPv6 address properly.
 470 If you use these functions,
 471 your program will not be able to handle scoped IPv6 addresses.
 472 For IPv6 address manipulation,
 473 .Fn getaddrinfo 3
 474 and
 475 .Fn getnameinfo 3
 476 are recommended.
 477 .Pp
 478 The text was shamelessly copied from RFC2553.