wait_on
—
wait for a file or directory to be changed
wait_on |
[-c ] [-h ]
[-i ] [-v ]
[-w ] [-t
timeout] file ... |
The wait_on
command waits for something to happen to the
files or directories given as arguments and then exits. It is anticipated that
the wait_on
command will be called from a shell
script, allowing, for example, a script to sleep until files have been added
to a directory or data is appended to a file. No polling is required.
The following options are available:
-c
- Print version string, copyright notice and exit.
-h
- Write information about changes to the standard output (possibly for for a
human to read).
-i
- Exit with an exit value that indicates to which file or directory an event
has occured.
-v
- Print version string, copyright notice and exit.
-w
- Only exit when something is written (i.e. ignore all other types of
events). Writing includes a file being added to a directory.
-t
- Wait for timeout seconds for an event to occur and
if none has exit anyway. The timeout value may be 0
to effect an odd kind of poll.
The wait_on
command must be able to open
file for reading.
The wait_on
command is implemented using the facilities
provided by
kqueue(3).
If a fatal error occurs wait_on
exists with a value
documented in
sysexits(3).
An exit value of 0 indicates a timeout has occured.
If the -i
flag is in effect then the exit
value of wait_on
indicates to which argument the
exit causing event has occured. A value of 1 indicates the event occured to
the first file or directory, 2 indicating the event occured to the second
file or directory and so on.
If the -i
flag is not in effect the exit
value of wait_on
is dependent on what event caused
wait_on
to exit.
- 0
- timeout seconds have elapsed with no reportable
events occuring.
- 1
- The file or directory file was deleted. See
unlink(2).
- 2
- The file file was written to or, if
file is a directory, a file was added to or removed
from file.
- 3
- The file or directory file was extended. See
truncate(2).
- 4
- The attributes of file have changed. This includes
permissions and file flags. See
chmod(2)
and
chflags(2).
- 5
- The link count of file has changed. See
link(2).
- 6
- The file or directory file has been renamed. See
rename(2).
- 7
- Access to the file or directory file has been
revoked. See
revoke(2)
and
unmount(2).
- The following example will watch your mailbox and tell you if it is
written to (as is the case when new mail arrives).
The output might be something like:
/var/mail/andrew: written extended
wait_on
would then exit with code
2.
- The following example could be used as a basis of a script to regularly
clear out the incoming directory of an FTP site.
SOURCE=/ftp/root/incoming
DESTINATION=/ftp/uploaded_files
while :; do
mv $SOURCE/* $DESTINATION
wait_on -w $SOURCE
done
You must NOT use this script as is on a
directory that untrusted users may write to. Security problems
abound!
- The following example demonstrates the use of the
-i
and -t
flags. It
displays a message indicating which, if either, of the files whose names
are stored in FILE1 or FILE2
changes first, timing out after one minute.
FILE1=1
FILE2=2
wait_on -t 60 -i $FILE1 $FILE2
case $? in
0)
echo Neither the file $FILE1 or the file $FILE2 changed.
;;
1)
echo File $FILE1 has been changed.
;;
2)
echo File $FILE2 has been changed.
;;
esac
For exit values see the EXIT VALUES
section.
- invalid timeout
- The argument given to
-t
was not parsable as an
integer between 0 and LONG_MAX
inclusive.
- can't open file for reading
- To monitor files or directories
wait_on
must be
able to open them for reading.
- -i specified with >= 64 files - exit code may be ambiguous
- If you use the
-i
flag and specify a lot of files
it is possible that wait_on
may exit with a value
that is both defined in
sysexits(3)
and is also the valid index of an argument. This is ambiguous. A warning
is produced but the action is allowed.
- unknown event of type 7 occured to file
- an event has occured to a monitored file or directory of a type that
wait_on
doesn't recognise.
- event on unknown file (file)
wait_on
has been informed that an event occured on
a file that it wasn't monitoring. This should never occur.
The wait_on
command was written in January 2002.
wait_on
was written under FreeBSD
4.4.
Andrew Stevenson ⟨andrew@ugh.net.au⟩
- It is not easy to find out which event happend to which file. Normally you
can find out one or the other. The workaround is to use the
-h
flag and parse the output.
- The
wait_on
command uses
kqueue(3)
and at the time of this writing
kqueue(3)
could only monitor files on UFS filesystems.
- Please report any other problems or requests for enhancements to
⟨andrew@ugh.net.au⟩.