|FMTMSG(3C)||Standard C Library Functions||FMTMSG(3C)|
#include <fmtmsg.h> int fmtmsg(long classification, const char *label, int severity, const char *text, const char *action, const char *tag);
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 classification 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.
The MSGVERB and SEV_LEVEL environment variables control the behavior of fmtmsg() 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 component'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 components.
The first time fmtmsg() is called, it examines MSGVERB to determine which message components are to be selected when generating 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.
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:
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 evaluate 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 values accepted on the initial call are saved for future calls.
One or more message components may be systematically omitted from messages generated by an application by using the null value of the argument for that component.
The table below indicates the null values and identifiers for fmtmsg() arguments.
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).
The fmtmsg() returns the following values:
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:
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:
the following call to fmtmsg()
fmtmsg(MM_UTIL | MM_PRINT, "UX:cat", 5, "invalid syntax", "refer to manual", "UX:cat:001")
UX:cat: NOTE: invalid syntax TO FIX: refer to manual UX:cat:001
See attributes(7) for descriptions of the following attributes:
|ATTRIBUTE TYPE||ATTRIBUTE VALUE|
fmtmsg(1), addseverity(3C), gettxt(3C), printf(3C), attributes(7), standards(7)
|July 24, 2002||OmniOS|