[thirdparty/strongswan.git] / doc / manpage.d / ipsec_subnettoa.3.html

Content-type: text/html

<HTML><HEAD><TITLE>Manpage of IPSEC_ATOADDR</TITLE>
</HEAD><BODY>
<H1>IPSEC_ATOADDR</H1>
Section: C Library Functions (3)<BR>Updated: 11 June 2001<BR><A HREF="#index">Index</A>
<A HREF="http://localhost/cgi-bin/man/man2html">Return to Main Contents</A><HR>


<A NAME="lbAB">&nbsp;</A>
<H2>NAME</H2>

ipsec atoaddr, addrtoa - convert Internet addresses to and from ASCII
<BR>

ipsec atosubnet, subnettoa - convert subnet/mask ASCII form to and from addresses
<A NAME="lbAC">&nbsp;</A>
<H2>SYNOPSIS</H2>

<B>#include &lt;<A HREF="file:/usr/include/freeswan.h">freeswan.h</A>&gt;</B>

<P>
<B>const char *atoaddr(const char *src, size_t srclen,</B>

<BR>
&nbsp;
<B>struct in_addr *addr);</B>

<BR>

<B>size_t addrtoa(struct in_addr addr, int format,</B>

<BR>
&nbsp;
<B>char *dst, size_t dstlen);</B>

<P>
<B>const char *atosubnet(const char *src, size_t srclen,</B>

<BR>
&nbsp;
<B>struct in_addr *addr, struct in_addr *mask);</B>

<BR>

<B>size_t subnettoa(struct in_addr addr, struct in_addr mask,</B>

<BR>
&nbsp;
<B>int format, char *dst, size_t dstlen);</B>

<A NAME="lbAD">&nbsp;</A>
<H2>DESCRIPTION</H2>

These functions are obsolete; see
<I><A HREF="ipsec_ttoaddr.3.html">ipsec_ttoaddr</A></I>(3)

for their replacements.
<P>

<I>Atoaddr</I>

converts an ASCII name or dotted-decimal address into a binary address
(in network byte order).
<I>Addrtoa</I>

does the reverse conversion, back to an ASCII dotted-decimal address.
<I>Atosubnet</I>

and
<I>subnettoa</I>

do likewise for the ``address/mask'' ASCII form used to write a
specification of a subnet.
<P>

An address is specified in ASCII as a
dotted-decimal address (e.g.
<B>1.2.3.4</B>),

an eight-digit network-order hexadecimal number with the usual C prefix (e.g.
<B>0x01020304</B>,

which is synonymous with
<B>1.2.3.4</B>),

an eight-digit host-order hexadecimal number with a
<B>0h</B>

prefix (e.g.
<B>0h01020304</B>,

which is synonymous with
<B>1.2.3.4</B>

on a big-endian host and
<B>4.3.2.1</B>

on a little-endian host),
a DNS name to be looked up via
<I><A HREF="gethostbyname.3.html">gethostbyname</A></I>(3),

or an old-style network name to be looked up via
<I><A HREF="getnetbyname.3.html">getnetbyname</A></I>(3).

<P>

A dotted-decimal address may be incomplete, in which case
ASCII-to-binary conversion implicitly appends
as many instances of
<B>.0</B>

as necessary to bring it up to four components.
The components of a dotted-decimal address are always taken as
decimal, and leading zeros are ignored.
For example,
<B>10</B>

is synonymous with
<B>10.0.0.0</B>,

and
<B>128.009.000.032</B>

is synonymous with
<B>128.9.0.32</B>

(the latter example is verbatim from RFC 1166).
The result of
<I>addrtoa</I>

is always complete and does not contain leading zeros.
<P>

The letters in
a hexadecimal address may be uppercase or lowercase or any mixture thereof.
Use of hexadecimal addresses is
<B>strongly</B>

<B>discouraged</B>;

they are included only to save hassles when dealing with
the handful of perverted programs which already print 
network addresses in hexadecimal.
<P>

DNS names may be complete (optionally terminated with a ``.'')
or incomplete, and are looked up as specified by local system configuration
(see
<I><A HREF="resolver.5.html">resolver</A></I>(5)).

