1 .\" $KAME: getipnodebyname.3,v 1.6 2000/08/09 21:16:17 itojun Exp $
3 .\" Copyright (c) 1983, 1987, 1991, 1993
4 .\" The Regents of the University of California. All rights reserved.
6 .\" Redistribution and use in source and binary forms, with or without
7 .\" modification, are permitted provided that the following conditions
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.
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
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 $
42 .Nd nodename-to-address and address-to-nodename translation
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"
55 .Fn freehostent "struct hostent *ptr"
62 functions are very similar to
67 The functions cover all the functionalities provided by the older ones,
68 and provide better interface to programmers.
69 The functions require additional arguments,
73 for specifying address family and operation mode.
74 The additional arguments allow programmer to get address for a nodename,
75 for specific address family
80 The functions also require an additional pointer argument,
82 to return the appropriate error code,
83 to support thread safe error code returns.
85 The type and usage of the return value,
94 argument can be either a node name or a numeric address
96 (i.e., a dotted-decimal IPv4 address or an IPv6 hex address).
99 argument specifies the address family, either
105 argument specifies the types of addresses that are searched for,
106 and the types of addresses that are returned.
107 We note that a special flags value of
110 should handle most applications.
111 That is, porting simple applications to use IPv6 replaces the call
113 hptr = gethostbyname(name);
118 hptr = getipnodebyname(name, AF_INET6, AI_DEFAULT, &error_num);
121 Applications desiring finer control over the types of addresses
122 searched for and returned, can specify other combinations of the
130 implies a strict interpretation of the
141 then the caller wants only IPv4 addresses.
145 If successful, the IPv4 addresses are returned and the
149 structure will be 4, else the function returns a
159 then the caller wants only IPv6 addresses.
163 If successful, the IPv6 addresses are returned and the
167 structure will be 16, else the function returns a
172 Other constants can be logically-ORed into the
174 argument, to modify the behavior of the function.
179 flag is specified along with an
183 then the caller will accept IPv4-mapped IPv6 addresses.
186 records are found then a query is made for
188 records and any found are returned as IPv4-mapped IPv6 addresses
193 flag is ignored unless
200 flag is exact same as the
202 flag only if the kernel supports IPv4-mapped IPv6 address.
206 flag is used in conjunction with the
208 flag, and only used with the IPv6 address family.
211 is logically or'd with
213 flag then the caller wants all addresses: IPv6 and IPv4-mapped IPv6.
214 A query is first made for
216 records and if successful, the
217 IPv6 addresses are returned.
218 Another query is then made for
220 records and any found are returned as IPv4-mapped IPv6 addresses.
223 Only if both queries fail does the function
227 This flag is ignored unless af equals
239 flag specifies that a query for
242 should occur only if the node has at least one IPv6 source
243 address configured and a query for
245 records should occur only if the node has at least one IPv4 source address
248 For example, if the node has no IPv6 source addresses configured,
251 equals AF_INET6, and the node name being looked up has both
259 specified, the function returns a
268 records are returned as IPv4-mapped IPv6 addresses;
271 The special flags value of
275 #define AI_DEFAULT (AI_V4MAPPED_CFG | AI_ADDRCONFIG)
280 function must allow the
282 argument to be either a node name or a literal address string
283 (i.e., a dotted-decimal IPv4 address or an IPv6 hex address).
284 This saves applications from having to call
286 to handle literal address strings.
289 argument is a literal address string,
292 argument is always ignored.
294 There are four scenarios based on the type of literal address string
298 The two simple cases are when
300 is a dotted-decimal IPv4 address and
306 is an IPv6 hex address and
311 returned hostent structure are:
313 points to a copy of the
332 is a pointer to the 4-byte or 16-byte binary address,
341 is a dotted-decimal IPv4 address and
348 an IPv4-mapped IPv6 address is returned:
350 points to an IPv6 hex address containing the IPv4-mapped IPv6 address,
361 is a pointer to the 16-byte binary address, and
369 is an IPv6 hex address and
373 The function's return value is a
375 pointer and the value pointed to by
383 takes almost the same argument as
384 .Xr gethostbyaddr 3 ,
385 but adds a pointer to return an error number.
386 Additionally it takes care of IPv4-mapped IPv6 addresses,
387 and IPv4-compatible IPv6 addresses.
394 dynamically allocate the structure to be returned to the caller.
398 reclaims memory region allocated and returned by
401 .Fn getipnodebyaddr .
404 .Bl -tag -width /etc/nsswitch.conf -compact
406 .It Pa /etc/nsswitch.conf
407 .It Pa /etc/resolv.conf
419 The integer values pointed to by
421 may then be checked to see whether this is a temporary failure
422 or an invalid or unknown host.
423 The meanings of each error code are described in
424 .Xr gethostbyname 3 .
428 .Xr gethostbyaddr 3 ,
429 .Xr gethostbyname 3 ,
432 .Xr nsswitch.conf 5 ,
441 .%T Basic Socket Interface Extensions for IPv6
453 .Dq Basic Socket Interface Extensions for IPv6
457 The implementation first appeared in KAME advanced networking kit.
465 do not handle scoped IPv6 address properly.
466 If you use these functions,
467 your program will not be able to handle scoped IPv6 addresses.
468 For IPv6 address manipulation,
474 The text was shamelessly copied from RFC 2553.