freeswan/doc/manpage.d/ipsec_subnettoa.3.html

   1 Content-type: text/html
   2
   3 <HTML><HEAD><TITLE>Manpage of IPSEC_ATOADDR</TITLE>
   4 </HEAD><BODY>
   5 <H1>IPSEC_ATOADDR</H1>
   6 Section: C Library Functions (3)<BR>Updated: 11 June 2001<BR><A HREF="#index">Index</A>
   7 <A HREF="http://localhost/cgi-bin/man/man2html">Return to Main Contents</A><HR>
   8
   9
  10 <A NAME="lbAB">&nbsp;</A>
  11 <H2>NAME</H2>
  12
  13 ipsec atoaddr, addrtoa - convert Internet addresses to and from ASCII
  14 <BR>
  15
  16 ipsec atosubnet, subnettoa - convert subnet/mask ASCII form to and from addresses
  17 <A NAME="lbAC">&nbsp;</A>
  18 <H2>SYNOPSIS</H2>
  19
  20 <B>#include &lt;<A HREF="file:/usr/include/freeswan.h">freeswan.h</A>&gt;</B>
  21
  22 <P>
  23 <B>const char *atoaddr(const char *src, size_t srclen,</B>
  24
  25 <BR>
  26 &nbsp;
  27 <B>struct in_addr *addr);</B>
  28
  29 <BR>
  30
  31 <B>size_t addrtoa(struct in_addr addr, int format,</B>
  32
  33 <BR>
  34 &nbsp;
  35 <B>char *dst, size_t dstlen);</B>
  36
  37 <P>
  38 <B>const char *atosubnet(const char *src, size_t srclen,</B>
  39
  40 <BR>
  41 &nbsp;
  42 <B>struct in_addr *addr, struct in_addr *mask);</B>
  43
  44 <BR>
  45
  46 <B>size_t subnettoa(struct in_addr addr, struct in_addr mask,</B>
  47
  48 <BR>
  49 &nbsp;
  50 <B>int format, char *dst, size_t dstlen);</B>
  51
  52 <A NAME="lbAD">&nbsp;</A>
  53 <H2>DESCRIPTION</H2>
  54
  55 These functions are obsolete; see
  56 <I><A HREF="ipsec_ttoaddr.3.html">ipsec_ttoaddr</A></I>(3)
  57
  58 for their replacements.
  59 <P>
  60
  61 <I>Atoaddr</I>
  62
  63 converts an ASCII name or dotted-decimal address into a binary address
  64 (in network byte order).
  65 <I>Addrtoa</I>
  66
  67 does the reverse conversion, back to an ASCII dotted-decimal address.
  68 <I>Atosubnet</I>
  69
  70 and
  71 <I>subnettoa</I>
  72
  73 do likewise for the ``address/mask'' ASCII form used to write a
  74 specification of a subnet.
  75 <P>
  76
  77 An address is specified in ASCII as a
  78 dotted-decimal address (e.g.
  79 <B>1.2.3.4</B>),
  80
  81 an eight-digit network-order hexadecimal number with the usual C prefix (e.g.
  82 <B>0x01020304</B>,
  83
  84 which is synonymous with
  85 <B>1.2.3.4</B>),
  86
  87 an eight-digit host-order hexadecimal number with a
  88 <B>0h</B>
  89
  90 prefix (e.g.
  91 <B>0h01020304</B>,
  92
  93 which is synonymous with
  94 <B>1.2.3.4</B>
  95
  96 on a big-endian host and
  97 <B>4.3.2.1</B>
  98
  99 on a little-endian host),
 100 a DNS name to be looked up via
 101 <I><A HREF="gethostbyname.3.html">gethostbyname</A></I>(3),
 102
 103 or an old-style network name to be looked up via
 104 <I><A HREF="getnetbyname.3.html">getnetbyname</A></I>(3).
 105
 106 <P>
 107
 108 A dotted-decimal address may be incomplete, in which case
 109 ASCII-to-binary conversion implicitly appends
 110 as many instances of
 111 <B>.0</B>
 112
 113 as necessary to bring it up to four components.
 114 The components of a dotted-decimal address are always taken as
 115 decimal, and leading zeros are ignored.
 116 For example,
 117 <B>10</B>
 118
 119 is synonymous with
 120 <B>10.0.0.0</B>,
 121
 122 and
 123 <B>128.009.000.032</B>
 124
 125 is synonymous with
 126 <B>128.9.0.32</B>
 127
 128 (the latter example is verbatim from RFC 1166).
 129 The result of
 130 <I>addrtoa</I>
 131
 132 is always complete and does not contain leading zeros.
 133 <P>
 134
 135 The letters in
 136 a hexadecimal address may be uppercase or lowercase or any mixture thereof.
 137 Use of hexadecimal addresses is
 138 <B>strongly</B>
 139
 140 <B>discouraged</B>;
 141
 142 they are included only to save hassles when dealing with
 143 the handful of perverted programs which already print
 144 network addresses in hexadecimal.
 145 <P>
 146
 147 DNS names may be complete (optionally terminated with a ``.'')
 148 or incomplete, and are looked up as specified by local system configuration
 149 (see
 150 <I><A HREF="resolver.5.html">resolver</A></I>(5)).
 151
 152 The
 153 <I>h_addr</I>
 154
 155 value returned by
 156 <I><A HREF="gethostbyname.3.html">gethostbyname</A></I>(3)
 157
 158 is used,
 159 so with current DNS implementations,
 160 the result when the name corresponds to more than one address is
 161 difficult to predict.
 162 Name lookup resorts to
 163 <I><A HREF="getnetbyname.3.html">getnetbyname</A></I>(3)
 164
 165 only if
 166 <I><A HREF="gethostbyname.3.html">gethostbyname</A></I>(3)
 167
 168 fails.
 169 <P>
 170
 171 A subnet specification is of the form <I>network</I><B>/</B><I>mask</I>.
 172 The
 173 <I>network</I>
 174
 175 and
 176 <I>mask</I>
 177
 178 can be any form acceptable to
 179 <I>atoaddr</I>.
 180
 181 In addition, the
 182 <I>mask</I>
 183
 184 can be a decimal integer (leading zeros ignored) giving a bit count,
 185 in which case
 186 it stands for a mask with that number of high bits on and all others off
 187 (e.g.,
 188 <B>24</B>
 189
 190 means
 191 <B>255.255.255.0</B>).
 192
 193 In any case, the mask must be contiguous
 194 (a sequence of high bits on and all remaining low bits off).
 195 As a special case, the subnet specification
 196 <B>%default</B>
 197
 198 is a synonym for
 199 <B>0.0.0.0/0</B>.
 200
 201 <P>
 202
 203 <I>Atosubnet</I>
 204
 205 ANDs the mask with the address before returning,
 206 so that any non-network bits in the address are turned off
 207 (e.g.,
 208 <B>10.1.2.3/24</B>
 209
 210 is synonymous with
 211 <B>10.1.2.0/24</B>).
 212
 213 <I>Subnettoa</I>
 214
 215 generates the decimal-integer-bit-count
 216 form of the mask,
 217 with no leading zeros,
 218 unless the mask is non-contiguous.
 219 <P>
 220
 221 The
 222 <I>srclen</I>
 223
 224 parameter of
 225 <I>atoaddr</I>
 226
 227 and
 228 <I>atosubnet</I>
 229
 230 specifies the length of the ASCII string pointed to by
 231 <I>src</I>;
 232
 233 it is an error for there to be anything else
 234 (e.g., a terminating NUL) within that length.
 235 As a convenience for cases where an entire NUL-terminated string is
 236 to be converted,
 237 a
 238 <I>srclen</I>
 239
 240 value of
 241 <B>0</B>
 242
 243 is taken to mean
 244 <B>strlen(src)</B>.
 245
 246 <P>
 247
 248 The
 249 <I>dstlen</I>
 250
 251 parameter of
 252 <I>addrtoa</I>
 253
 254 and
 255 <I>subnettoa</I>
 256
 257 specifies the size of the
 258 <I>dst</I>
 259
 260 parameter;
 261 under no circumstances are more than
 262 <I>dstlen</I>
 263
 264 bytes written to
 265 <I>dst</I>.
 266
 267 A result which will not fit is truncated.
 268 <I>Dstlen</I>
 269
 270 can be zero, in which case
 271 <I>dst</I>
 272
 273 need not be valid and no result is written,
 274 but the return value is unaffected;
 275 in all other cases, the (possibly truncated) result is NUL-terminated.
 276 The
 277 <I>freeswan.h</I>
 278
 279 header file defines constants,
 280 <B>ADDRTOA_BUF</B>
 281
 282 and
 283 <B>SUBNETTOA_BUF</B>,
 284
 285 which are the sizes of buffers just large enough for worst-case results.
 286 <P>
 287
 288 The
 289 <I>format</I>
 290
 291 parameter of
 292 <I>addrtoa</I>
 293
 294 and
 295 <I>subnettoa</I>
 296
 297 specifies what format is to be used for the conversion.
 298 The value
 299 <B>0</B>
 300
 301 (not the ASCII character
 302 <B>'0'</B>,
 303
 304 but a zero value)
 305 specifies a reasonable default,
 306 and is in fact the only format currently available.
 307 This parameter is a hedge against future needs.
 308 <P>
 309
 310 The ASCII-to-binary functions return NULL for success and
 311 a pointer to a string-literal error message for failure;
 312 see DIAGNOSTICS.
 313 The binary-to-ASCII functions return
 314 <B>0</B>
 315
 316 for a failure, and otherwise
 317 always return the size of buffer which would
 318 be needed to
 319 accommodate the full conversion result, including terminating NUL;
 320 it is the caller's responsibility to check this against the size of
 321 the provided buffer to determine whether truncation has occurred.
 322 <A NAME="lbAE">&nbsp;</A>
 323 <H2>SEE ALSO</H2>
 324
 325 <A HREF="inet.3.html">inet</A>(3)
 326 <A NAME="lbAF">&nbsp;</A>
 327 <H2>DIAGNOSTICS</H2>
 328
 329 Fatal errors in
 330 <I>atoaddr</I>
 331
 332 are:
 333 empty input;
 334 attempt to allocate temporary storage for a very long name failed;
 335 name lookup failed;
 336 syntax error in dotted-decimal form;
 337 dotted-decimal component too large to fit in 8 bits.
 338 <P>
 339
 340 Fatal errors in
 341 <I>atosubnet</I>
 342
 343 are:
 344 no
 345 <B>/</B>
 346
 347 in
 348 <I>src</I>;
 349
 350 <I>atoaddr</I>
 351
 352 error in conversion of
 353 <I>network</I>
 354
 355 or
 356 <I>mask</I>;
 357
 358 bit-count mask too big;
 359 mask non-contiguous.
 360 <P>
 361
 362 Fatal errors in
 363 <I>addrtoa</I>
 364
 365 and
 366 <I>subnettoa</I>
 367
 368 are:
 369 unknown format.
 370 <A NAME="lbAG">&nbsp;</A>
 371 <H2>HISTORY</H2>
 372
 373 Written for the FreeS/WAN project by Henry Spencer.
 374 <A NAME="lbAH">&nbsp;</A>
 375 <H2>BUGS</H2>
 376
 377 The interpretation of incomplete dotted-decimal addresses
 378 (e.g.
 379 <B>10/24</B>
 380
 381 means
 382 <B>10.0.0.0/24</B>)
 383
 384 differs from that of some older conversion
 385 functions, e.g. those of
 386 <I><A HREF="inet.3.html">inet</A></I>(3).
 387
 388 The behavior of the older functions has never been
 389 particularly consistent or particularly useful.
 390 <P>
 391
 392 Ignoring leading zeros in dotted-decimal components and bit counts
 393 is arguably the most useful behavior in this application,
 394 but it might occasionally cause confusion with the historical use of leading
 395 zeros to denote octal numbers.
 396 <P>
 397
 398 It is barely possible that somebody, somewhere,
 399 might have a legitimate use for non-contiguous subnet masks.
 400 <P>
 401
 402 <I><A HREF="Getnetbyname.3.html">Getnetbyname</A></I>(3)
 403
 404 is a historical dreg.
 405 <P>
 406
 407 The restriction of ASCII-to-binary error reports to literal strings
 408 (so that callers don't need to worry about freeing them or copying them)
 409 does limit the precision of error reporting.
 410 <P>
 411
 412 The ASCII-to-binary error-reporting convention lends itself
 413 to slightly obscure code,
 414 because many readers will not think of NULL as signifying success.
 415 A good way to make it clearer is to write something like:
 416 <P>
 417
 418 <DL COMPACT><DT><DD>
 419 <PRE>
 420 <B>const char *error;</B>
 421
 422 <B>error = atoaddr( /* ... */ );</B>
 423 <B>if (error != NULL) {</B>
 424 <B>        /* something went wrong */</B>
 425 </PRE>
 426
 427 </DL>
 428
 429 <P>
 430
 431 <HR>
 432 <A NAME="index">&nbsp;</A><H2>Index</H2>
 433 <DL>
 434 <DT><A HREF="#lbAB">NAME</A><DD>
 435 <DT><A HREF="#lbAC">SYNOPSIS</A><DD>
 436 <DT><A HREF="#lbAD">DESCRIPTION</A><DD>
 437 <DT><A HREF="#lbAE">SEE ALSO</A><DD>
 438 <DT><A HREF="#lbAF">DIAGNOSTICS</A><DD>
 439 <DT><A HREF="#lbAG">HISTORY</A><DD>
 440 <DT><A HREF="#lbAH">BUGS</A><DD>
 441 </DL>
 442 <HR>
 443 This document was created by
 444 <A HREF="http://localhost/cgi-bin/man/man2html">man2html</A>,
 445 using the manual pages.<BR>
 446 Time: 05:09:33 GMT, June 19, 2001
 447 </BODY>
 448 </HTML>