Debian Codegraph @

upstream/debian-trixie/man3/perror.3

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