evmshow - Displays an EVM event
evmshow [[-d | -D | -x] [-t show_template] | [-T timespec]
| -r | -b item_list] [-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. Outputs each event as a full multiline detailed
display, using the details function (fn_details) defined
for the event in the channel configuration file /etc/evmchannel.conf.
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
stdout 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,
@timestamp) or variables (for example, $my_variable), separated
by commas or tab characters. The list must be
enclosed in single quotes if $ or tab characters are used,
to protect them from interpretation by the shell. See the
DESCRIPTION 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
(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. 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 beginning
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 specified 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 none of the -d, -D, -r or -b options is specified, each
event is formatted according to the following rules and
written to stdout as a single line of text.
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 value.
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 variable in the template with the value of
the corresponding data item or variable 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 convenient 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 formatted 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
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 terminal if this option is used.
The -b 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 UINT64, 8 bytes of binary data are output. 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 terminal if the
-b option is used.
The -r and -b options 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. The
evmget and evmwatch commands can be made to run evmshow
automatically by use of their -A options. See evmget(1)
and evmwatch(1) for more information.
The evmshow command rejects attempts to output raw events
to a terminal device.
The following exit values are returned: Successful completion.
An error occurred.
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] @@" This ksh example
displays events in the same way as the previous example,
but the show_template is specified in an environment variable,
simplifying the evmshow command. export
EVM_SHOW_TEMPLATE="@timestamp [@priority] @@" evmget |
evmshow 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 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 evmshow command is then
used to display full details (indicated by the -d option)
of the first five (most recent) events from the file.
evmget | evmsort -s "@timestamp-" > my_eventfile evmshow
-n 5 -d my_eventfile | more 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 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 formatting options.
evmget | evmsort | evmshow -T "%Y/%m/%d %T " -t "[@priority]
@@" 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 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 events. evmshow -r -f "[priority
>= 500]" file1 > file2 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 explanation text. See evmtemplate(4) for details of
event templates. evmwatch -i | evmshow -t "@name [@priority]"
-x | more The following example uses evmget to
retrieve recent events from the system's binary error log
as EVM events, then uses the evmshow -b option to extract
the original binlog event from each EVM event, and writes
the events to a file. The resulting file has the same format
as the binary error log file, and can be processed by
DECevent or Compaq Analyze. evmget -C binlog -f '[age <
3d]' | evmshow -b '$binlog_event' > my_binlog_file
ENVIRONMENT VARIABLES [Toc] [Back]
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
Location of the EVM channel configuration file.
Commands: date(1), evmget(1), evminfo(1), evmpost(1), evmsort(1), evmwatch(1)
Files: evmchannel.conf(4), evmfilterfile(4), evmtemplate(4)
Event Management: EVM(5)
EVM Events: EvmEvent(5)
Event Filter: EvmFilter(5)
[ Back ]