]>
Commit | Line | Data |
---|---|---|
997358a6 MW |
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"> </A> | |
11 | <H2>NAME</H2> | |
12 | ||
13 | ipsec atoul, ultoa - convert unsigned-long numbers to and from ASCII | |
14 | <A NAME="lbAC"> </A> | |
15 | <H2>SYNOPSIS</H2> | |
16 | ||
17 | <B>#include <<A HREF="file:/usr/include/freeswan.h">freeswan.h</A>></B> | |
18 | ||
19 | <P> | |
20 | <B>const char *atoul(const char *src, size_t srclen,</B> | |
21 | ||
22 | <BR> | |
23 | | |
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 | | |
32 | <B>size_t dstlen);</B> | |
33 | ||
34 | <A NAME="lbAD"> </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"> </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"> </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"> </A> | |
212 | <H2>HISTORY</H2> | |
213 | ||
214 | Written for the FreeS/WAN project by Henry Spencer. | |
215 | <A NAME="lbAH"> </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"> </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: 21:40:17 GMT, November 11, 2003 | |
265 | </BODY> | |
266 | </HTML> |