2004-11-03 13:51:07 +00:00
|
|
|
.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk)
|
|
|
|
.\"
|
|
|
|
.\" Permission is granted to make and distribute verbatim copies of this
|
|
|
|
.\" manual provided the copyright notice and this permission notice are
|
|
|
|
.\" preserved on all copies.
|
|
|
|
.\"
|
|
|
|
.\" Permission is granted to copy and distribute modified versions of this
|
|
|
|
.\" manual under the conditions for verbatim copying, provided that the
|
|
|
|
.\" entire resulting derived work is distributed under the terms of a
|
|
|
|
.\" permission notice identical to this one.
|
|
|
|
.\"
|
|
|
|
.\" Since the Linux kernel and libraries are constantly changing, this
|
|
|
|
.\" manual page may be incorrect or out-of-date. The author(s) assume no
|
|
|
|
.\" responsibility for errors or omissions, or for damages resulting from
|
|
|
|
.\" the use of the information contained herein. The author(s) may not
|
|
|
|
.\" have taken the same level of care in the production of this manual,
|
|
|
|
.\" which is licensed free of charge, as they might when working
|
|
|
|
.\" professionally.
|
|
|
|
.\"
|
|
|
|
.\" Formatted or processed versions of this manual, if unaccompanied by
|
|
|
|
.\" the source, must acknowledge the copyright and authors of this work.
|
|
|
|
.\"
|
|
|
|
.\" References consulted:
|
|
|
|
.\" Linux libc source code
|
|
|
|
.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991)
|
|
|
|
.\" 386BSD man pages
|
|
|
|
.\" Modified Sun Jul 25 10:54:03 1993 by Rik Faith (faith@cs.unc.edu)
|
|
|
|
.\" Fixed typo, aeb, 950823
|
|
|
|
.\" 2002-02-22, joey, mihtjel: Added strtoull()
|
|
|
|
.\"
|
|
|
|
.TH STRTOUL 3 2002-05-30 "GNU" "Linux Programmer's Manual"
|
|
|
|
.SH NAME
|
|
|
|
strtoul, strtoull, strtouq \- convert a string to an unsigned long integer
|
|
|
|
.SH SYNOPSIS
|
|
|
|
.nf
|
|
|
|
.B #include <stdlib.h>
|
|
|
|
.sp
|
|
|
|
.BI "unsigned long int"
|
|
|
|
.BI "strtoul(const char *" nptr ", char **" endptr ", int " base );
|
|
|
|
.sp
|
|
|
|
.BI "unsigned long long int"
|
|
|
|
.BI "strtoull(const char *" nptr ", char **" endptr ", int " base );
|
|
|
|
.fi
|
|
|
|
.SH DESCRIPTION
|
2005-10-19 07:07:02 +00:00
|
|
|
The \fBstrtoul\fP() function converts the initial part of the string
|
2004-11-03 13:51:07 +00:00
|
|
|
in \fInptr\fP to an unsigned long integer value according to the
|
|
|
|
given \fIbase\fP, which must be between 2 and 36 inclusive, or be
|
|
|
|
the special value 0.
|
|
|
|
.PP
|
2006-01-19 18:45:50 +00:00
|
|
|
The string may begin with an arbitrary amount of white space (as
|
2004-11-03 13:51:07 +00:00
|
|
|
determined by
|
|
|
|
.BR isspace (3))
|
2005-07-07 08:27:03 +00:00
|
|
|
followed by a single optional `+' or `\-'
|
2004-11-03 13:51:07 +00:00
|
|
|
sign. If \fIbase\fP is zero or 16, the string may then include a
|
|
|
|
`0x' prefix, and the number will be read in base 16; otherwise, a
|
|
|
|
zero \fIbase\fP is taken as 10 (decimal) unless the next character
|
|
|
|
is `0', in which case it is taken as 8 (octal).
|
|
|
|
.PP
|
|
|
|
The remainder of the string is converted to an unsigned long int value
|
|
|
|
in the obvious manner, stopping at the first character which is not a
|
|
|
|
valid digit in the given base. (In bases above 10, the letter `A' in
|
|
|
|
either upper or lower case represents 10, `B' represents 11, and so
|
|
|
|
forth, with `Z' representing 35.)
|
|
|
|
.PP
|
2005-10-19 07:07:02 +00:00
|
|
|
If \fIendptr\fP is not NULL, \fBstrtoul\fP() stores the address of the
|
2004-11-03 13:51:07 +00:00
|
|
|
first invalid character in \fI*endptr\fP. If there were no digits at
|
2005-10-19 07:07:02 +00:00
|
|
|
all, \fBstrtoul\fP() stores the original value of \fInptr\fP in
|
2004-11-03 13:51:07 +00:00
|
|
|
\fI*endptr\fP (and returns 0).
|
|
|
|
In particular, if \fI*nptr\fP is not `\\0' but \fI**endptr\fP
|
|
|
|
is `\\0' on return, the entire string is valid.
|
|
|
|
.PP
|
|
|
|
The
|
2005-10-19 07:07:02 +00:00
|
|
|
.BR strtoull ()
|
2004-11-03 13:51:07 +00:00
|
|
|
function works just like the
|
2005-10-19 07:07:02 +00:00
|
|
|
.BR strtoul ()
|
2004-11-03 13:51:07 +00:00
|
|
|
function but returns an unsigned long long integer value.
|
|
|
|
.SH "RETURN VALUE"
|
2005-10-19 07:07:02 +00:00
|
|
|
The \fBstrtoul\fP() function returns either the result of the conversion
|
2004-11-03 13:51:07 +00:00
|
|
|
or, if there was a leading minus sign, the negation of the result of the
|
2006-06-06 01:07:10 +00:00
|
|
|
conversion represented as an unsigned value,
|
|
|
|
unless the original (non-negated) value would overflow; in
|
2005-10-19 07:07:02 +00:00
|
|
|
the latter case, \fBstrtoul\fP() returns ULONG_MAX and sets the global
|
2004-11-03 13:51:07 +00:00
|
|
|
variable \fIerrno\fP to ERANGE.
|
|
|
|
Precisely the same holds for
|
2005-10-19 07:07:02 +00:00
|
|
|
.BR strtoull ()
|
2004-11-03 13:51:07 +00:00
|
|
|
(with ULLONG_MAX instead of ULONG_MAX).
|
|
|
|
.SH ERRORS
|
|
|
|
.TP
|
|
|
|
.B EINVAL
|
|
|
|
(not in C99)
|
|
|
|
The given
|
|
|
|
.I base
|
|
|
|
contains an unsupported value.
|
|
|
|
.TP
|
|
|
|
.B ERANGE
|
|
|
|
The resulting value was out of range.
|
|
|
|
.LP
|
|
|
|
The implementation may also set \fIerrno\fP to \fBEINVAL\fP in case
|
|
|
|
no conversion was performed (no digits seen, and 0 returned).
|
|
|
|
.SH NOTES
|
2006-04-19 00:58:37 +00:00
|
|
|
Since
|
|
|
|
.BR strtoul ()
|
2006-05-14 21:41:45 +00:00
|
|
|
can legitimately return 0 or LONG_MAX (LLONG_MAX for
|
2006-04-19 00:58:37 +00:00
|
|
|
.BR strtoull ())
|
|
|
|
on both success and failure, the calling program should set
|
|
|
|
.I errno
|
|
|
|
to 0 before the call,
|
|
|
|
and then determine if an error occurred by checking whether
|
|
|
|
.I errno
|
|
|
|
has a non-zero value after the call.
|
|
|
|
|
2006-06-06 01:07:10 +00:00
|
|
|
In locales other than the "C" locale, other strings may be accepted.
|
2004-11-03 13:51:07 +00:00
|
|
|
(For example, the thousands separator of the current locale may be
|
|
|
|
supported.)
|
|
|
|
.LP
|
|
|
|
BSD also has
|
|
|
|
.sp
|
|
|
|
.in +4n
|
|
|
|
.nf
|
|
|
|
.BI "u_quad_t"
|
|
|
|
.BI "strtouq(const char *" nptr ", char **" endptr ", int base" );
|
|
|
|
.sp
|
|
|
|
.in -4n
|
|
|
|
.fi
|
|
|
|
with completely analogous definition.
|
|
|
|
Depending on the wordsize of the current architecture, this
|
|
|
|
may be equivalent to
|
2005-10-19 07:07:02 +00:00
|
|
|
.BR strtoull ()
|
2004-11-03 13:51:07 +00:00
|
|
|
or to
|
2005-10-19 07:07:02 +00:00
|
|
|
.BR strtoul ().
|
2006-06-06 01:07:10 +00:00
|
|
|
|
|
|
|
Negative values are considered valid input and are
|
|
|
|
silently converted to the equivalent unsigned long value.
|
2004-11-03 13:51:07 +00:00
|
|
|
.SH "CONFORMING TO"
|
2005-10-19 07:07:02 +00:00
|
|
|
.BR strtoul ()
|
2006-08-03 13:57:30 +00:00
|
|
|
conforms to SVr4, C99 and POSIX-2001, and
|
2005-10-19 07:07:02 +00:00
|
|
|
.BR strtoull ()
|
2006-08-03 13:57:30 +00:00
|
|
|
to C99 and POSIX.1-2001.
|
2006-04-19 01:33:09 +00:00
|
|
|
.SH EXAMPLE
|
|
|
|
See the example on the
|
|
|
|
.BR strtol (3)
|
|
|
|
manual page;
|
|
|
|
the use of the functions described in this manual page is similar.
|
2004-11-03 13:51:07 +00:00
|
|
|
.SH "SEE ALSO"
|
|
|
|
.BR atof (3),
|
|
|
|
.BR atoi (3),
|
|
|
|
.BR atol (3),
|
|
|
|
.BR strtod (3),
|
|
|
|
.BR strtol (3)
|