src/libfreeswan/libfreeswan/atoul.3

   1 .TH IPSEC_ATOUL 3 "11 June 2001"
   2 .\" RCSID $Id: atoul.3,v 1.1 2004/03/15 20:35:26 as Exp $
   3 .SH NAME
   4 ipsec atoul, ultoa \- convert unsigned-long numbers to and from ASCII
   5 .SH SYNOPSIS
   6 .B "#include <freeswan.h>
   7 .sp
   8 .B "const char *atoul(const char *src, size_t srclen,"
   9 .ti +1c
  10 .B "int base, unsigned long *n);"
  11 .br
  12 .B "size_t ultoa(unsigned long n, int base, char *dst,"
  13 .ti +1c
  14 .B "size_t dstlen);"
  15 .SH DESCRIPTION
  16 These functions are obsolete; see
  17 .IR ipsec_ttoul (3)
  18 for their replacements.
  19 .PP
  20 .I Atoul
  21 converts an ASCII number into a binary
  22 .B "unsigned long"
  23 value.
  24 .I Ultoa
  25 does the reverse conversion, back to an ASCII version.
  26 .PP
  27 Numbers are specified in ASCII as
  28 decimal (e.g.
  29 .BR 123 ),
  30 octal with a leading zero (e.g.
  31 .BR 012 ,
  32 which has value 10),
  33 or hexadecimal with a leading
  34 .B 0x
  35 (e.g.
  36 .BR 0x1f ,
  37 which has value 31)
  38 in either upper or lower case.
  39 .PP
  40 The
  41 .I srclen
  42 parameter of
  43 .I atoul
  44 specifies the length of the ASCII string pointed to by
  45 .IR src ;
  46 it is an error for there to be anything else
  47 (e.g., a terminating NUL) within that length.
  48 As a convenience for cases where an entire NUL-terminated string is
  49 to be converted,
  50 a
  51 .I srclen
  52 value of
  53 .B 0
  54 is taken to mean
  55 .BR strlen(src) .
  56 .PP
  57 The
  58 .I base
  59 parameter of
  60 .I atoul
  61 can be
  62 .BR 8 ,
  63 .BR 10 ,
  64 or
  65 .BR 16 ,
  66 in which case the number supplied is assumed to be of that form
  67 (and in the case of
  68 .BR 16 ,
  69 to lack any
  70 .B 0x
  71 prefix).
  72 It can also be
  73 .BR 0 ,
  74 in which case the number is examined for a leading zero
  75 or a leading
  76 .B 0x
  77 to determine its base,
  78 or
  79 .B 13
  80 (halfway between 10 and 16),
  81 which has the same effect as
  82 .B 0
  83 except that a non-hexadecimal
  84 number is considered decimal regardless of any leading zero.
  85 .PP
  86 The
  87 .I dstlen
  88 parameter of
  89 .I ultoa
  90 specifies the size of the
  91 .I dst
  92 parameter;
  93 under no circumstances are more than
  94 .I dstlen
  95 bytes written to
  96 .IR dst .
  97 A result which will not fit is truncated.
  98 .I Dstlen
  99 can be zero, in which case
 100 .I dst
 101 need not be valid and no result is written,
 102 but the return value is unaffected;
 103 in all other cases, the (possibly truncated) result is NUL-terminated.
 104 .PP
 105 The
 106 .I base
 107 parameter of
 108 .I ultoa
 109 must be
 110 .BR 8 ,
 111 .BR 10 ,
 112 or
 113 .BR 16 .
 114 .PP
 115 .I Atoul
 116 returns NULL for success and
 117 a pointer to a string-literal error message for failure;
 118 see DIAGNOSTICS.
 119 .I Ultoa
 120 returns the size of buffer which would
 121 be needed to
 122 accommodate the full conversion result, including terminating NUL;
 123 it is the caller's responsibility to check this against the size of
 124 the provided buffer to determine whether truncation has occurred.
 125 .SH SEE ALSO
 126 atol(3), strtoul(3)
 127 .SH DIAGNOSTICS
 128 Fatal errors in
 129 .I atoul
 130 are:
 131 empty input;
 132 unknown
 133 .IR base ;
 134 non-digit character found;
 135 number too large for an
 136 .BR "unsigned long" .
 137 .SH HISTORY
 138 Written for the FreeS/WAN project by Henry Spencer.
 139 .SH BUGS
 140 There is no provision for reporting an invalid
 141 .I base
 142 parameter given to
 143 .IR ultoa .
 144 .PP
 145 The restriction of error reports to literal strings
 146 (so that callers don't need to worry about freeing them or copying them)
 147 does limit the precision of error reporting.
 148 .PP
 149 The error-reporting convention lends itself to slightly obscure code,
 150 because many readers will not think of NULL as signifying success.
 151 A good way to make it clearer is to write something like:
 152 .PP
 153 .RS
 154 .nf
 155 .B "const char *error;"
 156 .sp
 157 .B "error = atoul( /* ... */ );"
 158 .B "if (error != NULL) {"
 159 .B "        /* something went wrong */"
 160 .fi
 161 .RE