 |
Index for
Section 3 |
|
 |
Alphabetical
listing for F |
|
 |
Bottom of
page |
|
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
classification
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:
Major Classifications
Identifies the source of the condition. The options are MM_HARD
(hardware), MM_SOFT (software), and MM_FIRM (firmware).
Message Source Subclassifications
Identifies the software type that exhibits the problem. The
options are MM_APPL (application), MM_UTIL (utility), MM_OPSYS, and
(operating system).
Display Subclassifications
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.
Status Subclassifications
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.
label
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.
severity
Indicates the seriousness of the condition. The options are as
follows:
MM_ERROR
Indicates that application has encountered an error. Produces the
string ERROR.
MM_HALT
Indicates that the application has stopped running because it has
found a severe error. Produces the string HALT.
MM_INFO
Displays information about a nonerror condition. Produces the
string INFO.
MM_NOSEV
Indicates that no severity level is provided for the message.
MM_WARNING
Indicates a condition that might be a problem and should be
monitored. Produces the string WARNING.
text
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.
action
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.
tag 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 console
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:
severity_level
Specifies the severity of the level.
level
Specifies a severity level with any positive integer except 0 to 4 (the
standard severity levels).
printstring
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
EXAMPLES
1. 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
2. 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:
MM_NOCON
The function was unable to generate a console message, but otherwise
succeeded.
MM_NOMSG
The function was unable to generate a message on standard error, but
otherwise succeeded.
MM_NOTOK
The function failed completely.
MM_OK
The function succeeded.
RELATED INFORMATION
Functions: printf(3)
Standards: standards(5)
|
Index for
Section 3 |
|
|
Alphabetical
listing for F |
|
 |
Top of
page |
|