unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (Debian-5.0)
Page:
Section:
Apropos / Subsearch:
optional field

IPSEC_TTOADDR(3)           Library Functions Manual           IPSEC_TTOADDR(3)



NAME
       ipsec  ttoaddr,  tnatoaddr, addrtot - convert Internet addresses to and
       from text
       ipsec ttosubnet, subnettot - convert subnet/mask text form to and  from
       addresses

SYNOPSIS
       #include <&lt;freeswan.h>&gt;

       const char *ttoaddr(const char *src, size_t srclen,
           int af, ip_address *addr);
       const char *tnatoaddr(const char *src, size_t srclen,
           int af, ip_address *addr);
       size_t addrtot(const ip_address *addr, int format,
           char *dst, size_t dstlen);

       const char *ttosubnet(const char *src, size_t srclen,
           int af, ip_subnet *dst);
       size_t subnettot(const ip_subnet *sub, int format,
           char *dst, size_t dstlen);

DESCRIPTION
       Ttoaddr  converts  a  text-string name or numeric address into a binary
       address (in network byte order).  Tnatoaddr does the  same  conversion,
       but  the  only  text  forms  it  accepts  are the ``official'' forms of
       numeric address (dotted-decimal for IPv4, colon-hex for IPv6).  Addrtot
       does  the  reverse conversion, from binary address back to a text form.
       Ttosubnet and subnettot do likewise for the ``address/mask'' form  used
       to write a specification of a subnet.

       An  IPv4 address is specified in text as a dotted-decimal address (e.g.
       1.2.3.4), an eight-digit  network-order  hexadecimal  number  with  the
       usual C prefix (e.g.  0x01020304, which is synonymous with 1.2.3.4), an
       eight-digit host-order  hexadecimal  number  with  a  0h  prefix  (e.g.
       0h01020304,  which  is synonymous with 1.2.3.4 on a big-endian host and
       4.3.2.1 on a little-endian host), a DNS name to be looked up via  geth-
       ostbyname(3),  or an old-style network name to be looked up via getnet-
       byname(3).

       A dotted-decimal address may be  incomplete,  in  which  case  text-to-
       binary  conversion implicitly appends as many instances of .0 as neces-
       sary to bring it up to four components.  The components  of  a  dotted-
       decimal  address  are  always  taken  as decimal, and leading zeros are
       ignored.   For  example,  10   is   synonymous   with   10.0.0.0,   and
       128.009.000.032  is  synonymous  with 128.9.0.32 (the latter example is
       verbatim from RFC 1166).  The result of applying  addrtot  to  an  IPv4
       address is always complete and does not contain leading zeros.

       Use of hexadecimal addresses is strongly discouraged; they are included
       only to save hassles when dealing with the handful  of  perverted  pro-
       grams which already print network addresses in hexadecimal.

       An  IPv6  address  is  specified  in text with colon-hex notation (e.g.
       0:56:78ab:22:33:44:55:66), colon-hex with :: abbreviating at  most  one
       subsequence of multiple zeros (e.g.  99:ab::54:068, which is synonymous
       with 99:ab:0:0:0:0:54:68), or a DNS name to be looked up via gethostby-
       name(3).  The result of applying addrtot to an IPv6 address will use ::
       abbreviation if possible, and will not contain leading zeros.

       The letters in hexadecimal may be uppercase or lowercase or any mixture
       thereof.

       DNS  names  may  be  complete  (optionally terminated with a ``.'')  or
       incomplete, and are looked up as specified by local  system  configura-
       tion (see resolver(5)).  The h_addr value returned by gethostbyname2(3)
       is used, so with current DNS implementations, the result when the  name
       corresponds  to  more  than  one address is difficult to predict.  IPv4
       name lookup resorts to getnetbyname(3) only if gethostbyname2(3) fails.

       A subnet specification is of the form network/mask.   The  network  and
       mask  can  be any form acceptable to ttoaddr.  In addition, and prefer-
       ably, the mask can be a decimal integer (leading zeros ignored)  giving
       a  bit  count,  in  which case it stands for a mask with that number of
       high bits on and all others off (e.g., 24 in IPv4 means 255.255.255.0).
       In  any  case,  the mask must be contiguous (a sequence of high bits on
       and all remaining low bits off).  As a special case, the subnet  speci-
       fication  %default  is  a synonym for 0.0.0.0/0 or ::/0 in IPv4 or IPv6
       respectively.

       Ttosubnet ANDs the mask with the address before returning, so that  any
       non-network  bits  in  the address are turned off (e.g., 10.1.2.3/24 is
       synonymous with 10.1.2.0/24).  Subnettot always generates the  decimal-
       integer-bit-count form of the mask, with no leading zeros.

       The  srclen  parameter of ttoaddr and ttosubnet specifies the length of
       the text string pointed to by src; it is an error for there to be  any-
       thing  else  (e.g., a terminating NUL) within that length.  As a conve-
       nience for cases where an entire NUL-terminated string is  to  be  con-
       verted, a srclen value of 0 is taken to mean strlen(src).

       The  af parameter of ttoaddr and ttosubnet specifies the address family
       of interest.  It should be either AF_INET or AF_INET6.

       The dstlen parameter of addrtot and subnettot specifies the size of the
       dst  parameter; under no circumstances are more than dstlen bytes writ-
       ten 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 trun-
       cated)  result  is  NUL-terminated.  The freeswan.h header file defines
       constants, ADDRTOT_BUF and SUBNETTOT_BUF, which are the sizes  of  buf-
       fers just large enough for worst-case results.

       The  format parameter of addrtot and subnettot specifies what format is
       to be used for the conversion.  The value 0 (not the character '0', but
       a  zero  value) specifies a reasonable default, and is in fact the only
       format currently available in subnettot.  Addrtot also  accepts  format
       values  'r'  (signifying  a text form suitable for DNS reverse lookups,
       e.g.  4.3.2.1.IN-ADDR.ARPA.  for IPv4 and RFC 2874  format  for  IPv6),
       and 'R' (signifying an alternate reverse-lookup form, an error for IPv4
       and RFC 1886 format for IPv6).  Reverse-lookup names always end with  a
       ``.''.

       The text-to-binary functions return NULL for success and a pointer to a
       string-literal error message for failure; see DIAGNOSTICS.  The binary-
       to-text  functions  return 0 for a failure, and otherwise always return
       the size of buffer which would be needed to accommodate the  full  con-
       version result, including terminating NUL; it is the caller's responsi-
       bility to check this against the size of the provided buffer to  deter-
       mine whether truncation has occurred.

