ipsec atoasr − convert ASCII to Internet address,
subnet, or range |
#include <freeswan.h> const char *atoasr(const char *src, size_t srclen, |
char *type, struct in_addr *addrs); |
size_t rangetoa(struct in_addr *addrs, int format, |
char *dst, size_t dstlen); |
These functions are obsolete; there is no current equivalent, because so far they have not proved useful. Atoasr converts an ASCII address, subnet, or address range into a suitable combination of binary addresses (in network byte order). Rangetoa converts an address range back into ASCII, using dotted-decimal form for the addresses (the other reverse conversions are handled by ipsec_addrtoa(3) and ipsec_subnettoa(3)). A single address can be any form acceptable to ipsec_atoaddr(3): dotted decimal, DNS name, or hexadecimal number. A subnet specification uses the form network/mask interpreted by ipsec_atosubnet(3). An address range is two ipsec_atoaddr(3) addresses separated by a ... delimiter. If there are four dots rather than three, the first is taken as part of the begin address, e.g. for a complete DNS name which ends with . to suppress completion attempts. The begin address of a range must be less than or equal to the end address. The srclen parameter of atoasr specifies the length of the ASCII string pointed to by 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 srclen value of 0 is taken to mean strlen(src). The type parameter of atoasr must point to a char variable used to record which form was found. The addrs parameter must point to a two-element array of struct in_addr which receives the results. The values stored into *type, and the corresponding values in the array, are: |
*type addrs[0] addrs[1]
address |
’a’ |
address |
- |
|
subnet |
’s’ |
network |
mask |
|
range |
’r’ |
begin |
end |
The dstlen parameter of rangetoa specifies the size of the dst parameter; under no circumstances are more than dstlen bytes written to dst. A result which will not fit is truncated. Dstlen can be zero, in which case 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 freeswan.h header file defines a constant, RANGETOA_BUF, which is the size of a buffer just large enough for worst-case results. The format parameter of rangetoa specifies what format is to be used for the conversion. The value 0 (not the ASCII character ’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. Atoasr returns NULL for success and a pointer to a string-literal error message for failure; see DIAGNOSTICS. Rangetoa returns 0 for a failure, and otherwise always returns 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. |
Fatal errors in atoasr are: empty input; error in ipsec_atoaddr(3) or ipsec_atosubnet(3) during conversion; begin address of range exceeds end address. Fatal errors in rangetoa are: unknown format. |
Written for the FreeS/WAN project by Henry Spencer. |
The restriction of 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. The 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: |
const char *error; error = atoasr( /* ... */ ); if (error != NULL) { /* something went wrong */ |