freeswan/lib/atoasr.3

   1 .TH IPSEC_ATOASR 3 "11 June 2001"
   2 .\" RCSID $Id: atoasr.3,v 1.8 2001/06/11 23:08:00 henry Exp $
   3 .SH NAME
   4 ipsec atoasr \- convert ASCII to Internet address, subnet, or range
   5 .br
   6 ipsec rangetoa \- convert Internet address range to ASCII
   7 .SH SYNOPSIS
   8 .B "#include <freeswan.h>
   9 .sp
  10 .B "const char *atoasr(const char *src, size_t srclen,"
  11 .ti +1c
  12 .B "char *type, struct in_addr *addrs);"
  13 .br
  14 .B "size_t rangetoa(struct in_addr *addrs, int format,
  15 .ti +1c
  16 .B "char *dst, size_t dstlen);"
  17 .SH DESCRIPTION
  18 These functions are obsolete;
  19 there is no current equivalent,
  20 because so far they have not proved useful.
  21 .PP
  22 .I Atoasr
  23 converts an ASCII address, subnet, or address range
  24 into a suitable combination of binary addresses
  25 (in network byte order).
  26 .I Rangetoa
  27 converts an address range back into ASCII,
  28 using dotted-decimal form for the addresses
  29 (the other reverse conversions are handled by
  30 .IR ipsec_addrtoa (3)
  31 and
  32 .IR ipsec_subnettoa (3)).
  33 .PP
  34 A single address can be any form acceptable to
  35 .IR ipsec_atoaddr (3):
  36 dotted decimal, DNS name, or hexadecimal number.
  37 A subnet
  38 specification uses the form \fInetwork\fB/\fImask\fR
  39 interpreted by
  40 .IR ipsec_atosubnet (3).
  41 .PP
  42 An address range is two
  43 .IR ipsec_atoaddr (3)
  44 addresses separated by a
  45 .B ...
  46 delimiter.
  47 If there are four dots rather than three, the first is taken as
  48 part of the begin address,
  49 e.g. for a complete DNS name which ends with
  50 .B .
  51 to suppress completion attempts.
  52 The begin address of a range must be
  53 less than or equal to the end address.
  54 .PP
  55 The
  56 .I srclen
  57 parameter of
  58 .I atoasr
  59 specifies the length of the ASCII string pointed to by
  60 .IR src ;
  61 it is an error for there to be anything else
  62 (e.g., a terminating NUL) within that length.
  63 As a convenience for cases where an entire NUL-terminated string is
  64 to be converted,
  65 a
  66 .I srclen
  67 value of
  68 .B 0
  69 is taken to mean
  70 .BR strlen(src) .
  71 .PP
  72 The
  73 .I type
  74 parameter of
  75 .I atoasr
  76 must point to a
  77 .B char
  78 variable used to record which form was found.
  79 The
  80 .I addrs
  81 parameter must point to a two-element array of
  82 .B "struct in_addr"
  83 which receives the results.
  84 The values stored into
  85 .BR *type ,
  86 and the corresponding values in the array, are:
  87 .PP
  88 .ta 3c +2c +3c
  89         *type   addrs[0]        addrs[1]
  90 .sp 0.8
  91 address \&\fB'a'\fR     address -
  92 .br
  93 subnet  \&\fB's'\fR     network mask
  94 .br
  95 range   \&\fB'r'\fR     begin   end
  96 .PP
  97 The
  98 .I dstlen
  99 parameter of
 100 .I rangetoa
 101 specifies the size of the
 102 .I dst
 103 parameter;
 104 under no circumstances are more than
 105 .I dstlen
 106 bytes written to
 107 .IR dst .
 108 A result which will not fit is truncated.
 109 .I Dstlen
 110 can be zero, in which case
 111 .I dst
 112 need not be valid and no result is written,
 113 but the return value is unaffected;
 114 in all other cases, the (possibly truncated) result is NUL-terminated.
 115 The
 116 .I freeswan.h
 117 header file defines a constant,
 118 .BR RANGETOA_BUF ,
 119 which is the size of a buffer just large enough for worst-case results.
 120 .PP
 121 The
 122 .I format
 123 parameter of
 124 .I rangetoa
 125 specifies what format is to be used for the conversion.
 126 The value
 127 .B 0
 128 (not the ASCII character
 129 .BR '0' ,
 130 but a zero value)
 131 specifies a reasonable default,
 132 and is in fact the only format currently available.
 133 This parameter is a hedge against future needs.
 134 .PP
 135 .I Atoasr
 136 returns NULL for success and
 137 a pointer to a string-literal error message for failure;
 138 see DIAGNOSTICS.
 139 .I Rangetoa
 140 returns
 141 .B 0
 142 for a failure, and otherwise
 143 always returns the size of buffer which would
 144 be needed to
 145 accommodate the full conversion result, including terminating NUL;
 146 it is the caller's responsibility to check this against the size of
 147 the provided buffer to determine whether truncation has occurred.
 148 .SH SEE ALSO
 149 ipsec_atoaddr(3), ipsec_atosubnet(3)
 150 .SH DIAGNOSTICS
 151 Fatal errors in
 152 .I atoasr
 153 are:
 154 empty input;
 155 error in
 156 .IR ipsec_atoaddr (3)
 157 or
 158 .IR ipsec_atosubnet (3)
 159 during conversion;
 160 begin address of range exceeds end address.
 161 .PP
 162 Fatal errors in
 163 .I rangetoa
 164 are:
 165 unknown format.
 166 .SH HISTORY
 167 Written for the FreeS/WAN project by Henry Spencer.
 168 .SH BUGS
 169 The restriction of error reports to literal strings
 170 (so that callers don't need to worry about freeing them or copying them)
 171 does limit the precision of error reporting.
 172 .PP
 173 The error-reporting convention lends itself
 174 to slightly obscure code,
 175 because many readers will not think of NULL as signifying success.
 176 A good way to make it clearer is to write something like:
 177 .PP
 178 .RS
 179 .nf
 180 .B "const char *error;"
 181 .sp
 182 .B "error = atoasr( /* ... */ );"
 183 .B "if (error != NULL) {"
 184 .B "        /* something went wrong */"
 185 .fi
 186 .RE