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