unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

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



EvmFilter(5)							 EvmFilter(5)



NAME

  EvmFilter - Event filter

DESCRIPTION

  An event filter is a specification of	a set of interesting events. Event
  subscribers use filters to tell the EVM daemon which events they want	to
  receive - for	example, one subscriber	may be only interested in receiving
  events reporting hardware errors, while another may want to receive all
  high-priority	events,	regardless of what they	are reporting.	If a sub-
  scriber does not set a filter, it will receive no events.

  The Event Viewer and some of the EVM user commands also use filters to
  select events	for viewing or processing.

  A filter is an ASCII character string	- it can be very simple	or arbi-
  trarily complex.  Complex filters are	created	by combining simple filters.

  A simple filter has the following format:

  [keyword expr] | all | 1 | none | 0

  The format of	expr is	specific to the	type of	filter.	 The left and right
  square brackets ([ and ]) are	required.  Keywords may	be specified in	any
  mix of upper and lower case, and where the underscore	character (_) is
  included in a	full-length keyword (as	in host_name), it may be omitted.
  Keywords may be abbreviated, and in the following paragraphs the minimum
  abbreviation for each	is indicated by	upper-case letters.

  Possible values for keyword and the associated expr are:

  Name event-name-specifier
      Selects events with a name matching the event-name-specifier.  Names
      are considered to	match when the event name matches as many components
      as included in the filter.

      The event-name-specifier may include the * and the ? characters as
      wildcards	in any component position.  The	* represents 0 or more com-
      ponents with any value.  The ? represents	exactly	one component.	Any
      event-name-specifier includes an implied trailing	.* wildcard.

  Priority equality-operator integer
      Only events with a priority meeting the specified	evaluation will	be
      passed.  The integer value may be	0 to 700, inclusive.  See the follow-
      ing table	for a description of equality-operator.	 May be	specified as
      prio.

  Timestamp time-range-specifier
      All events with a	timestamp that is within the time-range-specifier are
      passed.  See the description of time-range-specifier.  May be specified
      as time.

  Age equality-operator	age-specifier
      Selects events that meet the age specification.  See the description of
      age-specifier.  The equality-operator must specify less-than or less-
      than-or-equal, meaning "newer than", or greater-than or greater-than-
      or-equal,	meaning	"older than."  The "equal" or "not equal" operators
      are not allowed.

  BEFore absolute-time-specifier
      All events with a	timestamp that is earlier than the absolute-time-
      specifier	are passed.  See the description of absolute-time-specifier.

  SINce	absolute-time-specifier
      All events with a	timestamp that is equal	to or later than the
      absolute-time-specifier are passed.  See the description of absolute-
      time-specifier.

  Host_name host-name
      All events posted	from the machine host-name are passed.	May be speci-
      fied as host.

  CLUster_name cluster-name
      All events posted	from the cluster cluster-name are passed.  May be
      specified	as cluster.

  EVent_id equality-operator integer
      All events with an event_id meeting the specified	evaluation will	be
      passed.  See EvmEvent(5) for a description of the	event_id.  See the
      following	table for a description	of equality-operator.  The EVent_id
      keyword may be abbreviated to ID.

  NONE or 0
      A	filter value of	none or	0 passes no events.

  ALL or 1
      A	filter value of	all or 1 passes	all events.

  The available	equality-operator specifiers and their alternate representa-
  tions	are shown in the following table.  The alternate representations may
  be used in any mix of	upper and lower	case.

  ____________________________________________
  Operator   Alternate	 Meaning
  ____________________________________________
  =	     eq		 Equal
  >	     gt		 Greater Than
  <	     lt		 Less Than
  >=	     ge		 Greater Than or Equal
  <=	     le		 Less Than or Equal
  !=	     ne		 Not Equal
  ____________________________________________

  An age-specifier comprises an	integer	value followed immediately by one of
  the letters w	(weeks), d (days), h (hours), m	(minutes) or s (seconds).  An
  age-specifier	produces an absolute time value	relative to the	present	time,
  and is most likely to	be useful in retrieving	historical events through
  evmget or the	event viewer.  It is not meaningful to use an age-specifier
  when setting a filter	for use	by the EVM logger or evmwatch.

  If a period of weeks is specified, the period	is converted to	days by	mul-
  tiplying it by 7.  When calculating an absolute time for an age specified
  in weeks or days, the	first day is always regarded as	the period from	the
  previous midnight until the present time, and	earlier	days are counted from
  midnight to midnight.	 For example, if an age-specifier of 1d	is given,
  events are selected relative to 12:00	a.m.  on the same day.	A value	of 2d
  would	select events relative to 12:00	a.m. the previous day.	A value	of 0d
  is valid, and	is equivalent to 1d.  See the following	examples for more
  information.

  If a period of hours,	minutes	or seconds is specified, an absolute time is
  calculated by	subtracting the	age from the current time, without regard to
  day boundaries.  For example,	if an age-specifier of 24h is given at
  15:23:14, events are selected	relative to 15:23:14 on	the previous day.

  A time-range-specifier consists of seven colon-separated fields in the fol-
  lowing format:

       year:month-of-year:day-of-month:day-of-week:hours:minutes:seconds

  Any component	in the time range may be replaced by an	asterisk (*) charac-
  ter as a wildcard, meaning that any value in this component will match the
  filter. You can specify multiple discrete values for a component by
  separating them with a comma.	You can	specify	a range	by using a hyphen to
  separate the starting	and ending values for the range.

  An absolute-time-specifier is	very similar to	the time-range-specifier.  It
  has only six components, and does not	allow the use of wild cards.  It has
  the following	format:

       year:month-of-year:day-of-month:hours:minutes:seconds

  In both forms	of time	specification, the range of values for each component
  is shown in the following table.

  ____________________________
  Specifier	  Range
  ____________________________
  year		  1970 to 2030
  month-of-year	  1 to 12
  day-of-month	  1 to 31
  day-of-week	  0 (Sun) to 6
  hours		  0 to 23
  minutes	  0 to 59
  seconds	  0 to 59
  ____________________________

  Any expression may be	inverted (logically negated) by	the use	of the NOT
  operator, the	exclamation mark (!) or	the keyword NOT.

  A complex filter is composed of two or more simple filters, combined using
  the AND (&&amp; or	keyword	AND) and OR (| or keyword OR) logical operators.
  Component filter expressions may be grouped in parentheses ((	and )) to set
  the precedence of test operations.  The order	of precedence of logical and
  grouping operators (highest to lowest) is:

       ( ) ! &&amp; |

  Event	filters	can be direct or indirect.  A direct filter is a text string
  appearing at the point of filter specification. An indirect filter is	con-
  tained in a file, and	is referred to using the following syntax:

  @filename:filtername

  See evmfilterfile(4) for more	information about using	indirect filters.

  If an	event being evaluated does not contain the item	being compared in a
  filter expression, the expression always yields no match.  For example, if
  the timestamp	item is	missing	from the event and you include the before
  keyword in a filter string, that part	of the filter will return no match.





