gen.subproj/getipnodebyname.3

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