summaryrefslogtreecommitdiff
path: root/src/libfreeswan/atoaddr.3
diff options
context:
space:
mode:
authorYves-Alexis Perez <corsac@debian.org>2013-01-02 14:18:20 +0100
committerYves-Alexis Perez <corsac@debian.org>2013-01-02 14:18:20 +0100
commitc1343b3278cdf99533b7902744d15969f9d6fdc1 (patch)
treed5ed3dc5677a59260ec41cd39bb284d3e94c91b3 /src/libfreeswan/atoaddr.3
parentb34738ed08c2227300d554b139e2495ca5da97d6 (diff)
downloadvyos-strongswan-c1343b3278cdf99533b7902744d15969f9d6fdc1.tar.gz
vyos-strongswan-c1343b3278cdf99533b7902744d15969f9d6fdc1.zip
Imported Upstream version 5.0.1
Diffstat (limited to 'src/libfreeswan/atoaddr.3')
-rw-r--r--src/libfreeswan/atoaddr.3291
1 files changed, 0 insertions, 291 deletions
diff --git a/src/libfreeswan/atoaddr.3 b/src/libfreeswan/atoaddr.3
deleted file mode 100644
index 10da2691c..000000000
--- a/src/libfreeswan/atoaddr.3
+++ /dev/null
@@ -1,291 +0,0 @@
-.TH IPSEC_ATOADDR 3 "11 June 2001"
-.SH NAME
-ipsec atoaddr, addrtoa \- convert Internet addresses to and from ASCII
-.br
-ipsec atosubnet, subnettoa \- convert subnet/mask ASCII form to and from addresses
-.SH SYNOPSIS
-.B "#include <freeswan.h>
-.sp
-.B "const char *atoaddr(const char *src, size_t srclen,"
-.ti +1c
-.B "struct in_addr *addr);"
-.br
-.B "size_t addrtoa(struct in_addr addr, int format,"
-.ti +1c
-.B "char *dst, size_t dstlen);"
-.sp
-.B "const char *atosubnet(const char *src, size_t srclen,"
-.ti +1c
-.B "struct in_addr *addr, struct in_addr *mask);"
-.br
-.B "size_t subnettoa(struct in_addr addr, struct in_addr mask,"
-.ti +1c
-.B "int format, char *dst, size_t dstlen);"
-.SH DESCRIPTION
-These functions are obsolete; see
-.IR ipsec_ttoaddr (3)
-for their replacements.
-.PP
-.I Atoaddr
-converts an ASCII name or dotted-decimal address into a binary address
-(in network byte order).
-.I Addrtoa
-does the reverse conversion, back to an ASCII dotted-decimal address.
-.I Atosubnet
-and
-.I subnettoa
-do likewise for the ``address/mask'' ASCII form used to write a
-specification of a subnet.
-.PP
-An address is specified in ASCII 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
-ASCII-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
-.I addrtoa
-is always complete and does not contain leading zeros.
-.PP
-The letters in
-a hexadecimal address may be uppercase or lowercase or any mixture thereof.
-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
-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.
-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 atoaddr .
-In addition, 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
-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
-.BR 0.0.0.0/0 .
-.PP
-.I Atosubnet
-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 Subnettoa
-generates the decimal-integer-bit-count
-form of the mask,
-with no leading zeros,
-unless the mask is non-contiguous.
-.PP
-The
-.I srclen
-parameter of
-.I atoaddr
-and
-.I atosubnet
-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 addrtoa
-and
-.I subnettoa
-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 ADDRTOA_BUF
-and
-.BR SUBNETTOA_BUF ,
-which are the sizes of buffers just large enough for worst-case results.
-.PP
-The
-.I format
-parameter of
-.I addrtoa
-and
-.I subnettoa
-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
-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
-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 atoaddr
-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.
-.PP
-Fatal errors in
-.I atosubnet
-are:
-no
-.B /
-in
-.IR src ;
-.I atoaddr
-error in conversion of
-.I network
-or
-.IR mask ;
-bit-count mask too big;
-mask non-contiguous.
-.PP
-Fatal errors in
-.I addrtoa
-and
-.I subnettoa
-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
-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
-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