unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (OSF1-V5.1-alpha)
Page:
Section:
Apropos / Subsearch:
optional field



evmshow(1)							   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

  -c config_file
      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
      device.

  -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.

  -t show_template
      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.

  -T timespec
      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.

  -f filter_expr
      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.

  -k skip_count
      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.

  -n show_count
      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

  filename
      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 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
  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 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 [200]  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 [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) 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.

NOTES

   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
       more information.

RESTRICTIONS

  The evmshow command rejects attempts to output raw events to a terminal
  device.

EXIT STATUS

  The following	exit values are	returned:

  0   Successful completion.

  not 0
      An error occurred.

EXAMPLES

   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
       the file.
	    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
       formatting options.
	    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
       events.
	    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



ENVIRONMENT VARIABLES

  The following	environment variables affect the execution of evmshow:

  EVM_SHOW_TEMPLATE
      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.







FILES

  /etc/evmchannel.conf
      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)