git.saurik.com Git - apple/libc.git/blame_incremental

... / ...

Commit	Line	Data
	1	.\" Copyright (c) 1990, 1991, 1993
	2	.\" The Regents of the University of California. All rights reserved.
	3	.\"
	4	.\" This code is derived from software contributed to Berkeley by
	5	.\" the American National Standards Committee X3, on Information
	6	.\" Processing Systems.
	7	.\"
	8	.\" Redistribution and use in source and binary forms, with or without
	9	.\" modification, are permitted provided that the following conditions
	10	.\" are met:
	11	.\" 1. Redistributions of source code must retain the above copyright
	12	.\" notice, this list of conditions and the following disclaimer.
	13	.\" 2. Redistributions in binary form must reproduce the above copyright
	14	.\" notice, this list of conditions and the following disclaimer in the
	15	.\" documentation and/or other materials provided with the distribution.
	16	.\" 4. Neither the name of the University nor the names of its contributors
	17	.\" may be used to endorse or promote products derived from this software
	18	.\" without specific prior written permission.
	19	.\"
	20	.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
	21	.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
	22	.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
	23	.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
	24	.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
	25	.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
	26	.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
	27	.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
	28	.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
	29	.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
	30	.\" SUCH DAMAGE.
	31	.\"
	32	.\" @(#)atol.3 8.1 (Berkeley) 6/4/93
	33	.\" $FreeBSD: src/lib/libc/stdlib/atol.3,v 1.16 2009/03/01 05:44:28 delphij Exp $
	34	.\"
	35	.Dd February 1, 2009
	36	.Dt ATOL 3
	37	.Os
	38	.Sh NAME
	39	.Nm atol , atoll ,
	40	.Nm atol_l , atoll_l
	41	.Nd convert
	42	.Tn ASCII
	43	string to
	44	.Vt long
	45	or
	46	.Vt "long long"
	47	integer
	48	.Sh LIBRARY
	49	.Lb libc
	50	.Sh SYNOPSIS
	51	.In stdlib.h
	52	.Ft long
	53	.Fn atol "const char *str"
	54	.Ft "long long"
	55	.Fn atoll "const char *str"
	56	.In xlocale.h
	57	.Ft long
	58	.Fn atol_l "const char *str" "locale_t loc"
	59	.Ft "long long"
	60	.Fn atoll_l "const char *str" "locale_t loc"
	61	.Sh DESCRIPTION
	62	The
	63	.Fn atol
	64	function converts the initial portion of the string pointed to by
	65	.Fa str
	66	to
	67	.Vt long
	68	integer
	69	representation.
	70	.Pp
	71	It is equivalent to:
	72	.Pp
	73	.Dl "strtol(str, (char **)NULL, 10);"
	74	.Pp
	75	The
	76	.Fn atoll
	77	function converts the initial portion of the string pointed to by
	78	.Fa str
	79	to
	80	.Vt "long long"
	81	integer
	82	representation.
	83	.Pp
	84	It is equivalent to:
	85	.Pp
	86	.Dl "strtoll(str, (char **)NULL, 10);"
	87	.Pp
	88	While the
	89	.Fn atol
	90	and
	91	.Fn atoll
	92	functions use the current locale, the
	93	.Fn atol_l
	94	and
	95	.Fn atoll_l
	96	functions may be passed locales directly. See
	97	.Xr xlocale 3
	98	for more information.
	99	.Sh IMPLEMENTATION NOTES
	100	The
	101	.Fn atol ,
	102	.Fn atoll ,
	103	.Fn atol_l ,
	104	and
	105	.Fn atoll_l
	106	functions are thread-safe and async-cancel-safe.
	107	.Pp
	108	The
	109	.Fx
	110	implementations of the
	111	.Fn atol
	112	and
	113	.Fn atoll
	114	functions are thin wrappers around
	115	.Fn strtol
	116	and
	117	.Fn stroll
	118	respectively, so these functions will affect the value of
	119	.Va errno
	120	in the same way that the
	121	.Fn strtol
	122	and
	123	.Fn stroll
	124	functions are able to.
	125	This behavior of
	126	.Fn atol
	127	and
	128	.Fn atoll
	129	is not required by
	130	.St -isoC
	131	or
	132	.St -isoC-99 ,
	133	but it is allowed by all of
	134	.St -isoC , St -isoC-99
	135	and
	136	.St -p1003.1-2001 .
	137	.Sh ERRORS
	138	The functions
	139	.Fn atol
	140	and
	141	.Fn atoll
	142	may affect the value of
	143	.Va errno
	144	on an error.
	145	.Sh SEE ALSO
	146	.Xr atof 3 ,
	147	.Xr atoi 3 ,
	148	.Xr strtod 3 ,
	149	.Xr strtol 3 ,
	150	.Xr strtoul 3 ,
	151	.Xr xlocale 3
	152	.Sh STANDARDS
	153	The
	154	.Fn atol
	155	function
	156	conforms to
	157	.St -isoC .
	158	The
	159	.Fn atoll
	160	function
	161	conforms to
	162	.St -isoC-99 .