EvmEventFormat(3) — Subroutines

NAME

EvmEventFormat − Formats an event for display

LIBRARY

EVM Support Library (libevm.so, libevm.a)

SYNOPSIS

#include <evm/evm.h>

EvmStatus_t EvmEventFormat(
char ∗buffer,
size_t length,
EvmEvent_t event);

EvmStatus_t EvmEventFormat(
char ∗buffer,
size_t length,
EvmString_t show_template,
EvmEvent_t event);

PARAMETERS

bufferA pointer to a character string where EvmEventFormat() should store the formatted event data. The stored string will be null-terminated, even if truncated, unless the length parameter is zero (0).

lengthThe maximum length of the output string. If the formatted event is longer than length, the output is truncated.

eventThe event to be formatted.

show_templateThe primary template for formatting the output.

DESCRIPTION

Information contained in an event must be formatted to present it in human-readable form. The event poster supplies formatting information through the event’s format data item. The EvmEventFormat() routine provides the event formatting capability.

The supplied event’s format data item is combined with any data items or variables specified in the event’s format item and available in the event. A character string containing a formatted version of the event is returned.

If the event contains I18N message catalog information, and the catalog is available, the event is translated according to the user’s locale setting. If no translation is possible, the format information contained in the event is used.

If the event does not contain format information, a generic display of the name and any non-opaque variables is produced.

The EvmEventFormatFromTemplate() routine also formats an event, but uses the supplied show_template string as its primary formatting template. Literal characters in the 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. If width is supplied, the value will occupy a minumum of width character positions. 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.

NOTES

Floating point values are formatted using the printf(3) %.8g format specifier.

RETURN VALUES

EvmERROR_NONE
The operation was completed without error.

EvmERROR_INVALID_ARGUMENT
One of the arguments to the function was 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

None

FILES