| .\" Copyright (c) 1994 Michael Haardt (michael@moria.de), 1994-06-04 |
| .\" Copyright (c) 1995 Michael Haardt |
| .\" (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 |
| .\" the License, or (at your option) any later version. |
| .\" |
| .\" The GNU General Public License's references to "object code" |
| .\" and "executables" are to be interpreted as the output of any |
| .\" document formatting or typesetting system, including |
| .\" intermediate and printed output. |
| .\" |
| .\" This manual is distributed in the hope that it will be useful, |
| .\" but WITHOUT ANY WARRANTY; without even the implied warranty of |
| .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the |
| .\" 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, 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 2019-03-06 "" "Linux Programmer's Manual" |
| .SH NAME |
| perror \- print a system error message |
| .SH SYNOPSIS |
| .B #include <stdio.h> |
| .PP |
| .BI "void perror(const char *" s ); |
| |
| .B #include <errno.h> |
| .PP |
| .BI "const char * const " sys_errlist []; |
| .br |
| .BI "int " sys_nerr ; |
| .br |
| .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 |
| .BR perror () |
| 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 |
| .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 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. |
| .PP |
| The global error list |
| .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 |
| 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> .) |
| 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 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 |
| .BR perror (), |
| the value of |
| .I errno |
| should be saved. |
| .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 () |
| 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 |
| derive from BSD, but are not specified in POSIX.1. |
| .SH NOTES |
| The externals |
| .I sys_nerr |
| and |
| .I sys_errlist |
| are defined by glibc, but in |
| .IR <stdio.h> . |
| .\" and only when _BSD_SOURCE is defined. |
| .\" When |
| .\" .B _GNU_SOURCE |
| .\" is defined, the symbols |
| .\" .I _sys_nerr |
| .\" and |
| .\" .I _sys_errlist |
| .\" are provided. |
| .SH SEE ALSO |
| .BR err (3), |
| .BR errno (3), |
| .BR error (3), |
| .BR strerror (3) |