1fmtmsg(3C) Standard C Library Functions fmtmsg(3C)
2
6 fmtmsg - display a message on stderr or system console
7
9 #include <fmtmsg.h>
10 int fmtmsg(long classification, const char *label, int severity,
12 const char *text, const char *action, const char *tag);
13
16 The fmtmsg() function writes a formatted message to stderr, to the con‐
17 sole, or to both, on a message's classification component. It can be
18 used instead of the traditional printf(3C) interface to display mes‐
19 sages to stderr, and in conjunction with gettxt(3C), provides a simple
20 interface for producing language-independent applications.
21 A formatted message consists of up to five standard components ( label,
24 severity, text, action, and tag) as described below. The classification
25 component is not part of the standard message displayed to the user,
26 but rather defines the source of the message and directs the display of
27 the formatted message.
28 classification Contains identifiers from the following groups of
30 major classifications and subclassifications. Any one
31 identifier from a subclass may be used in combination
32 by ORing the values together with a single identifier
33 from a different subclass. Two or more identifiers
34 from the same subclass should not be used together,
35 with the exception of identifiers from the display
36 subclass. (Both display subclass identifiers may be
37 used so that messages can be displayed to both stderr
38 and the system console).
39 o "Major classifications" identify the
41 source of the condition. Identifiers are:
42 MM_HARD (hardware), MM_SOFT (software),
43 and MM_FIRM (firmware).
44 o "Message source subclassifications" iden‐
46 tify the type of software in which the
47 problem is spotted. Identifiers are:
48 MM_APPL (application), MM_UTIL (utility),
49 and MM_OPSYS (operating system).
50 o "Display subclassifications" indicate
52 where the message is to be displayed.
53 Identifiers are: MM_PRINT to display the
54 message on the standard error stream,
55 MM_CONSOLE to display the message on the
56 system console. Neither, either, or both
57 identifiers may be used.
58 o "Status subclassifications" indicate
60 whether the application will recover from
61 the condition. Identifiers are: MM_RECOVER
62 (recoverable) and MM_NRECOV (non-recover‐
63 able).
64 o An additional identifier, MM_NULLMC, indi‐
66 cates that no classification component is
67 supplied for the message.
68 label Identifies the source of the message. The format of
71 this component is two fields separated by a colon.
72 The first field is up to 10 characters long; the sec‐
73 ond is up to 14 characters. Suggested usage is that
74 label identifies the package in which the application
75 resides as well as the program or application name.
76 For example, the label UX:cat indicates the UNIX Sys‐
77 tem V package and the cat(1) utility.
78 severity Indicates the seriousness of the condition. Identi‐
81 fiers for the standard levels of severity are:
82 o MM_HALT indicates that the application has
84 encountered a severe fault and is halting.
85 Produces the print string HALT.
86 o MM_ERROR indicates that the application
88 has detected a fault. Produces the print
89 string ERROR.
90 o MM_WARNING indicates a condition out of
92 the ordinary that might be a problem and
93 should be watched. Produces the print
94 string WARNING.
95 o MM_INFO provides information about a con‐
97 dition that is not in error. Produces the
98 print string INFO.
99 o MM_NOSEV indicates that no severity level
101 is supplied for the message.
102 Other severity levels may be added by using the add‐
103 severity() routine.
104 text Describes the condition that produced the message.
107 The text string is not limited to a specific size.
108 action Describes the first step to be taken in the error
111 recovery process. fmtmsg() precedes each action
112 string with the prefix: TOFIX:. The action string is
113 not limited to a specific size.
114 tag An identifier which references on-line documentation
117 for the message. Suggested usage is that tag includes
118 the label and a unique identifying number. A sample
119 tag is UX:cat:146.
120 Environment Variables
123 The MSGVERB and SEV_LEVEL environment variables control the behavior of
124 fmtmsg() as follows:
125 MSGVERB This variable determines which message components fmtmsg()
127 selects when writing messages to stderr. Its value is a
128 colon-separated list of optional keywords and can be set
129 as follows:
130 MSGVERB=[keyword[:keyword[:...]]]
132 export MSGVERB
133 Valid keywords are: label, severity, text, action, and
135 tag. If MSGVERB contains a keyword for a component and the
136 component's value is not the component's null value,
137 fmtmsg() includes that component in the message when writ‐
138 ing the message to stderr. If MSGVERB does not include a
139 keyword for a message component, that component is not
140 included in the display of the message. The keywords may
141 appear in any order. If MSGVERB is not defined, if its
142 value is the null string, if its value is not of the cor‐
143 rect format, or if it contains keywords other than the
144 valid ones listed above, fmtmsg() selects all components.
145 The first time fmtmsg() is called, it examines MSGVERB to
147 determine which message components are to be selected when
148 generating a message to write to the standard error
149 stream, stderr. The values accepted on the initial call
150 are saved for future calls.
151 The MSGVERB environment variable affects only those compo‐
153 nents that are selected for display to the standard error
154 stream. All message components are included in console
155 messages.
156 SEV_LEVEL This variable defines severity levels and associates print
159 strings with them for use by fmtmsg(). The standard sever‐
160 ity levels listed below cannot be modified. Additional
161 severity levels can also be defined, redefined, and
162 removed using addseverity() (see addseverity(3C)). If the
163 same severity level is defined by both SEV_LEVEL and add‐
164 severity(), the definition by addseverity() takes prece‐
165 dence.
166 0 (no severity is used)
168 1 HALT
171 2 ERROR
174 3 WARNING
177 4 INFO
180 The SEV_LEVEL variable can be set as follows:
182 SEV_LEVEL=[description[:description[:...]]]
184 export SEV_LEVEL
185 where description is a comma-separated list containing
187 three fields:
188 description=severity_keyword,level,printstring
190 The severity_keyword field is a character string that is
192 used as the keyword on the -s severity option to the
193 fmtmsg(1) utility. (This field is not used by the fmtmsg()
194 function.)
195 The level field is a character string that evaluates to a
197 positive integer (other than 0, 1, 2, 3, or 4, which are
198 reserved for the standard severity levels). If the keyword
199 severity_keyword is used, level is the severity value
200 passed on to the fmtmsg() function.
201 The printstring field is the character string used by
203 fmtmsg() in the standard message format whenever the
204 severity value level is used.
205 If a description in the colon list is not a three-field
207 comma list, or if the second field of a comma list does
208 not evaluate to a positive integer, that description in
209 the colon list is ignored.
210 The first time fmtmsg() is called, it examines the
212 SEV_LEVEL environment variable, if defined, to determine
213 whether the environment expands the levels of severity
214 beyond the five standard levels and those defined using
215 addseverity(). The values accepted on the initial call are
216 saved for future calls.
217 Use in Applications
220 One or more message components may be systematically omitted from mes‐
221 sages generated by an application by using the null value of the argu‐
222 ment for that component.
223 The table below indicates the null values and identifiers for fmtmsg()
226 arguments.
227 ┌─────────────────────────────────────────────────────────────────┐
232 │Argument Type Null-Value Identifier │
233 │label char* (char*) NULL MM_NULLLBL │
234 │severity int 0 MM_NULLSEV │
235 │class long 0L MM_NULLMC │
236 │text char* (char*) NULL MM_NULLTXT │
237 │action char* (char*) NULL MM_NULLACT │
238 │tag char* (char*) NULL MM_NULLTAG │
239 └─────────────────────────────────────────────────────────────────┘
240 Another means of systematically omitting a component is by omitting the
243 component keyword(s) when defining the MSGVERB environment variable
244 (see the Environment Variables section above).
245
247 The fmtmsg() returns the following values:
248 MM_OK The function succeeded.
250 MM_NOTOK The function failed completely.
253 MM_NOMSG The function was unable to generate a message on the stan‐
256 dard error stream, but otherwise succeeded.
257 MM_NOCON The function was unable to generate a console message, but
260 otherwise succeeded.
261
264 Example 1 The following example of fmtmsg():
265 fmtmsg(MM_PRINT, "UX:cat", MM_ERROR, "invalid syntax",
267 "refer to manual", "UX:cat:001")
268 produces a complete message in the standard message format:
272 UX:cat: ERROR: invalid syntax
275 TO FIX: refer to manual UX:cat:001
276 Example 2 When the environment variable MSGVERB is set as follows:
279 MSGVERB=severity:text:action
281 and the Example 1 is used, fmtmsg() produces:
285 ERROR: invalid syntax
288 TO FIX: refer to manual
289 Example 3 When the environment variable SEV_LEVEL is set as follows:
292 SEV_LEVEL=note,5,NOTE
294 the following call to fmtmsg()
298 fmtmsg(MM_UTIL | MM_PRINT, "UX:cat", 5, "invalid syntax",
301 "refer to manual", "UX:cat:001")
302 produces
306 UX:cat: NOTE: invalid syntax
309 TO FIX: refer to manual UX:cat:001
310
313 See attributes(5) for descriptions of the following attributes:
314 ┌─────────────────────────────┬─────────────────────────────┐
319 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
320 ├─────────────────────────────┼─────────────────────────────┤
321 │Interface Stability │Standard │
322 ├─────────────────────────────┼─────────────────────────────┤
323 │MT-Level │Safe │
324 └─────────────────────────────┴─────────────────────────────┘
325
327 fmtmsg(1), addseverity(3C), gettxt(3C), printf(3C), attributes(5),
328 standards(5)
329SunOS 5.11 24 Jul 2002 fmtmsg(3C)