1.\" $FreeBSD: src/lib/libc/net/getipnodebyname.3,v 1.2.2.4 2001/12/14 18:33:55 ru Exp $ 2.\" $DragonFly: src/lib/libc/net/getipnodebyname.3,v 1.3 2006/02/17 19:35:06 swildner Exp $ 3.\" $KAME: getipnodebyname.3,v 1.6 2000/08/09 21:16:17 itojun Exp $ 4.\" 5.\" Copyright (c) 1983, 1987, 1991, 1993 6.\" The Regents of the University of California. All rights reserved. 7.\" 8.\" Redistribution and use in source and binary forms, with or without 9.\" modification, are permitted provided that the following conditions 10.\" are met: 11.\" 1. Redistributions of source code must retain the above copyright 12.\" notice, this list of conditions and the following disclaimer. 13.\" 2. Redistributions in binary form must reproduce the above copyright 14.\" notice, this list of conditions and the following disclaimer in the 15.\" documentation and/or other materials provided with the distribution. 16.\" 3. All advertising materials mentioning features or use of this software 17.\" must display the following acknowledgement: 18.\" This product includes software developed by the University of 19.\" California, Berkeley and its contributors. 20.\" 4. Neither the name of the University nor the names of its contributors 21.\" may be used to endorse or promote products derived from this software 22.\" without specific prior written permission. 23.\" 24.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 25.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 26.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 27.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 28.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 29.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 30.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 31.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 32.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 33.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 34.\" SUCH DAMAGE. 35.\" 36.\" From: @(#)gethostbyname.3 8.4 (Berkeley) 5/25/95 37.\" 38.Dd May 25, 1995 39.Dt GETIPNODEBYNAME 3 40.Os 41.\" 42.Sh NAME 43.Nm getipnodebyname , 44.Nm getipnodebyaddr , 45.Nm freehostent 46.Nd nodename-to-address and address-to-nodename translation 47.\" 48.Sh LIBRARY 49.Lb libc 50.Sh SYNOPSIS 51.In sys/types.h 52.In sys/socket.h 53.In netdb.h 54.Ft "struct hostent *" 55.Fn getipnodebyname "const char *name" "int af" "int flags" "int *error_num" 56.Ft "struct hostent *" 57.Fn getipnodebyaddr "const void *src" "size_t len" "int af" "int *error_num" 58.Ft void 59.Fn freehostent "struct hostent *ptr" 60.\" 61.Sh DESCRIPTION 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.Ar af , 74and 75.Ar 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.Ar 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.Ar 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.Ar af 102argument specifies the address family, either 103.Dv AF_INET 104or 105.Dv AF_INET6 . 106The 107.Ar 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.Ar flags 127argument. 128.Pp 129A 130.Ar flags 131of 132.Li 0 133implies a strict interpretation of the 134.Ar af 135argument: 136.Bl -bullet 137.It 138If 139.Ar flags 140is 0 and 141.Ar 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.Ar flags 158is 0 and if 159.Ar 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.Ar 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.Ar 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.Ar 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.Ar 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.Ar 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.Ar name 288argument is a literal address string, 289the 290.Ar 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.Ar af 296argument. 297The two simple cases are when 298.Ar name 299is a dotted-decimal IPv4 address and 300.Ar af 301equals 302.Dv AF_INET , 303or when 304.Ar name 305is an IPv6 hex address and 306.Ar 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.Ar name 314argument, 315.Li h_aliases 316is a 317.Dv NULL 318pointer, 319.Li h_addrtype 320is a copy of the 321.Ar 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.Ar name 340is a dotted-decimal IPv4 address and 341.Ar 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.Ar name 368is an IPv6 hex address and 369.Ar af 370equals 371.Dv AF_INET . 372The function's return value is a 373.Dv NULL 374pointer and the value pointed to by 375.Ar error_num 376equals 377.Dv HOST_NOT_FOUND . 378.Pp 379.Fn getipnodebyaddr 380takes almost the same argument as 381.Xr gethostbyaddr 3 , 382but adds a pointer to return an error number. 383Additionally it takes care of IPv4-mapped IPv6 addresses, 384and IPv4-compatible IPv6 addresses. 385.Pp 386.Fn getipnodebyname 387and 388.Fn getipnodebyaddr 389dynamically allocate the structure to be returned to the caller. 390.Fn freehostent 391reclaims memory region allocated and returned by 392.Fn getipnodebyname 393or 394.Fn getipnodebyaddr . 395.\" 396.Sh FILES 397.Bl -tag -width /etc/resolv.conf -compact 398.It Pa /etc/hosts 399.It Pa /etc/host.conf 400.It Pa /etc/resolv.conf 401.El 402.\" 403.Sh DIAGNOSTICS 404.Fn getipnodebyname 405and 406.Fn getipnodebyaddr 407returns 408.Dv NULL 409on errors. 410The integer values pointed to by 411.Ar error_num 412may then be checked to see whether this is a temporary failure 413or an invalid or unknown host. 414The meanings of each error code are described in 415.Xr gethostbyname 3 . 416.\" 417.Sh SEE ALSO 418.Xr gethostbyaddr 3 , 419.Xr gethostbyname 3 , 420.Xr hosts 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 STANDARDS 436.Fn getipnodebyname 437and 438.Fn getipnodebyaddr 439are documented in 440.Dq Basic Socket Interface Extensions for IPv6 441(RFC2553). 442.\" 443.Sh HISTORY 444The implementation first appeared in KAME advanced networking kit. 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