]>
Commit | Line | Data |
---|---|---|
fea681da | 1 | .\" Copyright 2002 walter harms (walter.harms@informatik.uni-oldenburg.de) |
2297bf0e | 2 | .\" |
95fb8859 | 3 | .\" SPDX-License-Identifier: GPL-1.0-or-later |
0389adc9 | 4 | .\" |
fea681da | 5 | .\" adapted glibc info page |
c13182ef | 6 | .\" |
fea681da | 7 | .\" This should run as 'Guru Meditation' (amiga joke :) |
763f0e47 | 8 | .\" The function is quite complex and deserves an example |
fea681da MK |
9 | .\" |
10 | .\" Polished, aeb, 2003-11-01 | |
45186a5d | 11 | .TH FMTMSG 3 2021-03-22 "Linux man-pages (unreleased)" |
fea681da MK |
12 | .SH NAME |
13 | fmtmsg \- print formatted error messages | |
cfba38f4 AC |
14 | .SH LIBRARY |
15 | Standard C library | |
16 | .RI ( libc ", " \-lc ) | |
fea681da MK |
17 | .SH SYNOPSIS |
18 | .nf | |
fea681da | 19 | .B #include <fmtmsg.h> |
68e4db0a | 20 | .PP |
fea681da | 21 | .BI "int fmtmsg(long " classification ", const char *" label , |
fea681da | 22 | .BI " int " severity ", const char *" text , |
fea681da | 23 | .BI " const char *" action ", const char *" tag ); |
fea681da MK |
24 | .fi |
25 | .SH DESCRIPTION | |
c4bb193f | 26 | This function displays a message described by its arguments on the device(s) |
fea681da MK |
27 | specified in the |
28 | .I classification | |
c4bb193f | 29 | argument. |
c13182ef | 30 | For messages written to |
fea681da MK |
31 | .IR stderr , |
32 | the format depends on the | |
33 | .B MSGVERB | |
34 | environment variable. | |
dd3568a1 | 35 | .PP |
fea681da MK |
36 | The |
37 | .I label | |
c4bb193f | 38 | argument identifies the source of the message. |
c13182ef | 39 | The string must consist |
fea681da | 40 | of two colon separated parts where the first part has not more |
c13182ef | 41 | than 10 and the second part not more than 14 characters. |
dd3568a1 | 42 | .PP |
fea681da MK |
43 | The |
44 | .I text | |
c4bb193f | 45 | argument describes the condition of the error. |
dd3568a1 | 46 | .PP |
fea681da MK |
47 | The |
48 | .I action | |
c4bb193f | 49 | argument describes possible steps to recover from the error. |
fea681da | 50 | If it is printed, it is prefixed by "TO FIX: ". |
dd3568a1 | 51 | .PP |
fea681da MK |
52 | The |
53 | .I tag | |
c4bb193f | 54 | argument is a reference to the online documentation where more |
c13182ef MK |
55 | information can be found. |
56 | It should contain the | |
fea681da MK |
57 | .I label |
58 | value and a unique identification number. | |
73d8cece | 59 | .SS Dummy arguments |
c4bb193f | 60 | Each of the arguments can have a dummy value. |
c13182ef | 61 | The dummy classification value |
fea681da MK |
62 | .B MM_NULLMC |
63 | (0L) does not specify any output, so nothing is printed. | |
64 | The dummy severity value | |
65 | .B NO_SEV | |
66 | (0) says that no severity is supplied. | |
67 | The values | |
68 | .BR MM_NULLLBL , | |
69 | .BR MM_NULLTXT , | |
70 | .BR MM_NULLACT , | |
0daa9e92 | 71 | .B MM_NULLTAG |
cab87712 | 72 | are synonyms for |
5049da5b | 73 | .IR "((char\ *)\ 0)" , |
cab87712 | 74 | the empty string, and |
fea681da MK |
75 | .B MM_NULLSEV |
76 | is a synonym for | |
77 | .BR NO_SEV . | |
73d8cece | 78 | .SS The classification argument |
c13182ef MK |
79 | The |
80 | .I classification | |
c4bb193f | 81 | argument is the sum of values describing 4 types of information. |
bdd915e2 | 82 | .PP |
fea681da MK |
83 | The first value defines the output channel. |
84 | .TP 12n | |
85 | .B MM_PRINT | |
86 | Output to | |
87 | .IR stderr . | |
88 | .TP | |
89 | .B MM_CONSOLE | |
90 | Output to the system console. | |
91 | .TP | |
92 | .B "MM_PRINT | MM_CONSOLE" | |
93 | Output to both. | |
94 | .PP | |
95 | The second value is the source of the error: | |
96 | .TP 12n | |
97 | .B MM_HARD | |
98 | A hardware error occurred. | |
99 | .TP | |
100 | .B MM_FIRM | |
101 | A firmware error occurred. | |
102 | .TP | |
103 | .B MM_SOFT | |
104 | A software error occurred. | |
105 | .PP | |
106 | The third value encodes the detector of the problem: | |
107 | .TP 12n | |
108 | .B MM_APPL | |
109 | It is detected by an application. | |
110 | .TP | |
111 | .B MM_UTIL | |
112 | It is detected by a utility. | |
113 | .TP | |
114 | .B MM_OPSYS | |
115 | It is detected by the operating system. | |
116 | .PP | |
117 | The fourth value shows the severity of the incident: | |
118 | .TP 12n | |
119 | .B MM_RECOVER | |
120 | It is a recoverable error. | |
121 | .TP | |
122 | .B MM_NRECOV | |
b28f6e56 | 123 | It is a nonrecoverable error. |
73d8cece | 124 | .SS The severity argument |
c13182ef MK |
125 | The |
126 | .I severity | |
c4bb193f | 127 | argument can take one of the following values: |
fea681da MK |
128 | .TP 12n |
129 | .B MM_NOSEV | |
130 | No severity is printed. | |
131 | .TP | |
132 | .B MM_HALT | |
133 | This value is printed as HALT. | |
134 | .TP | |
135 | .B MM_ERROR | |
136 | This value is printed as ERROR. | |
137 | .TP | |
138 | .B MM_WARNING | |
139 | This value is printed as WARNING. | |
140 | .TP | |
141 | .B MM_INFO | |
142 | This value is printed as INFO. | |
143 | .PP | |
c13182ef MK |
144 | The numeric values are between 0 and 4. |
145 | Using | |
fb186734 | 146 | .BR addseverity (3) |
fea681da MK |
147 | or the environment variable |
148 | .B SEV_LEVEL | |
149 | you can add more levels and strings to print. | |
47297adb | 150 | .SH RETURN VALUE |
2b2581ee MK |
151 | The function can return 4 values: |
152 | .TP 12n | |
153 | .B MM_OK | |
154 | Everything went smooth. | |
155 | .TP | |
156 | .B MM_NOTOK | |
157 | Complete failure. | |
158 | .TP | |
159 | .B MM_NOMSG | |
160 | Error writing to | |
161 | .IR stderr . | |
162 | .TP | |
163 | .B MM_NOCON | |
164 | Error writing to the console. | |
fea681da | 165 | .SH ENVIRONMENT |
c13182ef | 166 | The environment variable |
fea681da MK |
167 | .B MSGVERB |
168 | ("message verbosity") can be used to suppress parts of | |
169 | the output to | |
170 | .IR stderr . | |
171 | (It does not influence output to the console.) | |
172 | When this variable is defined, is non-NULL, and is a colon-separated | |
173 | list of valid keywords, then only the parts of the message corresponding | |
174 | to these keywords is printed. | |
735334d4 | 175 | Valid keywords are "label", "severity", "text", "action", and "tag". |
fea681da MK |
176 | .PP |
177 | The environment variable | |
178 | .B SEV_LEVEL | |
179 | can be used to introduce new severity levels. | |
180 | By default, only the five severity levels described | |
c13182ef MK |
181 | above are available. |
182 | Any other numeric value would make | |
183 | .BR fmtmsg () | |
b5cc2ffb | 184 | print nothing. |
c13182ef | 185 | If the user puts |
fea681da MK |
186 | .B SEV_LEVEL |
187 | with a format like | |
bdd915e2 | 188 | .PP |
fea681da MK |
189 | .RS |
190 | SEV_LEVEL=[description[:description[:...]]] | |
191 | .RE | |
bdd915e2 | 192 | .PP |
c13182ef | 193 | in the environment of the process before the first call to |
b5cc2ffb | 194 | .BR fmtmsg (), |
fea681da | 195 | where each description is of the form |
bdd915e2 | 196 | .PP |
fea681da MK |
197 | .RS |
198 | severity-keyword,level,printstring | |
199 | .RE | |
bdd915e2 | 200 | .PP |
fea681da | 201 | then |
31e9a9ec | 202 | .BR fmtmsg () |
fea681da | 203 | will also accept the indicated values for the level (in addition to |
9bc87ed0 | 204 | the standard levels 0\(en4), and use the indicated printstring when |
fea681da | 205 | such a level occurs. |
dd3568a1 | 206 | .PP |
fea681da | 207 | The severity-keyword part is not used by |
31e9a9ec | 208 | .BR fmtmsg () |
c13182ef MK |
209 | but it has to be present. |
210 | The level part is a string representation of a number. | |
fea681da | 211 | The numeric value must be a number greater than 4. |
c4bb193f | 212 | This value must be used in the severity argument of |
31e9a9ec | 213 | .BR fmtmsg () |
c13182ef MK |
214 | to select this class. |
215 | It is not possible to overwrite | |
216 | any of the predefined classes. | |
217 | The printstring | |
fea681da | 218 | is the string printed when a message of this class is processed by |
31e9a9ec | 219 | .BR fmtmsg (). |
c343e74c MK |
220 | .SH VERSIONS |
221 | .BR fmtmsg () | |
222 | is provided in glibc since version 2.1. | |
93a8236f | 223 | .SH ATTRIBUTES |
d751c37f MK |
224 | For an explanation of the terms used in this section, see |
225 | .BR attributes (7). | |
c466875e MK |
226 | .ad l |
227 | .nh | |
d751c37f MK |
228 | .TS |
229 | allbox; | |
c466875e | 230 | lb lb lbx |
d751c37f MK |
231 | l l l. |
232 | Interface Attribute Value | |
233 | T{ | |
234 | .BR fmtmsg () | |
235 | T} Thread safety T{ | |
b32feea5 MK |
236 | glibc\ >=\ 2.16: MT-Safe; |
237 | glibc\ <\ 2.16: MT-Unsafe | |
d751c37f MK |
238 | T} |
239 | .TE | |
c466875e MK |
240 | .hy |
241 | .ad | |
242 | .sp 1 | |
d751c37f | 243 | .PP |
93a8236f PH |
244 | Before glibc 2.16, the |
245 | .BR fmtmsg () | |
246 | function uses a static variable that is not protected, | |
247 | so it is not thread-safe. | |
847e0d88 | 248 | .PP |
93a8236f PH |
249 | Since glibc 2.16, |
250 | .\" Modified in commit 7724defcf8873116fe4efab256596861eef21a94 | |
251 | the | |
252 | .BR fmtmsg () | |
253 | function uses a lock to protect the static variable, so it is thread-safe. | |
3113c7f3 | 254 | .SH STANDARDS |
fea681da | 255 | The functions |
31e9a9ec | 256 | .BR fmtmsg () |
fea681da | 257 | and |
fb186734 | 258 | .BR addseverity (3), |
fea681da MK |
259 | and environment variables |
260 | .B MSGVERB | |
261 | and | |
262 | .B SEV_LEVEL | |
68e1685c | 263 | come from System V. |
847e0d88 | 264 | .PP |
fea681da | 265 | The function |
31e9a9ec | 266 | .BR fmtmsg () |
fea681da MK |
267 | and the environment variable |
268 | .B MSGVERB | |
43a72bdf | 269 | are described in POSIX.1-2001 and POSIX.1-2008. |
fea681da | 270 | .SH NOTES |
1f409d5d | 271 | System V and UnixWare man pages tell us that these functions |
fea681da MK |
272 | have been replaced by "pfmt() and addsev()" or by "pfmt(), |
273 | vpfmt(), lfmt(), and vlfmt()", and will be removed later. | |
a14af333 | 274 | .SH EXAMPLES |
207050fa | 275 | .EX |
fea681da | 276 | #include <stdio.h> |
af9c7ff2 | 277 | #include <stdlib.h> |
fea681da MK |
278 | #include <fmtmsg.h> |
279 | ||
c13182ef MK |
280 | int |
281 | main(void) | |
cf0a9ace MK |
282 | { |
283 | long class = MM_PRINT | MM_SOFT | MM_OPSYS | MM_RECOVER; | |
284 | int err; | |
a6bbb226 | 285 | |
29059a65 | 286 | err = fmtmsg(class, "util\-linux:mount", MM_ERROR, |
c13182ef | 287 | "unknown mount option", "See mount(8).", |
29059a65 | 288 | "util\-linux:mount:017"); |
d4949190 | 289 | switch (err) { |
fea681da | 290 | case MM_OK: |
cf0a9ace | 291 | break; |
fea681da | 292 | case MM_NOTOK: |
31a6818e | 293 | printf("Nothing printed\en"); |
cf0a9ace | 294 | break; |
fea681da | 295 | case MM_NOMSG: |
31a6818e | 296 | printf("Nothing printed to stderr\en"); |
cf0a9ace | 297 | break; |
fea681da | 298 | case MM_NOCON: |
31a6818e | 299 | printf("No console output\en"); |
cf0a9ace | 300 | break; |
fea681da | 301 | default: |
31a6818e | 302 | printf("Unknown error from fmtmsg()\en"); |
cf0a9ace | 303 | } |
5bc8c34c | 304 | exit(EXIT_SUCCESS); |
fea681da | 305 | } |
207050fa | 306 | .EE |
fea681da MK |
307 | .PP |
308 | The output should be: | |
207050fa MK |
309 | .PP |
310 | .in +4n | |
311 | .EX | |
312 | util\-linux:mount: ERROR: unknown mount option | |
313 | TO FIX: See mount(8). util\-linux:mount:017 | |
314 | .EE | |
315 | .in | |
316 | .PP | |
fea681da | 317 | and after |
207050fa MK |
318 | .PP |
319 | .in +4n | |
320 | .EX | |
321 | MSGVERB=text:action; export MSGVERB | |
322 | .EE | |
323 | .in | |
324 | .PP | |
fea681da | 325 | the output becomes: |
207050fa MK |
326 | .PP |
327 | .in +4n | |
328 | .EX | |
329 | unknown mount option | |
330 | TO FIX: See mount(8). | |
331 | .EE | |
332 | .in | |
47297adb | 333 | .SH SEE ALSO |
fea681da MK |
334 | .BR addseverity (3), |
335 | .BR perror (3) |