1 Content-type: text/html
3 <HTML><HEAD><TITLE>Manpage of IPSEC_ATOADDR
</TITLE>
6 Section: C Library Functions (
3)
<BR>Updated:
11 June
2001<BR><A HREF=
"#index">Index
</A>
7 <A HREF=
"http://localhost/cgi-bin/man/man2html">Return to Main Contents
</A><HR>
10 <A NAME=
"lbAB"> </A>
13 ipsec atoaddr, addrtoa - convert Internet addresses to and from ASCII
16 ipsec atosubnet, subnettoa - convert subnet/mask ASCII form to and from addresses
17 <A NAME=
"lbAC"> </A>
20 <B>#include
<<A HREF=
"file:/usr/include/freeswan.h">freeswan.h
</A>></B>
23 <B>const char *atoaddr(const char *src, size_t srclen,
</B>
27 <B>struct in_addr *addr);
</B>
31 <B>size_t addrtoa(struct in_addr addr, int format,
</B>
35 <B>char *dst, size_t dstlen);
</B>
38 <B>const char *atosubnet(const char *src, size_t srclen,
</B>
42 <B>struct in_addr *addr, struct in_addr *mask);
</B>
46 <B>size_t subnettoa(struct in_addr addr, struct in_addr mask,
</B>
50 <B>int format, char *dst, size_t dstlen);
</B>
52 <A NAME=
"lbAD"> </A>
55 These functions are obsolete; see
56 <I><A HREF=
"ipsec_ttoaddr.3.html">ipsec_ttoaddr
</A></I>(
3)
58 for their replacements.
63 converts an ASCII name or dotted-decimal address into a binary address
64 (in network byte order).
67 does the reverse conversion, back to an ASCII dotted-decimal address.
73 do likewise for the ``address/mask'' ASCII form used to write a
74 specification of a subnet.
77 An address is specified in ASCII as a
78 dotted-decimal address (e.g.
81 an eight-digit network-order hexadecimal number with the usual C prefix (e.g.
84 which is synonymous with
87 an eight-digit host-order hexadecimal number with a
93 which is synonymous with
96 on a big-endian host and
99 on a little-endian host),
100 a DNS name to be looked up via
101 <I><A HREF=
"gethostbyname.3.html">gethostbyname
</A></I>(
3),
103 or an old-style network name to be looked up via
104 <I><A HREF=
"getnetbyname.3.html">getnetbyname
</A></I>(
3).
108 A dotted-decimal address may be incomplete, in which case
109 ASCII-to-binary conversion implicitly appends
113 as necessary to bring it up to four components.
114 The components of a dotted-decimal address are always taken as
115 decimal, and leading zeros are ignored.
123 <B>128.009.000.032</B>
128 (the latter example is verbatim from RFC
1166).
132 is always complete and does not contain leading zeros.
136 a hexadecimal address may be uppercase or lowercase or any mixture thereof.
137 Use of hexadecimal addresses is
142 they are included only to save hassles when dealing with
143 the handful of perverted programs which already print
144 network addresses in hexadecimal.
147 DNS names may be complete (optionally terminated with a ``.'')
148 or incomplete, and are looked up as specified by local system configuration
150 <I><A HREF=
"resolver.5.html">resolver
</A></I>(
5)).
156 <I><A HREF=
"gethostbyname.3.html">gethostbyname
</A></I>(
3)
159 so with current DNS implementations,
160 the result when the name corresponds to more than one address is
161 difficult to predict.
162 Name lookup resorts to
163 <I><A HREF=
"getnetbyname.3.html">getnetbyname
</A></I>(
3)
166 <I><A HREF=
"gethostbyname.3.html">gethostbyname
</A></I>(
3)
171 A subnet specification is of the form
<I>network
</I><B>/
</B><I>mask
</I>.
178 can be any form acceptable to
184 can be a decimal integer (leading zeros ignored) giving a bit count,
186 it stands for a mask with that number of high bits on and all others off
191 <B>255.255.255.0</B>).
193 In any case, the mask must be contiguous
194 (a sequence of high bits on and all remaining low bits off).
195 As a special case, the subnet specification
205 ANDs the mask with the address before returning,
206 so that any non-network bits in the address are turned off
215 generates the decimal-integer-bit-count
217 with no leading zeros,
218 unless the mask is non-contiguous.
230 specifies the length of the ASCII string pointed to by
233 it is an error for there to be anything else
234 (e.g., a terminating NUL) within that length.
235 As a convenience for cases where an entire NUL-terminated string is
257 specifies the size of the
261 under no circumstances are more than
267 A result which will not fit is truncated.
270 can be zero, in which case
273 need not be valid and no result is written,
274 but the return value is unaffected;
275 in all other cases, the (possibly truncated) result is NUL-terminated.
279 header file defines constants,
283 <B>SUBNETTOA_BUF
</B>,
285 which are the sizes of buffers just large enough for worst-case results.
297 specifies what format is to be used for the conversion.
301 (not the ASCII character
305 specifies a reasonable default,
306 and is in fact the only format currently available.
307 This parameter is a hedge against future needs.
310 The ASCII-to-binary functions return NULL for success and
311 a pointer to a string-literal error message for failure;
313 The binary-to-ASCII functions return
316 for a failure, and otherwise
317 always return the size of buffer which would
319 accommodate the full conversion result, including terminating NUL;
320 it is the caller's responsibility to check this against the size of
321 the provided buffer to determine whether truncation has occurred.
322 <A NAME=
"lbAE"> </A>
325 <A HREF=
"inet.3.html">inet
</A>(
3)
326 <A NAME=
"lbAF"> </A>
334 attempt to allocate temporary storage for a very long name failed;
336 syntax error in dotted-decimal form;
337 dotted-decimal component too large to fit in
8 bits.
352 error in conversion of
358 bit-count mask too big;
370 <A NAME=
"lbAG"> </A>
373 Written for the FreeS/WAN project by Henry Spencer.
374 <A NAME=
"lbAH"> </A>
377 The interpretation of incomplete dotted-decimal addresses
384 differs from that of some older conversion
385 functions, e.g. those of
386 <I><A HREF=
"inet.3.html">inet
</A></I>(
3).
388 The behavior of the older functions has never been
389 particularly consistent or particularly useful.
392 Ignoring leading zeros in dotted-decimal components and bit counts
393 is arguably the most useful behavior in this application,
394 but it might occasionally cause confusion with the historical use of leading
395 zeros to denote octal numbers.
398 It is barely possible that somebody, somewhere,
399 might have a legitimate use for non-contiguous subnet masks.
402 <I><A HREF=
"Getnetbyname.3.html">Getnetbyname
</A></I>(
3)
404 is a historical dreg.
407 The restriction of ASCII-to-binary error reports to literal strings
408 (so that callers don't need to worry about freeing them or copying them)
409 does limit the precision of error reporting.
412 The ASCII-to-binary error-reporting convention lends itself
413 to slightly obscure code,
414 because many readers will not think of NULL as signifying success.
415 A good way to make it clearer is to write something like:
420 <B>const char *error;
</B>
422 <B>error = atoaddr( /* ... */ );
</B>
423 <B>if (error != NULL) {
</B>
424 <B> /* something went wrong */
</B>
432 <A NAME=
"index"> </A><H2>Index
</H2>
434 <DT><A HREF=
"#lbAB">NAME
</A><DD>
435 <DT><A HREF=
"#lbAC">SYNOPSIS
</A><DD>
436 <DT><A HREF=
"#lbAD">DESCRIPTION
</A><DD>
437 <DT><A HREF=
"#lbAE">SEE ALSO
</A><DD>
438 <DT><A HREF=
"#lbAF">DIAGNOSTICS
</A><DD>
439 <DT><A HREF=
"#lbAG">HISTORY
</A><DD>
440 <DT><A HREF=
"#lbAH">BUGS
</A><DD>
443 This document was created by
444 <A HREF=
"http://localhost/cgi-bin/man/man2html">man2html
</A>,
445 using the manual pages.
<BR>
446 Time:
21:
40:
17 GMT, November
11,
2003