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

   1 Content-type: text/html
   2
   3 <HTML><HEAD><TITLE>Manpage of IPSEC_ATOUL</TITLE>
   4 </HEAD><BODY>
   5 <H1>IPSEC_ATOUL</H1>
   6 Section: C Library Functions (3)<BR>Updated: 11 June 2001<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 atoul, ultoa - convert unsigned-long numbers to and from ASCII
  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 *atoul(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 ultoa(unsigned long n, int base, 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 These functions are obsolete; see
  38 <I><A HREF="ipsec_ttoul.3.html">ipsec_ttoul</A></I>(3)
  39
  40 for their replacements.
  41 <P>
  42
  43 <I>Atoul</I>
  44
  45 converts an ASCII number into a binary
  46 <B>unsigned long</B>
  47
  48 value.
  49 <I>Ultoa</I>
  50
  51 does the reverse conversion, back to an ASCII version.
  52 <P>
  53
  54 Numbers are specified in ASCII as
  55 decimal (e.g.
  56 <B>123</B>),
  57
  58 octal with a leading zero (e.g.
  59 <B>012</B>,
  60
  61 which has value 10),
  62 or hexadecimal with a leading
  63 <B>0x</B>
  64
  65 (e.g.
  66 <B>0x1f</B>,
  67
  68 which has value 31)
  69 in either upper or lower case.
  70 <P>
  71
  72 The
  73 <I>srclen</I>
  74
  75 parameter of
  76 <I>atoul</I>
  77
  78 specifies the length of the ASCII string pointed to by
  79 <I>src</I>;
  80
  81 it is an error for there to be anything else
  82 (e.g., a terminating NUL) within that length.
  83 As a convenience for cases where an entire NUL-terminated string is
  84 to be converted,
  85 a
  86 <I>srclen</I>
  87
  88 value of
  89 <B>0</B>
  90
  91 is taken to mean
  92 <B>strlen(src)</B>.
  93
  94 <P>
  95
  96 The
  97 <I>base</I>
  98
  99 parameter of
 100 <I>atoul</I>
 101
 102 can be
 103 <B>8</B>,
 104
 105 <B>10</B>,
 106
 107 or
 108 <B>16</B>,
 109
 110 in which case the number supplied is assumed to be of that form
 111 (and in the case of
 112 <B>16</B>,
 113
 114 to lack any
 115 <B>0x</B>
 116
 117 prefix).
 118 It can also be
 119 <B>0</B>,
 120
 121 in which case the number is examined for a leading zero
 122 or a leading
 123 <B>0x</B>
 124
 125 to determine its base,
 126 or
 127 <B>13</B>
 128
 129 (halfway between 10 and 16),
 130 which has the same effect as
 131 <B>0</B>
 132
 133 except that a non-hexadecimal
 134 number is considered decimal regardless of any leading zero.
 135 <P>
 136
 137 The
 138 <I>dstlen</I>
 139
 140 parameter of
 141 <I>ultoa</I>
 142
 143 specifies the size of the
 144 <I>dst</I>
 145
 146 parameter;
 147 under no circumstances are more than
 148 <I>dstlen</I>
 149
 150 bytes written to
 151 <I>dst</I>.
 152
 153 A result which will not fit is truncated.
 154 <I>Dstlen</I>
 155
 156 can be zero, in which case
 157 <I>dst</I>
 158
 159 need not be valid and no result is written,
 160 but the return value is unaffected;
 161 in all other cases, the (possibly truncated) result is NUL-terminated.
 162 <P>
 163
 164 The
 165 <I>base</I>
 166
 167 parameter of
 168 <I>ultoa</I>
 169
 170 must be
 171 <B>8</B>,
 172
 173 <B>10</B>,
 174
 175 or
 176 <B>16</B>.
 177
 178 <P>
 179
 180 <I>Atoul</I>
 181
 182 returns NULL for success and
 183 a pointer to a string-literal error message for failure;
 184 see DIAGNOSTICS.
 185 <I>Ultoa</I>
 186
 187 returns the size of buffer which would
 188 be needed to
 189 accommodate the full conversion result, including terminating NUL;
 190 it is the caller's responsibility to check this against the size of
 191 the provided buffer to determine whether truncation has occurred.
 192 <A NAME="lbAE">&nbsp;</A>
 193 <H2>SEE ALSO</H2>
 194
 195 <A HREF="atol.3.html">atol</A>(3), <A HREF="strtoul.3.html">strtoul</A>(3)
 196 <A NAME="lbAF">&nbsp;</A>
 197 <H2>DIAGNOSTICS</H2>
 198
 199 Fatal errors in
 200 <I>atoul</I>
 201
 202 are:
 203 empty input;
 204 unknown
 205 <I>base</I>;
 206
 207 non-digit character found;
 208 number too large for an
 209 <B>unsigned long</B>.
 210
 211 <A NAME="lbAG">&nbsp;</A>
 212 <H2>HISTORY</H2>
 213
 214 Written for the FreeS/WAN project by Henry Spencer.
 215 <A NAME="lbAH">&nbsp;</A>
 216 <H2>BUGS</H2>
 217
 218 There is no provision for reporting an invalid
 219 <I>base</I>
 220
 221 parameter given to
 222 <I>ultoa</I>.
 223
 224 <P>
 225
 226 The restriction of error reports to literal strings
 227 (so that callers don't need to worry about freeing them or copying them)
 228 does limit the precision of error reporting.
 229 <P>
 230
 231 The error-reporting convention lends itself to slightly obscure code,
 232 because many readers will not think of NULL as signifying success.
 233 A good way to make it clearer is to write something like:
 234 <P>
 235
 236 <DL COMPACT><DT><DD>
 237 <PRE>
 238 <B>const char *error;</B>
 239
 240 <B>error = atoul( /* ... */ );</B>
 241 <B>if (error != NULL) {</B>
 242 <B>        /* something went wrong */</B>
 243 </PRE>
 244
 245 </DL>
 246
 247 <P>
 248
 249 <HR>
 250 <A NAME="index">&nbsp;</A><H2>Index</H2>
 251 <DL>
 252 <DT><A HREF="#lbAB">NAME</A><DD>
 253 <DT><A HREF="#lbAC">SYNOPSIS</A><DD>
 254 <DT><A HREF="#lbAD">DESCRIPTION</A><DD>
 255 <DT><A HREF="#lbAE">SEE ALSO</A><DD>
 256 <DT><A HREF="#lbAF">DIAGNOSTICS</A><DD>
 257 <DT><A HREF="#lbAG">HISTORY</A><DD>
 258 <DT><A HREF="#lbAH">BUGS</A><DD>
 259 </DL>
 260 <HR>
 261 This document was created by
 262 <A HREF="http://localhost/cgi-bin/man/man2html">man2html</A>,
 263 using the manual pages.<BR>
 264 Time: 05:09:31 GMT, June 19, 2001
 265 </BODY>
 266 </HTML>