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
151 The argument must be a buffer of size
155 Preallocate file storage space. Note: upon success,
156 the space that is allocated can be the size requested,
157 larger than the size requested, or (if the
159 flag is not provided) smaller than the space requested.
161 Deallocate a region and replace it with a hole. Subsequent reads of the
162 affected region will return bytes of zeros that are usually not backed by
163 physical blocks. This will not change the actual file size. Holes must be
164 aligned to file system block boundaries. This will fail on
165 file systems that do not support this interface.
167 Truncate a file without zeroing space.
168 The calling process must have root privileges.
170 Issue an advisory read async with no copy to user.
172 Turn read ahead off/on.
179 .It Dv F_READBOOTSTRAP
180 Read bootstrap from disk.
181 .It Dv F_WRITEBOOTSTRAP
182 Write bootstrap on disk.
183 The calling process must have root privileges.
185 Turns data caching off/on. A non-zero value in
187 turns data caching off.
190 turns data caching on.
192 Get disk device information.
193 Currently this only returns the
194 disk device address that corresponds
195 to the current file offset. Note that the system
196 may return -1 as the disk device address if the file is not
197 backed by physical blocks. This is subject
199 .It Dv F_LOG2PHYS_EXT
200 Variant of F_LOG2PHYS that uses the passed in
201 file offset and length.
203 Does the same thing as
205 then asks the drive to
206 flush all buffered data to
207 the permanent storage device
210 This is currently implemented on HFS, MS-DOS (FAT),
211 and Universal Disk Format (UDF) file systems.
212 The operation may take quite a while to complete.
213 Certain FireWire drives have also been known
214 to ignore the request to flush their buffered data.
215 .It Dv F_SETNOSIGPIPE
218 signal will be generated when a write fails on a pipe or socket for
219 which there is no reader. If
223 generation is disabled for descriptor
227 of zero enables it (the default).
228 .It Dv F_GETNOSIGPIPE
231 signal will be generated when a write fails on a pipe or socket
232 for which there is no reader. The semantics of the return value
243 commands are as follows:
244 .Bl -tag -width FD_CLOEXECX -offset indent
246 Close-on-exec; the given file descriptor will be automatically
247 closed in the successor process image when one of the
251 family of system calls is invoked.
258 commands are as follows:
259 .Bl -tag -width O_NONBLOCKX -offset indent
261 Non-blocking I/O; if no data is available to a
265 operation would block,
266 the read or write call returns -1 with the error
269 Force each write to append at the end of file;
277 signal to be sent to the process group
278 when I/O is possible, e.g.,
279 upon availability of data to be read.
282 Several commands are available for doing advisory file locking;
283 they all operate on the following structure:
287 off_t l_start; /* starting offset */
288 off_t l_len; /* len = 0 means until end of file */
289 pid_t l_pid; /* lock owner */
290 short l_type; /* lock type: read/write, etc. */
291 short l_whence; /* type of l_start */
295 The commands available for advisory record locking are as follows:
296 .Bl -tag -width F_SETLKWX
298 Get the first lock that blocks the lock description pointed to by the
301 taken as a pointer to a
304 The information retrieved overwrites the information passed to
309 If no lock is found that would prevent this lock from being created,
310 the structure is left unchanged by this function call except for the
311 lock type which is set to
314 Set or clear a file segment lock according to the lock description
315 pointed to by the third argument,
317 taken as a pointer to a
321 is used to establish shared (or read) locks
323 or exclusive (or write) locks,
325 as well as remove either type of lock
327 If a shared or exclusive lock cannot be set,
329 returns immediately with
332 This command is the same as
334 except that if a shared or exclusive lock is blocked by other locks,
335 the process waits until the request can be satisfied.
336 If a signal that is to be caught is received while
338 is waiting for a region, the
340 will be interrupted if the signal handler has not specified the
346 When a shared lock has been set on a segment of a file,
347 other processes can set shared locks on that segment
349 A shared lock prevents any other process from setting an exclusive
350 lock on any portion of the protected area.
351 A request for a shared lock fails if the file descriptor was not
352 opened with read access.
354 An exclusive lock prevents any other process from setting a shared lock or
355 an exclusive lock on any portion of the protected area.
356 A request for an exclusive lock fails if the file was not
357 opened with write access.
366 to indicate that the relative offset,
368 bytes, will be measured from the start of the file,
369 current position, or end of the file, respectively.
372 is the number of consecutive bytes to be locked.
375 is negative, the result is undefined.
378 field is only used with
380 to return the process ID of the process holding a blocking lock.
383 request, the value of
388 Locks may start and extend beyond the current end of a file,
389 but may not start or extend before the beginning of the file.
390 A lock is set to extend to the largest possible value of the
391 file offset for that file if
397 point to the beginning of the file, and
399 is zero, the entire file is locked.
400 If an application wishes only to do entire file locking, the
402 system call is much more efficient.
404 There is at most one type of lock set for each byte in the file.
405 Before a successful return from an
409 request when the calling process has previously existing locks
410 on bytes in the region specified by the request,
411 the previous lock type for each byte in the specified
412 region is replaced by the new lock type.
413 As specified above under the descriptions
414 of shared locks and exclusive locks, an
418 request fails or blocks respectively when another process has existing
419 locks on bytes in the specified region and the type of any of those
420 locks conflicts with the type specified in the request.
422 This interface follows the completely stupid semantics of System V and
424 that require that all locks associated with a file for a given process are
425 removed when \fIany\fP file descriptor for that file is closed by that process.
426 This semantic means that applications must be aware of any files that
427 a subroutine library may access.
428 For example if an application for updating the password file locks the
429 password file database while making the update, and then calls
431 to retrieve a record,
432 the lock will be lost because
434 opens, reads, and closes the password database.
435 The database close will release all locks that the process has
436 associated with the database, even if the library routine never
437 requested a lock on the database.
438 Another minor semantic problem with this interface is that
439 locks are not inherited by a child process created using the
444 interface has much more rational last close semantics and
445 allows locks to be inherited by child processes.
447 is recommended for applications that want to ensure the integrity
448 of their locks when using library routines or wish to pass locks
454 locks may be safely used concurrently.
456 All locks associated with a file for a given process are
457 removed when the process terminates.
459 A potential for deadlock occurs if a process controlling a locked region
460 is put to sleep by attempting to lock the locked region of another process.
461 This implementation detects that sleeping until a locked region is unlocked
462 would cause a deadlock and fails with an
468 command operates on the following structure:
471 typedef struct fstore {
472 u_int32_t fst_flags; /* IN: flags word */
473 int fst_posmode; /* IN: indicates offset field */
474 off_t fst_offset; /* IN: start of the region */
475 off_t fst_length; /* IN: size of the region */
476 off_t fst_bytesalloc; /* OUT: number of bytes allocated */
480 The flags (fst_flags) for the
482 command are as follows:
483 .Bl -tag -width F_ALLOCATECONTIGX -offset indent
484 .It Dv F_ALLOCATECONTIG
485 Allocate contiguous space.
487 Allocate all requested space or no space at all.
490 The position modes (fst_posmode) for the
492 command indicate how to use the offset field.
493 The modes are as follows:
494 .Bl -tag -width F_PEOFPOSMODEX -offset indent
496 Allocate from the physical end of file.
498 Allocate from the volume offset.
503 command operates on the following structure:
506 typedef struct fpunchhole {
507 u_int32_t fp_flags; /* unused */
508 u_int32_t reserved; /* (to maintain 8-byte alignment) */
509 off_t fp_offset; /* IN: start of the region */
510 off_t fp_length; /* IN: size of the region */
516 command operates on the following structure
517 which holds information passed from the
522 off_t ra_offset; /* offset into the file */
523 int ra_count; /* size of the read */
528 .Dv F_READBOOTSTRAP and F_WRITEBOOTSTRAP
529 commands operate on the following structure.
532 typedef struct fbootstraptransfer {
533 off_t fbt_offset; /* IN: offset to start read/write */
534 size_t fbt_length; /* IN: number of bytes to transfer */
535 void *fbt_buffer; /* IN: buffer to be read/written */
536 } fbootstraptransfer_t;
541 command operates on the following structure:
545 u_int32_t l2p_flags; /* unused so far */
546 off_t l2p_contigbytes; /* unused so far */
547 off_t l2p_devoffset; /* bytes into device */
553 command operates on the same structure as F_LOG2PHYS but treats it as an in/out:
557 u_int32_t l2p_flags; /* unused so far */
558 off_t l2p_contigbytes; /* IN: number of bytes to be queried;
559 OUT: number of contiguous bytes allocated at this position */
560 off_t l2p_devoffset; /* IN: bytes into file;
561 OUT: bytes into device */
567 is a socket, then the
571 commands are directly analogous, and fully interoperate with the
579 Upon successful completion, the value returned depends on
582 .Bl -tag -width F_GETOWNX -offset indent
584 A new file descriptor.
586 Value of flag (only the low-order bit is defined).
590 Value of file descriptor owner.
595 Otherwise, a value of -1 is returned and
597 is set to indicate the error.
601 system call will fail if:
615 and the segment of a file to be locked is already
616 exclusive-locked by another process;
617 or the type is an exclusive lock and some portion of the
618 segment of a file to be locked is already shared-locked or
619 exclusive-locked by another process.
627 and the calling process does not have root privileges.
631 is not a valid open file descriptor.
645 is not a valid file descriptor open for reading.
659 is not a valid file descriptor open for writing.
665 and the calling process does not have
666 file write permission.
676 is not a valid file descriptor open for reading.
683 and a deadlock condition was detected.
690 and the function was interrupted by a signal.
698 is negative or greater than the maximum allowable number
700 .Xr getdtablesize 2 ) .
709 and the data to which
711 points is not valid, or
713 refers to a file that does not support locking.
731 is a negative or zero value.
742 are negative, or both
746 are not multiples of the file system block size.
754 and the operation was attempted on a non-HFS disk type.
760 and the maximum allowed number of file descriptors are currently
768 and the maximum number of file descriptors permitted for the
769 process are already in use,
770 or no file descriptors greater than or equal to
781 and satisfying the lock or unlock request would result in the
782 number of locked regions in the system exceeding a system-imposed limit.
789 and either there is no space available on the volume containing
795 and there is not enough space available on the volume containing
797 to satisfy the entire request.
803 and there is not enough space available on the volume containing
805 to satisfy the request. As an example, a filesystem that supports
806 cloned files may return this error if punching a hole requires the
807 creation of a clone and there is not enough space available to do so.
810 A return value would overflow its representation.
813 is F_GETLK, F_SETLK, or F_SETLKW
814 and the smallest (or, if l_len is non-zero, the largest) offset
815 of a byte in the requested segment
816 will not fit in an object of type off_t.
821 and the calling process does not have file write permission.
828 the process ID given as argument is not in use.
834 .Xr getdtablesize 2 ,
843 function call appeared in
projects / apple / xnu.git / blob