Package org.lwjgl.system.linux

Class FCNTL

java.lang.Object
org.lwjgl.system.linux.FCNTL
public class FCNTL extends Object
Native bindings to <fcntl.h>.

  • Field Details

    • O_ACCMODE

      public static final int O_ACCMODE
      Enum values:
      • O_ACCMODE
      • O_RDONLY
      • O_WRONLY
      • O_RDWR
      • O_APPEND - The file is opened in append mode.

        Before each write(2), the file offset is positioned at the end of the file, as if with lseek(2). O_APPEND may lead to corrupted files on NFS file systems if more than one process appends data to a file at once. This is because NFS does not support appending to a file, so the client kernel has to simulate it, which can't be done without a race condition.

      • O_ASYNC - Enable signal-driven I/O: generate a signal (SIGIO by default, but this can be changed via fcntl(2)) when input or output becomes possible on this file descriptor.

        This feature is only available for terminals, pseudoterminals, sockets, and (since Linux 2.6) pipes and FIFOs. See fcntl(2) for further details.

      • O_CLOEXEC - Enable the close-on-exec flag for the new file descriptor.

        Specifying this flag permits a program to avoid additional fcntl(2) F_SETFD operations to set the FD_CLOEXEC flag. Additionally, use of this flag is essential in some multithreaded programs since using a separate fcntl(2) F_SETFD operation to set the FD_CLOEXEC flag does not suffice to avoid race conditions where one thread opens a file descriptor at the same time as another thread does a fork(2) plus execve(2).

      • O_CREAT - If the file does not exist it will be created.

        The owner (user ID) of the file is set to the effective user ID of the process. The group ownership (group ID) is set either to the effective group ID of the process or to the group ID of the parent directory (depending on file system type and mount options, and the mode of the parent directory, see the mount options bsdgroups and sysvgroups described in mount(8)).

      • O_DIRECT - Try to minimize cache effects of the I/O to and from this file.

        In general this will degrade performance, but it is useful in special situations, such as when applications do their own caching. File I/O is done directly to/from user-space buffers. The O_DIRECT flag on its own makes an effort to transfer data synchronously, but does not give the guarantees of the O_SYNC flag that data and necessary metadata are transferred. To guarantee synchronous I/O, O_SYNC must be used in addition to O_DIRECT.

        A semantically similar (but deprecated) interface for block devices is described in raw(8).

      • O_DIRECTORY - If pathname is not a directory, cause the open to fail.

        This flag is Linux-specific, and was added in kernel version 2.1.126, to avoid denial-of-service problems if opendir(3) is called on a FIFO or tape device, but should not be used outside of the implementation of opendir(3).

      • O_DSYNC
      • O_EXCL - Ensure that this call creates the file: if this flag is specified in conjunction with O_CREAT, and pathname already exists, then open() will fail.

        When these two flags are specified, symbolic links are not followed: if pathname is a symbolic link, then open() fails regardless of where the symbolic link points to.

        In general, the behavior of O_EXCL is undefined if it is used without O_CREAT. There is one exception: on Linux 2.6 and later, O_EXCL can be used without O_CREAT if pathname refers to a block device. If the block device is in use by the system (e.g., mounted), open() fails with the error EBUSY.

        On NFS, O_EXCL is only supported when using NFSv3 or later on kernel 2.6 or later. In NFS environments where O_EXCL support is not provided, programs that rely on it for performing locking tasks will contain a race condition. Portable programs that want to perform atomic file locking using a lockfile, and need to avoid reliance on NFS support for O_EXCL, can create a unique file on the same file system (e.g., incorporating hostname and PID), and use link(2) to make a link to the lockfile. If link(2) returns 0, the lock is successful. Otherwise, use stat(2) on the unique file to check if its link count has increased to 2, in which case the lock is also successful.

      • O_LARGEFILE - (LFS) Allow files whose sizes cannot be represented in an off_t (but can be represented in an off64_t) to be opened.

        The _LARGEFILE64_SOURCE macro must be defined (before including any header files) in order to obtain this definition. Setting the _FILE_OFFSET_BITS feature test macro to 64 (rather than using O_LARGEFILE) is the preferred method of accessing large files on 32-bit systems (see feature_test_macros(7)).

      • O_NOATIME - Do not update the file last access time (st_atime in the inode) when the file is read(2).

        This flag is intended for use by indexing or backup programs, where its use can significantly reduce the amount of disk activity. This flag may not be effective on all file systems. One example is NFS, where the server maintains the access time.

      • O_NOCTTY - If pathname refers to a terminal device --see tty(4)-- it will not become the process's controlling terminal even if the process does not have one.
      • O_NOFOLLOW - If pathname is a symbolic link, then the open fails.

        This is a FreeBSD extension, which was added to Linux in version 2.1.126. Symbolic links in earlier components of the pathname will still be followed.

      • O_NONBLOCK - When possible, the file is opened in nonblocking mode.

        Neither the open() nor any subsequent operations on the file descriptor which is returned will cause the calling process to wait. For the handling of FIFOs (named pipes), see also fifo(7). For a discussion of the effect of O_NONBLOCK in conjunction with mandatory file locks and with file leases, see fcntl(2).

      • O_NDELAY
      • O_PATH
      • O_SYNC - The file is opened for synchronous I/O.

        Any write(2)s on the resulting file descriptor will block the calling process until the data has been physically written to the underlying hardware.

      • O_TMPFILE
      • O_TRUNC - If the file already exists and is a regular file and the open mode allows writing (i.e., is O_RDWR or O_WRONLY) it will be truncated to length 0.

        If the file is a FIFO or terminal device file, the O_TRUNC flag is ignored. Otherwise the effect of O_TRUNC is unspecified.

      See Also:

    • O_RDONLY

      public static final int O_RDONLY
      Enum values:
      • O_ACCMODE
      • O_RDONLY
      • O_WRONLY
      • O_RDWR
      • O_APPEND - The file is opened in append mode.

        Before each write(2), the file offset is positioned at the end of the file, as if with lseek(2). O_APPEND may lead to corrupted files on NFS file systems if more than one process appends data to a file at once. This is because NFS does not support appending to a file, so the client kernel has to simulate it, which can't be done without a race condition.

      • O_ASYNC - Enable signal-driven I/O: generate a signal (SIGIO by default, but this can be changed via fcntl(2)) when input or output becomes possible on this file descriptor.

        This feature is only available for terminals, pseudoterminals, sockets, and (since Linux 2.6) pipes and FIFOs. See fcntl(2) for further details.

      • O_CLOEXEC - Enable the close-on-exec flag for the new file descriptor.

        Specifying this flag permits a program to avoid additional fcntl(2) F_SETFD operations to set the FD_CLOEXEC flag. Additionally, use of this flag is essential in some multithreaded programs since using a separate fcntl(2) F_SETFD operation to set the FD_CLOEXEC flag does not suffice to avoid race conditions where one thread opens a file descriptor at the same time as another thread does a fork(2) plus execve(2).

      • O_CREAT - If the file does not exist it will be created.

        The owner (user ID) of the file is set to the effective user ID of the process. The group ownership (group ID) is set either to the effective group ID of the process or to the group ID of the parent directory (depending on file system type and mount options, and the mode of the parent directory, see the mount options bsdgroups and sysvgroups described in mount(8)).

      • O_DIRECT - Try to minimize cache effects of the I/O to and from this file.

        In general this will degrade performance, but it is useful in special situations, such as when applications do their own caching. File I/O is done directly to/from user-space buffers. The O_DIRECT flag on its own makes an effort to transfer data synchronously, but does not give the guarantees of the O_SYNC flag that data and necessary metadata are transferred. To guarantee synchronous I/O, O_SYNC must be used in addition to O_DIRECT.

        A semantically similar (but deprecated) interface for block devices is described in raw(8).

      • O_DIRECTORY - If pathname is not a directory, cause the open to fail.

        This flag is Linux-specific, and was added in kernel version 2.1.126, to avoid denial-of-service problems if opendir(3) is called on a FIFO or tape device, but should not be used outside of the implementation of opendir(3).

      • O_DSYNC
      • O_EXCL - Ensure that this call creates the file: if this flag is specified in conjunction with O_CREAT, and pathname already exists, then open() will fail.

        When these two flags are specified, symbolic links are not followed: if pathname is a symbolic link, then open() fails regardless of where the symbolic link points to.

        In general, the behavior of O_EXCL is undefined if it is used without O_CREAT. There is one exception: on Linux 2.6 and later, O_EXCL can be used without O_CREAT if pathname refers to a block device. If the block device is in use by the system (e.g., mounted), open() fails with the error EBUSY.

        On NFS, O_EXCL is only supported when using NFSv3 or later on kernel 2.6 or later. In NFS environments where O_EXCL support is not provided, programs that rely on it for performing locking tasks will contain a race condition. Portable programs that want to perform atomic file locking using a lockfile, and need to avoid reliance on NFS support for O_EXCL, can create a unique file on the same file system (e.g., incorporating hostname and PID), and use link(2) to make a link to the lockfile. If link(2) returns 0, the lock is successful. Otherwise, use stat(2) on the unique file to check if its link count has increased to 2, in which case the lock is also successful.

      • O_LARGEFILE - (LFS) Allow files whose sizes cannot be represented in an off_t (but can be represented in an off64_t) to be opened.

        The _LARGEFILE64_SOURCE macro must be defined (before including any header files) in order to obtain this definition. Setting the _FILE_OFFSET_BITS feature test macro to 64 (rather than using O_LARGEFILE) is the preferred method of accessing large files on 32-bit systems (see feature_test_macros(7)).

      • O_NOATIME - Do not update the file last access time (st_atime in the inode) when the file is read(2).

        This flag is intended for use by indexing or backup programs, where its use can significantly reduce the amount of disk activity. This flag may not be effective on all file systems. One example is NFS, where the server maintains the access time.

      • O_NOCTTY - If pathname refers to a terminal device --see tty(4)-- it will not become the process's controlling terminal even if the process does not have one.
      • O_NOFOLLOW - If pathname is a symbolic link, then the open fails.

        This is a FreeBSD extension, which was added to Linux in version 2.1.126. Symbolic links in earlier components of the pathname will still be followed.

      • O_NONBLOCK - When possible, the file is opened in nonblocking mode.

        Neither the open() nor any subsequent operations on the file descriptor which is returned will cause the calling process to wait. For the handling of FIFOs (named pipes), see also fifo(7). For a discussion of the effect of O_NONBLOCK in conjunction with mandatory file locks and with file leases, see fcntl(2).

      • O_NDELAY
      • O_PATH
      • O_SYNC - The file is opened for synchronous I/O.

        Any write(2)s on the resulting file descriptor will block the calling process until the data has been physically written to the underlying hardware.

      • O_TMPFILE
      • O_TRUNC - If the file already exists and is a regular file and the open mode allows writing (i.e., is O_RDWR or O_WRONLY) it will be truncated to length 0.

        If the file is a FIFO or terminal device file, the O_TRUNC flag is ignored. Otherwise the effect of O_TRUNC is unspecified.

      See Also:

    • O_WRONLY

      public static final int O_WRONLY
      Enum values:
      • O_ACCMODE
      • O_RDONLY
      • O_WRONLY
      • O_RDWR
      • O_APPEND - The file is opened in append mode.

        Before each write(2), the file offset is positioned at the end of the file, as if with lseek(2). O_APPEND may lead to corrupted files on NFS file systems if more than one process appends data to a file at once. This is because NFS does not support appending to a file, so the client kernel has to simulate it, which can't be done without a race condition.

      • O_ASYNC - Enable signal-driven I/O: generate a signal (SIGIO by default, but this can be changed via fcntl(2)) when input or output becomes possible on this file descriptor.

        This feature is only available for terminals, pseudoterminals, sockets, and (since Linux 2.6) pipes and FIFOs. See fcntl(2) for further details.

      • O_CLOEXEC - Enable the close-on-exec flag for the new file descriptor.

        Specifying this flag permits a program to avoid additional fcntl(2) F_SETFD operations to set the FD_CLOEXEC flag. Additionally, use of this flag is essential in some multithreaded programs since using a separate fcntl(2) F_SETFD operation to set the FD_CLOEXEC flag does not suffice to avoid race conditions where one thread opens a file descriptor at the same time as another thread does a fork(2) plus execve(2).

      • O_CREAT - If the file does not exist it will be created.

        The owner (user ID) of the file is set to the effective user ID of the process. The group ownership (group ID) is set either to the effective group ID of the process or to the group ID of the parent directory (depending on file system type and mount options, and the mode of the parent directory, see the mount options bsdgroups and sysvgroups described in mount(8)).

      • O_DIRECT - Try to minimize cache effects of the I/O to and from this file.

        In general this will degrade performance, but it is useful in special situations, such as when applications do their own caching. File I/O is done directly to/from user-space buffers. The O_DIRECT flag on its own makes an effort to transfer data synchronously, but does not give the guarantees of the O_SYNC flag that data and necessary metadata are transferred. To guarantee synchronous I/O, O_SYNC must be used in addition to O_DIRECT.

        A semantically similar (but deprecated) interface for block devices is described in raw(8).

      • O_DIRECTORY - If pathname is not a directory, cause the open to fail.

        This flag is Linux-specific, and was added in kernel version 2.1.126, to avoid denial-of-service problems if opendir(3) is called on a FIFO or tape device, but should not be used outside of the implementation of opendir(3).

      • O_DSYNC
      • O_EXCL - Ensure that this call creates the file: if this flag is specified in conjunction with O_CREAT, and pathname already exists, then open() will fail.

        When these two flags are specified, symbolic links are not followed: if pathname is a symbolic link, then open() fails regardless of where the symbolic link points to.

        In general, the behavior of O_EXCL is undefined if it is used without O_CREAT. There is one exception: on Linux 2.6 and later, O_EXCL can be used without O_CREAT if pathname refers to a block device. If the block device is in use by the system (e.g., mounted), open() fails with the error EBUSY.

        On NFS, O_EXCL is only supported when using NFSv3 or later on kernel 2.6 or later. In NFS environments where O_EXCL support is not provided, programs that rely on it for performing locking tasks will contain a race condition. Portable programs that want to perform atomic file locking using a lockfile, and need to avoid reliance on NFS support for O_EXCL, can create a unique file on the same file system (e.g., incorporating hostname and PID), and use link(2) to make a link to the lockfile. If link(2) returns 0, the lock is successful. Otherwise, use stat(2) on the unique file to check if its link count has increased to 2, in which case the lock is also successful.

      • O_LARGEFILE - (LFS) Allow files whose sizes cannot be represented in an off_t (but can be represented in an off64_t) to be opened.

        The _LARGEFILE64_SOURCE macro must be defined (before including any header files) in order to obtain this definition. Setting the _FILE_OFFSET_BITS feature test macro to 64 (rather than using O_LARGEFILE) is the preferred method of accessing large files on 32-bit systems (see feature_test_macros(7)).

      • O_NOATIME - Do not update the file last access time (st_atime in the inode) when the file is read(2).

        This flag is intended for use by indexing or backup programs, where its use can significantly reduce the amount of disk activity. This flag may not be effective on all file systems. One example is NFS, where the server maintains the access time.

      • O_NOCTTY - If pathname refers to a terminal device --see tty(4)-- it will not become the process's controlling terminal even if the process does not have one.
      • O_NOFOLLOW - If pathname is a symbolic link, then the open fails.

        This is a FreeBSD extension, which was added to Linux in version 2.1.126. Symbolic links in earlier components of the pathname will still be followed.

      • O_NONBLOCK - When possible, the file is opened in nonblocking mode.

        Neither the open() nor any subsequent operations on the file descriptor which is returned will cause the calling process to wait. For the handling of FIFOs (named pipes), see also fifo(7). For a discussion of the effect of O_NONBLOCK in conjunction with mandatory file locks and with file leases, see fcntl(2).

      • O_NDELAY
      • O_PATH
      • O_SYNC - The file is opened for synchronous I/O.

        Any write(2)s on the resulting file descriptor will block the calling process until the data has been physically written to the underlying hardware.

      • O_TMPFILE
      • O_TRUNC - If the file already exists and is a regular file and the open mode allows writing (i.e., is O_RDWR or O_WRONLY) it will be truncated to length 0.

        If the file is a FIFO or terminal device file, the O_TRUNC flag is ignored. Otherwise the effect of O_TRUNC is unspecified.

      See Also:

    • O_RDWR

      public static final int O_RDWR
      Enum values:
      • O_ACCMODE
      • O_RDONLY
      • O_WRONLY
      • O_RDWR
      • O_APPEND - The file is opened in append mode.

        Before each write(2), the file offset is positioned at the end of the file, as if with lseek(2). O_APPEND may lead to corrupted files on NFS file systems if more than one process appends data to a file at once. This is because NFS does not support appending to a file, so the client kernel has to simulate it, which can't be done without a race condition.

      • O_ASYNC - Enable signal-driven I/O: generate a signal (SIGIO by default, but this can be changed via fcntl(2)) when input or output becomes possible on this file descriptor.

        This feature is only available for terminals, pseudoterminals, sockets, and (since Linux 2.6) pipes and FIFOs. See fcntl(2) for further details.

      • O_CLOEXEC - Enable the close-on-exec flag for the new file descriptor.

        Specifying this flag permits a program to avoid additional fcntl(2) F_SETFD operations to set the FD_CLOEXEC flag. Additionally, use of this flag is essential in some multithreaded programs since using a separate fcntl(2) F_SETFD operation to set the FD_CLOEXEC flag does not suffice to avoid race conditions where one thread opens a file descriptor at the same time as another thread does a fork(2) plus execve(2).

      • O_CREAT - If the file does not exist it will be created.

        The owner (user ID) of the file is set to the effective user ID of the process. The group ownership (group ID) is set either to the effective group ID of the process or to the group ID of the parent directory (depending on file system type and mount options, and the mode of the parent directory, see the mount options bsdgroups and sysvgroups described in mount(8)).

      • O_DIRECT - Try to minimize cache effects of the I/O to and from this file.

        In general this will degrade performance, but it is useful in special situations, such as when applications do their own caching. File I/O is done directly to/from user-space buffers. The O_DIRECT flag on its own makes an effort to transfer data synchronously, but does not give the guarantees of the O_SYNC flag that data and necessary metadata are transferred. To guarantee synchronous I/O, O_SYNC must be used in addition to O_DIRECT.

        A semantically similar (but deprecated) interface for block devices is described in raw(8).

      • O_DIRECTORY - If pathname is not a directory, cause the open to fail.

        This flag is Linux-specific, and was added in kernel version 2.1.126, to avoid denial-of-service problems if opendir(3) is called on a FIFO or tape device, but should not be used outside of the implementation of opendir(3).

      • O_DSYNC
      • O_EXCL - Ensure that this call creates the file: if this flag is specified in conjunction with O_CREAT, and pathname already exists, then open() will fail.

        When these two flags are specified, symbolic links are not followed: if pathname is a symbolic link, then open() fails regardless of where the symbolic link points to.

        In general, the behavior of O_EXCL is undefined if it is used without O_CREAT. There is one exception: on Linux 2.6 and later, O_EXCL can be used without O_CREAT if pathname refers to a block device. If the block device is in use by the system (e.g., mounted), open() fails with the error EBUSY.

        On NFS, O_EXCL is only supported when using NFSv3 or later on kernel 2.6 or later. In NFS environments where O_EXCL support is not provided, programs that rely on it for performing locking tasks will contain a race condition. Portable programs that want to perform atomic file locking using a lockfile, and need to avoid reliance on NFS support for O_EXCL, can create a unique file on the same file system (e.g., incorporating hostname and PID), and use link(2) to make a link to the lockfile. If link(2) returns 0, the lock is successful. Otherwise, use stat(2) on the unique file to check if its link count has increased to 2, in which case the lock is also successful.

      • O_LARGEFILE - (LFS) Allow files whose sizes cannot be represented in an off_t (but can be represented in an off64_t) to be opened.

        The _LARGEFILE64_SOURCE macro must be defined (before including any header files) in order to obtain this definition. Setting the _FILE_OFFSET_BITS feature test macro to 64 (rather than using O_LARGEFILE) is the preferred method of accessing large files on 32-bit systems (see feature_test_macros(7)).

      • O_NOATIME - Do not update the file last access time (st_atime in the inode) when the file is read(2).

        This flag is intended for use by indexing or backup programs, where its use can significantly reduce the amount of disk activity. This flag may not be effective on all file systems. One example is NFS, where the server maintains the access time.

      • O_NOCTTY - If pathname refers to a terminal device --see tty(4)-- it will not become the process's controlling terminal even if the process does not have one.
      • O_NOFOLLOW - If pathname is a symbolic link, then the open fails.

        This is a FreeBSD extension, which was added to Linux in version 2.1.126. Symbolic links in earlier components of the pathname will still be followed.

      • O_NONBLOCK - When possible, the file is opened in nonblocking mode.

        Neither the open() nor any subsequent operations on the file descriptor which is returned will cause the calling process to wait. For the handling of FIFOs (named pipes), see also fifo(7). For a discussion of the effect of O_NONBLOCK in conjunction with mandatory file locks and with file leases, see fcntl(2).

      • O_NDELAY
      • O_PATH
      • O_SYNC - The file is opened for synchronous I/O.

        Any write(2)s on the resulting file descriptor will block the calling process until the data has been physically written to the underlying hardware.

      • O_TMPFILE
      • O_TRUNC - If the file already exists and is a regular file and the open mode allows writing (i.e., is O_RDWR or O_WRONLY) it will be truncated to length 0.

        If the file is a FIFO or terminal device file, the O_TRUNC flag is ignored. Otherwise the effect of O_TRUNC is unspecified.

      See Also:

    • O_APPEND

      public static final int O_APPEND
      Enum values:
      • O_ACCMODE
      • O_RDONLY
      • O_WRONLY
      • O_RDWR
      • O_APPEND - The file is opened in append mode.

        Before each write(2), the file offset is positioned at the end of the file, as if with lseek(2). O_APPEND may lead to corrupted files on NFS file systems if more than one process appends data to a file at once. This is because NFS does not support appending to a file, so the client kernel has to simulate it, which can't be done without a race condition.

      • O_ASYNC - Enable signal-driven I/O: generate a signal (SIGIO by default, but this can be changed via fcntl(2)) when input or output becomes possible on this file descriptor.

        This feature is only available for terminals, pseudoterminals, sockets, and (since Linux 2.6) pipes and FIFOs. See fcntl(2) for further details.

      • O_CLOEXEC - Enable the close-on-exec flag for the new file descriptor.

        Specifying this flag permits a program to avoid additional fcntl(2) F_SETFD operations to set the FD_CLOEXEC flag. Additionally, use of this flag is essential in some multithreaded programs since using a separate fcntl(2) F_SETFD operation to set the FD_CLOEXEC flag does not suffice to avoid race conditions where one thread opens a file descriptor at the same time as another thread does a fork(2) plus execve(2).

      • O_CREAT - If the file does not exist it will be created.

        The owner (user ID) of the file is set to the effective user ID of the process. The group ownership (group ID) is set either to the effective group ID of the process or to the group ID of the parent directory (depending on file system type and mount options, and the mode of the parent directory, see the mount options bsdgroups and sysvgroups described in mount(8)).

      • O_DIRECT - Try to minimize cache effects of the I/O to and from this file.

        In general this will degrade performance, but it is useful in special situations, such as when applications do their own caching. File I/O is done directly to/from user-space buffers. The O_DIRECT flag on its own makes an effort to transfer data synchronously, but does not give the guarantees of the O_SYNC flag that data and necessary metadata are transferred. To guarantee synchronous I/O, O_SYNC must be used in addition to O_DIRECT.

        A semantically similar (but deprecated) interface for block devices is described in raw(8).

      • O_DIRECTORY - If pathname is not a directory, cause the open to fail.

        This flag is Linux-specific, and was added in kernel version 2.1.126, to avoid denial-of-service problems if opendir(3) is called on a FIFO or tape device, but should not be used outside of the implementation of opendir(3).

      • O_DSYNC
      • O_EXCL - Ensure that this call creates the file: if this flag is specified in conjunction with O_CREAT, and pathname already exists, then open() will fail.

        When these two flags are specified, symbolic links are not followed: if pathname is a symbolic link, then open() fails regardless of where the symbolic link points to.

        In general, the behavior of O_EXCL is undefined if it is used without O_CREAT. There is one exception: on Linux 2.6 and later, O_EXCL can be used without O_CREAT if pathname refers to a block device. If the block device is in use by the system (e.g., mounted), open() fails with the error EBUSY.

        On NFS, O_EXCL is only supported when using NFSv3 or later on kernel 2.6 or later. In NFS environments where O_EXCL support is not provided, programs that rely on it for performing locking tasks will contain a race condition. Portable programs that want to perform atomic file locking using a lockfile, and need to avoid reliance on NFS support for O_EXCL, can create a unique file on the same file system (e.g., incorporating hostname and PID), and use link(2) to make a link to the lockfile. If link(2) returns 0, the lock is successful. Otherwise, use stat(2) on the unique file to check if its link count has increased to 2, in which case the lock is also successful.

      • O_LARGEFILE - (LFS) Allow files whose sizes cannot be represented in an off_t (but can be represented in an off64_t) to be opened.

        The _LARGEFILE64_SOURCE macro must be defined (before including any header files) in order to obtain this definition. Setting the _FILE_OFFSET_BITS feature test macro to 64 (rather than using O_LARGEFILE) is the preferred method of accessing large files on 32-bit systems (see feature_test_macros(7)).

      • O_NOATIME - Do not update the file last access time (st_atime in the inode) when the file is read(2).

        This flag is intended for use by indexing or backup programs, where its use can significantly reduce the amount of disk activity. This flag may not be effective on all file systems. One example is NFS, where the server maintains the access time.

      • O_NOCTTY - If pathname refers to a terminal device --see tty(4)-- it will not become the process's controlling terminal even if the process does not have one.
      • O_NOFOLLOW - If pathname is a symbolic link, then the open fails.

        This is a FreeBSD extension, which was added to Linux in version 2.1.126. Symbolic links in earlier components of the pathname will still be followed.

      • O_NONBLOCK - When possible, the file is opened in nonblocking mode.

        Neither the open() nor any subsequent operations on the file descriptor which is returned will cause the calling process to wait. For the handling of FIFOs (named pipes), see also fifo(7). For a discussion of the effect of O_NONBLOCK in conjunction with mandatory file locks and with file leases, see fcntl(2).

      • O_NDELAY
      • O_PATH
      • O_SYNC - The file is opened for synchronous I/O.

        Any write(2)s on the resulting file descriptor will block the calling process until the data has been physically written to the underlying hardware.

      • O_TMPFILE
      • O_TRUNC - If the file already exists and is a regular file and the open mode allows writing (i.e., is O_RDWR or O_WRONLY) it will be truncated to length 0.

        If the file is a FIFO or terminal device file, the O_TRUNC flag is ignored. Otherwise the effect of O_TRUNC is unspecified.

      See Also:

    • O_ASYNC

      public static final int O_ASYNC
      Enum values:
      • O_ACCMODE
      • O_RDONLY
      • O_WRONLY
      • O_RDWR
      • O_APPEND - The file is opened in append mode.

        Before each write(2), the file offset is positioned at the end of the file, as if with lseek(2). O_APPEND may lead to corrupted files on NFS file systems if more than one process appends data to a file at once. This is because NFS does not support appending to a file, so the client kernel has to simulate it, which can't be done without a race condition.

      • O_ASYNC - Enable signal-driven I/O: generate a signal (SIGIO by default, but this can be changed via fcntl(2)) when input or output becomes possible on this file descriptor.

        This feature is only available for terminals, pseudoterminals, sockets, and (since Linux 2.6) pipes and FIFOs. See fcntl(2) for further details.

      • O_CLOEXEC - Enable the close-on-exec flag for the new file descriptor.

        Specifying this flag permits a program to avoid additional fcntl(2) F_SETFD operations to set the FD_CLOEXEC flag. Additionally, use of this flag is essential in some multithreaded programs since using a separate fcntl(2) F_SETFD operation to set the FD_CLOEXEC flag does not suffice to avoid race conditions where one thread opens a file descriptor at the same time as another thread does a fork(2) plus execve(2).

      • O_CREAT - If the file does not exist it will be created.

        The owner (user ID) of the file is set to the effective user ID of the process. The group ownership (group ID) is set either to the effective group ID of the process or to the group ID of the parent directory (depending on file system type and mount options, and the mode of the parent directory, see the mount options bsdgroups and sysvgroups described in mount(8)).

      • O_DIRECT - Try to minimize cache effects of the I/O to and from this file.

        In general this will degrade performance, but it is useful in special situations, such as when applications do their own caching. File I/O is done directly to/from user-space buffers. The O_DIRECT flag on its own makes an effort to transfer data synchronously, but does not give the guarantees of the O_SYNC flag that data and necessary metadata are transferred. To guarantee synchronous I/O, O_SYNC must be used in addition to O_DIRECT.

        A semantically similar (but deprecated) interface for block devices is described in raw(8).

      • O_DIRECTORY - If pathname is not a directory, cause the open to fail.

        This flag is Linux-specific, and was added in kernel version 2.1.126, to avoid denial-of-service problems if opendir(3) is called on a FIFO or tape device, but should not be used outside of the implementation of opendir(3).

      • O_DSYNC
      • O_EXCL - Ensure that this call creates the file: if this flag is specified in conjunction with O_CREAT, and pathname already exists, then open() will fail.

        When these two flags are specified, symbolic links are not followed: if pathname is a symbolic link, then open() fails regardless of where the symbolic link points to.

        In general, the behavior of O_EXCL is undefined if it is used without O_CREAT. There is one exception: on Linux 2.6 and later, O_EXCL can be used without O_CREAT if pathname refers to a block device. If the block device is in use by the system (e.g., mounted), open() fails with the error EBUSY.

        On NFS, O_EXCL is only supported when using NFSv3 or later on kernel 2.6 or later. In NFS environments where O_EXCL support is not provided, programs that rely on it for performing locking tasks will contain a race condition. Portable programs that want to perform atomic file locking using a lockfile, and need to avoid reliance on NFS support for O_EXCL, can create a unique file on the same file system (e.g., incorporating hostname and PID), and use link(2) to make a link to the lockfile. If link(2) returns 0, the lock is successful. Otherwise, use stat(2) on the unique file to check if its link count has increased to 2, in which case the lock is also successful.

      • O_LARGEFILE - (LFS) Allow files whose sizes cannot be represented in an off_t (but can be represented in an off64_t) to be opened.

        The _LARGEFILE64_SOURCE macro must be defined (before including any header files) in order to obtain this definition. Setting the _FILE_OFFSET_BITS feature test macro to 64 (rather than using O_LARGEFILE) is the preferred method of accessing large files on 32-bit systems (see feature_test_macros(7)).

      • O_NOATIME - Do not update the file last access time (st_atime in the inode) when the file is read(2).

        This flag is intended for use by indexing or backup programs, where its use can significantly reduce the amount of disk activity. This flag may not be effective on all file systems. One example is NFS, where the server maintains the access time.

      • O_NOCTTY - If pathname refers to a terminal device --see tty(4)-- it will not become the process's controlling terminal even if the process does not have one.
      • O_NOFOLLOW - If pathname is a symbolic link, then the open fails.

        This is a FreeBSD extension, which was added to Linux in version 2.1.126. Symbolic links in earlier components of the pathname will still be followed.

      • O_NONBLOCK - When possible, the file is opened in nonblocking mode.

        Neither the open() nor any subsequent operations on the file descriptor which is returned will cause the calling process to wait. For the handling of FIFOs (named pipes), see also fifo(7). For a discussion of the effect of O_NONBLOCK in conjunction with mandatory file locks and with file leases, see fcntl(2).

      • O_NDELAY
      • O_PATH
      • O_SYNC - The file is opened for synchronous I/O.

        Any write(2)s on the resulting file descriptor will block the calling process until the data has been physically written to the underlying hardware.

      • O_TMPFILE
      • O_TRUNC - If the file already exists and is a regular file and the open mode allows writing (i.e., is O_RDWR or O_WRONLY) it will be truncated to length 0.

        If the file is a FIFO or terminal device file, the O_TRUNC flag is ignored. Otherwise the effect of O_TRUNC is unspecified.

      See Also:

    • O_CLOEXEC

      public static final int O_CLOEXEC
      Enum values:
      • O_ACCMODE
      • O_RDONLY
      • O_WRONLY
      • O_RDWR
      • O_APPEND - The file is opened in append mode.

        Before each write(2), the file offset is positioned at the end of the file, as if with lseek(2). O_APPEND may lead to corrupted files on NFS file systems if more than one process appends data to a file at once. This is because NFS does not support appending to a file, so the client kernel has to simulate it, which can't be done without a race condition.

      • O_ASYNC - Enable signal-driven I/O: generate a signal (SIGIO by default, but this can be changed via fcntl(2)) when input or output becomes possible on this file descriptor.

        This feature is only available for terminals, pseudoterminals, sockets, and (since Linux 2.6) pipes and FIFOs. See fcntl(2) for further details.

      • O_CLOEXEC - Enable the close-on-exec flag for the new file descriptor.

        Specifying this flag permits a program to avoid additional fcntl(2) F_SETFD operations to set the FD_CLOEXEC flag. Additionally, use of this flag is essential in some multithreaded programs since using a separate fcntl(2) F_SETFD operation to set the FD_CLOEXEC flag does not suffice to avoid race conditions where one thread opens a file descriptor at the same time as another thread does a fork(2) plus execve(2).

      • O_CREAT - If the file does not exist it will be created.

        The owner (user ID) of the file is set to the effective user ID of the process. The group ownership (group ID) is set either to the effective group ID of the process or to the group ID of the parent directory (depending on file system type and mount options, and the mode of the parent directory, see the mount options bsdgroups and sysvgroups described in mount(8)).

      • O_DIRECT - Try to minimize cache effects of the I/O to and from this file.

        In general this will degrade performance, but it is useful in special situations, such as when applications do their own caching. File I/O is done directly to/from user-space buffers. The O_DIRECT flag on its own makes an effort to transfer data synchronously, but does not give the guarantees of the O_SYNC flag that data and necessary metadata are transferred. To guarantee synchronous I/O, O_SYNC must be used in addition to O_DIRECT.

        A semantically similar (but deprecated) interface for block devices is described in raw(8).

      • O_DIRECTORY - If pathname is not a directory, cause the open to fail.

        This flag is Linux-specific, and was added in kernel version 2.1.126, to avoid denial-of-service problems if opendir(3) is called on a FIFO or tape device, but should not be used outside of the implementation of opendir(3).

      • O_DSYNC
      • O_EXCL - Ensure that this call creates the file: if this flag is specified in conjunction with O_CREAT, and pathname already exists, then open() will fail.

        When these two flags are specified, symbolic links are not followed: if pathname is a symbolic link, then open() fails regardless of where the symbolic link points to.

        In general, the behavior of O_EXCL is undefined if it is used without O_CREAT. There is one exception: on Linux 2.6 and later, O_EXCL can be used without O_CREAT if pathname refers to a block device. If the block device is in use by the system (e.g., mounted), open() fails with the error EBUSY.

        On NFS, O_EXCL is only supported when using NFSv3 or later on kernel 2.6 or later. In NFS environments where O_EXCL support is not provided, programs that rely on it for performing locking tasks will contain a race condition. Portable programs that want to perform atomic file locking using a lockfile, and need to avoid reliance on NFS support for O_EXCL, can create a unique file on the same file system (e.g., incorporating hostname and PID), and use link(2) to make a link to the lockfile. If link(2) returns 0, the lock is successful. Otherwise, use stat(2) on the unique file to check if its link count has increased to 2, in which case the lock is also successful.

      • O_LARGEFILE - (LFS) Allow files whose sizes cannot be represented in an off_t (but can be represented in an off64_t) to be opened.

        The _LARGEFILE64_SOURCE macro must be defined (before including any header files) in order to obtain this definition. Setting the _FILE_OFFSET_BITS feature test macro to 64 (rather than using O_LARGEFILE) is the preferred method of accessing large files on 32-bit systems (see feature_test_macros(7)).

      • O_NOATIME - Do not update the file last access time (st_atime in the inode) when the file is read(2).

        This flag is intended for use by indexing or backup programs, where its use can significantly reduce the amount of disk activity. This flag may not be effective on all file systems. One example is NFS, where the server maintains the access time.

      • O_NOCTTY - If pathname refers to a terminal device --see tty(4)-- it will not become the process's controlling terminal even if the process does not have one.
      • O_NOFOLLOW - If pathname is a symbolic link, then the open fails.

        This is a FreeBSD extension, which was added to Linux in version 2.1.126. Symbolic links in earlier components of the pathname will still be followed.

      • O_NONBLOCK - When possible, the file is opened in nonblocking mode.

        Neither the open() nor any subsequent operations on the file descriptor which is returned will cause the calling process to wait. For the handling of FIFOs (named pipes), see also fifo(7). For a discussion of the effect of O_NONBLOCK in conjunction with mandatory file locks and with file leases, see fcntl(2).

      • O_NDELAY
      • O_PATH
      • O_SYNC - The file is opened for synchronous I/O.

        Any write(2)s on the resulting file descriptor will block the calling process until the data has been physically written to the underlying hardware.

      • O_TMPFILE
      • O_TRUNC - If the file already exists and is a regular file and the open mode allows writing (i.e., is O_RDWR or O_WRONLY) it will be truncated to length 0.

        If the file is a FIFO or terminal device file, the O_TRUNC flag is ignored. Otherwise the effect of O_TRUNC is unspecified.

      See Also:

    • O_CREAT

      public static final int O_CREAT
      Enum values:
      • O_ACCMODE
      • O_RDONLY
      • O_WRONLY
      • O_RDWR
      • O_APPEND - The file is opened in append mode.

        Before each write(2), the file offset is positioned at the end of the file, as if with lseek(2). O_APPEND may lead to corrupted files on NFS file systems if more than one process appends data to a file at once. This is because NFS does not support appending to a file, so the client kernel has to simulate it, which can't be done without a race condition.

      • O_ASYNC - Enable signal-driven I/O: generate a signal (SIGIO by default, but this can be changed via fcntl(2)) when input or output becomes possible on this file descriptor.

        This feature is only available for terminals, pseudoterminals, sockets, and (since Linux 2.6) pipes and FIFOs. See fcntl(2) for further details.

      • O_CLOEXEC - Enable the close-on-exec flag for the new file descriptor.

        Specifying this flag permits a program to avoid additional fcntl(2) F_SETFD operations to set the FD_CLOEXEC flag. Additionally, use of this flag is essential in some multithreaded programs since using a separate fcntl(2) F_SETFD operation to set the FD_CLOEXEC flag does not suffice to avoid race conditions where one thread opens a file descriptor at the same time as another thread does a fork(2) plus execve(2).

      • O_CREAT - If the file does not exist it will be created.

        The owner (user ID) of the file is set to the effective user ID of the process. The group ownership (group ID) is set either to the effective group ID of the process or to the group ID of the parent directory (depending on file system type and mount options, and the mode of the parent directory, see the mount options bsdgroups and sysvgroups described in mount(8)).

      • O_DIRECT - Try to minimize cache effects of the I/O to and from this file.

        In general this will degrade performance, but it is useful in special situations, such as when applications do their own caching. File I/O is done directly to/from user-space buffers. The O_DIRECT flag on its own makes an effort to transfer data synchronously, but does not give the guarantees of the O_SYNC flag that data and necessary metadata are transferred. To guarantee synchronous I/O, O_SYNC must be used in addition to O_DIRECT.

        A semantically similar (but deprecated) interface for block devices is described in raw(8).

      • O_DIRECTORY - If pathname is not a directory, cause the open to fail.

        This flag is Linux-specific, and was added in kernel version 2.1.126, to avoid denial-of-service problems if opendir(3) is called on a FIFO or tape device, but should not be used outside of the implementation of opendir(3).

      • O_DSYNC
      • O_EXCL - Ensure that this call creates the file: if this flag is specified in conjunction with O_CREAT, and pathname already exists, then open() will fail.

        When these two flags are specified, symbolic links are not followed: if pathname is a symbolic link, then open() fails regardless of where the symbolic link points to.

        In general, the behavior of O_EXCL is undefined if it is used without O_CREAT. There is one exception: on Linux 2.6 and later, O_EXCL can be used without O_CREAT if pathname refers to a block device. If the block device is in use by the system (e.g., mounted), open() fails with the error EBUSY.

        On NFS, O_EXCL is only supported when using NFSv3 or later on kernel 2.6 or later. In NFS environments where O_EXCL support is not provided, programs that rely on it for performing locking tasks will contain a race condition. Portable programs that want to perform atomic file locking using a lockfile, and need to avoid reliance on NFS support for O_EXCL, can create a unique file on the same file system (e.g., incorporating hostname and PID), and use link(2) to make a link to the lockfile. If link(2) returns 0, the lock is successful. Otherwise, use stat(2) on the unique file to check if its link count has increased to 2, in which case the lock is also successful.

      • O_LARGEFILE - (LFS) Allow files whose sizes cannot be represented in an off_t (but can be represented in an off64_t) to be opened.

        The _LARGEFILE64_SOURCE macro must be defined (before including any header files) in order to obtain this definition. Setting the _FILE_OFFSET_BITS feature test macro to 64 (rather than using O_LARGEFILE) is the preferred method of accessing large files on 32-bit systems (see feature_test_macros(7)).

      • O_NOATIME - Do not update the file last access time (st_atime in the inode) when the file is read(2).

        This flag is intended for use by indexing or backup programs, where its use can significantly reduce the amount of disk activity. This flag may not be effective on all file systems. One example is NFS, where the server maintains the access time.

      • O_NOCTTY - If pathname refers to a terminal device --see tty(4)-- it will not become the process's controlling terminal even if the process does not have one.
      • O_NOFOLLOW - If pathname is a symbolic link, then the open fails.

        This is a FreeBSD extension, which was added to Linux in version 2.1.126. Symbolic links in earlier components of the pathname will still be followed.

      • O_NONBLOCK - When possible, the file is opened in nonblocking mode.

        Neither the open() nor any subsequent operations on the file descriptor which is returned will cause the calling process to wait. For the handling of FIFOs (named pipes), see also fifo(7). For a discussion of the effect of O_NONBLOCK in conjunction with mandatory file locks and with file leases, see fcntl(2).

      • O_NDELAY
      • O_PATH
      • O_SYNC - The file is opened for synchronous I/O.

        Any write(2)s on the resulting file descriptor will block the calling process until the data has been physically written to the underlying hardware.

      • O_TMPFILE
      • O_TRUNC - If the file already exists and is a regular file and the open mode allows writing (i.e., is O_RDWR or O_WRONLY) it will be truncated to length 0.

        If the file is a FIFO or terminal device file, the O_TRUNC flag is ignored. Otherwise the effect of O_TRUNC is unspecified.

      See Also:

    • O_DIRECT

      public static final int O_DIRECT
      Enum values:
      • O_ACCMODE
      • O_RDONLY
      • O_WRONLY
      • O_RDWR
      • O_APPEND - The file is opened in append mode.

        Before each write(2), the file offset is positioned at the end of the file, as if with lseek(2). O_APPEND may lead to corrupted files on NFS file systems if more than one process appends data to a file at once. This is because NFS does not support appending to a file, so the client kernel has to simulate it, which can't be done without a race condition.

      • O_ASYNC - Enable signal-driven I/O: generate a signal (SIGIO by default, but this can be changed via fcntl(2)) when input or output becomes possible on this file descriptor.

        This feature is only available for terminals, pseudoterminals, sockets, and (since Linux 2.6) pipes and FIFOs. See fcntl(2) for further details.

      • O_CLOEXEC - Enable the close-on-exec flag for the new file descriptor.

        Specifying this flag permits a program to avoid additional fcntl(2) F_SETFD operations to set the FD_CLOEXEC flag. Additionally, use of this flag is essential in some multithreaded programs since using a separate fcntl(2) F_SETFD operation to set the FD_CLOEXEC flag does not suffice to avoid race conditions where one thread opens a file descriptor at the same time as another thread does a fork(2) plus execve(2).

      • O_CREAT - If the file does not exist it will be created.

        The owner (user ID) of the file is set to the effective user ID of the process. The group ownership (group ID) is set either to the effective group ID of the process or to the group ID of the parent directory (depending on file system type and mount options, and the mode of the parent directory, see the mount options bsdgroups and sysvgroups described in mount(8)).

      • O_DIRECT - Try to minimize cache effects of the I/O to and from this file.

        In general this will degrade performance, but it is useful in special situations, such as when applications do their own caching. File I/O is done directly to/from user-space buffers. The O_DIRECT flag on its own makes an effort to transfer data synchronously, but does not give the guarantees of the O_SYNC flag that data and necessary metadata are transferred. To guarantee synchronous I/O, O_SYNC must be used in addition to O_DIRECT.

        A semantically similar (but deprecated) interface for block devices is described in raw(8).

      • O_DIRECTORY - If pathname is not a directory, cause the open to fail.

        This flag is Linux-specific, and was added in kernel version 2.1.126, to avoid denial-of-service problems if opendir(3) is called on a FIFO or tape device, but should not be used outside of the implementation of opendir(3).

      • O_DSYNC
      • O_EXCL - Ensure that this call creates the file: if this flag is specified in conjunction with O_CREAT, and pathname already exists, then open() will fail.

        When these two flags are specified, symbolic links are not followed: if pathname is a symbolic link, then open() fails regardless of where the symbolic link points to.

        In general, the behavior of O_EXCL is undefined if it is used without O_CREAT. There is one exception: on Linux 2.6 and later, O_EXCL can be used without O_CREAT if pathname refers to a block device. If the block device is in use by the system (e.g., mounted), open() fails with the error EBUSY.

        On NFS, O_EXCL is only supported when using NFSv3 or later on kernel 2.6 or later. In NFS environments where O_EXCL support is not provided, programs that rely on it for performing locking tasks will contain a race condition. Portable programs that want to perform atomic file locking using a lockfile, and need to avoid reliance on NFS support for O_EXCL, can create a unique file on the same file system (e.g., incorporating hostname and PID), and use link(2) to make a link to the lockfile. If link(2) returns 0, the lock is successful. Otherwise, use stat(2) on the unique file to check if its link count has increased to 2, in which case the lock is also successful.

      • O_LARGEFILE - (LFS) Allow files whose sizes cannot be represented in an off_t (but can be represented in an off64_t) to be opened.

        The _LARGEFILE64_SOURCE macro must be defined (before including any header files) in order to obtain this definition. Setting the _FILE_OFFSET_BITS feature test macro to 64 (rather than using O_LARGEFILE) is the preferred method of accessing large files on 32-bit systems (see feature_test_macros(7)).

      • O_NOATIME - Do not update the file last access time (st_atime in the inode) when the file is read(2).

        This flag is intended for use by indexing or backup programs, where its use can significantly reduce the amount of disk activity. This flag may not be effective on all file systems. One example is NFS, where the server maintains the access time.

      • O_NOCTTY - If pathname refers to a terminal device --see tty(4)-- it will not become the process's controlling terminal even if the process does not have one.
      • O_NOFOLLOW - If pathname is a symbolic link, then the open fails.

        This is a FreeBSD extension, which was added to Linux in version 2.1.126. Symbolic links in earlier components of the pathname will still be followed.

      • O_NONBLOCK - When possible, the file is opened in nonblocking mode.

        Neither the open() nor any subsequent operations on the file descriptor which is returned will cause the calling process to wait. For the handling of FIFOs (named pipes), see also fifo(7). For a discussion of the effect of O_NONBLOCK in conjunction with mandatory file locks and with file leases, see fcntl(2).

      • O_NDELAY
      • O_PATH
      • O_SYNC - The file is opened for synchronous I/O.

        Any write(2)s on the resulting file descriptor will block the calling process until the data has been physically written to the underlying hardware.

      • O_TMPFILE
      • O_TRUNC - If the file already exists and is a regular file and the open mode allows writing (i.e., is O_RDWR or O_WRONLY) it will be truncated to length 0.

        If the file is a FIFO or terminal device file, the O_TRUNC flag is ignored. Otherwise the effect of O_TRUNC is unspecified.

      See Also:

    • O_DIRECTORY

      public static final int O_DIRECTORY
      Enum values:
      • O_ACCMODE
      • O_RDONLY
      • O_WRONLY
      • O_RDWR
      • O_APPEND - The file is opened in append mode.

        Before each write(2), the file offset is positioned at the end of the file, as if with lseek(2). O_APPEND may lead to corrupted files on NFS file systems if more than one process appends data to a file at once. This is because NFS does not support appending to a file, so the client kernel has to simulate it, which can't be done without a race condition.

      • O_ASYNC - Enable signal-driven I/O: generate a signal (SIGIO by default, but this can be changed via fcntl(2)) when input or output becomes possible on this file descriptor.

        This feature is only available for terminals, pseudoterminals, sockets, and (since Linux 2.6) pipes and FIFOs. See fcntl(2) for further details.

      • O_CLOEXEC - Enable the close-on-exec flag for the new file descriptor.

        Specifying this flag permits a program to avoid additional fcntl(2) F_SETFD operations to set the FD_CLOEXEC flag. Additionally, use of this flag is essential in some multithreaded programs since using a separate fcntl(2) F_SETFD operation to set the FD_CLOEXEC flag does not suffice to avoid race conditions where one thread opens a file descriptor at the same time as another thread does a fork(2) plus execve(2).

      • O_CREAT - If the file does not exist it will be created.

        The owner (user ID) of the file is set to the effective user ID of the process. The group ownership (group ID) is set either to the effective group ID of the process or to the group ID of the parent directory (depending on file system type and mount options, and the mode of the parent directory, see the mount options bsdgroups and sysvgroups described in mount(8)).

      • O_DIRECT - Try to minimize cache effects of the I/O to and from this file.

        In general this will degrade performance, but it is useful in special situations, such as when applications do their own caching. File I/O is done directly to/from user-space buffers. The O_DIRECT flag on its own makes an effort to transfer data synchronously, but does not give the guarantees of the O_SYNC flag that data and necessary metadata are transferred. To guarantee synchronous I/O, O_SYNC must be used in addition to O_DIRECT.

        A semantically similar (but deprecated) interface for block devices is described in raw(8).

      • O_DIRECTORY - If pathname is not a directory, cause the open to fail.

        This flag is Linux-specific, and was added in kernel version 2.1.126, to avoid denial-of-service problems if opendir(3) is called on a FIFO or tape device, but should not be used outside of the implementation of opendir(3).

      • O_DSYNC
      • O_EXCL - Ensure that this call creates the file: if this flag is specified in conjunction with O_CREAT, and pathname already exists, then open() will fail.

        When these two flags are specified, symbolic links are not followed: if pathname is a symbolic link, then open() fails regardless of where the symbolic link points to.

        In general, the behavior of O_EXCL is undefined if it is used without O_CREAT. There is one exception: on Linux 2.6 and later, O_EXCL can be used without O_CREAT if pathname refers to a block device. If the block device is in use by the system (e.g., mounted), open() fails with the error EBUSY.

        On NFS, O_EXCL is only supported when using NFSv3 or later on kernel 2.6 or later. In NFS environments where O_EXCL support is not provided, programs that rely on it for performing locking tasks will contain a race condition. Portable programs that want to perform atomic file locking using a lockfile, and need to avoid reliance on NFS support for O_EXCL, can create a unique file on the same file system (e.g., incorporating hostname and PID), and use link(2) to make a link to the lockfile. If link(2) returns 0, the lock is successful. Otherwise, use stat(2) on the unique file to check if its link count has increased to 2, in which case the lock is also successful.

      • O_LARGEFILE - (LFS) Allow files whose sizes cannot be represented in an off_t (but can be represented in an off64_t) to be opened.

        The _LARGEFILE64_SOURCE macro must be defined (before including any header files) in order to obtain this definition. Setting the _FILE_OFFSET_BITS feature test macro to 64 (rather than using O_LARGEFILE) is the preferred method of accessing large files on 32-bit systems (see feature_test_macros(7)).

      • O_NOATIME - Do not update the file last access time (st_atime in the inode) when the file is read(2).

        This flag is intended for use by indexing or backup programs, where its use can significantly reduce the amount of disk activity. This flag may not be effective on all file systems. One example is NFS, where the server maintains the access time.

      • O_NOCTTY - If pathname refers to a terminal device --see tty(4)-- it will not become the process's controlling terminal even if the process does not have one.
      • O_NOFOLLOW - If pathname is a symbolic link, then the open fails.

        This is a FreeBSD extension, which was added to Linux in version 2.1.126. Symbolic links in earlier components of the pathname will still be followed.

      • O_NONBLOCK - When possible, the file is opened in nonblocking mode.

        Neither the open() nor any subsequent operations on the file descriptor which is returned will cause the calling process to wait. For the handling of FIFOs (named pipes), see also fifo(7). For a discussion of the effect of O_NONBLOCK in conjunction with mandatory file locks and with file leases, see fcntl(2).

      • O_NDELAY
      • O_PATH
      • O_SYNC - The file is opened for synchronous I/O.

        Any write(2)s on the resulting file descriptor will block the calling process until the data has been physically written to the underlying hardware.

      • O_TMPFILE
      • O_TRUNC - If the file already exists and is a regular file and the open mode allows writing (i.e., is O_RDWR or O_WRONLY) it will be truncated to length 0.

        If the file is a FIFO or terminal device file, the O_TRUNC flag is ignored. Otherwise the effect of O_TRUNC is unspecified.

      See Also:

    • O_DSYNC

      public static final int O_DSYNC
      Enum values:
      • O_ACCMODE
      • O_RDONLY
      • O_WRONLY
      • O_RDWR
      • O_APPEND - The file is opened in append mode.

        Before each write(2), the file offset is positioned at the end of the file, as if with lseek(2). O_APPEND may lead to corrupted files on NFS file systems if more than one process appends data to a file at once. This is because NFS does not support appending to a file, so the client kernel has to simulate it, which can't be done without a race condition.

      • O_ASYNC - Enable signal-driven I/O: generate a signal (SIGIO by default, but this can be changed via fcntl(2)) when input or output becomes possible on this file descriptor.

        This feature is only available for terminals, pseudoterminals, sockets, and (since Linux 2.6) pipes and FIFOs. See fcntl(2) for further details.

      • O_CLOEXEC - Enable the close-on-exec flag for the new file descriptor.

        Specifying this flag permits a program to avoid additional fcntl(2) F_SETFD operations to set the FD_CLOEXEC flag. Additionally, use of this flag is essential in some multithreaded programs since using a separate fcntl(2) F_SETFD operation to set the FD_CLOEXEC flag does not suffice to avoid race conditions where one thread opens a file descriptor at the same time as another thread does a fork(2) plus execve(2).

      • O_CREAT - If the file does not exist it will be created.

        The owner (user ID) of the file is set to the effective user ID of the process. The group ownership (group ID) is set either to the effective group ID of the process or to the group ID of the parent directory (depending on file system type and mount options, and the mode of the parent directory, see the mount options bsdgroups and sysvgroups described in mount(8)).

      • O_DIRECT - Try to minimize cache effects of the I/O to and from this file.

        In general this will degrade performance, but it is useful in special situations, such as when applications do their own caching. File I/O is done directly to/from user-space buffers. The O_DIRECT flag on its own makes an effort to transfer data synchronously, but does not give the guarantees of the O_SYNC flag that data and necessary metadata are transferred. To guarantee synchronous I/O, O_SYNC must be used in addition to O_DIRECT.

        A semantically similar (but deprecated) interface for block devices is described in raw(8).

      • O_DIRECTORY - If pathname is not a directory, cause the open to fail.

        This flag is Linux-specific, and was added in kernel version 2.1.126, to avoid denial-of-service problems if opendir(3) is called on a FIFO or tape device, but should not be used outside of the implementation of opendir(3).

      • O_DSYNC
      • O_EXCL - Ensure that this call creates the file: if this flag is specified in conjunction with O_CREAT, and pathname already exists, then open() will fail.

        When these two flags are specified, symbolic links are not followed: if pathname is a symbolic link, then open() fails regardless of where the symbolic link points to.

        In general, the behavior of O_EXCL is undefined if it is used without O_CREAT. There is one exception: on Linux 2.6 and later, O_EXCL can be used without O_CREAT if pathname refers to a block device. If the block device is in use by the system (e.g., mounted), open() fails with the error EBUSY.

        On NFS, O_EXCL is only supported when using NFSv3 or later on kernel 2.6 or later. In NFS environments where O_EXCL support is not provided, programs that rely on it for performing locking tasks will contain a race condition. Portable programs that want to perform atomic file locking using a lockfile, and need to avoid reliance on NFS support for O_EXCL, can create a unique file on the same file system (e.g., incorporating hostname and PID), and use link(2) to make a link to the lockfile. If link(2) returns 0, the lock is successful. Otherwise, use stat(2) on the unique file to check if its link count has increased to 2, in which case the lock is also successful.

      • O_LARGEFILE - (LFS) Allow files whose sizes cannot be represented in an off_t (but can be represented in an off64_t) to be opened.

        The _LARGEFILE64_SOURCE macro must be defined (before including any header files) in order to obtain this definition. Setting the _FILE_OFFSET_BITS feature test macro to 64 (rather than using O_LARGEFILE) is the preferred method of accessing large files on 32-bit systems (see feature_test_macros(7)).

      • O_NOATIME - Do not update the file last access time (st_atime in the inode) when the file is read(2).

        This flag is intended for use by indexing or backup programs, where its use can significantly reduce the amount of disk activity. This flag may not be effective on all file systems. One example is NFS, where the server maintains the access time.

      • O_NOCTTY - If pathname refers to a terminal device --see tty(4)-- it will not become the process's controlling terminal even if the process does not have one.
      • O_NOFOLLOW - If pathname is a symbolic link, then the open fails.

        This is a FreeBSD extension, which was added to Linux in version 2.1.126. Symbolic links in earlier components of the pathname will still be followed.

      • O_NONBLOCK - When possible, the file is opened in nonblocking mode.

        Neither the open() nor any subsequent operations on the file descriptor which is returned will cause the calling process to wait. For the handling of FIFOs (named pipes), see also fifo(7). For a discussion of the effect of O_NONBLOCK in conjunction with mandatory file locks and with file leases, see fcntl(2).

      • O_NDELAY
      • O_PATH
      • O_SYNC - The file is opened for synchronous I/O.

        Any write(2)s on the resulting file descriptor will block the calling process until the data has been physically written to the underlying hardware.

      • O_TMPFILE
      • O_TRUNC - If the file already exists and is a regular file and the open mode allows writing (i.e., is O_RDWR or O_WRONLY) it will be truncated to length 0.

        If the file is a FIFO or terminal device file, the O_TRUNC flag is ignored. Otherwise the effect of O_TRUNC is unspecified.

      See Also:

    • O_EXCL

      public static final int O_EXCL
      Enum values:
      • O_ACCMODE
      • O_RDONLY
      • O_WRONLY
      • O_RDWR
      • O_APPEND - The file is opened in append mode.

        Before each write(2), the file offset is positioned at the end of the file, as if with lseek(2). O_APPEND may lead to corrupted files on NFS file systems if more than one process appends data to a file at once. This is because NFS does not support appending to a file, so the client kernel has to simulate it, which can't be done without a race condition.

      • O_ASYNC - Enable signal-driven I/O: generate a signal (SIGIO by default, but this can be changed via fcntl(2)) when input or output becomes possible on this file descriptor.

        This feature is only available for terminals, pseudoterminals, sockets, and (since Linux 2.6) pipes and FIFOs. See fcntl(2) for further details.

      • O_CLOEXEC - Enable the close-on-exec flag for the new file descriptor.

        Specifying this flag permits a program to avoid additional fcntl(2) F_SETFD operations to set the FD_CLOEXEC flag. Additionally, use of this flag is essential in some multithreaded programs since using a separate fcntl(2) F_SETFD operation to set the FD_CLOEXEC flag does not suffice to avoid race conditions where one thread opens a file descriptor at the same time as another thread does a fork(2) plus execve(2).

      • O_CREAT - If the file does not exist it will be created.

        The owner (user ID) of the file is set to the effective user ID of the process. The group ownership (group ID) is set either to the effective group ID of the process or to the group ID of the parent directory (depending on file system type and mount options, and the mode of the parent directory, see the mount options bsdgroups and sysvgroups described in mount(8)).

      • O_DIRECT - Try to minimize cache effects of the I/O to and from this file.

        In general this will degrade performance, but it is useful in special situations, such as when applications do their own caching. File I/O is done directly to/from user-space buffers. The O_DIRECT flag on its own makes an effort to transfer data synchronously, but does not give the guarantees of the O_SYNC flag that data and necessary metadata are transferred. To guarantee synchronous I/O, O_SYNC must be used in addition to O_DIRECT.

        A semantically similar (but deprecated) interface for block devices is described in raw(8).

      • O_DIRECTORY - If pathname is not a directory, cause the open to fail.

        This flag is Linux-specific, and was added in kernel version 2.1.126, to avoid denial-of-service problems if opendir(3) is called on a FIFO or tape device, but should not be used outside of the implementation of opendir(3).

      • O_DSYNC
      • O_EXCL - Ensure that this call creates the file: if this flag is specified in conjunction with O_CREAT, and pathname already exists, then open() will fail.

        When these two flags are specified, symbolic links are not followed: if pathname is a symbolic link, then open() fails regardless of where the symbolic link points to.

        In general, the behavior of O_EXCL is undefined if it is used without O_CREAT. There is one exception: on Linux 2.6 and later, O_EXCL can be used without O_CREAT if pathname refers to a block device. If the block device is in use by the system (e.g., mounted), open() fails with the error EBUSY.

        On NFS, O_EXCL is only supported when using NFSv3 or later on kernel 2.6 or later. In NFS environments where O_EXCL support is not provided, programs that rely on it for performing locking tasks will contain a race condition. Portable programs that want to perform atomic file locking using a lockfile, and need to avoid reliance on NFS support for O_EXCL, can create a unique file on the same file system (e.g., incorporating hostname and PID), and use link(2) to make a link to the lockfile. If link(2) returns 0, the lock is successful. Otherwise, use stat(2) on the unique file to check if its link count has increased to 2, in which case the lock is also successful.

      • O_LARGEFILE - (LFS) Allow files whose sizes cannot be represented in an off_t (but can be represented in an off64_t) to be opened.

        The _LARGEFILE64_SOURCE macro must be defined (before including any header files) in order to obtain this definition. Setting the _FILE_OFFSET_BITS feature test macro to 64 (rather than using O_LARGEFILE) is the preferred method of accessing large files on 32-bit systems (see feature_test_macros(7)).

      • O_NOATIME - Do not update the file last access time (st_atime in the inode) when the file is read(2).

        This flag is intended for use by indexing or backup programs, where its use can significantly reduce the amount of disk activity. This flag may not be effective on all file systems. One example is NFS, where the server maintains the access time.

      • O_NOCTTY - If pathname refers to a terminal device --see tty(4)-- it will not become the process's controlling terminal even if the process does not have one.
      • O_NOFOLLOW - If pathname is a symbolic link, then the open fails.

        This is a FreeBSD extension, which was added to Linux in version 2.1.126. Symbolic links in earlier components of the pathname will still be followed.

      • O_NONBLOCK - When possible, the file is opened in nonblocking mode.

        Neither the open() nor any subsequent operations on the file descriptor which is returned will cause the calling process to wait. For the handling of FIFOs (named pipes), see also fifo(7). For a discussion of the effect of O_NONBLOCK in conjunction with mandatory file locks and with file leases, see fcntl(2).

      • O_NDELAY
      • O_PATH
      • O_SYNC - The file is opened for synchronous I/O.

        Any write(2)s on the resulting file descriptor will block the calling process until the data has been physically written to the underlying hardware.

      • O_TMPFILE
      • O_TRUNC - If the file already exists and is a regular file and the open mode allows writing (i.e., is O_RDWR or O_WRONLY) it will be truncated to length 0.

        If the file is a FIFO or terminal device file, the O_TRUNC flag is ignored. Otherwise the effect of O_TRUNC is unspecified.

      See Also:

    • O_LARGEFILE

      public static final int O_LARGEFILE
      Enum values:
      • O_ACCMODE
      • O_RDONLY
      • O_WRONLY
      • O_RDWR
      • O_APPEND - The file is opened in append mode.

        Before each write(2), the file offset is positioned at the end of the file, as if with lseek(2). O_APPEND may lead to corrupted files on NFS file systems if more than one process appends data to a file at once. This is because NFS does not support appending to a file, so the client kernel has to simulate it, which can't be done without a race condition.

      • O_ASYNC - Enable signal-driven I/O: generate a signal (SIGIO by default, but this can be changed via fcntl(2)) when input or output becomes possible on this file descriptor.

        This feature is only available for terminals, pseudoterminals, sockets, and (since Linux 2.6) pipes and FIFOs. See fcntl(2) for further details.

      • O_CLOEXEC - Enable the close-on-exec flag for the new file descriptor.

        Specifying this flag permits a program to avoid additional fcntl(2) F_SETFD operations to set the FD_CLOEXEC flag. Additionally, use of this flag is essential in some multithreaded programs since using a separate fcntl(2) F_SETFD operation to set the FD_CLOEXEC flag does not suffice to avoid race conditions where one thread opens a file descriptor at the same time as another thread does a fork(2) plus execve(2).

      • O_CREAT - If the file does not exist it will be created.

        The owner (user ID) of the file is set to the effective user ID of the process. The group ownership (group ID) is set either to the effective group ID of the process or to the group ID of the parent directory (depending on file system type and mount options, and the mode of the parent directory, see the mount options bsdgroups and sysvgroups described in mount(8)).

      • O_DIRECT - Try to minimize cache effects of the I/O to and from this file.

        In general this will degrade performance, but it is useful in special situations, such as when applications do their own caching. File I/O is done directly to/from user-space buffers. The O_DIRECT flag on its own makes an effort to transfer data synchronously, but does not give the guarantees of the O_SYNC flag that data and necessary metadata are transferred. To guarantee synchronous I/O, O_SYNC must be used in addition to O_DIRECT.

        A semantically similar (but deprecated) interface for block devices is described in raw(8).

      • O_DIRECTORY - If pathname is not a directory, cause the open to fail.

        This flag is Linux-specific, and was added in kernel version 2.1.126, to avoid denial-of-service problems if opendir(3) is called on a FIFO or tape device, but should not be used outside of the implementation of opendir(3).

      • O_DSYNC
      • O_EXCL - Ensure that this call creates the file: if this flag is specified in conjunction with O_CREAT, and pathname already exists, then open() will fail.

        When these two flags are specified, symbolic links are not followed: if pathname is a symbolic link, then open() fails regardless of where the symbolic link points to.

        In general, the behavior of O_EXCL is undefined if it is used without O_CREAT. There is one exception: on Linux 2.6 and later, O_EXCL can be used without O_CREAT if pathname refers to a block device. If the block device is in use by the system (e.g., mounted), open() fails with the error EBUSY.

        On NFS, O_EXCL is only supported when using NFSv3 or later on kernel 2.6 or later. In NFS environments where O_EXCL support is not provided, programs that rely on it for performing locking tasks will contain a race condition. Portable programs that want to perform atomic file locking using a lockfile, and need to avoid reliance on NFS support for O_EXCL, can create a unique file on the same file system (e.g., incorporating hostname and PID), and use link(2) to make a link to the lockfile. If link(2) returns 0, the lock is successful. Otherwise, use stat(2) on the unique file to check if its link count has increased to 2, in which case the lock is also successful.

      • O_LARGEFILE - (LFS) Allow files whose sizes cannot be represented in an off_t (but can be represented in an off64_t) to be opened.

        The _LARGEFILE64_SOURCE macro must be defined (before including any header files) in order to obtain this definition. Setting the _FILE_OFFSET_BITS feature test macro to 64 (rather than using O_LARGEFILE) is the preferred method of accessing large files on 32-bit systems (see feature_test_macros(7)).

      • O_NOATIME - Do not update the file last access time (st_atime in the inode) when the file is read(2).

        This flag is intended for use by indexing or backup programs, where its use can significantly reduce the amount of disk activity. This flag may not be effective on all file systems. One example is NFS, where the server maintains the access time.

      • O_NOCTTY - If pathname refers to a terminal device --see tty(4)-- it will not become the process's controlling terminal even if the process does not have one.
      • O_NOFOLLOW - If pathname is a symbolic link, then the open fails.

        This is a FreeBSD extension, which was added to Linux in version 2.1.126. Symbolic links in earlier components of the pathname will still be followed.

      • O_NONBLOCK - When possible, the file is opened in nonblocking mode.

        Neither the open() nor any subsequent operations on the file descriptor which is returned will cause the calling process to wait. For the handling of FIFOs (named pipes), see also fifo(7). For a discussion of the effect of O_NONBLOCK in conjunction with mandatory file locks and with file leases, see fcntl(2).

      • O_NDELAY
      • O_PATH
      • O_SYNC - The file is opened for synchronous I/O.

        Any write(2)s on the resulting file descriptor will block the calling process until the data has been physically written to the underlying hardware.

      • O_TMPFILE
      • O_TRUNC - If the file already exists and is a regular file and the open mode allows writing (i.e., is O_RDWR or O_WRONLY) it will be truncated to length 0.

        If the file is a FIFO or terminal device file, the O_TRUNC flag is ignored. Otherwise the effect of O_TRUNC is unspecified.

      See Also:

    • O_NOATIME

      public static final int O_NOATIME
      Enum values:
      • O_ACCMODE
      • O_RDONLY
      • O_WRONLY
      • O_RDWR
      • O_APPEND - The file is opened in append mode.

        Before each write(2), the file offset is positioned at the end of the file, as if with lseek(2). O_APPEND may lead to corrupted files on NFS file systems if more than one process appends data to a file at once. This is because NFS does not support appending to a file, so the client kernel has to simulate it, which can't be done without a race condition.

      • O_ASYNC - Enable signal-driven I/O: generate a signal (SIGIO by default, but this can be changed via fcntl(2)) when input or output becomes possible on this file descriptor.

        This feature is only available for terminals, pseudoterminals, sockets, and (since Linux 2.6) pipes and FIFOs. See fcntl(2) for further details.

      • O_CLOEXEC - Enable the close-on-exec flag for the new file descriptor.

        Specifying this flag permits a program to avoid additional fcntl(2) F_SETFD operations to set the FD_CLOEXEC flag. Additionally, use of this flag is essential in some multithreaded programs since using a separate fcntl(2) F_SETFD operation to set the FD_CLOEXEC flag does not suffice to avoid race conditions where one thread opens a file descriptor at the same time as another thread does a fork(2) plus execve(2).

      • O_CREAT - If the file does not exist it will be created.

        The owner (user ID) of the file is set to the effective user ID of the process. The group ownership (group ID) is set either to the effective group ID of the process or to the group ID of the parent directory (depending on file system type and mount options, and the mode of the parent directory, see the mount options bsdgroups and sysvgroups described in mount(8)).

      • O_DIRECT - Try to minimize cache effects of the I/O to and from this file.

        In general this will degrade performance, but it is useful in special situations, such as when applications do their own caching. File I/O is done directly to/from user-space buffers. The O_DIRECT flag on its own makes an effort to transfer data synchronously, but does not give the guarantees of the O_SYNC flag that data and necessary metadata are transferred. To guarantee synchronous I/O, O_SYNC must be used in addition to O_DIRECT.

        A semantically similar (but deprecated) interface for block devices is described in raw(8).

      • O_DIRECTORY - If pathname is not a directory, cause the open to fail.

        This flag is Linux-specific, and was added in kernel version 2.1.126, to avoid denial-of-service problems if opendir(3) is called on a FIFO or tape device, but should not be used outside of the implementation of opendir(3).

      • O_DSYNC
      • O_EXCL - Ensure that this call creates the file: if this flag is specified in conjunction with O_CREAT, and pathname already exists, then open() will fail.

        When these two flags are specified, symbolic links are not followed: if pathname is a symbolic link, then open() fails regardless of where the symbolic link points to.

        In general, the behavior of O_EXCL is undefined if it is used without O_CREAT. There is one exception: on Linux 2.6 and later, O_EXCL can be used without O_CREAT if pathname refers to a block device. If the block device is in use by the system (e.g., mounted), open() fails with the error EBUSY.

        On NFS, O_EXCL is only supported when using NFSv3 or later on kernel 2.6 or later. In NFS environments where O_EXCL support is not provided, programs that rely on it for performing locking tasks will contain a race condition. Portable programs that want to perform atomic file locking using a lockfile, and need to avoid reliance on NFS support for O_EXCL, can create a unique file on the same file system (e.g., incorporating hostname and PID), and use link(2) to make a link to the lockfile. If link(2) returns 0, the lock is successful. Otherwise, use stat(2) on the unique file to check if its link count has increased to 2, in which case the lock is also successful.

      • O_LARGEFILE - (LFS) Allow files whose sizes cannot be represented in an off_t (but can be represented in an off64_t) to be opened.

        The _LARGEFILE64_SOURCE macro must be defined (before including any header files) in order to obtain this definition. Setting the _FILE_OFFSET_BITS feature test macro to 64 (rather than using O_LARGEFILE) is the preferred method of accessing large files on 32-bit systems (see feature_test_macros(7)).

      • O_NOATIME - Do not update the file last access time (st_atime in the inode) when the file is read(2).

        This flag is intended for use by indexing or backup programs, where its use can significantly reduce the amount of disk activity. This flag may not be effective on all file systems. One example is NFS, where the server maintains the access time.

      • O_NOCTTY - If pathname refers to a terminal device --see tty(4)-- it will not become the process's controlling terminal even if the process does not have one.
      • O_NOFOLLOW - If pathname is a symbolic link, then the open fails.

        This is a FreeBSD extension, which was added to Linux in version 2.1.126. Symbolic links in earlier components of the pathname will still be followed.

      • O_NONBLOCK - When possible, the file is opened in nonblocking mode.

        Neither the open() nor any subsequent operations on the file descriptor which is returned will cause the calling process to wait. For the handling of FIFOs (named pipes), see also fifo(7). For a discussion of the effect of O_NONBLOCK in conjunction with mandatory file locks and with file leases, see fcntl(2).

      • O_NDELAY
      • O_PATH
      • O_SYNC - The file is opened for synchronous I/O.

        Any write(2)s on the resulting file descriptor will block the calling process until the data has been physically written to the underlying hardware.

      • O_TMPFILE
      • O_TRUNC - If the file already exists and is a regular file and the open mode allows writing (i.e., is O_RDWR or O_WRONLY) it will be truncated to length 0.

        If the file is a FIFO or terminal device file, the O_TRUNC flag is ignored. Otherwise the effect of O_TRUNC is unspecified.

      See Also:

    • O_NOCTTY

      public static final int O_NOCTTY
      Enum values:
      • O_ACCMODE
      • O_RDONLY
      • O_WRONLY
      • O_RDWR
      • O_APPEND - The file is opened in append mode.

        Before each write(2), the file offset is positioned at the end of the file, as if with lseek(2). O_APPEND may lead to corrupted files on NFS file systems if more than one process appends data to a file at once. This is because NFS does not support appending to a file, so the client kernel has to simulate it, which can't be done without a race condition.

      • O_ASYNC - Enable signal-driven I/O: generate a signal (SIGIO by default, but this can be changed via fcntl(2)) when input or output becomes possible on this file descriptor.

        This feature is only available for terminals, pseudoterminals, sockets, and (since Linux 2.6) pipes and FIFOs. See fcntl(2) for further details.

      • O_CLOEXEC - Enable the close-on-exec flag for the new file descriptor.

        Specifying this flag permits a program to avoid additional fcntl(2) F_SETFD operations to set the FD_CLOEXEC flag. Additionally, use of this flag is essential in some multithreaded programs since using a separate fcntl(2) F_SETFD operation to set the FD_CLOEXEC flag does not suffice to avoid race conditions where one thread opens a file descriptor at the same time as another thread does a fork(2) plus execve(2).

      • O_CREAT - If the file does not exist it will be created.

        The owner (user ID) of the file is set to the effective user ID of the process. The group ownership (group ID) is set either to the effective group ID of the process or to the group ID of the parent directory (depending on file system type and mount options, and the mode of the parent directory, see the mount options bsdgroups and sysvgroups described in mount(8)).

      • O_DIRECT - Try to minimize cache effects of the I/O to and from this file.

        In general this will degrade performance, but it is useful in special situations, such as when applications do their own caching. File I/O is done directly to/from user-space buffers. The O_DIRECT flag on its own makes an effort to transfer data synchronously, but does not give the guarantees of the O_SYNC flag that data and necessary metadata are transferred. To guarantee synchronous I/O, O_SYNC must be used in addition to O_DIRECT.

        A semantically similar (but deprecated) interface for block devices is described in raw(8).

      • O_DIRECTORY - If pathname is not a directory, cause the open to fail.

        This flag is Linux-specific, and was added in kernel version 2.1.126, to avoid denial-of-service problems if opendir(3) is called on a FIFO or tape device, but should not be used outside of the implementation of opendir(3).

      • O_DSYNC
      • O_EXCL - Ensure that this call creates the file: if this flag is specified in conjunction with O_CREAT, and pathname already exists, then open() will fail.

        When these two flags are specified, symbolic links are not followed: if pathname is a symbolic link, then open() fails regardless of where the symbolic link points to.

        In general, the behavior of O_EXCL is undefined if it is used without O_CREAT. There is one exception: on Linux 2.6 and later, O_EXCL can be used without O_CREAT if pathname refers to a block device. If the block device is in use by the system (e.g., mounted), open() fails with the error EBUSY.

        On NFS, O_EXCL is only supported when using NFSv3 or later on kernel 2.6 or later. In NFS environments where O_EXCL support is not provided, programs that rely on it for performing locking tasks will contain a race condition. Portable programs that want to perform atomic file locking using a lockfile, and need to avoid reliance on NFS support for O_EXCL, can create a unique file on the same file system (e.g., incorporating hostname and PID), and use link(2) to make a link to the lockfile. If link(2) returns 0, the lock is successful. Otherwise, use stat(2) on the unique file to check if its link count has increased to 2, in which case the lock is also successful.

      • O_LARGEFILE - (LFS) Allow files whose sizes cannot be represented in an off_t (but can be represented in an off64_t) to be opened.

        The _LARGEFILE64_SOURCE macro must be defined (before including any header files) in order to obtain this definition. Setting the _FILE_OFFSET_BITS feature test macro to 64 (rather than using O_LARGEFILE) is the preferred method of accessing large files on 32-bit systems (see feature_test_macros(7)).

      • O_NOATIME - Do not update the file last access time (st_atime in the inode) when the file is read(2).

        This flag is intended for use by indexing or backup programs, where its use can significantly reduce the amount of disk activity. This flag may not be effective on all file systems. One example is NFS, where the server maintains the access time.

      • O_NOCTTY - If pathname refers to a terminal device --see tty(4)-- it will not become the process's controlling terminal even if the process does not have one.
      • O_NOFOLLOW - If pathname is a symbolic link, then the open fails.

        This is a FreeBSD extension, which was added to Linux in version 2.1.126. Symbolic links in earlier components of the pathname will still be followed.

      • O_NONBLOCK - When possible, the file is opened in nonblocking mode.

        Neither the open() nor any subsequent operations on the file descriptor which is returned will cause the calling process to wait. For the handling of FIFOs (named pipes), see also fifo(7). For a discussion of the effect of O_NONBLOCK in conjunction with mandatory file locks and with file leases, see fcntl(2).

      • O_NDELAY
      • O_PATH
      • O_SYNC - The file is opened for synchronous I/O.

        Any write(2)s on the resulting file descriptor will block the calling process until the data has been physically written to the underlying hardware.

      • O_TMPFILE
      • O_TRUNC - If the file already exists and is a regular file and the open mode allows writing (i.e., is O_RDWR or O_WRONLY) it will be truncated to length 0.

        If the file is a FIFO or terminal device file, the O_TRUNC flag is ignored. Otherwise the effect of O_TRUNC is unspecified.

      See Also:

    • O_NOFOLLOW

      public static final int O_NOFOLLOW
      Enum values:
      • O_ACCMODE
      • O_RDONLY
      • O_WRONLY
      • O_RDWR
      • O_APPEND - The file is opened in append mode.

        Before each write(2), the file offset is positioned at the end of the file, as if with lseek(2). O_APPEND may lead to corrupted files on NFS file systems if more than one process appends data to a file at once. This is because NFS does not support appending to a file, so the client kernel has to simulate it, which can't be done without a race condition.

      • O_ASYNC - Enable signal-driven I/O: generate a signal (SIGIO by default, but this can be changed via fcntl(2)) when input or output becomes possible on this file descriptor.

        This feature is only available for terminals, pseudoterminals, sockets, and (since Linux 2.6) pipes and FIFOs. See fcntl(2) for further details.

      • O_CLOEXEC - Enable the close-on-exec flag for the new file descriptor.

        Specifying this flag permits a program to avoid additional fcntl(2) F_SETFD operations to set the FD_CLOEXEC flag. Additionally, use of this flag is essential in some multithreaded programs since using a separate fcntl(2) F_SETFD operation to set the FD_CLOEXEC flag does not suffice to avoid race conditions where one thread opens a file descriptor at the same time as another thread does a fork(2) plus execve(2).

      • O_CREAT - If the file does not exist it will be created.

        The owner (user ID) of the file is set to the effective user ID of the process. The group ownership (group ID) is set either to the effective group ID of the process or to the group ID of the parent directory (depending on file system type and mount options, and the mode of the parent directory, see the mount options bsdgroups and sysvgroups described in mount(8)).

      • O_DIRECT - Try to minimize cache effects of the I/O to and from this file.

        In general this will degrade performance, but it is useful in special situations, such as when applications do their own caching. File I/O is done directly to/from user-space buffers. The O_DIRECT flag on its own makes an effort to transfer data synchronously, but does not give the guarantees of the O_SYNC flag that data and necessary metadata are transferred. To guarantee synchronous I/O, O_SYNC must be used in addition to O_DIRECT.

        A semantically similar (but deprecated) interface for block devices is described in raw(8).

      • O_DIRECTORY - If pathname is not a directory, cause the open to fail.

        This flag is Linux-specific, and was added in kernel version 2.1.126, to avoid denial-of-service problems if opendir(3) is called on a FIFO or tape device, but should not be used outside of the implementation of opendir(3).

      • O_DSYNC
      • O_EXCL - Ensure that this call creates the file: if this flag is specified in conjunction with O_CREAT, and pathname already exists, then open() will fail.

        When these two flags are specified, symbolic links are not followed: if pathname is a symbolic link, then open() fails regardless of where the symbolic link points to.

        In general, the behavior of O_EXCL is undefined if it is used without O_CREAT. There is one exception: on Linux 2.6 and later, O_EXCL can be used without O_CREAT if pathname refers to a block device. If the block device is in use by the system (e.g., mounted), open() fails with the error EBUSY.

        On NFS, O_EXCL is only supported when using NFSv3 or later on kernel 2.6 or later. In NFS environments where O_EXCL support is not provided, programs that rely on it for performing locking tasks will contain a race condition. Portable programs that want to perform atomic file locking using a lockfile, and need to avoid reliance on NFS support for O_EXCL, can create a unique file on the same file system (e.g., incorporating hostname and PID), and use link(2) to make a link to the lockfile. If link(2) returns 0, the lock is successful. Otherwise, use stat(2) on the unique file to check if its link count has increased to 2, in which case the lock is also successful.

      • O_LARGEFILE - (LFS) Allow files whose sizes cannot be represented in an off_t (but can be represented in an off64_t) to be opened.

        The _LARGEFILE64_SOURCE macro must be defined (before including any header files) in order to obtain this definition. Setting the _FILE_OFFSET_BITS feature test macro to 64 (rather than using O_LARGEFILE) is the preferred method of accessing large files on 32-bit systems (see feature_test_macros(7)).

      • O_NOATIME - Do not update the file last access time (st_atime in the inode) when the file is read(2).

        This flag is intended for use by indexing or backup programs, where its use can significantly reduce the amount of disk activity. This flag may not be effective on all file systems. One example is NFS, where the server maintains the access time.

      • O_NOCTTY - If pathname refers to a terminal device --see tty(4)-- it will not become the process's controlling terminal even if the process does not have one.
      • O_NOFOLLOW - If pathname is a symbolic link, then the open fails.

        This is a FreeBSD extension, which was added to Linux in version 2.1.126. Symbolic links in earlier components of the pathname will still be followed.

      • O_NONBLOCK - When possible, the file is opened in nonblocking mode.

        Neither the open() nor any subsequent operations on the file descriptor which is returned will cause the calling process to wait. For the handling of FIFOs (named pipes), see also fifo(7). For a discussion of the effect of O_NONBLOCK in conjunction with mandatory file locks and with file leases, see fcntl(2).

      • O_NDELAY
      • O_PATH
      • O_SYNC - The file is opened for synchronous I/O.

        Any write(2)s on the resulting file descriptor will block the calling process until the data has been physically written to the underlying hardware.

      • O_TMPFILE
      • O_TRUNC - If the file already exists and is a regular file and the open mode allows writing (i.e., is O_RDWR or O_WRONLY) it will be truncated to length 0.

        If the file is a FIFO or terminal device file, the O_TRUNC flag is ignored. Otherwise the effect of O_TRUNC is unspecified.

      See Also:

    • O_NONBLOCK

      public static final int O_NONBLOCK
      Enum values:
      • O_ACCMODE
      • O_RDONLY
      • O_WRONLY
      • O_RDWR
      • O_APPEND - The file is opened in append mode.

        Before each write(2), the file offset is positioned at the end of the file, as if with lseek(2). O_APPEND may lead to corrupted files on NFS file systems if more than one process appends data to a file at once. This is because NFS does not support appending to a file, so the client kernel has to simulate it, which can't be done without a race condition.

      • O_ASYNC - Enable signal-driven I/O: generate a signal (SIGIO by default, but this can be changed via fcntl(2)) when input or output becomes possible on this file descriptor.

        This feature is only available for terminals, pseudoterminals, sockets, and (since Linux 2.6) pipes and FIFOs. See fcntl(2) for further details.

      • O_CLOEXEC - Enable the close-on-exec flag for the new file descriptor.

        Specifying this flag permits a program to avoid additional fcntl(2) F_SETFD operations to set the FD_CLOEXEC flag. Additionally, use of this flag is essential in some multithreaded programs since using a separate fcntl(2) F_SETFD operation to set the FD_CLOEXEC flag does not suffice to avoid race conditions where one thread opens a file descriptor at the same time as another thread does a fork(2) plus execve(2).

      • O_CREAT - If the file does not exist it will be created.

        The owner (user ID) of the file is set to the effective user ID of the process. The group ownership (group ID) is set either to the effective group ID of the process or to the group ID of the parent directory (depending on file system type and mount options, and the mode of the parent directory, see the mount options bsdgroups and sysvgroups described in mount(8)).

      • O_DIRECT - Try to minimize cache effects of the I/O to and from this file.

        In general this will degrade performance, but it is useful in special situations, such as when applications do their own caching. File I/O is done directly to/from user-space buffers. The O_DIRECT flag on its own makes an effort to transfer data synchronously, but does not give the guarantees of the O_SYNC flag that data and necessary metadata are transferred. To guarantee synchronous I/O, O_SYNC must be used in addition to O_DIRECT.

        A semantically similar (but deprecated) interface for block devices is described in raw(8).

      • O_DIRECTORY - If pathname is not a directory, cause the open to fail.

        This flag is Linux-specific, and was added in kernel version 2.1.126, to avoid denial-of-service problems if opendir(3) is called on a FIFO or tape device, but should not be used outside of the implementation of opendir(3).

      • O_DSYNC
      • O_EXCL - Ensure that this call creates the file: if this flag is specified in conjunction with O_CREAT, and pathname already exists, then open() will fail.

        When these two flags are specified, symbolic links are not followed: if pathname is a symbolic link, then open() fails regardless of where the symbolic link points to.

        In general, the behavior of O_EXCL is undefined if it is used without O_CREAT. There is one exception: on Linux 2.6 and later, O_EXCL can be used without O_CREAT if pathname refers to a block device. If the block device is in use by the system (e.g., mounted), open() fails with the error EBUSY.

        On NFS, O_EXCL is only supported when using NFSv3 or later on kernel 2.6 or later. In NFS environments where O_EXCL support is not provided, programs that rely on it for performing locking tasks will contain a race condition. Portable programs that want to perform atomic file locking using a lockfile, and need to avoid reliance on NFS support for O_EXCL, can create a unique file on the same file system (e.g., incorporating hostname and PID), and use link(2) to make a link to the lockfile. If link(2) returns 0, the lock is successful. Otherwise, use stat(2) on the unique file to check if its link count has increased to 2, in which case the lock is also successful.

      • O_LARGEFILE - (LFS) Allow files whose sizes cannot be represented in an off_t (but can be represented in an off64_t) to be opened.

        The _LARGEFILE64_SOURCE macro must be defined (before including any header files) in order to obtain this definition. Setting the _FILE_OFFSET_BITS feature test macro to 64 (rather than using O_LARGEFILE) is the preferred method of accessing large files on 32-bit systems (see feature_test_macros(7)).

      • O_NOATIME - Do not update the file last access time (st_atime in the inode) when the file is read(2).

        This flag is intended for use by indexing or backup programs, where its use can significantly reduce the amount of disk activity. This flag may not be effective on all file systems. One example is NFS, where the server maintains the access time.

      • O_NOCTTY - If pathname refers to a terminal device --see tty(4)-- it will not become the process's controlling terminal even if the process does not have one.
      • O_NOFOLLOW - If pathname is a symbolic link, then the open fails.

        This is a FreeBSD extension, which was added to Linux in version 2.1.126. Symbolic links in earlier components of the pathname will still be followed.

      • O_NONBLOCK - When possible, the file is opened in nonblocking mode.

        Neither the open() nor any subsequent operations on the file descriptor which is returned will cause the calling process to wait. For the handling of FIFOs (named pipes), see also fifo(7). For a discussion of the effect of O_NONBLOCK in conjunction with mandatory file locks and with file leases, see fcntl(2).

      • O_NDELAY
      • O_PATH
      • O_SYNC - The file is opened for synchronous I/O.

        Any write(2)s on the resulting file descriptor will block the calling process until the data has been physically written to the underlying hardware.

      • O_TMPFILE
      • O_TRUNC - If the file already exists and is a regular file and the open mode allows writing (i.e., is O_RDWR or O_WRONLY) it will be truncated to length 0.

        If the file is a FIFO or terminal device file, the O_TRUNC flag is ignored. Otherwise the effect of O_TRUNC is unspecified.

      See Also:

    • O_NDELAY

      public static final int O_NDELAY
      Enum values:
      • O_ACCMODE
      • O_RDONLY
      • O_WRONLY
      • O_RDWR
      • O_APPEND - The file is opened in append mode.

        Before each write(2), the file offset is positioned at the end of the file, as if with lseek(2). O_APPEND may lead to corrupted files on NFS file systems if more than one process appends data to a file at once. This is because NFS does not support appending to a file, so the client kernel has to simulate it, which can't be done without a race condition.

      • O_ASYNC - Enable signal-driven I/O: generate a signal (SIGIO by default, but this can be changed via fcntl(2)) when input or output becomes possible on this file descriptor.

        This feature is only available for terminals, pseudoterminals, sockets, and (since Linux 2.6) pipes and FIFOs. See fcntl(2) for further details.

      • O_CLOEXEC - Enable the close-on-exec flag for the new file descriptor.

        Specifying this flag permits a program to avoid additional fcntl(2) F_SETFD operations to set the FD_CLOEXEC flag. Additionally, use of this flag is essential in some multithreaded programs since using a separate fcntl(2) F_SETFD operation to set the FD_CLOEXEC flag does not suffice to avoid race conditions where one thread opens a file descriptor at the same time as another thread does a fork(2) plus execve(2).

      • O_CREAT - If the file does not exist it will be created.

        The owner (user ID) of the file is set to the effective user ID of the process. The group ownership (group ID) is set either to the effective group ID of the process or to the group ID of the parent directory (depending on file system type and mount options, and the mode of the parent directory, see the mount options bsdgroups and sysvgroups described in mount(8)).

      • O_DIRECT - Try to minimize cache effects of the I/O to and from this file.

        In general this will degrade performance, but it is useful in special situations, such as when applications do their own caching. File I/O is done directly to/from user-space buffers. The O_DIRECT flag on its own makes an effort to transfer data synchronously, but does not give the guarantees of the O_SYNC flag that data and necessary metadata are transferred. To guarantee synchronous I/O, O_SYNC must be used in addition to O_DIRECT.

        A semantically similar (but deprecated) interface for block devices is described in raw(8).

      • O_DIRECTORY - If pathname is not a directory, cause the open to fail.

        This flag is Linux-specific, and was added in kernel version 2.1.126, to avoid denial-of-service problems if opendir(3) is called on a FIFO or tape device, but should not be used outside of the implementation of opendir(3).

      • O_DSYNC
      • O_EXCL - Ensure that this call creates the file: if this flag is specified in conjunction with O_CREAT, and pathname already exists, then open() will fail.

        When these two flags are specified, symbolic links are not followed: if pathname is a symbolic link, then open() fails regardless of where the symbolic link points to.

        In general, the behavior of O_EXCL is undefined if it is used without O_CREAT. There is one exception: on Linux 2.6 and later, O_EXCL can be used without O_CREAT if pathname refers to a block device. If the block device is in use by the system (e.g., mounted), open() fails with the error EBUSY.

        On NFS, O_EXCL is only supported when using NFSv3 or later on kernel 2.6 or later. In NFS environments where O_EXCL support is not provided, programs that rely on it for performing locking tasks will contain a race condition. Portable programs that want to perform atomic file locking using a lockfile, and need to avoid reliance on NFS support for O_EXCL, can create a unique file on the same file system (e.g., incorporating hostname and PID), and use link(2) to make a link to the lockfile. If link(2) returns 0, the lock is successful. Otherwise, use stat(2) on the unique file to check if its link count has increased to 2, in which case the lock is also successful.

      • O_LARGEFILE - (LFS) Allow files whose sizes cannot be represented in an off_t (but can be represented in an off64_t) to be opened.

        The _LARGEFILE64_SOURCE macro must be defined (before including any header files) in order to obtain this definition. Setting the _FILE_OFFSET_BITS feature test macro to 64 (rather than using O_LARGEFILE) is the preferred method of accessing large files on 32-bit systems (see feature_test_macros(7)).

      • O_NOATIME - Do not update the file last access time (st_atime in the inode) when the file is read(2).

        This flag is intended for use by indexing or backup programs, where its use can significantly reduce the amount of disk activity. This flag may not be effective on all file systems. One example is NFS, where the server maintains the access time.

      • O_NOCTTY - If pathname refers to a terminal device --see tty(4)-- it will not become the process's controlling terminal even if the process does not have one.
      • O_NOFOLLOW - If pathname is a symbolic link, then the open fails.

        This is a FreeBSD extension, which was added to Linux in version 2.1.126. Symbolic links in earlier components of the pathname will still be followed.

      • O_NONBLOCK - When possible, the file is opened in nonblocking mode.

        Neither the open() nor any subsequent operations on the file descriptor which is returned will cause the calling process to wait. For the handling of FIFOs (named pipes), see also fifo(7). For a discussion of the effect of O_NONBLOCK in conjunction with mandatory file locks and with file leases, see fcntl(2).

      • O_NDELAY
      • O_PATH
      • O_SYNC - The file is opened for synchronous I/O.

        Any write(2)s on the resulting file descriptor will block the calling process until the data has been physically written to the underlying hardware.

      • O_TMPFILE
      • O_TRUNC - If the file already exists and is a regular file and the open mode allows writing (i.e., is O_RDWR or O_WRONLY) it will be truncated to length 0.

        If the file is a FIFO or terminal device file, the O_TRUNC flag is ignored. Otherwise the effect of O_TRUNC is unspecified.

      See Also:

    • O_PATH

      public static final int O_PATH
      Enum values:
      • O_ACCMODE
      • O_RDONLY
      • O_WRONLY
      • O_RDWR
      • O_APPEND - The file is opened in append mode.

        Before each write(2), the file offset is positioned at the end of the file, as if with lseek(2). O_APPEND may lead to corrupted files on NFS file systems if more than one process appends data to a file at once. This is because NFS does not support appending to a file, so the client kernel has to simulate it, which can't be done without a race condition.

      • O_ASYNC - Enable signal-driven I/O: generate a signal (SIGIO by default, but this can be changed via fcntl(2)) when input or output becomes possible on this file descriptor.

        This feature is only available for terminals, pseudoterminals, sockets, and (since Linux 2.6) pipes and FIFOs. See fcntl(2) for further details.

      • O_CLOEXEC - Enable the close-on-exec flag for the new file descriptor.

        Specifying this flag permits a program to avoid additional fcntl(2) F_SETFD operations to set the FD_CLOEXEC flag. Additionally, use of this flag is essential in some multithreaded programs since using a separate fcntl(2) F_SETFD operation to set the FD_CLOEXEC flag does not suffice to avoid race conditions where one thread opens a file descriptor at the same time as another thread does a fork(2) plus execve(2).

      • O_CREAT - If the file does not exist it will be created.

        The owner (user ID) of the file is set to the effective user ID of the process. The group ownership (group ID) is set either to the effective group ID of the process or to the group ID of the parent directory (depending on file system type and mount options, and the mode of the parent directory, see the mount options bsdgroups and sysvgroups described in mount(8)).

      • O_DIRECT - Try to minimize cache effects of the I/O to and from this file.

        In general this will degrade performance, but it is useful in special situations, such as when applications do their own caching. File I/O is done directly to/from user-space buffers. The O_DIRECT flag on its own makes an effort to transfer data synchronously, but does not give the guarantees of the O_SYNC flag that data and necessary metadata are transferred. To guarantee synchronous I/O, O_SYNC must be used in addition to O_DIRECT.

        A semantically similar (but deprecated) interface for block devices is described in raw(8).

      • O_DIRECTORY - If pathname is not a directory, cause the open to fail.

        This flag is Linux-specific, and was added in kernel version 2.1.126, to avoid denial-of-service problems if opendir(3) is called on a FIFO or tape device, but should not be used outside of the implementation of opendir(3).

      • O_DSYNC
      • O_EXCL - Ensure that this call creates the file: if this flag is specified in conjunction with O_CREAT, and pathname already exists, then open() will fail.

        When these two flags are specified, symbolic links are not followed: if pathname is a symbolic link, then open() fails regardless of where the symbolic link points to.

        In general, the behavior of O_EXCL is undefined if it is used without O_CREAT. There is one exception: on Linux 2.6 and later, O_EXCL can be used without O_CREAT if pathname refers to a block device. If the block device is in use by the system (e.g., mounted), open() fails with the error EBUSY.

        On NFS, O_EXCL is only supported when using NFSv3 or later on kernel 2.6 or later. In NFS environments where O_EXCL support is not provided, programs that rely on it for performing locking tasks will contain a race condition. Portable programs that want to perform atomic file locking using a lockfile, and need to avoid reliance on NFS support for O_EXCL, can create a unique file on the same file system (e.g., incorporating hostname and PID), and use link(2) to make a link to the lockfile. If link(2) returns 0, the lock is successful. Otherwise, use stat(2) on the unique file to check if its link count has increased to 2, in which case the lock is also successful.

      • O_LARGEFILE - (LFS) Allow files whose sizes cannot be represented in an off_t (but can be represented in an off64_t) to be opened.

        The _LARGEFILE64_SOURCE macro must be defined (before including any header files) in order to obtain this definition. Setting the _FILE_OFFSET_BITS feature test macro to 64 (rather than using O_LARGEFILE) is the preferred method of accessing large files on 32-bit systems (see feature_test_macros(7)).

      • O_NOATIME - Do not update the file last access time (st_atime in the inode) when the file is read(2).

        This flag is intended for use by indexing or backup programs, where its use can significantly reduce the amount of disk activity. This flag may not be effective on all file systems. One example is NFS, where the server maintains the access time.

      • O_NOCTTY - If pathname refers to a terminal device --see tty(4)-- it will not become the process's controlling terminal even if the process does not have one.
      • O_NOFOLLOW - If pathname is a symbolic link, then the open fails.

        This is a FreeBSD extension, which was added to Linux in version 2.1.126. Symbolic links in earlier components of the pathname will still be followed.

      • O_NONBLOCK - When possible, the file is opened in nonblocking mode.

        Neither the open() nor any subsequent operations on the file descriptor which is returned will cause the calling process to wait. For the handling of FIFOs (named pipes), see also fifo(7). For a discussion of the effect of O_NONBLOCK in conjunction with mandatory file locks and with file leases, see fcntl(2).

      • O_NDELAY
      • O_PATH
      • O_SYNC - The file is opened for synchronous I/O.

        Any write(2)s on the resulting file descriptor will block the calling process until the data has been physically written to the underlying hardware.

      • O_TMPFILE
      • O_TRUNC - If the file already exists and is a regular file and the open mode allows writing (i.e., is O_RDWR or O_WRONLY) it will be truncated to length 0.

        If the file is a FIFO or terminal device file, the O_TRUNC flag is ignored. Otherwise the effect of O_TRUNC is unspecified.

      See Also:

    • O_SYNC

      public static final int O_SYNC
      Enum values:
      • O_ACCMODE
      • O_RDONLY
      • O_WRONLY
      • O_RDWR
      • O_APPEND - The file is opened in append mode.

        Before each write(2), the file offset is positioned at the end of the file, as if with lseek(2). O_APPEND may lead to corrupted files on NFS file systems if more than one process appends data to a file at once. This is because NFS does not support appending to a file, so the client kernel has to simulate it, which can't be done without a race condition.

      • O_ASYNC - Enable signal-driven I/O: generate a signal (SIGIO by default, but this can be changed via fcntl(2)) when input or output becomes possible on this file descriptor.

        This feature is only available for terminals, pseudoterminals, sockets, and (since Linux 2.6) pipes and FIFOs. See fcntl(2) for further details.

      • O_CLOEXEC - Enable the close-on-exec flag for the new file descriptor.

        Specifying this flag permits a program to avoid additional fcntl(2) F_SETFD operations to set the FD_CLOEXEC flag. Additionally, use of this flag is essential in some multithreaded programs since using a separate fcntl(2) F_SETFD operation to set the FD_CLOEXEC flag does not suffice to avoid race conditions where one thread opens a file descriptor at the same time as another thread does a fork(2) plus execve(2).

      • O_CREAT - If the file does not exist it will be created.

        The owner (user ID) of the file is set to the effective user ID of the process. The group ownership (group ID) is set either to the effective group ID of the process or to the group ID of the parent directory (depending on file system type and mount options, and the mode of the parent directory, see the mount options bsdgroups and sysvgroups described in mount(8)).

      • O_DIRECT - Try to minimize cache effects of the I/O to and from this file.

        In general this will degrade performance, but it is useful in special situations, such as when applications do their own caching. File I/O is done directly to/from user-space buffers. The O_DIRECT flag on its own makes an effort to transfer data synchronously, but does not give the guarantees of the O_SYNC flag that data and necessary metadata are transferred. To guarantee synchronous I/O, O_SYNC must be used in addition to O_DIRECT.

        A semantically similar (but deprecated) interface for block devices is described in raw(8).

      • O_DIRECTORY - If pathname is not a directory, cause the open to fail.

        This flag is Linux-specific, and was added in kernel version 2.1.126, to avoid denial-of-service problems if opendir(3) is called on a FIFO or tape device, but should not be used outside of the implementation of opendir(3).

      • O_DSYNC
      • O_EXCL - Ensure that this call creates the file: if this flag is specified in conjunction with O_CREAT, and pathname already exists, then open() will fail.

        When these two flags are specified, symbolic links are not followed: if pathname is a symbolic link, then open() fails regardless of where the symbolic link points to.

        In general, the behavior of O_EXCL is undefined if it is used without O_CREAT. There is one exception: on Linux 2.6 and later, O_EXCL can be used without O_CREAT if pathname refers to a block device. If the block device is in use by the system (e.g., mounted), open() fails with the error EBUSY.

        On NFS, O_EXCL is only supported when using NFSv3 or later on kernel 2.6 or later. In NFS environments where O_EXCL support is not provided, programs that rely on it for performing locking tasks will contain a race condition. Portable programs that want to perform atomic file locking using a lockfile, and need to avoid reliance on NFS support for O_EXCL, can create a unique file on the same file system (e.g., incorporating hostname and PID), and use link(2) to make a link to the lockfile. If link(2) returns 0, the lock is successful. Otherwise, use stat(2) on the unique file to check if its link count has increased to 2, in which case the lock is also successful.

      • O_LARGEFILE - (LFS) Allow files whose sizes cannot be represented in an off_t (but can be represented in an off64_t) to be opened.

        The _LARGEFILE64_SOURCE macro must be defined (before including any header files) in order to obtain this definition. Setting the _FILE_OFFSET_BITS feature test macro to 64 (rather than using O_LARGEFILE) is the preferred method of accessing large files on 32-bit systems (see feature_test_macros(7)).

      • O_NOATIME - Do not update the file last access time (st_atime in the inode) when the file is read(2).

        This flag is intended for use by indexing or backup programs, where its use can significantly reduce the amount of disk activity. This flag may not be effective on all file systems. One example is NFS, where the server maintains the access time.

      • O_NOCTTY - If pathname refers to a terminal device --see tty(4)-- it will not become the process's controlling terminal even if the process does not have one.
      • O_NOFOLLOW - If pathname is a symbolic link, then the open fails.

        This is a FreeBSD extension, which was added to Linux in version 2.1.126. Symbolic links in earlier components of the pathname will still be followed.

      • O_NONBLOCK - When possible, the file is opened in nonblocking mode.

        Neither the open() nor any subsequent operations on the file descriptor which is returned will cause the calling process to wait. For the handling of FIFOs (named pipes), see also fifo(7). For a discussion of the effect of O_NONBLOCK in conjunction with mandatory file locks and with file leases, see fcntl(2).

      • O_NDELAY
      • O_PATH
      • O_SYNC - The file is opened for synchronous I/O.

        Any write(2)s on the resulting file descriptor will block the calling process until the data has been physically written to the underlying hardware.

      • O_TMPFILE
      • O_TRUNC - If the file already exists and is a regular file and the open mode allows writing (i.e., is O_RDWR or O_WRONLY) it will be truncated to length 0.

        If the file is a FIFO or terminal device file, the O_TRUNC flag is ignored. Otherwise the effect of O_TRUNC is unspecified.

      See Also:

    • O_TMPFILE

      public static final int O_TMPFILE
      Enum values:
      • O_ACCMODE
      • O_RDONLY
      • O_WRONLY
      • O_RDWR
      • O_APPEND - The file is opened in append mode.

        Before each write(2), the file offset is positioned at the end of the file, as if with lseek(2). O_APPEND may lead to corrupted files on NFS file systems if more than one process appends data to a file at once. This is because NFS does not support appending to a file, so the client kernel has to simulate it, which can't be done without a race condition.

      • O_ASYNC - Enable signal-driven I/O: generate a signal (SIGIO by default, but this can be changed via fcntl(2)) when input or output becomes possible on this file descriptor.

        This feature is only available for terminals, pseudoterminals, sockets, and (since Linux 2.6) pipes and FIFOs. See fcntl(2) for further details.

      • O_CLOEXEC - Enable the close-on-exec flag for the new file descriptor.

        Specifying this flag permits a program to avoid additional fcntl(2) F_SETFD operations to set the FD_CLOEXEC flag. Additionally, use of this flag is essential in some multithreaded programs since using a separate fcntl(2) F_SETFD operation to set the FD_CLOEXEC flag does not suffice to avoid race conditions where one thread opens a file descriptor at the same time as another thread does a fork(2) plus execve(2).

      • O_CREAT - If the file does not exist it will be created.

        The owner (user ID) of the file is set to the effective user ID of the process. The group ownership (group ID) is set either to the effective group ID of the process or to the group ID of the parent directory (depending on file system type and mount options, and the mode of the parent directory, see the mount options bsdgroups and sysvgroups described in mount(8)).

      • O_DIRECT - Try to minimize cache effects of the I/O to and from this file.

        In general this will degrade performance, but it is useful in special situations, such as when applications do their own caching. File I/O is done directly to/from user-space buffers. The O_DIRECT flag on its own makes an effort to transfer data synchronously, but does not give the guarantees of the O_SYNC flag that data and necessary metadata are transferred. To guarantee synchronous I/O, O_SYNC must be used in addition to O_DIRECT.

        A semantically similar (but deprecated) interface for block devices is described in raw(8).

      • O_DIRECTORY - If pathname is not a directory, cause the open to fail.

        This flag is Linux-specific, and was added in kernel version 2.1.126, to avoid denial-of-service problems if opendir(3) is called on a FIFO or tape device, but should not be used outside of the implementation of opendir(3).

      • O_DSYNC
      • O_EXCL - Ensure that this call creates the file: if this flag is specified in conjunction with O_CREAT, and pathname already exists, then open() will fail.

        When these two flags are specified, symbolic links are not followed: if pathname is a symbolic link, then open() fails regardless of where the symbolic link points to.

        In general, the behavior of O_EXCL is undefined if it is used without O_CREAT. There is one exception: on Linux 2.6 and later, O_EXCL can be used without O_CREAT if pathname refers to a block device. If the block device is in use by the system (e.g., mounted), open() fails with the error EBUSY.

        On NFS, O_EXCL is only supported when using NFSv3 or later on kernel 2.6 or later. In NFS environments where O_EXCL support is not provided, programs that rely on it for performing locking tasks will contain a race condition. Portable programs that want to perform atomic file locking using a lockfile, and need to avoid reliance on NFS support for O_EXCL, can create a unique file on the same file system (e.g., incorporating hostname and PID), and use link(2) to make a link to the lockfile. If link(2) returns 0, the lock is successful. Otherwise, use stat(2) on the unique file to check if its link count has increased to 2, in which case the lock is also successful.

      • O_LARGEFILE - (LFS) Allow files whose sizes cannot be represented in an off_t (but can be represented in an off64_t) to be opened.

        The _LARGEFILE64_SOURCE macro must be defined (before including any header files) in order to obtain this definition. Setting the _FILE_OFFSET_BITS feature test macro to 64 (rather than using O_LARGEFILE) is the preferred method of accessing large files on 32-bit systems (see feature_test_macros(7)).

      • O_NOATIME - Do not update the file last access time (st_atime in the inode) when the file is read(2).

        This flag is intended for use by indexing or backup programs, where its use can significantly reduce the amount of disk activity. This flag may not be effective on all file systems. One example is NFS, where the server maintains the access time.

      • O_NOCTTY - If pathname refers to a terminal device --see tty(4)-- it will not become the process's controlling terminal even if the process does not have one.
      • O_NOFOLLOW - If pathname is a symbolic link, then the open fails.

        This is a FreeBSD extension, which was added to Linux in version 2.1.126. Symbolic links in earlier components of the pathname will still be followed.

      • O_NONBLOCK - When possible, the file is opened in nonblocking mode.

        Neither the open() nor any subsequent operations on the file descriptor which is returned will cause the calling process to wait. For the handling of FIFOs (named pipes), see also fifo(7). For a discussion of the effect of O_NONBLOCK in conjunction with mandatory file locks and with file leases, see fcntl(2).

      • O_NDELAY
      • O_PATH
      • O_SYNC - The file is opened for synchronous I/O.

        Any write(2)s on the resulting file descriptor will block the calling process until the data has been physically written to the underlying hardware.

      • O_TMPFILE
      • O_TRUNC - If the file already exists and is a regular file and the open mode allows writing (i.e., is O_RDWR or O_WRONLY) it will be truncated to length 0.

        If the file is a FIFO or terminal device file, the O_TRUNC flag is ignored. Otherwise the effect of O_TRUNC is unspecified.

      See Also:

    • O_TRUNC

      public static final int O_TRUNC
      Enum values:
      • O_ACCMODE
      • O_RDONLY
      • O_WRONLY
      • O_RDWR
      • O_APPEND - The file is opened in append mode.

        Before each write(2), the file offset is positioned at the end of the file, as if with lseek(2). O_APPEND may lead to corrupted files on NFS file systems if more than one process appends data to a file at once. This is because NFS does not support appending to a file, so the client kernel has to simulate it, which can't be done without a race condition.

      • O_ASYNC - Enable signal-driven I/O: generate a signal (SIGIO by default, but this can be changed via fcntl(2)) when input or output becomes possible on this file descriptor.

        This feature is only available for terminals, pseudoterminals, sockets, and (since Linux 2.6) pipes and FIFOs. See fcntl(2) for further details.

      • O_CLOEXEC - Enable the close-on-exec flag for the new file descriptor.

        Specifying this flag permits a program to avoid additional fcntl(2) F_SETFD operations to set the FD_CLOEXEC flag. Additionally, use of this flag is essential in some multithreaded programs since using a separate fcntl(2) F_SETFD operation to set the FD_CLOEXEC flag does not suffice to avoid race conditions where one thread opens a file descriptor at the same time as another thread does a fork(2) plus execve(2).

      • O_CREAT - If the file does not exist it will be created.

        The owner (user ID) of the file is set to the effective user ID of the process. The group ownership (group ID) is set either to the effective group ID of the process or to the group ID of the parent directory (depending on file system type and mount options, and the mode of the parent directory, see the mount options bsdgroups and sysvgroups described in mount(8)).

      • O_DIRECT - Try to minimize cache effects of the I/O to and from this file.

        In general this will degrade performance, but it is useful in special situations, such as when applications do their own caching. File I/O is done directly to/from user-space buffers. The O_DIRECT flag on its own makes an effort to transfer data synchronously, but does not give the guarantees of the O_SYNC flag that data and necessary metadata are transferred. To guarantee synchronous I/O, O_SYNC must be used in addition to O_DIRECT.

        A semantically similar (but deprecated) interface for block devices is described in raw(8).

      • O_DIRECTORY - If pathname is not a directory, cause the open to fail.

        This flag is Linux-specific, and was added in kernel version 2.1.126, to avoid denial-of-service problems if opendir(3) is called on a FIFO or tape device, but should not be used outside of the implementation of opendir(3).

      • O_DSYNC
      • O_EXCL - Ensure that this call creates the file: if this flag is specified in conjunction with O_CREAT, and pathname already exists, then open() will fail.

        When these two flags are specified, symbolic links are not followed: if pathname is a symbolic link, then open() fails regardless of where the symbolic link points to.

        In general, the behavior of O_EXCL is undefined if it is used without O_CREAT. There is one exception: on Linux 2.6 and later, O_EXCL can be used without O_CREAT if pathname refers to a block device. If the block device is in use by the system (e.g., mounted), open() fails with the error EBUSY.

        On NFS, O_EXCL is only supported when using NFSv3 or later on kernel 2.6 or later. In NFS environments where O_EXCL support is not provided, programs that rely on it for performing locking tasks will contain a race condition. Portable programs that want to perform atomic file locking using a lockfile, and need to avoid reliance on NFS support for O_EXCL, can create a unique file on the same file system (e.g., incorporating hostname and PID), and use link(2) to make a link to the lockfile. If link(2) returns 0, the lock is successful. Otherwise, use stat(2) on the unique file to check if its link count has increased to 2, in which case the lock is also successful.

      • O_LARGEFILE - (LFS) Allow files whose sizes cannot be represented in an off_t (but can be represented in an off64_t) to be opened.

        The _LARGEFILE64_SOURCE macro must be defined (before including any header files) in order to obtain this definition. Setting the _FILE_OFFSET_BITS feature test macro to 64 (rather than using O_LARGEFILE) is the preferred method of accessing large files on 32-bit systems (see feature_test_macros(7)).

      • O_NOATIME - Do not update the file last access time (st_atime in the inode) when the file is read(2).

        This flag is intended for use by indexing or backup programs, where its use can significantly reduce the amount of disk activity. This flag may not be effective on all file systems. One example is NFS, where the server maintains the access time.

      • O_NOCTTY - If pathname refers to a terminal device --see tty(4)-- it will not become the process's controlling terminal even if the process does not have one.
      • O_NOFOLLOW - If pathname is a symbolic link, then the open fails.

        This is a FreeBSD extension, which was added to Linux in version 2.1.126. Symbolic links in earlier components of the pathname will still be followed.

      • O_NONBLOCK - When possible, the file is opened in nonblocking mode.

        Neither the open() nor any subsequent operations on the file descriptor which is returned will cause the calling process to wait. For the handling of FIFOs (named pipes), see also fifo(7). For a discussion of the effect of O_NONBLOCK in conjunction with mandatory file locks and with file leases, see fcntl(2).

      • O_NDELAY
      • O_PATH
      • O_SYNC - The file is opened for synchronous I/O.

        Any write(2)s on the resulting file descriptor will block the calling process until the data has been physically written to the underlying hardware.

      • O_TMPFILE
      • O_TRUNC - If the file already exists and is a regular file and the open mode allows writing (i.e., is O_RDWR or O_WRONLY) it will be truncated to length 0.

        If the file is a FIFO or terminal device file, the O_TRUNC flag is ignored. Otherwise the effect of O_TRUNC is unspecified.

      See Also:

    • S_IFMT

      public static final int S_IFMT
      File types encoded in type mode_t.
      Enum values:
      See Also:

    • S_IFBLK

      public static final int S_IFBLK
      File types encoded in type mode_t.
      Enum values:
      See Also:

    • S_IFCHR

      public static final int S_IFCHR
      File types encoded in type mode_t.
      Enum values:
      See Also:

    • S_IFIFO

      public static final int S_IFIFO
      File types encoded in type mode_t.
      Enum values:
      See Also:

    • S_IFREG

      public static final int S_IFREG
      File types encoded in type mode_t.
      Enum values:
      See Also:

    • S_IFDIR

      public static final int S_IFDIR
      File types encoded in type mode_t.
      Enum values:
      See Also:

    • S_IFLNK

      public static final int S_IFLNK
      File types encoded in type mode_t.
      Enum values:
      See Also:

    • S_IFSOCK

      public static final int S_IFSOCK
      File types encoded in type mode_t.
      Enum values:
      See Also:

    • S_IRWXU

      public static final int S_IRWXU
      File mode bits encoded in type mode_t.
      Enum values:
      • S_IRWXU - Read, write, execute/search by owner.
      • S_IRUSR - Read permission, owner.
      • S_IWUSR - Write permission, owner.
      • S_IXUSR - Execute/search permission, owner.
      • S_IRWXG - Read, write, execute/search by group.
      • S_IRGRP - Read permission, group.
      • S_IWGRP - Write permission, group.
      • S_IXGRP - Execute/search permission, group.
      • S_IRWXO - Read, write, execute/search by others.
      • S_IROTH - Read permission, others.
      • S_IWOTH - Write permission, others.
      • S_IXOTH - Execute/search permission, others.
      • S_ISUID - Set-user-ID on execution.
      • S_ISGID - Set-group-ID on execution.
      • S_ISVTX - On directories, restricted deletion flag.
      See Also:

    • S_IRUSR

      public static final int S_IRUSR
      File mode bits encoded in type mode_t.
      Enum values:
      • S_IRWXU - Read, write, execute/search by owner.
      • S_IRUSR - Read permission, owner.
      • S_IWUSR - Write permission, owner.
      • S_IXUSR - Execute/search permission, owner.
      • S_IRWXG - Read, write, execute/search by group.
      • S_IRGRP - Read permission, group.
      • S_IWGRP - Write permission, group.
      • S_IXGRP - Execute/search permission, group.
      • S_IRWXO - Read, write, execute/search by others.
      • S_IROTH - Read permission, others.
      • S_IWOTH - Write permission, others.
      • S_IXOTH - Execute/search permission, others.
      • S_ISUID - Set-user-ID on execution.
      • S_ISGID - Set-group-ID on execution.
      • S_ISVTX - On directories, restricted deletion flag.
      See Also:

    • S_IWUSR

      public static final int S_IWUSR
      File mode bits encoded in type mode_t.
      Enum values:
      • S_IRWXU - Read, write, execute/search by owner.
      • S_IRUSR - Read permission, owner.
      • S_IWUSR - Write permission, owner.
      • S_IXUSR - Execute/search permission, owner.
      • S_IRWXG - Read, write, execute/search by group.
      • S_IRGRP - Read permission, group.
      • S_IWGRP - Write permission, group.
      • S_IXGRP - Execute/search permission, group.
      • S_IRWXO - Read, write, execute/search by others.
      • S_IROTH - Read permission, others.
      • S_IWOTH - Write permission, others.
      • S_IXOTH - Execute/search permission, others.
      • S_ISUID - Set-user-ID on execution.
      • S_ISGID - Set-group-ID on execution.
      • S_ISVTX - On directories, restricted deletion flag.
      See Also:

    • S_IXUSR

      public static final int S_IXUSR
      File mode bits encoded in type mode_t.
      Enum values:
      • S_IRWXU - Read, write, execute/search by owner.
      • S_IRUSR - Read permission, owner.
      • S_IWUSR - Write permission, owner.
      • S_IXUSR - Execute/search permission, owner.
      • S_IRWXG - Read, write, execute/search by group.
      • S_IRGRP - Read permission, group.
      • S_IWGRP - Write permission, group.
      • S_IXGRP - Execute/search permission, group.
      • S_IRWXO - Read, write, execute/search by others.
      • S_IROTH - Read permission, others.
      • S_IWOTH - Write permission, others.
      • S_IXOTH - Execute/search permission, others.
      • S_ISUID - Set-user-ID on execution.
      • S_ISGID - Set-group-ID on execution.
      • S_ISVTX - On directories, restricted deletion flag.
      See Also:

    • S_IRWXG

      public static final int S_IRWXG
      File mode bits encoded in type mode_t.
      Enum values:
      • S_IRWXU - Read, write, execute/search by owner.
      • S_IRUSR - Read permission, owner.
      • S_IWUSR - Write permission, owner.
      • S_IXUSR - Execute/search permission, owner.
      • S_IRWXG - Read, write, execute/search by group.
      • S_IRGRP - Read permission, group.
      • S_IWGRP - Write permission, group.
      • S_IXGRP - Execute/search permission, group.
      • S_IRWXO - Read, write, execute/search by others.
      • S_IROTH - Read permission, others.
      • S_IWOTH - Write permission, others.
      • S_IXOTH - Execute/search permission, others.
      • S_ISUID - Set-user-ID on execution.
      • S_ISGID - Set-group-ID on execution.
      • S_ISVTX - On directories, restricted deletion flag.
      See Also:

    • S_IRGRP

      public static final int S_IRGRP
      File mode bits encoded in type mode_t.
      Enum values:
      • S_IRWXU - Read, write, execute/search by owner.
      • S_IRUSR - Read permission, owner.
      • S_IWUSR - Write permission, owner.
      • S_IXUSR - Execute/search permission, owner.
      • S_IRWXG - Read, write, execute/search by group.
      • S_IRGRP - Read permission, group.
      • S_IWGRP - Write permission, group.
      • S_IXGRP - Execute/search permission, group.
      • S_IRWXO - Read, write, execute/search by others.
      • S_IROTH - Read permission, others.
      • S_IWOTH - Write permission, others.
      • S_IXOTH - Execute/search permission, others.
      • S_ISUID - Set-user-ID on execution.
      • S_ISGID - Set-group-ID on execution.
      • S_ISVTX - On directories, restricted deletion flag.
      See Also:

    • S_IWGRP

      public static final int S_IWGRP
      File mode bits encoded in type mode_t.
      Enum values:
      • S_IRWXU - Read, write, execute/search by owner.
      • S_IRUSR - Read permission, owner.
      • S_IWUSR - Write permission, owner.
      • S_IXUSR - Execute/search permission, owner.
      • S_IRWXG - Read, write, execute/search by group.
      • S_IRGRP - Read permission, group.
      • S_IWGRP - Write permission, group.
      • S_IXGRP - Execute/search permission, group.
      • S_IRWXO - Read, write, execute/search by others.
      • S_IROTH - Read permission, others.
      • S_IWOTH - Write permission, others.
      • S_IXOTH - Execute/search permission, others.
      • S_ISUID - Set-user-ID on execution.
      • S_ISGID - Set-group-ID on execution.
      • S_ISVTX - On directories, restricted deletion flag.
      See Also:

    • S_IXGRP

      public static final int S_IXGRP
      File mode bits encoded in type mode_t.
      Enum values:
      • S_IRWXU - Read, write, execute/search by owner.
      • S_IRUSR - Read permission, owner.
      • S_IWUSR - Write permission, owner.
      • S_IXUSR - Execute/search permission, owner.
      • S_IRWXG - Read, write, execute/search by group.
      • S_IRGRP - Read permission, group.
      • S_IWGRP - Write permission, group.
      • S_IXGRP - Execute/search permission, group.
      • S_IRWXO - Read, write, execute/search by others.
      • S_IROTH - Read permission, others.
      • S_IWOTH - Write permission, others.
      • S_IXOTH - Execute/search permission, others.
      • S_ISUID - Set-user-ID on execution.
      • S_ISGID - Set-group-ID on execution.
      • S_ISVTX - On directories, restricted deletion flag.
      See Also:

    • S_IRWXO

      public static final int S_IRWXO
      File mode bits encoded in type mode_t.
      Enum values:
      • S_IRWXU - Read, write, execute/search by owner.
      • S_IRUSR - Read permission, owner.
      • S_IWUSR - Write permission, owner.
      • S_IXUSR - Execute/search permission, owner.
      • S_IRWXG - Read, write, execute/search by group.
      • S_IRGRP - Read permission, group.
      • S_IWGRP - Write permission, group.
      • S_IXGRP - Execute/search permission, group.
      • S_IRWXO - Read, write, execute/search by others.
      • S_IROTH - Read permission, others.
      • S_IWOTH - Write permission, others.
      • S_IXOTH - Execute/search permission, others.
      • S_ISUID - Set-user-ID on execution.
      • S_ISGID - Set-group-ID on execution.
      • S_ISVTX - On directories, restricted deletion flag.
      See Also:

    • S_IROTH

      public static final int S_IROTH
      File mode bits encoded in type mode_t.
      Enum values:
      • S_IRWXU - Read, write, execute/search by owner.
      • S_IRUSR - Read permission, owner.
      • S_IWUSR - Write permission, owner.
      • S_IXUSR - Execute/search permission, owner.
      • S_IRWXG - Read, write, execute/search by group.
      • S_IRGRP - Read permission, group.
      • S_IWGRP - Write permission, group.
      • S_IXGRP - Execute/search permission, group.
      • S_IRWXO - Read, write, execute/search by others.
      • S_IROTH - Read permission, others.
      • S_IWOTH - Write permission, others.
      • S_IXOTH - Execute/search permission, others.
      • S_ISUID - Set-user-ID on execution.
      • S_ISGID - Set-group-ID on execution.
      • S_ISVTX - On directories, restricted deletion flag.
      See Also:

    • S_IWOTH

      public static final int S_IWOTH
      File mode bits encoded in type mode_t.
      Enum values:
      • S_IRWXU - Read, write, execute/search by owner.
      • S_IRUSR - Read permission, owner.
      • S_IWUSR - Write permission, owner.
      • S_IXUSR - Execute/search permission, owner.
      • S_IRWXG - Read, write, execute/search by group.
      • S_IRGRP - Read permission, group.
      • S_IWGRP - Write permission, group.
      • S_IXGRP - Execute/search permission, group.
      • S_IRWXO - Read, write, execute/search by others.
      • S_IROTH - Read permission, others.
      • S_IWOTH - Write permission, others.
      • S_IXOTH - Execute/search permission, others.
      • S_ISUID - Set-user-ID on execution.
      • S_ISGID - Set-group-ID on execution.
      • S_ISVTX - On directories, restricted deletion flag.
      See Also:

    • S_IXOTH

      public static final int S_IXOTH
      File mode bits encoded in type mode_t.
      Enum values:
      • S_IRWXU - Read, write, execute/search by owner.
      • S_IRUSR - Read permission, owner.
      • S_IWUSR - Write permission, owner.
      • S_IXUSR - Execute/search permission, owner.
      • S_IRWXG - Read, write, execute/search by group.
      • S_IRGRP - Read permission, group.
      • S_IWGRP - Write permission, group.
      • S_IXGRP - Execute/search permission, group.
      • S_IRWXO - Read, write, execute/search by others.
      • S_IROTH - Read permission, others.
      • S_IWOTH - Write permission, others.
      • S_IXOTH - Execute/search permission, others.
      • S_ISUID - Set-user-ID on execution.
      • S_ISGID - Set-group-ID on execution.
      • S_ISVTX - On directories, restricted deletion flag.
      See Also:

    • S_ISUID

      public static final int S_ISUID
      File mode bits encoded in type mode_t.
      Enum values:
      • S_IRWXU - Read, write, execute/search by owner.
      • S_IRUSR - Read permission, owner.
      • S_IWUSR - Write permission, owner.
      • S_IXUSR - Execute/search permission, owner.
      • S_IRWXG - Read, write, execute/search by group.
      • S_IRGRP - Read permission, group.
      • S_IWGRP - Write permission, group.
      • S_IXGRP - Execute/search permission, group.
      • S_IRWXO - Read, write, execute/search by others.
      • S_IROTH - Read permission, others.
      • S_IWOTH - Write permission, others.
      • S_IXOTH - Execute/search permission, others.
      • S_ISUID - Set-user-ID on execution.
      • S_ISGID - Set-group-ID on execution.
      • S_ISVTX - On directories, restricted deletion flag.
      See Also:

    • S_ISGID

      public static final int S_ISGID
      File mode bits encoded in type mode_t.
      Enum values:
      • S_IRWXU - Read, write, execute/search by owner.
      • S_IRUSR - Read permission, owner.
      • S_IWUSR - Write permission, owner.
      • S_IXUSR - Execute/search permission, owner.
      • S_IRWXG - Read, write, execute/search by group.
      • S_IRGRP - Read permission, group.
      • S_IWGRP - Write permission, group.
      • S_IXGRP - Execute/search permission, group.
      • S_IRWXO - Read, write, execute/search by others.
      • S_IROTH - Read permission, others.
      • S_IWOTH - Write permission, others.
      • S_IXOTH - Execute/search permission, others.
      • S_ISUID - Set-user-ID on execution.
      • S_ISGID - Set-group-ID on execution.
      • S_ISVTX - On directories, restricted deletion flag.
      See Also:

    • S_ISVTX

      public static final int S_ISVTX
      File mode bits encoded in type mode_t.
      Enum values:
      • S_IRWXU - Read, write, execute/search by owner.
      • S_IRUSR - Read permission, owner.
      • S_IWUSR - Write permission, owner.
      • S_IXUSR - Execute/search permission, owner.
      • S_IRWXG - Read, write, execute/search by group.
      • S_IRGRP - Read permission, group.
      • S_IWGRP - Write permission, group.
      • S_IXGRP - Execute/search permission, group.
      • S_IRWXO - Read, write, execute/search by others.
      • S_IROTH - Read permission, others.
      • S_IWOTH - Write permission, others.
      • S_IXOTH - Execute/search permission, others.
      • S_ISUID - Set-user-ID on execution.
      • S_ISGID - Set-group-ID on execution.
      • S_ISVTX - On directories, restricted deletion flag.
      See Also:

    • F_DUPFD

      public static final int F_DUPFD
      fcntl(int, int) commands.
      Enum values:
      • F_DUPFD - Duplicate the file descriptor fd using the lowest-numbered available file descriptor greater than or equal to arg.

        This is different from dup2(2), which uses exactly the file descriptor specified.

        On success, the new file descriptor is returned.

        See dup(2) for further details.

      • F_GETFD - Return (as the function result) the file descriptor flags; arg is ignored.
      • F_SETFD - Set the file descriptor flags to the value specified by arg.
      • F_GETFL - Return (as the function result) the file access mode and the file status flags; arg is ignored.
      • F_SETFL - Set the file status flags to the value specified by arg.

        File access mode (O_RDONLY, O_WRONLY, O_RDWR) and file creation flags (i.e., O_CREAT, O_EXCL, O_NOCTTY, O_TRUNC) in arg are ignored. On Linux, this command can change only the O_APPEND, O_ASYNC, O_DIRECT, O_NOATIME, and O_NONBLOCK flags. It is not possible to change the O_DSYNC and O_SYNC flags; see BUGS, below.

      • F_GETLK - On input to this call, lock describes a lock we would like to place on the file.

        If the lock could be placed, fcntl() does not actually place it, but returns F_UNLCK in the l_type field of lock and leaves the other fields of the structure unchanged.

        If one or more incompatible locks would prevent this lock being placed, then fcntl() returns details about one of those locks in the l_type, l_whence, l_start, and l_len fields of lock. If the conflicting lock is a traditional (process-associated) record lock, then the l_pid field is set to the PID of the process holding that lock. If the conflicting lock is an open file description lock, then l_pid is set to -1. Note that the returned information may already be out of date by the time the caller inspects it.

      • F_SETLK - Acquire a lock (when l_type is F_RDLCK or F_WRLCK) or release a lock (when l_type is F_UNLCK) on the bytes specified by the l_whence, l_start, and l_len fields of lock.

        If a conflicting lock is held by another process, this call returns -1 and sets errno to EACCES or EAGAIN. (The error returned in this case differs across implementations, so POSIX requires a portable application to check for both errors.)

      • F_SETLKW - As for F_SETLK, but if a conflicting lock is held on the file, then wait for that lock to be released.

        If a signal is caught while waiting, then the call is interrupted and (after the signal handler has returned) returns immediately (with return value -1 and errno set to EINTR; see signal(7)).

      • F_SETOWN - Set the process ID or process group ID that will receive SIGIO and SIGURG signals for events on the file descriptor fd.

        The target process or process group ID is specified in arg. A process ID is specified as a positive value; a process group ID is specified as a negative value. Most commonly, the calling process specifies itself as the owner (that is, arg is specified as getpid(2)).

        As well as setting the file descriptor owner, one must also enable generation of signals on the file descriptor. This is done by using the fcntl() F_SETFL command to set the O_ASYNC file status flag on the file descriptor. Subsequently, a SIGIO signal is sent whenever input or output becomes possible on the file descriptor. The fcntl() F_SETSIG command can be used to obtain delivery of a signal other than SIGIO.

        Sending a signal to the owner process (group) specified by F_SETOWN is subject to the same permissions checks as are described for kill(2), where the sending process is the one that employs F_SETOWN (but see BUGS below). If this permission check fails, then the signal is silently discarded. Note: The F_SETOWN operation records the caller's credentials at the time of the fcntl() call, and it is these saved credentials that are used for the permission checks.

        If the file descriptor fd refers to a socket, F_SETOWN also selects the recipient of SIGURG signals that are delivered when out-of-band data arrives on that socket. (SIGURG is sent in any situation where select(2) would report the socket as having an "exceptional condition".)

        The following was true in 2.6.x kernels up to and including kernel 2.6.11:

        If a nonzero value is given to F_SETSIG in a multithreaded process running with a threading library that supports thread groups (e.g., NPTL), then a positive value given to F_SETOWN has a different meaning: instead of being a process ID identifying a whole process, it is a thread ID identifying a specific thread within a process. Consequently, it may be necessary to pass F_SETOWN the result of gettid(2) instead of getpid(2) to get sensible results when F_SETSIG is used. (In current Linux threading implementations, a main thread's thread ID is the same as its process ID. This means that a single-threaded program can equally use gettid(2) or getpid(2) in this scenario.) Note, however, that the statements in this paragraph do not apply to the SIGURG signal generated for out-of-band data on a socket: this signal is always sent to either a process or a process group, depending on the value given to F_SETOWN.

        The above behavior was accidentally dropped in Linux 2.6.12, and won't be restored. From Linux 2.6.32 onward, use F_SETOWN_EX to target SIGIO and SIGURG signals at a particular thread.

      • F_GETOWN - Return (as the function result) the process ID or process group ID currently receiving SIGIO and SIGURG signals for events on file descriptor fd.

        Process IDs are returned as positive values; process group IDs are returned as negative values (but see BUGS below). arg is ignored.

      • F_SETSIG - Set the signal sent when input or output becomes possible to the value given in arg.

        A value of zero means to send the default SIGIO signal. Any other value (including SIGIO) is the signal to send instead, and in this case additional info is available to the signal handler if installed with SA_SIGINFO.

        By using F_SETSIG with a nonzero value, and setting SA_SIGINFO for the signal handler (see sigaction(2)), extra information about I/O events is passed to the handler in a siginfo_t structure. If the si_code field indicates the source is SI_SIGIO, the si_fd field gives the file descriptor associated with the event. Otherwise, there is no indication which file descriptors are pending, and you should use the usual mechanisms (select(2), poll(2), read(2) with O_NONBLOCK set etc.) to determine which file descriptors are available for I/O.

        Note that the file descriptor provided in si_fd is the one that was specified during the F_SETSIG operation. This can lead to an unusual corner case. If the file descriptor is duplicated (dup(2) or similar), and the original file descriptor is closed, then I/O events will continue to be generated, but the si_fd field will contain the number of the now closed file descriptor.

        By selecting a real time signal (value ≥ SIGRTMIN), multiple I/O events may be queued using the same signal numbers. (Queuing is dependent on available memory.) Extra information is available if SA_SIGINFO is set for the signal handler, as above.

        Note that Linux imposes a limit on the number of real-time signals that may be queued to a process (see getrlimit(2) and signal(7)) and if this limit is reached, then the kernel reverts to delivering SIGIO, and this signal is delivered to the entire process rather than to a specific thread.

      • F_GETSIG - Return (as the function result) the signal sent when input or output becomes possible.

        A value of zero means SIGIO is sent. Any other value (including SIGIO) is the signal sent instead, and in this case additional info is available to the signal handler if installed with SA_SIGINFO. arg is ignored.

      • F_SETOWN_EX - This operation performs a similar task to F_SETOWN. It allows the caller to direct I/O availability signals to a specific thread, process, or process group.

        The caller specifies the target of signals via arg, which is a pointer to a FOwnerEx structure. The type field has one of the following values, which define how pid is interpreted: F_OWNER_TID, F_OWNER_PID, F_OWNER_PGRP.

      • F_GETOWN_EX - Return the current file descriptor owner settings as defined by a previous F_SETOWN_EX operation.

        The information is returned in the FOwnerEx structure pointed to by arg.

        The type field will have one of the values F_OWNER_TID, F_OWNER_PID, or F_OWNER_PGRP. The pid field is a positive integer representing a thread ID, process ID, or process group ID. See F_SETOWN_EX for more details.

      • F_OFD_GETLK - On input to this call, lock describes an open file description lock we would like to place on the file.

        If the lock could be placed, fcntl() does not actually place it, but returns F_UNLCK in the l_type field of lock and leaves the other fields of the structure unchanged. If one or more incompatible locks would prevent this lock being placed, then details about one of these locks are returned via lock, as described above for F_GETLK.

      • F_OFD_SETLK - Acquire an open file description lock (when l_type is F_RDLCK or F_WRLCK) or release an open file description lock (when l_type is F_UNLCK) on the bytes specified by the l_whence, l_start, and l_len fields of lock.

        If a conflicting lock is held by another process, this call returns -1 and sets errno to EAGAIN.

      • F_OFD_SETLKW - As for F_OFD_SETLK, but if a conflicting lock is held on the file, then wait for that lock to be released.

        If a signal is caught while waiting, then the call is interrupted and (after the signal handler has returned) returns immediately (with return value -1 and errno set to EINTR; see signal(7)).

      • F_SETLEASE - Set or remove a file lease according to which of the following values is specified in the integer arg: F_RDLCK, F_WRLCK, F_UNLCK
      • F_GETLEASE - Indicates what type of lease is associated with the file descriptor fd by returning either F_RDLCK, F_WRLCK, or F_UNLCK, indicating, respectively, a read lease, a write lease, or no lease. arg is ignored.
      • F_NOTIFY - (Linux 2.4 onward) Provide notification when the directory referred to by fd or any of the files that it contains is changed.

        The events to be notified are specified in arg, which is a bit mask specified by ORing together zero or more of the following bits: DN_ACCESS, DN_MODIFY, DN_CREATE, DN_DELETE, DN_RENAME, DN_ATTRIB

        (In order to obtain these definitions, the _GNU_SOURCE feature test macro must be defined before including any header files.)

        Directory notifications are normally "one-shot", and the application must reregister to receive further notifications. Alternatively, if DN_MULTISHOT is included in arg, then notification will remain in effect until explicitly removed.

        A series of F_NOTIFY requests is cumulative, with the events in arg being added to the set already monitored. To disable notification of all events, make an F_NOTIFY call specifying arg as 0.

        Notification occurs via delivery of a signal. The default signal is SIGIO, but this can be changed using the F_SETSIG command to fcntl(). (Note that SIGIO is one of the nonqueuing standard signals; switching to the use of a real-time signal means that multiple notifications can be queued to the process.) In the latter case, the signal handler receives a siginfo_t structure as its second argument (if the handler was established using SA_SIGINFO) and the si_fd field of this structure contains the file descriptor which generated the notification (useful when establishing notification on multiple directories).

        Especially when using DN_MULTISHOT, a real time signal should be used for notification, so that multiple notifications can be queued.

        NOTE: New applications should use the inotify interface (available since kernel 2.6.13), which provides a much superior interface for obtaining notifications of filesystem events. See inotify(7).

      • F_SETPIPE_SZ - Change the capacity of the pipe referred to by fd to be at least arg bytes.

        An unprivileged process can adjust the pipe capacity to any value between the system page size and the limit defined in /proc/sys/fs/pipe-max-size (see proc(5)). Attempts to set the pipe capacity below the page size are silently rounded up to the page size. Attempts by an unprivileged process to set the pipe capacity above the limit in /proc/sys/fs/pipe-max-size yield the error EPERM; a privileged process (CAP_SYS_RESOURCE) can override the limit.

        When allocating the buffer for the pipe, the kernel may use a capacity larger than arg, if that is convenient for the implementation. (In the current implementation, the allocation is the next higher power-of-two page-size multiple of the requested size.) The actual capacity (in bytes) that is set is returned as the function result.

        Attempting to set the pipe capacity smaller than the amount of buffer space currently used to store data produces the error EBUSY.

        Note that because of the way the pages of the pipe buffer are employed when data is written to the pipe, the number of bytes that can be written may be less than the nominal size, depending on the size of the writes.

      • F_GETPIPE_SZ - Return (as the function result) the capacity of the pipe referred to by fd.
      • F_ADD_SEALS - Add the seals given in the bit-mask argument arg to the set of seals of the inode referred to by the file descriptor fd.

        Seals cannot be removed again. Once this call succeeds, the seals are enforced by the kernel immediately. If the current set of seals includes F_SEAL_SEAL (see below), then this call will be rejected with EPERM. Adding a seal that is already set is a no-op, in case F_SEAL_SEAL is not set already. In order to place a seal, the file descriptor fd must be writable.

      • F_GET_SEALS - Return (as the function result) the current set of seals of the inode referred to by fd.

        If no seals are set, 0 is returned. If the file does not support sealing, -1 is returned and errno is set to EINVAL.

      • F_GET_RW_HINT - Returns the value of the read/write hint associated with the underlying inode referred to by fd.
      • F_SET_RW_HINT - Sets the read/write hint value associated with the underlying inode referred to by fd.

        This hint persists until either it is explicitly modified or the underlying filesystem is unmounted.

      • F_GET_FILE_RW_HINT - Returns the value of the read/write hint associated with the open file description referred to by fd.
      • F_SET_FILE_RW_HINT - Sets the read/write hint value associated with the open file description referred to by fd.
      • F_DUPFD_CLOEXEC - As for F_DUPFD, but additionally set the close-on-exec flag for the duplicate file descriptor.

        Specifying this flag permits a program to avoid an additional fcntl() F_SETFD operation to set the FD_CLOEXEC flag. For an explanation of why this flag is useful, see the description of O_CLOEXEC in open(2).

      See Also:

    • F_GETFD

      public static final int F_GETFD
      fcntl(int, int) commands.
      Enum values:
      • F_DUPFD - Duplicate the file descriptor fd using the lowest-numbered available file descriptor greater than or equal to arg.

        This is different from dup2(2), which uses exactly the file descriptor specified.

        On success, the new file descriptor is returned.

        See dup(2) for further details.

      • F_GETFD - Return (as the function result) the file descriptor flags; arg is ignored.
      • F_SETFD - Set the file descriptor flags to the value specified by arg.
      • F_GETFL - Return (as the function result) the file access mode and the file status flags; arg is ignored.
      • F_SETFL - Set the file status flags to the value specified by arg.

        File access mode (O_RDONLY, O_WRONLY, O_RDWR) and file creation flags (i.e., O_CREAT, O_EXCL, O_NOCTTY, O_TRUNC) in arg are ignored. On Linux, this command can change only the O_APPEND, O_ASYNC, O_DIRECT, O_NOATIME, and O_NONBLOCK flags. It is not possible to change the O_DSYNC and O_SYNC flags; see BUGS, below.

      • F_GETLK - On input to this call, lock describes a lock we would like to place on the file.

        If the lock could be placed, fcntl() does not actually place it, but returns F_UNLCK in the l_type field of lock and leaves the other fields of the structure unchanged.

        If one or more incompatible locks would prevent this lock being placed, then fcntl() returns details about one of those locks in the l_type, l_whence, l_start, and l_len fields of lock. If the conflicting lock is a traditional (process-associated) record lock, then the l_pid field is set to the PID of the process holding that lock. If the conflicting lock is an open file description lock, then l_pid is set to -1. Note that the returned information may already be out of date by the time the caller inspects it.

      • F_SETLK - Acquire a lock (when l_type is F_RDLCK or F_WRLCK) or release a lock (when l_type is F_UNLCK) on the bytes specified by the l_whence, l_start, and l_len fields of lock.

        If a conflicting lock is held by another process, this call returns -1 and sets errno to EACCES or EAGAIN. (The error returned in this case differs across implementations, so POSIX requires a portable application to check for both errors.)

      • F_SETLKW - As for F_SETLK, but if a conflicting lock is held on the file, then wait for that lock to be released.

        If a signal is caught while waiting, then the call is interrupted and (after the signal handler has returned) returns immediately (with return value -1 and errno set to EINTR; see signal(7)).

      • F_SETOWN - Set the process ID or process group ID that will receive SIGIO and SIGURG signals for events on the file descriptor fd.

        The target process or process group ID is specified in arg. A process ID is specified as a positive value; a process group ID is specified as a negative value. Most commonly, the calling process specifies itself as the owner (that is, arg is specified as getpid(2)).

        As well as setting the file descriptor owner, one must also enable generation of signals on the file descriptor. This is done by using the fcntl() F_SETFL command to set the O_ASYNC file status flag on the file descriptor. Subsequently, a SIGIO signal is sent whenever input or output becomes possible on the file descriptor. The fcntl() F_SETSIG command can be used to obtain delivery of a signal other than SIGIO.

        Sending a signal to the owner process (group) specified by F_SETOWN is subject to the same permissions checks as are described for kill(2), where the sending process is the one that employs F_SETOWN (but see BUGS below). If this permission check fails, then the signal is silently discarded. Note: The F_SETOWN operation records the caller's credentials at the time of the fcntl() call, and it is these saved credentials that are used for the permission checks.

        If the file descriptor fd refers to a socket, F_SETOWN also selects the recipient of SIGURG signals that are delivered when out-of-band data arrives on that socket. (SIGURG is sent in any situation where select(2) would report the socket as having an "exceptional condition".)

        The following was true in 2.6.x kernels up to and including kernel 2.6.11:

        If a nonzero value is given to F_SETSIG in a multithreaded process running with a threading library that supports thread groups (e.g., NPTL), then a positive value given to F_SETOWN has a different meaning: instead of being a process ID identifying a whole process, it is a thread ID identifying a specific thread within a process. Consequently, it may be necessary to pass F_SETOWN the result of gettid(2) instead of getpid(2) to get sensible results when F_SETSIG is used. (In current Linux threading implementations, a main thread's thread ID is the same as its process ID. This means that a single-threaded program can equally use gettid(2) or getpid(2) in this scenario.) Note, however, that the statements in this paragraph do not apply to the SIGURG signal generated for out-of-band data on a socket: this signal is always sent to either a process or a process group, depending on the value given to F_SETOWN.

        The above behavior was accidentally dropped in Linux 2.6.12, and won't be restored. From Linux 2.6.32 onward, use F_SETOWN_EX to target SIGIO and SIGURG signals at a particular thread.

      • F_GETOWN - Return (as the function result) the process ID or process group ID currently receiving SIGIO and SIGURG signals for events on file descriptor fd.

        Process IDs are returned as positive values; process group IDs are returned as negative values (but see BUGS below). arg is ignored.

      • F_SETSIG - Set the signal sent when input or output becomes possible to the value given in arg.

        A value of zero means to send the default SIGIO signal. Any other value (including SIGIO) is the signal to send instead, and in this case additional info is available to the signal handler if installed with SA_SIGINFO.

        By using F_SETSIG with a nonzero value, and setting SA_SIGINFO for the signal handler (see sigaction(2)), extra information about I/O events is passed to the handler in a siginfo_t structure. If the si_code field indicates the source is SI_SIGIO, the si_fd field gives the file descriptor associated with the event. Otherwise, there is no indication which file descriptors are pending, and you should use the usual mechanisms (select(2), poll(2), read(2) with O_NONBLOCK set etc.) to determine which file descriptors are available for I/O.

        Note that the file descriptor provided in si_fd is the one that was specified during the F_SETSIG operation. This can lead to an unusual corner case. If the file descriptor is duplicated (dup(2) or similar), and the original file descriptor is closed, then I/O events will continue to be generated, but the si_fd field will contain the number of the now closed file descriptor.

        By selecting a real time signal (value ≥ SIGRTMIN), multiple I/O events may be queued using the same signal numbers. (Queuing is dependent on available memory.) Extra information is available if SA_SIGINFO is set for the signal handler, as above.

        Note that Linux imposes a limit on the number of real-time signals that may be queued to a process (see getrlimit(2) and signal(7)) and if this limit is reached, then the kernel reverts to delivering SIGIO, and this signal is delivered to the entire process rather than to a specific thread.

      • F_GETSIG - Return (as the function result) the signal sent when input or output becomes possible.

        A value of zero means SIGIO is sent. Any other value (including SIGIO) is the signal sent instead, and in this case additional info is available to the signal handler if installed with SA_SIGINFO. arg is ignored.

      • F_SETOWN_EX - This operation performs a similar task to F_SETOWN. It allows the caller to direct I/O availability signals to a specific thread, process, or process group.

        The caller specifies the target of signals via arg, which is a pointer to a FOwnerEx structure. The type field has one of the following values, which define how pid is interpreted: F_OWNER_TID, F_OWNER_PID, F_OWNER_PGRP.

      • F_GETOWN_EX - Return the current file descriptor owner settings as defined by a previous F_SETOWN_EX operation.

        The information is returned in the FOwnerEx structure pointed to by arg.

        The type field will have one of the values F_OWNER_TID, F_OWNER_PID, or F_OWNER_PGRP. The pid field is a positive integer representing a thread ID, process ID, or process group ID. See F_SETOWN_EX for more details.

      • F_OFD_GETLK - On input to this call, lock describes an open file description lock we would like to place on the file.

        If the lock could be placed, fcntl() does not actually place it, but returns F_UNLCK in the l_type field of lock and leaves the other fields of the structure unchanged. If one or more incompatible locks would prevent this lock being placed, then details about one of these locks are returned via lock, as described above for F_GETLK.

      • F_OFD_SETLK - Acquire an open file description lock (when l_type is F_RDLCK or F_WRLCK) or release an open file description lock (when l_type is F_UNLCK) on the bytes specified by the l_whence, l_start, and l_len fields of lock.

        If a conflicting lock is held by another process, this call returns -1 and sets errno to EAGAIN.

      • F_OFD_SETLKW - As for F_OFD_SETLK, but if a conflicting lock is held on the file, then wait for that lock to be released.

        If a signal is caught while waiting, then the call is interrupted and (after the signal handler has returned) returns immediately (with return value -1 and errno set to EINTR; see signal(7)).

      • F_SETLEASE - Set or remove a file lease according to which of the following values is specified in the integer arg: F_RDLCK, F_WRLCK, F_UNLCK
      • F_GETLEASE - Indicates what type of lease is associated with the file descriptor fd by returning either F_RDLCK, F_WRLCK, or F_UNLCK, indicating, respectively, a read lease, a write lease, or no lease. arg is ignored.
      • F_NOTIFY - (Linux 2.4 onward) Provide notification when the directory referred to by fd or any of the files that it contains is changed.

        The events to be notified are specified in arg, which is a bit mask specified by ORing together zero or more of the following bits: DN_ACCESS, DN_MODIFY, DN_CREATE, DN_DELETE, DN_RENAME, DN_ATTRIB

        (In order to obtain these definitions, the _GNU_SOURCE feature test macro must be defined before including any header files.)

        Directory notifications are normally "one-shot", and the application must reregister to receive further notifications. Alternatively, if DN_MULTISHOT is included in arg, then notification will remain in effect until explicitly removed.

        A series of F_NOTIFY requests is cumulative, with the events in arg being added to the set already monitored. To disable notification of all events, make an F_NOTIFY call specifying arg as 0.

        Notification occurs via delivery of a signal. The default signal is SIGIO, but this can be changed using the F_SETSIG command to fcntl(). (Note that SIGIO is one of the nonqueuing standard signals; switching to the use of a real-time signal means that multiple notifications can be queued to the process.) In the latter case, the signal handler receives a siginfo_t structure as its second argument (if the handler was established using SA_SIGINFO) and the si_fd field of this structure contains the file descriptor which generated the notification (useful when establishing notification on multiple directories).

        Especially when using DN_MULTISHOT, a real time signal should be used for notification, so that multiple notifications can be queued.

        NOTE: New applications should use the inotify interface (available since kernel 2.6.13), which provides a much superior interface for obtaining notifications of filesystem events. See inotify(7).

      • F_SETPIPE_SZ - Change the capacity of the pipe referred to by fd to be at least arg bytes.

        An unprivileged process can adjust the pipe capacity to any value between the system page size and the limit defined in /proc/sys/fs/pipe-max-size (see proc(5)). Attempts to set the pipe capacity below the page size are silently rounded up to the page size. Attempts by an unprivileged process to set the pipe capacity above the limit in /proc/sys/fs/pipe-max-size yield the error EPERM; a privileged process (CAP_SYS_RESOURCE) can override the limit.

        When allocating the buffer for the pipe, the kernel may use a capacity larger than arg, if that is convenient for the implementation. (In the current implementation, the allocation is the next higher power-of-two page-size multiple of the requested size.) The actual capacity (in bytes) that is set is returned as the function result.

        Attempting to set the pipe capacity smaller than the amount of buffer space currently used to store data produces the error EBUSY.

        Note that because of the way the pages of the pipe buffer are employed when data is written to the pipe, the number of bytes that can be written may be less than the nominal size, depending on the size of the writes.

      • F_GETPIPE_SZ - Return (as the function result) the capacity of the pipe referred to by fd.
      • F_ADD_SEALS - Add the seals given in the bit-mask argument arg to the set of seals of the inode referred to by the file descriptor fd.

        Seals cannot be removed again. Once this call succeeds, the seals are enforced by the kernel immediately. If the current set of seals includes F_SEAL_SEAL (see below), then this call will be rejected with EPERM. Adding a seal that is already set is a no-op, in case F_SEAL_SEAL is not set already. In order to place a seal, the file descriptor fd must be writable.

      • F_GET_SEALS - Return (as the function result) the current set of seals of the inode referred to by fd.

        If no seals are set, 0 is returned. If the file does not support sealing, -1 is returned and errno is set to EINVAL.

      • F_GET_RW_HINT - Returns the value of the read/write hint associated with the underlying inode referred to by fd.
      • F_SET_RW_HINT - Sets the read/write hint value associated with the underlying inode referred to by fd.

        This hint persists until either it is explicitly modified or the underlying filesystem is unmounted.

      • F_GET_FILE_RW_HINT - Returns the value of the read/write hint associated with the open file description referred to by fd.
      • F_SET_FILE_RW_HINT - Sets the read/write hint value associated with the open file description referred to by fd.
      • F_DUPFD_CLOEXEC - As for F_DUPFD, but additionally set the close-on-exec flag for the duplicate file descriptor.

        Specifying this flag permits a program to avoid an additional fcntl() F_SETFD operation to set the FD_CLOEXEC flag. For an explanation of why this flag is useful, see the description of O_CLOEXEC in open(2).

      See Also:

    • F_SETFD

      public static final int F_SETFD
      fcntl(int, int) commands.
      Enum values:
      • F_DUPFD - Duplicate the file descriptor fd using the lowest-numbered available file descriptor greater than or equal to arg.

        This is different from dup2(2), which uses exactly the file descriptor specified.

        On success, the new file descriptor is returned.

        See dup(2) for further details.

      • F_GETFD - Return (as the function result) the file descriptor flags; arg is ignored.
      • F_SETFD - Set the file descriptor flags to the value specified by arg.
      • F_GETFL - Return (as the function result) the file access mode and the file status flags; arg is ignored.
      • F_SETFL - Set the file status flags to the value specified by arg.

        File access mode (O_RDONLY, O_WRONLY, O_RDWR) and file creation flags (i.e., O_CREAT, O_EXCL, O_NOCTTY, O_TRUNC) in arg are ignored. On Linux, this command can change only the O_APPEND, O_ASYNC, O_DIRECT, O_NOATIME, and O_NONBLOCK flags. It is not possible to change the O_DSYNC and O_SYNC flags; see BUGS, below.

      • F_GETLK - On input to this call, lock describes a lock we would like to place on the file.

        If the lock could be placed, fcntl() does not actually place it, but returns F_UNLCK in the l_type field of lock and leaves the other fields of the structure unchanged.

        If one or more incompatible locks would prevent this lock being placed, then fcntl() returns details about one of those locks in the l_type, l_whence, l_start, and l_len fields of lock. If the conflicting lock is a traditional (process-associated) record lock, then the l_pid field is set to the PID of the process holding that lock. If the conflicting lock is an open file description lock, then l_pid is set to -1. Note that the returned information may already be out of date by the time the caller inspects it.

      • F_SETLK - Acquire a lock (when l_type is F_RDLCK or F_WRLCK) or release a lock (when l_type is F_UNLCK) on the bytes specified by the l_whence, l_start, and l_len fields of lock.

        If a conflicting lock is held by another process, this call returns -1 and sets errno to EACCES or EAGAIN. (The error returned in this case differs across implementations, so POSIX requires a portable application to check for both errors.)

      • F_SETLKW - As for F_SETLK, but if a conflicting lock is held on the file, then wait for that lock to be released.

        If a signal is caught while waiting, then the call is interrupted and (after the signal handler has returned) returns immediately (with return value -1 and errno set to EINTR; see signal(7)).

      • F_SETOWN - Set the process ID or process group ID that will receive SIGIO and SIGURG signals for events on the file descriptor fd.

        The target process or process group ID is specified in arg. A process ID is specified as a positive value; a process group ID is specified as a negative value. Most commonly, the calling process specifies itself as the owner (that is, arg is specified as getpid(2)).

        As well as setting the file descriptor owner, one must also enable generation of signals on the file descriptor. This is done by using the fcntl() F_SETFL command to set the O_ASYNC file status flag on the file descriptor. Subsequently, a SIGIO signal is sent whenever input or output becomes possible on the file descriptor. The fcntl() F_SETSIG command can be used to obtain delivery of a signal other than SIGIO.

        Sending a signal to the owner process (group) specified by F_SETOWN is subject to the same permissions checks as are described for kill(2), where the sending process is the one that employs F_SETOWN (but see BUGS below). If this permission check fails, then the signal is silently discarded. Note: The F_SETOWN operation records the caller's credentials at the time of the fcntl() call, and it is these saved credentials that are used for the permission checks.

        If the file descriptor fd refers to a socket, F_SETOWN also selects the recipient of SIGURG signals that are delivered when out-of-band data arrives on that socket. (SIGURG is sent in any situation where select(2) would report the socket as having an "exceptional condition".)

        The following was true in 2.6.x kernels up to and including kernel 2.6.11:

        If a nonzero value is given to F_SETSIG in a multithreaded process running with a threading library that supports thread groups (e.g., NPTL), then a positive value given to F_SETOWN has a different meaning: instead of being a process ID identifying a whole process, it is a thread ID identifying a specific thread within a process. Consequently, it may be necessary to pass F_SETOWN the result of gettid(2) instead of getpid(2) to get sensible results when F_SETSIG is used. (In current Linux threading implementations, a main thread's thread ID is the same as its process ID. This means that a single-threaded program can equally use gettid(2) or getpid(2) in this scenario.) Note, however, that the statements in this paragraph do not apply to the SIGURG signal generated for out-of-band data on a socket: this signal is always sent to either a process or a process group, depending on the value given to F_SETOWN.

        The above behavior was accidentally dropped in Linux 2.6.12, and won't be restored. From Linux 2.6.32 onward, use F_SETOWN_EX to target SIGIO and SIGURG signals at a particular thread.

      • F_GETOWN - Return (as the function result) the process ID or process group ID currently receiving SIGIO and SIGURG signals for events on file descriptor fd.

        Process IDs are returned as positive values; process group IDs are returned as negative values (but see BUGS below). arg is ignored.

      • F_SETSIG - Set the signal sent when input or output becomes possible to the value given in arg.

        A value of zero means to send the default SIGIO signal. Any other value (including SIGIO) is the signal to send instead, and in this case additional info is available to the signal handler if installed with SA_SIGINFO.

        By using F_SETSIG with a nonzero value, and setting SA_SIGINFO for the signal handler (see sigaction(2)), extra information about I/O events is passed to the handler in a siginfo_t structure. If the si_code field indicates the source is SI_SIGIO, the si_fd field gives the file descriptor associated with the event. Otherwise, there is no indication which file descriptors are pending, and you should use the usual mechanisms (select(2), poll(2), read(2) with O_NONBLOCK set etc.) to determine which file descriptors are available for I/O.

        Note that the file descriptor provided in si_fd is the one that was specified during the F_SETSIG operation. This can lead to an unusual corner case. If the file descriptor is duplicated (dup(2) or similar), and the original file descriptor is closed, then I/O events will continue to be generated, but the si_fd field will contain the number of the now closed file descriptor.

        By selecting a real time signal (value ≥ SIGRTMIN), multiple I/O events may be queued using the same signal numbers. (Queuing is dependent on available memory.) Extra information is available if SA_SIGINFO is set for the signal handler, as above.

        Note that Linux imposes a limit on the number of real-time signals that may be queued to a process (see getrlimit(2) and signal(7)) and if this limit is reached, then the kernel reverts to delivering SIGIO, and this signal is delivered to the entire process rather than to a specific thread.

      • F_GETSIG - Return (as the function result) the signal sent when input or output becomes possible.

        A value of zero means SIGIO is sent. Any other value (including SIGIO) is the signal sent instead, and in this case additional info is available to the signal handler if installed with SA_SIGINFO. arg is ignored.

      • F_SETOWN_EX - This operation performs a similar task to F_SETOWN. It allows the caller to direct I/O availability signals to a specific thread, process, or process group.

        The caller specifies the target of signals via arg, which is a pointer to a FOwnerEx structure. The type field has one of the following values, which define how pid is interpreted: F_OWNER_TID, F_OWNER_PID, F_OWNER_PGRP.

      • F_GETOWN_EX - Return the current file descriptor owner settings as defined by a previous F_SETOWN_EX operation.

        The information is returned in the FOwnerEx structure pointed to by arg.

        The type field will have one of the values F_OWNER_TID, F_OWNER_PID, or F_OWNER_PGRP. The pid field is a positive integer representing a thread ID, process ID, or process group ID. See F_SETOWN_EX for more details.

      • F_OFD_GETLK - On input to this call, lock describes an open file description lock we would like to place on the file.

        If the lock could be placed, fcntl() does not actually place it, but returns F_UNLCK in the l_type field of lock and leaves the other fields of the structure unchanged. If one or more incompatible locks would prevent this lock being placed, then details about one of these locks are returned via lock, as described above for F_GETLK.

      • F_OFD_SETLK - Acquire an open file description lock (when l_type is F_RDLCK or F_WRLCK) or release an open file description lock (when l_type is F_UNLCK) on the bytes specified by the l_whence, l_start, and l_len fields of lock.

        If a conflicting lock is held by another process, this call returns -1 and sets errno to EAGAIN.

      • F_OFD_SETLKW - As for F_OFD_SETLK, but if a conflicting lock is held on the file, then wait for that lock to be released.

        If a signal is caught while waiting, then the call is interrupted and (after the signal handler has returned) returns immediately (with return value -1 and errno set to EINTR; see signal(7)).

      • F_SETLEASE - Set or remove a file lease according to which of the following values is specified in the integer arg: F_RDLCK, F_WRLCK, F_UNLCK
      • F_GETLEASE - Indicates what type of lease is associated with the file descriptor fd by returning either F_RDLCK, F_WRLCK, or F_UNLCK, indicating, respectively, a read lease, a write lease, or no lease. arg is ignored.
      • F_NOTIFY - (Linux 2.4 onward) Provide notification when the directory referred to by fd or any of the files that it contains is changed.

        The events to be notified are specified in arg, which is a bit mask specified by ORing together zero or more of the following bits: DN_ACCESS, DN_MODIFY, DN_CREATE, DN_DELETE, DN_RENAME, DN_ATTRIB

        (In order to obtain these definitions, the _GNU_SOURCE feature test macro must be defined before including any header files.)

        Directory notifications are normally "one-shot", and the application must reregister to receive further notifications. Alternatively, if DN_MULTISHOT is included in arg, then notification will remain in effect until explicitly removed.

        A series of F_NOTIFY requests is cumulative, with the events in arg being added to the set already monitored. To disable notification of all events, make an F_NOTIFY call specifying arg as 0.

        Notification occurs via delivery of a signal. The default signal is SIGIO, but this can be changed using the F_SETSIG command to fcntl(). (Note that SIGIO is one of the nonqueuing standard signals; switching to the use of a real-time signal means that multiple notifications can be queued to the process.) In the latter case, the signal handler receives a siginfo_t structure as its second argument (if the handler was established using SA_SIGINFO) and the si_fd field of this structure contains the file descriptor which generated the notification (useful when establishing notification on multiple directories).

        Especially when using DN_MULTISHOT, a real time signal should be used for notification, so that multiple notifications can be queued.

        NOTE: New applications should use the inotify interface (available since kernel 2.6.13), which provides a much superior interface for obtaining notifications of filesystem events. See inotify(7).

      • F_SETPIPE_SZ - Change the capacity of the pipe referred to by fd to be at least arg bytes.

        An unprivileged process can adjust the pipe capacity to any value between the system page size and the limit defined in /proc/sys/fs/pipe-max-size (see proc(5)). Attempts to set the pipe capacity below the page size are silently rounded up to the page size. Attempts by an unprivileged process to set the pipe capacity above the limit in /proc/sys/fs/pipe-max-size yield the error EPERM; a privileged process (CAP_SYS_RESOURCE) can override the limit.

        When allocating the buffer for the pipe, the kernel may use a capacity larger than arg, if that is convenient for the implementation. (In the current implementation, the allocation is the next higher power-of-two page-size multiple of the requested size.) The actual capacity (in bytes) that is set is returned as the function result.

        Attempting to set the pipe capacity smaller than the amount of buffer space currently used to store data produces the error EBUSY.

        Note that because of the way the pages of the pipe buffer are employed when data is written to the pipe, the number of bytes that can be written may be less than the nominal size, depending on the size of the writes.

      • F_GETPIPE_SZ - Return (as the function result) the capacity of the pipe referred to by fd.
      • F_ADD_SEALS - Add the seals given in the bit-mask argument arg to the set of seals of the inode referred to by the file descriptor fd.

        Seals cannot be removed again. Once this call succeeds, the seals are enforced by the kernel immediately. If the current set of seals includes F_SEAL_SEAL (see below), then this call will be rejected with EPERM. Adding a seal that is already set is a no-op, in case F_SEAL_SEAL is not set already. In order to place a seal, the file descriptor fd must be writable.

      • F_GET_SEALS - Return (as the function result) the current set of seals of the inode referred to by fd.

        If no seals are set, 0 is returned. If the file does not support sealing, -1 is returned and errno is set to EINVAL.

      • F_GET_RW_HINT - Returns the value of the read/write hint associated with the underlying inode referred to by fd.
      • F_SET_RW_HINT - Sets the read/write hint value associated with the underlying inode referred to by fd.

        This hint persists until either it is explicitly modified or the underlying filesystem is unmounted.

      • F_GET_FILE_RW_HINT - Returns the value of the read/write hint associated with the open file description referred to by fd.
      • F_SET_FILE_RW_HINT - Sets the read/write hint value associated with the open file description referred to by fd.
      • F_DUPFD_CLOEXEC - As for F_DUPFD, but additionally set the close-on-exec flag for the duplicate file descriptor.

        Specifying this flag permits a program to avoid an additional fcntl() F_SETFD operation to set the FD_CLOEXEC flag. For an explanation of why this flag is useful, see the description of O_CLOEXEC in open(2).

      See Also:

    • F_GETFL

      public static final int F_GETFL
      fcntl(int, int) commands.
      Enum values:
      • F_DUPFD - Duplicate the file descriptor fd using the lowest-numbered available file descriptor greater than or equal to arg.

        This is different from dup2(2), which uses exactly the file descriptor specified.

        On success, the new file descriptor is returned.

        See dup(2) for further details.

      • F_GETFD - Return (as the function result) the file descriptor flags; arg is ignored.
      • F_SETFD - Set the file descriptor flags to the value specified by arg.
      • F_GETFL - Return (as the function result) the file access mode and the file status flags; arg is ignored.
      • F_SETFL - Set the file status flags to the value specified by arg.

        File access mode (O_RDONLY, O_WRONLY, O_RDWR) and file creation flags (i.e., O_CREAT, O_EXCL, O_NOCTTY, O_TRUNC) in arg are ignored. On Linux, this command can change only the O_APPEND, O_ASYNC, O_DIRECT, O_NOATIME, and O_NONBLOCK flags. It is not possible to change the O_DSYNC and O_SYNC flags; see BUGS, below.

      • F_GETLK - On input to this call, lock describes a lock we would like to place on the file.

        If the lock could be placed, fcntl() does not actually place it, but returns F_UNLCK in the l_type field of lock and leaves the other fields of the structure unchanged.

        If one or more incompatible locks would prevent this lock being placed, then fcntl() returns details about one of those locks in the l_type, l_whence, l_start, and l_len fields of lock. If the conflicting lock is a traditional (process-associated) record lock, then the l_pid field is set to the PID of the process holding that lock. If the conflicting lock is an open file description lock, then l_pid is set to -1. Note that the returned information may already be out of date by the time the caller inspects it.

      • F_SETLK - Acquire a lock (when l_type is F_RDLCK or F_WRLCK) or release a lock (when l_type is F_UNLCK) on the bytes specified by the l_whence, l_start, and l_len fields of lock.

        If a conflicting lock is held by another process, this call returns -1 and sets errno to EACCES or EAGAIN. (The error returned in this case differs across implementations, so POSIX requires a portable application to check for both errors.)

      • F_SETLKW - As for F_SETLK, but if a conflicting lock is held on the file, then wait for that lock to be released.

        If a signal is caught while waiting, then the call is interrupted and (after the signal handler has returned) returns immediately (with return value -1 and errno set to EINTR; see signal(7)).

      • F_SETOWN - Set the process ID or process group ID that will receive SIGIO and SIGURG signals for events on the file descriptor fd.

        The target process or process group ID is specified in arg. A process ID is specified as a positive value; a process group ID is specified as a negative value. Most commonly, the calling process specifies itself as the owner (that is, arg is specified as getpid(2)).

        As well as setting the file descriptor owner, one must also enable generation of signals on the file descriptor. This is done by using the fcntl() F_SETFL command to set the O_ASYNC file status flag on the file descriptor. Subsequently, a SIGIO signal is sent whenever input or output becomes possible on the file descriptor. The fcntl() F_SETSIG command can be used to obtain delivery of a signal other than SIGIO.

        Sending a signal to the owner process (group) specified by F_SETOWN is subject to the same permissions checks as are described for kill(2), where the sending process is the one that employs F_SETOWN (but see BUGS below). If this permission check fails, then the signal is silently discarded. Note: The F_SETOWN operation records the caller's credentials at the time of the fcntl() call, and it is these saved credentials that are used for the permission checks.

        If the file descriptor fd refers to a socket, F_SETOWN also selects the recipient of SIGURG signals that are delivered when out-of-band data arrives on that socket. (SIGURG is sent in any situation where select(2) would report the socket as having an "exceptional condition".)

        The following was true in 2.6.x kernels up to and including kernel 2.6.11:

        If a nonzero value is given to F_SETSIG in a multithreaded process running with a threading library that supports thread groups (e.g., NPTL), then a positive value given to F_SETOWN has a different meaning: instead of being a process ID identifying a whole process, it is a thread ID identifying a specific thread within a process. Consequently, it may be necessary to pass F_SETOWN the result of gettid(2) instead of getpid(2) to get sensible results when F_SETSIG is used. (In current Linux threading implementations, a main thread's thread ID is the same as its process ID. This means that a single-threaded program can equally use gettid(2) or getpid(2) in this scenario.) Note, however, that the statements in this paragraph do not apply to the SIGURG signal generated for out-of-band data on a socket: this signal is always sent to either a process or a process group, depending on the value given to F_SETOWN.

        The above behavior was accidentally dropped in Linux 2.6.12, and won't be restored. From Linux 2.6.32 onward, use F_SETOWN_EX to target SIGIO and SIGURG signals at a particular thread.

      • F_GETOWN - Return (as the function result) the process ID or process group ID currently receiving SIGIO and SIGURG signals for events on file descriptor fd.

        Process IDs are returned as positive values; process group IDs are returned as negative values (but see BUGS below). arg is ignored.

      • F_SETSIG - Set the signal sent when input or output becomes possible to the value given in arg.

        A value of zero means to send the default SIGIO signal. Any other value (including SIGIO) is the signal to send instead, and in this case additional info is available to the signal handler if installed with SA_SIGINFO.

        By using F_SETSIG with a nonzero value, and setting SA_SIGINFO for the signal handler (see sigaction(2)), extra information about I/O events is passed to the handler in a siginfo_t structure. If the si_code field indicates the source is SI_SIGIO, the si_fd field gives the file descriptor associated with the event. Otherwise, there is no indication which file descriptors are pending, and you should use the usual mechanisms (select(2), poll(2), read(2) with O_NONBLOCK set etc.) to determine which file descriptors are available for I/O.

        Note that the file descriptor provided in si_fd is the one that was specified during the F_SETSIG operation. This can lead to an unusual corner case. If the file descriptor is duplicated (dup(2) or similar), and the original file descriptor is closed, then I/O events will continue to be generated, but the si_fd field will contain the number of the now closed file descriptor.

        By selecting a real time signal (value ≥ SIGRTMIN), multiple I/O events may be queued using the same signal numbers. (Queuing is dependent on available memory.) Extra information is available if SA_SIGINFO is set for the signal handler, as above.

        Note that Linux imposes a limit on the number of real-time signals that may be queued to a process (see getrlimit(2) and signal(7)) and if this limit is reached, then the kernel reverts to delivering SIGIO, and this signal is delivered to the entire process rather than to a specific thread.

      • F_GETSIG - Return (as the function result) the signal sent when input or output becomes possible.

        A value of zero means SIGIO is sent. Any other value (including SIGIO) is the signal sent instead, and in this case additional info is available to the signal handler if installed with SA_SIGINFO. arg is ignored.

      • F_SETOWN_EX - This operation performs a similar task to F_SETOWN. It allows the caller to direct I/O availability signals to a specific thread, process, or process group.

        The caller specifies the target of signals via arg, which is a pointer to a FOwnerEx structure. The type field has one of the following values, which define how pid is interpreted: F_OWNER_TID, F_OWNER_PID, F_OWNER_PGRP.

      • F_GETOWN_EX - Return the current file descriptor owner settings as defined by a previous F_SETOWN_EX operation.

        The information is returned in the FOwnerEx structure pointed to by arg.

        The type field will have one of the values F_OWNER_TID, F_OWNER_PID, or F_OWNER_PGRP. The pid field is a positive integer representing a thread ID, process ID, or process group ID. See F_SETOWN_EX for more details.

      • F_OFD_GETLK - On input to this call, lock describes an open file description lock we would like to place on the file.

        If the lock could be placed, fcntl() does not actually place it, but returns F_UNLCK in the l_type field of lock and leaves the other fields of the structure unchanged. If one or more incompatible locks would prevent this lock being placed, then details about one of these locks are returned via lock, as described above for F_GETLK.

      • F_OFD_SETLK - Acquire an open file description lock (when l_type is F_RDLCK or F_WRLCK) or release an open file description lock (when l_type is F_UNLCK) on the bytes specified by the l_whence, l_start, and l_len fields of lock.

        If a conflicting lock is held by another process, this call returns -1 and sets errno to EAGAIN.

      • F_OFD_SETLKW - As for F_OFD_SETLK, but if a conflicting lock is held on the file, then wait for that lock to be released.

        If a signal is caught while waiting, then the call is interrupted and (after the signal handler has returned) returns immediately (with return value -1 and errno set to EINTR; see signal(7)).

      • F_SETLEASE - Set or remove a file lease according to which of the following values is specified in the integer arg: F_RDLCK, F_WRLCK, F_UNLCK
      • F_GETLEASE - Indicates what type of lease is associated with the file descriptor fd by returning either F_RDLCK, F_WRLCK, or F_UNLCK, indicating, respectively, a read lease, a write lease, or no lease. arg is ignored.
      • F_NOTIFY - (Linux 2.4 onward) Provide notification when the directory referred to by fd or any of the files that it contains is changed.

        The events to be notified are specified in arg, which is a bit mask specified by ORing together zero or more of the following bits: DN_ACCESS, DN_MODIFY, DN_CREATE, DN_DELETE, DN_RENAME, DN_ATTRIB

        (In order to obtain these definitions, the _GNU_SOURCE feature test macro must be defined before including any header files.)

        Directory notifications are normally "one-shot", and the application must reregister to receive further notifications. Alternatively, if DN_MULTISHOT is included in arg, then notification will remain in effect until explicitly removed.

        A series of F_NOTIFY requests is cumulative, with the events in arg being added to the set already monitored. To disable notification of all events, make an F_NOTIFY call specifying arg as 0.

        Notification occurs via delivery of a signal. The default signal is SIGIO, but this can be changed using the F_SETSIG command to fcntl(). (Note that SIGIO is one of the nonqueuing standard signals; switching to the use of a real-time signal means that multiple notifications can be queued to the process.) In the latter case, the signal handler receives a siginfo_t structure as its second argument (if the handler was established using SA_SIGINFO) and the si_fd field of this structure contains the file descriptor which generated the notification (useful when establishing notification on multiple directories).

        Especially when using DN_MULTISHOT, a real time signal should be used for notification, so that multiple notifications can be queued.

        NOTE: New applications should use the inotify interface (available since kernel 2.6.13), which provides a much superior interface for obtaining notifications of filesystem events. See inotify(7).

      • F_SETPIPE_SZ - Change the capacity of the pipe referred to by fd to be at least arg bytes.

        An unprivileged process can adjust the pipe capacity to any value between the system page size and the limit defined in /proc/sys/fs/pipe-max-size (see proc(5)). Attempts to set the pipe capacity below the page size are silently rounded up to the page size. Attempts by an unprivileged process to set the pipe capacity above the limit in /proc/sys/fs/pipe-max-size yield the error EPERM; a privileged process (CAP_SYS_RESOURCE) can override the limit.

        When allocating the buffer for the pipe, the kernel may use a capacity larger than arg, if that is convenient for the implementation. (In the current implementation, the allocation is the next higher power-of-two page-size multiple of the requested size.) The actual capacity (in bytes) that is set is returned as the function result.

        Attempting to set the pipe capacity smaller than the amount of buffer space currently used to store data produces the error EBUSY.

        Note that because of the way the pages of the pipe buffer are employed when data is written to the pipe, the number of bytes that can be written may be less than the nominal size, depending on the size of the writes.

      • F_GETPIPE_SZ - Return (as the function result) the capacity of the pipe referred to by fd.
      • F_ADD_SEALS - Add the seals given in the bit-mask argument arg to the set of seals of the inode referred to by the file descriptor fd.

        Seals cannot be removed again. Once this call succeeds, the seals are enforced by the kernel immediately. If the current set of seals includes F_SEAL_SEAL (see below), then this call will be rejected with EPERM. Adding a seal that is already set is a no-op, in case F_SEAL_SEAL is not set already. In order to place a seal, the file descriptor fd must be writable.

      • F_GET_SEALS - Return (as the function result) the current set of seals of the inode referred to by fd.

        If no seals are set, 0 is returned. If the file does not support sealing, -1 is returned and errno is set to EINVAL.

      • F_GET_RW_HINT - Returns the value of the read/write hint associated with the underlying inode referred to by fd.
      • F_SET_RW_HINT - Sets the read/write hint value associated with the underlying inode referred to by fd.

        This hint persists until either it is explicitly modified or the underlying filesystem is unmounted.

      • F_GET_FILE_RW_HINT - Returns the value of the read/write hint associated with the open file description referred to by fd.
      • F_SET_FILE_RW_HINT - Sets the read/write hint value associated with the open file description referred to by fd.
      • F_DUPFD_CLOEXEC - As for F_DUPFD, but additionally set the close-on-exec flag for the duplicate file descriptor.

        Specifying this flag permits a program to avoid an additional fcntl() F_SETFD operation to set the FD_CLOEXEC flag. For an explanation of why this flag is useful, see the description of O_CLOEXEC in open(2).

      See Also:

    • F_SETFL

      public static final int F_SETFL
      fcntl(int, int) commands.
      Enum values:
      • F_DUPFD - Duplicate the file descriptor fd using the lowest-numbered available file descriptor greater than or equal to arg.

        This is different from dup2(2), which uses exactly the file descriptor specified.

        On success, the new file descriptor is returned.

        See dup(2) for further details.

      • F_GETFD - Return (as the function result) the file descriptor flags; arg is ignored.
      • F_SETFD - Set the file descriptor flags to the value specified by arg.
      • F_GETFL - Return (as the function result) the file access mode and the file status flags; arg is ignored.
      • F_SETFL - Set the file status flags to the value specified by arg.

        File access mode (O_RDONLY, O_WRONLY, O_RDWR) and file creation flags (i.e., O_CREAT, O_EXCL, O_NOCTTY, O_TRUNC) in arg are ignored. On Linux, this command can change only the O_APPEND, O_ASYNC, O_DIRECT, O_NOATIME, and O_NONBLOCK flags. It is not possible to change the O_DSYNC and O_SYNC flags; see BUGS, below.

      • F_GETLK - On input to this call, lock describes a lock we would like to place on the file.

        If the lock could be placed, fcntl() does not actually place it, but returns F_UNLCK in the l_type field of lock and leaves the other fields of the structure unchanged.

        If one or more incompatible locks would prevent this lock being placed, then fcntl() returns details about one of those locks in the l_type, l_whence, l_start, and l_len fields of lock. If the conflicting lock is a traditional (process-associated) record lock, then the l_pid field is set to the PID of the process holding that lock. If the conflicting lock is an open file description lock, then l_pid is set to -1. Note that the returned information may already be out of date by the time the caller inspects it.

      • F_SETLK - Acquire a lock (when l_type is F_RDLCK or F_WRLCK) or release a lock (when l_type is F_UNLCK) on the bytes specified by the l_whence, l_start, and l_len fields of lock.

        If a conflicting lock is held by another process, this call returns -1 and sets errno to EACCES or EAGAIN. (The error returned in this case differs across implementations, so POSIX requires a portable application to check for both errors.)

      • F_SETLKW - As for F_SETLK, but if a conflicting lock is held on the file, then wait for that lock to be released.

        If a signal is caught while waiting, then the call is interrupted and (after the signal handler has returned) returns immediately (with return value -1 and errno set to EINTR; see signal(7)).

      • F_SETOWN - Set the process ID or process group ID that will receive SIGIO and SIGURG signals for events on the file descriptor fd.

        The target process or process group ID is specified in arg. A process ID is specified as a positive value; a process group ID is specified as a negative value. Most commonly, the calling process specifies itself as the owner (that is, arg is specified as getpid(2)).

        As well as setting the file descriptor owner, one must also enable generation of signals on the file descriptor. This is done by using the fcntl() F_SETFL command to set the O_ASYNC file status flag on the file descriptor. Subsequently, a SIGIO signal is sent whenever input or output becomes possible on the file descriptor. The fcntl() F_SETSIG command can be used to obtain delivery of a signal other than SIGIO.

        Sending a signal to the owner process (group) specified by F_SETOWN is subject to the same permissions checks as are described for kill(2), where the sending process is the one that employs F_SETOWN (but see BUGS below). If this permission check fails, then the signal is silently discarded. Note: The F_SETOWN operation records the caller's credentials at the time of the fcntl() call, and it is these saved credentials that are used for the permission checks.

        If the file descriptor fd refers to a socket, F_SETOWN also selects the recipient of SIGURG signals that are delivered when out-of-band data arrives on that socket. (SIGURG is sent in any situation where select(2) would report the socket as having an "exceptional condition".)

        The following was true in 2.6.x kernels up to and including kernel 2.6.11:

        If a nonzero value is given to F_SETSIG in a multithreaded process running with a threading library that supports thread groups (e.g., NPTL), then a positive value given to F_SETOWN has a different meaning: instead of being a process ID identifying a whole process, it is a thread ID identifying a specific thread within a process. Consequently, it may be necessary to pass F_SETOWN the result of gettid(2) instead of getpid(2) to get sensible results when F_SETSIG is used. (In current Linux threading implementations, a main thread's thread ID is the same as its process ID. This means that a single-threaded program can equally use gettid(2) or getpid(2) in this scenario.) Note, however, that the statements in this paragraph do not apply to the SIGURG signal generated for out-of-band data on a socket: this signal is always sent to either a process or a process group, depending on the value given to F_SETOWN.

        The above behavior was accidentally dropped in Linux 2.6.12, and won't be restored. From Linux 2.6.32 onward, use F_SETOWN_EX to target SIGIO and SIGURG signals at a particular thread.

      • F_GETOWN - Return (as the function result) the process ID or process group ID currently receiving SIGIO and SIGURG signals for events on file descriptor fd.

        Process IDs are returned as positive values; process group IDs are returned as negative values (but see BUGS below). arg is ignored.

      • F_SETSIG - Set the signal sent when input or output becomes possible to the value given in arg.

        A value of zero means to send the default SIGIO signal. Any other value (including SIGIO) is the signal to send instead, and in this case additional info is available to the signal handler if installed with SA_SIGINFO.

        By using F_SETSIG with a nonzero value, and setting SA_SIGINFO for the signal handler (see sigaction(2)), extra information about I/O events is passed to the handler in a siginfo_t structure. If the si_code field indicates the source is SI_SIGIO, the si_fd field gives the file descriptor associated with the event. Otherwise, there is no indication which file descriptors are pending, and you should use the usual mechanisms (select(2), poll(2), read(2) with O_NONBLOCK set etc.) to determine which file descriptors are available for I/O.

        Note that the file descriptor provided in si_fd is the one that was specified during the F_SETSIG operation. This can lead to an unusual corner case. If the file descriptor is duplicated (dup(2) or similar), and the original file descriptor is closed, then I/O events will continue to be generated, but the si_fd field will contain the number of the now closed file descriptor.

        By selecting a real time signal (value ≥ SIGRTMIN), multiple I/O events may be queued using the same signal numbers. (Queuing is dependent on available memory.) Extra information is available if SA_SIGINFO is set for the signal handler, as above.

        Note that Linux imposes a limit on the number of real-time signals that may be queued to a process (see getrlimit(2) and signal(7)) and if this limit is reached, then the kernel reverts to delivering SIGIO, and this signal is delivered to the entire process rather than to a specific thread.

      • F_GETSIG - Return (as the function result) the signal sent when input or output becomes possible.

        A value of zero means SIGIO is sent. Any other value (including SIGIO) is the signal sent instead, and in this case additional info is available to the signal handler if installed with SA_SIGINFO. arg is ignored.

      • F_SETOWN_EX - This operation performs a similar task to F_SETOWN. It allows the caller to direct I/O availability signals to a specific thread, process, or process group.

        The caller specifies the target of signals via arg, which is a pointer to a FOwnerEx structure. The type field has one of the following values, which define how pid is interpreted: F_OWNER_TID, F_OWNER_PID, F_OWNER_PGRP.

      • F_GETOWN_EX - Return the current file descriptor owner settings as defined by a previous F_SETOWN_EX operation.

        The information is returned in the FOwnerEx structure pointed to by arg.

        The type field will have one of the values F_OWNER_TID, F_OWNER_PID, or F_OWNER_PGRP. The pid field is a positive integer representing a thread ID, process ID, or process group ID. See F_SETOWN_EX for more details.

      • F_OFD_GETLK - On input to this call, lock describes an open file description lock we would like to place on the file.

        If the lock could be placed, fcntl() does not actually place it, but returns F_UNLCK in the l_type field of lock and leaves the other fields of the structure unchanged. If one or more incompatible locks would prevent this lock being placed, then details about one of these locks are returned via lock, as described above for F_GETLK.

      • F_OFD_SETLK - Acquire an open file description lock (when l_type is F_RDLCK or F_WRLCK) or release an open file description lock (when l_type is F_UNLCK) on the bytes specified by the l_whence, l_start, and l_len fields of lock.

        If a conflicting lock is held by another process, this call returns -1 and sets errno to EAGAIN.

      • F_OFD_SETLKW - As for F_OFD_SETLK, but if a conflicting lock is held on the file, then wait for that lock to be released.

        If a signal is caught while waiting, then the call is interrupted and (after the signal handler has returned) returns immediately (with return value -1 and errno set to EINTR; see signal(7)).

      • F_SETLEASE - Set or remove a file lease according to which of the following values is specified in the integer arg: F_RDLCK, F_WRLCK, F_UNLCK
      • F_GETLEASE - Indicates what type of lease is associated with the file descriptor fd by returning either F_RDLCK, F_WRLCK, or F_UNLCK, indicating, respectively, a read lease, a write lease, or no lease. arg is ignored.
      • F_NOTIFY - (Linux 2.4 onward) Provide notification when the directory referred to by fd or any of the files that it contains is changed.

        The events to be notified are specified in arg, which is a bit mask specified by ORing together zero or more of the following bits: DN_ACCESS, DN_MODIFY, DN_CREATE, DN_DELETE, DN_RENAME, DN_ATTRIB

        (In order to obtain these definitions, the _GNU_SOURCE feature test macro must be defined before including any header files.)

        Directory notifications are normally "one-shot", and the application must reregister to receive further notifications. Alternatively, if DN_MULTISHOT is included in arg, then notification will remain in effect until explicitly removed.

        A series of F_NOTIFY requests is cumulative, with the events in arg being added to the set already monitored. To disable notification of all events, make an F_NOTIFY call specifying arg as 0.

        Notification occurs via delivery of a signal. The default signal is SIGIO, but this can be changed using the F_SETSIG command to fcntl(). (Note that SIGIO is one of the nonqueuing standard signals; switching to the use of a real-time signal means that multiple notifications can be queued to the process.) In the latter case, the signal handler receives a siginfo_t structure as its second argument (if the handler was established using SA_SIGINFO) and the si_fd field of this structure contains the file descriptor which generated the notification (useful when establishing notification on multiple directories).

        Especially when using DN_MULTISHOT, a real time signal should be used for notification, so that multiple notifications can be queued.

        NOTE: New applications should use the inotify interface (available since kernel 2.6.13), which provides a much superior interface for obtaining notifications of filesystem events. See inotify(7).

      • F_SETPIPE_SZ - Change the capacity of the pipe referred to by fd to be at least arg bytes.

        An unprivileged process can adjust the pipe capacity to any value between the system page size and the limit defined in /proc/sys/fs/pipe-max-size (see proc(5)). Attempts to set the pipe capacity below the page size are silently rounded up to the page size. Attempts by an unprivileged process to set the pipe capacity above the limit in /proc/sys/fs/pipe-max-size yield the error EPERM; a privileged process (CAP_SYS_RESOURCE) can override the limit.

        When allocating the buffer for the pipe, the kernel may use a capacity larger than arg, if that is convenient for the implementation. (In the current implementation, the allocation is the next higher power-of-two page-size multiple of the requested size.) The actual capacity (in bytes) that is set is returned as the function result.

        Attempting to set the pipe capacity smaller than the amount of buffer space currently used to store data produces the error EBUSY.

        Note that because of the way the pages of the pipe buffer are employed when data is written to the pipe, the number of bytes that can be written may be less than the nominal size, depending on the size of the writes.

      • F_GETPIPE_SZ - Return (as the function result) the capacity of the pipe referred to by fd.
      • F_ADD_SEALS - Add the seals given in the bit-mask argument arg to the set of seals of the inode referred to by the file descriptor fd.

        Seals cannot be removed again. Once this call succeeds, the seals are enforced by the kernel immediately. If the current set of seals includes F_SEAL_SEAL (see below), then this call will be rejected with EPERM. Adding a seal that is already set is a no-op, in case F_SEAL_SEAL is not set already. In order to place a seal, the file descriptor fd must be writable.

      • F_GET_SEALS - Return (as the function result) the current set of seals of the inode referred to by fd.

        If no seals are set, 0 is returned. If the file does not support sealing, -1 is returned and errno is set to EINVAL.

      • F_GET_RW_HINT - Returns the value of the read/write hint associated with the underlying inode referred to by fd.
      • F_SET_RW_HINT - Sets the read/write hint value associated with the underlying inode referred to by fd.

        This hint persists until either it is explicitly modified or the underlying filesystem is unmounted.

      • F_GET_FILE_RW_HINT - Returns the value of the read/write hint associated with the open file description referred to by fd.
      • F_SET_FILE_RW_HINT - Sets the read/write hint value associated with the open file description referred to by fd.
      • F_DUPFD_CLOEXEC - As for F_DUPFD, but additionally set the close-on-exec flag for the duplicate file descriptor.

        Specifying this flag permits a program to avoid an additional fcntl() F_SETFD operation to set the FD_CLOEXEC flag. For an explanation of why this flag is useful, see the description of O_CLOEXEC in open(2).

      See Also:

    • F_GETLK

      public static final int F_GETLK
      fcntl(int, int) commands.
      Enum values:
      • F_DUPFD - Duplicate the file descriptor fd using the lowest-numbered available file descriptor greater than or equal to arg.

        This is different from dup2(2), which uses exactly the file descriptor specified.

        On success, the new file descriptor is returned.

        See dup(2) for further details.

      • F_GETFD - Return (as the function result) the file descriptor flags; arg is ignored.
      • F_SETFD - Set the file descriptor flags to the value specified by arg.
      • F_GETFL - Return (as the function result) the file access mode and the file status flags; arg is ignored.
      • F_SETFL - Set the file status flags to the value specified by arg.

        File access mode (O_RDONLY, O_WRONLY, O_RDWR) and file creation flags (i.e., O_CREAT, O_EXCL, O_NOCTTY, O_TRUNC) in arg are ignored. On Linux, this command can change only the O_APPEND, O_ASYNC, O_DIRECT, O_NOATIME, and O_NONBLOCK flags. It is not possible to change the O_DSYNC and O_SYNC flags; see BUGS, below.

      • F_GETLK - On input to this call, lock describes a lock we would like to place on the file.

        If the lock could be placed, fcntl() does not actually place it, but returns F_UNLCK in the l_type field of lock and leaves the other fields of the structure unchanged.

        If one or more incompatible locks would prevent this lock being placed, then fcntl() returns details about one of those locks in the l_type, l_whence, l_start, and l_len fields of lock. If the conflicting lock is a traditional (process-associated) record lock, then the l_pid field is set to the PID of the process holding that lock. If the conflicting lock is an open file description lock, then l_pid is set to -1. Note that the returned information may already be out of date by the time the caller inspects it.

      • F_SETLK - Acquire a lock (when l_type is F_RDLCK or F_WRLCK) or release a lock (when l_type is F_UNLCK) on the bytes specified by the l_whence, l_start, and l_len fields of lock.

        If a conflicting lock is held by another process, this call returns -1 and sets errno to EACCES or EAGAIN. (The error returned in this case differs across implementations, so POSIX requires a portable application to check for both errors.)

      • F_SETLKW - As for F_SETLK, but if a conflicting lock is held on the file, then wait for that lock to be released.

        If a signal is caught while waiting, then the call is interrupted and (after the signal handler has returned) returns immediately (with return value -1 and errno set to EINTR; see signal(7)).

      • F_SETOWN - Set the process ID or process group ID that will receive SIGIO and SIGURG signals for events on the file descriptor fd.

        The target process or process group ID is specified in arg. A process ID is specified as a positive value; a process group ID is specified as a negative value. Most commonly, the calling process specifies itself as the owner (that is, arg is specified as getpid(2)).

        As well as setting the file descriptor owner, one must also enable generation of signals on the file descriptor. This is done by using the fcntl() F_SETFL command to set the O_ASYNC file status flag on the file descriptor. Subsequently, a SIGIO signal is sent whenever input or output becomes possible on the file descriptor. The fcntl() F_SETSIG command can be used to obtain delivery of a signal other than SIGIO.

        Sending a signal to the owner process (group) specified by F_SETOWN is subject to the same permissions checks as are described for kill(2), where the sending process is the one that employs F_SETOWN (but see BUGS below). If this permission check fails, then the signal is silently discarded. Note: The F_SETOWN operation records the caller's credentials at the time of the fcntl() call, and it is these saved credentials that are used for the permission checks.

        If the file descriptor fd refers to a socket, F_SETOWN also selects the recipient of SIGURG signals that are delivered when out-of-band data arrives on that socket. (SIGURG is sent in any situation where select(2) would report the socket as having an "exceptional condition".)

        The following was true in 2.6.x kernels up to and including kernel 2.6.11:

        If a nonzero value is given to F_SETSIG in a multithreaded process running with a threading library that supports thread groups (e.g., NPTL), then a positive value given to F_SETOWN has a different meaning: instead of being a process ID identifying a whole process, it is a thread ID identifying a specific thread within a process. Consequently, it may be necessary to pass F_SETOWN the result of gettid(2) instead of getpid(2) to get sensible results when F_SETSIG is used. (In current Linux threading implementations, a main thread's thread ID is the same as its process ID. This means that a single-threaded program can equally use gettid(2) or getpid(2) in this scenario.) Note, however, that the statements in this paragraph do not apply to the SIGURG signal generated for out-of-band data on a socket: this signal is always sent to either a process or a process group, depending on the value given to F_SETOWN.

        The above behavior was accidentally dropped in Linux 2.6.12, and won't be restored. From Linux 2.6.32 onward, use F_SETOWN_EX to target SIGIO and SIGURG signals at a particular thread.

      • F_GETOWN - Return (as the function result) the process ID or process group ID currently receiving SIGIO and SIGURG signals for events on file descriptor fd.

        Process IDs are returned as positive values; process group IDs are returned as negative values (but see BUGS below). arg is ignored.

      • F_SETSIG - Set the signal sent when input or output becomes possible to the value given in arg.

        A value of zero means to send the default SIGIO signal. Any other value (including SIGIO) is the signal to send instead, and in this case additional info is available to the signal handler if installed with SA_SIGINFO.

        By using F_SETSIG with a nonzero value, and setting SA_SIGINFO for the signal handler (see sigaction(2)), extra information about I/O events is passed to the handler in a siginfo_t structure. If the si_code field indicates the source is SI_SIGIO, the si_fd field gives the file descriptor associated with the event. Otherwise, there is no indication which file descriptors are pending, and you should use the usual mechanisms (select(2), poll(2), read(2) with O_NONBLOCK set etc.) to determine which file descriptors are available for I/O.

        Note that the file descriptor provided in si_fd is the one that was specified during the F_SETSIG operation. This can lead to an unusual corner case. If the file descriptor is duplicated (dup(2) or similar), and the original file descriptor is closed, then I/O events will continue to be generated, but the si_fd field will contain the number of the now closed file descriptor.

        By selecting a real time signal (value ≥ SIGRTMIN), multiple I/O events may be queued using the same signal numbers. (Queuing is dependent on available memory.) Extra information is available if SA_SIGINFO is set for the signal handler, as above.

        Note that Linux imposes a limit on the number of real-time signals that may be queued to a process (see getrlimit(2) and signal(7)) and if this limit is reached, then the kernel reverts to delivering SIGIO, and this signal is delivered to the entire process rather than to a specific thread.

      • F_GETSIG - Return (as the function result) the signal sent when input or output becomes possible.

        A value of zero means SIGIO is sent. Any other value (including SIGIO) is the signal sent instead, and in this case additional info is available to the signal handler if installed with SA_SIGINFO. arg is ignored.

      • F_SETOWN_EX - This operation performs a similar task to F_SETOWN. It allows the caller to direct I/O availability signals to a specific thread, process, or process group.

        The caller specifies the target of signals via arg, which is a pointer to a FOwnerEx structure. The type field has one of the following values, which define how pid is interpreted: F_OWNER_TID, F_OWNER_PID, F_OWNER_PGRP.

      • F_GETOWN_EX - Return the current file descriptor owner settings as defined by a previous F_SETOWN_EX operation.

        The information is returned in the FOwnerEx structure pointed to by arg.

        The type field will have one of the values F_OWNER_TID, F_OWNER_PID, or F_OWNER_PGRP. The pid field is a positive integer representing a thread ID, process ID, or process group ID. See F_SETOWN_EX for more details.

      • F_OFD_GETLK - On input to this call, lock describes an open file description lock we would like to place on the file.

        If the lock could be placed, fcntl() does not actually place it, but returns F_UNLCK in the l_type field of lock and leaves the other fields of the structure unchanged. If one or more incompatible locks would prevent this lock being placed, then details about one of these locks are returned via lock, as described above for F_GETLK.

      • F_OFD_SETLK - Acquire an open file description lock (when l_type is F_RDLCK or F_WRLCK) or release an open file description lock (when l_type is F_UNLCK) on the bytes specified by the l_whence, l_start, and l_len fields of lock.

        If a conflicting lock is held by another process, this call returns -1 and sets errno to EAGAIN.

      • F_OFD_SETLKW - As for F_OFD_SETLK, but if a conflicting lock is held on the file, then wait for that lock to be released.

        If a signal is caught while waiting, then the call is interrupted and (after the signal handler has returned) returns immediately (with return value -1 and errno set to EINTR; see signal(7)).

      • F_SETLEASE - Set or remove a file lease according to which of the following values is specified in the integer arg: F_RDLCK, F_WRLCK, F_UNLCK
      • F_GETLEASE - Indicates what type of lease is associated with the file descriptor fd by returning either F_RDLCK, F_WRLCK, or F_UNLCK, indicating, respectively, a read lease, a write lease, or no lease. arg is ignored.
      • F_NOTIFY - (Linux 2.4 onward) Provide notification when the directory referred to by fd or any of the files that it contains is changed.

        The events to be notified are specified in arg, which is a bit mask specified by ORing together zero or more of the following bits: DN_ACCESS, DN_MODIFY, DN_CREATE, DN_DELETE, DN_RENAME, DN_ATTRIB

        (In order to obtain these definitions, the _GNU_SOURCE feature test macro must be defined before including any header files.)

        Directory notifications are normally "one-shot", and the application must reregister to receive further notifications. Alternatively, if DN_MULTISHOT is included in arg, then notification will remain in effect until explicitly removed.

        A series of F_NOTIFY requests is cumulative, with the events in arg being added to the set already monitored. To disable notification of all events, make an F_NOTIFY call specifying arg as 0.

        Notification occurs via delivery of a signal. The default signal is SIGIO, but this can be changed using the F_SETSIG command to fcntl(). (Note that SIGIO is one of the nonqueuing standard signals; switching to the use of a real-time signal means that multiple notifications can be queued to the process.) In the latter case, the signal handler receives a siginfo_t structure as its second argument (if the handler was established using SA_SIGINFO) and the si_fd field of this structure contains the file descriptor which generated the notification (useful when establishing notification on multiple directories).

        Especially when using DN_MULTISHOT, a real time signal should be used for notification, so that multiple notifications can be queued.

        NOTE: New applications should use the inotify interface (available since kernel 2.6.13), which provides a much superior interface for obtaining notifications of filesystem events. See inotify(7).

      • F_SETPIPE_SZ - Change the capacity of the pipe referred to by fd to be at least arg bytes.

        An unprivileged process can adjust the pipe capacity to any value between the system page size and the limit defined in /proc/sys/fs/pipe-max-size (see proc(5)). Attempts to set the pipe capacity below the page size are silently rounded up to the page size. Attempts by an unprivileged process to set the pipe capacity above the limit in /proc/sys/fs/pipe-max-size yield the error EPERM; a privileged process (CAP_SYS_RESOURCE) can override the limit.

        When allocating the buffer for the pipe, the kernel may use a capacity larger than arg, if that is convenient for the implementation. (In the current implementation, the allocation is the next higher power-of-two page-size multiple of the requested size.) The actual capacity (in bytes) that is set is returned as the function result.

        Attempting to set the pipe capacity smaller than the amount of buffer space currently used to store data produces the error EBUSY.

        Note that because of the way the pages of the pipe buffer are employed when data is written to the pipe, the number of bytes that can be written may be less than the nominal size, depending on the size of the writes.

      • F_GETPIPE_SZ - Return (as the function result) the capacity of the pipe referred to by fd.
      • F_ADD_SEALS - Add the seals given in the bit-mask argument arg to the set of seals of the inode referred to by the file descriptor fd.

        Seals cannot be removed again. Once this call succeeds, the seals are enforced by the kernel immediately. If the current set of seals includes F_SEAL_SEAL (see below), then this call will be rejected with EPERM. Adding a seal that is already set is a no-op, in case F_SEAL_SEAL is not set already. In order to place a seal, the file descriptor fd must be writable.

      • F_GET_SEALS - Return (as the function result) the current set of seals of the inode referred to by fd.

        If no seals are set, 0 is returned. If the file does not support sealing, -1 is returned and errno is set to EINVAL.

      • F_GET_RW_HINT - Returns the value of the read/write hint associated with the underlying inode referred to by fd.
      • F_SET_RW_HINT - Sets the read/write hint value associated with the underlying inode referred to by fd.

        This hint persists until either it is explicitly modified or the underlying filesystem is unmounted.

      • F_GET_FILE_RW_HINT - Returns the value of the read/write hint associated with the open file description referred to by fd.
      • F_SET_FILE_RW_HINT - Sets the read/write hint value associated with the open file description referred to by fd.
      • F_DUPFD_CLOEXEC - As for F_DUPFD, but additionally set the close-on-exec flag for the duplicate file descriptor.

        Specifying this flag permits a program to avoid an additional fcntl() F_SETFD operation to set the FD_CLOEXEC flag. For an explanation of why this flag is useful, see the description of O_CLOEXEC in open(2).

      See Also:

    • F_SETLK

      public static final int F_SETLK
      fcntl(int, int) commands.
      Enum values:
      • F_DUPFD - Duplicate the file descriptor fd using the lowest-numbered available file descriptor greater than or equal to arg.

        This is different from dup2(2), which uses exactly the file descriptor specified.

        On success, the new file descriptor is returned.

        See dup(2) for further details.

      • F_GETFD - Return (as the function result) the file descriptor flags; arg is ignored.
      • F_SETFD - Set the file descriptor flags to the value specified by arg.
      • F_GETFL - Return (as the function result) the file access mode and the file status flags; arg is ignored.
      • F_SETFL - Set the file status flags to the value specified by arg.

        File access mode (O_RDONLY, O_WRONLY, O_RDWR) and file creation flags (i.e., O_CREAT, O_EXCL, O_NOCTTY, O_TRUNC) in arg are ignored. On Linux, this command can change only the O_APPEND, O_ASYNC, O_DIRECT, O_NOATIME, and O_NONBLOCK flags. It is not possible to change the O_DSYNC and O_SYNC flags; see BUGS, below.

      • F_GETLK - On input to this call, lock describes a lock we would like to place on the file.

        If the lock could be placed, fcntl() does not actually place it, but returns F_UNLCK in the l_type field of lock and leaves the other fields of the structure unchanged.

        If one or more incompatible locks would prevent this lock being placed, then fcntl() returns details about one of those locks in the l_type, l_whence, l_start, and l_len fields of lock. If the conflicting lock is a traditional (process-associated) record lock, then the l_pid field is set to the PID of the process holding that lock. If the conflicting lock is an open file description lock, then l_pid is set to -1. Note that the returned information may already be out of date by the time the caller inspects it.

      • F_SETLK - Acquire a lock (when l_type is F_RDLCK or F_WRLCK) or release a lock (when l_type is F_UNLCK) on the bytes specified by the l_whence, l_start, and l_len fields of lock.

        If a conflicting lock is held by another process, this call returns -1 and sets errno to EACCES or EAGAIN. (The error returned in this case differs across implementations, so POSIX requires a portable application to check for both errors.)

      • F_SETLKW - As for F_SETLK, but if a conflicting lock is held on the file, then wait for that lock to be released.

        If a signal is caught while waiting, then the call is interrupted and (after the signal handler has returned) returns immediately (with return value -1 and errno set to EINTR; see signal(7)).

      • F_SETOWN - Set the process ID or process group ID that will receive SIGIO and SIGURG signals for events on the file descriptor fd.

        The target process or process group ID is specified in arg. A process ID is specified as a positive value; a process group ID is specified as a negative value. Most commonly, the calling process specifies itself as the owner (that is, arg is specified as getpid(2)).

        As well as setting the file descriptor owner, one must also enable generation of signals on the file descriptor. This is done by using the fcntl() F_SETFL command to set the O_ASYNC file status flag on the file descriptor. Subsequently, a SIGIO signal is sent whenever input or output becomes possible on the file descriptor. The fcntl() F_SETSIG command can be used to obtain delivery of a signal other than SIGIO.

        Sending a signal to the owner process (group) specified by F_SETOWN is subject to the same permissions checks as are described for kill(2), where the sending process is the one that employs F_SETOWN (but see BUGS below). If this permission check fails, then the signal is silently discarded. Note: The F_SETOWN operation records the caller's credentials at the time of the fcntl() call, and it is these saved credentials that are used for the permission checks.

        If the file descriptor fd refers to a socket, F_SETOWN also selects the recipient of SIGURG signals that are delivered when out-of-band data arrives on that socket. (SIGURG is sent in any situation where select(2) would report the socket as having an "exceptional condition".)

        The following was true in 2.6.x kernels up to and including kernel 2.6.11:

        If a nonzero value is given to F_SETSIG in a multithreaded process running with a threading library that supports thread groups (e.g., NPTL), then a positive value given to F_SETOWN has a different meaning: instead of being a process ID identifying a whole process, it is a thread ID identifying a specific thread within a process. Consequently, it may be necessary to pass F_SETOWN the result of gettid(2) instead of getpid(2) to get sensible results when F_SETSIG is used. (In current Linux threading implementations, a main thread's thread ID is the same as its process ID. This means that a single-threaded program can equally use gettid(2) or getpid(2) in this scenario.) Note, however, that the statements in this paragraph do not apply to the SIGURG signal generated for out-of-band data on a socket: this signal is always sent to either a process or a process group, depending on the value given to F_SETOWN.

        The above behavior was accidentally dropped in Linux 2.6.12, and won't be restored. From Linux 2.6.32 onward, use F_SETOWN_EX to target SIGIO and SIGURG signals at a particular thread.

      • F_GETOWN - Return (as the function result) the process ID or process group ID currently receiving SIGIO and SIGURG signals for events on file descriptor fd.

        Process IDs are returned as positive values; process group IDs are returned as negative values (but see BUGS below). arg is ignored.

      • F_SETSIG - Set the signal sent when input or output becomes possible to the value given in arg.

        A value of zero means to send the default SIGIO signal. Any other value (including SIGIO) is the signal to send instead, and in this case additional info is available to the signal handler if installed with SA_SIGINFO.

        By using F_SETSIG with a nonzero value, and setting SA_SIGINFO for the signal handler (see sigaction(2)), extra information about I/O events is passed to the handler in a siginfo_t structure. If the si_code field indicates the source is SI_SIGIO, the si_fd field gives the file descriptor associated with the event. Otherwise, there is no indication which file descriptors are pending, and you should use the usual mechanisms (select(2), poll(2), read(2) with O_NONBLOCK set etc.) to determine which file descriptors are available for I/O.

        Note that the file descriptor provided in si_fd is the one that was specified during the F_SETSIG operation. This can lead to an unusual corner case. If the file descriptor is duplicated (dup(2) or similar), and the original file descriptor is closed, then I/O events will continue to be generated, but the si_fd field will contain the number of the now closed file descriptor.

        By selecting a real time signal (value ≥ SIGRTMIN), multiple I/O events may be queued using the same signal numbers. (Queuing is dependent on available memory.) Extra information is available if SA_SIGINFO is set for the signal handler, as above.

        Note that Linux imposes a limit on the number of real-time signals that may be queued to a process (see getrlimit(2) and signal(7)) and if this limit is reached, then the kernel reverts to delivering SIGIO, and this signal is delivered to the entire process rather than to a specific thread.

      • F_GETSIG - Return (as the function result) the signal sent when input or output becomes possible.

        A value of zero means SIGIO is sent. Any other value (including SIGIO) is the signal sent instead, and in this case additional info is available to the signal handler if installed with SA_SIGINFO. arg is ignored.

      • F_SETOWN_EX - This operation performs a similar task to F_SETOWN. It allows the caller to direct I/O availability signals to a specific thread, process, or process group.

        The caller specifies the target of signals via arg, which is a pointer to a FOwnerEx structure. The type field has one of the following values, which define how pid is interpreted: F_OWNER_TID, F_OWNER_PID, F_OWNER_PGRP.

      • F_GETOWN_EX - Return the current file descriptor owner settings as defined by a previous F_SETOWN_EX operation.

        The information is returned in the FOwnerEx structure pointed to by arg.

        The type field will have one of the values F_OWNER_TID, F_OWNER_PID, or F_OWNER_PGRP. The pid field is a positive integer representing a thread ID, process ID, or process group ID. See F_SETOWN_EX for more details.

      • F_OFD_GETLK - On input to this call, lock describes an open file description lock we would like to place on the file.

        If the lock could be placed, fcntl() does not actually place it, but returns F_UNLCK in the l_type field of lock and leaves the other fields of the structure unchanged. If one or more incompatible locks would prevent this lock being placed, then details about one of these locks are returned via lock, as described above for F_GETLK.

      • F_OFD_SETLK - Acquire an open file description lock (when l_type is F_RDLCK or F_WRLCK) or release an open file description lock (when l_type is F_UNLCK) on the bytes specified by the l_whence, l_start, and l_len fields of lock.

        If a conflicting lock is held by another process, this call returns -1 and sets errno to EAGAIN.

      • F_OFD_SETLKW - As for F_OFD_SETLK, but if a conflicting lock is held on the file, then wait for that lock to be released.

        If a signal is caught while waiting, then the call is interrupted and (after the signal handler has returned) returns immediately (with return value -1 and errno set to EINTR; see signal(7)).

      • F_SETLEASE - Set or remove a file lease according to which of the following values is specified in the integer arg: F_RDLCK, F_WRLCK, F_UNLCK
      • F_GETLEASE - Indicates what type of lease is associated with the file descriptor fd by returning either F_RDLCK, F_WRLCK, or F_UNLCK, indicating, respectively, a read lease, a write lease, or no lease. arg is ignored.
      • F_NOTIFY - (Linux 2.4 onward) Provide notification when the directory referred to by fd or any of the files that it contains is changed.

        The events to be notified are specified in arg, which is a bit mask specified by ORing together zero or more of the following bits: DN_ACCESS, DN_MODIFY, DN_CREATE, DN_DELETE, DN_RENAME, DN_ATTRIB

        (In order to obtain these definitions, the _GNU_SOURCE feature test macro must be defined before including any header files.)

        Directory notifications are normally "one-shot", and the application must reregister to receive further notifications. Alternatively, if DN_MULTISHOT is included in arg, then notification will remain in effect until explicitly removed.

        A series of F_NOTIFY requests is cumulative, with the events in arg being added to the set already monitored. To disable notification of all events, make an F_NOTIFY call specifying arg as 0.

        Notification occurs via delivery of a signal. The default signal is SIGIO, but this can be changed using the F_SETSIG command to fcntl(). (Note that SIGIO is one of the nonqueuing standard signals; switching to the use of a real-time signal means that multiple notifications can be queued to the process.) In the latter case, the signal handler receives a siginfo_t structure as its second argument (if the handler was established using SA_SIGINFO) and the si_fd field of this structure contains the file descriptor which generated the notification (useful when establishing notification on multiple directories).

        Especially when using DN_MULTISHOT, a real time signal should be used for notification, so that multiple notifications can be queued.

        NOTE: New applications should use the inotify interface (available since kernel 2.6.13), which provides a much superior interface for obtaining notifications of filesystem events. See inotify(7).

      • F_SETPIPE_SZ - Change the capacity of the pipe referred to by fd to be at least arg bytes.

        An unprivileged process can adjust the pipe capacity to any value between the system page size and the limit defined in /proc/sys/fs/pipe-max-size (see proc(5)). Attempts to set the pipe capacity below the page size are silently rounded up to the page size. Attempts by an unprivileged process to set the pipe capacity above the limit in /proc/sys/fs/pipe-max-size yield the error EPERM; a privileged process (CAP_SYS_RESOURCE) can override the limit.

        When allocating the buffer for the pipe, the kernel may use a capacity larger than arg, if that is convenient for the implementation. (In the current implementation, the allocation is the next higher power-of-two page-size multiple of the requested size.) The actual capacity (in bytes) that is set is returned as the function result.

        Attempting to set the pipe capacity smaller than the amount of buffer space currently used to store data produces the error EBUSY.

        Note that because of the way the pages of the pipe buffer are employed when data is written to the pipe, the number of bytes that can be written may be less than the nominal size, depending on the size of the writes.

      • F_GETPIPE_SZ - Return (as the function result) the capacity of the pipe referred to by fd.
      • F_ADD_SEALS - Add the seals given in the bit-mask argument arg to the set of seals of the inode referred to by the file descriptor fd.

        Seals cannot be removed again. Once this call succeeds, the seals are enforced by the kernel immediately. If the current set of seals includes F_SEAL_SEAL (see below), then this call will be rejected with EPERM. Adding a seal that is already set is a no-op, in case F_SEAL_SEAL is not set already. In order to place a seal, the file descriptor fd must be writable.

      • F_GET_SEALS - Return (as the function result) the current set of seals of the inode referred to by fd.

        If no seals are set, 0 is returned. If the file does not support sealing, -1 is returned and errno is set to EINVAL.

      • F_GET_RW_HINT - Returns the value of the read/write hint associated with the underlying inode referred to by fd.
      • F_SET_RW_HINT - Sets the read/write hint value associated with the underlying inode referred to by fd.

        This hint persists until either it is explicitly modified or the underlying filesystem is unmounted.

      • F_GET_FILE_RW_HINT - Returns the value of the read/write hint associated with the open file description referred to by fd.
      • F_SET_FILE_RW_HINT - Sets the read/write hint value associated with the open file description referred to by fd.
      • F_DUPFD_CLOEXEC - As for F_DUPFD, but additionally set the close-on-exec flag for the duplicate file descriptor.

        Specifying this flag permits a program to avoid an additional fcntl() F_SETFD operation to set the FD_CLOEXEC flag. For an explanation of why this flag is useful, see the description of O_CLOEXEC in open(2).

      See Also:

    • F_SETLKW

      public static final int F_SETLKW
      fcntl(int, int) commands.
      Enum values:
      • F_DUPFD - Duplicate the file descriptor fd using the lowest-numbered available file descriptor greater than or equal to arg.

        This is different from dup2(2), which uses exactly the file descriptor specified.

        On success, the new file descriptor is returned.

        See dup(2) for further details.

      • F_GETFD - Return (as the function result) the file descriptor flags; arg is ignored.
      • F_SETFD - Set the file descriptor flags to the value specified by arg.
      • F_GETFL - Return (as the function result) the file access mode and the file status flags; arg is ignored.
      • F_SETFL - Set the file status flags to the value specified by arg.

        File access mode (O_RDONLY, O_WRONLY, O_RDWR) and file creation flags (i.e., O_CREAT, O_EXCL, O_NOCTTY, O_TRUNC) in arg are ignored. On Linux, this command can change only the O_APPEND, O_ASYNC, O_DIRECT, O_NOATIME, and O_NONBLOCK flags. It is not possible to change the O_DSYNC and O_SYNC flags; see BUGS, below.

      • F_GETLK - On input to this call, lock describes a lock we would like to place on the file.

        If the lock could be placed, fcntl() does not actually place it, but returns F_UNLCK in the l_type field of lock and leaves the other fields of the structure unchanged.

        If one or more incompatible locks would prevent this lock being placed, then fcntl() returns details about one of those locks in the l_type, l_whence, l_start, and l_len fields of lock. If the conflicting lock is a traditional (process-associated) record lock, then the l_pid field is set to the PID of the process holding that lock. If the conflicting lock is an open file description lock, then l_pid is set to -1. Note that the returned information may already be out of date by the time the caller inspects it.

      • F_SETLK - Acquire a lock (when l_type is F_RDLCK or F_WRLCK) or release a lock (when l_type is F_UNLCK) on the bytes specified by the l_whence, l_start, and l_len fields of lock.

        If a conflicting lock is held by another process, this call returns -1 and sets errno to EACCES or EAGAIN. (The error returned in this case differs across implementations, so POSIX requires a portable application to check for both errors.)

      • F_SETLKW - As for F_SETLK, but if a conflicting lock is held on the file, then wait for that lock to be released.

        If a signal is caught while waiting, then the call is interrupted and (after the signal handler has returned) returns immediately (with return value -1 and errno set to EINTR; see signal(7)).

      • F_SETOWN - Set the process ID or process group ID that will receive SIGIO and SIGURG signals for events on the file descriptor fd.

        The target process or process group ID is specified in arg. A process ID is specified as a positive value; a process group ID is specified as a negative value. Most commonly, the calling process specifies itself as the owner (that is, arg is specified as getpid(2)).

        As well as setting the file descriptor owner, one must also enable generation of signals on the file descriptor. This is done by using the fcntl() F_SETFL command to set the O_ASYNC file status flag on the file descriptor. Subsequently, a SIGIO signal is sent whenever input or output becomes possible on the file descriptor. The fcntl() F_SETSIG command can be used to obtain delivery of a signal other than SIGIO.

        Sending a signal to the owner process (group) specified by F_SETOWN is subject to the same permissions checks as are described for kill(2), where the sending process is the one that employs F_SETOWN (but see BUGS below). If this permission check fails, then the signal is silently discarded. Note: The F_SETOWN operation records the caller's credentials at the time of the fcntl() call, and it is these saved credentials that are used for the permission checks.

        If the file descriptor fd refers to a socket, F_SETOWN also selects the recipient of SIGURG signals that are delivered when out-of-band data arrives on that socket. (SIGURG is sent in any situation where select(2) would report the socket as having an "exceptional condition".)

        The following was true in 2.6.x kernels up to and including kernel 2.6.11:

        If a nonzero value is given to F_SETSIG in a multithreaded process running with a threading library that supports thread groups (e.g., NPTL), then a positive value given to F_SETOWN has a different meaning: instead of being a process ID identifying a whole process, it is a thread ID identifying a specific thread within a process. Consequently, it may be necessary to pass F_SETOWN the result of gettid(2) instead of getpid(2) to get sensible results when F_SETSIG is used. (In current Linux threading implementations, a main thread's thread ID is the same as its process ID. This means that a single-threaded program can equally use gettid(2) or getpid(2) in this scenario.) Note, however, that the statements in this paragraph do not apply to the SIGURG signal generated for out-of-band data on a socket: this signal is always sent to either a process or a process group, depending on the value given to F_SETOWN.

        The above behavior was accidentally dropped in Linux 2.6.12, and won't be restored. From Linux 2.6.32 onward, use F_SETOWN_EX to target SIGIO and SIGURG signals at a particular thread.

      • F_GETOWN - Return (as the function result) the process ID or process group ID currently receiving SIGIO and SIGURG signals for events on file descriptor fd.

        Process IDs are returned as positive values; process group IDs are returned as negative values (but see BUGS below). arg is ignored.

      • F_SETSIG - Set the signal sent when input or output becomes possible to the value given in arg.

        A value of zero means to send the default SIGIO signal. Any other value (including SIGIO) is the signal to send instead, and in this case additional info is available to the signal handler if installed with SA_SIGINFO.

        By using F_SETSIG with a nonzero value, and setting SA_SIGINFO for the signal handler (see sigaction(2)), extra information about I/O events is passed to the handler in a siginfo_t structure. If the si_code field indicates the source is SI_SIGIO, the si_fd field gives the file descriptor associated with the event. Otherwise, there is no indication which file descriptors are pending, and you should use the usual mechanisms (select(2), poll(2), read(2) with O_NONBLOCK set etc.) to determine which file descriptors are available for I/O.

        Note that the file descriptor provided in si_fd is the one that was specified during the F_SETSIG operation. This can lead to an unusual corner case. If the file descriptor is duplicated (dup(2) or similar), and the original file descriptor is closed, then I/O events will continue to be generated, but the si_fd field will contain the number of the now closed file descriptor.

        By selecting a real time signal (value ≥ SIGRTMIN), multiple I/O events may be queued using the same signal numbers. (Queuing is dependent on available memory.) Extra information is available if SA_SIGINFO is set for the signal handler, as above.

        Note that Linux imposes a limit on the number of real-time signals that may be queued to a process (see getrlimit(2) and signal(7)) and if this limit is reached, then the kernel reverts to delivering SIGIO, and this signal is delivered to the entire process rather than to a specific thread.

      • F_GETSIG - Return (as the function result) the signal sent when input or output becomes possible.

        A value of zero means SIGIO is sent. Any other value (including SIGIO) is the signal sent instead, and in this case additional info is available to the signal handler if installed with SA_SIGINFO. arg is ignored.

      • F_SETOWN_EX - This operation performs a similar task to F_SETOWN. It allows the caller to direct I/O availability signals to a specific thread, process, or process group.

        The caller specifies the target of signals via arg, which is a pointer to a FOwnerEx structure. The type field has one of the following values, which define how pid is interpreted: F_OWNER_TID, F_OWNER_PID, F_OWNER_PGRP.

      • F_GETOWN_EX - Return the current file descriptor owner settings as defined by a previous F_SETOWN_EX operation.

        The information is returned in the FOwnerEx structure pointed to by arg.

        The type field will have one of the values F_OWNER_TID, F_OWNER_PID, or F_OWNER_PGRP. The pid field is a positive integer representing a thread ID, process ID, or process group ID. See F_SETOWN_EX for more details.

      • F_OFD_GETLK - On input to this call, lock describes an open file description lock we would like to place on the file.

        If the lock could be placed, fcntl() does not actually place it, but returns F_UNLCK in the l_type field of lock and leaves the other fields of the structure unchanged. If one or more incompatible locks would prevent this lock being placed, then details about one of these locks are returned via lock, as described above for F_GETLK.

      • F_OFD_SETLK - Acquire an open file description lock (when l_type is F_RDLCK or F_WRLCK) or release an open file description lock (when l_type is F_UNLCK) on the bytes specified by the l_whence, l_start, and l_len fields of lock.

        If a conflicting lock is held by another process, this call returns -1 and sets errno to EAGAIN.

      • F_OFD_SETLKW - As for F_OFD_SETLK, but if a conflicting lock is held on the file, then wait for that lock to be released.

        If a signal is caught while waiting, then the call is interrupted and (after the signal handler has returned) returns immediately (with return value -1 and errno set to EINTR; see signal(7)).

      • F_SETLEASE - Set or remove a file lease according to which of the following values is specified in the integer arg: F_RDLCK, F_WRLCK, F_UNLCK
      • F_GETLEASE - Indicates what type of lease is associated with the file descriptor fd by returning either F_RDLCK, F_WRLCK, or F_UNLCK, indicating, respectively, a read lease, a write lease, or no lease. arg is ignored.
      • F_NOTIFY - (Linux 2.4 onward) Provide notification when the directory referred to by fd or any of the files that it contains is changed.

        The events to be notified are specified in arg, which is a bit mask specified by ORing together zero or more of the following bits: DN_ACCESS, DN_MODIFY, DN_CREATE, DN_DELETE, DN_RENAME, DN_ATTRIB

        (In order to obtain these definitions, the _GNU_SOURCE feature test macro must be defined before including any header files.)

        Directory notifications are normally "one-shot", and the application must reregister to receive further notifications. Alternatively, if DN_MULTISHOT is included in arg, then notification will remain in effect until explicitly removed.

        A series of F_NOTIFY requests is cumulative, with the events in arg being added to the set already monitored. To disable notification of all events, make an F_NOTIFY call specifying arg as 0.

        Notification occurs via delivery of a signal. The default signal is SIGIO, but this can be changed using the F_SETSIG command to fcntl(). (Note that SIGIO is one of the nonqueuing standard signals; switching to the use of a real-time signal means that multiple notifications can be queued to the process.) In the latter case, the signal handler receives a siginfo_t structure as its second argument (if the handler was established using SA_SIGINFO) and the si_fd field of this structure contains the file descriptor which generated the notification (useful when establishing notification on multiple directories).

        Especially when using DN_MULTISHOT, a real time signal should be used for notification, so that multiple notifications can be queued.

        NOTE: New applications should use the inotify interface (available since kernel 2.6.13), which provides a much superior interface for obtaining notifications of filesystem events. See inotify(7).

      • F_SETPIPE_SZ - Change the capacity of the pipe referred to by fd to be at least arg bytes.

        An unprivileged process can adjust the pipe capacity to any value between the system page size and the limit defined in /proc/sys/fs/pipe-max-size (see proc(5)). Attempts to set the pipe capacity below the page size are silently rounded up to the page size. Attempts by an unprivileged process to set the pipe capacity above the limit in /proc/sys/fs/pipe-max-size yield the error EPERM; a privileged process (CAP_SYS_RESOURCE) can override the limit.

        When allocating the buffer for the pipe, the kernel may use a capacity larger than arg, if that is convenient for the implementation. (In the current implementation, the allocation is the next higher power-of-two page-size multiple of the requested size.) The actual capacity (in bytes) that is set is returned as the function result.

        Attempting to set the pipe capacity smaller than the amount of buffer space currently used to store data produces the error EBUSY.

        Note that because of the way the pages of the pipe buffer are employed when data is written to the pipe, the number of bytes that can be written may be less than the nominal size, depending on the size of the writes.

      • F_GETPIPE_SZ - Return (as the function result) the capacity of the pipe referred to by fd.
      • F_ADD_SEALS - Add the seals given in the bit-mask argument arg to the set of seals of the inode referred to by the file descriptor fd.

        Seals cannot be removed again. Once this call succeeds, the seals are enforced by the kernel immediately. If the current set of seals includes F_SEAL_SEAL (see below), then this call will be rejected with EPERM. Adding a seal that is already set is a no-op, in case F_SEAL_SEAL is not set already. In order to place a seal, the file descriptor fd must be writable.

      • F_GET_SEALS - Return (as the function result) the current set of seals of the inode referred to by fd.

        If no seals are set, 0 is returned. If the file does not support sealing, -1 is returned and errno is set to EINVAL.

      • F_GET_RW_HINT - Returns the value of the read/write hint associated with the underlying inode referred to by fd.
      • F_SET_RW_HINT - Sets the read/write hint value associated with the underlying inode referred to by fd.

        This hint persists until either it is explicitly modified or the underlying filesystem is unmounted.

      • F_GET_FILE_RW_HINT - Returns the value of the read/write hint associated with the open file description referred to by fd.
      • F_SET_FILE_RW_HINT - Sets the read/write hint value associated with the open file description referred to by fd.
      • F_DUPFD_CLOEXEC - As for F_DUPFD, but additionally set the close-on-exec flag for the duplicate file descriptor.

        Specifying this flag permits a program to avoid an additional fcntl() F_SETFD operation to set the FD_CLOEXEC flag. For an explanation of why this flag is useful, see the description of O_CLOEXEC in open(2).

      See Also:

    • F_SETOWN

      public static final int F_SETOWN
      fcntl(int, int) commands.
      Enum values:
      • F_DUPFD - Duplicate the file descriptor fd using the lowest-numbered available file descriptor greater than or equal to arg.

        This is different from dup2(2), which uses exactly the file descriptor specified.

        On success, the new file descriptor is returned.

        See dup(2) for further details.

      • F_GETFD - Return (as the function result) the file descriptor flags; arg is ignored.
      • F_SETFD - Set the file descriptor flags to the value specified by arg.
      • F_GETFL - Return (as the function result) the file access mode and the file status flags; arg is ignored.
      • F_SETFL - Set the file status flags to the value specified by arg.

        File access mode (O_RDONLY, O_WRONLY, O_RDWR) and file creation flags (i.e., O_CREAT, O_EXCL, O_NOCTTY, O_TRUNC) in arg are ignored. On Linux, this command can change only the O_APPEND, O_ASYNC, O_DIRECT, O_NOATIME, and O_NONBLOCK flags. It is not possible to change the O_DSYNC and O_SYNC flags; see BUGS, below.

      • F_GETLK - On input to this call, lock describes a lock we would like to place on the file.

        If the lock could be placed, fcntl() does not actually place it, but returns F_UNLCK in the l_type field of lock and leaves the other fields of the structure unchanged.

        If one or more incompatible locks would prevent this lock being placed, then fcntl() returns details about one of those locks in the l_type, l_whence, l_start, and l_len fields of lock. If the conflicting lock is a traditional (process-associated) record lock, then the l_pid field is set to the PID of the process holding that lock. If the conflicting lock is an open file description lock, then l_pid is set to -1. Note that the returned information may already be out of date by the time the caller inspects it.

      • F_SETLK - Acquire a lock (when l_type is F_RDLCK or F_WRLCK) or release a lock (when l_type is F_UNLCK) on the bytes specified by the l_whence, l_start, and l_len fields of lock.

        If a conflicting lock is held by another process, this call returns -1 and sets errno to EACCES or EAGAIN. (The error returned in this case differs across implementations, so POSIX requires a portable application to check for both errors.)

      • F_SETLKW - As for F_SETLK, but if a conflicting lock is held on the file, then wait for that lock to be released.

        If a signal is caught while waiting, then the call is interrupted and (after the signal handler has returned) returns immediately (with return value -1 and errno set to EINTR; see signal(7)).

      • F_SETOWN - Set the process ID or process group ID that will receive SIGIO and SIGURG signals for events on the file descriptor fd.

        The target process or process group ID is specified in arg. A process ID is specified as a positive value; a process group ID is specified as a negative value. Most commonly, the calling process specifies itself as the owner (that is, arg is specified as getpid(2)).

        As well as setting the file descriptor owner, one must also enable generation of signals on the file descriptor. This is done by using the fcntl() F_SETFL command to set the O_ASYNC file status flag on the file descriptor. Subsequently, a SIGIO signal is sent whenever input or output becomes possible on the file descriptor. The fcntl() F_SETSIG command can be used to obtain delivery of a signal other than SIGIO.

        Sending a signal to the owner process (group) specified by F_SETOWN is subject to the same permissions checks as are described for kill(2), where the sending process is the one that employs F_SETOWN (but see BUGS below). If this permission check fails, then the signal is silently discarded. Note: The F_SETOWN operation records the caller's credentials at the time of the fcntl() call, and it is these saved credentials that are used for the permission checks.

        If the file descriptor fd refers to a socket, F_SETOWN also selects the recipient of SIGURG signals that are delivered when out-of-band data arrives on that socket. (SIGURG is sent in any situation where select(2) would report the socket as having an "exceptional condition".)

        The following was true in 2.6.x kernels up to and including kernel 2.6.11:

        If a nonzero value is given to F_SETSIG in a multithreaded process running with a threading library that supports thread groups (e.g., NPTL), then a positive value given to F_SETOWN has a different meaning: instead of being a process ID identifying a whole process, it is a thread ID identifying a specific thread within a process. Consequently, it may be necessary to pass F_SETOWN the result of gettid(2) instead of getpid(2) to get sensible results when F_SETSIG is used. (In current Linux threading implementations, a main thread's thread ID is the same as its process ID. This means that a single-threaded program can equally use gettid(2) or getpid(2) in this scenario.) Note, however, that the statements in this paragraph do not apply to the SIGURG signal generated for out-of-band data on a socket: this signal is always sent to either a process or a process group, depending on the value given to F_SETOWN.

        The above behavior was accidentally dropped in Linux 2.6.12, and won't be restored. From Linux 2.6.32 onward, use F_SETOWN_EX to target SIGIO and SIGURG signals at a particular thread.

      • F_GETOWN - Return (as the function result) the process ID or process group ID currently receiving SIGIO and SIGURG signals for events on file descriptor fd.

        Process IDs are returned as positive values; process group IDs are returned as negative values (but see BUGS below). arg is ignored.

      • F_SETSIG - Set the signal sent when input or output becomes possible to the value given in arg.

        A value of zero means to send the default SIGIO signal. Any other value (including SIGIO) is the signal to send instead, and in this case additional info is available to the signal handler if installed with SA_SIGINFO.

        By using F_SETSIG with a nonzero value, and setting SA_SIGINFO for the signal handler (see sigaction(2)), extra information about I/O events is passed to the handler in a siginfo_t structure. If the si_code field indicates the source is SI_SIGIO, the si_fd field gives the file descriptor associated with the event. Otherwise, there is no indication which file descriptors are pending, and you should use the usual mechanisms (select(2), poll(2), read(2) with O_NONBLOCK set etc.) to determine which file descriptors are available for I/O.

        Note that the file descriptor provided in si_fd is the one that was specified during the F_SETSIG operation. This can lead to an unusual corner case. If the file descriptor is duplicated (dup(2) or similar), and the original file descriptor is closed, then I/O events will continue to be generated, but the si_fd field will contain the number of the now closed file descriptor.

        By selecting a real time signal (value ≥ SIGRTMIN), multiple I/O events may be queued using the same signal numbers. (Queuing is dependent on available memory.) Extra information is available if SA_SIGINFO is set for the signal handler, as above.

        Note that Linux imposes a limit on the number of real-time signals that may be queued to a process (see getrlimit(2) and signal(7)) and if this limit is reached, then the kernel reverts to delivering SIGIO, and this signal is delivered to the entire process rather than to a specific thread.

      • F_GETSIG - Return (as the function result) the signal sent when input or output becomes possible.

        A value of zero means SIGIO is sent. Any other value (including SIGIO) is the signal sent instead, and in this case additional info is available to the signal handler if installed with SA_SIGINFO. arg is ignored.

      • F_SETOWN_EX - This operation performs a similar task to F_SETOWN. It allows the caller to direct I/O availability signals to a specific thread, process, or process group.

        The caller specifies the target of signals via arg, which is a pointer to a FOwnerEx structure. The type field has one of the following values, which define how pid is interpreted: F_OWNER_TID, F_OWNER_PID, F_OWNER_PGRP.

      • F_GETOWN_EX - Return the current file descriptor owner settings as defined by a previous F_SETOWN_EX operation.

        The information is returned in the FOwnerEx structure pointed to by arg.

        The type field will have one of the values F_OWNER_TID, F_OWNER_PID, or F_OWNER_PGRP. The pid field is a positive integer representing a thread ID, process ID, or process group ID. See F_SETOWN_EX for more details.

      • F_OFD_GETLK - On input to this call, lock describes an open file description lock we would like to place on the file.

        If the lock could be placed, fcntl() does not actually place it, but returns F_UNLCK in the l_type field of lock and leaves the other fields of the structure unchanged. If one or more incompatible locks would prevent this lock being placed, then details about one of these locks are returned via lock, as described above for F_GETLK.

      • F_OFD_SETLK - Acquire an open file description lock (when l_type is F_RDLCK or F_WRLCK) or release an open file description lock (when l_type is F_UNLCK) on the bytes specified by the l_whence, l_start, and l_len fields of lock.

        If a conflicting lock is held by another process, this call returns -1 and sets errno to EAGAIN.

      • F_OFD_SETLKW - As for F_OFD_SETLK, but if a conflicting lock is held on the file, then wait for that lock to be released.

        If a signal is caught while waiting, then the call is interrupted and (after the signal handler has returned) returns immediately (with return value -1 and errno set to EINTR; see signal(7)).

      • F_SETLEASE - Set or remove a file lease according to which of the following values is specified in the integer arg: F_RDLCK, F_WRLCK, F_UNLCK
      • F_GETLEASE - Indicates what type of lease is associated with the file descriptor fd by returning either F_RDLCK, F_WRLCK, or F_UNLCK, indicating, respectively, a read lease, a write lease, or no lease. arg is ignored.
      • F_NOTIFY - (Linux 2.4 onward) Provide notification when the directory referred to by fd or any of the files that it contains is changed.

        The events to be notified are specified in arg, which is a bit mask specified by ORing together zero or more of the following bits: DN_ACCESS, DN_MODIFY, DN_CREATE, DN_DELETE, DN_RENAME, DN_ATTRIB

        (In order to obtain these definitions, the _GNU_SOURCE feature test macro must be defined before including any header files.)

        Directory notifications are normally "one-shot", and the application must reregister to receive further notifications. Alternatively, if DN_MULTISHOT is included in arg, then notification will remain in effect until explicitly removed.

        A series of F_NOTIFY requests is cumulative, with the events in arg being added to the set already monitored. To disable notification of all events, make an F_NOTIFY call specifying arg as 0.

        Notification occurs via delivery of a signal. The default signal is SIGIO, but this can be changed using the F_SETSIG command to fcntl(). (Note that SIGIO is one of the nonqueuing standard signals; switching to the use of a real-time signal means that multiple notifications can be queued to the process.) In the latter case, the signal handler receives a siginfo_t structure as its second argument (if the handler was established using SA_SIGINFO) and the si_fd field of this structure contains the file descriptor which generated the notification (useful when establishing notification on multiple directories).

        Especially when using DN_MULTISHOT, a real time signal should be used for notification, so that multiple notifications can be queued.

        NOTE: New applications should use the inotify interface (available since kernel 2.6.13), which provides a much superior interface for obtaining notifications of filesystem events. See inotify(7).

      • F_SETPIPE_SZ - Change the capacity of the pipe referred to by fd to be at least arg bytes.

        An unprivileged process can adjust the pipe capacity to any value between the system page size and the limit defined in /proc/sys/fs/pipe-max-size (see proc(5)). Attempts to set the pipe capacity below the page size are silently rounded up to the page size. Attempts by an unprivileged process to set the pipe capacity above the limit in /proc/sys/fs/pipe-max-size yield the error EPERM; a privileged process (CAP_SYS_RESOURCE) can override the limit.

        When allocating the buffer for the pipe, the kernel may use a capacity larger than arg, if that is convenient for the implementation. (In the current implementation, the allocation is the next higher power-of-two page-size multiple of the requested size.) The actual capacity (in bytes) that is set is returned as the function result.

        Attempting to set the pipe capacity smaller than the amount of buffer space currently used to store data produces the error EBUSY.

        Note that because of the way the pages of the pipe buffer are employed when data is written to the pipe, the number of bytes that can be written may be less than the nominal size, depending on the size of the writes.

      • F_GETPIPE_SZ - Return (as the function result) the capacity of the pipe referred to by fd.
      • F_ADD_SEALS - Add the seals given in the bit-mask argument arg to the set of seals of the inode referred to by the file descriptor fd.

        Seals cannot be removed again. Once this call succeeds, the seals are enforced by the kernel immediately. If the current set of seals includes F_SEAL_SEAL (see below), then this call will be rejected with EPERM. Adding a seal that is already set is a no-op, in case F_SEAL_SEAL is not set already. In order to place a seal, the file descriptor fd must be writable.

      • F_GET_SEALS - Return (as the function result) the current set of seals of the inode referred to by fd.

        If no seals are set, 0 is returned. If the file does not support sealing, -1 is returned and errno is set to EINVAL.

      • F_GET_RW_HINT - Returns the value of the read/write hint associated with the underlying inode referred to by fd.
      • F_SET_RW_HINT - Sets the read/write hint value associated with the underlying inode referred to by fd.

        This hint persists until either it is explicitly modified or the underlying filesystem is unmounted.

      • F_GET_FILE_RW_HINT - Returns the value of the read/write hint associated with the open file description referred to by fd.
      • F_SET_FILE_RW_HINT - Sets the read/write hint value associated with the open file description referred to by fd.
      • F_DUPFD_CLOEXEC - As for F_DUPFD, but additionally set the close-on-exec flag for the duplicate file descriptor.

        Specifying this flag permits a program to avoid an additional fcntl() F_SETFD operation to set the FD_CLOEXEC flag. For an explanation of why this flag is useful, see the description of O_CLOEXEC in open(2).

      See Also:

    • F_GETOWN

      public static final int F_GETOWN
      fcntl(int, int) commands.
      Enum values:
      • F_DUPFD - Duplicate the file descriptor fd using the lowest-numbered available file descriptor greater than or equal to arg.

        This is different from dup2(2), which uses exactly the file descriptor specified.

        On success, the new file descriptor is returned.

        See dup(2) for further details.

      • F_GETFD - Return (as the function result) the file descriptor flags; arg is ignored.
      • F_SETFD - Set the file descriptor flags to the value specified by arg.
      • F_GETFL - Return (as the function result) the file access mode and the file status flags; arg is ignored.
      • F_SETFL - Set the file status flags to the value specified by arg.

        File access mode (O_RDONLY, O_WRONLY, O_RDWR) and file creation flags (i.e., O_CREAT, O_EXCL, O_NOCTTY, O_TRUNC) in arg are ignored. On Linux, this command can change only the O_APPEND, O_ASYNC, O_DIRECT, O_NOATIME, and O_NONBLOCK flags. It is not possible to change the O_DSYNC and O_SYNC flags; see BUGS, below.

      • F_GETLK - On input to this call, lock describes a lock we would like to place on the file.

        If the lock could be placed, fcntl() does not actually place it, but returns F_UNLCK in the l_type field of lock and leaves the other fields of the structure unchanged.

        If one or more incompatible locks would prevent this lock being placed, then fcntl() returns details about one of those locks in the l_type, l_whence, l_start, and l_len fields of lock. If the conflicting lock is a traditional (process-associated) record lock, then the l_pid field is set to the PID of the process holding that lock. If the conflicting lock is an open file description lock, then l_pid is set to -1. Note that the returned information may already be out of date by the time the caller inspects it.

      • F_SETLK - Acquire a lock (when l_type is F_RDLCK or F_WRLCK) or release a lock (when l_type is F_UNLCK) on the bytes specified by the l_whence, l_start, and l_len fields of lock.

        If a conflicting lock is held by another process, this call returns -1 and sets errno to EACCES or EAGAIN. (The error returned in this case differs across implementations, so POSIX requires a portable application to check for both errors.)

      • F_SETLKW - As for F_SETLK, but if a conflicting lock is held on the file, then wait for that lock to be released.

        If a signal is caught while waiting, then the call is interrupted and (after the signal handler has returned) returns immediately (with return value -1 and errno set to EINTR; see signal(7)).

      • F_SETOWN - Set the process ID or process group ID that will receive SIGIO and SIGURG signals for events on the file descriptor fd.

        The target process or process group ID is specified in arg. A process ID is specified as a positive value; a process group ID is specified as a negative value. Most commonly, the calling process specifies itself as the owner (that is, arg is specified as getpid(2)).

        As well as setting the file descriptor owner, one must also enable generation of signals on the file descriptor. This is done by using the fcntl() F_SETFL command to set the O_ASYNC file status flag on the file descriptor. Subsequently, a SIGIO signal is sent whenever input or output becomes possible on the file descriptor. The fcntl() F_SETSIG command can be used to obtain delivery of a signal other than SIGIO.

        Sending a signal to the owner process (group) specified by F_SETOWN is subject to the same permissions checks as are described for kill(2), where the sending process is the one that employs F_SETOWN (but see BUGS below). If this permission check fails, then the signal is silently discarded. Note: The F_SETOWN operation records the caller's credentials at the time of the fcntl() call, and it is these saved credentials that are used for the permission checks.

        If the file descriptor fd refers to a socket, F_SETOWN also selects the recipient of SIGURG signals that are delivered when out-of-band data arrives on that socket. (SIGURG is sent in any situation where select(2) would report the socket as having an "exceptional condition".)

        The following was true in 2.6.x kernels up to and including kernel 2.6.11:

        If a nonzero value is given to F_SETSIG in a multithreaded process running with a threading library that supports thread groups (e.g., NPTL), then a positive value given to F_SETOWN has a different meaning: instead of being a process ID identifying a whole process, it is a thread ID identifying a specific thread within a process. Consequently, it may be necessary to pass F_SETOWN the result of gettid(2) instead of getpid(2) to get sensible results when F_SETSIG is used. (In current Linux threading implementations, a main thread's thread ID is the same as its process ID. This means that a single-threaded program can equally use gettid(2) or getpid(2) in this scenario.) Note, however, that the statements in this paragraph do not apply to the SIGURG signal generated for out-of-band data on a socket: this signal is always sent to either a process or a process group, depending on the value given to F_SETOWN.

        The above behavior was accidentally dropped in Linux 2.6.12, and won't be restored. From Linux 2.6.32 onward, use F_SETOWN_EX to target SIGIO and SIGURG signals at a particular thread.

      • F_GETOWN - Return (as the function result) the process ID or process group ID currently receiving SIGIO and SIGURG signals for events on file descriptor fd.

        Process IDs are returned as positive values; process group IDs are returned as negative values (but see BUGS below). arg is ignored.

      • F_SETSIG - Set the signal sent when input or output becomes possible to the value given in arg.

        A value of zero means to send the default SIGIO signal. Any other value (including SIGIO) is the signal to send instead, and in this case additional info is available to the signal handler if installed with SA_SIGINFO.

        By using F_SETSIG with a nonzero value, and setting SA_SIGINFO for the signal handler (see sigaction(2)), extra information about I/O events is passed to the handler in a siginfo_t structure. If the si_code field indicates the source is SI_SIGIO, the si_fd field gives the file descriptor associated with the event. Otherwise, there is no indication which file descriptors are pending, and you should use the usual mechanisms (select(2), poll(2), read(2) with O_NONBLOCK set etc.) to determine which file descriptors are available for I/O.

        Note that the file descriptor provided in si_fd is the one that was specified during the F_SETSIG operation. This can lead to an unusual corner case. If the file descriptor is duplicated (dup(2) or similar), and the original file descriptor is closed, then I/O events will continue to be generated, but the si_fd field will contain the number of the now closed file descriptor.

        By selecting a real time signal (value ≥ SIGRTMIN), multiple I/O events may be queued using the same signal numbers. (Queuing is dependent on available memory.) Extra information is available if SA_SIGINFO is set for the signal handler, as above.

        Note that Linux imposes a limit on the number of real-time signals that may be queued to a process (see getrlimit(2) and signal(7)) and if this limit is reached, then the kernel reverts to delivering SIGIO, and this signal is delivered to the entire process rather than to a specific thread.

      • F_GETSIG - Return (as the function result) the signal sent when input or output becomes possible.

        A value of zero means SIGIO is sent. Any other value (including SIGIO) is the signal sent instead, and in this case additional info is available to the signal handler if installed with SA_SIGINFO. arg is ignored.

      • F_SETOWN_EX - This operation performs a similar task to F_SETOWN. It allows the caller to direct I/O availability signals to a specific thread, process, or process group.

        The caller specifies the target of signals via arg, which is a pointer to a FOwnerEx structure. The type field has one of the following values, which define how pid is interpreted: F_OWNER_TID, F_OWNER_PID, F_OWNER_PGRP.

      • F_GETOWN_EX - Return the current file descriptor owner settings as defined by a previous F_SETOWN_EX operation.

        The information is returned in the FOwnerEx structure pointed to by arg.

        The type field will have one of the values F_OWNER_TID, F_OWNER_PID, or F_OWNER_PGRP. The pid field is a positive integer representing a thread ID, process ID, or process group ID. See F_SETOWN_EX for more details.

      • F_OFD_GETLK - On input to this call, lock describes an open file description lock we would like to place on the file.

        If the lock could be placed, fcntl() does not actually place it, but returns F_UNLCK in the l_type field of lock and leaves the other fields of the structure unchanged. If one or more incompatible locks would prevent this lock being placed, then details about one of these locks are returned via lock, as described above for F_GETLK.

      • F_OFD_SETLK - Acquire an open file description lock (when l_type is F_RDLCK or F_WRLCK) or release an open file description lock (when l_type is F_UNLCK) on the bytes specified by the l_whence, l_start, and l_len fields of lock.

        If a conflicting lock is held by another process, this call returns -1 and sets errno to EAGAIN.

      • F_OFD_SETLKW - As for F_OFD_SETLK, but if a conflicting lock is held on the file, then wait for that lock to be released.

        If a signal is caught while waiting, then the call is interrupted and (after the signal handler has returned) returns immediately (with return value -1 and errno set to EINTR; see signal(7)).

      • F_SETLEASE - Set or remove a file lease according to which of the following values is specified in the integer arg: F_RDLCK, F_WRLCK, F_UNLCK
      • F_GETLEASE - Indicates what type of lease is associated with the file descriptor fd by returning either F_RDLCK, F_WRLCK, or F_UNLCK, indicating, respectively, a read lease, a write lease, or no lease. arg is ignored.
      • F_NOTIFY - (Linux 2.4 onward) Provide notification when the directory referred to by fd or any of the files that it contains is changed.

        The events to be notified are specified in arg, which is a bit mask specified by ORing together zero or more of the following bits: DN_ACCESS, DN_MODIFY, DN_CREATE, DN_DELETE, DN_RENAME, DN_ATTRIB

        (In order to obtain these definitions, the _GNU_SOURCE feature test macro must be defined before including any header files.)

        Directory notifications are normally "one-shot", and the application must reregister to receive further notifications. Alternatively, if DN_MULTISHOT is included in arg, then notification will remain in effect until explicitly removed.

        A series of F_NOTIFY requests is cumulative, with the events in arg being added to the set already monitored. To disable notification of all events, make an F_NOTIFY call specifying arg as 0.

        Notification occurs via delivery of a signal. The default signal is SIGIO, but this can be changed using the F_SETSIG command to fcntl(). (Note that SIGIO is one of the nonqueuing standard signals; switching to the use of a real-time signal means that multiple notifications can be queued to the process.) In the latter case, the signal handler receives a siginfo_t structure as its second argument (if the handler was established using SA_SIGINFO) and the si_fd field of this structure contains the file descriptor which generated the notification (useful when establishing notification on multiple directories).

        Especially when using DN_MULTISHOT, a real time signal should be used for notification, so that multiple notifications can be queued.

        NOTE: New applications should use the inotify interface (available since kernel 2.6.13), which provides a much superior interface for obtaining notifications of filesystem events. See inotify(7).

      • F_SETPIPE_SZ - Change the capacity of the pipe referred to by fd to be at least arg bytes.

        An unprivileged process can adjust the pipe capacity to any value between the system page size and the limit defined in /proc/sys/fs/pipe-max-size (see proc(5)). Attempts to set the pipe capacity below the page size are silently rounded up to the page size. Attempts by an unprivileged process to set the pipe capacity above the limit in /proc/sys/fs/pipe-max-size yield the error EPERM; a privileged process (CAP_SYS_RESOURCE) can override the limit.

        When allocating the buffer for the pipe, the kernel may use a capacity larger than arg, if that is convenient for the implementation. (In the current implementation, the allocation is the next higher power-of-two page-size multiple of the requested size.) The actual capacity (in bytes) that is set is returned as the function result.

        Attempting to set the pipe capacity smaller than the amount of buffer space currently used to store data produces the error EBUSY.

        Note that because of the way the pages of the pipe buffer are employed when data is written to the pipe, the number of bytes that can be written may be less than the nominal size, depending on the size of the writes.

      • F_GETPIPE_SZ - Return (as the function result) the capacity of the pipe referred to by fd.
      • F_ADD_SEALS - Add the seals given in the bit-mask argument arg to the set of seals of the inode referred to by the file descriptor fd.

        Seals cannot be removed again. Once this call succeeds, the seals are enforced by the kernel immediately. If the current set of seals includes F_SEAL_SEAL (see below), then this call will be rejected with EPERM. Adding a seal that is already set is a no-op, in case F_SEAL_SEAL is not set already. In order to place a seal, the file descriptor fd must be writable.

      • F_GET_SEALS - Return (as the function result) the current set of seals of the inode referred to by fd.

        If no seals are set, 0 is returned. If the file does not support sealing, -1 is returned and errno is set to EINVAL.

      • F_GET_RW_HINT - Returns the value of the read/write hint associated with the underlying inode referred to by fd.
      • F_SET_RW_HINT - Sets the read/write hint value associated with the underlying inode referred to by fd.

        This hint persists until either it is explicitly modified or the underlying filesystem is unmounted.

      • F_GET_FILE_RW_HINT - Returns the value of the read/write hint associated with the open file description referred to by fd.
      • F_SET_FILE_RW_HINT - Sets the read/write hint value associated with the open file description referred to by fd.
      • F_DUPFD_CLOEXEC - As for F_DUPFD, but additionally set the close-on-exec flag for the duplicate file descriptor.

        Specifying this flag permits a program to avoid an additional fcntl() F_SETFD operation to set the FD_CLOEXEC flag. For an explanation of why this flag is useful, see the description of O_CLOEXEC in open(2).

      See Also:

    • F_SETSIG

      public static final int F_SETSIG
      fcntl(int, int) commands.
      Enum values:
      • F_DUPFD - Duplicate the file descriptor fd using the lowest-numbered available file descriptor greater than or equal to arg.

        This is different from dup2(2), which uses exactly the file descriptor specified.

        On success, the new file descriptor is returned.

        See dup(2) for further details.

      • F_GETFD - Return (as the function result) the file descriptor flags; arg is ignored.
      • F_SETFD - Set the file descriptor flags to the value specified by arg.
      • F_GETFL - Return (as the function result) the file access mode and the file status flags; arg is ignored.
      • F_SETFL - Set the file status flags to the value specified by arg.

        File access mode (O_RDONLY, O_WRONLY, O_RDWR) and file creation flags (i.e., O_CREAT, O_EXCL, O_NOCTTY, O_TRUNC) in arg are ignored. On Linux, this command can change only the O_APPEND, O_ASYNC, O_DIRECT, O_NOATIME, and O_NONBLOCK flags. It is not possible to change the O_DSYNC and O_SYNC flags; see BUGS, below.

      • F_GETLK - On input to this call, lock describes a lock we would like to place on the file.

        If the lock could be placed, fcntl() does not actually place it, but returns F_UNLCK in the l_type field of lock and leaves the other fields of the structure unchanged.

        If one or more incompatible locks would prevent this lock being placed, then fcntl() returns details about one of those locks in the l_type, l_whence, l_start, and l_len fields of lock. If the conflicting lock is a traditional (process-associated) record lock, then the l_pid field is set to the PID of the process holding that lock. If the conflicting lock is an open file description lock, then l_pid is set to -1. Note that the returned information may already be out of date by the time the caller inspects it.

      • F_SETLK - Acquire a lock (when l_type is F_RDLCK or F_WRLCK) or release a lock (when l_type is F_UNLCK) on the bytes specified by the l_whence, l_start, and l_len fields of lock.

        If a conflicting lock is held by another process, this call returns -1 and sets errno to EACCES or EAGAIN. (The error returned in this case differs across implementations, so POSIX requires a portable application to check for both errors.)

      • F_SETLKW - As for F_SETLK, but if a conflicting lock is held on the file, then wait for that lock to be released.

        If a signal is caught while waiting, then the call is interrupted and (after the signal handler has returned) returns immediately (with return value -1 and errno set to EINTR; see signal(7)).

      • F_SETOWN - Set the process ID or process group ID that will receive SIGIO and SIGURG signals for events on the file descriptor fd.

        The target process or process group ID is specified in arg. A process ID is specified as a positive value; a process group ID is specified as a negative value. Most commonly, the calling process specifies itself as the owner (that is, arg is specified as getpid(2)).

        As well as setting the file descriptor owner, one must also enable generation of signals on the file descriptor. This is done by using the fcntl() F_SETFL command to set the O_ASYNC file status flag on the file descriptor. Subsequently, a SIGIO signal is sent whenever input or output becomes possible on the file descriptor. The fcntl() F_SETSIG command can be used to obtain delivery of a signal other than SIGIO.

        Sending a signal to the owner process (group) specified by F_SETOWN is subject to the same permissions checks as are described for kill(2), where the sending process is the one that employs F_SETOWN (but see BUGS below). If this permission check fails, then the signal is silently discarded. Note: The F_SETOWN operation records the caller's credentials at the time of the fcntl() call, and it is these saved credentials that are used for the permission checks.

        If the file descriptor fd refers to a socket, F_SETOWN also selects the recipient of SIGURG signals that are delivered when out-of-band data arrives on that socket. (SIGURG is sent in any situation where select(2) would report the socket as having an "exceptional condition".)

        The following was true in 2.6.x kernels up to and including kernel 2.6.11:

        If a nonzero value is given to F_SETSIG in a multithreaded process running with a threading library that supports thread groups (e.g., NPTL), then a positive value given to F_SETOWN has a different meaning: instead of being a process ID identifying a whole process, it is a thread ID identifying a specific thread within a process. Consequently, it may be necessary to pass F_SETOWN the result of gettid(2) instead of getpid(2) to get sensible results when F_SETSIG is used. (In current Linux threading implementations, a main thread's thread ID is the same as its process ID. This means that a single-threaded program can equally use gettid(2) or getpid(2) in this scenario.) Note, however, that the statements in this paragraph do not apply to the SIGURG signal generated for out-of-band data on a socket: this signal is always sent to either a process or a process group, depending on the value given to F_SETOWN.

        The above behavior was accidentally dropped in Linux 2.6.12, and won't be restored. From Linux 2.6.32 onward, use F_SETOWN_EX to target SIGIO and SIGURG signals at a particular thread.

      • F_GETOWN - Return (as the function result) the process ID or process group ID currently receiving SIGIO and SIGURG signals for events on file descriptor fd.

        Process IDs are returned as positive values; process group IDs are returned as negative values (but see BUGS below). arg is ignored.

      • F_SETSIG - Set the signal sent when input or output becomes possible to the value given in arg.

        A value of zero means to send the default SIGIO signal. Any other value (including SIGIO) is the signal to send instead, and in this case additional info is available to the signal handler if installed with SA_SIGINFO.

        By using F_SETSIG with a nonzero value, and setting SA_SIGINFO for the signal handler (see sigaction(2)), extra information about I/O events is passed to the handler in a siginfo_t structure. If the si_code field indicates the source is SI_SIGIO, the si_fd field gives the file descriptor associated with the event. Otherwise, there is no indication which file descriptors are pending, and you should use the usual mechanisms (select(2), poll(2), read(2) with O_NONBLOCK set etc.) to determine which file descriptors are available for I/O.

        Note that the file descriptor provided in si_fd is the one that was specified during the F_SETSIG operation. This can lead to an unusual corner case. If the file descriptor is duplicated (dup(2) or similar), and the original file descriptor is closed, then I/O events will continue to be generated, but the si_fd field will contain the number of the now closed file descriptor.

        By selecting a real time signal (value ≥ SIGRTMIN), multiple I/O events may be queued using the same signal numbers. (Queuing is dependent on available memory.) Extra information is available if SA_SIGINFO is set for the signal handler, as above.

        Note that Linux imposes a limit on the number of real-time signals that may be queued to a process (see getrlimit(2) and signal(7)) and if this limit is reached, then the kernel reverts to delivering SIGIO, and this signal is delivered to the entire process rather than to a specific thread.

      • F_GETSIG - Return (as the function result) the signal sent when input or output becomes possible.

        A value of zero means SIGIO is sent. Any other value (including SIGIO) is the signal sent instead, and in this case additional info is available to the signal handler if installed with SA_SIGINFO. arg is ignored.

      • F_SETOWN_EX - This operation performs a similar task to F_SETOWN. It allows the caller to direct I/O availability signals to a specific thread, process, or process group.

        The caller specifies the target of signals via arg, which is a pointer to a FOwnerEx structure. The type field has one of the following values, which define how pid is interpreted: F_OWNER_TID, F_OWNER_PID, F_OWNER_PGRP.

      • F_GETOWN_EX - Return the current file descriptor owner settings as defined by a previous F_SETOWN_EX operation.

        The information is returned in the FOwnerEx structure pointed to by arg.

        The type field will have one of the values F_OWNER_TID, F_OWNER_PID, or F_OWNER_PGRP. The pid field is a positive integer representing a thread ID, process ID, or process group ID. See F_SETOWN_EX for more details.

      • F_OFD_GETLK - On input to this call, lock describes an open file description lock we would like to place on the file.

        If the lock could be placed, fcntl() does not actually place it, but returns F_UNLCK in the l_type field of lock and leaves the other fields of the structure unchanged. If one or more incompatible locks would prevent this lock being placed, then details about one of these locks are returned via lock, as described above for F_GETLK.

      • F_OFD_SETLK - Acquire an open file description lock (when l_type is F_RDLCK or F_WRLCK) or release an open file description lock (when l_type is F_UNLCK) on the bytes specified by the l_whence, l_start, and l_len fields of lock.

        If a conflicting lock is held by another process, this call returns -1 and sets errno to EAGAIN.

      • F_OFD_SETLKW - As for F_OFD_SETLK, but if a conflicting lock is held on the file, then wait for that lock to be released.

        If a signal is caught while waiting, then the call is interrupted and (after the signal handler has returned) returns immediately (with return value -1 and errno set to EINTR; see signal(7)).

      • F_SETLEASE - Set or remove a file lease according to which of the following values is specified in the integer arg: F_RDLCK, F_WRLCK, F_UNLCK
      • F_GETLEASE - Indicates what type of lease is associated with the file descriptor fd by returning either F_RDLCK, F_WRLCK, or F_UNLCK, indicating, respectively, a read lease, a write lease, or no lease. arg is ignored.
      • F_NOTIFY - (Linux 2.4 onward) Provide notification when the directory referred to by fd or any of the files that it contains is changed.

        The events to be notified are specified in arg, which is a bit mask specified by ORing together zero or more of the following bits: DN_ACCESS, DN_MODIFY, DN_CREATE, DN_DELETE, DN_RENAME, DN_ATTRIB

        (In order to obtain these definitions, the _GNU_SOURCE feature test macro must be defined before including any header files.)

        Directory notifications are normally "one-shot", and the application must reregister to receive further notifications. Alternatively, if DN_MULTISHOT is included in arg, then notification will remain in effect until explicitly removed.

        A series of F_NOTIFY requests is cumulative, with the events in arg being added to the set already monitored. To disable notification of all events, make an F_NOTIFY call specifying arg as 0.

        Notification occurs via delivery of a signal. The default signal is SIGIO, but this can be changed using the F_SETSIG command to fcntl(). (Note that SIGIO is one of the nonqueuing standard signals; switching to the use of a real-time signal means that multiple notifications can be queued to the process.) In the latter case, the signal handler receives a siginfo_t structure as its second argument (if the handler was established using SA_SIGINFO) and the si_fd field of this structure contains the file descriptor which generated the notification (useful when establishing notification on multiple directories).

        Especially when using DN_MULTISHOT, a real time signal should be used for notification, so that multiple notifications can be queued.

        NOTE: New applications should use the inotify interface (available since kernel 2.6.13), which provides a much superior interface for obtaining notifications of filesystem events. See inotify(7).

      • F_SETPIPE_SZ - Change the capacity of the pipe referred to by fd to be at least arg bytes.

        An unprivileged process can adjust the pipe capacity to any value between the system page size and the limit defined in /proc/sys/fs/pipe-max-size (see proc(5)). Attempts to set the pipe capacity below the page size are silently rounded up to the page size. Attempts by an unprivileged process to set the pipe capacity above the limit in /proc/sys/fs/pipe-max-size yield the error EPERM; a privileged process (CAP_SYS_RESOURCE) can override the limit.

        When allocating the buffer for the pipe, the kernel may use a capacity larger than arg, if that is convenient for the implementation. (In the current implementation, the allocation is the next higher power-of-two page-size multiple of the requested size.) The actual capacity (in bytes) that is set is returned as the function result.

        Attempting to set the pipe capacity smaller than the amount of buffer space currently used to store data produces the error EBUSY.

        Note that because of the way the pages of the pipe buffer are employed when data is written to the pipe, the number of bytes that can be written may be less than the nominal size, depending on the size of the writes.

      • F_GETPIPE_SZ - Return (as the function result) the capacity of the pipe referred to by fd.
      • F_ADD_SEALS - Add the seals given in the bit-mask argument arg to the set of seals of the inode referred to by the file descriptor fd.

        Seals cannot be removed again. Once this call succeeds, the seals are enforced by the kernel immediately. If the current set of seals includes F_SEAL_SEAL (see below), then this call will be rejected with EPERM. Adding a seal that is already set is a no-op, in case F_SEAL_SEAL is not set already. In order to place a seal, the file descriptor fd must be writable.

      • F_GET_SEALS - Return (as the function result) the current set of seals of the inode referred to by fd.

        If no seals are set, 0 is returned. If the file does not support sealing, -1 is returned and errno is set to EINVAL.

      • F_GET_RW_HINT - Returns the value of the read/write hint associated with the underlying inode referred to by fd.
      • F_SET_RW_HINT - Sets the read/write hint value associated with the underlying inode referred to by fd.

        This hint persists until either it is explicitly modified or the underlying filesystem is unmounted.

      • F_GET_FILE_RW_HINT - Returns the value of the read/write hint associated with the open file description referred to by fd.
      • F_SET_FILE_RW_HINT - Sets the read/write hint value associated with the open file description referred to by fd.
      • F_DUPFD_CLOEXEC - As for F_DUPFD, but additionally set the close-on-exec flag for the duplicate file descriptor.

        Specifying this flag permits a program to avoid an additional fcntl() F_SETFD operation to set the FD_CLOEXEC flag. For an explanation of why this flag is useful, see the description of O_CLOEXEC in open(2).

      See Also:

    • F_GETSIG

      public static final int F_GETSIG
      fcntl(int, int) commands.
      Enum values:
      • F_DUPFD - Duplicate the file descriptor fd using the lowest-numbered available file descriptor greater than or equal to arg.

        This is different from dup2(2), which uses exactly the file descriptor specified.

        On success, the new file descriptor is returned.

        See dup(2) for further details.

      • F_GETFD - Return (as the function result) the file descriptor flags; arg is ignored.
      • F_SETFD - Set the file descriptor flags to the value specified by arg.
      • F_GETFL - Return (as the function result) the file access mode and the file status flags; arg is ignored.
      • F_SETFL - Set the file status flags to the value specified by arg.

        File access mode (O_RDONLY, O_WRONLY, O_RDWR) and file creation flags (i.e., O_CREAT, O_EXCL, O_NOCTTY, O_TRUNC) in arg are ignored. On Linux, this command can change only the O_APPEND, O_ASYNC, O_DIRECT, O_NOATIME, and O_NONBLOCK flags. It is not possible to change the O_DSYNC and O_SYNC flags; see BUGS, below.

      • F_GETLK - On input to this call, lock describes a lock we would like to place on the file.

        If the lock could be placed, fcntl() does not actually place it, but returns F_UNLCK in the l_type field of lock and leaves the other fields of the structure unchanged.

        If one or more incompatible locks would prevent this lock being placed, then fcntl() returns details about one of those locks in the l_type, l_whence, l_start, and l_len fields of lock. If the conflicting lock is a traditional (process-associated) record lock, then the l_pid field is set to the PID of the process holding that lock. If the conflicting lock is an open file description lock, then l_pid is set to -1. Note that the returned information may already be out of date by the time the caller inspects it.

      • F_SETLK - Acquire a lock (when l_type is F_RDLCK or F_WRLCK) or release a lock (when l_type is F_UNLCK) on the bytes specified by the l_whence, l_start, and l_len fields of lock.

        If a conflicting lock is held by another process, this call returns -1 and sets errno to EACCES or EAGAIN. (The error returned in this case differs across implementations, so POSIX requires a portable application to check for both errors.)

      • F_SETLKW - As for F_SETLK, but if a conflicting lock is held on the file, then wait for that lock to be released.

        If a signal is caught while waiting, then the call is interrupted and (after the signal handler has returned) returns immediately (with return value -1 and errno set to EINTR; see signal(7)).

      • F_SETOWN - Set the process ID or process group ID that will receive SIGIO and SIGURG signals for events on the file descriptor fd.

        The target process or process group ID is specified in arg. A process ID is specified as a positive value; a process group ID is specified as a negative value. Most commonly, the calling process specifies itself as the owner (that is, arg is specified as getpid(2)).

        As well as setting the file descriptor owner, one must also enable generation of signals on the file descriptor. This is done by using the fcntl() F_SETFL command to set the O_ASYNC file status flag on the file descriptor. Subsequently, a SIGIO signal is sent whenever input or output becomes possible on the file descriptor. The fcntl() F_SETSIG command can be used to obtain delivery of a signal other than SIGIO.

        Sending a signal to the owner process (group) specified by F_SETOWN is subject to the same permissions checks as are described for kill(2), where the sending process is the one that employs F_SETOWN (but see BUGS below). If this permission check fails, then the signal is silently discarded. Note: The F_SETOWN operation records the caller's credentials at the time of the fcntl() call, and it is these saved credentials that are used for the permission checks.

        If the file descriptor fd refers to a socket, F_SETOWN also selects the recipient of SIGURG signals that are delivered when out-of-band data arrives on that socket. (SIGURG is sent in any situation where select(2) would report the socket as having an "exceptional condition".)

        The following was true in 2.6.x kernels up to and including kernel 2.6.11:

        If a nonzero value is given to F_SETSIG in a multithreaded process running with a threading library that supports thread groups (e.g., NPTL), then a positive value given to F_SETOWN has a different meaning: instead of being a process ID identifying a whole process, it is a thread ID identifying a specific thread within a process. Consequently, it may be necessary to pass F_SETOWN the result of gettid(2) instead of getpid(2) to get sensible results when F_SETSIG is used. (In current Linux threading implementations, a main thread's thread ID is the same as its process ID. This means that a single-threaded program can equally use gettid(2) or getpid(2) in this scenario.) Note, however, that the statements in this paragraph do not apply to the SIGURG signal generated for out-of-band data on a socket: this signal is always sent to either a process or a process group, depending on the value given to F_SETOWN.

        The above behavior was accidentally dropped in Linux 2.6.12, and won't be restored. From Linux 2.6.32 onward, use F_SETOWN_EX to target SIGIO and SIGURG signals at a particular thread.

      • F_GETOWN - Return (as the function result) the process ID or process group ID currently receiving SIGIO and SIGURG signals for events on file descriptor fd.

        Process IDs are returned as positive values; process group IDs are returned as negative values (but see BUGS below). arg is ignored.

      • F_SETSIG - Set the signal sent when input or output becomes possible to the value given in arg.

        A value of zero means to send the default SIGIO signal. Any other value (including SIGIO) is the signal to send instead, and in this case additional info is available to the signal handler if installed with SA_SIGINFO.

        By using F_SETSIG with a nonzero value, and setting SA_SIGINFO for the signal handler (see sigaction(2)), extra information about I/O events is passed to the handler in a siginfo_t structure. If the si_code field indicates the source is SI_SIGIO, the si_fd field gives the file descriptor associated with the event. Otherwise, there is no indication which file descriptors are pending, and you should use the usual mechanisms (select(2), poll(2), read(2) with O_NONBLOCK set etc.) to determine which file descriptors are available for I/O.

        Note that the file descriptor provided in si_fd is the one that was specified during the F_SETSIG operation. This can lead to an unusual corner case. If the file descriptor is duplicated (dup(2) or similar), and the original file descriptor is closed, then I/O events will continue to be generated, but the si_fd field will contain the number of the now closed file descriptor.

        By selecting a real time signal (value ≥ SIGRTMIN), multiple I/O events may be queued using the same signal numbers. (Queuing is dependent on available memory.) Extra information is available if SA_SIGINFO is set for the signal handler, as above.

        Note that Linux imposes a limit on the number of real-time signals that may be queued to a process (see getrlimit(2) and signal(7)) and if this limit is reached, then the kernel reverts to delivering SIGIO, and this signal is delivered to the entire process rather than to a specific thread.

      • F_GETSIG - Return (as the function result) the signal sent when input or output becomes possible.

        A value of zero means SIGIO is sent. Any other value (including SIGIO) is the signal sent instead, and in this case additional info is available to the signal handler if installed with SA_SIGINFO. arg is ignored.

      • F_SETOWN_EX - This operation performs a similar task to F_SETOWN. It allows the caller to direct I/O availability signals to a specific thread, process, or process group.

        The caller specifies the target of signals via arg, which is a pointer to a FOwnerEx structure. The type field has one of the following values, which define how pid is interpreted: F_OWNER_TID, F_OWNER_PID, F_OWNER_PGRP.

      • F_GETOWN_EX - Return the current file descriptor owner settings as defined by a previous F_SETOWN_EX operation.

        The information is returned in the FOwnerEx structure pointed to by arg.

        The type field will have one of the values F_OWNER_TID, F_OWNER_PID, or F_OWNER_PGRP. The pid field is a positive integer representing a thread ID, process ID, or process group ID. See F_SETOWN_EX for more details.

      • F_OFD_GETLK - On input to this call, lock describes an open file description lock we would like to place on the file.

        If the lock could be placed, fcntl() does not actually place it, but returns F_UNLCK in the l_type field of lock and leaves the other fields of the structure unchanged. If one or more incompatible locks would prevent this lock being placed, then details about one of these locks are returned via lock, as described above for F_GETLK.

      • F_OFD_SETLK - Acquire an open file description lock (when l_type is F_RDLCK or F_WRLCK) or release an open file description lock (when l_type is F_UNLCK) on the bytes specified by the l_whence, l_start, and l_len fields of lock.

        If a conflicting lock is held by another process, this call returns -1 and sets errno to EAGAIN.

      • F_OFD_SETLKW - As for F_OFD_SETLK, but if a conflicting lock is held on the file, then wait for that lock to be released.

        If a signal is caught while waiting, then the call is interrupted and (after the signal handler has returned) returns immediately (with return value -1 and errno set to EINTR; see signal(7)).

      • F_SETLEASE - Set or remove a file lease according to which of the following values is specified in the integer arg: F_RDLCK, F_WRLCK, F_UNLCK
      • F_GETLEASE - Indicates what type of lease is associated with the file descriptor fd by returning either F_RDLCK, F_WRLCK, or F_UNLCK, indicating, respectively, a read lease, a write lease, or no lease. arg is ignored.
      • F_NOTIFY - (Linux 2.4 onward) Provide notification when the directory referred to by fd or any of the files that it contains is changed.

        The events to be notified are specified in arg, which is a bit mask specified by ORing together zero or more of the following bits: DN_ACCESS, DN_MODIFY, DN_CREATE, DN_DELETE, DN_RENAME, DN_ATTRIB

        (In order to obtain these definitions, the _GNU_SOURCE feature test macro must be defined before including any header files.)

        Directory notifications are normally "one-shot", and the application must reregister to receive further notifications. Alternatively, if DN_MULTISHOT is included in arg, then notification will remain in effect until explicitly removed.

        A series of F_NOTIFY requests is cumulative, with the events in arg being added to the set already monitored. To disable notification of all events, make an F_NOTIFY call specifying arg as 0.

        Notification occurs via delivery of a signal. The default signal is SIGIO, but this can be changed using the F_SETSIG command to fcntl(). (Note that SIGIO is one of the nonqueuing standard signals; switching to the use of a real-time signal means that multiple notifications can be queued to the process.) In the latter case, the signal handler receives a siginfo_t structure as its second argument (if the handler was established using SA_SIGINFO) and the si_fd field of this structure contains the file descriptor which generated the notification (useful when establishing notification on multiple directories).

        Especially when using DN_MULTISHOT, a real time signal should be used for notification, so that multiple notifications can be queued.

        NOTE: New applications should use the inotify interface (available since kernel 2.6.13), which provides a much superior interface for obtaining notifications of filesystem events. See inotify(7).

      • F_SETPIPE_SZ - Change the capacity of the pipe referred to by fd to be at least arg bytes.

        An unprivileged process can adjust the pipe capacity to any value between the system page size and the limit defined in /proc/sys/fs/pipe-max-size (see proc(5)). Attempts to set the pipe capacity below the page size are silently rounded up to the page size. Attempts by an unprivileged process to set the pipe capacity above the limit in /proc/sys/fs/pipe-max-size yield the error EPERM; a privileged process (CAP_SYS_RESOURCE) can override the limit.

        When allocating the buffer for the pipe, the kernel may use a capacity larger than arg, if that is convenient for the implementation. (In the current implementation, the allocation is the next higher power-of-two page-size multiple of the requested size.) The actual capacity (in bytes) that is set is returned as the function result.

        Attempting to set the pipe capacity smaller than the amount of buffer space currently used to store data produces the error EBUSY.

        Note that because of the way the pages of the pipe buffer are employed when data is written to the pipe, the number of bytes that can be written may be less than the nominal size, depending on the size of the writes.

      • F_GETPIPE_SZ - Return (as the function result) the capacity of the pipe referred to by fd.
      • F_ADD_SEALS - Add the seals given in the bit-mask argument arg to the set of seals of the inode referred to by the file descriptor fd.

        Seals cannot be removed again. Once this call succeeds, the seals are enforced by the kernel immediately. If the current set of seals includes F_SEAL_SEAL (see below), then this call will be rejected with EPERM. Adding a seal that is already set is a no-op, in case F_SEAL_SEAL is not set already. In order to place a seal, the file descriptor fd must be writable.

      • F_GET_SEALS - Return (as the function result) the current set of seals of the inode referred to by fd.

        If no seals are set, 0 is returned. If the file does not support sealing, -1 is returned and errno is set to EINVAL.

      • F_GET_RW_HINT - Returns the value of the read/write hint associated with the underlying inode referred to by fd.
      • F_SET_RW_HINT - Sets the read/write hint value associated with the underlying inode referred to by fd.

        This hint persists until either it is explicitly modified or the underlying filesystem is unmounted.

      • F_GET_FILE_RW_HINT - Returns the value of the read/write hint associated with the open file description referred to by fd.
      • F_SET_FILE_RW_HINT - Sets the read/write hint value associated with the open file description referred to by fd.
      • F_DUPFD_CLOEXEC - As for F_DUPFD, but additionally set the close-on-exec flag for the duplicate file descriptor.

        Specifying this flag permits a program to avoid an additional fcntl() F_SETFD operation to set the FD_CLOEXEC flag. For an explanation of why this flag is useful, see the description of O_CLOEXEC in open(2).

      See Also:

    • F_SETOWN_EX

      public static final int F_SETOWN_EX
      fcntl(int, int) commands.
      Enum values:
      • F_DUPFD - Duplicate the file descriptor fd using the lowest-numbered available file descriptor greater than or equal to arg.

        This is different from dup2(2), which uses exactly the file descriptor specified.

        On success, the new file descriptor is returned.

        See dup(2) for further details.

      • F_GETFD - Return (as the function result) the file descriptor flags; arg is ignored.
      • F_SETFD - Set the file descriptor flags to the value specified by arg.
      • F_GETFL - Return (as the function result) the file access mode and the file status flags; arg is ignored.
      • F_SETFL - Set the file status flags to the value specified by arg.

        File access mode (O_RDONLY, O_WRONLY, O_RDWR) and file creation flags (i.e., O_CREAT, O_EXCL, O_NOCTTY, O_TRUNC) in arg are ignored. On Linux, this command can change only the O_APPEND, O_ASYNC, O_DIRECT, O_NOATIME, and O_NONBLOCK flags. It is not possible to change the O_DSYNC and O_SYNC flags; see BUGS, below.

      • F_GETLK - On input to this call, lock describes a lock we would like to place on the file.

        If the lock could be placed, fcntl() does not actually place it, but returns F_UNLCK in the l_type field of lock and leaves the other fields of the structure unchanged.

        If one or more incompatible locks would prevent this lock being placed, then fcntl() returns details about one of those locks in the l_type, l_whence, l_start, and l_len fields of lock. If the conflicting lock is a traditional (process-associated) record lock, then the l_pid field is set to the PID of the process holding that lock. If the conflicting lock is an open file description lock, then l_pid is set to -1. Note that the returned information may already be out of date by the time the caller inspects it.

      • F_SETLK - Acquire a lock (when l_type is F_RDLCK or F_WRLCK) or release a lock (when l_type is F_UNLCK) on the bytes specified by the l_whence, l_start, and l_len fields of lock.

        If a conflicting lock is held by another process, this call returns -1 and sets errno to EACCES or EAGAIN. (The error returned in this case differs across implementations, so POSIX requires a portable application to check for both errors.)

      • F_SETLKW - As for F_SETLK, but if a conflicting lock is held on the file, then wait for that lock to be released.

        If a signal is caught while waiting, then the call is interrupted and (after the signal handler has returned) returns immediately (with return value -1 and errno set to EINTR; see signal(7)).

      • F_SETOWN - Set the process ID or process group ID that will receive SIGIO and SIGURG signals for events on the file descriptor fd.

        The target process or process group ID is specified in arg. A process ID is specified as a positive value; a process group ID is specified as a negative value. Most commonly, the calling process specifies itself as the owner (that is, arg is specified as getpid(2)).

        As well as setting the file descriptor owner, one must also enable generation of signals on the file descriptor. This is done by using the fcntl() F_SETFL command to set the O_ASYNC file status flag on the file descriptor. Subsequently, a SIGIO signal is sent whenever input or output becomes possible on the file descriptor. The fcntl() F_SETSIG command can be used to obtain delivery of a signal other than SIGIO.

        Sending a signal to the owner process (group) specified by F_SETOWN is subject to the same permissions checks as are described for kill(2), where the sending process is the one that employs F_SETOWN (but see BUGS below). If this permission check fails, then the signal is silently discarded. Note: The F_SETOWN operation records the caller's credentials at the time of the fcntl() call, and it is these saved credentials that are used for the permission checks.

        If the file descriptor fd refers to a socket, F_SETOWN also selects the recipient of SIGURG signals that are delivered when out-of-band data arrives on that socket. (SIGURG is sent in any situation where select(2) would report the socket as having an "exceptional condition".)

        The following was true in 2.6.x kernels up to and including kernel 2.6.11:

        If a nonzero value is given to F_SETSIG in a multithreaded process running with a threading library that supports thread groups (e.g., NPTL), then a positive value given to F_SETOWN has a different meaning: instead of being a process ID identifying a whole process, it is a thread ID identifying a specific thread within a process. Consequently, it may be necessary to pass F_SETOWN the result of gettid(2) instead of getpid(2) to get sensible results when F_SETSIG is used. (In current Linux threading implementations, a main thread's thread ID is the same as its process ID. This means that a single-threaded program can equally use gettid(2) or getpid(2) in this scenario.) Note, however, that the statements in this paragraph do not apply to the SIGURG signal generated for out-of-band data on a socket: this signal is always sent to either a process or a process group, depending on the value given to F_SETOWN.

        The above behavior was accidentally dropped in Linux 2.6.12, and won't be restored. From Linux 2.6.32 onward, use F_SETOWN_EX to target SIGIO and SIGURG signals at a particular thread.

      • F_GETOWN - Return (as the function result) the process ID or process group ID currently receiving SIGIO and SIGURG signals for events on file descriptor fd.

        Process IDs are returned as positive values; process group IDs are returned as negative values (but see BUGS below). arg is ignored.

      • F_SETSIG - Set the signal sent when input or output becomes possible to the value given in arg.

        A value of zero means to send the default SIGIO signal. Any other value (including SIGIO) is the signal to send instead, and in this case additional info is available to the signal handler if installed with SA_SIGINFO.

        By using F_SETSIG with a nonzero value, and setting SA_SIGINFO for the signal handler (see sigaction(2)), extra information about I/O events is passed to the handler in a siginfo_t structure. If the si_code field indicates the source is SI_SIGIO, the si_fd field gives the file descriptor associated with the event. Otherwise, there is no indication which file descriptors are pending, and you should use the usual mechanisms (select(2), poll(2), read(2) with O_NONBLOCK set etc.) to determine which file descriptors are available for I/O.

        Note that the file descriptor provided in si_fd is the one that was specified during the F_SETSIG operation. This can lead to an unusual corner case. If the file descriptor is duplicated (dup(2) or similar), and the original file descriptor is closed, then I/O events will continue to be generated, but the si_fd field will contain the number of the now closed file descriptor.

        By selecting a real time signal (value ≥ SIGRTMIN), multiple I/O events may be queued using the same signal numbers. (Queuing is dependent on available memory.) Extra information is available if SA_SIGINFO is set for the signal handler, as above.

        Note that Linux imposes a limit on the number of real-time signals that may be queued to a process (see getrlimit(2) and signal(7)) and if this limit is reached, then the kernel reverts to delivering SIGIO, and this signal is delivered to the entire process rather than to a specific thread.

      • F_GETSIG - Return (as the function result) the signal sent when input or output becomes possible.

        A value of zero means SIGIO is sent. Any other value (including SIGIO) is the signal sent instead, and in this case additional info is available to the signal handler if installed with SA_SIGINFO. arg is ignored.

      • F_SETOWN_EX - This operation performs a similar task to F_SETOWN. It allows the caller to direct I/O availability signals to a specific thread, process, or process group.

        The caller specifies the target of signals via arg, which is a pointer to a FOwnerEx structure. The type field has one of the following values, which define how pid is interpreted: F_OWNER_TID, F_OWNER_PID, F_OWNER_PGRP.

      • F_GETOWN_EX - Return the current file descriptor owner settings as defined by a previous F_SETOWN_EX operation.

        The information is returned in the FOwnerEx structure pointed to by arg.

        The type field will have one of the values F_OWNER_TID, F_OWNER_PID, or F_OWNER_PGRP. The pid field is a positive integer representing a thread ID, process ID, or process group ID. See F_SETOWN_EX for more details.

      • F_OFD_GETLK - On input to this call, lock describes an open file description lock we would like to place on the file.

        If the lock could be placed, fcntl() does not actually place it, but returns F_UNLCK in the l_type field of lock and leaves the other fields of the structure unchanged. If one or more incompatible locks would prevent this lock being placed, then details about one of these locks are returned via lock, as described above for F_GETLK.

      • F_OFD_SETLK - Acquire an open file description lock (when l_type is F_RDLCK or F_WRLCK) or release an open file description lock (when l_type is F_UNLCK) on the bytes specified by the l_whence, l_start, and l_len fields of lock.

        If a conflicting lock is held by another process, this call returns -1 and sets errno to EAGAIN.

      • F_OFD_SETLKW - As for F_OFD_SETLK, but if a conflicting lock is held on the file, then wait for that lock to be released.

        If a signal is caught while waiting, then the call is interrupted and (after the signal handler has returned) returns immediately (with return value -1 and errno set to EINTR; see signal(7)).

      • F_SETLEASE - Set or remove a file lease according to which of the following values is specified in the integer arg: F_RDLCK, F_WRLCK, F_UNLCK
      • F_GETLEASE - Indicates what type of lease is associated with the file descriptor fd by returning either F_RDLCK, F_WRLCK, or F_UNLCK, indicating, respectively, a read lease, a write lease, or no lease. arg is ignored.
      • F_NOTIFY - (Linux 2.4 onward) Provide notification when the directory referred to by fd or any of the files that it contains is changed.

        The events to be notified are specified in arg, which is a bit mask specified by ORing together zero or more of the following bits: DN_ACCESS, DN_MODIFY, DN_CREATE, DN_DELETE, DN_RENAME, DN_ATTRIB

        (In order to obtain these definitions, the _GNU_SOURCE feature test macro must be defined before including any header files.)

        Directory notifications are normally "one-shot", and the application must reregister to receive further notifications. Alternatively, if DN_MULTISHOT is included in arg, then notification will remain in effect until explicitly removed.

        A series of F_NOTIFY requests is cumulative, with the events in arg being added to the set already monitored. To disable notification of all events, make an F_NOTIFY call specifying arg as 0.

        Notification occurs via delivery of a signal. The default signal is SIGIO, but this can be changed using the F_SETSIG command to fcntl(). (Note that SIGIO is one of the nonqueuing standard signals; switching to the use of a real-time signal means that multiple notifications can be queued to the process.) In the latter case, the signal handler receives a siginfo_t structure as its second argument (if the handler was established using SA_SIGINFO) and the si_fd field of this structure contains the file descriptor which generated the notification (useful when establishing notification on multiple directories).

        Especially when using DN_MULTISHOT, a real time signal should be used for notification, so that multiple notifications can be queued.

        NOTE: New applications should use the inotify interface (available since kernel 2.6.13), which provides a much superior interface for obtaining notifications of filesystem events. See inotify(7).

      • F_SETPIPE_SZ - Change the capacity of the pipe referred to by fd to be at least arg bytes.

        An unprivileged process can adjust the pipe capacity to any value between the system page size and the limit defined in /proc/sys/fs/pipe-max-size (see proc(5)). Attempts to set the pipe capacity below the page size are silently rounded up to the page size. Attempts by an unprivileged process to set the pipe capacity above the limit in /proc/sys/fs/pipe-max-size yield the error EPERM; a privileged process (CAP_SYS_RESOURCE) can override the limit.

        When allocating the buffer for the pipe, the kernel may use a capacity larger than arg, if that is convenient for the implementation. (In the current implementation, the allocation is the next higher power-of-two page-size multiple of the requested size.) The actual capacity (in bytes) that is set is returned as the function result.

        Attempting to set the pipe capacity smaller than the amount of buffer space currently used to store data produces the error EBUSY.

        Note that because of the way the pages of the pipe buffer are employed when data is written to the pipe, the number of bytes that can be written may be less than the nominal size, depending on the size of the writes.

      • F_GETPIPE_SZ - Return (as the function result) the capacity of the pipe referred to by fd.
      • F_ADD_SEALS - Add the seals given in the bit-mask argument arg to the set of seals of the inode referred to by the file descriptor fd.

        Seals cannot be removed again. Once this call succeeds, the seals are enforced by the kernel immediately. If the current set of seals includes F_SEAL_SEAL (see below), then this call will be rejected with EPERM. Adding a seal that is already set is a no-op, in case F_SEAL_SEAL is not set already. In order to place a seal, the file descriptor fd must be writable.

      • F_GET_SEALS - Return (as the function result) the current set of seals of the inode referred to by fd.

        If no seals are set, 0 is returned. If the file does not support sealing, -1 is returned and errno is set to EINVAL.

      • F_GET_RW_HINT - Returns the value of the read/write hint associated with the underlying inode referred to by fd.
      • F_SET_RW_HINT - Sets the read/write hint value associated with the underlying inode referred to by fd.

        This hint persists until either it is explicitly modified or the underlying filesystem is unmounted.

      • F_GET_FILE_RW_HINT - Returns the value of the read/write hint associated with the open file description referred to by fd.
      • F_SET_FILE_RW_HINT - Sets the read/write hint value associated with the open file description referred to by fd.
      • F_DUPFD_CLOEXEC - As for F_DUPFD, but additionally set the close-on-exec flag for the duplicate file descriptor.

        Specifying this flag permits a program to avoid an additional fcntl() F_SETFD operation to set the FD_CLOEXEC flag. For an explanation of why this flag is useful, see the description of O_CLOEXEC in open(2).

      See Also:

    • F_GETOWN_EX

      public static final int F_GETOWN_EX
      fcntl(int, int) commands.
      Enum values:
      • F_DUPFD - Duplicate the file descriptor fd using the lowest-numbered available file descriptor greater than or equal to arg.

        This is different from dup2(2), which uses exactly the file descriptor specified.

        On success, the new file descriptor is returned.

        See dup(2) for further details.

      • F_GETFD - Return (as the function result) the file descriptor flags; arg is ignored.
      • F_SETFD - Set the file descriptor flags to the value specified by arg.
      • F_GETFL - Return (as the function result) the file access mode and the file status flags; arg is ignored.
      • F_SETFL - Set the file status flags to the value specified by arg.

        File access mode (O_RDONLY, O_WRONLY, O_RDWR) and file creation flags (i.e., O_CREAT, O_EXCL, O_NOCTTY, O_TRUNC) in arg are ignored. On Linux, this command can change only the O_APPEND, O_ASYNC, O_DIRECT, O_NOATIME, and O_NONBLOCK flags. It is not possible to change the O_DSYNC and O_SYNC flags; see BUGS, below.

      • F_GETLK - On input to this call, lock describes a lock we would like to place on the file.

        If the lock could be placed, fcntl() does not actually place it, but returns F_UNLCK in the l_type field of lock and leaves the other fields of the structure unchanged.

        If one or more incompatible locks would prevent this lock being placed, then fcntl() returns details about one of those locks in the l_type, l_whence, l_start, and l_len fields of lock. If the conflicting lock is a traditional (process-associated) record lock, then the l_pid field is set to the PID of the process holding that lock. If the conflicting lock is an open file description lock, then l_pid is set to -1. Note that the returned information may already be out of date by the time the caller inspects it.

      • F_SETLK - Acquire a lock (when l_type is F_RDLCK or F_WRLCK) or release a lock (when l_type is F_UNLCK) on the bytes specified by the l_whence, l_start, and l_len fields of lock.

        If a conflicting lock is held by another process, this call returns -1 and sets errno to EACCES or EAGAIN. (The error returned in this case differs across implementations, so POSIX requires a portable application to check for both errors.)

      • F_SETLKW - As for F_SETLK, but if a conflicting lock is held on the file, then wait for that lock to be released.

        If a signal is caught while waiting, then the call is interrupted and (after the signal handler has returned) returns immediately (with return value -1 and errno set to EINTR; see signal(7)).

      • F_SETOWN - Set the process ID or process group ID that will receive SIGIO and SIGURG signals for events on the file descriptor fd.

        The target process or process group ID is specified in arg. A process ID is specified as a positive value; a process group ID is specified as a negative value. Most commonly, the calling process specifies itself as the owner (that is, arg is specified as getpid(2)).

        As well as setting the file descriptor owner, one must also enable generation of signals on the file descriptor. This is done by using the fcntl() F_SETFL command to set the O_ASYNC file status flag on the file descriptor. Subsequently, a SIGIO signal is sent whenever input or output becomes possible on the file descriptor. The fcntl() F_SETSIG command can be used to obtain delivery of a signal other than SIGIO.

        Sending a signal to the owner process (group) specified by F_SETOWN is subject to the same permissions checks as are described for kill(2), where the sending process is the one that employs F_SETOWN (but see BUGS below). If this permission check fails, then the signal is silently discarded. Note: The F_SETOWN operation records the caller's credentials at the time of the fcntl() call, and it is these saved credentials that are used for the permission checks.

        If the file descriptor fd refers to a socket, F_SETOWN also selects the recipient of SIGURG signals that are delivered when out-of-band data arrives on that socket. (SIGURG is sent in any situation where select(2) would report the socket as having an "exceptional condition".)

        The following was true in 2.6.x kernels up to and including kernel 2.6.11:

        If a nonzero value is given to F_SETSIG in a multithreaded process running with a threading library that supports thread groups (e.g., NPTL), then a positive value given to F_SETOWN has a different meaning: instead of being a process ID identifying a whole process, it is a thread ID identifying a specific thread within a process. Consequently, it may be necessary to pass F_SETOWN the result of gettid(2) instead of getpid(2) to get sensible results when F_SETSIG is used. (In current Linux threading implementations, a main thread's thread ID is the same as its process ID. This means that a single-threaded program can equally use gettid(2) or getpid(2) in this scenario.) Note, however, that the statements in this paragraph do not apply to the SIGURG signal generated for out-of-band data on a socket: this signal is always sent to either a process or a process group, depending on the value given to F_SETOWN.

        The above behavior was accidentally dropped in Linux 2.6.12, and won't be restored. From Linux 2.6.32 onward, use F_SETOWN_EX to target SIGIO and SIGURG signals at a particular thread.

      • F_GETOWN - Return (as the function result) the process ID or process group ID currently receiving SIGIO and SIGURG signals for events on file descriptor fd.

        Process IDs are returned as positive values; process group IDs are returned as negative values (but see BUGS below). arg is ignored.

      • F_SETSIG - Set the signal sent when input or output becomes possible to the value given in arg.

        A value of zero means to send the default SIGIO signal. Any other value (including SIGIO) is the signal to send instead, and in this case additional info is available to the signal handler if installed with SA_SIGINFO.

        By using F_SETSIG with a nonzero value, and setting SA_SIGINFO for the signal handler (see sigaction(2)), extra information about I/O events is passed to the handler in a siginfo_t structure. If the si_code field indicates the source is SI_SIGIO, the si_fd field gives the file descriptor associated with the event. Otherwise, there is no indication which file descriptors are pending, and you should use the usual mechanisms (select(2), poll(2), read(2) with O_NONBLOCK set etc.) to determine which file descriptors are available for I/O.

        Note that the file descriptor provided in si_fd is the one that was specified during the F_SETSIG operation. This can lead to an unusual corner case. If the file descriptor is duplicated (dup(2) or similar), and the original file descriptor is closed, then I/O events will continue to be generated, but the si_fd field will contain the number of the now closed file descriptor.

        By selecting a real time signal (value ≥ SIGRTMIN), multiple I/O events may be queued using the same signal numbers. (Queuing is dependent on available memory.) Extra information is available if SA_SIGINFO is set for the signal handler, as above.

        Note that Linux imposes a limit on the number of real-time signals that may be queued to a process (see getrlimit(2) and signal(7)) and if this limit is reached, then the kernel reverts to delivering SIGIO, and this signal is delivered to the entire process rather than to a specific thread.

      • F_GETSIG - Return (as the function result) the signal sent when input or output becomes possible.

        A value of zero means SIGIO is sent. Any other value (including SIGIO) is the signal sent instead, and in this case additional info is available to the signal handler if installed with SA_SIGINFO. arg is ignored.

      • F_SETOWN_EX - This operation performs a similar task to F_SETOWN. It allows the caller to direct I/O availability signals to a specific thread, process, or process group.

        The caller specifies the target of signals via arg, which is a pointer to a FOwnerEx structure. The type field has one of the following values, which define how pid is interpreted: F_OWNER_TID, F_OWNER_PID, F_OWNER_PGRP.

      • F_GETOWN_EX - Return the current file descriptor owner settings as defined by a previous F_SETOWN_EX operation.

        The information is returned in the FOwnerEx structure pointed to by arg.

        The type field will have one of the values F_OWNER_TID, F_OWNER_PID, or F_OWNER_PGRP. The pid field is a positive integer representing a thread ID, process ID, or process group ID. See F_SETOWN_EX for more details.

      • F_OFD_GETLK - On input to this call, lock describes an open file description lock we would like to place on the file.

        If the lock could be placed, fcntl() does not actually place it, but returns F_UNLCK in the l_type field of lock and leaves the other fields of the structure unchanged. If one or more incompatible locks would prevent this lock being placed, then details about one of these locks are returned via lock, as described above for F_GETLK.

      • F_OFD_SETLK - Acquire an open file description lock (when l_type is F_RDLCK or F_WRLCK) or release an open file description lock (when l_type is F_UNLCK) on the bytes specified by the l_whence, l_start, and l_len fields of lock.

        If a conflicting lock is held by another process, this call returns -1 and sets errno to EAGAIN.

      • F_OFD_SETLKW - As for F_OFD_SETLK, but if a conflicting lock is held on the file, then wait for that lock to be released.

        If a signal is caught while waiting, then the call is interrupted and (after the signal handler has returned) returns immediately (with return value -1 and errno set to EINTR; see signal(7)).

      • F_SETLEASE - Set or remove a file lease according to which of the following values is specified in the integer arg: F_RDLCK, F_WRLCK, F_UNLCK
      • F_GETLEASE - Indicates what type of lease is associated with the file descriptor fd by returning either F_RDLCK, F_WRLCK, or F_UNLCK, indicating, respectively, a read lease, a write lease, or no lease. arg is ignored.
      • F_NOTIFY - (Linux 2.4 onward) Provide notification when the directory referred to by fd or any of the files that it contains is changed.

        The events to be notified are specified in arg, which is a bit mask specified by ORing together zero or more of the following bits: DN_ACCESS, DN_MODIFY, DN_CREATE, DN_DELETE, DN_RENAME, DN_ATTRIB

        (In order to obtain these definitions, the _GNU_SOURCE feature test macro must be defined before including any header files.)

        Directory notifications are normally "one-shot", and the application must reregister to receive further notifications. Alternatively, if DN_MULTISHOT is included in arg, then notification will remain in effect until explicitly removed.

        A series of F_NOTIFY requests is cumulative, with the events in arg being added to the set already monitored. To disable notification of all events, make an F_NOTIFY call specifying arg as 0.

        Notification occurs via delivery of a signal. The default signal is SIGIO, but this can be changed using the F_SETSIG command to fcntl(). (Note that SIGIO is one of the nonqueuing standard signals; switching to the use of a real-time signal means that multiple notifications can be queued to the process.) In the latter case, the signal handler receives a siginfo_t structure as its second argument (if the handler was established using SA_SIGINFO) and the si_fd field of this structure contains the file descriptor which generated the notification (useful when establishing notification on multiple directories).

        Especially when using DN_MULTISHOT, a real time signal should be used for notification, so that multiple notifications can be queued.

        NOTE: New applications should use the inotify interface (available since kernel 2.6.13), which provides a much superior interface for obtaining notifications of filesystem events. See inotify(7).

      • F_SETPIPE_SZ - Change the capacity of the pipe referred to by fd to be at least arg bytes.

        An unprivileged process can adjust the pipe capacity to any value between the system page size and the limit defined in /proc/sys/fs/pipe-max-size (see proc(5)). Attempts to set the pipe capacity below the page size are silently rounded up to the page size. Attempts by an unprivileged process to set the pipe capacity above the limit in /proc/sys/fs/pipe-max-size yield the error EPERM; a privileged process (CAP_SYS_RESOURCE) can override the limit.

        When allocating the buffer for the pipe, the kernel may use a capacity larger than arg, if that is convenient for the implementation. (In the current implementation, the allocation is the next higher power-of-two page-size multiple of the requested size.) The actual capacity (in bytes) that is set is returned as the function result.

        Attempting to set the pipe capacity smaller than the amount of buffer space currently used to store data produces the error EBUSY.

        Note that because of the way the pages of the pipe buffer are employed when data is written to the pipe, the number of bytes that can be written may be less than the nominal size, depending on the size of the writes.

      • F_GETPIPE_SZ - Return (as the function result) the capacity of the pipe referred to by fd.
      • F_ADD_SEALS - Add the seals given in the bit-mask argument arg to the set of seals of the inode referred to by the file descriptor fd.

        Seals cannot be removed again. Once this call succeeds, the seals are enforced by the kernel immediately. If the current set of seals includes F_SEAL_SEAL (see below), then this call will be rejected with EPERM. Adding a seal that is already set is a no-op, in case F_SEAL_SEAL is not set already. In order to place a seal, the file descriptor fd must be writable.

      • F_GET_SEALS - Return (as the function result) the current set of seals of the inode referred to by fd.

        If no seals are set, 0 is returned. If the file does not support sealing, -1 is returned and errno is set to EINVAL.

      • F_GET_RW_HINT - Returns the value of the read/write hint associated with the underlying inode referred to by fd.
      • F_SET_RW_HINT - Sets the read/write hint value associated with the underlying inode referred to by fd.

        This hint persists until either it is explicitly modified or the underlying filesystem is unmounted.

      • F_GET_FILE_RW_HINT - Returns the value of the read/write hint associated with the open file description referred to by fd.
      • F_SET_FILE_RW_HINT - Sets the read/write hint value associated with the open file description referred to by fd.
      • F_DUPFD_CLOEXEC - As for F_DUPFD, but additionally set the close-on-exec flag for the duplicate file descriptor.

        Specifying this flag permits a program to avoid an additional fcntl() F_SETFD operation to set the FD_CLOEXEC flag. For an explanation of why this flag is useful, see the description of O_CLOEXEC in open(2).

      See Also:

    • F_OFD_GETLK

      public static final int F_OFD_GETLK
      fcntl(int, int) commands.
      Enum values:
      • F_DUPFD - Duplicate the file descriptor fd using the lowest-numbered available file descriptor greater than or equal to arg.

        This is different from dup2(2), which uses exactly the file descriptor specified.

        On success, the new file descriptor is returned.

        See dup(2) for further details.

      • F_GETFD - Return (as the function result) the file descriptor flags; arg is ignored.
      • F_SETFD - Set the file descriptor flags to the value specified by arg.
      • F_GETFL - Return (as the function result) the file access mode and the file status flags; arg is ignored.
      • F_SETFL - Set the file status flags to the value specified by arg.

        File access mode (O_RDONLY, O_WRONLY, O_RDWR) and file creation flags (i.e., O_CREAT, O_EXCL, O_NOCTTY, O_TRUNC) in arg are ignored. On Linux, this command can change only the O_APPEND, O_ASYNC, O_DIRECT, O_NOATIME, and O_NONBLOCK flags. It is not possible to change the O_DSYNC and O_SYNC flags; see BUGS, below.

      • F_GETLK - On input to this call, lock describes a lock we would like to place on the file.

        If the lock could be placed, fcntl() does not actually place it, but returns F_UNLCK in the l_type field of lock and leaves the other fields of the structure unchanged.

        If one or more incompatible locks would prevent this lock being placed, then fcntl() returns details about one of those locks in the l_type, l_whence, l_start, and l_len fields of lock. If the conflicting lock is a traditional (process-associated) record lock, then the l_pid field is set to the PID of the process holding that lock. If the conflicting lock is an open file description lock, then l_pid is set to -1. Note that the returned information may already be out of date by the time the caller inspects it.

      • F_SETLK - Acquire a lock (when l_type is F_RDLCK or F_WRLCK) or release a lock (when l_type is F_UNLCK) on the bytes specified by the l_whence, l_start, and l_len fields of lock.

        If a conflicting lock is held by another process, this call returns -1 and sets errno to EACCES or EAGAIN. (The error returned in this case differs across implementations, so POSIX requires a portable application to check for both errors.)

      • F_SETLKW - As for F_SETLK, but if a conflicting lock is held on the file, then wait for that lock to be released.

        If a signal is caught while waiting, then the call is interrupted and (after the signal handler has returned) returns immediately (with return value -1 and errno set to EINTR; see signal(7)).

      • F_SETOWN - Set the process ID or process group ID that will receive SIGIO and SIGURG signals for events on the file descriptor fd.

        The target process or process group ID is specified in arg. A process ID is specified as a positive value; a process group ID is specified as a negative value. Most commonly, the calling process specifies itself as the owner (that is, arg is specified as getpid(2)).

        As well as setting the file descriptor owner, one must also enable generation of signals on the file descriptor. This is done by using the fcntl() F_SETFL command to set the O_ASYNC file status flag on the file descriptor. Subsequently, a SIGIO signal is sent whenever input or output becomes possible on the file descriptor. The fcntl() F_SETSIG command can be used to obtain delivery of a signal other than SIGIO.

        Sending a signal to the owner process (group) specified by F_SETOWN is subject to the same permissions checks as are described for kill(2), where the sending process is the one that employs F_SETOWN (but see BUGS below). If this permission check fails, then the signal is silently discarded. Note: The F_SETOWN operation records the caller's credentials at the time of the fcntl() call, and it is these saved credentials that are used for the permission checks.

        If the file descriptor fd refers to a socket, F_SETOWN also selects the recipient of SIGURG signals that are delivered when out-of-band data arrives on that socket. (SIGURG is sent in any situation where select(2) would report the socket as having an "exceptional condition".)

        The following was true in 2.6.x kernels up to and including kernel 2.6.11:

        If a nonzero value is given to F_SETSIG in a multithreaded process running with a threading library that supports thread groups (e.g., NPTL), then a positive value given to F_SETOWN has a different meaning: instead of being a process ID identifying a whole process, it is a thread ID identifying a specific thread within a process. Consequently, it may be necessary to pass F_SETOWN the result of gettid(2) instead of getpid(2) to get sensible results when F_SETSIG is used. (In current Linux threading implementations, a main thread's thread ID is the same as its process ID. This means that a single-threaded program can equally use gettid(2) or getpid(2) in this scenario.) Note, however, that the statements in this paragraph do not apply to the SIGURG signal generated for out-of-band data on a socket: this signal is always sent to either a process or a process group, depending on the value given to F_SETOWN.

        The above behavior was accidentally dropped in Linux 2.6.12, and won't be restored. From Linux 2.6.32 onward, use F_SETOWN_EX to target SIGIO and SIGURG signals at a particular thread.

      • F_GETOWN - Return (as the function result) the process ID or process group ID currently receiving SIGIO and SIGURG signals for events on file descriptor fd.

        Process IDs are returned as positive values; process group IDs are returned as negative values (but see BUGS below). arg is ignored.

      • F_SETSIG - Set the signal sent when input or output becomes possible to the value given in arg.

        A value of zero means to send the default SIGIO signal. Any other value (including SIGIO) is the signal to send instead, and in this case additional info is available to the signal handler if installed with SA_SIGINFO.

        By using F_SETSIG with a nonzero value, and setting SA_SIGINFO for the signal handler (see sigaction(2)), extra information about I/O events is passed to the handler in a siginfo_t structure. If the si_code field indicates the source is SI_SIGIO, the si_fd field gives the file descriptor associated with the event. Otherwise, there is no indication which file descriptors are pending, and you should use the usual mechanisms (select(2), poll(2), read(2) with O_NONBLOCK set etc.) to determine which file descriptors are available for I/O.

        Note that the file descriptor provided in si_fd is the one that was specified during the F_SETSIG operation. This can lead to an unusual corner case. If the file descriptor is duplicated (dup(2) or similar), and the original file descriptor is closed, then I/O events will continue to be generated, but the si_fd field will contain the number of the now closed file descriptor.

        By selecting a real time signal (value ≥ SIGRTMIN), multiple I/O events may be queued using the same signal numbers. (Queuing is dependent on available memory.) Extra information is available if SA_SIGINFO is set for the signal handler, as above.

        Note that Linux imposes a limit on the number of real-time signals that may be queued to a process (see getrlimit(2) and signal(7)) and if this limit is reached, then the kernel reverts to delivering SIGIO, and this signal is delivered to the entire process rather than to a specific thread.

      • F_GETSIG - Return (as the function result) the signal sent when input or output becomes possible.

        A value of zero means SIGIO is sent. Any other value (including SIGIO) is the signal sent instead, and in this case additional info is available to the signal handler if installed with SA_SIGINFO. arg is ignored.

      • F_SETOWN_EX - This operation performs a similar task to F_SETOWN. It allows the caller to direct I/O availability signals to a specific thread, process, or process group.

        The caller specifies the target of signals via arg, which is a pointer to a FOwnerEx structure. The type field has one of the following values, which define how pid is interpreted: F_OWNER_TID, F_OWNER_PID, F_OWNER_PGRP.

      • F_GETOWN_EX - Return the current file descriptor owner settings as defined by a previous F_SETOWN_EX operation.

        The information is returned in the FOwnerEx structure pointed to by arg.

        The type field will have one of the values F_OWNER_TID, F_OWNER_PID, or F_OWNER_PGRP. The pid field is a positive integer representing a thread ID, process ID, or process group ID. See F_SETOWN_EX for more details.

      • F_OFD_GETLK - On input to this call, lock describes an open file description lock we would like to place on the file.

        If the lock could be placed, fcntl() does not actually place it, but returns F_UNLCK in the l_type field of lock and leaves the other fields of the structure unchanged. If one or more incompatible locks would prevent this lock being placed, then details about one of these locks are returned via lock, as described above for F_GETLK.

      • F_OFD_SETLK - Acquire an open file description lock (when l_type is F_RDLCK or F_WRLCK) or release an open file description lock (when l_type is F_UNLCK) on the bytes specified by the l_whence, l_start, and l_len fields of lock.

        If a conflicting lock is held by another process, this call returns -1 and sets errno to EAGAIN.

      • F_OFD_SETLKW - As for F_OFD_SETLK, but if a conflicting lock is held on the file, then wait for that lock to be released.

        If a signal is caught while waiting, then the call is interrupted and (after the signal handler has returned) returns immediately (with return value -1 and errno set to EINTR; see signal(7)).

      • F_SETLEASE - Set or remove a file lease according to which of the following values is specified in the integer arg: F_RDLCK, F_WRLCK, F_UNLCK
      • F_GETLEASE - Indicates what type of lease is associated with the file descriptor fd by returning either F_RDLCK, F_WRLCK, or F_UNLCK, indicating, respectively, a read lease, a write lease, or no lease. arg is ignored.
      • F_NOTIFY - (Linux 2.4 onward) Provide notification when the directory referred to by fd or any of the files that it contains is changed.

        The events to be notified are specified in arg, which is a bit mask specified by ORing together zero or more of the following bits: DN_ACCESS, DN_MODIFY, DN_CREATE, DN_DELETE, DN_RENAME, DN_ATTRIB

        (In order to obtain these definitions, the _GNU_SOURCE feature test macro must be defined before including any header files.)

        Directory notifications are normally "one-shot", and the application must reregister to receive further notifications. Alternatively, if DN_MULTISHOT is included in arg, then notification will remain in effect until explicitly removed.

        A series of F_NOTIFY requests is cumulative, with the events in arg being added to the set already monitored. To disable notification of all events, make an F_NOTIFY call specifying arg as 0.

        Notification occurs via delivery of a signal. The default signal is SIGIO, but this can be changed using the F_SETSIG command to fcntl(). (Note that SIGIO is one of the nonqueuing standard signals; switching to the use of a real-time signal means that multiple notifications can be queued to the process.) In the latter case, the signal handler receives a siginfo_t structure as its second argument (if the handler was established using SA_SIGINFO) and the si_fd field of this structure contains the file descriptor which generated the notification (useful when establishing notification on multiple directories).

        Especially when using DN_MULTISHOT, a real time signal should be used for notification, so that multiple notifications can be queued.

        NOTE: New applications should use the inotify interface (available since kernel 2.6.13), which provides a much superior interface for obtaining notifications of filesystem events. See inotify(7).

      • F_SETPIPE_SZ - Change the capacity of the pipe referred to by fd to be at least arg bytes.

        An unprivileged process can adjust the pipe capacity to any value between the system page size and the limit defined in /proc/sys/fs/pipe-max-size (see proc(5)). Attempts to set the pipe capacity below the page size are silently rounded up to the page size. Attempts by an unprivileged process to set the pipe capacity above the limit in /proc/sys/fs/pipe-max-size yield the error EPERM; a privileged process (CAP_SYS_RESOURCE) can override the limit.

        When allocating the buffer for the pipe, the kernel may use a capacity larger than arg, if that is convenient for the implementation. (In the current implementation, the allocation is the next higher power-of-two page-size multiple of the requested size.) The actual capacity (in bytes) that is set is returned as the function result.

        Attempting to set the pipe capacity smaller than the amount of buffer space currently used to store data produces the error EBUSY.

        Note that because of the way the pages of the pipe buffer are employed when data is written to the pipe, the number of bytes that can be written may be less than the nominal size, depending on the size of the writes.

      • F_GETPIPE_SZ - Return (as the function result) the capacity of the pipe referred to by fd.
      • F_ADD_SEALS - Add the seals given in the bit-mask argument arg to the set of seals of the inode referred to by the file descriptor fd.

        Seals cannot be removed again. Once this call succeeds, the seals are enforced by the kernel immediately. If the current set of seals includes F_SEAL_SEAL (see below), then this call will be rejected with EPERM. Adding a seal that is already set is a no-op, in case F_SEAL_SEAL is not set already. In order to place a seal, the file descriptor fd must be writable.

      • F_GET_SEALS - Return (as the function result) the current set of seals of the inode referred to by fd.

        If no seals are set, 0 is returned. If the file does not support sealing, -1 is returned and errno is set to EINVAL.

      • F_GET_RW_HINT - Returns the value of the read/write hint associated with the underlying inode referred to by fd.
      • F_SET_RW_HINT - Sets the read/write hint value associated with the underlying inode referred to by fd.

        This hint persists until either it is explicitly modified or the underlying filesystem is unmounted.

      • F_GET_FILE_RW_HINT - Returns the value of the read/write hint associated with the open file description referred to by fd.
      • F_SET_FILE_RW_HINT - Sets the read/write hint value associated with the open file description referred to by fd.
      • F_DUPFD_CLOEXEC - As for F_DUPFD, but additionally set the close-on-exec flag for the duplicate file descriptor.

        Specifying this flag permits a program to avoid an additional fcntl() F_SETFD operation to set the FD_CLOEXEC flag. For an explanation of why this flag is useful, see the description of O_CLOEXEC in open(2).

      See Also:

    • F_OFD_SETLK

      public static final int F_OFD_SETLK
      fcntl(int, int) commands.
      Enum values:
      • F_DUPFD - Duplicate the file descriptor fd using the lowest-numbered available file descriptor greater than or equal to arg.

        This is different from dup2(2), which uses exactly the file descriptor specified.

        On success, the new file descriptor is returned.

        See dup(2) for further details.

      • F_GETFD - Return (as the function result) the file descriptor flags; arg is ignored.
      • F_SETFD - Set the file descriptor flags to the value specified by arg.
      • F_GETFL - Return (as the function result) the file access mode and the file status flags; arg is ignored.
      • F_SETFL - Set the file status flags to the value specified by arg.

        File access mode (O_RDONLY, O_WRONLY, O_RDWR) and file creation flags (i.e., O_CREAT, O_EXCL, O_NOCTTY, O_TRUNC) in arg are ignored. On Linux, this command can change only the O_APPEND, O_ASYNC, O_DIRECT, O_NOATIME, and O_NONBLOCK flags. It is not possible to change the O_DSYNC and O_SYNC flags; see BUGS, below.

      • F_GETLK - On input to this call, lock describes a lock we would like to place on the file.

        If the lock could be placed, fcntl() does not actually place it, but returns F_UNLCK in the l_type field of lock and leaves the other fields of the structure unchanged.

        If one or more incompatible locks would prevent this lock being placed, then fcntl() returns details about one of those locks in the l_type, l_whence, l_start, and l_len fields of lock. If the conflicting lock is a traditional (process-associated) record lock, then the l_pid field is set to the PID of the process holding that lock. If the conflicting lock is an open file description lock, then l_pid is set to -1. Note that the returned information may already be out of date by the time the caller inspects it.

      • F_SETLK - Acquire a lock (when l_type is F_RDLCK or F_WRLCK) or release a lock (when l_type is F_UNLCK) on the bytes specified by the l_whence, l_start, and l_len fields of lock.

        If a conflicting lock is held by another process, this call returns -1 and sets errno to EACCES or EAGAIN. (The error returned in this case differs across implementations, so POSIX requires a portable application to check for both errors.)

      • F_SETLKW - As for F_SETLK, but if a conflicting lock is held on the file, then wait for that lock to be released.

        If a signal is caught while waiting, then the call is interrupted and (after the signal handler has returned) returns immediately (with return value -1 and errno set to EINTR; see signal(7)).

      • F_SETOWN - Set the process ID or process group ID that will receive SIGIO and SIGURG signals for events on the file descriptor fd.

        The target process or process group ID is specified in arg. A process ID is specified as a positive value; a process group ID is specified as a negative value. Most commonly, the calling process specifies itself as the owner (that is, arg is specified as getpid(2)).

        As well as setting the file descriptor owner, one must also enable generation of signals on the file descriptor. This is done by using the fcntl() F_SETFL command to set the O_ASYNC file status flag on the file descriptor. Subsequently, a SIGIO signal is sent whenever input or output becomes possible on the file descriptor. The fcntl() F_SETSIG command can be used to obtain delivery of a signal other than SIGIO.

        Sending a signal to the owner process (group) specified by F_SETOWN is subject to the same permissions checks as are described for kill(2), where the sending process is the one that employs F_SETOWN (but see BUGS below). If this permission check fails, then the signal is silently discarded. Note: The F_SETOWN operation records the caller's credentials at the time of the fcntl() call, and it is these saved credentials that are used for the permission checks.

        If the file descriptor fd refers to a socket, F_SETOWN also selects the recipient of SIGURG signals that are delivered when out-of-band data arrives on that socket. (SIGURG is sent in any situation where select(2) would report the socket as having an "exceptional condition".)

        The following was true in 2.6.x kernels up to and including kernel 2.6.11:

        If a nonzero value is given to F_SETSIG in a multithreaded process running with a threading library that supports thread groups (e.g., NPTL), then a positive value given to F_SETOWN has a different meaning: instead of being a process ID identifying a whole process, it is a thread ID identifying a specific thread within a process. Consequently, it may be necessary to pass F_SETOWN the result of gettid(2) instead of getpid(2) to get sensible results when F_SETSIG is used. (In current Linux threading implementations, a main thread's thread ID is the same as its process ID. This means that a single-threaded program can equally use gettid(2) or getpid(2) in this scenario.) Note, however, that the statements in this paragraph do not apply to the SIGURG signal generated for out-of-band data on a socket: this signal is always sent to either a process or a process group, depending on the value given to F_SETOWN.

        The above behavior was accidentally dropped in Linux 2.6.12, and won't be restored. From Linux 2.6.32 onward, use F_SETOWN_EX to target SIGIO and SIGURG signals at a particular thread.

      • F_GETOWN - Return (as the function result) the process ID or process group ID currently receiving SIGIO and SIGURG signals for events on file descriptor fd.

        Process IDs are returned as positive values; process group IDs are returned as negative values (but see BUGS below). arg is ignored.

      • F_SETSIG - Set the signal sent when input or output becomes possible to the value given in arg.

        A value of zero means to send the default SIGIO signal. Any other value (including SIGIO) is the signal to send instead, and in this case additional info is available to the signal handler if installed with SA_SIGINFO.

        By using F_SETSIG with a nonzero value, and setting SA_SIGINFO for the signal handler (see sigaction(2)), extra information about I/O events is passed to the handler in a siginfo_t structure. If the si_code field indicates the source is SI_SIGIO, the si_fd field gives the file descriptor associated with the event. Otherwise, there is no indication which file descriptors are pending, and you should use the usual mechanisms (select(2), poll(2), read(2) with O_NONBLOCK set etc.) to determine which file descriptors are available for I/O.

        Note that the file descriptor provided in si_fd is the one that was specified during the F_SETSIG operation. This can lead to an unusual corner case. If the file descriptor is duplicated (dup(2) or similar), and the original file descriptor is closed, then I/O events will continue to be generated, but the si_fd field will contain the number of the now closed file descriptor.

        By selecting a real time signal (value ≥ SIGRTMIN), multiple I/O events may be queued using the same signal numbers. (Queuing is dependent on available memory.) Extra information is available if SA_SIGINFO is set for the signal handler, as above.

        Note that Linux imposes a limit on the number of real-time signals that may be queued to a process (see getrlimit(2) and signal(7)) and if this limit is reached, then the kernel reverts to delivering SIGIO, and this signal is delivered to the entire process rather than to a specific thread.

      • F_GETSIG - Return (as the function result) the signal sent when input or output becomes possible.

        A value of zero means SIGIO is sent. Any other value (including SIGIO) is the signal sent instead, and in this case additional info is available to the signal handler if installed with SA_SIGINFO. arg is ignored.

      • F_SETOWN_EX - This operation performs a similar task to F_SETOWN. It allows the caller to direct I/O availability signals to a specific thread, process, or process group.

        The caller specifies the target of signals via arg, which is a pointer to a FOwnerEx structure. The type field has one of the following values, which define how pid is interpreted: F_OWNER_TID, F_OWNER_PID, F_OWNER_PGRP.

      • F_GETOWN_EX - Return the current file descriptor owner settings as defined by a previous F_SETOWN_EX operation.

        The information is returned in the FOwnerEx structure pointed to by arg.

        The type field will have one of the values F_OWNER_TID, F_OWNER_PID, or F_OWNER_PGRP. The pid field is a positive integer representing a thread ID, process ID, or process group ID. See F_SETOWN_EX for more details.

      • F_OFD_GETLK - On input to this call, lock describes an open file description lock we would like to place on the file.

        If the lock could be placed, fcntl() does not actually place it, but returns F_UNLCK in the l_type field of lock and leaves the other fields of the structure unchanged. If one or more incompatible locks would prevent this lock being placed, then details about one of these locks are returned via lock, as described above for F_GETLK.

      • F_OFD_SETLK - Acquire an open file description lock (when l_type is F_RDLCK or F_WRLCK) or release an open file description lock (when l_type is F_UNLCK) on the bytes specified by the l_whence, l_start, and l_len fields of lock.

        If a conflicting lock is held by another process, this call returns -1 and sets errno to EAGAIN.

      • F_OFD_SETLKW - As for F_OFD_SETLK, but if a conflicting lock is held on the file, then wait for that lock to be released.

        If a signal is caught while waiting, then the call is interrupted and (after the signal handler has returned) returns immediately (with return value -1 and errno set to EINTR; see signal(7)).

      • F_SETLEASE - Set or remove a file lease according to which of the following values is specified in the integer arg: F_RDLCK, F_WRLCK, F_UNLCK
      • F_GETLEASE - Indicates what type of lease is associated with the file descriptor fd by returning either F_RDLCK, F_WRLCK, or F_UNLCK, indicating, respectively, a read lease, a write lease, or no lease. arg is ignored.
      • F_NOTIFY - (Linux 2.4 onward) Provide notification when the directory referred to by fd or any of the files that it contains is changed.

        The events to be notified are specified in arg, which is a bit mask specified by ORing together zero or more of the following bits: DN_ACCESS, DN_MODIFY, DN_CREATE, DN_DELETE, DN_RENAME, DN_ATTRIB

        (In order to obtain these definitions, the _GNU_SOURCE feature test macro must be defined before including any header files.)

        Directory notifications are normally "one-shot", and the application must reregister to receive further notifications. Alternatively, if DN_MULTISHOT is included in arg, then notification will remain in effect until explicitly removed.

        A series of F_NOTIFY requests is cumulative, with the events in arg being added to the set already monitored. To disable notification of all events, make an F_NOTIFY call specifying arg as 0.

        Notification occurs via delivery of a signal. The default signal is SIGIO, but this can be changed using the F_SETSIG command to fcntl(). (Note that SIGIO is one of the nonqueuing standard signals; switching to the use of a real-time signal means that multiple notifications can be queued to the process.) In the latter case, the signal handler receives a siginfo_t structure as its second argument (if the handler was established using SA_SIGINFO) and the si_fd field of this structure contains the file descriptor which generated the notification (useful when establishing notification on multiple directories).

        Especially when using DN_MULTISHOT, a real time signal should be used for notification, so that multiple notifications can be queued.

        NOTE: New applications should use the inotify interface (available since kernel 2.6.13), which provides a much superior interface for obtaining notifications of filesystem events. See inotify(7).

      • F_SETPIPE_SZ - Change the capacity of the pipe referred to by fd to be at least arg bytes.

        An unprivileged process can adjust the pipe capacity to any value between the system page size and the limit defined in /proc/sys/fs/pipe-max-size (see proc(5)). Attempts to set the pipe capacity below the page size are silently rounded up to the page size. Attempts by an unprivileged process to set the pipe capacity above the limit in /proc/sys/fs/pipe-max-size yield the error EPERM; a privileged process (CAP_SYS_RESOURCE) can override the limit.

        When allocating the buffer for the pipe, the kernel may use a capacity larger than arg, if that is convenient for the implementation. (In the current implementation, the allocation is the next higher power-of-two page-size multiple of the requested size.) The actual capacity (in bytes) that is set is returned as the function result.

        Attempting to set the pipe capacity smaller than the amount of buffer space currently used to store data produces the error EBUSY.

        Note that because of the way the pages of the pipe buffer are employed when data is written to the pipe, the number of bytes that can be written may be less than the nominal size, depending on the size of the writes.

      • F_GETPIPE_SZ - Return (as the function result) the capacity of the pipe referred to by fd.
      • F_ADD_SEALS - Add the seals given in the bit-mask argument arg to the set of seals of the inode referred to by the file descriptor fd.

        Seals cannot be removed again. Once this call succeeds, the seals are enforced by the kernel immediately. If the current set of seals includes F_SEAL_SEAL (see below), then this call will be rejected with EPERM. Adding a seal that is already set is a no-op, in case F_SEAL_SEAL is not set already. In order to place a seal, the file descriptor fd must be writable.

      • F_GET_SEALS - Return (as the function result) the current set of seals of the inode referred to by fd.

        If no seals are set, 0 is returned. If the file does not support sealing, -1 is returned and errno is set to EINVAL.

      • F_GET_RW_HINT - Returns the value of the read/write hint associated with the underlying inode referred to by fd.
      • F_SET_RW_HINT - Sets the read/write hint value associated with the underlying inode referred to by fd.

        This hint persists until either it is explicitly modified or the underlying filesystem is unmounted.

      • F_GET_FILE_RW_HINT - Returns the value of the read/write hint associated with the open file description referred to by fd.
      • F_SET_FILE_RW_HINT - Sets the read/write hint value associated with the open file description referred to by fd.
      • F_DUPFD_CLOEXEC - As for F_DUPFD, but additionally set the close-on-exec flag for the duplicate file descriptor.

        Specifying this flag permits a program to avoid an additional fcntl() F_SETFD operation to set the FD_CLOEXEC flag. For an explanation of why this flag is useful, see the description of O_CLOEXEC in open(2).

      See Also:

    • F_OFD_SETLKW

      public static final int F_OFD_SETLKW
      fcntl(int, int) commands.
      Enum values:
      • F_DUPFD - Duplicate the file descriptor fd using the lowest-numbered available file descriptor greater than or equal to arg.

        This is different from dup2(2), which uses exactly the file descriptor specified.

        On success, the new file descriptor is returned.

        See dup(2) for further details.

      • F_GETFD - Return (as the function result) the file descriptor flags; arg is ignored.
      • F_SETFD - Set the file descriptor flags to the value specified by arg.
      • F_GETFL - Return (as the function result) the file access mode and the file status flags; arg is ignored.
      • F_SETFL - Set the file status flags to the value specified by arg.

        File access mode (O_RDONLY, O_WRONLY, O_RDWR) and file creation flags (i.e., O_CREAT, O_EXCL, O_NOCTTY, O_TRUNC) in arg are ignored. On Linux, this command can change only the O_APPEND, O_ASYNC, O_DIRECT, O_NOATIME, and O_NONBLOCK flags. It is not possible to change the O_DSYNC and O_SYNC flags; see BUGS, below.

      • F_GETLK - On input to this call, lock describes a lock we would like to place on the file.

        If the lock could be placed, fcntl() does not actually place it, but returns F_UNLCK in the l_type field of lock and leaves the other fields of the structure unchanged.

        If one or more incompatible locks would prevent this lock being placed, then fcntl() returns details about one of those locks in the l_type, l_whence, l_start, and l_len fields of lock. If the conflicting lock is a traditional (process-associated) record lock, then the l_pid field is set to the PID of the process holding that lock. If the conflicting lock is an open file description lock, then l_pid is set to -1. Note that the returned information may already be out of date by the time the caller inspects it.

      • F_SETLK - Acquire a lock (when l_type is F_RDLCK or F_WRLCK) or release a lock (when l_type is F_UNLCK) on the bytes specified by the l_whence, l_start, and l_len fields of lock.

        If a conflicting lock is held by another process, this call returns -1 and sets errno to EACCES or EAGAIN. (The error returned in this case differs across implementations, so POSIX requires a portable application to check for both errors.)

      • F_SETLKW - As for F_SETLK, but if a conflicting lock is held on the file, then wait for that lock to be released.

        If a signal is caught while waiting, then the call is interrupted and (after the signal handler has returned) returns immediately (with return value -1 and errno set to EINTR; see signal(7)).

      • F_SETOWN - Set the process ID or process group ID that will receive SIGIO and SIGURG signals for events on the file descriptor fd.

        The target process or process group ID is specified in arg. A process ID is specified as a positive value; a process group ID is specified as a negative value. Most commonly, the calling process specifies itself as the owner (that is, arg is specified as getpid(2)).

        As well as setting the file descriptor owner, one must also enable generation of signals on the file descriptor. This is done by using the fcntl() F_SETFL command to set the O_ASYNC file status flag on the file descriptor. Subsequently, a SIGIO signal is sent whenever input or output becomes possible on the file descriptor. The fcntl() F_SETSIG command can be used to obtain delivery of a signal other than SIGIO.

        Sending a signal to the owner process (group) specified by F_SETOWN is subject to the same permissions checks as are described for kill(2), where the sending process is the one that employs F_SETOWN (but see BUGS below). If this permission check fails, then the signal is silently discarded. Note: The F_SETOWN operation records the caller's credentials at the time of the fcntl() call, and it is these saved credentials that are used for the permission checks.

        If the file descriptor fd refers to a socket, F_SETOWN also selects the recipient of SIGURG signals that are delivered when out-of-band data arrives on that socket. (SIGURG is sent in any situation where select(2) would report the socket as having an "exceptional condition".)

        The following was true in 2.6.x kernels up to and including kernel 2.6.11:

        If a nonzero value is given to F_SETSIG in a multithreaded process running with a threading library that supports thread groups (e.g., NPTL), then a positive value given to F_SETOWN has a different meaning: instead of being a process ID identifying a whole process, it is a thread ID identifying a specific thread within a process. Consequently, it may be necessary to pass F_SETOWN the result of gettid(2) instead of getpid(2) to get sensible results when F_SETSIG is used. (In current Linux threading implementations, a main thread's thread ID is the same as its process ID. This means that a single-threaded program can equally use gettid(2) or getpid(2) in this scenario.) Note, however, that the statements in this paragraph do not apply to the SIGURG signal generated for out-of-band data on a socket: this signal is always sent to either a process or a process group, depending on the value given to F_SETOWN.

        The above behavior was accidentally dropped in Linux 2.6.12, and won't be restored. From Linux 2.6.32 onward, use F_SETOWN_EX to target SIGIO and SIGURG signals at a particular thread.

      • F_GETOWN - Return (as the function result) the process ID or process group ID currently receiving SIGIO and SIGURG signals for events on file descriptor fd.

        Process IDs are returned as positive values; process group IDs are returned as negative values (but see BUGS below). arg is ignored.

      • F_SETSIG - Set the signal sent when input or output becomes possible to the value given in arg.

        A value of zero means to send the default SIGIO signal. Any other value (including SIGIO) is the signal to send instead, and in this case additional info is available to the signal handler if installed with SA_SIGINFO.

        By using F_SETSIG with a nonzero value, and setting SA_SIGINFO for the signal handler (see sigaction(2)), extra information about I/O events is passed to the handler in a siginfo_t structure. If the si_code field indicates the source is SI_SIGIO, the si_fd field gives the file descriptor associated with the event. Otherwise, there is no indication which file descriptors are pending, and you should use the usual mechanisms (select(2), poll(2), read(2) with O_NONBLOCK set etc.) to determine which file descriptors are available for I/O.

        Note that the file descriptor provided in si_fd is the one that was specified during the F_SETSIG operation. This can lead to an unusual corner case. If the file descriptor is duplicated (dup(2) or similar), and the original file descriptor is closed, then I/O events will continue to be generated, but the si_fd field will contain the number of the now closed file descriptor.

        By selecting a real time signal (value ≥ SIGRTMIN), multiple I/O events may be queued using the same signal numbers. (Queuing is dependent on available memory.) Extra information is available if SA_SIGINFO is set for the signal handler, as above.

        Note that Linux imposes a limit on the number of real-time signals that may be queued to a process (see getrlimit(2) and signal(7)) and if this limit is reached, then the kernel reverts to delivering SIGIO, and this signal is delivered to the entire process rather than to a specific thread.

      • F_GETSIG - Return (as the function result) the signal sent when input or output becomes possible.

        A value of zero means SIGIO is sent. Any other value (including SIGIO) is the signal sent instead, and in this case additional info is available to the signal handler if installed with SA_SIGINFO. arg is ignored.

      • F_SETOWN_EX - This operation performs a similar task to F_SETOWN. It allows the caller to direct I/O availability signals to a specific thread, process, or process group.

        The caller specifies the target of signals via arg, which is a pointer to a FOwnerEx structure. The type field has one of the following values, which define how pid is interpreted: F_OWNER_TID, F_OWNER_PID, F_OWNER_PGRP.

      • F_GETOWN_EX - Return the current file descriptor owner settings as defined by a previous F_SETOWN_EX operation.

        The information is returned in the FOwnerEx structure pointed to by arg.

        The type field will have one of the values F_OWNER_TID, F_OWNER_PID, or F_OWNER_PGRP. The pid field is a positive integer representing a thread ID, process ID, or process group ID. See F_SETOWN_EX for more details.

      • F_OFD_GETLK - On input to this call, lock describes an open file description lock we would like to place on the file.

        If the lock could be placed, fcntl() does not actually place it, but returns F_UNLCK in the l_type field of lock and leaves the other fields of the structure unchanged. If one or more incompatible locks would prevent this lock being placed, then details about one of these locks are returned via lock, as described above for F_GETLK.

      • F_OFD_SETLK - Acquire an open file description lock (when l_type is F_RDLCK or F_WRLCK) or release an open file description lock (when l_type is F_UNLCK) on the bytes specified by the l_whence, l_start, and l_len fields of lock.

        If a conflicting lock is held by another process, this call returns -1 and sets errno to EAGAIN.

      • F_OFD_SETLKW - As for F_OFD_SETLK, but if a conflicting lock is held on the file, then wait for that lock to be released.

        If a signal is caught while waiting, then the call is interrupted and (after the signal handler has returned) returns immediately (with return value -1 and errno set to EINTR; see signal(7)).

      • F_SETLEASE - Set or remove a file lease according to which of the following values is specified in the integer arg: F_RDLCK, F_WRLCK, F_UNLCK
      • F_GETLEASE - Indicates what type of lease is associated with the file descriptor fd by returning either F_RDLCK, F_WRLCK, or F_UNLCK, indicating, respectively, a read lease, a write lease, or no lease. arg is ignored.
      • F_NOTIFY - (Linux 2.4 onward) Provide notification when the directory referred to by fd or any of the files that it contains is changed.

        The events to be notified are specified in arg, which is a bit mask specified by ORing together zero or more of the following bits: DN_ACCESS, DN_MODIFY, DN_CREATE, DN_DELETE, DN_RENAME, DN_ATTRIB

        (In order to obtain these definitions, the _GNU_SOURCE feature test macro must be defined before including any header files.)

        Directory notifications are normally "one-shot", and the application must reregister to receive further notifications. Alternatively, if DN_MULTISHOT is included in arg, then notification will remain in effect until explicitly removed.

        A series of F_NOTIFY requests is cumulative, with the events in arg being added to the set already monitored. To disable notification of all events, make an F_NOTIFY call specifying arg as 0.

        Notification occurs via delivery of a signal. The default signal is SIGIO, but this can be changed using the F_SETSIG command to fcntl(). (Note that SIGIO is one of the nonqueuing standard signals; switching to the use of a real-time signal means that multiple notifications can be queued to the process.) In the latter case, the signal handler receives a siginfo_t structure as its second argument (if the handler was established using SA_SIGINFO) and the si_fd field of this structure contains the file descriptor which generated the notification (useful when establishing notification on multiple directories).

        Especially when using DN_MULTISHOT, a real time signal should be used for notification, so that multiple notifications can be queued.

        NOTE: New applications should use the inotify interface (available since kernel 2.6.13), which provides a much superior interface for obtaining notifications of filesystem events. See inotify(7).

      • F_SETPIPE_SZ - Change the capacity of the pipe referred to by fd to be at least arg bytes.

        An unprivileged process can adjust the pipe capacity to any value between the system page size and the limit defined in /proc/sys/fs/pipe-max-size (see proc(5)). Attempts to set the pipe capacity below the page size are silently rounded up to the page size. Attempts by an unprivileged process to set the pipe capacity above the limit in /proc/sys/fs/pipe-max-size yield the error EPERM; a privileged process (CAP_SYS_RESOURCE) can override the limit.

        When allocating the buffer for the pipe, the kernel may use a capacity larger than arg, if that is convenient for the implementation. (In the current implementation, the allocation is the next higher power-of-two page-size multiple of the requested size.) The actual capacity (in bytes) that is set is returned as the function result.

        Attempting to set the pipe capacity smaller than the amount of buffer space currently used to store data produces the error EBUSY.

        Note that because of the way the pages of the pipe buffer are employed when data is written to the pipe, the number of bytes that can be written may be less than the nominal size, depending on the size of the writes.

      • F_GETPIPE_SZ - Return (as the function result) the capacity of the pipe referred to by fd.
      • F_ADD_SEALS - Add the seals given in the bit-mask argument arg to the set of seals of the inode referred to by the file descriptor fd.

        Seals cannot be removed again. Once this call succeeds, the seals are enforced by the kernel immediately. If the current set of seals includes F_SEAL_SEAL (see below), then this call will be rejected with EPERM. Adding a seal that is already set is a no-op, in case F_SEAL_SEAL is not set already. In order to place a seal, the file descriptor fd must be writable.

      • F_GET_SEALS - Return (as the function result) the current set of seals of the inode referred to by fd.

        If no seals are set, 0 is returned. If the file does not support sealing, -1 is returned and errno is set to EINVAL.

      • F_GET_RW_HINT - Returns the value of the read/write hint associated with the underlying inode referred to by fd.
      • F_SET_RW_HINT - Sets the read/write hint value associated with the underlying inode referred to by fd.

        This hint persists until either it is explicitly modified or the underlying filesystem is unmounted.

      • F_GET_FILE_RW_HINT - Returns the value of the read/write hint associated with the open file description referred to by fd.
      • F_SET_FILE_RW_HINT - Sets the read/write hint value associated with the open file description referred to by fd.
      • F_DUPFD_CLOEXEC - As for F_DUPFD, but additionally set the close-on-exec flag for the duplicate file descriptor.

        Specifying this flag permits a program to avoid an additional fcntl() F_SETFD operation to set the FD_CLOEXEC flag. For an explanation of why this flag is useful, see the description of O_CLOEXEC in open(2).

      See Also:

    • F_SETLEASE

      public static final int F_SETLEASE
      fcntl(int, int) commands.
      Enum values:
      • F_DUPFD - Duplicate the file descriptor fd using the lowest-numbered available file descriptor greater than or equal to arg.

        This is different from dup2(2), which uses exactly the file descriptor specified.

        On success, the new file descriptor is returned.

        See dup(2) for further details.

      • F_GETFD - Return (as the function result) the file descriptor flags; arg is ignored.
      • F_SETFD - Set the file descriptor flags to the value specified by arg.
      • F_GETFL - Return (as the function result) the file access mode and the file status flags; arg is ignored.
      • F_SETFL - Set the file status flags to the value specified by arg.

        File access mode (O_RDONLY, O_WRONLY, O_RDWR) and file creation flags (i.e., O_CREAT, O_EXCL, O_NOCTTY, O_TRUNC) in arg are ignored. On Linux, this command can change only the O_APPEND, O_ASYNC, O_DIRECT, O_NOATIME, and O_NONBLOCK flags. It is not possible to change the O_DSYNC and O_SYNC flags; see BUGS, below.

      • F_GETLK - On input to this call, lock describes a lock we would like to place on the file.

        If the lock could be placed, fcntl() does not actually place it, but returns F_UNLCK in the l_type field of lock and leaves the other fields of the structure unchanged.

        If one or more incompatible locks would prevent this lock being placed, then fcntl() returns details about one of those locks in the l_type, l_whence, l_start, and l_len fields of lock. If the conflicting lock is a traditional (process-associated) record lock, then the l_pid field is set to the PID of the process holding that lock. If the conflicting lock is an open file description lock, then l_pid is set to -1. Note that the returned information may already be out of date by the time the caller inspects it.

      • F_SETLK - Acquire a lock (when l_type is F_RDLCK or F_WRLCK) or release a lock (when l_type is F_UNLCK) on the bytes specified by the l_whence, l_start, and l_len fields of lock.

        If a conflicting lock is held by another process, this call returns -1 and sets errno to EACCES or EAGAIN. (The error returned in this case differs across implementations, so POSIX requires a portable application to check for both errors.)

      • F_SETLKW - As for F_SETLK, but if a conflicting lock is held on the file, then wait for that lock to be released.

        If a signal is caught while waiting, then the call is interrupted and (after the signal handler has returned) returns immediately (with return value -1 and errno set to EINTR; see signal(7)).

      • F_SETOWN - Set the process ID or process group ID that will receive SIGIO and SIGURG signals for events on the file descriptor fd.

        The target process or process group ID is specified in arg. A process ID is specified as a positive value; a process group ID is specified as a negative value. Most commonly, the calling process specifies itself as the owner (that is, arg is specified as getpid(2)).

        As well as setting the file descriptor owner, one must also enable generation of signals on the file descriptor. This is done by using the fcntl() F_SETFL command to set the O_ASYNC file status flag on the file descriptor. Subsequently, a SIGIO signal is sent whenever input or output becomes possible on the file descriptor. The fcntl() F_SETSIG command can be used to obtain delivery of a signal other than SIGIO.

        Sending a signal to the owner process (group) specified by F_SETOWN is subject to the same permissions checks as are described for kill(2), where the sending process is the one that employs F_SETOWN (but see BUGS below). If this permission check fails, then the signal is silently discarded. Note: The F_SETOWN operation records the caller's credentials at the time of the fcntl() call, and it is these saved credentials that are used for the permission checks.

        If the file descriptor fd refers to a socket, F_SETOWN also selects the recipient of SIGURG signals that are delivered when out-of-band data arrives on that socket. (SIGURG is sent in any situation where select(2) would report the socket as having an "exceptional condition".)

        The following was true in 2.6.x kernels up to and including kernel 2.6.11:

        If a nonzero value is given to F_SETSIG in a multithreaded process running with a threading library that supports thread groups (e.g., NPTL), then a positive value given to F_SETOWN has a different meaning: instead of being a process ID identifying a whole process, it is a thread ID identifying a specific thread within a process. Consequently, it may be necessary to pass F_SETOWN the result of gettid(2) instead of getpid(2) to get sensible results when F_SETSIG is used. (In current Linux threading implementations, a main thread's thread ID is the same as its process ID. This means that a single-threaded program can equally use gettid(2) or getpid(2) in this scenario.) Note, however, that the statements in this paragraph do not apply to the SIGURG signal generated for out-of-band data on a socket: this signal is always sent to either a process or a process group, depending on the value given to F_SETOWN.

        The above behavior was accidentally dropped in Linux 2.6.12, and won't be restored. From Linux 2.6.32 onward, use F_SETOWN_EX to target SIGIO and SIGURG signals at a particular thread.

      • F_GETOWN - Return (as the function result) the process ID or process group ID currently receiving SIGIO and SIGURG signals for events on file descriptor fd.

        Process IDs are returned as positive values; process group IDs are returned as negative values (but see BUGS below). arg is ignored.

      • F_SETSIG - Set the signal sent when input or output becomes possible to the value given in arg.

        A value of zero means to send the default SIGIO signal. Any other value (including SIGIO) is the signal to send instead, and in this case additional info is available to the signal handler if installed with SA_SIGINFO.

        By using F_SETSIG with a nonzero value, and setting SA_SIGINFO for the signal handler (see sigaction(2)), extra information about I/O events is passed to the handler in a siginfo_t structure. If the si_code field indicates the source is SI_SIGIO, the si_fd field gives the file descriptor associated with the event. Otherwise, there is no indication which file descriptors are pending, and you should use the usual mechanisms (select(2), poll(2), read(2) with O_NONBLOCK set etc.) to determine which file descriptors are available for I/O.

        Note that the file descriptor provided in si_fd is the one that was specified during the F_SETSIG operation. This can lead to an unusual corner case. If the file descriptor is duplicated (dup(2) or similar), and the original file descriptor is closed, then I/O events will continue to be generated, but the si_fd field will contain the number of the now closed file descriptor.

        By selecting a real time signal (value ≥ SIGRTMIN), multiple I/O events may be queued using the same signal numbers. (Queuing is dependent on available memory.) Extra information is available if SA_SIGINFO is set for the signal handler, as above.

        Note that Linux imposes a limit on the number of real-time signals that may be queued to a process (see getrlimit(2) and signal(7)) and if this limit is reached, then the kernel reverts to delivering SIGIO, and this signal is delivered to the entire process rather than to a specific thread.

      • F_GETSIG - Return (as the function result) the signal sent when input or output becomes possible.

        A value of zero means SIGIO is sent. Any other value (including SIGIO) is the signal sent instead, and in this case additional info is available to the signal handler if installed with SA_SIGINFO. arg is ignored.

      • F_SETOWN_EX - This operation performs a similar task to F_SETOWN. It allows the caller to direct I/O availability signals to a specific thread, process, or process group.

        The caller specifies the target of signals via arg, which is a pointer to a FOwnerEx structure. The type field has one of the following values, which define how pid is interpreted: F_OWNER_TID, F_OWNER_PID, F_OWNER_PGRP.

      • F_GETOWN_EX - Return the current file descriptor owner settings as defined by a previous F_SETOWN_EX operation.

        The information is returned in the FOwnerEx structure pointed to by arg.

        The type field will have one of the values F_OWNER_TID, F_OWNER_PID, or F_OWNER_PGRP. The pid field is a positive integer representing a thread ID, process ID, or process group ID. See F_SETOWN_EX for more details.

      • F_OFD_GETLK - On input to this call, lock describes an open file description lock we would like to place on the file.

        If the lock could be placed, fcntl() does not actually place it, but returns F_UNLCK in the l_type field of lock and leaves the other fields of the structure unchanged. If one or more incompatible locks would prevent this lock being placed, then details about one of these locks are returned via lock, as described above for F_GETLK.

      • F_OFD_SETLK - Acquire an open file description lock (when l_type is F_RDLCK or F_WRLCK) or release an open file description lock (when l_type is F_UNLCK) on the bytes specified by the l_whence, l_start, and l_len fields of lock.

        If a conflicting lock is held by another process, this call returns -1 and sets errno to EAGAIN.

      • F_OFD_SETLKW - As for F_OFD_SETLK, but if a conflicting lock is held on the file, then wait for that lock to be released.

        If a signal is caught while waiting, then the call is interrupted and (after the signal handler has returned) returns immediately (with return value -1 and errno set to EINTR; see signal(7)).

      • F_SETLEASE - Set or remove a file lease according to which of the following values is specified in the integer arg: F_RDLCK, F_WRLCK, F_UNLCK
      • F_GETLEASE - Indicates what type of lease is associated with the file descriptor fd by returning either F_RDLCK, F_WRLCK, or F_UNLCK, indicating, respectively, a read lease, a write lease, or no lease. arg is ignored.
      • F_NOTIFY - (Linux 2.4 onward) Provide notification when the directory referred to by fd or any of the files that it contains is changed.

        The events to be notified are specified in arg, which is a bit mask specified by ORing together zero or more of the following bits: DN_ACCESS, DN_MODIFY, DN_CREATE, DN_DELETE, DN_RENAME, DN_ATTRIB

        (In order to obtain these definitions, the _GNU_SOURCE feature test macro must be defined before including any header files.)

        Directory notifications are normally "one-shot", and the application must reregister to receive further notifications. Alternatively, if DN_MULTISHOT is included in arg, then notification will remain in effect until explicitly removed.

        A series of F_NOTIFY requests is cumulative, with the events in arg being added to the set already monitored. To disable notification of all events, make an F_NOTIFY call specifying arg as 0.

        Notification occurs via delivery of a signal. The default signal is SIGIO, but this can be changed using the F_SETSIG command to fcntl(). (Note that SIGIO is one of the nonqueuing standard signals; switching to the use of a real-time signal means that multiple notifications can be queued to the process.) In the latter case, the signal handler receives a siginfo_t structure as its second argument (if the handler was established using SA_SIGINFO) and the si_fd field of this structure contains the file descriptor which generated the notification (useful when establishing notification on multiple directories).

        Especially when using DN_MULTISHOT, a real time signal should be used for notification, so that multiple notifications can be queued.

        NOTE: New applications should use the inotify interface (available since kernel 2.6.13), which provides a much superior interface for obtaining notifications of filesystem events. See inotify(7).

      • F_SETPIPE_SZ - Change the capacity of the pipe referred to by fd to be at least arg bytes.

        An unprivileged process can adjust the pipe capacity to any value between the system page size and the limit defined in /proc/sys/fs/pipe-max-size (see proc(5)). Attempts to set the pipe capacity below the page size are silently rounded up to the page size. Attempts by an unprivileged process to set the pipe capacity above the limit in /proc/sys/fs/pipe-max-size yield the error EPERM; a privileged process (CAP_SYS_RESOURCE) can override the limit.

        When allocating the buffer for the pipe, the kernel may use a capacity larger than arg, if that is convenient for the implementation. (In the current implementation, the allocation is the next higher power-of-two page-size multiple of the requested size.) The actual capacity (in bytes) that is set is returned as the function result.

        Attempting to set the pipe capacity smaller than the amount of buffer space currently used to store data produces the error EBUSY.

        Note that because of the way the pages of the pipe buffer are employed when data is written to the pipe, the number of bytes that can be written may be less than the nominal size, depending on the size of the writes.

      • F_GETPIPE_SZ - Return (as the function result) the capacity of the pipe referred to by fd.
      • F_ADD_SEALS - Add the seals given in the bit-mask argument arg to the set of seals of the inode referred to by the file descriptor fd.

        Seals cannot be removed again. Once this call succeeds, the seals are enforced by the kernel immediately. If the current set of seals includes F_SEAL_SEAL (see below), then this call will be rejected with EPERM. Adding a seal that is already set is a no-op, in case F_SEAL_SEAL is not set already. In order to place a seal, the file descriptor fd must be writable.

      • F_GET_SEALS - Return (as the function result) the current set of seals of the inode referred to by fd.

        If no seals are set, 0 is returned. If the file does not support sealing, -1 is returned and errno is set to EINVAL.

      • F_GET_RW_HINT - Returns the value of the read/write hint associated with the underlying inode referred to by fd.
      • F_SET_RW_HINT - Sets the read/write hint value associated with the underlying inode referred to by fd.

        This hint persists until either it is explicitly modified or the underlying filesystem is unmounted.

      • F_GET_FILE_RW_HINT - Returns the value of the read/write hint associated with the open file description referred to by fd.
      • F_SET_FILE_RW_HINT - Sets the read/write hint value associated with the open file description referred to by fd.
      • F_DUPFD_CLOEXEC - As for F_DUPFD, but additionally set the close-on-exec flag for the duplicate file descriptor.

        Specifying this flag permits a program to avoid an additional fcntl() F_SETFD operation to set the FD_CLOEXEC flag. For an explanation of why this flag is useful, see the description of O_CLOEXEC in open(2).

      See Also:

    • F_GETLEASE

      public static final int F_GETLEASE
      fcntl(int, int) commands.
      Enum values:
      • F_DUPFD - Duplicate the file descriptor fd using the lowest-numbered available file descriptor greater than or equal to arg.

        This is different from dup2(2), which uses exactly the file descriptor specified.

        On success, the new file descriptor is returned.

        See dup(2) for further details.

      • F_GETFD - Return (as the function result) the file descriptor flags; arg is ignored.
      • F_SETFD - Set the file descriptor flags to the value specified by arg.
      • F_GETFL - Return (as the function result) the file access mode and the file status flags; arg is ignored.
      • F_SETFL - Set the file status flags to the value specified by arg.

        File access mode (O_RDONLY, O_WRONLY, O_RDWR) and file creation flags (i.e., O_CREAT, O_EXCL, O_NOCTTY, O_TRUNC) in arg are ignored. On Linux, this command can change only the O_APPEND, O_ASYNC, O_DIRECT, O_NOATIME, and O_NONBLOCK flags. It is not possible to change the O_DSYNC and O_SYNC flags; see BUGS, below.

      • F_GETLK - On input to this call, lock describes a lock we would like to place on the file.

        If the lock could be placed, fcntl() does not actually place it, but returns F_UNLCK in the l_type field of lock and leaves the other fields of the structure unchanged.

        If one or more incompatible locks would prevent this lock being placed, then fcntl() returns details about one of those locks in the l_type, l_whence, l_start, and l_len fields of lock. If the conflicting lock is a traditional (process-associated) record lock, then the l_pid field is set to the PID of the process holding that lock. If the conflicting lock is an open file description lock, then l_pid is set to -1. Note that the returned information may already be out of date by the time the caller inspects it.

      • F_SETLK - Acquire a lock (when l_type is F_RDLCK or F_WRLCK) or release a lock (when l_type is F_UNLCK) on the bytes specified by the l_whence, l_start, and l_len fields of lock.

        If a conflicting lock is held by another process, this call returns -1 and sets errno to EACCES or EAGAIN. (The error returned in this case differs across implementations, so POSIX requires a portable application to check for both errors.)

      • F_SETLKW - As for F_SETLK, but if a conflicting lock is held on the file, then wait for that lock to be released.

        If a signal is caught while waiting, then the call is interrupted and (after the signal handler has returned) returns immediately (with return value -1 and errno set to EINTR; see signal(7)).

      • F_SETOWN - Set the process ID or process group ID that will receive SIGIO and SIGURG signals for events on the file descriptor fd.

        The target process or process group ID is specified in arg. A process ID is specified as a positive value; a process group ID is specified as a negative value. Most commonly, the calling process specifies itself as the owner (that is, arg is specified as getpid(2)).

        As well as setting the file descriptor owner, one must also enable generation of signals on the file descriptor. This is done by using the fcntl() F_SETFL command to set the O_ASYNC file status flag on the file descriptor. Subsequently, a SIGIO signal is sent whenever input or output becomes possible on the file descriptor. The fcntl() F_SETSIG command can be used to obtain delivery of a signal other than SIGIO.

        Sending a signal to the owner process (group) specified by F_SETOWN is subject to the same permissions checks as are described for kill(2), where the sending process is the one that employs F_SETOWN (but see BUGS below). If this permission check fails, then the signal is silently discarded. Note: The F_SETOWN operation records the caller's credentials at the time of the fcntl() call, and it is these saved credentials that are used for the permission checks.

        If the file descriptor fd refers to a socket, F_SETOWN also selects the recipient of SIGURG signals that are delivered when out-of-band data arrives on that socket. (SIGURG is sent in any situation where select(2) would report the socket as having an "exceptional condition".)

        The following was true in 2.6.x kernels up to and including kernel 2.6.11:

        If a nonzero value is given to F_SETSIG in a multithreaded process running with a threading library that supports thread groups (e.g., NPTL), then a positive value given to F_SETOWN has a different meaning: instead of being a process ID identifying a whole process, it is a thread ID identifying a specific thread within a process. Consequently, it may be necessary to pass F_SETOWN the result of gettid(2) instead of getpid(2) to get sensible results when F_SETSIG is used. (In current Linux threading implementations, a main thread's thread ID is the same as its process ID. This means that a single-threaded program can equally use gettid(2) or getpid(2) in this scenario.) Note, however, that the statements in this paragraph do not apply to the SIGURG signal generated for out-of-band data on a socket: this signal is always sent to either a process or a process group, depending on the value given to F_SETOWN.

        The above behavior was accidentally dropped in Linux 2.6.12, and won't be restored. From Linux 2.6.32 onward, use F_SETOWN_EX to target SIGIO and SIGURG signals at a particular thread.

      • F_GETOWN - Return (as the function result) the process ID or process group ID currently receiving SIGIO and SIGURG signals for events on file descriptor fd.

        Process IDs are returned as positive values; process group IDs are returned as negative values (but see BUGS below). arg is ignored.

      • F_SETSIG - Set the signal sent when input or output becomes possible to the value given in arg.

        A value of zero means to send the default SIGIO signal. Any other value (including SIGIO) is the signal to send instead, and in this case additional info is available to the signal handler if installed with SA_SIGINFO.

        By using F_SETSIG with a nonzero value, and setting SA_SIGINFO for the signal handler (see sigaction(2)), extra information about I/O events is passed to the handler in a siginfo_t structure. If the si_code field indicates the source is SI_SIGIO, the si_fd field gives the file descriptor associated with the event. Otherwise, there is no indication which file descriptors are pending, and you should use the usual mechanisms (select(2), poll(2), read(2) with O_NONBLOCK set etc.) to determine which file descriptors are available for I/O.

        Note that the file descriptor provided in si_fd is the one that was specified during the F_SETSIG operation. This can lead to an unusual corner case. If the file descriptor is duplicated (dup(2) or similar), and the original file descriptor is closed, then I/O events will continue to be generated, but the si_fd field will contain the number of the now closed file descriptor.

        By selecting a real time signal (value ≥ SIGRTMIN), multiple I/O events may be queued using the same signal numbers. (Queuing is dependent on available memory.) Extra information is available if SA_SIGINFO is set for the signal handler, as above.

        Note that Linux imposes a limit on the number of real-time signals that may be queued to a process (see getrlimit(2) and signal(7)) and if this limit is reached, then the kernel reverts to delivering SIGIO, and this signal is delivered to the entire process rather than to a specific thread.

      • F_GETSIG - Return (as the function result) the signal sent when input or output becomes possible.

        A value of zero means SIGIO is sent. Any other value (including SIGIO) is the signal sent instead, and in this case additional info is available to the signal handler if installed with SA_SIGINFO. arg is ignored.

      • F_SETOWN_EX - This operation performs a similar task to F_SETOWN. It allows the caller to direct I/O availability signals to a specific thread, process, or process group.

        The caller specifies the target of signals via arg, which is a pointer to a FOwnerEx structure. The type field has one of the following values, which define how pid is interpreted: F_OWNER_TID, F_OWNER_PID, F_OWNER_PGRP.

      • F_GETOWN_EX - Return the current file descriptor owner settings as defined by a previous F_SETOWN_EX operation.

        The information is returned in the FOwnerEx structure pointed to by arg.

        The type field will have one of the values F_OWNER_TID, F_OWNER_PID, or F_OWNER_PGRP. The pid field is a positive integer representing a thread ID, process ID, or process group ID. See F_SETOWN_EX for more details.

      • F_OFD_GETLK - On input to this call, lock describes an open file description lock we would like to place on the file.

        If the lock could be placed, fcntl() does not actually place it, but returns F_UNLCK in the l_type field of lock and leaves the other fields of the structure unchanged. If one or more incompatible locks would prevent this lock being placed, then details about one of these locks are returned via lock, as described above for F_GETLK.

      • F_OFD_SETLK - Acquire an open file description lock (when l_type is F_RDLCK or F_WRLCK) or release an open file description lock (when l_type is F_UNLCK) on the bytes specified by the l_whence, l_start, and l_len fields of lock.

        If a conflicting lock is held by another process, this call returns -1 and sets errno to EAGAIN.

      • F_OFD_SETLKW - As for F_OFD_SETLK, but if a conflicting lock is held on the file, then wait for that lock to be released.

        If a signal is caught while waiting, then the call is interrupted and (after the signal handler has returned) returns immediately (with return value -1 and errno set to EINTR; see signal(7)).

      • F_SETLEASE - Set or remove a file lease according to which of the following values is specified in the integer arg: F_RDLCK, F_WRLCK, F_UNLCK
      • F_GETLEASE - Indicates what type of lease is associated with the file descriptor fd by returning either F_RDLCK, F_WRLCK, or F_UNLCK, indicating, respectively, a read lease, a write lease, or no lease. arg is ignored.
      • F_NOTIFY - (Linux 2.4 onward) Provide notification when the directory referred to by fd or any of the files that it contains is changed.

        The events to be notified are specified in arg, which is a bit mask specified by ORing together zero or more of the following bits: DN_ACCESS, DN_MODIFY, DN_CREATE, DN_DELETE, DN_RENAME, DN_ATTRIB

        (In order to obtain these definitions, the _GNU_SOURCE feature test macro must be defined before including any header files.)

        Directory notifications are normally "one-shot", and the application must reregister to receive further notifications. Alternatively, if DN_MULTISHOT is included in arg, then notification will remain in effect until explicitly removed.

        A series of F_NOTIFY requests is cumulative, with the events in arg being added to the set already monitored. To disable notification of all events, make an F_NOTIFY call specifying arg as 0.

        Notification occurs via delivery of a signal. The default signal is SIGIO, but this can be changed using the F_SETSIG command to fcntl(). (Note that SIGIO is one of the nonqueuing standard signals; switching to the use of a real-time signal means that multiple notifications can be queued to the process.) In the latter case, the signal handler receives a siginfo_t structure as its second argument (if the handler was established using SA_SIGINFO) and the si_fd field of this structure contains the file descriptor which generated the notification (useful when establishing notification on multiple directories).

        Especially when using DN_MULTISHOT, a real time signal should be used for notification, so that multiple notifications can be queued.

        NOTE: New applications should use the inotify interface (available since kernel 2.6.13), which provides a much superior interface for obtaining notifications of filesystem events. See inotify(7).

      • F_SETPIPE_SZ - Change the capacity of the pipe referred to by fd to be at least arg bytes.

        An unprivileged process can adjust the pipe capacity to any value between the system page size and the limit defined in /proc/sys/fs/pipe-max-size (see proc(5)). Attempts to set the pipe capacity below the page size are silently rounded up to the page size. Attempts by an unprivileged process to set the pipe capacity above the limit in /proc/sys/fs/pipe-max-size yield the error EPERM; a privileged process (CAP_SYS_RESOURCE) can override the limit.

        When allocating the buffer for the pipe, the kernel may use a capacity larger than arg, if that is convenient for the implementation. (In the current implementation, the allocation is the next higher power-of-two page-size multiple of the requested size.) The actual capacity (in bytes) that is set is returned as the function result.

        Attempting to set the pipe capacity smaller than the amount of buffer space currently used to store data produces the error EBUSY.

        Note that because of the way the pages of the pipe buffer are employed when data is written to the pipe, the number of bytes that can be written may be less than the nominal size, depending on the size of the writes.

      • F_GETPIPE_SZ - Return (as the function result) the capacity of the pipe referred to by fd.
      • F_ADD_SEALS - Add the seals given in the bit-mask argument arg to the set of seals of the inode referred to by the file descriptor fd.

        Seals cannot be removed again. Once this call succeeds, the seals are enforced by the kernel immediately. If the current set of seals includes F_SEAL_SEAL (see below), then this call will be rejected with EPERM. Adding a seal that is already set is a no-op, in case F_SEAL_SEAL is not set already. In order to place a seal, the file descriptor fd must be writable.

      • F_GET_SEALS - Return (as the function result) the current set of seals of the inode referred to by fd.

        If no seals are set, 0 is returned. If the file does not support sealing, -1 is returned and errno is set to EINVAL.

      • F_GET_RW_HINT - Returns the value of the read/write hint associated with the underlying inode referred to by fd.
      • F_SET_RW_HINT - Sets the read/write hint value associated with the underlying inode referred to by fd.

        This hint persists until either it is explicitly modified or the underlying filesystem is unmounted.

      • F_GET_FILE_RW_HINT - Returns the value of the read/write hint associated with the open file description referred to by fd.
      • F_SET_FILE_RW_HINT - Sets the read/write hint value associated with the open file description referred to by fd.
      • F_DUPFD_CLOEXEC - As for F_DUPFD, but additionally set the close-on-exec flag for the duplicate file descriptor.

        Specifying this flag permits a program to avoid an additional fcntl() F_SETFD operation to set the FD_CLOEXEC flag. For an explanation of why this flag is useful, see the description of O_CLOEXEC in open(2).

      See Also:

    • F_NOTIFY

      public static final int F_NOTIFY
      fcntl(int, int) commands.
      Enum values:
      • F_DUPFD - Duplicate the file descriptor fd using the lowest-numbered available file descriptor greater than or equal to arg.

        This is different from dup2(2), which uses exactly the file descriptor specified.

        On success, the new file descriptor is returned.

        See dup(2) for further details.

      • F_GETFD - Return (as the function result) the file descriptor flags; arg is ignored.
      • F_SETFD - Set the file descriptor flags to the value specified by arg.
      • F_GETFL - Return (as the function result) the file access mode and the file status flags; arg is ignored.
      • F_SETFL - Set the file status flags to the value specified by arg.

        File access mode (O_RDONLY, O_WRONLY, O_RDWR) and file creation flags (i.e., O_CREAT, O_EXCL, O_NOCTTY, O_TRUNC) in arg are ignored. On Linux, this command can change only the O_APPEND, O_ASYNC, O_DIRECT, O_NOATIME, and O_NONBLOCK flags. It is not possible to change the O_DSYNC and O_SYNC flags; see BUGS, below.

      • F_GETLK - On input to this call, lock describes a lock we would like to place on the file.

        If the lock could be placed, fcntl() does not actually place it, but returns F_UNLCK in the l_type field of lock and leaves the other fields of the structure unchanged.

        If one or more incompatible locks would prevent this lock being placed, then fcntl() returns details about one of those locks in the l_type, l_whence, l_start, and l_len fields of lock. If the conflicting lock is a traditional (process-associated) record lock, then the l_pid field is set to the PID of the process holding that lock. If the conflicting lock is an open file description lock, then l_pid is set to -1. Note that the returned information may already be out of date by the time the caller inspects it.

      • F_SETLK - Acquire a lock (when l_type is F_RDLCK or F_WRLCK) or release a lock (when l_type is F_UNLCK) on the bytes specified by the l_whence, l_start, and l_len fields of lock.

        If a conflicting lock is held by another process, this call returns -1 and sets errno to EACCES or EAGAIN. (The error returned in this case differs across implementations, so POSIX requires a portable application to check for both errors.)

      • F_SETLKW - As for F_SETLK, but if a conflicting lock is held on the file, then wait for that lock to be released.

        If a signal is caught while waiting, then the call is interrupted and (after the signal handler has returned) returns immediately (with return value -1 and errno set to EINTR; see signal(7)).

      • F_SETOWN - Set the process ID or process group ID that will receive SIGIO and SIGURG signals for events on the file descriptor fd.

        The target process or process group ID is specified in arg. A process ID is specified as a positive value; a process group ID is specified as a negative value. Most commonly, the calling process specifies itself as the owner (that is, arg is specified as getpid(2)).

        As well as setting the file descriptor owner, one must also enable generation of signals on the file descriptor. This is done by using the fcntl() F_SETFL command to set the O_ASYNC file status flag on the file descriptor. Subsequently, a SIGIO signal is sent whenever input or output becomes possible on the file descriptor. The fcntl() F_SETSIG command can be used to obtain delivery of a signal other than SIGIO.

        Sending a signal to the owner process (group) specified by F_SETOWN is subject to the same permissions checks as are described for kill(2), where the sending process is the one that employs F_SETOWN (but see BUGS below). If this permission check fails, then the signal is silently discarded. Note: The F_SETOWN operation records the caller's credentials at the time of the fcntl() call, and it is these saved credentials that are used for the permission checks.

        If the file descriptor fd refers to a socket, F_SETOWN also selects the recipient of SIGURG signals that are delivered when out-of-band data arrives on that socket. (SIGURG is sent in any situation where select(2) would report the socket as having an "exceptional condition".)

        The following was true in 2.6.x kernels up to and including kernel 2.6.11:

        If a nonzero value is given to F_SETSIG in a multithreaded process running with a threading library that supports thread groups (e.g., NPTL), then a positive value given to F_SETOWN has a different meaning: instead of being a process ID identifying a whole process, it is a thread ID identifying a specific thread within a process. Consequently, it may be necessary to pass F_SETOWN the result of gettid(2) instead of getpid(2) to get sensible results when F_SETSIG is used. (In current Linux threading implementations, a main thread's thread ID is the same as its process ID. This means that a single-threaded program can equally use gettid(2) or getpid(2) in this scenario.) Note, however, that the statements in this paragraph do not apply to the SIGURG signal generated for out-of-band data on a socket: this signal is always sent to either a process or a process group, depending on the value given to F_SETOWN.

        The above behavior was accidentally dropped in Linux 2.6.12, and won't be restored. From Linux 2.6.32 onward, use F_SETOWN_EX to target SIGIO and SIGURG signals at a particular thread.

      • F_GETOWN - Return (as the function result) the process ID or process group ID currently receiving SIGIO and SIGURG signals for events on file descriptor fd.

        Process IDs are returned as positive values; process group IDs are returned as negative values (but see BUGS below). arg is ignored.

      • F_SETSIG - Set the signal sent when input or output becomes possible to the value given in arg.

        A value of zero means to send the default SIGIO signal. Any other value (including SIGIO) is the signal to send instead, and in this case additional info is available to the signal handler if installed with SA_SIGINFO.

        By using F_SETSIG with a nonzero value, and setting SA_SIGINFO for the signal handler (see sigaction(2)), extra information about I/O events is passed to the handler in a siginfo_t structure. If the si_code field indicates the source is SI_SIGIO, the si_fd field gives the file descriptor associated with the event. Otherwise, there is no indication which file descriptors are pending, and you should use the usual mechanisms (select(2), poll(2), read(2) with O_NONBLOCK set etc.) to determine which file descriptors are available for I/O.

        Note that the file descriptor provided in si_fd is the one that was specified during the F_SETSIG operation. This can lead to an unusual corner case. If the file descriptor is duplicated (dup(2) or similar), and the original file descriptor is closed, then I/O events will continue to be generated, but the si_fd field will contain the number of the now closed file descriptor.

        By selecting a real time signal (value ≥ SIGRTMIN), multiple I/O events may be queued using the same signal numbers. (Queuing is dependent on available memory.) Extra information is available if SA_SIGINFO is set for the signal handler, as above.

        Note that Linux imposes a limit on the number of real-time signals that may be queued to a process (see getrlimit(2) and signal(7)) and if this limit is reached, then the kernel reverts to delivering SIGIO, and this signal is delivered to the entire process rather than to a specific thread.

      • F_GETSIG - Return (as the function result) the signal sent when input or output becomes possible.

        A value of zero means SIGIO is sent. Any other value (including SIGIO) is the signal sent instead, and in this case additional info is available to the signal handler if installed with SA_SIGINFO. arg is ignored.

      • F_SETOWN_EX - This operation performs a similar task to F_SETOWN. It allows the caller to direct I/O availability signals to a specific thread, process, or process group.

        The caller specifies the target of signals via arg, which is a pointer to a FOwnerEx structure. The type field has one of the following values, which define how pid is interpreted: F_OWNER_TID, F_OWNER_PID, F_OWNER_PGRP.

      • F_GETOWN_EX - Return the current file descriptor owner settings as defined by a previous F_SETOWN_EX operation.

        The information is returned in the FOwnerEx structure pointed to by arg.

        The type field will have one of the values F_OWNER_TID, F_OWNER_PID, or F_OWNER_PGRP. The pid field is a positive integer representing a thread ID, process ID, or process group ID. See F_SETOWN_EX for more details.

      • F_OFD_GETLK - On input to this call, lock describes an open file description lock we would like to place on the file.

        If the lock could be placed, fcntl() does not actually place it, but returns F_UNLCK in the l_type field of lock and leaves the other fields of the structure unchanged. If one or more incompatible locks would prevent this lock being placed, then details about one of these locks are returned via lock, as described above for F_GETLK.

      • F_OFD_SETLK - Acquire an open file description lock (when l_type is F_RDLCK or F_WRLCK) or release an open file description lock (when l_type is F_UNLCK) on the bytes specified by the l_whence, l_start, and l_len fields of lock.

        If a conflicting lock is held by another process, this call returns -1 and sets errno to EAGAIN.

      • F_OFD_SETLKW - As for F_OFD_SETLK, but if a conflicting lock is held on the file, then wait for that lock to be released.

        If a signal is caught while waiting, then the call is interrupted and (after the signal handler has returned) returns immediately (with return value -1 and errno set to EINTR; see signal(7)).

      • F_SETLEASE - Set or remove a file lease according to which of the following values is specified in the integer arg: F_RDLCK, F_WRLCK, F_UNLCK
      • F_GETLEASE - Indicates what type of lease is associated with the file descriptor fd by returning either F_RDLCK, F_WRLCK, or F_UNLCK, indicating, respectively, a read lease, a write lease, or no lease. arg is ignored.
      • F_NOTIFY - (Linux 2.4 onward) Provide notification when the directory referred to by fd or any of the files that it contains is changed.

        The events to be notified are specified in arg, which is a bit mask specified by ORing together zero or more of the following bits: DN_ACCESS, DN_MODIFY, DN_CREATE, DN_DELETE, DN_RENAME, DN_ATTRIB

        (In order to obtain these definitions, the _GNU_SOURCE feature test macro must be defined before including any header files.)

        Directory notifications are normally "one-shot", and the application must reregister to receive further notifications. Alternatively, if DN_MULTISHOT is included in arg, then notification will remain in effect until explicitly removed.

        A series of F_NOTIFY requests is cumulative, with the events in arg being added to the set already monitored. To disable notification of all events, make an F_NOTIFY call specifying arg as 0.

        Notification occurs via delivery of a signal. The default signal is SIGIO, but this can be changed using the F_SETSIG command to fcntl(). (Note that SIGIO is one of the nonqueuing standard signals; switching to the use of a real-time signal means that multiple notifications can be queued to the process.) In the latter case, the signal handler receives a siginfo_t structure as its second argument (if the handler was established using SA_SIGINFO) and the si_fd field of this structure contains the file descriptor which generated the notification (useful when establishing notification on multiple directories).

        Especially when using DN_MULTISHOT, a real time signal should be used for notification, so that multiple notifications can be queued.

        NOTE: New applications should use the inotify interface (available since kernel 2.6.13), which provides a much superior interface for obtaining notifications of filesystem events. See inotify(7).

      • F_SETPIPE_SZ - Change the capacity of the pipe referred to by fd to be at least arg bytes.

        An unprivileged process can adjust the pipe capacity to any value between the system page size and the limit defined in /proc/sys/fs/pipe-max-size (see proc(5)). Attempts to set the pipe capacity below the page size are silently rounded up to the page size. Attempts by an unprivileged process to set the pipe capacity above the limit in /proc/sys/fs/pipe-max-size yield the error EPERM; a privileged process (CAP_SYS_RESOURCE) can override the limit.

        When allocating the buffer for the pipe, the kernel may use a capacity larger than arg, if that is convenient for the implementation. (In the current implementation, the allocation is the next higher power-of-two page-size multiple of the requested size.) The actual capacity (in bytes) that is set is returned as the function result.

        Attempting to set the pipe capacity smaller than the amount of buffer space currently used to store data produces the error EBUSY.

        Note that because of the way the pages of the pipe buffer are employed when data is written to the pipe, the number of bytes that can be written may be less than the nominal size, depending on the size of the writes.

      • F_GETPIPE_SZ - Return (as the function result) the capacity of the pipe referred to by fd.
      • F_ADD_SEALS - Add the seals given in the bit-mask argument arg to the set of seals of the inode referred to by the file descriptor fd.

        Seals cannot be removed again. Once this call succeeds, the seals are enforced by the kernel immediately. If the current set of seals includes F_SEAL_SEAL (see below), then this call will be rejected with EPERM. Adding a seal that is already set is a no-op, in case F_SEAL_SEAL is not set already. In order to place a seal, the file descriptor fd must be writable.

      • F_GET_SEALS - Return (as the function result) the current set of seals of the inode referred to by fd.

        If no seals are set, 0 is returned. If the file does not support sealing, -1 is returned and errno is set to EINVAL.

      • F_GET_RW_HINT - Returns the value of the read/write hint associated with the underlying inode referred to by fd.
      • F_SET_RW_HINT - Sets the read/write hint value associated with the underlying inode referred to by fd.

        This hint persists until either it is explicitly modified or the underlying filesystem is unmounted.

      • F_GET_FILE_RW_HINT - Returns the value of the read/write hint associated with the open file description referred to by fd.
      • F_SET_FILE_RW_HINT - Sets the read/write hint value associated with the open file description referred to by fd.
      • F_DUPFD_CLOEXEC - As for F_DUPFD, but additionally set the close-on-exec flag for the duplicate file descriptor.

        Specifying this flag permits a program to avoid an additional fcntl() F_SETFD operation to set the FD_CLOEXEC flag. For an explanation of why this flag is useful, see the description of O_CLOEXEC in open(2).

      See Also:

    • F_SETPIPE_SZ

      public static final int F_SETPIPE_SZ
      fcntl(int, int) commands.
      Enum values:
      • F_DUPFD - Duplicate the file descriptor fd using the lowest-numbered available file descriptor greater than or equal to arg.

        This is different from dup2(2), which uses exactly the file descriptor specified.

        On success, the new file descriptor is returned.

        See dup(2) for further details.

      • F_GETFD - Return (as the function result) the file descriptor flags; arg is ignored.
      • F_SETFD - Set the file descriptor flags to the value specified by arg.
      • F_GETFL - Return (as the function result) the file access mode and the file status flags; arg is ignored.
      • F_SETFL - Set the file status flags to the value specified by arg.

        File access mode (O_RDONLY, O_WRONLY, O_RDWR) and file creation flags (i.e., O_CREAT, O_EXCL, O_NOCTTY, O_TRUNC) in arg are ignored. On Linux, this command can change only the O_APPEND, O_ASYNC, O_DIRECT, O_NOATIME, and O_NONBLOCK flags. It is not possible to change the O_DSYNC and O_SYNC flags; see BUGS, below.

      • F_GETLK - On input to this call, lock describes a lock we would like to place on the file.

        If the lock could be placed, fcntl() does not actually place it, but returns F_UNLCK in the l_type field of lock and leaves the other fields of the structure unchanged.

        If one or more incompatible locks would prevent this lock being placed, then fcntl() returns details about one of those locks in the l_type, l_whence, l_start, and l_len fields of lock. If the conflicting lock is a traditional (process-associated) record lock, then the l_pid field is set to the PID of the process holding that lock. If the conflicting lock is an open file description lock, then l_pid is set to -1. Note that the returned information may already be out of date by the time the caller inspects it.

      • F_SETLK - Acquire a lock (when l_type is F_RDLCK or F_WRLCK) or release a lock (when l_type is F_UNLCK) on the bytes specified by the l_whence, l_start, and l_len fields of lock.

        If a conflicting lock is held by another process, this call returns -1 and sets errno to EACCES or EAGAIN. (The error returned in this case differs across implementations, so POSIX requires a portable application to check for both errors.)

      • F_SETLKW - As for F_SETLK, but if a conflicting lock is held on the file, then wait for that lock to be released.

        If a signal is caught while waiting, then the call is interrupted and (after the signal handler has returned) returns immediately (with return value -1 and errno set to EINTR; see signal(7)).

      • F_SETOWN - Set the process ID or process group ID that will receive SIGIO and SIGURG signals for events on the file descriptor fd.

        The target process or process group ID is specified in arg. A process ID is specified as a positive value; a process group ID is specified as a negative value. Most commonly, the calling process specifies itself as the owner (that is, arg is specified as getpid(2)).

        As well as setting the file descriptor owner, one must also enable generation of signals on the file descriptor. This is done by using the fcntl() F_SETFL command to set the O_ASYNC file status flag on the file descriptor. Subsequently, a SIGIO signal is sent whenever input or output becomes possible on the file descriptor. The fcntl() F_SETSIG command can be used to obtain delivery of a signal other than SIGIO.

        Sending a signal to the owner process (group) specified by F_SETOWN is subject to the same permissions checks as are described for kill(2), where the sending process is the one that employs F_SETOWN (but see BUGS below). If this permission check fails, then the signal is silently discarded. Note: The F_SETOWN operation records the caller's credentials at the time of the fcntl() call, and it is these saved credentials that are used for the permission checks.

        If the file descriptor fd refers to a socket, F_SETOWN also selects the recipient of SIGURG signals that are delivered when out-of-band data arrives on that socket. (SIGURG is sent in any situation where select(2) would report the socket as having an "exceptional condition".)

        The following was true in 2.6.x kernels up to and including kernel 2.6.11:

        If a nonzero value is given to F_SETSIG in a multithreaded process running with a threading library that supports thread groups (e.g., NPTL), then a positive value given to F_SETOWN has a different meaning: instead of being a process ID identifying a whole process, it is a thread ID identifying a specific thread within a process. Consequently, it may be necessary to pass F_SETOWN the result of gettid(2) instead of getpid(2) to get sensible results when F_SETSIG is used. (In current Linux threading implementations, a main thread's thread ID is the same as its process ID. This means that a single-threaded program can equally use gettid(2) or getpid(2) in this scenario.) Note, however, that the statements in this paragraph do not apply to the SIGURG signal generated for out-of-band data on a socket: this signal is always sent to either a process or a process group, depending on the value given to F_SETOWN.

        The above behavior was accidentally dropped in Linux 2.6.12, and won't be restored. From Linux 2.6.32 onward, use F_SETOWN_EX to target SIGIO and SIGURG signals at a particular thread.

      • F_GETOWN - Return (as the function result) the process ID or process group ID currently receiving SIGIO and SIGURG signals for events on file descriptor fd.

        Process IDs are returned as positive values; process group IDs are returned as negative values (but see BUGS below). arg is ignored.

      • F_SETSIG - Set the signal sent when input or output becomes possible to the value given in arg.

        A value of zero means to send the default SIGIO signal. Any other value (including SIGIO) is the signal to send instead, and in this case additional info is available to the signal handler if installed with SA_SIGINFO.

        By using F_SETSIG with a nonzero value, and setting SA_SIGINFO for the signal handler (see sigaction(2)), extra information about I/O events is passed to the handler in a siginfo_t structure. If the si_code field indicates the source is SI_SIGIO, the si_fd field gives the file descriptor associated with the event. Otherwise, there is no indication which file descriptors are pending, and you should use the usual mechanisms (select(2), poll(2), read(2) with O_NONBLOCK set etc.) to determine which file descriptors are available for I/O.

        Note that the file descriptor provided in si_fd is the one that was specified during the F_SETSIG operation. This can lead to an unusual corner case. If the file descriptor is duplicated (dup(2) or similar), and the original file descriptor is closed, then I/O events will continue to be generated, but the si_fd field will contain the number of the now closed file descriptor.

        By selecting a real time signal (value ≥ SIGRTMIN), multiple I/O events may be queued using the same signal numbers. (Queuing is dependent on available memory.) Extra information is available if SA_SIGINFO is set for the signal handler, as above.

        Note that Linux imposes a limit on the number of real-time signals that may be queued to a process (see getrlimit(2) and signal(7)) and if this limit is reached, then the kernel reverts to delivering SIGIO, and this signal is delivered to the entire process rather than to a specific thread.

      • F_GETSIG - Return (as the function result) the signal sent when input or output becomes possible.

        A value of zero means SIGIO is sent. Any other value (including SIGIO) is the signal sent instead, and in this case additional info is available to the signal handler if installed with SA_SIGINFO. arg is ignored.

      • F_SETOWN_EX - This operation performs a similar task to F_SETOWN. It allows the caller to direct I/O availability signals to a specific thread, process, or process group.

        The caller specifies the target of signals via arg, which is a pointer to a FOwnerEx structure. The type field has one of the following values, which define how pid is interpreted: F_OWNER_TID, F_OWNER_PID, F_OWNER_PGRP.

      • F_GETOWN_EX - Return the current file descriptor owner settings as defined by a previous F_SETOWN_EX operation.

        The information is returned in the FOwnerEx structure pointed to by arg.

        The type field will have one of the values F_OWNER_TID, F_OWNER_PID, or F_OWNER_PGRP. The pid field is a positive integer representing a thread ID, process ID, or process group ID. See F_SETOWN_EX for more details.

      • F_OFD_GETLK - On input to this call, lock describes an open file description lock we would like to place on the file.

        If the lock could be placed, fcntl() does not actually place it, but returns F_UNLCK in the l_type field of lock and leaves the other fields of the structure unchanged. If one or more incompatible locks would prevent this lock being placed, then details about one of these locks are returned via lock, as described above for F_GETLK.

      • F_OFD_SETLK - Acquire an open file description lock (when l_type is F_RDLCK or F_WRLCK) or release an open file description lock (when l_type is F_UNLCK) on the bytes specified by the l_whence, l_start, and l_len fields of lock.

        If a conflicting lock is held by another process, this call returns -1 and sets errno to EAGAIN.

      • F_OFD_SETLKW - As for F_OFD_SETLK, but if a conflicting lock is held on the file, then wait for that lock to be released.

        If a signal is caught while waiting, then the call is interrupted and (after the signal handler has returned) returns immediately (with return value -1 and errno set to EINTR; see signal(7)).

      • F_SETLEASE - Set or remove a file lease according to which of the following values is specified in the integer arg: F_RDLCK, F_WRLCK, F_UNLCK
      • F_GETLEASE - Indicates what type of lease is associated with the file descriptor fd by returning either F_RDLCK, F_WRLCK, or F_UNLCK, indicating, respectively, a read lease, a write lease, or no lease. arg is ignored.
      • F_NOTIFY - (Linux 2.4 onward) Provide notification when the directory referred to by fd or any of the files that it contains is changed.

        The events to be notified are specified in arg, which is a bit mask specified by ORing together zero or more of the following bits: DN_ACCESS, DN_MODIFY, DN_CREATE, DN_DELETE, DN_RENAME, DN_ATTRIB

        (In order to obtain these definitions, the _GNU_SOURCE feature test macro must be defined before including any header files.)

        Directory notifications are normally "one-shot", and the application must reregister to receive further notifications. Alternatively, if DN_MULTISHOT is included in arg, then notification will remain in effect until explicitly removed.

        A series of F_NOTIFY requests is cumulative, with the events in arg being added to the set already monitored. To disable notification of all events, make an F_NOTIFY call specifying arg as 0.

        Notification occurs via delivery of a signal. The default signal is SIGIO, but this can be changed using the F_SETSIG command to fcntl(). (Note that SIGIO is one of the nonqueuing standard signals; switching to the use of a real-time signal means that multiple notifications can be queued to the process.) In the latter case, the signal handler receives a siginfo_t structure as its second argument (if the handler was established using SA_SIGINFO) and the si_fd field of this structure contains the file descriptor which generated the notification (useful when establishing notification on multiple directories).

        Especially when using DN_MULTISHOT, a real time signal should be used for notification, so that multiple notifications can be queued.

        NOTE: New applications should use the inotify interface (available since kernel 2.6.13), which provides a much superior interface for obtaining notifications of filesystem events. See inotify(7).

      • F_SETPIPE_SZ - Change the capacity of the pipe referred to by fd to be at least arg bytes.

        An unprivileged process can adjust the pipe capacity to any value between the system page size and the limit defined in /proc/sys/fs/pipe-max-size (see proc(5)). Attempts to set the pipe capacity below the page size are silently rounded up to the page size. Attempts by an unprivileged process to set the pipe capacity above the limit in /proc/sys/fs/pipe-max-size yield the error EPERM; a privileged process (CAP_SYS_RESOURCE) can override the limit.

        When allocating the buffer for the pipe, the kernel may use a capacity larger than arg, if that is convenient for the implementation. (In the current implementation, the allocation is the next higher power-of-two page-size multiple of the requested size.) The actual capacity (in bytes) that is set is returned as the function result.

        Attempting to set the pipe capacity smaller than the amount of buffer space currently used to store data produces the error EBUSY.

        Note that because of the way the pages of the pipe buffer are employed when data is written to the pipe, the number of bytes that can be written may be less than the nominal size, depending on the size of the writes.

      • F_GETPIPE_SZ - Return (as the function result) the capacity of the pipe referred to by fd.
      • F_ADD_SEALS - Add the seals given in the bit-mask argument arg to the set of seals of the inode referred to by the file descriptor fd.

        Seals cannot be removed again. Once this call succeeds, the seals are enforced by the kernel immediately. If the current set of seals includes F_SEAL_SEAL (see below), then this call will be rejected with EPERM. Adding a seal that is already set is a no-op, in case F_SEAL_SEAL is not set already. In order to place a seal, the file descriptor fd must be writable.

      • F_GET_SEALS - Return (as the function result) the current set of seals of the inode referred to by fd.

        If no seals are set, 0 is returned. If the file does not support sealing, -1 is returned and errno is set to EINVAL.

      • F_GET_RW_HINT - Returns the value of the read/write hint associated with the underlying inode referred to by fd.
      • F_SET_RW_HINT - Sets the read/write hint value associated with the underlying inode referred to by fd.

        This hint persists until either it is explicitly modified or the underlying filesystem is unmounted.

      • F_GET_FILE_RW_HINT - Returns the value of the read/write hint associated with the open file description referred to by fd.
      • F_SET_FILE_RW_HINT - Sets the read/write hint value associated with the open file description referred to by fd.
      • F_DUPFD_CLOEXEC - As for F_DUPFD, but additionally set the close-on-exec flag for the duplicate file descriptor.

        Specifying this flag permits a program to avoid an additional fcntl() F_SETFD operation to set the FD_CLOEXEC flag. For an explanation of why this flag is useful, see the description of O_CLOEXEC in open(2).

      See Also:

    • F_GETPIPE_SZ

      public static final int F_GETPIPE_SZ
      fcntl(int, int) commands.
      Enum values:
      • F_DUPFD - Duplicate the file descriptor fd using the lowest-numbered available file descriptor greater than or equal to arg.

        This is different from dup2(2), which uses exactly the file descriptor specified.

        On success, the new file descriptor is returned.

        See dup(2) for further details.

      • F_GETFD - Return (as the function result) the file descriptor flags; arg is ignored.
      • F_SETFD - Set the file descriptor flags to the value specified by arg.
      • F_GETFL - Return (as the function result) the file access mode and the file status flags; arg is ignored.
      • F_SETFL - Set the file status flags to the value specified by arg.

        File access mode (O_RDONLY, O_WRONLY, O_RDWR) and file creation flags (i.e., O_CREAT, O_EXCL, O_NOCTTY, O_TRUNC) in arg are ignored. On Linux, this command can change only the O_APPEND, O_ASYNC, O_DIRECT, O_NOATIME, and O_NONBLOCK flags. It is not possible to change the O_DSYNC and O_SYNC flags; see BUGS, below.

      • F_GETLK - On input to this call, lock describes a lock we would like to place on the file.

        If the lock could be placed, fcntl() does not actually place it, but returns F_UNLCK in the l_type field of lock and leaves the other fields of the structure unchanged.

        If one or more incompatible locks would prevent this lock being placed, then fcntl() returns details about one of those locks in the l_type, l_whence, l_start, and l_len fields of lock. If the conflicting lock is a traditional (process-associated) record lock, then the l_pid field is set to the PID of the process holding that lock. If the conflicting lock is an open file description lock, then l_pid is set to -1. Note that the returned information may already be out of date by the time the caller inspects it.

      • F_SETLK - Acquire a lock (when l_type is F_RDLCK or F_WRLCK) or release a lock (when l_type is F_UNLCK) on the bytes specified by the l_whence, l_start, and l_len fields of lock.

        If a conflicting lock is held by another process, this call returns -1 and sets errno to EACCES or EAGAIN. (The error returned in this case differs across implementations, so POSIX requires a portable application to check for both errors.)

      • F_SETLKW - As for F_SETLK, but if a conflicting lock is held on the file, then wait for that lock to be released.

        If a signal is caught while waiting, then the call is interrupted and (after the signal handler has returned) returns immediately (with return value -1 and errno set to EINTR; see signal(7)).

      • F_SETOWN - Set the process ID or process group ID that will receive SIGIO and SIGURG signals for events on the file descriptor fd.

        The target process or process group ID is specified in arg. A process ID is specified as a positive value; a process group ID is specified as a negative value. Most commonly, the calling process specifies itself as the owner (that is, arg is specified as getpid(2)).

        As well as setting the file descriptor owner, one must also enable generation of signals on the file descriptor. This is done by using the fcntl() F_SETFL command to set the O_ASYNC file status flag on the file descriptor. Subsequently, a SIGIO signal is sent whenever input or output becomes possible on the file descriptor. The fcntl() F_SETSIG command can be used to obtain delivery of a signal other than SIGIO.

        Sending a signal to the owner process (group) specified by F_SETOWN is subject to the same permissions checks as are described for kill(2), where the sending process is the one that employs F_SETOWN (but see BUGS below). If this permission check fails, then the signal is silently discarded. Note: The F_SETOWN operation records the caller's credentials at the time of the fcntl() call, and it is these saved credentials that are used for the permission checks.

        If the file descriptor fd refers to a socket, F_SETOWN also selects the recipient of SIGURG signals that are delivered when out-of-band data arrives on that socket. (SIGURG is sent in any situation where select(2) would report the socket as having an "exceptional condition".)

        The following was true in 2.6.x kernels up to and including kernel 2.6.11:

        If a nonzero value is given to F_SETSIG in a multithreaded process running with a threading library that supports thread groups (e.g., NPTL), then a positive value given to F_SETOWN has a different meaning: instead of being a process ID identifying a whole process, it is a thread ID identifying a specific thread within a process. Consequently, it may be necessary to pass F_SETOWN the result of gettid(2) instead of getpid(2) to get sensible results when F_SETSIG is used. (In current Linux threading implementations, a main thread's thread ID is the same as its process ID. This means that a single-threaded program can equally use gettid(2) or getpid(2) in this scenario.) Note, however, that the statements in this paragraph do not apply to the SIGURG signal generated for out-of-band data on a socket: this signal is always sent to either a process or a process group, depending on the value given to F_SETOWN.

        The above behavior was accidentally dropped in Linux 2.6.12, and won't be restored. From Linux 2.6.32 onward, use F_SETOWN_EX to target SIGIO and SIGURG signals at a particular thread.

      • F_GETOWN - Return (as the function result) the process ID or process group ID currently receiving SIGIO and SIGURG signals for events on file descriptor fd.

        Process IDs are returned as positive values; process group IDs are returned as negative values (but see BUGS below). arg is ignored.

      • F_SETSIG - Set the signal sent when input or output becomes possible to the value given in arg.

        A value of zero means to send the default SIGIO signal. Any other value (including SIGIO) is the signal to send instead, and in this case additional info is available to the signal handler if installed with SA_SIGINFO.

        By using F_SETSIG with a nonzero value, and setting SA_SIGINFO for the signal handler (see sigaction(2)), extra information about I/O events is passed to the handler in a siginfo_t structure. If the si_code field indicates the source is SI_SIGIO, the si_fd field gives the file descriptor associated with the event. Otherwise, there is no indication which file descriptors are pending, and you should use the usual mechanisms (select(2), poll(2), read(2) with O_NONBLOCK set etc.) to determine which file descriptors are available for I/O.

        Note that the file descriptor provided in si_fd is the one that was specified during the F_SETSIG operation. This can lead to an unusual corner case. If the file descriptor is duplicated (dup(2) or similar), and the original file descriptor is closed, then I/O events will continue to be generated, but the si_fd field will contain the number of the now closed file descriptor.

        By selecting a real time signal (value ≥ SIGRTMIN), multiple I/O events may be queued using the same signal numbers. (Queuing is dependent on available memory.) Extra information is available if SA_SIGINFO is set for the signal handler, as above.

        Note that Linux imposes a limit on the number of real-time signals that may be queued to a process (see getrlimit(2) and signal(7)) and if this limit is reached, then the kernel reverts to delivering SIGIO, and this signal is delivered to the entire process rather than to a specific thread.

      • F_GETSIG - Return (as the function result) the signal sent when input or output becomes possible.

        A value of zero means SIGIO is sent. Any other value (including SIGIO) is the signal sent instead, and in this case additional info is available to the signal handler if installed with SA_SIGINFO. arg is ignored.

      • F_SETOWN_EX - This operation performs a similar task to F_SETOWN. It allows the caller to direct I/O availability signals to a specific thread, process, or process group.

        The caller specifies the target of signals via arg, which is a pointer to a FOwnerEx structure. The type field has one of the following values, which define how pid is interpreted: F_OWNER_TID, F_OWNER_PID, F_OWNER_PGRP.

      • F_GETOWN_EX - Return the current file descriptor owner settings as defined by a previous F_SETOWN_EX operation.

        The information is returned in the FOwnerEx structure pointed to by arg.

        The type field will have one of the values F_OWNER_TID, F_OWNER_PID, or F_OWNER_PGRP. The pid field is a positive integer representing a thread ID, process ID, or process group ID. See F_SETOWN_EX for more details.

      • F_OFD_GETLK - On input to this call, lock describes an open file description lock we would like to place on the file.

        If the lock could be placed, fcntl() does not actually place it, but returns F_UNLCK in the l_type field of lock and leaves the other fields of the structure unchanged. If one or more incompatible locks would prevent this lock being placed, then details about one of these locks are returned via lock, as described above for F_GETLK.

      • F_OFD_SETLK - Acquire an open file description lock (when l_type is F_RDLCK or F_WRLCK) or release an open file description lock (when l_type is F_UNLCK) on the bytes specified by the l_whence, l_start, and l_len fields of lock.

        If a conflicting lock is held by another process, this call returns -1 and sets errno to EAGAIN.

      • F_OFD_SETLKW - As for F_OFD_SETLK, but if a conflicting lock is held on the file, then wait for that lock to be released.

        If a signal is caught while waiting, then the call is interrupted and (after the signal handler has returned) returns immediately (with return value -1 and errno set to EINTR; see signal(7)).

      • F_SETLEASE - Set or remove a file lease according to which of the following values is specified in the integer arg: F_RDLCK, F_WRLCK, F_UNLCK
      • F_GETLEASE - Indicates what type of lease is associated with the file descriptor fd by returning either F_RDLCK, F_WRLCK, or F_UNLCK, indicating, respectively, a read lease, a write lease, or no lease. arg is ignored.
      • F_NOTIFY - (Linux 2.4 onward) Provide notification when the directory referred to by fd or any of the files that it contains is changed.

        The events to be notified are specified in arg, which is a bit mask specified by ORing together zero or more of the following bits: DN_ACCESS, DN_MODIFY, DN_CREATE, DN_DELETE, DN_RENAME, DN_ATTRIB

        (In order to obtain these definitions, the _GNU_SOURCE feature test macro must be defined before including any header files.)

        Directory notifications are normally "one-shot", and the application must reregister to receive further notifications. Alternatively, if DN_MULTISHOT is included in arg, then notification will remain in effect until explicitly removed.

        A series of F_NOTIFY requests is cumulative, with the events in arg being added to the set already monitored. To disable notification of all events, make an F_NOTIFY call specifying arg as 0.

        Notification occurs via delivery of a signal. The default signal is SIGIO, but this can be changed using the F_SETSIG command to fcntl(). (Note that SIGIO is one of the nonqueuing standard signals; switching to the use of a real-time signal means that multiple notifications can be queued to the process.) In the latter case, the signal handler receives a siginfo_t structure as its second argument (if the handler was established using SA_SIGINFO) and the si_fd field of this structure contains the file descriptor which generated the notification (useful when establishing notification on multiple directories).

        Especially when using DN_MULTISHOT, a real time signal should be used for notification, so that multiple notifications can be queued.

        NOTE: New applications should use the inotify interface (available since kernel 2.6.13), which provides a much superior interface for obtaining notifications of filesystem events. See inotify(7).

      • F_SETPIPE_SZ - Change the capacity of the pipe referred to by fd to be at least arg bytes.

        An unprivileged process can adjust the pipe capacity to any value between the system page size and the limit defined in /proc/sys/fs/pipe-max-size (see proc(5)). Attempts to set the pipe capacity below the page size are silently rounded up to the page size. Attempts by an unprivileged process to set the pipe capacity above the limit in /proc/sys/fs/pipe-max-size yield the error EPERM; a privileged process (CAP_SYS_RESOURCE) can override the limit.

        When allocating the buffer for the pipe, the kernel may use a capacity larger than arg, if that is convenient for the implementation. (In the current implementation, the allocation is the next higher power-of-two page-size multiple of the requested size.) The actual capacity (in bytes) that is set is returned as the function result.

        Attempting to set the pipe capacity smaller than the amount of buffer space currently used to store data produces the error EBUSY.

        Note that because of the way the pages of the pipe buffer are employed when data is written to the pipe, the number of bytes that can be written may be less than the nominal size, depending on the size of the writes.

      • F_GETPIPE_SZ - Return (as the function result) the capacity of the pipe referred to by fd.
      • F_ADD_SEALS - Add the seals given in the bit-mask argument arg to the set of seals of the inode referred to by the file descriptor fd.

        Seals cannot be removed again. Once this call succeeds, the seals are enforced by the kernel immediately. If the current set of seals includes F_SEAL_SEAL (see below), then this call will be rejected with EPERM. Adding a seal that is already set is a no-op, in case F_SEAL_SEAL is not set already. In order to place a seal, the file descriptor fd must be writable.

      • F_GET_SEALS - Return (as the function result) the current set of seals of the inode referred to by fd.

        If no seals are set, 0 is returned. If the file does not support sealing, -1 is returned and errno is set to EINVAL.

      • F_GET_RW_HINT - Returns the value of the read/write hint associated with the underlying inode referred to by fd.
      • F_SET_RW_HINT - Sets the read/write hint value associated with the underlying inode referred to by fd.

        This hint persists until either it is explicitly modified or the underlying filesystem is unmounted.

      • F_GET_FILE_RW_HINT - Returns the value of the read/write hint associated with the open file description referred to by fd.
      • F_SET_FILE_RW_HINT - Sets the read/write hint value associated with the open file description referred to by fd.
      • F_DUPFD_CLOEXEC - As for F_DUPFD, but additionally set the close-on-exec flag for the duplicate file descriptor.

        Specifying this flag permits a program to avoid an additional fcntl() F_SETFD operation to set the FD_CLOEXEC flag. For an explanation of why this flag is useful, see the description of O_CLOEXEC in open(2).

      See Also:

    • F_ADD_SEALS

      public static final int F_ADD_SEALS
      fcntl(int, int) commands.
      Enum values:
      • F_DUPFD - Duplicate the file descriptor fd using the lowest-numbered available file descriptor greater than or equal to arg.

        This is different from dup2(2), which uses exactly the file descriptor specified.

        On success, the new file descriptor is returned.

        See dup(2) for further details.

      • F_GETFD - Return (as the function result) the file descriptor flags; arg is ignored.
      • F_SETFD - Set the file descriptor flags to the value specified by arg.
      • F_GETFL - Return (as the function result) the file access mode and the file status flags; arg is ignored.
      • F_SETFL - Set the file status flags to the value specified by arg.

        File access mode (O_RDONLY, O_WRONLY, O_RDWR) and file creation flags (i.e., O_CREAT, O_EXCL, O_NOCTTY, O_TRUNC) in arg are ignored. On Linux, this command can change only the O_APPEND, O_ASYNC, O_DIRECT, O_NOATIME, and O_NONBLOCK flags. It is not possible to change the O_DSYNC and O_SYNC flags; see BUGS, below.

      • F_GETLK - On input to this call, lock describes a lock we would like to place on the file.

        If the lock could be placed, fcntl() does not actually place it, but returns F_UNLCK in the l_type field of lock and leaves the other fields of the structure unchanged.

        If one or more incompatible locks would prevent this lock being placed, then fcntl() returns details about one of those locks in the l_type, l_whence, l_start, and l_len fields of lock. If the conflicting lock is a traditional (process-associated) record lock, then the l_pid field is set to the PID of the process holding that lock. If the conflicting lock is an open file description lock, then l_pid is set to -1. Note that the returned information may already be out of date by the time the caller inspects it.

      • F_SETLK - Acquire a lock (when l_type is F_RDLCK or F_WRLCK) or release a lock (when l_type is F_UNLCK) on the bytes specified by the l_whence, l_start, and l_len fields of lock.

        If a conflicting lock is held by another process, this call returns -1 and sets errno to EACCES or EAGAIN. (The error returned in this case differs across implementations, so POSIX requires a portable application to check for both errors.)

      • F_SETLKW - As for F_SETLK, but if a conflicting lock is held on the file, then wait for that lock to be released.

        If a signal is caught while waiting, then the call is interrupted and (after the signal handler has returned) returns immediately (with return value -1 and errno set to EINTR; see signal(7)).

      • F_SETOWN - Set the process ID or process group ID that will receive SIGIO and SIGURG signals for events on the file descriptor fd.

        The target process or process group ID is specified in arg. A process ID is specified as a positive value; a process group ID is specified as a negative value. Most commonly, the calling process specifies itself as the owner (that is, arg is specified as getpid(2)).

        As well as setting the file descriptor owner, one must also enable generation of signals on the file descriptor. This is done by using the fcntl() F_SETFL command to set the O_ASYNC file status flag on the file descriptor. Subsequently, a SIGIO signal is sent whenever input or output becomes possible on the file descriptor. The fcntl() F_SETSIG command can be used to obtain delivery of a signal other than SIGIO.

        Sending a signal to the owner process (group) specified by F_SETOWN is subject to the same permissions checks as are described for kill(2), where the sending process is the one that employs F_SETOWN (but see BUGS below). If this permission check fails, then the signal is silently discarded. Note: The F_SETOWN operation records the caller's credentials at the time of the fcntl() call, and it is these saved credentials that are used for the permission checks.

        If the file descriptor fd refers to a socket, F_SETOWN also selects the recipient of SIGURG signals that are delivered when out-of-band data arrives on that socket. (SIGURG is sent in any situation where select(2) would report the socket as having an "exceptional condition".)

        The following was true in 2.6.x kernels up to and including kernel 2.6.11:

        If a nonzero value is given to F_SETSIG in a multithreaded process running with a threading library that supports thread groups (e.g., NPTL), then a positive value given to F_SETOWN has a different meaning: instead of being a process ID identifying a whole process, it is a thread ID identifying a specific thread within a process. Consequently, it may be necessary to pass F_SETOWN the result of gettid(2) instead of getpid(2) to get sensible results when F_SETSIG is used. (In current Linux threading implementations, a main thread's thread ID is the same as its process ID. This means that a single-threaded program can equally use gettid(2) or getpid(2) in this scenario.) Note, however, that the statements in this paragraph do not apply to the SIGURG signal generated for out-of-band data on a socket: this signal is always sent to either a process or a process group, depending on the value given to F_SETOWN.

        The above behavior was accidentally dropped in Linux 2.6.12, and won't be restored. From Linux 2.6.32 onward, use F_SETOWN_EX to target SIGIO and SIGURG signals at a particular thread.

      • F_GETOWN - Return (as the function result) the process ID or process group ID currently receiving SIGIO and SIGURG signals for events on file descriptor fd.

        Process IDs are returned as positive values; process group IDs are returned as negative values (but see BUGS below). arg is ignored.

      • F_SETSIG - Set the signal sent when input or output becomes possible to the value given in arg.

        A value of zero means to send the default SIGIO signal. Any other value (including SIGIO) is the signal to send instead, and in this case additional info is available to the signal handler if installed with SA_SIGINFO.

        By using F_SETSIG with a nonzero value, and setting SA_SIGINFO for the signal handler (see sigaction(2)), extra information about I/O events is passed to the handler in a siginfo_t structure. If the si_code field indicates the source is SI_SIGIO, the si_fd field gives the file descriptor associated with the event. Otherwise, there is no indication which file descriptors are pending, and you should use the usual mechanisms (select(2), poll(2), read(2) with O_NONBLOCK set etc.) to determine which file descriptors are available for I/O.

        Note that the file descriptor provided in si_fd is the one that was specified during the F_SETSIG operation. This can lead to an unusual corner case. If the file descriptor is duplicated (dup(2) or similar), and the original file descriptor is closed, then I/O events will continue to be generated, but the si_fd field will contain the number of the now closed file descriptor.

        By selecting a real time signal (value ≥ SIGRTMIN), multiple I/O events may be queued using the same signal numbers. (Queuing is dependent on available memory.) Extra information is available if SA_SIGINFO is set for the signal handler, as above.

        Note that Linux imposes a limit on the number of real-time signals that may be queued to a process (see getrlimit(2) and signal(7)) and if this limit is reached, then the kernel reverts to delivering SIGIO, and this signal is delivered to the entire process rather than to a specific thread.

      • F_GETSIG - Return (as the function result) the signal sent when input or output becomes possible.

        A value of zero means SIGIO is sent. Any other value (including SIGIO) is the signal sent instead, and in this case additional info is available to the signal handler if installed with SA_SIGINFO. arg is ignored.

      • F_SETOWN_EX - This operation performs a similar task to F_SETOWN. It allows the caller to direct I/O availability signals to a specific thread, process, or process group.

        The caller specifies the target of signals via arg, which is a pointer to a FOwnerEx structure. The type field has one of the following values, which define how pid is interpreted: F_OWNER_TID, F_OWNER_PID, F_OWNER_PGRP.

      • F_GETOWN_EX - Return the current file descriptor owner settings as defined by a previous F_SETOWN_EX operation.

        The information is returned in the FOwnerEx structure pointed to by arg.

        The type field will have one of the values F_OWNER_TID, F_OWNER_PID, or F_OWNER_PGRP. The pid field is a positive integer representing a thread ID, process ID, or process group ID. See F_SETOWN_EX for more details.

      • F_OFD_GETLK - On input to this call, lock describes an open file description lock we would like to place on the file.

        If the lock could be placed, fcntl() does not actually place it, but returns F_UNLCK in the l_type field of lock and leaves the other fields of the structure unchanged. If one or more incompatible locks would prevent this lock being placed, then details about one of these locks are returned via lock, as described above for F_GETLK.

      • F_OFD_SETLK - Acquire an open file description lock (when l_type is F_RDLCK or F_WRLCK) or release an open file description lock (when l_type is F_UNLCK) on the bytes specified by the l_whence, l_start, and l_len fields of lock.

        If a conflicting lock is held by another process, this call returns -1 and sets errno to EAGAIN.

      • F_OFD_SETLKW - As for F_OFD_SETLK, but if a conflicting lock is held on the file, then wait for that lock to be released.

        If a signal is caught while waiting, then the call is interrupted and (after the signal handler has returned) returns immediately (with return value -1 and errno set to EINTR; see signal(7)).

      • F_SETLEASE - Set or remove a file lease according to which of the following values is specified in the integer arg: F_RDLCK, F_WRLCK, F_UNLCK
      • F_GETLEASE - Indicates what type of lease is associated with the file descriptor fd by returning either F_RDLCK, F_WRLCK, or F_UNLCK, indicating, respectively, a read lease, a write lease, or no lease. arg is ignored.
      • F_NOTIFY - (Linux 2.4 onward) Provide notification when the directory referred to by fd or any of the files that it contains is changed.

        The events to be notified are specified in arg, which is a bit mask specified by ORing together zero or more of the following bits: DN_ACCESS, DN_MODIFY, DN_CREATE, DN_DELETE, DN_RENAME, DN_ATTRIB

        (In order to obtain these definitions, the _GNU_SOURCE feature test macro must be defined before including any header files.)

        Directory notifications are normally "one-shot", and the application must reregister to receive further notifications. Alternatively, if DN_MULTISHOT is included in arg, then notification will remain in effect until explicitly removed.

        A series of F_NOTIFY requests is cumulative, with the events in arg being added to the set already monitored. To disable notification of all events, make an F_NOTIFY call specifying arg as 0.

        Notification occurs via delivery of a signal. The default signal is SIGIO, but this can be changed using the F_SETSIG command to fcntl(). (Note that SIGIO is one of the nonqueuing standard signals; switching to the use of a real-time signal means that multiple notifications can be queued to the process.) In the latter case, the signal handler receives a siginfo_t structure as its second argument (if the handler was established using SA_SIGINFO) and the si_fd field of this structure contains the file descriptor which generated the notification (useful when establishing notification on multiple directories).

        Especially when using DN_MULTISHOT, a real time signal should be used for notification, so that multiple notifications can be queued.

        NOTE: New applications should use the inotify interface (available since kernel 2.6.13), which provides a much superior interface for obtaining notifications of filesystem events. See inotify(7).

      • F_SETPIPE_SZ - Change the capacity of the pipe referred to by fd to be at least arg bytes.

        An unprivileged process can adjust the pipe capacity to any value between the system page size and the limit defined in /proc/sys/fs/pipe-max-size (see proc(5)). Attempts to set the pipe capacity below the page size are silently rounded up to the page size. Attempts by an unprivileged process to set the pipe capacity above the limit in /proc/sys/fs/pipe-max-size yield the error EPERM; a privileged process (CAP_SYS_RESOURCE) can override the limit.

        When allocating the buffer for the pipe, the kernel may use a capacity larger than arg, if that is convenient for the implementation. (In the current implementation, the allocation is the next higher power-of-two page-size multiple of the requested size.) The actual capacity (in bytes) that is set is returned as the function result.

        Attempting to set the pipe capacity smaller than the amount of buffer space currently used to store data produces the error EBUSY.

        Note that because of the way the pages of the pipe buffer are employed when data is written to the pipe, the number of bytes that can be written may be less than the nominal size, depending on the size of the writes.

      • F_GETPIPE_SZ - Return (as the function result) the capacity of the pipe referred to by fd.
      • F_ADD_SEALS - Add the seals given in the bit-mask argument arg to the set of seals of the inode referred to by the file descriptor fd.

        Seals cannot be removed again. Once this call succeeds, the seals are enforced by the kernel immediately. If the current set of seals includes F_SEAL_SEAL (see below), then this call will be rejected with EPERM. Adding a seal that is already set is a no-op, in case F_SEAL_SEAL is not set already. In order to place a seal, the file descriptor fd must be writable.

      • F_GET_SEALS - Return (as the function result) the current set of seals of the inode referred to by fd.

        If no seals are set, 0 is returned. If the file does not support sealing, -1 is returned and errno is set to EINVAL.

      • F_GET_RW_HINT - Returns the value of the read/write hint associated with the underlying inode referred to by fd.
      • F_SET_RW_HINT - Sets the read/write hint value associated with the underlying inode referred to by fd.

        This hint persists until either it is explicitly modified or the underlying filesystem is unmounted.

      • F_GET_FILE_RW_HINT - Returns the value of the read/write hint associated with the open file description referred to by fd.
      • F_SET_FILE_RW_HINT - Sets the read/write hint value associated with the open file description referred to by fd.
      • F_DUPFD_CLOEXEC - As for F_DUPFD, but additionally set the close-on-exec flag for the duplicate file descriptor.

        Specifying this flag permits a program to avoid an additional fcntl() F_SETFD operation to set the FD_CLOEXEC flag. For an explanation of why this flag is useful, see the description of O_CLOEXEC in open(2).

      See Also:

    • F_GET_SEALS

      public static final int F_GET_SEALS
      fcntl(int, int) commands.
      Enum values:
      • F_DUPFD - Duplicate the file descriptor fd using the lowest-numbered available file descriptor greater than or equal to arg.

        This is different from dup2(2), which uses exactly the file descriptor specified.

        On success, the new file descriptor is returned.

        See dup(2) for further details.

      • F_GETFD - Return (as the function result) the file descriptor flags; arg is ignored.
      • F_SETFD - Set the file descriptor flags to the value specified by arg.
      • F_GETFL - Return (as the function result) the file access mode and the file status flags; arg is ignored.
      • F_SETFL - Set the file status flags to the value specified by arg.

        File access mode (O_RDONLY, O_WRONLY, O_RDWR) and file creation flags (i.e., O_CREAT, O_EXCL, O_NOCTTY, O_TRUNC) in arg are ignored. On Linux, this command can change only the O_APPEND, O_ASYNC, O_DIRECT, O_NOATIME, and O_NONBLOCK flags. It is not possible to change the O_DSYNC and O_SYNC flags; see BUGS, below.

      • F_GETLK - On input to this call, lock describes a lock we would like to place on the file.

        If the lock could be placed, fcntl() does not actually place it, but returns F_UNLCK in the l_type field of lock and leaves the other fields of the structure unchanged.

        If one or more incompatible locks would prevent this lock being placed, then fcntl() returns details about one of those locks in the l_type, l_whence, l_start, and l_len fields of lock. If the conflicting lock is a traditional (process-associated) record lock, then the l_pid field is set to the PID of the process holding that lock. If the conflicting lock is an open file description lock, then l_pid is set to -1. Note that the returned information may already be out of date by the time the caller inspects it.

      • F_SETLK - Acquire a lock (when l_type is F_RDLCK or F_WRLCK) or release a lock (when l_type is F_UNLCK) on the bytes specified by the l_whence, l_start, and l_len fields of lock.

        If a conflicting lock is held by another process, this call returns -1 and sets errno to EACCES or EAGAIN. (The error returned in this case differs across implementations, so POSIX requires a portable application to check for both errors.)

      • F_SETLKW - As for F_SETLK, but if a conflicting lock is held on the file, then wait for that lock to be released.

        If a signal is caught while waiting, then the call is interrupted and (after the signal handler has returned) returns immediately (with return value -1 and errno set to EINTR; see signal(7)).

      • F_SETOWN - Set the process ID or process group ID that will receive SIGIO and SIGURG signals for events on the file descriptor fd.

        The target process or process group ID is specified in arg. A process ID is specified as a positive value; a process group ID is specified as a negative value. Most commonly, the calling process specifies itself as the owner (that is, arg is specified as getpid(2)).

        As well as setting the file descriptor owner, one must also enable generation of signals on the file descriptor. This is done by using the fcntl() F_SETFL command to set the O_ASYNC file status flag on the file descriptor. Subsequently, a SIGIO signal is sent whenever input or output becomes possible on the file descriptor. The fcntl() F_SETSIG command can be used to obtain delivery of a signal other than SIGIO.

        Sending a signal to the owner process (group) specified by F_SETOWN is subject to the same permissions checks as are described for kill(2), where the sending process is the one that employs F_SETOWN (but see BUGS below). If this permission check fails, then the signal is silently discarded. Note: The F_SETOWN operation records the caller's credentials at the time of the fcntl() call, and it is these saved credentials that are used for the permission checks.

        If the file descriptor fd refers to a socket, F_SETOWN also selects the recipient of SIGURG signals that are delivered when out-of-band data arrives on that socket. (SIGURG is sent in any situation where select(2) would report the socket as having an "exceptional condition".)

        The following was true in 2.6.x kernels up to and including kernel 2.6.11:

        If a nonzero value is given to F_SETSIG in a multithreaded process running with a threading library that supports thread groups (e.g., NPTL), then a positive value given to F_SETOWN has a different meaning: instead of being a process ID identifying a whole process, it is a thread ID identifying a specific thread within a process. Consequently, it may be necessary to pass F_SETOWN the result of gettid(2) instead of getpid(2) to get sensible results when F_SETSIG is used. (In current Linux threading implementations, a main thread's thread ID is the same as its process ID. This means that a single-threaded program can equally use gettid(2) or getpid(2) in this scenario.) Note, however, that the statements in this paragraph do not apply to the SIGURG signal generated for out-of-band data on a socket: this signal is always sent to either a process or a process group, depending on the value given to F_SETOWN.

        The above behavior was accidentally dropped in Linux 2.6.12, and won't be restored. From Linux 2.6.32 onward, use F_SETOWN_EX to target SIGIO and SIGURG signals at a particular thread.

      • F_GETOWN - Return (as the function result) the process ID or process group ID currently receiving SIGIO and SIGURG signals for events on file descriptor fd.

        Process IDs are returned as positive values; process group IDs are returned as negative values (but see BUGS below). arg is ignored.

      • F_SETSIG - Set the signal sent when input or output becomes possible to the value given in arg.

        A value of zero means to send the default SIGIO signal. Any other value (including SIGIO) is the signal to send instead, and in this case additional info is available to the signal handler if installed with SA_SIGINFO.

        By using F_SETSIG with a nonzero value, and setting SA_SIGINFO for the signal handler (see sigaction(2)), extra information about I/O events is passed to the handler in a siginfo_t structure. If the si_code field indicates the source is SI_SIGIO, the si_fd field gives the file descriptor associated with the event. Otherwise, there is no indication which file descriptors are pending, and you should use the usual mechanisms (select(2), poll(2), read(2) with O_NONBLOCK set etc.) to determine which file descriptors are available for I/O.

        Note that the file descriptor provided in si_fd is the one that was specified during the F_SETSIG operation. This can lead to an unusual corner case. If the file descriptor is duplicated (dup(2) or similar), and the original file descriptor is closed, then I/O events will continue to be generated, but the si_fd field will contain the number of the now closed file descriptor.

        By selecting a real time signal (value ≥ SIGRTMIN), multiple I/O events may be queued using the same signal numbers. (Queuing is dependent on available memory.) Extra information is available if SA_SIGINFO is set for the signal handler, as above.

        Note that Linux imposes a limit on the number of real-time signals that may be queued to a process (see getrlimit(2) and signal(7)) and if this limit is reached, then the kernel reverts to delivering SIGIO, and this signal is delivered to the entire process rather than to a specific thread.

      • F_GETSIG - Return (as the function result) the signal sent when input or output becomes possible.

        A value of zero means SIGIO is sent. Any other value (including SIGIO) is the signal sent instead, and in this case additional info is available to the signal handler if installed with SA_SIGINFO. arg is ignored.

      • F_SETOWN_EX - This operation performs a similar task to F_SETOWN. It allows the caller to direct I/O availability signals to a specific thread, process, or process group.

        The caller specifies the target of signals via arg, which is a pointer to a FOwnerEx structure. The type field has one of the following values, which define how pid is interpreted: F_OWNER_TID, F_OWNER_PID, F_OWNER_PGRP.

      • F_GETOWN_EX - Return the current file descriptor owner settings as defined by a previous F_SETOWN_EX operation.

        The information is returned in the FOwnerEx structure pointed to by arg.

        The type field will have one of the values F_OWNER_TID, F_OWNER_PID, or F_OWNER_PGRP. The pid field is a positive integer representing a thread ID, process ID, or process group ID. See F_SETOWN_EX for more details.

      • F_OFD_GETLK - On input to this call, lock describes an open file description lock we would like to place on the file.

        If the lock could be placed, fcntl() does not actually place it, but returns F_UNLCK in the l_type field of lock and leaves the other fields of the structure unchanged. If one or more incompatible locks would prevent this lock being placed, then details about one of these locks are returned via lock, as described above for F_GETLK.

      • F_OFD_SETLK - Acquire an open file description lock (when l_type is F_RDLCK or F_WRLCK) or release an open file description lock (when l_type is F_UNLCK) on the bytes specified by the l_whence, l_start, and l_len fields of lock.

        If a conflicting lock is held by another process, this call returns -1 and sets errno to EAGAIN.

      • F_OFD_SETLKW - As for F_OFD_SETLK, but if a conflicting lock is held on the file, then wait for that lock to be released.

        If a signal is caught while waiting, then the call is interrupted and (after the signal handler has returned) returns immediately (with return value -1 and errno set to EINTR; see signal(7)).

      • F_SETLEASE - Set or remove a file lease according to which of the following values is specified in the integer arg: F_RDLCK, F_WRLCK, F_UNLCK
      • F_GETLEASE - Indicates what type of lease is associated with the file descriptor fd by returning either F_RDLCK, F_WRLCK, or F_UNLCK, indicating, respectively, a read lease, a write lease, or no lease. arg is ignored.
      • F_NOTIFY - (Linux 2.4 onward) Provide notification when the directory referred to by fd or any of the files that it contains is changed.

        The events to be notified are specified in arg, which is a bit mask specified by ORing together zero or more of the following bits: DN_ACCESS, DN_MODIFY, DN_CREATE, DN_DELETE, DN_RENAME, DN_ATTRIB

        (In order to obtain these definitions, the _GNU_SOURCE feature test macro must be defined before including any header files.)

        Directory notifications are normally "one-shot", and the application must reregister to receive further notifications. Alternatively, if DN_MULTISHOT is included in arg, then notification will remain in effect until explicitly removed.

        A series of F_NOTIFY requests is cumulative, with the events in arg being added to the set already monitored. To disable notification of all events, make an F_NOTIFY call specifying arg as 0.

        Notification occurs via delivery of a signal. The default signal is SIGIO, but this can be changed using the F_SETSIG command to fcntl(). (Note that SIGIO is one of the nonqueuing standard signals; switching to the use of a real-time signal means that multiple notifications can be queued to the process.) In the latter case, the signal handler receives a siginfo_t structure as its second argument (if the handler was established using SA_SIGINFO) and the si_fd field of this structure contains the file descriptor which generated the notification (useful when establishing notification on multiple directories).

        Especially when using DN_MULTISHOT, a real time signal should be used for notification, so that multiple notifications can be queued.

        NOTE: New applications should use the inotify interface (available since kernel 2.6.13), which provides a much superior interface for obtaining notifications of filesystem events. See inotify(7).

      • F_SETPIPE_SZ - Change the capacity of the pipe referred to by fd to be at least arg bytes.

        An unprivileged process can adjust the pipe capacity to any value between the system page size and the limit defined in /proc/sys/fs/pipe-max-size (see proc(5)). Attempts to set the pipe capacity below the page size are silently rounded up to the page size. Attempts by an unprivileged process to set the pipe capacity above the limit in /proc/sys/fs/pipe-max-size yield the error EPERM; a privileged process (CAP_SYS_RESOURCE) can override the limit.

        When allocating the buffer for the pipe, the kernel may use a capacity larger than arg, if that is convenient for the implementation. (In the current implementation, the allocation is the next higher power-of-two page-size multiple of the requested size.) The actual capacity (in bytes) that is set is returned as the function result.

        Attempting to set the pipe capacity smaller than the amount of buffer space currently used to store data produces the error EBUSY.

        Note that because of the way the pages of the pipe buffer are employed when data is written to the pipe, the number of bytes that can be written may be less than the nominal size, depending on the size of the writes.

      • F_GETPIPE_SZ - Return (as the function result) the capacity of the pipe referred to by fd.
      • F_ADD_SEALS - Add the seals given in the bit-mask argument arg to the set of seals of the inode referred to by the file descriptor fd.

        Seals cannot be removed again. Once this call succeeds, the seals are enforced by the kernel immediately. If the current set of seals includes F_SEAL_SEAL (see below), then this call will be rejected with EPERM. Adding a seal that is already set is a no-op, in case F_SEAL_SEAL is not set already. In order to place a seal, the file descriptor fd must be writable.

      • F_GET_SEALS - Return (as the function result) the current set of seals of the inode referred to by fd.

        If no seals are set, 0 is returned. If the file does not support sealing, -1 is returned and errno is set to EINVAL.

      • F_GET_RW_HINT - Returns the value of the read/write hint associated with the underlying inode referred to by fd.
      • F_SET_RW_HINT - Sets the read/write hint value associated with the underlying inode referred to by fd.

        This hint persists until either it is explicitly modified or the underlying filesystem is unmounted.

      • F_GET_FILE_RW_HINT - Returns the value of the read/write hint associated with the open file description referred to by fd.
      • F_SET_FILE_RW_HINT - Sets the read/write hint value associated with the open file description referred to by fd.
      • F_DUPFD_CLOEXEC - As for F_DUPFD, but additionally set the close-on-exec flag for the duplicate file descriptor.

        Specifying this flag permits a program to avoid an additional fcntl() F_SETFD operation to set the FD_CLOEXEC flag. For an explanation of why this flag is useful, see the description of O_CLOEXEC in open(2).

      See Also:

    • F_GET_RW_HINT

      public static final int F_GET_RW_HINT
      fcntl(int, int) commands.
      Enum values:
      • F_DUPFD - Duplicate the file descriptor fd using the lowest-numbered available file descriptor greater than or equal to arg.

        This is different from dup2(2), which uses exactly the file descriptor specified.

        On success, the new file descriptor is returned.

        See dup(2) for further details.

      • F_GETFD - Return (as the function result) the file descriptor flags; arg is ignored.
      • F_SETFD - Set the file descriptor flags to the value specified by arg.
      • F_GETFL - Return (as the function result) the file access mode and the file status flags; arg is ignored.
      • F_SETFL - Set the file status flags to the value specified by arg.

        File access mode (O_RDONLY, O_WRONLY, O_RDWR) and file creation flags (i.e., O_CREAT, O_EXCL, O_NOCTTY, O_TRUNC) in arg are ignored. On Linux, this command can change only the O_APPEND, O_ASYNC, O_DIRECT, O_NOATIME, and O_NONBLOCK flags. It is not possible to change the O_DSYNC and O_SYNC flags; see BUGS, below.

      • F_GETLK - On input to this call, lock describes a lock we would like to place on the file.

        If the lock could be placed, fcntl() does not actually place it, but returns F_UNLCK in the l_type field of lock and leaves the other fields of the structure unchanged.

        If one or more incompatible locks would prevent this lock being placed, then fcntl() returns details about one of those locks in the l_type, l_whence, l_start, and l_len fields of lock. If the conflicting lock is a traditional (process-associated) record lock, then the l_pid field is set to the PID of the process holding that lock. If the conflicting lock is an open file description lock, then l_pid is set to -1. Note that the returned information may already be out of date by the time the caller inspects it.

      • F_SETLK - Acquire a lock (when l_type is F_RDLCK or F_WRLCK) or release a lock (when l_type is F_UNLCK) on the bytes specified by the l_whence, l_start, and l_len fields of lock.

        If a conflicting lock is held by another process, this call returns -1 and sets errno to EACCES or EAGAIN. (The error returned in this case differs across implementations, so POSIX requires a portable application to check for both errors.)

      • F_SETLKW - As for F_SETLK, but if a conflicting lock is held on the file, then wait for that lock to be released.

        If a signal is caught while waiting, then the call is interrupted and (after the signal handler has returned) returns immediately (with return value -1 and errno set to EINTR; see signal(7)).

      • F_SETOWN - Set the process ID or process group ID that will receive SIGIO and SIGURG signals for events on the file descriptor fd.

        The target process or process group ID is specified in arg. A process ID is specified as a positive value; a process group ID is specified as a negative value. Most commonly, the calling process specifies itself as the owner (that is, arg is specified as getpid(2)).

        As well as setting the file descriptor owner, one must also enable generation of signals on the file descriptor. This is done by using the fcntl() F_SETFL command to set the O_ASYNC file status flag on the file descriptor. Subsequently, a SIGIO signal is sent whenever input or output becomes possible on the file descriptor. The fcntl() F_SETSIG command can be used to obtain delivery of a signal other than SIGIO.

        Sending a signal to the owner process (group) specified by F_SETOWN is subject to the same permissions checks as are described for kill(2), where the sending process is the one that employs F_SETOWN (but see BUGS below). If this permission check fails, then the signal is silently discarded. Note: The F_SETOWN operation records the caller's credentials at the time of the fcntl() call, and it is these saved credentials that are used for the permission checks.

        If the file descriptor fd refers to a socket, F_SETOWN also selects the recipient of SIGURG signals that are delivered when out-of-band data arrives on that socket. (SIGURG is sent in any situation where select(2) would report the socket as having an "exceptional condition".)

        The following was true in 2.6.x kernels up to and including kernel 2.6.11:

        If a nonzero value is given to F_SETSIG in a multithreaded process running with a threading library that supports thread groups (e.g., NPTL), then a positive value given to F_SETOWN has a different meaning: instead of being a process ID identifying a whole process, it is a thread ID identifying a specific thread within a process. Consequently, it may be necessary to pass F_SETOWN the result of gettid(2) instead of getpid(2) to get sensible results when F_SETSIG is used. (In current Linux threading implementations, a main thread's thread ID is the same as its process ID. This means that a single-threaded program can equally use gettid(2) or getpid(2) in this scenario.) Note, however, that the statements in this paragraph do not apply to the SIGURG signal generated for out-of-band data on a socket: this signal is always sent to either a process or a process group, depending on the value given to F_SETOWN.

        The above behavior was accidentally dropped in Linux 2.6.12, and won't be restored. From Linux 2.6.32 onward, use F_SETOWN_EX to target SIGIO and SIGURG signals at a particular thread.

      • F_GETOWN - Return (as the function result) the process ID or process group ID currently receiving SIGIO and SIGURG signals for events on file descriptor fd.

        Process IDs are returned as positive values; process group IDs are returned as negative values (but see BUGS below). arg is ignored.

      • F_SETSIG - Set the signal sent when input or output becomes possible to the value given in arg.

        A value of zero means to send the default SIGIO signal. Any other value (including SIGIO) is the signal to send instead, and in this case additional info is available to the signal handler if installed with SA_SIGINFO.

        By using F_SETSIG with a nonzero value, and setting SA_SIGINFO for the signal handler (see sigaction(2)), extra information about I/O events is passed to the handler in a siginfo_t structure. If the si_code field indicates the source is SI_SIGIO, the si_fd field gives the file descriptor associated with the event. Otherwise, there is no indication which file descriptors are pending, and you should use the usual mechanisms (select(2), poll(2), read(2) with O_NONBLOCK set etc.) to determine which file descriptors are available for I/O.

        Note that the file descriptor provided in si_fd is the one that was specified during the F_SETSIG operation. This can lead to an unusual corner case. If the file descriptor is duplicated (dup(2) or similar), and the original file descriptor is closed, then I/O events will continue to be generated, but the si_fd field will contain the number of the now closed file descriptor.

        By selecting a real time signal (value ≥ SIGRTMIN), multiple I/O events may be queued using the same signal numbers. (Queuing is dependent on available memory.) Extra information is available if SA_SIGINFO is set for the signal handler, as above.

        Note that Linux imposes a limit on the number of real-time signals that may be queued to a process (see getrlimit(2) and signal(7)) and if this limit is reached, then the kernel reverts to delivering SIGIO, and this signal is delivered to the entire process rather than to a specific thread.

      • F_GETSIG - Return (as the function result) the signal sent when input or output becomes possible.

        A value of zero means SIGIO is sent. Any other value (including SIGIO) is the signal sent instead, and in this case additional info is available to the signal handler if installed with SA_SIGINFO. arg is ignored.

      • F_SETOWN_EX - This operation performs a similar task to F_SETOWN. It allows the caller to direct I/O availability signals to a specific thread, process, or process group.

        The caller specifies the target of signals via arg, which is a pointer to a FOwnerEx structure. The type field has one of the following values, which define how pid is interpreted: F_OWNER_TID, F_OWNER_PID, F_OWNER_PGRP.

      • F_GETOWN_EX - Return the current file descriptor owner settings as defined by a previous F_SETOWN_EX operation.

        The information is returned in the FOwnerEx structure pointed to by arg.

        The type field will have one of the values F_OWNER_TID, F_OWNER_PID, or F_OWNER_PGRP. The pid field is a positive integer representing a thread ID, process ID, or process group ID. See F_SETOWN_EX for more details.

      • F_OFD_GETLK - On input to this call, lock describes an open file description lock we would like to place on the file.

        If the lock could be placed, fcntl() does not actually place it, but returns F_UNLCK in the l_type field of lock and leaves the other fields of the structure unchanged. If one or more incompatible locks would prevent this lock being placed, then details about one of these locks are returned via lock, as described above for F_GETLK.

      • F_OFD_SETLK - Acquire an open file description lock (when l_type is F_RDLCK or F_WRLCK) or release an open file description lock (when l_type is F_UNLCK) on the bytes specified by the l_whence, l_start, and l_len fields of lock.

        If a conflicting lock is held by another process, this call returns -1 and sets errno to EAGAIN.

      • F_OFD_SETLKW - As for F_OFD_SETLK, but if a conflicting lock is held on the file, then wait for that lock to be released.

        If a signal is caught while waiting, then the call is interrupted and (after the signal handler has returned) returns immediately (with return value -1 and errno set to EINTR; see signal(7)).

      • F_SETLEASE - Set or remove a file lease according to which of the following values is specified in the integer arg: F_RDLCK, F_WRLCK, F_UNLCK
      • F_GETLEASE - Indicates what type of lease is associated with the file descriptor fd by returning either F_RDLCK, F_WRLCK, or F_UNLCK, indicating, respectively, a read lease, a write lease, or no lease. arg is ignored.
      • F_NOTIFY - (Linux 2.4 onward) Provide notification when the directory referred to by fd or any of the files that it contains is changed.

        The events to be notified are specified in arg, which is a bit mask specified by ORing together zero or more of the following bits: DN_ACCESS, DN_MODIFY, DN_CREATE, DN_DELETE, DN_RENAME, DN_ATTRIB

        (In order to obtain these definitions, the _GNU_SOURCE feature test macro must be defined before including any header files.)

        Directory notifications are normally "one-shot", and the application must reregister to receive further notifications. Alternatively, if DN_MULTISHOT is included in arg, then notification will remain in effect until explicitly removed.

        A series of F_NOTIFY requests is cumulative, with the events in arg being added to the set already monitored. To disable notification of all events, make an F_NOTIFY call specifying arg as 0.

        Notification occurs via delivery of a signal. The default signal is SIGIO, but this can be changed using the F_SETSIG command to fcntl(). (Note that SIGIO is one of the nonqueuing standard signals; switching to the use of a real-time signal means that multiple notifications can be queued to the process.) In the latter case, the signal handler receives a siginfo_t structure as its second argument (if the handler was established using SA_SIGINFO) and the si_fd field of this structure contains the file descriptor which generated the notification (useful when establishing notification on multiple directories).

        Especially when using DN_MULTISHOT, a real time signal should be used for notification, so that multiple notifications can be queued.

        NOTE: New applications should use the inotify interface (available since kernel 2.6.13), which provides a much superior interface for obtaining notifications of filesystem events. See inotify(7).

      • F_SETPIPE_SZ - Change the capacity of the pipe referred to by fd to be at least arg bytes.

        An unprivileged process can adjust the pipe capacity to any value between the system page size and the limit defined in /proc/sys/fs/pipe-max-size (see proc(5)). Attempts to set the pipe capacity below the page size are silently rounded up to the page size. Attempts by an unprivileged process to set the pipe capacity above the limit in /proc/sys/fs/pipe-max-size yield the error EPERM; a privileged process (CAP_SYS_RESOURCE) can override the limit.

        When allocating the buffer for the pipe, the kernel may use a capacity larger than arg, if that is convenient for the implementation. (In the current implementation, the allocation is the next higher power-of-two page-size multiple of the requested size.) The actual capacity (in bytes) that is set is returned as the function result.

        Attempting to set the pipe capacity smaller than the amount of buffer space currently used to store data produces the error EBUSY.

        Note that because of the way the pages of the pipe buffer are employed when data is written to the pipe, the number of bytes that can be written may be less than the nominal size, depending on the size of the writes.

      • F_GETPIPE_SZ - Return (as the function result) the capacity of the pipe referred to by fd.
      • F_ADD_SEALS - Add the seals given in the bit-mask argument arg to the set of seals of the inode referred to by the file descriptor fd.

        Seals cannot be removed again. Once this call succeeds, the seals are enforced by the kernel immediately. If the current set of seals includes F_SEAL_SEAL (see below), then this call will be rejected with EPERM. Adding a seal that is already set is a no-op, in case F_SEAL_SEAL is not set already. In order to place a seal, the file descriptor fd must be writable.

      • F_GET_SEALS - Return (as the function result) the current set of seals of the inode referred to by fd.

        If no seals are set, 0 is returned. If the file does not support sealing, -1 is returned and errno is set to EINVAL.

      • F_GET_RW_HINT - Returns the value of the read/write hint associated with the underlying inode referred to by fd.
      • F_SET_RW_HINT - Sets the read/write hint value associated with the underlying inode referred to by fd.

        This hint persists until either it is explicitly modified or the underlying filesystem is unmounted.

      • F_GET_FILE_RW_HINT - Returns the value of the read/write hint associated with the open file description referred to by fd.
      • F_SET_FILE_RW_HINT - Sets the read/write hint value associated with the open file description referred to by fd.
      • F_DUPFD_CLOEXEC - As for F_DUPFD, but additionally set the close-on-exec flag for the duplicate file descriptor.

        Specifying this flag permits a program to avoid an additional fcntl() F_SETFD operation to set the FD_CLOEXEC flag. For an explanation of why this flag is useful, see the description of O_CLOEXEC in open(2).

      See Also:

    • F_SET_RW_HINT

      public static final int F_SET_RW_HINT
      fcntl(int, int) commands.
      Enum values:
      • F_DUPFD - Duplicate the file descriptor fd using the lowest-numbered available file descriptor greater than or equal to arg.

        This is different from dup2(2), which uses exactly the file descriptor specified.

        On success, the new file descriptor is returned.

        See dup(2) for further details.

      • F_GETFD - Return (as the function result) the file descriptor flags; arg is ignored.
      • F_SETFD - Set the file descriptor flags to the value specified by arg.
      • F_GETFL - Return (as the function result) the file access mode and the file status flags; arg is ignored.
      • F_SETFL - Set the file status flags to the value specified by arg.

        File access mode (O_RDONLY, O_WRONLY, O_RDWR) and file creation flags (i.e., O_CREAT, O_EXCL, O_NOCTTY, O_TRUNC) in arg are ignored. On Linux, this command can change only the O_APPEND, O_ASYNC, O_DIRECT, O_NOATIME, and O_NONBLOCK flags. It is not possible to change the O_DSYNC and O_SYNC flags; see BUGS, below.

      • F_GETLK - On input to this call, lock describes a lock we would like to place on the file.

        If the lock could be placed, fcntl() does not actually place it, but returns F_UNLCK in the l_type field of lock and leaves the other fields of the structure unchanged.

        If one or more incompatible locks would prevent this lock being placed, then fcntl() returns details about one of those locks in the l_type, l_whence, l_start, and l_len fields of lock. If the conflicting lock is a traditional (process-associated) record lock, then the l_pid field is set to the PID of the process holding that lock. If the conflicting lock is an open file description lock, then l_pid is set to -1. Note that the returned information may already be out of date by the time the caller inspects it.

      • F_SETLK - Acquire a lock (when l_type is F_RDLCK or F_WRLCK) or release a lock (when l_type is F_UNLCK) on the bytes specified by the l_whence, l_start, and l_len fields of lock.

        If a conflicting lock is held by another process, this call returns -1 and sets errno to EACCES or EAGAIN. (The error returned in this case differs across implementations, so POSIX requires a portable application to check for both errors.)

      • F_SETLKW - As for F_SETLK, but if a conflicting lock is held on the file, then wait for that lock to be released.

        If a signal is caught while waiting, then the call is interrupted and (after the signal handler has returned) returns immediately (with return value -1 and errno set to EINTR; see signal(7)).

      • F_SETOWN - Set the process ID or process group ID that will receive SIGIO and SIGURG signals for events on the file descriptor fd.

        The target process or process group ID is specified in arg. A process ID is specified as a positive value; a process group ID is specified as a negative value. Most commonly, the calling process specifies itself as the owner (that is, arg is specified as getpid(2)).

        As well as setting the file descriptor owner, one must also enable generation of signals on the file descriptor. This is done by using the fcntl() F_SETFL command to set the O_ASYNC file status flag on the file descriptor. Subsequently, a SIGIO signal is sent whenever input or output becomes possible on the file descriptor. The fcntl() F_SETSIG command can be used to obtain delivery of a signal other than SIGIO.

        Sending a signal to the owner process (group) specified by F_SETOWN is subject to the same permissions checks as are described for kill(2), where the sending process is the one that employs F_SETOWN (but see BUGS below). If this permission check fails, then the signal is silently discarded. Note: The F_SETOWN operation records the caller's credentials at the time of the fcntl() call, and it is these saved credentials that are used for the permission checks.

        If the file descriptor fd refers to a socket, F_SETOWN also selects the recipient of SIGURG signals that are delivered when out-of-band data arrives on that socket. (SIGURG is sent in any situation where select(2) would report the socket as having an "exceptional condition".)

        The following was true in 2.6.x kernels up to and including kernel 2.6.11:

        If a nonzero value is given to F_SETSIG in a multithreaded process running with a threading library that supports thread groups (e.g., NPTL), then a positive value given to F_SETOWN has a different meaning: instead of being a process ID identifying a whole process, it is a thread ID identifying a specific thread within a process. Consequently, it may be necessary to pass F_SETOWN the result of gettid(2) instead of getpid(2) to get sensible results when F_SETSIG is used. (In current Linux threading implementations, a main thread's thread ID is the same as its process ID. This means that a single-threaded program can equally use gettid(2) or getpid(2) in this scenario.) Note, however, that the statements in this paragraph do not apply to the SIGURG signal generated for out-of-band data on a socket: this signal is always sent to either a process or a process group, depending on the value given to F_SETOWN.

        The above behavior was accidentally dropped in Linux 2.6.12, and won't be restored. From Linux 2.6.32 onward, use F_SETOWN_EX to target SIGIO and SIGURG signals at a particular thread.

      • F_GETOWN - Return (as the function result) the process ID or process group ID currently receiving SIGIO and SIGURG signals for events on file descriptor fd.

        Process IDs are returned as positive values; process group IDs are returned as negative values (but see BUGS below). arg is ignored.

      • F_SETSIG - Set the signal sent when input or output becomes possible to the value given in arg.

        A value of zero means to send the default SIGIO signal. Any other value (including SIGIO) is the signal to send instead, and in this case additional info is available to the signal handler if installed with SA_SIGINFO.

        By using F_SETSIG with a nonzero value, and setting SA_SIGINFO for the signal handler (see sigaction(2)), extra information about I/O events is passed to the handler in a siginfo_t structure. If the si_code field indicates the source is SI_SIGIO, the si_fd field gives the file descriptor associated with the event. Otherwise, there is no indication which file descriptors are pending, and you should use the usual mechanisms (select(2), poll(2), read(2) with O_NONBLOCK set etc.) to determine which file descriptors are available for I/O.

        Note that the file descriptor provided in si_fd is the one that was specified during the F_SETSIG operation. This can lead to an unusual corner case. If the file descriptor is duplicated (dup(2) or similar), and the original file descriptor is closed, then I/O events will continue to be generated, but the si_fd field will contain the number of the now closed file descriptor.

        By selecting a real time signal (value ≥ SIGRTMIN), multiple I/O events may be queued using the same signal numbers. (Queuing is dependent on available memory.) Extra information is available if SA_SIGINFO is set for the signal handler, as above.

        Note that Linux imposes a limit on the number of real-time signals that may be queued to a process (see getrlimit(2) and signal(7)) and if this limit is reached, then the kernel reverts to delivering SIGIO, and this signal is delivered to the entire process rather than to a specific thread.

      • F_GETSIG - Return (as the function result) the signal sent when input or output becomes possible.

        A value of zero means SIGIO is sent. Any other value (including SIGIO) is the signal sent instead, and in this case additional info is available to the signal handler if installed with SA_SIGINFO. arg is ignored.

      • F_SETOWN_EX - This operation performs a similar task to F_SETOWN. It allows the caller to direct I/O availability signals to a specific thread, process, or process group.

        The caller specifies the target of signals via arg, which is a pointer to a FOwnerEx structure. The type field has one of the following values, which define how pid is interpreted: F_OWNER_TID, F_OWNER_PID, F_OWNER_PGRP.

      • F_GETOWN_EX - Return the current file descriptor owner settings as defined by a previous F_SETOWN_EX operation.

        The information is returned in the FOwnerEx structure pointed to by arg.

        The type field will have one of the values F_OWNER_TID, F_OWNER_PID, or F_OWNER_PGRP. The pid field is a positive integer representing a thread ID, process ID, or process group ID. See F_SETOWN_EX for more details.

      • F_OFD_GETLK - On input to this call, lock describes an open file description lock we would like to place on the file.

        If the lock could be placed, fcntl() does not actually place it, but returns F_UNLCK in the l_type field of lock and leaves the other fields of the structure unchanged. If one or more incompatible locks would prevent this lock being placed, then details about one of these locks are returned via lock, as described above for F_GETLK.

      • F_OFD_SETLK - Acquire an open file description lock (when l_type is F_RDLCK or F_WRLCK) or release an open file description lock (when l_type is F_UNLCK) on the bytes specified by the l_whence, l_start, and l_len fields of lock.

        If a conflicting lock is held by another process, this call returns -1 and sets errno to EAGAIN.

      • F_OFD_SETLKW - As for F_OFD_SETLK, but if a conflicting lock is held on the file, then wait for that lock to be released.

        If a signal is caught while waiting, then the call is interrupted and (after the signal handler has returned) returns immediately (with return value -1 and errno set to EINTR; see signal(7)).

      • F_SETLEASE - Set or remove a file lease according to which of the following values is specified in the integer arg: F_RDLCK, F_WRLCK, F_UNLCK
      • F_GETLEASE - Indicates what type of lease is associated with the file descriptor fd by returning either F_RDLCK, F_WRLCK, or F_UNLCK, indicating, respectively, a read lease, a write lease, or no lease. arg is ignored.
      • F_NOTIFY - (Linux 2.4 onward) Provide notification when the directory referred to by fd or any of the files that it contains is changed.

        The events to be notified are specified in arg, which is a bit mask specified by ORing together zero or more of the following bits: DN_ACCESS, DN_MODIFY, DN_CREATE, DN_DELETE, DN_RENAME, DN_ATTRIB

        (In order to obtain these definitions, the _GNU_SOURCE feature test macro must be defined before including any header files.)

        Directory notifications are normally "one-shot", and the application must reregister to receive further notifications. Alternatively, if DN_MULTISHOT is included in arg, then notification will remain in effect until explicitly removed.

        A series of F_NOTIFY requests is cumulative, with the events in arg being added to the set already monitored. To disable notification of all events, make an F_NOTIFY call specifying arg as 0.

        Notification occurs via delivery of a signal. The default signal is SIGIO, but this can be changed using the F_SETSIG command to fcntl(). (Note that SIGIO is one of the nonqueuing standard signals; switching to the use of a real-time signal means that multiple notifications can be queued to the process.) In the latter case, the signal handler receives a siginfo_t structure as its second argument (if the handler was established using SA_SIGINFO) and the si_fd field of this structure contains the file descriptor which generated the notification (useful when establishing notification on multiple directories).

        Especially when using DN_MULTISHOT, a real time signal should be used for notification, so that multiple notifications can be queued.

        NOTE: New applications should use the inotify interface (available since kernel 2.6.13), which provides a much superior interface for obtaining notifications of filesystem events. See inotify(7).

      • F_SETPIPE_SZ - Change the capacity of the pipe referred to by fd to be at least arg bytes.

        An unprivileged process can adjust the pipe capacity to any value between the system page size and the limit defined in /proc/sys/fs/pipe-max-size (see proc(5)). Attempts to set the pipe capacity below the page size are silently rounded up to the page size. Attempts by an unprivileged process to set the pipe capacity above the limit in /proc/sys/fs/pipe-max-size yield the error EPERM; a privileged process (CAP_SYS_RESOURCE) can override the limit.

        When allocating the buffer for the pipe, the kernel may use a capacity larger than arg, if that is convenient for the implementation. (In the current implementation, the allocation is the next higher power-of-two page-size multiple of the requested size.) The actual capacity (in bytes) that is set is returned as the function result.

        Attempting to set the pipe capacity smaller than the amount of buffer space currently used to store data produces the error EBUSY.

        Note that because of the way the pages of the pipe buffer are employed when data is written to the pipe, the number of bytes that can be written may be less than the nominal size, depending on the size of the writes.

      • F_GETPIPE_SZ - Return (as the function result) the capacity of the pipe referred to by fd.
      • F_ADD_SEALS - Add the seals given in the bit-mask argument arg to the set of seals of the inode referred to by the file descriptor fd.

        Seals cannot be removed again. Once this call succeeds, the seals are enforced by the kernel immediately. If the current set of seals includes F_SEAL_SEAL (see below), then this call will be rejected with EPERM. Adding a seal that is already set is a no-op, in case F_SEAL_SEAL is not set already. In order to place a seal, the file descriptor fd must be writable.

      • F_GET_SEALS - Return (as the function result) the current set of seals of the inode referred to by fd.

        If no seals are set, 0 is returned. If the file does not support sealing, -1 is returned and errno is set to EINVAL.

      • F_GET_RW_HINT - Returns the value of the read/write hint associated with the underlying inode referred to by fd.
      • F_SET_RW_HINT - Sets the read/write hint value associated with the underlying inode referred to by fd.

        This hint persists until either it is explicitly modified or the underlying filesystem is unmounted.

      • F_GET_FILE_RW_HINT - Returns the value of the read/write hint associated with the open file description referred to by fd.
      • F_SET_FILE_RW_HINT - Sets the read/write hint value associated with the open file description referred to by fd.
      • F_DUPFD_CLOEXEC - As for F_DUPFD, but additionally set the close-on-exec flag for the duplicate file descriptor.

        Specifying this flag permits a program to avoid an additional fcntl() F_SETFD operation to set the FD_CLOEXEC flag. For an explanation of why this flag is useful, see the description of O_CLOEXEC in open(2).

      See Also:

    • F_GET_FILE_RW_HINT

      public static final int F_GET_FILE_RW_HINT
      fcntl(int, int) commands.
      Enum values:
      • F_DUPFD - Duplicate the file descriptor fd using the lowest-numbered available file descriptor greater than or equal to arg.

        This is different from dup2(2), which uses exactly the file descriptor specified.

        On success, the new file descriptor is returned.

        See dup(2) for further details.

      • F_GETFD - Return (as the function result) the file descriptor flags; arg is ignored.
      • F_SETFD - Set the file descriptor flags to the value specified by arg.
      • F_GETFL - Return (as the function result) the file access mode and the file status flags; arg is ignored.
      • F_SETFL - Set the file status flags to the value specified by arg.

        File access mode (O_RDONLY, O_WRONLY, O_RDWR) and file creation flags (i.e., O_CREAT, O_EXCL, O_NOCTTY, O_TRUNC) in arg are ignored. On Linux, this command can change only the O_APPEND, O_ASYNC, O_DIRECT, O_NOATIME, and O_NONBLOCK flags. It is not possible to change the O_DSYNC and O_SYNC flags; see BUGS, below.

      • F_GETLK - On input to this call, lock describes a lock we would like to place on the file.

        If the lock could be placed, fcntl() does not actually place it, but returns F_UNLCK in the l_type field of lock and leaves the other fields of the structure unchanged.

        If one or more incompatible locks would prevent this lock being placed, then fcntl() returns details about one of those locks in the l_type, l_whence, l_start, and l_len fields of lock. If the conflicting lock is a traditional (process-associated) record lock, then the l_pid field is set to the PID of the process holding that lock. If the conflicting lock is an open file description lock, then l_pid is set to -1. Note that the returned information may already be out of date by the time the caller inspects it.

      • F_SETLK - Acquire a lock (when l_type is F_RDLCK or F_WRLCK) or release a lock (when l_type is F_UNLCK) on the bytes specified by the l_whence, l_start, and l_len fields of lock.

        If a conflicting lock is held by another process, this call returns -1 and sets errno to EACCES or EAGAIN. (The error returned in this case differs across implementations, so POSIX requires a portable application to check for both errors.)

      • F_SETLKW - As for F_SETLK, but if a conflicting lock is held on the file, then wait for that lock to be released.

        If a signal is caught while waiting, then the call is interrupted and (after the signal handler has returned) returns immediately (with return value -1 and errno set to EINTR; see signal(7)).

      • F_SETOWN - Set the process ID or process group ID that will receive SIGIO and SIGURG signals for events on the file descriptor fd.

        The target process or process group ID is specified in arg. A process ID is specified as a positive value; a process group ID is specified as a negative value. Most commonly, the calling process specifies itself as the owner (that is, arg is specified as getpid(2)).

        As well as setting the file descriptor owner, one must also enable generation of signals on the file descriptor. This is done by using the fcntl() F_SETFL command to set the O_ASYNC file status flag on the file descriptor. Subsequently, a SIGIO signal is sent whenever input or output becomes possible on the file descriptor. The fcntl() F_SETSIG command can be used to obtain delivery of a signal other than SIGIO.

        Sending a signal to the owner process (group) specified by F_SETOWN is subject to the same permissions checks as are described for kill(2), where the sending process is the one that employs F_SETOWN (but see BUGS below). If this permission check fails, then the signal is silently discarded. Note: The F_SETOWN operation records the caller's credentials at the time of the fcntl() call, and it is these saved credentials that are used for the permission checks.

        If the file descriptor fd refers to a socket, F_SETOWN also selects the recipient of SIGURG signals that are delivered when out-of-band data arrives on that socket. (SIGURG is sent in any situation where select(2) would report the socket as having an "exceptional condition".)

        The following was true in 2.6.x kernels up to and including kernel 2.6.11:

        If a nonzero value is given to F_SETSIG in a multithreaded process running with a threading library that supports thread groups (e.g., NPTL), then a positive value given to F_SETOWN has a different meaning: instead of being a process ID identifying a whole process, it is a thread ID identifying a specific thread within a process. Consequently, it may be necessary to pass F_SETOWN the result of gettid(2) instead of getpid(2) to get sensible results when F_SETSIG is used. (In current Linux threading implementations, a main thread's thread ID is the same as its process ID. This means that a single-threaded program can equally use gettid(2) or getpid(2) in this scenario.) Note, however, that the statements in this paragraph do not apply to the SIGURG signal generated for out-of-band data on a socket: this signal is always sent to either a process or a process group, depending on the value given to F_SETOWN.

        The above behavior was accidentally dropped in Linux 2.6.12, and won't be restored. From Linux 2.6.32 onward, use F_SETOWN_EX to target SIGIO and SIGURG signals at a particular thread.

      • F_GETOWN - Return (as the function result) the process ID or process group ID currently receiving SIGIO and SIGURG signals for events on file descriptor fd.

        Process IDs are returned as positive values; process group IDs are returned as negative values (but see BUGS below). arg is ignored.

      • F_SETSIG - Set the signal sent when input or output becomes possible to the value given in arg.

        A value of zero means to send the default SIGIO signal. Any other value (including SIGIO) is the signal to send instead, and in this case additional info is available to the signal handler if installed with SA_SIGINFO.

        By using F_SETSIG with a nonzero value, and setting SA_SIGINFO for the signal handler (see sigaction(2)), extra information about I/O events is passed to the handler in a siginfo_t structure. If the si_code field indicates the source is SI_SIGIO, the si_fd field gives the file descriptor associated with the event. Otherwise, there is no indication which file descriptors are pending, and you should use the usual mechanisms (select(2), poll(2), read(2) with O_NONBLOCK set etc.) to determine which file descriptors are available for I/O.

        Note that the file descriptor provided in si_fd is the one that was specified during the F_SETSIG operation. This can lead to an unusual corner case. If the file descriptor is duplicated (dup(2) or similar), and the original file descriptor is closed, then I/O events will continue to be generated, but the si_fd field will contain the number of the now closed file descriptor.

        By selecting a real time signal (value ≥ SIGRTMIN), multiple I/O events may be queued using the same signal numbers. (Queuing is dependent on available memory.) Extra information is available if SA_SIGINFO is set for the signal handler, as above.

        Note that Linux imposes a limit on the number of real-time signals that may be queued to a process (see getrlimit(2) and signal(7)) and if this limit is reached, then the kernel reverts to delivering SIGIO, and this signal is delivered to the entire process rather than to a specific thread.

      • F_GETSIG - Return (as the function result) the signal sent when input or output becomes possible.

        A value of zero means SIGIO is sent. Any other value (including SIGIO) is the signal sent instead, and in this case additional info is available to the signal handler if installed with SA_SIGINFO. arg is ignored.

      • F_SETOWN_EX - This operation performs a similar task to F_SETOWN. It allows the caller to direct I/O availability signals to a specific thread, process, or process group.

        The caller specifies the target of signals via arg, which is a pointer to a FOwnerEx structure. The type field has one of the following values, which define how pid is interpreted: F_OWNER_TID, F_OWNER_PID, F_OWNER_PGRP.

      • F_GETOWN_EX - Return the current file descriptor owner settings as defined by a previous F_SETOWN_EX operation.

        The information is returned in the FOwnerEx structure pointed to by arg.

        The type field will have one of the values F_OWNER_TID, F_OWNER_PID, or F_OWNER_PGRP. The pid field is a positive integer representing a thread ID, process ID, or process group ID. See F_SETOWN_EX for more details.

      • F_OFD_GETLK - On input to this call, lock describes an open file description lock we would like to place on the file.

        If the lock could be placed, fcntl() does not actually place it, but returns F_UNLCK in the l_type field of lock and leaves the other fields of the structure unchanged. If one or more incompatible locks would prevent this lock being placed, then details about one of these locks are returned via lock, as described above for F_GETLK.

      • F_OFD_SETLK - Acquire an open file description lock (when l_type is F_RDLCK or F_WRLCK) or release an open file description lock (when l_type is F_UNLCK) on the bytes specified by the l_whence, l_start, and l_len fields of lock.

        If a conflicting lock is held by another process, this call returns -1 and sets errno to EAGAIN.

      • F_OFD_SETLKW - As for F_OFD_SETLK, but if a conflicting lock is held on the file, then wait for that lock to be released.

        If a signal is caught while waiting, then the call is interrupted and (after the signal handler has returned) returns immediately (with return value -1 and errno set to EINTR; see signal(7)).

      • F_SETLEASE - Set or remove a file lease according to which of the following values is specified in the integer arg: F_RDLCK, F_WRLCK, F_UNLCK
      • F_GETLEASE - Indicates what type of lease is associated with the file descriptor fd by returning either F_RDLCK, F_WRLCK, or F_UNLCK, indicating, respectively, a read lease, a write lease, or no lease. arg is ignored.
      • F_NOTIFY - (Linux 2.4 onward) Provide notification when the directory referred to by fd or any of the files that it contains is changed.

        The events to be notified are specified in arg, which is a bit mask specified by ORing together zero or more of the following bits: DN_ACCESS, DN_MODIFY, DN_CREATE, DN_DELETE, DN_RENAME, DN_ATTRIB

        (In order to obtain these definitions, the _GNU_SOURCE feature test macro must be defined before including any header files.)

        Directory notifications are normally "one-shot", and the application must reregister to receive further notifications. Alternatively, if DN_MULTISHOT is included in arg, then notification will remain in effect until explicitly removed.

        A series of F_NOTIFY requests is cumulative, with the events in arg being added to the set already monitored. To disable notification of all events, make an F_NOTIFY call specifying arg as 0.

        Notification occurs via delivery of a signal. The default signal is SIGIO, but this can be changed using the F_SETSIG command to fcntl(). (Note that SIGIO is one of the nonqueuing standard signals; switching to the use of a real-time signal means that multiple notifications can be queued to the process.) In the latter case, the signal handler receives a siginfo_t structure as its second argument (if the handler was established using SA_SIGINFO) and the si_fd field of this structure contains the file descriptor which generated the notification (useful when establishing notification on multiple directories).

        Especially when using DN_MULTISHOT, a real time signal should be used for notification, so that multiple notifications can be queued.

        NOTE: New applications should use the inotify interface (available since kernel 2.6.13), which provides a much superior interface for obtaining notifications of filesystem events. See inotify(7).

      • F_SETPIPE_SZ - Change the capacity of the pipe referred to by fd to be at least arg bytes.

        An unprivileged process can adjust the pipe capacity to any value between the system page size and the limit defined in /proc/sys/fs/pipe-max-size (see proc(5)). Attempts to set the pipe capacity below the page size are silently rounded up to the page size. Attempts by an unprivileged process to set the pipe capacity above the limit in /proc/sys/fs/pipe-max-size yield the error EPERM; a privileged process (CAP_SYS_RESOURCE) can override the limit.

        When allocating the buffer for the pipe, the kernel may use a capacity larger than arg, if that is convenient for the implementation. (In the current implementation, the allocation is the next higher power-of-two page-size multiple of the requested size.) The actual capacity (in bytes) that is set is returned as the function result.

        Attempting to set the pipe capacity smaller than the amount of buffer space currently used to store data produces the error EBUSY.

        Note that because of the way the pages of the pipe buffer are employed when data is written to the pipe, the number of bytes that can be written may be less than the nominal size, depending on the size of the writes.

      • F_GETPIPE_SZ - Return (as the function result) the capacity of the pipe referred to by fd.
      • F_ADD_SEALS - Add the seals given in the bit-mask argument arg to the set of seals of the inode referred to by the file descriptor fd.

        Seals cannot be removed again. Once this call succeeds, the seals are enforced by the kernel immediately. If the current set of seals includes F_SEAL_SEAL (see below), then this call will be rejected with EPERM. Adding a seal that is already set is a no-op, in case F_SEAL_SEAL is not set already. In order to place a seal, the file descriptor fd must be writable.

      • F_GET_SEALS - Return (as the function result) the current set of seals of the inode referred to by fd.

        If no seals are set, 0 is returned. If the file does not support sealing, -1 is returned and errno is set to EINVAL.

      • F_GET_RW_HINT - Returns the value of the read/write hint associated with the underlying inode referred to by fd.
      • F_SET_RW_HINT - Sets the read/write hint value associated with the underlying inode referred to by fd.

        This hint persists until either it is explicitly modified or the underlying filesystem is unmounted.

      • F_GET_FILE_RW_HINT - Returns the value of the read/write hint associated with the open file description referred to by fd.
      • F_SET_FILE_RW_HINT - Sets the read/write hint value associated with the open file description referred to by fd.
      • F_DUPFD_CLOEXEC - As for F_DUPFD, but additionally set the close-on-exec flag for the duplicate file descriptor.

        Specifying this flag permits a program to avoid an additional fcntl() F_SETFD operation to set the FD_CLOEXEC flag. For an explanation of why this flag is useful, see the description of O_CLOEXEC in open(2).

      See Also:

    • F_SET_FILE_RW_HINT

      public static final int F_SET_FILE_RW_HINT
      fcntl(int, int) commands.
      Enum values:
      • F_DUPFD - Duplicate the file descriptor fd using the lowest-numbered available file descriptor greater than or equal to arg.

        This is different from dup2(2), which uses exactly the file descriptor specified.

        On success, the new file descriptor is returned.

        See dup(2) for further details.

      • F_GETFD - Return (as the function result) the file descriptor flags; arg is ignored.
      • F_SETFD - Set the file descriptor flags to the value specified by arg.
      • F_GETFL - Return (as the function result) the file access mode and the file status flags; arg is ignored.
      • F_SETFL - Set the file status flags to the value specified by arg.

        File access mode (O_RDONLY, O_WRONLY, O_RDWR) and file creation flags (i.e., O_CREAT, O_EXCL, O_NOCTTY, O_TRUNC) in arg are ignored. On Linux, this command can change only the O_APPEND, O_ASYNC, O_DIRECT, O_NOATIME, and O_NONBLOCK flags. It is not possible to change the O_DSYNC and O_SYNC flags; see BUGS, below.

      • F_GETLK - On input to this call, lock describes a lock we would like to place on the file.

        If the lock could be placed, fcntl() does not actually place it, but returns F_UNLCK in the l_type field of lock and leaves the other fields of the structure unchanged.

        If one or more incompatible locks would prevent this lock being placed, then fcntl() returns details about one of those locks in the l_type, l_whence, l_start, and l_len fields of lock. If the conflicting lock is a traditional (process-associated) record lock, then the l_pid field is set to the PID of the process holding that lock. If the conflicting lock is an open file description lock, then l_pid is set to -1. Note that the returned information may already be out of date by the time the caller inspects it.

      • F_SETLK - Acquire a lock (when l_type is F_RDLCK or F_WRLCK) or release a lock (when l_type is F_UNLCK) on the bytes specified by the l_whence, l_start, and l_len fields of lock.

        If a conflicting lock is held by another process, this call returns -1 and sets errno to EACCES or EAGAIN. (The error returned in this case differs across implementations, so POSIX requires a portable application to check for both errors.)

      • F_SETLKW - As for F_SETLK, but if a conflicting lock is held on the file, then wait for that lock to be released.

        If a signal is caught while waiting, then the call is interrupted and (after the signal handler has returned) returns immediately (with return value -1 and errno set to EINTR; see signal(7)).

      • F_SETOWN - Set the process ID or process group ID that will receive SIGIO and SIGURG signals for events on the file descriptor fd.

        The target process or process group ID is specified in arg. A process ID is specified as a positive value; a process group ID is specified as a negative value. Most commonly, the calling process specifies itself as the owner (that is, arg is specified as getpid(2)).

        As well as setting the file descriptor owner, one must also enable generation of signals on the file descriptor. This is done by using the fcntl() F_SETFL command to set the O_ASYNC file status flag on the file descriptor. Subsequently, a SIGIO signal is sent whenever input or output becomes possible on the file descriptor. The fcntl() F_SETSIG command can be used to obtain delivery of a signal other than SIGIO.

        Sending a signal to the owner process (group) specified by F_SETOWN is subject to the same permissions checks as are described for kill(2), where the sending process is the one that employs F_SETOWN (but see BUGS below). If this permission check fails, then the signal is silently discarded. Note: The F_SETOWN operation records the caller's credentials at the time of the fcntl() call, and it is these saved credentials that are used for the permission checks.

        If the file descriptor fd refers to a socket, F_SETOWN also selects the recipient of SIGURG signals that are delivered when out-of-band data arrives on that socket. (SIGURG is sent in any situation where select(2) would report the socket as having an "exceptional condition".)

        The following was true in 2.6.x kernels up to and including kernel 2.6.11:

        If a nonzero value is given to F_SETSIG in a multithreaded process running with a threading library that supports thread groups (e.g., NPTL), then a positive value given to F_SETOWN has a different meaning: instead of being a process ID identifying a whole process, it is a thread ID identifying a specific thread within a process. Consequently, it may be necessary to pass F_SETOWN the result of gettid(2) instead of getpid(2) to get sensible results when F_SETSIG is used. (In current Linux threading implementations, a main thread's thread ID is the same as its process ID. This means that a single-threaded program can equally use gettid(2) or getpid(2) in this scenario.) Note, however, that the statements in this paragraph do not apply to the SIGURG signal generated for out-of-band data on a socket: this signal is always sent to either a process or a process group, depending on the value given to F_SETOWN.

        The above behavior was accidentally dropped in Linux 2.6.12, and won't be restored. From Linux 2.6.32 onward, use F_SETOWN_EX to target SIGIO and SIGURG signals at a particular thread.

      • F_GETOWN - Return (as the function result) the process ID or process group ID currently receiving SIGIO and SIGURG signals for events on file descriptor fd.

        Process IDs are returned as positive values; process group IDs are returned as negative values (but see BUGS below). arg is ignored.

      • F_SETSIG - Set the signal sent when input or output becomes possible to the value given in arg.

        A value of zero means to send the default SIGIO signal. Any other value (including SIGIO) is the signal to send instead, and in this case additional info is available to the signal handler if installed with SA_SIGINFO.

        By using F_SETSIG with a nonzero value, and setting SA_SIGINFO for the signal handler (see sigaction(2)), extra information about I/O events is passed to the handler in a siginfo_t structure. If the si_code field indicates the source is SI_SIGIO, the si_fd field gives the file descriptor associated with the event. Otherwise, there is no indication which file descriptors are pending, and you should use the usual mechanisms (select(2), poll(2), read(2) with O_NONBLOCK set etc.) to determine which file descriptors are available for I/O.

        Note that the file descriptor provided in si_fd is the one that was specified during the F_SETSIG operation. This can lead to an unusual corner case. If the file descriptor is duplicated (dup(2) or similar), and the original file descriptor is closed, then I/O events will continue to be generated, but the si_fd field will contain the number of the now closed file descriptor.

        By selecting a real time signal (value ≥ SIGRTMIN), multiple I/O events may be queued using the same signal numbers. (Queuing is dependent on available memory.) Extra information is available if SA_SIGINFO is set for the signal handler, as above.

        Note that Linux imposes a limit on the number of real-time signals that may be queued to a process (see getrlimit(2) and signal(7)) and if this limit is reached, then the kernel reverts to delivering SIGIO, and this signal is delivered to the entire process rather than to a specific thread.

      • F_GETSIG - Return (as the function result) the signal sent when input or output becomes possible.

        A value of zero means SIGIO is sent. Any other value (including SIGIO) is the signal sent instead, and in this case additional info is available to the signal handler if installed with SA_SIGINFO. arg is ignored.

      • F_SETOWN_EX - This operation performs a similar task to F_SETOWN. It allows the caller to direct I/O availability signals to a specific thread, process, or process group.

        The caller specifies the target of signals via arg, which is a pointer to a FOwnerEx structure. The type field has one of the following values, which define how pid is interpreted: F_OWNER_TID, F_OWNER_PID, F_OWNER_PGRP.

      • F_GETOWN_EX - Return the current file descriptor owner settings as defined by a previous F_SETOWN_EX operation.

        The information is returned in the FOwnerEx structure pointed to by arg.

        The type field will have one of the values F_OWNER_TID, F_OWNER_PID, or F_OWNER_PGRP. The pid field is a positive integer representing a thread ID, process ID, or process group ID. See F_SETOWN_EX for more details.

      • F_OFD_GETLK - On input to this call, lock describes an open file description lock we would like to place on the file.

        If the lock could be placed, fcntl() does not actually place it, but returns F_UNLCK in the l_type field of lock and leaves the other fields of the structure unchanged. If one or more incompatible locks would prevent this lock being placed, then details about one of these locks are returned via lock, as described above for F_GETLK.

      • F_OFD_SETLK - Acquire an open file description lock (when l_type is F_RDLCK or F_WRLCK) or release an open file description lock (when l_type is F_UNLCK) on the bytes specified by the l_whence, l_start, and l_len fields of lock.

        If a conflicting lock is held by another process, this call returns -1 and sets errno to EAGAIN.

      • F_OFD_SETLKW - As for F_OFD_SETLK, but if a conflicting lock is held on the file, then wait for that lock to be released.

        If a signal is caught while waiting, then the call is interrupted and (after the signal handler has returned) returns immediately (with return value -1 and errno set to EINTR; see signal(7)).

      • F_SETLEASE - Set or remove a file lease according to which of the following values is specified in the integer arg: F_RDLCK, F_WRLCK, F_UNLCK
      • F_GETLEASE - Indicates what type of lease is associated with the file descriptor fd by returning either F_RDLCK, F_WRLCK, or F_UNLCK, indicating, respectively, a read lease, a write lease, or no lease. arg is ignored.
      • F_NOTIFY - (Linux 2.4 onward) Provide notification when the directory referred to by fd or any of the files that it contains is changed.

        The events to be notified are specified in arg, which is a bit mask specified by ORing together zero or more of the following bits: DN_ACCESS, DN_MODIFY, DN_CREATE, DN_DELETE, DN_RENAME, DN_ATTRIB

        (In order to obtain these definitions, the _GNU_SOURCE feature test macro must be defined before including any header files.)

        Directory notifications are normally "one-shot", and the application must reregister to receive further notifications. Alternatively, if DN_MULTISHOT is included in arg, then notification will remain in effect until explicitly removed.

        A series of F_NOTIFY requests is cumulative, with the events in arg being added to the set already monitored. To disable notification of all events, make an F_NOTIFY call specifying arg as 0.

        Notification occurs via delivery of a signal. The default signal is SIGIO, but this can be changed using the F_SETSIG command to fcntl(). (Note that SIGIO is one of the nonqueuing standard signals; switching to the use of a real-time signal means that multiple notifications can be queued to the process.) In the latter case, the signal handler receives a siginfo_t structure as its second argument (if the handler was established using SA_SIGINFO) and the si_fd field of this structure contains the file descriptor which generated the notification (useful when establishing notification on multiple directories).

        Especially when using DN_MULTISHOT, a real time signal should be used for notification, so that multiple notifications can be queued.

        NOTE: New applications should use the inotify interface (available since kernel 2.6.13), which provides a much superior interface for obtaining notifications of filesystem events. See inotify(7).

      • F_SETPIPE_SZ - Change the capacity of the pipe referred to by fd to be at least arg bytes.

        An unprivileged process can adjust the pipe capacity to any value between the system page size and the limit defined in /proc/sys/fs/pipe-max-size (see proc(5)). Attempts to set the pipe capacity below the page size are silently rounded up to the page size. Attempts by an unprivileged process to set the pipe capacity above the limit in /proc/sys/fs/pipe-max-size yield the error EPERM; a privileged process (CAP_SYS_RESOURCE) can override the limit.

        When allocating the buffer for the pipe, the kernel may use a capacity larger than arg, if that is convenient for the implementation. (In the current implementation, the allocation is the next higher power-of-two page-size multiple of the requested size.) The actual capacity (in bytes) that is set is returned as the function result.

        Attempting to set the pipe capacity smaller than the amount of buffer space currently used to store data produces the error EBUSY.

        Note that because of the way the pages of the pipe buffer are employed when data is written to the pipe, the number of bytes that can be written may be less than the nominal size, depending on the size of the writes.

      • F_GETPIPE_SZ - Return (as the function result) the capacity of the pipe referred to by fd.
      • F_ADD_SEALS - Add the seals given in the bit-mask argument arg to the set of seals of the inode referred to by the file descriptor fd.

        Seals cannot be removed again. Once this call succeeds, the seals are enforced by the kernel immediately. If the current set of seals includes F_SEAL_SEAL (see below), then this call will be rejected with EPERM. Adding a seal that is already set is a no-op, in case F_SEAL_SEAL is not set already. In order to place a seal, the file descriptor fd must be writable.

      • F_GET_SEALS - Return (as the function result) the current set of seals of the inode referred to by fd.

        If no seals are set, 0 is returned. If the file does not support sealing, -1 is returned and errno is set to EINVAL.

      • F_GET_RW_HINT - Returns the value of the read/write hint associated with the underlying inode referred to by fd.
      • F_SET_RW_HINT - Sets the read/write hint value associated with the underlying inode referred to by fd.

        This hint persists until either it is explicitly modified or the underlying filesystem is unmounted.

      • F_GET_FILE_RW_HINT - Returns the value of the read/write hint associated with the open file description referred to by fd.
      • F_SET_FILE_RW_HINT - Sets the read/write hint value associated with the open file description referred to by fd.
      • F_DUPFD_CLOEXEC - As for F_DUPFD, but additionally set the close-on-exec flag for the duplicate file descriptor.

        Specifying this flag permits a program to avoid an additional fcntl() F_SETFD operation to set the FD_CLOEXEC flag. For an explanation of why this flag is useful, see the description of O_CLOEXEC in open(2).

      See Also:

    • F_DUPFD_CLOEXEC

      public static final int F_DUPFD_CLOEXEC
      fcntl(int, int) commands.
      Enum values:
      • F_DUPFD - Duplicate the file descriptor fd using the lowest-numbered available file descriptor greater than or equal to arg.

        This is different from dup2(2), which uses exactly the file descriptor specified.

        On success, the new file descriptor is returned.

        See dup(2) for further details.

      • F_GETFD - Return (as the function result) the file descriptor flags; arg is ignored.
      • F_SETFD - Set the file descriptor flags to the value specified by arg.
      • F_GETFL - Return (as the function result) the file access mode and the file status flags; arg is ignored.
      • F_SETFL - Set the file status flags to the value specified by arg.

        File access mode (O_RDONLY, O_WRONLY, O_RDWR) and file creation flags (i.e., O_CREAT, O_EXCL, O_NOCTTY, O_TRUNC) in arg are ignored. On Linux, this command can change only the O_APPEND, O_ASYNC, O_DIRECT, O_NOATIME, and O_NONBLOCK flags. It is not possible to change the O_DSYNC and O_SYNC flags; see BUGS, below.

      • F_GETLK - On input to this call, lock describes a lock we would like to place on the file.

        If the lock could be placed, fcntl() does not actually place it, but returns F_UNLCK in the l_type field of lock and leaves the other fields of the structure unchanged.

        If one or more incompatible locks would prevent this lock being placed, then fcntl() returns details about one of those locks in the l_type, l_whence, l_start, and l_len fields of lock. If the conflicting lock is a traditional (process-associated) record lock, then the l_pid field is set to the PID of the process holding that lock. If the conflicting lock is an open file description lock, then l_pid is set to -1. Note that the returned information may already be out of date by the time the caller inspects it.

      • F_SETLK - Acquire a lock (when l_type is F_RDLCK or F_WRLCK) or release a lock (when l_type is F_UNLCK) on the bytes specified by the l_whence, l_start, and l_len fields of lock.

        If a conflicting lock is held by another process, this call returns -1 and sets errno to EACCES or EAGAIN. (The error returned in this case differs across implementations, so POSIX requires a portable application to check for both errors.)

      • F_SETLKW - As for F_SETLK, but if a conflicting lock is held on the file, then wait for that lock to be released.

        If a signal is caught while waiting, then the call is interrupted and (after the signal handler has returned) returns immediately (with return value -1 and errno set to EINTR; see signal(7)).

      • F_SETOWN - Set the process ID or process group ID that will receive SIGIO and SIGURG signals for events on the file descriptor fd.

        The target process or process group ID is specified in arg. A process ID is specified as a positive value; a process group ID is specified as a negative value. Most commonly, the calling process specifies itself as the owner (that is, arg is specified as getpid(2)).

        As well as setting the file descriptor owner, one must also enable generation of signals on the file descriptor. This is done by using the fcntl() F_SETFL command to set the O_ASYNC file status flag on the file descriptor. Subsequently, a SIGIO signal is sent whenever input or output becomes possible on the file descriptor. The fcntl() F_SETSIG command can be used to obtain delivery of a signal other than SIGIO.

        Sending a signal to the owner process (group) specified by F_SETOWN is subject to the same permissions checks as are described for kill(2), where the sending process is the one that employs F_SETOWN (but see BUGS below). If this permission check fails, then the signal is silently discarded. Note: The F_SETOWN operation records the caller's credentials at the time of the fcntl() call, and it is these saved credentials that are used for the permission checks.

        If the file descriptor fd refers to a socket, F_SETOWN also selects the recipient of SIGURG signals that are delivered when out-of-band data arrives on that socket. (SIGURG is sent in any situation where select(2) would report the socket as having an "exceptional condition".)

        The following was true in 2.6.x kernels up to and including kernel 2.6.11:

        If a nonzero value is given to F_SETSIG in a multithreaded process running with a threading library that supports thread groups (e.g., NPTL), then a positive value given to F_SETOWN has a different meaning: instead of being a process ID identifying a whole process, it is a thread ID identifying a specific thread within a process. Consequently, it may be necessary to pass F_SETOWN the result of gettid(2) instead of getpid(2) to get sensible results when F_SETSIG is used. (In current Linux threading implementations, a main thread's thread ID is the same as its process ID. This means that a single-threaded program can equally use gettid(2) or getpid(2) in this scenario.) Note, however, that the statements in this paragraph do not apply to the SIGURG signal generated for out-of-band data on a socket: this signal is always sent to either a process or a process group, depending on the value given to F_SETOWN.

        The above behavior was accidentally dropped in Linux 2.6.12, and won't be restored. From Linux 2.6.32 onward, use F_SETOWN_EX to target SIGIO and SIGURG signals at a particular thread.

      • F_GETOWN - Return (as the function result) the process ID or process group ID currently receiving SIGIO and SIGURG signals for events on file descriptor fd.

        Process IDs are returned as positive values; process group IDs are returned as negative values (but see BUGS below). arg is ignored.

      • F_SETSIG - Set the signal sent when input or output becomes possible to the value given in arg.

        A value of zero means to send the default SIGIO signal. Any other value (including SIGIO) is the signal to send instead, and in this case additional info is available to the signal handler if installed with SA_SIGINFO.

        By using F_SETSIG with a nonzero value, and setting SA_SIGINFO for the signal handler (see sigaction(2)), extra information about I/O events is passed to the handler in a siginfo_t structure. If the si_code field indicates the source is SI_SIGIO, the si_fd field gives the file descriptor associated with the event. Otherwise, there is no indication which file descriptors are pending, and you should use the usual mechanisms (select(2), poll(2), read(2) with O_NONBLOCK set etc.) to determine which file descriptors are available for I/O.

        Note that the file descriptor provided in si_fd is the one that was specified during the F_SETSIG operation. This can lead to an unusual corner case. If the file descriptor is duplicated (dup(2) or similar), and the original file descriptor is closed, then I/O events will continue to be generated, but the si_fd field will contain the number of the now closed file descriptor.

        By selecting a real time signal (value ≥ SIGRTMIN), multiple I/O events may be queued using the same signal numbers. (Queuing is dependent on available memory.) Extra information is available if SA_SIGINFO is set for the signal handler, as above.

        Note that Linux imposes a limit on the number of real-time signals that may be queued to a process (see getrlimit(2) and signal(7)) and if this limit is reached, then the kernel reverts to delivering SIGIO, and this signal is delivered to the entire process rather than to a specific thread.

      • F_GETSIG - Return (as the function result) the signal sent when input or output becomes possible.

        A value of zero means SIGIO is sent. Any other value (including SIGIO) is the signal sent instead, and in this case additional info is available to the signal handler if installed with SA_SIGINFO. arg is ignored.

      • F_SETOWN_EX - This operation performs a similar task to F_SETOWN. It allows the caller to direct I/O availability signals to a specific thread, process, or process group.

        The caller specifies the target of signals via arg, which is a pointer to a FOwnerEx structure. The type field has one of the following values, which define how pid is interpreted: F_OWNER_TID, F_OWNER_PID, F_OWNER_PGRP.

      • F_GETOWN_EX - Return the current file descriptor owner settings as defined by a previous F_SETOWN_EX operation.

        The information is returned in the FOwnerEx structure pointed to by arg.

        The type field will have one of the values F_OWNER_TID, F_OWNER_PID, or F_OWNER_PGRP. The pid field is a positive integer representing a thread ID, process ID, or process group ID. See F_SETOWN_EX for more details.

      • F_OFD_GETLK - On input to this call, lock describes an open file description lock we would like to place on the file.

        If the lock could be placed, fcntl() does not actually place it, but returns F_UNLCK in the l_type field of lock and leaves the other fields of the structure unchanged. If one or more incompatible locks would prevent this lock being placed, then details about one of these locks are returned via lock, as described above for F_GETLK.

      • F_OFD_SETLK - Acquire an open file description lock (when l_type is F_RDLCK or F_WRLCK) or release an open file description lock (when l_type is F_UNLCK) on the bytes specified by the l_whence, l_start, and l_len fields of lock.

        If a conflicting lock is held by another process, this call returns -1 and sets errno to EAGAIN.

      • F_OFD_SETLKW - As for F_OFD_SETLK, but if a conflicting lock is held on the file, then wait for that lock to be released.

        If a signal is caught while waiting, then the call is interrupted and (after the signal handler has returned) returns immediately (with return value -1 and errno set to EINTR; see signal(7)).

      • F_SETLEASE - Set or remove a file lease according to which of the following values is specified in the integer arg: F_RDLCK, F_WRLCK, F_UNLCK
      • F_GETLEASE - Indicates what type of lease is associated with the file descriptor fd by returning either F_RDLCK, F_WRLCK, or F_UNLCK, indicating, respectively, a read lease, a write lease, or no lease. arg is ignored.
      • F_NOTIFY - (Linux 2.4 onward) Provide notification when the directory referred to by fd or any of the files that it contains is changed.

        The events to be notified are specified in arg, which is a bit mask specified by ORing together zero or more of the following bits: DN_ACCESS, DN_MODIFY, DN_CREATE, DN_DELETE, DN_RENAME, DN_ATTRIB

        (In order to obtain these definitions, the _GNU_SOURCE feature test macro must be defined before including any header files.)

        Directory notifications are normally "one-shot", and the application must reregister to receive further notifications. Alternatively, if DN_MULTISHOT is included in arg, then notification will remain in effect until explicitly removed.

        A series of F_NOTIFY requests is cumulative, with the events in arg being added to the set already monitored. To disable notification of all events, make an F_NOTIFY call specifying arg as 0.

        Notification occurs via delivery of a signal. The default signal is SIGIO, but this can be changed using the F_SETSIG command to fcntl(). (Note that SIGIO is one of the nonqueuing standard signals; switching to the use of a real-time signal means that multiple notifications can be queued to the process.) In the latter case, the signal handler receives a siginfo_t structure as its second argument (if the handler was established using SA_SIGINFO) and the si_fd field of this structure contains the file descriptor which generated the notification (useful when establishing notification on multiple directories).

        Especially when using DN_MULTISHOT, a real time signal should be used for notification, so that multiple notifications can be queued.

        NOTE: New applications should use the inotify interface (available since kernel 2.6.13), which provides a much superior interface for obtaining notifications of filesystem events. See inotify(7).

      • F_SETPIPE_SZ - Change the capacity of the pipe referred to by fd to be at least arg bytes.

        An unprivileged process can adjust the pipe capacity to any value between the system page size and the limit defined in /proc/sys/fs/pipe-max-size (see proc(5)). Attempts to set the pipe capacity below the page size are silently rounded up to the page size. Attempts by an unprivileged process to set the pipe capacity above the limit in /proc/sys/fs/pipe-max-size yield the error EPERM; a privileged process (CAP_SYS_RESOURCE) can override the limit.

        When allocating the buffer for the pipe, the kernel may use a capacity larger than arg, if that is convenient for the implementation. (In the current implementation, the allocation is the next higher power-of-two page-size multiple of the requested size.) The actual capacity (in bytes) that is set is returned as the function result.

        Attempting to set the pipe capacity smaller than the amount of buffer space currently used to store data produces the error EBUSY.

        Note that because of the way the pages of the pipe buffer are employed when data is written to the pipe, the number of bytes that can be written may be less than the nominal size, depending on the size of the writes.

      • F_GETPIPE_SZ - Return (as the function result) the capacity of the pipe referred to by fd.
      • F_ADD_SEALS - Add the seals given in the bit-mask argument arg to the set of seals of the inode referred to by the file descriptor fd.

        Seals cannot be removed again. Once this call succeeds, the seals are enforced by the kernel immediately. If the current set of seals includes F_SEAL_SEAL (see below), then this call will be rejected with EPERM. Adding a seal that is already set is a no-op, in case F_SEAL_SEAL is not set already. In order to place a seal, the file descriptor fd must be writable.

      • F_GET_SEALS - Return (as the function result) the current set of seals of the inode referred to by fd.

        If no seals are set, 0 is returned. If the file does not support sealing, -1 is returned and errno is set to EINVAL.

      • F_GET_RW_HINT - Returns the value of the read/write hint associated with the underlying inode referred to by fd.
      • F_SET_RW_HINT - Sets the read/write hint value associated with the underlying inode referred to by fd.

        This hint persists until either it is explicitly modified or the underlying filesystem is unmounted.

      • F_GET_FILE_RW_HINT - Returns the value of the read/write hint associated with the open file description referred to by fd.
      • F_SET_FILE_RW_HINT - Sets the read/write hint value associated with the open file description referred to by fd.
      • F_DUPFD_CLOEXEC - As for F_DUPFD, but additionally set the close-on-exec flag for the duplicate file descriptor.

        Specifying this flag permits a program to avoid an additional fcntl() F_SETFD operation to set the FD_CLOEXEC flag. For an explanation of why this flag is useful, see the description of O_CLOEXEC in open(2).

      See Also:

    • FD_CLOEXEC

      public static final int FD_CLOEXEC
      See Also:

    • F_RDLCK

      public static final int F_RDLCK
      For posix fcntl(int, int) and l_type field of an Flock for lockf().
      Enum values:
      • F_RDLCK - Take out a read lease.

        This will cause the calling process to be notified when the file is opened for writing or is truncated. A read lease can be placed only on a file descriptor that is opened read-only.

      • F_WRLCK - Take out a write lease.

        This will cause the caller to be notified when the file is opened for reading or writing or is truncated. A write lease may be placed on a file only if there are no other open file descriptors for the file.

      • F_UNLCK - Remove our lease from the file.
      • F_EXLCK
      • F_SHLCK
      See Also:

    • F_WRLCK

      public static final int F_WRLCK
      For posix fcntl(int, int) and l_type field of an Flock for lockf().
      Enum values:
      • F_RDLCK - Take out a read lease.

        This will cause the calling process to be notified when the file is opened for writing or is truncated. A read lease can be placed only on a file descriptor that is opened read-only.

      • F_WRLCK - Take out a write lease.

        This will cause the caller to be notified when the file is opened for reading or writing or is truncated. A write lease may be placed on a file only if there are no other open file descriptors for the file.

      • F_UNLCK - Remove our lease from the file.
      • F_EXLCK
      • F_SHLCK
      See Also:

    • F_UNLCK

      public static final int F_UNLCK
      For posix fcntl(int, int) and l_type field of an Flock for lockf().
      Enum values:
      • F_RDLCK - Take out a read lease.

        This will cause the calling process to be notified when the file is opened for writing or is truncated. A read lease can be placed only on a file descriptor that is opened read-only.

      • F_WRLCK - Take out a write lease.

        This will cause the caller to be notified when the file is opened for reading or writing or is truncated. A write lease may be placed on a file only if there are no other open file descriptors for the file.

      • F_UNLCK - Remove our lease from the file.
      • F_EXLCK
      • F_SHLCK
      See Also:

    • F_EXLCK

      public static final int F_EXLCK
      For posix fcntl(int, int) and l_type field of an Flock for lockf().
      Enum values:
      • F_RDLCK - Take out a read lease.

        This will cause the calling process to be notified when the file is opened for writing or is truncated. A read lease can be placed only on a file descriptor that is opened read-only.

      • F_WRLCK - Take out a write lease.

        This will cause the caller to be notified when the file is opened for reading or writing or is truncated. A write lease may be placed on a file only if there are no other open file descriptors for the file.

      • F_UNLCK - Remove our lease from the file.
      • F_EXLCK
      • F_SHLCK
      See Also:

    • F_SHLCK

      public static final int F_SHLCK
      For posix fcntl(int, int) and l_type field of an Flock for lockf().
      Enum values:
      • F_RDLCK - Take out a read lease.

        This will cause the calling process to be notified when the file is opened for writing or is truncated. A read lease can be placed only on a file descriptor that is opened read-only.

      • F_WRLCK - Take out a write lease.

        This will cause the caller to be notified when the file is opened for reading or writing or is truncated. A write lease may be placed on a file only if there are no other open file descriptors for the file.

      • F_UNLCK - Remove our lease from the file.
      • F_EXLCK
      • F_SHLCK
      See Also:

    • F_OWNER_TID

      public static final int F_OWNER_TID
      FOwnerEx::type values.
      Enum values:
      • F_OWNER_TID - Send the signal to the thread whose thread ID (the value returned by a call to clone(2) or gettid(2)) is specified in pid.
      • F_OWNER_PID - Send the signal to the process whose ID is specified in pid.
      • F_OWNER_PGRP - Send the signal to the process group whose ID is specified in pid.

        (Note that, unlike with F_SETOWN, a process group ID is specified as a positive value here.)

      See Also:

    • F_OWNER_PID

      public static final int F_OWNER_PID
      FOwnerEx::type values.
      Enum values:
      • F_OWNER_TID - Send the signal to the thread whose thread ID (the value returned by a call to clone(2) or gettid(2)) is specified in pid.
      • F_OWNER_PID - Send the signal to the process whose ID is specified in pid.
      • F_OWNER_PGRP - Send the signal to the process group whose ID is specified in pid.

        (Note that, unlike with F_SETOWN, a process group ID is specified as a positive value here.)

      See Also:

    • F_OWNER_PGRP

      public static final int F_OWNER_PGRP
      FOwnerEx::type values.
      Enum values:
      • F_OWNER_TID - Send the signal to the thread whose thread ID (the value returned by a call to clone(2) or gettid(2)) is specified in pid.
      • F_OWNER_PID - Send the signal to the process whose ID is specified in pid.
      • F_OWNER_PGRP - Send the signal to the process group whose ID is specified in pid.

        (Note that, unlike with F_SETOWN, a process group ID is specified as a positive value here.)

      See Also:

    • LOCK_SH

      public static final int LOCK_SH
      Enum values:
      • LOCK_SH - shared lock
      • LOCK_EX - exclusive lock
      • LOCK_NB - or'd with one of the above to prevent blocking
      • LOCK_UN - remove lock
      • LOCK_MAND - This is a mandatory flock...
      • LOCK_READ - which allows concurrent read operations
      • LOCK_WRITE - which allows concurrent write operations
      • LOCK_RW - which allows concurrent read & writes ops
      See Also:

    • LOCK_EX

      public static final int LOCK_EX
      Enum values:
      • LOCK_SH - shared lock
      • LOCK_EX - exclusive lock
      • LOCK_NB - or'd with one of the above to prevent blocking
      • LOCK_UN - remove lock
      • LOCK_MAND - This is a mandatory flock...
      • LOCK_READ - which allows concurrent read operations
      • LOCK_WRITE - which allows concurrent write operations
      • LOCK_RW - which allows concurrent read & writes ops
      See Also:

    • LOCK_NB

      public static final int LOCK_NB
      Enum values:
      • LOCK_SH - shared lock
      • LOCK_EX - exclusive lock
      • LOCK_NB - or'd with one of the above to prevent blocking
      • LOCK_UN - remove lock
      • LOCK_MAND - This is a mandatory flock...
      • LOCK_READ - which allows concurrent read operations
      • LOCK_WRITE - which allows concurrent write operations
      • LOCK_RW - which allows concurrent read & writes ops
      See Also:

    • LOCK_UN

      public static final int LOCK_UN
      Enum values:
      • LOCK_SH - shared lock
      • LOCK_EX - exclusive lock
      • LOCK_NB - or'd with one of the above to prevent blocking
      • LOCK_UN - remove lock
      • LOCK_MAND - This is a mandatory flock...
      • LOCK_READ - which allows concurrent read operations
      • LOCK_WRITE - which allows concurrent write operations
      • LOCK_RW - which allows concurrent read & writes ops
      See Also:

    • LOCK_MAND

      public static final int LOCK_MAND
      Enum values:
      • LOCK_SH - shared lock
      • LOCK_EX - exclusive lock
      • LOCK_NB - or'd with one of the above to prevent blocking
      • LOCK_UN - remove lock
      • LOCK_MAND - This is a mandatory flock...
      • LOCK_READ - which allows concurrent read operations
      • LOCK_WRITE - which allows concurrent write operations
      • LOCK_RW - which allows concurrent read & writes ops
      See Also:

    • LOCK_READ

      public static final int LOCK_READ
      Enum values:
      • LOCK_SH - shared lock
      • LOCK_EX - exclusive lock
      • LOCK_NB - or'd with one of the above to prevent blocking
      • LOCK_UN - remove lock
      • LOCK_MAND - This is a mandatory flock...
      • LOCK_READ - which allows concurrent read operations
      • LOCK_WRITE - which allows concurrent write operations
      • LOCK_RW - which allows concurrent read & writes ops
      See Also:

    • LOCK_WRITE

      public static final int LOCK_WRITE
      Enum values:
      • LOCK_SH - shared lock
      • LOCK_EX - exclusive lock
      • LOCK_NB - or'd with one of the above to prevent blocking
      • LOCK_UN - remove lock
      • LOCK_MAND - This is a mandatory flock...
      • LOCK_READ - which allows concurrent read operations
      • LOCK_WRITE - which allows concurrent write operations
      • LOCK_RW - which allows concurrent read & writes ops
      See Also:

    • LOCK_RW

      public static final int LOCK_RW
      Enum values:
      • LOCK_SH - shared lock
      • LOCK_EX - exclusive lock
      • LOCK_NB - or'd with one of the above to prevent blocking
      • LOCK_UN - remove lock
      • LOCK_MAND - This is a mandatory flock...
      • LOCK_READ - which allows concurrent read operations
      • LOCK_WRITE - which allows concurrent write operations
      • LOCK_RW - which allows concurrent read & writes ops
      See Also:

    • DN_ACCESS

      public static final int DN_ACCESS
      Enum values:
      • DN_ACCESS - A file was accessed (read(2), pread(2), readv(2), and similar).
      • DN_MODIFY - A file was modified (write(2), pwrite(2), writev(2), truncate(2), ftruncate(2), and similar).
      • DN_CREATE - A file was created (open(2), creat(2), mknod(2), mkdir(2), link(2), symlink(2), rename(2) into this directory).
      • DN_DELETE - A file was unlinked (unlink(2), rename(2) to another directory, rmdir(2)).
      • DN_RENAME - A file was renamed within this directory (rename(2)).
      • DN_ATTRIB - The attributes of a file were changed (chown(2), chmod(2), utime(2), utimensat(2), and similar).
      • DN_MULTISHOT - Don't remove notifier
      See Also:

    • DN_MODIFY

      public static final int DN_MODIFY
      Enum values:
      • DN_ACCESS - A file was accessed (read(2), pread(2), readv(2), and similar).
      • DN_MODIFY - A file was modified (write(2), pwrite(2), writev(2), truncate(2), ftruncate(2), and similar).
      • DN_CREATE - A file was created (open(2), creat(2), mknod(2), mkdir(2), link(2), symlink(2), rename(2) into this directory).
      • DN_DELETE - A file was unlinked (unlink(2), rename(2) to another directory, rmdir(2)).
      • DN_RENAME - A file was renamed within this directory (rename(2)).
      • DN_ATTRIB - The attributes of a file were changed (chown(2), chmod(2), utime(2), utimensat(2), and similar).
      • DN_MULTISHOT - Don't remove notifier
      See Also:

    • DN_CREATE

      public static final int DN_CREATE
      Enum values:
      • DN_ACCESS - A file was accessed (read(2), pread(2), readv(2), and similar).
      • DN_MODIFY - A file was modified (write(2), pwrite(2), writev(2), truncate(2), ftruncate(2), and similar).
      • DN_CREATE - A file was created (open(2), creat(2), mknod(2), mkdir(2), link(2), symlink(2), rename(2) into this directory).
      • DN_DELETE - A file was unlinked (unlink(2), rename(2) to another directory, rmdir(2)).
      • DN_RENAME - A file was renamed within this directory (rename(2)).
      • DN_ATTRIB - The attributes of a file were changed (chown(2), chmod(2), utime(2), utimensat(2), and similar).
      • DN_MULTISHOT - Don't remove notifier
      See Also:

    • DN_DELETE

      public static final int DN_DELETE
      Enum values:
      • DN_ACCESS - A file was accessed (read(2), pread(2), readv(2), and similar).
      • DN_MODIFY - A file was modified (write(2), pwrite(2), writev(2), truncate(2), ftruncate(2), and similar).
      • DN_CREATE - A file was created (open(2), creat(2), mknod(2), mkdir(2), link(2), symlink(2), rename(2) into this directory).
      • DN_DELETE - A file was unlinked (unlink(2), rename(2) to another directory, rmdir(2)).
      • DN_RENAME - A file was renamed within this directory (rename(2)).
      • DN_ATTRIB - The attributes of a file were changed (chown(2), chmod(2), utime(2), utimensat(2), and similar).
      • DN_MULTISHOT - Don't remove notifier
      See Also:

    • DN_RENAME

      public static final int DN_RENAME
      Enum values:
      • DN_ACCESS - A file was accessed (read(2), pread(2), readv(2), and similar).
      • DN_MODIFY - A file was modified (write(2), pwrite(2), writev(2), truncate(2), ftruncate(2), and similar).
      • DN_CREATE - A file was created (open(2), creat(2), mknod(2), mkdir(2), link(2), symlink(2), rename(2) into this directory).
      • DN_DELETE - A file was unlinked (unlink(2), rename(2) to another directory, rmdir(2)).
      • DN_RENAME - A file was renamed within this directory (rename(2)).
      • DN_ATTRIB - The attributes of a file were changed (chown(2), chmod(2), utime(2), utimensat(2), and similar).
      • DN_MULTISHOT - Don't remove notifier
      See Also:

    • DN_ATTRIB

      public static final int DN_ATTRIB
      Enum values:
      • DN_ACCESS - A file was accessed (read(2), pread(2), readv(2), and similar).
      • DN_MODIFY - A file was modified (write(2), pwrite(2), writev(2), truncate(2), ftruncate(2), and similar).
      • DN_CREATE - A file was created (open(2), creat(2), mknod(2), mkdir(2), link(2), symlink(2), rename(2) into this directory).
      • DN_DELETE - A file was unlinked (unlink(2), rename(2) to another directory, rmdir(2)).
      • DN_RENAME - A file was renamed within this directory (rename(2)).
      • DN_ATTRIB - The attributes of a file were changed (chown(2), chmod(2), utime(2), utimensat(2), and similar).
      • DN_MULTISHOT - Don't remove notifier
      See Also:

    • DN_MULTISHOT

      public static final int DN_MULTISHOT
      Enum values:
      • DN_ACCESS - A file was accessed (read(2), pread(2), readv(2), and similar).
      • DN_MODIFY - A file was modified (write(2), pwrite(2), writev(2), truncate(2), ftruncate(2), and similar).
      • DN_CREATE - A file was created (open(2), creat(2), mknod(2), mkdir(2), link(2), symlink(2), rename(2) into this directory).
      • DN_DELETE - A file was unlinked (unlink(2), rename(2) to another directory, rmdir(2)).
      • DN_RENAME - A file was renamed within this directory (rename(2)).
      • DN_ATTRIB - The attributes of a file were changed (chown(2), chmod(2), utime(2), utimensat(2), and similar).
      • DN_MULTISHOT - Don't remove notifier
      See Also:

    • F_SEAL_SEAL

      public static final int F_SEAL_SEAL
      Enum values:
      • F_SEAL_SEAL - If this seal is set, any further call to fcntl() with F_ADD_SEALS fails with the error EPERM.

        Therefore, this seal prevents any modifications to the set of seals itself. If the initial set of seals of a file includes F_SEAL_SEAL, then this effectively causes the set of seals to be constant and locked.

      • F_SEAL_SHRINK - If this seal is set, the file in question cannot be reduced in size.

        This affects open(2) with the O_TRUNC flag as well as truncate(2) and ftruncate(2). Those calls fail with EPERM if you try to shrink the file in question. Increasing the file size is still possible.

      • F_SEAL_GROW - If this seal is set, the size of the file in question cannot be increased.

        This affects write(2) beyond the end of the file, truncate(2), ftruncate(2), and fallocate(2). These calls fail with EPERM if you use them to increase the file size. If you keep the size or shrink it, those calls still work as expected.

      • F_SEAL_WRITE - If this seal is set, you cannot modify the contents of the file.

        Note that shrinking or growing the size of the file is still possible and allowed. Thus, this seal is normally used in combination with one of the other seals. This seal affects write(2) and fallocate(2) (only in combination with the FALLOC_FL_PUNCH_HOLE flag). Those calls fail with EPERM if this seal is set. Furthermore, trying to create new shared, writable memory-mappings via mmap(2) will also fail with EPERM.

        Using the F_ADD_SEALS operation to set the F_SEAL_WRITE seal fails with EBUSY if any writable, shared mapping exists. Such mappings must be unmapped before you can add this seal. Furthermore, if there are any asynchronous I/O operations (io_submit(2)) pending on the file, all outstanding writes will be discarded.

      • F_SEAL_FUTURE_WRITE - The effect of this seal is similar to F_SEAL_WRITE, but the contents of the file can still be modified via shared writable mappings that were created prior to the seal being set.

        Any attempt to create a new writable mapping on the file via mmap(2) will fail with EPERM. Likewise, an attempt to write to the file via write(2) will fail with EPERM.

        Using this seal, one process can create a memory buffer that it can continue to modify while sharing that buffer on a "read-only" basis with other processes.

        (since Linux 5.1)

      See Also:

    • F_SEAL_SHRINK

      public static final int F_SEAL_SHRINK
      Enum values:
      • F_SEAL_SEAL - If this seal is set, any further call to fcntl() with F_ADD_SEALS fails with the error EPERM.

        Therefore, this seal prevents any modifications to the set of seals itself. If the initial set of seals of a file includes F_SEAL_SEAL, then this effectively causes the set of seals to be constant and locked.

      • F_SEAL_SHRINK - If this seal is set, the file in question cannot be reduced in size.

        This affects open(2) with the O_TRUNC flag as well as truncate(2) and ftruncate(2). Those calls fail with EPERM if you try to shrink the file in question. Increasing the file size is still possible.

      • F_SEAL_GROW - If this seal is set, the size of the file in question cannot be increased.

        This affects write(2) beyond the end of the file, truncate(2), ftruncate(2), and fallocate(2). These calls fail with EPERM if you use them to increase the file size. If you keep the size or shrink it, those calls still work as expected.

      • F_SEAL_WRITE - If this seal is set, you cannot modify the contents of the file.

        Note that shrinking or growing the size of the file is still possible and allowed. Thus, this seal is normally used in combination with one of the other seals. This seal affects write(2) and fallocate(2) (only in combination with the FALLOC_FL_PUNCH_HOLE flag). Those calls fail with EPERM if this seal is set. Furthermore, trying to create new shared, writable memory-mappings via mmap(2) will also fail with EPERM.

        Using the F_ADD_SEALS operation to set the F_SEAL_WRITE seal fails with EBUSY if any writable, shared mapping exists. Such mappings must be unmapped before you can add this seal. Furthermore, if there are any asynchronous I/O operations (io_submit(2)) pending on the file, all outstanding writes will be discarded.

      • F_SEAL_FUTURE_WRITE - The effect of this seal is similar to F_SEAL_WRITE, but the contents of the file can still be modified via shared writable mappings that were created prior to the seal being set.

        Any attempt to create a new writable mapping on the file via mmap(2) will fail with EPERM. Likewise, an attempt to write to the file via write(2) will fail with EPERM.

        Using this seal, one process can create a memory buffer that it can continue to modify while sharing that buffer on a "read-only" basis with other processes.

        (since Linux 5.1)

      See Also:

    • F_SEAL_GROW

      public static final int F_SEAL_GROW
      Enum values:
      • F_SEAL_SEAL - If this seal is set, any further call to fcntl() with F_ADD_SEALS fails with the error EPERM.

        Therefore, this seal prevents any modifications to the set of seals itself. If the initial set of seals of a file includes F_SEAL_SEAL, then this effectively causes the set of seals to be constant and locked.

      • F_SEAL_SHRINK - If this seal is set, the file in question cannot be reduced in size.

        This affects open(2) with the O_TRUNC flag as well as truncate(2) and ftruncate(2). Those calls fail with EPERM if you try to shrink the file in question. Increasing the file size is still possible.

      • F_SEAL_GROW - If this seal is set, the size of the file in question cannot be increased.

        This affects write(2) beyond the end of the file, truncate(2), ftruncate(2), and fallocate(2). These calls fail with EPERM if you use them to increase the file size. If you keep the size or shrink it, those calls still work as expected.

      • F_SEAL_WRITE - If this seal is set, you cannot modify the contents of the file.

        Note that shrinking or growing the size of the file is still possible and allowed. Thus, this seal is normally used in combination with one of the other seals. This seal affects write(2) and fallocate(2) (only in combination with the FALLOC_FL_PUNCH_HOLE flag). Those calls fail with EPERM if this seal is set. Furthermore, trying to create new shared, writable memory-mappings via mmap(2) will also fail with EPERM.

        Using the F_ADD_SEALS operation to set the F_SEAL_WRITE seal fails with EBUSY if any writable, shared mapping exists. Such mappings must be unmapped before you can add this seal. Furthermore, if there are any asynchronous I/O operations (io_submit(2)) pending on the file, all outstanding writes will be discarded.

      • F_SEAL_FUTURE_WRITE - The effect of this seal is similar to F_SEAL_WRITE, but the contents of the file can still be modified via shared writable mappings that were created prior to the seal being set.

        Any attempt to create a new writable mapping on the file via mmap(2) will fail with EPERM. Likewise, an attempt to write to the file via write(2) will fail with EPERM.

        Using this seal, one process can create a memory buffer that it can continue to modify while sharing that buffer on a "read-only" basis with other processes.

        (since Linux 5.1)

      See Also:

    • F_SEAL_WRITE

      public static final int F_SEAL_WRITE
      Enum values:
      • F_SEAL_SEAL - If this seal is set, any further call to fcntl() with F_ADD_SEALS fails with the error EPERM.

        Therefore, this seal prevents any modifications to the set of seals itself. If the initial set of seals of a file includes F_SEAL_SEAL, then this effectively causes the set of seals to be constant and locked.

      • F_SEAL_SHRINK - If this seal is set, the file in question cannot be reduced in size.

        This affects open(2) with the O_TRUNC flag as well as truncate(2) and ftruncate(2). Those calls fail with EPERM if you try to shrink the file in question. Increasing the file size is still possible.

      • F_SEAL_GROW - If this seal is set, the size of the file in question cannot be increased.

        This affects write(2) beyond the end of the file, truncate(2), ftruncate(2), and fallocate(2). These calls fail with EPERM if you use them to increase the file size. If you keep the size or shrink it, those calls still work as expected.

      • F_SEAL_WRITE - If this seal is set, you cannot modify the contents of the file.

        Note that shrinking or growing the size of the file is still possible and allowed. Thus, this seal is normally used in combination with one of the other seals. This seal affects write(2) and fallocate(2) (only in combination with the FALLOC_FL_PUNCH_HOLE flag). Those calls fail with EPERM if this seal is set. Furthermore, trying to create new shared, writable memory-mappings via mmap(2) will also fail with EPERM.

        Using the F_ADD_SEALS operation to set the F_SEAL_WRITE seal fails with EBUSY if any writable, shared mapping exists. Such mappings must be unmapped before you can add this seal. Furthermore, if there are any asynchronous I/O operations (io_submit(2)) pending on the file, all outstanding writes will be discarded.

      • F_SEAL_FUTURE_WRITE - The effect of this seal is similar to F_SEAL_WRITE, but the contents of the file can still be modified via shared writable mappings that were created prior to the seal being set.

        Any attempt to create a new writable mapping on the file via mmap(2) will fail with EPERM. Likewise, an attempt to write to the file via write(2) will fail with EPERM.

        Using this seal, one process can create a memory buffer that it can continue to modify while sharing that buffer on a "read-only" basis with other processes.

        (since Linux 5.1)

      See Also:

    • F_SEAL_FUTURE_WRITE

      public static final int F_SEAL_FUTURE_WRITE
      Enum values:
      • F_SEAL_SEAL - If this seal is set, any further call to fcntl() with F_ADD_SEALS fails with the error EPERM.

        Therefore, this seal prevents any modifications to the set of seals itself. If the initial set of seals of a file includes F_SEAL_SEAL, then this effectively causes the set of seals to be constant and locked.

      • F_SEAL_SHRINK - If this seal is set, the file in question cannot be reduced in size.

        This affects open(2) with the O_TRUNC flag as well as truncate(2) and ftruncate(2). Those calls fail with EPERM if you try to shrink the file in question. Increasing the file size is still possible.

      • F_SEAL_GROW - If this seal is set, the size of the file in question cannot be increased.

        This affects write(2) beyond the end of the file, truncate(2), ftruncate(2), and fallocate(2). These calls fail with EPERM if you use them to increase the file size. If you keep the size or shrink it, those calls still work as expected.

      • F_SEAL_WRITE - If this seal is set, you cannot modify the contents of the file.

        Note that shrinking or growing the size of the file is still possible and allowed. Thus, this seal is normally used in combination with one of the other seals. This seal affects write(2) and fallocate(2) (only in combination with the FALLOC_FL_PUNCH_HOLE flag). Those calls fail with EPERM if this seal is set. Furthermore, trying to create new shared, writable memory-mappings via mmap(2) will also fail with EPERM.

        Using the F_ADD_SEALS operation to set the F_SEAL_WRITE seal fails with EBUSY if any writable, shared mapping exists. Such mappings must be unmapped before you can add this seal. Furthermore, if there are any asynchronous I/O operations (io_submit(2)) pending on the file, all outstanding writes will be discarded.

      • F_SEAL_FUTURE_WRITE - The effect of this seal is similar to F_SEAL_WRITE, but the contents of the file can still be modified via shared writable mappings that were created prior to the seal being set.

        Any attempt to create a new writable mapping on the file via mmap(2) will fail with EPERM. Likewise, an attempt to write to the file via write(2) will fail with EPERM.

        Using this seal, one process can create a memory buffer that it can continue to modify while sharing that buffer on a "read-only" basis with other processes.

        (since Linux 5.1)

      See Also:

    • RWH_WRITE_LIFE_NOT_SET

      public static final int RWH_WRITE_LIFE_NOT_SET
      Enum values:
      See Also:

    • RWH_WRITE_LIFE_NONE

      public static final int RWH_WRITE_LIFE_NONE
      Enum values:
      See Also:

    • RWH_WRITE_LIFE_SHORT

      public static final int RWH_WRITE_LIFE_SHORT
      Enum values:
      See Also:

    • RWH_WRITE_LIFE_MEDIUM

      public static final int RWH_WRITE_LIFE_MEDIUM
      Enum values:
      See Also:

    • RWH_WRITE_LIFE_LONG

      public static final int RWH_WRITE_LIFE_LONG
      Enum values:
      See Also:

    • RWH_WRITE_LIFE_EXTREME

      public static final int RWH_WRITE_LIFE_EXTREME
      Enum values:
      See Also:

  • Method Details