man3/strtoul.3

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