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 de‐
17 vice(s) specified in the classification argument. For messages written
18 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 at‐
141 tributes(7).
142 ┌──────────┬───────────────┬───────────────────────────────────────────┐
144 │Interface │ Attribute │ Value │
145 ├──────────┼───────────────┼───────────────────────────────────────────┤
146 │fmtmsg() │ Thread safety │ glibc >= 2.16: MT-Safe; glibc < 2.16: MT- │
147 │ │ │ Unsafe │
148 └──────────┴───────────────┴───────────────────────────────────────────┘
149 Before glibc 2.16, the fmtmsg() function uses a static variable that is
151 not protected, so it is not thread-safe.
152 Since glibc 2.16, the fmtmsg() function uses a lock to protect the
154 static variable, so it is thread-safe.
155
157 The functions fmtmsg() and addseverity(3), and environment variables
158 MSGVERB and SEV_LEVEL come from System V.
159 The function fmtmsg() and the environment variable MSGVERB are de‐
161 scribed in POSIX.1-2001 and POSIX.1-2008.
162
164 System V and UnixWare man pages tell us that these functions have been
165 replaced by "pfmt() and addsev()" or by "pfmt(), vpfmt(), lfmt(), and
166 vlfmt()", and will be removed later.
167
169 #include <stdio.h>
170 #include <stdlib.h>
171 #include <fmtmsg.h>
172 int
174 main(void)
175 {
176 long class = MM_PRINT | MM_SOFT | MM_OPSYS | MM_RECOVER;
177 int err;
178 err = fmtmsg(class, "util-linux:mount", MM_ERROR,
180 "unknown mount option", "See mount(8).",
181 "util-linux:mount:017");
182 switch (err) {
183 case MM_OK:
184 break;
185 case MM_NOTOK:
186 printf("Nothing printed\n");
187 break;
188 case MM_NOMSG:
189 printf("Nothing printed to stderr\n");
190 break;
191 case MM_NOCON:
192 printf("No console output\n");
193 break;
194 default:
195 printf("Unknown error from fmtmsg()\n");
196 }
197 exit(EXIT_SUCCESS);
198 }
199 The output should be:
201 util-linux:mount: ERROR: unknown mount option
203 TO FIX: See mount(8). util-linux:mount:017
204 and after
206 MSGVERB=text:action; export MSGVERB
208 the output becomes:
210 unknown mount option
212 TO FIX: See mount(8).
213
215 addseverity(3), perror(3)
216
218 This page is part of release 5.12 of the Linux man-pages project. A
219 description of the project, information about reporting bugs, and the
220 latest version of this page, can be found at
221 https://www.kernel.org/doc/man-pages/.
222 2021-03-22 FMTMSG(3)