freeswan/lib/ttoul.3

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