Adding upstream version 6.8.upstream/6.8upstream

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

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)