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 same size or
157 larger than the space requested.
159 Deallocate a region and replace it with a hole. Subsequent reads of the
160 affected region will return bytes of zeros that are usually not backed by
161 physical blocks. This will not change the actual file size. Holes must be
162 aligned to file system block boundaries. This will fail on
163 file systems that do not support this interface.
165 Truncate a file without zeroing space.
166 The calling process must have root privileges.
168 Issue an advisory read async with no copy to user.
170 Turn read ahead off/on.
177 .It Dv F_READBOOTSTRAP
178 Read bootstrap from disk.
179 .It Dv F_WRITEBOOTSTRAP
180 Write bootstrap on disk.
181 The calling process must have root privileges.
183 Turns data caching off/on. A non-zero value in
185 turns data caching off.
188 turns data caching on.
190 Get disk device information.
191 Currently this only returns the
192 disk device address that corresponds
193 to the current file offset. Note that the system
194 may return -1 as the disk device address if the file is not
195 backed by physical blocks. This is subject
197 .It Dv F_LOG2PHYS_EXT
198 Variant of F_LOG2PHYS that uses the passed in
199 file offset and length.
201 Does the same thing as
203 then asks the drive to
204 flush all buffered data to
205 the permanent storage device
208 This is currently implemented on HFS, MS-DOS (FAT),
209 and Universal Disk Format (UDF) file systems.
210 The operation may take quite a while to complete.
211 Certain FireWire drives have also been known
212 to ignore the request to flush their buffered data.
213 .It Dv F_SETNOSIGPIPE
216 signal will be generated when a write fails on a pipe or socket for
217 which there is no reader. If
221 generation is disabled for descriptor
225 of zero enables it (the default).
226 .It Dv F_GETNOSIGPIPE
229 signal will be generated when a write fails on a pipe or socket
230 for which there is no reader. The semantics of the return value
241 commands are as follows:
242 .Bl -tag -width FD_CLOEXECX -offset indent
244 Close-on-exec; the given file descriptor will be automatically
245 closed in the successor process image when one of the
249 family of system calls is invoked.
256 commands are as follows:
257 .Bl -tag -width O_NONBLOCKX -offset indent
259 Non-blocking I/O; if no data is available to a
263 operation would block,
264 the read or write call returns -1 with the error
267 Force each write to append at the end of file;
275 signal to be sent to the process group
276 when I/O is possible, e.g.,
277 upon availability of data to be read.
280 Several commands are available for doing advisory file locking;
281 they all operate on the following structure:
285 off_t l_start; /* starting offset */
286 off_t l_len; /* len = 0 means until end of file */
287 pid_t l_pid; /* lock owner */
288 short l_type; /* lock type: read/write, etc. */
289 short l_whence; /* type of l_start */
293 The commands available for advisory record locking are as follows:
294 .Bl -tag -width F_SETLKWX
296 Get the first lock that blocks the lock description pointed to by the
299 taken as a pointer to a
302 The information retrieved overwrites the information passed to
307 If no lock is found that would prevent this lock from being created,
308 the structure is left unchanged by this function call except for the
309 lock type which is set to
312 Set or clear a file segment lock according to the lock description
313 pointed to by the third argument,
315 taken as a pointer to a
319 is used to establish shared (or read) locks
321 or exclusive (or write) locks,
323 as well as remove either type of lock
325 If a shared or exclusive lock cannot be set,
327 returns immediately with
330 This command is the same as
332 except that if a shared or exclusive lock is blocked by other locks,
333 the process waits until the request can be satisfied.
334 If a signal that is to be caught is received while
336 is waiting for a region, the
338 will be interrupted if the signal handler has not specified the
344 When a shared lock has been set on a segment of a file,
345 other processes can set shared locks on that segment
347 A shared lock prevents any other process from setting an exclusive
348 lock on any portion of the protected area.
349 A request for a shared lock fails if the file descriptor was not
350 opened with read access.
352 An exclusive lock prevents any other process from setting a shared lock or
353 an exclusive lock on any portion of the protected area.
354 A request for an exclusive lock fails if the file was not
355 opened with write access.
364 to indicate that the relative offset,
366 bytes, will be measured from the start of the file,
367 current position, or end of the file, respectively.
370 is the number of consecutive bytes to be locked.
373 is negative, the result is undefined.
376 field is only used with
378 to return the process ID of the process holding a blocking lock.
381 request, the value of
386 Locks may start and extend beyond the current end of a file,
387 but may not start or extend before the beginning of the file.
388 A lock is set to extend to the largest possible value of the
389 file offset for that file if
395 point to the beginning of the file, and
397 is zero, the entire file is locked.
398 If an application wishes only to do entire file locking, the
400 system call is much more efficient.
402 There is at most one type of lock set for each byte in the file.
403 Before a successful return from an
407 request when the calling process has previously existing locks
408 on bytes in the region specified by the request,
409 the previous lock type for each byte in the specified
410 region is replaced by the new lock type.
411 As specified above under the descriptions
412 of shared locks and exclusive locks, an
416 request fails or blocks respectively when another process has existing
417 locks on bytes in the specified region and the type of any of those
418 locks conflicts with the type specified in the request.
420 This interface follows the completely stupid semantics of System V and
422 that require that all locks associated with a file for a given process are
423 removed when \fIany\fP file descriptor for that file is closed by that process.
424 This semantic means that applications must be aware of any files that
425 a subroutine library may access.
426 For example if an application for updating the password file locks the
427 password file database while making the update, and then calls
429 to retrieve a record,
430 the lock will be lost because
432 opens, reads, and closes the password database.
433 The database close will release all locks that the process has
434 associated with the database, even if the library routine never
435 requested a lock on the database.
436 Another minor semantic problem with this interface is that
437 locks are not inherited by a child process created using the
442 interface has much more rational last close semantics and
443 allows locks to be inherited by child processes.
445 is recommended for applications that want to ensure the integrity
446 of their locks when using library routines or wish to pass locks
452 locks may be safely used concurrently.
454 All locks associated with a file for a given process are
455 removed when the process terminates.
457 A potential for deadlock occurs if a process controlling a locked region
458 is put to sleep by attempting to lock the locked region of another process.
459 This implementation detects that sleeping until a locked region is unlocked
460 would cause a deadlock and fails with an
466 command operates on the following structure:
469 typedef struct fstore {
470 u_int32_t fst_flags; /* IN: flags word */
471 int fst_posmode; /* IN: indicates offset field */
472 off_t fst_offset; /* IN: start of the region */
473 off_t fst_length; /* IN: size of the region */
474 off_t fst_bytesalloc; /* OUT: number of bytes allocated */
478 The flags (fst_flags) for the
480 command are as follows:
481 .Bl -tag -width F_ALLOCATECONTIGX -offset indent
482 .It Dv F_ALLOCATECONTIG
483 Allocate contiguous space.
485 Allocate all requested space or no space at all.
488 The position modes (fst_posmode) for the
490 command indicate how to use the offset field.
491 The modes are as follows:
492 .Bl -tag -width F_PEOFPOSMODEX -offset indent
494 Allocate from the physical end of file.
496 Allocate from the volume offset.
501 command operates on the following structure:
504 typedef struct fpunchhole {
505 u_int32_t fp_flags; /* unused */
506 u_int32_t reserved; /* (to maintain 8-byte alignment) */
507 off_t fp_offset; /* IN: start of the region */
508 off_t fp_length; /* IN: size of the region */
514 command operates on the following structure
515 which holds information passed from the
520 off_t ra_offset; /* offset into the file */
521 int ra_count; /* size of the read */
526 .Dv F_READBOOTSTRAP and F_WRITEBOOTSTRAP
527 commands operate on the following structure.
530 typedef struct fbootstraptransfer {
531 off_t fbt_offset; /* IN: offset to start read/write */
532 size_t fbt_length; /* IN: number of bytes to transfer */
533 void *fbt_buffer; /* IN: buffer to be read/written */
534 } fbootstraptransfer_t;
539 command operates on the following structure:
543 u_int32_t l2p_flags; /* unused so far */
544 off_t l2p_contigbytes; /* unused so far */
545 off_t l2p_devoffset; /* bytes into device */
551 command operates on the same structure as F_LOG2PHYS but treats it as an in/out:
555 u_int32_t l2p_flags; /* unused so far */
556 off_t l2p_contigbytes; /* IN: number of bytes to be queried;
557 OUT: number of contiguous bytes allocated at this position */
558 off_t l2p_devoffset; /* IN: bytes into file;
559 OUT: bytes into device */
565 is a socket, then the
569 commands are directly analogous, and fully interoperate with the
577 Upon successful completion, the value returned depends on
580 .Bl -tag -width F_GETOWNX -offset indent
582 A new file descriptor.
584 Value of flag (only the low-order bit is defined).
588 Value of file descriptor owner.
593 Otherwise, a value of -1 is returned and
595 is set to indicate the error.
599 system call will fail if:
613 and the segment of a file to be locked is already
614 exclusive-locked by another process;
615 or the type is an exclusive lock and some portion of the
616 segment of a file to be locked is already shared-locked or
617 exclusive-locked by another process.
625 and the calling process does not have root privileges.
629 is not a valid open file descriptor.
643 is not a valid file descriptor open for reading.
657 is not a valid file descriptor open for writing.
663 and the calling process does not have
664 file write permission.
674 is not a valid file descriptor open for reading.
681 and a deadlock condition was detected.
688 and the function was interrupted by a signal.
696 is negative or greater than the maximum allowable number
698 .Xr getdtablesize 2 ) .
707 and the data to which
709 points is not valid, or
711 refers to a file that does not support locking.
729 is a negative or zero value.
740 are negative, or both
744 are not multiples of the file system block size.
752 and the operation was attempted on a non-HFS disk type.
758 and the maximum allowed number of file descriptors are currently
766 and the maximum number of file descriptors permitted for the
767 process are already in use,
768 or no file descriptors greater than or equal to
779 and satisfying the lock or unlock request would result in the
780 number of locked regions in the system exceeding a system-imposed limit.
783 A return value would overflow its representation.
786 is F_GETLK, F_SETLK, or F_SETLKW
787 and the smallest (or, if l_len is non-zero, the largest) offset
788 of a byte in the requested segment
789 will not fit in an object of type off_t.
796 the process ID given as argument is not in use.
802 .Xr getdtablesize 2 ,
811 function call appeared in
projects / apple / xnu.git / blob