]>
Commit | Line | Data |
---|---|---|
997358a6 MW |
1 | Content-type: text/html |
2 | ||
3 | <HTML><HEAD><TITLE>Manpage of IPSEC_TTOADDR</TITLE> | |
4 | </HEAD><BODY> | |
5 | <H1>IPSEC_TTOADDR</H1> | |
6 | Section: C Library Functions (3)<BR>Updated: 28 Sept 2001<BR><A HREF="#index">Index</A> | |
7 | <A HREF="http://localhost/cgi-bin/man/man2html">Return to Main Contents</A><HR> | |
8 | ||
9 | ||
10 | <A NAME="lbAB"> </A> | |
11 | <H2>NAME</H2> | |
12 | ||
13 | ipsec ttoaddr, tnatoaddr, addrtot - convert Internet addresses to and from text | |
14 | <BR> | |
15 | ||
16 | ipsec ttosubnet, subnettot - convert subnet/mask text form to and from addresses | |
17 | <A NAME="lbAC"> </A> | |
18 | <H2>SYNOPSIS</H2> | |
19 | ||
20 | <B>#include <<A HREF="file:/usr/include/freeswan.h">freeswan.h</A>></B> | |
21 | ||
22 | <P> | |
23 | <B>const char *ttoaddr(const char *src, size_t srclen,</B> | |
24 | ||
25 | <BR> | |
26 | | |
27 | <B>int af, ip_address *addr);</B> | |
28 | ||
29 | <BR> | |
30 | ||
31 | <B>const char *tnatoaddr(const char *src, size_t srclen,</B> | |
32 | ||
33 | <BR> | |
34 | | |
35 | <B>int af, ip_address *addr);</B> | |
36 | ||
37 | <BR> | |
38 | ||
39 | <B>size_t addrtot(const ip_address *addr, int format,</B> | |
40 | ||
41 | <BR> | |
42 | | |
43 | <B>char *dst, size_t dstlen);</B> | |
44 | ||
45 | <P> | |
46 | <B>const char *ttosubnet(const char *src, size_t srclen,</B> | |
47 | ||
48 | <BR> | |
49 | | |
50 | <B>int af, ip_subnet *dst);</B> | |
51 | ||
52 | <BR> | |
53 | ||
54 | <B>size_t subnettot(const ip_subnet *sub, int format,</B> | |
55 | ||
56 | <BR> | |
57 | | |
58 | <B>char *dst, size_t dstlen);</B> | |
59 | ||
60 | <A NAME="lbAD"> </A> | |
61 | <H2>DESCRIPTION</H2> | |
62 | ||
63 | <I>Ttoaddr</I> | |
64 | ||
65 | converts a text-string name or numeric address into a binary address | |
66 | (in network byte order). | |
67 | <I>Tnatoaddr</I> | |
68 | ||
69 | does the same conversion, | |
70 | but the only text forms it accepts are | |
71 | the ``official'' forms of | |
72 | numeric address (dotted-decimal for IPv4, colon-hex for IPv6). | |
73 | <I>Addrtot</I> | |
74 | ||
75 | does the reverse conversion, from binary address back to a text form. | |
76 | <I>Ttosubnet</I> | |
77 | ||
78 | and | |
79 | <I>subnettot</I> | |
80 | ||
81 | do likewise for the ``address/mask'' form used to write a | |
82 | specification of a subnet. | |
83 | <P> | |
84 | ||
85 | An IPv4 address is specified in text as a | |
86 | dotted-decimal address (e.g. | |
87 | <B>1.2.3.4</B>), | |
88 | ||
89 | an eight-digit network-order hexadecimal number with the usual C prefix (e.g. | |
90 | <B>0x01020304</B>, | |
91 | ||
92 | which is synonymous with | |
93 | <B>1.2.3.4</B>), | |
94 | ||
95 | an eight-digit host-order hexadecimal number with a | |
96 | <B>0h</B> | |
97 | ||
98 | prefix (e.g. | |
99 | <B>0h01020304</B>, | |
100 | ||
101 | which is synonymous with | |
102 | <B>1.2.3.4</B> | |
103 | ||
104 | on a big-endian host and | |
105 | <B>4.3.2.1</B> | |
106 | ||
107 | on a little-endian host), | |
108 | a DNS name to be looked up via | |
109 | <I><A HREF="gethostbyname.3.html">gethostbyname</A></I>(3), | |
110 | ||
111 | or an old-style network name to be looked up via | |
112 | <I><A HREF="getnetbyname.3.html">getnetbyname</A></I>(3). | |
113 | ||
114 | <P> | |
115 | ||
116 | A dotted-decimal address may be incomplete, in which case | |
117 | text-to-binary conversion implicitly appends | |
118 | as many instances of | |
119 | <B>.0</B> | |
120 | ||
121 | as necessary to bring it up to four components. | |
122 | The components of a dotted-decimal address are always taken as | |
123 | decimal, and leading zeros are ignored. | |
124 | For example, | |
125 | <B>10</B> | |
126 | ||
127 | is synonymous with | |
128 | <B>10.0.0.0</B>, | |
129 | ||
130 | and | |
131 | <B>128.009.000.032</B> | |
132 | ||
133 | is synonymous with | |
134 | <B>128.9.0.32</B> | |
135 | ||
136 | (the latter example is verbatim from RFC 1166). | |
137 | The result of applying | |
138 | <I>addrtot</I> | |
139 | ||
140 | to an IPv4 address is always complete and does not contain leading zeros. | |
141 | <P> | |
142 | ||
143 | Use of hexadecimal addresses is | |
144 | <B>strongly</B> | |
145 | ||
146 | <B>discouraged</B>; | |
147 | ||
148 | they are included only to save hassles when dealing with | |
149 | the handful of perverted programs which already print | |
150 | network addresses in hexadecimal. | |
151 | <P> | |
152 | ||
153 | An IPv6 address is specified in text with | |
154 | colon-hex notation (e.g. | |
155 | <B>0:56:78ab:22:33:44:55:66</B>), | |
156 | ||
157 | colon-hex with | |
158 | <B>::</B> | |
159 | ||
160 | abbreviating at most one subsequence of multiple zeros (e.g. | |
161 | <B>99:ab::54:068</B>, | |
162 | ||
163 | which is synonymous with | |
164 | <B>99:ab:0:0:0:0:54:68</B>), | |
165 | ||
166 | or a DNS name to be looked up via | |
167 | <I><A HREF="gethostbyname.3.html">gethostbyname</A></I>(3). | |
168 | ||
169 | The result of applying | |
170 | <I>addrtot</I> | |
171 | ||
172 | to an IPv6 address will use | |
173 | <B>::</B> | |
174 | ||
175 | abbreviation if possible, | |
176 | and will not contain leading zeros. | |
177 | <P> | |
178 | ||
179 | The letters in hexadecimal | |
180 | may be uppercase or lowercase or any mixture thereof. | |
181 | <P> | |
182 | ||
183 | DNS names may be complete (optionally terminated with a ``.'') | |
184 | or incomplete, and are looked up as specified by local system configuration | |
185 | (see | |
186 | <I><A HREF="resolver.5.html">resolver</A></I>(5)). | |
187 | ||
188 | The | |
189 | <I>h_addr</I> | |
190 | ||
191 | value returned by | |
192 | <I><A HREF="gethostbyname2.3.html">gethostbyname2</A></I>(3) | |
193 | ||
194 | is used, | |
195 | so with current DNS implementations, | |
196 | the result when the name corresponds to more than one address is | |
197 | difficult to predict. | |
198 | IPv4 name lookup resorts to | |
199 | <I><A HREF="getnetbyname.3.html">getnetbyname</A></I>(3) | |
200 | ||
201 | only if | |
202 | <I><A HREF="gethostbyname2.3.html">gethostbyname2</A></I>(3) | |
203 | ||
204 | fails. | |
205 | <P> | |
206 | ||
207 | A subnet specification is of the form <I>network</I><B>/</B><I>mask</I>. | |
208 | The | |
209 | <I>network</I> | |
210 | ||
211 | and | |
212 | <I>mask</I> | |
213 | ||
214 | can be any form acceptable to | |
215 | <I>ttoaddr</I>. | |
216 | ||
217 | In addition, and preferably, the | |
218 | <I>mask</I> | |
219 | ||
220 | can be a decimal integer (leading zeros ignored) giving a bit count, | |
221 | in which case | |
222 | it stands for a mask with that number of high bits on and all others off | |
223 | (e.g., | |
224 | <B>24</B> | |
225 | ||
226 | in IPv4 means | |
227 | <B>255.255.255.0</B>). | |
228 | ||
229 | In any case, the mask must be contiguous | |
230 | (a sequence of high bits on and all remaining low bits off). | |
231 | As a special case, the subnet specification | |
232 | <B>%default</B> | |
233 | ||
234 | is a synonym for | |
235 | <B>0.0.0.0/0</B> | |
236 | ||
237 | or | |
238 | <B>::/0</B> | |
239 | ||
240 | in IPv4 or IPv6 respectively. | |
241 | <P> | |
242 | ||
243 | <I>Ttosubnet</I> | |
244 | ||
245 | ANDs the mask with the address before returning, | |
246 | so that any non-network bits in the address are turned off | |
247 | (e.g., | |
248 | <B>10.1.2.3/24</B> | |
249 | ||
250 | is synonymous with | |
251 | <B>10.1.2.0/24</B>). | |
252 | ||
253 | <I>Subnettot</I> | |
254 | ||
255 | always generates the decimal-integer-bit-count | |
256 | form of the mask, | |
257 | with no leading zeros. | |
258 | <P> | |
259 | ||
260 | The | |
261 | <I>srclen</I> | |
262 | ||
263 | parameter of | |
264 | <I>ttoaddr</I> | |
265 | ||
266 | and | |
267 | <I>ttosubnet</I> | |
268 | ||
269 | specifies the length of the text string pointed to by | |
270 | <I>src</I>; | |
271 | ||
272 | it is an error for there to be anything else | |
273 | (e.g., a terminating NUL) within that length. | |
274 | As a convenience for cases where an entire NUL-terminated string is | |
275 | to be converted, | |
276 | a | |
277 | <I>srclen</I> | |
278 | ||
279 | value of | |
280 | <B>0</B> | |
281 | ||
282 | is taken to mean | |
283 | <B>strlen(src)</B>. | |
284 | ||
285 | <P> | |
286 | ||
287 | The | |
288 | <I>af</I> | |
289 | ||
290 | parameter of | |
291 | <I>ttoaddr</I> | |
292 | ||
293 | and | |
294 | <I>ttosubnet</I> | |
295 | ||
296 | specifies the address family of interest. | |
297 | It should be either | |
298 | <B>AF_INET</B> | |
299 | ||
300 | or | |
301 | <B>AF_INET6</B>. | |
302 | ||
303 | <P> | |
304 | ||
305 | The | |
306 | <I>dstlen</I> | |
307 | ||
308 | parameter of | |
309 | <I>addrtot</I> | |
310 | ||
311 | and | |
312 | <I>subnettot</I> | |
313 | ||
314 | specifies the size of the | |
315 | <I>dst</I> | |
316 | ||
317 | parameter; | |
318 | under no circumstances are more than | |
319 | <I>dstlen</I> | |
320 | ||
321 | bytes written to | |
322 | <I>dst</I>. | |
323 | ||
324 | A result which will not fit is truncated. | |
325 | <I>Dstlen</I> | |
326 | ||
327 | can be zero, in which case | |
328 | <I>dst</I> | |
329 | ||
330 | need not be valid and no result is written, | |
331 | but the return value is unaffected; | |
332 | in all other cases, the (possibly truncated) result is NUL-terminated. | |
333 | The | |
334 | <I>freeswan.h</I> | |
335 | ||
336 | header file defines constants, | |
337 | <B>ADDRTOT_BUF</B> | |
338 | ||
339 | and | |
340 | <B>SUBNETTOT_BUF</B>, | |
341 | ||
342 | which are the sizes of buffers just large enough for worst-case results. | |
343 | <P> | |
344 | ||
345 | The | |
346 | <I>format</I> | |
347 | ||
348 | parameter of | |
349 | <I>addrtot</I> | |
350 | ||
351 | and | |
352 | <I>subnettot</I> | |
353 | ||
354 | specifies what format is to be used for the conversion. | |
355 | The value | |
356 | <B>0</B> | |
357 | ||
358 | (not the character | |
359 | <B>'0'</B>, | |
360 | ||
361 | but a zero value) | |
362 | specifies a reasonable default, | |
363 | and is in fact the only format currently available in | |
364 | <I>subnettot</I>. | |
365 | ||
366 | <I>Addrtot</I> | |
367 | ||
368 | also accepts format values | |
369 | <B>'r'</B> | |
370 | ||
371 | (signifying a text form suitable for DNS reverse lookups, | |
372 | e.g. | |
373 | <B>4.3.2.1.IN-ADDR.ARPA.</B> | |
374 | ||
375 | for IPv4 and | |
376 | RFC 2874 format for IPv6), | |
377 | and | |
378 | <B>'R'</B> | |
379 | ||
380 | (signifying an alternate reverse-lookup form, | |
381 | an error for IPv4 and RFC 1886 format for IPv6). | |
382 | Reverse-lookup names always end with a ``.''. | |
383 | <P> | |
384 | ||
385 | The text-to-binary functions return NULL for success and | |
386 | a pointer to a string-literal error message for failure; | |
387 | see DIAGNOSTICS. | |
388 | The binary-to-text functions return | |
389 | <B>0</B> | |
390 | ||
391 | for a failure, and otherwise | |
392 | always return the size of buffer which would | |
393 | be needed to | |
394 | accommodate the full conversion result, including terminating NUL; | |
395 | it is the caller's responsibility to check this against the size of | |
396 | the provided buffer to determine whether truncation has occurred. | |
397 | <A NAME="lbAE"> </A> | |
398 | <H2>SEE ALSO</H2> | |
399 | ||
400 | <A HREF="inet.3.html">inet</A>(3) | |
401 | <A NAME="lbAF"> </A> | |
402 | <H2>DIAGNOSTICS</H2> | |
403 | ||
404 | Fatal errors in | |
405 | <I>ttoaddr</I> | |
406 | ||
407 | are: | |
408 | empty input; | |
409 | unknown address family; | |
410 | attempt to allocate temporary storage for a very long name failed; | |
411 | name lookup failed; | |
412 | syntax error in dotted-decimal or colon-hex form; | |
413 | dotted-decimal or colon-hex component too large. | |
414 | <P> | |
415 | ||
416 | Fatal errors in | |
417 | <I>ttosubnet</I> | |
418 | ||
419 | are: | |
420 | no | |
421 | <B>/</B> | |
422 | ||
423 | in | |
424 | <I>src</I>; | |
425 | ||
426 | <I>ttoaddr</I> | |
427 | ||
428 | error in conversion of | |
429 | <I>network</I> | |
430 | ||
431 | or | |
432 | <I>mask</I>; | |
433 | ||
434 | bit-count mask too big; | |
435 | mask non-contiguous. | |
436 | <P> | |
437 | ||
438 | Fatal errors in | |
439 | <I>addrtot</I> | |
440 | ||
441 | and | |
442 | <I>subnettot</I> | |
443 | ||
444 | are: | |
445 | unknown format. | |
446 | <A NAME="lbAG"> </A> | |
447 | <H2>HISTORY</H2> | |
448 | ||
449 | Written for the FreeS/WAN project by Henry Spencer. | |
450 | <A NAME="lbAH"> </A> | |
451 | <H2>BUGS</H2> | |
452 | ||
453 | The interpretation of incomplete dotted-decimal addresses | |
454 | (e.g. | |
455 | <B>10/24</B> | |
456 | ||
457 | means | |
458 | <B>10.0.0.0/24</B>) | |
459 | ||
460 | differs from that of some older conversion | |
461 | functions, e.g. those of | |
462 | <I><A HREF="inet.3.html">inet</A></I>(3). | |
463 | ||
464 | The behavior of the older functions has never been | |
465 | particularly consistent or particularly useful. | |
466 | <P> | |
467 | ||
468 | Ignoring leading zeros in dotted-decimal components and bit counts | |
469 | is arguably the most useful behavior in this application, | |
470 | but it might occasionally cause confusion with the historical use of leading | |
471 | zeros to denote octal numbers. | |
472 | <P> | |
473 | ||
474 | <I>Ttoaddr</I> | |
475 | ||
476 | does not support the mixed colon-hex-dotted-decimal | |
477 | convention used to embed an IPv4 address in an IPv6 address. | |
478 | <P> | |
479 | ||
480 | <I>Addrtot</I> | |
481 | ||
482 | always uses the | |
483 | <B>::</B> | |
484 | ||
485 | abbreviation (which can appear only once in an address) for the | |
486 | <I>first</I> | |
487 | ||
488 | sequence of multiple zeros in an IPv6 address. | |
489 | One can construct addresses (unlikely ones) in which this is suboptimal. | |
490 | <P> | |
491 | ||
492 | <I>Addrtot</I> | |
493 | ||
494 | <B>'r'</B> | |
495 | ||
496 | conversion of an IPv6 address uses lowercase hexadecimal, | |
497 | not the uppercase used in RFC 2874's examples. | |
498 | It takes careful reading of RFCs 2874, 2673, and 2234 to realize | |
499 | that lowercase is technically legitimate here, | |
500 | and there may be software which botches this | |
501 | and hence would have trouble with lowercase hex. | |
502 | <P> | |
503 | ||
504 | Possibly | |
505 | <I>subnettot</I> | |
506 | ||
507 | ought to recognize the | |
508 | <B>%default</B> | |
509 | ||
510 | case and generate that string as its output. | |
511 | Currently it doesn't. | |
512 | <P> | |
513 | ||
514 | It is barely possible that somebody, somewhere, | |
515 | might have a legitimate use for non-contiguous subnet masks. | |
516 | <P> | |
517 | ||
518 | <I><A HREF="Getnetbyname.3.html">Getnetbyname</A></I>(3) | |
519 | ||
520 | is a historical dreg. | |
521 | <P> | |
522 | ||
523 | <I>Tnatoaddr</I> | |
524 | ||
525 | probably should enforce completeness of dotted-decimal addresses. | |
526 | <P> | |
527 | ||
528 | The restriction of text-to-binary error reports to literal strings | |
529 | (so that callers don't need to worry about freeing them or copying them) | |
530 | does limit the precision of error reporting. | |
531 | <P> | |
532 | ||
533 | The text-to-binary error-reporting convention lends itself | |
534 | to slightly obscure code, | |
535 | because many readers will not think of NULL as signifying success. | |
536 | A good way to make it clearer is to write something like: | |
537 | <P> | |
538 | ||
539 | <DL COMPACT><DT><DD> | |
540 | <PRE> | |
541 | <B>const char *error;</B> | |
542 | ||
543 | <B>error = ttoaddr( /* ... */ );</B> | |
544 | <B>if (error != NULL) {</B> | |
545 | <B> /* something went wrong */</B> | |
546 | </PRE> | |
547 | ||
548 | </DL> | |
549 | ||
550 | <P> | |
551 | ||
552 | <HR> | |
553 | <A NAME="index"> </A><H2>Index</H2> | |
554 | <DL> | |
555 | <DT><A HREF="#lbAB">NAME</A><DD> | |
556 | <DT><A HREF="#lbAC">SYNOPSIS</A><DD> | |
557 | <DT><A HREF="#lbAD">DESCRIPTION</A><DD> | |
558 | <DT><A HREF="#lbAE">SEE ALSO</A><DD> | |
559 | <DT><A HREF="#lbAF">DIAGNOSTICS</A><DD> | |
560 | <DT><A HREF="#lbAG">HISTORY</A><DD> | |
561 | <DT><A HREF="#lbAH">BUGS</A><DD> | |
562 | </DL> | |
563 | <HR> | |
564 | This document was created by | |
565 | <A HREF="http://localhost/cgi-bin/man/man2html">man2html</A>, | |
566 | using the manual pages.<BR> | |
567 | Time: 21:40:18 GMT, November 11, 2003 | |
568 | </BODY> | |
569 | </HTML> |