.\" .\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for .\" permission to reproduce portions of its copyrighted documentation. .\" Original documentation from The Open Group can be obtained online at .\" http://www.opengroup.org/bookstore/. .\" .\" The Institute of Electrical and Electronics Engineers and The Open .\" Group, have given us permission to reprint portions of their .\" documentation. .\" .\" In the following statement, the phrase ``this text'' refers to portions .\" of the system documentation. .\" .\" Portions of this text are reprinted and reproduced in electronic form .\" in the SunOS Reference Manual, from IEEE Std 1003.1, 2004 Edition, .\" Standard for Information Technology -- Portable Operating System .\" Interface (POSIX), The Open Group Base Specifications Issue 6, .\" Copyright (C) 2001-2004 by the Institute of Electrical and Electronics .\" Engineers, Inc and The Open Group. In the event of any discrepancy .\" between these versions and the original IEEE and The Open Group .\" Standard, the original IEEE and The Open Group Standard is the referee .\" document. The original Standard can be obtained online at .\" http://www.opengroup.org/unix/online.html. .\" .\" This notice shall appear on any product containing this material. .\" .\" The contents of this file are subject to the terms of the .\" Common Development and Distribution License (the "License"). .\" You may not use this file except in compliance with the License. .\" .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE .\" or http://www.opensolaris.org/os/licensing. .\" See the License for the specific language governing permissions .\" and limitations under the License. .\" .\" When distributing Covered Code, include this CDDL HEADER in each .\" file and include the License file at usr/src/OPENSOLARIS.LICENSE. .\" If applicable, add the following below this CDDL HEADER, with the .\" fields enclosed by brackets "[]" replaced with your own identifying .\" information: Portions Copyright [yyyy] [name of copyright owner] .\" .\" .\" Copyright 1989 AT&T .\" Portions Copyright (c) 1992, X/Open Company Limited All Rights Reserved .\" Copyright (c) 2002, Sun Microsystems, Inc. All Rights Reserved. .\" Copyright 2015 Joyent, Inc. .\" .TH LOCKF 3C "Feb 16, 2015" .SH NAME lockf \- POSIX-style record locking on files .SH SYNOPSIS .LP .nf #include \fBint\fR \fBlockf\fR(\fBint\fR \fIfildes\fR, \fBint\fR \fIfunction\fR, \fBoff_t\fR \fIsize\fR); .fi .SH DESCRIPTION .LP The \fBlockf()\fR function allows sections of a file to be locked; advisory or mandatory write locks depending on the mode bits of the file (see \fBchmod\fR(2)). Calls to \fBlockf()\fR from other threads that attempt to lock the locked file section will either return an error value or be put to sleep until the resource becomes unlocked. All the locks for a process are removed when the process terminates. See \fBfcntl\fR(2) for more information about record locking. .sp .LP The \fIfildes\fR argument is an open file descriptor. The file descriptor must have \fBO_WRONLY\fR or \fBO_RDWR\fR permission in order to establish locks with this function call. .sp .LP The \fIfunction\fR argument is a control value that specifies the action to be taken. The permissible values for \fIfunction\fR are defined in <\fBunistd.h\fR> as follows: .sp .in +2 .nf #define F_ULOCK 0 /* unlock previously locked section */ #define F_LOCK 1 /* lock section for exclusive use */ #define F_TLOCK 2 /* test & lock section for exclusive use */ #define F_TEST 3 /* test section for other locks */ .fi .in -2 .sp .LP All other values of \fIfunction\fR are reserved for future extensions and will result in an error if not implemented. .sp .LP \fBF_TEST\fR is used to detect if a lock by another process or open file handle is present on the specified section. \fBF_LOCK\fR and \fBF_TLOCK\fR both lock a section of a file if the section is available. \fBF_ULOCK\fR removes locks from a section of the file. .sp .LP The \fIsize\fR argument is the number of contiguous bytes to be locked or unlocked. The resource to be locked or unlocked starts at the current offset in the file and extends forward for a positive \fIsize\fR and backward for a negative \fIsize\fR (the preceding bytes up to but not including the current offset). If \fIsize\fR is zero, the section from the current offset through the largest file offset is locked (that is, from the current offset through the present or any future end-of-file). An area need not be allocated to the file in order to be locked as such locks may exist past the end-of-file. .sp .LP The sections locked with \fBF_LOCK\fR or \fBF_TLOCK\fR may, in whole or in part, contain or be contained by a previously locked section for the same process. Locked sections will be unlocked starting at the point of the offset through \fIsize\fR bytes or to the end of file if \fIsize\fR is (\fBoff_t\fR) 0. When this situation occurs, or if this situation occurs in adjacent sections, the sections are combined into a single section. If the request requires that a new element be added to the table of active locks and this table is already full, an error is returned, and the new section is not locked. .sp .LP \fBF_LOCK\fR and \fBF_TLOCK\fR requests differ only by the action taken if the resource is not available. \fBF_LOCK\fR blocks the calling thread until the resource is available. \fBF_TLOCK\fR causes the function to return \(mi1 and set \fBerrno\fR to \fBEAGAIN\fR if the section is already locked by another process. .sp .LP File locks are released on first close by the locking process of any file descriptor for the file. .sp .LP \fBF_ULOCK\fR requests may, in whole or in part, release one or more locked sections controlled by the process. When sections are not fully released, the remaining sections are still locked by the process. Releasing the center section of a locked section requires an additional element in the table of active locks. If this table is full, an \fBerrno\fR is set to \fBEDEADLK\fR and the requested section is not released. .sp .LP An \fBF_ULOCK\fR request in which \fIsize\fR is non-zero and the offset of the last byte of the requested section is the maximum value for an object of type \fBoff_t\fR, when the process has an existing lock in which \fIsize\fR is 0 and which includes the last byte of the requested section, will be treated as a request to unlock from the start of the requested section with a \fIsize\fR equal to 0. Otherwise, an \fBF_ULOCK\fR request will attempt to unlock only the requested section. .sp .LP A potential for deadlock occurs if the threads of a process controlling a locked resource is put to sleep by requesting another process's locked resource. Thus calls to \fBlockf()\fR or \fBfcntl\fR(2) scan for a deadlock prior to sleeping on a locked resource. An error return is made if sleeping on the locked resource would cause a deadlock. .sp .LP Sleeping on a resource is interrupted with any signal. The \fBalarm\fR(2) function may be used to provide a timeout facility in applications that require this facility. .SH RETURN VALUES .LP Upon successful completion, \fB0\fR is returned. Otherwise, \fB\(mi1\fR is returned and \fBerrno\fR is set to indicate the error. .SH ERRORS .LP The \fBlockf()\fR function will fail if: .sp .ne 2 .na \fB\fBEBADF\fR\fR .ad .RS 20n The \fIfildes\fR argument is not a valid open file descriptor; or \fIfunction\fR is \fBF_LOCK\fR or \fBF_TLOCK\fR and \fIfildes\fR is not a valid file descriptor open for writing. .RE .sp .ne 2 .na \fB\fBEACCES\fR or \fBEAGAIN\fR\fR .ad .RS 20n The \fIfunction\fR argument is \fBF_TLOCK\fR or \fBF_TEST\fR and the section is already locked by another process. .RE .sp .ne 2 .na \fB\fBEDEADLK\fR\fR .ad .RS 20n The \fIfunction\fR argument is \fBF_LOCK\fR and a deadlock is detected. .RE .sp .ne 2 .na \fB\fBEINTR\fR\fR .ad .RS 20n A signal was caught during execution of the function. .RE .sp .ne 2 .na \fB\fBECOMM\fR\fR .ad .RS 20n The \fIfildes\fR argument is on a remote machine and the link to that machine is no longer active. .RE .sp .ne 2 .na \fB\fBEINVAL\fR\fR .ad .RS 20n The \fIfunction\fR argument is not one of \fBF_LOCK\fR, \fBF_TLOCK\fR, \fBF_TEST\fR, or \fBF_ULOCK\fR; or \fIsize\fR plus the current file offset is less than 0. .RE .sp .ne 2 .na \fB\fBEOVERFLOW\fR\fR .ad .RS 20n The offset of the first, or if \fIsize\fR is not 0 then the last, byte in the requested section cannot be represented correctly in an object of type \fBoff_t\fR. .RE .sp .LP The \fBlockf()\fR function may fail if: .sp .ne 2 .na \fB\fBEAGAIN\fR\fR .ad .RS 24n The \fIfunction\fR argument is \fBF_LOCK\fR or \fBF_TLOCK\fR and the file is mapped with \fBmmap\fR(2). .RE .sp .ne 2 .na \fB\fBEDEADLK\fR or \fBENOLCK\fR\fR .ad .RS 24n The \fIfunction\fR argument is \fBF_LOCK\fR, \fBF_TLOCK\fR, or \fBF_ULOCK\fR and the request would cause the number of locks to exceed a system-imposed limit. .RE .sp .ne 2 .na \fB\fBEOPNOTSUPP\fR or \fBEINVAL\fR\fR .ad .RS 24n The locking of files of the type indicated by the \fIfildes\fR argument is not supported. .RE .SH USAGE .LP Record-locking should not be used in combination with the \fBfopen\fR(3C), \fBfread\fR(3C), \fBfwrite\fR(3C) and other \fBstdio\fR functions. Instead, the more primitive, non-buffered functions (such as \fBopen\fR(2)) should be used. Unexpected results may occur in processes that do buffering in the user address space. The process may later read/write data which is/was locked. The \fBstdio\fR functions are the most common source of unexpected buffering. .sp .LP The \fBalarm\fR(2) function may be used to provide a timeout facility in applications requiring it. .sp .LP The \fBlockf()\fR function has a transitional interface for 64-bit file offsets. See \fBlf64\fR(5). .SH ATTRIBUTES .LP See \fBattributes\fR(5) for descriptions of the following attributes: .sp .sp .TS box; c | c l | l . ATTRIBUTE TYPE ATTRIBUTE VALUE _ Interface Stability Standard _ MT-Level MT-Safe .TE .SH SEE ALSO .LP \fBIntro\fR(2), \fBalarm\fR(2), \fBchmod\fR(2), \fBclose\fR(2), \fBcreat\fR(2), \fBfcntl\fR(2), \fBmmap\fR(2), \fBopen\fR(2), \fBread\fR(2), \fBwrite\fR(2), \fBattributes\fR(5), \fBlf64\fR(5), \fBstandards\fR(5)