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