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.\" 3. 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: src/lib/libc/net/getipnodebyname.3,v 1.18 2007/01/09 00:28:02 imp Exp $ 32.\" 33.Dd May 5, 2019 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 112 hptr = gethostbyname(name); 113.Ed 114.Pp 115with 116.Bd -literal 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.Dv 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 227.Fa af 228equals 229.Dv AF_INET6 . 230If both 231.Dv AI_ALL 232and 233.Dv AI_V4MAPPED 234are specified, 235.Dv AI_ALL 236takes precedence. 237.It 238The 239.Dv AI_ADDRCONFIG 240flag specifies that a query for 241.Li AAAA 242records 243should occur only if the node has at least one IPv6 source 244address configured and a query for 245.Li A 246records should occur only if the node has at least one IPv4 source address 247configured. 248.Pp 249For example, if the node has no IPv6 source addresses configured, 250and 251.Fa af 252equals 253.Dv AF_INET6 , 254and the node name being looked up has both 255.Li AAAA 256and 257.Li A 258records, then: 259(a) if only 260.Dv AI_ADDRCONFIG 261is 262specified, the function returns a 263.Dv NULL 264pointer; 265(b) if 266.Dv AI_ADDRCONFIG 267| 268.Dv AI_V4MAPPED 269is specified, the 270.Li A 271records are returned as IPv4-mapped IPv6 addresses; 272.El 273.Pp 274The special flags value of 275.Dv AI_DEFAULT 276is defined as 277.Bd -literal 278 #define AI_DEFAULT (AI_V4MAPPED_CFG | AI_ADDRCONFIG) 279.Ed 280.Pp 281We noted that the 282.Fn getipnodebyname 283function must allow the 284.Fa name 285argument to be either a node name or a literal address string 286(i.e., a dotted-decimal IPv4 address or an IPv6 hex address). 287This saves applications from having to call 288.Xr inet_pton 3 289to handle literal address strings. 290When the 291.Fa name 292argument is a literal address string, 293the 294.Fa flags 295argument is always ignored. 296.Pp 297There are four scenarios based on the type of literal address string 298and the value of the 299.Fa af 300argument. 301The two simple cases are when 302.Fa name 303is a dotted-decimal IPv4 address and 304.Fa af 305equals 306.Dv AF_INET , 307or when 308.Fa name 309is an IPv6 hex address and 310.Fa af 311equals 312.Dv AF_INET6 . 313The members of the 314returned hostent structure are: 315.Li h_name 316points to a copy of the 317.Fa name 318argument, 319.Li h_aliases 320is a 321.Dv NULL 322pointer, 323.Li h_addrtype 324is a copy of the 325.Fa af 326argument, 327.Li h_length 328is either 4 329(for 330.Dv AF_INET ) 331or 16 332(for 333.Dv AF_INET6 ) , 334.Li h_addr_list[0] 335is a pointer to the 4-byte or 16-byte binary address, 336and 337.Li h_addr_list[1] 338is a 339.Dv NULL 340pointer. 341.Pp 342When 343.Fa name 344is a dotted-decimal IPv4 address and 345.Fa af 346equals 347.Dv AF_INET6 , 348and 349.Dv AI_V4MAPPED 350is specified, 351an IPv4-mapped IPv6 address is returned: 352.Li h_name 353points to an IPv6 hex address containing the IPv4-mapped IPv6 address, 354.Li h_aliases 355is a 356.Dv NULL 357pointer, 358.Li h_addrtype 359is 360.Dv AF_INET6 , 361.Li h_length 362is 16, 363.Li h_addr_list[0] 364is a pointer to the 16-byte binary address, and 365.Li h_addr_list[1] 366is a 367.Dv NULL 368pointer. 369.Pp 370It is an error when 371.Fa name 372is an IPv6 hex address and 373.Fa af 374equals 375.Dv AF_INET . 376The function's return value is a 377.Dv NULL 378pointer and the value pointed to by 379.Fa error_num 380equals 381.Dv HOST_NOT_FOUND . 382.Pp 383The 384.Fn getipnodebyaddr 385function 386takes almost the same argument as 387.Xr gethostbyaddr 3 , 388but adds a pointer to return an error number. 389Additionally it takes care of IPv4-mapped IPv6 addresses, 390and IPv4-compatible IPv6 addresses. 391.Pp 392The 393.Fn getipnodebyname 394and 395.Fn getipnodebyaddr 396functions 397dynamically allocate the structure to be returned to the caller. 398The 399.Fn freehostent 400function 401reclaims memory region allocated and returned by 402.Fn getipnodebyname 403or 404.Fn getipnodebyaddr . 405.\" 406.Sh RETURN VALUES 407The 408.Fn getipnodebyname 409and 410.Fn getipnodebyaddr 411functions 412returns 413.Dv NULL 414on errors. 415The integer values pointed to by 416.Fa error_num 417may then be checked to see whether this is a temporary failure 418or an invalid or unknown host. 419The meanings of each error code are described in 420.Xr gethostbyname 3 . 421.\" 422.Sh FILES 423.Bl -tag -width /etc/nsswitch.conf -compact 424.It Pa /etc/hosts 425.It Pa /etc/nsswitch.conf 426.It Pa /etc/resolv.conf 427.El 428.\" 429.Sh SEE ALSO 430.Xr getaddrinfo 3 , 431.Xr gethostbyaddr 3 , 432.Xr gethostbyname 3 , 433.Xr getnameinfo 3 , 434.Xr hosts 5 , 435.Xr nsswitch.conf 5 , 436.Xr services 5 , 437.Xr hostname 7 , 438.Xr named 8 439.Rs 440.%A R. Gilligan 441.%A S. Thomson 442.%A J. Bound 443.%A W. Stevens 444.%T Basic Socket Interface Extensions for IPv6 445.%R RFC 2553 446.%D March 1999 447.Re 448.\" 449.Sh STANDARDS 450The 451.Fn getipnodebyname 452and 453.Fn getipnodebyaddr 454functions 455are documented in 456.Dq Basic Socket Interface Extensions for IPv6 457(RFC 2553). 458.\" 459.Sh HISTORY 460The implementation first appeared in KAME advanced networking kit. 461.\" 462.Sh BUGS 463The 464.Fn getipnodebyname 465and 466.Fn getipnodebyaddr 467functions 468do not handle scoped IPv6 address properly. 469If you use these functions, 470your program will not be able to handle scoped IPv6 addresses. 471For IPv6 address manipulation, 472.Fn getaddrinfo 3 473and 474.Fn getnameinfo 3 475are recommended. 476.Pp 477The text was shamelessly copied from RFC 2553. 478