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

   1 Content-type: text/html
   2
   3 <HTML><HEAD><TITLE>Manpage of IPSEC_TTOADDR</TITLE>
   4 </HEAD><BODY>
   5 <H1>IPSEC_TTOADDR</H1>
   6 Section: C Library Functions (3)<BR>Updated: 15 Dec 2000<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 ttoaddr, tnatoaddr, addrtot - convert Internet addresses to and from text
  14 <BR>
  15
  16 ipsec ttosubnet, subnettot - convert subnet/mask text 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 *ttoaddr(const char *src, size_t srclen,</B>
  24
  25 <BR>
  26 &nbsp;
  27 <B>int af, ip_address *addr);</B>
  28
  29 <BR>
  30
  31 <B>const char *tnatoaddr(const char *src, size_t srclen,</B>
  32
  33 <BR>
  34 &nbsp;
  35 <B>int af, ip_address *addr);</B>
  36
  37 <BR>
  38
  39 <B>size_t addrtot(const ip_address *addr, int format,</B>
  40
  41 <BR>
  42 &nbsp;
  43 <B>char *dst, size_t dstlen);</B>
  44
  45 <P>
  46 <B>const char *ttosubnet(const char *src, size_t srclen,</B>
  47
  48 <BR>
  49 &nbsp;
  50 <B>int af, ip_subnet *dst);</B>
  51
  52 <BR>
  53
  54 <B>size_t subnettot(const ip_subnet *sub, int format,</B>
  55
  56 <BR>
  57 &nbsp;
  58 <B>char *dst, size_t dstlen);</B>
  59
  60 <A NAME="lbAD">&nbsp;</A>
  61 <H2>DESCRIPTION</H2>
  62
  63 <I>Ttoaddr</I>
  64
  65 converts a text-string name or numeric address into a binary address
  66 (in network byte order).
  67 <I>Tnatoaddr</I>
  68
  69 does the same conversion,
  70 but the only text forms it accepts are
  71 the ``official'' forms of
  72 numeric address (dotted-decimal for IPv4, colon-hex for IPv6).
  73 <I>Addrtot</I>
  74
  75 does the reverse conversion, from binary address back to a text form.
  76 <I>Ttosubnet</I>
  77
  78 and
  79 <I>subnettot</I>
  80
  81 do likewise for the ``address/mask'' form used to write a
  82 specification of a subnet.
  83 <P>
  84
  85 An IPv4 address is specified in text as a
  86 dotted-decimal address (e.g.
  87 <B>1.2.3.4</B>),
  88
  89 an eight-digit network-order hexadecimal number with the usual C prefix (e.g.
  90 <B>0x01020304</B>,
  91
  92 which is synonymous with
  93 <B>1.2.3.4</B>),
  94
  95 an eight-digit host-order hexadecimal number with a
  96 <B>0h</B>
  97
  98 prefix (e.g.
  99 <B>0h01020304</B>,
 100
 101 which is synonymous with
 102 <B>1.2.3.4</B>
 103
 104 on a big-endian host and
 105 <B>4.3.2.1</B>
 106
 107 on a little-endian host),
 108 a DNS name to be looked up via
 109 <I><A HREF="gethostbyname.3.html">gethostbyname</A></I>(3),
 110
 111 or an old-style network name to be looked up via
 112 <I><A HREF="getnetbyname.3.html">getnetbyname</A></I>(3).
 113
 114 <P>
 115
 116 A dotted-decimal address may be incomplete, in which case
 117 text-to-binary conversion implicitly appends
 118 as many instances of
 119 <B>.0</B>
 120
 121 as necessary to bring it up to four components.
 122 The components of a dotted-decimal address are always taken as
 123 decimal, and leading zeros are ignored.
 124 For example,
 125 <B>10</B>
 126
 127 is synonymous with
 128 <B>10.0.0.0</B>,
 129
 130 and
 131 <B>128.009.000.032</B>
 132
 133 is synonymous with
 134 <B>128.9.0.32</B>
 135
 136 (the latter example is verbatim from RFC 1166).
 137 The result of applying
 138 <I>addrtot</I>
 139
 140 to an IPv4 address is always complete and does not contain leading zeros.
 141 <P>
 142
 143 Use of hexadecimal addresses is
 144 <B>strongly</B>
 145
 146 <B>discouraged</B>;
 147
 148 they are included only to save hassles when dealing with
 149 the handful of perverted programs which already print
 150 network addresses in hexadecimal.
 151 <P>
 152
 153 An IPv6 address is specified in text with
 154 colon-hex notation (e.g.
 155 <B>0:56:78ab:22:33:44:55:66</B>),
 156
 157 colon-hex with
 158 <B>::</B>
 159
 160 abbreviating at most one subsequence of multiple zeros (e.g.
 161 <B>99:ab::54:068</B>,
 162
 163 which is synonymous with
 164 <B>99:ab:0:0:0:0:54:68</B>),
 165
 166 or a DNS name to be looked up via
 167 <I><A HREF="gethostbyname.3.html">gethostbyname</A></I>(3).
 168
 169 The result of applying
 170 <I>addrtot</I>
 171
 172 to an IPv6 address will use
 173 <B>::</B>
 174
 175 abbreviation if possible,
 176 and will not contain leading zeros.
 177 <P>
 178
 179 The letters in hexadecimal
 180 may be uppercase or lowercase or any mixture thereof.
 181 <P>
 182
 183 DNS names may be complete (optionally terminated with a ``.'')
 184 or incomplete, and are looked up as specified by local system configuration
 185 (see
 186 <I><A HREF="resolver.5.html">resolver</A></I>(5)).
 187
 188 The
 189 <I>h_addr</I>
 190
 191 value returned by
 192 <I><A HREF="gethostbyname2.3.html">gethostbyname2</A></I>(3)
 193
 194 is used,
 195 so with current DNS implementations,
 196 the result when the name corresponds to more than one address is
 197 difficult to predict.
 198 IPv4 name lookup resorts to
 199 <I><A HREF="getnetbyname.3.html">getnetbyname</A></I>(3)
 200
 201 only if
 202 <I><A HREF="gethostbyname2.3.html">gethostbyname2</A></I>(3)
 203
 204 fails.
 205 <P>
 206
 207 A subnet specification is of the form <I>network</I><B>/</B><I>mask</I>.
 208 The
 209 <I>network</I>
 210
 211 and
 212 <I>mask</I>
 213
 214 can be any form acceptable to
 215 <I>ttoaddr</I>.
 216
 217 In addition, and preferably, the
 218 <I>mask</I>
 219
 220 can be a decimal integer (leading zeros ignored) giving a bit count,
 221 in which case
 222 it stands for a mask with that number of high bits on and all others off
 223 (e.g.,
 224 <B>24</B>
 225
 226 in IPv4 means
 227 <B>255.255.255.0</B>).
 228
 229 In any case, the mask must be contiguous
 230 (a sequence of high bits on and all remaining low bits off).
 231 As a special case, the subnet specification
 232 <B>%default</B>
 233
 234 is a synonym for
 235 <B>0.0.0.0/0</B>
 236
 237 or
 238 <B>::/0</B>
 239
 240 in IPv4 or IPv6 respectively.
 241 <P>
 242
 243 <I>Ttosubnet</I>
 244
 245 ANDs the mask with the address before returning,
 246 so that any non-network bits in the address are turned off
 247 (e.g.,
 248 <B>10.1.2.3/24</B>
 249
 250 is synonymous with
 251 <B>10.1.2.0/24</B>).
 252
 253 <I>Subnettot</I>
 254
 255 always generates the decimal-integer-bit-count
 256 form of the mask,
 257 with no leading zeros.
 258 <P>
 259
 260 The
 261 <I>srclen</I>
 262
 263 parameter of
 264 <I>ttoaddr</I>
 265
 266 and
 267 <I>ttosubnet</I>
 268
 269 specifies the length of the text string pointed to by
 270 <I>src</I>;
 271
 272 it is an error for there to be anything else
 273 (e.g., a terminating NUL) within that length.
 274 As a convenience for cases where an entire NUL-terminated string is
 275 to be converted,
 276 a
 277 <I>srclen</I>
 278
 279 value of
 280 <B>0</B>
 281
 282 is taken to mean
 283 <B>strlen(src)</B>.
 284
 285 <P>
 286
 287 The
 288 <I>af</I>
 289
 290 parameter of
 291 <I>ttoaddr</I>
 292
 293 and
 294 <I>ttosubnet</I>
 295
 296 specifies the address family of interest.
 297 It should be either
 298 <B>AF_INET</B>
 299
 300 or
 301 <B>AF_INET6</B>.
 302
 303 <P>
 304
 305 The
 306 <I>dstlen</I>
 307
 308 parameter of
 309 <I>addrtot</I>
 310
 311 and
 312 <I>subnettot</I>
 313
 314 specifies the size of the
 315 <I>dst</I>
 316
 317 parameter;
 318 under no circumstances are more than
 319 <I>dstlen</I>
 320
 321 bytes written to
 322 <I>dst</I>.
 323
 324 A result which will not fit is truncated.
 325 <I>Dstlen</I>
 326
 327 can be zero, in which case
 328 <I>dst</I>
 329
 330 need not be valid and no result is written,
 331 but the return value is unaffected;
 332 in all other cases, the (possibly truncated) result is NUL-terminated.
 333 The
 334 <I>freeswan.h</I>
 335
 336 header file defines constants,
 337 <B>ADDRTOT_BUF</B>
 338
 339 and
 340 <B>SUBNETTOT_BUF</B>,
 341
 342 which are the sizes of buffers just large enough for worst-case results.
 343 <P>
 344
 345 The
 346 <I>format</I>
 347
 348 parameter of
 349 <I>addrtot</I>
 350
 351 and
 352 <I>subnettot</I>
 353
 354 specifies what format is to be used for the conversion.
 355 The value
 356 <B>0</B>
 357
 358 (not the character
 359 <B>'0'</B>,
 360
 361 but a zero value)
 362 specifies a reasonable default,
 363 and is in fact the only format currently available in
 364 <I>subnettot</I>.
 365
 366 <I>Addrtot</I>
 367
 368 also accepts format values
 369 <B>'r'</B>
 370
 371 (signifying a text form suitable for DNS reverse lookups,
 372 e.g.
 373 <B>4.3.2.1.IN-ADDR.ARPA.</B>
 374
 375 for IPv4 and
 376 RFC 2874 format for IPv6),
 377 and
 378 <B>'R'</B>
 379
 380 (signifying an alternate reverse-lookup form,
 381 an error for IPv4 and RFC 1886 format for IPv6).
 382 Reverse-lookup names always end with a ``.''.
 383 <P>
 384
 385 The text-to-binary functions return NULL for success and
 386 a pointer to a string-literal error message for failure;
 387 see DIAGNOSTICS.
 388 The binary-to-text functions return
 389 <B>0</B>
 390
 391 for a failure, and otherwise
 392 always return the size of buffer which would
 393 be needed to
 394 accommodate the full conversion result, including terminating NUL;
 395 it is the caller's responsibility to check this against the size of
 396 the provided buffer to determine whether truncation has occurred.
 397 <A NAME="lbAE">&nbsp;</A>
 398 <H2>SEE ALSO</H2>
 399
 400 <A HREF="inet.3.html">inet</A>(3)
 401 <A NAME="lbAF">&nbsp;</A>
 402 <H2>DIAGNOSTICS</H2>
 403
 404 Fatal errors in
 405 <I>ttoaddr</I>
 406
 407 are:
 408 empty input;
 409 attempt to allocate temporary storage for a very long name failed;
 410 name lookup failed;
 411 syntax error in dotted-decimal or colon-hex form;
 412 dotted-decimal or colon-hex component too large.
 413 <P>
 414
 415 Fatal errors in
 416 <I>ttosubnet</I>
 417
 418 are:
 419 no
 420 <B>/</B>
 421
 422 in
 423 <I>src</I>;
 424
 425 <I>ttoaddr</I>
 426
 427 error in conversion of
 428 <I>network</I>
 429
 430 or
 431 <I>mask</I>;
 432
 433 bit-count mask too big;
 434 mask non-contiguous.
 435 <P>
 436
 437 Fatal errors in
 438 <I>addrtot</I>
 439
 440 and
 441 <I>subnettot</I>
 442
 443 are:
 444 unknown format.
 445 <A NAME="lbAG">&nbsp;</A>
 446 <H2>HISTORY</H2>
 447
 448 Written for the FreeS/WAN project by Henry Spencer.
 449 <A NAME="lbAH">&nbsp;</A>
 450 <H2>BUGS</H2>
 451
 452 The interpretation of incomplete dotted-decimal addresses
 453 (e.g.
 454 <B>10/24</B>
 455
 456 means
 457 <B>10.0.0.0/24</B>)
 458
 459 differs from that of some older conversion
 460 functions, e.g. those of
 461 <I><A HREF="inet.3.html">inet</A></I>(3).
 462
 463 The behavior of the older functions has never been
 464 particularly consistent or particularly useful.
 465 <P>
 466
 467 Ignoring leading zeros in dotted-decimal components and bit counts
 468 is arguably the most useful behavior in this application,
 469 but it might occasionally cause confusion with the historical use of leading
 470 zeros to denote octal numbers.
 471 <P>
 472
 473 <I>Ttoaddr</I>
 474
 475 does not support the mixed colon-hex-dotted-decimal
 476 convention used to embed an IPv4 address in an IPv6 address.
 477 <P>
 478
 479 <I>Addrtot</I>
 480
 481 always uses the
 482 <B>::</B>
 483
 484 abbreviation (which can appear only once in an address) for the
 485 <I>first</I>
 486
 487 sequence of multiple zeros in an IPv6 address.
 488 One can construct addresses (unlikely ones) in which this is suboptimal.
 489 <P>
 490
 491 <I>Addrtot</I>
 492
 493 <B>'r'</B>
 494
 495 conversion of an IPv6 address uses lowercase hexadecimal,
 496 not the uppercase used in RFC 2874's examples.
 497 It takes careful reading of RFCs 2874, 2673, and 2234 to realize
 498 that lowercase is technically legitimate here,
 499 and there may be software which botches this
 500 and hence would have trouble with lowercase hex.
 501 <P>
 502
 503 Possibly
 504 <I>subnettot</I>
 505
 506 ought to recognize the
 507 <B>%default</B>
 508
 509 case and generate that string as its output.
 510 Currently it doesn't.
 511 <P>
 512
 513 It is barely possible that somebody, somewhere,
 514 might have a legitimate use for non-contiguous subnet masks.
 515 <P>
 516
 517 <I><A HREF="Getnetbyname.3.html">Getnetbyname</A></I>(3)
 518
 519 is a historical dreg.
 520 <P>
 521
 522 <I>Tnatoaddr</I>
 523
 524 probably should enforce completeness of dotted-decimal addresses.
 525 <P>
 526
 527 The restriction of text-to-binary error reports to literal strings
 528 (so that callers don't need to worry about freeing them or copying them)
 529 does limit the precision of error reporting.
 530 <P>
 531
 532 The text-to-binary error-reporting convention lends itself
 533 to slightly obscure code,
 534 because many readers will not think of NULL as signifying success.
 535 A good way to make it clearer is to write something like:
 536 <P>
 537
 538 <DL COMPACT><DT><DD>
 539 <PRE>
 540 <B>const char *error;</B>
 541
 542 <B>error = ttoaddr( /* ... */ );</B>
 543 <B>if (error != NULL) {</B>
 544 <B>        /* something went wrong */</B>
 545 </PRE>
 546
 547 </DL>
 548
 549 <P>
 550
 551 <HR>
 552 <A NAME="index">&nbsp;</A><H2>Index</H2>
 553 <DL>
 554 <DT><A HREF="#lbAB">NAME</A><DD>
 555 <DT><A HREF="#lbAC">SYNOPSIS</A><DD>
 556 <DT><A HREF="#lbAD">DESCRIPTION</A><DD>
 557 <DT><A HREF="#lbAE">SEE ALSO</A><DD>
 558 <DT><A HREF="#lbAF">DIAGNOSTICS</A><DD>
 559 <DT><A HREF="#lbAG">HISTORY</A><DD>
 560 <DT><A HREF="#lbAH">BUGS</A><DD>
 561 </DL>
 562 <HR>
 563 This document was created by
 564 <A HREF="http://localhost/cgi-bin/man/man2html">man2html</A>,
 565 using the manual pages.<BR>
 566 Time: 05:09:33 GMT, June 19, 2001
 567 </BODY>
 568 </HTML>