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