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