diff options
Diffstat (limited to 'src/libfreeswan/atoaddr.3')
-rw-r--r-- | src/libfreeswan/atoaddr.3 | 291 |
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 |