1 files changed, 0 insertions, 217 deletions
diff --git a/src/libfreeswan/atosa.3 b/src/libfreeswan/atosa.3
deleted file mode 100644
index f57fcf1e9..000000000
--- a/src/libfreeswan/atosa.3
+++ /dev/null
@@ -1,217 +0,0 @@
-.TH IPSEC_ATOSA 3 "11 June 2001"
-.SH NAME
-ipsec atosa, satoa \- convert IPsec Security Association IDs to and from ASCII
-.SH SYNOPSIS
-.B "#include <freeswan.h>
-.sp
-.B "const char *atosa(const char *src, size_t srclen,"
-.ti +1c
-.B "struct sa_id *sa);
-.br
-.B "size_t satoa(struct sa_id sa, int format,"
-.ti +1c
-.B "char *dst, size_t dstlen);"
-.sp
-.B "struct sa_id {"
-.ti +1c
-.B "struct in_addr dst;"
-.ti +1c
-.B "ipsec_spi_t spi;"
-.ti +1c
-.B "int proto;"
-.br
-.B "};"
-.SH DESCRIPTION
-These functions are obsolete; see
-.IR ipsec_ttosa (3)
-for their replacements.
-.PP
-.I Atosa
-converts an ASCII Security Association (SA) specifier into an
-.B sa_id
-structure (containing
-a destination-host address
-in network byte order,
-an SPI number in network byte order, and
-a protocol code).
-.I Satoa
-does the reverse conversion, back to an ASCII SA specifier.
-.PP
-An SA is specified in ASCII with a mail-like syntax, e.g.
-.BR esp507@1.2.3.4 .
-An SA specifier contains
-a protocol prefix (currently
-.BR ah ,
-.BR esp ,
-or
-.BR tun ),
-an unsigned integer SPI number,
-and an IP address.
-The SPI number can be decimal or hexadecimal
-(with
-.B 0x
-prefix), as accepted by
-.IR ipsec_atoul (3).
-The IP address can be any form accepted by
-.IR ipsec_atoaddr (3),
-e.g. dotted-decimal address or DNS name.
-.PP
-As a special case, the SA specifier
-.B %passthrough
-signifies the special SA used to indicate that packets should be
-passed through unaltered.
-(At present, this is a synonym for
-.BR tun0x0@0.0.0.0 ,
-but that is subject to change without notice.)
-This form is known to both
-.I atosa
-and
-.IR satoa ,
-so the internal form of
-.B %passthrough
-is never visible.
-.PP
-The
-.B <freeswan.h>
-header file supplies the
-.B sa_id
-structure, as well as a data type
-.B ipsec_spi_t
-which is an unsigned 32-bit integer.
-(There is no consistency between kernel and user on what such a type
-is called, hence the header hides the differences.)
-.PP
-The protocol code uses the same numbers that IP does.
-For user convenience, given the difficulty in acquiring the exact set of
-protocol names used by the kernel,
-.B <freeswan.h>
-defines the names
-.BR SA_ESP ,
-.BR SA_AH ,
-and
-.B SA_IPIP
-to have the same values as the kernel names
-.BR IPPROTO_ESP ,
-.BR IPPROTO_AH ,
-and
-.BR IPPROTO_IPIP .
-.PP
-The
-.I srclen
-parameter of
-.I atosa
-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 dstlen
-parameter of
-.I satoa
-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 SATOA_BUF ,
-which is the size of a buffer just large enough for worst-case results.
-.PP
-The
-.I format
-parameter of
-.I satoa
-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
-(currently
-lowercase protocol prefix, lowercase hexadecimal SPI, dotted-decimal address).
-The value
-.B d
-causes the SPI to be generated in decimal instead.
-.PP
-.I Atosa
-returns
-.B NULL
-for success and
-a pointer to a string-literal error message for failure;
-see DIAGNOSTICS.
-.I Satoa
-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_atoul(3), ipsec_atoaddr(3), inet(3)
-.SH DIAGNOSTICS
-Fatal errors in
-.I atosa
-are:
-empty input;
-input too small to be a legal SA specifier;
-no
-.B @
-in input;
-unknown protocol prefix;
-conversion error in
-.I atoul
-or
-.IR atoaddr .
-.PP
-Fatal errors in
-.I satoa
-are:
-unknown format; unknown protocol code.
-.SH HISTORY
-Written for the FreeS/WAN project by Henry Spencer.
-.SH BUGS
-The
-.B tun
-protocol code is a FreeS/WANism which may eventually disappear.
-.PP
-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.
-.PP
-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:
-.PP
-.RS
-.nf
-.B "const char *error;"
-.sp
-.B "error = atoaddr( /* ... */ );"
-.B "if (error != NULL) {"
-.B "        /* something went wrong */"
-.fi
-.RE