fmtmsg - output message to stderr and/or system console

Syntax

#include <fmtmsg.h>

int fmtmsg(long classification, const char *label, int severity, const char *text,

const char *action, const char *tag);

Description

Building on the classification component of a message, fmtmsg() writes a formatted message to stderr, the system console or both.

fmtmsg() can be used instead of the usual printf() interface to output messages via stderr. In conjunction with gettxt(), fmtmsg() provides a simple interface for the creation of language-independent application programs.

A formatted message consists of up to five standard components which are defined below. The classification component is not part of the standard message that is shown to the user; instead, it defines the message source and controls the display of the formatted message..

classification

 

contains identifiers from the following groups of main and secondary classifications. Every identifier of a subclass can be used with a single identifier of a different subclass via inclusive OR. With the exception of the display classification, two or more identifiers from the same subclass should not be used together. Both identifiers of the display classification can be used such that the messages appear on both stderr and the system console.

Major classifications

identify the origin of a status. The identifiers are: MM_HARD (hardware), MM_SOFT (software) and MM_FIRM (firmware).

Message source subclassifications

identify the type of software in which the problem occurred. The identifiers are: MM_APPL (application), MM_UTIL (utility routine) and MM_OPSYS (operating system).

Display subclassifications

identify where the message is to be displayed. The identifiers are MM_PRINT for outputting the message to standard error output, and MM_CONSOLE for outputting the message to the system console. You can use one or both identifiers or you can omit the specification (in the latter case, nothing is output).

Status subclassifications

indicate whether the application program can recover after the status. Identifiers are: MM_RECOVER (recoverable) and MM_NRECOV (non-recoverable).

Additional identifier MM_NULLMC

indicates that no classification component is specified for the message.

label

defines the origin of the message. The format of this component consists of two fields separated by a colon. The first field is up to 10 characters long; the second is up to 14 characters long.

It is advisable to mark the package and the program or the application name with label. For example, the content UX:cat for label indicates that the package UNIX system V and the application cat are meant.

severity

indicates the severity level of the status. Identifiers for the severity levels are:

MM_HALT	indicates that the application has come across a critical error and processing is being halted. The string “HALT“ is output.
MM_ERROR	indicates that the application has detected an error. The string “ERROR“ is output.
MM_WARNING	indicates that an unusual state has arisen which could involve a problem that needs monitoring. The string “WARNING“ is issued.
MM_INFO	provides information on a state which does not represent an error. The string “INFO“ is output.
MM_NOSEV	indicates that no severity level exists for the message.

 

text

describes the cause of the message. The text string is not limited to a particular length. If the string is empty, the text that is output is undefined.

 

action

describes the first action to be executed in the error recovery process. fmtmsg() writes the prefix “TO FIX:“ before this string. The action string is not limited to a particular length.

 

tag

An identifier that refers to the online documentation for the message. It is recommended that tag contain the origin of the message addressed via label and a unique number. An example of tag is UX:cat:146.

 

Environment variables

There are two environment variables which influence the behavior of fmtmsg(): MSGVERB and SEV_LEVEL.

MSGVERB informs fmtmsg() which message components are to be selected when writing the messages to stderr. The value of MSGVERB consists of a list of optional keywords separated by colons. MSGVERB can be set 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 this component does not have the null value assigned to it (see below), fmtmsg() outputs this component to stderr at message output. If MSGVERB does not contain the keyword for a message component, this component is not output. The keywords can be specified in any order. If MSGVERB is not defined, if this identifier contains a null string, if the value is not specified in the correct format, or if invalid keywords are specified, fmtmsg() selects all components.

At the first call of fmtmsg() the MSGVERB environment variable is verified so that the message components can be selected if a message is generated via the standard error output stderr. The values accepted at the first call are saved for the subsequent calls.

MSGVERB influences only the selection of the components that are to be displayed via the standard error output. In the case of output to the console, all messages are selected.

SEV_LEVEL defines the severity levels and assigns the strings to be output that are to be used by fmtmsg(). The standard severity levels given below cannot be changed. Additional severity levels can be defined, modified and deleted via the addseverity () function (see addseverity(3C)). If the same severity level is defined by SEV_LEVEL and addseverity(), the addseverity() definition takes precedence.

0   (no severity level used)
1   HALT
2   ERROR
3   WARNING
4   INFO

SEV_LEVEL can be set as follows:

SEV_LEVEL=[description[: description[:...]]]

export SEV_LEVEL

description contains a list with three fields, each separated by a comma:

description = severity_keyword , level , printstrin

severity_keyword is a string that is used as the keyword for the option -s severity of the fmtmsg command. This field is not used by the fmtmsg() function.

level is a string containing a positive integer (not 0, 1, 2, 3 or 4 because these values are reserved for the standard severity levels). If the keyword severity_keyword is used, level represents the severity level of the value that was passed to the fmtmsg() function.

printstring is a string that is used by fmtmsg() for the standard message format when the severity level level is specified.

If in the list description does not represent a list of three fields separated by commas, or if the second field of a list is not an integer, description is ignored in the list.

When fmtmsg() is called for the first time, the SEV_LEVEL environment variable is checked to see whether, in addition to the five standard severity levels and those defined via addseverity(), any other severity levels were defined. The values established at the first call are saved for later calls.

Return val.

MM_OK

if successful.

.

MM_NOTOK

The function has completely failed.

.

MM_NOMSG

The function could not generate a message via the standard error output, but was otherwise successful.

 

MM_NOCON

The function could not generate a message via the system console, but was otherwise successful.

 Notes

One or more message components can be systematically omitted from the message if the null value of the respective components is specified.
The following table shows the null values and identifiers for the arguments of 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

A further means of systematic omission of a component consists of leaving out the keywords of the component when defining the MSGVERB environment variable.

Example 1

fmtmsg(MM_PRINT, "UX:cat", MM_ERROR, "Incorrect syntax",

"See manual", "UX:cat:001")

returns a complete message with the standard message format:

UX:cat: ERROR: Incorrect syntax TO FIX: See manual UX:cat:001

Example 2

If the MSGVERB environment variable is set as follows:

MSGVERB=severity:text:action

and example 1 is then used, fmtmsg() generates:

ERROR: Incorrect syntax TO FIX: See manual

Example 3

If the SEV_LEVEL environment variable is set as follows:

SEV_LEVEL=note,5,NOTE

the following fmtmsg() call

fmtmsg(MM_UTIL | MM_PRINT, "UX:cat", 5, "Incorrect syntax",

"See manual", "UX:cat:001")

returns the following output:

UX:cat: NOTE: Incorrect syntax TO FIX: See manual UX:cat:001

See also

printf(), fmtmsg.h.