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