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. All advertising materials mentioning features or use of this software 15.\" must display the following acknowledgement: 16.\" This product includes software developed by the University of 17.\" California, Berkeley and its contributors. 18.\" 4. Neither the name of the University nor the names of its contributors 19.\" may be used to endorse or promote products derived from this software 20.\" without specific prior written permission. 21.\" 22.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 23.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 24.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 25.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 26.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 27.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 28.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 29.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 30.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 31.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 32.\" SUCH DAMAGE. 33.\" 34.\" From: @(#)gethostbyname.3 8.4 (Berkeley) 5/25/95 35.\" $FreeBSD$ 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 61The 62.Fn getipnodebyname 63and 64.Fn getipnodebyaddr 65functions are very similar to 66.Xr gethostbyname 3 , 67.Xr gethostbyname2 3 68and 69.Xr gethostbyaddr 3 . 70The functions cover all the functionalities provided by the older ones, 71and provide better interface to programmers. 72The functions require additional arguments, 73.Fa af , 74and 75.Fa flags , 76for specifying address family and operation mode. 77The additional arguments allow programmer to get address for a nodename, 78for specific address family 79(such as 80.Dv AF_INET 81or 82.Dv AF_INET6 ) . 83The functions also require an additional pointer argument, 84.Fa error_num 85to return the appropriate error code, 86to support thread safe error code returns. 87.Pp 88The type and usage of the return value, 89.Li "struct hostent" 90is described in 91.Xr gethostbyname 3 . 92.Pp 93For 94.Fn getipnodebyname , 95the 96.Fa name 97argument can be either a node name or a numeric address 98string 99(i.e., a dotted-decimal IPv4 address or an IPv6 hex address). 100The 101.Fa af 102argument specifies the address family, either 103.Dv AF_INET 104or 105.Dv AF_INET6 . 106The 107.Fa flags 108argument specifies the types of addresses that are searched for, 109and the types of addresses that are returned. 110We note that a special flags value of 111.Dv AI_DEFAULT 112(defined below) 113should handle most applications. 114That is, porting simple applications to use IPv6 replaces the call 115.Bd -literal -offset 116 hptr = gethostbyname(name); 117.Ed 118.Pp 119with 120.Bd -literal -offset 121 hptr = getipnodebyname(name, AF_INET6, AI_DEFAULT, &error_num); 122.Ed 123.Pp 124Applications desiring finer control over the types of addresses 125searched for and returned, can specify other combinations of the 126.Fa flags 127argument. 128.Pp 129A 130.Fa flags 131of 132.Li 0 133implies a strict interpretation of the 134.Fa af 135argument: 136.Bl -bullet 137.It 138If 139.Fa flags 140is 0 and 141.Fa af 142is 143.Dv AF_INET , 144then the caller wants only IPv4 addresses. 145A query is made for 146.Li A 147records. 148If successful, the IPv4 addresses are returned and the 149.Li h_length 150member of the 151.Li hostent 152structure will be 4, else the function returns a 153.Dv NULL 154pointer. 155.It 156If 157.Fa flags 158is 0 and if 159.Fa af 160is 161.Li AF_INET6 , 162then the caller wants only IPv6 addresses. 163A query is made for 164.Li AAAA 165records. 166If successful, the IPv6 addresses are returned and the 167.Li h_length 168member of the 169.Li hostent 170structure will be 16, else the function returns a 171.Dv NULL 172pointer. 173.El 174.Pp 175Other constants can be logically-ORed into the 176.Fa flags 177argument, to modify the behavior of the function. 178.Bl -bullet 179.It 180If the 181.Dv AI_V4MAPPED 182flag is specified along with an 183.Fa af 184of 185.Dv AF_INET6 , 186then the caller will accept IPv4-mapped IPv6 addresses. 187That is, if no 188.Li AAAA 189records are found then a query is made for 190.Li A 191records and any found are returned as IPv4-mapped IPv6 addresses 192.Li ( h_length 193will be 16). 194The 195.Dv AI_V4MAPPED 196flag is ignored unless 197.Fa af 198equals 199.Dv AF_INET6 . 200.It 201The 202.Dv AI_V4MAPPED_CFG 203flag is exact same as the 204.Dv AI_V4MAPPED 205flag only if the kernel supports IPv4-mapped IPv6 address. 206.It 207If the 208.Dv AI_ALL 209flag is used in conjunction with the 210.Dv AI_V4MAPPED 211flag, and only used with the IPv6 address family. 212When 213.Dv AI_ALL 214is logically or'd with 215.Dv AI_V4MAPPED 216flag then the caller wants all addresses: IPv6 and IPv4-mapped IPv6. 217A query is first made for 218.Li AAAA 219records and if successful, the 220IPv6 addresses are returned. Another query is then made for 221.Li A 222records and any found are returned as IPv4-mapped IPv6 addresses. 223.Li h_length 224will be 16. Only if both queries fail does the function 225return a 226.Dv NULL 227pointer. This flag is ignored unless af equals 228AF_INET6. If both 229.Dv AI_ALL 230and 231.Dv AI_V4MAPPED 232are specified, 233.Dv AI_ALL 234takes precedence. 235.It 236The 237.Dv AI_ADDRCONFIG 238flag specifies that a query for 239.Li AAAA 240records 241should occur only if the node has at least one IPv6 source 242address configured and a query for 243.Li A 244records should occur only if the node has at least one IPv4 source address 245configured. 246.Pp 247For example, if the node has no IPv6 source addresses configured, 248and 249.Fa af 250equals AF_INET6, and the node name being looked up has both 251.Li AAAA 252and 253.Li A 254records, then: 255(a) if only 256.Dv AI_ADDRCONFIG 257is 258specified, the function returns a 259.Dv NULL 260pointer; 261(b) if 262.Dv AI_ADDRCONFIG 263| 264.Dv AI_V4MAPPED 265is specified, the 266.Li A 267records are returned as IPv4-mapped IPv6 addresses; 268.El 269.Pp 270The special flags value of 271.Dv AI_DEFAULT 272is defined as 273.Bd -literal -offset 274 #define AI_DEFAULT (AI_V4MAPPED_CFG | AI_ADDRCONFIG) 275.Ed 276.Pp 277We noted that the 278.Fn getipnodebyname 279function must allow the 280.Fa name 281argument to be either a node name or a literal address string 282(i.e., a dotted-decimal IPv4 address or an IPv6 hex address). 283This saves applications from having to call 284.Xr inet_pton 3 285to handle literal address strings. 286When the 287.Fa name 288argument is a literal address string, 289the 290.Fa flags 291argument is always ignored. 292.Pp 293There are four scenarios based on the type of literal address string 294and the value of the 295.Fa af 296argument. 297The two simple cases are when 298.Fa name 299is a dotted-decimal IPv4 address and 300.Fa af 301equals 302.Dv AF_INET , 303or when 304.Fa name 305is an IPv6 hex address and 306.Fa af 307equals 308.Dv AF_INET6 . 309The members of the 310returned hostent structure are: 311.Li h_name 312points to a copy of the 313.Fa name 314argument, 315.Li h_aliases 316is a 317.Dv NULL 318pointer, 319.Li h_addrtype 320is a copy of the 321.Fa af 322argument, 323.Li h_length 324is either 4 325(for 326.Dv AF_INET ) 327or 16 328(for 329.Dv AF_INET6 ) , 330.Li h_addr_list[0] 331is a pointer to the 4-byte or 16-byte binary address, 332and 333.Li h_addr_list[1] 334is a 335.Dv NULL 336pointer. 337.Pp 338When 339.Fa name 340is a dotted-decimal IPv4 address and 341.Fa af 342equals 343.Dv AF_INET6 , 344and 345.Dv AI_V4MAPPED 346is specified, 347an IPv4-mapped IPv6 address is returned: 348.Li h_name 349points to an IPv6 hex address containing the IPv4-mapped IPv6 address, 350.Li h_aliases 351is a 352.Dv NULL 353pointer, 354.Li h_addrtype 355is 356.Dv AF_INET6 , 357.Li h_length 358is 16, 359.Li h_addr_list[0] 360is a pointer to the 16-byte binary address, and 361.Li h_addr_list[1] 362is a 363.Dv NULL 364pointer. 365.Pp 366It is an error when 367.Fa name 368is an IPv6 hex address and 369.Fa af 370equals 371.Dv AF_INET . 372The function's return value is a 373.Dv NULL 374pointer and the value pointed to by 375.Fa error_num 376equals 377.Dv HOST_NOT_FOUND . 378.Pp 379The 380.Fn getipnodebyaddr 381function 382takes almost the same argument as 383.Xr gethostbyaddr 3 , 384but adds a pointer to return an error number. 385Additionally it takes care of IPv4-mapped IPv6 addresses, 386and IPv4-compatible IPv6 addresses. 387.Pp 388The 389.Fn getipnodebyname 390and 391.Fn getipnodebyaddr 392functions 393dynamically allocate the structure to be returned to the caller. 394The 395.Fn freehostent 396function 397reclaims memory region allocated and returned by 398.Fn getipnodebyname 399or 400.Fn getipnodebyaddr . 401.\" 402.Sh FILES 403.Bl -tag -width /etc/nsswitch.conf -compact 404.It Pa /etc/hosts 405.It Pa /etc/nsswitch.conf 406.It Pa /etc/resolv.conf 407.El 408.\" 409.Sh DIAGNOSTICS 410The 411.Fn getipnodebyname 412and 413.Fn getipnodebyaddr 414functions 415returns 416.Dv NULL 417on errors. 418The integer values pointed to by 419.Fa error_num 420may then be checked to see whether this is a temporary failure 421or an invalid or unknown host. 422The meanings of each error code are described in 423.Xr gethostbyname 3 . 424.\" 425.Sh SEE ALSO 426.Xr gethostbyaddr 3 , 427.Xr gethostbyname 3 , 428.Xr hosts 5 , 429.Xr nsswitch.conf 5 , 430.Xr services 5 , 431.Xr hostname 7 , 432.Xr named 8 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 HISTORY 445The implementation first appeared in KAME advanced networking kit. 446.\" 447.Sh STANDARDS 448The 449.Fn getipnodebyname 450and 451.Fn getipnodebyaddr 452functions 453are documented in 454.Dq Basic Socket Interface Extensions for IPv6 455(RFC2553). 456.\" 457.Sh BUGS 458Although the current implementation is otherwise thread-safe, using 459it in conjunction with 460.Fn gethostby* 461(see 462.Xr gethostbyname 3 ) 463or 464.Xr yp 8 465breaks the thread-safety of both. 466.Pp 467The 468.Fn getipnodebyname 469and 470.Fn getipnodebyaddr 471functions 472do not handle scoped IPv6 address properly. 473If you use these functions, 474your program will not be able to handle scoped IPv6 addresses. 475For IPv6 address manipulation, 476.Fn getaddrinfo 3 477and 478.Fn getnameinfo 3 479are recommended. 480.Pp 481The text was shamelessly copied from RFC2553. 482