man3/perror.3

   1 .\" Copyright (c) 1994 Michael Haardt (michael@moria.de), 1994-06-04
   2 .\" Copyright (c) 1995 Michael Haardt
   3 .\"      (michael@cantor.informatik.rwth-aachen.de), 1995-03-16
   4 .\" Copyright (c) 1996 Andries Brouwer (aeb@cwi.nl), 1996-01-13
   5 .\"
   6 .\" %%%LICENSE_START(GPLv2+_DOC_FULL)
   7 .\" This is free documentation; you can redistribute it and/or
   8 .\" modify it under the terms of the GNU General Public License as
   9 .\" published by the Free Software Foundation; either version 2 of
  10 .\" the License, or (at your option) any later version.
  11 .\"
  12 .\" The GNU General Public License's references to "object code"
  13 .\" and "executables" are to be interpreted as the output of any
  14 .\" document formatting or typesetting system, including
  15 .\" intermediate and printed output.
  16 .\"
  17 .\" This manual is distributed in the hope that it will be useful,
  18 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
  19 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  20 .\" GNU General Public License for more details.
  21 .\"
  22 .\" You should have received a copy of the GNU General Public
  23 .\" License along with this manual; if not, see
  24 .\" <http://www.gnu.org/licenses/>.
  25 .\" %%%LICENSE_END
  26 .\"
  27 .\" 1996-01-13 aeb: merged in some text contributed by Melvin Smith
  28 .\"   (msmith@falcon.mercer.peachnet.edu) and various other changes.
  29 .\" Modified 1996-05-16 by Martin Schulze (joey@infodrom.north.de)
  30 .\"
  31 .TH PERROR 3 2021-03-22 "" "Linux Programmer's Manual"
  32 .SH NAME
  33 perror \- print a system error message
  34 .SH SYNOPSIS
  35 .nf
  36 .B #include <stdio.h>
  37 .PP
  38 .BI "void perror(const char *" s );
  39 .PP
  40 .B #include <errno.h>
  41 .PP
  42 .BI "const char *const " sys_errlist [];
  43 .BI "int " sys_nerr ;
  44 .BI "int " errno ";       \fR/* Not really declared this way; see errno(3) */"
  45 .fi
  46 .PP
  47 .RS -4
  48 Feature Test Macro Requirements for glibc (see
  49 .BR feature_test_macros (7)):
  50 .RE
  51 .PP
  52 .IR sys_errlist ,
  53 .IR sys_nerr :
  54 .nf
  55     From glibc 2.19 to 2.31:
  56         _DEFAULT_SOURCE
  57     Glibc 2.19 and earlier:
  58         _BSD_SOURCE
  59 .fi
  60 .SH DESCRIPTION
  61 The
  62 .BR perror ()
  63 function produces a message on standard error describing the last
  64 error encountered during a call to a system or library function.
  65 .PP
  66 First (if
  67 .I s
  68 is not NULL and
  69 .I *s
  70 is not a null byte (\(aq\e0\(aq)), the argument string
  71 .I s
  72 is printed, followed by a colon and a blank.
  73 Then an error message corresponding to the current value of
  74 .I errno
  75 and a new-line.
  76 .PP
  77 To be of most use, the argument string should include the name
  78 of the function that incurred the error.
  79 .PP
  80 The global error list
  81 .IR sys_errlist "[],"
  82 which can be indexed by
  83 .IR errno ,
  84 can be used to obtain the error message without the newline.
  85 The largest message number provided in the table is
  86 .IR sys_nerr "\-1."
  87 Be careful when directly accessing this list, because new error values
  88 may not have been added to
  89 .IR sys_errlist "[]."
  90 The use of
  91 .IR sys_errlist "[]"
  92 is nowadays deprecated; use
  93 .BR strerror (3)
  94 instead.
  95 .PP
  96 When a system call fails, it usually returns \-1 and sets the
  97 variable
  98 .I errno
  99 to a value describing what went wrong.
 100 (These values can be found in
 101 .IR <errno.h> .)
 102 Many library functions do likewise.
 103 The function
 104 .BR perror ()
 105 serves to translate this error code into human-readable form.
 106 Note that
 107 .I errno
 108 is undefined after a successful system call or library function call:
 109 this call may well change this variable, even though it succeeds,
 110 for example because it internally used some other library function that failed.
 111 Thus, if a failing call is not immediately followed by a call to
 112 .BR perror (),
 113 the value of
 114 .I errno
 115 should be saved.
 116 .SH VERSIONS
 117 Since glibc version 2.32, the declarations of
 118 .I sys_errlist
 119 and
 120 .I sys_nerr
 121 are no longer exposed by
 122 .IR <stdio.h> .
 123 .SH ATTRIBUTES
 124 For an explanation of the terms used in this section, see
 125 .BR attributes (7).
 126 .ad l
 127 .nh
 128 .TS
 129 allbox;
 130 lbx lb lb
 131 l l l.
 132 Interface       Attribute       Value
 133 T{
 134 .BR perror ()
 135 T}      Thread safety   MT-Safe race:stderr
 136 .TE
 137 .hy
 138 .ad
 139 .sp 1
 140 .SH CONFORMING TO
 141 .BR perror (),
 142 .IR errno :
 143 POSIX.1-2001, POSIX.1-2008, C89, C99, 4.3BSD.
 144 .PP
 145 The externals
 146 .I sys_nerr
 147 and
 148 .I sys_errlist
 149 derive from BSD, but are not specified in POSIX.1.
 150 .SH NOTES
 151 The externals
 152 .I sys_nerr
 153 and
 154 .I sys_errlist
 155 are defined by glibc, but in
 156 .IR <stdio.h> .
 157 .\" and only when _BSD_SOURCE is defined.
 158 .\" When
 159 .\" .B _GNU_SOURCE
 160 .\" is defined, the symbols
 161 .\" .I _sys_nerr
 162 .\" and
 163 .\" .I _sys_errlist
 164 .\" are provided.
 165 .SH SEE ALSO
 166 .BR err (3),
 167 .BR errno (3),
 168 .BR error (3),
 169 .BR strerror (3)