NOTES

  Successive versions of EVM may evolve	the filter syntax by adding new	key-
  words	or operators.  If you use EVM's	remote connection facilities to	con-
  nect to a system running an older version of EVM, and	you attempt to
  retrieve or subscribe	for events using a filter with syntax that is not
  supported by the older version, you will receive a response indicating that
  the filter is	invalid.  To determine what syntax is supported	by the older
  system, log into the system and view this reference page.

EXAMPLES

  The following	table shows a number of	filter specifications, and the
  interpretation given to each.

  ___________________________________________________________________________
  Filter String				 Interpretation
  ___________________________________________________________________________
  "[name *]"				 Any named event.
  "[name myco.*]"

					 All events with names that start
					 with myco.
  "![name myco.*]"

					 All events with names that do not
					 start with myco.
  "[name ?.?.?]"

					 Any event with	a name that has	at
					 least three components.
  "[name myco.myapp.*]"

					 Any event with	a name that has	the
					 first two components myco.myapp.
  "[name myco.myapp]"

					 Any event with	a name that has	the
					 first two components myco.myapp.
					 Identical in meaning to the previous
					 filter	string.
  "[name sys.unix.syslog]"

					 Events	which have sys.unix.syslog as
					 the first three components of the
					 name.
  "[name myco.myapp.*.showme]"

					 Any event name	that starts with the
					 components myco.myapp and ends	with
					 showme, no matter how many com-
					 ponents are included between.
  "[age	<&lt; 1d]"				 Any event posted today.
  "[age	<&lt; 4w]"

					 Any event posted within the last 4
					 weeks.
  "[age	lt 30s]"

					 Any event posted within the last 30
					 seconds.
  "[age	gt 1d]"				 Any event posted before today.
  "[time 2000:6:1:*:*:*:*]"		 Any event posted on June 1, 2000.
  "[time 2000:6:1,3:*:*:*:*]"

					 Any event posted on June 1 or June
					 3, 2000.
  "[time 2000:6:1-3:*:*:*:*]"

					 Any event posted between June 1 and
					 June 3, 2000.
  "[time 2000:6:1-3,5-7:*:*:*:*]"

					 Any event posted between June 1 and
					 June 3, 2000, or between June 5 and
					 June 7, 2000, inclusive.
  "[time *:*:*:*:00-02:*:*]"

					 All events occurring between mid-
					 night and 2:59:59 a.m., inclusive.
  "[since 2000:6:1:03:00:00]"

					 All events occurring after 3:00 a.m.
					 on June 1, 2000.
  "[before 2000:6:1:03:00:00]"

					 All events occurring before 3:00
					 a.m. on June 1, 2000.
  "[prio >&gt; 500]"

					 All events with priority greater
					 than 500
  "[name myco.myapp] &&amp; [pri >&gt;= 500]"

					 All events that have names starting
					 with myco.myapp and priority at
					 least 500.


  "[name myco.myapp] | [pri >&gt;= 500]"

					 All events that have names starting
					 with myco.myapp or that have prior-
					 ity at	least 500.


  "[name sys.unix.syslog] &&amp;  [age <&lt;
  2d]"


					 All syslog events occurring today or
					 yesterday.



  "[name sys.unix.syslog] and  [time
  2000:6:1-3:*:*:*:*]"


					 All syslog events occurring on	June
					 1, 2 or 3, 2000.
  "none"				 Passes	no events.
  "0"					 Passes	no events.
  "all"					 Passes	all events.
  "1"					 Passes	all events.
  "@sys"

					 Specifies an indirect filter.	The
					 filter	string is the default filter
					 contained in a	filter file named sys
					 or sys.evf.
  "@sys:advfs"

					 Specifies an indirect filter.	The
					 filter	string is the filter named
					 advfs contained in a filter file
					 named sys or sys.evf.
  ___________________________________________________________________________

SEE ALSO

  Commands: evmget(1), evmshow(1), evmwatch(1)

  Routines: EvmConnSubscribe(3), EvmFilterCreate(3), EvmFilterDestroy(3),
  EvmFilterIsFile(3), EvmFilterReadFile(3), EvmFilterSet(3), EvmFilterTest(3)

  Files: evmfilterfile(4)

  Event	Management: EVM(5)

  EVM Events: EvmEvent(5)