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