1 files changed, 0 insertions, 287 deletions
diff --git a/src/libfreeswan/ttosa.3 b/src/libfreeswan/ttosa.3
deleted file mode 100644
index f9ea36a09..000000000
--- a/src/libfreeswan/ttosa.3
+++ /dev/null
@@ -1,287 +0,0 @@
-.TH IPSEC_TTOSA 3 "26 Nov 2001"
-.SH NAME
-ipsec ttosa, satot \- convert IPsec Security Association IDs to and from text
-.br
-ipsec initsaid \- initialize an SA ID
-.SH SYNOPSIS
-.B "#include <freeswan.h>
-.sp
-.B "typedef struct {"
-.ti +1c
-.B "ip_address dst;"
-.ti +1c
-.B "ipsec_spi_t spi;"
-.ti +1c
-.B "int proto;"
-.br
-.B "} ip_said;"
-.sp
-.B "const char *ttosa(const char *src, size_t srclen,"
-.ti +1c
-.B "ip_said *sa);
-.br
-.B "size_t satot(const ip_said *sa, int format,"
-.ti +1c
-.B "char *dst, size_t dstlen);"
-.br
-.B "void initsaid(const ip_address *addr, ipsec_spi_t spi,"
-.ti +1c
-.B "int proto, ip_said *dst);"
-.SH DESCRIPTION
-.I Ttosa
-converts an ASCII Security Association (SA) specifier into an
-.B ip_said
-structure (containing
-a destination-host address
-in network byte order,
-an SPI number in network byte order, and
-a protocol code).
-.I Satot
-does the reverse conversion, back to a text SA specifier.
-.I Initsaid
-initializes an
-.B ip_said
-from separate items of information.
-.PP
-An SA is specified in text with a mail-like syntax, e.g.
-.BR esp.5a7@1.2.3.4 .
-An SA specifier contains
-a protocol prefix (currently
-.BR ah ,
-.BR esp ,
-.BR tun ,
-.BR comp ,
-or
-.BR int ),
-a single character indicating the address family
-.RB ( .
-for IPv4,
-.B :
-for IPv6),
-an unsigned integer SPI number in hexadecimal (with no
-.B 0x
-prefix),
-and an IP address.
-The IP address can be any form accepted by
-.IR ipsec_ttoaddr (3),
-e.g. dotted-decimal IPv4 address,
-colon-hex IPv6 address,
-or DNS name.
-.PP
-As a special case, the SA specifier
-.B %passthrough4
-or
-.B %passthrough6
-signifies the special SA used to indicate that packets should be
-passed through unaltered.
-(At present, these are synonyms for
-.B tun.0@0.0.0.0
-and
-.B tun:0@::
-respectively,
-but that is subject to change without notice.)
-.B %passthrough
-is a historical synonym for
-.BR %passthrough4 . 
-These forms are known to both
-.I ttosa
-and
-.IR satot ,
-so the internal representation is never visible.
-.PP
-Similarly, the SA specifiers
-.BR %pass ,
-.BR %drop ,
-.BR %reject ,
-.BR %hold ,
-.BR %trap ,
-and
-.BR %trapsubnet
-signify special ``magic'' SAs used to indicate that packets should be
-passed, dropped, rejected (dropped with ICMP notification),
-held,
-and trapped (sent up to
-.IR ipsec_pluto (8),
-with either of two forms of
-.B %hold
-automatically installed)
-respectively.
-These forms too are known to both routines,
-so the internal representation of the magic SAs should never be visible.
-.PP
-The
-.B <freeswan.h>
-header file supplies the
-.B ip_said
-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 ,
-.BR SA_IPIP ,
-and
-.BR SA_COMP
-to have the same values as the kernel names
-.BR IPPROTO_ESP ,
-.BR IPPROTO_AH ,
-.BR IPPROTO_IPIP ,
-and
-.BR IPPROTO_COMP .
-.PP
-.B <freeswan.h>
-also defines
-.BR SA_INT
-to have the value
-.BR 61
-(reserved by IANA for ``any host internal protocol'')
-and
-.BR SPI_PASS ,
-.BR SPI_DROP ,
-.BR SPI_REJECT ,
-.BR SPI_HOLD ,
-and
-.B SPI_TRAP
-to have the values 256-260 (in \fIhost\fR byte order) respectively.
-These are used in constructing the magic SAs
-(which always have address
-.BR 0.0.0.0 ).
-.PP
-If
-.I satot
-encounters an unknown protocol code, e.g. 77,
-it yields output using a prefix
-showing the code numerically, e.g. ``unk77''.
-This form is
-.I not
-recognized by
-.IR ttosa .
-.PP
-The
-.I srclen
-parameter of
-.I ttosa
-specifies the length of the 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 satot
-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
-.B <freeswan.h>
-header file defines a constant,
-.BR SATOT_BUF ,
-which is the size of a buffer just large enough for worst-case results.
-.PP
-The
-.I format
-parameter of
-.I satot
-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 or colon-hex address).
-The value
-.B 'f'
-is similar except that the SPI is padded with
-.BR 0 s
-to a fixed 32-bit width, to ease aligning displayed tables.
-.PP
-.I Ttosa
-returns
-.B NULL
-for success and
-a pointer to a string-literal error message for failure;
-see DIAGNOSTICS.
-.I Satot
-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.
-.PP
-There is also, temporarily, support for some obsolete
-forms of SA specifier which lack the address-family indicator.
-.SH SEE ALSO
-ipsec_ttoul(3), ipsec_ttoaddr(3), ipsec_samesaid(3), inet(3)
-.SH DIAGNOSTICS
-Fatal errors in
-.I ttosa
-are:
-empty input;
-input too small to be a legal SA specifier;
-no
-.B @
-in input;
-unknown protocol prefix;
-conversion error in
-.I ttoul
-or
-.IR ttoaddr .
-.PP
-Fatal errors in
-.I satot
-are:
-unknown format.
-.SH HISTORY
-Written for the FreeS/WAN project by Henry Spencer.
-.SH BUGS
-The restriction of text-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 text-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 = ttosa( /* ... */ );"
-.B "if (error != NULL) {"
-.B "        /* something went wrong */"
-.fi
-.RE