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 For an explanation of the terms used in this section, see
141 attributes(7).
142 ┌──────────┬───────────────┬─────────────────────────┐
144 │Interface │ Attribute │ Value │
145 ├──────────┼───────────────┼─────────────────────────┤
146 │fmtmsg() │ Thread safety │ glibc >= 2.16: MT-Safe │
147 │ │ │ glibc < 2.16: MT-Unsafe │
148 └──────────┴───────────────┴─────────────────────────┘
149 Before glibc 2.16, the fmtmsg() function uses a static variable that is
150 not protected, so it is not thread-safe.
151 Since glibc 2.16, the fmtmsg() function uses a lock to protect the
153 static variable, so it is thread-safe.
154
156 The functions fmtmsg() and addseverity(3), and environment variables
157 MSGVERB and SEV_LEVEL come from System V.
158 The function fmtmsg() and the environment variable MSGVERB are
160 described in POSIX.1-2001 and POSIX.1-2008.
161
163 System V and UnixWare man pages tell us that these functions have been
164 replaced by "pfmt() and addsev()" or by "pfmt(), vpfmt(), lfmt(), and
165 vlfmt()", and will be removed later.
166
168 #include <stdio.h>
169 #include <stdlib.h>
170 #include <fmtmsg.h>
171 int
173 main(void)
174 {
175 long class = MM_PRINT | MM_SOFT | MM_OPSYS | MM_RECOVER;
176 int err;
177 err = fmtmsg(class, "util-linux:mount", MM_ERROR,
179 "unknown mount option", "See mount(8).",
180 "util-linux:mount:017");
181 switch (err) {
182 case MM_OK:
183 break;
184 case MM_NOTOK:
185 printf("Nothing printed\n");
186 break;
187 case MM_NOMSG:
188 printf("Nothing printed to stderr\n");
189 break;
190 case MM_NOCON:
191 printf("No console output\n");
192 break;
193 default:
194 printf("Unknown error from fmtmsg()\n");
195 }
196 exit(EXIT_SUCCESS);
197 }
198 The output should be:
200 util-linux:mount: ERROR: unknown mount option
202 TO FIX: See mount(8). util-linux:mount:017
203 and after
205 MSGVERB=text:action; export MSGVERB
207 the output becomes:
209 unknown mount option
211 TO FIX: See mount(8).
212
214 addseverity(3), perror(3)
215
217 This page is part of release 5.02 of the Linux man-pages project. A
218 description of the project, information about reporting bugs, and the
219 latest version of this page, can be found at
220 https://www.kernel.org/doc/man-pages/.
221 2017-09-15 FMTMSG(3)