mirror of https://github.com/mkerrisk/man-pages
128 lines
3.7 KiB
Groff
128 lines
3.7 KiB
Groff
.\" 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
|
|
.\"
|
|
.\" 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, write to the Free
|
|
.\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111,
|
|
.\" USA.
|
|
.\"
|
|
.\" 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 "" "Library functions"
|
|
.SH NAME
|
|
perror \- print a system error message
|
|
.SH SYNOPSIS
|
|
.B #include <stdio.h>
|
|
.sp
|
|
.BI "void perror(const char " *s );
|
|
.sp
|
|
.B #include <errno.h>
|
|
.sp
|
|
.BI "const char *" sys_errlist [];
|
|
.br
|
|
.BI "int " sys_nerr ;
|
|
.br
|
|
.BI "int " errno ;
|
|
.SH DESCRIPTION
|
|
The routine
|
|
.BR perror ()
|
|
produces a message on the standard error output, describing the last
|
|
error encountered during a call to a system or library function.
|
|
First (if
|
|
.I s
|
|
is not NULL and
|
|
.RI * s
|
|
is not a null byte ('\\0')) the argument string
|
|
.I s
|
|
is printed, followed by a colon and a blank.
|
|
Then the message and a new-line.
|
|
|
|
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.
|
|
|
|
The global error list
|
|
.IR sys_errlist "[]"
|
|
indexed by
|
|
.I 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 "[]."
|
|
|
|
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 library 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 "CONFORMING TO"
|
|
The function
|
|
.BR perror ()
|
|
and the external
|
|
.I errno
|
|
(see
|
|
.BR errno (3))
|
|
conform to ANSI C, 4.3BSD, POSIX, X/OPEN.
|
|
The externals
|
|
.I sys_nerr
|
|
and
|
|
.I sys_errlist
|
|
conform to BSD.
|
|
.SH NOTE
|
|
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 _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)
|