]>
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 | |
c343e74c | 13 | .TH FMTMSG 3 2008-06-14 "" "Linux Programmer's Manual" |
fea681da MK |
14 | .SH NAME |
15 | fmtmsg \- print formatted error messages | |
16 | .SH SYNOPSIS | |
17 | .nf | |
fea681da MK |
18 | .B #include <fmtmsg.h> |
19 | .sp | |
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. | |
36 | .LP | |
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. |
fea681da MK |
43 | .LP |
44 | The | |
45 | .I text | |
c4bb193f | 46 | argument describes the condition of the error. |
fea681da MK |
47 | .LP |
48 | The | |
49 | .I action | |
c4bb193f | 50 | argument describes possible steps to recover from the error. |
fea681da MK |
51 | If it is printed, it is prefixed by "TO FIX: ". |
52 | .LP | |
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 MK |
73 | are synonyms for |
74 | .IR "((char *) 0)" , | |
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. |
c13182ef | 83 | .br |
fea681da MK |
84 | .sp |
85 | The first value defines the output channel. | |
86 | .TP 12n | |
87 | .B MM_PRINT | |
88 | Output to | |
89 | .IR stderr . | |
90 | .TP | |
91 | .B MM_CONSOLE | |
92 | Output to the system console. | |
93 | .TP | |
94 | .B "MM_PRINT | MM_CONSOLE" | |
95 | Output to both. | |
96 | .PP | |
97 | The second value is the source of the error: | |
98 | .TP 12n | |
99 | .B MM_HARD | |
100 | A hardware error occurred. | |
101 | .TP | |
102 | .B MM_FIRM | |
103 | A firmware error occurred. | |
104 | .TP | |
105 | .B MM_SOFT | |
106 | A software error occurred. | |
107 | .PP | |
108 | The third value encodes the detector of the problem: | |
109 | .TP 12n | |
110 | .B MM_APPL | |
111 | It is detected by an application. | |
112 | .TP | |
113 | .B MM_UTIL | |
114 | It is detected by a utility. | |
115 | .TP | |
116 | .B MM_OPSYS | |
117 | It is detected by the operating system. | |
118 | .PP | |
119 | The fourth value shows the severity of the incident: | |
120 | .TP 12n | |
121 | .B MM_RECOVER | |
122 | It is a recoverable error. | |
123 | .TP | |
124 | .B MM_NRECOV | |
b28f6e56 | 125 | It is a nonrecoverable error. |
73d8cece | 126 | .SS The severity argument |
c13182ef MK |
127 | The |
128 | .I severity | |
c4bb193f | 129 | argument can take one of the following values: |
fea681da MK |
130 | .TP 12n |
131 | .B MM_NOSEV | |
132 | No severity is printed. | |
133 | .TP | |
134 | .B MM_HALT | |
135 | This value is printed as HALT. | |
136 | .TP | |
137 | .B MM_ERROR | |
138 | This value is printed as ERROR. | |
139 | .TP | |
140 | .B MM_WARNING | |
141 | This value is printed as WARNING. | |
142 | .TP | |
143 | .B MM_INFO | |
144 | This value is printed as INFO. | |
145 | .PP | |
c13182ef MK |
146 | The numeric values are between 0 and 4. |
147 | Using | |
fb186734 | 148 | .BR addseverity (3) |
fea681da MK |
149 | or the environment variable |
150 | .B SEV_LEVEL | |
151 | you can add more levels and strings to print. | |
47297adb | 152 | .SH RETURN VALUE |
2b2581ee MK |
153 | The function can return 4 values: |
154 | .TP 12n | |
155 | .B MM_OK | |
156 | Everything went smooth. | |
157 | .TP | |
158 | .B MM_NOTOK | |
159 | Complete failure. | |
160 | .TP | |
161 | .B MM_NOMSG | |
162 | Error writing to | |
163 | .IR stderr . | |
164 | .TP | |
165 | .B MM_NOCON | |
166 | Error writing to the console. | |
fea681da | 167 | .SH ENVIRONMENT |
c13182ef | 168 | The environment variable |
fea681da MK |
169 | .B MSGVERB |
170 | ("message verbosity") can be used to suppress parts of | |
171 | the output to | |
172 | .IR stderr . | |
173 | (It does not influence output to the console.) | |
174 | When this variable is defined, is non-NULL, and is a colon-separated | |
175 | list of valid keywords, then only the parts of the message corresponding | |
176 | to these keywords is printed. | |
177 | Valid keywords are "label", "severity", "text", "action" and "tag". | |
178 | .PP | |
179 | The environment variable | |
180 | .B SEV_LEVEL | |
181 | can be used to introduce new severity levels. | |
182 | By default, only the five severity levels described | |
c13182ef MK |
183 | above are available. |
184 | Any other numeric value would make | |
185 | .BR fmtmsg () | |
b5cc2ffb | 186 | print nothing. |
c13182ef | 187 | If the user puts |
fea681da MK |
188 | .B SEV_LEVEL |
189 | with a format like | |
190 | .sp | |
191 | .RS | |
192 | SEV_LEVEL=[description[:description[:...]]] | |
193 | .RE | |
194 | .sp | |
c13182ef | 195 | in the environment of the process before the first call to |
b5cc2ffb | 196 | .BR fmtmsg (), |
fea681da MK |
197 | where each description is of the form |
198 | .sp | |
199 | .RS | |
200 | severity-keyword,level,printstring | |
201 | .RE | |
202 | .sp | |
203 | then | |
31e9a9ec | 204 | .BR fmtmsg () |
fea681da MK |
205 | will also accept the indicated values for the level (in addition to |
206 | the standard levels 0-4), and use the indicated printstring when | |
207 | such a level occurs. | |
208 | .LP | |
209 | The severity-keyword part is not used by | |
31e9a9ec | 210 | .BR fmtmsg () |
c13182ef MK |
211 | but it has to be present. |
212 | The level part is a string representation of a number. | |
fea681da | 213 | The numeric value must be a number greater than 4. |
c4bb193f | 214 | This value must be used in the severity argument of |
31e9a9ec | 215 | .BR fmtmsg () |
c13182ef MK |
216 | to select this class. |
217 | It is not possible to overwrite | |
218 | any of the predefined classes. | |
219 | The printstring | |
fea681da | 220 | is the string printed when a message of this class is processed by |
31e9a9ec | 221 | .BR fmtmsg (). |
c343e74c MK |
222 | .SH VERSIONS |
223 | .BR fmtmsg () | |
224 | is provided in glibc since version 2.1. | |
47297adb | 225 | .SH CONFORMING TO |
fea681da | 226 | The functions |
31e9a9ec | 227 | .BR fmtmsg () |
fea681da | 228 | and |
fb186734 | 229 | .BR addseverity (3), |
fea681da MK |
230 | and environment variables |
231 | .B MSGVERB | |
232 | and | |
233 | .B SEV_LEVEL | |
68e1685c | 234 | come from System V. |
fea681da | 235 | The function |
31e9a9ec | 236 | .BR fmtmsg () |
fea681da MK |
237 | and the environment variable |
238 | .B MSGVERB | |
68e1685c | 239 | are described in POSIX.1-2001. |
fea681da | 240 | .SH NOTES |
1f409d5d | 241 | System V and UnixWare man pages tell us that these functions |
fea681da MK |
242 | have been replaced by "pfmt() and addsev()" or by "pfmt(), |
243 | vpfmt(), lfmt(), and vlfmt()", and will be removed later. | |
244 | .SH EXAMPLE | |
245 | .nf | |
246 | #include <stdio.h> | |
af9c7ff2 | 247 | #include <stdlib.h> |
fea681da MK |
248 | #include <fmtmsg.h> |
249 | ||
c13182ef MK |
250 | int |
251 | main(void) | |
cf0a9ace MK |
252 | { |
253 | long class = MM_PRINT | MM_SOFT | MM_OPSYS | MM_RECOVER; | |
254 | int err; | |
a6bbb226 | 255 | |
29059a65 | 256 | err = fmtmsg(class, "util\-linux:mount", MM_ERROR, |
c13182ef | 257 | "unknown mount option", "See mount(8).", |
29059a65 | 258 | "util\-linux:mount:017"); |
d4949190 | 259 | switch (err) { |
fea681da | 260 | case MM_OK: |
cf0a9ace | 261 | break; |
fea681da | 262 | case MM_NOTOK: |
31a6818e | 263 | printf("Nothing printed\en"); |
cf0a9ace | 264 | break; |
fea681da | 265 | case MM_NOMSG: |
31a6818e | 266 | printf("Nothing printed to stderr\en"); |
cf0a9ace | 267 | break; |
fea681da | 268 | case MM_NOCON: |
31a6818e | 269 | printf("No console output\en"); |
cf0a9ace | 270 | break; |
fea681da | 271 | default: |
31a6818e | 272 | printf("Unknown error from fmtmsg()\en"); |
cf0a9ace | 273 | } |
5bc8c34c | 274 | exit(EXIT_SUCCESS); |
fea681da MK |
275 | } |
276 | .fi | |
277 | .PP | |
278 | The output should be: | |
279 | .nf | |
cab87712 MK |
280 | |
281 | util\-linux:mount: ERROR: unknown mount option | |
282 | TO FIX: See mount(8). util\-linux:mount:017 | |
283 | ||
fea681da MK |
284 | .fi |
285 | and after | |
286 | .nf | |
cab87712 MK |
287 | |
288 | MSGVERB=text:action; export MSGVERB | |
289 | ||
fea681da MK |
290 | .fi |
291 | the output becomes: | |
292 | .nf | |
cab87712 MK |
293 | |
294 | unknown mount option | |
295 | TO FIX: See mount(8). | |
fea681da | 296 | .fi |
47297adb | 297 | .SH SEE ALSO |
fea681da MK |
298 | .BR addseverity (3), |
299 | .BR perror (3) |