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.In sys/types.h 51.In sys/socket.h 52.In 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(such as 79.Dv AF_INET 80or 81.Dv AF_INET6 ) . 82The functions also require an additional pointer argument, 83.Ar error_num 84to return the appropriate error code, 85to support thread safe error code returns. 86.Pp 87The type and usage of the return value, 88.Li "struct hostent" 89is described in 90.Xr gethostbyname 3 . 91.Pp 92For 93.Fn getipnodebyname , 94the 95.Ar name 96argument can be either a node name or a numeric address 97string 98(i.e., a dotted-decimal IPv4 address or an IPv6 hex address). 99The 100.Ar af 101argument specifies the address family, either 102.Dv AF_INET 103or 104.Dv AF_INET6 . 105The 106.Ar flags 107argument specifies the types of addresses that are searched for, 108and the types of addresses that are returned. 109We note that a special flags value of 110.Dv AI_DEFAULT 111(defined below) 112should handle most applications. 113That is, porting simple applications to use IPv6 replaces the call 114.Bd -literal -offset 115 hptr = gethostbyname(name); 116.Ed 117.Pp 118with 119.Bd -literal -offset 120 hptr = getipnodebyname(name, AF_INET6, AI_DEFAULT, &error_num); 121.Ed 122.Pp 123Applications desiring finer control over the types of addresses 124searched for and returned, can specify other combinations of the 125.Ar flags 126argument. 127.Pp 128A 129.Ar flags 130of 131.Li 0 132implies a strict interpretation of the 133.Ar af 134argument: 135.Bl -bullet 136.It 137If 138.Ar flags 139is 0 and 140.Ar af 141is 142.Dv AF_INET , 143then the caller wants only IPv4 addresses. 144A query is made for 145.Li A 146records. 147If successful, the IPv4 addresses are returned and the 148.Li h_length 149member of the 150.Li hostent 151structure will be 4, else the function returns a 152.Dv NULL 153pointer. 154.It 155If 156.Ar flags 157is 0 and if 158.Ar af 159is 160.Li AF_INET6 , 161then the caller wants only IPv6 addresses. 162A query is made for 163.Li AAAA 164records. 165If successful, the IPv6 addresses are returned and the 166.Li h_length 167member of the 168.Li hostent 169structure will be 16, else the function returns a 170.Dv NULL 171pointer. 172.El 173.Pp 174Other constants can be logically-ORed into the 175.Ar flags 176argument, to modify the behavior of the function. 177.Bl -bullet 178.It 179If the 180.Dv AI_V4MAPPED 181flag is specified along with an 182.Ar af 183of 184.Dv AF_INET6 , 185then the caller will accept IPv4-mapped IPv6 addresses. 186That is, if no 187.Li AAAA 188records are found then a query is made for 189.Li A 190records and any found are returned as IPv4-mapped IPv6 addresses 191.Li ( h_length 192will be 16). 193The 194.Dv AI_V4MAPPED 195flag is ignored unless 196.Ar af 197equals 198.Dv AF_INET6 . 199.It 200The 201.Dv AI_V4MAPPED_CFG 202flag is exact same as the 203.Dv AI_V4MAPPED 204flag only if the kernel supports IPv4-mapped IPv6 address. 205.It 206If the 207.Dv AI_ALL 208flag is used in conjunction with the 209.Dv AI_V4MAPPED 210flag, and only used with the IPv6 address family. 211When 212.Dv AI_ALL 213is logically or'd with 214.Dv AI_V4MAPPED 215flag then the caller wants all addresses: IPv6 and IPv4-mapped IPv6. 216A query is first made for 217.Li AAAA 218records and if successful, the 219IPv6 addresses are returned. Another query is then made for 220.Li A 221records and any found are returned as IPv4-mapped IPv6 addresses. 222.Li h_length 223will be 16. Only if both queries fail does the function 224return a 225.Dv NULL 226pointer. This flag is ignored unless af equals 227AF_INET6. If 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.Ar 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 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.Ar 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.Ar name 287argument is a literal address string, 288the 289.Ar 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.Ar af 295argument. 296The two simple cases are when 297.Ar name 298is a dotted-decimal IPv4 address and 299.Ar af 300equals 301.Dv AF_INET , 302or when 303.Ar name 304is an IPv6 hex address and 305.Ar 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.Ar name 313argument, 314.Li h_aliases 315is a 316.Dv NULL 317pointer, 318.Li h_addrtype 319is a copy of the 320.Ar 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.Ar name 339is a dotted-decimal IPv4 address and 340.Ar 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.Ar name 367is an IPv6 hex address and 368.Ar af 369equals 370.Dv AF_INET . 371The function's return value is a 372.Dv NULL 373pointer and the value pointed to by 374.Ar error_num 375equals 376.Dv HOST_NOT_FOUND . 377.Pp 378.Fn getipnodebyaddr 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 385.Fn getipnodebyname 386and 387.Fn getipnodebyaddr 388dynamically allocate the structure to be returned to the caller. 389.Fn freehostent 390reclaims memory region allocated and returned by 391.Fn getipnodebyname 392or 393.Fn getipnodebyaddr . 394.\" 395.Sh FILES 396.Bl -tag -width /etc/nsswitch.conf -compact 397.It Pa /etc/hosts 398.It Pa /etc/nsswitch.conf 399.It Pa /etc/resolv.conf 400.El 401.\" 402.Sh DIAGNOSTICS 403.Fn getipnodebyname 404and 405.Fn getipnodebyaddr 406returns 407.Dv NULL 408on errors. 409The integer values pointed to by 410.Ar error_num 411may then be checked to see whether this is a temporary failure 412or an invalid or unknown host. 413The meanings of each error code are described in 414.Xr gethostbyname 3 . 415.\" 416.Sh SEE ALSO 417.Xr gethostbyaddr 3 , 418.Xr gethostbyname 3 , 419.Xr hosts 5 , 420.Xr nsswitch.conf 5 , 421.Xr services 5 , 422.Xr hostname 7 , 423.Xr named 8 424.Pp 425.Rs 426.%A R. Gilligan 427.%A S. Thomson 428.%A J. Bound 429.%A W. Stevens 430.%T Basic Socket Interface Extensions for IPv6 431.%R RFC2553 432.%D March 1999 433.Re 434.\" 435.Sh HISTORY 436The implementation first appeared in KAME advanced networking kit. 437.\" 438.Sh STANDARDS 439.Fn getipnodebyname 440and 441.Fn getipnodebyaddr 442are documented in 443.Dq Basic Socket Interface Extensions for IPv6 444(RFC2553). 445.\" 446.Sh BUGS 447.Fn getipnodebyname 448and 449.Fn getipnodebyaddr 450do not handle scoped IPv6 address properly. 451If you use these functions, 452your program will not be able to handle scoped IPv6 addresses. 453For IPv6 address manipulation, 454.Fn getaddrinfo 3 455and 456.Fn getnameinfo 3 457are recommended. 458.Pp 459The current implementation is not thread-safe. 460.Pp 461The text was shamelessly copied from RFC2553. 462