fmtmsg(1)							   User Commands							 fmtmsg(1)

NAME

       fmtmsg - display a message on stderr or system console

SYNOPSIS

       fmtmsg [-c class] [-u subclass] [-l label] [-s severity] [-t tag] [-a action] text

DESCRIPTION

       Based on a message's classification component, the fmtmsg utility either writes a formatted message to stderr or writes a formatted message
       to the console.

       A formatted message consists of up to five standard components (see environment variable MSGVERB in the ENVIRONMENT  VARIABLES  section	of
       this  page).  The classification and subclass components are not displayed as part of the standard message, but rather define the source of
       the message and direct the display of the formatted message.

OPTIONS

       The following options are supported:

       -c class        Describes the source of the message. Valid keywords are:

		       hard	       The source of the condition is hardware.

		       soft	       The source of the condition is software.

		       firm	       The source of the condition is firmware.

       -u subclass     A list of keywords (separated by commas) that further defines the message and directs the display  of  the  message.  Valid
		       keywords are:

		       appl	       The condition originated in an application. This keyword should not be used in combination with either util
				       or opsys.

		       util	       The condition originated in a utility. This keyword should not be used in combination with either  appl	or
				       opsys.

		       opsys	       The  message  originated  in the kernel. This keyword should not be used in combination with either appl or
				       util.

		       recov	       The application will recover from the condition. This keyword should not be used in combination	with  nre-
				       cov.

		       nrecov	       The  application  will  not recover from the condition. This keyword should not be used in combination with
				       recov.

		       print	       Print the message to the standard error stream stderr.

		       console	       Write the message to the system console. print, console, or both may be used.

       -l label        Identifies the source of the message.

       -s severity     Indicates the seriousness of the error. The keywords and definitions of the standard levels of severity are:

		       halt	       The application has encountered a severe fault and is halting.

		       error	       The application has detected a fault.

		       warn	       The application has detected a condition that is out of the ordinary and might be a problem.

		       info	       The application is providing information about a condition that is not in error.

       -t tag	       The string containing an identifier for the message.

       -a action       A text string describing the first step in the error recovery process. This string must	be  written  so  that  the  entire
		       action argument is interpreted as a single argument. fmtmsg precedes each action string with the TO FIX: prefix.

       text	       A  text	string describing the condition. Must be written so that the entire text argument is interpreted as a single argu-
		       ment.

EXAMPLES

       Example 1: Standard message format

       The following example of fmtmsg produces a complete message in the standard message format and displays it to the standard error stream.

       example% fmtmsg -c soft -u recov,print,appl -l UX:cat 
	    -s error -t UX:cat:001 -a "refer to manual" "invalid syntax"

       produces:

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

       Example 2: Using MSGVERB

       When the environment variable MSGVERB is set as follows:

       MSGVERB=severity:text:action

       and Example 1 is used, fmtmsg produces:

       ERROR: invalid syntax
       TO FIX: refer to manual

       Example 3: Using SEV_LEVEL

       When the environment variable SEV_LEVEL is set as follows:

       SEV_LEVEL=note,5,NOTE

       the following fmtmsg command:

       example% fmtmsg -c soft -u print -l UX:cat -s note 
	    -a "refer to manual" "invalid syntax"

       produces:

       NOTE: invalid syntax
       TO FIX: refer to manual

       and displays the message on stderr.

ENVIRONMENT VARIABLES

       The environment variables MSGVERB and SEV_LEVEL control the behavior of fmtmsg. MSGVERB is set by the administrator in the /etc/profile for
       the  system.  Users can override the value of MSGVERB set by the system by resetting MSGVERB in their own .profile files or by changing the
       value in their current shell session. SEV_LEVEL can be used in shell scripts.

       MSGVERB tells fmtmsg which message components to select when writing messages to stderr. The value of MSGVERB is a colon-separated list	of
       optional keywords. 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 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.

       MSGVERB affects only which message components are selected for display. All message components are included in console messages.

       SEV_LEVEL defines severity levels and associates print strings with them for use by fmtmsg. The standard severity levels shown below cannot
       be modified. Additional severity levels can be defined, redefined, and removed.

       0	(no severity is used)

       1	HALT

       2	ERROR

       3	WARNING

       4	INFO

       SEV_LEVEL is set as follows:

       description is a comma-separated list containing three fields:

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

	      description=severity_keyword, level, printstring

       severity_keyword is a character string used as the keyword with the -s severity option to fmtmsg.

       level 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 fmtmsg(3C).

       printstring is the character string used by fmtmsg in the standard message format whenever the severity value level is used.

       If  SEV_LEVEL  is  not  defined, or if its value is null, no severity levels other than the defaults are available. If a description in the
       colon separated list is not a comma separated list containing three fields, or if the second field of a comma separated list does not eval-
       uate to a positive integer, that description in the colon separated list is ignored.

EXIT STATUS

       The following exit values are returned:

       0	All the requested functions were executed successfully.

       1	The command contains a syntax error, an invalid option, or an invalid argument to an option.

       2	The function executed with partial success, however the message was not displayed on stderr.

       4	The function executed with partial success; however, the message was not displayed on the system console.

       32	No requested functions were executed successfully.

ATTRIBUTES

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

       +-----------------------------+-----------------------------+
       |      ATTRIBUTE TYPE	     |	    ATTRIBUTE VALUE	   |
       +-----------------------------+-----------------------------+
       |Availability		     |SUNWcsu			   |
       +-----------------------------+-----------------------------+

SEE ALSO

       addseverity(3C), fmtmsg(3C), attributes(5)

SunOS 5.10							    20 Jul 1994 							 fmtmsg(1)