- import of strongswan-2.7.0
- applied patch for charon
This commit is contained in:
Martin Willi
@@ -0,0 +1,186 @@
|
||||
.TH IPSEC_ATOASR 3 "11 June 2001"
|
||||
.\" RCSID $Id: atoasr.3,v 1.1 2004/03/15 20:35:25 as Exp $
|
||||
.SH NAME
|
||||
ipsec atoasr \- convert ASCII to Internet address, subnet, or range
|
||||
.br
|
||||
ipsec rangetoa \- convert Internet address range to ASCII
|
||||
.SH SYNOPSIS
|
||||
.B "#include <freeswan.h>
|
||||
.sp
|
||||
.B "const char *atoasr(const char *src, size_t srclen,"
|
||||
.ti +1c
|
||||
.B "char *type, struct in_addr *addrs);"
|
||||
.br
|
||||
.B "size_t rangetoa(struct in_addr *addrs, int format,
|
||||
.ti +1c
|
||||
.B "char *dst, size_t dstlen);"
|
||||
.SH DESCRIPTION
|
||||
These functions are obsolete;
|
||||
there is no current equivalent,
|
||||
because so far they have not proved useful.
|
||||
.PP
|
||||
.I Atoasr
|
||||
converts an ASCII address, subnet, or address range
|
||||
into a suitable combination of binary addresses
|
||||
(in network byte order).
|
||||
.I Rangetoa
|
||||
converts an address range back into ASCII,
|
||||
using dotted-decimal form for the addresses
|
||||
(the other reverse conversions are handled by
|
||||
.IR ipsec_addrtoa (3)
|
||||
and
|
||||
.IR ipsec_subnettoa (3)).
|
||||
.PP
|
||||
A single address can be any form acceptable to
|
||||
.IR ipsec_atoaddr (3):
|
||||
dotted decimal, DNS name, or hexadecimal number.
|
||||
A subnet
|
||||
specification uses the form \fInetwork\fB/\fImask\fR
|
||||
interpreted by
|
||||
.IR ipsec_atosubnet (3).
|
||||
.PP
|
||||
An address range is two
|
||||
.IR ipsec_atoaddr (3)
|
||||
addresses separated by a
|
||||
.B ...
|
||||
delimiter.
|
||||
If there are four dots rather than three, the first is taken as
|
||||
part of the begin address,
|
||||
e.g. for a complete DNS name which ends with
|
||||
.B .
|
||||
to suppress completion attempts.
|
||||
The begin address of a range must be
|
||||
less than or equal to the end address.
|
||||
.PP
|
||||
The
|
||||
.I srclen
|
||||
parameter of
|
||||
.I atoasr
|
||||
specifies the length of the ASCII string pointed to by
|
||||
.IR src ;
|
||||
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
|
||||
value of
|
||||
.B 0
|
||||
is taken to mean
|
||||
.BR strlen(src) .
|
||||
.PP
|
||||
The
|
||||
.I type
|
||||
parameter of
|
||||
.I atoasr
|
||||
must point to a
|
||||
.B char
|
||||
variable used to record which form was found.
|
||||
The
|
||||
.I addrs
|
||||
parameter must point to a two-element array of
|
||||
.B "struct in_addr"
|
||||
which receives the results.
|
||||
The values stored into
|
||||
.BR *type ,
|
||||
and the corresponding values in the array, are:
|
||||
.PP
|
||||
.ta 3c +2c +3c
|
||||
*type addrs[0] addrs[1]
|
||||
.sp 0.8
|
||||
address \&\fB'a'\fR address -
|
||||
.br
|
||||
subnet \&\fB's'\fR network mask
|
||||
.br
|
||||
range \&\fB'r'\fR begin end
|
||||
.PP
|
||||
The
|
||||
.I dstlen
|
||||
parameter of
|
||||
.I rangetoa
|
||||
specifies the size of the
|
||||
.I dst
|
||||
parameter;
|
||||
under no circumstances are more than
|
||||
.I dstlen
|
||||
bytes written to
|
||||
.IR dst .
|
||||
A result which will not fit is truncated.
|
||||
.I Dstlen
|
||||
can be zero, in which case
|
||||
.I dst
|
||||
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
|
||||
header file defines a constant,
|
||||
.BR RANGETOA_BUF ,
|
||||
which is the size of a buffer just large enough for worst-case results.
|
||||
.PP
|
||||
The
|
||||
.I format
|
||||
parameter of
|
||||
.I rangetoa
|
||||
specifies what format is to be used for the conversion.
|
||||
The value
|
||||
.B 0
|
||||
(not the ASCII character
|
||||
.BR '0' ,
|
||||
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.
|
||||
.PP
|
||||
.I Atoasr
|
||||
returns NULL for success and
|
||||
a pointer to a string-literal error message for failure;
|
||||
see DIAGNOSTICS.
|
||||
.I Rangetoa
|
||||
returns
|
||||
.B 0
|
||||
for a failure, and otherwise
|
||||
always returns 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.
|
||||
.SH SEE ALSO
|
||||
ipsec_atoaddr(3), ipsec_atosubnet(3)
|
||||
.SH DIAGNOSTICS
|
||||
Fatal errors in
|
||||
.I atoasr
|
||||
are:
|
||||
empty input;
|
||||
error in
|
||||
.IR ipsec_atoaddr (3)
|
||||
or
|
||||
.IR ipsec_atosubnet (3)
|
||||
during conversion;
|
||||
begin address of range exceeds end address.
|
||||
.PP
|
||||
Fatal errors in
|
||||
.I rangetoa
|
||||
are:
|
||||
unknown format.
|
||||
.SH HISTORY
|
||||
Written for the FreeS/WAN project by Henry Spencer.
|
||||
.SH BUGS
|
||||
The restriction of 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.
|
||||
.PP
|
||||
The 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:
|
||||
.PP
|
||||
.RS
|
||||
.nf
|
||||
.B "const char *error;"
|
||||
.sp
|
||||
.B "error = atoasr( /* ... */ );"
|
||||
.B "if (error != NULL) {"
|
||||
.B " /* something went wrong */"
|
||||
.fi
|
||||
.RE
|
||||
Reference in New Issue
Block a user