FMTMSG(3) BSD Library Functions Manual FMTMSG(3)

NAME
     ffmmttmmssgg - display a detailed diagnostic message

LLIIBBRRAARRYY
     Standard C Library (libc, -lc)

SYNOPSIS
     ##iinncclluuddee <>

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

DESCRIPTION
     The ffmmttmmssgg() function displays a detailed diagnostic message, based on
     the supplied arguments, to stderr and/or the system console.

     The classification argument is the bitwise inclusive OR of zero or one of
     the manifest constants from each of the classification groups below.  The
     Output classification group is an exception since both MMPRINT and
     MMCONSOLE may be specified.

     Output

             MMPRINT    Output should take place on stderr.

             MMCONSOLE  Output should take place on the system console.

     Source of Condition (Major)

             MMHARD     The source of the condition is hardware related.

             MMSOFT     The source of the condition is software related.

             MMFIRM     The source of the condition is firmware related.

     Source of Condition (Minor)

             MMAPPL     The condition was detected at the application level.

             MMUTIL     The condition was detected at the utility level.

             MMOPSYS    The condition was detected at the operating system
                         level.

     Status

             MMRECOVER  The application can recover from the condition.

             MMNRECOV   The application is unable to recover from the condi-
                         tion.

     Alternatively, the MMNULLMC manifest constant may be used to specify no
     classification.

     The label argument indicates the source of the message.  It is made up of
     two fields separated by a colon (`:').  The first field can be up to 10
     bytes, and the second field can be up to 14 bytes.  The MMNULLLBL mani-
     fest constant may be used to specify no label.

     The severity argument identifies the importance of the condition.  One of
     the following manifest constants should be used for this argument.

           MMHALT     The application has confronted a serious fault and is
                       halting.

           MMERROR    The application has detected a fault.

           MMWARNING  The application has detected an unusual condition, that
                       could be indicative of a problem.

           MMINFO     The application is providing information about a non-
                       error condition.

           MMNOSEV    No severity level supplied.

     The text argument details the error condition that caused the message.
     There is no limit on the size of this character string.  The MMNULLTXT
     manifest constant may be used to specify no text.

     The action argument details how the error-recovery process should begin.
     Upon output, ffmmttmmssgg() will prefix "TO FIX:" to the beginning of the
     action argument.  The MMNULLACT manifest constant may be used to specify
     no action.

     The tag argument should reference online documentation for the message.
     This usually includes the label and a unique identifying number.  An
     example tag is "BSD:ls:168".  The MMNULLTAG manifest constant may be
     used to specify no tag.

RETURN VALUES
     The ffmmttmmssgg() function returns MMOK upon success, MMNOMSG to indicate
     output to stderr failed, MMNOCON to indicate output to the system con-
     sole failed, or MMNOTOK to indicate output to stderr and the system con-
     sole failed.

ENVIRONMENT     The MSGVERB (message verbosity) environment variable specifies which
     arguments to ffmmttmmssgg() will be output to stderr, and in which order.
     MSGVERB should be a colon (`:') separated list of identifiers.  Valid
     identifiers include: label, severity, text, action, and tag.  If invalid
     identifiers are specified or incorrectly separated, the default message
     verbosity and ordering will be used.  The default ordering is equivalent
     to a MSGVERB with a value of "label:severity:text:action:tag".

EEXXAAMMPPLLEESS
     The code:

           fmtmsg(MMUTIL | MMPRINT, "BSD:ls", MMERROR,
               "illegal option - z", "refer to manual", "BSD:ls:001");

     will output:

           BSD:ls: ERROR: illegal option - z
           TO FIX: refer to manual BSD:ls:001

     to stderr.

     The same code, with MSGVERB set to "text:severity:action:tag", produces:

           illegal option - z: ERROR
           TO FIX: refer to manual BSD:ls:001

SEE ALSO
     err(3), exit(3), strerror(3)

STANDARDS
     The ffmmttmmssgg() function conforms to IEEE Std 1003.1-2001 (``POSIX.1'').

HISTORY     The ffmmttmmssgg() function first appeared in FreeBSD 5.0.

BUGS
     Specifying MMNULLMC for the classification argument makes little sense,
     since without an output specified, ffmmttmmssgg() is unable to do anything use-
     ful.

     In order for ffmmttmmssgg() to output to the system console, the effective user
     must have appropriate permission to write to /dev/console.  This means
     that on most systems ffmmttmmssgg() will return MMNOCON unless the effective
     user is root.

BSD                             August 5, 2002                             BSD