1 files changed, 0 insertions, 374 deletions
diff --git a/src/libfreeswan/ttoaddr.3 b/src/libfreeswan/ttoaddr.3
deleted file mode 100644
index d43d2b16f..000000000
--- a/src/libfreeswan/ttoaddr.3
+++ /dev/null
@@ -1,374 +0,0 @@
-.TH IPSEC_TTOADDR 3 "28 Sept 2001"
-.SH NAME
-ipsec ttoaddr, tnatoaddr, addrtot \- convert Internet addresses to and from text
-.br
-ipsec ttosubnet, subnettot \- convert subnet/mask text form to and from addresses
-.SH SYNOPSIS
-.B "#include <freeswan.h>
-.sp
-.B "const char *ttoaddr(const char *src, size_t srclen,"
-.ti +1c
-.B "int af, ip_address *addr);"
-.br
-.B "const char *tnatoaddr(const char *src, size_t srclen,"
-.ti +1c
-.B "int af, ip_address *addr);"
-.br
-.B "size_t addrtot(const ip_address *addr, int format,"
-.ti +1c
-.B "char *dst, size_t dstlen);"
-.sp
-.B "const char *ttosubnet(const char *src, size_t srclen,"
-.ti +1c
-.B "int af, ip_subnet *dst);"
-.br
-.B "size_t subnettot(const ip_subnet *sub, int format,"
-.ti +1c
-.B "char *dst, size_t dstlen);"
-.SH DESCRIPTION
-.I Ttoaddr
-converts a text-string name or numeric address into a binary address
-(in network byte order).
-.I Tnatoaddr
-does the same conversion,
-but the only text forms it accepts are
-the ``official'' forms of
-numeric address (dotted-decimal for IPv4, colon-hex for IPv6).
-.I Addrtot
-does the reverse conversion, from binary address back to a text form.
-.I Ttosubnet
-and
-.I subnettot
-do likewise for the ``address/mask'' form used to write a
-specification of a subnet.
-.PP
-An IPv4 address is specified in text as a
-dotted-decimal address (e.g.
-.BR 1.2.3.4 ),
-an eight-digit network-order hexadecimal number with the usual C prefix (e.g.
-.BR 0x01020304 ,
-which is synonymous with
-.BR 1.2.3.4 ),
-an eight-digit host-order hexadecimal number with a
-.B 0h
-prefix (e.g.
-.BR 0h01020304 ,
-which is synonymous with
-.B 1.2.3.4
-on a big-endian host and
-.B 4.3.2.1
-on a little-endian host),
-a DNS name to be looked up via
-.IR getaddrinfo (3),
-or an old-style network name to be looked up via
-.IR getnetbyname (3).
-.PP
-A dotted-decimal address may be incomplete, in which case
-text-to-binary conversion implicitly appends
-as many instances of
-.B .0
-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
-is synonymous with
-.BR 10.0.0.0 ,
-and
-.B 128.009.000.032
-is synonymous with
-.BR 128.9.0.32
-(the latter example is verbatim from RFC 1166).
-The result of applying
-.I addrtot
-to an IPv4 address is always complete and does not contain leading zeros.
-.PP
-Use of hexadecimal addresses is
-.B strongly
-.BR discouraged ;
-they are included only to save hassles when dealing with
-the handful of perverted programs which already print 
-network addresses in hexadecimal.
-.PP
-An IPv6 address is specified in text with
-colon-hex notation (e.g.
-.BR 0:56:78ab:22:33:44:55:66 ),
-colon-hex with
-.B ::
-abbreviating at most one subsequence of multiple zeros (e.g.
-.BR 99:ab::54:068 ,
-which is synonymous with
-.BR 99:ab:0:0:0:0:54:68 ),
-or a DNS name to be looked up via
-.IR getaddrinfo (3).
-The result of applying
-.I addrtot
-to an IPv6 address will use
-.B ::
-abbreviation if possible,
-and will not contain leading zeros.
-.PP
-The letters in hexadecimal
-may be uppercase or lowercase or any mixture thereof.
-.PP
-DNS names may be complete (optionally terminated with a ``.'')
-or incomplete, and are looked up as specified by local system configuration
-(see
-.IR resolver (5)).
-The first value returned by
-.IR getaddrinfo (3)
-is used,
-so with current DNS implementations,
-the result when the name corresponds to more than one address is
-difficult to predict.
-IPv4 name lookup resorts to
-.IR getnetbyname (3)
-only if
-.IR getaddrinfo (3)
-fails.
-.PP
-A subnet specification is of the form \fInetwork\fB/\fImask\fR.
-The
-.I network
-and
-.I mask
-can be any form acceptable to
-.IR ttoaddr .
-In addition, and preferably, the
-.I mask
-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
-in IPv4 means
-.BR 255.255.255.0 ).
-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
-is a synonym for
-.B 0.0.0.0/0
-or
-.B ::/0
-in IPv4 or IPv6 respectively.
-.PP
-.I Ttosubnet
-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
-is synonymous with
-.BR 10.1.2.0/24 ).
-.I Subnettot
-always generates the decimal-integer-bit-count
-form of the mask,
-with no leading zeros.
-.PP
-The
-.I srclen
-parameter of
-.I ttoaddr
-and
-.I ttosubnet
-specifies the length of the text 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 af
-parameter of
-.I ttoaddr
-and
-.I ttosubnet
-specifies the address family of interest.
-It should be either
-.B AF_INET
-or
-.BR AF_INET6 .
-.PP
-The
-.I dstlen
-parameter of
-.I addrtot
-and
-.I subnettot
-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 constants,
-.B ADDRTOT_BUF
-and
-.BR SUBNETTOT_BUF ,
-which are the sizes of buffers just large enough for worst-case results.
-.PP
-The
-.I format
-parameter of
-.I addrtot
-and
-.I subnettot
-specifies what format is to be used for the conversion.
-The value
-.B 0
-(not the character
-.BR '0' ,
-but a zero value)
-specifies a reasonable default,
-and is in fact the only format currently available in
-.IR subnettot .
-.I Addrtot
-also accepts format values
-.B 'r'
-(signifying a text form suitable for DNS reverse lookups,
-e.g.
-.B 4.3.2.1.IN-ADDR.ARPA.
-for IPv4 and
-RFC 2874 format for IPv6),
-and
-.B 'R'
-(signifying an alternate reverse-lookup form,
-an error for IPv4 and RFC 1886 format for IPv6).
-Reverse-lookup names always end with a ``.''.
-.PP
-The text-to-binary functions return NULL for success and
-a pointer to a string-literal error message for failure;
-see DIAGNOSTICS.
-The binary-to-text functions return
-.B 0
-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.
-.SH SEE ALSO
-inet(3)
-.SH DIAGNOSTICS
-Fatal errors in
-.I ttoaddr
-are:
-empty input;
-unknown address family;
-attempt to allocate temporary storage for a very long name failed;
-name lookup failed;
-syntax error in dotted-decimal or colon-hex form;
-dotted-decimal or colon-hex component too large.
-.PP
-Fatal errors in
-.I ttosubnet
-are:
-no
-.B /
-in
-.IR src ;
-.I ttoaddr
-error in conversion of
-.I network
-or
-.IR mask ;
-bit-count mask too big;
-mask non-contiguous.
-.PP
-Fatal errors in
-.I addrtot
-and
-.I subnettot
-are:
-unknown format.
-.SH HISTORY
-Written for the FreeS/WAN project by Henry Spencer.
-.SH BUGS
-The interpretation of incomplete dotted-decimal addresses
-(e.g.
-.B 10/24
-means
-.BR 10.0.0.0/24 )
-differs from that of some older conversion
-functions, e.g. those of
-.IR inet (3).
-The behavior of the older functions has never been
-particularly consistent or particularly useful.
-.PP
-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.
-.PP
-.I Ttoaddr
-does not support the mixed colon-hex-dotted-decimal
-convention used to embed an IPv4 address in an IPv6 address.
-.PP
-.I Addrtot
-always uses the
-.B ::
-abbreviation (which can appear only once in an address) for the
-.I first
-sequence of multiple zeros in an IPv6 address.
-One can construct addresses (unlikely ones) in which this is suboptimal.
-.PP
-.I Addrtot
-.B 'r'
-conversion of an IPv6 address uses lowercase hexadecimal,
-not the uppercase used in RFC 2874's examples.
-It takes careful reading of RFCs 2874, 2673, and 2234 to realize
-that lowercase is technically legitimate here,
-and there may be software which botches this
-and hence would have trouble with lowercase hex.
-.PP
-Possibly
-.I subnettot
-ought to recognize the
-.B %default
-case and generate that string as its output.
-Currently it doesn't.
-.PP
-It is barely possible that somebody, somewhere,
-might have a legitimate use for non-contiguous subnet masks.
-.PP
-.IR Getnetbyname (3)
-is a historical dreg.
-.PP
-.I Tnatoaddr
-probably should enforce completeness of dotted-decimal addresses.
-.PP
-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 = ttoaddr( /* ... */ );"
-.B "if (error != NULL) {"
-.B "        /* something went wrong */"
-.fi
-.RE