1STRTOUL(P)                 POSIX Programmer's Manual                STRTOUL(P)
2
3
4

NAME

6       strtoul, strtoull - convert a string to an unsigned long
7

SYNOPSIS

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

DESCRIPTION

18       These functions shall convert the initial portion of the string pointed
19       to by str to a type unsigned long and unsigned  long  long  representa‐
20       tion,  respectively.  First, they decompose the input string into three
21       parts:
22
23        1. An initial, possibly empty, sequence of white-space characters  (as
24           specified by isspace())
25
26        2. A  subject  sequence  interpreted as an integer represented in some
27           radix determined by the value of base
28
29        3. A final string of one or more  unrecognized  characters,  including
30           the terminating null byte of the input string
31
32       Then  they shall attempt to convert the subject sequence to an unsigned
33       integer, and return the result.
34
35       If the value of base is 0, the expected form of the subject sequence is
36       that  of  a  decimal constant, octal constant, or hexadecimal constant,
37       any of which may be preceded by a '+' or '-' sign. A  decimal  constant
38       begins  with  a  non-zero  digit, and consists of a sequence of decimal
39       digits. An octal constant consists of the prefix  '0'  optionally  fol‐
40       lowed  by a sequence of the digits '0' to '7' only.  A hexadecimal con‐
41       stant consists of the prefix 0x or 0X followed by  a  sequence  of  the
42       decimal  digits  and letters 'a' (or 'A' ) to 'f' (or 'F' ) with values
43       10 to 15 respectively.
44
45       If the value of base is between 2 and 36, the expected form of the sub‐
46       ject sequence is a sequence of letters and digits representing an inte‐
47       ger with the radix specified by base, optionally preceded by a  '+'  or
48       '-' sign. The letters from 'a' (or 'A' ) to 'z' (or 'Z' ) inclusive are
49       ascribed the values 10 to 35; only letters whose  ascribed  values  are
50       less  than  that of base are permitted. If the value of base is 16, the
51       characters 0x or 0X may optionally precede the sequence of letters  and
52       digits, following the sign if present.
53
54       The  subject  sequence is defined as the longest initial subsequence of
55       the input string, starting with  the  first  non-white-space  character
56       that  is  of  the  expected form. The subject sequence shall contain no
57       characters if the input string is empty or consists entirely of  white-
58       space  characters,  or  if the first non-white-space character is other
59       than a sign or a permissible letter or digit.
60
61       If the subject sequence has the expected form and the value of base  is
62       0,  the  sequence  of characters starting with the first digit shall be
63       interpreted as an integer constant. If the  subject  sequence  has  the
64       expected  form  and  the value of base is between 2 and 36, it shall be
65       used as the base for conversion, ascribing to each letter its value  as
66       given  above.  If  the  subject  sequence begins with a minus sign, the
67       value resulting from the conversion shall be negated. A pointer to  the
68       final  string  shall be stored in the object pointed to by endptr, pro‐
69       vided that endptr is not a null pointer.
70
71       In other than the C    or POSIX  locales, other  implementation-defined
72       subject sequences may be accepted.
73
74       If the subject sequence is empty or does not have the expected form, no
75       conversion shall be performed; the value of str shall be stored in  the
76       object  pointed  to  by  endptr,  provided  that  endptr  is not a null
77       pointer.
78
79       The strtoul() function shall not change the setting of  errno  if  suc‐
80       cessful.
81
82       Since  0,  {ULONG_MAX},  and {ULLONG_MAX} are returned on error and are
83       also valid returns on success, an  application  wishing  to  check  for
84       error  situations  should  set  errno to 0, then call strtoul() or str‐
85       toull(), then check errno.
86

RETURN VALUE

88       Upon successful completion, these functions shall return the  converted
89       value, if any. If no conversion could be performed, 0 shall be returned
90        and errno may be set to [EINVAL].  If the correct value is outside the
91       range  of  representable  values,  {ULONG_MAX} or {ULLONG_MAX} shall be
92       returned and errno set to [ERANGE].
93

ERRORS

95       These functions shall fail if:
96
97       EINVAL The value of base is not supported.
98
99       ERANGE The value to be returned is not representable.
100
101
102       These functions may fail if:
103
104       EINVAL No conversion could be performed.
105
106
107       The following sections are informative.
108

EXAMPLES

110       None.
111

APPLICATION USAGE

113       None.
114

RATIONALE

116       None.
117

FUTURE DIRECTIONS

119       None.
120

SEE ALSO

122       isalpha() , scanf() , strtod() , strtol() , the Base Definitions volume
123       of IEEE Std 1003.1-2001, <stdlib.h>
124
126       Portions  of  this text are reprinted and reproduced in electronic form
127       from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
128       --  Portable  Operating  System  Interface (POSIX), The Open Group Base
129       Specifications Issue 6, Copyright (C) 2001-2003  by  the  Institute  of
130       Electrical  and  Electronics  Engineers, Inc and The Open Group. In the
131       event of any discrepancy between this version and the original IEEE and
132       The  Open Group Standard, the original IEEE and The Open Group Standard
133       is the referee document. The original Standard can be  obtained  online
134       at http://www.opengroup.org/unix/online.html .
135
136
137
138IEEE/The Open Group                  2003                           STRTOUL(P)
Impressum