diff options
Diffstat (limited to 'src/libfreeswan/ttoaddr.3')
| -rw-r--r-- | src/libfreeswan/ttoaddr.3 | 377 |
1 files changed, 377 insertions, 0 deletions
diff --git a/src/libfreeswan/ttoaddr.3 b/src/libfreeswan/ttoaddr.3 new file mode 100644 index 000000000..5bf48d4b2 --- /dev/null +++ b/src/libfreeswan/ttoaddr.3 @@ -0,0 +1,377 @@ +.TH IPSEC_TTOADDR 3 "28 Sept 2001" +.\" RCSID $Id: ttoaddr.3,v 1.1 2004/03/15 20:35:26 as Exp $ +.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 gethostbyname (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 gethostbyname (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 +.I h_addr +value returned by +.IR gethostbyname2 (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 gethostbyname2 (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 |