man3/atoi.3

   1 '\" t
   2 .\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk)
   3 .\"
   4 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   5 .\"
   6 .\" References consulted:
   7 .\"     Linux libc source code
   8 .\"     Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991)
   9 .\"     386BSD man pages
  10 .\" Modified Mon Mar 29 22:39:41 1993, David Metcalfe
  11 .\" Modified Sat Jul 24 21:38:42 1993, Rik Faith (faith@cs.unc.edu)
  12 .\" Modified Sun Dec 17 18:35:06 2000, Joseph S. Myers
  13 .\"
  14 .TH atoi 3 (date) "Linux man-pages (unreleased)"
  15 .SH NAME
  16 atoi, atol, atoll \- convert a string to an integer
  17 .SH LIBRARY
  18 Standard C library
  19 .RI ( libc ", " \-lc )
  20 .SH SYNOPSIS
  21 .nf
  22 .B #include <stdlib.h>
  23 .PP
  24 .BI "int atoi(const char *" nptr );
  25 .BI "long atol(const char *" nptr );
  26 .BI "long long atoll(const char *" nptr );
  27 .fi
  28 .PP
  29 .RS -4
  30 Feature Test Macro Requirements for glibc (see
  31 .BR feature_test_macros (7)):
  32 .RE
  33 .PP
  34 .BR atoll ():
  35 .nf
  36     _ISOC99_SOURCE
  37         || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE
  38 .fi
  39 .SH DESCRIPTION
  40 The
  41 .BR atoi ()
  42 function converts the initial portion of the string
  43 pointed to by \fInptr\fP to
  44 .IR int .
  45 The behavior is the same as
  46 .PP
  47 .in +4n
  48 .EX
  49 strtol(nptr, NULL, 10);
  50 .EE
  51 .in
  52 .PP
  53 except that
  54 .BR atoi ()
  55 does not detect errors.
  56 .PP
  57 The
  58 .BR atol ()
  59 and
  60 .BR atoll ()
  61 functions behave the same as
  62 .BR atoi (),
  63 except that they convert the initial portion of the
  64 string to their return type of \fIlong\fP or \fIlong long\fP.
  65 .SH RETURN VALUE
  66 The converted value or 0 on error.
  67 .SH ATTRIBUTES
  68 For an explanation of the terms used in this section, see
  69 .BR attributes (7).
  70 .ad l
  71 .nh
  72 .TS
  73 allbox;
  74 lbx lb lb
  75 l l l.
  76 Interface       Attribute       Value
  77 T{
  78 .BR atoi (),
  79 .BR atol (),
  80 .BR atoll ()
  81 T}      Thread safety   MT-Safe locale
  82 .TE
  83 .hy
  84 .ad
  85 .sp 1
  86 .SH STANDARDS
  87 POSIX.1-2001, POSIX.1-2008, C99, SVr4, 4.3BSD.
  88 .\" .SH NOTES
  89 .\" Linux libc provided
  90 .\" .BR atoq ()
  91 .\" as an obsolete name for
  92 .\" .BR atoll ();
  93 .\" .BR atoq ()
  94 .\" is not provided by glibc.
  95 .\" The
  96 .\" .BR atoll ()
  97 .\" function is present since glibc 2.0.2, but
  98 .\" not in libc4 or libc5.
  99 .SH NOTES
 100 POSIX.1 leaves the return value of
 101 .BR atoi ()
 102 on error unspecified.
 103 On glibc, musl libc, and uClibc, 0 is returned on error.
 104 .SH BUGS
 105 .I errno
 106 is not set on error so there is no way to distinguish between 0 as an
 107 error and as the converted value.
 108 No checks for overflow or underflow are done.
 109 Only base-10 input can be converted.
 110 It is recommended to instead use the
 111 .BR strtol ()
 112 and
 113 .BR strtoul ()
 114 family of functions in new programs.
 115 .SH SEE ALSO
 116 .BR atof (3),
 117 .BR strtod (3),
 118 .BR strtol (3),
 119 .BR strtoul (3)