Function

f_setlk invokes the fcntl callable service to set or release a lock on part of a file.

Parameters

fd

The file descriptor (a number) for the file.

stem

The name of a stem variable that is the flock structure used to set or release the lock. To access the information, you can specify a numeric value (see REXX predefined variables) or the predefined variables beginning with L_ that derive the appropriate numeric value. For example, stem.1 and stem.l_type are both the lock-type request.

Variable	Description
L_LEN	The length of the byte range that is to be set, cleared, or queried.
L_PID	The process ID of the process holding the blocking lock, if one was found.
L_START	The starting offset byte of the lock that is to be set, cleared, or queried.
L_TYPE	The type of lock being set, cleared, or queried. To specify the information, you can specify a numeric value (see REXX predefined variables) or one of the following predefined variables used to derive the appropriate numeric value:
	F_RDLCK Shared or read lock. This type of lock specifies that the process can read the locked part of the file, and other processes cannot write on that part of the file in the meantime. A process can change a held write lock, or any part of it, to a read lock, thereby making it available for other processes to read. Multiple processes can have read locks on the same part of a file simultaneously. To establish a read lock, a process must have the file accessed for reading.
	F_WRLCK Exclusive or write lock. This type of lock indicates that the process can write on the locked part of the file, without interference from other processes. If one process puts a write lock on part of a file, no other process can establish a read lock or write lock on that same part of the file. A process cannot put a write lock on part of a file if there is already a read lock on an overlapping part of the file, unless that process is the only owner of that overlapping read lock. In such a case, the read lock on the overlapping section is replaced by the write lock being requested. To establish a write lock, a process must have the file accessed for writing.
L_TYPE	F_UNLCK Unlock. This is used to unlock all locks held on the given range by the requesting process.
L_WHENCE	The flag for the starting offset. To specify the information, you can specify a numeric value (see REXX predefined variables) or one of the predefined variables beginning with SEEK_ used to derive the appropriate numeric value. Valid values are: SEEK_CUR The current offset SEEK_END The end of the file SEEK_SET The specified offset

Usage notes

If the lock cannot be obtained, a RETVAL of -1 is returned along with an appropriate ERRNO and ERRNOJR. You can also use F_SETLK to release locks already held, by setting l_type to F_UNLCK.

Multiple lock requests: A process can have several locks on a file simultaneously, but it can have only one type of lock set on any given byte. Therefore, if a process puts a new lock on part of a file that it had previously locked, the process has only one lock on that part of the file and the lock type is the one given by the most recent locking operation.

Releasing locks: When an f_setlk or f_setlkw request is made to unlock a byte region of a file, all locks held by that process within the specified region are released. In other words, each byte specified on an unlock request is freed from any lock that is held against it by the requesting process.

All of a process's locks on a file are removed when the process closes a file descriptor for that file. Locks are not inherited by child processes created with the fork service.

Advisory locking: All locks are advisory only. Processes can use locks to inform each other that they want to protect parts of a file, but locks do not prevent I/O on the locked parts. A process that has appropriate permissions on a file can perform whatever I/O it chooses, regardless of which locks are set. Therefore, file locking is only a convention, and it works only when all processes respect the convention.