Commit | Line | Data |
---|---|---|
7860c229 KB |
1 | .\" Copyright (c) 1990, 1991, 1993 |
2 | .\" The Regents of the University of California. All rights reserved. | |
375c4de4 KB |
3 | .\" |
4 | .\" This code is derived from software contributed to Berkeley by | |
043368e6 KB |
5 | .\" Chris Torek and the American National Standards Committee X3, |
6 | .\" on Information Processing Systems. | |
7 | .\" | |
375c4de4 KB |
8 | .\" %sccs.include.redist.man% |
9 | .\" | |
7860c229 | 10 | .\" @(#)strtoul.3 8.1 (Berkeley) %G% |
375c4de4 | 11 | .\" |
9c42089d CL |
12 | .Dd |
13 | .Dt STRTOUL 3 | |
14 | .Os | |
15 | .Sh NAME | |
1778ab6f KB |
16 | .Nm strtoul, strtouq |
17 | .Nd convert a string to an unsigned long or uquad_t integer | |
9c42089d CL |
18 | .Sh SYNOPSIS |
19 | .Fd #include <stdlib.h> | |
20 | .Fd #include <limits.h> | |
1778ab6f | 21 | .Ft unsigned long |
9c42089d | 22 | .Fn strtoul "const char *nptr" "char **endptr" "int base" |
1778ab6f KB |
23 | |
24 | .Fd #include <sys/types.h> | |
25 | .Fd #include <stdlib.h> | |
26 | .Fd #include <limits.h> | |
27 | .Ft u_quad_t | |
28 | .Fn strtouq "const char *nptr" "char **endptr" "int base" | |
9c42089d CL |
29 | .Sh DESCRIPTION |
30 | The | |
31 | .Fn strtoul | |
32 | function | |
375c4de4 | 33 | converts the string in |
9c42089d | 34 | .Fa nptr |
375c4de4 | 35 | to an |
9c42089d | 36 | .Em unsigned long |
1778ab6f KB |
37 | value. |
38 | The | |
39 | .Fn strtouq | |
40 | function | |
41 | converts the string in | |
42 | .Fa nptr | |
43 | to a | |
44 | .Em u_quad_t | |
45 | value. | |
46 | The conversion is done according to the given | |
9c42089d | 47 | .Fa base , |
375c4de4 KB |
48 | which must be between 2 and 36 inclusive, |
49 | or be the special value 0. | |
9c42089d | 50 | .Pp |
375c4de4 KB |
51 | The string may begin with an arbitrary amount of white space |
52 | (as determined by | |
9c42089d CL |
53 | .Xr isspace 3 ) |
54 | followed by a single optional | |
55 | .Ql + | |
56 | or | |
57 | .Ql - | |
58 | sign. | |
375c4de4 | 59 | If |
9c42089d | 60 | .Fa base |
375c4de4 | 61 | is zero or 16, |
9c42089d CL |
62 | the string may then include a |
63 | .Ql 0x | |
64 | prefix, | |
375c4de4 | 65 | and the number will be read in base 16; otherwise, a zero |
9c42089d CL |
66 | .Fa base |
67 | is taken as 10 (decimal) unless the next character is | |
68 | .Ql 0 , | |
375c4de4 | 69 | in which case it is taken as 8 (octal). |
9c42089d | 70 | .Pp |
375c4de4 | 71 | The remainder of the string is converted to an |
9c42089d | 72 | .Em unsigned long |
375c4de4 KB |
73 | value in the obvious manner, |
74 | stopping at the end of the string | |
75 | or at the first character that does not produce a valid digit | |
76 | in the given base. | |
9c42089d CL |
77 | (In bases above 10, the letter |
78 | .Ql A | |
79 | in either upper or lower case | |
80 | represents 10, | |
81 | .Ql B | |
82 | represents 11, and so forth, with | |
83 | .Ql Z | |
84 | representing 35.) | |
85 | .Pp | |
375c4de4 | 86 | If |
9c42089d | 87 | .Fa endptr |
375c4de4 | 88 | is non nil, |
9c42089d | 89 | .Fn strtoul |
375c4de4 | 90 | stores the address of the first invalid character in |
9c42089d | 91 | .Fa *endptr . |
375c4de4 | 92 | If there were no digits at all, however, |
9c42089d | 93 | .Fn strtoul |
375c4de4 | 94 | stores the original value of |
9c42089d | 95 | .Fa nptr |
375c4de4 | 96 | in |
9c42089d | 97 | .Fa *endptr . |
375c4de4 | 98 | (Thus, if |
9c42089d CL |
99 | .Fa *nptr |
100 | is not | |
101 | .Ql \e0 | |
102 | but | |
103 | .Fa **endptr | |
104 | is | |
105 | .Ql \e0 | |
106 | on return, the entire string was valid.) | |
107 | .Sh RETURN VALUES | |
108 | The | |
109 | .Fn strtoul | |
110 | function | |
375c4de4 KB |
111 | returns either the result of the conversion |
112 | or, if there was a leading minus sign, | |
113 | the negation of the result of the conversion, | |
114 | unless the original (non-negated) value would overflow; | |
115 | in the latter case, | |
9c42089d | 116 | .Fn strtoul |
375c4de4 | 117 | returns |
9c42089d CL |
118 | .Dv ULONG_MAX |
119 | and sets the global variable | |
120 | .Va errno | |
375c4de4 | 121 | to |
9c42089d CL |
122 | .Er ERANGE . |
123 | .Sh ERRORS | |
124 | .Bl -tag -width [ERANGE] | |
125 | .It Bq Er ERANGE | |
375c4de4 | 126 | The given string was out of range; the value converted has been clamped. |
9c42089d CL |
127 | .El |
128 | .Sh SEE ALSO | |
129 | .Xr strtol 3 | |
130 | .Sh STANDARDS | |
131 | The | |
132 | .Fn strtoul | |
133 | function | |
134 | conforms to | |
135 | .St -ansiC . | |
136 | .Sh BUGS | |
375c4de4 | 137 | Ignores the current locale. |