unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

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

IPSEC_TTOUL(3)             Library Functions Manual             IPSEC_TTOUL(3)



NAME
       ipsec ttoul, ultot - convert unsigned-long numbers to and from text

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

       const char *ttoul(const char *src, size_t srclen,
           int base, unsigned long *n);
       size_t ultot(unsigned long n, int format, char *dst,
           size_t dstlen);

DESCRIPTION
       Ttoul  converts a text-string number into a binary unsigned long value.
       Ultot does the reverse conversion, back to a text version.

       Numbers are specified in text as decimal  (e.g.   123),  octal  with  a
       leading  zero  (e.g.   012,  which has value 10), or hexadecimal with a
       leading 0x (e.g.  0x1f, which has value 31) in either  upper  or  lower
       case.

       The  srclen  parameter  of  ttoul  specifies  the  length of the 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 base parameter of ttoul can be 8, 10, or 16, in which case the num-
       ber supplied is assumed to be of that form (and in the case of  16,  to
       lack  any  0x  prefix).   It can also be 0, in which case the number is
       examined for a leading zero or a leading 0x to determine its base.

       The dstlen parameter of ultot 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 a con-
       stant, ULTOT_BUF, which is the size of a buffer just large  enough  for
       worst-case results.

       The format parameter of ultot must be one of:

              'o' octal conversion with leading 0

               8  octal conversion with no leading 0

              'd' decimal conversion

              10  same as d

              'x' hexadecimal conversion, including leading 0x

              16  hexadecimal conversion with no leading 0x

              17  like  16 except padded on left with 0s to eight digits (full
                  width of a 32-bit number)

       Ttoul returns NULL for success and a pointer to a string-literal  error
       message  for  failure; see DIAGNOSTICS.  Ultot returns 0 for a failure,
       and otherwise returns 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
       atol(3), strtoul(3)

DIAGNOSTICS
       Fatal errors in ttoul are: empty input; unknown base; non-digit charac-
       ter found; number too large for an unsigned long.

       Fatal errors in ultot are: unknown format.

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

BUGS
       Conversion of 0 with format o yields 00.

       Ultot format 17 is a bit of a kludge.

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



                                  16 Aug 2000                   IPSEC_TTOUL(3)