xref: /freebsd/lib/libc/net/getipnodebyname.3 (revision 87569f75a91f298c52a71823c04d41cf53c88889) 
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 August 6, 2004
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.
221Another query is then made for
222.Li A
223records and any found are returned as IPv4-mapped IPv6 addresses.
224.Li h_length
225will be 16.
226Only if both queries fail does the function
227return a
228.Dv NULL
229pointer.
230This flag is ignored unless af equals
231AF_INET6.
232If both
233.Dv AI_ALL
234and
235.Dv AI_V4MAPPED
236are specified,
237.Dv AI_ALL
238takes precedence.
239.It
240The
241.Dv AI_ADDRCONFIG
242flag specifies that a query for
243.Li AAAA
244records
245should occur only if the node has at least one IPv6 source
246address configured and a query for
247.Li A
248records should occur only if the node has at least one IPv4 source address
249configured.
250.Pp
251For example, if the node has no IPv6 source addresses configured,
252and
253.Fa af
254equals AF_INET6, and the node name being looked up has both
255.Li AAAA
256and
257.Li A
258records, then:
259(a) if only
260.Dv AI_ADDRCONFIG
261is
262specified, the function returns a
263.Dv NULL
264pointer;
265(b) if
266.Dv AI_ADDRCONFIG
267|
268.Dv AI_V4MAPPED
269is specified, the
270.Li A
271records are returned as IPv4-mapped IPv6 addresses;
272.El
273.Pp
274The special flags value of
275.Dv AI_DEFAULT
276is defined as
277.Bd -literal -offset
278   #define  AI_DEFAULT  (AI_V4MAPPED_CFG | AI_ADDRCONFIG)
279.Ed
280.Pp
281We noted that the
282.Fn getipnodebyname
283function must allow the
284.Fa name
285argument to be either a node name or a literal address string
286(i.e., a dotted-decimal IPv4 address or an IPv6 hex address).
287This saves applications from having to call
288.Xr inet_pton 3
289to handle literal address strings.
290When the
291.Fa name
292argument is a literal address string,
293the
294.Fa flags
295argument is always ignored.
296.Pp
297There are four scenarios based on the type of literal address string
298and the value of the
299.Fa af
300argument.
301The two simple cases are when
302.Fa name
303is a dotted-decimal IPv4 address and
304.Fa af
305equals
306.Dv AF_INET ,
307or when
308.Fa name
309is an IPv6 hex address and
310.Fa af
311equals
312.Dv AF_INET6 .
313The members of the
314returned hostent structure are:
315.Li h_name
316points to a copy of the
317.Fa name
318argument,
319.Li h_aliases
320is a
321.Dv NULL
322pointer,
323.Li h_addrtype
324is a copy of the
325.Fa af
326argument,
327.Li h_length
328is either 4
329(for
330.Dv AF_INET )
331or 16
332(for
333.Dv AF_INET6 ) ,
334.Li h_addr_list[0]
335is a pointer to the 4-byte or 16-byte binary address,
336and
337.Li h_addr_list[1]
338is a
339.Dv NULL
340pointer.
341.Pp
342When
343.Fa name
344is a dotted-decimal IPv4 address and
345.Fa af
346equals
347.Dv AF_INET6 ,
348and
349.Dv AI_V4MAPPED
350is specified,
351an IPv4-mapped IPv6 address is returned:
352.Li h_name
353points to an IPv6 hex address containing the IPv4-mapped IPv6 address,
354.Li h_aliases
355is a
356.Dv NULL
357pointer,
358.Li h_addrtype
359is
360.Dv AF_INET6 ,
361.Li h_length
362is 16,
363.Li h_addr_list[0]
364is a pointer to the 16-byte binary address, and
365.Li h_addr_list[1]
366is a
367.Dv NULL
368pointer.
369.Pp
370It is an error when
371.Fa name
372is an IPv6 hex address and
373.Fa af
374equals
375.Dv AF_INET .
376The function's return value is a
377.Dv NULL
378pointer and the value pointed to by
379.Fa error_num
380equals
381.Dv HOST_NOT_FOUND .
382.Pp
383The
384.Fn getipnodebyaddr
385function
386takes almost the same argument as
387.Xr gethostbyaddr 3 ,
388but adds a pointer to return an error number.
389Additionally it takes care of IPv4-mapped IPv6 addresses,
390and IPv4-compatible IPv6 addresses.
391.Pp
392The
393.Fn getipnodebyname
394and
395.Fn getipnodebyaddr
396functions
397dynamically allocate the structure to be returned to the caller.
398The
399.Fn freehostent
400function
401reclaims memory region allocated and returned by
402.Fn getipnodebyname
403or
404.Fn getipnodebyaddr .
405.\"
406.Sh FILES
407.Bl -tag -width /etc/nsswitch.conf -compact
408.It Pa /etc/hosts
409.It Pa /etc/nsswitch.conf
410.It Pa /etc/resolv.conf
411.El
412.\"
413.Sh DIAGNOSTICS
414The
415.Fn getipnodebyname
416and
417.Fn getipnodebyaddr
418functions
419returns
420.Dv NULL
421on errors.
422The integer values pointed to by
423.Fa error_num
424may then be checked to see whether this is a temporary failure
425or an invalid or unknown host.
426The meanings of each error code are described in
427.Xr gethostbyname 3 .
428.\"
429.Sh SEE ALSO
430.Xr getaddrinfo 3 ,
431.Xr gethostbyaddr 3 ,
432.Xr gethostbyname 3 ,
433.Xr getnameinfo 3 ,
434.Xr hosts 5 ,
435.Xr nsswitch.conf 5 ,
436.Xr services 5 ,
437.Xr hostname 7 ,
438.Xr named 8
439.Pp
440.Rs
441.%A R. Gilligan
442.%A S. Thomson
443.%A J. Bound
444.%A W. Stevens
445.%T Basic Socket Interface Extensions for IPv6
446.%R RFC2553
447.%D March 1999
448.Re
449.\"
450.Sh STANDARDS
451The
452.Fn getipnodebyname
453and
454.Fn getipnodebyaddr
455functions
456are documented in
457.Dq Basic Socket Interface Extensions for IPv6
458(RFC2553).
459.\"
460.Sh HISTORY
461The implementation first appeared in KAME advanced networking kit.
462.\"
463.Sh BUGS
464The
465.Fn getipnodebyname
466and
467.Fn getipnodebyaddr
468functions
469do not handle scoped IPv6 address properly.
470If you use these functions,
471your program will not be able to handle scoped IPv6 addresses.
472For IPv6 address manipulation,
473.Fn getaddrinfo 3
474and
475.Fn getnameinfo 3
476are recommended.
477.Pp
478The text was shamelessly copied from RFC2553.
479