Debian Codegraph @

upstream/debian-unstable/man3/error.3

raw
1 '\" t
2 .\" Copyright 2006, Justin Pryzby <[email protected]>
3 .\" Copyright 2006, Michael Kerrisk <[email protected]>
4 .\" Copyright, the authors of the Linux man-pages project
5 .\"
6 .\" %%%LICENSE_START(PERMISSIVE_MISC)
7 .\" Permission is hereby granted, free of charge, to any person obtaining
8 .\" a copy of this software and associated documentation files (the
9 .\" "Software"), to deal in the Software without restriction, including
10 .\" without limitation the rights to use, copy, modify, merge, publish,
11 .\" distribute, sublicense, and/or sell copies of the Software, and to
12 .\" permit persons to whom the Software is furnished to do so, subject to
13 .\" the following conditions:
14 .\"
15 .\" The above copyright notice and this permission notice shall be
16 .\" included in all copies or substantial portions of the Software.
17 .\"
18 .\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
19 .\" EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
20 .\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
21 .\" IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
22 .\" CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
23 .\" TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
24 .\" SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
25 .\" %%%LICENSE_END
26 .\"
27 .TH error 3 2026-02-08 "Linux man-pages 6.18"
28 .SH NAME
29 error, error_at_line, error_message_count, error_one_per_line,
30 error_print_progname \- glibc error reporting functions
31 .SH LIBRARY
32 Standard C library
33 .RI ( libc ,\~ \-lc )
34 .SH SYNOPSIS
35 .nf
36 .B #include <error.h>
37 .P
38 .BI "void error(int " status ", int " errnum ", const char *" format ", ...);"
39 .BI "void error_at_line(int " status ", int " errnum ", const char *" file ,
40 .BI " unsigned int " line ", const char *" format ", ...);"
41 .P
42 .BI "extern unsigned int " error_message_count ;
43 .BI "extern int " error_one_per_line ;
44 .P
45 .BI "extern typeof(void (void)) *" error_print_progname ;
46 .fi
47 .SH DESCRIPTION
48 .BR error ()
49 is a general error-reporting function.
50 It flushes
51 .IR stdout ,
52 and then outputs to
53 .I stderr
54 the program name, a colon and a space, the message specified by the
55 .BR printf (3)-style
56 format string
57 .IR format ,
58 and, if
59 .I errnum
60 is nonzero,
61 a second colon and a space followed by the string given by
62 .IR strerror(errnum) .
63 Any arguments required for
64 .I format
65 should follow
66 .I format
67 in the argument list.
68 The output is terminated by a newline character.
69 .P
70 The program name printed by
71 .BR error ()
72 is the value of the global variable
73 .BR program_invocation_name (3).
74 .I program_invocation_name
75 initially has the same value as
76 .IR main ()'s
77 .IR argv[0] .
78 The value of this variable can be modified to change the output of
79 .BR error ().
80 .P
81 If
82 .I status
83 has a nonzero value, then
84 .BR error ()
85 calls
86 .BR exit (3)
87 to terminate the program using the given value as the exit status;
88 otherwise it returns after printing the error message.
89 .P
90 The
91 .BR error_at_line ()
92 function is exactly the same as
93 .BR error (),
94 except for the addition of the arguments
95 .I file
96 and
97 .IR line .
98 The output produced is as for
99 .BR error (),
100 except that after the program name are written: a colon, the value of
101 .IR file ,
102 a colon, and the value of
103 .IR line .
104 The preprocessor values
105 .B __LINE__
106 and
107 .B __FILE__
108 may be useful when calling
109 .BR error_at_line (),
110 but other values can also be used.
111 For example, these arguments could refer to a location in an input file.
112 .P
113 If the global variable
114 .I error_one_per_line
115 is set nonzero,
116 a sequence of
117 .BR error_at_line ()
118 calls with the
119 same value of
120 .I file
121 and
122 .I line
123 will result in only
124 one message (the first) being output.
125 .P
126 The global variable
127 .I error_message_count
128 counts the number of
129 messages that have been output by
130 .BR error ()
131 and
132 .BR error_at_line ().
133 .P
134 If the global variable
135 .I error_print_progname
136 is assigned the address of a function
137 (i.e., is not NULL), then that function is called
138 instead of prefixing the message with the program name and colon.
139 The function should print a suitable string to
140 .IR stderr .
141 .SH ATTRIBUTES
142 For an explanation of the terms used in this section, see
143 .BR attributes (7).
144 .TS
145 allbox;
146 lb lb lbx
147 l l l.
148 Interface Attribute Value
149 T{
150 .na
151 .nh
152 .BR error ()
153 T} Thread safety MT-Safe locale
154 T{
155 .na
156 .nh
157 .BR error_at_line ()
158 T} Thread safety T{
159 .na
160 .nh
161 MT-Unsafe\ race: error_at_line/\:error_one_per_line locale
162 T}
163 .TE
164 .P
165 The internal
166 .I error_one_per_line
167 variable is accessed
168 (without any form of synchronization,
169 but since it's an
170 .I int
171 used once,
172 it should be safe enough),
173 and if
174 .I error_one_per_line
175 is set nonzero,
176 the internal static variables
177 (not exposed to users)
178 used to hold the last printed filename and line number are accessed
179 and modified without synchronization;
180 the update is not atomic and
181 it occurs before disabling cancelation,
182 so it can be interrupted
183 only after one of the two variables is modified.
184 After that,
185 .BR error_at_line ()
186 is very much like
187 .BR error ().
188 .SH STANDARDS
189 GNU.
190 .SH SEE ALSO
191 .BR err (3),
192 .BR errno (3),
193 .BR exit (3),
194 .BR perror (3),
195 .BR program_invocation_name (3),
196 .BR strerror (3)