193 lines
3.7 KiB
Groff
193 lines
3.7 KiB
Groff
.TH IPSEC_TTOUL 3 "16 Aug 2000"
|
|
.\" RCSID $Id: ttoul.3,v 1.1 2004/03/15 20:35:26 as Exp $
|
|
.SH NAME
|
|
ipsec ttoul, ultot \- convert unsigned-long numbers to and from text
|
|
.SH SYNOPSIS
|
|
.B "#include <freeswan.h>
|
|
.sp
|
|
.B "const char *ttoul(const char *src, size_t srclen,"
|
|
.ti +1c
|
|
.B "int base, unsigned long *n);"
|
|
.br
|
|
.B "size_t ultot(unsigned long n, int format, char *dst,"
|
|
.ti +1c
|
|
.B "size_t dstlen);"
|
|
.SH DESCRIPTION
|
|
.I Ttoul
|
|
converts a text-string number into a binary
|
|
.B "unsigned long"
|
|
value.
|
|
.I Ultot
|
|
does the reverse conversion, back to a text version.
|
|
.PP
|
|
Numbers are specified in text 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 ttoul
|
|
specifies the length of the 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 ttoul
|
|
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.
|
|
.PP
|
|
The
|
|
.I dstlen
|
|
parameter of
|
|
.I ultot
|
|
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.
|
|
The
|
|
.I freeswan.h
|
|
header file defines a constant,
|
|
.BR ULTOT_BUF ,
|
|
which is the size of a buffer just large enough for worst-case results.
|
|
.PP
|
|
The
|
|
.I format
|
|
parameter of
|
|
.I ultot
|
|
must be one of:
|
|
.RS
|
|
.IP \fB'o'\fR 4
|
|
octal conversion with leading
|
|
.B 0
|
|
.IP \fB\ 8\fR
|
|
octal conversion with no leading
|
|
.B 0
|
|
.IP \fB'd'\fR
|
|
decimal conversion
|
|
.IP \fB10\fR
|
|
same as
|
|
.B d
|
|
.IP \fB'x'\fR
|
|
hexadecimal conversion, including leading
|
|
.B 0x
|
|
.IP \fB16\fR
|
|
hexadecimal conversion with no leading
|
|
.B 0x
|
|
.IP \fB17\fR
|
|
like
|
|
.B 16
|
|
except padded on left with
|
|
.BR 0 s
|
|
to eight digits (full width of a 32-bit number)
|
|
.RE
|
|
.PP
|
|
.I Ttoul
|
|
returns NULL for success and
|
|
a pointer to a string-literal error message for failure;
|
|
see DIAGNOSTICS.
|
|
.I Ultot
|
|
returns
|
|
.B 0
|
|
for a failure, and otherwise
|
|
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 ttoul
|
|
are:
|
|
empty input;
|
|
unknown
|
|
.IR base ;
|
|
non-digit character found;
|
|
number too large for an
|
|
.BR "unsigned long" .
|
|
.PP
|
|
Fatal errors in
|
|
.I ultot
|
|
are:
|
|
unknown
|
|
.IR format .
|
|
.SH HISTORY
|
|
Written for the FreeS/WAN project by Henry Spencer.
|
|
.SH BUGS
|
|
Conversion of
|
|
.B 0
|
|
with format
|
|
.B o
|
|
yields
|
|
.BR 00 .
|
|
.PP
|
|
.I Ultot
|
|
format
|
|
.B 17
|
|
is a bit of a kludge.
|
|
.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 = ttoul( /* ... */ );"
|
|
.B "if (error != NULL) {"
|
|
.B " /* something went wrong */"
|
|
.fi
|
|
.RE
|