1 .\" Copyright 2002 walter harms (walter.harms@informatik.uni-oldenburg.de)
3 .\" %%%LICENSE_START(GPL_NOVERSION_ONELINE)
4 .\" Distributed under GPL
7 .\" adapted glibc info page
9 .\" This should run as 'Guru Meditation' (amiga joke :)
10 .\" The function is quite complex and deserves an example
12 .\" Polished, aeb, 2003-11-01
13 .TH FMTMSG 3 2013-06-21 "" "Linux Programmer's Manual"
15 fmtmsg \- print formatted error messages
18 .B #include <fmtmsg.h>
20 .BI "int fmtmsg(long " classification ", const char *" label ,
22 .BI " int " severity ", const char *" text ,
24 .BI " const char *" action ", const char *" tag );
27 This function displays a message described by its arguments on the device(s)
31 For messages written to
33 the format depends on the
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.
46 argument describes the condition of the error.
50 argument describes possible steps to recover from the error.
51 If it is printed, it is prefixed by "TO FIX: ".
55 argument is a reference to the online documentation where more
56 information can be found.
59 value and a unique identification number.
61 Each of the arguments can have a dummy value.
62 The dummy classification value
64 (0L) does not specify any output, so nothing is printed.
65 The dummy severity value
67 (0) says that no severity is supplied.
74 .IR "((char\ *)\ 0)" ,
79 .SS The classification argument
82 argument is the sum of values describing 4 types of information.
85 The first value defines the output channel.
92 Output to the system console.
94 .B "MM_PRINT | MM_CONSOLE"
97 The second value is the source of the error:
100 A hardware error occurred.
103 A firmware error occurred.
106 A software error occurred.
108 The third value encodes the detector of the problem:
111 It is detected by an application.
114 It is detected by a utility.
117 It is detected by the operating system.
119 The fourth value shows the severity of the incident:
122 It is a recoverable error.
125 It is a nonrecoverable error.
126 .SS The severity argument
129 argument can take one of the following values:
132 No severity is printed.
135 This value is printed as HALT.
138 This value is printed as ERROR.
141 This value is printed as WARNING.
144 This value is printed as INFO.
146 The numeric values are between 0 and 4.
149 or the environment variable
151 you can add more levels and strings to print.
153 The function can return 4 values:
156 Everything went smooth.
166 Error writing to the console.
168 The environment variable
170 ("message verbosity") can be used to suppress parts of
173 (It does not influence output to the console.)
174 When this variable is defined, is non-NULL, and is a colon-separated
175 list of valid keywords, then only the parts of the message corresponding
176 to these keywords is printed.
177 Valid keywords are "label", "severity", "text", "action" and "tag".
179 The environment variable
181 can be used to introduce new severity levels.
182 By default, only the five severity levels described
184 Any other numeric value would make
192 SEV_LEVEL=[description[:description[:...]]]
195 in the environment of the process before the first call to
197 where each description is of the form
200 severity-keyword,level,printstring
205 will also accept the indicated values for the level (in addition to
206 the standard levels 0-4), and use the indicated printstring when
209 The severity-keyword part is not used by
211 but it has to be present.
212 The level part is a string representation of a number.
213 The numeric value must be a number greater than 4.
214 This value must be used in the severity argument of
216 to select this class.
217 It is not possible to overwrite
218 any of the predefined classes.
220 is the string printed when a message of this class is processed by
224 is provided in glibc since version 2.1.
226 .SS Multithreading (see pthreads(7))
227 Before glibc 2.16, the
229 function uses a static variable that is not protected,
230 so it is not thread-safe.
233 .\" Modified in commit 7724defcf8873116fe4efab256596861eef21a94
236 function uses a lock to protect the static variable, so it is thread-safe.
242 and environment variables
249 and the environment variable
251 are described in POSIX.1-2001.
253 System V and UnixWare man pages tell us that these functions
254 have been replaced by "pfmt() and addsev()" or by "pfmt(),
255 vpfmt(), lfmt(), and vlfmt()", and will be removed later.
265 long class = MM_PRINT | MM_SOFT | MM_OPSYS | MM_RECOVER;
268 err = fmtmsg(class, "util\-linux:mount", MM_ERROR,
269 "unknown mount option", "See mount(8).",
270 "util\-linux:mount:017");
275 printf("Nothing printed\en");
278 printf("Nothing printed to stderr\en");
281 printf("No console output\en");
284 printf("Unknown error from fmtmsg()\en");
290 The output should be:
293 util\-linux:mount: ERROR: unknown mount option
294 TO FIX: See mount(8). util\-linux:mount:017
300 MSGVERB=text:action; export MSGVERB
307 TO FIX: See mount(8).