diff options
Diffstat (limited to 'man/man3/strtol.3')
| -rw-r--r-- | man/man3/strtol.3 | 321 |
1 files changed, 321 insertions, 0 deletions
diff --git a/man/man3/strtol.3 b/man/man3/strtol.3 new file mode 100644 index 0000000..c001265 --- /dev/null +++ b/man/man3/strtol.3 @@ -0,0 +1,321 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" and Copyright 2006 Michael Kerrisk <mtk.manpages@ganil.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" 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 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +strtol, strtoll, strtoq \- convert a string to a long integer +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <stdlib.h> +.P +.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 +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.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. +.P +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 \[aq]0\[aq], in which case it is taken as 8 (octal). +.P +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 \[aq]A\[aq] in +either uppercase or lowercase represents 10, \[aq]B\[aq] represents 11, and so +forth, with \[aq]Z\[aq] representing 35.) +.P +If +.I endptr +is not NULL, +and the +.I base +is supported, +.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. +.P +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 +This function does not modify +.I errno +on success. +.TP +.B EINVAL +(not in C99) +The given +.I base +contains an unsupported value. +.TP +.B ERANGE +The resulting value was out of range. +.P +The implementation may also set +.I 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). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR strtol (), +.BR strtoll (), +.BR strtoq () +T} Thread safety MT-Safe locale +.TE +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +.TP +.BR strtol () +POSIX.1-2001, C89, SVr4, 4.3BSD. +.TP +.BR strtoll () +POSIX.1-2001, 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 == ERANGE +after the call. +.P +According to POSIX.1, +in locales other than "C" and "POSIX", +these functions may accept other, +implementation-defined numeric strings. +.P +BSD also has +.P +.in +4n +.EX +.BI "quad_t strtoq(const char *" nptr ", char **" endptr ", int " base ); +.EE +.in +.P +with completely analogous definition. +Depending on the wordsize of the current architecture, this +may be equivalent to +.BR strtoll () +or to +.BR strtol (). +.SH CAVEATS +If the +.I base +needs to be tested, +it should be tested in a call where the string is known to succeed. +Otherwise, it's impossible to portably differentiate the errors. +.P +.in +4n +.EX +errno = 0; +strtol("0", NULL, base); +if (errno == EINVAL) + goto unsupported_base; +.EE +.in +.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: +.P +.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 +\& +.\" SRC BEGIN (strtol.c) +.EX +#include <errno.h> +#include <stdio.h> +#include <stdlib.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 */ + strtol("0", NULL, base); + if (errno == EINVAL) { + perror("strtol"); + exit(EXIT_FAILURE); + } +\& + errno = 0; /* To distinguish success/failure after call */ + val = strtol(str, &endptr, base); +\& + /* Check for various possible errors. */ +\& + if (errno == ERANGE) { + 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 +.\" SRC END +.SH SEE ALSO +.BR atof (3), +.BR atoi (3), +.BR atol (3), +.BR strtod (3), +.BR strtoimax (3), +.BR strtoul (3) |