Debian Codegraph @

upstream/debian-trixie/man3/fmtmsg.3

raw
1 '\" t
2 .\" Copyright 2002 walter harms ([email protected])
3 .\"
4 .\" SPDX-License-Identifier: GPL-1.0-or-later
5 .\"
6 .\" adapted glibc info page
7 .\"
8 .\" This should run as 'Guru Meditation' (amiga joke :)
9 .\" The function is quite complex and deserves an example
10 .\"
11 .\" Polished, aeb, 2003-11-01
12 .TH fmtmsg 3 2024-06-15 "Linux man-pages 6.9.1"
13 .SH NAME
14 fmtmsg \- print formatted error messages
15 .SH LIBRARY
16 Standard C library
17 .RI ( libc ", " \-lc )
18 .SH SYNOPSIS
19 .nf
20 .B #include <fmtmsg.h>
21 .P
22 .BI "int fmtmsg(long " classification ", const char *" label ,
23 .BI " int " severity ", const char *" text ,
24 .BI " const char *" action ", const char *" tag );
25 .fi
26 .SH DESCRIPTION
27 This function displays a message described by its arguments on the device(s)
28 specified in the
29 .I classification
30 argument.
31 For messages written to
32 .IR stderr ,
33 the format depends on the
34 .B MSGVERB
35 environment variable.
36 .P
37 The
38 .I label
39 argument identifies the source of the message.
40 The string must consist
41 of two colon separated parts where the first part has not more
42 than 10 and the second part not more than 14 characters.
43 .P
44 The
45 .I text
46 argument describes the condition of the error.
47 .P
48 The
49 .I action
50 argument describes possible steps to recover from the error.
51 If it is printed, it is prefixed by "TO FIX: ".
52 .P
53 The
54 .I tag
55 argument is a reference to the online documentation where more
56 information can be found.
57 It should contain the
58 .I label
59 value and a unique identification number.
60 .SS Dummy arguments
61 Each of the arguments can have a dummy value.
62 The dummy classification value
63 .B MM_NULLMC
64 (0L) does not specify any output, so nothing is printed.
65 The dummy severity value
66 .B NO_SEV
67 (0) says that no severity is supplied.
68 The values
69 .BR MM_NULLLBL ,
70 .BR MM_NULLTXT ,
71 .BR MM_NULLACT ,
72 .B MM_NULLTAG
73 are synonyms for
74 .IR "((char\ *)\ 0)" ,
75 the empty string, and
76 .B MM_NULLSEV
77 is a synonym for
78 .BR NO_SEV .
79 .SS The classification argument
80 The
81 .I classification
82 argument is the sum of values describing 4 types of information.
83 .P
84 The first value defines the output channel.
85 .TP 12n
86 .B MM_PRINT
87 Output to
88 .IR stderr .
89 .TP
90 .B MM_CONSOLE
91 Output to the system console.
92 .TP
93 .B "MM_PRINT | MM_CONSOLE"
94 Output to both.
95 .P
96 The second value is the source of the error:
97 .TP 12n
98 .B MM_HARD
99 A hardware error occurred.
100 .TP
101 .B MM_FIRM
102 A firmware error occurred.
103 .TP
104 .B MM_SOFT
105 A software error occurred.
106 .P
107 The third value encodes the detector of the problem:
108 .TP 12n
109 .B MM_APPL
110 It is detected by an application.
111 .TP
112 .B MM_UTIL
113 It is detected by a utility.
114 .TP
115 .B MM_OPSYS
116 It is detected by the operating system.
117 .P
118 The fourth value shows the severity of the incident:
119 .TP 12n
120 .B MM_RECOVER
121 It is a recoverable error.
122 .TP
123 .B MM_NRECOV
124 It is a nonrecoverable error.
125 .SS The severity argument
126 The
127 .I severity
128 argument can take one of the following values:
129 .TP 12n
130 .B MM_NOSEV
131 No severity is printed.
132 .TP
133 .B MM_HALT
134 This value is printed as HALT.
135 .TP
136 .B MM_ERROR
137 This value is printed as ERROR.
138 .TP
139 .B MM_WARNING
140 This value is printed as WARNING.
141 .TP
142 .B MM_INFO
143 This value is printed as INFO.
144 .P
145 The numeric values are between 0 and 4.
146 Using
147 .BR addseverity (3)
148 or the environment variable
149 .B SEV_LEVEL
150 you can add more levels and strings to print.
151 .SH RETURN VALUE
152 The function can return 4 values:
153 .TP 12n
154 .B MM_OK
155 Everything went smooth.
156 .TP
157 .B MM_NOTOK
158 Complete failure.
159 .TP
160 .B MM_NOMSG
161 Error writing to
162 .IR stderr .
163 .TP
164 .B MM_NOCON
165 Error writing to the console.
166 .SH ENVIRONMENT
167 The environment variable
168 .B MSGVERB
169 ("message verbosity") can be used to suppress parts of
170 the output to
171 .IR stderr .
172 (It does not influence output to the console.)
173 When this variable is defined, is non-NULL, and is a colon-separated
174 list of valid keywords, then only the parts of the message corresponding
175 to these keywords is printed.
176 Valid keywords are "label", "severity", "text", "action", and "tag".
177 .P
178 The environment variable
179 .B SEV_LEVEL
180 can be used to introduce new severity levels.
181 By default, only the five severity levels described
182 above are available.
183 Any other numeric value would make
184 .BR fmtmsg ()
185 print nothing.
186 If the user puts
187 .B SEV_LEVEL
188 with a format like
189 .P
190 .RS
191 SEV_LEVEL=[description[:description[:...]]]
192 .RE
193 .P
194 in the environment of the process before the first call to
195 .BR fmtmsg (),
196 where each description is of the form
197 .P
198 .RS
199 severity-keyword,level,printstring
200 .RE
201 .P
202 then
203 .BR fmtmsg ()
204 will also accept the indicated values for the level (in addition to
205 the standard levels 0\[en]4), and use the indicated printstring when
206 such a level occurs.
207 .P
208 The severity-keyword part is not used by
209 .BR fmtmsg ()
210 but it has to be present.
211 The level part is a string representation of a number.
212 The numeric value must be a number greater than 4.
213 This value must be used in the severity argument of
214 .BR fmtmsg ()
215 to select this class.
216 It is not possible to overwrite
217 any of the predefined classes.
218 The printstring
219 is the string printed when a message of this class is processed by
220 .BR fmtmsg ().
221 .SH ATTRIBUTES
222 For an explanation of the terms used in this section, see
223 .BR attributes (7).
224 .TS
225 allbox;
226 lb lb lbx
227 l l l.
228 Interface Attribute Value
229 T{
230 .na
231 .nh
232 .BR fmtmsg ()
233 T} Thread safety T{
234 .na
235 .nh
236 glibc\ >=\ 2.16: MT-Safe;
237 glibc\ <\ 2.16: MT-Unsafe
238 T}
239 .TE
240 .P
241 Before glibc 2.16, the
242 .BR fmtmsg ()
243 function uses a static variable that is not protected,
244 so it is not thread-safe.
245 .P
246 Since glibc 2.16,
247 .\" Modified in commit 7724defcf8873116fe4efab256596861eef21a94
248 the
249 .BR fmtmsg ()
250 function uses a lock to protect the static variable, so it is thread-safe.
251 .SH STANDARDS
252 .TP
253 .BR fmtmsg ()
254 .TQ
255 .B MSGVERB
256 POSIX.1-2008.
257 .SH HISTORY
258 .TP
259 .BR fmtmsg ()
260 System V.
261 POSIX.1-2001 and POSIX.1-2008.
262 glibc 2.1.
263 .TP
264 .B MSGVERB
265 System V.
266 POSIX.1-2001 and POSIX.1-2008.
267 .TP
268 .B SEV_LEVEL
269 System V.
270 .P
271 System V and UnixWare man pages tell us that these functions
272 have been replaced by "pfmt() and addsev()" or by "pfmt(),
273 vpfmt(), lfmt(), and vlfmt()", and will be removed later.
274 .SH EXAMPLES
275 .\" SRC BEGIN (fmtmsg.c)
276 .EX
277 #include <fmtmsg.h>
278 #include <stdio.h>
279 #include <stdlib.h>
280 \&
281 int
282 main(void)
283 {
284 long class = MM_PRINT | MM_SOFT | MM_OPSYS | MM_RECOVER;
285 int err;
286 \&
287 err = fmtmsg(class, "util\-linux:mount", MM_ERROR,
288 "unknown mount option", "See mount(8).",
289 "util\-linux:mount:017");
290 switch (err) {
291 case MM_OK:
292 break;
293 case MM_NOTOK:
294 printf("Nothing printed\[rs]n");
295 break;
296 case MM_NOMSG:
297 printf("Nothing printed to stderr\[rs]n");
298 break;
299 case MM_NOCON:
300 printf("No console output\[rs]n");
301 break;
302 default:
303 printf("Unknown error from fmtmsg()\[rs]n");
304 }
305 exit(EXIT_SUCCESS);
306 }
307 .EE
308 .\" SRC END
309 .P
310 The output should be:
311 .P
312 .in +4n
313 .EX
314 util\-linux:mount: ERROR: unknown mount option
315 TO FIX: See mount(8). util\-linux:mount:017
316 .EE
317 .in
318 .P
319 and after
320 .P
321 .in +4n
322 .EX
323 MSGVERB=text:action; export MSGVERB
324 .EE
325 .in
326 .P
327 the output becomes:
328 .P
329 .in +4n
330 .EX
331 unknown mount option
332 TO FIX: See mount(8).
333 .EE
334 .in
335 .SH SEE ALSO
336 .BR addseverity (3),
337 .BR perror (3)