fmtmsg(3C) Standard C Library Functions fmtmsg(3C)
NAME
fmtmsg - display a message on stderr or system console
SYNOPSIS
#include <fmtmsg.h>
int fmtmsg(long classification, const char *label, int severity, const char *text, const char *action, const char *tag);
DESCRIPTION
The fmtmsg() function writes a formatted message to stderr, to the console, or to both, on a message's classification component. It can be
used instead of the traditional printf(3C) interface to display messages to stderr, and in conjunction with gettxt(3C), provides a simple
interface for producing language-independent applications.
A formatted message consists of up to five standard components ( label, severity, text, action, and tag) as described below. The classifi-
cation component is not part of the standard message displayed to the user, but rather defines the source of the message and directs the
display of the formatted message.
classification Contains identifiers from the following groups of major classifications and subclassifications. Any one identifier from a
subclass may be used in combination by ORing the values together with a single identifier from a different subclass. Two or
more identifiers from the same subclass should not be used together, with the exception of identifiers from the display
subclass. (Both display subclass identifiers may be used so that messages can be displayed to both stderr and the system
console).
o "Major classifications" identify the source of the condition. Identifiers are: MM_HARD (hardware), MM_SOFT (software),
and MM_FIRM (firmware).
o "Message source subclassifications" identify the type of software in which the problem is spotted. Identifiers are:
MM_APPL (application), MM_UTIL (utility), and MM_OPSYS (operating system).
o "Display subclassifications" indicate where the message is to be displayed. Identifiers are: MM_PRINT to display the
message on the standard error stream, MM_CONSOLE to display the message on the system console. Neither, either, or
both identifiers may be used.
o "Status subclassifications" indicate whether the application will recover from the condition. Identifiers are:
MM_RECOVER (recoverable) and MM_NRECOV (non-recoverable).
o An additional identifier, MM_NULLMC, indicates that no classification component is supplied for the message.
label Identifies the source of the message. The format of this component is two fields separated by a colon. The first field is
up to 10 characters long; the second is up to 14 characters. Suggested usage is that label identifies the package in which
the application resides as well as the program or application name. For example, the label UX:cat indicates the UNIX System
V package and the cat(1) utility.
severity Indicates the seriousness of the condition. Identifiers for the standard levels of severity are:
o MM_HALT indicates that the application has encountered a severe fault and is halting. Produces the print string HALT.
o MM_ERROR indicates that the application has detected a fault. Produces the print string ERROR.
o MM_WARNING indicates a condition out of the ordinary that might be a problem and should be watched. Produces the print
string WARNING.
o MM_INFO provides information about a condition that is not in error. Produces the print string INFO.
o MM_NOSEV indicates that no severity level is supplied for the message.
Other severity levels may be added by using the addseverity() routine.
text Describes the condition that produced the message. The text string is not limited to a specific size.
action Describes the first step to be taken in the error recovery process. fmtmsg() precedes each action string with the prefix:
TOFIX:. The action string is not limited to a specific size.
tag An identifier which references on-line documentation for the message. Suggested usage is that tag includes the label and a
unique identifying number. A sample tag is UX:cat:146.
Environment Variables
The MSGVERB and SEV_LEVEL environment variables control the behavior of fmtmsg() as follows:
MSGVERB This variable determines which message components fmtmsg() selects when writing messages to stderr. Its value is a colon-
separated list of optional keywords and can be set as follows:
MSGVERB=[keyword[:keyword[:...]]]
export MSGVERB
Valid keywords are: label, severity, text, action, and tag. If MSGVERB contains a keyword for a component and the compo-
nent's value is not the component's null value, fmtmsg() includes that component in the message when writing the message to
stderr. If MSGVERB does not include a keyword for a message component, that component is not included in the display of the
message. The keywords may appear in any order. If MSGVERB is not defined, if its value is the null string, if its value is
not of the correct format, or if it contains keywords other than the valid ones listed above, fmtmsg() selects all compo-
nents.
The first time fmtmsg() is called, it examines MSGVERB to determine which message components are to be selected when gener-
ating a message to write to the standard error stream, stderr. The values accepted on the initial call are saved for future
calls.
The MSGVERB environment variable affects only those components that are selected for display to the standard error stream.
All message components are included in console messages.
SEV_LEVEL This variable defines severity levels and associates print strings with them for use by fmtmsg(). The standard severity
levels listed below cannot be modified. Additional severity levels can also be defined, redefined, and removed using add-
severity() (see addseverity(3C)). If the same severity level is defined by both SEV_LEVEL and addseverity(), the definition
by addseverity() takes precedence.
0 (no severity is used)
1 HALT
2 ERROR
3 WARNING
4 INFO
The SEV_LEVEL variable can be set as follows:
SEV_LEVEL=[description[:description[:...]]]
export SEV_LEVEL
where description is a comma-separated list containing three fields:
description=severity_keyword,level,printstring
The severity_keyword field is a character string that is used as the keyword on the -s severity option to the fmtmsg(1)
utility. (This field is not used by the fmtmsg() function.)
The level field is a character string that evaluates to a positive integer (other than 0, 1, 2, 3, or 4, which are reserved
for the standard severity levels). If the keyword severity_keyword is used, level is the severity value passed on to the
fmtmsg() function.
The printstring field is the character string used by fmtmsg() in the standard message format whenever the severity value
level is used.
If a description in the colon list is not a three-field comma list, or if the second field of a comma list does not evalu-
ate to a positive integer, that description in the colon list is ignored.
The first time fmtmsg() is called, it examines the SEV_LEVEL environment variable, if defined, to determine whether the
environment expands the levels of severity beyond the five standard levels and those defined using addseverity(). The val-
ues accepted on the initial call are saved for future calls.
Use in Applications
One or more message components may be systematically omitted from messages generated by an application by using the null value of the argu-
ment for that component.
The table below indicates the null values and identifiers for fmtmsg() arguments.
+-----------------------------------------------------------------+
| Argument Type Null-Value Identifier |
|label char* (char*) NULL MM_NULLLBL |
|severity int 0 MM_NULLSEV |
|class long 0L MM_NULLMC |
|text char* (char*) NULL MM_NULLTXT |
|action char* (char*) NULL MM_NULLACT |
|tag char* (char*) NULL MM_NULLTAG |
+-----------------------------------------------------------------+
Another means of systematically omitting a component is by omitting the component keyword(s) when defining the MSGVERB environment variable
(see the Environment Variables section above).
RETURN VALUES
The fmtmsg() returns the following values:
MM_OK The function succeeded.
MM_NOTOK The function failed completely.
MM_NOMSG The function was unable to generate a message on the standard error stream, but otherwise succeeded.
MM_NOCON The function was unable to generate a console message, but otherwise succeeded.
EXAMPLES
Example 1: The following example of fmtmsg():
fmtmsg(MM_PRINT, "UX:cat", MM_ERROR, "invalid syntax",
"refer to manual", "UX:cat:001")
produces a complete message in the standard message format:
UX:cat: ERROR: invalid syntax
TO FIX: refer to manual UX:cat:001
Example 2: When the environment variable MSGVERB is set as follows:
MSGVERB=severity:text:action
and the Example 1 is used, fmtmsg() produces:
ERROR: invalid syntax
TO FIX: refer to manual
Example 3: When the environment variable SEV_LEVEL is set as follows:
SEV_LEVEL=note,5,NOTE
the following call to fmtmsg()
fmtmsg(MM_UTIL | MM_PRINT, "UX:cat", 5, "invalid syntax",
"refer to manual", "UX:cat:001")
produces
UX:cat: NOTE: invalid syntax
TO FIX: refer to manual UX:cat:001
ATTRIBUTES
See attributes(5) for descriptions of the following attributes:
+-----------------------------+-----------------------------+
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
+-----------------------------+-----------------------------+
|Interface Stability |Standard |
+-----------------------------+-----------------------------+
|MT-Level |Safe |
+-----------------------------+-----------------------------+
SEE ALSO
fmtmsg(1), addseverity(3C), gettxt(3C), printf(3C), attributes(5), standards(5)
SunOS 5.10 24 Jul 2002 fmtmsg(3C)