Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
DIREVENT(8)		    Direvent User Reference		   DIREVENT(8)

NAME
       direvent	- directory event monitor

SYNOPSIS
       direvent	 [-HVdfh]  [-F NAME] [-P FILE] [-l PRIO] [-I DIR] [-T COMMAND]
       [--debug]  [--facility=NAME]  [--foreground]  [--include=DIR]   [--pid-
       file=FILE] [--self-test=COMMAND]	[--user=NAME] [CONFIG]

       direvent	-h
       direvent	--help

       direvent	-H
       direvent	--config-help

       direvent	--usage

       direvent	-V
       direvent	--version

DESCRIPTION
       GNU  Direvent  monitors a set of	directories on the file	system and re-
       acts when a file	system event occurs in any of them.   Directories  and
       events  to  monitor  are	 specified in the configuration	file.  When an
       event occurs the	utility	reacts by invoking an external command config-
       ured for	that event.

       The following generic events can	be monitored by	the program:

       create A	file was created;

       delete A	file was deleted;

       write  A	file was written to;

       attrib File attributes have changed.  This includes changes in the file
	      ownership, mode, link count, etc.

       Depending on the	interface provided by the underlying operating	system
       direvent	 can  trace various system-dependent events, which may offer a
       better resolution.  These events	are described in  the  section	SYSTEM
       DEPENDENCIES below.

       A  watcher is a configuration entity within direvent which associates a
       set of directories with a set of	events and instructs  the  program  to
       run  a specified	external command when any of these events occur	in any
       of these	directories.  This external command (called a handler) can ob-
       tain  information about the event that triggered	its execution from the
       environment variables, or from its command line (see the	HANDLER	 ENVI-
       RONMENT section below).

       Watchers	 are declared in the program configuration file	direvent.conf,
       located in the system configuration directory (normally /etc).

       An alternative configuration file can be	used, by supplying  its	 path-
       name  as	 the  command  line argument (CONFIG parameter in the SYNOPSIS
       section above).

OPTIONS
       -d, --debug
	      Increase debug verbosity level.

       -F, --facility=FACILITY
	      Log under	this syslog facility.  Allowed values for FACILITY are
	      a	 decimal  number or any	of the following symbolic names: auth,
	      authpriv,	cron, daemon, ftp, local0 through local7,  lpr,	 mail,
	      news, user, and uucp.

	      The option -F 0 directs logging to the standard error.

       -f, --foreground
	      Run in the foreground.

       -I, --include=DIR
	      Add  DIR to the include search path.  When looking for a file to
	      be included in the #include (#include_once) statement,  direvent
	      scans  first  the	directories given with -I options (in the same
	      order as given on	the command line), and then the	directories in
	      the standard include search path.	 The latter is defined at com-
	      pile time	and can	be inspected in	the output of the  --help  op-
	      tion.

       -l PRIO
	      While  connected	to a terminal direvent outputs its diagnostics
	      messages to stderr and, if configured, to	syslog.	  This	option
	      limits  the  amount of information output	to the standard	error.
	      PRIO is one of the following priorities (in order	of  increasing
	      severity):  debug,  info,	 notice,  warning,  err,  crit,	alert,
	      emerg.  When this	option is given, only messages with the	prior-
	      ity  level  equal	 to or greater than PRIO will be duplicated on
	      the standard error.

       -P, --pidfile=FILE
	      Write PID	to FILE.

       -T, --self-test=COMMAND
	      Run in self-test mode.  In this mode, direvent  starts  external
	      command  supplied	 as  the argument to this option and continues
	      running until the	command	exits.	If the command terminates nor-
	      mally, direvent exits with the code returned by it.  If the com-
	      mand terminates on SIGHUP, direvent exits	with code  0.	If  it
	      terminates on another signal, direvent exits with	code 2.

	      COMMAND  can include any command line options or arguments, pro-
	      vided that it is properly	quoted.	 It is invoked as  /bin/sh  -c
	      COMMAND in the environment of the	parent direvent	process.

	      The  macro  variable $self_test_pid holds	the PID	of the COMMAND
	      (see section MACRO EXPANSION in direvent.conf(5)).

       -t, --lint
	      Check configuration file for errors and exit.

       -u, --user=USER
	      Run as this USER.

       Informative options cause the program to	display	the requested piece of
       information and exit:

       -h, --help
	      Output a terse help summary and exit.

       -H, --config-help
	      Describe configuration file syntax.

       --usage
	      Show available command line options.

       -V, --version
	      Print program version and	copyright information.

