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