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