diff options
Diffstat (limited to 'man3/strtol.3')
| -rw-r--r-- | man3/strtol.3 | 64 |
1 files changed, 45 insertions, 19 deletions
diff --git a/man3/strtol.3 b/man3/strtol.3 index fe5555a..b6609b2 100644 --- a/man3/strtol.3 +++ b/man3/strtol.3 @@ -10,7 +10,7 @@ .\" 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 2023-07-20 "Linux man-pages 6.05.01" +.TH strtol 3 2023-12-19 "Linux man-pages 6.7" .SH NAME strtol, strtoll, strtoq \- convert a string to a long integer .SH LIBRARY @@ -19,18 +19,18 @@ Standard C library .SH SYNOPSIS .nf .B #include <stdlib.h> -.PP +.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 -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR strtoll (): .nf _ISOC99_SOURCE @@ -45,7 +45,7 @@ in 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 +.P The string may begin with an arbitrary amount of white space (as determined by .BR isspace (3)) @@ -58,7 +58,7 @@ 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). -.PP +.P The remainder of the string is converted to a .I long value @@ -67,10 +67,13 @@ 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.) -.PP +.P If .I endptr is not NULL, +and the +.I base +is supported, .BR strtol () stores the address of the first invalid character in @@ -88,7 +91,7 @@ In particular, if is not \[aq]\e0\[aq] but .I **endptr is \[aq]\e0\[aq] on return, the entire string is valid. -.PP +.P The .BR strtoll () function works just like the @@ -124,6 +127,9 @@ instead of and .BR LONG_MAX ). .SH ERRORS +This function does not modify +.I errno +on success. .TP .B EINVAL (not in C99) @@ -133,7 +139,7 @@ contains an unsupported value. .TP .B ERANGE The resulting value was out of range. -.PP +.P The implementation may also set .I errno to @@ -156,7 +162,6 @@ T{ .BR strtoq () T} Thread safety MT-Safe locale .TE -.sp 1 .SH STANDARDS C11, POSIX.1-2008. .SH HISTORY @@ -182,28 +187,43 @@ 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 +.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. -.PP +.P BSD also has -.PP +.P .in +4n .EX .BI "quad_t strtoq(const char *" nptr ", char **" endptr ", int " base ); .EE .in -.PP +.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 (). @@ -218,7 +238,7 @@ 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 +.P .in +4n .EX .RB "$" " ./a.out 123" @@ -241,7 +261,6 @@ strtol: Numerical result out of range .\" SRC BEGIN (strtol.c) .EX #include <errno.h> -#include <limits.h> #include <stdio.h> #include <stdlib.h> \& @@ -261,11 +280,18 @@ main(int argc, char *argv[]) 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 != 0) { + if (errno == ERANGE) { perror("strtol"); exit(EXIT_FAILURE); } |