Debian Codegraph @

upstream/debian-unstable/man3/fmtmsg.3

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