FreeBSD Manual Pages
NAME wait_on -- wait for a file or directory to be changed SYNOPSIS wait_on [-c] [-h] [-i] [-v] [-w] [-t timeout] file ... DESCRIPTION The wait_on command waits for something to happen to the files or di- rectories given as arguments and then exits. It is anticipated that the wait_on command will be called from a shell script, allowing, for exam- ple, 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 (possi- bly for for a human to read). -i Exit with an exit value that indicates to which file or direc- tory 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 di- rectory. -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. IMPLEMENTATION NOTES The wait_on command is implemented using the facilities provided by kqueue(3). EXIT VALUES 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 indi- cates 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 occur- ing. 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). EXAMPLES 1. The following example will watch your mailbox and tell you if it is written to (as is the case when new mail arrives). wait_on -hw $MAIL The output might be something like: /var/mail/andrew: written extended wait_on would then exit with code 2. 2. The following example could be used as a basis of a script to reg- ularly 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! 3. 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 DIAGNOSTICS For exit values see the "EXIT VALUES" section. invalid timeout The argument given to -t was not parsable as an inte- ger 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 mon- itored 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. SEE ALSO newmail(1), kqueue(3) HISTORY The wait_on command was written in January 2002. wait_on was written under FreeBSD 4.4. AUTHORS Andrew Stevenson <andrew@ugh.net.au> BUGS 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>. January 29, 2002 WAIT_ON(1)
NAME | SYNOPSIS | DESCRIPTION | IMPLEMENTATION NOTES | EXIT VALUES | EXAMPLES | DIAGNOSTICS | SEE ALSO | HISTORY | AUTHORS | BUGS
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=wait_on&sektion=1&manpath=FreeBSD+Ports+15.0>