summaryrefslogtreecommitdiffstats
path: root/man3/strtol.3
diff options
context:
space:
mode:
Diffstat (limited to 'man3/strtol.3')
-rw-r--r--man3/strtol.3321
1 files changed, 0 insertions, 321 deletions
diff --git a/man3/strtol.3 b/man3/strtol.3
deleted file mode 100644
index b6609b2..0000000
--- a/man3/strtol.3
+++ /dev/null
@@ -1,321 +0,0 @@
-'\" 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 2023-12-19 "Linux man-pages 6.7"
-.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)