fmtmsg - Displays a message in the specified format
Standard C Library (libc.so, libc.a)
const char *label,
const char *text,
const char *action,
const char *tag);
Interfaces documented on this reference page conform to industry standards as follows:
Refer to the standards(5) reference page for more information about industry standards and associated tags.
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 condition. 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 condition. 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 maximum 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.
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.
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 console messages.
[Digital] 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:
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 setting 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 following message is displayed:
program:subroutine: NOTE: invalid syntax TO FIX: correct the syntax program:subroutine:002
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:
and Example 1 is used, the fmtmsg() function produces the following results:
ERROR: invalid syntax TO FIX: read the program manpage
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 succeeded.
Standards: standards(5) delim off