xref: /dragonfly/lib/libc/net/getipnodebyname.3 (revision bbb35c81) 
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 May 5, 2019
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.Dv 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
227.Fa af
228equals
229.Dv AF_INET6 .
230If both
231.Dv AI_ALL
232and
233.Dv AI_V4MAPPED
234are specified,
235.Dv AI_ALL
236takes precedence.
237.It
238The
239.Dv AI_ADDRCONFIG
240flag specifies that a query for
241.Li AAAA
242records
243should occur only if the node has at least one IPv6 source
244address configured and a query for
245.Li A
246records should occur only if the node has at least one IPv4 source address
247configured.
248.Pp
249For example, if the node has no IPv6 source addresses configured,
250and
251.Fa af
252equals
253.Dv AF_INET6 ,
254and 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
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 RETURN VALUES
407The
408.Fn getipnodebyname
409and
410.Fn getipnodebyaddr
411functions
412returns
413.Dv NULL
414on errors.
415The integer values pointed to by
416.Fa error_num
417may then be checked to see whether this is a temporary failure
418or an invalid or unknown host.
419The meanings of each error code are described in
420.Xr gethostbyname 3 .
421.\"
422.Sh FILES
423.Bl -tag -width /etc/nsswitch.conf -compact
424.It Pa /etc/hosts
425.It Pa /etc/nsswitch.conf
426.It Pa /etc/resolv.conf
427.El
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.Rs
440.%A R. Gilligan
441.%A S. Thomson
442.%A J. Bound
443.%A W. Stevens
444.%T Basic Socket Interface Extensions for IPv6
445.%R RFC 2553
446.%D March 1999
447.Re
448.\"
449.Sh STANDARDS
450The
451.Fn getipnodebyname
452and
453.Fn getipnodebyaddr
454functions
455are documented in
456.Dq Basic Socket Interface Extensions for IPv6
457(RFC 2553).
458.\"
459.Sh HISTORY
460The implementation first appeared in KAME advanced networking kit.
461.\"
462.Sh BUGS
463The
464.Fn getipnodebyname
465and
466.Fn getipnodebyaddr
467functions
468do not handle scoped IPv6 address properly.
469If you use these functions,
470your program will not be able to handle scoped IPv6 addresses.
471For IPv6 address manipulation,
472.Fn getaddrinfo 3
473and
474.Fn getnameinfo 3
475are recommended.
476.Pp
477The text was shamelessly copied from RFC 2553.
478