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

PROLOG

6       This  manual  page is part of the POSIX Programmer's Manual.  The Linux
7       implementation of this interface may differ (consult the  corresponding
8       Linux  manual page for details of Linux behavior), or the interface may
9       not be implemented on Linux.
10

NAME

12       strtoul, strtoull — convert a string to an unsigned long
13

SYNOPSIS

15       #include <stdlib.h>
16
17       unsigned long strtoul(const char *restrict str,
18           char **restrict endptr, int base);
19       unsigned long long strtoull(const char *restrict str,
20           char **restrict endptr, int base);
21

DESCRIPTION

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

RETURN VALUE

97       Upon  successful completion, these functions shall return the converted
98       value, if any. If no conversion could be performed, 0 shall be returned
99       and errno may be set to [EINVAL].
100
101       If  the  value  of base is not supported, 0 shall be returned and errno
102       shall be set to [EINVAL].
103
104       If the correct value is outside  the  range  of  representable  values,
105       {ULONG_MAX}  or  {ULLONG_MAX}  shall  be  returned  and  errno  set  to
106       [ERANGE].
107

ERRORS

109       These functions shall fail if:
110
111       EINVAL The value of base is not supported.
112
113       ERANGE The value to be returned is not representable.
114
115       These functions may fail if:
116
117       EINVAL No conversion could be performed.
118
119       The following sections are informative.
120

EXAMPLES

122       None.
123

APPLICATION USAGE

125       Since the value of *endptr is unspecified if the value of base  is  not
126       supported,  applications should either ensure that base has a supported
127       value (0 or between 2 and 36) before the call, or check for an [EINVAL]
128       error before examining *endptr.
129

RATIONALE

131       None.
132

FUTURE DIRECTIONS

134       None.
135

SEE ALSO

137       fscanf(), isalpha(), strtod(), strtol()
138
139       The Base Definitions volume of POSIX.1‐2017, <stdlib.h>
140
142       Portions  of  this text are reprinted and reproduced in electronic form
143       from IEEE Std 1003.1-2017, Standard for Information Technology --  Por‐
144       table  Operating System Interface (POSIX), The Open Group Base Specifi‐
145       cations Issue 7, 2018 Edition, Copyright (C) 2018 by the  Institute  of
146       Electrical  and  Electronics Engineers, Inc and The Open Group.  In the
147       event of any discrepancy between this version and the original IEEE and
148       The  Open Group Standard, the original IEEE and The Open Group Standard
149       is the referee document. The original Standard can be  obtained  online
150       at http://www.opengroup.org/unix/online.html .
151
152       Any  typographical  or  formatting  errors that appear in this page are
153       most likely to have been introduced during the conversion of the source
154       files  to  man page format. To report such errors, see https://www.ker
155       nel.org/doc/man-pages/reporting_bugs.html .
156
157
158
159IEEE/The Open Group                  2017                          STRTOUL(3P)
Impressum