346 lines
9.7 KiB
Plaintext
346 lines
9.7 KiB
Plaintext
'\"macro stdmacro
|
|
.if n .pH g3c.lfmt @(#)lfmt 41.12 of 5/26/91
|
|
.\" Copyright 1991 UNIX System Laboratories, Inc.
|
|
.\" Copyright 1990 AT&T
|
|
.nr X
|
|
.if \nX=0 .ds x} lfmt 3C "" "\&"
|
|
.if \nX=1 .ds x} lfmt 3C ""
|
|
.if \nX=2 .ds x} lfmt 3C "" "\&"
|
|
.if \nX=3 .ds x} lfmt "" "" "\&"
|
|
.TH \*(x}
|
|
.SH NAME
|
|
\f4lfmt\f1, \f4vlfmt\f1 \- display error message in standard format and pass to logging and monitoring services
|
|
.SH SYNOPSIS
|
|
\f4#include <pfmt.h>\f1
|
|
.P
|
|
.nf
|
|
\f4int lfmt(FILE \(**\f2stream\f4, long \f2flags\f4, char \(**\f2format\f4, . . . /\(** \f2args\f4 \(**/);
|
|
.sp
|
|
.ft 4
|
|
.nf
|
|
#include <stdarg.h>
|
|
#include <pfmt.h>
|
|
.P
|
|
.nf
|
|
\f4int vlfmt(FILE \(**\f2stream\f4, long \f2flags\f4, char \(**\f2format\f4, va_list \f2ap\f4);
|
|
.ft 1
|
|
.fi
|
|
.SH DESCRIPTION
|
|
\f4lfmt\f1 retrieves a format string from a locale-specific message
|
|
database (unless \f4MM_NOGET\f1 is specified)
|
|
and uses it for \f4printf\f1 style formatting of \f2args\f1.
|
|
The output is displayed on \f2stream\f1.
|
|
If \f2stream\f1 is \f4NULL\f1, no output is displayed.
|
|
\f4lfmt\f1 encapsulates the output in the standard error message format
|
|
(unless \f4MM_NOSTD\f1 is specified,
|
|
in which case the output is simply \f4printf\f1-like).
|
|
.P
|
|
\f4lfmt\f1 forwards
|
|
its output to the logging and monitoring facility, even if \f2stream\f1
|
|
is null.
|
|
\f4lfmt\f1 will also display the output on the console, with a
|
|
date and time stamp, when \f4MM_CONSOLE\f1 is specified (see below).
|
|
.P
|
|
If the \f4printf\f1 format string is to be retrieved from a message
|
|
database, the \f2format\f1 argument must have the following structure:
|
|
.P
|
|
.RS
|
|
\f4[\f2catalog\f4:]\f2msgnum\f4:\f2defmsg\f1.
|
|
.RE
|
|
.P
|
|
If \f4MM_NOGET\f1 is specified,
|
|
only the \f2defmsg\f1
|
|
part must be specified.
|
|
.P
|
|
\f2catalog\f1 indicates the message database that contains
|
|
the localized version of the format string.
|
|
\f2catalog\f1 must be limited to 14 characters.
|
|
These characters must be selected from a set of all character values,
|
|
excluding \f4\\0\f1 (null) and the ASCII codes for \f4/\f1 (slash) and
|
|
\f4:\f1 (colon).
|
|
.P
|
|
\f2msgnum\f1 must be a positive number that indicates the index of the string
|
|
into the message database.
|
|
.P
|
|
If \f2catalog\f1 does not exist in the locale (specified by the last call to
|
|
\f4setlocale\f1 using the \f4LC_ALL\f1 or \f4LC_MESSAGES\f1
|
|
categories), or if the message number is out of bounds,
|
|
\f4lfmt\f1 attempts to retrieve the message from the \f4C\f1 locale.
|
|
If this second retrieval fails, \f4lfmt\f1 uses the \f2defmsg\f1
|
|
part of the \f2format\f1 argument.
|
|
.P
|
|
If \f2catalog\f1 is omitted, \f4lfmt\f1 attempts to retrieve the
|
|
string from the default catalog specified by the last call to \f4setcat\f1.
|
|
In this case, the \f2format\f1 argument has the following structure:
|
|
.P
|
|
.RS
|
|
\f4\f2msgnum\f4:\f2defmsg\f1.
|
|
.RE
|
|
.P
|
|
\f4lfmt\f1 outputs \f4Message not found!!\f2\en\f1 as the format string if:
|
|
.RS
|
|
.TP .25i
|
|
\-
|
|
\f2catalog\f1 is not a valid catalog name as defined above
|
|
.TP .25i
|
|
\-
|
|
no catalog is specified (either explicitly or via \f4setcat\f1)
|
|
.TP .25i
|
|
\-
|
|
\f2msgnum\f1 is not a positive number
|
|
.TP .25i
|
|
\-
|
|
if no message could be retrieved from the message databases and
|
|
\f2defmsg\f1 was omitted
|
|
.RE
|
|
.P
|
|
The \f2flags\f1 determine the type of output (that is, whether the \f2format\f1
|
|
should be interpreted as is or encapsulated in the standard message format),
|
|
and the access to message catalogs to retrieve a localized version of \f2format\f1.
|
|
The \f2flags\f1 are composed of several groups, and can take the following
|
|
values (one from each group):
|
|
.P
|
|
.I "Output format control"
|
|
.RS
|
|
.TP 13
|
|
\f4MM_NOSTD\f1
|
|
do not use the standard message format, interpret \f2format\f1
|
|
as a \f4printf\f1 \f2format\f1.
|
|
Only \f2catalog access control flags\f1,
|
|
\f2console display control\f1, and \f2logging information\f1
|
|
should be specified if \f4MM_NOSTD\f1
|
|
is used;
|
|
all other flags will be ignored.
|
|
.TP 13
|
|
\f4MM_STD\f1
|
|
output using the standard message format (default, value 0).
|
|
.RE
|
|
.P
|
|
.I "Catalog access control"
|
|
.RS
|
|
.TP 13
|
|
\f4MM_NOGET\f1
|
|
do not retrieve a localized version of \f2format\f1.
|
|
In this case, only the \f2defmsg\f1 part of the \f2format\f1 is specified.
|
|
.TP 13
|
|
\f4MM_GET\f1
|
|
retrieve a localized version of \f2format\f1, from the \f2catalog\f1, using
|
|
\f2msgnum\f1 as the index and \f2defmsg\f1 as the default message (default,
|
|
value 0).
|
|
.RE
|
|
.P
|
|
.I "Severity (standard message format only)"
|
|
.RS
|
|
.TP 13
|
|
\f4MM_HALT\f1
|
|
generates a localized version of \f4HALT\f1.
|
|
.TP 13
|
|
\f4MM_ERROR\f1
|
|
generates a localized version of \f4ERROR\f1 (default, value 0).
|
|
.TP 13
|
|
\f4MM_WARNING\f1
|
|
generates a localized version of \f4WARNING\f1.
|
|
.TP 13
|
|
\f4MM_INFO\f1
|
|
generates a localized version of \f4INFO\f1.
|
|
.P
|
|
Additional severities can be defined.
|
|
Add-on severities can be defined with number-string pairs with numeric
|
|
values from the range [5-255], using \f4addsev\f1(3C).
|
|
The numeric value ORed with other \f2flags\f1 will generate the specified
|
|
severity.
|
|
.P
|
|
If the severity is not defined, \f4lfmt\f1 uses the string \f4SEV=\f2N\f1
|
|
where \f2N\f1 is replaced by the integer severity value passed in \f2flags\f1.
|
|
.P
|
|
Multiple severities passed in \f2flags\f1 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
|
|
\f4SEV=\f2N\f1 (if undefined).
|
|
.RE
|
|
.P
|
|
.I "Action"
|
|
.RS
|
|
.TP 13
|
|
\f4MM_ACTION\f1
|
|
specifies an action message.
|
|
Any severity value is superseded and replaced by a localized version of
|
|
\f4TO FIX\f1.
|
|
.RE
|
|
.br
|
|
.ne 1.25i
|
|
.P
|
|
.I "Console display control"
|
|
.RS
|
|
.TP 16
|
|
\f4MM_CONSOLE\f1
|
|
display the message to the console in addition to the specified \f2stream\f1.
|
|
.TP 16
|
|
\f4MM_NOCONSOLE\f1
|
|
do not display the message to the console in addition to the specified
|
|
\f2stream\f1 (default, value 0).
|
|
.RE
|
|
.TP 3
|
|
.I "Logging information"
|
|
.RS
|
|
.TP 10
|
|
\f2Major classification\f1
|
|
identifies the source of the condition.
|
|
Identifiers are:
|
|
\f4MM_HARD\f1 (hardware),
|
|
\f4MM_SOFT\f1 (software), and
|
|
\f4MM_FIRM\f1 (firmware).
|
|
.TP 10
|
|
\f2Message source subclassification\f1
|
|
identifies the type of software in which the problem is spotted.
|
|
Identifiers are:
|
|
\f4MM_APPL\f1 (application),
|
|
\f4MM_UTIL\f1 (utility), and
|
|
\f4MM_OPSYS\f1 (operating system).
|
|
.RE
|
|
.SS "Standard Error Message Format"
|
|
\f4lfmt\f1 displays error messages in the following format:
|
|
.P
|
|
.RS
|
|
\f2label\f4: \f2severity\f4: \f2text\f1
|
|
.RE
|
|
.P
|
|
If no \f2label\f1 was defined by a call to \f4setlabel\f1, the message
|
|
is displayed in the format:
|
|
.P
|
|
.RS
|
|
\f2severity\f4: \f2text\f1
|
|
.RE
|
|
.P
|
|
If \f4lfmt\f1 is called twice to display an error message and a helpful
|
|
\f2action\f1 or recovery message, the output can look like:
|
|
.P
|
|
.RS
|
|
\f2label\f4: \f2severity\f4: \f2text\f1
|
|
.br
|
|
\f2label\f4: TO FIX: \f2text\f1
|
|
.RE
|
|
.SS "vlfmt"
|
|
\f4vlfmt\f1 is the same as \f4lfmt\f1
|
|
except that instead of being called with a variable
|
|
number of arguments, it is called with an argument
|
|
list as defined by the \f4stdarg.h\f1 header file.
|
|
.PP
|
|
The \f4stdarg.h\f1 header file defines the
|
|
type \f4va_list\f1 and a set of macros for advancing
|
|
through a list of arguments whose number and types may vary.
|
|
The argument \f2ap\f1 to \f4vlfmt\f1
|
|
is of type \f4va_list\f1.
|
|
This argument is used with the \f4stdarg.h\f1 header
|
|
file macros \f4va_start\f1, \f4va_arg\f1 and \f4va_end\f1
|
|
[see \f4va_start\f1, \f4va_arg\f1, and \f4va_end\f1
|
|
in \f4stdarg\fP(5)].
|
|
The EXAMPLE sections below show their use.
|
|
.P
|
|
The macro \f4va_alist\f1 is used as the parameter list in a function
|
|
definition as in the function called \f4error\f1
|
|
in the example below.
|
|
The macro \f4va_start(\f2ap\fP, )\f1, where \f2ap\f1 is of type
|
|
\f4va_list\f1, must be called before any attempt to traverse and
|
|
access unnamed arguments.
|
|
Calls to \f4va_arg(\f2ap\f4, \f2atype\f4)\f1 traverse the argument
|
|
list.
|
|
Each execution of \f4va_arg\f1 expands to an expression with the
|
|
value and type of the next argument in the list \f2ap\f1,
|
|
which is the same object initialized by \f4va_start\f1.
|
|
The argument \f2atype\f1 is the type that the returned argument is
|
|
expected to be.
|
|
The \f4va_end(\f2ap\f4)\f1 macro must be invoked when all
|
|
desired arguments have been accessed.
|
|
[The argument list in \f2ap\f1 can be traversed again if \f4va_start\f1
|
|
is called again after \f4va_end\f1.]
|
|
In the example below, \f4va_arg\f1 is executed first to\p
|
|
.br
|
|
.ne 3
|
|
retrieve the
|
|
format string passed to \f4error\f1.
|
|
The remaining \f4error\f1 arguments, \f2arg1\f1, \f2arg2\f1, \f1. . .\^,
|
|
are given to \f4vlfmt\f1 in the argument \f2ap\f1.
|
|
.br
|
|
.ne 1i
|
|
.SH EXAMPLES
|
|
.SS "lfmt example 1"
|
|
.ft 4
|
|
.nf
|
|
setlabel("UX:test");
|
|
lfmt(stderr, MM_ERROR|MM_CONSOLE|MM_SOFT|MM_UTIL,
|
|
"test:2:Cannot open file: %s\\n", strerror(errno));
|
|
.ft 1
|
|
.fi
|
|
.P
|
|
displays the message to \f2stderr\f1 and to the console and makes it
|
|
available for \%logging:
|
|
.P
|
|
.RS
|
|
\f4UX:test: ERROR: Cannot open file: No such file or directory\f1
|
|
.RE
|
|
.SS "lfmt example 2"
|
|
.ft 4
|
|
.nf
|
|
setlabel("UX:test");
|
|
lfmt(stderr, MM_INFO|MM_SOFT|MM_UTIL,
|
|
"test:23:test facility is enabled\\n");
|
|
.ft 1
|
|
.fi
|
|
.P
|
|
displays the message to \f2stderr\f1 and makes it available for logging:
|
|
.P
|
|
.RS
|
|
\f4UX:test: INFO: test facility enabled\f1
|
|
.RE
|
|
.SS "vlfmt example"
|
|
The following demonstrates how \f4vlfmt\f1 could be used to write
|
|
an \f4errlog\f1 routine:
|
|
.PP
|
|
.RS
|
|
.nf
|
|
.ft 4
|
|
#include <pfmt.h>
|
|
#include <stdarg.h>
|
|
\&. . .
|
|
/\(**
|
|
\(** errlog should be called like
|
|
\(** errlog(log_info, format, arg1, ...);
|
|
\(**/
|
|
void errlog(long log_info, const char \(**format, ...)
|
|
.sp0.5
|
|
{
|
|
va_list ap;
|
|
.sp0.5
|
|
va_start(ap, format);
|
|
(void) vlfmt(stderr, log_info|MM_ERROR, format, ap);
|
|
va_end(ap);
|
|
(void) abort();
|
|
}
|
|
.ft 1
|
|
.fi
|
|
.RE
|
|
.SH SEE ALSO
|
|
.na
|
|
\f4lfmt\fP(1),
|
|
\f4pfmt\fP(1),
|
|
\f4addsev\fP(3C),
|
|
\f4gettxt\fP(3C),
|
|
\f4setcat\fP(3C),
|
|
\f4setlabel\fP(3C),
|
|
\f4setlocale\fP(3C),
|
|
\f4printf\fP(3S),
|
|
\f4environ\fP(5),
|
|
\f4stdarg\fP(5)
|
|
.ad
|
|
.SH DIAGNOSTICS
|
|
On success, \f4lfmt\f1 and
|
|
\f4vlfmt\f1 return the number of bytes transmitted.
|
|
On failure, they return a negative value:
|
|
.nf
|
|
.sp .5
|
|
\-1 write error to \f2stream\f1
|
|
.sp .5
|
|
\-2 cannot log and/or display at console.
|
|
.fi
|