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