man3/strtoul.3

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