Provided by: strongswan_4.2.4-5ubuntu1_i386 bug

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 <freeswan.h>

       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
       gethostbyname(3),  or  an  old-style  network  name to be looked up via
       getnetbyname(3).

       A dotted-decimal address may be  incomplete,  in  which  case  text-to-
       binary  conversion  implicitly  appends  as  many  instances  of  .0 as
       necessary 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
       programs 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
       gethostbyname(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
       configuration  (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
       preferably, 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 specification %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
       anything  else  (e.g.,  a  terminating  NUL)  within that length.  As a
       convenience for cases where an entire NUL-terminated string  is  to  be
       converted, 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
       written 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
       truncated)  result  is  NUL-terminated.   The  freeswan.h  header  file
       defines constants, ADDRTOT_BUF and SUBNETTOT_BUF, which are  the  sizes
       of buffers 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
       conversion  result,  including  terminating  NUL;  it  is  the caller’s
       responsibility to check this against the size of the provided buffer to
       determine 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;
       dotted-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
       functions,  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.

       Addrtotr’  conversion of an IPv6 address uses lowercase hexadecimal,
       not the uppercase used  in  RFC  2874’s  examples.   It  takes  careful
       reading  of  RFCs  2874,  2673,  and  2234 to realize that lowercase is
       technically 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)