mirror of https://github.com/mkerrisk/man-pages
262 lines
6.8 KiB
Groff
262 lines
6.8 KiB
Groff
.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk)
|
|
.\"
|
|
.\" Permission is granted to make and distribute verbatim copies of this
|
|
.\" manual provided the copyright notice and this permission notice are
|
|
.\" preserved on all copies.
|
|
.\"
|
|
.\" Permission is granted to copy and distribute modified versions of this
|
|
.\" manual under the conditions for verbatim copying, provided that the
|
|
.\" entire resulting derived work is distributed under the terms of a
|
|
.\" permission notice identical to this one.
|
|
.\"
|
|
.\" Since the Linux kernel and libraries are constantly changing, this
|
|
.\" manual page may be incorrect or out-of-date. The author(s) assume no
|
|
.\" responsibility for errors or omissions, or for damages resulting from
|
|
.\" the use of the information contained herein. The author(s) may not
|
|
.\" have taken the same level of care in the production of this manual,
|
|
.\" which is licensed free of charge, as they might when working
|
|
.\" professionally.
|
|
.\"
|
|
.\" Formatted or processed versions of this manual, if unaccompanied by
|
|
.\" the source, must acknowledge the copyright and authors of this work.
|
|
.\"
|
|
.\" 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 2007-07-26 "GNU" "Linux Programmer's Manual"
|
|
.SH NAME
|
|
strtol, strtoll, strtoq \- convert a string to a long integer
|
|
.SH SYNOPSIS
|
|
.nf
|
|
.B #include <stdlib.h>
|
|
.sp
|
|
.BI "long int strtol(const char *" nptr ", char **" endptr ", int " base );
|
|
.sp
|
|
.BI "long long int strtoll(const char *" nptr ", char **" endptr \
|
|
", int " base );
|
|
.fi
|
|
.sp
|
|
.in -4n
|
|
Feature Test Macro Requirements for glibc (see
|
|
.BR feature_test_macros (7)):
|
|
.in
|
|
.sp
|
|
.ad l
|
|
.BR strtoll ():
|
|
XOPEN_SOURCE >= 600 || _BSD_SOURCE || _SVID_SOURCE || _ISOC99_SOURCE; or
|
|
.I cc\ -std=c99
|
|
.ad b
|
|
.SH DESCRIPTION
|
|
The
|
|
.BR strtol ()
|
|
function converts the initial part of the string
|
|
in \fInptr\fP to a long integer value according to the given \fIbase\fP,
|
|
which must be between 2 and 36 inclusive, or be the special value 0.
|
|
.PP
|
|
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 \fIbase\fP is zero or 16, the string may then include a
|
|
"0x" prefix, and the number will be read in base 16; otherwise, a
|
|
zero \fIbase\fP is taken as 10 (decimal) unless the next character
|
|
is \(aq0\(aq, in which case it is taken as 8 (octal).
|
|
.PP
|
|
The remainder of the string is converted to a
|
|
.I long int
|
|
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 \(aqA\(aq in
|
|
either upper or lower case represents 10, \(aqB\(aq represents 11, and so
|
|
forth, with \(aqZ\(aq representing 35.)
|
|
.PP
|
|
If \fIendptr\fP is not NULL,
|
|
.BR strtol ()
|
|
stores the address of the
|
|
first invalid character in \fI*endptr\fP.
|
|
If there were no digits at
|
|
all,
|
|
.BR strtol ()
|
|
stores the original value of \fInptr\fP in
|
|
\fI*endptr\fP (and returns 0).
|
|
In particular, if \fI*nptr\fP is not \(aq\\0\(aq but \fI**endptr\fP
|
|
is \(aq\\0\(aq on return, the entire string is valid.
|
|
.PP
|
|
The
|
|
.BR strtoll ()
|
|
function works just like the
|
|
.BR strtol ()
|
|
function but returns a 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, \fIerrno\fP 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
|
|
.TP
|
|
.B EINVAL
|
|
(not in C99)
|
|
The given
|
|
.I base
|
|
contains an unsupported value.
|
|
.TP
|
|
.B ERANGE
|
|
The resulting value was out of range.
|
|
.LP
|
|
The implementation may also set \fIerrno\fP to \fBEINVAL\fP in case
|
|
no conversion was performed (no digits seen, and 0 returned).
|
|
.SH "CONFORMING TO"
|
|
.BR strtol ()
|
|
conforms to SVr4, 4.3BSD, C89, C99 and POSIX.1-2001, and
|
|
.BR strtoll ()
|
|
to C99 and POSIX.1-2001.
|
|
.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
|
|
has a non-zero value after the call.
|
|
|
|
In locales other than the "C" locale, other strings may also be accepted.
|
|
(For example, the thousands separator of the current locale may be
|
|
supported.)
|
|
.LP
|
|
BSD also has
|
|
.sp
|
|
.in +4n
|
|
.nf
|
|
.BI "quad_t strtoq(const char *" nptr ", char **" endptr ", int " base );
|
|
.sp
|
|
.in
|
|
.fi
|
|
with completely analogous definition.
|
|
Depending on the wordsize of the current architecture, this
|
|
may be equivalent to
|
|
.BR strtoll ()
|
|
or to
|
|
.BR strtol ().
|
|
.SH EXAMPLE
|
|
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:
|
|
.in +4n
|
|
.nf
|
|
|
|
$ ./a.out 123
|
|
strtol() returned 123
|
|
$ ./a.out \(aq 123\(aq
|
|
strtol() returned 123
|
|
$ ./a.out 123abc
|
|
strtol() returned 123
|
|
Further characters after number: abc
|
|
$ ./a.out 123abc 55
|
|
strtol: Invalid argument
|
|
$ ./a.out \(aq\(aq
|
|
No digits were found
|
|
$ ./a.out 4000000000
|
|
strtol: Numerical result out of range
|
|
|
|
.fi
|
|
.in
|
|
The source code of the program is as follows:
|
|
.nf
|
|
|
|
#include <stdlib.h>
|
|
#include <limits.h>
|
|
#include <stdio.h>
|
|
#include <errno.h>
|
|
|
|
int
|
|
main(int argc, char *argv[])
|
|
{
|
|
int base;
|
|
char *endptr, *str;
|
|
long val;
|
|
|
|
if (argc < 2) {
|
|
fprintf(stderr, "Usage: %s str [base]\\n", argv[0]);
|
|
exit(EXIT_FAILURE);
|
|
}
|
|
|
|
str = argv[1];
|
|
base = (argc > 2) ? atoi(argv[2]) : 10;
|
|
|
|
errno = 0; /* To distinguish success/failure after call */
|
|
val = strtol(str, &endptr, base);
|
|
|
|
/* Check for various possible errors */
|
|
|
|
if ((errno == ERANGE && (val == LONG_MAX || val == LONG_MIN))
|
|
|| (errno != 0 && val == 0)) {
|
|
perror("strtol");
|
|
exit(EXIT_FAILURE);
|
|
}
|
|
|
|
if (endptr == str) {
|
|
fprintf(stderr, "No digits were found\\n");
|
|
exit(EXIT_FAILURE);
|
|
}
|
|
|
|
/* If we got here, strtol() successfully parsed a number */
|
|
|
|
printf("strtol() returned %ld\\n", val);
|
|
|
|
if (*endptr != \(aq\\0\(aq) /* Not necessarily an error... */
|
|
printf("Further characters after number: %s\\n", endptr);
|
|
|
|
exit(EXIT_SUCCESS);
|
|
}
|
|
.fi
|
|
.SH "SEE ALSO"
|
|
.BR atof (3),
|
|
.BR atoi (3),
|
|
.BR atol (3),
|
|
.BR strtod (3),
|
|
.BR strtoul (3)
|