mirror of https://github.com/mkerrisk/man-pages
235 lines
5.6 KiB
Groff
235 lines
5.6 KiB
Groff
.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk)
|
|
.\"
|
|
.\" %%%LICENSE_START(VERBATIM)
|
|
.\" 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.
|
|
.\" %%%LICENSE_END
|
|
.\"
|
|
.\" 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 2021-03-22 "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>
|
|
.PP
|
|
.BI "unsigned long strtoul(const char *restrict " nptr ,
|
|
.BI " char **restrict " endptr ", int " base );
|
|
.BI "unsigned long long strtoull(const char *restrict " nptr ,
|
|
.BI " char **restrict " endptr ", int " base );
|
|
.fi
|
|
.PP
|
|
.RS -4
|
|
Feature Test Macro Requirements for glibc (see
|
|
.BR feature_test_macros (7)):
|
|
.RE
|
|
.PP
|
|
.BR strtoull ():
|
|
.nf
|
|
_ISOC99_SOURCE
|
|
|| /* Glibc <= 2.19: */ _SVID_SOURCE || _BSD_SOURCE
|
|
.fi
|
|
.SH DESCRIPTION
|
|
The
|
|
.BR strtoul ()
|
|
function converts the initial part of the string
|
|
in
|
|
.I nptr
|
|
to an
|
|
.I "unsigned long"
|
|
value according to the
|
|
given
|
|
.IR base ,
|
|
which must be between 2 and 36 inclusive, or be
|
|
the special value 0.
|
|
.PP
|
|
The string may begin with an arbitrary amount of white space (as
|
|
determined by
|
|
.BR isspace (3))
|
|
followed by a single optional \(aq+\(aq or \(aq\-\(aq
|
|
sign.
|
|
If
|
|
.I base
|
|
is zero or 16, the string may then include a
|
|
"0x" prefix, and the number will be read in base 16; otherwise, a
|
|
zero
|
|
.I base
|
|
is taken as 10 (decimal) unless the next character
|
|
is \(aq0\(aq, in which case it is taken as 8 (octal).
|
|
.PP
|
|
The remainder of the string is converted to an
|
|
.I "unsigned long"
|
|
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 \(aqA\(aq in
|
|
either uppercase or lowercase represents 10, \(aqB\(aq represents 11, and so
|
|
forth, with \(aqZ\(aq representing 35.)
|
|
.PP
|
|
If
|
|
.I endptr
|
|
is not NULL,
|
|
.BR strtoul ()
|
|
stores the address of the
|
|
first invalid character in
|
|
.IR *endptr .
|
|
If there were no digits at
|
|
all,
|
|
.BR strtoul ()
|
|
stores the original value of
|
|
.I nptr
|
|
in
|
|
.I *endptr
|
|
(and returns 0).
|
|
In particular, if
|
|
.I *nptr
|
|
is not \(aq\e0\(aq but
|
|
.I **endptr
|
|
is \(aq\e0\(aq on return, the entire string is valid.
|
|
.PP
|
|
The
|
|
.BR strtoull ()
|
|
function works just like the
|
|
.BR strtoul ()
|
|
function but returns an
|
|
.I "unsigned long long"
|
|
value.
|
|
.SH RETURN VALUE
|
|
The
|
|
.BR strtoul ()
|
|
function returns either the result of the conversion
|
|
or, if there was a leading minus sign, the negation of the result of the
|
|
conversion represented as an unsigned value,
|
|
unless the original (nonnegated) value would overflow; in
|
|
the latter case,
|
|
.BR strtoul ()
|
|
returns
|
|
.B ULONG_MAX
|
|
and sets
|
|
.I errno
|
|
to
|
|
.BR ERANGE .
|
|
Precisely the same holds for
|
|
.BR strtoull ()
|
|
(with
|
|
.B ULLONG_MAX
|
|
instead of
|
|
.BR 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.
|
|
.PP
|
|
The implementation may also set
|
|
.IR errno
|
|
to
|
|
.B EINVAL
|
|
in case
|
|
no conversion was performed (no digits seen, and 0 returned).
|
|
.SH ATTRIBUTES
|
|
For an explanation of the terms used in this section, see
|
|
.BR attributes (7).
|
|
.ad l
|
|
.nh
|
|
.TS
|
|
allbox;
|
|
lbx lb lb
|
|
l l l.
|
|
Interface Attribute Value
|
|
T{
|
|
.BR strtoul (),
|
|
.BR strtoull (),
|
|
.BR strtouq ()
|
|
T} Thread safety MT-Safe locale
|
|
.TE
|
|
.hy
|
|
.ad
|
|
.sp 1
|
|
.SH CONFORMING TO
|
|
.BR strtoul ():
|
|
POSIX.1-2001, POSIX.1-2008, C89, C99 SVr4.
|
|
.PP
|
|
.BR strtoull ():
|
|
POSIX.1-2001, POSIX.1-2008, C99.
|
|
.SH NOTES
|
|
Since
|
|
.BR strtoul ()
|
|
can legitimately return 0 or
|
|
.B ULONG_MAX
|
|
.RB ( ULLONG_MAX
|
|
for
|
|
.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 nonzero value after the call.
|
|
.PP
|
|
In locales other than the "C" locale, other strings may be accepted.
|
|
(For example, the thousands separator of the current locale may be
|
|
supported.)
|
|
.PP
|
|
BSD also has
|
|
.PP
|
|
.in +4n
|
|
.EX
|
|
.BI "u_quad_t strtouq(const char *" nptr ", char **" endptr ", int " base );
|
|
.EE
|
|
.in
|
|
.PP
|
|
with completely analogous definition.
|
|
Depending on the wordsize of the current architecture, this
|
|
may be equivalent to
|
|
.BR strtoull ()
|
|
or to
|
|
.BR strtoul ().
|
|
.PP
|
|
Negative values are considered valid input and are
|
|
silently converted to the equivalent
|
|
.I "unsigned long"
|
|
value.
|
|
.SH EXAMPLES
|
|
See the example on the
|
|
.BR strtol (3)
|
|
manual page;
|
|
the use of the functions described in this manual page is similar.
|
|
.SH SEE ALSO
|
|
.BR a64l (3),
|
|
.BR atof (3),
|
|
.BR atoi (3),
|
|
.BR atol (3),
|
|
.BR strtod (3),
|
|
.BR strtol (3),
|
|
.BR strtoumax (3)
|