CONFIGURATION
       The  default  configuration file	is /etc/direvent.conf.	If a file name
       is supplied as an argument to the program, that file will be  read  in-
       stead.

       The   configuration   file   syntax  is	discussed  in  detail  in  di-
       revent.conf(5).	This section provides only a short description of it.

       Three types of comments are allowed: inline comments, that begin	with a
       #  or  // and extend to the end of line,	and multi-line comments, which
       comprise	everything enclosed between /* and  */.	  Comments  and	 empty
       lines  are  ignored.  Whitespace	characters are ignored as well,	except
       as they serve to	separate tokens.

       A token is a  string  of	 consecutive  characters  from	the  following
       classes:	  alphanumeric	 characters,   underscores,  dots,  asteriscs,
       slashes,	semicolons, commercial at's, and dashes.

       Any other sequence of characters	must be	enclosed in  double  quotation
       marks in	order to represent a single token.

       Adjacent	quoted strings are concatenated.

       Configuration  statements  consist  of a	keyword	and value separated by
       any amount of whitespace	and is terminated with a semicolon.   A	 block
       statement is a collection of statements enclosed	in curly braces.

       The  most  important configuration statement is watcher.	 It is defined
       as follows:

	 watcher {
	     path PATHNAME [recursive [LEVEL]];
	     event EVENT-LIST;
	     command COMMAND-LINE;
	     user NAME;
	     timeout NUMBER;
	     environ ENV-SPEC;
	     option STRING-LIST;
	 }

       Each watcher statement instructs	direvent to monitor the	events	listed
       in  EVENT-LIST  occurring  in the directories specified by PATHNAMEs in
       path statements (any number of path statements can be given).  When any
       such event is detected, the COMMAND-LINE	will be	executed.

       Each  directory	defined	with the recursive keyword will	be watched re-
       cursively.  This	means that for each subdirectory created  in  it,  di-
       revent  will install a watcher similar to that of its parent directory.
       The optional LEVEL can be used to set up	a cut-off nesting  level,  be-
       yond which the recursive	operation is disabled.

       The  PATHNAME  is  not  required	to be a	directory, it can as well be a
       file of any type.  This file is not required to exist, either.	If  it
       does not, direvent will defer configuring the watcher until the file is
       eventually created.

       The rest	of statements are optional.  The user statement	can be used to
       execute	the  COMMAND-LINE  as the user NAME (provided, of course, that
       direvent	is started with	root privileges).  The timeout	specifies  the
       maximum	amount of time (in seconds) the	command	is allowed to run.  It
       defaults	to 5.  The environ statement modifies the command  environment
       (see  the  following  section).	Finally, the option statement supplies
       additional options.  It can be used, for	example, to  divert  the  com-
       mand's output to	syslog.

       The program's logging is	controlled by the debug	and syslog statements.

       debug NUMBER;
	      Sets the debugging level to NUMBER -- an integer value between 0
	      and 3.  Zero is the default and means the	debugging is disabled.
	      The  bigger  the	NUMBER the more	detailed debugging information
	      will be output.

       The syslog statement controls the syslog	logging:

	 syslog	{
	     facility STRING;
	     tag STRING;
	     print-priority BOOL;
	 }

       The pidfile statement instructs the program to write its	PID to
       the named file after disconnecting from the controlling terminal.

HANDLER	ENVIRONMENT
       The handler to be executed on an	event is defined by the	command	state-
       ment in the watcher configuration block (see direvent.conf(5)).	Before
       executing, the following	operations are performed:

       1.     The current working directory is set to the directory where  the
	      event occurred.

       2.     If the environ statement is present in the watcher, the environ-
	      ment is modified according to its	rules.	See the	description of
	      the environ statement in direvent.conf(5).

       3.     The standard input is closed.

	      If  the  stdout  option is supplied, the standard	output is cap-
	      tured and	redirected to the syslog.  Otherwise it	is closed.

	      If the stderr option is supplied,	the standard error is captured
	      and redirected to	the syslog.  Otherwise it is closed.

	      All file descriptors above 2 are closed.

       4.     Macro  variables	are expanded.  See the section MACRO EXPANSION
	      in direvent.conf(5).  For	example, if the	handler	is about to be
	      executed	for the	write event on the file	somefile, and the com-
	      mand definition was:

		  command "/libexec/handler -e '$genev_name' -f	'$file'";

	      then the resulting command line will be:

		  /libexec/handler -e 'open' -f	'somefile'

       5.     Word splitting is	performed on the resulting command line.   The
	      first  word is treated as	the pathname of	the program to be exe-
	      cuted.

       6.     The program is invoked.

