]>
Commit | Line | Data |
---|---|---|
921166c4 | 1 | .\" Copyright (C) 2006 Justin Pryzby <pryzbyj@justinpryzby.com> |
c11b1abf | 2 | .\" and Copyright (C) 2006 Michael Kerrisk <mtk.manpages@gmail.com> |
921166c4 | 3 | .\" |
7c576f45 | 4 | .\" %%%LICENSE_START(PERMISSIVE_MISC) |
921166c4 MK |
5 | .\" Permission is hereby granted, free of charge, to any person obtaining |
6 | .\" a copy of this software and associated documentation files (the | |
7 | .\" "Software"), to deal in the Software without restriction, including | |
8 | .\" without limitation the rights to use, copy, modify, merge, publish, | |
9 | .\" distribute, sublicense, and/or sell copies of the Software, and to | |
10 | .\" permit persons to whom the Software is furnished to do so, subject to | |
11 | .\" the following conditions: | |
12 | .\" | |
13 | .\" The above copyright notice and this permission notice shall be | |
14 | .\" included in all copies or substantial portions of the Software. | |
15 | .\" | |
16 | .\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, | |
17 | .\" EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF | |
18 | .\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. | |
19 | .\" IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY | |
20 | .\" CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, | |
21 | .\" TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE | |
22 | .\" SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. | |
8ff7380d | 23 | .\" %%%LICENSE_END |
921166c4 MK |
24 | .\" |
25 | .\" References: | |
26 | .\" glibc manual and source | |
4b8c67d9 | 27 | .TH ERROR 3 2017-09-15 "GNU" "Linux Programmer's Manual" |
921166c4 | 28 | .SH NAME |
9a4aaddc | 29 | error, error_at_line, error_message_count, error_one_per_line, |
921166c4 MK |
30 | error_print_progname \- glibc error reporting functions |
31 | .SH SYNOPSIS | |
32 | .nf | |
7f8e1b17 | 33 | .B #include <error.h> |
dbfe9c70 | 34 | .PP |
7f8e1b17 | 35 | .BI "void error(int " status ", int " errnum ", const char *" format ", ...);" |
dbfe9c70 | 36 | .PP |
7f8e1b17 MK |
37 | .BI "void error_at_line(int " status ", int " errnum ", const char *" filename , |
38 | .BI " unsigned int " linenum ", const char *" format ", ...);" | |
dbfe9c70 | 39 | .PP |
7f8e1b17 | 40 | .BI "extern unsigned int " error_message_count ; |
dbfe9c70 | 41 | .PP |
7f8e1b17 | 42 | .BI "extern int " error_one_per_line ; |
dbfe9c70 | 43 | .PP |
7f8e1b17 | 44 | .BI "extern void (*" error_print_progname ") (void);" |
921166c4 MK |
45 | .fi |
46 | .SH DESCRIPTION | |
60a90ecd | 47 | .BR error () |
f1bb2402 | 48 | is a general error-reporting function. |
921166c4 MK |
49 | It flushes |
50 | .IR stdout , | |
c13182ef MK |
51 | and then outputs to |
52 | .I stderr | |
53 | the program name, a colon and a space, the message specified by the | |
54 | .BR printf (3)-style | |
921166c4 | 55 | format string \fIformat\fP, and, if \fIerrnum\fP is |
c7094399 | 56 | nonzero, a second colon and a space followed by the string given by |
97a21066 | 57 | .IR strerror(errnum) . |
921166c4 | 58 | Any arguments required for |
c13182ef MK |
59 | .I format |
60 | should follow | |
921166c4 MK |
61 | .I format |
62 | in the argument list. | |
63 | The output is terminated by a newline character. | |
847e0d88 | 64 | .PP |
c13182ef | 65 | The program name printed by |
921166c4 MK |
66 | .BR error () |
67 | is the value of the global variable | |
7fe9faa2 | 68 | .BR program_invocation_name (3). |
0daa9e92 | 69 | .I program_invocation_name |
6ff9cf67 MK |
70 | initially has the same value as |
71 | .IR main ()'s | |
72 | .IR argv[0] . | |
921166c4 MK |
73 | The value of this variable can be modified to change the output of |
74 | .BR error (). | |
847e0d88 | 75 | .PP |
c7094399 | 76 | If \fIstatus\fP has a nonzero value, then |
921166c4 MK |
77 | .BR error () |
78 | calls | |
79 | .BR exit (3) | |
80 | to terminate the program using the given value as the exit status. | |
847e0d88 | 81 | .PP |
60a90ecd MK |
82 | The |
83 | .BR error_at_line () | |
84 | function is exactly the same as | |
85 | .BR error (), | |
921166c4 MK |
86 | except for the addition of the arguments |
87 | .I filename | |
88 | and | |
89 | .IR linenum . | |
c13182ef | 90 | The output produced is as for |
921166c4 MK |
91 | .BR error (), |
92 | except that after the program name are written: a colon, the value of | |
93 | .IR filename , | |
c13182ef | 94 | a colon, and the value of |
921166c4 MK |
95 | .IR linenum . |
96 | The preprocessor values \fB__LINE__\fP and | |
60a90ecd MK |
97 | \fB__FILE__\fP may be useful when calling |
98 | .BR error_at_line (), | |
921166c4 MK |
99 | but other values can also be used. |
100 | For example, these arguments could refer to a location in an input file. | |
847e0d88 | 101 | .PP |
c7094399 | 102 | If the global variable \fIerror_one_per_line\fP is set nonzero, |
0143e6bc | 103 | a sequence of |
60a90ecd MK |
104 | .BR error_at_line () |
105 | calls with the | |
7669b5a6 | 106 | same value of \fIfilename\fP and \fIlinenum\fP will result in only |
c13182ef | 107 | one message (the first) being output. |
847e0d88 | 108 | .PP |
c13182ef | 109 | The global variable \fIerror_message_count\fP counts the number of |
921166c4 | 110 | messages that have been output by |
60a90ecd MK |
111 | .BR error () |
112 | and | |
113 | .BR error_at_line (). | |
847e0d88 | 114 | .PP |
c13182ef | 115 | If the global variable \fIerror_print_progname\fP |
921166c4 MK |
116 | is assigned the address of a function |
117 | (i.e., is not NULL), then that function is called | |
118 | instead of prefixing the message with the program name and colon. | |
119 | The function should print a suitable string to | |
120 | .IR stderr . | |
b08ffceb ZL |
121 | .SH ATTRIBUTES |
122 | For an explanation of the terms used in this section, see | |
123 | .BR attributes (7). | |
74714ea8 | 124 | .ad l |
b08ffceb ZL |
125 | .TS |
126 | allbox; | |
74714ea8 | 127 | lb lb lbw33 |
b08ffceb ZL |
128 | l l l. |
129 | Interface Attribute Value | |
130 | T{ | |
131 | .BR error () | |
132 | T} Thread safety MT-Safe locale | |
133 | T{ | |
134 | .BR error_at_line () | |
135 | T} Thread safety T{ | |
da31981e | 136 | MT-Unsafe\ race: error_at_line/error_one_per_line locale |
b08ffceb ZL |
137 | T} |
138 | .TE | |
74714ea8 | 139 | .ad |
847e0d88 | 140 | .PP |
b08ffceb ZL |
141 | The internal |
142 | .I error_one_per_line | |
da31981e MK |
143 | variable is accessed (without any form of synchronization, but since it's an |
144 | .I int | |
145 | used once, it should be safe enough) and, if | |
b08ffceb | 146 | .I error_one_per_line |
da31981e MK |
147 | is set nonzero, the internal static variables (not exposed to users) |
148 | used to hold the last printed filename and line number are accessed | |
b08ffceb | 149 | and modified without synchronization; the update is not atomic and it |
da31981e MK |
150 | occurs before disabling cancellation, so it can be interrupted only after |
151 | one of the two variables is modified. | |
152 | After that, | |
bcb464e2 | 153 | .BR error_at_line () |
b08ffceb | 154 | is very much like |
bf7bc8b8 | 155 | .BR error (). |
47297adb | 156 | .SH CONFORMING TO |
921166c4 MK |
157 | These functions and variables are GNU extensions, and should not be |
158 | used in programs intended to be portable. | |
159 | .SH SEE ALSO | |
c768efc6 | 160 | .BR err (3), |
921166c4 | 161 | .BR errno (3), |
c768efc6 | 162 | .BR exit (3), |
921166c4 | 163 | .BR perror (3), |
7fe9faa2 | 164 | .BR program_invocation_name (3), |
c768efc6 | 165 | .BR strerror (3) |