Merging upstream version 6.7.

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

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);
     }