SEE ALSO
       inet(3)

DIAGNOSTICS
       Fatal  errors  in  ttoaddr  are:  empty  input; unknown address family;
       attempt to allocate temporary storage for a very long name failed; name
       lookup  failed;  syntax error in dotted-decimal or colon-hex form; dot-
       ted-decimal or colon-hex component too large.

       Fatal errors in ttosubnet are: no / in src; ttoaddr error in conversion
       of network or mask; bit-count mask too big; mask non-contiguous.

       Fatal errors in addrtot and subnettot are: unknown format.

HISTORY
       Written for the FreeS/WAN project by Henry Spencer.

BUGS
       The  interpretation of incomplete dotted-decimal addresses (e.g.  10/24
       means 10.0.0.0/24) differs from that of  some  older  conversion  func-
       tions,  e.g. those of inet(3).  The behavior of the older functions has
       never been particularly consistent or particularly useful.

       Ignoring leading zeros in dotted-decimal components and bit  counts  is
       arguably  the  most  useful  behavior in this application, but it might
       occasionally cause confusion with the historical use of  leading  zeros
       to denote octal numbers.

       Ttoaddr  does not support the mixed colon-hex-dotted-decimal convention
       used to embed an IPv4 address in an IPv6 address.

       Addrtot always uses the :: abbreviation (which can appear only once  in
       an  address)  for  the  first  sequence  of  multiple  zeros in an IPv6
       address.  One can construct addresses (unlikely ones) in which this  is
       suboptimal.

       Addrtot  'r'  conversion of an IPv6 address uses lowercase hexadecimal,
       not the uppercase used in RFC 2874's examples.  It takes careful  read-
       ing  of  RFCs 2874, 2673, and 2234 to realize that lowercase is techni-
       cally legitimate here, and there may be software which botches this and
       hence would have trouble with lowercase hex.

       Possibly  subnettot  ought  to recognize the %default case and generate
       that string as its output.  Currently it doesn't.

       It is barely possible that somebody, somewhere, might have a legitimate
       use for non-contiguous subnet masks.

       Getnetbyname(3) is a historical dreg.

       Tnatoaddr   probably  should  enforce  completeness  of  dotted-decimal
       addresses.

       The restriction of text-to-binary 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 text-to-binary 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 = ttoaddr( /* ... */ );
              if (error != NULL) {
                      /* something went wrong */



                                 28 Sept 2001                 IPSEC_TTOADDR(3)