strtoul(3c) - osol9

1strtoul(3C)              Standard C Library Functions              strtoul(3C)
2
3
4

NAME

6       strtoul, strtoull - convert string to unsigned long
7

SYNOPSIS

9       #include <stdlib.h>
10
11       unsigned long strtoul(const char *restrict str,
12            char **restrict endptr, int base);
13
14
15       unsigned long long strtoull(const char *restrict str,
16            char **restrict endptr, int base);
17
18

DESCRIPTION

20       The  strtoul()  function  converts  the  initial  portion of the string
21       pointed to by str to a type unsigned long int representation. First  it
22       decomposes  the  input  string  into  three parts: an initial, possibly
23       empty,  sequence  of  white-space  characters  (as  specified  by  iss‐
24       pace(3C));  a subject sequence interpreted as an integer represented in
25       some radix determined by the value of base; and a final string  of  one
26       or more unrecognised characters, including the terminating null byte of
27       the input string. Then it attempts to convert the subject  sequence  to
28       an unsigned integer, and returns the result.
29
30
31       If the value of base is 0, the expected form of the subject sequence is
32       that of a decimal constant, octal constant or hexadecimal constant, any
33       of  which  may  be preceded by a + or − sign. A decimal constant begins
34       with a non-zero digit, and consists of a sequence of decimal digits. An
35       octal  constant  consists  of  the  prefix  0  optionally followed by a
36       sequence of the digits 0 to 7 only. A hexadecimal constant consists  of
37       the  prefix  0x  or 0X followed by a sequence of the decimal digits and
38       letters a (or A) to f (or F) with values 10 to 15 respectively.
39
40
41       If the value of base is between 2 and 36, the expected form of the sub‐
42       ject sequence is a sequence of letters and digits representing an inte‐
43       ger with the radix specified by base, optionally preceded by a +  or  −
44       sign.  The letters from a (or A) to z (or Z) inclusive are ascribed the
45       values 10 to 35; only letters whose ascribed values are less than  that
46       of base are permitted. If the value of base is 16, the characters 0x or
47       0X may optionally precede the sequence of letters and digits, following
48       the sign if present.
49
50
51       The  subject  sequence is defined as the longest initial subsequence of
52       the input string, starting with the  first  non-white-space  character,
53       that  is of the expected form. The subject sequence contains no charac‐
54       ters if the input string is empty or consists entirely  of  white-space
55       characters,  or  if the first non-white-space character is other than a
56       sign or a permissible letter or digit.
57
58
59       If the subject sequence has the expected form and the value of base  is
60       0,  the  sequence of characters starting with the first digit is inter‐
61       preted as an integer constant. If the subject sequence has the expected
62       form  and the value of base is between 2 and 36, it is used as the base
63       for conversion, ascribing to each letter its value as given  above.  If
64       the subject sequence begins with a minus sign, the value resulting from
65       the conversion is negated. A pointer to the final string is  stored  in
66       the  object  pointed  to  by endptr, provided that endptr is not a null
67       pointer.
68
69
70       In other than the  POSIX  locale,  additional  implementation-dependent
71       subject sequence forms may be accepted.
72
73
74       If the subject sequence is empty or does not have the expected form, no
75       conversion is performed; the value of  str  is  stored  in  the  object
76       pointed to by endptr, provided that endptr is not a null pointer.
77
78
79       The  strtoull()  function  is  identical  to  strtoul()  except that it
80       returns the value represented by str as an unsigned long long.
81

RETURN VALUES

83       Upon successful completion strtoul() returns the  converted  value,  if
84       any.  If  no conversion could be performed, 0 is returned and errno may
85       be set to EINVAL. If the correct value is outside the range  of  repre‐
86       sentable values, ULONG_MAX is returned and errno is set to ERANGE.
87

ERRORS

89       The strtoul() function will fail if:
90
91       EINVAL    The value of base is not supported.
92
93
94       ERANGE    The value to be returned is not representable.
95
96
97
98       The strtoul() function may fail if:
99
100       EINVAL    No conversion could be performed.
101
102

USAGE

104       Because  0  and  ULONG_MAX  are  returned  on  error and are also valid
105       returns on success, an application wishing to check  for  error  situa‐
106       tions  should set errno to 0, then call strtoul(), then check errno and
107       if it is non-zero, assume an error has occurred.
108
109
110       Unlike strtod(3C) and strtol(3C), strtoul() must always return  a  non-
111       negative  number;  so,  using the return value of strtoul() for out-of-
112       range numbers with strtoul() could cause more severe problems than just
113       loss of precision if those numbers can ever be negative.
114

ATTRIBUTES

116       See attributes(5) for descriptions of the following attributes:
117
118
119
120
121       ┌─────────────────────────────┬─────────────────────────────┐
122       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
123       ├─────────────────────────────┼─────────────────────────────┤
124       │Interface Stability          │Standard                     │
125       ├─────────────────────────────┼─────────────────────────────┤
126       │MT-Level                     │MT-Safe                      │
127       └─────────────────────────────┴─────────────────────────────┘
128