unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (SunOS-5.10)
Page:
Section:
Apropos / Subsearch:
optional field

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 mes-
       sage 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  dis-
       played 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 hard-
                                       ware.




                       soft            The source of the  condition  is  soft-
                                       ware.



                       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 mes-
                       sage. Valid keywords are:


                       appl            The condition originated in an applica-
                                       tion.  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 com-
                                       bination with either appl or opsys.



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



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



                       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  con-
                                       sole.  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  condi-
                                       tion  that  is  out of the ordinary and
                                       might be a problem.



                       info            The application is  providing  informa-
                                       tion  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 argument.



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  key-
       word  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 mes-
       sage format whenever the severity value level is used.

       If SEV_LEVEL is not defined, or if its value is null, no severity  lev-
       els  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  mes-
                sage was not displayed on stderr.



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



       32       No requested functions were executed successfully.



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


       tab()    allbox;    cw(2.750000i)|     cw(2.750000i)     lw(2.750000i)|
       lw(2.750000i).  ATTRIBUTE TYPEATTRIBUTE VALUE AvailabilitySUNWcsu


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



SunOS 5.10                        20 Jul 1994                        fmtmsg(1)