Debian Codegraph @

upstream/debian-unstable/man3/perror.3

raw
1 '\" t
2 .\" Copyright 1996, Andries E. Brouwer <[email protected]>
3 .\" Copyright, the authors of the Linux man-pages project
4 .\"
5 .\" SPDX-License-Identifier: GPL-2.0-or-later
6 .\"
7 .TH perror 3 2026-02-08 "Linux man-pages 6.18"
8 .SH NAME
9 perror \- print a system error message
10 .SH LIBRARY
11 Standard C library
12 .RI ( libc ,\~ \-lc )
13 .SH SYNOPSIS
14 .nf
15 .B #include <stdio.h>
16 .P
17 .BI "void perror(const char *" s );
18 .P
19 .B #include <errno.h>
20 .P
21 .BI "int " errno "; \f[R]/* Not really declared this way; see errno(3) */\f[]"
22 .P
23 .BI "[[deprecated]] const char *const " sys_errlist [];
24 .BI "[[deprecated]] int " sys_nerr ;
25 .fi
26 .P
27 .RS -4
28 Feature Test Macro Requirements for glibc (see
29 .BR feature_test_macros (7)):
30 .RE
31 .P
32 .IR sys_errlist ,
33 .IR sys_nerr :
34 .nf
35 From glibc 2.19 to glibc 2.31:
36 _DEFAULT_SOURCE
37 glibc 2.19 and earlier:
38 _BSD_SOURCE
39 .fi
40 .SH DESCRIPTION
41 The
42 .BR perror ()
43 function produces a message on standard error describing the last
44 error encountered during a call to a system or library function.
45 .P
46 First (if
47 .I s
48 is not NULL and
49 .I *s
50 is not a null byte (\[aq]\[rs]0\[aq])), the argument string
51 .I s
52 is printed, followed by a colon and a blank.
53 Then an error message corresponding to the current value of
54 .I errno
55 and a new-line.
56 .P
57 To be of most use, the argument string should include the name
58 of the function that incurred the error.
59 .P
60 The global error list
61 .IR sys_errlist "[],"
62 which can be indexed by
63 .IR errno ,
64 can be used to obtain the error message without the newline.
65 The largest message number provided in the table is
66 .IR sys_nerr "\-1."
67 Be careful when directly accessing this list,
68 because new error values
69 may not have been added to
70 .IR sys_errlist [].
71 The use of
72 .IR sys_errlist []
73 is nowadays deprecated;
74 use
75 .BR strerror (3)
76 instead.
77 .P
78 When a system call fails,
79 it usually returns \-1
80 and sets the variable
81 .I errno
82 to a value describing what went wrong.
83 (These values can be found in
84 .IR <errno.h> .)
85 Many library functions do likewise.
86 The function
87 .BR perror ()
88 serves to translate this error code into human-readable form.
89 Note that
90 .I errno
91 is undefined after a successful system call or library function call:
92 this call may well change this variable, even though it succeeds,
93 for example because it internally used some other library function that failed.
94 Thus, if a failing call is not immediately followed by a call to
95 .BR perror (),
96 the value of
97 .I errno
98 should be saved.
99 .SH ATTRIBUTES
100 For an explanation of the terms used in this section, see
101 .BR attributes (7).
102 .TS
103 allbox;
104 lbx lb lb
105 l l l.
106 Interface Attribute Value
107 T{
108 .na
109 .nh
110 .BR perror ()
111 T} Thread safety MT-Safe race:stderr
112 .TE
113 .SH STANDARDS
114 .TP
115 .I errno
116 .TQ
117 .BR perror ()
118 C11, POSIX.1-2008.
119 .TP
120 .I sys_nerr
121 .TQ
122 .I sys_errlist
123 BSD.
124 .SH HISTORY
125 .TP
126 .I errno
127 .TQ
128 .BR perror ()
129 POSIX.1-2001, C89, 4.3BSD.
130 .TP
131 .I sys_nerr
132 .TQ
133 .I sys_errlist
134 Removed in glibc 2.32.
135 .SH SEE ALSO
136 .BR err (3),
137 .BR errno (3),
138 .BR error (3),
139 .BR strerror (3)