1FMTMSG(3) Linux Programmer's Manual FMTMSG(3)
2
6 fmtmsg - print formatted error messages
7
9 #include <fmtmsg.h>
10 int fmtmsg(long classification, const char *label,
12 int severity, const char *text,
13 const char *action, const char *tag);
14
16 This function displays a message described by its arguments on the
17 device(s) specified in the classification argument. For messages writ‐
18 ten to stderr, the format depends on the MSGVERB environment variable.
19 The label argument identifies the source of the message. The string
21 must consist of two colon separated parts where the first part has not
22 more than 10 and the second part not more than 14 characters.
23 The text argument describes the condition of the error.
25 The action argument describes possible steps to recover from the error.
27 If it is printed, it is prefixed by "TO FIX: ".
28 The tag argument is a reference to the online documentation where more
30 information can be found. It should contain the label value and a
31 unique identification number.
32 Dummy arguments
34 Each of the arguments can have a dummy value. The dummy classification
35 value MM_NULLMC [22m(0L) does not specify any output, so nothing is
36 printed. The dummy severity value NO_SEV (0) says that no severity is
37 supplied. The values MM_NULLLBL, MM_NULLTXT, MM_NULLACT, MM_NULLTAG
38 are synonyms for ((char *) 0), the empty string, and MM_NULLSEV is a
39 synonym for NO_SEV.
40 The classification argument
42 The classification argument is the sum of values describing 4 types of
43 information.
44 The first value defines the output channel.
46 MM_PRINT Output to stderr.
48 MM_CONSOLE Output to the system console.
50 MM_PRINT | MM_CONSOLE
52 Output to both.
53 The second value is the source of the error:
55 MM_HARD A hardware error occurred.
57 MM_FIRM A firmware error occurred.
59 MM_SOFT A software error occurred.
61 The third value encodes the detector of the problem:
63 MM_APPL It is detected by an application.
65 MM_UTIL It is detected by a utility.
67 MM_OPSYS It is detected by the operating system.
69 The fourth value shows the severity of the incident:
71 MM_RECOVER It is a recoverable error.
73 MM_NRECOV It is a nonrecoverable error.
75 The severity argument
77 The severity argument can take one of the following values:
78 MM_NOSEV No severity is printed.
80 MM_HALT This value is printed as HALT.
82 MM_ERROR This value is printed as ERROR.
84 MM_WARNING This value is printed as WARNING.
86 MM_INFO This value is printed as INFO.
88 The numeric values are between 0 and 4. Using addseverity(3) or the
90 environment variable SEV_LEVEL you can add more levels and strings to
91 print.
92
94 The function can return 4 values:
95 MM_OK Everything went smooth.
97 MM_NOTOK Complete failure.
99 MM_NOMSG Error writing to stderr.
101 MM_NOCON Error writing to the console.
103
105 The environment variable MSGVERB ("message verbosity") can be used to
106 suppress parts of the output to stderr. (It does not influence output
107 to the console.) When this variable is defined, is non-NULL, and is a
108 colon-separated list of valid keywords, then only the parts of the mes‐
109 sage corresponding to these keywords is printed. Valid keywords are
110 "label", "severity", "text", "action" and "tag".
111 The environment variable SEV_LEVEL can be used to introduce new sever‐
113 ity levels. By default, only the five severity levels described above
114 are available. Any other numeric value would make fmtmsg() print noth‐
115 ing. If the user puts SEV_LEVEL with a format like
116 SEV_LEVEL=[description[:description[:...]]]
118 in the environment of the process before the first call to fmtmsg(),
120 where each description is of the form
121 severity-keyword,level,printstring
123 then fmtmsg() will also accept the indicated values for the level (in
125 addition to the standard levels 0-4), and use the indicated printstring
126 when such a level occurs.
127 The severity-keyword part is not used by fmtmsg() but it has to be
129 present. The level part is a string representation of a number. The
130 numeric value must be a number greater than 4. This value must be used
131 in the severity argument of fmtmsg() to select this class. It is not
132 possible to overwrite any of the predefined classes. The printstring
133 is the string printed when a message of this class is processed by
134 fmtmsg().
135
137 fmtmsg() is provided in glibc since version 2.1.
138
140 The functions fmtmsg() and addseverity(3), and environment variables
141 MSGVERB and SEV_LEVEL come from System V. The function fmtmsg() and
142 the environment variable MSGVERB are described in POSIX.1-2001.
143
145 System V and Unixware man pages tell us that these functions have been
146 replaced by "pfmt() and addsev()" or by "pfmt(), vpfmt(), lfmt(), and
147 vlfmt()", and will be removed later.
148
150 #include <stdio.h>
151 #include <stdlib.h>
152 #include <fmtmsg.h>
153 int
155 main(void)
156 {
157 long class = MM_PRINT | MM_SOFT | MM_OPSYS | MM_RECOVER;
158 int err;
159 err = fmtmsg(class, "util-linux:mount", MM_ERROR,
161 "unknown mount option", "See mount(8).",
162 "util-linux:mount:017");
163 switch (err) {
164 case MM_OK:
165 break;
166 case MM_NOTOK:
167 printf("Nothing printed\n");
168 break;
169 case MM_NOMSG:
170 printf("Nothing printed to stderr\n");
171 break;
172 case MM_NOCON:
173 printf("No console output\n");
174 break;
175 default:
176 printf("Unknown error from fmtmsg()\n");
177 }
178 exit(EXIT_SUCCESS);
179 }
180 The output should be:
182 util-linux:mount: ERROR: unknown mount option
184 TO FIX: See mount(8). util-linux:mount:017
185 and after
187 MSGVERB=text:action; export MSGVERB
189 the output becomes:
191 unknown mount option
193 TO FIX: See mount(8).
194
196 addseverity(3), perror(3)
197
199 This page is part of release 3.25 of the Linux man-pages project. A
200 description of the project, and information about reporting bugs, can
201 be found at http://www.kernel.org/doc/man-pages/.
202 2008-06-14 FMTMSG(3)