NAME    [Toc]    [Back]

     fmtmsg - format and display a message

LIBRARY    [Toc]    [Back]

     Standard C Library (libc, -lc)

SYNOPSIS    [Toc]    [Back]

     #include <fmtmsg.h>

     int
     fmtmsg(long classification, const char *label, int severity,
             const char *text, const char *action, const char *tag);

DESCRIPTION    [Toc]    [Back]

     The fmtmsg() function can be used to display messages in the specified
     format.  Messages may be written either to standard error, to the console,
 or both.

     A formatted message consists of up to five components specified in label,
     severity, text, action and tag.  Further information such as the origin
     of the message, the recoverability from the condition causing the message
     and where to display the message is specified in classification.

   classification
     The classification argument consists of a major classification and several
 sub-classifications.  It has no effect on the content of the message
     displayed.  With the exception of the display sub-classification, only a
     single identifier may be specified for each (sub-)classification.  The
     following classifications are available:

     Major Classifications                 The source of the condition.
                                           Available identifiers are: MM_HARD
                                           (hardware), MM_SOFT (software), and
                                           MM_FIRM (firmware).

     Message Source Sub-classifications    The type of software detecting the
                                           condition.  Available identifiers
                                           are: MM_APPL (application), MM_UTIL
                                           (utility), and MM_OPSYS (operating
                                           system).

     Display Sub-classifications           The displays the formatted messages
                                           is to be written to.  Available
                                           identifiers are: MM_PRINT (standard
                                           error stream) and MM_CONSOLE (system
 console).

     Status Sub-classifications            The capability of the calling software
 to recover from the condition.
                                           Available identifiers are:
                                           MM_RECOVER (recoverable) and
                                           MM_NRECOV (non-recoverable).

     If no classification is to be supplied, MM_NULLMC must be specified.

   label
     The label argument identifies the source of the message.  It consists of
     two fields separated by a colon (:).  The first field is up to 10 characters,
 the second is up to 14 characters.

     If no label is to be supplied, MM_NULLLBL must be specified.

   severity
     The seriousness of the condition causing the message.  The following
     severity levels are available:

     MM_HALT       The software has encountered a severe fault and is halting.

     MM_ERROR      The software has encountered a fault.

     MM_WARNING    The software has encountered an unusual non-fault condition.


     MM_INFO       The software informs about a non-error condition.

     If no severity level is to be supplied, MM_NOSEV must be specified.

   text
     The description of the condition the software encountered.  The character
     string is not limited to a specific size.

     If no text is to be supplied, MM_NOTXT must be specified.

   action
     The first step to be taken to recover from the condition the software
     encountered; it will be preceded by the prefix ``TO FIX:''.  The character
 string is not limited to a specific size.

     If no action is to be supplied, MM_NOACT must be specified.

   tag
     The on-line documentation which provides further information about the
     condition and the message, such as ``fmtmsg(3)''.  The character string
     is not limited to a specific size.

     If no tag is to be supplied, MM_NOTAG must be specified.

     Further effect on the formatting of the message as displayed on the standard
 error stream (but not on the system console!) may be taken by setting
 the MSGVERB environment variable, which selects the subset of message
 components to be printed.  It consists of a colon-separated list of
     the optional keywords label, severity, text, action, and tag, which correspond
 to the arguments to fmtmsg() with the same names.  If MSGVERB is
     either not set or malformed (containing empty or unknown keywords), its
     content is ignored an all message components will be selected.

     Note that displaying a message on the system console may fail due to
     inappropriate privileges or a non-permissive file mode of the console
     device.

RETURN VALUES    [Toc]    [Back]

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

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

SEE ALSO    [Toc]    [Back]

     printf(3), syslog(3)

STANDARDS    [Toc]    [Back]

     The fmtmsg() function conforms to X/Open System Interfaces and Headers
     Issue 5 (``XSH5'').

BSD                           September 10, 1999                           BSD