fmtmsg(3C)




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  com-
     ponents  (  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).

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

              o  "Message source subclassifications" identify the
                 type  of  software in which the problem is spot-
                 ted.  Identifiers  are:  MM_APPL  (application),
                 MM_UTIL  (utility), and MM_OPSYS (operating sys-
                 tem).

              o  "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.

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

              o  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  Sys-
           tem V package and the cat(1) utility.

     severity
           Indicates the seriousness of the  condition.  Identif-
           iers for the standard levels of severity are:

              o  MM_HALT  indicates  that  the  application   has
                 encountered  a severe fault and is halting. Pro-
                 duces the print string HALT.

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

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

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

              o  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 lim-
           ited 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  mes-
           sage. 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 con-
           tains 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 stan-
           dard 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 stan-
           dard severity levels listed below cannot be  modified.
           Additional  severity levels can also be defined, rede-
           fined,   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 sever-
     ity 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 deter-
           mine 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  attri-
     butes:

     ____________________________________________________________
    |       ATTRIBUTE TYPE        |       ATTRIBUTE VALUE       |
    |_____________________________|_____________________________|
    | MT-Level                    | Safe                        |
    |_____________________________|_____________________________|


SEE ALSO

     fmtmsg(1), addseverity(3C), gettxt(3C),  printf(3C),  attri-
     butes(5)


Man(1) output converted with man2html