292 lines
7.1 KiB
Groff
292 lines
7.1 KiB
Groff
.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
|