| blob | 0697c64e68bd8320f7b6a3d71ed3c582eb5e3480 |
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$
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
57 The
58 .Fn getipnodebyname
59 and
60 .Fn getipnodebyaddr
61 functions are very similar to
62 .Xr gethostbyname 3 ,
63 .Xr gethostbyname2 3
64 and
65 .Xr gethostbyaddr 3 .
66 The functions cover all the functionalities provided by the older ones,
67 and provide better interface to programmers.
68 The functions require additional arguments,
69 .Fa af ,
70 and
71 .Fa flags ,
72 for specifying address family and operation mode.
73 The additional arguments allow programmer to get address for a nodename,
74 for specific address family
75 (such as
76 .Dv AF_INET
77 or
78 .Dv AF_INET6 ) .
79 The functions also require an additional pointer argument,
80 .Fa error_num
81 to return the appropriate error code,
82 to support thread safe error code returns.
83 .Pp
84 The type and usage of the return value,
85 .Li "struct hostent"
86 is described in
87 .Xr gethostbyname 3 .
88 .Pp
89 For
90 .Fn getipnodebyname ,
91 the
92 .Fa name
93 argument can be either a node name or a numeric address
94 string
95 (i.e., a dotted-decimal IPv4 address or an IPv6 hex address).
96 The
97 .Fa af
98 argument specifies the address family, either
99 .Dv AF_INET
100 or
101 .Dv AF_INET6 .
102 The
103 .Fa flags
104 argument specifies the types of addresses that are searched for,
105 and the types of addresses that are returned.
106 We note that a special flags value of
107 .Dv AI_DEFAULT
108 (defined below)
109 should handle most applications.
110 That is, porting simple applications to use IPv6 replaces the call
111 .Bd -literal -offset indent
112 hptr = gethostbyname(name);
113 .Ed
114 .Pp
115 with
116 .Bd -literal -offset indent
117 hptr = getipnodebyname(name, AF_INET6, AI_DEFAULT, &error_num);
118 .Ed
119 .Pp
120 Applications desiring finer control over the types of addresses
121 searched for and returned, can specify other combinations of the
122 .Fa flags
123 argument.
124 .Pp
125 A
126 .Fa flags
127 of
128 .Li 0
129 implies a strict interpretation of the
130 .Fa af
131 argument:
132 .Bl -bullet
133 .It
134 If
135 .Fa flags
136 is 0 and
137 .Fa af
138 is
139 .Dv AF_INET ,
140 then the caller wants only IPv4 addresses.
141 A query is made for
142 .Li A
143 records.
144 If successful, the IPv4 addresses are returned and the
145 .Li h_length
146 member of the
147 .Li hostent
148 structure will be 4, else the function returns a
149 .Dv NULL
150 pointer.
151 .It
152 If
153 .Fa flags
154 is 0 and if
155 .Fa af
156 is
157 .Li AF_INET6 ,
158 then the caller wants only IPv6 addresses.
159 A query is made for
160 .Li AAAA
161 records.
162 If successful, the IPv6 addresses are returned and the
163 .Li h_length
164 member of the
165 .Li hostent
166 structure will be 16, else the function returns a
167 .Dv NULL
168 pointer.
169 .El
170 .Pp
171 Other constants can be logically-ORed into the
172 .Fa flags
173 argument, to modify the behavior of the function.
174 .Bl -bullet
175 .It
176 If the
177 .Dv AI_V4MAPPED
178 flag is specified along with an
179 .Fa af
180 of
181 .Dv AF_INET6 ,
182 then the caller will accept IPv4-mapped IPv6 addresses.
183 That is, if no
184 .Li AAAA
185 records are found then a query is made for
186 .Li A
187 records and any found are returned as IPv4-mapped IPv6 addresses
188 .Li ( h_length
189 will be 16).
190 The
191 .Dv AI_V4MAPPED
192 flag is ignored unless
193 .Fa af
194 equals
195 .Dv AF_INET6 .
196 .It
197 The
198 .Dv AI_V4MAPPED_CFG
199 flag is exact same as the
200 .Dv AI_V4MAPPED
201 flag only if the kernel supports IPv4-mapped IPv6 address.
202 .It
203 If the
204 .Dv AI_ALL
205 flag is used in conjunction with the
206 .Dv AI_V4MAPPED
207 flag, and only used with the IPv6 address family.
208 When
209 .Dv AI_ALL
210 is logically or'd with
211 .Dv AI_V4MAPPED
212 flag then the caller wants all addresses: IPv6 and IPv4-mapped IPv6.
213 A query is first made for
214 .Li AAAA
215 records and if successful, the
216 IPv6 addresses are returned.
217 Another query is then made for
218 .Li A
219 records and any found are returned as IPv4-mapped IPv6 addresses.
220 .Li h_length
221 will be 16.
222 Only if both queries fail does the function
223 return a
224 .Dv NULL
225 pointer.
226 This flag is ignored unless af equals
227 AF_INET6.
228 If both
229 .Dv AI_ALL
230 and
231 .Dv AI_V4MAPPED
232 are specified,
233 .Dv AI_ALL
234 takes precedence.
235 .It
236 The
237 .Dv AI_ADDRCONFIG
238 flag specifies that a query for
239 .Li AAAA
240 records
241 should occur only if the node has at least one IPv6 source
242 address configured and a query for
243 .Li A
244 records should occur only if the node has at least one IPv4 source address
245 configured.
246 .Pp
247 For example, if the node has no IPv6 source addresses configured,
248 and
249 .Fa af
250 equals AF_INET6, and the node name being looked up has both
251 .Li AAAA
252 and
253 .Li A
254 records, then:
255 (a) if only
256 .Dv AI_ADDRCONFIG
257 is
258 specified, the function returns a
259 .Dv NULL
260 pointer;
261 (b) if
262 .Dv AI_ADDRCONFIG
263 |
264 .Dv AI_V4MAPPED
265 is specified, the
266 .Li A
267 records are returned as IPv4-mapped IPv6 addresses;
268 .El
269 .Pp
270 The special flags value of
271 .Dv AI_DEFAULT
272 is defined as
273 .Bd -literal -offset indent
274 #define AI_DEFAULT (AI_V4MAPPED_CFG | AI_ADDRCONFIG)
275 .Ed
276 .Pp
277 We noted that the
278 .Fn getipnodebyname
279 function must allow the
280 .Fa name
281 argument to be either a node name or a literal address string
282 (i.e., a dotted-decimal IPv4 address or an IPv6 hex address).
283 This saves applications from having to call
284 .Xr inet_pton 3
285 to handle literal address strings.
286 When the
287 .Fa name
288 argument is a literal address string,
289 the
290 .Fa flags
291 argument is always ignored.
292 .Pp
293 There are four scenarios based on the type of literal address string
294 and the value of the
295 .Fa af
296 argument.
297 The two simple cases are when
298 .Fa name
299 is a dotted-decimal IPv4 address and
300 .Fa af
301 equals
302 .Dv AF_INET ,
303 or when
304 .Fa name
305 is an IPv6 hex address and
306 .Fa af
307 equals
308 .Dv AF_INET6 .
309 The members of the
310 returned hostent structure are:
311 .Li h_name
312 points to a copy of the
313 .Fa name
314 argument,
315 .Li h_aliases
316 is a
317 .Dv NULL
318 pointer,
319 .Li h_addrtype
320 is a copy of the
321 .Fa af
322 argument,
323 .Li h_length
324 is either 4
325 (for
326 .Dv AF_INET )
327 or 16
328 (for
329 .Dv AF_INET6 ) ,
330 .Li h_addr_list[0]
331 is a pointer to the 4-byte or 16-byte binary address,
332 and
333 .Li h_addr_list[1]
334 is a
335 .Dv NULL
336 pointer.
337 .Pp
338 When
339 .Fa name
340 is a dotted-decimal IPv4 address and
341 .Fa af
342 equals
343 .Dv AF_INET6 ,
344 and
345 .Dv AI_V4MAPPED
346 is specified,
347 an IPv4-mapped IPv6 address is returned:
348 .Li h_name
349 points to an IPv6 hex address containing the IPv4-mapped IPv6 address,
350 .Li h_aliases
351 is a
352 .Dv NULL
353 pointer,
354 .Li h_addrtype
355 is
356 .Dv AF_INET6 ,
357 .Li h_length
358 is 16,
359 .Li h_addr_list[0]
360 is a pointer to the 16-byte binary address, and
361 .Li h_addr_list[1]
362 is a
363 .Dv NULL
364 pointer.
365 .Pp
366 It is an error when
367 .Fa name
368 is an IPv6 hex address and
369 .Fa af
370 equals
371 .Dv AF_INET .
372 The function's return value is a
373 .Dv NULL
374 pointer and the value pointed to by
375 .Fa error_num
376 equals
377 .Dv HOST_NOT_FOUND .
378 .Pp
379 The
380 .Fn getipnodebyaddr
381 function
382 takes almost the same argument as
383 .Xr gethostbyaddr 3 ,
384 but adds a pointer to return an error number.
385 Additionally it takes care of IPv4-mapped IPv6 addresses,
386 and IPv4-compatible IPv6 addresses.
387 .Pp
388 The
389 .Fn getipnodebyname
390 and
391 .Fn getipnodebyaddr
392 functions
393 dynamically allocate the structure to be returned to the caller.
394 The
395 .Fn freehostent
396 function
397 reclaims memory region allocated and returned by
398 .Fn getipnodebyname
399 or
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
410 The
411 .Fn getipnodebyname
412 and
413 .Fn getipnodebyaddr
414 functions
415 returns
416 .Dv NULL
417 on errors.
418 The integer values pointed to by
419 .Fa error_num
420 may then be checked to see whether this is a temporary failure
421 or an invalid or unknown host.
422 The 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 .Pp
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 RFC2553
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 (RFC2553).
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 RFC2553.