fce8884e421ca4c2fec04839d0b98dded2d25b7b
[strongswan.git] / src / libfreeswan / atoaddr.3
1 .TH IPSEC_ATOADDR 3 "11 June 2001"
2 .SH NAME
3 ipsec atoaddr, addrtoa \- convert Internet addresses to and from ASCII
4 .br
5 ipsec atosubnet, subnettoa \- convert subnet/mask ASCII form to and from addresses
6 .SH SYNOPSIS
7 .B "#include <freeswan.h>
8 .sp
9 .B "const char *atoaddr(const char *src, size_t srclen,"
10 .ti +1c
11 .B "struct in_addr *addr);"
12 .br
13 .B "size_t addrtoa(struct in_addr addr, int format,"
14 .ti +1c
15 .B "char *dst, size_t dstlen);"
16 .sp
17 .B "const char *atosubnet(const char *src, size_t srclen,"
18 .ti +1c
19 .B "struct in_addr *addr, struct in_addr *mask);"
20 .br
21 .B "size_t subnettoa(struct in_addr addr, struct in_addr mask,"
22 .ti +1c
23 .B "int format, char *dst, size_t dstlen);"
24 .SH DESCRIPTION
25 These functions are obsolete; see
26 .IR ipsec_ttoaddr (3)
27 for their replacements.
28 .PP
29 .I Atoaddr
30 converts an ASCII name or dotted-decimal address into a binary address
31 (in network byte order).
32 .I Addrtoa
33 does the reverse conversion, back to an ASCII dotted-decimal address.
34 .I Atosubnet
35 and
36 .I subnettoa
37 do likewise for the ``address/mask'' ASCII form used to write a
38 specification of a subnet.
39 .PP
40 An address is specified in ASCII as a
41 dotted-decimal address (e.g.
42 .BR 1.2.3.4 ),
43 an eight-digit network-order hexadecimal number with the usual C prefix (e.g.
44 .BR 0x01020304 ,
45 which is synonymous with
46 .BR 1.2.3.4 ),
47 an eight-digit host-order hexadecimal number with a
48 .B 0h
49 prefix (e.g.
50 .BR 0h01020304 ,
51 which is synonymous with
52 .B 1.2.3.4
53 on a big-endian host and
54 .B 4.3.2.1
55 on a little-endian host),
56 a DNS name to be looked up via
57 .IR gethostbyname (3),
58 or an old-style network name to be looked up via
59 .IR getnetbyname (3).
60 .PP
61 A dotted-decimal address may be incomplete, in which case
62 ASCII-to-binary conversion implicitly appends
63 as many instances of
64 .B .0
65 as necessary to bring it up to four components.
66 The components of a dotted-decimal address are always taken as
67 decimal, and leading zeros are ignored.
68 For example,
69 .B 10
70 is synonymous with
71 .BR 10.0.0.0 ,
72 and
73 .B 128.009.000.032
74 is synonymous with
75 .BR 128.9.0.32
76 (the latter example is verbatim from RFC 1166).
77 The result of
78 .I addrtoa
79 is always complete and does not contain leading zeros.
80 .PP
81 The letters in
82 a hexadecimal address may be uppercase or lowercase or any mixture thereof.
83 Use of hexadecimal addresses is
84 .B strongly
85 .BR discouraged ;
86 they are included only to save hassles when dealing with
87 the handful of perverted programs which already print 
88 network addresses in hexadecimal.
89 .PP
90 DNS names may be complete (optionally terminated with a ``.'')
91 or incomplete, and are looked up as specified by local system configuration
92 (see
93 .IR resolver (5)).
94 The
95 .I h_addr
96 value returned by
97 .IR gethostbyname (3)
98 is used,
99 so with current DNS implementations,
100 the result when the name corresponds to more than one address is
101 difficult to predict.
102 Name lookup resorts to
103 .IR getnetbyname (3)
104 only if
105 .IR gethostbyname (3)
106 fails.
107 .PP
108 A subnet specification is of the form \fInetwork\fB/\fImask\fR.
109 The
110 .I network
111 and
112 .I mask
113 can be any form acceptable to
114 .IR atoaddr .
115 In addition, the
116 .I mask
117 can be a decimal integer (leading zeros ignored) giving a bit count,
118 in which case
119 it stands for a mask with that number of high bits on and all others off
120 (e.g.,
121 .B 24
122 means
123 .BR 255.255.255.0 ).
124 In any case, the mask must be contiguous
125 (a sequence of high bits on and all remaining low bits off).
126 As a special case, the subnet specification
127 .B %default
128 is a synonym for
129 .BR 0.0.0.0/0 .
130 .PP
131 .I Atosubnet
132 ANDs the mask with the address before returning,
133 so that any non-network bits in the address are turned off
134 (e.g.,
135 .B 10.1.2.3/24
136 is synonymous with
137 .BR 10.1.2.0/24 ).
138 .I Subnettoa
139 generates the decimal-integer-bit-count
140 form of the mask,
141 with no leading zeros,
142 unless the mask is non-contiguous.
143 .PP
144 The
145 .I srclen
146 parameter of
147 .I atoaddr
148 and
149 .I atosubnet
150 specifies the length of the ASCII string pointed to by
151 .IR src ;
152 it is an error for there to be anything else
153 (e.g., a terminating NUL) within that length.
154 As a convenience for cases where an entire NUL-terminated string is
155 to be converted,
156 a
157 .I srclen
158 value of
159 .B 0
160 is taken to mean
161 .BR strlen(src) .
162 .PP
163 The
164 .I dstlen
165 parameter of
166 .I addrtoa
167 and
168 .I subnettoa
169 specifies the size of the
170 .I dst
171 parameter;
172 under no circumstances are more than
173 .I dstlen
174 bytes written to
175 .IR dst .
176 A result which will not fit is truncated.
177 .I Dstlen
178 can be zero, in which case
179 .I dst
180 need not be valid and no result is written,
181 but the return value is unaffected;
182 in all other cases, the (possibly truncated) result is NUL-terminated.
183 The
184 .I freeswan.h
185 header file defines constants,
186 .B ADDRTOA_BUF
187 and
188 .BR SUBNETTOA_BUF ,
189 which are the sizes of buffers just large enough for worst-case results.
190 .PP
191 The
192 .I format
193 parameter of
194 .I addrtoa
195 and
196 .I subnettoa
197 specifies what format is to be used for the conversion.
198 The value
199 .B 0
200 (not the ASCII character
201 .BR '0' ,
202 but a zero value)
203 specifies a reasonable default,
204 and is in fact the only format currently available.
205 This parameter is a hedge against future needs.
206 .PP
207 The ASCII-to-binary functions return NULL for success and
208 a pointer to a string-literal error message for failure;
209 see DIAGNOSTICS.
210 The binary-to-ASCII functions return
211 .B 0
212 for a failure, and otherwise
213 always return the size of buffer which would 
214 be needed to
215 accommodate the full conversion result, including terminating NUL;
216 it is the caller's responsibility to check this against the size of
217 the provided buffer to determine whether truncation has occurred.
218 .SH SEE ALSO
219 inet(3)
220 .SH DIAGNOSTICS
221 Fatal errors in
222 .I atoaddr
223 are:
224 empty input;
225 attempt to allocate temporary storage for a very long name failed;
226 name lookup failed;
227 syntax error in dotted-decimal form;
228 dotted-decimal component too large to fit in 8 bits.
229 .PP
230 Fatal errors in
231 .I atosubnet
232 are:
233 no
234 .B /
235 in
236 .IR src ;
237 .I atoaddr
238 error in conversion of
239 .I network
240 or
241 .IR mask ;
242 bit-count mask too big;
243 mask non-contiguous.
244 .PP
245 Fatal errors in
246 .I addrtoa
247 and
248 .I subnettoa
249 are:
250 unknown format.
251 .SH HISTORY
252 Written for the FreeS/WAN project by Henry Spencer.
253 .SH BUGS
254 The interpretation of incomplete dotted-decimal addresses
255 (e.g.
256 .B 10/24
257 means
258 .BR 10.0.0.0/24 )
259 differs from that of some older conversion
260 functions, e.g. those of
261 .IR inet (3).
262 The behavior of the older functions has never been
263 particularly consistent or particularly useful.
264 .PP
265 Ignoring leading zeros in dotted-decimal components and bit counts
266 is arguably the most useful behavior in this application,
267 but it might occasionally cause confusion with the historical use of leading 
268 zeros to denote octal numbers.
269 .PP
270 It is barely possible that somebody, somewhere,
271 might have a legitimate use for non-contiguous subnet masks.
272 .PP
273 .IR Getnetbyname (3)
274 is a historical dreg.
275 .PP
276 The restriction of ASCII-to-binary error reports to literal strings
277 (so that callers don't need to worry about freeing them or copying them)
278 does limit the precision of error reporting.
279 .PP
280 The ASCII-to-binary error-reporting convention lends itself
281 to slightly obscure code,
282 because many readers will not think of NULL as signifying success.
283 A good way to make it clearer is to write something like:
284 .PP
285 .RS
286 .nf
287 .B "const char *error;"
288 .sp
289 .B "error = atoaddr( /* ... */ );"
290 .B "if (error != NULL) {"
291 .B "        /* something went wrong */"
292 .fi
293 .RE