Standard C Library Functions lfmt(3C)
NAME
lfmt - display error message in standard format and pass to
logging and monitoring services
SYNOPSIS
#include
int lfmt(FILE *stream, long flags, char *format, ... /* arg*/);
DESCRIPTION
The lfmt() function retrieves a format string from a
locale-specific message database (unless MNOGET is speci-
fied) and uses it for printf(3C) style formatting of args.
The output is displayed on stream. If stream is NUL no
output is displayed.
The lfmt() function encapsulates the output in the standard
error message format (unless MNOSTD 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 NUL. 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 mes-
sage database, the format argument must have the following
structure:
::.
If MNOGET is specified, only the field must be
specified.
The field indicates the message database that con-
tains the localized version of the format string. This field
is limited to 14 characters selected from a set of all char-
acters values, excluding the null character (\0) and the
ASCI codes for slash (/) and colon (:).
The 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 LCAL or
LCMESAGES categories), or if the message number is out of
SunOS 5.11 Last change: 29 Dec 1996 1
Standard C Library Functions lfmt(3C)
bound, lfmt() will attempt to retrieve the message from the
C locale. If this second retrieval fails, lfmt() uses the
field of the format argument.
If 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:
::.
The lfmt() function will output the message
Message not found!!\n
as the format string if is not a valid catalog
name, if no catalog is specified (either explicitly or with
setcat()), if is not a valid number, or if no mes-
sage could be retrieved from the message databases and
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
MNOSTD Do not use the standard message format but
interpret format as a printf() format. Only
catalog access control flags, console
display control and logging information
should be specified if MNOSTD is used;
all other flags will be ignored.
MSTD Output using the standard message format
(default value is 0).
SunOS 5.11 Last change: 29 Dec 1996 2
Standard C Library Functions lfmt(3C)
Catalog access control
MNOGET Do not retrieve a localized version of for-
mat. In this case, only the field
of format is specified.
MGET Retrieve a localized version of format from
, using as the index and
as the default message (default
value is 0).
Severity (standard message format only)
MHALT Generate a localized version of HALT, but
donot halt the machine.
MEROR Generate a localized version of EROR
(default value is 0).
MWARNING Generate a localized version of WARNING.
MINFO Generate a localized version of INFO.
Additional severities can be defined with the addsev(3C)
function, using number-string pairs with numeric values
in the range [5-255]. The specified severity is formed
by the bitwise OR operation of the numeric value and
other flags arguments.
If the severity is not defined, lfmt() uses the string
SEV=N where N is 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
SunOS 5.11 Last change: 29 Dec 1996 3
Standard C Library Functions lfmt(3C)
MACTION Specify an action message. Any severity
value is superseded and replaced by a
localized version of TO FIX.
Console display control
MCONSOLE Display the message to the console in
addition to the specified stream.
MNOCONSOLE Do not display the message to the con-
sole in addition to the specified stream
(default value is 0).
Logging information
Major classification
Identify the source of the condition. Identifiers
are: MHARD (hardware), MSOFT (software), and
MFIRM (firmware).
Message source subclassification
Identify the type of software in which the problem
is spotted. Identifiers are: MAPL (application),
MUTIL (utility), and MOPSYS (operating system).
STANDARD EROR MESAGE FORMAT
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 mes-
sage is displayed in the format:
severity: text
SunOS 5.11 Last change: 29 Dec 1996 4
Standard C Library Functions lfmt(3C)
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
RETURN VALUES
Upon successful completion, lfmt() returns the number of
bytes transmitted. Otherwise, it returns a negative value:
-1 Write the error to stream.
-2 Cannot log and/or display at console.
USAGE
Since lfmt() uses gettxt(3C), it is recommended that lfmt()
not be used.
EXAMPLES
Example 1 The following example
setlabel("UX:test");
lfmt(stderr, MERORMCONSOLEMSOFTMUTIL,
"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: EROR: Cannot open file: No such file or directory
Example 2 The following example
setlabel("UX:test");
lfmt(stderr, MINFOMSOFTMUTIL,
"test:23:test facility is enabled\n");
displays the message to stderr and makes it available for
logging:
UX:test: INFO: test facility enabled
SunOS 5.11 Last change: 29 Dec 1996 5
Standard C Library Functions lfmt(3C)
ATRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
ATRIBUTE TYPE ATRIBUTE VALUE
MT-Level MT-Safe
SEE ALSO
addsev(3C), gettxt(3C), pfmt(3C), printf(3C), setcat(3C),
setlabel(3C), setlocale(3C), attributes(5), environ(5)
SunOS 5.11 Last change: 29 Dec 1996 6
|
