man3/strtoul.3

   1 .\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk)
   2 .\"
   3 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   4 .\"
   5 .\" References consulted:
   6 .\"     Linux libc source code
   7 .\"     Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991)
   8 .\"     386BSD man pages
   9 .\" Modified Sun Jul 25 10:54:03 1993 by Rik Faith (faith@cs.unc.edu)
  10 .\" Fixed typo, aeb, 950823
  11 .\" 2002-02-22, joey, mihtjel: Added strtoull()
  12 .\"
  13 .TH STRTOUL 3  2021-03-22 "Linux man-pages (unreleased)" "Linux Programmer's Manual"
  14 .SH NAME
  15 strtoul, strtoull, strtouq \- convert a string to an unsigned long integer
  16 .SH LIBRARY
  17 Standard C library
  18 .RI ( libc ", " \-lc )
  19 .SH SYNOPSIS
  20 .nf
  21 .B #include <stdlib.h>
  22 .PP
  23 .BI "unsigned long strtoul(const char *restrict " nptr ,
  24 .BI "                      char **restrict " endptr ", int " base );
  25 .BI "unsigned long long strtoull(const char *restrict " nptr ,
  26 .BI "                      char **restrict " endptr ", int " base );
  27 .fi
  28 .PP
  29 .RS -4
  30 Feature Test Macro Requirements for glibc (see
  31 .BR feature_test_macros (7)):
  32 .RE
  33 .PP
  34 .BR strtoull ():
  35 .nf
  36     _ISOC99_SOURCE
  37         || /* Glibc <= 2.19: */ _SVID_SOURCE || _BSD_SOURCE
  38 .fi
  39 .SH DESCRIPTION
  40 The
  41 .BR strtoul ()
  42 function converts the initial part of the string
  43 in
  44 .I nptr
  45 to an
  46 .I "unsigned long"
  47 value according to the
  48 given
  49 .IR base ,
  50 which must be between 2 and 36 inclusive, or be
  51 the special value 0.
  52 .PP
  53 The string may begin with an arbitrary amount of white space (as
  54 determined by
  55 .BR isspace (3))
  56 followed by a single optional \(aq+\(aq or \(aq\-\(aq
  57 sign.
  58 If
  59 .I base
  60 is zero or 16, the string may then include a
  61 "0x" prefix, and the number will be read in base 16; otherwise, a
  62 zero
  63 .I base
  64 is taken as 10 (decimal) unless the next character
  65 is \(aq0\(aq, in which case it is taken as 8 (octal).
  66 .PP
  67 The remainder of the string is converted to an
  68 .I "unsigned long"
  69 value in the obvious manner,
  70 stopping at the first character which is not a
  71 valid digit in the given base.
  72 (In bases above 10, the letter \(aqA\(aq in
  73 either uppercase or lowercase represents 10, \(aqB\(aq represents 11, and so
  74 forth, with \(aqZ\(aq representing 35.)
  75 .PP
  76 If
  77 .I endptr
  78 is not NULL,
  79 .BR strtoul ()
  80 stores the address of the
  81 first invalid character in
  82 .IR *endptr .
  83 If there were no digits at
  84 all,
  85 .BR strtoul ()
  86 stores the original value of
  87 .I nptr
  88 in
  89 .I *endptr
  90 (and returns 0).
  91 In particular, if
  92 .I *nptr
  93 is not \(aq\e0\(aq but
  94 .I **endptr
  95 is \(aq\e0\(aq on return, the entire string is valid.
  96 .PP
  97 The
  98 .BR strtoull ()
  99 function works just like the
 100 .BR strtoul ()
 101 function but returns an
 102 .I "unsigned long long"
 103 value.
 104 .SH RETURN VALUE
 105 The
 106 .BR strtoul ()
 107 function returns either the result of the conversion
 108 or, if there was a leading minus sign, the negation of the result of the
 109 conversion represented as an unsigned value,
 110 unless the original (nonnegated) value would overflow; in
 111 the latter case,
 112 .BR strtoul ()
 113 returns
 114 .B ULONG_MAX
 115 and sets
 116 .I errno
 117 to
 118 .BR ERANGE .
 119 Precisely the same holds for
 120 .BR strtoull ()
 121 (with
 122 .B ULLONG_MAX
 123 instead of
 124 .BR ULONG_MAX ).
 125 .SH ERRORS
 126 .TP
 127 .B EINVAL
 128 (not in C99)
 129 The given
 130 .I base
 131 contains an unsupported value.
 132 .TP
 133 .B ERANGE
 134 The resulting value was out of range.
 135 .PP
 136 The implementation may also set
 137 .I errno
 138 to
 139 .B EINVAL
 140 in case
 141 no conversion was performed (no digits seen, and 0 returned).
 142 .SH ATTRIBUTES
 143 For an explanation of the terms used in this section, see
 144 .BR attributes (7).
 145 .ad l
 146 .nh
 147 .TS
 148 allbox;
 149 lbx lb lb
 150 l l l.
 151 Interface       Attribute       Value
 152 T{
 153 .BR strtoul (),
 154 .BR strtoull (),
 155 .BR strtouq ()
 156 T}      Thread safety   MT-Safe locale
 157 .TE
 158 .hy
 159 .ad
 160 .sp 1
 161 .SH STANDARDS
 162 .BR strtoul ():
 163 POSIX.1-2001, POSIX.1-2008, C89, C99 SVr4.
 164 .PP
 165 .BR strtoull ():
 166 POSIX.1-2001, POSIX.1-2008, C99.
 167 .SH NOTES
 168 Since
 169 .BR strtoul ()
 170 can legitimately return 0 or
 171 .B ULONG_MAX
 172 .RB ( ULLONG_MAX
 173 for
 174 .BR strtoull ())
 175 on both success and failure, the calling program should set
 176 .I errno
 177 to 0 before the call,
 178 and then determine if an error occurred by checking whether
 179 .I errno
 180 has a nonzero value after the call.
 181 .PP
 182 In locales other than the "C" locale, other strings may be accepted.
 183 (For example, the thousands separator of the current locale may be
 184 supported.)
 185 .PP
 186 BSD also has
 187 .PP
 188 .in +4n
 189 .EX
 190 .BI "u_quad_t strtouq(const char *" nptr ", char **" endptr ", int " base );
 191 .EE
 192 .in
 193 .PP
 194 with completely analogous definition.
 195 Depending on the wordsize of the current architecture, this
 196 may be equivalent to
 197 .BR strtoull ()
 198 or to
 199 .BR strtoul ().
 200 .PP
 201 Negative values are considered valid input and are
 202 silently converted to the equivalent
 203 .I "unsigned long"
 204 value.
 205 .SH EXAMPLES
 206 See the example on the
 207 .BR strtol (3)
 208 manual page;
 209 the use of the functions described in this manual page is similar.
 210 .SH SEE ALSO
 211 .BR a64l (3),
 212 .BR atof (3),
 213 .BR atoi (3),
 214 .BR atol (3),
 215 .BR strtod (3),
 216 .BR strtol (3),
 217 .BR strtoumax (3)