2004-11-03 13:51:07 +00:00
|
|
|
.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved
|
2007-06-20 22:33:04 +00:00
|
|
|
.TH "STRTOUL" 3P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
|
2004-11-03 13:51:07 +00:00
|
|
|
.\" strtoul
|
2007-09-20 06:03:25 +00:00
|
|
|
.SH PROLOG
|
|
|
|
This manual page is part of the POSIX Programmer's Manual.
|
|
|
|
The Linux implementation of this interface may differ (consult
|
|
|
|
the corresponding Linux manual page for details of Linux behavior),
|
|
|
|
or the interface may not be implemented on Linux.
|
2004-11-03 13:51:07 +00:00
|
|
|
.SH NAME
|
|
|
|
strtoul, strtoull \- convert a string to an unsigned long
|
|
|
|
.SH SYNOPSIS
|
|
|
|
.LP
|
|
|
|
\fB#include <stdlib.h>
|
|
|
|
.br
|
|
|
|
.sp
|
|
|
|
unsigned long strtoul(const char *restrict\fP \fIstr\fP\fB,
|
|
|
|
.br
|
|
|
|
\ \ \ \ \ \ char **restrict\fP \fIendptr\fP\fB, int\fP \fIbase\fP\fB);
|
|
|
|
.br
|
|
|
|
unsigned long long strtoull(const char *restrict\fP \fIstr\fP\fB,
|
|
|
|
.br
|
|
|
|
\ \ \ \ \ \ char **restrict\fP \fIendptr\fP\fB, int\fP \fIbase\fP\fB);
|
|
|
|
.br
|
|
|
|
\fP
|
|
|
|
.SH DESCRIPTION
|
|
|
|
.LP
|
|
|
|
These functions shall convert the initial portion of the string pointed
|
|
|
|
to by \fIstr\fP to a type \fBunsigned long\fP and
|
|
|
|
\fBunsigned long long\fP representation, respectively. First, they
|
|
|
|
decompose the input string into three parts:
|
|
|
|
.IP " 1." 4
|
|
|
|
An initial, possibly empty, sequence of white-space characters (as
|
|
|
|
specified by \fIisspace\fP())
|
|
|
|
.LP
|
|
|
|
.IP " 2." 4
|
|
|
|
A subject sequence interpreted as an integer represented in some radix
|
|
|
|
determined by the value of \fIbase\fP
|
|
|
|
.LP
|
|
|
|
.IP " 3." 4
|
|
|
|
A final string of one or more unrecognized characters, including the
|
|
|
|
terminating null byte of the input string
|
|
|
|
.LP
|
|
|
|
.LP
|
|
|
|
Then they shall attempt to convert the subject sequence to an unsigned
|
|
|
|
integer, and return the result.
|
|
|
|
.LP
|
|
|
|
If the value of \fIbase\fP is 0, the expected form of the subject
|
|
|
|
sequence is that of a decimal constant, octal constant, or
|
|
|
|
hexadecimal constant, any of which may be preceded by a \fB'+'\fP
|
|
|
|
or \fB'-'\fP sign. A decimal constant begins with a
|
|
|
|
non-zero digit, and consists of a sequence of decimal digits. An octal
|
|
|
|
constant consists of the prefix \fB'0'\fP optionally
|
|
|
|
followed by a sequence of the digits \fB'0'\fP to \fB'7'\fP only.
|
|
|
|
A hexadecimal constant consists of the prefix 0x or 0X
|
|
|
|
followed by a sequence of the decimal digits and letters \fB'a'\fP
|
|
|
|
(or \fB'A'\fP ) to \fB'f'\fP (or \fB'F'\fP ) with
|
|
|
|
values 10 to 15 respectively.
|
|
|
|
.LP
|
|
|
|
If the value of \fIbase\fP is between 2 and 36, the expected form
|
|
|
|
of the subject sequence is a sequence of letters and digits
|
|
|
|
representing an integer with the radix specified by \fIbase\fP, optionally
|
|
|
|
preceded by a \fB'+'\fP or \fB'-'\fP sign. The
|
|
|
|
letters from \fB'a'\fP (or \fB'A'\fP ) to \fB'z'\fP (or \fB'Z'\fP
|
|
|
|
) inclusive are ascribed the values 10 to 35; only
|
|
|
|
letters whose ascribed values are less than that of \fIbase\fP are
|
|
|
|
permitted. If the value of \fIbase\fP is 16, the characters 0x
|
|
|
|
or 0X may optionally precede the sequence of letters and digits, following
|
|
|
|
the sign if present.
|
|
|
|
.LP
|
|
|
|
The subject sequence is defined as the longest initial subsequence
|
|
|
|
of the input string, starting with the first non-white-space
|
|
|
|
character that is of the expected form. The subject sequence shall
|
|
|
|
contain no characters if the input string is empty or consists
|
|
|
|
entirely of white-space characters, or if the first non-white-space
|
|
|
|
character is other than a sign or a permissible letter or
|
|
|
|
digit.
|
|
|
|
.LP
|
|
|
|
If the subject sequence has the expected form and the value of \fIbase\fP
|
|
|
|
is 0, the sequence of characters starting with the
|
|
|
|
first digit shall be interpreted as an integer constant. If the subject
|
|
|
|
sequence has the expected form and the value of \fIbase\fP
|
|
|
|
is between 2 and 36, it shall be used as the base for conversion,
|
|
|
|
ascribing to each letter its value as given above. If the subject
|
|
|
|
sequence begins with a minus sign, the value resulting from the conversion
|
|
|
|
shall be negated. A pointer to the final string shall be
|
|
|
|
stored in the object pointed to by \fIendptr\fP, provided that \fIendptr\fP
|
|
|
|
is not a null pointer.
|
|
|
|
.LP
|
|
|
|
In other than the C \ or POSIX locales, other
|
|
|
|
implementation-defined subject sequences may be accepted.
|
|
|
|
.LP
|
|
|
|
If the subject sequence is empty or does not have the expected form,
|
|
|
|
no conversion shall be performed; the value of \fIstr\fP
|
|
|
|
shall be stored in the object pointed to by \fIendptr\fP, provided
|
|
|
|
that \fIendptr\fP is not a null pointer.
|
|
|
|
.LP
|
|
|
|
The
|
|
|
|
\fIstrtoul\fP() function shall not change the setting of \fIerrno\fP
|
|
|
|
if successful.
|
|
|
|
.LP
|
|
|
|
Since 0, {ULONG_MAX}, and {ULLONG_MAX} are returned on error and are
|
|
|
|
also valid returns on success, an application wishing to
|
|
|
|
check for error situations should set \fIerrno\fP to 0, then call
|
|
|
|
\fIstrtoul\fP() or \fIstrtoull\fP(), then check \fIerrno\fP.
|
|
|
|
.SH RETURN VALUE
|
|
|
|
.LP
|
|
|
|
Upon successful completion, these functions shall return the converted
|
|
|
|
value, if any. If no conversion could be performed, 0
|
|
|
|
shall be returned \ and \fIerrno\fP may be set to [EINVAL]. If
|
|
|
|
the
|
|
|
|
correct value is outside the range of representable values, {ULONG_MAX}
|
|
|
|
or {ULLONG_MAX} shall be returned and \fIerrno\fP set to
|
|
|
|
[ERANGE].
|
|
|
|
.SH ERRORS
|
|
|
|
.LP
|
|
|
|
These functions shall fail if:
|
|
|
|
.TP 7
|
|
|
|
.B EINVAL
|
|
|
|
The value of \fIbase\fP is not supported.
|
|
|
|
.TP 7
|
|
|
|
.B ERANGE
|
|
|
|
The value to be returned is not representable.
|
|
|
|
.sp
|
|
|
|
.LP
|
|
|
|
These functions may fail if:
|
|
|
|
.TP 7
|
|
|
|
.B EINVAL
|
|
|
|
No
|
|
|
|
conversion could be performed.
|
|
|
|
.sp
|
|
|
|
.LP
|
|
|
|
\fIThe following sections are informative.\fP
|
|
|
|
.SH EXAMPLES
|
|
|
|
.LP
|
|
|
|
None.
|
|
|
|
.SH APPLICATION USAGE
|
|
|
|
.LP
|
|
|
|
None.
|
|
|
|
.SH RATIONALE
|
|
|
|
.LP
|
|
|
|
None.
|
|
|
|
.SH FUTURE DIRECTIONS
|
|
|
|
.LP
|
|
|
|
None.
|
|
|
|
.SH SEE ALSO
|
|
|
|
.LP
|
2007-09-20 06:11:55 +00:00
|
|
|
\fIisalpha\fP(), \fIscanf\fP(), \fIstrtod\fP(), \fIstrtol\fP()
|
2004-11-03 13:51:07 +00:00
|
|
|
, the Base Definitions volume of
|
|
|
|
IEEE\ Std\ 1003.1-2001, \fI<stdlib.h>\fP
|
|
|
|
.SH COPYRIGHT
|
|
|
|
Portions of this text are reprinted and reproduced in electronic form
|
|
|
|
from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
|
|
|
|
-- Portable Operating System Interface (POSIX), The Open Group Base
|
|
|
|
Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
|
|
|
|
Electrical and Electronics Engineers, Inc and The Open Group. In the
|
|
|
|
event of any discrepancy between this version and the original IEEE and
|
|
|
|
The Open Group Standard, the original IEEE and The Open Group Standard
|
|
|
|
is the referee document. The original Standard can be obtained online at
|
|
|
|
http://www.opengroup.org/unix/online.html .
|