| .\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) |
| .\" and Copyright 2006 Michael Kerrisk <mtk.manpages@ganil.com> |
| .\" |
| .\" %%%LICENSE_START(VERBATIM) |
| .\" Permission is granted to make and distribute verbatim copies of this |
| .\" manual provided the copyright notice and this permission notice are |
| .\" preserved on all copies. |
| .\" |
| .\" Permission is granted to copy and distribute modified versions of this |
| .\" manual under the conditions for verbatim copying, provided that the |
| .\" entire resulting derived work is distributed under the terms of a |
| .\" permission notice identical to this one. |
| .\" |
| .\" Since the Linux kernel and libraries are constantly changing, this |
| .\" manual page may be incorrect or out-of-date. The author(s) assume no |
| .\" responsibility for errors or omissions, or for damages resulting from |
| .\" the use of the information contained herein. The author(s) may not |
| .\" have taken the same level of care in the production of this manual, |
| .\" which is licensed free of charge, as they might when working |
| .\" professionally. |
| .\" |
| .\" Formatted or processed versions of this manual, if unaccompanied by |
| .\" the source, must acknowledge the copyright and authors of this work. |
| .\" %%%LICENSE_END |
| .\" |
| .\" References consulted: |
| .\" Linux libc source code |
| .\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) |
| .\" 386BSD man pages |
| .\" Modified Sun Jul 25 10:53:39 1993 by Rik Faith (faith@cs.unc.edu) |
| .\" Added correction due to nsd@bbc.com (Nick Duffek) - aeb, 950610 |
| .TH STRTOL 3 2021-03-22 "GNU" "Linux Programmer's Manual" |
| .SH NAME |
| strtol, strtoll, strtoq \- convert a string to a long integer |
| .SH SYNOPSIS |
| .nf |
| .B #include <stdlib.h> |
| .PP |
| .BI "long strtol(const char *restrict " nptr , |
| .BI " char **restrict " endptr ", int " base ); |
| .BI "long long strtoll(const char *restrict " nptr , |
| .BI " char **restrict " endptr ", int " base ); |
| .fi |
| .PP |
| .RS -4 |
| Feature Test Macro Requirements for glibc (see |
| .BR feature_test_macros (7)): |
| .RE |
| .PP |
| .BR strtoll (): |
| .nf |
| _ISOC99_SOURCE |
| || /* Glibc <= 2.19: */ _SVID_SOURCE || _BSD_SOURCE |
| .fi |
| .SH DESCRIPTION |
| The |
| .BR strtol () |
| function converts the initial part of the string |
| in |
| .I nptr |
| to a long integer value according to the given |
| .IR base , |
| which must be between 2 and 36 inclusive, or be the special value 0. |
| .PP |
| The string may begin with an arbitrary amount of white space (as |
| determined by |
| .BR isspace (3)) |
| followed by a single optional \(aq+\(aq or \(aq\-\(aq sign. |
| If |
| .I base |
| is zero or 16, the string may then include a |
| "0x" or "0X" prefix, and the number will be read in base 16; otherwise, a |
| zero |
| .I base |
| is taken as 10 (decimal) unless the next character |
| is \(aq0\(aq, in which case it is taken as 8 (octal). |
| .PP |
| The remainder of the string is converted to a |
| .I long |
| value |
| in the obvious manner, stopping at the first character which is not a |
| valid digit in the given base. |
| (In bases above 10, the letter \(aqA\(aq in |
| either uppercase or lowercase represents 10, \(aqB\(aq represents 11, and so |
| forth, with \(aqZ\(aq representing 35.) |
| .PP |
| If |
| .I endptr |
| is not NULL, |
| .BR strtol () |
| stores the address of the |
| first invalid character in |
| .IR *endptr . |
| If there were no digits at |
| all, |
| .BR strtol () |
| stores the original value of |
| .I nptr |
| in |
| .I *endptr |
| (and returns 0). |
| In particular, if |
| .I *nptr |
| is not \(aq\e0\(aq but |
| .I **endptr |
| is \(aq\e0\(aq on return, the entire string is valid. |
| .PP |
| The |
| .BR strtoll () |
| function works just like the |
| .BR strtol () |
| function but returns a |
| .I long long |
| integer value. |
| .SH RETURN VALUE |
| The |
| .BR strtol () |
| function returns the result of the conversion, |
| unless the value would underflow or overflow. |
| If an underflow occurs, |
| .BR strtol () |
| returns |
| .BR LONG_MIN . |
| If an overflow occurs, |
| .BR strtol () |
| returns |
| .BR LONG_MAX . |
| In both cases, |
| .I errno |
| is set to |
| .BR ERANGE . |
| Precisely the same holds for |
| .BR strtoll () |
| (with |
| .B LLONG_MIN |
| and |
| .B LLONG_MAX |
| instead of |
| .B LONG_MIN |
| and |
| .BR LONG_MAX ). |
| .SH ERRORS |
| .TP |
| .B EINVAL |
| (not in C99) |
| The given |
| .I base |
| contains an unsupported value. |
| .TP |
| .B ERANGE |
| The resulting value was out of range. |
| .PP |
| The implementation may also set |
| .IR errno |
| to |
| .B EINVAL |
| in case |
| no conversion was performed (no digits seen, and 0 returned). |
| .SH ATTRIBUTES |
| For an explanation of the terms used in this section, see |
| .BR attributes (7). |
| .ad l |
| .nh |
| .TS |
| allbox; |
| lbx lb lb |
| l l l. |
| Interface Attribute Value |
| T{ |
| .BR strtol (), |
| .BR strtoll (), |
| .BR strtoq () |
| T} Thread safety MT-Safe locale |
| .TE |
| .hy |
| .ad |
| .sp 1 |
| .SH CONFORMING TO |
| .BR strtol (): |
| POSIX.1-2001, POSIX.1-2008, C89, C99 SVr4, 4.3BSD. |
| .PP |
| .BR strtoll (): |
| POSIX.1-2001, POSIX.1-2008, C99. |
| .SH NOTES |
| Since |
| .BR strtol () |
| can legitimately return 0, |
| .BR LONG_MAX , |
| or |
| .B LONG_MIN |
| .RB ( LLONG_MAX |
| or |
| .B LLONG_MIN |
| for |
| .BR strtoll ()) |
| on both success and failure, the calling program should set |
| .I errno |
| to 0 before the call, |
| and then determine if an error occurred by checking whether |
| .I errno |
| has a nonzero value after the call. |
| .PP |
| According to POSIX.1, |
| in locales other than "C" and "POSIX", |
| these functions may accept other, |
| implementation-defined numeric strings. |
| .PP |
| BSD also has |
| .PP |
| .in +4n |
| .EX |
| .BI "quad_t strtoq(const char *" nptr ", char **" endptr ", int " base ); |
| .EE |
| .in |
| .PP |
| with completely analogous definition. |
| Depending on the wordsize of the current architecture, this |
| may be equivalent to |
| .BR strtoll () |
| or to |
| .BR strtol (). |
| .SH EXAMPLES |
| The program shown below demonstrates the use of |
| .BR strtol (). |
| The first command-line argument specifies a string from which |
| .BR strtol () |
| should parse a number. |
| The second (optional) argument specifies the base to be used for |
| the conversion. |
| (This argument is converted to numeric form using |
| .BR atoi (3), |
| a function that performs no error checking and |
| has a simpler interface than |
| .BR strtol ().) |
| Some examples of the results produced by this program are the following: |
| .PP |
| .in +4n |
| .EX |
| .RB "$" " ./a.out 123" |
| strtol() returned 123 |
| .RB "$" " ./a.out \(aq 123\(aq" |
| strtol() returned 123 |
| .RB "$" " ./a.out 123abc" |
| strtol() returned 123 |
| Further characters after number: "abc" |
| .RB "$" " ./a.out 123abc 55" |
| strtol: Invalid argument |
| .RB "$" " ./a.out \(aq\(aq" |
| No digits were found |
| .RB "$" " ./a.out 4000000000" |
| strtol: Numerical result out of range |
| .EE |
| .in |
| .SS Program source |
| \& |
| .EX |
| #include <stdlib.h> |
| #include <limits.h> |
| #include <stdio.h> |
| #include <errno.h> |
| |
| int |
| main(int argc, char *argv[]) |
| { |
| int base; |
| char *endptr, *str; |
| long val; |
| |
| if (argc < 2) { |
| fprintf(stderr, "Usage: %s str [base]\en", argv[0]); |
| exit(EXIT_FAILURE); |
| } |
| |
| str = argv[1]; |
| base = (argc > 2) ? atoi(argv[2]) : 0; |
| |
| errno = 0; /* To distinguish success/failure after call */ |
| val = strtol(str, &endptr, base); |
| |
| /* Check for various possible errors. */ |
| |
| if (errno != 0) { |
| perror("strtol"); |
| exit(EXIT_FAILURE); |
| } |
| |
| if (endptr == str) { |
| fprintf(stderr, "No digits were found\en"); |
| exit(EXIT_FAILURE); |
| } |
| |
| /* If we got here, strtol() successfully parsed a number. */ |
| |
| printf("strtol() returned %ld\en", val); |
| |
| if (*endptr != \(aq\e0\(aq) /* Not necessarily an error... */ |
| printf("Further characters after number: \e"%s\e"\en", endptr); |
| |
| exit(EXIT_SUCCESS); |
| } |
| .EE |
| .SH SEE ALSO |
| .BR atof (3), |
| .BR atoi (3), |
| .BR atol (3), |
| .BR strtod (3), |
| .BR strtoimax (3), |
| .BR strtoul (3), |