NAME
fmtmsg —
format and display a
message
LIBRARY
Standard C Library (libc, -lc)
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 can be used to display messages in the
specified format. Messages may be written either to standard error, to the
console, or both.
A formatted message consists of up to five components specified in
label,
severity,
text,
action and
tag. Further information such as the origin of the
message, the recoverability from the condition causing the message and where
to display the message is specified in
classification.
Classification
The
classification argument consists of a major
classification and several sub-classifications. It has no effect on the
content of the message displayed. With the exception of the display
sub-classification, only a single identifier may be specified for each
(sub-)classification. The following classifications are available:
-
-
- Major
classifications
- The source of the condition. Available identifiers are:
MM_HARD
(hardware),
MM_SOFT
(software), and
MM_FIRM
(firmware).
-
-
- Message source
sub-classifications
- The type of software detecting the condition. Available
identifiers are:
MM_APPL
(application),
MM_UTIL
(utility), and
MM_OPSYS
(operating system).
-
-
- Display
sub-classifications
- The displays the formatted messages is to be written to.
Available identifiers are:
MM_PRINT
(standard
error stream) and MM_CONSOLE
(system
console).
-
-
- Status
sub-classifications
- The capability of the calling software to recover from the
condition. Available identifiers are:
MM_RECOVER
(recoverable) and MM_NRECOV
(non-recoverable).
If no
classification is to be supplied,
MM_NULLMC
must be specified.
Label
The
label argument identifies the source of the message.
It consists of two fields separated by a colon (:). The first field is up to
10 characters, the second is up to 14 characters.
If no
label is to be supplied,
MM_NULLLBL
must be specified.
Severity
The seriousness of the condition causing the message. The following
severity levels are available:
-
-
MM_HALT
- The software has encountered a severe fault and is
halting.
-
-
MM_ERROR
- The software has encountered a fault.
-
-
MM_WARNING
- The software has encountered an unusual non-fault
condition.
-
-
MM_INFO
- The software informs about a non-error condition.
If no
severity level is to be supplied,
MM_NOSEV
must be specified.
Text
The description of the condition the software encountered. The character string
is not limited to a specific size.
If no
text is to be supplied,
MM_NOTXT
must be specified.
Action
The first step to be taken to recover from the condition the software
encountered; it will be preceded by the prefix “TO FIX:”. The
character string is not limited to a specific size.
If no
action is to be supplied,
MM_NOACT
must be specified.
Tag
The on-line documentation which provides further information about the condition
and the message, such as
“
fmtmsg(3)”. The
character string is not limited to a specific size.
If no
tag is to be supplied,
MM_NOTAG
must be specified.
Further effect on the formatting of the message as displayed on the standard
error stream (but not on the system console!) may be taken by setting the
MSGVERB
environment variable, which selects the subset
of message components to be printed. It consists of a colon-separated list of
the optional keywords
label,
severity,
text,
action, and
tag, which correspond
to the arguments to
fmtmsg() with the same names. If
MSGVERB
is either not set or malformed (containing
empty or unknown keywords), its content is ignored an all message components
will be selected.
Note that displaying a message on the system console may fail due to
inappropriate privileges or a non-permissive file mode of the console device.
RETURN VALUES
The
fmtmsg() function returns one of 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 standard
error, but otherwise succeeded.
-
-
MM_NOCOM
- The function was unable to generate a message on the
console, but otherwise succeeded.
SEE ALSO
printf(3),
syslog(3)
STANDARDS
The
fmtmsg() function conforms to
X/Open
System Interfaces and Headers Issue 5 (“XSH5”).