freeswan/doc/manpage.d/ipsec_ultot.3.html

   1 Content-type: text/html
   2
   3 <HTML><HEAD><TITLE>Manpage of IPSEC_TTOUL</TITLE>
   4 </HEAD><BODY>
   5 <H1>IPSEC_TTOUL</H1>
   6 Section: C Library Functions (3)<BR>Updated: 16 Aug 2000<BR><A HREF="#index">Index</A>
   7 <A HREF="http://localhost/cgi-bin/man/man2html">Return to Main Contents</A><HR>
   8
   9
  10 <A NAME="lbAB">&nbsp;</A>
  11 <H2>NAME</H2>
  12
  13 ipsec ttoul, ultot - convert unsigned-long numbers to and from text
  14 <A NAME="lbAC">&nbsp;</A>
  15 <H2>SYNOPSIS</H2>
  16
  17 <B>#include &lt;<A HREF="file:/usr/include/freeswan.h">freeswan.h</A>&gt;</B>
  18
  19 <P>
  20 <B>const char *ttoul(const char *src, size_t srclen,</B>
  21
  22 <BR>
  23 &nbsp;
  24 <B>int base, unsigned long *n);</B>
  25
  26 <BR>
  27
  28 <B>size_t ultot(unsigned long n, int format, char *dst,</B>
  29
  30 <BR>
  31 &nbsp;
  32 <B>size_t dstlen);</B>
  33
  34 <A NAME="lbAD">&nbsp;</A>
  35 <H2>DESCRIPTION</H2>
  36
  37 <I>Ttoul</I>
  38
  39 converts a text-string number into a binary
  40 <B>unsigned long</B>
  41
  42 value.
  43 <I>Ultot</I>
  44
  45 does the reverse conversion, back to a text version.
  46 <P>
  47
  48 Numbers are specified in text as
  49 decimal (e.g.
  50 <B>123</B>),
  51
  52 octal with a leading zero (e.g.
  53 <B>012</B>,
  54
  55 which has value 10),
  56 or hexadecimal with a leading
  57 <B>0x</B>
  58
  59 (e.g.
  60 <B>0x1f</B>,
  61
  62 which has value 31)
  63 in either upper or lower case.
  64 <P>
  65
  66 The
  67 <I>srclen</I>
  68
  69 parameter of
  70 <I>ttoul</I>
  71
  72 specifies the length of the string pointed to by
  73 <I>src</I>;
  74
  75 it is an error for there to be anything else
  76 (e.g., a terminating NUL) within that length.
  77 As a convenience for cases where an entire NUL-terminated string is
  78 to be converted,
  79 a
  80 <I>srclen</I>
  81
  82 value of
  83 <B>0</B>
  84
  85 is taken to mean
  86 <B>strlen(src)</B>.
  87
  88 <P>
  89
  90 The
  91 <I>base</I>
  92
  93 parameter of
  94 <I>ttoul</I>
  95
  96 can be
  97 <B>8</B>,
  98
  99 <B>10</B>,
 100
 101 or
 102 <B>16</B>,
 103
 104 in which case the number supplied is assumed to be of that form
 105 (and in the case of
 106 <B>16</B>,
 107
 108 to lack any
 109 <B>0x</B>
 110
 111 prefix).
 112 It can also be
 113 <B>0</B>,
 114
 115 in which case the number is examined for a leading zero
 116 or a leading
 117 <B>0x</B>
 118
 119 to determine its base.
 120 <P>
 121
 122 The
 123 <I>dstlen</I>
 124
 125 parameter of
 126 <I>ultot</I>
 127
 128 specifies the size of the
 129 <I>dst</I>
 130
 131 parameter;
 132 under no circumstances are more than
 133 <I>dstlen</I>
 134
 135 bytes written to
 136 <I>dst</I>.
 137
 138 A result which will not fit is truncated.
 139 <I>Dstlen</I>
 140
 141 can be zero, in which case
 142 <I>dst</I>
 143
 144 need not be valid and no result is written,
 145 but the return value is unaffected;
 146 in all other cases, the (possibly truncated) result is NUL-terminated.
 147 The
 148 <I>freeswan.h</I>
 149
 150 header file defines a constant,
 151 <B>ULTOT_BUF</B>,
 152
 153 which is the size of a buffer just large enough for worst-case results.
 154 <P>
 155
 156 The
 157 <I>format</I>
 158
 159 parameter of
 160 <I>ultot</I>
 161
 162 must be one of:
 163 <DL COMPACT><DT><DD>
 164 <DL COMPACT>
 165 <DT><B>'o'</B><DD>
 166 octal conversion with leading
 167 <B>0</B>
 168
 169 <DT><B>&nbsp;8</B><DD>
 170 octal conversion with no leading
 171 <B>0</B>
 172
 173 <DT><B>'d'</B><DD>
 174 decimal conversion
 175 <DT><B>10</B><DD>
 176 same as
 177 <B>d</B>
 178
 179 <DT><B>'x'</B><DD>
 180 hexadecimal conversion, including leading
 181 <B>0x</B>
 182
 183 <DT><B>16</B><DD>
 184 hexadecimal conversion with no leading
 185 <B>0x</B>
 186
 187 <DT><B>17</B><DD>
 188 like
 189 <B>16</B>
 190
 191 except padded on left with
 192 <B>0</B>s
 193
 194 to eight digits (full width of a 32-bit number)
 195 </DL>
 196 </DL>
 197
 198 <P>
 199
 200 <I>Ttoul</I>
 201
 202 returns NULL for success and
 203 a pointer to a string-literal error message for failure;
 204 see DIAGNOSTICS.
 205 <I>Ultot</I>
 206
 207 returns
 208 <B>0</B>
 209
 210 for a failure, and otherwise
 211 returns the size of buffer which would
 212 be needed to
 213 accommodate the full conversion result, including terminating NUL
 214 (it is the caller's responsibility to check this against the size of
 215 the provided buffer to determine whether truncation has occurred).
 216 <A NAME="lbAE">&nbsp;</A>
 217 <H2>SEE ALSO</H2>
 218
 219 <A HREF="atol.3.html">atol</A>(3), <A HREF="strtoul.3.html">strtoul</A>(3)
 220 <A NAME="lbAF">&nbsp;</A>
 221 <H2>DIAGNOSTICS</H2>
 222
 223 Fatal errors in
 224 <I>ttoul</I>
 225
 226 are:
 227 empty input;
 228 unknown
 229 <I>base</I>;
 230
 231 non-digit character found;
 232 number too large for an
 233 <B>unsigned long</B>.
 234
 235 <P>
 236
 237 Fatal errors in
 238 <I>ultot</I>
 239
 240 are:
 241 unknown
 242 <I>format</I>.
 243
 244 <A NAME="lbAG">&nbsp;</A>
 245 <H2>HISTORY</H2>
 246
 247 Written for the FreeS/WAN project by Henry Spencer.
 248 <A NAME="lbAH">&nbsp;</A>
 249 <H2>BUGS</H2>
 250
 251 Conversion of
 252 <B>0</B>
 253
 254 with format
 255 <B>o</B>
 256
 257 yields
 258 <B>00</B>.
 259
 260 <P>
 261
 262 <I>Ultot</I>
 263
 264 format
 265 <B>17</B>
 266
 267 is a bit of a kludge.
 268 <P>
 269
 270 The restriction of error reports to literal strings
 271 (so that callers don't need to worry about freeing them or copying them)
 272 does limit the precision of error reporting.
 273 <P>
 274
 275 The error-reporting convention lends itself to slightly obscure code,
 276 because many readers will not think of NULL as signifying success.
 277 A good way to make it clearer is to write something like:
 278 <P>
 279
 280 <DL COMPACT><DT><DD>
 281 <PRE>
 282 <B>const char *error;</B>
 283
 284 <B>error = ttoul( /* ... */ );</B>
 285 <B>if (error != NULL) {</B>
 286 <B>        /* something went wrong */</B>
 287 </PRE>
 288
 289 </DL>
 290
 291 <P>
 292
 293 <HR>
 294 <A NAME="index">&nbsp;</A><H2>Index</H2>
 295 <DL>
 296 <DT><A HREF="#lbAB">NAME</A><DD>
 297 <DT><A HREF="#lbAC">SYNOPSIS</A><DD>
 298 <DT><A HREF="#lbAD">DESCRIPTION</A><DD>
 299 <DT><A HREF="#lbAE">SEE ALSO</A><DD>
 300 <DT><A HREF="#lbAF">DIAGNOSTICS</A><DD>
 301 <DT><A HREF="#lbAG">HISTORY</A><DD>
 302 <DT><A HREF="#lbAH">BUGS</A><DD>
 303 </DL>
 304 <HR>
 305 This document was created by
 306 <A HREF="http://localhost/cgi-bin/man/man2html">man2html</A>,
 307 using the manual pages.<BR>
 308 Time: 05:09:34 GMT, June 19, 2001
 309 </BODY>
 310 </HTML>