2 .\" Copyright (c) 2011 Apple Inc. All rights reserved.
4 .\" @APPLE_LICENSE_HEADER_START@
6 .\" This file contains Original Code and/or Modifications of Original Code
7 .\" as defined in and that are subject to the Apple Public Source License
8 .\" Version 2.0 (the 'License'). You may not use this file except in
9 .\" compliance with the License. Please obtain a copy of the License at
10 .\" http://www.opensource.apple.com/apsl/ and read it before using this
13 .\" The Original Code and all software distributed under the License are
14 .\" distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
15 .\" EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
16 .\" INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
17 .\" FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
18 .\" Please see the License for the specific language governing rights and
19 .\" limitations under the License.
21 .\" @APPLE_LICENSE_HEADER_END@
24 .\" $NetBSD: fcntl.2,v 1.6 1995/02/27 12:32:29 cgd Exp $
26 .\" Copyright (c) 1983, 1993
27 .\" The Regents of the University of California. All rights reserved.
29 .\" Redistribution and use in source and binary forms, with or without
30 .\" modification, are permitted provided that the following conditions
32 .\" 1. Redistributions of source code must retain the above copyright
33 .\" notice, this list of conditions and the following disclaimer.
34 .\" 2. Redistributions in binary form must reproduce the above copyright
35 .\" notice, this list of conditions and the following disclaimer in the
36 .\" documentation and/or other materials provided with the distribution.
37 .\" 3. All advertising materials mentioning features or use of this software
38 .\" must display the following acknowledgement:
39 .\" This product includes software developed by the University of
40 .\" California, Berkeley and its contributors.
41 .\" 4. Neither the name of the University nor the names of its contributors
42 .\" may be used to endorse or promote products derived from this software
43 .\" without specific prior written permission.
45 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
46 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
47 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
48 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
49 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
50 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
51 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
52 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
53 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
54 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
57 .\" @(#)fcntl.2 8.2 (Berkeley) 1/12/94
66 .Fd #include <fcntl.h>
75 provides for control over descriptors.
78 is a descriptor to be operated on by
81 .Bl -tag -width F_WRITEBOOTSTRAPX
83 Return a new descriptor as follows:
85 .Bl -bullet -compact -offset 4n
87 Lowest numbered available descriptor greater than or equal to
90 Same object references as the original descriptor.
92 New descriptor shares the same file offset if the object
95 Same access mode (read, write or read/write).
97 Same file status flags (i.e., both file descriptors
98 share the same file status flags).
100 The close-on-exec flag associated with the new file descriptor
101 is cleared so that the descriptor remains open across an
105 .It Dv F_DUPFD_CLOEXEC
108 except that the close-on-exec flag associated with the new file descriptor
111 Get the flags associated with the file descriptor
117 Set the file descriptor flags to
120 Get descriptor status flags, as described below
124 Set descriptor status flags to
127 Get the process ID or process group
132 signals; process groups are returned
137 Set the process or process group
143 process groups are specified by supplying
145 as negative, otherwise
147 is interpreted as a process ID.
149 Get the path of the file descriptor
150 .It Dv F_GETPATH_NOFIRMLINK
151 Get the non firmlinked path of the file descriptor
153 The argument must be a buffer of size
157 Preallocate file storage space. Note: upon success,
158 the space that is allocated can be the size requested,
159 larger than the size requested, or (if the
161 flag is not provided) smaller than the space requested.
163 Deallocate a region and replace it with a hole. Subsequent reads of the
164 affected region will return bytes of zeros that are usually not backed by
165 physical blocks. This will not change the actual file size. Holes must be
166 aligned to file system block boundaries. This will fail on
167 file systems that do not support this interface.
169 Truncate a file without zeroing space.
170 The calling process must have root privileges.
172 Issue an advisory read async with no copy to user.
174 Turn read ahead off/on.
182 Turns data caching off/on. A non-zero value in
184 turns data caching off.
187 turns data caching on.
189 Get disk device information.
190 Currently this only returns the
191 disk device address that corresponds
192 to the current file offset. Note that the system
193 may return -1 as the disk device address if the file is not
194 backed by physical blocks. This is subject
196 .It Dv F_LOG2PHYS_EXT
197 Variant of F_LOG2PHYS that uses the passed in
198 file offset and length.
199 .It Dv F_BARRIERFSYNC
200 Does the same thing as
202 then issues a barrier command to the drive
205 The barrier applies to I/O that have been flushed with
207 on the same device before. These operations are guaranteed to
208 be persisted before any other I/O that would follow the barrier,
209 although no assumption should be made on what has been persisted
210 or not when this call returns. After the barrier has been issued,
211 operations on other FDs that have been fsync'd before can still be
212 re-ordered by the device, but not after the barrier. This is
213 typically useful to guarantee valid state on disk when ordering is a
214 concern but durability is not. A barrier can be used to order two phases of operations on
215 a set of file descriptors and ensure that no file can possibly get persisted
216 with the effect of the second phase without the effect of the first one. To do so,
217 execute operations of phase one, then
219 each FD and issue a single barrier. Finally execute operations of phase two.
220 This is currently implemented on HFS and APFS. It requires hardware support,
221 which Apple SSDs are guaranteed to provide.
223 Does the same thing as
225 then asks the drive to
226 flush all buffered data to
227 the permanent storage device
230 As this drains the entire queue of the device and acts as a
231 barrier, data that had been fsync'd on the same device before
232 is guaranteed to be persisted when this call returns.
233 This is currently implemented on HFS, MS-DOS (FAT),
234 Universal Disk Format (UDF) and APFS file systems.
235 The operation may take quite a while to complete.
236 Certain FireWire drives have also been known
237 to ignore the request to flush their buffered data.
238 .It Dv F_SETNOSIGPIPE
241 signal will be generated when a write fails on a pipe or socket for
242 which there is no reader. If
246 generation is disabled for descriptor
250 of zero enables it (the default).
251 .It Dv F_GETNOSIGPIPE
254 signal will be generated when a write fails on a pipe or socket
255 for which there is no reader. The semantics of the return value
266 commands are as follows:
267 .Bl -tag -width FD_CLOEXECX -offset indent
269 Close-on-exec; the given file descriptor will be automatically
270 closed in the successor process image when one of the
274 family of system calls is invoked.
281 commands are as follows:
282 .Bl -tag -width O_NONBLOCKX -offset indent
284 Non-blocking I/O; if no data is available to a
288 operation would block,
289 the read or write call returns -1 with the error
292 Force each write to append at the end of file;
300 signal to be sent to the process group
301 when I/O is possible, e.g.,
302 upon availability of data to be read.
305 Several commands are available for doing advisory file locking;
306 they all operate on the following structure:
310 off_t l_start; /* starting offset */
311 off_t l_len; /* len = 0 means until end of file */
312 pid_t l_pid; /* lock owner */
313 short l_type; /* lock type: read/write, etc. */
314 short l_whence; /* type of l_start */
318 The commands available for advisory record locking are as follows:
319 .Bl -tag -width F_SETLKWX
321 Get the first lock that blocks the lock description pointed to by the
324 taken as a pointer to a
327 The information retrieved overwrites the information passed to
332 If no lock is found that would prevent this lock from being created,
333 the structure is left unchanged by this function call except for the
334 lock type which is set to
337 Set or clear a file segment lock according to the lock description
338 pointed to by the third argument,
340 taken as a pointer to a
344 is used to establish shared (or read) locks
346 or exclusive (or write) locks,
348 as well as remove either type of lock
350 If a shared or exclusive lock cannot be set,
352 returns immediately with
355 This command is the same as
357 except that if a shared or exclusive lock is blocked by other locks,
358 the process waits until the request can be satisfied.
359 If a signal that is to be caught is received while
361 is waiting for a region, the
363 will be interrupted if the signal handler has not specified the
369 When a shared lock has been set on a segment of a file,
370 other processes can set shared locks on that segment
372 A shared lock prevents any other process from setting an exclusive
373 lock on any portion of the protected area.
374 A request for a shared lock fails if the file descriptor was not
375 opened with read access.
377 An exclusive lock prevents any other process from setting a shared lock or
378 an exclusive lock on any portion of the protected area.
379 A request for an exclusive lock fails if the file was not
380 opened with write access.
389 to indicate that the relative offset,
391 bytes, will be measured from the start of the file,
392 current position, or end of the file, respectively.
395 is the number of consecutive bytes to be locked.
398 is negative, the result is undefined.
401 field is only used with
403 to return the process ID of the process holding a blocking lock.
406 request, the value of
411 Locks may start and extend beyond the current end of a file,
412 but may not start or extend before the beginning of the file.
413 A lock is set to extend to the largest possible value of the
414 file offset for that file if
420 point to the beginning of the file, and
422 is zero, the entire file is locked.
423 If an application wishes only to do entire file locking, the
425 system call is much more efficient.
427 There is at most one type of lock set for each byte in the file.
428 Before a successful return from an
432 request when the calling process has previously existing locks
433 on bytes in the region specified by the request,
434 the previous lock type for each byte in the specified
435 region is replaced by the new lock type.
436 As specified above under the descriptions
437 of shared locks and exclusive locks, an
441 request fails or blocks respectively when another process has existing
442 locks on bytes in the specified region and the type of any of those
443 locks conflicts with the type specified in the request.
445 This interface follows the completely stupid semantics of System V and
447 that require that all locks associated with a file for a given process are
448 removed when \fIany\fP file descriptor for that file is closed by that process.
449 This semantic means that applications must be aware of any files that
450 a subroutine library may access.
451 For example if an application for updating the password file locks the
452 password file database while making the update, and then calls
454 to retrieve a record,
455 the lock will be lost because
457 opens, reads, and closes the password database.
458 The database close will release all locks that the process has
459 associated with the database, even if the library routine never
460 requested a lock on the database.
461 Another minor semantic problem with this interface is that
462 locks are not inherited by a child process created using the
467 interface has much more rational last close semantics and
468 allows locks to be inherited by child processes.
470 is recommended for applications that want to ensure the integrity
471 of their locks when using library routines or wish to pass locks
477 locks may be safely used concurrently.
479 All locks associated with a file for a given process are
480 removed when the process terminates.
482 A potential for deadlock occurs if a process controlling a locked region
483 is put to sleep by attempting to lock the locked region of another process.
484 This implementation detects that sleeping until a locked region is unlocked
485 would cause a deadlock and fails with an
491 command operates on the following structure:
494 typedef struct fstore {
495 u_int32_t fst_flags; /* IN: flags word */
496 int fst_posmode; /* IN: indicates offset field */
497 off_t fst_offset; /* IN: start of the region */
498 off_t fst_length; /* IN: size of the region */
499 off_t fst_bytesalloc; /* OUT: number of bytes allocated */
503 The flags (fst_flags) for the
505 command are as follows:
506 .Bl -tag -width F_ALLOCATECONTIGX -offset indent
507 .It Dv F_ALLOCATECONTIG
508 Allocate contiguous space.
510 Allocate all requested space or no space at all.
513 The position modes (fst_posmode) for the
515 command indicate how to use the offset field.
516 The modes are as follows:
517 .Bl -tag -width F_PEOFPOSMODEX -offset indent
519 Allocate from the physical end of file.
522 indicates the number of newly allocated bytes desired.
524 Allocate from the volume offset.
529 command operates on the following structure:
532 typedef struct fpunchhole {
533 u_int32_t fp_flags; /* unused */
534 u_int32_t reserved; /* (to maintain 8-byte alignment) */
535 off_t fp_offset; /* IN: start of the region */
536 off_t fp_length; /* IN: size of the region */
542 command operates on the following structure
543 which holds information passed from the
548 off_t ra_offset; /* offset into the file */
549 int ra_count; /* size of the read */
554 .Dv F_READBOOTSTRAP and F_WRITEBOOTSTRAP
555 commands operate on the following structure.
558 typedef struct fbootstraptransfer {
559 off_t fbt_offset; /* IN: offset to start read/write */
560 size_t fbt_length; /* IN: number of bytes to transfer */
561 void *fbt_buffer; /* IN: buffer to be read/written */
562 } fbootstraptransfer_t;
567 command operates on the following structure:
571 u_int32_t l2p_flags; /* unused so far */
572 off_t l2p_contigbytes; /* unused so far */
573 off_t l2p_devoffset; /* bytes into device */
579 command operates on the same structure as F_LOG2PHYS but treats it as an in/out:
583 u_int32_t l2p_flags; /* unused so far */
584 off_t l2p_contigbytes; /* IN: number of bytes to be queried;
585 OUT: number of contiguous bytes allocated at this position */
586 off_t l2p_devoffset; /* IN: bytes into file;
587 OUT: bytes into device */
593 is a socket, then the
597 commands are directly analogous, and fully interoperate with the
605 Upon successful completion, the value returned depends on
608 .Bl -tag -width F_GETOWNX -offset indent
610 A new file descriptor.
612 Value of flag (only the low-order bit is defined).
616 Value of file descriptor owner.
621 Otherwise, a value of -1 is returned and
623 is set to indicate the error.
627 system call will fail if:
641 and the segment of a file to be locked is already
642 exclusive-locked by another process;
643 or the type is an exclusive lock and some portion of the
644 segment of a file to be locked is already shared-locked or
645 exclusive-locked by another process.
653 and the calling process does not have root privileges.
657 is not a valid open file descriptor.
671 is not a valid file descriptor open for reading.
685 is not a valid file descriptor open for writing.
691 and the calling process does not have
692 file write permission.
702 is not a valid file descriptor open for reading.
709 and a deadlock condition was detected.
716 and the function was interrupted by a signal.
724 is negative or greater than the maximum allowable number
726 .Xr getdtablesize 2 ) .
735 and the data to which
737 points is not valid, or
739 refers to a file that does not support locking.
757 is a negative or zero value.
768 are negative, or both
772 are not multiples of the file system block size.
780 and the operation was attempted on a non-HFS disk type.
786 and the maximum allowed number of file descriptors are currently
794 and the maximum number of file descriptors permitted for the
795 process are already in use,
796 or no file descriptors greater than or equal to
807 and satisfying the lock or unlock request would result in the
808 number of locked regions in the system exceeding a system-imposed limit.
815 and either there is no space available on the volume containing
821 and there is not enough space available on the volume containing
823 to satisfy the entire request.
829 and there is not enough space available on the volume containing
831 to satisfy the request. As an example, a filesystem that supports
832 cloned files may return this error if punching a hole requires the
833 creation of a clone and there is not enough space available to do so.
836 A return value would overflow its representation.
839 is F_GETLK, F_SETLK, or F_SETLKW
840 and the smallest (or, if l_len is non-zero, the largest) offset
841 of a byte in the requested segment
842 will not fit in an object of type off_t.
847 and the calling process does not have file write permission.
854 the process ID given as argument is not in use.
860 .Xr getdtablesize 2 ,
869 function call appeared in
projects / apple / xnu.git / blob