13.4 File/Stream Ports🔗ℹ

The mode argument can be #'shared or #'exclusive. Multiple processes can acquire a #'shared lock on a file, but at most one process can hold an #'exclusive lock, and #'shared and #'exclusive locks are mutually exclusive. When mode is #'shared, then port must be an input port; when mode is #'exclusive, then port must be an output port.

The result is #true if the requested lock is acquired, #false otherwise. When a lock is acquired, it is held until either it is released with Port.FileStream.unlock or the port is closed (perhaps because the process terminates).

Depending on the platform, locks may be merely advisory (i.e., locks affect only the ability of processes to acquire locks) or they may correspond to mandatory locks that prevent reads and writes to the locked file. Specifically, locks are mandatory on Windows and advisory on other platforms. Multiple tries for a #'shared lock on a single port can succeed; on Unix and Mac OS, a single Port.FileStream.unlock releases the lock, while on other Windows, a Port.FileStream.unlock is needed for each successful Port.FileStream.try_lock. On Unix and Mac OS, multiple tries for a #'exclusive lock can succeed and a single Port.FileStream.unlock releases the lock, while on Windows, a try for an #'exclusive lock fails for a given port if the port already holds the lock.

A lock acquired for an input port from Port.open_input_output_file can be released through Port.FileStream.unlock on the corresponding output port, and vice versa. If the output port from Port.open_input_output_file holds an #'exclusive lock, the corresponding input port can still acquire a #'shared lock, even multiple times; on Windows, a Port.open_input_output_file is needed for each successful lock try, while a single Port.open_input_output_file balances the lock tries on Unix and Mac OS. A #'shared lock on an input port can be upgraded to an #'exclusive lock through the corresponding output port on Unix and Mac OS, in which case a single Port.open_input_output_file (on either port) releases the lock, while such upgrades are not allowed on Windows.

Locking is normally supported only for file ports, and attempting to acquire a lock with other kinds of file-stream ports throws an Exn.Fail.Filesystem exception.

The Port.FileStream.stat function similarly corresponds to filesystem.stat.

On Unix and Mac OS, opening a fifo for output creates a peer-waiting port if no reader for the same fifo is already opened. In that case, the output port is not ready for writing until a reader is opened; that is, write operations will block. Use sync if necessary to wait until writing will not block—that is, until the read end of the fifo is opened.