1 .TH IPSEC_ATOUL 3 "11 June 2001"
2 .\" RCSID $Id: atoul.3,v 1.1 2004/03/15 20:35:26 as Exp $
4 ipsec atoul, ultoa \- convert unsigned-long numbers to and from ASCII
6 .B "#include <freeswan.h>
8 .B "const char *atoul(const char *src, size_t srclen,"
10 .B "int base, unsigned long *n);"
12 .B "size_t ultoa(unsigned long n, int base, char *dst,"
16 These functions are obsolete; see
18 for their replacements.
21 converts an ASCII number into a binary
25 does the reverse conversion, back to an ASCII version.
27 Numbers are specified in ASCII as
30 octal with a leading zero (e.g.
33 or hexadecimal with a leading
38 in either upper or lower case.
44 specifies the length of the ASCII string pointed to by
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
66 in which case the number supplied is assumed to be of that form
74 in which case the number is examined for a leading zero
77 to determine its base,
80 (halfway between 10 and 16),
81 which has the same effect as
83 except that a non-hexadecimal
84 number is considered decimal regardless of any leading zero.
90 specifies the size of the
93 under no circumstances are more than
97 A result which will not fit is truncated.
99 can be zero, in which case
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.
116 returns NULL for success and
117 a pointer to a string-literal error message for failure;
120 returns the size of buffer which would
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.
134 non-digit character found;
135 number too large for an
136 .BR "unsigned long" .
138 Written for the FreeS/WAN project by Henry Spencer.
140 There is no provision for reporting an invalid
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.
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:
155 .B "const char *error;"
157 .B "error = atoul( /* ... */ );"
158 .B "if (error != NULL) {"
159 .B " /* something went wrong */"