pfmt(3C)


pfmt, vpfmt -- display error message in standard format

Synopsis

   #include <pfmt.h>
   

int pfmt(FILE *stream, long flags, char *format, . . . /* args */); #include <stdarg.h> #include <pfmt.h>

int vpfmt(FILE *stream, long flags, char *format, va_list ap);

Description

pfmt

pfmt uses a format string for printf style formatting of args. The output is displayed on stream. pfmt encapsulates the output in the standard error message format.

If the printf format string is to be retrieved from a message database, the format argument must have the following structure:

   [[catalog]:[msgnum]:]defmsg.

defmsg can only appear alone if flags include MM_NOGET.

catalog indicates the message database that contains the localized version of the format string. catalog must be limited to 14 characters. These characters must be selected from a set of all characters values, excluding \0 (null) and the ASCII codes for ``/'' (slash) and ``:'' (colon).

msgnum must be a positive number that indicates the index of the string into the message database.

If catalog does not exist in the locale (specified by the last call to setlocale using the LC_ALL or LC_MESSAGES categories), or if the message number is out of bounds, pfmt attempts to retrieve the message from the C locale. If this second retrieval fails, pfmt uses the defmsg part of the format argument.

If catalog is omitted, pfmt attempts to retrieve the string from the default catalog specified by the last call to setcat. In this case, the format argument has the following structure:

   msgnum:defmsg.

pfmt outputs

   Message not found!! . . .

as the format string if:

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

The flags are 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, interpret format as a printf format. Only ``catalog access control flags'' should be specified if MM_NOSTD is used; all other flags will be ignored.

MM_STD
output using the standard message format (default, value 0).

Catalog access control

MM_NOGET
do not retrieve a localized version of format. In this case, only the defmsg part of the format is specified.

MM_GET
retrieve a localized version of format, from the catalog, using msgnum as the index and defmsg as the default message (default, value 0).

Severity (standard message format only)

MM_HALT
generates a localized version of HALT.

MM_ERROR
generates a localized version of ERROR (default, value 0).

MM_WARNING
generates a localized version of WARNING.

MM_INFO
generates 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 numeric value ORed with other flags will generate the specified severity.

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 severity string (if defined) or the string SEV=N (if undefined).


Action

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

Standard error message format

pfmt displays error messages in the following format:
   label: severity: text

If no label was defined by a call to setlabel, the message 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 like:

   label: severity: text
   label: TO FIX: text

vpfmt

vpfmt is the same as pfmt except that instead of being called with a variable number of arguments, it is called with an argument list as defined by the stdarg.h header file.

The stdarg.h header file defines the type va_list and a set of macros for advancing through a list of arguments whose number and types may vary. The argument ap to vpfmt is of type va_list. This argument is used with the stdarg.h header file macros va_start, va_arg and va_end [see va_start, va_arg, and va_end in stdarg(5)]. The USAGE sections below show their use.

The macro va_alist is used as the parameter list in a function definition as in the function called error in the example below. The macro

   va_start(ap, )

where ap is of type va_list, must be called before any attempt to traverse and access unnamed arguments. Calls to

   va_arg(ap, atype)

traverse the argument list. Each execution of va_arg expands to an expression with the value and type of the next argument in the list ap, which is the same object initialized by va_start. The argument atype is the type that the returned argument is expected to be.

The

   va_end(ap)

macro must be invoked when all desired arguments have been accessed. [The argument list in ap can be traversed again if va_start is called again after va_end.] In the example below, va_arg is executed first to retrieve the format string passed to error. The remaining error arguments, arg1, arg2, . . ., are given to vpfmt in the argument ap.

Return values

On success, pfmt and vpfmt return the number of bytes transmitted. On failure, they return a negative value:

Errors


-1
write error to stream

Usage

pfmt example 1

setlabel("UX:test");
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

pfmt example 2

setlabel("UX:test");
setcat("test");
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 ...

vpfmt example

The following demonstrates how vpfmt could be used to write an error routine:
   #include <pfmt.h>
   #include <stdarg.h>
   . . .
   /*
    *   error should be called like
    *         error(format, arg1, ...);
    */
   void error(const char *format, ...)
   

{ va_list ap;

va_start(ap, ); (void) vpfmt(stderr, MM_ERROR, format, ap); va_end(ap); (void) abort(); }

References

addsev(3C), environ(5), fprintf(3S), gettxt(3C), lfmt(3C), pfmt(1), setcat(3C), setlabel(3C), setlocale(3C), stdarg(5)
© 2004 The SCO Group, Inc. All rights reserved.
UnixWare 7 Release 7.1.4 - 25 April 2004