MAN page from CentOS Other silk-rwpollexec-3.19.1-3.el8.x86_64.rpm


Section: SiLK Tool Suite (8)
Updated: 2021-01-04


rwpollexec - Monitor a directory for files and execute a command on them 


  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


rwpollexec is a daemon that monitors a directory for incoming filesand executes a given command on each file. If the command runssuccessfully on a file, the file is either moved to an archivedirectory or deleted. If the command runs unsuccessfully or isterminated by a signal, the file is moved to an error directory.

rwpollexec executes a single command on each file. If you need torun multiple commands on a file, create a script to run the commandsand have rwpollexec execute the script.

The --simultaneous switch specifies the maximum number ofinvocations of COMMAND that rwpollexec will run concurrently.The default is one, which causes rwpollexec to process the filesone at a time.

If there is a possibility that the command will ``hang'' and causerwpollexec to stop processing files, you may wish to specify thatrwpollexec send a signal to the command after it has been runningfor some number of seconds by using the --timeout switch. Thisswitch may be repeated to send different signals after various times.

When rwpollexec is signaled to exit, it waits for all runningcommands to terminate before exiting. If a command has ``hung'',rwpollexec does not exit until that command is killed, or untilrwpollexec itself is sent a SIGKILL.

As rwpollexec scans the incoming file directory, it ignores a fileif its size is 0 bytes or if its name begins with a dot ("."). Oneach scan, if rwpollexec detects a file name that was not presentin the previous scan, it records the name and size of the file. Ifthe file has a different size on the next scan, the new size isrecorded. Once the file has the same size on two consecutive scans,rwpollexec executes the command on the file.

If the exit status of running the command of a file is zero,rwpollexec deletes the file unless the --archive-directoryswitch is specified, in which case the file is moved to that directoryor to a subdirectory of that directory depending on whether the--flat-archive switch is specified.

If the exit status of the command is non-zero, the file is moved tothe error directory. rwpollexec does not provide a method tore-try a command that fails. 


Option names may be abbreviated if the abbreviation is unique or is anexact match for an option. A parameter to an option may be specifiedas --arg=param or --arg param, though the first form isrequired for options that take optional parameters.
Periodically scan the directory DIR_PATH for files on which to runthe command specified by the --command switch. As rwpollexecscans DIR_PATH, it ignores a file if its name begins with a dot(".") or if its size is 0 bytes. When a file is first detected, itssize is recorded, and the file must have the same size for twoconsecutive scans before rwpollexec will execute the command on it.The interval between scans is set by --polling-interval.DIR_PATH must be a complete directory path. This switch isrequired.
Run COMMAND on each file noticed in the directory specified by--incoming-directory. Each occurrence of the string %s inCOMMAND is replaced with the full path to the file, and eachoccurrence of "%%" is replaced with "%". If any other characterfollows "%", rwpollexec exits with an error. If the exit statusof COMMAND is zero, rwpollexec deletes the file unless the--archive-directory switch is specified, in which caserwpollexec moves the file to that directory. If the command exitswith a non-zero status or is terminated by a signal, rwpollexecmoves the file to the directory specified by --error-directory.This switch is required.

COMMAND is interpreted by the shell used by rwpollexec. Whenthe "SILK_RWPOLLEXEC_SHELL" environment variable is set, its value isused as the shell. Otherwise, rwpollexec determines the shell asdescribed in the ``FILES'' section. Any output on "stdout" or"stderr" from COMMAND will appear in the log when the log messagesare being written to a local log file.

Move to this directory files where COMMAND either runsunsuccessfully (i.e., has a non-zero exit status) or terminates by asignal. DIR_PATH must be a complete directory path. This switchis required.
Move to this directory the files where COMMAND runs successfully(i.e., has an exit status of zero). DIR_PATH must be a completedirectory path. If this switch is not supplied, rwpollexec willdelete these files instead. When the --flat-archive switch is alsoprovided, incoming files are moved into DIR_PATH; when--flat-archive is not given, each file is moved to a subdirectoryof DIR_PATH based on the current local time:DIR_PATH/YEAR/MONTH/DAY/HOUR/. Removing files from thearchive-directory is not the job of rwpollexec; the systemadministrator should implement a separate process to clean thisdirectory.
When archiving input files via the --archive-directory switch, movethe files into the top of the archive-directory, not intosubdirectories of the archive-directory. This switch has no effect if--archive-directory is not also specified. This switch may be usedto allow another process to watch for new files appearing in thearchive-directory.
Allow a maximum of NUM commands to be executed simultaneously. Thedefault is one, which allows only one command to be run at a time.The maximum value allowed for this switch is 50.
Send SIGNAL to the running command if it has been executing forSECS seconds. SIGNAL may be a signal name, with or without a"SIG" prefix, or a signal number. A list of signals can bedetermined by running the command "kill -l" at a shell prompt(cf. kill(1)). This switch may be repeated to send differentsignals after various amounts of time.
Configure rwpollexec to check the incoming directory for newfiles every NUM seconds. The default polling interval is 15seconds.

