usr/src/man/man3c/lockf.3c

   1 .\"
   2 .\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for
   3 .\" permission to reproduce portions of its copyrighted documentation.
   4 .\" Original documentation from The Open Group can be obtained online at
   5 .\" http://www.opengroup.org/bookstore/.
   6 .\"
   7 .\" The Institute of Electrical and Electronics Engineers and The Open
   8 .\" Group, have given us permission to reprint portions of their
   9 .\" documentation.
  10 .\"
  11 .\" In the following statement, the phrase ``this text'' refers to portions
  12 .\" of the system documentation.
  13 .\"
  14 .\" Portions of this text are reprinted and reproduced in electronic form
  15 .\" in the SunOS Reference Manual, from IEEE Std 1003.1, 2004 Edition,
  16 .\" Standard for Information Technology -- Portable Operating System
  17 .\" Interface (POSIX), The Open Group Base Specifications Issue 6,
  18 .\" Copyright (C) 2001-2004 by the Institute of Electrical and Electronics
  19 .\" Engineers, Inc and The Open Group.  In the event of any discrepancy
  20 .\" between these versions and the original IEEE and The Open Group
  21 .\" Standard, the original IEEE and The Open Group Standard is the referee
  22 .\" document.  The original Standard can be obtained online at
  23 .\" http://www.opengroup.org/unix/online.html.
  24 .\"
  25 .\" This notice shall appear on any product containing this material.
  26 .\"
  27 .\" The contents of this file are subject to the terms of the
  28 .\" Common Development and Distribution License (the "License").
  29 .\" You may not use this file except in compliance with the License.
  30 .\"
  31 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
  32 .\" or http://www.opensolaris.org/os/licensing.
  33 .\" See the License for the specific language governing permissions
  34 .\" and limitations under the License.
  35 .\"
  36 .\" When distributing Covered Code, include this CDDL HEADER in each
  37 .\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
  38 .\" If applicable, add the following below this CDDL HEADER, with the
  39 .\" fields enclosed by brackets "[]" replaced with your own identifying
  40 .\" information: Portions Copyright [yyyy] [name of copyright owner]
  41 .\"
  42 .\"
  43 .\" Copyright 1989 AT&T
  44 .\" Portions Copyright (c) 1992, X/Open Company Limited  All Rights Reserved
  45 .\" Copyright (c) 2002, Sun Microsystems, Inc.  All Rights Reserved.
  46 .\" Copyright 2015 Joyent, Inc.
  47 .\"
  48 .TH LOCKF 3C "Feb 16, 2015"
  49 .SH NAME
  50 lockf \- POSIX-style record locking on files
  51 .SH SYNOPSIS
  52 .LP
  53 .nf
  54 #include <unistd.h>
  55
  56 \fBint\fR \fBlockf\fR(\fBint\fR \fIfildes\fR, \fBint\fR \fIfunction\fR, \fBoff_t\fR \fIsize\fR);
  57 .fi
  58
  59 .SH DESCRIPTION
  60 .LP
  61 The \fBlockf()\fR function allows sections of a file to be locked; advisory or
  62 mandatory write locks depending on the mode bits of the file (see
  63 \fBchmod\fR(2)). Calls to \fBlockf()\fR from other threads that attempt to lock
  64 the locked file section will either return an error value or be put to sleep
  65 until the resource becomes unlocked. All the locks for a process are removed
  66 when the process terminates. See \fBfcntl\fR(2) for more information about
  67 record locking.
  68 .sp
  69 .LP
  70 The \fIfildes\fR argument is an open file descriptor. The file descriptor must
  71 have \fBO_WRONLY\fR or \fBO_RDWR\fR permission in order to establish locks with
  72 this function call.
  73 .sp
  74 .LP
  75 The \fIfunction\fR argument is a control value that specifies the action to be
  76 taken. The permissible values for \fIfunction\fR are defined in
  77 <\fBunistd.h\fR> as follows:
  78 .sp
  79 .in +2
  80 .nf
  81 #define   F_ULOCK   0   /* unlock previously locked section */
  82 #define   F_LOCK    1   /* lock section for exclusive use */
  83 #define   F_TLOCK   2   /* test & lock section for exclusive use */
  84 #define   F_TEST    3   /* test section for other locks */
  85 .fi
  86 .in -2
  87
  88 .sp
  89 .LP
  90 All other values of \fIfunction\fR are reserved for future extensions and will
  91 result in an error if not implemented.
  92 .sp
  93 .LP
  94 \fBF_TEST\fR is used to detect if a lock by another process or open file handle
  95 is present on the specified section. \fBF_LOCK\fR and \fBF_TLOCK\fR both lock
  96 a section of a file if the section is available. \fBF_ULOCK\fR removes locks
  97 from a section of the file.
  98 .sp
  99 .LP
 100 The \fIsize\fR argument is the number of contiguous bytes to be locked or
 101 unlocked. The resource to be locked or unlocked starts at the current offset in
 102 the file and extends forward for a positive \fIsize\fR and backward for a negative
 103 \fIsize\fR (the preceding bytes up to but not including the current offset). If
 104 \fIsize\fR is zero, the section from the current offset through the largest
 105 file offset is locked (that is, from the current offset through the present or
 106 any future end-of-file). An area need not be allocated to the file in order to
 107 be locked as such locks may exist past the end-of-file.
 108 .sp
 109 .LP
 110 The sections locked with \fBF_LOCK\fR or \fBF_TLOCK\fR may, in whole or in
 111 part, contain or be contained by a previously locked section for the same
 112 process.  Locked sections will be unlocked starting at the point of the offset
 113 through \fIsize\fR bytes or to the end of file if \fIsize\fR is (\fBoff_t\fR)
 114 0. When this situation occurs, or if this situation occurs in adjacent
 115 sections, the sections are combined into a single section. If the request
 116 requires that a new element be added to the table of active locks and this
 117 table is already full, an error is returned, and the new section is not locked.
 118 .sp
 119 .LP
 120 \fBF_LOCK\fR and \fBF_TLOCK\fR requests differ only by the action taken if the
 121 resource is not available. \fBF_LOCK\fR blocks the calling thread until the
 122 resource is available. \fBF_TLOCK\fR causes the function to return \(mi1 and
 123 set \fBerrno\fR to \fBEAGAIN\fR if the section is already locked by another
 124 process.
 125 .sp
 126 .LP
 127 File locks are released on first close by the locking process of any file
 128 descriptor for the file.
 129 .sp
 130 .LP
 131 \fBF_ULOCK\fR requests may, in whole or in part, release one or more locked
 132 sections controlled by the process. When sections are not fully released, the
 133 remaining sections are still locked by the process. Releasing the center
 134 section of a locked section requires an additional element in the table of
 135 active locks. If this table is full, an \fBerrno\fR is set to \fBEDEADLK\fR and
 136 the requested section is not released.
 137 .sp
 138 .LP
 139 An \fBF_ULOCK\fR request in which \fIsize\fR is non-zero and the offset of the
 140 last byte of the requested section is the maximum value for an object of type
 141 \fBoff_t\fR, when the process has an existing lock in which \fIsize\fR is 0 and
 142 which includes the last byte of the requested section, will be treated as a
 143 request to unlock from the start of the requested section with a \fIsize\fR equal to
 144 0. Otherwise, an \fBF_ULOCK\fR request will attempt to unlock only the
 145 requested section.
 146 .sp
 147 .LP
 148 A potential for deadlock occurs if the threads of a process controlling a
 149 locked resource is put to sleep by requesting another process's locked
 150 resource. Thus calls to \fBlockf()\fR or \fBfcntl\fR(2) scan for a deadlock
 151 prior to sleeping on a locked resource. An error return is made if sleeping on
 152 the locked resource would cause a deadlock.
 153 .sp
 154 .LP
 155 Sleeping on a resource is interrupted with any signal. The \fBalarm\fR(2)
 156 function may be used to provide a timeout facility in applications that require
 157 this facility.
 158 .SH RETURN VALUES
 159 .LP
 160 Upon successful completion, \fB0\fR is returned.  Otherwise, \fB\(mi1\fR is
 161 returned and \fBerrno\fR is set to indicate the error.
 162 .SH ERRORS
 163 .LP
 164 The \fBlockf()\fR function will fail if:
 165 .sp
 166 .ne 2
 167 .na
 168 \fB\fBEBADF\fR\fR
 169 .ad
 170 .RS 20n
 171 The \fIfildes\fR argument is not a valid open file descriptor; or
 172 \fIfunction\fR is \fBF_LOCK\fR or \fBF_TLOCK\fR and \fIfildes\fR is not a valid
 173 file descriptor open for writing.
 174 .RE
 175
 176 .sp
 177 .ne 2
 178 .na
 179 \fB\fBEACCES\fR or \fBEAGAIN\fR\fR
 180 .ad
 181 .RS 20n
 182 The \fIfunction\fR argument is \fBF_TLOCK\fR or \fBF_TEST\fR and the section is
 183 already locked by another process.
 184 .RE
 185
 186 .sp
 187 .ne 2
 188 .na
 189 \fB\fBEDEADLK\fR\fR
 190 .ad
 191 .RS 20n
 192 The \fIfunction\fR argument is \fBF_LOCK\fR and a deadlock is detected.
 193 .RE
 194
 195 .sp
 196 .ne 2
 197 .na
 198 \fB\fBEINTR\fR\fR
 199 .ad
 200 .RS 20n
 201 A signal was caught during execution of the function.
 202 .RE
 203
 204 .sp
 205 .ne 2
 206 .na
 207 \fB\fBECOMM\fR\fR
 208 .ad
 209 .RS 20n
 210 The \fIfildes\fR argument is on a remote machine and the link to that machine
 211 is no longer active.
 212 .RE
 213
 214 .sp
 215 .ne 2
 216 .na
 217 \fB\fBEINVAL\fR\fR
 218 .ad
 219 .RS 20n
 220 The \fIfunction\fR argument is not one of \fBF_LOCK\fR, \fBF_TLOCK\fR,
 221 \fBF_TEST\fR, or \fBF_ULOCK\fR; or \fIsize\fR plus the current file offset is
 222 less than 0.
 223 .RE
 224
 225 .sp
 226 .ne 2
 227 .na
 228 \fB\fBEOVERFLOW\fR\fR
 229 .ad
 230 .RS 20n
 231 The offset of the first, or if \fIsize\fR is not 0 then the last, byte in the
 232 requested section cannot be represented correctly in an object of type
 233 \fBoff_t\fR.
 234 .RE
 235
 236 .sp
 237 .LP
 238 The \fBlockf()\fR function may fail if:
 239 .sp
 240 .ne 2
 241 .na
 242 \fB\fBEAGAIN\fR\fR
 243 .ad
 244 .RS 24n
 245 The \fIfunction\fR argument is \fBF_LOCK\fR or \fBF_TLOCK\fR and the file is
 246 mapped with \fBmmap\fR(2).
 247 .RE
 248
 249 .sp
 250 .ne 2
 251 .na
 252 \fB\fBEDEADLK\fR or \fBENOLCK\fR\fR
 253 .ad
 254 .RS 24n
 255 The \fIfunction\fR argument is \fBF_LOCK\fR, \fBF_TLOCK\fR, or \fBF_ULOCK\fR
 256 and the request would cause the number of locks to exceed a system-imposed
 257 limit.
 258 .RE
 259
 260 .sp
 261 .ne 2
 262 .na
 263 \fB\fBEOPNOTSUPP\fR or \fBEINVAL\fR\fR
 264 .ad
 265 .RS 24n
 266 The locking of files of the type indicated by the \fIfildes\fR argument is not
 267 supported.
 268 .RE
 269
 270 .SH USAGE
 271 .LP
 272 Record-locking should not be used in combination with the \fBfopen\fR(3C),
 273 \fBfread\fR(3C), \fBfwrite\fR(3C) and other \fBstdio\fR functions.  Instead,
 274 the more primitive, non-buffered functions (such as \fBopen\fR(2)) should be
 275 used.  Unexpected results may occur in processes that do buffering in the user
 276 address space.  The process may later read/write data which is/was locked.  The
 277 \fBstdio\fR functions are the most common source of unexpected buffering.
 278 .sp
 279 .LP
 280 The \fBalarm\fR(2) function may be used to provide a timeout facility in
 281 applications requiring it.
 282 .sp
 283 .LP
 284 The \fBlockf()\fR function has a transitional interface for 64-bit file
 285 offsets.  See \fBlf64\fR(5).
 286 .SH ATTRIBUTES
 287 .LP
 288 See \fBattributes\fR(5) for descriptions of the following attributes:
 289 .sp
 290
 291 .sp
 292 .TS
 293 box;
 294 c | c
 295 l | l .
 296 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 297 _
 298 Interface Stability     Standard
 299 _
 300 MT-Level        MT-Safe
 301 .TE
 302
 303 .SH SEE ALSO
 304 .LP
 305 \fBIntro\fR(2), \fBalarm\fR(2), \fBchmod\fR(2), \fBclose\fR(2), \fBcreat\fR(2),
 306 \fBfcntl\fR(2), \fBmmap\fR(2), \fBopen\fR(2), \fBread\fR(2), \fBwrite\fR(2),
 307 \fBattributes\fR(5), \fBlf64\fR(5), \fBstandards\fR(5)