1 .\" Copyright (c) 1983, 1987, 1991, 1993
2 .\" The Regents of the University of California. All rights reserved.
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
7 .\" 1. Redistributions of source code must retain the above copyright
8 .\" notice, this list of conditions and the following disclaimer.
9 .\" 2. Redistributions in binary form must reproduce the above copyright
10 .\" notice, this list of conditions and the following disclaimer in the
11 .\" documentation and/or other materials provided with the distribution.
12 .\" 3. All advertising materials mentioning features or use of this software
13 .\" must display the following acknowledgement:
14 .\" This product includes software developed by the University of
15 .\" California, Berkeley and its contributors.
16 .\" 4. Neither the name of the University nor the names of its contributors
17 .\" may be used to endorse or promote products derived from this software
18 .\" without specific prior written permission.
20 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
21 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
22 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
23 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
24 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
25 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
26 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
27 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
28 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
29 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
32 .\" From: @(#)gethostbyname.3 8.4 (Berkeley) 5/25/95
33 .\" $Id: getipnodebyname.3,v 1.2 1999/09/13 16:04:51 itojun Exp $
44 .Nd nodename-to-address and address-to-nodename translation
47 .Fd #include <sys/types.h>
48 .Fd #include <sys/socket.h>
49 .Fd #include <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"
55 .Fn freehostent "struct hostent *ptr"
61 functions are very similar to
66 The functions cover all the functionalities provided by the older ones,
67 and provide better interface to programmers.
68 The functions require additional arguments,
72 for specifying address family and operation mode.
73 The additional arguments allow programmer to get address for a nodename,
74 for specific address family
81 The functions also require an additional pointer argument,
83 to return the appropriate error code,
84 to support thread safe error code returns.
86 The type and usage of the return value,
95 argument can be either a node name or a numeric address
98 i.e., a dotted-decimal IPv4 address or an IPv6 hex address
102 argument specifies the address family, either
108 argument specifies the types of addresses that are searched for,
109 and the types of addresses that are returned.
110 We note that a special flags value of
113 should handle most applications.
114 That is, porting simple applications to use IPv6 replaces the call
116 hptr = gethostbyname(name);
121 hptr = getipnodebyname(name, AF_INET6, AI_DEFAULT, &error_num);
124 Applications desiring finer control over the types of addresses
125 searched for and returned, can specify other combinations of the
133 implies a strict interpretation of the
144 then the caller wants only IPv4 addresses.
148 If successful, the IPv4 addresses are returned and the
152 structure will be 4, else the function returns a
162 then the caller wants only IPv6 addresses.
166 If successful, the IPv6 addresses are returned and the
170 structure will be 16, else the function returns a
175 Other constants can be logically-ORed into the
177 argument, to modify the behavior of the function.
182 flag is specified along with an
186 then the caller will accept IPv4-mapped IPv6 addresses.
189 records are found then a query is made for
191 records and any found are returned as IPv4-mapped IPv6 addresses
198 flag is ignored unless
205 flag is exact same as the
207 flag only if the kernel supports IPv4-mapped IPv6 address.
211 flag is used in conjunction with the
213 flag, and only used with the IPv6 address family.
216 is logically or'd with
218 flag then the caller wants all addresses: IPv6 and IPv4-mapped IPv6.
219 A query is first made for
221 records and if successful, the
222 IPv6 addresses are returned. Another query is then made for
224 records and any found are returned as IPv4-mapped IPv6 addresses.
226 will be 16. Only if both queries fail does the function
229 pointer. This flag is ignored unless af equals
240 flag specifies that a query for
243 should occur only if the node has at least one IPv6 source
244 address configured and a query for
246 records should occur only if the node has at least one IPv4 source address
249 For example, if the node has no IPv6 source addresses configured,
252 equals AF_INET6, and the node name being looked up has both
260 specified, the function returns a
269 records are returned as IPv4-mapped IPv6 addresses;
272 The special flags value of
276 #define AI_DEFAULT (AI_V4MAPPED_CFG | AI_ADDRCONFIG)
281 function must allow the
283 argument to be either a node name or a literal address string
285 i.e., a dotted-decimal IPv4 address or an IPv6 hex address
287 This saves applications from having to call
289 to handle literal address strings.
292 argument is a literal address string,
295 argument is always ignored.
297 There are four scenarios based on the type of literal address string
301 The two simple cases are when
303 is a dotted-decimal IPv4 address and
309 is an IPv6 hex address and
314 returned hostent structure are:
316 points to a copy of the
339 is a pointer to the 4-byte or 16-byte binary address,
348 is a dotted-decimal IPv4 address and
355 an IPv4-mapped IPv6 address is returned:
357 points to an IPv6 hex address containing the IPv4-mapped IPv6 address,
368 is a pointer to the 16-byte binary address, and
376 is an IPv6 hex address and
380 The function's return value is a
382 pointer and the value pointed to by
388 takes almost the same argument as
389 .Xr gethostbyaddr 3 ,
390 but adds a pointer to return an error number.
391 Additionally it takes care of IPv4-mapped IPv6 addresses,
392 and IPv4-compatible IPv6 addresses.
397 dynamically allocate the structure to be returned to the caller.
399 reclaims memory region allocated and returned by
402 .Fn getipnodebyaddr .
405 .Bl -tag -width /etc/resolv.conf -compact
407 .It Pa /etc/host.conf
408 .It Pa /etc/resolv.conf
418 The integer values pointed to by
420 may then be checked to see whether this is a temporary failure
421 or an invalid or unknown host.
422 The meanings of each error code are described in
423 .Xr gethostbyname 3 .
426 .Xr gethostbyname 3 ,
427 .Xr gethostbyaddr 3 ,
433 R. Gilligan, S. Thomson, J. Bound, and W. Stevens,
434 ``Basic Socket Interface Extensions for IPv6,'' RFC2553, March 1999.
437 The implementation first appeared in KAME advanced networking kit.
443 are documented in ``Basic Socket Interface Extensions for IPv6''
447 The text was shamelessly copied from RFC2553.