This is usage documentation for for the procedures zget, zput, zfile::lock, and zfile::unlock (version 1.0). Executable source code has been placed in the public domain. You can find it with an annotated description. Both this usage documentation and the annotated description are copyrighted J Adrian Zimmer, 1998.

The zfile procedures provide read/write access to "short" files and can cooperate with a file locking mechanism that works on multiple platforms.

The procedures zget and zput will read and write entire files and are useful without the locking mechanism. In fact, they ignore locks unless used with the -mutex switch.

The file locking mechanism is a variant on the use of lock files (as seen in older Unix programs). A file is "locked" by creating another file whose existence tells procedures to stay away from the original file.

The zfile procedures will honor a lock that has existed for less than zfile::MinLockTime seconds. After that, a procedure will destroy the old lock and create its own. The intent here is to provide for exclusive access to short files for a very limited length of time. The use of a time limit solves problems that would otherwise be created when procedures create locks and then die abnormally.

The constant parameter zfile::MinLockTime is set to 20 seconds in the original distribution. This value may be changed keeping in mind that the time should be short but long enough for an unexpected interruption during a file transfer. Also, be aware that, if a third procedure grabs the lock, then a procedure that is waiting for the lock may wait longer than zfile::MinLockTime. The lock mechanism will give up after waiting 10 times longer than zfile::MinLockTime.

This script needs to source the following script:

zproc

These scripts will be automatically sourced.

This script requires Tcl version 8.0, or later.