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);
DESCRIPTIONlfmt 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.
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:
Page 1
lfmt(3C)lfmt(3C)
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.
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.
Page 2
lfmt(3C)lfmt(3C)
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.
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:
Page 3
lfmt(3C)lfmt(3C)
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.
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 EXAMPLE sections 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.
EXAMPLESlfmt 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
lfmt 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:
Page 4
lfmt(3C)lfmt(3C)
#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();
}
SEE ALSOlfmt(1), pfmt(1), addsev(3C), gettxt(3C), setcat(3C), setlabel(3C),
setlocale(3C), printf(3S), environ(5), stdarg(5)DIAGNOSTICS
On success, lfmt and vlfmt return the number of bytes transmitted. On
failure, they return a negative value:
-1 write error to stream
-2 cannot log and/or display at console.
Page 5
