Manual Pages for UNIX Operating System command usage for man lfmt

Standard C Library Functions                             lfmt(3C)



NAME
     lfmt - display error message in standard format and pass  to
     logging and monitoring services

SYNOPSIS
     #include 

     int lfmt(FILE *stream, long flags, char *format, ... /* arg*/);


DESCRIPTION
     The  lfmt()  function  retrieves  a  format  string  from  a
     locale-specific message database (unless  MM_NOGET is speci-
     fied) and uses it for printf(3C) style formatting  of  args.
     The  output  is  displayed  on stream. If stream is  NULL no
     output is displayed.


     The lfmt() function encapsulates the output in the  standard
     error  message  format  (unless   MM_NOSTD  is specified, in
     which case the output is like that of printf(). It  forwards
     its  output  to the logging and monitoring facility, even if
     stream is  NULL. Optionally, lfmt() displays the  output  on
     the console with a date and time stamp.


     If the printf() format string is to be retrieved from a mes-
     sage  database,  the format argument must have the following
     structure:


     ::.


     If  MM_NOGET is specified,  only the  field must  be
     specified.


     The  field indicates the message database that con-
     tains the localized version of the format string. This field
     is limited to 14 characters selected from a set of all char-
     acters  values,  excluding  the  null character (\0) and the
     ASCII codes for slash (/) and colon (:).


     The  field is a positive number that  indicates  the
     index of the string into the message database.


     If the catalog does not exist in the  locale  (specified  by
     the   last  call  to  setlocale(3C)  using  the   LC_ALL  or
     LC_MESSAGES categories), or if the message number is out  of



SunOS 5.11          Last change: 29 Dec 1996                    1






Standard C Library Functions                             lfmt(3C)



     bound,  lfmt() will attempt to retrieve the message from the
     C locale. If this second retrieval fails,  lfmt()  uses  the
      field of the format argument.


     If  is omitted, lfmt() will attempt to retrieve the
     string  from  the default catalog specified by the last call
     to setcat(3C). In this case, the  format  argument  has  the
     following structure:


     ::.


     The lfmt() function will output the message


     Message not found!!\n


     as the format string if  is  not  a  valid  catalog
     name,  if no catalog is specified (either explicitly or with
     setcat()), if  is not a valid number, or if no  mes-
     sage  could  be  retrieved  from  the  message databases and
      was omitted.


     The flags argument determines the type  of  output  (whether
     the format should be interpreted as it is or be encapsulated
     in the standard message format) and the  access  to  message
     catalogs to retrieve a localized version of format.


     The flags argument is composed of several  groups,  and  can
     take the following values (one from each group):

     Output format control


         MM_NOSTD    Do not use the standard message  format  but
                     interpret  format as a printf() format. Only
                     catalog  access   control   flags,   console
                     display   control  and  logging  information
                     should be specified if   MM_NOSTD  is  used;
                     all other flags will be ignored.


         MM_STD      Output using  the  standard  message  format
                     (default value is 0).






SunOS 5.11          Last change: 29 Dec 1996                    2






Standard C Library Functions                             lfmt(3C)



     Catalog access control


         MM_NOGET    Do not retrieve a localized version of  for-
                     mat.  In  this case, only the  field
                     of format is specified.


         MM_GET      Retrieve a localized version of format  from
                     ,  using    as the index and
                      as  the  default  message  (default
                     value is 0).



     Severity (standard message format only)


         MM_HALT       Generate a localized version of  HALT, but
                       donot halt the machine.


         MM_ERROR      Generate a  localized  version  of   ERROR
                       (default value is 0).


         MM_WARNING    Generate a localized version of  WARNING.


         MM_INFO       Generate a localized version of  INFO.

         Additional severities can be defined with the addsev(3C)
         function,  using number-string pairs with numeric values
         in the range [5-255]. The specified severity  is  formed
         by  the  bitwise  OR  operation of the numeric value and
         other flags arguments.

         If the severity is not defined, lfmt() uses  the  string
         SEV=N  where  N  is the integer severity value passed in
         flags.

         Multiple severities passed in flags will not be detected
         as  an  error.  Any  combination  of  severities will be
         summed and the numeric value will cause the  display  of
         either  a  severity  string  (if  defined) or the string
         SEV=N (if undefined).


     Action






SunOS 5.11          Last change: 29 Dec 1996                    3






Standard C Library Functions                             lfmt(3C)



         MM_ACTION    Specify an  action  message.  Any  severity
                      value  is  superseded  and  replaced  by  a
                      localized version of TO FIX.



     Console display control


         MM_CONSOLE      Display the message to  the  console  in
                         addition to the specified stream.


         MM_NOCONSOLE    Do not display the message to  the  con-
                         sole in addition to the specified stream
                         (default value is 0).



     Logging information


         Major classification

             Identify the source of  the  condition.  Identifiers
             are:  MM_HARD  (hardware),  MM_SOFT  (software), and
             MM_FIRM (firmware).


         Message source subclassification

             Identify the type of software in which  the  problem
             is  spotted. Identifiers are: MM_APPL (application),
             MM_UTIL (utility), and MM_OPSYS (operating system).



STANDARD ERROR MESSAGE FORMAT
     The lfmt() function displays error messages in the following
     format:

       label: severity: text



     If no label was defined by a call to setlabel(3C), the  mes-
     sage is displayed in the format:

       severity: text






SunOS 5.11          Last change: 29 Dec 1996                    4






Standard C Library Functions                             lfmt(3C)



     If lfmt() is called twice to display an error message and  a
     helpful action or recovery message, the output may appear as
     follows:

       label: severity: text
       label:  TO FIX: text


RETURN VALUES
     Upon successful completion, lfmt()  returns  the  number  of
     bytes transmitted.  Otherwise, it returns a negative value:

     -1       Write the error to stream.


     -2       Cannot log and/or display at console.


USAGE
     Since lfmt() uses gettxt(3C), it is recommended that  lfmt()
     not be used.

EXAMPLES
     Example 1 The following example

       setlabel("UX:test");
       lfmt(stderr, MM_ERROR|MM_CONSOLE|MM_SOFT|MM_UTIL,
            "test:2:Cannot open file: %s\n", strerror(errno));



     displays the message to stderr and to the console and  makes
     it available for logging:


       UX:test: ERROR: Cannot open file: No such file or directory


     Example 2 The following example

       setlabel("UX:test");
       lfmt(stderr, MM_INFO|MM_SOFT|MM_UTIL,
               "test:23:test facility is enabled\n");



     displays the message to stderr and makes  it  available  for
     logging:


       UX:test: INFO: test facility enabled




SunOS 5.11          Last change: 29 Dec 1996                    5






Standard C Library Functions                             lfmt(3C)



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



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


SEE ALSO
     addsev(3C), gettxt(3C),  pfmt(3C),  printf(3C),  setcat(3C),
     setlabel(3C), setlocale(3C), attributes(5), environ(5)







































SunOS 5.11          Last change: 29 Dec 1996                    6