One of the following logging switches is required:

Specify the destination where logging messages are written. WhenDESTINATION begins with a slash "/", it is treated as a filesystem path and all log messages are written to that file; there is nolog rotation. When DESTINATION does not begin with "/", it mustbe one of the following strings:
Messages are not written anywhere.
Messages are written to the standard output.
Messages are written to the standard error.
Messages are written using the syslog(3) facility.
Messages are written to the syslog facility and to the standard error(this option is not available on all platforms).
Use DIR_PATH as the directory where the log files are written.DIR_PATH must be a complete directory path. The log files have theform


where YYYYMMDD is the current date and LOG_BASENAME is theapplication name or the value passed to the --log-basename switchwhen provided. The log files are rotated: At midnight local time, anew log is opened, the previous file is closed, and the commandspecified by --log-post-rotate is invoked on the previous day's logfile. (Old log files are not removed by rwpollexec; theadministrator should use another tool to remove them.) When thisswitch is provided, a process-ID file (PID) is also written in thisdirectory unless the --pidfile switch is provided.

Use FILE_PATH as the complete path to the log file. The log fileis not rotated.

The following set of switches is optional:

Set the severity of messages that are logged. The levels from mostsevere to least are: "emerg", "alert", "crit", "err", "warning","notice", "info", "debug". The default is "info".
Set the facility that syslog(3) uses for logging messages. Thisswitch takes a number as an argument. The default is a value thatcorresponds to "LOG_USER" on the system where rwpollexec isrunning. This switch produces an error unless--log-destination=syslog is specified.
Use LOG_BASENAME in place of the application name in the name oflog files in the log directory. See the description of the--log-directory switch. This switch does not affect the name ofthe process-ID file.
Run COMMAND on the previous day's log file after log rotation.When this switch is not specified, the previous day's log file iscompressed with gzip(1). When the switch is specified andCOMMAND is the empty string, no action is taken on the log file.Each occurrence of the string %s in COMMAND is replaced with thefull path to the log file, and each occurrence of "%%" is replacedwith "%". If any other character follows "%", rwpollexec exitswith an error. Specifying this switch without also using--log-directory is an error.
Set the complete path to the file in which rwpollexec writes itsprocess ID (PID) when it is running as a daemon. No PID file iswritten when --no-daemon is given. When this switch is notpresent, no PID file is written unless the --log-directory switchis specified, in which case the PID is written toLOGPATH/
Do not change directory to the root directory. When rwpollexecbecomes a daemon process, it changes its current directory to the rootdirectory so as to avoid potentially running on a mounted file system.Specifying --no-chdir prevents this behavior, which may be usefulduring debugging. The application does not change its directory when--no-daemon is given.
Force rwpollexec to run in the foreground---it does not become adaemon process. This may be useful during debugging.
Print the available options and exit.
Print the version number and information about how SiLK wasconfigured, then exit the application.


The shell to use for executing commands. If this variable is not set,rwpollexec tests the list of shells specified in ``FILES'' to finda shell that uses a member of the execl(3) family of functions torun the command. More details are available in the ``BUGS'' section.


Shells that rwpollexec may use to invoke the command specified by--command. The shell specified in SILK_RWPOLLEXEC_SHELL is alwaysused when that variable is set. Otherwise, rwpollexec checks thelist of shells to find one that uses execl(3) to invoke thecommand. When a suitable shell is not found, rwpollexec uses/bin/sh. See ``BUGS'' for additional information.


rwpollexec uses a subshell to execute the command specified as theargument to --command. How the subshell invokes the command isimportant when the --timeout switch is specified. Many shells usea member of execl(3) family of functions to invoke the command,which causes the command's process to replace the shell process. Forthese shells, signals sent by rwpollexec are received by thecommand process directly. However, some shells use a combination offork(2) and wait(2) to invoke the command. In these shells, thesignal is received by the subshell instead of the command, and thiscan lead to undesirable or unreliable behavior. When theSILK_RWPOLLEXEC_SHELL environment variable is set, rwpollexec usesthat shell regardless of how it invokes its command, though if thespecified shell uses fork(2), rwpollexec will emit a warning tothe standard error and to the log. When SILK_RWPOLLEXEC_SHELL is notset, rwpollexec attempts to find a shell that uses execl(3). Ifrwpollexec fails to find a suitable shell, it uses /bin/sh andemits a warning message to standard error and to the log. The list ofshells rwpollexec checks are specified in the ``FILES'' section.

rwpollexec is unable to tell the difference between a commandreturning a non-zero exit status and a command that fails because thecommand does not exist or is malformed. Both appear as a failedcommand with a non-zero exit status. The shell may emit messages thatexplain why a command has failed. In these instances, these messageswill appear in the log.

rwpollexec only attempts to run the command one time. There is noway to tell rwpollexec to attempt the command multiple times. 


silk(7), kill(1), gzip(1), syslog(3), fork(2),wait(2), execl(3)




This document was created byman2html,using the manual pages.