xref: /dragonfly/lib/libc/net/getipnodebyname.3 (revision 73610d44) 
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. 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.
17.\"
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
28.\" SUCH DAMAGE.
29.\"
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.\"
33.Dd August 6, 2004
34.Dt GETIPNODEBYNAME 3
35.Os
36.\"
37.Sh NAME
38.Nm getipnodebyname ,
39.Nm getipnodebyaddr ,
40.Nm freehostent
41.Nd nodename-to-address and address-to-nodename translation
42.\"
43.Sh LIBRARY
44.Lb libc
45.Sh SYNOPSIS
46.In sys/types.h
47.In sys/socket.h
48.In netdb.h
49.Ft "struct hostent *"
50.Fn getipnodebyname "const char *name" "int af" "int flags" "int *error_num"
51.Ft "struct hostent *"
52.Fn getipnodebyaddr "const void *src" "size_t len" "int af" "int *error_num"
53.Ft void
54.Fn freehostent "struct hostent *ptr"
55.\"
56.Sh DESCRIPTION
57The
58.Fn getipnodebyname
59and
60.Fn getipnodebyaddr
61functions are very similar to
62.Xr gethostbyname 3 ,
63.Xr gethostbyname2 3
64and
65.Xr gethostbyaddr 3 .
66The functions cover all the functionalities provided by the older ones,
67and provide better interface to programmers.
68The functions require additional arguments,
69.Fa af ,
70and
71.Fa flags ,
72for specifying address family and operation mode.
73The additional arguments allow programmer to get address for a nodename,
74for specific address family
75(such as
76.Dv AF_INET
77or
78.Dv AF_INET6 ) .
79The functions also require an additional pointer argument,
80.Fa error_num
81to return the appropriate error code,
82to support thread safe error code returns.
83.Pp
84The type and usage of the return value,
85.Li "struct hostent"
86is described in
87.Xr gethostbyname 3 .
88.Pp
89For
90.Fn getipnodebyname ,
91the
92.Fa name
93argument can be either a node name or a numeric address
94string
95(i.e., a dotted-decimal IPv4 address or an IPv6 hex address).
96The
97.Fa af
98argument specifies the address family, either
99.Dv AF_INET
100or
101.Dv AF_INET6 .
102The
103.Fa flags
104argument specifies the types of addresses that are searched for,
105and the types of addresses that are returned.
106We note that a special flags value of
107.Dv AI_DEFAULT
108(defined below)
109should handle most applications.
110That is, porting simple applications to use IPv6 replaces the call
111.Bd -literal
112   hptr = gethostbyname(name);
113.Ed
114.Pp
115with
116.Bd -literal
117   hptr = getipnodebyname(name, AF_INET6, AI_DEFAULT, &error_num);
118.Ed
119.Pp
120Applications desiring finer control over the types of addresses
121searched for and returned, can specify other combinations of the
122.Fa flags
123argument.
124.Pp
125A
126.Fa flags
127of
128.Li 0
129implies a strict interpretation of the
130.Fa af
131argument:
132.Bl -bullet
133.It
134If
135.Fa flags
136is 0 and
137.Fa af
138is
139.Dv AF_INET ,
140then the caller wants only IPv4 addresses.
141A query is made for
142.Li A
143records.
144If successful, the IPv4 addresses are returned and the
145.Li h_length
146member of the
147.Li hostent
148structure will be 4, else the function returns a
149.Dv NULL
150pointer.
151.It
152If
153.Fa flags
154is 0 and if
155.Fa af
156is
157.Li AF_INET6 ,
158then the caller wants only IPv6 addresses.
159A query is made for
160.Li AAAA
161records.
162If successful, the IPv6 addresses are returned and the
163.Li h_length
164member of the
165.Li hostent
166structure will be 16, else the function returns a
167.Dv NULL
168pointer.
169.El
170.Pp
171Other constants can be logically-ORed into the
172.Fa flags
173argument, to modify the behavior of the function.
174.Bl -bullet
175.It
176If the
177.Dv AI_V4MAPPED
178flag is specified along with an
179.Fa af
180of
181.Dv AF_INET6 ,
182then the caller will accept IPv4-mapped IPv6 addresses.
183That is, if no
184.Li AAAA
185records are found then a query is made for
186.Li A
187records and any found are returned as IPv4-mapped IPv6 addresses
188.Li ( h_length
189will be 16).
190The
191.Dv AI_V4MAPPED
192flag is ignored unless
193.Fa af
194equals
195.Dv AF_INET6 .
196.It
197The
198.Dv AI_V4MAPPED_CFG
199flag is exact same as the
200.Dv AI_V4MAPPED
201flag only if the kernel supports IPv4-mapped IPv6 address.
202.It
203If the
204.Dv AI_ALL
205flag is used in conjunction with the
206.Dv AI_V4MAPPED
207flag, and only used with the IPv6 address family.
208When
209.Dv AI_ALL
210is logically or'd with
211.Dv AI_V4MAPPED
212flag then the caller wants all addresses: IPv6 and IPv4-mapped IPv6.
213A query is first made for
214.Li AAAA
215records and if successful, the
216IPv6 addresses are returned.
217Another query is then made for
218.Li A
219records and any found are returned as IPv4-mapped IPv6 addresses.
220.Li h_length
221will be 16.
222Only if both queries fail does the function
223return a
224.Dv NULL
225pointer.
226This flag is ignored unless af equals
227AF_INET6.
228If 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.Fa 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
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.Fa 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.Fa name
288argument is a literal address string,
289the
290.Fa 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.Fa af
296argument.
297The two simple cases are when
298.Fa name
299is a dotted-decimal IPv4 address and
300.Fa af
301equals
302.Dv AF_INET ,
303or when
304.Fa name
305is an IPv6 hex address and
306.Fa 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.Fa name
314argument,
315.Li h_aliases
316is a
317.Dv NULL
318pointer,
319.Li h_addrtype
320is a copy of the
321.Fa 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.Fa name
340is a dotted-decimal IPv4 address and
341.Fa 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.Fa name
368is an IPv6 hex address and
369.Fa af
370equals
371.Dv AF_INET .
372The function's return value is a
373.Dv NULL
374pointer and the value pointed to by
375.Fa error_num
376equals
377.Dv HOST_NOT_FOUND .
378.Pp
379The
380.Fn getipnodebyaddr
381function
382takes almost the same argument as
383.Xr gethostbyaddr 3 ,
384but adds a pointer to return an error number.
385Additionally it takes care of IPv4-mapped IPv6 addresses,
386and IPv4-compatible IPv6 addresses.
387.Pp
388The
389.Fn getipnodebyname
390and
391.Fn getipnodebyaddr
392functions
393dynamically allocate the structure to be returned to the caller.
394The
395.Fn freehostent
396function
397reclaims memory region allocated and returned by
398.Fn getipnodebyname
399or
400.Fn getipnodebyaddr .
401.\"
402.Sh FILES
403.Bl -tag -width /etc/nsswitch.conf -compact
404.It Pa /etc/hosts
405.It Pa /etc/nsswitch.conf
406.It Pa /etc/resolv.conf
407.El
408.\"
409.Sh DIAGNOSTICS
410The
411.Fn getipnodebyname
412and
413.Fn getipnodebyaddr
414functions
415returns
416.Dv NULL
417on errors.
418The integer values pointed to by
419.Fa error_num
420may then be checked to see whether this is a temporary failure
421or an invalid or unknown host.
422The meanings of each error code are described in
423.Xr gethostbyname 3 .
424.\"
425.Sh SEE ALSO
426.Xr getaddrinfo 3 ,
427.Xr gethostbyaddr 3 ,
428.Xr gethostbyname 3 ,
429.Xr getnameinfo 3 ,
430.Xr hosts 5 ,
431.Xr nsswitch.conf 5 ,
432.Xr services 5 ,
433.Xr hostname 7 ,
434.Xr named 8
435.Rs
436.%A R. Gilligan
437.%A S. Thomson
438.%A J. Bound
439.%A W. Stevens
440.%T Basic Socket Interface Extensions for IPv6
441.%R RFC 2553
442.%D March 1999
443.Re
444.\"
445.Sh STANDARDS
446The
447.Fn getipnodebyname
448and
449.Fn getipnodebyaddr
450functions
451are documented in
452.Dq Basic Socket Interface Extensions for IPv6
453(RFC 2553).
454.\"
455.Sh HISTORY
456The implementation first appeared in KAME advanced networking kit.
457.\"
458.Sh BUGS
459The
460.Fn getipnodebyname
461and
462.Fn getipnodebyaddr
463functions
464do not handle scoped IPv6 address properly.
465If you use these functions,
466your program will not be able to handle scoped IPv6 addresses.
467For IPv6 address manipulation,
468.Fn getaddrinfo 3
469and
470.Fn getnameinfo 3
471are recommended.
472.Pp
473The text was shamelessly copied from RFC 2553.
474