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