man3/strtol.3

   1 .\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk)
   2 .\" and Copyright 2006 Michael Kerrisk <mtk.manpages@ganil.com>
   3 .\"
   4 .\" %%%LICENSE_START(VERBATIM)
   5 .\" Permission is granted to make and distribute verbatim copies of this
   6 .\" manual provided the copyright notice and this permission notice are
   7 .\" preserved on all copies.
   8 .\"
   9 .\" Permission is granted to copy and distribute modified versions of this
  10 .\" manual under the conditions for verbatim copying, provided that the
  11 .\" entire resulting derived work is distributed under the terms of a
  12 .\" permission notice identical to this one.
  13 .\"
  14 .\" Since the Linux kernel and libraries are constantly changing, this
  15 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  16 .\" responsibility for errors or omissions, or for damages resulting from
  17 .\" the use of the information contained herein.  The author(s) may not
  18 .\" have taken the same level of care in the production of this manual,
  19 .\" which is licensed free of charge, as they might when working
  20 .\" professionally.
  21 .\"
  22 .\" Formatted or processed versions of this manual, if unaccompanied by
  23 .\" the source, must acknowledge the copyright and authors of this work.
  24 .\" %%%LICENSE_END
  25 .\"
  26 .\" References consulted:
  27 .\"     Linux libc source code
  28 .\"     Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991)
  29 .\"     386BSD man pages
  30 .\" Modified Sun Jul 25 10:53:39 1993 by Rik Faith (faith@cs.unc.edu)
  31 .\" Added correction due to nsd@bbc.com (Nick Duffek) - aeb, 950610
  32 .TH STRTOL 3  2021-03-22 "GNU" "Linux Programmer's Manual"
  33 .SH NAME
  34 strtol, strtoll, strtoq \- convert a string to a long integer
  35 .SH SYNOPSIS
  36 .nf
  37 .B #include <stdlib.h>
  38 .PP
  39 .BI "long strtol(const char *restrict " nptr ,
  40 .BI "            char **restrict " endptr ", int " base );
  41 .BI "long long strtoll(const char *restrict " nptr ,
  42 .BI "            char **restrict " endptr ", int " base );
  43 .fi
  44 .PP
  45 .RS -4
  46 Feature Test Macro Requirements for glibc (see
  47 .BR feature_test_macros (7)):
  48 .RE
  49 .PP
  50 .BR strtoll ():
  51 .nf
  52     _ISOC99_SOURCE
  53         || /* Glibc <= 2.19: */ _SVID_SOURCE || _BSD_SOURCE
  54 .fi
  55 .SH DESCRIPTION
  56 The
  57 .BR strtol ()
  58 function converts the initial part of the string
  59 in
  60 .I nptr
  61 to a long integer value according to the given
  62 .IR base ,
  63 which must be between 2 and 36 inclusive, or be the special value 0.
  64 .PP
  65 The string may begin with an arbitrary amount of white space (as
  66 determined by
  67 .BR isspace (3))
  68 followed by a single optional \(aq+\(aq or \(aq\-\(aq sign.
  69 If
  70 .I base
  71 is zero or 16, the string may then include a
  72 "0x" or "0X" prefix, and the number will be read in base 16; otherwise, a
  73 zero
  74 .I base
  75 is taken as 10 (decimal) unless the next character
  76 is \(aq0\(aq, in which case it is taken as 8 (octal).
  77 .PP
  78 The remainder of the string is converted to a
  79 .I long
  80 value
  81 in the obvious manner, stopping at the first character which is not a
  82 valid digit in the given base.
  83 (In bases above 10, the letter \(aqA\(aq in
  84 either uppercase or lowercase represents 10, \(aqB\(aq represents 11, and so
  85 forth, with \(aqZ\(aq representing 35.)
  86 .PP
  87 If
  88 .I endptr
  89 is not NULL,
  90 .BR strtol ()
  91 stores the address of the
  92 first invalid character in
  93 .IR *endptr .
  94 If there were no digits at
  95 all,
  96 .BR strtol ()
  97 stores the original value of
  98 .I nptr
  99 in
 100 .I *endptr
 101 (and returns 0).
 102 In particular, if
 103 .I *nptr
 104 is not \(aq\e0\(aq but
 105 .I **endptr
 106 is \(aq\e0\(aq on return, the entire string is valid.
 107 .PP
 108 The
 109 .BR strtoll ()
 110 function works just like the
 111 .BR strtol ()
 112 function but returns a
 113 .I long long
 114 integer value.
 115 .SH RETURN VALUE
 116 The
 117 .BR strtol ()
 118 function returns the result of the conversion,
 119 unless the value would underflow or overflow.
 120 If an underflow occurs,
 121 .BR strtol ()
 122 returns
 123 .BR LONG_MIN .
 124 If an overflow occurs,
 125 .BR strtol ()
 126 returns
 127 .BR LONG_MAX .
 128 In both cases,
 129 .I errno
 130 is set to
 131 .BR ERANGE .
 132 Precisely the same holds for
 133 .BR strtoll ()
 134 (with
 135 .B LLONG_MIN
 136 and
 137 .B LLONG_MAX
 138 instead of
 139 .B LONG_MIN
 140 and
 141 .BR LONG_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 strtol (),
 171 .BR strtoll (),
 172 .BR strtoq ()
 173 T}      Thread safety   MT-Safe locale
 174 .TE
 175 .hy
 176 .ad
 177 .sp 1
 178 .SH CONFORMING TO
 179 .BR strtol ():
 180 POSIX.1-2001, POSIX.1-2008, C89, C99 SVr4, 4.3BSD.
 181 .PP
 182 .BR strtoll ():
 183 POSIX.1-2001, POSIX.1-2008, C99.
 184 .SH NOTES
 185 Since
 186 .BR strtol ()
 187 can legitimately return 0,
 188 .BR LONG_MAX ,
 189 or
 190 .B LONG_MIN
 191 .RB ( LLONG_MAX
 192 or
 193 .B LLONG_MIN
 194 for
 195 .BR strtoll ())
 196 on both success and failure, the calling program should set
 197 .I errno
 198 to 0 before the call,
 199 and then determine if an error occurred by checking whether
 200 .I errno
 201 has a nonzero value after the call.
 202 .PP
 203 According to POSIX.1,
 204 in locales other than "C" and "POSIX",
 205 these functions may accept other,
 206 implementation-defined numeric strings.
 207 .PP
 208 BSD also has
 209 .PP
 210 .in +4n
 211 .EX
 212 .BI "quad_t strtoq(const char *" nptr ", char **" endptr ", int " base );
 213 .EE
 214 .in
 215 .PP
 216 with completely analogous definition.
 217 Depending on the wordsize of the current architecture, this
 218 may be equivalent to
 219 .BR strtoll ()
 220 or to
 221 .BR strtol ().
 222 .SH EXAMPLES
 223 The program shown below demonstrates the use of
 224 .BR strtol ().
 225 The first command-line argument specifies a string from which
 226 .BR strtol ()
 227 should parse a number.
 228 The second (optional) argument specifies the base to be used for
 229 the conversion.
 230 (This argument is converted to numeric form using
 231 .BR atoi (3),
 232 a function that performs no error checking and
 233 has a simpler interface than
 234 .BR strtol ().)
 235 Some examples of the results produced by this program are the following:
 236 .PP
 237 .in +4n
 238 .EX
 239 .RB "$" " ./a.out 123"
 240 strtol() returned 123
 241 .RB "$" " ./a.out \(aq    123\(aq"
 242 strtol() returned 123
 243 .RB "$" " ./a.out 123abc"
 244 strtol() returned 123
 245 Further characters after number: "abc"
 246 .RB "$" " ./a.out 123abc 55"
 247 strtol: Invalid argument
 248 .RB "$" " ./a.out \(aq\(aq"
 249 No digits were found
 250 .RB "$" " ./a.out 4000000000"
 251 strtol: Numerical result out of range
 252 .EE
 253 .in
 254 .SS Program source
 255 \&
 256 .EX
 257 #include <stdlib.h>
 258 #include <limits.h>
 259 #include <stdio.h>
 260 #include <errno.h>
 261
 262 int
 263 main(int argc, char *argv[])
 264 {
 265     int base;
 266     char *endptr, *str;
 267     long val;
 268
 269     if (argc < 2) {
 270         fprintf(stderr, "Usage: %s str [base]\en", argv[0]);
 271         exit(EXIT_FAILURE);
 272     }
 273
 274     str = argv[1];
 275     base = (argc > 2) ? atoi(argv[2]) : 0;
 276
 277     errno = 0;    /* To distinguish success/failure after call */
 278     val = strtol(str, &endptr, base);
 279
 280     /* Check for various possible errors. */
 281
 282     if (errno != 0) {
 283         perror("strtol");
 284         exit(EXIT_FAILURE);
 285     }
 286
 287     if (endptr == str) {
 288         fprintf(stderr, "No digits were found\en");
 289         exit(EXIT_FAILURE);
 290     }
 291
 292     /* If we got here, strtol() successfully parsed a number. */
 293
 294     printf("strtol() returned %ld\en", val);
 295
 296     if (*endptr != \(aq\e0\(aq)        /* Not necessarily an error... */
 297         printf("Further characters after number: \e"%s\e"\en", endptr);
 298
 299     exit(EXIT_SUCCESS);
 300 }
 301 .EE
 302 .SH SEE ALSO
 303 .BR atof (3),
 304 .BR atoi (3),
 305 .BR atol (3),
 306 .BR strtod (3),
 307 .BR strtoimax (3),
 308 .BR strtoul (3),