pfmt(3C) DG/UX 5.4R3.00 pfmt(3C)
NAME
pfmt - display error message in standard format
SYNOPSIS
#include <pfmt.h>
int pfmt(FILE *stream, long flags, char *format, ... /* arg */);
DESCRIPTION
Pfmt() retrieves a format string from a locale-specific message
database (unless MMNOGET is specified) and uses it for printf()
style formatting of args. The output is displayed on stream.
pfmt() encapsulates the output in the standard error message format
(unless MMNOSTD is specified, in which case the output is simply
printf() like).
If the printf() format string is to be retrieved from a message
database, the format argument must have the following structure:
<catalog>:<msgnum>:<defmsg>.
If MMNOGET is specified, only the <defmsg> part must be specified.
<catalog> is used to indicate 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> 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() using the LCALL or LCMESSAGES categories), or
if the message number is out of bounds, pfmt() will attempt 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() will attempt 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() will output Message not found!!\n as the format string if
<catalog> is not a valid catalog name, if no catalog is specified
(either explicitly or via 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 determine the type of output (i.e. 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.
Licensed material--property of copyright holder(s) 1
pfmt(3C) DG/UX 5.4R3.00 pfmt(3C)
The flags are composed of several groups, and can take the following
values (one from each group):
Output format control
MMNOSTD Do not use the standard message format,
interpret format as a printf() format. Only
catalog access control flags should be
specified if MMNOSTD is used; all other flags
will be ignored
MMSTD Output using the standard message format
(default, value 0).
Catalog access control
MMNOGET Do not retrieve a localized version of format.
In this case, only the <defmsg> part of the
format is specified.
MMGET Retrieve a localized version of format, from
the <catalog>, using <msgid> as the index and
<defmsg> as the default message (default,
value 0).
Severity (standard message format only)
MMHALT generates a localized version of HALT.
MMERROR generates a localized version of ERROR
(default, value 0).
MMWARNING generates a localized version of WARNING.
MMINFO 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(). The numeric value ORed
with other flags will generate the specified severity.
If the severity is not defined, pfmt() used 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
MMACTION specifies an action message. Any severity
value is superseded and replaced by a
Licensed material--property of copyright holder(s) 2
pfmt(3C) DG/UX 5.4R3.00 pfmt(3C)
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
Considerations for Threads Programming
+---------+-----------------------------+
| | async- |
|function | reentrant cancel cancel |
| | point safe |
+---------+-----------------------------+
|pfmt | Y Y N |
+---------+-----------------------------+
EXAMPLES
Example 1:
setlabel("UX:test");
pfmt(stderr, MMERROR, "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:
setlabel("UX:test");
setcat("test");
pfmt(stderr, MMERROR, ":10:Syntax error\n");
pfmt(stderr, MMACTION, "55:Usage ...\n");
displays the message
UX:test: ERROR: Syntax error
UX:test: TO FIX: Usage ...
RETURN VALUE
Upon success, pfmt() returns the number of bytes transmitted. Upon
failure, it returns a negative value:
-1 write error to stream.
SEE ALSO
pfmt(1), reentrant(3), addsev(3C), gettxt(3C), lfmt(3C), printf(3S),
setcat(3C), setlabel(3C), setlocale(3C), environ(5).
Licensed material--property of copyright holder(s) 3