xref: /freebsd/lib/libc/stdlib/strtol.3 (revision 4e6b1570629ce55fb6038c1d7ea2400c0a47a8a4)
158f0484fSRodney W. Grimes.\" Copyright (c) 1990, 1991, 1993
258f0484fSRodney W. Grimes.\"	The Regents of the University of California.  All rights reserved.
358f0484fSRodney W. Grimes.\"
458f0484fSRodney W. Grimes.\" This code is derived from software contributed to Berkeley by
558f0484fSRodney W. Grimes.\" Chris Torek and the American National Standards Committee X3,
658f0484fSRodney W. Grimes.\" on Information Processing Systems.
758f0484fSRodney W. Grimes.\"
858f0484fSRodney W. Grimes.\" Redistribution and use in source and binary forms, with or without
958f0484fSRodney W. Grimes.\" modification, are permitted provided that the following conditions
1058f0484fSRodney W. Grimes.\" are met:
1158f0484fSRodney W. Grimes.\" 1. Redistributions of source code must retain the above copyright
1258f0484fSRodney W. Grimes.\"    notice, this list of conditions and the following disclaimer.
1358f0484fSRodney W. Grimes.\" 2. Redistributions in binary form must reproduce the above copyright
1458f0484fSRodney W. Grimes.\"    notice, this list of conditions and the following disclaimer in the
1558f0484fSRodney W. Grimes.\"    documentation and/or other materials provided with the distribution.
1658f0484fSRodney W. Grimes.\" 3. All advertising materials mentioning features or use of this software
1758f0484fSRodney W. Grimes.\"    must display the following acknowledgement:
1858f0484fSRodney W. Grimes.\"	This product includes software developed by the University of
1958f0484fSRodney W. Grimes.\"	California, Berkeley and its contributors.
2058f0484fSRodney W. Grimes.\" 4. Neither the name of the University nor the names of its contributors
2158f0484fSRodney W. Grimes.\"    may be used to endorse or promote products derived from this software
2258f0484fSRodney W. Grimes.\"    without specific prior written permission.
2358f0484fSRodney W. Grimes.\"
2458f0484fSRodney W. Grimes.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
2558f0484fSRodney W. Grimes.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
2658f0484fSRodney W. Grimes.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
2758f0484fSRodney W. Grimes.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
2858f0484fSRodney W. Grimes.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
2958f0484fSRodney W. Grimes.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
3058f0484fSRodney W. Grimes.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
3158f0484fSRodney W. Grimes.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
3258f0484fSRodney W. Grimes.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
3358f0484fSRodney W. Grimes.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
3458f0484fSRodney W. Grimes.\" SUCH DAMAGE.
3558f0484fSRodney W. Grimes.\"
3658f0484fSRodney W. Grimes.\"     @(#)strtol.3	8.1 (Berkeley) 6/4/93
377f3dea24SPeter Wemm.\" $FreeBSD$
3858f0484fSRodney W. Grimes.\"
3958f0484fSRodney W. Grimes.Dd June 4, 1993
4058f0484fSRodney W. Grimes.Dt STRTOL 3
4158f0484fSRodney W. Grimes.Os
4258f0484fSRodney W. Grimes.Sh NAME
434c0440cbSDavid E. O'Brien.Nm strtol , strtoll , strtoq
44083745b5SDavid E. O'Brien.Nd "convert a string value to a long, long long, or quad_t integer"
4525bb73e0SAlexey Zelkin.Sh LIBRARY
4625bb73e0SAlexey Zelkin.Lb libc
4758f0484fSRodney W. Grimes.Sh SYNOPSIS
4858f0484fSRodney W. Grimes.Fd #include <stdlib.h>
4958f0484fSRodney W. Grimes.Fd #include <limits.h>
5058f0484fSRodney W. Grimes.Ft long
516333eac6SBruce Evans.Fn strtol "const char *nptr" "char **endptr" "int base"
524c0440cbSDavid E. O'Brien.Ft long long
534c0440cbSDavid E. O'Brien.Fn strtoll "const char *nptr" "char **endptr" "int base"
5458f0484fSRodney W. Grimes.Fd #include <sys/types.h>
5558f0484fSRodney W. Grimes.Fd #include <stdlib.h>
5658f0484fSRodney W. Grimes.Fd #include <limits.h>
5758f0484fSRodney W. Grimes.Ft quad_t
586333eac6SBruce Evans.Fn strtoq "const char *nptr" "char **endptr" "int base"
5958f0484fSRodney W. Grimes.Sh DESCRIPTION
6058f0484fSRodney W. GrimesThe
6158f0484fSRodney W. Grimes.Fn strtol
6258f0484fSRodney W. Grimesfunction
6358f0484fSRodney W. Grimesconverts the string in
6458f0484fSRodney W. Grimes.Fa nptr
6558f0484fSRodney W. Grimesto a
6658f0484fSRodney W. Grimes.Em long
6758f0484fSRodney W. Grimesvalue.
6858f0484fSRodney W. GrimesThe
694c0440cbSDavid E. O'Brien.Fn strtoll
704c0440cbSDavid E. O'Brienfunction
714c0440cbSDavid E. O'Brienconverts the string in
724c0440cbSDavid E. O'Brien.Fa nptr
734c0440cbSDavid E. O'Briento a
744c0440cbSDavid E. O'Brien.Em long long
754c0440cbSDavid E. O'Brienvalue.
764c0440cbSDavid E. O'BrienThe
7758f0484fSRodney W. Grimes.Fn strtoq
7858f0484fSRodney W. Grimesfunction
7958f0484fSRodney W. Grimesconverts the string in
8058f0484fSRodney W. Grimes.Fa nptr
8158f0484fSRodney W. Grimesto a
8258f0484fSRodney W. Grimes.Em quad_t
8358f0484fSRodney W. Grimesvalue.
8458f0484fSRodney W. GrimesThe conversion is done according to the given
8558f0484fSRodney W. Grimes.Fa base ,
8658f0484fSRodney W. Grimeswhich must be between 2 and 36 inclusive,
8758f0484fSRodney W. Grimesor be the special value 0.
8858f0484fSRodney W. Grimes.Pp
8958f0484fSRodney W. GrimesThe string may begin with an arbitrary amount of white space
9058f0484fSRodney W. Grimes(as determined by
9158f0484fSRodney W. Grimes.Xr isspace 3 )
9258f0484fSRodney W. Grimesfollowed by a single optional
9358f0484fSRodney W. Grimes.Ql +
9458f0484fSRodney W. Grimesor
9558f0484fSRodney W. Grimes.Ql -
9658f0484fSRodney W. Grimessign.
9758f0484fSRodney W. GrimesIf
9858f0484fSRodney W. Grimes.Fa base
9958f0484fSRodney W. Grimesis zero or 16,
10058f0484fSRodney W. Grimesthe string may then include a
10158f0484fSRodney W. Grimes.Ql 0x
10258f0484fSRodney W. Grimesprefix,
10358f0484fSRodney W. Grimesand the number will be read in base 16; otherwise, a zero
10458f0484fSRodney W. Grimes.Fa base
10558f0484fSRodney W. Grimesis taken as 10 (decimal) unless the next character is
10658f0484fSRodney W. Grimes.Ql 0 ,
10758f0484fSRodney W. Grimesin which case it is taken as 8 (octal).
10858f0484fSRodney W. Grimes.Pp
10958f0484fSRodney W. GrimesThe remainder of the string is converted to a
11058f0484fSRodney W. Grimes.Em long
11158f0484fSRodney W. Grimesvalue in the obvious manner,
11258f0484fSRodney W. Grimesstopping at the first character which is not a valid digit
11358f0484fSRodney W. Grimesin the given base.
11458f0484fSRodney W. Grimes(In bases above 10, the letter
11558f0484fSRodney W. Grimes.Ql A
11658f0484fSRodney W. Grimesin either upper or lower case
11758f0484fSRodney W. Grimesrepresents 10,
11858f0484fSRodney W. Grimes.Ql B
11958f0484fSRodney W. Grimesrepresents 11, and so forth, with
12058f0484fSRodney W. Grimes.Ql Z
12158f0484fSRodney W. Grimesrepresenting 35.)
12258f0484fSRodney W. Grimes.Pp
12358f0484fSRodney W. GrimesIf
12458f0484fSRodney W. Grimes.Fa endptr
12558f0484fSRodney W. Grimesis non nil,
12658f0484fSRodney W. Grimes.Fn strtol
12758f0484fSRodney W. Grimesstores the address of the first invalid character in
12858f0484fSRodney W. Grimes.Fa *endptr .
12958f0484fSRodney W. GrimesIf there were no digits at all, however,
13058f0484fSRodney W. Grimes.Fn strtol
13158f0484fSRodney W. Grimesstores the original value of
13258f0484fSRodney W. Grimes.Fa nptr
13358f0484fSRodney W. Grimesin
13458f0484fSRodney W. Grimes.Fa *endptr .
13558f0484fSRodney W. Grimes(Thus, if
13658f0484fSRodney W. Grimes.Fa *nptr
13758f0484fSRodney W. Grimesis not
13858f0484fSRodney W. Grimes.Ql \e0
13958f0484fSRodney W. Grimesbut
14058f0484fSRodney W. Grimes.Fa **endptr
14158f0484fSRodney W. Grimesis
14258f0484fSRodney W. Grimes.Ql \e0
14358f0484fSRodney W. Grimeson return, the entire string was valid.)
14458f0484fSRodney W. Grimes.Sh RETURN VALUES
14558f0484fSRodney W. GrimesThe
14658f0484fSRodney W. Grimes.Fn strtol
1474e6b1570SAndrey A. Chernovor
1484e6b1570SAndrey A. Chernov.Fn strtoll
14958f0484fSRodney W. Grimesfunction
15058f0484fSRodney W. Grimesreturns the result of the conversion,
15158f0484fSRodney W. Grimesunless the value would underflow or overflow.
1524e6b1570SAndrey A. ChernovIf no conversion could be performed, 0 shall be returned and
1534e6b1570SAndrey A. Chernov.Va errno
1544e6b1570SAndrey A. Chernovwill be
1554e6b1570SAndrey A. Chernovset to
1564e6b1570SAndrey A. Chernov.Er EINVAL .
15758f0484fSRodney W. GrimesIf an underflow occurs,
15858f0484fSRodney W. Grimes.Fn strtol
15958f0484fSRodney W. Grimesreturns
16058f0484fSRodney W. Grimes.Dv LONG_MIN .
16158f0484fSRodney W. GrimesIf an overflow occurs,
16258f0484fSRodney W. Grimes.Fn strtol
16358f0484fSRodney W. Grimesreturns
16458f0484fSRodney W. Grimes.Dv LONG_MAX .
1654c0440cbSDavid E. O'BrienIf an underflow occurs,
1664c0440cbSDavid E. O'Brien.Fn strtoll
1674c0440cbSDavid E. O'Brienreturns
1684c0440cbSDavid E. O'Brien.Dv LLONG_MIN .
1694c0440cbSDavid E. O'BrienIf an overflow occurs,
1704c0440cbSDavid E. O'Brien.Fn strtoll
1714c0440cbSDavid E. O'Brienreturns
1724c0440cbSDavid E. O'Brien.Dv LLONG_MAX .
1734c0440cbSDavid E. O'BrienIn all cases,
17458f0484fSRodney W. Grimes.Va errno
17558f0484fSRodney W. Grimesis set to
17658f0484fSRodney W. Grimes.Er ERANGE .
17758f0484fSRodney W. Grimes.Sh ERRORS
178274b6244SAlexey Zelkin.Bl -tag -width Er
1794e6b1570SAndrey A. Chernov.It Bq Er EINVAL
1804e6b1570SAndrey A. ChernovThe value of base is not supported or
1814e6b1570SAndrey A. Chernovno conversion could be performed.
18258f0484fSRodney W. Grimes.It Bq Er ERANGE
18358f0484fSRodney W. GrimesThe given string was out of range; the value converted has been clamped.
18458f0484fSRodney W. Grimes.El
18558f0484fSRodney W. Grimes.Sh SEE ALSO
18658f0484fSRodney W. Grimes.Xr atof 3 ,
18758f0484fSRodney W. Grimes.Xr atoi 3 ,
18858f0484fSRodney W. Grimes.Xr atol 3 ,
18958f0484fSRodney W. Grimes.Xr strtod 3 ,
19058f0484fSRodney W. Grimes.Xr strtoul 3
19158f0484fSRodney W. Grimes.Sh STANDARDS
19258f0484fSRodney W. GrimesThe
19358f0484fSRodney W. Grimes.Fn strtol
19458f0484fSRodney W. Grimesfunction
19558f0484fSRodney W. Grimesconforms to
196588a200cSRuslan Ermilov.St -isoC .
1974c0440cbSDavid E. O'BrienThe
1984c0440cbSDavid E. O'Brien.Fn strtoll
1994c0440cbSDavid E. O'Brienfunction
2004c0440cbSDavid E. O'Brienconforms to
2014c0440cbSDavid E. O'Brien.St -isoC-99 .
202083745b5SDavid E. O'BrienThe
203083745b5SDavid E. O'Brien.Bx
2044c0440cbSDavid E. O'Brien.Fn strtoq
2054c0440cbSDavid E. O'Brienfunction is deprecated.
206