Man Linux: Main Page and Category List

NAME

       ipsec atoaddr, addrtoa - convert Internet addresses to and from ASCII
       ipsec atosubnet, subnettoa - convert subnet/mask ASCII form to and from
       addresses

SYNOPSIS

       #include <freeswan.h>

       const char *atoaddr(const char *src, size_t srclen,
           struct in_addr *addr);
       size_t addrtoa(struct in_addr addr, int format,
           char *dst, size_t dstlen);

       const char *atosubnet(const char *src, size_t srclen,
           struct in_addr *addr, struct in_addr *mask);
       size_t subnettoa(struct in_addr addr, struct in_addr mask,
           int format, char *dst, size_t dstlen);

DESCRIPTION

       These  functions  are  obsolete;   see   ipsec_ttoaddr(3)   for   their
       replacements.

       Atoaddr  converts an ASCII name or dotted-decimal address into a binary
       address (in network byte order).  Addrtoa does the reverse  conversion,
       back  to  an  ASCII dotted-decimal address.  Atosubnet and subnettoa do
       likewise  for  the  ‘‘address/mask’’  ASCII  form  used  to   write   a
       specification of a subnet.

       An  address  is  specified  in  ASCII 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  ASCII-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 addrtoa is always complete  and
       does not contain leading zeros.

       The  letters  in a hexadecimal address may be uppercase or lowercase or
       any  mixture  thereof.   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.

       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
       gethostbyname(3) is used, so  with  current  DNS  implementations,  the
       result  when the name corresponds to more than one address is difficult
       to  predict.   Name  lookup  resorts   to   getnetbyname(3)   only   if
       gethostbyname(3) fails.

       A  subnet  specification  is of the form network/mask.  The network and
       mask can be any form acceptable to atoaddr.  In addition, 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 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.

       Atosubnet 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).  Subnettoa generates the decimal-integer-
       bit-count  form  of the mask, with no leading zeros, unless the mask is
       non-contiguous.

       The srclen parameter of atoaddr and atosubnet specifies the  length  of
       the  ASCII  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 dstlen parameter of addrtoa and subnettoa 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, ADDRTOA_BUF and SUBNETTOA_BUF, which are  the  sizes
       of buffers just large enough for worst-case results.

       The  format parameter of addrtoa and subnettoa specifies what format is
       to be used for the conversion.  The value 0 (not  the  ASCII  character
       ’0’,  but  a zero value) specifies a reasonable default, and is in fact
       the only format currently available.  This parameter is a hedge against
       future needs.

       The  ASCII-to-binary functions return NULL for success and a pointer to
       a string-literal error  message  for  failure;  see  DIAGNOSTICS.   The
       binary-to-ASCII  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 atoaddr are: empty input; attempt to allocate temporary
       storage for a very long name failed; name lookup failed;  syntax  error
       in  dotted-decimal form; dotted-decimal component too large to fit in 8
       bits.

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

       Fatal errors in addrtoa and subnettoa 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.

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

       Getnetbyname(3) is a historical dreg.

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

                                 11 June 2001                 IPSEC_ATOADDR(3)