evmshow(1)evmshow(1)NAMEevmshow - display an EVM event
SYNOPSIS
show_template] timespec] item_list] config_file] filter_exprt]
skip_count] show_count] [filename
DESCRIPTION
The command is EVM's event formatter. It reads raw EVM events either
produced by other EVM commands or stored in a file and converts them to
display format for viewing. Events are read from if no filename is
specified or if filename is Formatted output is written to The command
can be also used as a filter, producing a selected set of raw events as
its output.
If none of the or options is specified, each event is formatted accord‐
ing to the following rules and written to as a single line of text.
If the option is included, the supplied show_template string is used to
format the event. If the option is omitted but the variable is present
in the environment, the value of the variable is used as the show_tem‐
plate. If no show_template is available, a default value of is used.
The is explained in more detail later in this section.
A show_template is a string that contains event data item specifiers of
the form width], where item_name is the name of any standard event data
item, such as or and width. The width is the minimum number of charac‐
ter spaces the value should occupy. See EvmEvent(5) for a complete
list of standard event data items.
Variables defined in EVM events and templates can be included in the
show_template by using variable specifiers, which begin with
If a show_template is available, replaces each specifier or variable in
the template with the value of the corresponding data item or variable
from the event. The produced output string contains only the required
items. Any character in show_template is not changed in the output if
it is not part of an item specifier or not part of a variable. This
method provides a convenient way to insert literal strings, punctua‐
tion, and spacing characters.
Tabs and newlines are inserted by using and respectively.
For example, a show_template of causes each event read by to be dis‐
played as a single line of text. The line of text is comprised of the
date and time, the priority of the event enclosed in brackets, and then
the event name.
The output appears as follows:
The special show_template specifier is replaced with the event's for‐
matted text. The formatted text is produced by taking the format data
item. Then, any embedded variable specifiers (beginning with are
replaced with the corresponding variable value, and any data item spec‐
ifiers are replaced with the corresponding data item.
For example, the show_template of results in the following style of
display:
Items specified by in the show_template that are not present in the
event are replaced by the hyphen character
An or character not associated with a valid item name or variable
value, respectively, is unchanged in the output. If it is necessary to
have an or sequence in the output, the and characters should be escaped
with backslashes
If the option is specified, each formatted line is prefixed with the
event's timestamp value in a format specified by timespec. The time‐
spec can be any string containing specifiers as defined in the section
of the date(1) manpage. For example, the string yields the date and
time in format with a trailing space character separating it from the
rest of the line. Use this option instead of specifying in the
show_template to produce a timestamp in any desired format.
The option can be used to specify an EVM filter string, to limit the
events that are passed through If this option is used, only events that
match the filter_expr are output. See the EvmFilter(5) manpage for the
filter syntax.
The option can be used in combination with the and options to make act
as a filter, reading a stream of events and writing only those that
meet the selection criteria specified by the other options. Events are
output as raw EVM events, so output cannot be directed to a terminal if
this option is used.
The option can be used to extract one or more data items or variable
values from an event stream in their native binary formats. This
option is particularly useful for producing a data file from events
that contain the required data in variables.
Binary values are written to the output file in the size appropriate to
their types -- for example, if a variable named in the item_list is
present in an event and has a type of 8 bytes of binary data are out‐
put. String values are output as arbitrary-length character strings,
terminated by a single null byte. If a data item or variable specified
in the item_list is not present in an event, nothing is written to the
output, and no error is reported. Output cannot be directed to a ter‐
minal if the option is used.
Options
Uses config_file as the channel configuration file
instead of the default file, The channel configura‐
tion file is read when the or the option is used.
Outputs each event as a full multiline detailed display, using the
details function defined for the event in the chan‐
nel configuration file
Outputs each event as a multiline dump of the contents of the event.
This format does not include explanation text or
any additional details about the event.
Does not format events, but outputs each event as a raw (binary) event.
This option results in an error if is directed to a
terminal device.
Outputs the specified data items or variable values in their native
form,
ASCII or binary, as appropriate. The item_list
must specify one or more standard data items (for
example, or variables (for example, my_variable),
separated by commas or tab characters. The list
must be enclosed in single quotes if or tab charac‐
ters are used, to protect them from interpretation
by the shell. See the section for details of the
output produced by this option.
Outputs the explanation text for the event.
The explanation is obtained using the explanation
function (defined for the event in the channel con‐
figuration file
Outputs each event as a formatted line using the specified
show_template. If this option is used in conjunc‐
tion with or the formatted line is output first
followed by the multiline output resulting from the
other option.
Outputs the event's timestamp value at the start of each formatted text
line using timespec as a template for the timestamp
format. See the section for details of timespec.
Outputs only events that match the
filter_expr. See the EvmFilter(5) manpage for the
filter syntax.
Echoes any specified filter string to
and terminates. If the filter specified with the
option refers to a stored filter, the filter is
expanded before being displayed. This feature is
useful for retrieving filter strings from a file.
This option cannot be used in conjunction with any
other output format control option.
Skips the first skip_count events from the input stream before
beginning output. If skip_count exceeds the number
of events in the input stream, no output is pro‐
duced.
Stops producing output after
show_count events have been output. If show_count
exceeds the number of events in the input stream,
outputs all events.
Operands
filename Reads events from file filename. If filename is omitted, or
is specified as events are read from
Notes
1. The and options should not be used when output is sent indirectly to
a terminal device, such as piping the output of the command to the
command.
2. The and commands can be made to run automatically by use of their
options. See evmget(1) and evmwatch(1) for more information.
EXTERNAL INFLUENCES
Environment Variables
The following environment variable affects the execution of
This variable contains a string formatted as described for a
show_template. If the and options are omitted, the string is
used as the show_template for output.
RETURN VALUES
The following exit values are returned:
Successful completion.
An error occurred.
EXAMPLES
· In the following example, all available events are retrieved and
piped to for formatting. The show_template causes the events to be
displayed as timestamp value, followed by the event's priority
enclosed in brackets, followed by the formatted event message.
· This example displays events in the same way as the previous exam‐
ple, but the show_template is specified in an environment variable,
simplifying the command.
· The following example retrieves all available events using and sorts
them into a file. In the command, the option requests that the
events be sorted into timestamp order, and the hyphen character at
the end of the sort specification indicates that the sort order
should be descending. This results in the most recent events
appearing first. The command is then used to display full details
(indicated by the option) of the first five (most recent) events
from the file.
· The following example displays the value of the filter named from
the supplied filter file. Refer to evmfilterfile(4) for more infor‐
mation about filter files.
· The following example retrieves all events and displays them with
the timestamp in the form followed by the priority and the formatted
message. See date(1) for details of the timestamp formatting
options.
· The following example watches for events of priority 600 or greater,
and mails them in detailed display format to user with a subject
line that identifies the event. In the command, the option produces
the subject line as the first line of the output, and the option
causes to follow the subject line with a detailed display of the
event. The command uses the line beginning with as the subject for
the mail message.
· The following example reads raw EVM events from the file and writes
the events that have a priority of 500 or greater to Because the
option is specified, the output file contains raw EVM events.
· The following example uses the option to request a list of all event
templates from the EVM daemon, and then uses to display the name and
priority of each template, followed by its explanation text. See
evmtemplate(4) for details of event templates.
WARNINGS
The command rejects attempts to output raw events to a terminal device.
FILES
Location of the EVM channel configuration file
SEE ALSO
Commands
date(1), evmget(1), evminfo(1), evmpost(1), evmsort(1), evmwatch(1).
Routines
EvmEventFormat(3).
Files
evmchannel.conf(4), evmfilterfile(4), evmtemplate(4).
Event Management
EVM(5).
EVM Events
EvmEvent(5).
Event Filter
EvmFilter(5).
evmshow(1)