| blob | 4dc5a9f1a7e9a23d1fc0c291ce32508301bb5417 |
1 '\" te
2 .\" Copyright 1989 AT&T Copyright (c) 1994, Sun Microsystems, Inc. All Rights Reserved
3 .\" 2003, Sun Microsystems, Inc. All Rights Reserved
4 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
5 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
6 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
7 .TH FMTMSG 1 "Jul 20, 1994"
8 .SH NAME
9 fmtmsg \- display a message on stderr or system console
10 .SH SYNOPSIS
11 .LP
12 .nf
13 \fBfmtmsg\fR [\fB-c\fR \fIclass\fR] [\fB-u\fR \fIsubclass\fR] [\fB-l\fR \fIlabel\fR] [\fB-s\fR \fIseverity\fR]
14 [\fB-t\fR \fItag\fR] [\fB-a\fR \fIaction\fR] \fItext\fR
15 .fi
17 .SH DESCRIPTION
18 .sp
19 .LP
20 Based on a message's classification component, the \fBfmtmsg\fR utility either
21 writes a formatted message to \fBstderr\fR or writes a formatted message to the
22 console.
23 .sp
24 .LP
25 A formatted message consists of up to five standard components (see environment
26 variable \fBMSGVERB\fR in the ENVIRONMENT VARIABLES section of this page). The
27 classification and subclass components are not displayed as part of the
28 standard message, but rather define the source of the message and direct the
29 display of the formatted message.
30 .SH OPTIONS
31 .sp
32 .LP
33 The following options are supported:
34 .sp
35 .ne 2
36 .na
37 \fB\fB-c\fR \fIclass\fR \fR
38 .ad
39 .RS 16n
40 Describes the source of the message. Valid keywords are:
41 .sp
42 .ne 2
43 .na
44 \fB\fBhard\fR \fR
45 .ad
46 .RS 9n
47 The source of the condition is hardware.
48 .RE
50 .sp
51 .ne 2
52 .na
53 \fB\fBsoft\fR \fR
54 .ad
55 .RS 9n
56 The source of the condition is software.
57 .RE
59 .sp
60 .ne 2
61 .na
62 \fB\fBfirm\fR \fR
63 .ad
64 .RS 9n
65 The source of the condition is firmware.
66 .RE
68 .RE
70 .sp
71 .ne 2
72 .na
73 \fB\fB-u\fR \fIsubclass\fR \fR
74 .ad
75 .RS 16n
76 A list of keywords (separated by commas) that further defines the message and
77 directs the display of the message. Valid keywords are:
78 .sp
79 .ne 2
80 .na
81 \fB\fBappl\fR \fR
82 .ad
83 .RS 12n
84 The condition originated in an application. This keyword should not be used in
85 combination with either \fButil\fR or \fBopsys\fR.
86 .RE
88 .sp
89 .ne 2
90 .na
91 \fB\fButil\fR \fR
92 .ad
93 .RS 12n
94 The condition originated in a utility. This keyword should not be used in
95 combination with either \fBappl\fR or \fBopsys\fR.
96 .RE
98 .sp
99 .ne 2
100 .na
101 \fB\fBopsys\fR \fR
102 .ad
103 .RS 12n
104 The message originated in the kernel. This keyword should not be used in
105 combination with either \fBappl\fR or \fButil\fR.
106 .RE
108 .sp
109 .ne 2
110 .na
111 \fB\fBrecov\fR \fR
112 .ad
113 .RS 12n
114 The application will recover from the condition. This keyword should not be
115 used in combination with \fBnrecov\fR.
116 .RE
118 .sp
119 .ne 2
120 .na
121 \fB\fBnrecov\fR \fR
122 .ad
123 .RS 12n
124 The application will not recover from the condition. This keyword should not be
125 used in combination with \fBrecov\fR.
126 .RE
128 .sp
129 .ne 2
130 .na
131 \fB\fBprint\fR \fR
132 .ad
133 .RS 12n
134 Print the message to the standard error stream \fBstderr\fR.
135 .RE
137 .sp
138 .ne 2
139 .na
140 \fB\fBconsole\fR \fR
141 .ad
142 .RS 12n
143 Write the message to the system console. \fBprint\fR, \fBconsole\fR, or both
144 may be used.
145 .RE
147 .RE
149 .sp
150 .ne 2
151 .na
152 \fB\fB-l\fR \fIlabel\fR \fR
153 .ad
154 .RS 16n
155 Identifies the source of the message.
156 .RE
158 .sp
159 .ne 2
160 .na
161 \fB\fB-s\fR \fIseverity\fR \fR
162 .ad
163 .RS 16n
164 Indicates the seriousness of the error. The keywords and definitions of the
165 standard levels of \fIseverity\fR are:
166 .sp
167 .ne 2
168 .na
169 \fB\fBhalt\fR \fR
170 .ad
171 .RS 9n
172 The application has encountered a severe fault and is halting.
173 .RE
175 .sp
176 .ne 2
177 .na
178 \fB\fBerror\fR\fR
179 .ad
180 .RS 9n
181 The application has detected a fault.
182 .RE
184 .sp
185 .ne 2
186 .na
187 \fB\fBwarn\fR\fR
188 .ad
189 .RS 9n
190 The application has detected a condition that is out of the ordinary and might
191 be a problem.
192 .RE
194 .sp
195 .ne 2
196 .na
197 \fB\fBinfo\fR \fR
198 .ad
199 .RS 9n
200 The application is providing information about a condition that is not in
201 error.
202 .RE
204 .RE
206 .sp
207 .ne 2
208 .na
209 \fB\fB-t\fR \fItag\fR \fR
210 .ad
211 .RS 16n
212 The string containing an identifier for the message.
213 .RE
215 .sp
216 .ne 2
217 .na
218 \fB\fB-a\fR \fIaction\fR \fR
219 .ad
220 .RS 16n
221 A text string describing the first step in the error recovery process. This
222 string must be written so that the entire \fIaction\fR argument is interpreted
223 as a single argument. \fBfmtmsg\fR precedes each action string with the \fBTO
224 FIX:\fR prefix.
225 .RE
227 .sp
228 .ne 2
229 .na
230 \fB\fItext\fR \fR
231 .ad
232 .RS 16n
233 A text string describing the condition. Must be written so that the entire
234 \fItext\fR argument is interpreted as a single argument.
235 .RE
237 .SH EXAMPLES
238 .LP
239 \fBExample 1 \fRStandard message format
240 .sp
241 .LP
242 The following example of \fBfmtmsg\fR produces a complete message in the
243 standard message format and displays it to the standard error stream.
245 .sp
246 .in +2
247 .nf
248 example% \fBfmtmsg -c soft -u recov,print,appl -l UX:cat \e
249 -s error -t UX:cat:001 -a "refer to manual" "invalid syntax"\fR
250 .fi
251 .in -2
252 .sp
254 .sp
255 .LP
256 produces:
258 .sp
259 .in +2
260 .nf
261 UX:cat: ERROR: invalid syntax
262 TO FIX: refer to manual UX:cat:138
263 .fi
264 .in -2
265 .sp
267 .LP
268 \fBExample 2 \fRUsing MSGVERB
269 .sp
270 .LP
271 When the environment variable \fBMSGVERB\fR is set as follows:
273 .sp
274 .in +2
275 .nf
276 \fBMSGVERB=severity:text:action\fR
277 .fi
278 .in -2
279 .sp
281 .sp
282 .LP
283 and Example 1 is used, \fBfmtmsg\fR produces:
285 .sp
286 .in +2
287 .nf
288 ERROR: invalid syntax
289 TO FIX: refer to manual
290 .fi
291 .in -2
292 .sp
294 .LP
295 \fBExample 3 \fRUsing SEV_LEVEL
296 .sp
297 .LP
298 When the environment variable \fBSEV_LEVEL\fR is set as follows:
300 .sp
301 .in +2
302 .nf
303 \fBSEV_LEVEL=note,5,NOTE\fR
304 .fi
305 .in -2
306 .sp
308 .sp
309 .LP
310 the following \fBfmtmsg\fR command:
312 .sp
313 .in +2
314 .nf
315 example% \fBfmtmsg -c soft -u print -l UX:cat -s note \e
316 -a "refer to manual" "invalid syntax"\fR
317 .fi
318 .in -2
319 .sp
321 .sp
322 .LP
323 produces:
325 .sp
326 .in +2
327 .nf
328 NOTE: invalid syntax
329 TO FIX: refer to manual
330 .fi
331 .in -2
332 .sp
334 .sp
335 .LP
336 and displays the message on \fBstderr\fR.
338 .SH ENVIRONMENT VARIABLES
339 .sp
340 .LP
341 The environment variables \fBMSGVERB\fR and \fBSEV_LEVEL\fR control the
342 behavior of \fBfmtmsg\fR. \fBMSGVERB\fR is set by the administrator in the
343 \fB/etc/profile\fR for the system. Users can override the value of
344 \fBMSGVERB\fR set by the system by resetting \fBMSGVERB\fR in their own
345 \fB\&.profile\fR files or by changing the value in their current shell session.
346 \fBSEV_LEVEL\fR can be used in shell scripts.
347 .sp
348 .LP
349 \fBMSGVERB\fR tells \fBfmtmsg\fR which message components to select when
350 writing messages to \fBstderr\fR. The value of \fBMSGVERB\fR is a
351 colon-separated list of optional keywords. \fBMSGVERB\fR can be set as follows:
352 .sp
353 .in +2
354 .nf
355 \fBMSGVERB=[\fIkeyword\fR[:\fIkeyword\fR[:...]]]
356 export MSGVERB\fR
357 .fi
358 .in -2
359 .sp
361 .sp
362 .LP
363 Valid \fIkeyword\fRs are: \fBlabel\fR, \fBseverity\fR, \fBtext\fR,
364 \fBaction\fR, and \fBtag\fR. If \fBMSGVERB\fR contains a keyword for a
365 component and the component's value is not the component's null value,
366 \fBfmtmsg\fR includes that component in the message when writing the message to
367 \fBstderr\fR. If \fBMSGVERB\fR does not include a keyword for a message
368 component, that component is not included in the display of the message. The
369 keywords may appear in any order. If \fBMSGVERB\fR is not defined, if its value
370 is the null string, if its value is not of the correct format, or if it
371 contains keywords other than the valid ones listed above, \fBfmtmsg\fR selects
372 all components.
373 .sp
374 .LP
375 \fBMSGVERB\fR affects only which message components are selected for display.
376 All message components are included in console messages.
377 .sp
378 .LP
379 \fBSEV_LEVEL\fR defines severity levels and associates print strings with them
380 for use by \fBfmtmsg\fR. The standard severity levels shown below cannot be
381 modified. Additional severity levels can be defined, redefined, and removed.
382 .sp
383 .ne 2
384 .na
385 \fB\fB0\fR \fR
386 .ad
387 .RS 6n
388 (no severity is used)
389 .RE
391 .sp
392 .ne 2
393 .na
394 \fB\fB1\fR \fR
395 .ad
396 .RS 6n
397 \fBHALT\fR
398 .RE
400 .sp
401 .ne 2
402 .na
403 \fB\fB2\fR \fR
404 .ad
405 .RS 6n
406 \fBERROR\fR
407 .RE
409 .sp
410 .ne 2
411 .na
412 \fB\fB3\fR \fR
413 .ad
414 .RS 6n
415 \fBWARNING\fR
416 .RE
418 .sp
419 .ne 2
420 .na
421 \fB\fB4\fR \fR
422 .ad
423 .RS 6n
424 \fBINFO\fR
425 .RE
427 .sp
428 .LP
429 \fBSEV_LEVEL\fR is set as follows:
430 .sp
431 .LP
432 \fIdescription\fR is a comma-separated list containing three fields:
433 .sp
434 .in +2
435 .nf
436 \fBSEV_LEVEL= [\fIdescription\fR[:\fIdescription\fR[:...]]]
437 export SEV_LEVEL\fR
438 .fi
439 .in -2
440 .sp
442 .sp
443 .LP
444 \fIdescription\fR=\fIseverity_keyword\fR, \fIlevel\fR, \fIprintstring\fR
445 .sp
446 .LP
447 \fIseverity_keyword\fR is a character string used as the keyword with the
448 \fB-s\fR \fIseverity\fR option to \fBfmtmsg\fR.
449 .sp
450 .LP
451 \fIlevel\fR is a character string that evaluates to a positive integer (other
452 than \fB0\fR, \fB1\fR, \fB2\fR, \fB3\fR, or \fB4\fR, which are reserved for the
453 standard severity levels). If the keyword \fIseverity_keyword\fR is used,
454 \fIlevel\fR is the severity value passed on to \fBfmtmsg\fR(3C).
455 .sp
456 .LP
457 \fIprintstring\fR is the character string used by \fBfmtmsg\fR in the standard
458 message format whenever the severity value \fIlevel\fR is used.
459 .sp
460 .LP
461 If \fBSEV_LEVEL\fR is not defined, or if its value is null, no severity levels
462 other than the defaults are available. If a \fIdescription\fR in the colon
463 separated list is not a comma separated list containing three fields, or if the
464 second field of a comma separated list does not evaluate to a positive integer,
465 that \fIdescription\fR in the colon separated list is ignored.
466 .SH EXIT STATUS
467 .sp
468 .LP
469 The following exit values are returned:
470 .sp
471 .ne 2
472 .na
473 \fB\fB0\fR \fR
474 .ad
475 .RS 7n
476 All the requested functions were executed successfully.
477 .RE
479 .sp
480 .ne 2
481 .na
482 \fB\fB1\fR \fR
483 .ad
484 .RS 7n
485 The command contains a syntax error, an invalid option, or an invalid argument
486 to an option.
487 .RE
489 .sp
490 .ne 2
491 .na
492 \fB\fB2\fR \fR
493 .ad
494 .RS 7n
495 The function executed with partial success, however the message was not
496 displayed on \fBstderr\fR.
497 .RE
499 .sp
500 .ne 2
501 .na
502 \fB\fB4\fR \fR
503 .ad
504 .RS 7n
505 The function executed with partial success; however, the message was not
506 displayed on the system console.
507 .RE
509 .sp
510 .ne 2
511 .na
512 \fB\fB32\fR \fR
513 .ad
514 .RS 7n
515 No requested functions were executed successfully.
516 .RE
518 .SH SEE ALSO
519 .sp
520 .LP
521 \fBaddseverity\fR(3C), \fBfmtmsg\fR(3C), \fBattributes\fR(5)