[thirdparty/man-pages.git] / man3 / perror.3

.\" 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 2015-07-23 "" "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
.B #include <errno.h>
.sp
.BI "const char * const " sys_errlist [];
.br
.BI "int " sys_nerr ;
.br
.BI "int " errno ";       \fR/* Not really declared this way; see errno(3) */"
.sp
.in -4n
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.in
.sp
.IR sys_errlist ,
.IR sys_nerr :
_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.

First (if
.I s
is not NULL and
.I *s
is not a null byte (\(aq\\0\(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.

To be of most use, the argument string should include the name
of the function that incurred the error.

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.

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 sysme 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

.SH CONFORMING TO
.BR perror (),
.IR errno :
POSIX.1-2001, POSIX.1-2008, C89, C99, 4.3BSD.

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)
Commit	Line	Data
	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 2015-07-23 "" "Linux Programmer's Manual"
	32	.SH NAME
	33	perror \- print a system error message
	34	.SH SYNOPSIS
	35	.B #include <stdio.h>
	36	.sp
	37	.BI "void perror(const char *" s );
	38	.sp
	39	.B #include <errno.h>
	40	.sp
	41	.BI "const char * const " sys_errlist [];
	42	.br
	43	.BI "int " sys_nerr ;
	44	.br
	45	.BI "int " errno "; \fR/* Not really declared this way; see errno(3) */"
	46	.sp
	47	.in -4n
	48	Feature Test Macro Requirements for glibc (see
	49	.BR feature_test_macros (7)):
	50	.in
	51	.sp
	52	.IR sys_errlist ,
	53	.IR sys_nerr :
	54	_BSD_SOURCE
	55	.SH DESCRIPTION
	56	The
	57	.BR perror ()
	58	function produces a message on standard error describing the last
	59	error encountered during a call to a system or library function.
	60
	61	First (if
	62	.I s
	63	is not NULL and
	64	.I *s
	65	is not a null byte (\(aq\\0\(aq)), the argument string
	66	.I s
	67	is printed, followed by a colon and a blank.
	68	Then an error message corresponding to the current value of
	69	.I errno
	70	and a new-line.
	71
	72	To be of most use, the argument string should include the name
	73	of the function that incurred the error.
	74
	75	The global error list
	76	.IR sys_errlist "[],"
	77	which can be indexed by
	78	.IR errno ,
	79	can be used to obtain the error message without the newline.
	80	The largest message number provided in the table is
	81	.IR sys_nerr "\-1."
	82	Be careful when directly accessing this list, because new error values
	83	may not have been added to
	84	.IR sys_errlist "[]."
	85	The use of
	86	.IR sys_errlist "[]"
	87	is nowadays deprecated.
	88
	89	When a system call fails, it usually returns \-1 and sets the
	90	variable
	91	.I errno
	92	to a value describing what went wrong.
	93	(These values can be found in
	94	.IR <errno.h> .)
	95	Many library functions do likewise.
	96	The function
	97	.BR perror ()
	98	serves to translate this error code into human-readable form.
	99	Note that
	100	.I errno
	101	is undefined after a successful sysme call or library function call:
	102	this call may well change this variable, even though it succeeds,
	103	for example because it internally used some other library function that failed.
	104	Thus, if a failing call is not immediately followed by a call to
	105	.BR perror (),
	106	the value of
	107	.I errno
	108	should be saved.
	109	.SH ATTRIBUTES
	110	For an explanation of the terms used in this section, see
	111	.BR attributes (7).
	112	.TS
	113	allbox;
	114	lb lb lb
	115	l l l.
	116	Interface Attribute Value
	117	T{
	118	.BR perror ()
	119	T} Thread safety MT-Safe race:stderr
	120	.TE
	121
	122	.SH CONFORMING TO
	123	.BR perror (),
	124	.IR errno :
	125	POSIX.1-2001, POSIX.1-2008, C89, C99, 4.3BSD.
	126
	127	The externals
	128	.I sys_nerr
	129	and
	130	.I sys_errlist
	131	derive from BSD, but are not specified in POSIX.1.
	132	.SH NOTES
	133	The externals
	134	.I sys_nerr
	135	and
	136	.I sys_errlist
	137	are defined by glibc, but in
	138	.IR <stdio.h> .
	139	.\" and only when _BSD_SOURCE is defined.
	140	.\" When
	141	.\" .B _GNU_SOURCE
	142	.\" is defined, the symbols
	143	.\" .I _sys_nerr
	144	.\" and
	145	.\" .I _sys_errlist
	146	.\" are provided.
	147	.SH SEE ALSO
	148	.BR err (3),
	149	.BR errno (3),
	150	.BR error (3),
	151	.BR strerror (3)