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.
170 In previous releases, this would allow a process with root privileges to
171 truncate a file without zeroing space.
172 For security reasons, this operation is no longer supported and will
173 instead truncate the file in the same manner as
176 Issue an advisory read async with no copy to user.
178 Turn read ahead off/on.
186 Turns data caching off/on. A non-zero value in
188 turns data caching off.
191 turns data caching on.
193 Get disk device information.
194 Currently this only returns the
195 disk device address that corresponds
196 to the current file offset. Note that the system
197 may return -1 as the disk device address if the file is not
198 backed by physical blocks. This is subject
200 .It Dv F_LOG2PHYS_EXT
201 Variant of F_LOG2PHYS that uses the passed in
202 file offset and length.
203 .It Dv F_BARRIERFSYNC
204 Does the same thing as
206 then issues a barrier command to the drive
209 The barrier applies to I/O that have been flushed with
211 on the same device before. These operations are guaranteed to
212 be persisted before any other I/O that would follow the barrier,
213 although no assumption should be made on what has been persisted
214 or not when this call returns. After the barrier has been issued,
215 operations on other FDs that have been fsync'd before can still be
216 re-ordered by the device, but not after the barrier. This is
217 typically useful to guarantee valid state on disk when ordering is a
218 concern but durability is not. A barrier can be used to order two phases of operations on
219 a set of file descriptors and ensure that no file can possibly get persisted
220 with the effect of the second phase without the effect of the first one. To do so,
221 execute operations of phase one, then
223 each FD and issue a single barrier. Finally execute operations of phase two.
224 This is currently implemented on HFS and APFS. It requires hardware support,
225 which Apple SSDs are guaranteed to provide.
227 Does the same thing as
229 then asks the drive to
230 flush all buffered data to
231 the permanent storage device
234 As this drains the entire queue of the device and acts as a
235 barrier, data that had been fsync'd on the same device before
236 is guaranteed to be persisted when this call returns.
237 This is currently implemented on HFS, MS-DOS (FAT),
238 Universal Disk Format (UDF) and APFS file systems.
239 The operation may take quite a while to complete.
240 Certain FireWire drives have also been known
241 to ignore the request to flush their buffered data.
242 .It Dv F_SETNOSIGPIPE
245 signal will be generated when a write fails on a pipe or socket for
246 which there is no reader. If
250 generation is disabled for descriptor
254 of zero enables it (the default).
255 .It Dv F_GETNOSIGPIPE
258 signal will be generated when a write fails on a pipe or socket
259 for which there is no reader. The semantics of the return value
270 commands are as follows:
271 .Bl -tag -width FD_CLOEXECX -offset indent
273 Close-on-exec; the given file descriptor will be automatically
274 closed in the successor process image when one of the
278 family of system calls is invoked.
285 commands are as follows:
286 .Bl -tag -width O_NONBLOCKX -offset indent
288 Non-blocking I/O; if no data is available to a
292 operation would block,
293 the read or write call returns -1 with the error
296 Force each write to append at the end of file;
304 signal to be sent to the process group
305 when I/O is possible, e.g.,
306 upon availability of data to be read.
309 Several commands are available for doing advisory file locking;
310 they all operate on the following structure:
314 off_t l_start; /* starting offset */
315 off_t l_len; /* len = 0 means until end of file */
316 pid_t l_pid; /* lock owner */
317 short l_type; /* lock type: read/write, etc. */
318 short l_whence; /* type of l_start */
322 The commands available for advisory record locking are as follows:
323 .Bl -tag -width F_SETLKWX
325 Get the first lock that blocks the lock description pointed to by the
328 taken as a pointer to a
331 The information retrieved overwrites the information passed to
336 If no lock is found that would prevent this lock from being created,
337 the structure is left unchanged by this function call except for the
338 lock type which is set to
341 Set or clear a file segment lock according to the lock description
342 pointed to by the third argument,
344 taken as a pointer to a
348 is used to establish shared (or read) locks
350 or exclusive (or write) locks,
352 as well as remove either type of lock
354 If a shared or exclusive lock cannot be set,
356 returns immediately with
359 This command is the same as
361 except that if a shared or exclusive lock is blocked by other locks,
362 the process waits until the request can be satisfied.
363 If a signal that is to be caught is received while
365 is waiting for a region, the
367 will be interrupted if the signal handler has not specified the
373 When a shared lock has been set on a segment of a file,
374 other processes can set shared locks on that segment
376 A shared lock prevents any other process from setting an exclusive
377 lock on any portion of the protected area.
378 A request for a shared lock fails if the file descriptor was not
379 opened with read access.
381 An exclusive lock prevents any other process from setting a shared lock or
382 an exclusive lock on any portion of the protected area.
383 A request for an exclusive lock fails if the file was not
384 opened with write access.
393 to indicate that the relative offset,
395 bytes, will be measured from the start of the file,
396 current position, or end of the file, respectively.
399 is the number of consecutive bytes to be locked.
402 is negative, the result is undefined.
405 field is only used with
407 to return the process ID of the process holding a blocking lock.
410 request, the value of
415 Locks may start and extend beyond the current end of a file,
416 but may not start or extend before the beginning of the file.
417 A lock is set to extend to the largest possible value of the
418 file offset for that file if
424 point to the beginning of the file, and
426 is zero, the entire file is locked.
427 If an application wishes only to do entire file locking, the
429 system call is much more efficient.
431 There is at most one type of lock set for each byte in the file.
432 Before a successful return from an
436 request when the calling process has previously existing locks
437 on bytes in the region specified by the request,
438 the previous lock type for each byte in the specified
439 region is replaced by the new lock type.
440 As specified above under the descriptions
441 of shared locks and exclusive locks, an
445 request fails or blocks respectively when another process has existing
446 locks on bytes in the specified region and the type of any of those
447 locks conflicts with the type specified in the request.
449 This interface follows the completely stupid semantics of System V and
451 that require that all locks associated with a file for a given process are
452 removed when \fIany\fP file descriptor for that file is closed by that process.
453 This semantic means that applications must be aware of any files that
454 a subroutine library may access.
455 For example if an application for updating the password file locks the
456 password file database while making the update, and then calls
458 to retrieve a record,
459 the lock will be lost because
461 opens, reads, and closes the password database.
462 The database close will release all locks that the process has
463 associated with the database, even if the library routine never
464 requested a lock on the database.
465 Another minor semantic problem with this interface is that
466 locks are not inherited by a child process created using the
471 interface has much more rational last close semantics and
472 allows locks to be inherited by child processes.
474 is recommended for applications that want to ensure the integrity
475 of their locks when using library routines or wish to pass locks
481 locks may be safely used concurrently.
483 All locks associated with a file for a given process are
484 removed when the process terminates.
486 A potential for deadlock occurs if a process controlling a locked region
487 is put to sleep by attempting to lock the locked region of another process.
488 This implementation detects that sleeping until a locked region is unlocked
489 would cause a deadlock and fails with an
495 command operates on the following structure:
498 typedef struct fstore {
499 u_int32_t fst_flags; /* IN: flags word */
500 int fst_posmode; /* IN: indicates offset field */
501 off_t fst_offset; /* IN: start of the region */
502 off_t fst_length; /* IN: size of the region */
503 off_t fst_bytesalloc; /* OUT: number of bytes allocated */
507 The flags (fst_flags) for the
509 command are as follows:
510 .Bl -tag -width F_ALLOCATECONTIGX -offset indent
511 .It Dv F_ALLOCATECONTIG
512 Allocate contiguous space.
514 Allocate all requested space or no space at all.
517 The position modes (fst_posmode) for the
519 command indicate how to use the offset field.
520 The modes are as follows:
521 .Bl -tag -width F_PEOFPOSMODEX -offset indent
523 Allocate from the physical end of file.
526 indicates the number of newly allocated bytes desired.
528 Allocate from the volume offset.
533 command operates on the following structure:
536 typedef struct fpunchhole {
537 u_int32_t fp_flags; /* unused */
538 u_int32_t reserved; /* (to maintain 8-byte alignment) */
539 off_t fp_offset; /* IN: start of the region */
540 off_t fp_length; /* IN: size of the region */
546 command operates on the following structure
547 which holds information passed from the
552 off_t ra_offset; /* offset into the file */
553 int ra_count; /* size of the read */
558 .Dv F_READBOOTSTRAP and F_WRITEBOOTSTRAP
559 commands operate on the following structure.
562 typedef struct fbootstraptransfer {
563 off_t fbt_offset; /* IN: offset to start read/write */
564 size_t fbt_length; /* IN: number of bytes to transfer */
565 void *fbt_buffer; /* IN: buffer to be read/written */
566 } fbootstraptransfer_t;
571 command operates on the following structure:
575 u_int32_t l2p_flags; /* unused so far */
576 off_t l2p_contigbytes; /* unused so far */
577 off_t l2p_devoffset; /* bytes into device */
583 command operates on the same structure as F_LOG2PHYS but treats it as an in/out:
587 u_int32_t l2p_flags; /* unused so far */
588 off_t l2p_contigbytes; /* IN: number of bytes to be queried;
589 OUT: number of contiguous bytes allocated at this position */
590 off_t l2p_devoffset; /* IN: bytes into file;
591 OUT: bytes into device */
597 is a socket, then the
601 commands are directly analogous, and fully interoperate with the
609 Upon successful completion, the value returned depends on
612 .Bl -tag -width F_GETOWNX -offset indent
614 A new file descriptor.
616 Value of flag (only the low-order bit is defined).
620 Value of file descriptor owner.
625 Otherwise, a value of -1 is returned and
627 is set to indicate the error.
631 system call will fail if:
645 and the segment of a file to be locked is already
646 exclusive-locked by another process;
647 or the type is an exclusive lock and some portion of the
648 segment of a file to be locked is already shared-locked or
649 exclusive-locked by another process.
657 and the calling process does not have root privileges.
661 is not a valid open file descriptor.
675 is not a valid file descriptor open for reading.
689 is not a valid file descriptor open for writing.
695 and the calling process does not have
696 file write permission.
706 is not a valid file descriptor open for reading.
713 and a deadlock condition was detected.
720 and the function was interrupted by a signal.
728 is negative or greater than the maximum allowable number
730 .Xr getdtablesize 2 ) .
739 and the data to which
741 points is not valid, or
743 refers to a file that does not support locking.
761 is a negative or zero value.
772 are negative, or both
776 are not multiples of the file system block size.
784 and the operation was attempted on a non-HFS disk type.
790 and the maximum allowed number of file descriptors are currently
798 and the maximum number of file descriptors permitted for the
799 process are already in use,
800 or no file descriptors greater than or equal to
811 and satisfying the lock or unlock request would result in the
812 number of locked regions in the system exceeding a system-imposed limit.
819 and either there is no space available on the volume containing
825 and there is not enough space available on the volume containing
827 to satisfy the entire request.
833 and there is not enough space available on the volume containing
835 to satisfy the request. As an example, a filesystem that supports
836 cloned files may return this error if punching a hole requires the
837 creation of a clone and there is not enough space available to do so.
840 A return value would overflow its representation.
843 is F_GETLK, F_SETLK, or F_SETLKW
844 and the smallest (or, if l_len is non-zero, the largest) offset
845 of a byte in the requested segment
846 will not fit in an object of type off_t.
851 and the calling process does not have file write permission.
858 the process ID given as argument is not in use.
864 .Xr getdtablesize 2 ,
873 function call appeared in
projects / apple / xnu.git / blob