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