summaryrefslogtreecommitdiffstats
path: root/man3/strtol.3
diff options
context:
space:
mode:
Diffstat (limited to 'man3/strtol.3')
-rw-r--r--man3/strtol.364
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);
}