evmshow(1)evmshow(1)NAMEevmshow - Displays an EVM event
SYNOPSISevmshow [[-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 | -]
OPTIONS
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 speci‐
fied 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 configura‐
tion file /etc/evmchannel.conf. Outputs each event as a formatted line
using the specified show_template. If this option is used in conjunc‐
tion 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 syn‐
tax. 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 out‐
put 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.
OPERANDS
Reads events from file filename. If filename is omitted, or is speci‐
fied as -, events are read from stdin.
DESCRIPTION
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 vari‐
able 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, pro‐
viding 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 compris‐
ing 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 [200] 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 spec‐
ifiers 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 [200] 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) ref‐
erence 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 writ‐
ten to the output, and no error is reported. Output cannot be directed
to a terminal if the -b option is used.
NOTES
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.
RESTRICTIONS
The evmshow command rejects attempts to output raw events to a terminal
device.
EXIT STATUS
The following exit values are returned: Successful completion. An
error occurred.
EXAMPLES
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 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 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 evmfil‐
terfile(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
The following environment variables affect the execution of evmshow:
This variable contains a string formatted as described for a show_tem‐
plate. If the -d, -D, -t, and -x options are omitted, the string is
used as the show_template for output.
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)
