.\"
.\" @(#)fcntl.2 8.2 (Berkeley) 1/12/94
.\"
-.Dd February 17, 2011
+.Dd August 8, 2018
.Dt FCNTL 2
.Os BSD 4.2
.Sh NAME
.Fa arg
is interpreted as a process ID.
.It Dv F_GETPATH
-Get the path of the file descriptor
+Get the path of the file descriptor
+.It Dv F_GETPATH_NOFIRMLINK
+Get the non firmlinked path of the file descriptor
.Fa Fildes .
The argument must be a buffer of size
.Sy MAXPATHLEN
or greater.
.It Dv F_PREALLOCATE
Preallocate file storage space. Note: upon success,
-the space that is allocated can be the same size or
-larger than the space requested.
+the space that is allocated can be the size requested,
+larger than the size requested, or (if the
+.Dv F_ALLOCATEALL
+flag is not provided) smaller than the space requested.
.It Dv F_PUNCHHOLE
Deallocate a region and replace it with a hole. Subsequent reads of the
affected region will return bytes of zeros that are usually not backed by
aligned to file system block boundaries. This will fail on
file systems that do not support this interface.
.It Dv F_SETSIZE
-Truncate a file without zeroing space.
-The calling process must have root privileges.
+Deprecated.
+In previous releases, this would allow a process with root privileges to
+truncate a file without zeroing space.
+For security reasons, this operation is no longer supported and will
+instead truncate the file in the same manner as
+.Xr truncate 2 .
.It Dv F_RDADVISE
Issue an advisory read async with no copy to user.
.It Dv F_RDAHEAD
A non-zero value in
.Fa arg
turns read ahead on.
-.It Dv F_READBOOTSTRAP
-Read bootstrap from disk.
-.It Dv F_WRITEBOOTSTRAP
-Write bootstrap on disk.
-The calling process must have root privileges.
.It Dv F_NOCACHE
Turns data caching off/on. A non-zero value in
.Fa arg
turns data caching on.
.It Dv F_LOG2PHYS
Get disk device information.
-Currently this only includes the
+Currently this only returns the
disk device address that corresponds
-to the current file offset. Note that if the
-file offset is not backed by physical blocks
-we can return -1 as the offset. This is subject
+to the current file offset. Note that the system
+may return -1 as the disk device address if the file is not
+backed by physical blocks. This is subject
to change.
.It Dv F_LOG2PHYS_EXT
Variant of F_LOG2PHYS that uses the passed in
file offset and length.
+.It Dv F_BARRIERFSYNC
+Does the same thing as
+.Xr fsync 2
+then issues a barrier command to the drive
+.Fa ( arg
+is ignored).
+The barrier applies to I/O that have been flushed with
+.Xr fsync 2
+on the same device before. These operations are guaranteed to
+be persisted before any other I/O that would follow the barrier,
+although no assumption should be made on what has been persisted
+or not when this call returns. After the barrier has been issued,
+operations on other FDs that have been fsync'd before can still be
+re-ordered by the device, but not after the barrier. This is
+typically useful to guarantee valid state on disk when ordering is a
+concern but durability is not. A barrier can be used to order two phases of operations on
+a set of file descriptors and ensure that no file can possibly get persisted
+with the effect of the second phase without the effect of the first one. To do so,
+execute operations of phase one, then
+.Xr fsync 2
+each FD and issue a single barrier. Finally execute operations of phase two.
+This is currently implemented on HFS and APFS. It requires hardware support,
+which Apple SSDs are guaranteed to provide.
.It Dv F_FULLFSYNC
Does the same thing as
.Xr fsync 2
the permanent storage device
.Fa ( arg
is ignored).
+As this drains the entire queue of the device and acts as a
+barrier, data that had been fsync'd on the same device before
+is guaranteed to be persisted when this call returns.
This is currently implemented on HFS, MS-DOS (FAT),
-and Universal Disk Format (UDF) file systems.
+Universal Disk Format (UDF) and APFS file systems.
The operation may take quite a while to complete.
Certain FireWire drives have also been known
to ignore the request to flush their buffered data.
.Bl -tag -width F_PEOFPOSMODEX -offset indent
.It Dv F_PEOFPOSMODE
Allocate from the physical end of file.
+In this case,
+.Fa fst_length
+indicates the number of newly allocated bytes desired.
.It Dv F_VOLPOSMODE
Allocate from the volume offset.
.El
and satisfying the lock or unlock request would result in the
number of locked regions in the system exceeding a system-imposed limit.
.\" ==========
+.It Bq Er ENOSPC
+The argument
+.Fa cmd
+is
+.Dv F_PREALLOCATE
+and either there is no space available on the volume containing
+.Fa fildes
+or
+.Fa fst_flags
+contains
+.Dv F_ALLOCATEALL
+and there is not enough space available on the volume containing
+.Fa fildes
+to satisfy the entire request.
+.Pp
+The argument
+.Fa cmd
+is
+.Dv F_PUNCHHOLE
+and there is not enough space available on the volume containing
+.Fa fildes
+to satisfy the request. As an example, a filesystem that supports
+cloned files may return this error if punching a hole requires the
+creation of a clone and there is not enough space available to do so.
+.\" ==========
.It Bq Er EOVERFLOW
A return value would overflow its representation.
For example,
of a byte in the requested segment
will not fit in an object of type off_t.
.\" ==========
+.It Bq Er EPERM
+The argument cmd is
+.Dv F_PUNCHHOLE
+and the calling process does not have file write permission.
+.\" ==========
.It Bq Er ESRCH
.Fa Cmd
is
projects / apple / xnu.git / blobdiff