lib/libc/net/getipnodebyname.3

   1 .\" Copyright (c) 1983, 1987, 1991, 1993
   2 .\"     The Regents of the University of California.  All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\" 3. All advertising materials mentioning features or use of this software
  13 .\"    must display the following acknowledgement:
  14 .\"     This product includes software developed by the University of
  15 .\"     California, Berkeley and its contributors.
  16 .\" 4. Neither the name of the University nor the names of its contributors
  17 .\"    may be used to endorse or promote products derived from this software
  18 .\"    without specific prior written permission.
  19 .\"
  20 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  21 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  22 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  23 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  24 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  25 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  26 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  27 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  28 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  29 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  30 .\" SUCH DAMAGE.
  31 .\"
  32 .\"     From: @(#)gethostbyname.3       8.4 (Berkeley) 5/25/95
  33 .\"     $Id: getipnodebyname.3,v 1.2 1999/09/13 16:04:51 itojun Exp $
  34 .\      $FreeBSD$
  35 .\"
  36 .Dd May 25, 1995
  37 .Dt GETIPNODEBYNAME 3
  38 .Os KAME
  39 .\"
  40 .Sh NAME
  41 .Nm getipnodebyname ,
  42 .Nm getipnodebyaddr ,
  43 .Nm freehostent
  44 .Nd nodename-to-address and address-to-nodename translation
  45 .\"
  46 .Sh SYNOPSIS
  47 .Fd #include <sys/types.h>
  48 .Fd #include <sys/socket.h>
  49 .Fd #include <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 .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 .Ar af ,
  70 and
  71 .Ar 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 .Po
  76 such as
  77 .Dv AF_INET
  78 or
  79 .Dv AF_INET6
  80 .Pc .
  81 The functions also require an additional pointer argument,
  82 .Ar error_num
  83 to return the appropriate error code,
  84 to support thread safe error code returns.
  85 .Pp
  86 The type and usage of the return value,
  87 .Li "struct hostent"
  88 is described in
  89 .Xr gethostbyname 3 .
  90 .Pp
  91 For
  92 .Fn getipnodebyname ,
  93 the
  94 .Ar name
  95 argument can be either a node name or a numeric address
  96 string
  97 .Po
  98 i.e., a dotted-decimal IPv4 address or an IPv6 hex address
  99 .Pc .
 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 .Pq 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 .Po
 193 .Li h_length
 194 will be 16
 195 .Pc .
 196 The
 197 .Dv AI_V4MAPPED
 198 flag is ignored unless
 199 .Ar af
 200 equals
 201 .Dv AF_INET6 .
 202 .It
 203 The
 204 .Dv AI_V4MAPPED_CFG
 205 flag is exact same as the
 206 .Dv AI_V4MAPPED
 207 flag only if the kernel supports IPv4-mapped IPv6 address.
 208 .It
 209 If the
 210 .Dv AI_ALL
 211 flag is used in conjunction with the
 212 .Dv AI_V4MAPPED
 213 flag, and only used with the IPv6 address family.
 214 When
 215 .Dv AI_ALL
 216 is logically or'd with
 217 .Dv AI_V4MAPPED
 218 flag then the caller wants all addresses: IPv6 and IPv4-mapped IPv6.
 219 A query is first made for
 220 .Li AAAA
 221 records and if successful, the
 222 IPv6 addresses are returned.  Another query is then made for
 223 .Li A
 224 records and any found are returned as IPv4-mapped IPv6 addresses.
 225 .Li h_length
 226 will be 16.  Only if both queries fail does the function
 227 return a
 228 .Dv NULL
 229 pointer.  This flag is ignored unless af equals
 230 AF_INET6.  If both
 231 .Dv AI_ALL
 232 and
 233 .Dv AI_V4MAPPED
 234 are specified,
 235 .Dv AI_ALL
 236 takes precedence.
 237 .It
 238 The
 239 .Dv AI_ADDRCONFIG
 240 flag specifies that a query for
 241 .Li AAAA
 242 records
 243 should occur only if the node has at least one IPv6 source
 244 address configured and a query for
 245 .Li A
 246 records should occur only if the node has at least one IPv4 source address
 247 configured.
 248 .Pp
 249 For example, if the node has no IPv6 source addresses configured,
 250 and
 251 .Ar af
 252 equals AF_INET6, and the node name being looked up has both
 253 .Li AAAA
 254 and
 255 .Li A
 256 records, then:
 257 (a) if only
 258 .Dv AI_ADDRCONFIG
 259 is
 260 specified, the function returns a
 261 .Dv NULL
 262 pointer;
 263 (b) if
 264 .Dv AI_ADDRCONFIG
 265 |
 266 .Dv AI_V4MAPPED
 267 is specified, the
 268 .Li A
 269 records are returned as IPv4-mapped IPv6 addresses;
 270 .El
 271 .Pp
 272 The special flags value of
 273 .Dv AI_DEFAULT
 274 is defined as
 275 .Bd -literal -offset
 276    #define  AI_DEFAULT  (AI_V4MAPPED_CFG | AI_ADDRCONFIG)
 277 .Ed
 278 .Pp
 279 We noted that the
 280 .Fn getipnodebyname
 281 function must allow the
 282 .Ar name
 283 argument to be either a node name or a literal address string
 284 .Po
 285 i.e., a dotted-decimal IPv4 address or an IPv6 hex address
 286 .Pc .
 287 This saves applications from having to call
 288 .Xr inet_pton 3
 289 to handle literal address strings.
 290 When the
 291 .Ar name
 292 argument is a literal address string,
 293 the
 294 .Ar 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 .Ar af
 300 argument.
 301 The two simple cases are when
 302 .Ar name
 303 is a dotted-decimal IPv4 address and
 304 .Ar af
 305 equals
 306 .Dv AF_INET ,
 307 or when
 308 .Ar name
 309 is an IPv6 hex address and
 310 .Ar 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 .Ar 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 .Ar af
 326 argument,
 327 .Li h_length
 328 is either 4
 329 .Po
 330 for
 331 .Dv AF_INET
 332 .Pc
 333 or 16
 334 .Po
 335 for
 336 .Dv AF_INET6
 337 .Pc ,
 338 .Li h_addr_list[0]
 339 is a pointer to the 4-byte or 16-byte binary address,
 340 and
 341 .Li h_addr_list[1]
 342 is a
 343 .Dv NULL
 344 pointer.
 345 .Pp
 346 When
 347 .Ar name
 348 is a dotted-decimal IPv4 address and
 349 .Ar af
 350 equals
 351 .Dv AF_INET6 ,
 352 and
 353 .Dv AI_V4MAPPED
 354 is specified,
 355 an IPv4-mapped IPv6 address is returned:
 356 .Li h_name
 357 points to an IPv6 hex address containing the IPv4-mapped IPv6 address,
 358 .Li h_aliases
 359 is a
 360 .Dv NULL
 361 pointer,
 362 .Li h_addrtype
 363 is
 364 .Dv AF_INET6 ,
 365 .Li h_length
 366 is 16,
 367 .Li h_addr_list[0]
 368 is a pointer to the 16-byte binary address, and
 369 .Li h_addr_list[1]
 370 is a
 371 .Dv NULL
 372 pointer.
 373 .Pp
 374 It is an error when
 375 .Ar name
 376 is an IPv6 hex address and
 377 .Ar af
 378 equals
 379 .Dv AF_INET .
 380 The function's return value is a
 381 .Dv NULL
 382 pointer and the value pointed to by
 383 .Ar error_num
 384 equals
 385 .Dv HOST_NOT_FOUND .
 386 .Pp
 387 .Fn getipnodebyaddr
 388 takes almost the same argument as
 389 .Xr gethostbyaddr 3 ,
 390 but adds a pointer to return an error number.
 391 Additionally it takes care of IPv4-mapped IPv6 addresses,
 392 and IPv4-compatible IPv6 addresses.
 393 .Pp
 394 .Fn getipnodebyname
 395 and
 396 .Fn getipnodebyaddr
 397 dynamically allocate the structure to be returned to the caller.
 398 .Fn freehostent
 399 reclaims memory region allocated and returned by
 400 .Fn getipnodebyname
 401 or
 402 .Fn getipnodebyaddr .
 403 .\"
 404 .Sh FILES
 405 .Bl -tag -width /etc/resolv.conf -compact
 406 .It Pa /etc/hosts
 407 .It Pa /etc/host.conf
 408 .It Pa /etc/resolv.conf
 409 .El
 410 .\"
 411 .Sh DIAGNOSTICS
 412 .Nm getipnodebyname
 413 and
 414 .Nm getipnodebyaddr
 415 returns
 416 .Dv NULL
 417 on errors.
 418 The integer values pointed to by
 419 .Ar 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 gethostbyname 3 ,
 427 .Xr gethostbyaddr 3 ,
 428 .Xr hosts 5 ,
 429 .Xr services 5 ,
 430 .Xr hostname 7 ,
 431 .Xr named 8
 432 .Pp
 433 R. Gilligan, S.  Thomson, J. Bound, and W. Stevens,
 434 ``Basic Socket Interface Extensions for IPv6,'' RFC2553, March 1999.
 435 .\"
 436 .Sh HISTORY
 437 The implementation first appeared in KAME advanced networking kit.
 438 .\"
 439 .Sh STANDARDS
 440 .Fn getipnodebyname
 441 and
 442 .Fn getipnodebyaddr
 443 are documented in ``Basic Socket Interface Extensions for IPv6''
 444 .Pq RFC2553 .
 445 .\"
 446 .Sh BUGS
 447 The text was shamelessly copied from RFC2553.