xref: /dragonfly/lib/libc/net/getipnodebyname.3 (revision 63ab6604) 
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.4 2007/11/23 23:16:36 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/nsswitch.conf -compact
398.It Pa /etc/hosts
399.It Pa /etc/nsswitch.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 nsswitch.conf 5 ,
422.Xr services 5 ,
423.Xr hostname 7 ,
424.Xr named 8
425.Pp
426.Rs
427.%A R. Gilligan
428.%A S. Thomson
429.%A J. Bound
430.%A W. Stevens
431.%T Basic Socket Interface Extensions for IPv6
432.%R RFC 2553
433.%D March 1999
434.Re
435.\"
436.Sh STANDARDS
437.Fn getipnodebyname
438and
439.Fn getipnodebyaddr
440are documented in
441.Dq Basic Socket Interface Extensions for IPv6
442(RFC 2553).
443.\"
444.Sh HISTORY
445The implementation first appeared in KAME advanced networking kit.
446.\"
447.Sh BUGS
448.Fn getipnodebyname
449and
450.Fn getipnodebyaddr
451do not handle scoped IPv6 address properly.
452If you use these functions,
453your program will not be able to handle scoped IPv6 addresses.
454For IPv6 address manipulation,
455.Fn getaddrinfo 3
456and
457.Fn getnameinfo 3
458are recommended.
459.Pp
460The current implementation is not thread-safe.
461.Pp
462The text was shamelessly copied from RFC 2553.
463