DragonFly On-Line Manual Pages
rwpollexec(8) SiLK Tool Suite rwpollexec(8)
NAME
rwpollexec - Monitor a directory for files and execute a command on
them
SYNOPSIS
rwpollexec --incoming-directory=DIR_PATH --command=COMMAND
--error-directory=DIR_PATH [--archive-directory=DIR_PATH]
[--flat-archive] [--simultaneous=NUM]
[--timeout=SIGNAL,SECS [--timeout=SIGNAL,SECS ...]]
[--polling-interval=NUM]
{ --log-destination=DESTINATION
| --log-pathname=FILE_PATH
| --log-directory=DIR_PATH [--log-basename=LOG_BASENAME]
[--log-post-rotate=COMMAND] }
[--log-level=LEVEL] [--log-sysfacility=NUMBER]
[--pidfile=FILE_PATH] [--no-chdir] [--no-daemon]
rwpollexec --help
rwpollexec --version
DESCRIPTION
rwpollexec is a daemon that monitors a directory for incoming files,
and then runs a given command on each file. If the command runs
successfully on a file, the file is either moved to an archive
directory or deleted. If the command runs unsuccessfully or is
terminated by a signal, the file is moved to an error directory.
rwpollexec allows a single command to be specified. If you need to run
multiple commands on a file, create a script to run these commands and
have rwpollexec run the script.
The --simultaneous switch specifies the maximum number of invocations
of COMMAND that rwpollexec will run concurrently. The default is one,
which causes rwpollexec to process the files one at a time.
If there is a possibility that the command will "hang" and cause
rwpollexec to stop processing files, you may wish to specify that
rwpollexec send a signal to the command after it has been running for
some number of seconds by using the --timeout switch. This switch may
be repeated to send different signals after various times.
When rwpollexec is signaled to exit, it waits for all running commands
to terminate before exiting. If a command has "hung", rwpollexec will
not exit until that command is killed, or rwpollexec itself is sent a
SIGKILL.
OPTIONS
Option names may be abbreviated if the abbreviation is unique or is an
exact match for an option. A parameter to an option may be specified
as --arg=param or --arg param, though the first form is required for
options that take optional parameters.
--incoming-directory=DIR_PATH
Monitor this directory for new files to handle. DIR_PATH must be a
complete directory path. For each new file in this directory,
rwpollexec will run the command specified by the --command switch.
rwpollexec ignores any files in this directory that are empty or
whose names begin with a dot ("."). In addition, new files will
only be considered when their size is constant for one polling-
interval after they are first noticed. This switch is required.
--command=COMMAND
Run COMMAND on each file noticed in the directory specified by
--incoming-directory. Each occurrence of the string %s in COMMAND
will be replaced with the full path to the file, and each
occurrence of "%%" will be replaced with "%". If any other
character follows "%", rwpollexec exits with an error. If the exit
status of COMMAND is zero, rwpollexec will delete the file unless
the --archive-directory switch is specified, in which case
rwpollexec moves the file to that directory. If the command exits
with a non-zero status or is terminated by a signal, rwpollexec
moves the file to the directory specified by --error-directory.
This switch is required.
COMMAND is interpreted by the shell used by rwpollexec. When the
"SILK_RWPOLLEXEC_SHELL" environment variable is set, its value will
be used as the shell. Otherwise, rwpollexec determines the shell
as described in the "FILES" section. Any output on "stdout" or
"stderr" from COMMAND will appear in the log when the log messages
are being written to a local log file.
--error-directory=DIR_PATH
Move to this directory files where COMMAND either runs
unsuccessfully (i.e., has a non-zero exit status) or terminates by
a signal. DIR_PATH must be a complete directory path. This switch
is required.
--archive-directory=DIR_PATH
Move to this directory the files where COMMAND runs successfully
(i.e., has an exit status of zero). DIR_PATH must be a complete
directory path. If this switch is not supplied, rwpollexec will
delete these files instead. When the --flat-archive switch is also
provided, incoming files are moved into the top of DIR_PATH; when
--flat-archive is not given, each file is moved to a subdirectory
based on the current local time: DIR_PATH/YEAR/MONTH/DAY/HOUR/.
Removing files from the archive-directory is not the job of
rwpollexec; the system administrator should implement a separate
process to clean this directory.
--flat-archive
When archiving input files via the --archive-directory switch, move
the files into the top of the archive-directory, not into
subdirectories of the archive-directory. This switch has no effect
if --archive-directory is not also specified. This switch can be
used to allow another process to watch for new files appearing in
the archive-directory.
--simultaneous=NUM
Allow a maximum of NUM commands to be executed simultaneously. The
default is one, which allows only one command to be run at a time.
The maximum value allowed for this switch is 50.
--timeout=SIGNAL,SECS
Send SIGNAL to the running command if it has been executing for
SECS seconds. SIGNAL can be a signal name, with or without a "SIG"
prefix, or a signal number. A list of signals can be determined by
running the command "kill -l". This switch may be repeated to send
different signals after various amounts of time.
--polling-interval=NUM
Configure rwpollexec to check the incoming directory for new files
every NUM seconds. The default polling interval is 15 seconds.
One of the following logging switches is required:
--log-destination=DESTINATION
Specify the destination where logging messages are written. When
DESTINATION begins with a slash "/", it is treated as a file system
path and all log messages are written to that file; there is no log
rotation. When DESTINATION does not begin with "/", it must be one
of the following strings:
"none"
Messages are not written anywhere.
"stdout"
Messages are written to the standard output.
"stderr"
Messages are written to the standard error.
"syslog"
Messages are written using the ssyysslloogg(3) facility.
"both"
Messages are written to the syslog facility and to the standard
error (this option is not available on all platforms).
--log-directory=DIR_PATH
Use DIR_PATH as the directory where the log files are written.
DIR_PATH must be a complete directory path. The log files have the
form
DIR_PATH/LOG_BASENAME-YYYYMMDD.log
where YYYYMMDD is the current date and LOG_BASENAME is the
application name or the value passed to the --log-basename switch
when provided. The log files are rotated: At midnight local time,
a new log is opened, the previous file is closed, and the command
specified by --log-post-rotate is invoked on the previous day's log
file. (Old log files are not removed by rwpollexec; the
administrator should use another tool to remove them.) When this
switch is provided, a process-ID file (PID) is also written in this
directory unless the --pidfile switch is provided.
--log-pathname=FILE_PATH
Use FILE_PATH as the complete path to the log file. The log file
is not rotated.
The following set of switches is optional:
--log-level=LEVEL
Set the severity of messages that will be logged. The levels from
most severe to least are: "emerg", "alert", "crit", "err",
"warning", "notice", "info", "debug". The default is "info".
--log-sysfacility=NUMBER
Set the facility that ssyysslloogg(3) uses for logging messages. This
switch takes a number as an argument. The default is a value that
corresponds to "LOG_USER" on the system where rwpollexec is
running. This switch produces an error unless
--log-destination=syslog is specified.
--log-basename=LOG_BASENAME
Use LOG_BASENAME in place of the application name in the name of
log files in the log directory. See the description of the
--log-directory switch. This switch does not affect the name of
the process-ID file.
--log-post-rotate=COMMAND
Run COMMAND on the previous day's log file after log rotation.
When this switch is not specified, the previous day's log file is
compressed with ggzziipp(1). When the switch is specified and COMMAND
is the empty string, no action is taken on the log file. Each
occurrence of the string %s in COMMAND will be replaced with the
full path to the log file, and each occurrence of "%%" will be
replaced with "%". If any other character follows "%", rwpollexec
exits with an error. Specifying this switch without also using
--log-directory is an error.
--pidfile=FILE_PATH
Set the complete path to the file in which rwpollexec writes its
process ID (PID) when it is running as a daemon. No PID file is
written when --no-daemon is given. When this switch is not
present, no PID file is written unless the --log-directory switch
is specified, in which case the PID is written to
LOGPATH/rwpollexec.pid.
--no-chdir
Do not change directory to the root directory. When rwpollexec
becomes a daemon process, it changes its current directory to the
root directory so as to avoid potentially running on a mounted file
system. Specifying --no-chdir prevents this behavior, which may be
useful during debugging. The application does not change its
directory when --no-daemon is given.
--no-daemon
Force rwpollexec to run in the foreground---it does not become a
daemon process. This may be useful during debugging.
--help
Print the available options and exit.
--version
Print the version number and information about how SiLK was
configured, then exit the application.
ENVIRONMENT
SILK_RWPOLLEXEC_SHELL
The shell to use for executing commands. If this variable is not
set, rwpollexec tests the list of shells specified in "FILES" to
find a shell that uses a member of the eexxeeccll(3) family of functions
to run the command. More details are available in the "BUGS"
section.
FILES
${SILK_RWPOLLEXEC_SHELL}
/bin/sh
/bin/bash
/bin/ksh
/usr/bin/sh
/usr/bin/bash
/usr/bin/ksh
Shells that rwpollexec may use to invoke the command specified by
--command. The shell specified in SILK_RWPOLLEXEC_SHELL is always
used when that variable is set. Otherwise, rwpollexec checks the
list of shells to find one that uses eexxeeccll(3) to invoke the
command. When a suitable shell is not found, rwpollexec uses
/bin/sh. See "BUGS" for additional information.
BUGS
rwpollexec uses a subshell to execute the command specified as the
argument to --command. How the subshell invokes the command is
important when the --timeout switch is specified. Many shells use a
member of eexxeeccll(3) family of functions to invoke the command, which
causes the command's process to replace the shell process. For these
shells, signals sent by rwpollexec are received by the command process
directly. However, some shells use a combination of ffoorrkk(2) and
wwaaiitt(2) to invoke the command. In these shells, the signal is received
by the subshell instead of the command, and this can lead to
undesirable or unreliable behavior. When the SILK_RWPOLLEXEC_SHELL
environment variable is set, rwpollexec uses that shell regardless of
how it invokes its command, though if the specified shell uses ffoorrkk(2),
rwpollexec will emit a warning to the standard error and to the log.
When SILK_RWPOLLEXEC_SHELL is not set, rwpollexec attempts to find a
shell that uses eexxeeccll(3). If rwpollexec fails to find a suitable
shell, it uses /bin/sh and emits and error to standard error and to the
log. The list of shells rwpollexec checks are specified in the "FILES"
section.
rwpollexec is unable to tell the difference between a command returning
a non-zero exit status and a command that fails because the command
does not exist or is malformed. Both appear as a failed command with a
non-zero exit status. The shell may emit messages that explain why a
command has failed. In these instances, these messages will appear in
the log.
SEE ALSO
ssiillkk(7), kkiillll(1), ggzziipp(1), ssyysslloogg(3), ffoorrkk(2), wwaaiitt(2), eexxeeccll(3)
SiLK 3.11.0.1 2016-02-19 rwpollexec(8)