original/man3/strtol.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:53:39 1993 by Rik Faith (faith@cs.unc.edu)
  30 .\" Added correction due to nsd@bbc.com (Nick Duffek) - aeb, 950610
  31 .TH STRTOL 3  2013-02-10 "GNU" "Linux Programmer's Manual"
  32 .SH NAME
  33 strtol, strtoll, strtoq \- convert a string to a long integer
  34 .SH SYNOPSIS
  35 .nf
  36 .B #include <stdlib.h>
  37 .sp
  38 .BI "long int strtol(const char *" nptr ", char **" endptr ", int " base );
  39 .sp
  40 .BI "long long int strtoll(const char *" nptr ", char **" endptr \
  41 ", int " base );
  42 .fi
  43 .sp
  44 .in -4n
  45 Feature Test Macro Requirements for glibc (see
  46 .BR feature_test_macros (7)):
  47 .in
  48 .sp
  49 .ad l
  50 .BR strtoll ():
  51 .RS 4
  52 XOPEN_SOURCE\ >=\ 600 || _BSD_SOURCE || _SVID_SOURCE || _ISOC99_SOURCE ||
  53 _POSIX_C_SOURCE\ >=\ 200112L;
  54 .br
  55 or
  56 .I cc\ -std=c99
  57 .RE
  58 .ad
  59 .SH DESCRIPTION
  60 The
  61 .BR strtol ()
  62 function converts the initial part of the string
  63 in \fInptr\fP to a long integer value according to the given \fIbase\fP,
  64 which must be between 2 and 36 inclusive, or be the special value 0.
  65 .PP
  66 The string may begin with an arbitrary amount of white space (as
  67 determined by
  68 .BR isspace (3))
  69 followed by a single optional \(aq+\(aq or \(aq\-\(aq sign.
  70 If \fIbase\fP is zero or 16, the string may then include a
  71 "0x" prefix, and the number will be read in base 16; otherwise, a
  72 zero \fIbase\fP is taken as 10 (decimal) unless the next character
  73 is \(aq0\(aq, in which case it is taken as 8 (octal).
  74 .PP
  75 The remainder of the string is converted to a
  76 .I long int
  77 value
  78 in the obvious manner, stopping at the first character which is not a
  79 valid digit in the given base.
  80 (In bases above 10, the letter \(aqA\(aq in
  81 either upper or lower case represents 10, \(aqB\(aq represents 11, and so
  82 forth, with \(aqZ\(aq representing 35.)
  83 .PP
  84 If \fIendptr\fP is not NULL,
  85 .BR strtol ()
  86 stores the address of the
  87 first invalid character in \fI*endptr\fP.
  88 If there were no digits at
  89 all,
  90 .BR strtol ()
  91 stores the original value of \fInptr\fP in
  92 \fI*endptr\fP (and returns 0).
  93 In particular, if \fI*nptr\fP is not \(aq\\0\(aq but \fI**endptr\fP
  94 is \(aq\\0\(aq on return, the entire string is valid.
  95 .PP
  96 The
  97 .BR strtoll ()
  98 function works just like the
  99 .BR strtol ()
 100 function but returns a long long integer value.
 101 .SH RETURN VALUE
 102 The
 103 .BR strtol ()
 104 function returns the result of the conversion,
 105 unless the value would underflow or overflow.
 106 If an underflow occurs,
 107 .BR strtol ()
 108 returns
 109 .BR LONG_MIN .
 110 If an overflow occurs,
 111 .BR strtol ()
 112 returns
 113 .BR LONG_MAX .
 114 In both cases, \fIerrno\fP is set to
 115 .BR ERANGE .
 116 Precisely the same holds for
 117 .BR strtoll ()
 118 (with
 119 .B LLONG_MIN
 120 and
 121 .B LLONG_MAX
 122 instead of
 123 .B LONG_MIN
 124 and
 125 .BR LONG_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 .LP
 137 The implementation may also set \fIerrno\fP to \fBEINVAL\fP in case
 138 no conversion was performed (no digits seen, and 0 returned).
 139 .SH CONFORMING TO
 140 .BR strtol ()
 141 conforms to SVr4, 4.3BSD, C89, C99 and POSIX.1-2001, and
 142 .BR strtoll ()
 143 to C99 and POSIX.1-2001.
 144 .SH NOTES
 145 Since
 146 .BR strtol ()
 147 can legitimately return 0,
 148 .BR LONG_MAX ,
 149 or
 150 .B LONG_MIN
 151 .RB ( LLONG_MAX
 152 or
 153 .B LLONG_MIN
 154 for
 155 .BR strtoll ())
 156 on both success and failure, the calling program should set
 157 .I errno
 158 to 0 before the call,
 159 and then determine if an error occurred by checking whether
 160 .I errno
 161 has a nonzero value after the call.
 162
 163 According to POSIX.1-2001,
 164 in locales other than the "C" and "POSIX",
 165 these functions may accept other,
 166 implementation-defined numeric strings.
 167 .LP
 168 BSD also has
 169 .sp
 170 .in +4n
 171 .nf
 172 .BI "quad_t strtoq(const char *" nptr ", char **" endptr ", int " base );
 173 .sp
 174 .in
 175 .fi
 176 with completely analogous definition.
 177 Depending on the wordsize of the current architecture, this
 178 may be equivalent to
 179 .BR strtoll ()
 180 or to
 181 .BR strtol ().
 182 .SH EXAMPLE
 183 The program shown below demonstrates the use of
 184 .BR strtol ().
 185 The first command-line argument specifies a string from which
 186 .BR strtol ()
 187 should parse a number.
 188 The second (optional) argument specifies the base to be used for
 189 the conversion.
 190 (This argument is converted to numeric form using
 191 .BR atoi (3),
 192 a function that performs no error checking and
 193 has a simpler interface than
 194 .BR strtol ().)
 195 Some examples of the results produced by this program are the following:
 196 .in +4n
 197 .nf
 198
 199 .RB "$" " ./a.out 123"
 200 strtol() returned 123
 201 .RB "$" " ./a.out \(aq    123\(aq"
 202 strtol() returned 123
 203 .RB "$" " ./a.out 123abc"
 204 strtol() returned 123
 205 Further characters after number: abc
 206 .RB "$" " ./a.out 123abc 55"
 207 strtol: Invalid argument
 208 .RB "$" " ./a.out \(aq\(aq"
 209 No digits were found
 210 .RB "$" " ./a.out 4000000000"
 211 strtol: Numerical result out of range
 212 .fi
 213 .in
 214 .SS Program source
 215 \&
 216 .nf
 217 #include <stdlib.h>
 218 #include <limits.h>
 219 #include <stdio.h>
 220 #include <errno.h>
 221
 222 int
 223 main(int argc, char *argv[])
 224 {
 225     int base;
 226     char *endptr, *str;
 227     long val;
 228
 229     if (argc < 2) {
 230         fprintf(stderr, "Usage: %s str [base]\\n", argv[0]);
 231         exit(EXIT_FAILURE);
 232     }
 233
 234     str = argv[1];
 235     base = (argc > 2) ? atoi(argv[2]) : 10;
 236
 237     errno = 0;    /* To distinguish success/failure after call */
 238     val = strtol(str, &endptr, base);
 239
 240     /* Check for various possible errors */
 241
 242     if ((errno == ERANGE && (val == LONG_MAX || val == LONG_MIN))
 243             || (errno != 0 && val == 0)) {
 244         perror("strtol");
 245         exit(EXIT_FAILURE);
 246     }
 247
 248     if (endptr == str) {
 249         fprintf(stderr, "No digits were found\\n");
 250         exit(EXIT_FAILURE);
 251     }
 252
 253     /* If we got here, strtol() successfully parsed a number */
 254
 255     printf("strtol() returned %ld\\n", val);
 256
 257     if (*endptr != \(aq\\0\(aq)        /* Not necessarily an error... */
 258         printf("Further characters after number: %s\\n", endptr);
 259
 260     exit(EXIT_SUCCESS);
 261 }
 262 .fi
 263 .SH SEE ALSO
 264 .BR atof (3),
 265 .BR atoi (3),
 266 .BR atol (3),
 267 .BR strtod (3),
 268 .BR strtoul (3)