The
<I>h_addr</I>

value returned by
<I><A HREF="gethostbyname.3.html">gethostbyname</A></I>(3)

is used,
so with current DNS implementations,
the result when the name corresponds to more than one address is
difficult to predict.
Name lookup resorts to
<I><A HREF="getnetbyname.3.html">getnetbyname</A></I>(3)

only if
<I><A HREF="gethostbyname.3.html">gethostbyname</A></I>(3)

fails.
<P>

A subnet specification is of the form <I>network</I><B>/</B><I>mask</I>.
The
<I>network</I>

and
<I>mask</I>

can be any form acceptable to
<I>atoaddr</I>.

In addition, the
<I>mask</I>

can be a decimal integer (leading zeros ignored) giving a bit count,
in which case
it stands for a mask with that number of high bits on and all others off
(e.g.,
<B>24</B>

means
<B>255.255.255.0</B>).

In any case, the mask must be contiguous
(a sequence of high bits on and all remaining low bits off).
As a special case, the subnet specification
<B>%default</B>

is a synonym for
<B>0.0.0.0/0</B>.

<P>

<I>Atosubnet</I>

ANDs the mask with the address before returning,
so that any non-network bits in the address are turned off
(e.g.,
<B>10.1.2.3/24</B>

is synonymous with
<B>10.1.2.0/24</B>).

<I>Subnettoa</I>

generates the decimal-integer-bit-count
form of the mask,
with no leading zeros,
unless the mask is non-contiguous.
<P>

The
<I>srclen</I>

parameter of
<I>atoaddr</I>

and
<I>atosubnet</I>

specifies the length of the ASCII string pointed to by
<I>src</I>;

it is an error for there to be anything else
(e.g., a terminating NUL) within that length.
As a convenience for cases where an entire NUL-terminated string is
to be converted,
a
<I>srclen</I>

value of
<B>0</B>

is taken to mean
<B>strlen(src)</B>.

<P>

The
<I>dstlen</I>

parameter of
<I>addrtoa</I>

and
<I>subnettoa</I>

specifies the size of the
<I>dst</I>

parameter;
under no circumstances are more than
<I>dstlen</I>

bytes written to
<I>dst</I>.

A result which will not fit is truncated.
<I>Dstlen</I>

can be zero, in which case
<I>dst</I>

need not be valid and no result is written,
but the return value is unaffected;
in all other cases, the (possibly truncated) result is NUL-terminated.
The
<I>freeswan.h</I>

header file defines constants,
<B>ADDRTOA_BUF</B>

and
<B>SUBNETTOA_BUF</B>,

which are the sizes of buffers just large enough for worst-case results.
<P>

The
<I>format</I>

parameter of
<I>addrtoa</I>

and
<I>subnettoa</I>

specifies what format is to be used for the conversion.
The value
<B>0</B>

(not the ASCII character
<B>'0'</B>,

but a zero value)
specifies a reasonable default,
and is in fact the only format currently available.
This parameter is a hedge against future needs.
<P>

The ASCII-to-binary functions return NULL for success and
a pointer to a string-literal error message for failure;
see DIAGNOSTICS.
The binary-to-ASCII functions return
<B>0</B>

for a failure, and otherwise
always return the size of buffer which would 
be needed to
accommodate the full conversion result, including terminating NUL;
it is the caller's responsibility to check this against the size of
the provided buffer to determine whether truncation has occurred.
<A NAME="lbAE">&nbsp;</A>
<H2>SEE ALSO</H2>

<A HREF="inet.3.html">inet</A>(3)
<A NAME="lbAF">&nbsp;</A>
<H2>DIAGNOSTICS</H2>

Fatal errors in
<I>atoaddr</I>

are:
empty input;
attempt to allocate temporary storage for a very long name failed;
name lookup failed;
syntax error in dotted-decimal form;
dotted-decimal component too large to fit in 8 bits.
<P>

Fatal errors in
<I>atosubnet</I>

are:
no
<B>/</B>

in
<I>src</I>;

<I>atoaddr</I>

error in conversion of
<I>network</I>

or
<I>mask</I>;

bit-count mask too big;
mask non-contiguous.
<P>

