.\" (michael@cantor.informatik.rwth-aachen.de), 1995-03-16
.\" Copyright (c) 1996 Andries Brouwer (aeb@cwi.nl), 1996-01-13
.\"
+.\" %%%LICENSE_START(GPLv2+_DOC_FULL)
.\" This is free documentation; you can redistribute it and/or
.\" modify it under the terms of the GNU General Public License as
.\" published by the Free Software Foundation; either version 2 of
.\" GNU General Public License for more details.
.\"
.\" You should have received a copy of the GNU General Public
-.\" License along with this manual; if not, write to the Free
-.\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111,
-.\" USA.
+.\" License along with this manual; if not, see
+.\" <http://www.gnu.org/licenses/>.
+.\" %%%LICENSE_END
.\"
.\" 1996-01-13 aeb: merged in some text contributed by Melvin Smith
.\" (msmith@falcon.mercer.peachnet.edu) and various other changes.
.\" Modified 1996-05-16 by Martin Schulze (joey@infodrom.north.de)
.\"
-.TH PERROR 3 2001-12-14 "" "Linux Programmer's Manual"
+.TH PERROR 3 2019-03-06 "" "Linux Programmer's Manual"
.SH NAME
perror \- print a system error message
.SH SYNOPSIS
.B #include <stdio.h>
-.sp
-.BI "void perror(const char " *s );
-.sp
+.PP
+.BI "void perror(const char *" s );
+
.B #include <errno.h>
-.sp
-.BI "const char *" sys_errlist [];
+.PP
+.BI "const char * const " sys_errlist [];
.br
.BI "int " sys_nerr ;
.br
-.BI "int " errno ;
+.BI "int " errno "; \fR/* Not really declared this way; see errno(3) */"
+.PP
+.in -4n
+Feature Test Macro Requirements for glibc (see
+.BR feature_test_macros (7)):
+.in
+.PP
+.IR sys_errlist ,
+.IR sys_nerr :
+ Since glibc 2.19:
+ _DEFAULT_SOURCE
+ Glibc 2.19 and earlier:
+ _BSD_SOURCE
.SH DESCRIPTION
-The routine
+The
.BR perror ()
-produces a message on the standard error output, describing the last
+function produces a message on standard error describing the last
error encountered during a call to a system or library function.
+.PP
First (if
.I s
is not NULL and
-.RI * s
-is not a null byte ('\\0')) the argument string
+.I *s
+is not a null byte (\(aq\e0\(aq)), the argument string
.I s
is printed, followed by a colon and a blank.
-Then the message and a new-line.
-
+Then an error message corresponding to the current value of
+.I errno
+and a new-line.
+.PP
To be of most use, the argument string should include the name
of the function that incurred the error.
-The error number is taken from
-the external variable
-.IR errno ,
-which is set when errors occur but not
-cleared when non-erroneous calls are made.
-
+.PP
The global error list
-.IR sys_errlist "[]"
-indexed by
-.I errno
+.IR sys_errlist "[],"
+which can be indexed by
+.IR errno ,
can be used to obtain the error message without the newline.
The largest message number provided in the table is
-.IR sys_nerr " \-1."
-Be careful when directly accessing this list because new error values
+.IR sys_nerr "\-1."
+Be careful when directly accessing this list, because new error values
may not have been added to
.IR sys_errlist "[]."
-
+The use of
+.IR sys_errlist "[]"
+is nowadays deprecated; use
+.BR strerror (3)
+instead.
+.PP
When a system call fails, it usually returns \-1 and sets the
variable
.I errno
to a value describing what went wrong.
(These values can be found in
-.IR "<errno.h>" .)
+.IR <errno.h> .)
Many library functions do likewise.
The function
.BR perror ()
serves to translate this error code into human-readable form.
Note that
.I errno
-is undefined after a successful library call:
+is undefined after a successful system call or library function call:
this call may well change this variable, even though it succeeds,
for example because it internally used some other library function that failed.
Thus, if a failing call is not immediately followed by a call to
the value of
.I errno
should be saved.
-.SH "CONFORMING TO"
-The function
+.SH ATTRIBUTES
+For an explanation of the terms used in this section, see
+.BR attributes (7).
+.TS
+allbox;
+lb lb lb
+l l l.
+Interface Attribute Value
+T{
.BR perror ()
-and the external
-.I errno
-(see
-.BR errno (3))
-conform to C89, C99, 4.3BSD, POSIX.1-2001.
+T} Thread safety MT-Safe race:stderr
+.TE
+.sp 1
+.SH CONFORMING TO
+.BR perror (),
+.IR errno :
+POSIX.1-2001, POSIX.1-2008, C89, C99, 4.3BSD.
+.PP
The externals
.I sys_nerr
and
.I sys_errlist
-conform to BSD.
+derive from BSD, but are not specified in POSIX.1.
.SH NOTES
The externals
.I sys_nerr
.IR <stdio.h> .
.\" and only when _BSD_SOURCE is defined.
.\" When
-.B _GNU_SOURCE
-is defined, the symbols
+.\" .B _GNU_SOURCE
+.\" is defined, the symbols
.\" .I _sys_nerr
.\" and
.\" .I _sys_errlist
.\" are provided.
-.SH "SEE ALSO"
+.SH SEE ALSO
.BR err (3),
.BR errno (3),
.BR error (3),
projects / thirdparty / man-pages.git / blobdiff