stdlib/FreeBSD/atol.3

   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 .