FMTMSG(3) BSD Library Functions Manual FMTMSG(3)NAMEfmtmsg — 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 con‐
sole, 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 sev‐
eral 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 (operat‐
ing 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 condi‐
tion. 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 charac‐
ters, 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 con‐
dition.
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 stan‐
dard error stream (but not on the system console!) may be taken by set‐
ting the MSGVERB environment variable, which selects the subset of mes‐
sage components to be printed. It consists of a colon-separated list of
the optional keywords label, severity, text, action, and tag, which cor‐
respond 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 con‐
sole, but otherwise succeeded.
SEE ALSOprintf(3), syslog(3)STANDARDS
The fmtmsg() function conforms to X/Open System Interfaces and Headers
Issue 5 (“XSH5”).
BSD April 11, 2011 BSD
