lib/libc/net/getipnodebyname.3

   1 .\"     $FreeBSD: src/lib/libc/net/getipnodebyname.3,v 1.2.2.4 2001/12/14 18:33:55 ru Exp $
   2 .\"     $DragonFly: src/lib/libc/net/getipnodebyname.3,v 1.3 2006/02/17 19:35:06 swildner Exp $
   3 .\"     $KAME: getipnodebyname.3,v 1.6 2000/08/09 21:16:17 itojun Exp $
   4 .\"
   5 .\" Copyright (c) 1983, 1987, 1991, 1993
   6 .\"     The Regents of the University of California.  All rights reserved.
   7 .\"
   8 .\" Redistribution and use in source and binary forms, with or without
   9 .\" modification, are permitted provided that the following conditions
  10 .\" are met:
  11 .\" 1. Redistributions of source code must retain the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer.
  13 .\" 2. Redistributions in binary form must reproduce the above copyright
  14 .\"    notice, this list of conditions and the following disclaimer in the
  15 .\"    documentation and/or other materials provided with the distribution.
  16 .\" 3. All advertising materials mentioning features or use of this software
  17 .\"    must display the following acknowledgement:
  18 .\"     This product includes software developed by the University of
  19 .\"     California, Berkeley and its contributors.
  20 .\" 4. Neither the name of the University nor the names of its contributors
  21 .\"    may be used to endorse or promote products derived from this software
  22 .\"    without specific prior written permission.
  23 .\"
  24 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  25 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  26 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  27 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  28 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  29 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  30 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  31 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  32 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  33 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  34 .\" SUCH DAMAGE.
  35 .\"
  36 .\"     From: @(#)gethostbyname.3       8.4 (Berkeley) 5/25/95
  37 .\"
  38 .Dd May 25, 1995
  39 .Dt GETIPNODEBYNAME 3
  40 .Os
  41 .\"
  42 .Sh NAME
  43 .Nm getipnodebyname ,
  44 .Nm getipnodebyaddr ,
  45 .Nm freehostent
  46 .Nd nodename-to-address and address-to-nodename translation
  47 .\"
  48 .Sh LIBRARY
  49 .Lb libc
  50 .Sh SYNOPSIS
  51 .In sys/types.h
  52 .In sys/socket.h
  53 .In netdb.h
  54 .Ft "struct hostent *"
  55 .Fn getipnodebyname "const char *name" "int af" "int flags" "int *error_num"
  56 .Ft "struct hostent *"
  57 .Fn getipnodebyaddr "const void *src" "size_t len" "int af" "int *error_num"
  58 .Ft void
  59 .Fn freehostent "struct hostent *ptr"
  60 .\"
  61 .Sh DESCRIPTION
  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 .Ar af ,
  74 and
  75 .Ar 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 .Ar 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 .Ar 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 .Ar af
 102 argument specifies the address family, either
 103 .Dv AF_INET
 104 or
 105 .Dv AF_INET6 .
 106 The
 107 .Ar 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 .Ar flags
 127 argument.
 128 .Pp
 129 A
 130 .Ar flags
 131 of
 132 .Li 0
 133 implies a strict interpretation of the
 134 .Ar af
 135 argument:
 136 .Bl -bullet
 137 .It
 138 If
 139 .Ar flags
 140 is 0 and
 141 .Ar 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 .Ar flags
 158 is 0 and if
 159 .Ar 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 .Ar 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 .Ar 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 .Ar 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.  Another query is then made for
 221 .Li A
 222 records and any found are returned as IPv4-mapped IPv6 addresses.
 223 .Li h_length
 224 will be 16.  Only if both queries fail does the function
 225 return a
 226 .Dv NULL
 227 pointer.  This flag is ignored unless af equals
 228 AF_INET6.  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 .Ar 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 .Ar 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 .Ar name
 288 argument is a literal address string,
 289 the
 290 .Ar 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 .Ar af
 296 argument.
 297 The two simple cases are when
 298 .Ar name
 299 is a dotted-decimal IPv4 address and
 300 .Ar af
 301 equals
 302 .Dv AF_INET ,
 303 or when
 304 .Ar name
 305 is an IPv6 hex address and
 306 .Ar 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 .Ar 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 .Ar 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 .Ar name
 340 is a dotted-decimal IPv4 address and
 341 .Ar 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 .Ar name
 368 is an IPv6 hex address and
 369 .Ar 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 .Ar error_num
 376 equals
 377 .Dv HOST_NOT_FOUND .
 378 .Pp
 379 .Fn getipnodebyaddr
 380 takes almost the same argument as
 381 .Xr gethostbyaddr 3 ,
 382 but adds a pointer to return an error number.
 383 Additionally it takes care of IPv4-mapped IPv6 addresses,
 384 and IPv4-compatible IPv6 addresses.
 385 .Pp
 386 .Fn getipnodebyname
 387 and
 388 .Fn getipnodebyaddr
 389 dynamically allocate the structure to be returned to the caller.
 390 .Fn freehostent
 391 reclaims memory region allocated and returned by
 392 .Fn getipnodebyname
 393 or
 394 .Fn getipnodebyaddr .
 395 .\"
 396 .Sh FILES
 397 .Bl -tag -width /etc/resolv.conf -compact
 398 .It Pa /etc/hosts
 399 .It Pa /etc/host.conf
 400 .It Pa /etc/resolv.conf
 401 .El
 402 .\"
 403 .Sh DIAGNOSTICS
 404 .Fn getipnodebyname
 405 and
 406 .Fn getipnodebyaddr
 407 returns
 408 .Dv NULL
 409 on errors.
 410 The integer values pointed to by
 411 .Ar error_num
 412 may then be checked to see whether this is a temporary failure
 413 or an invalid or unknown host.
 414 The meanings of each error code are described in
 415 .Xr gethostbyname 3 .
 416 .\"
 417 .Sh SEE ALSO
 418 .Xr gethostbyaddr 3 ,
 419 .Xr gethostbyname 3 ,
 420 .Xr hosts 5 ,
 421 .Xr services 5 ,
 422 .Xr hostname 7 ,
 423 .Xr named 8
 424 .Pp
 425 .Rs
 426 .%A R. Gilligan
 427 .%A S. Thomson
 428 .%A J. Bound
 429 .%A W. Stevens
 430 .%T Basic Socket Interface Extensions for IPv6
 431 .%R RFC2553
 432 .%D March 1999
 433 .Re
 434 .\"
 435 .Sh STANDARDS
 436 .Fn getipnodebyname
 437 and
 438 .Fn getipnodebyaddr
 439 are documented in
 440 .Dq Basic Socket Interface Extensions for IPv6
 441 (RFC2553).
 442 .\"
 443 .Sh HISTORY
 444 The implementation first appeared in KAME advanced networking kit.
 445 .\"
 446 .Sh BUGS
 447 .Fn getipnodebyname
 448 and
 449 .Fn getipnodebyaddr
 450 do not handle scoped IPv6 address properly.
 451 If you use these functions,
 452 your program will not be able to handle scoped IPv6 addresses.
 453 For IPv6 address manipulation,
 454 .Fn getaddrinfo 3
 455 and
 456 .Fn getnameinfo 3
 457 are recommended.
 458 .Pp
 459 The current implementation is not thread-safe.
 460 .Pp
 461 The text was shamelessly copied from RFC2553.