3.2.4.16 Application Requests a Byte-Range Lock on a File

  • Article

The application provides:

  • The Client.Open representing the file to be locked.

  • An array of byte ranges to be locked. For each range, the application provides:

    • A starting offset, in bytes.

    • A length, in bytes.

  • The number of byte ranges to be locked.

  • The type of lock requested.

  • The new oplock level, if this is a request from the server in response to a change.

  • The length of time (in milliseconds) that the server is requested to wait for the locks to become available.

  • An optional Boolean indicating whether the byte ranges are to be locked or shared.

  • An optional Timeout.

Any of the following commands can be used to explicitly lock a contiguous range of bytes in a regular file:

  • SMB_COM_LOCK_BYTE_RANGE (deprecated)

    The client MUST construct the SMB_COM_LOCK_BYTE_RANGE request as defined in section 2.2.4.13.1. This command is limited to 32-bit offsets, and is considered deprecated. The SMB_COM_LOCKING_ANDX command SHOULD be used instead.

  • SMB_COM_LOCK_AND_READ (deprecated)

    This command combines the byte range lock with a read operation. The bytes locked by the request are also the bytes to be read. The application can provide an indication of the number of additional bytes immediately following the locked bytes that it designates to read. The client MUST construct the SMB_COM_LOCK_AND_READ (section 2.2.4.20.1) request.

  • SMB_COM_LOCKING_ANDX

    Multiple non-overlapping byte ranges can be locked with this command. The client MUST construct the SMB_COM_LOCKING_ANDX request as defined in section 2.2.4.32.1. This client request is atomic. If the area to be locked is already locked or the lock request otherwise fails, no other ranges specified in the client request are locked. This command is capable of using 64-bit file offsets. If CAP_LARGE_FILES is set in Client.Connection.ServerCapabilities, 64-bit offsets SHOULD be used.

    The SMB_COM_LOCKING_ANDX command supports requests for shared locks. The preceding deprecated locking commands do not support shared locks. The application can request a shared lock. If the application does not specify the lock type, an exclusive read/write lock is requested by default. The request for a shared lock is specified by setting the SHARED_LOCK bit in the TypeOfLock field (see section 2.2.4.32.1).

Locks prevent attempts by other PIDs to lock, read, or write the locked portion of the file. Overlapping exclusive locks are not permitted. Offsets beyond the current end of file can be locked. Such locks MUST NOT cause allocation of additional file space. A lock MUST be unlocked only by the PID that performed the lock.

The request MUST be sent to the server as described in section 3.2.4.1.