SYSTEM DEPENDENCIES
       Direvent	relies on the event monitoring API provided by the kernel.

Linux
       On Linux	the program uses inotify(7).

       The maximum number of watches a user process can	have is	controlled  by
       the fs.inotify.max_user_watches system variable.	 Normally it is	set to
       8192, which is quite enough for most purposes.  However,	if you monitor
       a  big  number  or directories and/or are using recursive watchers, you
       may need	more watches.  In that case, use sysctl(8) to raise the	limit,
       e.g.:

	   sysctl -w fs.inotify.max_user_watches=16384

       Most  GNU/Linux	distributions  provide the file	/etc/sysctl.conf which
       can be used to set this variable	on startup.

       The following system-dependent events are defined on systems  that  use
       inotify(7):

       ACCESS A	file was accessed.

       ATTRIB A	file's metadata	changed.

       CLOSE_WRITE
	      A	writable file was closed.

       CLOSE_NOWRITE
	      An unwritable file closed.

       CREATE A	file was created.

       DELETE A	file was deleted.

       MODIFY A	file was modified.

       MOVED_FROM
	      A	file was moved into a monitored	directory.

       MOVED_TO
	      A	file was moved out from	a monitored directory.

       OPEN   A	file was opened.

BSD
       When   compiled	on  BSD	 systems  (including  Darwin),	direvent  uses
       kqueue(2).  This	interface needs	an open	file handle for	each file in a
       monitored directory, which means	that the number	of watchers is limited
       by the maximum number of	open files.  Use ulimit	-n NUM to raise	it  to
       a higher	number.

       Since  it operates on files, kqueue does	not provide direct support for
       the create generic event.  Direvent works  over	this  disadvantage  by
       keeping	track  of the contents of each monitored directory and rescan-
       ning it each time a WRITE system	event is reported  for	it.   It  then
       generates  the  open  event  for	each file that appeared	after the last
       scan.  Such a rescan can	consume	considerable time if a directory has a
       very large number of files in it.

       The following system-dependent events are available:

       DELETE The unlink() system call was called on the monitored file.

       WRITE  A	write occurred on the file.

       EXTEND The file was extended.

       ATTRIB The file attributes have changed.

       LINK   The link count on	the file changed.

       RENAME The file was renamed.

       REVOKE Access  to  the file was revoked via revoke(2) or	the underlying
	      file system was unmounted.

Darwin
       Essentially the same as BSD.  The main difference compared to Linux and
       BSD is that on Darwin the watchers are set after	disconnecting from the
       controlling terminal, because Darwin lacks the rfork(2)	call  and  the
       event queue cannot be inherited by the child process.

EXIT CODE
       0      Successful termination.

       1      Command line usage error.

       2      Another error occurred.

SEE ALSO
       direvent.conf(5), inotify(7), kqueue(2).

AUTHORS
       Sergey Poznyakoff

BUG REPORTS
       Report bugs to <bug-direvent@gnu.org.ua>.

COPYRIGHT
       Copyright (C) 2012, 2013	Sergey Poznyakoff
       License GPLv3+: GNU GPL version 3 or later <http://gnu.org/li-
       censes/gpl.html>
       This is free software: you are free  to	change	and  redistribute  it.
       There is	NO WARRANTY, to	the extent permitted by	law.

DIREVENT			August 25, 2016			   DIREVENT(8)

NAME | SYNOPSIS | DESCRIPTION | OPTIONS | CONFIGURATION | HANDLER ENVIRONMENT | SYSTEM DEPENDENCIES | Linux | BSD | Darwin | EXIT CODE | SEE ALSO | AUTHORS | BUG REPORTS | COPYRIGHT

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=direvent&sektion=8&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help