commit e406b110d302fe4a2f378882d4762ff96f5b477b
parent db0d32a5f480449fb9f040b89d0d89366e761d22
Author: Natasha Kerensikova <natacha@instinctive.eu>
Date: Mon, 19 Oct 2015 21:37:39 +0200
Add man pages for `filewatcherd(8)` and `watchtab(5)`
Diffstat:
| A | filewatcherd.8 | | | 49 | +++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | watchtab.5 | | | 104 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
2 files changed, 153 insertions(+), 0 deletions(-)
diff --git a/filewatcherd.8 b/filewatcherd.8
@@ -0,0 +1,49 @@
+.\" Copyright (c) 2015, Natacha Porté
+.\"
+.\" Permission to use, copy, modify, and distribute this software for any
+.\" purpose with or without fee is hereby granted, provided that the above
+.\" copyright notice and this permission notice appear in all copies.
+.\"
+.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+.Dd October 19, 2015
+.Dt FILEWATCHERD 8
+.Os
+.Sh NAME
+.Nm filewatcherd
+.Nd run commands in response to file changes
+.Sh SYNOPSIS
+.Nm
+.Op Fl dh
+.Op Fl w Ar delay_ms
+.Ar watchtab
+.Sh DESCRIPTION
+.Nm
+is a daemon inspired by cron, that run commands based on file
+changes instead of time.
+In principle it is similar to incron, but it's simpler, more limited,
+and does not depend on anything outside of FreeBSD base.
+.Pp
+.Ar watchtab
+describes which paths and what events to watch, and commands to run
+when triggered.
+.Sh OPTIONS
+The following options are supported by
+.Nm :
+.Bl -tag -width "foo"
+.It Fl d , Cm --foreground
+Don't fork to background and log to stderr.
+.It Fl h , Cm --help
+Display help text.
+.It Fl w Ar delay_ms , Cm --wait Ar delay_ms
+Wait that number of milliseconds after
+.Ar watchtag
+changes before reloading it.
+.El
+.Sh SEE ALSO
+.Xr watchtab 5
diff --git a/watchtab.5 b/watchtab.5
@@ -0,0 +1,104 @@
+.\" Copyright (c) 2015, Natacha Porté
+.\"
+.\" Permission to use, copy, modify, and distribute this software for any
+.\" purpose with or without fee is hereby granted, provided that the above
+.\" copyright notice and this permission notice appear in all copies.
+.\"
+.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+.Dd October 19, 2015
+.Dt WATCHTAB 5
+.Os
+.Sh NAME
+.Nm watchtab
+.Nd tables for driving filewatcherd
+.Sh DESCRIPTION
+A
+.Nm
+file contains instructions to the
+.Xr filewatcherd 8
+daemon of the general form: ``run this command when these events happen
+to the file at this path''.
+.Pp
+Blank lines and leading spaces and tabs are ignored.
+Lines whose first non-space character is a pound-sign (#) are comments,
+and are ignored. Note that comments are not allowed on the same line as
+.Nm
+commands, since they will be taken to be part of the command.
+Similarly, comments are not allowed on the same line as
+environment variable settings.
+.Pp
+An active line of a
+.Nm
+will be either an environment setting or a command.
+An environment setting is of the form
+.Bd -literal
+ name = value
+.Ed
+.Pp
+where the spaces around the equal-sign (=) are optional, and any subsequent
+non-leading spaces in
+.Em value
+will be part of the value assigned to
+.Em name .
+Note that
+.Em name
+cannot contain any blackslash or tabulation.
+.Pp
+Several environment variables are set up automatically by the
+.Xr filewatcherd 8
+daemon.
+.Ev LOGNAME
+and
+.Ev USER
+are set to the command user,
+.Ev HOME
+is set to the home directory of the command user, unless explicitly overriden.
+.Ev TRIGGER
+is set to the path that has triggered the command execution.
+.Pp
+The format of a
+.Nm
+command is a tabulation-separated sequence of fields, interpreted as follow:
+.Bl -tag -width command
+.It path
+Path of the file to watch
+.It events
+Set of events which trigger the command. It can either be a single
+star-sign (*), or a punctuation-separated list of names among:
+DELETE, WRITE, EXTEND, ATTRIB, LINK, RENAME and REVOKE. Their meaning is
+defined in
+.Xr kqueue 2
+for
+.Va fflags
+for EVFILT_VNODE.
+.It delay
+Number of seconds, allowing a decimal point, between the trigger and when
+the command is actually run.
+.It user
+User, and optionally group preceded by a colon sign (:), to change to
+before running the command.
+.It chroot
+Path of a directory in which to chroot before running the command.
+.It command
+The command to run.
+.El
+When less than 6 fields are given in a command line, the
+.Va chroot
+value is considered omitted, and chroot will be performed.
+When less than 5 fields are given, the
+.Va user
+value is considered omitted, and no setuid or setgid will be performed.
+When less than 4 fields are given, the
+.Va delay
+value is considered as zero.
+It is an error to provide less than 3 fields.
+.Sh SEE ALSO
+.Xr crontab 5
+.Xr filewatcherd 8
+.Xr kqueue 2