Fatal errors in
<I>addrtoa</I>

and
<I>subnettoa</I>

are:
unknown format.
<A NAME="lbAG">&nbsp;</A>
<H2>HISTORY</H2>

Written for the FreeS/WAN project by Henry Spencer.
<A NAME="lbAH">&nbsp;</A>
<H2>BUGS</H2>

The interpretation of incomplete dotted-decimal addresses
(e.g.
<B>10/24</B>

means
<B>10.0.0.0/24</B>)

differs from that of some older conversion
functions, e.g. those of
<I><A HREF="inet.3.html">inet</A></I>(3).

The behavior of the older functions has never been
particularly consistent or particularly useful.
<P>

Ignoring leading zeros in dotted-decimal components and bit counts
is arguably the most useful behavior in this application,
but it might occasionally cause confusion with the historical use of leading 
zeros to denote octal numbers.
<P>

It is barely possible that somebody, somewhere,
might have a legitimate use for non-contiguous subnet masks.
<P>

<I><A HREF="Getnetbyname.3.html">Getnetbyname</A></I>(3)

is a historical dreg.
<P>

The restriction of ASCII-to-binary error reports to literal strings
(so that callers don't need to worry about freeing them or copying them)
does limit the precision of error reporting.
<P>

The ASCII-to-binary error-reporting convention lends itself
to slightly obscure code,
because many readers will not think of NULL as signifying success.
A good way to make it clearer is to write something like:
<P>

<DL COMPACT><DT><DD>
<PRE>
<B>const char *error;</B>

<B>error = atoaddr( /* ... */ );</B>
<B>if (error != NULL) {</B>
<B>        /* something went wrong */</B>
</PRE>

</DL>

<P>

<HR>
<A NAME="index">&nbsp;</A><H2>Index</H2>
<DL>
<DT><A HREF="#lbAB">NAME</A><DD>
<DT><A HREF="#lbAC">SYNOPSIS</A><DD>
<DT><A HREF="#lbAD">DESCRIPTION</A><DD>
<DT><A HREF="#lbAE">SEE ALSO</A><DD>
<DT><A HREF="#lbAF">DIAGNOSTICS</A><DD>
<DT><A HREF="#lbAG">HISTORY</A><DD>
<DT><A HREF="#lbAH">BUGS</A><DD>
</DL>
<HR>
This document was created by
<A HREF="http://localhost/cgi-bin/man/man2html">man2html</A>,
using the manual pages.<BR>
Time: 21:40:18 GMT, November 11, 2003
</BODY>
</HTML>
Commit	Line	Data
997358a6 MW	1	Content-type: text/html
	2
	3	<HTML><HEAD><TITLE>Manpage of IPSEC_ATOADDR</TITLE>
	4	</HEAD><BODY>
	5	<H1>IPSEC_ATOADDR</H1>
	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>
	8
	9
	10	<A NAME="lbAB"> </A>
	11	<H2>NAME</H2>
	12
	13	ipsec atoaddr, addrtoa - convert Internet addresses to and from ASCII
	14	<BR>
	15
	16	ipsec atosubnet, subnettoa - convert subnet/mask ASCII 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 atoaddr(const char src, size_t srclen,</B>
	24
	25	<BR>
	26
	27	<B>struct in_addr *addr);</B>
	28
	29	<BR>
	30
	31	<B>size_t addrtoa(struct in_addr addr, int format,</B>
	32
	33	<BR>
	34
	35	<B>char *dst, size_t dstlen);</B>
	36
	37	<P>
	38	<B>const char atosubnet(const char src, size_t srclen,</B>
	39
	40	<BR>
	41
	42	<B>struct in_addr addr, struct in_addr mask);</B>
	43
	44	<BR>
	45
	46	<B>size_t subnettoa(struct in_addr addr, struct in_addr mask,</B>
	47
	48	<BR>
	49
	50	<B>int format, char *dst, size_t dstlen);</B>
	51
	52	<A NAME="lbAD"> </A>
	53	<H2>DESCRIPTION</H2>
	54
	55	These functions are obsolete; see
	56	<I><A HREF="ipsec_ttoaddr.3.html">ipsec_ttoaddr</A></I>(3)
	57
	58	for their replacements.
	59	<P>
	60
	61	<I>Atoaddr</I>
	62
	63	converts an ASCII name or dotted-decimal address into a binary address
	64	(in network byte order).
65	<I>Addrtoa</I>
66
67	does the reverse conversion, back to an ASCII dotted-decimal address.
68	<I>Atosubnet</I>
69
70	and
71	<I>subnettoa</I>
72
73	do likewise for the ``address/mask'' ASCII form used to write a
74	specification of a subnet.
75	<P>
76
77	An address is specified in ASCII as a
78	dotted-decimal address (e.g.
79	<B>1.2.3.4</B>),
80
81	an eight-digit network-order hexadecimal number with the usual C prefix (e.g.
82	<B>0x01020304</B>,
83
84	which is synonymous with
85	<B>1.2.3.4</B>),
86
87	an eight-digit host-order hexadecimal number with a
88	<B>0h</B>
89
90	prefix (e.g.
91	<B>0h01020304</B>,
92
93	which is synonymous with
94	<B>1.2.3.4</B>
95
96	on a big-endian host and
97	<B>4.3.2.1</B>
98
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),
102
103	or an old-style network name to be looked up via
104	<I><A HREF="getnetbyname.3.html">getnetbyname</A></I>(3).
105
106	<P>
107
108	A dotted-decimal address may be incomplete, in which case
109	ASCII-to-binary conversion implicitly appends
110	as many instances of
111	<B>.0</B>
112
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.
116	For example,
117	<B>10</B>
118
119	is synonymous with
120	<B>10.0.0.0</B>,
121
122	and
123	<B>128.009.000.032</B>
124
125	is synonymous with
126	<B>128.9.0.32</B>
127
128	(the latter example is verbatim from RFC 1166).
129	The result of
130	<I>addrtoa</I>
131
132	is always complete and does not contain leading zeros.
133	<P>
134
135	The letters in
136	a hexadecimal address may be uppercase or lowercase or any mixture thereof.
137	Use of hexadecimal addresses is
138	<B>strongly</B>
139
140	<B>discouraged</B>;
141
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.
145	<P>
146
147	DNS names may be complete (optionally terminated with a ``.'')
148	or incomplete, and are looked up as specified by local system configuration
149	(see
150	<I><A HREF="resolver.5.html">resolver</A></I>(5)).
151
152	The
153	<I>h_addr</I>
154
155	value returned by
156	<I><A HREF="gethostbyname.3.html">gethostbyname</A></I>(3)
157
158	is used,
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)
164
165	only if
166	<I><A HREF="gethostbyname.3.html">gethostbyname</A></I>(3)
167
168	fails.
169	<P>
170
171	A subnet specification is of the form <I>network</I><B>/</B><I>mask</I>.
172	The
173	<I>network</I>
174
175	and
176	<I>mask</I>
177
178	can be any form acceptable to
179	<I>atoaddr</I>.
180
181	In addition, the
182	<I>mask</I>
183
184	can be a decimal integer (leading zeros ignored) giving a bit count,
185	in which case
186	it stands for a mask with that number of high bits on and all others off
187	(e.g.,
188	<B>24</B>
189
190	means
191	<B>255.255.255.0</B>).
192
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
196	<B>%default</B>
197
198	is a synonym for
199	<B>0.0.0.0/0</B>.
200
201	<P>
202
203	<I>Atosubnet</I>
204
205	ANDs the mask with the address before returning,
206	so that any non-network bits in the address are turned off
207	(e.g.,
208	<B>10.1.2.3/24</B>
209
210	is synonymous with
211	<B>10.1.2.0/24</B>).
212
213	<I>Subnettoa</I>
214
215	generates the decimal-integer-bit-count
216	form of the mask,
217	with no leading zeros,
218	unless the mask is non-contiguous.
219	<P>
220
221	The
222	<I>srclen</I>
223
224	parameter of
225	<I>atoaddr</I>
226
227	and
228	<I>atosubnet</I>
229
230	specifies the length of the ASCII string pointed to by
231	<I>src</I>;
232
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
236	to be converted,
237	a
238	<I>srclen</I>
239
240	value of
241	<B>0</B>
242
243	is taken to mean
244	<B>strlen(src)</B>.
245
246	<P>
247
248	The
249	<I>dstlen</I>
250
251	parameter of
252	<I>addrtoa</I>
253
254	and
255	<I>subnettoa</I>
256
257	specifies the size of the
258	<I>dst</I>
259
260	parameter;
261	under no circumstances are more than
262	<I>dstlen</I>
263
264	bytes written to
265	<I>dst</I>.
266
267	A result which will not fit is truncated.
268	<I>Dstlen</I>
269
270	can be zero, in which case
271	<I>dst</I>
272
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.
276	The
277	<I>freeswan.h</I>
278
279	header file defines constants,
280	<B>ADDRTOA_BUF</B>
281
282	and
283	<B>SUBNETTOA_BUF</B>,
284
285	which are the sizes of buffers just large enough for worst-case results.
286	<P>
287
288	The
289	<I>format</I>
290
291	parameter of
292	<I>addrtoa</I>
293
294	and
295	<I>subnettoa</I>
296
297	specifies what format is to be used for the conversion.
298	The value
299	<B>0</B>
300
301	(not the ASCII character
302	<B>'0'</B>,
303
304	but a zero value)
305	specifies a reasonable default,
306	and is in fact the only format currently available.
307	This parameter is a hedge against future needs.
308	<P>
309
310	The ASCII-to-binary functions return NULL for success and
311	a pointer to a string-literal error message for failure;
312	see DIAGNOSTICS.
313	The binary-to-ASCII functions return
314	<B>0</B>
315
316	for a failure, and otherwise
317	always return the size of buffer which would
318	be needed to
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>
323	<H2>SEE ALSO</H2>
324
325	<A HREF="inet.3.html">inet</A>(3)
326	<A NAME="lbAF"> </A>
327	<H2>DIAGNOSTICS</H2>
328
329	Fatal errors in
330	<I>atoaddr</I>
331
332	are:
333	empty input;
334	attempt to allocate temporary storage for a very long name failed;
335	name lookup failed;
336	syntax error in dotted-decimal form;
337	dotted-decimal component too large to fit in 8 bits.
338	<P>
339
340	Fatal errors in
341	<I>atosubnet</I>
342
343	are:
344	no
345	<B>/</B>
346
347	in
348	<I>src</I>;
349
350	<I>atoaddr</I>
351
352	error in conversion of
353	<I>network</I>
354
355	or
356	<I>mask</I>;
357
358	bit-count mask too big;
359	mask non-contiguous.
360	<P>
361
362	Fatal errors in
363	<I>addrtoa</I>
364
365	and
366	<I>subnettoa</I>
367
368	are:
369	unknown format.
370	<A NAME="lbAG"> </A>
371	<H2>HISTORY</H2>
372
373	Written for the FreeS/WAN project by Henry Spencer.
374	<A NAME="lbAH"> </A>
375	<H2>BUGS</H2>
376
377	The interpretation of incomplete dotted-decimal addresses
378	(e.g.
379	<B>10/24</B>
380
381	means
382	<B>10.0.0.0/24</B>)
383
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).
387
388	The behavior of the older functions has never been
389	particularly consistent or particularly useful.
390	<P>
391
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.
396	<P>
397
398	It is barely possible that somebody, somewhere,
399	might have a legitimate use for non-contiguous subnet masks.
400	<P>
401
402	<I><A HREF="Getnetbyname.3.html">Getnetbyname</A></I>(3)
403
404	is a historical dreg.
405	<P>
406
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.
410	<P>
411
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:
416	<P>
417
418	<DL COMPACT><DT><DD>
419	<PRE>
420	<B>const char *error;</B>
421
422	<B>error = atoaddr( /* ... */ );</B>
423	<B>if (error != NULL) {</B>
424	<B> /* something went wrong */</B>
425	</PRE>
426
427	</DL>
428
429	<P>
430
431	<HR>
432	<A NAME="index"> </A><H2>Index</H2>
433	<DL>
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>
441	</DL>
442	<HR>
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:18 GMT, November 11, 2003
447	</BODY>
448	</HTML>