linux/lib/libfreeswan/atoaddr.3

   1 .TH IPSEC_ATOADDR 3 "11 June 2001"
   2 .\" RCSID $Id: atoaddr.3,v 1.1 2004/03/15 20:35:25 as Exp $
   3 .SH NAME
   4 ipsec atoaddr, addrtoa \- convert Internet addresses to and from ASCII
   5 .br
   6 ipsec atosubnet, subnettoa \- convert subnet/mask ASCII form to and from addresses
   7 .SH SYNOPSIS
   8 .B "#include <freeswan.h>
   9 .sp
  10 .B "const char *atoaddr(const char *src, size_t srclen,"
  11 .ti +1c
  12 .B "struct in_addr *addr);"
  13 .br
  14 .B "size_t addrtoa(struct in_addr addr, int format,"
  15 .ti +1c
  16 .B "char *dst, size_t dstlen);"
  17 .sp
  18 .B "const char *atosubnet(const char *src, size_t srclen,"
  19 .ti +1c
  20 .B "struct in_addr *addr, struct in_addr *mask);"
  21 .br
  22 .B "size_t subnettoa(struct in_addr addr, struct in_addr mask,"
  23 .ti +1c
  24 .B "int format, char *dst, size_t dstlen);"
  25 .SH DESCRIPTION
  26 These functions are obsolete; see
  27 .IR ipsec_ttoaddr (3)
  28 for their replacements.
  29 .PP
  30 .I Atoaddr
  31 converts an ASCII name or dotted-decimal address into a binary address
  32 (in network byte order).
  33 .I Addrtoa
  34 does the reverse conversion, back to an ASCII dotted-decimal address.
  35 .I Atosubnet
  36 and
  37 .I subnettoa
  38 do likewise for the ``address/mask'' ASCII form used to write a
  39 specification of a subnet.
  40 .PP
  41 An address is specified in ASCII as a
  42 dotted-decimal address (e.g.
  43 .BR 1.2.3.4 ),
  44 an eight-digit network-order hexadecimal number with the usual C prefix (e.g.
  45 .BR 0x01020304 ,
  46 which is synonymous with
  47 .BR 1.2.3.4 ),
  48 an eight-digit host-order hexadecimal number with a
  49 .B 0h
  50 prefix (e.g.
  51 .BR 0h01020304 ,
  52 which is synonymous with
  53 .B 1.2.3.4
  54 on a big-endian host and
  55 .B 4.3.2.1
  56 on a little-endian host),
  57 a DNS name to be looked up via
  58 .IR gethostbyname (3),
  59 or an old-style network name to be looked up via
  60 .IR getnetbyname (3).
  61 .PP
  62 A dotted-decimal address may be incomplete, in which case
  63 ASCII-to-binary conversion implicitly appends
  64 as many instances of
  65 .B .0
  66 as necessary to bring it up to four components.
  67 The components of a dotted-decimal address are always taken as
  68 decimal, and leading zeros are ignored.
  69 For example,
  70 .B 10
  71 is synonymous with
  72 .BR 10.0.0.0 ,
  73 and
  74 .B 128.009.000.032
  75 is synonymous with
  76 .BR 128.9.0.32
  77 (the latter example is verbatim from RFC 1166).
  78 The result of
  79 .I addrtoa
  80 is always complete and does not contain leading zeros.
  81 .PP
  82 The letters in
  83 a hexadecimal address may be uppercase or lowercase or any mixture thereof.
  84 Use of hexadecimal addresses is
  85 .B strongly
  86 .BR discouraged ;
  87 they are included only to save hassles when dealing with
  88 the handful of perverted programs which already print
  89 network addresses in hexadecimal.
  90 .PP
  91 DNS names may be complete (optionally terminated with a ``.'')
  92 or incomplete, and are looked up as specified by local system configuration
  93 (see
  94 .IR resolver (5)).
  95 The
  96 .I h_addr
  97 value returned by
  98 .IR gethostbyname (3)
  99 is used,
 100 so with current DNS implementations,
 101 the result when the name corresponds to more than one address is
 102 difficult to predict.
 103 Name lookup resorts to
 104 .IR getnetbyname (3)
 105 only if
 106 .IR gethostbyname (3)
 107 fails.
 108 .PP
 109 A subnet specification is of the form \fInetwork\fB/\fImask\fR.
 110 The
 111 .I network
 112 and
 113 .I mask
 114 can be any form acceptable to
 115 .IR atoaddr .
 116 In addition, the
 117 .I mask
 118 can be a decimal integer (leading zeros ignored) giving a bit count,
 119 in which case
 120 it stands for a mask with that number of high bits on and all others off
 121 (e.g.,
 122 .B 24
 123 means
 124 .BR 255.255.255.0 ).
 125 In any case, the mask must be contiguous
 126 (a sequence of high bits on and all remaining low bits off).
 127 As a special case, the subnet specification
 128 .B %default
 129 is a synonym for
 130 .BR 0.0.0.0/0 .
 131 .PP
 132 .I Atosubnet
 133 ANDs the mask with the address before returning,
 134 so that any non-network bits in the address are turned off
 135 (e.g.,
 136 .B 10.1.2.3/24
 137 is synonymous with
 138 .BR 10.1.2.0/24 ).
 139 .I Subnettoa
 140 generates the decimal-integer-bit-count
 141 form of the mask,
 142 with no leading zeros,
 143 unless the mask is non-contiguous.
 144 .PP
 145 The
 146 .I srclen
 147 parameter of
 148 .I atoaddr
 149 and
 150 .I atosubnet
 151 specifies the length of the ASCII string pointed to by
 152 .IR src ;
 153 it is an error for there to be anything else
 154 (e.g., a terminating NUL) within that length.
 155 As a convenience for cases where an entire NUL-terminated string is
 156 to be converted,
 157 a
 158 .I srclen
 159 value of
 160 .B 0
 161 is taken to mean
 162 .BR strlen(src) .
 163 .PP
 164 The
 165 .I dstlen
 166 parameter of
 167 .I addrtoa
 168 and
 169 .I subnettoa
 170 specifies the size of the
 171 .I dst
 172 parameter;
 173 under no circumstances are more than
 174 .I dstlen
 175 bytes written to
 176 .IR dst .
 177 A result which will not fit is truncated.
 178 .I Dstlen
 179 can be zero, in which case
 180 .I dst
 181 need not be valid and no result is written,
 182 but the return value is unaffected;
 183 in all other cases, the (possibly truncated) result is NUL-terminated.
 184 The
 185 .I freeswan.h
 186 header file defines constants,
 187 .B ADDRTOA_BUF
 188 and
 189 .BR SUBNETTOA_BUF ,
 190 which are the sizes of buffers just large enough for worst-case results.
 191 .PP
 192 The
 193 .I format
 194 parameter of
 195 .I addrtoa
 196 and
 197 .I subnettoa
 198 specifies what format is to be used for the conversion.
 199 The value
 200 .B 0
 201 (not the ASCII character
 202 .BR '0' ,
 203 but a zero value)
 204 specifies a reasonable default,
 205 and is in fact the only format currently available.
 206 This parameter is a hedge against future needs.
 207 .PP
 208 The ASCII-to-binary functions return NULL for success and
 209 a pointer to a string-literal error message for failure;
 210 see DIAGNOSTICS.
 211 The binary-to-ASCII functions return
 212 .B 0
 213 for a failure, and otherwise
 214 always return the size of buffer which would
 215 be needed to
 216 accommodate the full conversion result, including terminating NUL;
 217 it is the caller's responsibility to check this against the size of
 218 the provided buffer to determine whether truncation has occurred.
 219 .SH SEE ALSO
 220 inet(3)
 221 .SH DIAGNOSTICS
 222 Fatal errors in
 223 .I atoaddr
 224 are:
 225 empty input;
 226 attempt to allocate temporary storage for a very long name failed;
 227 name lookup failed;
 228 syntax error in dotted-decimal form;
 229 dotted-decimal component too large to fit in 8 bits.
 230 .PP
 231 Fatal errors in
 232 .I atosubnet
 233 are:
 234 no
 235 .B /
 236 in
 237 .IR src ;
 238 .I atoaddr
 239 error in conversion of
 240 .I network
 241 or
 242 .IR mask ;
 243 bit-count mask too big;
 244 mask non-contiguous.
 245 .PP
 246 Fatal errors in
 247 .I addrtoa
 248 and
 249 .I subnettoa
 250 are:
 251 unknown format.
 252 .SH HISTORY
 253 Written for the FreeS/WAN project by Henry Spencer.
 254 .SH BUGS
 255 The interpretation of incomplete dotted-decimal addresses
 256 (e.g.
 257 .B 10/24
 258 means
 259 .BR 10.0.0.0/24 )
 260 differs from that of some older conversion
 261 functions, e.g. those of
 262 .IR inet (3).
 263 The behavior of the older functions has never been
 264 particularly consistent or particularly useful.
 265 .PP
 266 Ignoring leading zeros in dotted-decimal components and bit counts
 267 is arguably the most useful behavior in this application,
 268 but it might occasionally cause confusion with the historical use of leading
 269 zeros to denote octal numbers.
 270 .PP
 271 It is barely possible that somebody, somewhere,
 272 might have a legitimate use for non-contiguous subnet masks.
 273 .PP
 274 .IR Getnetbyname (3)
 275 is a historical dreg.
 276 .PP
 277 The restriction of ASCII-to-binary error reports to literal strings
 278 (so that callers don't need to worry about freeing them or copying them)
 279 does limit the precision of error reporting.
 280 .PP
 281 The ASCII-to-binary error-reporting convention lends itself
 282 to slightly obscure code,
 283 because many readers will not think of NULL as signifying success.
 284 A good way to make it clearer is to write something like:
 285 .PP
 286 .RS
 287 .nf
 288 .B "const char *error;"
 289 .sp
 290 .B "error = atoaddr( /* ... */ );"
 291 .B "if (error != NULL) {"
 292 .B "        /* something went wrong */"
 293 .fi
 294 .RE