mirror of https://github.com/mkerrisk/man-pages
130 lines
4.5 KiB
Groff
130 lines
4.5 KiB
Groff
|
.\" 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
|
||
|
The \fBstrtoul()\fP function converts the initial part of the string
|
||
|
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
|
||
|
The string must begin with an arbitrary amount of white space (as
|
||
|
determined by
|
||
|
.BR isspace (3))
|
||
|
followed by a single optional `+' or `-'
|
||
|
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
|
||
|
If \fIendptr\fP is not NULL, \fBstrtoul()\fP stores the address of the
|
||
|
first invalid character in \fI*endptr\fP. If there were no digits at
|
||
|
all, \fBstrtoul()\fP stores the original value of \fInptr\fP in
|
||
|
\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
|
||
|
.B strtoull()
|
||
|
function works just like the
|
||
|
.B strtoul()
|
||
|
function but returns an unsigned long long integer value.
|
||
|
.SH "RETURN VALUE"
|
||
|
The \fBstrtoul()\fP function returns either the result of the conversion
|
||
|
or, if there was a leading minus sign, the negation of the result of the
|
||
|
conversion, unless the original (non-negated) value would overflow; in
|
||
|
the latter case, \fBstrtoul()\fP returns ULONG_MAX and sets the global
|
||
|
variable \fIerrno\fP to ERANGE.
|
||
|
Precisely the same holds for
|
||
|
.B strtoull()
|
||
|
(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
|
||
|
In locales other than the "C" locale, also other strings may be accepted.
|
||
|
(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
|
||
|
.B strtoull()
|
||
|
or to
|
||
|
.BR strtoul() .
|
||
|
.SH "CONFORMING TO"
|
||
|
.B strtoul()
|
||
|
conforms to SVID 3, BSD 4.3, ISO 9899 (C99) and POSIX, and
|
||
|
.BR strtoull()
|
||
|
to ISO 9899 (C99) and POSIX 1003.1-2001.
|
||
|
.SH "SEE ALSO"
|
||
|
.BR atof (3),
|
||
|
.BR atoi (3),
|
||
|
.BR atol (3),
|
||
|
.BR strtod (3),
|
||
|
.BR strtol (3)
|