evmshow(1) General Commands Manual evmshow(1)
NAME
evmshow - Displays an EVM event
SYNOPSIS
evmshow [[-d | -D | -x] [-t show_template] [-T timespec] | -r] [-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 flag 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 flag results in an error if stdout is directed to a terminal device. Outputs the explanation
text for the event. The explanation is obtained using the explanation function (fn_explain) defined for the event in the channel configu-
ration file /etc/evmchannel.conf. Outputs each event as a formatted line using the specified show_template. If this flag is used in con-
junction with -d, -D or -x the formatted line is output first, followed by the multiline output resulting from the other flag. 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 DESCRIP-
TION 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 fil-
ter, the filter is expanded before being displayed. This feature is useful for retrieving filter strings from a file. This flag cannot be
used in conjunction with any other output format control flag. 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, all events are output.
OPERANDS
Reads events from file filename. If filename is omitted, or is specified as -, events are read from stdin.
DESCRIPTION
The evmshow command is EVM's event formatter - it reads raw EVM events 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 flag is specified, each event is formatted according to the following rules, and written to stdout as a single
line of text.
If the -t flag is included, the supplied show_template string is used to format the event. If the -t flag 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 the EvmEvent(5) reference page for a complete list of standard event data items.)
If a show_template is available, evmshow replaces each specifier in the template with the value of the corresponding data item 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 are output unchanged, providing a convenient way to insert literal strings, punctuation and spacing characters.
For example, show_template "@timestamp [@priority] @name" causes each event read by evmshow to be displayed as a single line of text com-
prising 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, produced by taking the format data item and replacing
any embedded variable specifiers (beginning with $) with the corresponding variable value, and replacing any data item specifiers (begin-
ning with @) 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
If an item specified in the show_template is not present in the event, the character - is output in its place. An @ character not associ-
ated with a valid item name is unchanged in the output. If it is necessary to have an @@ sequence in the output, the @ 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 characer 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 flag 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 flag can be used in combination with the -f, -k and -n flags 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 flags. Events are output as raw EVM events, so output cannot be
directed to a terminal if this option is used.
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 flags are omitted, the string is used as the show_template for output.
NOTES
The -r flag 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.
RESTRICTIONS
The evmshow command rejects attempts to output raw events to a terminal device.
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 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 flag) 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 the evmfilterfile(4) reference page 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 format-
ted message. See the date(1) reference page 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 flag produces the subject line as the first line of the
output, and the -d flag 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 [@prior-
ity] @@" -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 flag 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. Refer to the evmtemplate reference page for details
of event templates. evmwatch -i | evmshow -t "@name [@priority]" -x | more
EXIT VALUES
The following exit values are returned: Successful completion An error occurred
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)
delim off
evmshow(1)