pfmt - display error message in standard format


     #include <pfmt.h>

     int pfmt(FILE *stream, long flags, char *format, ... /*  arg


     The pfmt() retrieves a format string from a  locale-specific
     message  database (unless MM_NOGET is specified) and uses it
     for printf(3C) style  formatting  of  args.  The  output  is
     displayed on stream.

     The pfmt() function encapsulates the output in the  standard
     error message format (unless MM_NOSTD is specified, in which
     case the output is similar to printf()).

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


     If MM_NOGET is specified, only  the  defmsg  field  must  be

     The catalog field is used to indicate the  message  database
     that  contains  the  localized version of the format string.
     This field must be limited to 14  characters  selected  from
     the  set  of  all characters values, excluding \0 (null) and
     the ASCII codes for / (slash) and : (colon).

     The msgnum 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
     bound,  pfmt() will attempt to retrieve the message from the
     C locale. If this second retrieval fails,  pfmt()  uses  the
     defmsg field of the format argument.

     If catalog is omitted, pfmt() 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 pfmt() will  output  Message  not  found!!\n  as  format
     string if catalog is not a valid catalog name, if no catalog
     is specified  (either  explicitely  or  with  setcat()),  if
     msgnum  is  not  a  valid  number, or if no message could be
     retrieved from the message databases and defmsg was omitted.

     The flags argument determine the type  of  output  (such  as
     whether  the  format should be interpreted as is or encapsu-
     lated 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

           Do not use the standard message format, interpret for-
           mat  as  printf()  format. Only catalog access control
           flags should be specified if  MM_NOSTD  is  used;  all
           other flags will be ignored.

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

     Catalog access control

           Do not retrieve a localized  version  of  format.   In
           this  case,  only  the  defmsg  field of the format is

           Retrieve a localized version of format from the  cata-
           log,  using  msgid  as  the  index  and  defmsg as the
           default message (default value 0).

     Severity (standard message format only)

           Generate a localized version of HALT, but do not  halt
           the machine.

           Generate a localized version of ERROR  (default  value

           Generate a localized version of WARNING.

           Generate a localized version of INFO.

     Additional severities can be defined. Add-on severities  can
     be defined with number-string pairs with numeric values from
     the range [5-255], using addsev(3C). The specified  severity
     will  be  generated  from  the  bitwise  OR operation of the
     numeric value  and  other  flags  If  the  severity  is  not
     defined,  pfmt()  uses the string SEV=N, where N is replaced
     by 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  sever-
     ity string (if defined) or the string SEV=N (if undefined).


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


     The pfmt() function displays error messages in the following

     label: severity: text

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

     severity: text

     If pfmt() is called twice to display an error message and  a
     helpful  action  or  recovery  message,  the output can look

     label: severity: textlabel: TO FIX: text


     Upon success, pfmt() returns the number of  bytes  transmit-
     ted. Upon failure, it returns a negative value:

     -1    Write error to stream.


     Example 1: Example of pfmt() function.

     Example 1:

     pfmt(stderr, MM_ERROR, "test:2:Cannot open file: %s\n", strerror(errno));

     displays the message:

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

     Example 2:

     pfmt(stderr, MM_ERROR, ":10:Syntax error\n");
     pfmt(stderr, MM_ACTION, "55:Usage ...\n");

     displays the message

     UX:test: ERROR: Syntax error
     UX:test: TO FIX: Usage ...


     Since it uses gettxt(3C), pfmt() should not be used.


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

    |       ATTRIBUTE TYPE        |       ATTRIBUTE VALUE       |
    | MT-Level                    | MT-safe                     |


     addsev(3C), gettxt(3C),  lfmt(3C),  printf(3C),  setcat(3C),
     setlabel(3C), setlocale(3C), attributes(5), environ(5)

Man(1) output converted with man2html