| blob | 0506896118c475cb824d9eef8a35ad6eb8343de2 |
1 '\" te
2 .\" Copyright 2015 Joyent, Inc.
3 .\" Copyright (c) 2013, OmniTI Computer Consulting, Inc. All rights reserved.
4 .\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved.
5 .\" Copyright 1989 AT&T
6 .\" Portions Copyright (c) 1992, X/Open Company Limited. All Rights Reserved.
7 .\" 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
8 .\" http://www.opengroup.org/bookstore/.
9 .\" 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 Sun OS 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.
10 .\" This notice shall appear on any product containing this material.
11 .\" 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.
12 .\" 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.
13 .\" 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]
14 .TH FCNTL 2 "Feb 16, 2015"
15 .SH NAME
16 fcntl \- file control
17 .SH SYNOPSIS
18 .LP
19 .nf
20 #include <sys/types.h>
21 #include <unistd.h>
22 #include <fcntl.h>
24 \fBint\fR \fBfcntl\fR(\fBint\fR \fIfildes\fR, \fBint\fR \fIcmd\fR, \fB/*\fR \fIarg\fR */ ...);
25 .fi
27 .SH DESCRIPTION
28 .LP
29 The \fBfcntl()\fR function provides for control over open files. The
30 \fIfildes\fR argument is an open file descriptor.
31 .sp
32 .LP
33 The \fBfcntl()\fR function can take a third argument, \fIarg\fR, whose data
34 type, value, and use depend upon the value of \fIcmd\fR. The \fIcmd\fR argument
35 specifies the operation to be performed by \fBfcntl()\fR.
36 .sp
37 .LP
38 The values for \fIcmd\fR are defined in <\fBfcntl.h\fR> and include:
39 .sp
40 .ne 2
41 .na
42 \fB\fBF_DUPFD\fR\fR
43 .ad
44 .RS 15n
45 Return a new file descriptor which is the lowest numbered available (that is,
46 not already open) file descriptor greater than or equal to the third argument,
47 \fIarg\fR, taken as an integer of type \fBint\fR. The new file descriptor
48 refers to the same open file description as the original file descriptor, and
49 shares any locks. The \fBFD_CLOEXEC\fR flag associated with the new file
50 descriptor is cleared to keep the file open across calls to one of the
51 \fBexec\fR(2) functions.
52 .RE
54 .sp
55 .ne 2
56 .na
57 \fB\fBF_DUP2FD\fR\fR
58 .ad
59 .RS 15n
60 Similar to \fBF_DUPFD\fR, but always returns \fIarg\fR. \fBF_DUP2FD\fR closes
61 \fIarg\fR if it is open and not equal to \fIfildes.\fR \fBF_DUP2FD\fR is
62 equivalent to \fBdup2\fR(\fIfildes\fR, \fIarg\fR).
63 .RE
65 .sp
66 .ne 2
67 .na
68 \fB\fBF_DUPFD_CLOEXEC\fR\fR
69 .ad
70 .RS 15n
71 Similar to \fBF_DUPFD\fR except that instead of clearing \fBFD_CLOEXEC\fR
72 it is explicitly set on the returned file descriptor.
73 .RE
75 .sp
76 .ne 2
77 .na
78 \fB\fBF_DUP2FD_CLOEXEC\fR\fR
79 .ad
80 .RS 15n
81 Similar to \fBF_DUP2FD\fR with two exceptions. The \fBFD_CLOEXEC\fR flag is
82 explicitly set on the returned file descriptor. If \fIfiledes\fR equals
83 \fIarg\fR, the call will fail setting \fBerrno\fR to \fBEINVAL\fR.
84 .RE
86 .sp
87 .ne 2
88 .na
89 \fB\fBF_FREESP\fR\fR
90 .ad
91 .RS 15n
92 Free storage space associated with a section of the ordinary file \fIfildes\fR.
93 The section is specified by a variable of data type \fBstruct flock\fR pointed
94 to by \fIarg\fR. The data type \fBstruct flock\fR is defined in the
95 <\fBfcntl.h\fR> header (see \fBfcntl.h\fR(3HEAD)) and is described below. Note
96 that all file systems might not support all possible variations of
97 \fBF_FREESP\fR arguments. In particular, many file systems allow space to be
98 freed only at the end of a file.
99 .RE
101 .sp
102 .ne 2
103 .na
104 \fB\fBF_FREESP64\fR\fR
105 .ad
106 .RS 15n
107 Equivalent to \fBF_FREESP\fR, but takes a \fBstruct flock64\fR argument rather
108 than a \fBstruct flock\fR argument.
109 .RE
111 .sp
112 .ne 2
113 .na
114 \fB\fBF_ALLOCSP\fR\fR
115 .ad
116 .RS 15n
117 Allocate space for a section of the ordinary file \fIfildes\fR. The section is
118 specified by a variable of data type \fBstruct flock\fR pointed to by
119 \fIarg\fR. The data type \fBstruct flock\fR is defined in the <\fBfcntl.h\fR>
120 header (see \fBfcntl.h\fR(3HEAD) and is described below.
121 .RE
123 .sp
124 .ne 2
125 .na
126 \fB\fBF_ALLOCSP64\fR\fR
127 .ad
128 .RS 15n
129 Equivalent to \fBF_ALLOCSP\fR, but takes a \fBstruct flock64\fR argument rather
130 than a \fBstruct flock\fR argument.
131 .RE
133 .sp
134 .ne 2
135 .na
136 \fB\fBF_GETFD\fR\fR
137 .ad
138 .RS 15n
139 Get the file descriptor flags defined in <\fBfcntl.h\fR> that are associated
140 with the file descriptor \fIfildes\fR. File descriptor flags are associated
141 with a single file descriptor and do not affect other file descriptors that
142 refer to the same file.
143 .RE
145 .sp
146 .ne 2
147 .na
148 \fB\fBF_GETFL\fR\fR
149 .ad
150 .RS 15n
151 Get the file status flags and file access modes, defined in <\fBfcntl.h\fR>,
152 for the file descriptor specified by \fIfildes\fR. The file access modes can be
153 extracted from the return value using the mask \fBO_ACCMODE\fR, which is
154 defined in <\fBfcntl.h\fR>. File status flags and file access modes do not
155 affect other file descriptors that refer to the same file with different open
156 file descriptions.
157 .RE
159 .sp
160 .ne 2
161 .na
162 \fB\fBF_GETOWN\fR\fR
163 .ad
164 .RS 15n
165 If \fIfildes\fR refers to a socket, get the process or process group \fBID\fR
166 specified to receive \fBSIGURG\fR signals when out-of-band data is available.
167 Positive values indicate a process ID; negative values, other than \(mi1,
168 indicate a process group ID. If \fIfildes\fR does not refer to a socket, the
169 results are unspecified.
170 .RE
172 .sp
173 .ne 2
174 .na
175 \fB\fBF_GETXFL\fR\fR
176 .ad
177 .RS 15n
178 Get the file status flags, file access modes, and file creation and assignment
179 flags, defined in <\fBfcntl.h\fR>, for the file descriptor specified by
180 \fIfildes\fR. The file access modes can be extracted from the return value
181 using the mask \fBO_ACCMODE\fR, which is defined in <\fBfcntl.h\fR>. File
182 status flags, file access modes, and file creation and assignment flags do not
183 affect other file descriptors that refer to the same file with different open
184 file descriptions.
185 .RE
187 .sp
188 .ne 2
189 .na
190 \fB\fBF_SETFD\fR\fR
191 .ad
192 .RS 15n
193 Set the file descriptor flags defined in <\fBfcntl.h\fR>, that are associated
194 with \fIfildes\fR, to the third argument, \fIarg\fR, taken as type \fBint\fR.
195 If the \fBFD_CLOEXEC\fR flag in the third argument is 0, the file will remain
196 open across the \fBexec()\fR functions; otherwise the file will be closed upon
197 successful execution of one of the \fBexec()\fR functions.
198 .RE
200 .sp
201 .ne 2
202 .na
203 \fB\fBF_SETFL\fR\fR
204 .ad
205 .RS 15n
206 Set the file status flags, defined in <\fBfcntl.h\fR>, for the file descriptor
207 specified by \fIfildes\fR from the corresponding bits in the \fIarg\fR
208 argument, taken as type \fBint\fR. Bits corresponding to the file access mode
209 and file creation and assignment flags that are set in \fIarg\fR are ignored.
210 If any bits in \fIarg\fR other than those mentioned here are changed by the
211 application, the result is unspecified.
212 .RE
214 .sp
215 .ne 2
216 .na
217 \fB\fBF_SETOWN\fR\fR
218 .ad
219 .RS 15n
220 If \fIfildes\fR refers to a socket, set the process or process group \fBID\fR
221 specified to receive \fBSIGURG\fR signals when out-of-band data is available,
222 using the value of the third argument, \fIarg\fR, taken as type \fBint\fR.
223 Positive values indicate a process ID; negative values, other than \(mi1,
224 indicate a process group ID. If \fIfildes\fR does not refer to a socket, the
225 results are unspecified.
226 .RE
228 .sp
229 .LP
230 The following commands are available for POSIX advisory or mandatory record
231 locking. POSIX record locking is supported for regular files, and may be
232 supported for other files. See the FILE LOCKING section of this manual page for
233 information about the types of file locks available and their interaction.
234 .sp
235 .ne 2
236 .na
237 \fB\fBF_GETLK\fR\fR
238 .ad
239 .RS 14n
240 Get the first lock which blocks the POSIX lock description pointed to by the
241 third argument, \fIarg\fR, taken as a pointer to type \fBstruct flock\fR,
242 defined in <\fBfcntl.h\fR>. The information retrieved overwrites the
243 information passed to \fBfcntl()\fR in the structure \fBflock\fR. If no lock is
244 found that would prevent this lock from being created, then the structure will
245 be left unchanged except for the lock type which will be set to \fBF_UNLCK\fR.
246 If multiple locks exist that would prevent this lock from being created, which
247 one is returned is unspecified. If the blocking lock is an OFD-style lock,
248 \fB\(mi1\fR\& will be returned for the lock's pid value.
249 .RE
251 .sp
252 .ne 2
253 .na
254 \fB\fBF_GETLK64\fR\fR
255 .ad
256 .RS 14n
257 Equivalent to \fBF_GETLK\fR, but takes a \fBstruct flock64\fR argument rather
258 than a \fBstruct flock\fR argument. See \fBlf64\fR(5).
259 .RE
261 .sp
262 .ne 2
263 .na
264 \fB\fBF_SETLK\fR\fR
265 .ad
266 .RS 14n
267 Set or clear a POSIX record lock according to the lock description pointed to
268 by the third argument, \fIarg\fR, taken as a pointer to type \fBstruct
269 flock\fR, defined in <\fBfcntl.h\fR>. \fBF_SETLK\fR is used to establish shared
270 (or read) locks (\fBF_RDLCK\fR) or exclusive (or write) locks (\fBF_WRLCK\fR),
271 as well as to remove either type of lock (\fBF_UNLCK\fR). \fBF_RDLCK\fR,
272 \fBF_WRLCK\fR and \fBF_UNLCK\fR are defined in <\fBfcntl.h\fR>. If a shared or
273 exclusive lock cannot be set, \fBfcntl()\fR will return immediately with a
274 return value of \fB\(mi1\fR\&.
275 .RE
277 .sp
278 .ne 2
279 .na
280 \fB\fBF_SETLK64\fR\fR
281 .ad
282 .RS 14n
283 Equivalent to \fBF_SETLK\fR, but takes a \fBstruct flock64\fR argument rather
284 than a \fBstruct flock\fR argument. See \fBlf64\fR(5).
285 .RE
287 .sp
288 .ne 2
289 .na
290 \fB\fBF_SETLKW\fR\fR
291 .ad
292 .RS 14n
293 This command is the same as \fBF_SETLK\fR except that if a shared or exclusive
294 lock is blocked by other locks, the process will wait until the request can be
295 satisfied. If a signal that is to be caught is received while \fBfcntl()\fR is
296 waiting for a region, \fBfcntl()\fR will be interrupted. Upon return from the
297 process' signal handler, \fBfcntl()\fR will return \fB\(mi1\fR with \fBerrno\fR
298 set to \fBEINTR\fR, and the lock operation will not be done.
299 .RE
301 .sp
302 .ne 2
303 .na
304 \fB\fBF_SETLKW64\fR\fR
305 .ad
306 .RS 14n
307 Equivalent to \fBF_SETLKW\fR, but takes a \fBstruct flock64\fR argument rather
308 than a \fBstruct flock\fR argument. See \fBlf64\fR(5).
309 .RE
311 .sp
312 .LP
313 The following commands are available for OFD (open file description) advisory
314 record locking. OFD record locking is supported for regular files, and may be
315 supported for other files. See the FILE LOCKING section of this manual page for
316 information about the types of file locks available and their interaction.
317 OFD-style record locks are currently limited to spanning the entire file and
318 these locks are currently not supported over remote file systems (e.g.
319 \fBnfs\fR(4)) which use the Network Lock Manager.
320 .sp
321 .ne 2
322 .na
323 \fB\fBF_OFD_GETLK\fR\fR
324 .ad
325 .RS 14n
326 Get the first lock which blocks the OFD lock description pointed to by the
327 third argument, \fIarg\fR, taken as a pointer to type \fBstruct flock\fR,
328 defined in <\fBfcntl.h\fR>. The information retrieved overwrites the
329 information passed to \fBfcntl()\fR in the structure \fBflock\fR. If no lock is
330 found that would prevent this lock from being created, then the structure will
331 be left unchanged except for the lock type which will be set to \fBF_UNLCK\fR.
332 If multiple locks exist that would prevent this lock from being created, which
333 one is returned is unspecified. If the blocking lock is an OFD-style lock,
334 \fB\(mi1\fR\& will be returned for the lock's pid value.
335 .RE
337 .sp
338 .ne 2
339 .na
340 \fB\fBF_OFD_GETLK64\fR\fR
341 .ad
342 .RS 14n
343 Equivalent to \fBF_OFD_GETLK\fR, but takes a \fBstruct flock64\fR argument
344 rather than a \fBstruct flock\fR argument. See \fBlf64\fR(5). This command
345 exists solely to allow the use of OFD locks with the transitional 64-bit file
346 interfaces.
347 .RE
349 .sp
350 .ne 2
351 .na
352 \fB\fBF_OFD_SETLK\fR\fR
353 .ad
354 .RS 14n
355 Set or clear a OFD record lock according to the lock description pointed to
356 by the third argument, \fIarg\fR, taken as a pointer to type \fBstruct
357 flock\fR, defined in <\fBfcntl.h\fR>. \fBF_OFD_SETLK\fR is used to establish
358 shared (or read) locks (\fBF_RDLCK\fR) or exclusive (or write) locks
359 (\fBF_WRLCK\fR), as well as to remove either type of lock (\fBF_UNLCK\fR).
360 \fBF_RDLCK\fR, \fBF_WRLCK\fR and \fBF_UNLCK\fR are defined in <\fBfcntl.h\fR>.
361 If a shared or exclusive lock cannot be set, \fBfcntl()\fR will return
362 immediately with a return value of \fB\(mi1\fR\&.
363 .RE
365 .sp
366 .ne 2
367 .na
368 \fB\fBF_OFD_SETLK64\fR\fR
369 .ad
370 .RS 14n
371 Equivalent to \fBF_OFD_SETLK\fR, but takes a \fBstruct flock64\fR argument
372 rather than a \fBstruct flock\fR argument. See \fBlf64\fR(5). This command
373 exists solely to allow the use of OFD locks with the transitional 64-bit file
374 interfaces.
375 .RE
377 .sp
378 .ne 2
379 .na
380 \fB\fBF_OFD_SETLKW\fR\fR
381 .ad
382 .RS 14n
383 This command is the same as \fBF_OFD_SETLK\fR except that if a shared or
384 exclusive lock is blocked by other locks, the process will wait until the
385 request can be satisfied. If a signal that is to be caught is received while
386 \fBfcntl()\fR is waiting for a region, \fBfcntl()\fR will be interrupted. Upon
387 return from the process' signal handler, \fBfcntl()\fR will return \fB\(mi1\fR
388 with \fBerrno\fR set to \fBEINTR\fR, and the lock operation will not be done.
389 .RE
391 .sp
392 .ne 2
393 .na
394 \fB\fBF_OFD_SETLKW64\fR\fR
395 .ad
396 .RS 14n
397 Equivalent to \fBF_OFD_SETLKW\fR, but takes a \fBstruct flock64\fR argument
398 rather than a \fBstruct flock\fR argument. See \fBlf64\fR(5). This command
399 exists solely to allow the use of OFD locks with the transitional 64-bit file
400 interfaces.
401 .RE
403 .sp
404 .LP
405 The following values for \fIcmd\fR are used for file share reservations. A
406 share reservation is placed on an entire file to allow cooperating processes to
407 control access to the file. See the SHARE RESERVATIONS section of this manual
408 page below for additional information.
409 .sp
410 .ne 2
411 .na
412 \fB\fBF_SHARE\fR\fR
413 .ad
414 .RS 13n
415 Sets a share reservation on a file with the specified access mode and
416 designates which types of access to deny.
417 .RE
419 .sp
420 .ne 2
421 .na
422 \fB\fBF_UNSHARE\fR\fR
423 .ad
424 .RS 13n
425 Remove an existing share reservation.
426 .RE
428 .SH FILE LOCKING
429 .LP
430 Two types of file locks are supported: POSIX-style and OFD-style. OFD-style
431 locks are associated with the open file description (not descriptor) instead
432 of with a process. Either type is advisory by default, but POSIX-style locks
433 can be mandatory if, and only if, mandatory locking has been enabled on the
434 file being locked. Each type of lock may be created through two different
435 interfaces. POSIX-style locks are created via the \fBF_SETLK\fR,
436 \fBF_SETLK64\fR, \fBF_SETLKW\fR, or \fBF_SETLKW64\fR commands to this system
437 call or by use of the \fBlockf\fR(3C) routine. There is no difference between
438 locks created via one mechanism or the other. Likewise, OFD-style locks are
439 created via the \fBF_OFD_SETLK\fR, \fBF_OFD_SETLK64\fR, \fBF_OFD_SETLKW\fR, or
440 \fBF_OFD_SETLKW64\fR commands to this system call or by use of the
441 Linux/BSD-compatible \fBflock\fR(3C) routine. Note that this system call
442 supports the creation of range-specified OFD-style file locks, while
443 \fBflock\fR(3C) does not. However, the current implementation of OFD-style
444 locking is limited to locking the entire file. This limitation might be
445 removed in the future.
446 .sp
447 .LP
448 The essential distinction between POSIX-style locks and OFD-style locks lie
449 in how ownership of a lock is scoped. POSIX locks are scoped to a process. All
450 POSIX locks associated with a file for a given process are removed when any
451 file descriptor for that file is closed by that process or the process holding
452 that file descriptor terminates. POSIX-style locks are not inherited by a child
453 process created using \fBfork\fR(2). An OFD-style lock is scoped to the file
454 description for a file, not the process or open file descriptor. Thus all file
455 descriptors referring to the same description (i.e. those created via the
456 \fBF_DUPFD\fR, \fBF_DUP2FD\fR, \fBF_DUPFD_CLOEXEC\fR, or \fBF_DUP2FD_CLOEXEC\fR
457 commands to the \fBfcntl\fR(2) system call, or those created via the
458 \fBdup\fR(2) system call, or those inherited by a child process created via
459 \fBfork\fR(2)) reference the same lock, but a file descriptor obtained via a
460 separate \fBopen\fR(2) call on the same file will reference a different lock.
461 A lock is removed only on the last \fBclose\fR(2) of the description, or when
462 the lock is explicitly unlocked.
463 .sp
464 .LP
465 Locks of both styles are compatible. A file that has been locked with one
466 style of lock will be regarded as locked when creation of a lock of either
467 style is attempted, and information about the lock will be provided via
468 any of the \fBF_GETLK\fR, \fBF_GETLK64\fR, \fBF_OFD_GETLK\fR, or
469 \fBF_OFD_GETLK64\fR commands to this system call if that lock would conflict
470 with an attempt to create the specified lock regardless of whether the
471 specified lock is of the same style as the conflicting extant lock.
472 Because ownership of OFD-style locks is scoped to the open description rather
473 than the calling process, the \fBl_pid\fR field of a lock descriptor for any
474 such lock will always be set to \fB\(mi1\fR\&.
475 .sp
476 .LP
477 When a shared lock is set on a segment of a file, other callers (regardless
478 of whether in the same or different process and of whether referenced via the
479 same open file) will be able to set shared locks on that segment or a portion
480 of it. A POSIX-style shared lock prevents any other process from setting an
481 exclusive lock on any portion of the protected area. A OFD-style shared lock
482 prevents any caller (even callers in the same process) from setting an
483 exclusive lock on any portion of the protected area, unless the caller makes
484 the request against a file descriptor referencing the same open file against
485 which the shared lock was created, in which case the lock will be downgraded
486 to a shared lock with respect to the specified region. A request for a shared
487 lock of either style will fail if the file descriptor was not opened with
488 read access.
489 .sp
490 .LP
491 A POSIX-style exclusive lock will prevent any other process from setting a
492 shared lock or an exclusive lock (of either style) on any portion of the
493 protected area. A request for an exclusive lock will fail if the file
494 descriptor was not opened with write access.
495 .sp
496 .LP
497 The \fBflock\fR structure contains at least the following elements:
498 .sp
499 .in +2
500 .nf
501 short l_type; /* lock operation type */
502 short l_whence; /* lock base indicator */
503 off_t l_start; /* starting offset from base */
504 off_t l_len; /* lock length; l_len == 0 means
505 until end of file */
506 int l_sysid; /* system ID running process holding lock */
507 pid_t l_pid; /* process ID of process holding lock */
508 .fi
509 .in -2
511 .sp
512 .LP
513 The value of \fBl_whence\fR is \fBSEEK_SET\fR, \fBSEEK_CUR\fR, or
514 \fBSEEK_END\fR, to indicate that the relative offset \fBl_start\fR bytes will
515 be measured from the start of the file, current position or end of the file,
516 respectively. The value of \fBl_len\fR is the number of consecutive bytes to be
517 locked. The value of \fBl_len\fR may be negative (where the definition of
518 \fBoff_t\fR permits negative values of \fBl_len\fR). After a successful
519 \fBF_GETLK\fR, \fBF_GETLK64\fR, \fBF_OFD_GETLK\fR, or \fBF_OFD_GETLK64\fR
520 request, that is, one in which a lock was found, the value of \fBl_whence\fR
521 will be \fBSEEK_SET\fR.
522 .sp
523 .LP
524 The \fBl_pid\fR and \fBl_sysid\fR fields are used only with \fBF_GETLK\fR or
525 \fBF_GETLK64\fR to return the process \fBID\fR of the process holding a
526 POSIX-style blocking lock and to indicate which system is running that process,
527 or \fB\(mi1\fR\& if it is an OFD-style lock. These fields must both be
528 initialized to 0 prior to issuing a OFD-style locking command
529 (\fBF_OFD_GETLK\fR or \fBF_OFD_GETLK64\fR).
530 .sp
531 .LP
532 If \fBl_len\fR is positive, the area affected starts at \fBl_start\fR and ends
533 at \fBl_start\fR + \fBl_len \(mi 1\fR. If \fBl_len\fR is negative, the area
534 affected starts at \fBl_start\fR + \fBl_len\fR and ends at \fBl_start \(mi
535 1\fR. Locks may start and extend beyond the current end of a file, but must not
536 be negative relative to the beginning of the file. A lock will be set to extend
537 to the largest possible value of the file offset for that file by setting
538 \fBl_len\fR to 0. If such a lock also has \fBl_start\fR set to 0 and
539 \fBl_whence\fR is set to \fBSEEK_SET\fR, the whole file will be locked.
540 .sp
541 .LP
542 If a lock exists for which \fBl_len\fR is 0 and which includes the last byte of
543 the requested segment, and an unlock (\fBF_UNLCK\fR) request is made in which
544 \fBl_len\fR is non-zero and the offset of the last byte of the requested
545 segment is the maximum value for an object of type \fBoff_t\fR, then the
546 \fBF_UNLCK\fR request will be treated as a request to unlock from the start
547 of the requested segment with an \fBl_len\fR equal to 0. Otherwise, the request
548 will attempt to unlock only the requested segment.
549 .sp
550 .LP
551 There will be at most one type of lock set for each byte in the
552 file. Before a successful return from an \fBF_SETLK\fR, \fBF_SETLK64\fR,
553 \fBF_SETLKW\fR, or \fBF_SETLKW64\fR request when the calling process has
554 previously existing POSIX-style locks on bytes in the region specified by the
555 request, the previous POSIX-style lock type for each byte in the specified
556 region will be replaced by the new lock type. As specified above under the
557 descriptions of shared locks and exclusive locks, an \fBF_SETLK\fR,
558 \fBF_SETLK64\fR, \fBF_SETLKW\fR, or \fBF_SETLKW64\fR request will
559 (respectively) fail or block when locks exist on bytes in the specified region
560 and the type of any of those locks conflicts with the type specified in the
561 request.
562 .sp
563 .LP
564 Similarly, before a successful return from an \fBF_OFD_SETLK\fR,
565 \fBF_OFD_SETLK64\fR, \fBF_OFD_SETLKW\fR, or \fBF_OFD_SETLKW64\fR request when
566 previously-created OFD-style locks associated with the open file apply to
567 bytes in the region specified by the request, the previous OFD-style lock type
568 for each byte in the specified region will be replaced by the new lock type.
569 As specified above under the descriptions of shared locks and exclusive locks,
570 an \fBF_OFD_SETLK\fR, \fBF_OFD_SETLK64\fR, \fBF_OFD_SETLKW\fR, or
571 \fBF_OFD_SETLKW64\fR request will (respectively) fail or block when locks exist
572 on bytes in the specified region and the type of any of those locks conflicts
573 with the type specified in the request.
574 .sp
575 .LP
576 A potential for deadlock occurs if a process controlling a locked region is put
577 to sleep by attempting to lock another process' locked region. If the system
578 detects that sleeping until a locked region is unlocked would cause a deadlock,
579 \fBfcntl()\fR will fail with an \fBEDEADLK\fR error. This deadlock detection
580 and error value apply only to POSIX-style locks. No deadlock detection is
581 performed when attempting to set an OFD-style lock.
583 .SH SHARE RESERVATIONS
584 .LP
585 File share reservations are an advisory form of access control among
586 cooperating processes, on both local and remote machines. They are most often
587 used by \fBDOS\fR or Windows emulators and \fBDOS based\fR \fBNFS\fR clients.
588 However, native UNIX versions of \fBDOS\fR or Windows applications may also
589 choose to use this form of access control.
590 .sp
591 .LP
592 A share reservation is described by an \fBfshare\fR structure defined in
593 <\fBsys/fcntl.h\fR>, which is included in <\fBfcntl.h\fR> as follows:
594 .sp
595 .in +2
596 .nf
597 typedef struct fshare {
598 short f_access;
599 short f_deny;
600 int f_id;
601 } fshare_t;
602 .fi
603 .in -2
605 .sp
606 .LP
607 A share reservation specifies the type of access, \fBf_access\fR, to be
608 requested on the open file descriptor. If access is granted, it further
609 specifies what type of access to deny other processes, \fBf_deny\fR. A single
610 process on the same file may hold multiple non-conflicting reservations by
611 specifying an identifier, \fBf_id\fR, unique to the process, with each request.
612 .sp
613 .LP
614 An \fBF_UNSHARE\fR request releases the reservation with the specified
615 \fBf_id\fR. The \fBf_access\fR and \fBf_deny\fR fields are ignored.
616 .sp
617 .LP
618 Valid \fBf_access\fR values are:
619 .sp
620 .ne 2
621 .na
622 \fB\fBF_RDACC\fR\fR
623 .ad
624 .RS 11n
625 Set a file share reservation for read-only access.
626 .RE
628 .sp
629 .ne 2
630 .na
631 \fB\fBF_WRACC\fR\fR
632 .ad
633 .RS 11n
634 Set a file share reservation for write-only access.
635 .RE
637 .sp
638 .ne 2
639 .na
640 \fB\fBF_RWACC\fR\fR
641 .ad
642 .RS 11n
643 Set a file share reservation for read and write access.
644 .RE
646 .sp
647 .LP
648 Valid \fBf_deny\fR values are:
649 .sp
650 .ne 2
651 .na
652 \fB\fBF_COMPAT\fR\fR
653 .ad
654 .RS 12n
655 Set a file share reservation to compatibility mode.
656 .RE
658 .sp
659 .ne 2
660 .na
661 \fB\fBF_RDDNY\fR\fR
662 .ad
663 .RS 12n
664 Set a file share reservation to deny read access to other processes.
665 .RE
667 .sp
668 .ne 2
669 .na
670 \fB\fBF_WRDNY\fR\fR
671 .ad
672 .RS 12n
673 Set a file share reservation to deny write access to other processes.
674 .RE
676 .sp
677 .ne 2
678 .na
679 \fB\fBF_RWDNY\fR\fR
680 .ad
681 .RS 12n
682 Set a file share reservation to deny read and write access to other processes.
683 .RE
685 .sp
686 .ne 2
687 .na
688 \fB\fBF_NODNY\fR\fR
689 .ad
690 .RS 12n
691 Do not deny read or write access to any other process.
692 .RE
694 .SH RETURN VALUES
695 .LP
696 Upon successful completion, the value returned depends on \fIcmd\fR as follows:
697 .sp
698 .ne 2
699 .na
700 \fB\fBF_DUPFD\fR\fR
701 .ad
702 .RS 14n
703 A new file descriptor.
704 .RE
706 .sp
707 .ne 2
708 .na
709 \fB\fBF_FREESP\fR\fR
710 .ad
711 .RS 14n
712 Value of \fB0\fR.
713 .RE
715 .sp
716 .ne 2
717 .na
718 \fB\fBF_GETFD\fR\fR
719 .ad
720 .RS 14n
721 Value of flags defined in \fB<fcntl.h>\fR\&. The return value will not be
722 negative.
723 .RE
725 .sp
726 .ne 2
727 .na
728 \fB\fBF_GETFL\fR\fR
729 .ad
730 .RS 14n
731 Value of file status flags and access modes. The return value will not be
732 negative.
733 .RE
735 .sp
736 .ne 2
737 .na
738 \fB\fBF_GETLK\fR\fR
739 .ad
740 .RS 14n
741 Value other than \fB\(mi1\fR\&.
742 .RE
744 .sp
745 .ne 2
746 .na
747 \fB\fBF_GETLK64\fR\fR
748 .ad
749 .RS 14n
750 Value other than \fB\(mi1\fR\&.
751 .RE
753 .sp
754 .ne 2
755 .na
756 \fB\fBF_GETOWN\fR\fR
757 .ad
758 .RS 14n
759 Value of the socket owner process or process group; this will not be
760 \fB\(mi1\fR\&.
761 .RE
763 .sp
764 .ne 2
765 .na
766 \fB\fBF_GETXFL\fR\fR
767 .ad
768 .RS 14n
769 Value of file status flags, access modes, and creation and assignment flags.
770 The return value will not be negative.
771 .RE
773 .sp
774 .ne 2
775 .na
776 \fB\fBF_OFD_GETLK\fR\fR
777 .ad
778 .RS 14n
779 Value other then \fB\(mi1\fR\&.
780 .RE
782 .sp
783 .ne 2
784 .na
785 \fB\fBF_OFD_GETLK64\fR\fR
786 .ad
787 .RS 14n
788 Value other then \fB\(mi1\fR\&.
789 .RE
791 .sp
792 .ne 2
793 .na
794 \fB\fBF_OFD_SETLK\fR\fR
795 .ad
796 .RS 14n
797 Value other then \fB\(mi1\fR\&.
798 .RE
800 .sp
801 .ne 2
802 .na
803 \fB\fBF_OFD_SETLK64\fR\fR
804 .ad
805 .RS 14n
806 Value other then \fB\(mi1\fR\&.
807 .RE
809 .sp
810 .ne 2
811 .na
812 \fB\fBF_OFD_SETLKW\fR\fR
813 .ad
814 .RS 14n
815 Value other then \fB\(mi1\fR\&.
816 .RE
818 .sp
819 .ne 2
820 .na
821 \fB\fBF_OFD_SETLKW64\fR\fR
822 .ad
823 .RS 14n
824 Value other then \fB\(mi1\fR\&.
825 .RE
827 .sp
828 .ne 2
829 .na
830 \fB\fBF_SETFD\fR\fR
831 .ad
832 .RS 14n
833 Value other than \fB\(mi1\fR\&.
834 .RE
836 .sp
837 .ne 2
838 .na
839 \fB\fBF_SETFL\fR\fR
840 .ad
841 .RS 14n
842 Value other than \fB\(mi1\fR\&.
843 .RE
845 .sp
846 .ne 2
847 .na
848 \fB\fBF_SETLK\fR\fR
849 .ad
850 .RS 14n
851 Value other than \fB\(mi1\fR\&.
852 .RE
854 .sp
855 .ne 2
856 .na
857 \fB\fBF_SETLK64\fR\fR
858 .ad
859 .RS 14n
860 Value other than \fB\(mi1\fR\&.
861 .RE
863 .sp
864 .ne 2
865 .na
866 \fB\fBF_SETLKW\fR\fR
867 .ad
868 .RS 14n
869 Value other than \fB\(mi1\fR\&.
870 .RE
872 .sp
873 .ne 2
874 .na
875 \fB\fBF_SETLKW64\fR\fR
876 .ad
877 .RS 14n
878 Value other than \fB\(mi1\fR\&.
879 .RE
881 .sp
882 .ne 2
883 .na
884 \fB\fBF_SETOWN\fR\fR
885 .ad
886 .RS 14n
887 Value other than \fB\(mi1\fR\&.
888 .RE
890 .sp
891 .ne 2
892 .na
893 \fB\fBF_SHARE\fR\fR
894 .ad
895 .RS 14n
896 Value other than \fB\(mi1\fR\&.
897 .RE
899 .sp
900 .ne 2
901 .na
902 \fB\fBF_UNSHARE\fR\fR
903 .ad
904 .RS 14n
905 Value other than \fB\(mi1\fR\&.
906 .RE
908 .sp
909 .LP
910 Otherwise, \fB\(mi1\fR is returned and \fBerrno\fR is set to indicate the
911 error.
912 .SH ERRORS
913 .LP
914 The \fBfcntl()\fR function will fail if:
915 .sp
916 .ne 2
917 .na
918 \fB\fBEAGAIN\fR\fR
919 .ad
920 .RS 13n
921 The \fIcmd\fR argument is \fBF_SETLK\fR, \fBF_SETLK64\fR, \fBF_OFD_SETLK\fR,
922 or \fBF_OFD_SETLK64\fR, the type of lock \fB(l_type)\fR is a shared
923 (\fBF_RDLCK\fR) or exclusive (\fBF_WRLCK\fR) lock, and the segment of a file
924 to be locked is already exclusive-locked by another process or open file; or
925 the type is an exclusive lock and some portion of the segment of a file to be
926 locked is already shared-locked or exclusive-locked by another process or open
927 file.
928 .sp
929 The \fIcmd\fR argument is \fBF_FREESP\fR, the file exists, mandatory
930 file/record locking is set, and there are outstanding record locks on the file;
931 or the \fIcmd\fR argument is \fBF_SETLK\fR, \fBF_SETLK64\fR, \fBF_SETLKW\fR, or
932 \fBF_SETLKW64\fR, mandatory file/record locking is set, and the file is
933 currently being mapped to virtual memory using \fBmmap\fR(2).
934 .sp
935 The \fIcmd\fR argument is \fBF_SHARE\fR and \fBf_access\fR conflicts with an
936 existing \fBf_deny\fR share reservation.
937 .RE
939 .sp
940 .ne 2
941 .na
942 \fB\fBEBADF\fR\fR
943 .ad
944 .RS 13n
945 The \fIfildes\fR argument is not a valid open file descriptor; or the \fIcmd\fR
946 argument is \fBF_SETLK\fR, \fBF_SETLK64\fR, \fBF_SETLKW\fR, \fBF_SETLKW64\fR,
947 \fBF_OFD_SETLK\fR, \fBF_OFD_SETLK64\fR, \fBF_OFD_SETLKW\fR, or
948 \fBF_OFD_SETLKW64\fR, the type of lock, \fBl_type\fR, is a shared lock
949 (\fBF_RDLCK\fR), and \fIfildes\fR is not a valid file descriptor open for
950 reading; or the type of lock \fBl_type\fR is an exclusive lock (\fBF_WRLCK\fR)
951 and \fIfildes\fR is not a valid file descriptor open for writing.
952 .sp
953 The \fIcmd\fR argument is \fBF_FREESP\fR and \fIfildes\fR is not a valid file
954 descriptor open for writing.
955 .sp
956 The \fIcmd\fR argument is \fBF_DUP2FD\fR, and \fIarg\fR is negative or is not
957 less than the current resource limit for \fBRLIMIT_NOFILE.\fR
958 .sp
959 The \fIcmd\fR argument is \fBF_SHARE,\fR the \fBf_access\fR share reservation
960 is for write access, and \fIfildes\fR is not a valid file descriptor open for
961 writing.
962 .sp
963 The \fIcmd\fR argument is \fBF_SHARE,\fR the \fBf_access\fR share reservation
964 is for read access, and \fIfildes\fR is not a valid file descriptor open for
965 reading.
966 .RE
968 .sp
969 .ne 2
970 .na
971 \fB\fBEFAULT\fR\fR
972 .ad
973 .RS 13n
974 The \fIcmd\fR argument is \fBF_GETLK\fR, \fBF_GETLK64\fR, \fBF_SETLK\fR,
975 \fBF_SETLK64\fR, \fBF_SETLKW\fR, \fBF_SETLKW64\fR, \fBF_OFD_GETLK\fR,
976 \fBF_OFD_GETLK64\fR, \fBF_OFD_SETLK\fR, \fBF_OFD_SETLK64\fR, \fBF_OFD_SETLKW\fR,
977 \fBF_OFD_SETLKW64\fB, \fBF_SHARE\fR, \fBF_UNSHARE\fR, or \fBF_FREESP\fR and the
978 \fIarg\fR argument points to an illegal address.
979 .RE
981 .sp
982 .ne 2
983 .na
984 \fB\fBEINTR\fR\fR
985 .ad
986 .RS 13n
987 The \fIcmd\fR argument is \fBF_SETLKW\fR, \fBF_SETLKW64\fR, \fBF_OFD_SETLKW\fR,
988 or \fBF_OFD_SETLKW64\fR, and the function was interrupted by a signal.
989 .RE
991 .sp
992 .ne 2
993 .na
994 \fB\fBEINVAL\fR\fR
995 .ad
996 .RS 13n
997 The \fIcmd\fR argument is invalid or not supported by the file system; or the
998 \fIcmd\fR argument is \fBF_DUPFD\fR and \fIarg\fR is negative or greater than
999 or equal to \fBOPEN_MAX\fR; or the \fIcmd\fR argument is \fBF_GETLK\fR,
1000 \fBF_GETLK64\fR, \fBF_SETLK\fR, \fBF_SETLK64\fR, \fBF_SETLKW\fR,
1001 \fBF_SETLKW64\fR, \fBF_OFD_GETLK\fR, \fBF_OFD_GETLK64\fR, \fBF_OFD_SETLK\fR,
1002 \fBF_OFD_SETLK64\fR, \fBF_OFD_SETLKW\fR, or \fBF_OFD_SETLKW64\fR, and the data
1003 pointed to by \fIarg\fR is not valid; or \fIfildes\fR refers to a file that
1004 does not support locking.
1005 .sp
1006 The \fIcmd\fR argument is \fBF_UNSHARE\fR and a reservation with this
1007 \fBf_id\fR for this process does not exist.
1008 .sp
1009 The \fIcmd\fR argument is \fBF_DUP2FD_CLOEXEC\fR and \fIfildes\fR is equal
1010 to \fBarg\fR.
1011 .RE
1013 .sp
1014 .ne 2
1015 .na
1016 \fB\fBEIO\fR\fR
1017 .ad
1018 .RS 13n
1019 An I/O error occurred while reading from or writing to the file system.
1020 .RE
1022 .sp
1023 .ne 2
1024 .na
1025 \fB\fBEMFILE\fR\fR
1026 .ad
1027 .RS 13n
1028 The \fIcmd\fR argument is \fBF_DUPFD\fR and either \fBOPEN_MAX\fR file
1029 descriptors are currently open in the calling process, or no file descriptors
1030 greater than or equal to \fIarg\fR are available.
1031 .RE
1033 .sp
1034 .ne 2
1035 .na
1036 \fB\fBENOLCK\fR\fR
1037 .ad
1038 .RS 13n
1039 The \fIcmd\fR argument is \fBF_SETLK\fR, \fBF_SETLK64\fR, \fBF_SETLKW\fR,
1040 \fBF_SETLKW64\fR, \fBF_OFD_SETLK\fR, \fBF_OFD_SETLK64\fR, \fBF_OFD_SETLKW\fR,
1041 or \fBF_OFD_SETLKW64\fR, and satisfying the lock or unlock request would
1042 result in the number of locked regions in the system exceeding a
1043 system-imposed limit.
1044 .RE
1046 .sp
1047 .ne 2
1048 .na
1049 \fB\fBENOLINK\fR\fR
1050 .ad
1051 .RS 13n
1052 Either the \fIfildes\fR argument is on a remote machine and the link to that
1053 machine is no longer active; or the \fIcmd\fR argument is \fBF_FREESP\fR, the
1054 file is on a remote machine, and the link to that machine is no longer active.
1055 .RE
1057 .sp
1058 .ne 2
1059 .na
1060 \fB\fBEOVERFLOW\fR\fR
1061 .ad
1062 .RS 13n
1063 One of the values to be returned cannot be represented correctly.
1064 .sp
1065 The \fIcmd\fR argument is \fBF_GETLK\fR, \fBF_SETLK\fR, \fBF_SETLKW\fR,
1066 \fBF_OFD_GETLK\fR, \fBF_OFD_SETLK\fR, or \fBF_OFD_SETLKW\fR, and
1067 the smallest or, if \fBl_len\fR is non-zero, the largest, offset of any byte in
1068 the requested segment cannot be represented correctly in an object of type
1069 \fBoff_t\fR.
1070 .sp
1071 The \fIcmd\fR argument is \fBF_GETLK64\fR, \fBF_SETLK64\fR, \fBF_SETLKW64\fR,
1072 \fBF_OFD_GETLK64\fR, \fBF_OFD_SETLK64\fR, or \fBF_OFD_SETLKW64\fR,
1073 and the smallest or, if \fBl_len\fR is non-zero, the largest, offset of any
1074 byte in the requested segment cannot be represented correctly in an object of
1075 type \fBoff64_t\fR.
1076 .RE
1078 .sp
1079 .LP
1080 The \fBfcntl()\fR function may fail if:
1081 .sp
1082 .ne 2
1083 .na
1084 \fB\fBEAGAIN\fR\fR
1085 .ad
1086 .RS 11n
1087 The \fIcmd\fR argument is \fBF_SETLK\fR, \fBF_SETLK64\fR, \fBF_SETLKW\fR,
1088 \fBF_SETLKW64\fR, \fBF_OFD_SETLK\fR, \fBF_OFD_SETLK64\fR, \fBF_OFD_SETLKW\fR,
1089 or \fBF_OFD_SETLKW64\fR and the file is currently being mapped to virtual memory
1090 using \fBmmap\fR(2).
1091 .RE
1093 .sp
1094 .ne 2
1095 .na
1096 \fB\fBEDEADLK\fR\fR
1097 .ad
1098 .RS 11n
1099 The \fIcmd\fR argument is \fBF_SETLKW\fR or \fBF_SETLKW64\fR, the lock is
1100 blocked by some lock from another process and putting the calling process to
1101 sleep, waiting for that lock to become free would cause a deadlock.
1102 .sp
1103 The \fIcmd\fR argument is \fBF_FREESP,\fR mandatory record locking is enabled,
1104 \fBO_NDELAY\fR and \fBO_NONBLOCK\fR are clear and a deadlock condition was
1105 detected.
1106 .RE
1108 .SH ATTRIBUTES
1109 .LP
1110 See \fBattributes\fR(5) for descriptions of the following attributes:
1111 .sp
1113 .sp
1114 .TS
1115 box;
1116 c | c
1117 l | l .
1118 ATTRIBUTE TYPE ATTRIBUTE VALUE
1119 _
1120 Interface Stability Standard
1121 _
1122 MT-Level Async-Signal Safe
1123 .TE
1125 .SH SEE ALSO
1126 .LP
1127 \fBlockd\fR(1M), \fBchmod\fR(2), \fBclose\fR(2), \fBcreat\fR(2), \fBdup\fR(2),
1128 \fBexec\fR(2), \fBfork\fR(2), \fBmmap\fR(2), \fBopen\fR(2), \fBpipe\fR(2),
1129 \fBread\fR(2), \fBsigaction\fR(2), \fBwrite\fR(2), \fBdup2\fR(3C),
1130 \fBflock\fR(3C), \fBlockf\fR(3C), \fBfcntl.h\fR(3HEAD), \fBattributes\fR(5),
1131 \fBlf64\fR(5), \fBstandards\fR(5)
1132 .sp
1133 .LP
1134 \fIProgramming Interfaces Guide\fR
1135 .SH NOTES
1136 .LP
1137 In the past, the variable \fBerrno\fR was set to \fBEACCES\fR rather than
1138 \fBEAGAIN\fR when a section of a file is already locked by another process.
1139 Therefore, portable application programs should expect and test for either
1140 value.
1141 .sp
1142 .LP
1143 Advisory locks allow cooperating processes to perform consistent operations on
1144 files, but do not guarantee exclusive access. Files can be accessed without
1145 advisory locks, but inconsistencies may result. The network share locking
1146 protocol does not support the \fBf_deny\fR value of \fBF_COMPAT\fR. For network
1147 file systems, if \fBf_access\fR is \fBF_RDACC\fR, \fBf_deny\fR is mapped to
1148 \fBF_RDDNY\fR. Otherwise, it is mapped to \fBF_RWDNY\fR.
1149 .sp
1150 .LP
1151 To prevent possible file corruption, the system may reject \fBmmap()\fR
1152 requests for advisory locked files, or it may reject advisory locking requests
1153 for mapped files. Applications that require a file be both locked and mapped
1154 should lock the entire file (\fBl_start\fR and \fBl_len\fR both set to 0). If a
1155 file is mapped, the system may reject an unlock request, resulting in a lock
1156 that does not cover the entire file.
1157 .sp
1158 .LP
1159 The process ID returned for locked files on network file systems might not be
1160 meaningful.
1161 .sp
1162 .LP
1163 If the file server crashes and has to be rebooted, the lock manager (see
1164 \fBlockd\fR(1M)) attempts to recover all locks that were associated with that
1165 server. If a lock cannot be reclaimed, the process that held the lock is issued
1166 a \fBSIGLOST\fR signal.