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