man/man3c/fmtmsg.3c

         te
 Copyright 1989 AT&T Copyright (c) 2002, Sun Microsystems, Inc. All Rights Reserved
 The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
 You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
 When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
 FMTMSG 3C "Jul 24, 2002"
 NAME
fmtmsg - display a message on stderr or system console
 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 writes a formatted message to stderr, to the
console, or to both, on a message's classification component. It can be used
instead of the traditional printf(3C) interface to display messages to
stderr, and in conjunction with gettxt(3C), provides a simple
interface for producing language-independent applications.

A formatted message consists of up to five standard components ( label,
severity, text, action, and tag) as described below.
The classification component is not part of the standard message
displayed to the user, but rather defines the source of the message and directs
the display of the formatted message.
classification

Contains identifiers from the following groups of major classifications and
subclassifications. Any one identifier from a subclass may be used in
combination by ORing the values together with a single identifier from a
different subclass. Two or more identifiers from the same subclass should not
be used together, with the exception of identifiers from the display subclass.
(Both display subclass identifiers may be used so that messages can be
displayed to both stderr and the system console).


"Major classifications" identify the source of the condition. Identifiers are:
MM_HARD (hardware), MM_SOFT (software), and MM_FIRM
(firmware).


"Message source subclassifications" identify the type of software in which the
problem is spotted. Identifiers are: MM_APPL (application), MM_UTIL
(utility), and MM_OPSYS (operating system).


"Display subclassifications" indicate where the message is to be displayed.
Identifiers are: MM_PRINT to display the message on the standard error
stream, MM_CONSOLE to display the message on the system console. Neither,
either, or both identifiers may be used.


"Status subclassifications" indicate whether the application will recover from
the condition. Identifiers are: MM_RECOVER (recoverable) and
MM_NRECOV (non-recoverable).


An additional identifier, MM_NULLMC, indicates that no classification
component is supplied for the message.


label

Identifies the source of the message. The format of this component is two
fields separated by a colon. The first field is up to 10 characters long; the
second is up to 14 characters. Suggested usage is that label identifies
the package in which the application resides as well as the program or
application name. For example, the label UX:cat indicates the
UNIX System V package and the cat(1) utility.


severity

Indicates the seriousness of the condition. Identifiers for the standard levels
of severity are:


MM_HALT indicates that the application has encountered a severe fault and
is halting. Produces the print string HALT.


MM_ERROR indicates that the application has detected a fault. Produces
the print string ERROR.


MM_WARNING indicates a condition out of the ordinary that might be a
problem and should be watched. Produces the print string WARNING.


MM_INFO provides information about a condition that is not in error.
Produces the print string INFO.


MM_NOSEV indicates that no severity level is supplied for the message.

Other severity levels may be added by using the addseverity() routine.


text

Describes the condition that produced the message. The text string is not
limited to a specific size.


action

Describes the first step to be taken in the error recovery process.
fmtmsg() precedes each action string with the prefix: TOFIX:.
The action string is not limited to a specific size.


tag

An identifier which references on-line documentation for the message. Suggested
usage is that tag includes the label and a unique identifying
number. A sample tag is UX:cat:146.


 "Environment Variables"

The MSGVERB and SEV_LEVEL environment variables control the
behavior of fmtmsg() as follows:
MSGVERB

This variable determines which message components fmtmsg() selects when
writing messages to stderr. Its value is a colon-separated list of
optional keywords and 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 the component's value is not the component's null value,
fmtmsg() includes that component in the message when writing the message
to stderr. If MSGVERB does not include a keyword for a message
component, that component is not included in the display of the message. The
keywords may appear in any order. 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 keywords other than the valid ones listed above, fmtmsg()
selects all components.
The first time fmtmsg() is called, it examines MSGVERB to determine
which message components are to be selected when generating a message to write
to the standard error stream, stderr. The values accepted on the initial
call are saved for future calls.
The MSGVERB environment variable affects only those components that are
selected for display to the standard error stream. All message components are
included in console messages.


SEV_LEVEL

This variable defines severity levels and associates print strings with them
for use by fmtmsg(). The standard severity levels listed below cannot be
modified. Additional severity levels can also be defined, redefined, and
removed using addseverity() (see addseverity(3C)). If the same
severity level is defined by both SEV_LEVEL and addseverity(), the
definition by addseverity() takes precedence.
0

(no severity is used)


1

HALT


2

ERROR


3

WARNING


4

INFO


The SEV_LEVEL variable can be set as follows:
SEV_LEVEL=[description[:description[:\|.\|.\|.]]]
export SEV_LEVEL


where description is a comma-separated list containing three fields:
description=severity_keyword,level,printstring
The severity_keyword field is a character string that is used as the
keyword on the -s severity option to the
fmtmsg(1) utility. (This field is not used by the fmtmsg()
function.)
The level field is a character string that evaluates to a positive
integer (other than 0, 1, 2, 3, or 4, which are reserved for the standard
severity levels). If the keyword severity_keyword is used, level is
the severity value passed on to the fmtmsg() function.
The printstring field is the character string used by fmtmsg() in
the standard message format whenever the severity value level is used.
If a description in the colon list is not a three-field comma list, or if
the second field of a comma list does not evaluate to a positive integer, that
description in the colon list is ignored.
The first time fmtmsg() is called, it examines the SEV_LEVEL
environment variable, if defined, to determine whether the environment expands
the levels of severity beyond the five standard levels and those defined using
addseverity(). The values accepted on the initial call are saved for
future calls.


 "Use in Applications"

One or more message components may be systematically omitted from messages
generated by an application by using the null value of the argument for that
component.

The table below indicates the null values and identifiers for fmtmsg()
arguments.


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


Another means of systematically omitting a component is by omitting the
component keyword(s) when defining the MSGVERB environment variable (see
the Environment Variables section above).
 RETURN VALUES

The fmtmsg() returns 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 the standard error stream, but
otherwise succeeded.


MM_NOCON

The function was unable to generate a console message, but otherwise succeeded.


 EXAMPLES

Example 1 The following example of fmtmsg():
fmtmsg(MM_PRINT, "UX:cat", MM_ERROR, "invalid syntax",
"refer to manual", "UX:cat:001")


produces a complete message in the standard message format:

UX:cat: ERROR: invalid syntax
TO FIX: refer to manual UX:cat:001


Example 2 When the environment variable MSGVERB is set as follows:
MSGVERB=severity:text:action


and the Example 1 is used, fmtmsg() produces:

ERROR: invalid syntax
TO FIX: refer to manual


Example 3 When the environment variable SEV_LEVEL is set as
follows:
SEV_LEVEL=note,5,NOTE


the following call to fmtmsg()

fmtmsg(MM_UTIL | MM_PRINT, "UX:cat", 5, "invalid syntax",
"refer to manual", "UX:cat:001")


produces

UX:cat: NOTE: invalid syntax
TO FIX: refer to manual UX:cat:001


 ATTRIBUTES

See attributes(5) for descriptions of the following attributes:


ATTRIBUTE TYPE ATTRIBUTE VALUE
Interface Stability Standard
MT-Level Safe


 SEE ALSO

fmtmsg(1), addseverity(3C), gettxt(3C), printf(3C),
attributes(5), standards(5)