NAME
EvmEventFormat(), EvmEventFormatFromTemplate(), EvmVarFormat() — format events for display
SYNOPSIS
#include <evm/evm.h>
EvmStatus_t EvmEventFormat(
char *buffer,
size_t length,
EvmEvent_t event );
EvmStatus_t EvmEventFormatFromTemplate(
char *buffer,
size_t length",
EvmString_t show_template,
EvmEvent_t event );
EvmStatus_t EvmVarFormat(
EvmEvent_t event ,
const char *var_name,
char *buffer,
size_t length",
EvmBoolean_t translate );
Library
EVM Support Library
(libevm.so).
Parameters
- buffer
A pointer to a character string to receive the formatted event data.
The stored string is null-terminated, even if truncated, unless
the length operand is zero (0).
- length
The maximum length (number of characters) of the output string.
If the formatted event is
longer than
length,
the output is truncated.
- event
The event to be formatted.
- show_template
The primary template for formatting the output.
- var_name
The name of a variable data item of the event whose value is
to be formatted.
- translate
A Boolean value indicating whether I18N (internationalization) translation
is to be attempted on the variable data item
(var_name).
If the
translate
operand is
EvmTRUE,
translation is attempted.
In addition, the following conditions must be met:
The variable is of type string and includes an I18N (internationalization) message identifier
The event contains I18N (internationalization) catalog information.
DESCRIPTION
Information contained in an event must be formatted into a readable format.
The software which posts the event (event poster) supplies formatting information
through the event's format data item.
The routines described here explain the event formatting capabilities.
The
EvmEventFormat()
routine combines the supplied event's format data item
with any data items or variables specified in the event's format item that
are available in the event.
EvmEventFormat()
returns a formatted version of the event in
buffer.
If the event contains I18N message catalog information, and the catalog is
available in the user's locale, the format string is retrieved from the
message catalog if possible.
If no translation is possible, the format string from the event is used.
If the event does not contain format information,
EvmEventFormat()
produces a generic display of the event's name and any variables.
The
EvmEventFormatFromTemplate()
routine also formats the supplied event.
EvmEventFormatFromTemplate()
uses the supplied
show_template
string as its primary formatting template.
Literal characters in
show_template
are transferred to the buffer unchanged.
Any token of the form
@item_name[%width]
or
@{item_name[%width]}
is replaced by the value of the corresponding data
item from the supplied event, if it is present.
item_name
is the name of the item stored in the event.
If
width
is supplied, the value occupies a minimum of
width
character positions.
width
is an integer number specifying the size of the value stored in
item_name.
The
item_name
is the name of a standard event data item.
The special string
@@
is replaced by the results of applying
EvmEventFormat()
to the event.
Refer to
evmshow(1)
and
EvmEvent(5)
for more information about formatting events for display.
EvmVarFormat()
retrieves a variable called
var_name
from the supplied event, and returns a formatted version of its value in
buffer.
If
translate
is
EvmTRUE,
I18N translation is applied as appropriate.
Notes
Floating point values are formatted using the
printf() %.8g
format specifier.
RETURN VALUE
- EvmERROR_NONE
The operation completed without error.
- EvmERROR_INVALID_ARGUMENT
One of the arguments to the function is invalid.
- EvmERROR_INVALID_VALUE
A value in a structure member is invalid.
- EvmERROR_NO_MEMORY
An operation failed because an attempt to acquire heap memory failed.
ERRORS
The value of
errno
is not set.
Printable version
