1 .TH IPSEC_ATOADDR 3 "11 June 2001"
2 .\" RCSID $Id: atoaddr.3,v 1.11 2001/06/11 23:08:00 henry Exp $
4 ipsec atoaddr, addrtoa \- convert Internet addresses to and from ASCII
6 ipsec atosubnet, subnettoa \- convert subnet/mask ASCII form to and from addresses
8 .B "#include <freeswan.h>
10 .B "const char *atoaddr(const char *src, size_t srclen,"
12 .B "struct in_addr *addr);"
14 .B "size_t addrtoa(struct in_addr addr, int format,"
16 .B "char *dst, size_t dstlen);"
18 .B "const char *atosubnet(const char *src, size_t srclen,"
20 .B "struct in_addr *addr, struct in_addr *mask);"
22 .B "size_t subnettoa(struct in_addr addr, struct in_addr mask,"
24 .B "int format, char *dst, size_t dstlen);"
26 These functions are obsolete; see
28 for their replacements.
31 converts an ASCII name or dotted-decimal address into a binary address
32 (in network byte order).
34 does the reverse conversion, back to an ASCII dotted-decimal address.
38 do likewise for the ``address/mask'' ASCII form used to write a
39 specification of a subnet.
41 An address is specified in ASCII as a
42 dotted-decimal address (e.g.
44 an eight-digit network-order hexadecimal number with the usual C prefix (e.g.
46 which is synonymous with
48 an eight-digit host-order hexadecimal number with a
52 which is synonymous with
54 on a big-endian host and
56 on a little-endian host),
57 a DNS name to be looked up via
58 .IR gethostbyname (3),
59 or an old-style network name to be looked up via
62 A dotted-decimal address may be incomplete, in which case
63 ASCII-to-binary conversion implicitly appends
66 as necessary to bring it up to four components.
67 The components of a dotted-decimal address are always taken as
68 decimal, and leading zeros are ignored.
77 (the latter example is verbatim from RFC 1166).
80 is always complete and does not contain leading zeros.
83 a hexadecimal address may be uppercase or lowercase or any mixture thereof.
84 Use of hexadecimal addresses is
87 they are included only to save hassles when dealing with
88 the handful of perverted programs which already print
89 network addresses in hexadecimal.
91 DNS names may be complete (optionally terminated with a ``.'')
92 or incomplete, and are looked up as specified by local system configuration
100 so with current DNS implementations,
101 the result when the name corresponds to more than one address is
102 difficult to predict.
103 Name lookup resorts to
106 .IR gethostbyname (3)
109 A subnet specification is of the form \fInetwork\fB/\fImask\fR.
114 can be any form acceptable to
118 can be a decimal integer (leading zeros ignored) giving a bit count,
120 it stands for a mask with that number of high bits on and all others off
125 In any case, the mask must be contiguous
126 (a sequence of high bits on and all remaining low bits off).
127 As a special case, the subnet specification
133 ANDs the mask with the address before returning,
134 so that any non-network bits in the address are turned off
140 generates the decimal-integer-bit-count
142 with no leading zeros,
143 unless the mask is non-contiguous.
151 specifies the length of the ASCII string pointed to by
153 it is an error for there to be anything else
154 (e.g., a terminating NUL) within that length.
155 As a convenience for cases where an entire NUL-terminated string is
170 specifies the size of the
173 under no circumstances are more than
177 A result which will not fit is truncated.
179 can be zero, in which case
181 need not be valid and no result is written,
182 but the return value is unaffected;
183 in all other cases, the (possibly truncated) result is NUL-terminated.
186 header file defines constants,
190 which are the sizes of buffers just large enough for worst-case results.
198 specifies what format is to be used for the conversion.
201 (not the ASCII character
204 specifies a reasonable default,
205 and is in fact the only format currently available.
206 This parameter is a hedge against future needs.
208 The ASCII-to-binary functions return NULL for success and
209 a pointer to a string-literal error message for failure;
211 The binary-to-ASCII functions return
213 for a failure, and otherwise
214 always return the size of buffer which would
216 accommodate the full conversion result, including terminating NUL;
217 it is the caller's responsibility to check this against the size of
218 the provided buffer to determine whether truncation has occurred.
226 attempt to allocate temporary storage for a very long name failed;
228 syntax error in dotted-decimal form;
229 dotted-decimal component too large to fit in 8 bits.
239 error in conversion of
243 bit-count mask too big;
253 Written for the FreeS/WAN project by Henry Spencer.
255 The interpretation of incomplete dotted-decimal addresses
260 differs from that of some older conversion
261 functions, e.g. those of
263 The behavior of the older functions has never been
264 particularly consistent or particularly useful.
266 Ignoring leading zeros in dotted-decimal components and bit counts
267 is arguably the most useful behavior in this application,
268 but it might occasionally cause confusion with the historical use of leading
269 zeros to denote octal numbers.
271 It is barely possible that somebody, somewhere,
272 might have a legitimate use for non-contiguous subnet masks.
275 is a historical dreg.
277 The restriction of ASCII-to-binary error reports to literal strings
278 (so that callers don't need to worry about freeing them or copying them)
279 does limit the precision of error reporting.
281 The ASCII-to-binary error-reporting convention lends itself
282 to slightly obscure code,
283 because many readers will not think of NULL as signifying success.
284 A good way to make it clearer is to write something like:
288 .B "const char *error;"
290 .B "error = atoaddr( /* ... */ );"
291 .B "if (error != NULL) {"
292 .B " /* something went wrong */"