lockf, lockf64 - lock file section

Syntax	#include <unistd.h> int lockf(int fildes, int function, off_t size); int lockf64(int fildes, int function, off64_t size);
Description	lockf() is used to lock file sections, whereby recommended or mandatory write locks depend on the respective mode bits of the file (see chmod()). Lock calls from other processes attempting to lock an already locked file section either cause an error value to be returned or they pause until the resource is released. All locks for a process are removed if the process is terminated. lockf() can be used on normal files. fildes is an open file descriptor. The file descriptor must have O_WRONLY or O_RDWR permission so that the lock can be set up with this function call. function is control value which specifies the measures to be taken. The permissible values for function are defined as follows in unistd.h: #define F_ULOCK 0 /* Release locked section */ #define F_LOCK 1 /* Lock section exclusively */ #define F_TLOCK 2 /* Test section and lock it exclusively */ #define F_TEST 3 /* Test section for locks of other processes */ All other values of function are reserved for future extensions and lead to an error message if they are not implemented. F_TEST is used to determine whether a section contains a lock from another process. F_LOCK and F_TLOCK each lock a section of a file if this section is available. F_ULOCK removes the locks of a file section. size is the number of contiguous bytes to be locked or unlocked. The resource to be locked or unlocked begins at the current offset in the file and extends forward for a positive size and backward for a negative size (the preceding bytes up to but not including the current offset). If size is zero, the section from the current offset to the largest file offset is locked, i.e. from the current offset up to the current or any future end of file. An area does not need to be allocated to a file in order to be locked, because these locks can also extend beyond the end of the file. The sections locked with F_LOCK or F_TLOCK can contain or be contained in all or part of a section which was previously locked by the same process. If this situation occurs in this or neighboring sections, the sections are combined into one section. If the request requires a new element to be added to the table of active locks and this table is already full, an error message is issued and the new section is not locked. The requirements of F_LOCK and F_TLOCK differ only in the action that is taken if the resource is not available. F_LOCK causes the calling process to pause until the resource is available. F_TLOCK causes the function to return -1 and set errno to the EACCES error if the section is already locked by another process. Locked sections are released by the first close call issued by the process which set the lock for a file descriptor of the associated file. F_ULOCK requests can fully or partially release one or more locked sections controlled by the process. Locked sections are unlocked as of the point of the offset until size bytes have been unlocked or until the end of the file if size has the value (off_t)0. If the sections are not fully unlocked, the remaining sections stay locked by the process. The release of the middle segment of a locked section requires an additional entry in the table of active locks. If this table is full, errno is set to ENOLK and the requested section is not released. A deadlock situation can arise if a process that controls a locked resource is made to pause by a request for the locked resource of another process. Therefore when lockf() or fcntl() are called, a check is first made for possible deadlocks before the process is suspended until a locked resource is released. If the waiting for a locked resource would cause a deadlock, the call fails and errno is set to EDEADLK. Simultaneous locking with lockf() and fcntl() leads to undefined interactions. The waiting for a resource is interrupted with a random signal. The alarm() system call can be used for the provision of a time lock for applications which require such a facility. There is no difference in functionality between lock() and lock64() except that lockf64() the size of the area to be locked is specified in an offset type off64_t. If threads are used, then the function affects the process or a thread in the following manner: File section is locked, lock calls from other threads that attempt to lock a file section that is already locked will result in the return of an error number or the calling thread will be blocked until the section is released. All locks for a process are deleted when the process is terminated.
Return val.	0	if successful.
	-1	if an error occurs. errno is set to indicate the error. Existing locks are not changed.
Errors	lockf() and lockf64() will fail if:
	EBADF	fildes is not a valid open file descriptor, or function is F_LOCK or F_TLOCK and the file addressed via fildes is not opened for writing.
	EACCES	function is F_TLOCK or F_TEST, and the section is already locked by another process.
	EDEADLK	function is F_LOCK and a deadlock would occur.
	EINTR	A signal was caught during execution of the function.
	EAGAIN	function is F_LOCK or F_TLOCK and the file was generated with mmap().
	ENOLCK	function is F_LOCK, F_TLOCK or F_ULOCK, and there is no longer enough storage space for additional entries in the lock table.
	EINVAL	fildes points to a file type that cannot be locked in this implementation, or the contents of function are invalid, or the sum of size plus the current file offset is less than 0 or greater than the highest permissible file offset.
	ECOMM	fildes is on a remote computer and the link to this computer is no longer active.
	EOVERFLOW	The offset of the first byte or, when the size is not equal to 0, the last byte in the requested section cannot be represented correctly in an object of type off_t.
Notes	Unexpected events can occur in processes that buffer in the address space of the user. The process can later read or write data that is or was locked. The standard I/O package is the most common cause of unexpected buffering. Instead of this, simpler functions should be used which work unbuffered, e.g. open(). Because the errno variable will in future be set to EAGAIN and not to EACCES if a file section is already locked by another process, portable user programs must expect and check both values. The alarm() function can be used to monitor a timeout which may occur.
See also	alarm(), chmod(), close(), creat(), fcntl(), mmap(), open(), read(), write(), unistd.h.