d9b4c6910f26d3dcce5246e177c81f52b8c949c2
[dragonfly.git] / lib / libc / net / getipnodebyname.3
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 .\" 4. 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 .\" $DragonFly: src/lib/libc/net/getipnodebyname.3,v 1.4 2007/11/23 23:16:36 swildner Exp $
33 .\"
34 .Dd August 6, 2004
35 .Dt GETIPNODEBYNAME 3
36 .Os
37 .\"
38 .Sh NAME
39 .Nm getipnodebyname ,
40 .Nm getipnodebyaddr ,
41 .Nm freehostent
42 .Nd nodename-to-address and address-to-nodename translation
43 .\"
44 .Sh LIBRARY
45 .Lb libc
46 .Sh SYNOPSIS
47 .In sys/types.h
48 .In sys/socket.h
49 .In 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"
54 .Ft void
55 .Fn freehostent "struct hostent *ptr"
56 .\"
57 .Sh DESCRIPTION
58 The
59 .Fn getipnodebyname
60 and
61 .Fn getipnodebyaddr
62 functions are very similar to
63 .Xr gethostbyname 3 ,
64 .Xr gethostbyname2 3
65 and
66 .Xr gethostbyaddr 3 .
67 The functions cover all the functionalities provided by the older ones,
68 and provide better interface to programmers.
69 The functions require additional arguments,
70 .Fa af ,
71 and
72 .Fa flags ,
73 for specifying address family and operation mode.
74 The additional arguments allow programmer to get address for a nodename,
75 for specific address family
76 (such as
77 .Dv AF_INET
78 or
79 .Dv AF_INET6 ) .
80 The functions also require an additional pointer argument,
81 .Fa error_num
82 to return the appropriate error code,
83 to support thread safe error code returns.
84 .Pp
85 The type and usage of the return value,
86 .Li "struct hostent"
87 is described in
88 .Xr gethostbyname 3 .
89 .Pp
90 For
91 .Fn getipnodebyname ,
92 the
93 .Fa name
94 argument can be either a node name or a numeric address
95 string
96 (i.e., a dotted-decimal IPv4 address or an IPv6 hex address).
97 The
98 .Fa af
99 argument specifies the address family, either
100 .Dv AF_INET
101 or
102 .Dv AF_INET6 .
103 The
104 .Fa flags
105 argument specifies the types of addresses that are searched for,
106 and the types of addresses that are returned.
107 We note that a special flags value of
108 .Dv AI_DEFAULT
109 (defined below)
110 should handle most applications.
111 That is, porting simple applications to use IPv6 replaces the call
112 .Bd -literal -offset
113    hptr = gethostbyname(name);
114 .Ed
115 .Pp
116 with
117 .Bd -literal -offset
118    hptr = getipnodebyname(name, AF_INET6, AI_DEFAULT, &error_num);
119 .Ed
120 .Pp
121 Applications desiring finer control over the types of addresses
122 searched for and returned, can specify other combinations of the
123 .Fa flags
124 argument.
125 .Pp
126 A
127 .Fa flags
128 of
129 .Li 0
130 implies a strict interpretation of the
131 .Fa af
132 argument:
133 .Bl -bullet
134 .It
135 If
136 .Fa flags
137 is 0 and
138 .Fa af
139 is
140 .Dv AF_INET ,
141 then the caller wants only IPv4 addresses.
142 A query is made for
143 .Li A
144 records.
145 If successful, the IPv4 addresses are returned and the
146 .Li h_length
147 member of the
148 .Li hostent
149 structure will be 4, else the function returns a
150 .Dv NULL
151 pointer.
152 .It
153 If
154 .Fa flags
155 is 0 and if
156 .Fa af
157 is
158 .Li AF_INET6 ,
159 then the caller wants only IPv6 addresses.
160 A query is made for
161 .Li AAAA
162 records.
163 If successful, the IPv6 addresses are returned and the
164 .Li h_length
165 member of the
166 .Li hostent
167 structure will be 16, else the function returns a
168 .Dv NULL
169 pointer.
170 .El
171 .Pp
172 Other constants can be logically-ORed into the
173 .Fa flags
174 argument, to modify the behavior of the function.
175 .Bl -bullet
176 .It
177 If the
178 .Dv AI_V4MAPPED
179 flag is specified along with an
180 .Fa af
181 of
182 .Dv AF_INET6 ,
183 then the caller will accept IPv4-mapped IPv6 addresses.
184 That is, if no
185 .Li AAAA
186 records are found then a query is made for
187 .Li A
188 records and any found are returned as IPv4-mapped IPv6 addresses
189 .Li ( h_length
190 will be 16).
191 The
192 .Dv AI_V4MAPPED
193 flag is ignored unless
194 .Fa af
195 equals
196 .Dv AF_INET6 .
197 .It
198 The
199 .Dv AI_V4MAPPED_CFG
200 flag is exact same as the
201 .Dv AI_V4MAPPED
202 flag only if the kernel supports IPv4-mapped IPv6 address.
203 .It
204 If the
205 .Dv AI_ALL
206 flag is used in conjunction with the
207 .Dv AI_V4MAPPED
208 flag, and only used with the IPv6 address family.
209 When
210 .Dv AI_ALL
211 is logically or'd with
212 .Dv AI_V4MAPPED
213 flag then the caller wants all addresses: IPv6 and IPv4-mapped IPv6.
214 A query is first made for
215 .Li AAAA
216 records and if successful, the
217 IPv6 addresses are returned.
218 Another query is then made for
219 .Li A
220 records and any found are returned as IPv4-mapped IPv6 addresses.
221 .Li h_length
222 will be 16.
223 Only if both queries fail does the function
224 return a
225 .Dv NULL
226 pointer.
227 This flag is ignored unless af equals
228 AF_INET6.
229 If both
230 .Dv AI_ALL
231 and
232 .Dv AI_V4MAPPED
233 are specified,
234 .Dv AI_ALL
235 takes precedence.
236 .It
237 The
238 .Dv AI_ADDRCONFIG
239 flag specifies that a query for
240 .Li AAAA
241 records
242 should occur only if the node has at least one IPv6 source
243 address configured and a query for
244 .Li A
245 records should occur only if the node has at least one IPv4 source address
246 configured.
247 .Pp
248 For example, if the node has no IPv6 source addresses configured,
249 and
250 .Fa af
251 equals AF_INET6, and the node name being looked up has both
252 .Li AAAA
253 and
254 .Li A
255 records, then:
256 (a) if only
257 .Dv AI_ADDRCONFIG
258 is
259 specified, the function returns a
260 .Dv NULL
261 pointer;
262 (b) if
263 .Dv AI_ADDRCONFIG
264 |
265 .Dv AI_V4MAPPED
266 is specified, the
267 .Li A
268 records are returned as IPv4-mapped IPv6 addresses;
269 .El
270 .Pp
271 The special flags value of
272 .Dv AI_DEFAULT
273 is defined as
274 .Bd -literal -offset
275    #define  AI_DEFAULT  (AI_V4MAPPED_CFG | AI_ADDRCONFIG)
276 .Ed
277 .Pp
278 We noted that the
279 .Fn getipnodebyname
280 function must allow the
281 .Fa name
282 argument to be either a node name or a literal address string
283 (i.e., a dotted-decimal IPv4 address or an IPv6 hex address).
284 This saves applications from having to call
285 .Xr inet_pton 3
286 to handle literal address strings.
287 When the
288 .Fa name
289 argument is a literal address string,
290 the
291 .Fa flags
292 argument is always ignored.
293 .Pp
294 There are four scenarios based on the type of literal address string
295 and the value of the
296 .Fa af
297 argument.
298 The two simple cases are when
299 .Fa name
300 is a dotted-decimal IPv4 address and
301 .Fa af
302 equals
303 .Dv AF_INET ,
304 or when
305 .Fa name
306 is an IPv6 hex address and
307 .Fa af
308 equals
309 .Dv AF_INET6 .
310 The members of the
311 returned hostent structure are:
312 .Li h_name
313 points to a copy of the
314 .Fa name
315 argument,
316 .Li h_aliases
317 is a
318 .Dv NULL
319 pointer,
320 .Li h_addrtype
321 is a copy of the
322 .Fa af
323 argument,
324 .Li h_length
325 is either 4
326 (for
327 .Dv AF_INET )
328 or 16
329 (for
330 .Dv AF_INET6 ) ,
331 .Li h_addr_list[0]
332 is a pointer to the 4-byte or 16-byte binary address,
333 and
334 .Li h_addr_list[1]
335 is a
336 .Dv NULL
337 pointer.
338 .Pp
339 When
340 .Fa name
341 is a dotted-decimal IPv4 address and
342 .Fa af
343 equals
344 .Dv AF_INET6 ,
345 and
346 .Dv AI_V4MAPPED
347 is specified,
348 an IPv4-mapped IPv6 address is returned:
349 .Li h_name
350 points to an IPv6 hex address containing the IPv4-mapped IPv6 address,
351 .Li h_aliases
352 is a
353 .Dv NULL
354 pointer,
355 .Li h_addrtype
356 is
357 .Dv AF_INET6 ,
358 .Li h_length
359 is 16,
360 .Li h_addr_list[0]
361 is a pointer to the 16-byte binary address, and
362 .Li h_addr_list[1]
363 is a
364 .Dv NULL
365 pointer.
366 .Pp
367 It is an error when
368 .Fa name
369 is an IPv6 hex address and
370 .Fa af
371 equals
372 .Dv AF_INET .
373 The function's return value is a
374 .Dv NULL
375 pointer and the value pointed to by
376 .Fa error_num
377 equals
378 .Dv HOST_NOT_FOUND .
379 .Pp
380 The
381 .Fn getipnodebyaddr
382 function
383 takes almost the same argument as
384 .Xr gethostbyaddr 3 ,
385 but adds a pointer to return an error number.
386 Additionally it takes care of IPv4-mapped IPv6 addresses,
387 and IPv4-compatible IPv6 addresses.
388 .Pp
389 The
390 .Fn getipnodebyname
391 and
392 .Fn getipnodebyaddr
393 functions
394 dynamically allocate the structure to be returned to the caller.
395 The
396 .Fn freehostent
397 function
398 reclaims memory region allocated and returned by
399 .Fn getipnodebyname
400 or
401 .Fn getipnodebyaddr .
402 .\"
403 .Sh FILES
404 .Bl -tag -width /etc/nsswitch.conf -compact
405 .It Pa /etc/hosts
406 .It Pa /etc/nsswitch.conf
407 .It Pa /etc/resolv.conf
408 .El
409 .\"
410 .Sh DIAGNOSTICS
411 The
412 .Fn getipnodebyname
413 and
414 .Fn getipnodebyaddr
415 functions
416 returns
417 .Dv NULL
418 on errors.
419 The integer values pointed to by
420 .Fa error_num
421 may then be checked to see whether this is a temporary failure
422 or an invalid or unknown host.
423 The meanings of each error code are described in
424 .Xr gethostbyname 3 .
425 .\"
426 .Sh SEE ALSO
427 .Xr getaddrinfo 3 ,
428 .Xr gethostbyaddr 3 ,
429 .Xr gethostbyname 3 ,
430 .Xr getnameinfo 3 ,
431 .Xr hosts 5 ,
432 .Xr nsswitch.conf 5 ,
433 .Xr services 5 ,
434 .Xr hostname 7 ,
435 .Xr named 8
436 .Rs
437 .%A R. Gilligan
438 .%A S. Thomson
439 .%A J. Bound
440 .%A W. Stevens
441 .%T Basic Socket Interface Extensions for IPv6
442 .%R RFC 2553
443 .%D March 1999
444 .Re
445 .\"
446 .Sh STANDARDS
447 The
448 .Fn getipnodebyname
449 and
450 .Fn getipnodebyaddr
451 functions
452 are documented in
453 .Dq Basic Socket Interface Extensions for IPv6
454 (RFC 2553).
455 .\"
456 .Sh HISTORY
457 The implementation first appeared in KAME advanced networking kit.
458 .\"
459 .Sh BUGS
460 The
461 .Fn getipnodebyname
462 and
463 .Fn getipnodebyaddr
464 functions
465 do not handle scoped IPv6 address properly.
466 If you use these functions,
467 your program will not be able to handle scoped IPv6 addresses.
468 For IPv6 address manipulation,
469 .Fn getaddrinfo 3
470 and
471 .Fn getnameinfo 3
472 are recommended.
473 .Pp
474 The text was shamelessly copied from RFC 2553.