pfmt(3C)pfmt(3C)NAME
pfmt(), vpfmt() - display message in standard format
SYNOPSIS DESCRIPTION
The system call can be used to write a message in standard format to stream. It can also be used to write a localized string to stream.
The arguments to are formatted using style formatting. is similar to except that the arguments are passed in an argument list (see
stdarg(5)).
The standard format displayed on stream has the following fields:
The label string is defined through setlabel(3C). If no label is defined, this field is not used. The severity string is controlled by
the severity group of flags. The text string is the formatted user string.
The flags control how formatting is done. The control information is separated into several different groups. Only one flag from each
group should be set.
Output Format
Do not use the standard format.
Treat fmt as a format string. In this mode, only flags related to catalog access can be set.
Format using the standard format
is the default).
Catalog Access
Do not access the localized message catalog.
Use the def_str (a field in fmt) as the format string.
Access the localized message catalog
is the default).
Severity
Display a localized string.
Display a localized string is the default).
Display a localized string.
Display a localized string.
Besides these reserved severities, additional severity strings may be defined by the user (see addsev(3C)). To specify a
user defined severity, flags should be a logical-or of the numeric value of the user defined severity and flags from other
control groups.
Action
This flag generates the localized string of
in the severity field of the standard format message. If this flag and flags from the severity control
group are set, this flag has precedence and the string will be displayed.
The fmt string has the following fields:
The catalog is the message catalog created by mkmsgs(1) where the localized message is to be retrieved. The msg_number is a positive index
number identifying the string to be retrieved from the message catalog (begins at 1). The def_str is the default string to use if fails to
retrieve the message from catalog from either the current locale or the default locale. The failure may occur if the message catalog does
not exist or if the msg_number is out of bound.
If catalog is not specified, uses the message catalog defined by setcat(3C). If is set in flags, only def_str must be specified.
The system call displays under the following conditions:
o No message catalog is specified in fmt and no catalog is defined via setcat(3C).
o msg_number is not positive.
o No message could be retrieved and def_str is not specified.
RETURN VALUE
If successful, and return the number of bytes written. Otherwise, they return a negative value.
EXAMPLES
Example 1
generates the message:
Example 2
generates the message:
Example 3
generates the message:
Example 4
generates the message:
SEE ALSO mkmsgs(1), addsev(3C), gettxt(3C), printf(3S), setcat(3C), setlabel(3C), setlocale(3C), stdarg(5), thread_safety(5).
STANDARDS CONFORMANCE pfmt(3C)
Check Out this Related Man Page
pfmt(3C) Standard C Library Functions pfmt(3C)NAME
pfmt - display error message in standard format
SYNOPSIS
#include <pfmt.h>
int pfmt(FILE *stream, long flags, char *format, ... /* arg */);
DESCRIPTION
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 message database, the format argument must have the following structure:
<catalog>:<msgnum>:<defmsg>.
If MM_NOGET is specified, only the defmsg field must be specified.
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 (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:
:<msgnum>:<defmsg>.
The pfmt() will output Message not found!!
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 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, interpret format as 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 field of the format is specified.
MM_GET 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)
MM_HALT Generate a localized version of HALT, but do not halt the machine.
MM_ERROR Generate a localized version of ERROR (default value 0).
MM_WARNING Generate a localized version of WARNING.
MM_INFO 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 sever-
ity 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 Specify an action message. Any severity value is superseded and replaced by a localized version of TO FIX.
STANDARD ERROR MESSAGE FORMAT
The pfmt() function displays error messages in the following format:
label: severity: text
If no label was defined by a call to setlabel(3C), 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: textlabel: TO FIX: text
RETURN VALUES
Upon success, pfmt() returns the number of bytes transmitted. Upon failure, it returns a negative value:
-1 Write error to stream.
EXAMPLES
Example 1: Example of pfmt() function.
Example 1:
setlabel("UX:test");
pfmt(stderr, MM_ERROR, "test:2:Cannot open file: %s
", 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, MM_ERROR, ":10:Syntax error
");
pfmt(stderr, MM_ACTION, "55:Usage ...
");
displays the message
UX:test: ERROR: Syntax error
UX:test: TO FIX: Usage ...
USAGE
Since it uses gettxt(3C), pfmt() should not be used.
ATTRIBUTES
See attributes(5) for descriptions of the following attributes:
+-----------------------------+-----------------------------+
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
+-----------------------------+-----------------------------+
|MT-Level |MT-safe |
+-----------------------------+-----------------------------+
SEE ALSO addsev(3C), gettxt(3C), lfmt(3C), printf(3C), setcat(3C), setlabel(3C), setlocale(3C), attributes(5), environ(5)SunOS 5.10 29 Dec 1996 pfmt(3C)