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