#include <pfmt.h>

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

The lfmt() function 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. 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 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 indicates the message database that contains the localized version of the format string. This field is limited to 14 characters selected from a set of all characters values, excluding the null character (\e0) 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, lfmt() will attempt to retrieve the message from the C locale. If this second retrieval fails, lfmt() uses the <defmsg> field of the format argument.

If <catalog> 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:

:<msgnum>:<defmsg>.

The lfmt() function will output the message

Message not found!!\en

as the format string if <catalog> is not a valid catalog name, if no catalog is specified (either explicitly 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 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

Catalog access control

Severity (standard message format only)

Action

Console display control

Logging information

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 message is displayed in the format:

severity: text

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

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

-1

-2

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

Example 1 The following example

setlabel("UX:test");
lfmt(stderr, MM_ERROR|MM_CONSOLE|MM_SOFT|MM_UTIL,
 "test:2:Cannot open file: %s\en", 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\en");

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

UX:test: INFO: test facility enabled

See attributes(5) for descriptions of the following attributes:

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