path: root/man3p/strtol.3p

.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved 
.TH "STRTOL" 3P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
.\" strtol 
.SH PROLOG
This manual page is part of the POSIX Programmer's Manual.
The Linux implementation of this interface may differ (consult
the corresponding Linux manual page for details of Linux behavior),
or the interface may not be implemented on Linux.
.SH NAME
strtol, strtoll \- convert a string to a long integer
.SH SYNOPSIS
.LP
\fB#include <stdlib.h>
.br
.sp
long strtol(const char *restrict\fP \fIstr\fP\fB, char **restrict\fP
\fIendptr\fP\fB, int\fP \fIbase\fP\fB);
.br
long long strtoll(const char *restrict\fP \fIstr\fP\fB, char **restrict\fP
\fIendptr\fP\fB,
.br
\ \ \ \ \ \  int\fP \fIbase\fP\fB)
.br
\fP
.SH DESCRIPTION
.LP
These functions shall convert the initial portion of the string pointed
to by \fIstr\fP to a type \fBlong\fP and \fBlong
long\fP representation, respectively. First, they decompose the input
string into three parts:
.IP " 1." 4
An initial, possibly empty, sequence of white-space characters (as
specified by \fIisspace\fP())
.LP
.IP " 2." 4
A subject sequence interpreted as an integer represented in some radix
determined by the value of \fIbase\fP
.LP
.IP " 3." 4
A final string of one or more unrecognized characters, including the
terminating null byte of the input string.
.LP
.LP
Then they shall attempt to convert the subject sequence to an integer,
and return the result.
.LP
If the value of \fIbase\fP is 0, the expected form of the subject
sequence is that of a decimal constant, octal constant, or
hexadecimal constant, any of which may be preceded by a \fB'+'\fP
or \fB'-'\fP sign. A decimal constant begins with a
non-zero digit, and consists of a sequence of decimal digits. An octal
constant consists of the prefix \fB'0'\fP optionally
followed by a sequence of the digits \fB'0'\fP to \fB'7'\fP only.
A hexadecimal constant consists of the prefix 0x or 0X
followed by a sequence of the decimal digits and letters \fB'a'\fP
(or \fB'A'\fP ) to \fB'f'\fP (or \fB'F'\fP ) with
values 10 to 15 respectively.
.LP
If the value of \fIbase\fP is between 2 and 36, the expected form
of the subject sequence is a sequence of letters and digits
representing an integer with the radix specified by \fIbase\fP, optionally
preceded by a \fB'+'\fP or \fB'-'\fP sign. The
letters from \fB'a'\fP (or \fB'A'\fP ) to \fB'z'\fP (or \fB'Z'\fP
) inclusive are ascribed the values 10 to 35; only
letters whose ascribed values are less than that of \fIbase\fP are
permitted. If the value of \fIbase\fP is 16, the characters 0x
or 0X may optionally precede the sequence of letters and digits, following
the sign if present.
.LP
The subject sequence is defined as the longest initial subsequence
of the input string, starting with the first non-white-space
character that is of the expected form. The subject sequence shall
contain no characters if the input string is empty or consists
entirely of white-space characters, or if the first non-white-space
character is other than a sign or a permissible letter or
digit.
.LP
If the subject sequence has the expected form and the value of \fIbase\fP
is 0, the sequence of characters starting with the
first digit shall be interpreted as an integer constant. If the subject
sequence has the expected form and the value of \fIbase\fP
is between 2 and 36, it shall be used as the base for conversion,
ascribing to each letter its value as given above. If the subject
sequence begins with a minus sign, the value resulting from the conversion
shall be negated. A pointer to the final string shall be
stored in the object pointed to by \fIendptr\fP, provided that \fIendptr\fP
is not a null pointer.
.LP
In other than the C   \ or POSIX  locales, other
implementation-defined subject sequences may be accepted.
.LP
If the subject sequence is empty or does not have the expected form,
no conversion is performed; the value of \fIstr\fP is
stored in the object pointed to by \fIendptr\fP, provided that \fIendptr\fP
is not a null pointer.
.LP
The
\fIstrtol\fP() function shall not change the setting of \fIerrno\fP
if successful.
.LP
Since 0, {LONG_MIN} or {LLONG_MIN}, and {LONG_MAX} or {LLONG_MAX}
are returned on error and are also valid returns on success,
an application wishing to check for error situations should set \fIerrno\fP
to 0, then call \fIstrtol\fP() or \fIstrtoll\fP(),
then check \fIerrno\fP. 
.SH RETURN VALUE
.LP
Upon successful completion, these functions shall return the converted
value, if any. If no conversion could be performed, 0
shall be returned   \ and \fIerrno\fP may be set to [EINVAL]. 
.LP
If the correct value is outside the range of representable values,
{LONG_MIN}, {LONG_MAX}, {LLONG_MIN}, or {LLONG_MAX} shall be
returned (according to the sign of the value), and \fIerrno\fP set
to [ERANGE].
.SH ERRORS
.LP
These functions shall fail if:
.TP 7
.B ERANGE
The value to be returned is not representable.
.sp
.LP
These functions may fail if:
.TP 7
.B EINVAL
The value of \fIbase\fP is not supported. 
.sp
.LP
\fIThe following sections are informative.\fP
.SH EXAMPLES
.LP
None.
.SH APPLICATION USAGE
.LP
None.
.SH RATIONALE
.LP
None.
.SH FUTURE DIRECTIONS
.LP
None.
.SH SEE ALSO
.LP
\fIisalpha\fP() , \fIscanf\fP() , \fIstrtod\fP() , the Base Definitions
volume of IEEE\ Std\ 1003.1-2001, \fI<stdlib.h>\fP
.SH COPYRIGHT
Portions of this text are reprinted and reproduced in electronic form
from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
-- Portable Operating System Interface (POSIX), The Open Group Base
Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
Electrical and Electronics Engineers, Inc and The Open Group. In the
event of any discrepancy between this version and the original IEEE and
The Open Group Standard, the original IEEE and The Open Group Standard
is the referee document. The original Standard can be obtained online at
http://www.opengroup.org/unix/online.html .