9.  File and Record Locking  

      The procedures described in this section are only defined if some form of file-based locking is available on the local system (either locking of entire files, or record locking). In this case, the feature unix:file-locking is provided at the time the UNIX extension is loaded. If the local system supports locking of individual file segments, the feature unix:record-locks is provided as well, and the locking primitives are based on the fcntl() system call (otherwise the flock() system call is used).

(unix-set-lock fdescr lock wait?)

The lock argument is a lock-record with these fields:

+-----------+---------+------------------------------------------+
|  Field    |  Type   |                 Contents                 |
+-----------+---------+------------------------------------------+
+-----------+---------+------------------------------------------+
|exclusive? | boolean | exclusive lock (write lock) if #t,       |
|           |         | shared lock (read lock) otherwise        |
+-----------+---------+------------------------------------------+
|whence     | symbol  | set, current, or end:                    |
|           |         | interpretation of start (see unix-lseek) |
+-----------+---------+------------------------------------------+
|start      | integer | relative offset in bytes                 |
+-----------+---------+------------------------------------------+
|length     | integer | length in bytes                          |
|           |         | (0 means lock to EOF)                    |
+-----------+---------+------------------------------------------+

If record locks are supported, the fields whence, start, and length specify a segment in the file referred to by fdescr that is to be locked or unlocked. If only entire files can be locked, the contents of these fields are ignored by the lock procedures.

An arbitrary number of shared locks for a file or file segment may be active at a given time, but more than one exclusive lock, or both shared and exclusive locks, cannot be set at the same time. fdescr must be opened for reading to be able to set a shared lock; it must be opened with write access for an exclusive lock. A shared lock may be upgraded to an exclusive lock, and vice versa. Mandatory locking may or may not be supported by the local system.

If the wait? argument is #t and the specified lock cannot be applied, unix-set-lock blocks until the lock becomes available.

unix-set-lock returns #t if the specified lock could be applied, #f otherwise.

(unix-remove-lock fdescr lock)

This procedure removes the specified file lock or record lock from the file pointed to by fdescr. lock is a lock-record; see unix-set-lock above for a description. unix-remove-lock returns the non-printing object.

(unix-query-lock fdescr lock)

If record locks are not supported, this procedure always returns #f. If record locks are supported, unix-query-lock returns information about the first lock that would cause a call to unix-set-lock with lock to fail or block, or #f if no such lock exists (i.e. if claiming the specified lock would succeed). Information about the lock is returned as a pair; the car is an integer (the process-ID of the the process that owns the lock), the cdr is a lock-record. The process-ID may be meaningless in a network environment.


Markup created by unroff 1.0,    September 24, 1996,    net@informatik.uni-bremen.de