lfmt(3C) lfmt(3C)
NAME
lfmt, vlfmt - 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, . . . /* args */);
#include <stdarg.h>
#include <pfmt.h>
int vlfmt(FILE *stream, long flags, char *format, va_list ap);
DESCRIPTION
lfmt
lfmt retrieves a format string from a locale-specific message
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 output is simply
printf-like).
lfmt forwards its output to the logging and monitoring
facility, even if stream is null. lfmt will also display the
output on the console, with a date and time stamp, when
MM_CONSOLE is specified (see below).
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 part must be
specified.
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 character 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.
Copyright 1994 Novell, Inc. Page 1
lfmt(3C) lfmt(3C)
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, lfmt attempts 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 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.
lfmt outputs
Message not found!!\n
as the format string if:
catalog is not a valid catalog name as defined above
no catalog is specified (either explicitly or via
setcat)
msgnum is not a positive number
if no message could be retrieved from the message
databases and defmsg was omitted
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, console
display control, and logging information
should be specified if MM_NOSTD is used;
all other flags will be ignored.
Copyright 1994 Novell, Inc. Page 2
lfmt(3C) lfmt(3C)
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, lfmt 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.
Copyright 1994 Novell, Inc. Page 3
lfmt(3C) lfmt(3C)
Console display control
MM_CONSOLE display the message to the console in
addition to the specified stream.
MM_NOCONSOLE do not display the message to the
console 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. Identifiers 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
vlfmt
vlfmt is the same as lfmt 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.
Copyright 1994 Novell, Inc. Page 4
lfmt(3C) lfmt(3C)
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 vlfmt 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 section 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 vlfmt in the
argument ap.
Return Values
On success, lfmt and vlfmt return the number of bytes
transmitted. On failure, they return a negative value.
Errors
-1 write error to stream
-2 cannot log and/or display at console.
USAGE
lftmt Example 1
setlabel("UX:test");
lfmt(stderr, MM_ERROR|MM_CONSOLE|MM_SOFT|MM_UTIL,
"test:2:Cannot open file: %s\n", strerror(errno));
Copyright 1994 Novell, Inc. Page 5
lfmt(3C) lfmt(3C)
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
lftmt 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
vlfmt Example
The following demonstrates how vlfmt could be used to write an
errlog routine:
#include <pfmt.h>
#include <stdarg.h>
. . .
/*
* errlog should be called like
* errlog(log_info, format, arg1, ...);
*/
void errlog(long log_info, const char *format, ...)
{
va_list ap;
va_start(ap, format);
(void) vlfmt(stderr, log_info|MM_ERROR, format, ap);
va_end(ap);
(void) abort();
}
REFERENCES
addsev(3C), environ(5), fprintf(3S), gettxt(3C), lfmt(1),
pfmt(1), setcat(3C), setlabel(3C), setlocale(3C), stdarg(5)
Copyright 1994 Novell, Inc. Page 6