1
by Francesco Paolo Lovergine
rules: linking manpages-posix not manpages. |
1 |
.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved |
2
by Francesco Paolo Lovergine
* Alligned to linux main manpages edition. |
2 |
.TH "STRTOUL" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" |
1
by Francesco Paolo Lovergine
rules: linking manpages-posix not manpages. |
3 |
.\" strtoul |
4 |
.SH NAME |
|
5 |
strtoul, strtoull \- convert a string to an unsigned long
|
|
6 |
.SH SYNOPSIS |
|
7 |
.LP
|
|
8 |
\fB#include <stdlib.h>
|
|
9 |
.br
|
|
10 |
.sp
|
|
11 |
unsigned long strtoul(const char *restrict\fP \fIstr\fP\fB, |
|
12 |
.br
|
|
13 |
\ \ \ \ \ \ char **restrict\fP \fIendptr\fP\fB, int\fP \fIbase\fP\fB); |
|
14 |
.br
|
|
15 |
unsigned long long strtoull(const char *restrict\fP \fIstr\fP\fB, |
|
16 |
.br
|
|
17 |
\ \ \ \ \ \ char **restrict\fP \fIendptr\fP\fB, int\fP \fIbase\fP\fB); |
|
18 |
.br
|
|
19 |
\fP
|
|
20 |
.SH DESCRIPTION |
|
21 |
.LP
|
|
22 |
These functions shall convert the initial portion of the string pointed |
|
23 |
to by \fIstr\fP to a type \fBunsigned long\fP and |
|
24 |
\fBunsigned long long\fP representation, respectively. First, they |
|
25 |
decompose the input string into three parts: |
|
26 |
.IP " 1." 4 |
|
27 |
An initial, possibly empty, sequence of white-space characters (as |
|
28 |
specified by \fIisspace\fP()) |
|
29 |
.LP
|
|
30 |
.IP " 2." 4 |
|
31 |
A subject sequence interpreted as an integer represented in some radix |
|
32 |
determined by the value of \fIbase\fP |
|
33 |
.LP
|
|
34 |
.IP " 3." 4 |
|
35 |
A final string of one or more unrecognized characters, including the |
|
36 |
terminating null byte of the input string |
|
37 |
.LP
|
|
38 |
.LP
|
|
39 |
Then they shall attempt to convert the subject sequence to an unsigned |
|
40 |
integer, and return the result. |
|
41 |
.LP
|
|
42 |
If the value of \fIbase\fP is 0, the expected form of the subject |
|
43 |
sequence is that of a decimal constant, octal constant, or |
|
44 |
hexadecimal constant, any of which may be preceded by a \fB'+'\fP |
|
45 |
or \fB'-'\fP sign. A decimal constant begins with a |
|
46 |
non-zero digit, and consists of a sequence of decimal digits. An octal |
|
47 |
constant consists of the prefix \fB'0'\fP optionally |
|
48 |
followed by a sequence of the digits \fB'0'\fP to \fB'7'\fP only. |
|
49 |
A hexadecimal constant consists of the prefix 0x or 0X |
|
50 |
followed by a sequence of the decimal digits and letters \fB'a'\fP |
|
51 |
(or \fB'A'\fP ) to \fB'f'\fP (or \fB'F'\fP ) with |
|
52 |
values 10 to 15 respectively. |
|
53 |
.LP
|
|
54 |
If the value of \fIbase\fP is between 2 and 36, the expected form |
|
55 |
of the subject sequence is a sequence of letters and digits |
|
56 |
representing an integer with the radix specified by \fIbase\fP, optionally |
|
57 |
preceded by a \fB'+'\fP or \fB'-'\fP sign. The |
|
58 |
letters from \fB'a'\fP (or \fB'A'\fP ) to \fB'z'\fP (or \fB'Z'\fP |
|
59 |
) inclusive are ascribed the values 10 to 35; only |
|
60 |
letters whose ascribed values are less than that of \fIbase\fP are |
|
61 |
permitted. If the value of \fIbase\fP is 16, the characters 0x |
|
62 |
or 0X may optionally precede the sequence of letters and digits, following |
|
63 |
the sign if present. |
|
64 |
.LP
|
|
65 |
The subject sequence is defined as the longest initial subsequence |
|
66 |
of the input string, starting with the first non-white-space |
|
67 |
character that is of the expected form. The subject sequence shall |
|
68 |
contain no characters if the input string is empty or consists |
|
69 |
entirely of white-space characters, or if the first non-white-space |
|
70 |
character is other than a sign or a permissible letter or |
|
71 |
digit. |
|
72 |
.LP
|
|
73 |
If the subject sequence has the expected form and the value of \fIbase\fP |
|
74 |
is 0, the sequence of characters starting with the |
|
75 |
first digit shall be interpreted as an integer constant. If the subject |
|
76 |
sequence has the expected form and the value of \fIbase\fP |
|
77 |
is between 2 and 36, it shall be used as the base for conversion, |
|
78 |
ascribing to each letter its value as given above. If the subject |
|
79 |
sequence begins with a minus sign, the value resulting from the conversion |
|
80 |
shall be negated. A pointer to the final string shall be |
|
81 |
stored in the object pointed to by \fIendptr\fP, provided that \fIendptr\fP |
|
82 |
is not a null pointer. |
|
83 |
.LP
|
|
84 |
In other than the C \ or POSIX locales, other
|
|
85 |
implementation-defined subject sequences may be accepted. |
|
86 |
.LP
|
|
87 |
If the subject sequence is empty or does not have the expected form, |
|
88 |
no conversion shall be performed; the value of \fIstr\fP |
|
89 |
shall be stored in the object pointed to by \fIendptr\fP, provided |
|
90 |
that \fIendptr\fP is not a null pointer. |
|
91 |
.LP
|
|
92 |
The |
|
93 |
\fIstrtoul\fP() function shall not change the setting of \fIerrno\fP |
|
94 |
if successful. |
|
95 |
.LP
|
|
96 |
Since 0, {ULONG_MAX}, and {ULLONG_MAX} are returned on error and are |
|
97 |
also valid returns on success, an application wishing to |
|
98 |
check for error situations should set \fIerrno\fP to 0, then call |
|
99 |
\fIstrtoul\fP() or \fIstrtoull\fP(), then check \fIerrno\fP. |
|
100 |
.SH RETURN VALUE |
|
101 |
.LP
|
|
102 |
Upon successful completion, these functions shall return the converted |
|
103 |
value, if any. If no conversion could be performed, 0 |
|
104 |
shall be returned \ and \fIerrno\fP may be set to [EINVAL]. If |
|
105 |
the |
|
106 |
correct value is outside the range of representable values, {ULONG_MAX} |
|
107 |
or {ULLONG_MAX} shall be returned and \fIerrno\fP set to |
|
108 |
[ERANGE]. |
|
109 |
.SH ERRORS |
|
110 |
.LP
|
|
111 |
These functions shall fail if: |
|
112 |
.TP 7 |
|
113 |
.B EINVAL |
|
114 |
The value of \fIbase\fP is not supported. |
|
115 |
.TP 7 |
|
116 |
.B ERANGE |
|
117 |
The value to be returned is not representable. |
|
118 |
.sp
|
|
119 |
.LP
|
|
120 |
These functions may fail if: |
|
121 |
.TP 7 |
|
122 |
.B EINVAL |
|
123 |
No |
|
124 |
conversion could be performed. |
|
125 |
.sp
|
|
126 |
.LP
|
|
127 |
\fIThe following sections are informative.\fP |
|
128 |
.SH EXAMPLES |
|
129 |
.LP
|
|
130 |
None. |
|
131 |
.SH APPLICATION USAGE |
|
132 |
.LP
|
|
133 |
None. |
|
134 |
.SH RATIONALE |
|
135 |
.LP
|
|
136 |
None. |
|
137 |
.SH FUTURE DIRECTIONS |
|
138 |
.LP
|
|
139 |
None. |
|
140 |
.SH SEE ALSO |
|
141 |
.LP
|
|
142 |
\fIisalpha\fP() , \fIscanf\fP() , \fIstrtod\fP() , \fIstrtol\fP() |
|
143 |
, the Base Definitions volume of |
|
144 |
IEEE\ Std\ 1003.1-2001, \fI<stdlib.h>\fP |
|
145 |
.SH COPYRIGHT |
|
146 |
Portions of this text are reprinted and reproduced in electronic form |
|
147 |
from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology |
|
148 |
-- Portable Operating System Interface (POSIX), The Open Group Base |
|
149 |
Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of |
|
150 |
Electrical and Electronics Engineers, Inc and The Open Group. In the |
|
151 |
event of any discrepancy between this version and the original IEEE and |
|
152 |
The Open Group Standard, the original IEEE and The Open Group Standard |
|
153 |
is the referee document. The original Standard can be obtained online at |
|
154 |
http://www.opengroup.org/unix/online.html . |