ChangeMode

Change the current mode of a Lock or FileHandle (V36)

This allows you to attempt to change the mode in use by a Lock or FileHandle. For example, you could attempt to turn a shared Lock into an exclusive Lock. The handler may well reject this request.

type

Either CHANGE_FH or CHANGE_LOCK

object

A Lock or FileHandle; never use NULL

newmode

The new mode you want, which must be either SHARED_LOCK or EXCLUSIVE_LOCK, even for the CHANGE_FH type

If you use the wrong type for the object, e.g. CHANGE_FH for a Lock, undefined behaviour may follow, which includes crashing your program or the file system.

The "type" parameter must be either CHANGE_FH or CHANGE_LOCK.

The "newmode" parameter must be either SHARED_LOCK or EXCLUSIVE_LOCK, regardless of whether the "type" parameter is CHANGE_FH or CHANGE_LOCK. This may appear to be a mistake, but it is indeed the correct behaviour.

If the "type" parameter is CHANGE_FH, you will need to know how to translate the file Open() mode into the associated SHARED_LOCK or EXCLUSIVE_LOCK "newmode" parameter:

MODE_NEWFILE

Use EXCLUSIVE_LOCK for the "newmode" parameter

MODE_OLDFILE

Use SHARED_LOCK for the "newmode" parameter

MODE_READWRITE

Use SHARED_LOCK for the "newmode" parameter

A FileHandle always contains a Lock, and it is this Lock which ChangeMode(CHANGE_FH, ...) will change.

If you accidentally call ChangeMode(CHANGE_LOCK, ...) on a file or ChangeMode(CHANGE_FH, ...) on a Lock, the effects will be unpredictable. ChangeMode() does not validate the "newmode" parameter. This task falls to the respective file system or handler.

As research shows, many file system implementations just copy the "newmode" value to the Lock or file after having first checked that there is currently no other Lock or file using exclusive access. However, these tests compare the "newmode" value against SHARED_LOCK/EXCLUSIVE_LOCK.

If you accidentally provided a "newmode" value which is none of SHARED_LOCK and EXCLUSIVE_LOCK, then functions such as DupLock(), DupLockFromFH(), NameFromLock() and NameFromFH() may unexpectedly fail because the file system encounters a Lock/FileHandle which uses neither SHARED_LOCK/EXCLUSIVE_LOCK. Which approach the file takes here is implementation-specific, so there is no predictable behaviour in this context.

The original V36-V40 documentation for the ChangeLock() function did not provide specific details on which values were suitable for the "newmode" parameter. It just stated "The new mode you want" and nothing more, leading developers to pick MODE_NEWFILE, MODE_OLDFILE or MODE_READWRITE for ChangeLock(CHANGE_FH, fh, ...).

success

Boolean

Did not work in 2.02 or before (V36). Works in V37. In the earlier versions, it can crash the machine.

Will crash in V36-V47.23 if type == CHANGE_FH and the object is a FileHandle opened on "NIL:". Fixed in V47.24.

Broken for valid (not NULL) Lock and FileHandle beginning with V47.20, ChangeMode() immediately returning FALSE and setting IoErr() to ERROR_INVALID_LOCK. Fixed in V47.30.

A workaround for the use of MODE_NEWFILE, MODE_OLDFILE and MODE_READWRITE as the "newmode" parameter is provided in V47.35, which may be removed in a future release.

Lock(), Open(), DupLock(), DupLockFromFH(), NameFromLock(), NameFromFH()