evmshow - Displays an EVM event
evmshow [[-d | -D | -x] [-t show_template] [-T timespec]| -r] [-c
config_file] [-f filter_expr] [-F] [-k skip_count] [-n show_count]
[filename | -]
Uses config_file as the channel configuration file instead of the
default file, /etc/evmchannel.conf. The channel configuration file is
read when the -d or the -x option is used.
-d Outputs each event as a full multiline detailed display, using the
details function (fn_details) defined for the event in the channel con-
figuration file /etc/evmchannel.conf.
-D 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.
-r Does not format events, but outputs each event as a raw (binary) event.
This option results in an error if stdout is directed to a terminal
-x Outputs the explanation text for the event. The explanation is obtained
using the explanation function (fn_explain) defined for the event in
the channel configuration file /etc/evmchannel.conf.
Outputs each event as a formatted line using the specified
show_template. If this option is used in conjunction with -d, -D, or
-x, 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
DESCRIPTION section for details of timespec.
Outputs only events that match the filter_expr. See the EvmFilter(5)
reference page for the filter syntax.
-F Echoes any specified filter string to stdout, and terminates. If the
filter specified with the -f 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 begin-
ning output. If skip_count exceeds the number of events in the input
stream, no output is produced.
Stops producing output after show_count events have been output. If
show_count exceeds the number of events in the input stream, evmshow
outputs all events.
Reads events from file filename. If filename is omitted, or is speci-
fied as -, events are read from stdin.
The evmshow 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 stdin if no filename is
specified or if filename is -. Formatted output is written to stdout. The
evmshow command can be also used as a filter, producing a selected set of
raw events as its output.
If neither the -d or the -D option is specified, each event is formatted
according to the following rules and written to stdout as a single line of
If the -t option is included, the supplied show_template string is used to
format the event. If the -t option is omitted but the variable
EVM_SHOW_TEMPLATE is present in the environment, the value of the variable
is used as the show_template. If no show_template is available, a default
value of @@ is used. See the explanation below for the meaning of this
A show_template is a string that may contain event data item specifiers of
the form @item_name[%width], where item_name is the name of any standard
event data item, such as timestamp or priority and width, if specified, is
the minimum number of character spaces the value should occupy. (See
EvmEvent(5) for a complete list of standard event data items.)
Variables defined in EVM events and templates also can be included in the
show_template by using variable specifiers, which begin with $.
If a show_template is available, evmshow replaces each specifier or vari-
able in the template with the value of the corresponding data item or vari-
able from the event, producing an output string containing only the
required items. Any characters in the show_template that are not part of an
item specifier or variable is unchanged in the output, providing a con-
venient way to insert literal strings, punctuation, and spacing characters.
Tabs and newlines can be inserted by using \t and \n, respectively.
For example, show_template "@timestamp [@priority] @name" causes each event
read by evmshow to be displayed as a single line of text comprising the
date and time, the priority of the event enclosed in brackets, and then the
event name. The output appears as follows:
03-Feb-2000 02:00:00  sys.unix.evm.chmgr.cleanup_done
The special show_template specifier @@ is replaced with the event's format-
ted text, which is produced by taking the evmtemplate format data item and
replacing any embedded variable specifiers (beginning with $) with the
corresponding variable value and replacing any data item specifiers with
the corresponding data item.
For example, the show_template "@timestamp [@priority] @@" results in the
following style of display:
03-Feb-2000 02:00:00  EVM channel mgr: Log cleanup completed
Items specified by @ in the show_template that are not present in the event
are replaced by the 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 -T option is specified, each formatted line is prefixed with the
event's timestamp value in a format specified by timespec. The timespec can
be any string containing specifiers as defined in the Field Descriptors
section of the date(1) reference page. For example, the string "%Y/%m/%d
%T" yields the date and time in yyyy/mm/dd hh:mm:ss format with a trailing
space character separating it from the rest of the line. You can use this
option instead of specifying @timestamp in the show_template to produce a
timestamp in any format you want.
The -f option can be used to specify an EVM filter string, to limit the
events that are passed through evmshow. If this option is used, only events
that match the filter_expr are output. See the EvmFilter(5) reference page
for the filter syntax.
The -r option can be used in combination with the -f, -k, and -n options to
make evmshow 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 ter-
minal if this option is used.
1. The -r option should not be used when output is sent indirectly to a
terminal device, such as piping the output of the evmshow command to
the more command.
2. The evmget and evmwatch commands can be made to run evmshow automati-
cally by use of their -A options. See evmget(1) and evmwatch(1) for
The evmshow command rejects attempts to output raw events to a terminal
The following exit values are returned:
0 Successful completion.
An error occurred.
1. In the following example, all available events are retrieved and piped
to evmshow 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.
evmget | evmshow -t "@timestamp [@priority] @@"
2. This ksh example displays events in the same way as the previous exam-
ple, but the show_template is specified in an environment variable,
simplifying the evmshow command.
export EVM_SHOW_TEMPLATE="@timestamp [@priority] @@"
evmget | evmshow
3. The following example retrieves all available events using evmget, and
sorts them into a file. In the evmsort command, the -s option requests
that the events be sorted into timestamp order, and the hyphen charac-
ter 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 evmshow command is then used to display full details (indi-
cated by the -d option) of the first five (most recent) events from
evmget | evmsort -s "@timestamp-" >> my_eventfile
evmshow -n 5 -d my_eventfile | more
4. The following example displays the value of the filter named evm, from
the supplied sys filter file. Refer to evmfilterfile(4) for more
information about filter files.
evmshow -f "@sys:evm" -F
5. The following example retrieves all events and displays them with the
timestamp in the form yyyy/mm/dd hh:mm:ss, followed by the priority
and the formatted message. See date(1) for details of the timestamp
evmget | evmsort | evmshow -T "%Y/%m/%d %T " -t "[@priority] @@"
6. The following example watches for events of priority 600 or greater,
and mails them in detailed display format to user jim, with a subject
line that identifies the event. In the evmshow command, the -t option
produces the subject line as the first line of the output, and the -d
option causes evmshow to follow the subject line with a detailed
display of the event. The mail command uses the line beginning with
Subject: as the subject for the mail message.
evmwatch -f "[priority >>= 600]" |
evmshow -t "Subject: EVENT [@priority] @@" -d | mail jim
7. The following example reads raw EVM events from the file file1 and
writes the events that have a priority of 500 or greater to file2.
Because the -r option is specified, the output file contains raw EVM
evmshow -r -f "[priority >>= 500]" file1 >> file2
8. The following example uses the evmwatch -i option to request a list of
all event templates from the EVM daemon, and then uses evmshow to
display the name and priority of each template, followed by its expla-
nation text. See evmtemplate(1) for details of event templates.
evmwatch -i | evmshow -t "@name [@priority]" -x | more
The following environment variables affect the execution of evmshow:
This variable contains a string formatted as described for a
show_template. If the -d, -D, -t, and -x options are omitted, the
string is used as the show_template for output.
Location of the EVM channel configuration file.
Commands: date(1), evmget(1), evminfo(1), evmpost(1), evmsort(1),
Files: evmchannel.conf(4), evmfilterfile(4), evmtemplate(4)
Event Management: EVM(5)
EVM Events: EvmEvent(5)
Event Filter: EvmFilter(5)