FMTMSG(3C)FMTMSG(3C)NAMEfmtmsg - display a message on stderr or system console
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 con‐
sole, or to both, on a message's classification component. It can be
used instead of the traditional printf(3C) interface to display mes‐
sages 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 classifica‐
tion component is not part of the standard message displayed to the
user, but rather defines the source of the message and directs the dis‐
play of the formatted message.
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" iden‐
tify 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-recover‐
o An additional identifier, MM_NULLMC, indi‐
cates that no classification component is
supplied for the message.
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 sec‐
ond 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 Sys‐
tem V package and the cat(1) utility.
Indicates the seriousness of the condition. Identi‐
fiers 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
o MM_WARNING indicates a condition out of
the ordinary that might be a problem and
should be watched. Produces the print
o MM_INFO provides information about a con‐
dition 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 add‐
Describes the condition that produced the message.
The text string is not limited to a specific size.
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.
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.
The MSGVERB and SEV_LEVEL environment variables control the behavior of
fmtmsg() as follows:
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
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 writ‐
ing 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 cor‐
rect 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 compo‐
nents that are selected for display to the standard error
stream. All message components are included in console
This variable defines severity levels and associates print
strings with them for use by fmtmsg(). The standard sever‐
ity levels listed below cannot be modified. Additional
severity levels can also be defined, redefined, and
removed using addseverity() (see addseverity(3C)). If the
same severity level is defined by both SEV_LEVEL and add‐
severity(), the definition by addseverity() takes prece‐
(no severity is used)
The SEV_LEVEL variable can be set as follows:
where description is a comma-separated list containing
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()
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.
Use in Applications
One or more message components may be systematically omitted from mes‐
sages 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()
│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).
The fmtmsg() returns the following values:
The function succeeded.
The function failed completely.
The function was unable to generate a message on the stan‐
dard error stream, but otherwise succeeded.
The function was unable to generate a console message, but
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:
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(5) for descriptions of the following attributes:
│ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
│Interface Stability │ Standard │
│MT-Level │ Safe │
SEE ALSOfmtmsg(1), addseverity(3C), gettxt(3C), printf(3C), attributes(5),
Jul 24, 2002 FMTMSG(3C)