| blob | ad389bfa34e70bcea7e642c0ca629ab17432ba43 |
1 '\" te
2 .\" Copyright 1989 AT&T Copyright (c) 2002, Sun Microsystems, Inc. All Rights Reserved
3 .\" 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.
4 .\" 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.
5 .\" 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]
6 .TH FMTMSG 3C "Jul 24, 2002"
7 .SH NAME
8 fmtmsg \- display a message on stderr or system console
9 .SH SYNOPSIS
10 .LP
11 .nf
12 #include <fmtmsg.h>
14 \fBint\fR \fBfmtmsg\fR(\fBlong\fR \fIclassification\fR, \fBconst char *\fR\fIlabel\fR, \fBint\fR \fIseverity\fR,
15 \fBconst char *\fR\fItext\fR, \fBconst char *\fR\fIaction\fR, \fBconst char *\fR\fItag\fR);
16 .fi
18 .SH DESCRIPTION
19 .sp
20 .LP
21 The \fBfmtmsg()\fR function writes a formatted message to \fBstderr\fR, to the
22 console, or to both, on a message's classification component. It can be used
23 instead of the traditional \fBprintf\fR(3C) interface to display messages to
24 \fBstderr\fR, and in conjunction with \fBgettxt\fR(3C), provides a simple
25 interface for producing language-independent applications.
26 .sp
27 .LP
28 A formatted message consists of up to five standard components ( \fIlabel\fR,
29 \fIseverity\fR, \fItext\fR, \fIaction\fR, and \fItag\fR) as described below.
30 The \fIclassification\fR component is not part of the standard message
31 displayed to the user, but rather defines the source of the message and directs
32 the display of the formatted message.
33 .sp
34 .ne 2
35 .na
36 \fB\fIclassification\fR\fR
37 .ad
38 .RS 18n
39 Contains identifiers from the following groups of major classifications and
40 subclassifications. Any one identifier from a subclass may be used in
41 combination by ORing the values together with a single identifier from a
42 different subclass. Two or more identifiers from the same subclass should not
43 be used together, with the exception of identifiers from the display subclass.
44 (Both display subclass identifiers may be used so that messages can be
45 displayed to both \fBstderr\fR and the system console).
46 .RS +4
47 .TP
48 .ie t \(bu
49 .el o
50 "Major classifications" identify the source of the condition. Identifiers are:
51 \fBMM_HARD\fR (hardware), \fBMM_SOFT\fR (software), and \fBMM_FIRM\fR
52 (firmware).
53 .RE
54 .RS +4
55 .TP
56 .ie t \(bu
57 .el o
58 "Message source subclassifications" identify the type of software in which the
59 problem is spotted. Identifiers are: \fBMM_APPL\fR (application), \fBMM_UTIL\fR
60 (utility), and \fBMM_OPSYS\fR (operating system).
61 .RE
62 .RS +4
63 .TP
64 .ie t \(bu
65 .el o
66 "Display subclassifications" indicate where the message is to be displayed.
67 Identifiers are: \fBMM_PRINT\fR to display the message on the standard error
68 stream, \fBMM_CONSOLE\fR to display the message on the system console. Neither,
69 either, or both identifiers may be used.
70 .RE
71 .RS +4
72 .TP
73 .ie t \(bu
74 .el o
75 "Status subclassifications" indicate whether the application will recover from
76 the condition. Identifiers are: \fBMM_RECOVER\fR (recoverable) and
77 \fBMM_NRECOV\fR (non-recoverable).
78 .RE
79 .RS +4
80 .TP
81 .ie t \(bu
82 .el o
83 An additional identifier, \fBMM_NULLMC\fR, indicates that no classification
84 component is supplied for the message.
85 .RE
86 .RE
88 .sp
89 .ne 2
90 .na
91 \fB\fIlabel\fR\fR
92 .ad
93 .RS 18n
94 Identifies the source of the message. The format of this component is two
95 fields separated by a colon. The first field is up to 10 characters long; the
96 second is up to 14 characters. Suggested usage is that \fIlabel\fR identifies
97 the package in which the application resides as well as the program or
98 application name. For example, the \fIlabel\fR \fBUX:cat\fR indicates the
99 \fBUNIX\fR System V package and the \fBcat\fR(1) utility.
100 .RE
102 .sp
103 .ne 2
104 .na
105 \fB\fIseverity\fR\fR
106 .ad
107 .RS 18n
108 Indicates the seriousness of the condition. Identifiers for the standard levels
109 of \fIseverity\fR are:
110 .RS +4
111 .TP
112 .ie t \(bu
113 .el o
114 \fBMM_HALT\fR indicates that the application has encountered a severe fault and
115 is halting. Produces the print string \fBHALT\fR.
116 .RE
117 .RS +4
118 .TP
119 .ie t \(bu
120 .el o
121 \fBMM_ERROR\fR indicates that the application has detected a fault. Produces
122 the print string \fBERROR\fR.
123 .RE
124 .RS +4
125 .TP
126 .ie t \(bu
127 .el o
128 \fBMM_WARNING\fR indicates a condition out of the ordinary that might be a
129 problem and should be watched. Produces the print string \fBWARNING\fR.
130 .RE
131 .RS +4
132 .TP
133 .ie t \(bu
134 .el o
135 \fBMM_INFO\fR provides information about a condition that is not in error.
136 Produces the print string \fBINFO\fR.
137 .RE
138 .RS +4
139 .TP
140 .ie t \(bu
141 .el o
142 \fBMM_NOSEV\fR indicates that no severity level is supplied for the message.
143 .RE
144 Other severity levels may be added by using the \fBaddseverity()\fR routine.
145 .RE
147 .sp
148 .ne 2
149 .na
150 \fB\fItext\fR\fR
151 .ad
152 .RS 18n
153 Describes the condition that produced the message. The \fItext\fR string is not
154 limited to a specific size.
155 .RE
157 .sp
158 .ne 2
159 .na
160 \fB\fIaction\fR\fR
161 .ad
162 .RS 18n
163 Describes the first step to be taken in the error recovery process.
164 \fBfmtmsg()\fR precedes each action string with the prefix: \fBTO\fRFIX\fB:.\fR
165 The \fIaction\fR string is not limited to a specific size.
166 .RE
168 .sp
169 .ne 2
170 .na
171 \fB\fItag\fR\fR
172 .ad
173 .RS 18n
174 An identifier which references on-line documentation for the message. Suggested
175 usage is that \fItag\fR includes the \fIlabel\fR and a unique identifying
176 number. A sample \fItag\fR is \fBUX:cat:146\fR.
177 .RE
179 .SS "Environment Variables"
180 .sp
181 .LP
182 The \fBMSGVERB\fR and \fBSEV_LEVEL\fR environment variables control the
183 behavior of \fBfmtmsg()\fR as follows:
184 .sp
185 .ne 2
186 .na
187 \fB\fBMSGVERB\fR\fR
188 .ad
189 .RS 13n
190 This variable determines which message components \fBfmtmsg()\fR selects when
191 writing messages to \fBstderr\fR. Its value is a colon-separated list of
192 optional keywords and can be set as follows:
193 .sp
194 .in +2
195 .nf
196 \fBMSGVERB=\fR[\fIkeyword\fR[\fB:\fR\fIkeyword\fR[\fB:\fR\|.\|.\|.]]]
197 \fBexport MSGVERB\fR
198 .fi
199 .in -2
201 Valid \fIkeywords\fR are: \fBlabel\fR, \fBseverity\fR, \fBtext\fR,
202 \fBaction\fR, and \fBtag\fR. If \fBMSGVERB\fR contains a keyword for a
203 component and the component's value is not the component's null value,
204 \fBfmtmsg()\fR includes that component in the message when writing the message
205 to \fBstderr\fR. If \fBMSGVERB\fR does not include a keyword for a message
206 component, that component is not included in the display of the message. The
207 keywords may appear in any order. If \fBMSGVERB\fR is not defined, if its value
208 is the null string, if its value is not of the correct format, or if it
209 contains keywords other than the valid ones listed above, \fBfmtmsg()\fR
210 selects all components.
211 .sp
212 The first time \fBfmtmsg()\fR is called, it examines \fBMSGVERB\fR to determine
213 which message components are to be selected when generating a message to write
214 to the standard error stream, \fBstderr\fR. The values accepted on the initial
215 call are saved for future calls.
216 .sp
217 The \fBMSGVERB\fR environment variable affects only those components that are
218 selected for display to the standard error stream. All message components are
219 included in console messages.
220 .RE
222 .sp
223 .ne 2
224 .na
225 \fB\fBSEV_LEVEL\fR\fR
226 .ad
227 .RS 13n
228 This variable defines severity levels and associates print strings with them
229 for use by \fBfmtmsg()\fR. The standard severity levels listed below cannot be
230 modified. Additional severity levels can also be defined, redefined, and
231 removed using \fBaddseverity()\fR (see \fBaddseverity\fR(3C)). If the same
232 severity level is defined by both \fBSEV_LEVEL\fR and \fBaddseverity()\fR, the
233 definition by \fBaddseverity()\fR takes precedence.
234 .sp
235 .ne 2
236 .na
237 \fB0\fR
238 .ad
239 .RS 5n
240 (no severity is used)
241 .RE
243 .sp
244 .ne 2
245 .na
246 \fB1\fR
247 .ad
248 .RS 5n
249 \fBHALT\fR
250 .RE
252 .sp
253 .ne 2
254 .na
255 \fB2\fR
256 .ad
257 .RS 5n
258 \fBERROR\fR
259 .RE
261 .sp
262 .ne 2
263 .na
264 \fB3\fR
265 .ad
266 .RS 5n
267 \fBWARNING\fR
268 .RE
270 .sp
271 .ne 2
272 .na
273 \fB4\fR
274 .ad
275 .RS 5n
276 \fBINFO\fR
277 .RE
279 The \fBSEV_LEVEL\fR variable can be set as follows:
280 .sp
281 .in +2
282 .nf
283 \fBSEV_LEVEL=\fR[\fIdescription\fR[\fB:\fR\fIdescription\fR[\fB:\fR\|.\|.\|.]]]
284 \fBexport SEV_LEVEL\fR
285 .fi
286 .in -2
288 where \fIdescription\fR is a comma-separated list containing three fields:
289 .sp
290 \fIdescription\fR=\fIseverity_keyword\fR,\fIlevel\fR,\fIprintstring\fR
291 .sp
292 The \fIseverity_keyword\fR field is a character string that is used as the
293 keyword on the \fB\fR\fB-s\fR\fB \fR\fIseverity\fR option to the
294 \fBfmtmsg\fR(1) utility. (This field is not used by the \fBfmtmsg()\fR
295 function.)
296 .sp
297 The \fIlevel\fR field is a character string that evaluates to a positive
298 integer (other than 0, 1, 2, 3, or 4, which are reserved for the standard
299 severity levels). If the keyword \fIseverity_keyword\fR is used, \fIlevel\fR is
300 the severity value passed on to the \fBfmtmsg()\fR function.
301 .sp
302 The \fIprintstring\fR field is the character string used by \fBfmtmsg()\fR in
303 the standard message format whenever the severity value \fIlevel\fR is used.
304 .sp
305 If a \fIdescription\fR in the colon list is not a three-field comma list, or if
306 the second field of a comma list does not evaluate to a positive integer, that
307 \fIdescription\fR in the colon list is ignored.
308 .sp
309 The first time \fBfmtmsg()\fR is called, it examines the \fBSEV_LEVEL\fR
310 environment variable, if defined, to determine whether the environment expands
311 the levels of severity beyond the five standard levels and those defined using
312 \fBaddseverity()\fR. The values accepted on the initial call are saved for
313 future calls.
314 .RE
316 .SS "Use in Applications"
317 .sp
318 .LP
319 One or more message components may be systematically omitted from messages
320 generated by an application by using the null value of the argument for that
321 component.
322 .sp
323 .LP
324 The table below indicates the null values and identifiers for \fBfmtmsg()\fR
325 arguments.
326 .sp
328 .sp
329 .TS
330 box;
331 l l l l
332 l l l l .
333 Argument Type Null-Value Identifier
334 \fIlabel\fR \fBchar*\fR \fB(char*) NULL\fR \fBMM_NULLLBL\fR
335 \fIseverity\fR \fBint\fR \fB0\fR \fBMM_NULLSEV\fR
336 \fIclass\fR \fBlong\fR \fB0L\fR \fBMM_NULLMC\fR
337 \fItext\fR \fBchar*\fR \fB(char*) NULL\fR \fBMM_NULLTXT\fR
338 \fIaction\fR \fBchar*\fR \fB(char*) NULL\fR \fBMM_NULLACT\fR
339 \fItag\fR \fBchar*\fR \fB(char*) NULL\fR \fBMM_NULLTAG\fR
340 .TE
342 .sp
343 .LP
344 Another means of systematically omitting a component is by omitting the
345 component keyword(s) when defining the \fBMSGVERB\fR environment variable (see
346 the \fBEnvironment Variables\fR section above).
347 .SH RETURN VALUES
348 .sp
349 .LP
350 The \fBfmtmsg()\fR returns the following values:
351 .sp
352 .ne 2
353 .na
354 \fB\fBMM_OK\fR\fR
355 .ad
356 .RS 12n
357 The function succeeded.
358 .RE
360 .sp
361 .ne 2
362 .na
363 \fB\fBMM_NOTOK\fR\fR
364 .ad
365 .RS 12n
366 The function failed completely.
367 .RE
369 .sp
370 .ne 2
371 .na
372 \fB\fBMM_NOMSG\fR\fR
373 .ad
374 .RS 12n
375 The function was unable to generate a message on the standard error stream, but
376 otherwise succeeded.
377 .RE
379 .sp
380 .ne 2
381 .na
382 \fB\fBMM_NOCON\fR\fR
383 .ad
384 .RS 12n
385 The function was unable to generate a console message, but otherwise succeeded.
386 .RE
388 .SH EXAMPLES
389 .LP
390 \fBExample 1 \fRThe following example of \fBfmtmsg()\fR:
391 .sp
392 .in +2
393 .nf
394 fmtmsg(MM_PRINT, "UX:cat", MM_ERROR, "invalid syntax",
395 "refer to manual", "UX:cat:001")
396 .fi
397 .in -2
399 .sp
400 .LP
401 produces a complete message in the standard message format:
403 .sp
404 .in +2
405 .nf
406 UX:cat: ERROR: invalid syntax
407 TO FIX: refer to manual UX:cat:001
408 .fi
409 .in -2
411 .LP
412 \fBExample 2 \fRWhen the environment variable \fBMSGVERB\fR is set as follows:
413 .sp
414 .in +2
415 .nf
416 MSGVERB=severity:text:action
417 .fi
418 .in -2
420 .sp
421 .LP
422 and the Example 1 is used, \fBfmtmsg()\fR produces:
424 .sp
425 .in +2
426 .nf
427 ERROR: invalid syntax
428 TO FIX: refer to manual
429 .fi
430 .in -2
432 .LP
433 \fBExample 3 \fRWhen the environment variable \fBSEV_LEVEL\fR is set as
434 follows:
435 .sp
436 .in +2
437 .nf
438 SEV_LEVEL=note,5,NOTE
439 .fi
440 .in -2
442 .sp
443 .LP
444 the following call to \fBfmtmsg()\fR
446 .sp
447 .in +2
448 .nf
449 fmtmsg(MM_UTIL | MM_PRINT, "UX:cat", 5, "invalid syntax",
450 "refer to manual", "UX:cat:001")
451 .fi
452 .in -2
454 .sp
455 .LP
456 produces
458 .sp
459 .in +2
460 .nf
461 UX:cat: NOTE: invalid syntax
462 TO FIX: refer to manual UX:cat:001
463 .fi
464 .in -2
466 .SH ATTRIBUTES
467 .sp
468 .LP
469 See \fBattributes\fR(5) for descriptions of the following attributes:
470 .sp
472 .sp
473 .TS
474 box;
475 c | c
476 l | l .
477 ATTRIBUTE TYPE ATTRIBUTE VALUE
478 _
479 Interface Stability Standard
480 _
481 MT-Level Safe
482 .TE
484 .SH SEE ALSO
485 .sp
486 .LP
487 \fBfmtmsg\fR(1), \fBaddseverity\fR(3C), \fBgettxt\fR(3C), \fBprintf\fR(3C),
488 \fBattributes\fR(5), \fBstandards\fR(5)