LFMT(3C-SVR4) RISC/os Reference Manual LFMT(3C-SVR4)
NAME
lfmt - display error message in standard format and pass to
logging and monitoring services
SYNOPSIS
#include <pfmt.h>
int lfmt(FILE *stream, long flags, char *format, ... /* arg */);
DESCRIPTION
lfmt() retrieves a format string from a locale-specific mes-
sage database (unless MM_NOGET is specified) and uses it for
printf() style formatting of args. The output is displayed
on stream. If stream is NULL, no output is displayed.
lfmt() encapsulates the output in the standard error message
format (unless MM_NOSTD is specified, in which case the out-
put is simply printf() like).
lfmt() forwards its output to the logging and monitoring
facility, even if stream is NULL. Optionally, lfmt() will
display the output on the console, with a date and time
stamp.
If the printf() format string is to be retrieved from a mes-
sage database, the format argument must have the following
structure:
<catalog>:<msgnum>:<defmsg>.
If MM_NOGET is specified, only the <defmsg> part must be
specified.
<catalog> is used to indicate the message database that con-
tains 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 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> part 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(). In this case, the format argument has the fol-
lowing structure:
Printed 11/19/92 Page 1
LFMT(3C-SVR4) RISC/os Reference Manual LFMT(3C-SVR4)
:<msgnum>:<defmsg>.
lfmt() will output
Message not found!!\n
as 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 mes-
sage 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.
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, con-
sole display control and logging infor-
mation should be specified if MM_NOSTD
is used; all other flags will be
ignored
MM_STD Output using the standard message for-
mat (default, value 0).
Page 2 Printed 11/19/92
LFMT(3C-SVR4) RISC/os Reference Manual LFMT(3C-SVR4)
Catalog access control
MM_NOGET Do not retrieve a localized version of
format. In this case, only the
<defmsg> part of the format is speci-
fied.
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 generates a localized version of HALT.
MM_ERROR generates a localized version of ERROR
(default, value 0).
MM_WARNING generates a localized version of WARN-
ING.
MM_INFO generates a localized version of INFO.
Additional severities can be defined. Add-on severi-
ties can be defined with number-string pairs with
numeric values from the range [5-255], using addsev().
The numeric value, OR-ed with other fIflags, will gen-
erate the specified severity.
If the severity is not defined, lfmt() used the string
SEV=N where N is replaced by the integer severity value
passed in flags.
Multiple severities passed inf 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.
Console display control
MM_CONSOLE display the message to the console in
addition to the specified stream.
Printed 11/19/92 Page 3
LFMT(3C-SVR4) RISC/os Reference Manual LFMT(3C-SVR4)
MM_NOCONSOLE do not display the message to the con-
sole in addition to the specified
stream (default, value 0).
Logging information
Major classification
Identifies the source of the condition.
Identifiers are: MM_HARD (hardware),
MM_SOFT (software), and MM_FIRM
(firmware).
Message source subclassification
Identifies the type of software in
which the problem is spotted. Identif-
iers are: MM_APPL (application),
MM_UTIL (utility), and MM_OPSYS
(operating system).
STANDARD ERROR MESSAGE FORMAT
lfmt() 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 lfmt() 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
RETURN VALUE
Upon success, lfmt() returns the number of bytes transmit-
ted. Upon failure, it returns a negative value:
-1 write error to stream.
-2 cannot log and/or display at console.
EXAMPLES
Example 1:
setlabel("UX:test");
lfmt(stderr, MM_ERROR|MM_CONSOLE|MM_SOFT|MM_UTIL,
"test:2:Cannot open file: %s\n", 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
Page 4 Printed 11/19/92
LFMT(3C-SVR4) RISC/os Reference Manual LFMT(3C-SVR4)
Example 2:
setlabel("UX:test");
lfmt(stderr, MM_INFO|MM_SOFT|MM_UTIL,
"test:23:test facility is enabled\n");
displays the message to stderr and makes it available for
logging:
UX:test: INFO: test facility enabled
SEE ALSO
addsev(3C-SVR4), environ(5-SVR4), gettxt(3C-SVR4), pfmt(3C-
SVR4), printf(3C-SVR4), setcat(3C-SVR4), setlabel(3C-SVR4),
setlocale(3C-SVR4).
lfmt(1) in the User's Reference Manual.
Printed 11/19/92 Page 5