161 lines
3.3 KiB
Groff
161 lines
3.3 KiB
Groff
.TH IPSEC_ATOUL 3 "11 June 2001"
|
|
.SH NAME
|
|
ipsec atoul, ultoa \- convert unsigned-long numbers to and from ASCII
|
|
.SH SYNOPSIS
|
|
.B "#include <freeswan.h>
|
|
.sp
|
|
.B "const char *atoul(const char *src, size_t srclen,"
|
|
.ti +1c
|
|
.B "int base, unsigned long *n);"
|
|
.br
|
|
.B "size_t ultoa(unsigned long n, int base, char *dst,"
|
|
.ti +1c
|
|
.B "size_t dstlen);"
|
|
.SH DESCRIPTION
|
|
These functions are obsolete; see
|
|
.IR ipsec_ttoul (3)
|
|
for their replacements.
|
|
.PP
|
|
.I Atoul
|
|
converts an ASCII number into a binary
|
|
.B "unsigned long"
|
|
value.
|
|
.I Ultoa
|
|
does the reverse conversion, back to an ASCII version.
|
|
.PP
|
|
Numbers are specified in ASCII as
|
|
decimal (e.g.
|
|
.BR 123 ),
|
|
octal with a leading zero (e.g.
|
|
.BR 012 ,
|
|
which has value 10),
|
|
or hexadecimal with a leading
|
|
.B 0x
|
|
(e.g.
|
|
.BR 0x1f ,
|
|
which has value 31)
|
|
in either upper or lower case.
|
|
.PP
|
|
The
|
|
.I srclen
|
|
parameter of
|
|
.I atoul
|
|
specifies the length of the ASCII string pointed to by
|
|
.IR src ;
|
|
it is an error for there to be anything else
|
|
(e.g., a terminating NUL) within that length.
|
|
As a convenience for cases where an entire NUL-terminated string is
|
|
to be converted,
|
|
a
|
|
.I srclen
|
|
value of
|
|
.B 0
|
|
is taken to mean
|
|
.BR strlen(src) .
|
|
.PP
|
|
The
|
|
.I base
|
|
parameter of
|
|
.I atoul
|
|
can be
|
|
.BR 8 ,
|
|
.BR 10 ,
|
|
or
|
|
.BR 16 ,
|
|
in which case the number supplied is assumed to be of that form
|
|
(and in the case of
|
|
.BR 16 ,
|
|
to lack any
|
|
.B 0x
|
|
prefix).
|
|
It can also be
|
|
.BR 0 ,
|
|
in which case the number is examined for a leading zero
|
|
or a leading
|
|
.B 0x
|
|
to determine its base,
|
|
or
|
|
.B 13
|
|
(halfway between 10 and 16),
|
|
which has the same effect as
|
|
.B 0
|
|
except that a non-hexadecimal
|
|
number is considered decimal regardless of any leading zero.
|
|
.PP
|
|
The
|
|
.I dstlen
|
|
parameter of
|
|
.I ultoa
|
|
specifies the size of the
|
|
.I dst
|
|
parameter;
|
|
under no circumstances are more than
|
|
.I dstlen
|
|
bytes written to
|
|
.IR dst .
|
|
A result which will not fit is truncated.
|
|
.I Dstlen
|
|
can be zero, in which case
|
|
.I dst
|
|
need not be valid and no result is written,
|
|
but the return value is unaffected;
|
|
in all other cases, the (possibly truncated) result is NUL-terminated.
|
|
.PP
|
|
The
|
|
.I base
|
|
parameter of
|
|
.I ultoa
|
|
must be
|
|
.BR 8 ,
|
|
.BR 10 ,
|
|
or
|
|
.BR 16 .
|
|
.PP
|
|
.I Atoul
|
|
returns NULL for success and
|
|
a pointer to a string-literal error message for failure;
|
|
see DIAGNOSTICS.
|
|
.I Ultoa
|
|
returns the size of buffer which would
|
|
be needed to
|
|
accommodate the full conversion result, including terminating NUL;
|
|
it is the caller's responsibility to check this against the size of
|
|
the provided buffer to determine whether truncation has occurred.
|
|
.SH SEE ALSO
|
|
atol(3), strtoul(3)
|
|
.SH DIAGNOSTICS
|
|
Fatal errors in
|
|
.I atoul
|
|
are:
|
|
empty input;
|
|
unknown
|
|
.IR base ;
|
|
non-digit character found;
|
|
number too large for an
|
|
.BR "unsigned long" .
|
|
.SH HISTORY
|
|
Written for the FreeS/WAN project by Henry Spencer.
|
|
.SH BUGS
|
|
There is no provision for reporting an invalid
|
|
.I base
|
|
parameter given to
|
|
.IR ultoa .
|
|
.PP
|
|
The restriction of error reports to literal strings
|
|
(so that callers don't need to worry about freeing them or copying them)
|
|
does limit the precision of error reporting.
|
|
.PP
|
|
The error-reporting convention lends itself to slightly obscure code,
|
|
because many readers will not think of NULL as signifying success.
|
|
A good way to make it clearer is to write something like:
|
|
.PP
|
|
.RS
|
|
.nf
|
|
.B "const char *error;"
|
|
.sp
|
|
.B "error = atoul( /* ... */ );"
|
|
.B "if (error != NULL) {"
|
|
.B " /* something went wrong */"
|
|
.fi
|
|
.RE
|