fmtmsg(3) Library Functions Manual fmtmsg(3)
NAME
fmtmsg - Displays a message in the specified format
LIBRARY
Standard C Library (libc)
SYNOPSIS
#include <fmtmsg.h>
int fmtmsg(
long classification,
const char *label,
int severity,
const char *text,
const char *action,
const char *tag);
STANDARDS
Interfaces documented on this reference page conform to industry standards as follows:
fmtmsg(): XSH5.0
Refer to the standards(5) reference page for more information about industry standards and associated tags.
PARAMETERS
Defines the source of the message and directs the display of the formatted message, using the classes of identifiers listed below. Any one
identifier from a subclass can be combined with a single identifier from a different subclass. Using two or more identifiers from the same
subclass is not allowed, with the exception of identifiers from the Display subclass. (Both Display subclass identifiers may be used so
that messages can be displayed to both standard error and the system console). The following identifiers are available: Identifies the
source of the condition. The options are MM_HARD (hardware), MM_SOFT (software), and MM_FIRM (firmware). Identifies the software type
that exhibits the problem. The options are MM_APPL (application), MM_UTIL (utility), MM_OPSYS, and (operating system). Identifies where
the message is to be displayed. The options are MM_PRINT (standard error) or MM_CONSOLE (system console). One or both options may be
used. Identifies whether the application will recover from the condition. The options are MM_RECOVER (can recover) or MM_NRECOV (cannot
recover).
An additional identifier, MM_NULLMC, indicates that no classification component is supplied for the message. Identifies the message
source. The label format consists of two fields separated by a colon. The first field can contain up to 10 bytes. The second field can
contain up to 14 bytes. It is suggested that label contain at least the name of the application. Indicates the seriousness of the condi-
tion. The options are as follows: Indicates that application has encountered an error. Produces the string ERROR. Indicates that the
application has stopped running because it has found a severe error. Produces the string HALT. Displays information about a nonerror con-
dition. Produces the string INFO. Indicates that no severity level is provided for the message. Indicates a condition that might be a
problem and should be monitored. Produces the string WARNING. Describes the error that produced the message. The text string has no maxi-
mum length. If the text string is empty, the text produced is unspecified. Describes the first action to be taken to recover from the
error condition. The fmtmsg() function precedes every action string with the prefix TO FIX:. The action string has no maximum length.
Points the user to the online documentation for the message. It is suggested that tag include the label as well as a unique identifying
number. For example, program:subroutine:003.
DESCRIPTION
The fmtmsg() function writes a formatted message to either standard error, the system console, or both. Any message typically written to
standard error (stderr) by printf() can also be displayed using the fmtmsg() function.
A formatted message consists of up to five components (label, severity, text, action, and tag), as described in the previous section. The
classification component is not part of a message displayed to the user, but defines the source of the message and directs the display of
the formatted message.
To omit any field from messages, use the null value of the field's parameter, as shown in the following table:
--------------------------------------------------
Parameter Type Null Value Identifier
--------------------------------------------------
label char* (char*)NULL MM_NULLLBL
severity int 0 MM_NULLSEV
classification long 0L MM_NULLMC
text char* (char*)NULL MM_NULLTXT
action char* (char*)NULL MM_NULLACT
tag char* (char*)NULL MM_NULLTAG
--------------------------------------------------
The MSGVERB environment variable (for message verbosity) defines which parameters are used by the fmtmsg() function when writing a message
to standard error (stderr). The value of MSGVERB is a colon-separated list of optional keywords. Valid keywords are: label, severity,
text, action, and tag. These parameters may be specified in any order. See the PARAMETERS section for parameter definitions.
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 written to standard error. If MSGVERB omits a keyword for a message component, that component is omitted in the display of
the message. 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
invalid keywords, the fmtmsg() function displays all of the components.
The MSGVERB setting affects only which components are selected for display to standard error. All message components are included in con-
sole messages.
NOTES
[Tru64 UNIX] The following functionality does not conform to the current standards and is supported only for backward compatibility. When
specifying the classification component, you can combine more than one option from a subclass with an option from a different subclass if
you OR the values together. The SEV_LEVEL (severity level) environment variable can be used to define, modify, or delete severity levels
other than the default.
Each severity level that you define has a print string associated with it that is used by the fmtmsg function. The syntax is:
SEV_LEVEL=[description[:description[: ...]]] export SEV_LEVEL
The description arguments consist of three fields separated by commas as follows:
description=severity_level,level,printstring
The value of each field is: Specifies the severity of the level. Specifies a severity level with any positive integer except 0 to 4 (the
standard severity levels). Specifies the severity level message used by the fmtmsg() function whenever the severity level level is used.
If the SEV_LEVEL environment variable is not set, or it has a null value, the defaults are used. If the description is not a 3-field comma
separated list as described previously or if the level field specified is not a positive integer, the SEV_LEVEL environment variable set-
ting is ignored.
The SEV_LEVEL environment variable can be set in the user's shell or used in shell scripts.
For example, when the environment variable SEV_LEVEL is set as follows:
SEV_LEVEL=note, 5, NOTE
and the fmtmsg() function is called as follows::
fmtmsg(MM_PRINT, "program:subroutine", 5, "large output file produced", "check file size before dump", "program:subroutine:002") the fol-
lowing message is displayed:
program:subroutine: NOTE: invalid syntax TO FIX: correct the syntax program:subroutine:002
EXAMPLES
The following example of fmtmsg():
fmtmsg(MM_PRINT, "program:subroutine", MM_ERROR, "invalid syntax", "read the program manpage", "program:subroutine:003"),
produces a complete message in the specified message format:
program:subroutine: ERROR: invalid syntax TO FIX: read the program manpage program:subroutine:003 When the environment variable MSGVERB is
set as follows:
MSGVERB=severity:text:action
and Example 1 is used, the fmtmsg() function produces the following results:
ERROR: invalid syntax TO FIX: read the program manpage
RETURN VALUES
The fmtmsg() function returns the following values: The function was unable to generate a console message, but otherwise succeeded. The
function was unable to generate a message on standard error, but otherwise succeeded. The function failed completely. The function suc-
ceeded.
RELATED INFORMATION
Functions: printf(3)
Standards: standards(5) delim off
fmtmsg(3)