1 .\" Copyright 2002 walter harms (walter.harms@informatik.uni-oldenburg.de)
2 .\" Distributed under GPL
3 .\" adapted glibc info page
5 .\" This should run as 'Guru Meditation' (amiga joke :)
6 .\" The function is quite complex and deserves an example
8 .\" Polished, aeb, 2003-11-01
9 .TH FMTMSG 3 2008-06-14 "" "Linux Programmer's Manual"
11 fmtmsg \- print formatted error messages
14 .B #include <fmtmsg.h>
16 .BI "int fmtmsg(long " classification ", const char *" label ,
18 .BI " int " severity ", const char *" text ,
20 .BI " const char *" action ", const char *" tag );
23 This function displays a message described by its arguments on the device(s)
27 For messages written to
29 the format depends on the
35 argument identifies the source of the message.
36 The string must consist
37 of two colon separated parts where the first part has not more
38 than 10 and the second part not more than 14 characters.
42 argument describes the condition of the error.
46 argument describes possible steps to recover from the error.
47 If it is printed, it is prefixed by "TO FIX: ".
51 argument is a reference to the online documentation where more
52 information can be found.
55 value and a unique identification number.
57 Each of the arguments can have a dummy value.
58 The dummy classification value
60 (0L) does not specify any output, so nothing is printed.
61 The dummy severity value
63 (0) says that no severity is supplied.
75 .SS "The classification argument"
78 argument is the sum of values describing 4 types of information.
81 The first value defines the output channel.
88 Output to the system console.
90 .B "MM_PRINT | MM_CONSOLE"
93 The second value is the source of the error:
96 A hardware error occurred.
99 A firmware error occurred.
102 A software error occurred.
104 The third value encodes the detector of the problem:
107 It is detected by an application.
110 It is detected by a utility.
113 It is detected by the operating system.
115 The fourth value shows the severity of the incident:
118 It is a recoverable error.
121 It is a nonrecoverable error.
122 .SS "The severity argument"
125 argument can take one of the following values:
128 No severity is printed.
131 This value is printed as HALT.
134 This value is printed as ERROR.
137 This value is printed as WARNING.
140 This value is printed as INFO.
142 The numeric values are between 0 and 4.
145 or the environment variable
147 you can add more levels and strings to print.
149 The function can return 4 values:
152 Everything went smooth.
162 Error writing to the console.
164 The environment variable
166 ("message verbosity") can be used to suppress parts of
169 (It does not influence output to the console.)
170 When this variable is defined, is non-NULL, and is a colon-separated
171 list of valid keywords, then only the parts of the message corresponding
172 to these keywords is printed.
173 Valid keywords are "label", "severity", "text", "action" and "tag".
175 The environment variable
177 can be used to introduce new severity levels.
178 By default, only the five severity levels described
180 Any other numeric value would make
188 SEV_LEVEL=[description[:description[:...]]]
191 in the environment of the process before the first call to
193 where each description is of the form
196 severity-keyword,level,printstring
201 will also accept the indicated values for the level (in addition to
202 the standard levels 0-4), and use the indicated printstring when
205 The severity-keyword part is not used by
207 but it has to be present.
208 The level part is a string representation of a number.
209 The numeric value must be a number greater than 4.
210 This value must be used in the severity argument of
212 to select this class.
213 It is not possible to overwrite
214 any of the predefined classes.
216 is the string printed when a message of this class is processed by
220 is provided in glibc since version 2.1.
226 and environment variables
233 and the environment variable
235 are described in POSIX.1-2001.
237 System V and UnixWare man pages tell us that these functions
238 have been replaced by "pfmt() and addsev()" or by "pfmt(),
239 vpfmt(), lfmt(), and vlfmt()", and will be removed later.
249 long class = MM_PRINT | MM_SOFT | MM_OPSYS | MM_RECOVER;
252 err = fmtmsg(class, "util\-linux:mount", MM_ERROR,
253 "unknown mount option", "See mount(8).",
254 "util\-linux:mount:017");
259 printf("Nothing printed\en");
262 printf("Nothing printed to stderr\en");
265 printf("No console output\en");
268 printf("Unknown error from fmtmsg()\en");
274 The output should be:
277 util\-linux:mount: ERROR: unknown mount option
278 TO FIX: See mount(8). util\-linux:mount:017
284 MSGVERB=text:action; export MSGVERB
291 TO FIX: See mount(8).