Class FCNTL
-
Field Summary
Modifier and TypeFieldDescriptionstatic final int
Enum values:static final int
Enum values:static final int
Enum values:static final int
Enum values:static final int
Enum values:static final int
Enum values:static final int
Enum values:static final int
fcntl(int, int)
commands.static final int
fcntl(int, int)
commands.static final int
fcntl(int, int)
commands.static final int
static final int
fcntl(int, int)
commands.static final int
fcntl(int, int)
commands.static final int
fcntl(int, int)
commands.static final int
fcntl(int, int)
commands.static final int
fcntl(int, int)
commands.static final int
fcntl(int, int)
commands.static final int
fcntl(int, int)
commands.static final int
fcntl(int, int)
commands.static final int
fcntl(int, int)
commands.static final int
fcntl(int, int)
commands.static final int
fcntl(int, int)
commands.static final int
fcntl(int, int)
commands.static final int
fcntl(int, int)
commands.static final int
fcntl(int, int)
commands.static final int
fcntl(int, int)
commands.static final int
FOwnerEx
::type
values.static final int
FOwnerEx
::type
values.static final int
FOwnerEx
::type
values.static final int
static final int
Enum values:static final int
Enum values:static final int
Enum values:static final int
Enum values:static final int
Enum values:static final int
fcntl(int, int)
commands.static final int
fcntl(int, int)
commands.static final int
fcntl(int, int)
commands.static final int
fcntl(int, int)
commands.static final int
fcntl(int, int)
commands.static final int
fcntl(int, int)
commands.static final int
fcntl(int, int)
commands.static final int
fcntl(int, int)
commands.static final int
fcntl(int, int)
commands.static final int
fcntl(int, int)
commands.static final int
fcntl(int, int)
commands.static final int
static final int
static final int
static final int
static final int
Enum values:static final int
Enum values:static final int
Enum values:static final int
Enum values:static final int
Enum values:static final int
Enum values:static final int
Enum values:static final int
Enum values:static final int
Enum values:static final int
Enum values:static final int
Enum values:static final int
Enum values:static final int
Enum values:static final int
Enum values:static final int
Enum values:static final int
Enum values:static final int
Enum values:static final int
Enum values:static final int
Enum values:static final int
Enum values:static final int
Enum values:static final int
Enum values:static final int
Enum values:static final int
Enum values:static final int
Enum values:static final int
Enum values:static final int
Enum values:static final int
Enum values:static final int
Enum values:static final int
Enum values:static final int
Enum values:static final int
Enum values:static final int
Enum values:static final int
Enum values:static final int
Enum values:static final int
Enum values:static final int
File types encoded in typemode_t
.static final int
File types encoded in typemode_t
.static final int
File types encoded in typemode_t
.static final int
File types encoded in typemode_t
.static final int
File types encoded in typemode_t
.static final int
File types encoded in typemode_t
.static final int
File types encoded in typemode_t
.static final int
File types encoded in typemode_t
.static final int
File mode bits encoded in typemode_t
.static final int
File mode bits encoded in typemode_t
.static final int
File mode bits encoded in typemode_t
.static final int
File mode bits encoded in typemode_t
.static final int
File mode bits encoded in typemode_t
.static final int
File mode bits encoded in typemode_t
.static final int
File mode bits encoded in typemode_t
.static final int
File mode bits encoded in typemode_t
.static final int
File mode bits encoded in typemode_t
.static final int
File mode bits encoded in typemode_t
.static final int
File mode bits encoded in typemode_t
.static final int
File mode bits encoded in typemode_t
.static final int
File mode bits encoded in typemode_t
.static final int
File mode bits encoded in typemode_t
.static final int
File mode bits encoded in typemode_t
. -
Method Summary
Modifier and TypeMethodDescriptionstatic int
creat
(CharSequence pathname, int mode) Equivalent toopen()
withflags
equal toO_CREAT|O_WRONLY|O_TRUNC
.static int
creat
(ByteBuffer pathname, int mode) Equivalent toopen()
withflags
equal toO_CREAT|O_WRONLY|O_TRUNC
.static int
fcntl
(int fd, int cmd) Performs one of the operations determined bycmd
on the open file descriptorfd
.static int
fcntli
(int fd, int cmd, int arg) fcntl(int, int)
overload that takes a third argument of typeint
.static int
fcntlp
(int fd, int cmd, long arg) fcntl(int, int)
overload that takes a third argument of typevoid *
.static int
ncreat
(long pathname, int mode) Unsafe version of:creat(java.nio.ByteBuffer, int)
static int
nfcntli
(int fd, int cmd, int arg) Unsafe version of:fcntli(int, int, int)
static int
nfcntlp
(int fd, int cmd, long arg) Unsafe version of:fcntlp(int, int, long)
static int
nopen
(long pathname, int flags, int mode) Unsafe version of:open(java.nio.ByteBuffer, int, int)
static int
nopenat
(int dirfd, long pathname, int flags, int mode) Unsafe version of:openat(int, java.nio.ByteBuffer, int, int)
static int
open
(CharSequence pathname, int flags, int mode) Given apathname
for a file,open()
returns a file descriptor, a small, nonnegative integer for use in subsequent system calls (read(2)
,write(2)
,lseek(2)
,fcntl(2)
, etc.).static int
open
(ByteBuffer pathname, int flags, int mode) Given apathname
for a file,open()
returns a file descriptor, a small, nonnegative integer for use in subsequent system calls (read(2)
,write(2)
,lseek(2)
,fcntl(2)
, etc.).static int
openat
(int dirfd, CharSequence pathname, int flags, int mode) Theopenat()
system call operates in exactly the same way asopen(2)
, except for the differences described in this manual page.static int
openat
(int dirfd, ByteBuffer pathname, int flags, int mode) Theopenat()
system call operates in exactly the same way asopen(2)
, except for the differences described in this manual page.
-
Field Details
-
O_ACCMODE
public static final int O_ACCMODEEnum 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 withlseek(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 viafcntl(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 theFD_CLOEXEC
flag. Additionally, use of this flag is essential in some multithreaded programs since using a separatefcntl(2) F_SETFD
operation to set theFD_CLOEXEC
flag does not suffice to avoid race conditions where one thread opens a file descriptor at the same time as another thread does afork(2)
plusexecve(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
andsysvgroups
described inmount(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 theO_SYNC
flag that data and necessary metadata are transferred. To guarantee synchronous I/O,O_SYNC
must be used in addition toO_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 ofopendir(3)
.O_DSYNC
O_EXCL
- Ensure that this call creates the file: if this flag is specified in conjunction withO_CREAT
, and pathname already exists, thenopen()
will fail.When these two flags are specified, symbolic links are not followed: if
pathname
is a symbolic link, thenopen()
fails regardless of where the symbolic link points to.In general, the behavior of
O_EXCL
is undefined if it is used withoutO_CREAT
. There is one exception: on Linux 2.6 and later,O_EXCL
can be used withoutO_CREAT
ifpathname
refers to a block device. If the block device is in use by the system (e.g., mounted),open()
fails with the errorEBUSY
.On NFS,
O_EXCL
is only supported when using NFSv3 or later on kernel 2.6 or later. In NFS environments whereO_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 forO_EXCL
, can create a unique file on the same file system (e.g., incorporating hostname and PID), and uselink(2)
to make a link to the lockfile. Iflink(2)
returns 0, the lock is successful. Otherwise, usestat(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 anoff_t
(but can be represented in anoff64_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 usingO_LARGEFILE
) is the preferred method of accessing large files on 32-bit systems (seefeature_test_macros(7)
).O_NOATIME
- Do not update the file last access time (st_atime
in theinode
) when the file isread(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
- Ifpathname
refers to a terminal device --seetty(4)
-- it will not become the process's controlling terminal even if the process does not have one.O_NOFOLLOW
- Ifpathname
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 alsofifo(7)
. For a discussion of the effect ofO_NONBLOCK
in conjunction with mandatory file locks and with file leases, seefcntl(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., isO_RDWR
orO_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 ofO_TRUNC
is unspecified.
- See Also:
-
O_RDONLY
public static final int O_RDONLYEnum 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 withlseek(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 viafcntl(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 theFD_CLOEXEC
flag. Additionally, use of this flag is essential in some multithreaded programs since using a separatefcntl(2) F_SETFD
operation to set theFD_CLOEXEC
flag does not suffice to avoid race conditions where one thread opens a file descriptor at the same time as another thread does afork(2)
plusexecve(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
andsysvgroups
described inmount(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 theO_SYNC
flag that data and necessary metadata are transferred. To guarantee synchronous I/O,O_SYNC
must be used in addition toO_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 ofopendir(3)
.O_DSYNC
O_EXCL
- Ensure that this call creates the file: if this flag is specified in conjunction withO_CREAT
, and pathname already exists, thenopen()
will fail.When these two flags are specified, symbolic links are not followed: if
pathname
is a symbolic link, thenopen()
fails regardless of where the symbolic link points to.In general, the behavior of
O_EXCL
is undefined if it is used withoutO_CREAT
. There is one exception: on Linux 2.6 and later,O_EXCL
can be used withoutO_CREAT
ifpathname
refers to a block device. If the block device is in use by the system (e.g., mounted),open()
fails with the errorEBUSY
.On NFS,
O_EXCL
is only supported when using NFSv3 or later on kernel 2.6 or later. In NFS environments whereO_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 forO_EXCL
, can create a unique file on the same file system (e.g., incorporating hostname and PID), and uselink(2)
to make a link to the lockfile. Iflink(2)
returns 0, the lock is successful. Otherwise, usestat(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 anoff_t
(but can be represented in anoff64_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 usingO_LARGEFILE
) is the preferred method of accessing large files on 32-bit systems (seefeature_test_macros(7)
).O_NOATIME
- Do not update the file last access time (st_atime
in theinode
) when the file isread(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
- Ifpathname
refers to a terminal device --seetty(4)
-- it will not become the process's controlling terminal even if the process does not have one.O_NOFOLLOW
- Ifpathname
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 alsofifo(7)
. For a discussion of the effect ofO_NONBLOCK
in conjunction with mandatory file locks and with file leases, seefcntl(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., isO_RDWR
orO_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 ofO_TRUNC
is unspecified.
- See Also:
-
O_WRONLY
public static final int O_WRONLYEnum 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 withlseek(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 viafcntl(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 theFD_CLOEXEC
flag. Additionally, use of this flag is essential in some multithreaded programs since using a separatefcntl(2) F_SETFD
operation to set theFD_CLOEXEC
flag does not suffice to avoid race conditions where one thread opens a file descriptor at the same time as another thread does afork(2)
plusexecve(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
andsysvgroups
described inmount(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 theO_SYNC
flag that data and necessary metadata are transferred. To guarantee synchronous I/O,O_SYNC
must be used in addition toO_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 ofopendir(3)
.O_DSYNC
O_EXCL
- Ensure that this call creates the file: if this flag is specified in conjunction withO_CREAT
, and pathname already exists, thenopen()
will fail.When these two flags are specified, symbolic links are not followed: if
pathname
is a symbolic link, thenopen()
fails regardless of where the symbolic link points to.In general, the behavior of
O_EXCL
is undefined if it is used withoutO_CREAT
. There is one exception: on Linux 2.6 and later,O_EXCL
can be used withoutO_CREAT
ifpathname
refers to a block device. If the block device is in use by the system (e.g., mounted),open()
fails with the errorEBUSY
.On NFS,
O_EXCL
is only supported when using NFSv3 or later on kernel 2.6 or later. In NFS environments whereO_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 forO_EXCL
, can create a unique file on the same file system (e.g., incorporating hostname and PID), and uselink(2)
to make a link to the lockfile. Iflink(2)
returns 0, the lock is successful. Otherwise, usestat(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 anoff_t
(but can be represented in anoff64_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 usingO_LARGEFILE
) is the preferred method of accessing large files on 32-bit systems (seefeature_test_macros(7)
).O_NOATIME
- Do not update the file last access time (st_atime
in theinode
) when the file isread(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
- Ifpathname
refers to a terminal device --seetty(4)
-- it will not become the process's controlling terminal even if the process does not have one.O_NOFOLLOW
- Ifpathname
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 alsofifo(7)
. For a discussion of the effect ofO_NONBLOCK
in conjunction with mandatory file locks and with file leases, seefcntl(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., isO_RDWR
orO_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 ofO_TRUNC
is unspecified.
- See Also:
-
O_RDWR
public static final int O_RDWREnum 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 withlseek(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 viafcntl(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 theFD_CLOEXEC
flag. Additionally, use of this flag is essential in some multithreaded programs since using a separatefcntl(2) F_SETFD
operation to set theFD_CLOEXEC
flag does not suffice to avoid race conditions where one thread opens a file descriptor at the same time as another thread does afork(2)
plusexecve(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
andsysvgroups
described inmount(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 theO_SYNC
flag that data and necessary metadata are transferred. To guarantee synchronous I/O,O_SYNC
must be used in addition toO_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 ofopendir(3)
.O_DSYNC
O_EXCL
- Ensure that this call creates the file: if this flag is specified in conjunction withO_CREAT
, and pathname already exists, thenopen()
will fail.When these two flags are specified, symbolic links are not followed: if
pathname
is a symbolic link, thenopen()
fails regardless of where the symbolic link points to.In general, the behavior of
O_EXCL
is undefined if it is used withoutO_CREAT
. There is one exception: on Linux 2.6 and later,O_EXCL
can be used withoutO_CREAT
ifpathname
refers to a block device. If the block device is in use by the system (e.g., mounted),open()
fails with the errorEBUSY
.On NFS,
O_EXCL
is only supported when using NFSv3 or later on kernel 2.6 or later. In NFS environments whereO_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 forO_EXCL
, can create a unique file on the same file system (e.g., incorporating hostname and PID), and uselink(2)
to make a link to the lockfile. Iflink(2)
returns 0, the lock is successful. Otherwise, usestat(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 anoff_t
(but can be represented in anoff64_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 usingO_LARGEFILE
) is the preferred method of accessing large files on 32-bit systems (seefeature_test_macros(7)
).O_NOATIME
- Do not update the file last access time (st_atime
in theinode
) when the file isread(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
- Ifpathname
refers to a terminal device --seetty(4)
-- it will not become the process's controlling terminal even if the process does not have one.O_NOFOLLOW
- Ifpathname
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 alsofifo(7)
. For a discussion of the effect ofO_NONBLOCK
in conjunction with mandatory file locks and with file leases, seefcntl(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., isO_RDWR
orO_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 ofO_TRUNC
is unspecified.
- See Also:
-
O_APPEND
public static final int O_APPENDEnum 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 withlseek(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 viafcntl(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 theFD_CLOEXEC
flag. Additionally, use of this flag is essential in some multithreaded programs since using a separatefcntl(2) F_SETFD
operation to set theFD_CLOEXEC
flag does not suffice to avoid race conditions where one thread opens a file descriptor at the same time as another thread does afork(2)
plusexecve(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
andsysvgroups
described inmount(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 theO_SYNC
flag that data and necessary metadata are transferred. To guarantee synchronous I/O,O_SYNC
must be used in addition toO_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 ofopendir(3)
.O_DSYNC
O_EXCL
- Ensure that this call creates the file: if this flag is specified in conjunction withO_CREAT
, and pathname already exists, thenopen()
will fail.When these two flags are specified, symbolic links are not followed: if
pathname
is a symbolic link, thenopen()
fails regardless of where the symbolic link points to.In general, the behavior of
O_EXCL
is undefined if it is used withoutO_CREAT
. There is one exception: on Linux 2.6 and later,O_EXCL
can be used withoutO_CREAT
ifpathname
refers to a block device. If the block device is in use by the system (e.g., mounted),open()
fails with the errorEBUSY
.On NFS,
O_EXCL
is only supported when using NFSv3 or later on kernel 2.6 or later. In NFS environments whereO_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 forO_EXCL
, can create a unique file on the same file system (e.g., incorporating hostname and PID), and uselink(2)
to make a link to the lockfile. Iflink(2)
returns 0, the lock is successful. Otherwise, usestat(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 anoff_t
(but can be represented in anoff64_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 usingO_LARGEFILE
) is the preferred method of accessing large files on 32-bit systems (seefeature_test_macros(7)
).O_NOATIME
- Do not update the file last access time (st_atime
in theinode
) when the file isread(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
- Ifpathname
refers to a terminal device --seetty(4)
-- it will not become the process's controlling terminal even if the process does not have one.O_NOFOLLOW
- Ifpathname
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 alsofifo(7)
. For a discussion of the effect ofO_NONBLOCK
in conjunction with mandatory file locks and with file leases, seefcntl(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., isO_RDWR
orO_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 ofO_TRUNC
is unspecified.
- See Also:
-
O_ASYNC
public static final int O_ASYNCEnum 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 withlseek(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 viafcntl(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 theFD_CLOEXEC
flag. Additionally, use of this flag is essential in some multithreaded programs since using a separatefcntl(2) F_SETFD
operation to set theFD_CLOEXEC
flag does not suffice to avoid race conditions where one thread opens a file descriptor at the same time as another thread does afork(2)
plusexecve(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
andsysvgroups
described inmount(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 theO_SYNC
flag that data and necessary metadata are transferred. To guarantee synchronous I/O,O_SYNC
must be used in addition toO_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 ofopendir(3)
.O_DSYNC
O_EXCL
- Ensure that this call creates the file: if this flag is specified in conjunction withO_CREAT
, and pathname already exists, thenopen()
will fail.When these two flags are specified, symbolic links are not followed: if
pathname
is a symbolic link, thenopen()
fails regardless of where the symbolic link points to.In general, the behavior of
O_EXCL
is undefined if it is used withoutO_CREAT
. There is one exception: on Linux 2.6 and later,O_EXCL
can be used withoutO_CREAT
ifpathname
refers to a block device. If the block device is in use by the system (e.g., mounted),open()
fails with the errorEBUSY
.On NFS,
O_EXCL
is only supported when using NFSv3 or later on kernel 2.6 or later. In NFS environments whereO_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 forO_EXCL
, can create a unique file on the same file system (e.g., incorporating hostname and PID), and uselink(2)
to make a link to the lockfile. Iflink(2)
returns 0, the lock is successful. Otherwise, usestat(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 anoff_t
(but can be represented in anoff64_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 usingO_LARGEFILE
) is the preferred method of accessing large files on 32-bit systems (seefeature_test_macros(7)
).O_NOATIME
- Do not update the file last access time (st_atime
in theinode
) when the file isread(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
- Ifpathname
refers to a terminal device --seetty(4)
-- it will not become the process's controlling terminal even if the process does not have one.O_NOFOLLOW
- Ifpathname
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 alsofifo(7)
. For a discussion of the effect ofO_NONBLOCK
in conjunction with mandatory file locks and with file leases, seefcntl(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., isO_RDWR
orO_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 ofO_TRUNC
is unspecified.
- See Also:
-
O_CLOEXEC
public static final int O_CLOEXECEnum 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 withlseek(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 viafcntl(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 theFD_CLOEXEC
flag. Additionally, use of this flag is essential in some multithreaded programs since using a separatefcntl(2) F_SETFD
operation to set theFD_CLOEXEC
flag does not suffice to avoid race conditions where one thread opens a file descriptor at the same time as another thread does afork(2)
plusexecve(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
andsysvgroups
described inmount(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 theO_SYNC
flag that data and necessary metadata are transferred. To guarantee synchronous I/O,O_SYNC
must be used in addition toO_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 ofopendir(3)
.O_DSYNC
O_EXCL
- Ensure that this call creates the file: if this flag is specified in conjunction withO_CREAT
, and pathname already exists, thenopen()
will fail.When these two flags are specified, symbolic links are not followed: if
pathname
is a symbolic link, thenopen()
fails regardless of where the symbolic link points to.In general, the behavior of
O_EXCL
is undefined if it is used withoutO_CREAT
. There is one exception: on Linux 2.6 and later,O_EXCL
can be used withoutO_CREAT
ifpathname
refers to a block device. If the block device is in use by the system (e.g., mounted),open()
fails with the errorEBUSY
.On NFS,
O_EXCL
is only supported when using NFSv3 or later on kernel 2.6 or later. In NFS environments whereO_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 forO_EXCL
, can create a unique file on the same file system (e.g., incorporating hostname and PID), and uselink(2)
to make a link to the lockfile. Iflink(2)
returns 0, the lock is successful. Otherwise, usestat(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 anoff_t
(but can be represented in anoff64_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 usingO_LARGEFILE
) is the preferred method of accessing large files on 32-bit systems (seefeature_test_macros(7)
).O_NOATIME
- Do not update the file last access time (st_atime
in theinode
) when the file isread(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
- Ifpathname
refers to a terminal device --seetty(4)
-- it will not become the process's controlling terminal even if the process does not have one.O_NOFOLLOW
- Ifpathname
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 alsofifo(7)
. For a discussion of the effect ofO_NONBLOCK
in conjunction with mandatory file locks and with file leases, seefcntl(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., isO_RDWR
orO_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 ofO_TRUNC
is unspecified.
- See Also:
-
O_CREAT
public static final int O_CREATEnum 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 withlseek(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 viafcntl(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 theFD_CLOEXEC
flag. Additionally, use of this flag is essential in some multithreaded programs since using a separatefcntl(2) F_SETFD
operation to set theFD_CLOEXEC
flag does not suffice to avoid race conditions where one thread opens a file descriptor at the same time as another thread does afork(2)
plusexecve(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
andsysvgroups
described inmount(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 theO_SYNC
flag that data and necessary metadata are transferred. To guarantee synchronous I/O,O_SYNC
must be used in addition toO_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 ofopendir(3)
.O_DSYNC
O_EXCL
- Ensure that this call creates the file: if this flag is specified in conjunction withO_CREAT
, and pathname already exists, thenopen()
will fail.When these two flags are specified, symbolic links are not followed: if
pathname
is a symbolic link, thenopen()
fails regardless of where the symbolic link points to.In general, the behavior of
O_EXCL
is undefined if it is used withoutO_CREAT
. There is one exception: on Linux 2.6 and later,O_EXCL
can be used withoutO_CREAT
ifpathname
refers to a block device. If the block device is in use by the system (e.g., mounted),open()
fails with the errorEBUSY
.On NFS,
O_EXCL
is only supported when using NFSv3 or later on kernel 2.6 or later. In NFS environments whereO_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 forO_EXCL
, can create a unique file on the same file system (e.g., incorporating hostname and PID), and uselink(2)
to make a link to the lockfile. Iflink(2)
returns 0, the lock is successful. Otherwise, usestat(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 anoff_t
(but can be represented in anoff64_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 usingO_LARGEFILE
) is the preferred method of accessing large files on 32-bit systems (seefeature_test_macros(7)
).O_NOATIME
- Do not update the file last access time (st_atime
in theinode
) when the file isread(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
- Ifpathname
refers to a terminal device --seetty(4)
-- it will not become the process's controlling terminal even if the process does not have one.O_NOFOLLOW
- Ifpathname
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 alsofifo(7)
. For a discussion of the effect ofO_NONBLOCK
in conjunction with mandatory file locks and with file leases, seefcntl(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., isO_RDWR
orO_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 ofO_TRUNC
is unspecified.
- See Also:
-
O_DIRECT
public static final int O_DIRECTEnum 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 withlseek(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 viafcntl(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 theFD_CLOEXEC
flag. Additionally, use of this flag is essential in some multithreaded programs since using a separatefcntl(2) F_SETFD
operation to set theFD_CLOEXEC
flag does not suffice to avoid race conditions where one thread opens a file descriptor at the same time as another thread does afork(2)
plusexecve(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
andsysvgroups
described inmount(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 theO_SYNC
flag that data and necessary metadata are transferred. To guarantee synchronous I/O,O_SYNC
must be used in addition toO_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 ofopendir(3)
.O_DSYNC
O_EXCL
- Ensure that this call creates the file: if this flag is specified in conjunction withO_CREAT
, and pathname already exists, thenopen()
will fail.When these two flags are specified, symbolic links are not followed: if
pathname
is a symbolic link, thenopen()
fails regardless of where the symbolic link points to.In general, the behavior of
O_EXCL
is undefined if it is used withoutO_CREAT
. There is one exception: on Linux 2.6 and later,O_EXCL
can be used withoutO_CREAT
ifpathname
refers to a block device. If the block device is in use by the system (e.g., mounted),open()
fails with the errorEBUSY
.On NFS,
O_EXCL
is only supported when using NFSv3 or later on kernel 2.6 or later. In NFS environments whereO_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 forO_EXCL
, can create a unique file on the same file system (e.g., incorporating hostname and PID), and uselink(2)
to make a link to the lockfile. Iflink(2)
returns 0, the lock is successful. Otherwise, usestat(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 anoff_t
(but can be represented in anoff64_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 usingO_LARGEFILE
) is the preferred method of accessing large files on 32-bit systems (seefeature_test_macros(7)
).O_NOATIME
- Do not update the file last access time (st_atime
in theinode
) when the file isread(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
- Ifpathname
refers to a terminal device --seetty(4)
-- it will not become the process's controlling terminal even if the process does not have one.O_NOFOLLOW
- Ifpathname
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 alsofifo(7)
. For a discussion of the effect ofO_NONBLOCK
in conjunction with mandatory file locks and with file leases, seefcntl(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., isO_RDWR
orO_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 ofO_TRUNC
is unspecified.
- See Also:
-
O_DIRECTORY
public static final int O_DIRECTORYEnum 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 withlseek(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 viafcntl(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 theFD_CLOEXEC
flag. Additionally, use of this flag is essential in some multithreaded programs since using a separatefcntl(2) F_SETFD
operation to set theFD_CLOEXEC
flag does not suffice to avoid race conditions where one thread opens a file descriptor at the same time as another thread does afork(2)
plusexecve(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
andsysvgroups
described inmount(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 theO_SYNC
flag that data and necessary metadata are transferred. To guarantee synchronous I/O,O_SYNC
must be used in addition toO_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 ofopendir(3)
.O_DSYNC
O_EXCL
- Ensure that this call creates the file: if this flag is specified in conjunction withO_CREAT
, and pathname already exists, thenopen()
will fail.When these two flags are specified, symbolic links are not followed: if
pathname
is a symbolic link, thenopen()
fails regardless of where the symbolic link points to.In general, the behavior of
O_EXCL
is undefined if it is used withoutO_CREAT
. There is one exception: on Linux 2.6 and later,O_EXCL
can be used withoutO_CREAT
ifpathname
refers to a block device. If the block device is in use by the system (e.g., mounted),open()
fails with the errorEBUSY
.On NFS,
O_EXCL
is only supported when using NFSv3 or later on kernel 2.6 or later. In NFS environments whereO_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 forO_EXCL
, can create a unique file on the same file system (e.g., incorporating hostname and PID), and uselink(2)
to make a link to the lockfile. Iflink(2)
returns 0, the lock is successful. Otherwise, usestat(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 anoff_t
(but can be represented in anoff64_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 usingO_LARGEFILE
) is the preferred method of accessing large files on 32-bit systems (seefeature_test_macros(7)
).O_NOATIME
- Do not update the file last access time (st_atime
in theinode
) when the file isread(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
- Ifpathname
refers to a terminal device --seetty(4)
-- it will not become the process's controlling terminal even if the process does not have one.O_NOFOLLOW
- Ifpathname
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 alsofifo(7)
. For a discussion of the effect ofO_NONBLOCK
in conjunction with mandatory file locks and with file leases, seefcntl(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., isO_RDWR
orO_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 ofO_TRUNC
is unspecified.
- See Also:
-
O_DSYNC
public static final int O_DSYNCEnum 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 withlseek(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 viafcntl(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 theFD_CLOEXEC
flag. Additionally, use of this flag is essential in some multithreaded programs since using a separatefcntl(2) F_SETFD
operation to set theFD_CLOEXEC
flag does not suffice to avoid race conditions where one thread opens a file descriptor at the same time as another thread does afork(2)
plusexecve(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
andsysvgroups
described inmount(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 theO_SYNC
flag that data and necessary metadata are transferred. To guarantee synchronous I/O,O_SYNC
must be used in addition toO_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 ofopendir(3)
.O_DSYNC
O_EXCL
- Ensure that this call creates the file: if this flag is specified in conjunction withO_CREAT
, and pathname already exists, thenopen()
will fail.When these two flags are specified, symbolic links are not followed: if
pathname
is a symbolic link, thenopen()
fails regardless of where the symbolic link points to.In general, the behavior of
O_EXCL
is undefined if it is used withoutO_CREAT
. There is one exception: on Linux 2.6 and later,O_EXCL
can be used withoutO_CREAT
ifpathname
refers to a block device. If the block device is in use by the system (e.g., mounted),open()
fails with the errorEBUSY
.On NFS,
O_EXCL
is only supported when using NFSv3 or later on kernel 2.6 or later. In NFS environments whereO_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 forO_EXCL
, can create a unique file on the same file system (e.g., incorporating hostname and PID), and uselink(2)
to make a link to the lockfile. Iflink(2)
returns 0, the lock is successful. Otherwise, usestat(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 anoff_t
(but can be represented in anoff64_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 usingO_LARGEFILE
) is the preferred method of accessing large files on 32-bit systems (seefeature_test_macros(7)
).O_NOATIME
- Do not update the file last access time (st_atime
in theinode
) when the file isread(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
- Ifpathname
refers to a terminal device --seetty(4)
-- it will not become the process's controlling terminal even if the process does not have one.O_NOFOLLOW
- Ifpathname
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 alsofifo(7)
. For a discussion of the effect ofO_NONBLOCK
in conjunction with mandatory file locks and with file leases, seefcntl(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., isO_RDWR
orO_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 ofO_TRUNC
is unspecified.
- See Also:
-
O_EXCL
public static final int O_EXCLEnum 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 withlseek(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 viafcntl(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 theFD_CLOEXEC
flag. Additionally, use of this flag is essential in some multithreaded programs since using a separatefcntl(2) F_SETFD
operation to set theFD_CLOEXEC
flag does not suffice to avoid race conditions where one thread opens a file descriptor at the same time as another thread does afork(2)
plusexecve(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
andsysvgroups
described inmount(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 theO_SYNC
flag that data and necessary metadata are transferred. To guarantee synchronous I/O,O_SYNC
must be used in addition toO_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 ofopendir(3)
.O_DSYNC
O_EXCL
- Ensure that this call creates the file: if this flag is specified in conjunction withO_CREAT
, and pathname already exists, thenopen()
will fail.When these two flags are specified, symbolic links are not followed: if
pathname
is a symbolic link, thenopen()
fails regardless of where the symbolic link points to.In general, the behavior of
O_EXCL
is undefined if it is used withoutO_CREAT
. There is one exception: on Linux 2.6 and later,O_EXCL
can be used withoutO_CREAT
ifpathname
refers to a block device. If the block device is in use by the system (e.g., mounted),open()
fails with the errorEBUSY
.On NFS,
O_EXCL
is only supported when using NFSv3 or later on kernel 2.6 or later. In NFS environments whereO_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 forO_EXCL
, can create a unique file on the same file system (e.g., incorporating hostname and PID), and uselink(2)
to make a link to the lockfile. Iflink(2)
returns 0, the lock is successful. Otherwise, usestat(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 anoff_t
(but can be represented in anoff64_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 usingO_LARGEFILE
) is the preferred method of accessing large files on 32-bit systems (seefeature_test_macros(7)
).O_NOATIME
- Do not update the file last access time (st_atime
in theinode
) when the file isread(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
- Ifpathname
refers to a terminal device --seetty(4)
-- it will not become the process's controlling terminal even if the process does not have one.O_NOFOLLOW
- Ifpathname
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 alsofifo(7)
. For a discussion of the effect ofO_NONBLOCK
in conjunction with mandatory file locks and with file leases, seefcntl(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., isO_RDWR
orO_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 ofO_TRUNC
is unspecified.
- See Also:
-
O_LARGEFILE
public static final int O_LARGEFILEEnum 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 withlseek(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 viafcntl(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 theFD_CLOEXEC
flag. Additionally, use of this flag is essential in some multithreaded programs since using a separatefcntl(2) F_SETFD
operation to set theFD_CLOEXEC
flag does not suffice to avoid race conditions where one thread opens a file descriptor at the same time as another thread does afork(2)
plusexecve(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
andsysvgroups
described inmount(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 theO_SYNC
flag that data and necessary metadata are transferred. To guarantee synchronous I/O,O_SYNC
must be used in addition toO_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 ofopendir(3)
.O_DSYNC
O_EXCL
- Ensure that this call creates the file: if this flag is specified in conjunction withO_CREAT
, and pathname already exists, thenopen()
will fail.When these two flags are specified, symbolic links are not followed: if
pathname
is a symbolic link, thenopen()
fails regardless of where the symbolic link points to.In general, the behavior of
O_EXCL
is undefined if it is used withoutO_CREAT
. There is one exception: on Linux 2.6 and later,O_EXCL
can be used withoutO_CREAT
ifpathname
refers to a block device. If the block device is in use by the system (e.g., mounted),open()
fails with the errorEBUSY
.On NFS,
O_EXCL
is only supported when using NFSv3 or later on kernel 2.6 or later. In NFS environments whereO_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 forO_EXCL
, can create a unique file on the same file system (e.g., incorporating hostname and PID), and uselink(2)
to make a link to the lockfile. Iflink(2)
returns 0, the lock is successful. Otherwise, usestat(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 anoff_t
(but can be represented in anoff64_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 usingO_LARGEFILE
) is the preferred method of accessing large files on 32-bit systems (seefeature_test_macros(7)
).O_NOATIME
- Do not update the file last access time (st_atime
in theinode
) when the file isread(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
- Ifpathname
refers to a terminal device --seetty(4)
-- it will not become the process's controlling terminal even if the process does not have one.O_NOFOLLOW
- Ifpathname
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 alsofifo(7)
. For a discussion of the effect ofO_NONBLOCK
in conjunction with mandatory file locks and with file leases, seefcntl(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., isO_RDWR
orO_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 ofO_TRUNC
is unspecified.
- See Also:
-
O_NOATIME
public static final int O_NOATIMEEnum 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 withlseek(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 viafcntl(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 theFD_CLOEXEC
flag. Additionally, use of this flag is essential in some multithreaded programs since using a separatefcntl(2) F_SETFD
operation to set theFD_CLOEXEC
flag does not suffice to avoid race conditions where one thread opens a file descriptor at the same time as another thread does afork(2)
plusexecve(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
andsysvgroups
described inmount(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 theO_SYNC
flag that data and necessary metadata are transferred. To guarantee synchronous I/O,O_SYNC
must be used in addition toO_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 ofopendir(3)
.O_DSYNC
O_EXCL
- Ensure that this call creates the file: if this flag is specified in conjunction withO_CREAT
, and pathname already exists, thenopen()
will fail.When these two flags are specified, symbolic links are not followed: if
pathname
is a symbolic link, thenopen()
fails regardless of where the symbolic link points to.In general, the behavior of
O_EXCL
is undefined if it is used withoutO_CREAT
. There is one exception: on Linux 2.6 and later,O_EXCL
can be used withoutO_CREAT
ifpathname
refers to a block device. If the block device is in use by the system (e.g., mounted),open()
fails with the errorEBUSY
.On NFS,
O_EXCL
is only supported when using NFSv3 or later on kernel 2.6 or later. In NFS environments whereO_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 forO_EXCL
, can create a unique file on the same file system (e.g., incorporating hostname and PID), and uselink(2)
to make a link to the lockfile. Iflink(2)
returns 0, the lock is successful. Otherwise, usestat(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 anoff_t
(but can be represented in anoff64_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 usingO_LARGEFILE
) is the preferred method of accessing large files on 32-bit systems (seefeature_test_macros(7)
).O_NOATIME
- Do not update the file last access time (st_atime
in theinode
) when the file isread(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
- Ifpathname
refers to a terminal device --seetty(4)
-- it will not become the process's controlling terminal even if the process does not have one.O_NOFOLLOW
- Ifpathname
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 alsofifo(7)
. For a discussion of the effect ofO_NONBLOCK
in conjunction with mandatory file locks and with file leases, seefcntl(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., isO_RDWR
orO_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 ofO_TRUNC
is unspecified.
- See Also:
-
O_NOCTTY
public static final int O_NOCTTYEnum 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 withlseek(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 viafcntl(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 theFD_CLOEXEC
flag. Additionally, use of this flag is essential in some multithreaded programs since using a separatefcntl(2) F_SETFD
operation to set theFD_CLOEXEC
flag does not suffice to avoid race conditions where one thread opens a file descriptor at the same time as another thread does afork(2)
plusexecve(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
andsysvgroups
described inmount(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 theO_SYNC
flag that data and necessary metadata are transferred. To guarantee synchronous I/O,O_SYNC
must be used in addition toO_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 ofopendir(3)
.O_DSYNC
O_EXCL
- Ensure that this call creates the file: if this flag is specified in conjunction withO_CREAT
, and pathname already exists, thenopen()
will fail.When these two flags are specified, symbolic links are not followed: if
pathname
is a symbolic link, thenopen()
fails regardless of where the symbolic link points to.In general, the behavior of
O_EXCL
is undefined if it is used withoutO_CREAT
. There is one exception: on Linux 2.6 and later,O_EXCL
can be used withoutO_CREAT
ifpathname
refers to a block device. If the block device is in use by the system (e.g., mounted),open()
fails with the errorEBUSY
.On NFS,
O_EXCL
is only supported when using NFSv3 or later on kernel 2.6 or later. In NFS environments whereO_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 forO_EXCL
, can create a unique file on the same file system (e.g., incorporating hostname and PID), and uselink(2)
to make a link to the lockfile. Iflink(2)
returns 0, the lock is successful. Otherwise, usestat(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 anoff_t
(but can be represented in anoff64_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 usingO_LARGEFILE
) is the preferred method of accessing large files on 32-bit systems (seefeature_test_macros(7)
).O_NOATIME
- Do not update the file last access time (st_atime
in theinode
) when the file isread(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
- Ifpathname
refers to a terminal device --seetty(4)
-- it will not become the process's controlling terminal even if the process does not have one.O_NOFOLLOW
- Ifpathname
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 alsofifo(7)
. For a discussion of the effect ofO_NONBLOCK
in conjunction with mandatory file locks and with file leases, seefcntl(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., isO_RDWR
orO_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 ofO_TRUNC
is unspecified.
- See Also:
-
O_NOFOLLOW
public static final int O_NOFOLLOWEnum 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 withlseek(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 viafcntl(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 theFD_CLOEXEC
flag. Additionally, use of this flag is essential in some multithreaded programs since using a separatefcntl(2) F_SETFD
operation to set theFD_CLOEXEC
flag does not suffice to avoid race conditions where one thread opens a file descriptor at the same time as another thread does afork(2)
plusexecve(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
andsysvgroups
described inmount(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 theO_SYNC
flag that data and necessary metadata are transferred. To guarantee synchronous I/O,O_SYNC
must be used in addition toO_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 ofopendir(3)
.O_DSYNC
O_EXCL
- Ensure that this call creates the file: if this flag is specified in conjunction withO_CREAT
, and pathname already exists, thenopen()
will fail.When these two flags are specified, symbolic links are not followed: if
pathname
is a symbolic link, thenopen()
fails regardless of where the symbolic link points to.In general, the behavior of
O_EXCL
is undefined if it is used withoutO_CREAT
. There is one exception: on Linux 2.6 and later,O_EXCL
can be used withoutO_CREAT
ifpathname
refers to a block device. If the block device is in use by the system (e.g., mounted),open()
fails with the errorEBUSY
.On NFS,
O_EXCL
is only supported when using NFSv3 or later on kernel 2.6 or later. In NFS environments whereO_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 forO_EXCL
, can create a unique file on the same file system (e.g., incorporating hostname and PID), and uselink(2)
to make a link to the lockfile. Iflink(2)
returns 0, the lock is successful. Otherwise, usestat(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 anoff_t
(but can be represented in anoff64_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 usingO_LARGEFILE
) is the preferred method of accessing large files on 32-bit systems (seefeature_test_macros(7)
).O_NOATIME
- Do not update the file last access time (st_atime
in theinode
) when the file isread(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
- Ifpathname
refers to a terminal device --seetty(4)
-- it will not become the process's controlling terminal even if the process does not have one.O_NOFOLLOW
- Ifpathname
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 alsofifo(7)
. For a discussion of the effect ofO_NONBLOCK
in conjunction with mandatory file locks and with file leases, seefcntl(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., isO_RDWR
orO_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 ofO_TRUNC
is unspecified.
- See Also:
-
O_NONBLOCK
public static final int O_NONBLOCKEnum 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 withlseek(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 viafcntl(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 theFD_CLOEXEC
flag. Additionally, use of this flag is essential in some multithreaded programs since using a separatefcntl(2) F_SETFD
operation to set theFD_CLOEXEC
flag does not suffice to avoid race conditions where one thread opens a file descriptor at the same time as another thread does afork(2)
plusexecve(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
andsysvgroups
described inmount(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 theO_SYNC
flag that data and necessary metadata are transferred. To guarantee synchronous I/O,O_SYNC
must be used in addition toO_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 ofopendir(3)
.O_DSYNC
O_EXCL
- Ensure that this call creates the file: if this flag is specified in conjunction withO_CREAT
, and pathname already exists, thenopen()
will fail.When these two flags are specified, symbolic links are not followed: if
pathname
is a symbolic link, thenopen()
fails regardless of where the symbolic link points to.In general, the behavior of
O_EXCL
is undefined if it is used withoutO_CREAT
. There is one exception: on Linux 2.6 and later,O_EXCL
can be used withoutO_CREAT
ifpathname
refers to a block device. If the block device is in use by the system (e.g., mounted),open()
fails with the errorEBUSY
.On NFS,
O_EXCL
is only supported when using NFSv3 or later on kernel 2.6 or later. In NFS environments whereO_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 forO_EXCL
, can create a unique file on the same file system (e.g., incorporating hostname and PID), and uselink(2)
to make a link to the lockfile. Iflink(2)
returns 0, the lock is successful. Otherwise, usestat(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 anoff_t
(but can be represented in anoff64_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 usingO_LARGEFILE
) is the preferred method of accessing large files on 32-bit systems (seefeature_test_macros(7)
).O_NOATIME
- Do not update the file last access time (st_atime
in theinode
) when the file isread(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
- Ifpathname
refers to a terminal device --seetty(4)
-- it will not become the process's controlling terminal even if the process does not have one.O_NOFOLLOW
- Ifpathname
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 alsofifo(7)
. For a discussion of the effect ofO_NONBLOCK
in conjunction with mandatory file locks and with file leases, seefcntl(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., isO_RDWR
orO_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 ofO_TRUNC
is unspecified.
- See Also:
-
O_NDELAY
public static final int O_NDELAYEnum 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 withlseek(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 viafcntl(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 theFD_CLOEXEC
flag. Additionally, use of this flag is essential in some multithreaded programs since using a separatefcntl(2) F_SETFD
operation to set theFD_CLOEXEC
flag does not suffice to avoid race conditions where one thread opens a file descriptor at the same time as another thread does afork(2)
plusexecve(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
andsysvgroups
described inmount(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 theO_SYNC
flag that data and necessary metadata are transferred. To guarantee synchronous I/O,O_SYNC
must be used in addition toO_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 ofopendir(3)
.O_DSYNC
O_EXCL
- Ensure that this call creates the file: if this flag is specified in conjunction withO_CREAT
, and pathname already exists, thenopen()
will fail.When these two flags are specified, symbolic links are not followed: if
pathname
is a symbolic link, thenopen()
fails regardless of where the symbolic link points to.In general, the behavior of
O_EXCL
is undefined if it is used withoutO_CREAT
. There is one exception: on Linux 2.6 and later,O_EXCL
can be used withoutO_CREAT
ifpathname
refers to a block device. If the block device is in use by the system (e.g., mounted),open()
fails with the errorEBUSY
.On NFS,
O_EXCL
is only supported when using NFSv3 or later on kernel 2.6 or later. In NFS environments whereO_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 forO_EXCL
, can create a unique file on the same file system (e.g., incorporating hostname and PID), and uselink(2)
to make a link to the lockfile. Iflink(2)
returns 0, the lock is successful. Otherwise, usestat(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 anoff_t
(but can be represented in anoff64_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 usingO_LARGEFILE
) is the preferred method of accessing large files on 32-bit systems (seefeature_test_macros(7)
).O_NOATIME
- Do not update the file last access time (st_atime
in theinode
) when the file isread(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
- Ifpathname
refers to a terminal device --seetty(4)
-- it will not become the process's controlling terminal even if the process does not have one.O_NOFOLLOW
- Ifpathname
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 alsofifo(7)
. For a discussion of the effect ofO_NONBLOCK
in conjunction with mandatory file locks and with file leases, seefcntl(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., isO_RDWR
orO_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 ofO_TRUNC
is unspecified.
- See Also:
-
O_PATH
public static final int O_PATHEnum 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 withlseek(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 viafcntl(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 theFD_CLOEXEC
flag. Additionally, use of this flag is essential in some multithreaded programs since using a separatefcntl(2) F_SETFD
operation to set theFD_CLOEXEC
flag does not suffice to avoid race conditions where one thread opens a file descriptor at the same time as another thread does afork(2)
plusexecve(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
andsysvgroups
described inmount(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 theO_SYNC
flag that data and necessary metadata are transferred. To guarantee synchronous I/O,O_SYNC
must be used in addition toO_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 ofopendir(3)
.O_DSYNC
O_EXCL
- Ensure that this call creates the file: if this flag is specified in conjunction withO_CREAT
, and pathname already exists, thenopen()
will fail.When these two flags are specified, symbolic links are not followed: if
pathname
is a symbolic link, thenopen()
fails regardless of where the symbolic link points to.In general, the behavior of
O_EXCL
is undefined if it is used withoutO_CREAT
. There is one exception: on Linux 2.6 and later,O_EXCL
can be used withoutO_CREAT
ifpathname
refers to a block device. If the block device is in use by the system (e.g., mounted),open()
fails with the errorEBUSY
.On NFS,
O_EXCL
is only supported when using NFSv3 or later on kernel 2.6 or later. In NFS environments whereO_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 forO_EXCL
, can create a unique file on the same file system (e.g., incorporating hostname and PID), and uselink(2)
to make a link to the lockfile. Iflink(2)
returns 0, the lock is successful. Otherwise, usestat(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 anoff_t
(but can be represented in anoff64_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 usingO_LARGEFILE
) is the preferred method of accessing large files on 32-bit systems (seefeature_test_macros(7)
).O_NOATIME
- Do not update the file last access time (st_atime
in theinode
) when the file isread(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
- Ifpathname
refers to a terminal device --seetty(4)
-- it will not become the process's controlling terminal even if the process does not have one.O_NOFOLLOW
- Ifpathname
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 alsofifo(7)
. For a discussion of the effect ofO_NONBLOCK
in conjunction with mandatory file locks and with file leases, seefcntl(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., isO_RDWR
orO_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 ofO_TRUNC
is unspecified.
- See Also:
-
O_SYNC
public static final int O_SYNCEnum 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 withlseek(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 viafcntl(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 theFD_CLOEXEC
flag. Additionally, use of this flag is essential in some multithreaded programs since using a separatefcntl(2) F_SETFD
operation to set theFD_CLOEXEC
flag does not suffice to avoid race conditions where one thread opens a file descriptor at the same time as another thread does afork(2)
plusexecve(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
andsysvgroups
described inmount(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 theO_SYNC
flag that data and necessary metadata are transferred. To guarantee synchronous I/O,O_SYNC
must be used in addition toO_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 ofopendir(3)
.O_DSYNC
O_EXCL
- Ensure that this call creates the file: if this flag is specified in conjunction withO_CREAT
, and pathname already exists, thenopen()
will fail.When these two flags are specified, symbolic links are not followed: if
pathname
is a symbolic link, thenopen()
fails regardless of where the symbolic link points to.In general, the behavior of
O_EXCL
is undefined if it is used withoutO_CREAT
. There is one exception: on Linux 2.6 and later,O_EXCL
can be used withoutO_CREAT
ifpathname
refers to a block device. If the block device is in use by the system (e.g., mounted),open()
fails with the errorEBUSY
.On NFS,
O_EXCL
is only supported when using NFSv3 or later on kernel 2.6 or later. In NFS environments whereO_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 forO_EXCL
, can create a unique file on the same file system (e.g., incorporating hostname and PID), and uselink(2)
to make a link to the lockfile. Iflink(2)
returns 0, the lock is successful. Otherwise, usestat(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 anoff_t
(but can be represented in anoff64_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 usingO_LARGEFILE
) is the preferred method of accessing large files on 32-bit systems (seefeature_test_macros(7)
).O_NOATIME
- Do not update the file last access time (st_atime
in theinode
) when the file isread(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
- Ifpathname
refers to a terminal device --seetty(4)
-- it will not become the process's controlling terminal even if the process does not have one.O_NOFOLLOW
- Ifpathname
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 alsofifo(7)
. For a discussion of the effect ofO_NONBLOCK
in conjunction with mandatory file locks and with file leases, seefcntl(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., isO_RDWR
orO_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 ofO_TRUNC
is unspecified.
- See Also:
-
O_TMPFILE
public static final int O_TMPFILEEnum 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 withlseek(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 viafcntl(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 theFD_CLOEXEC
flag. Additionally, use of this flag is essential in some multithreaded programs since using a separatefcntl(2) F_SETFD
operation to set theFD_CLOEXEC
flag does not suffice to avoid race conditions where one thread opens a file descriptor at the same time as another thread does afork(2)
plusexecve(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
andsysvgroups
described inmount(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 theO_SYNC
flag that data and necessary metadata are transferred. To guarantee synchronous I/O,O_SYNC
must be used in addition toO_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 ofopendir(3)
.O_DSYNC
O_EXCL
- Ensure that this call creates the file: if this flag is specified in conjunction withO_CREAT
, and pathname already exists, thenopen()
will fail.When these two flags are specified, symbolic links are not followed: if
pathname
is a symbolic link, thenopen()
fails regardless of where the symbolic link points to.In general, the behavior of
O_EXCL
is undefined if it is used withoutO_CREAT
. There is one exception: on Linux 2.6 and later,O_EXCL
can be used withoutO_CREAT
ifpathname
refers to a block device. If the block device is in use by the system (e.g., mounted),open()
fails with the errorEBUSY
.On NFS,
O_EXCL
is only supported when using NFSv3 or later on kernel 2.6 or later. In NFS environments whereO_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 forO_EXCL
, can create a unique file on the same file system (e.g., incorporating hostname and PID), and uselink(2)
to make a link to the lockfile. Iflink(2)
returns 0, the lock is successful. Otherwise, usestat(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 anoff_t
(but can be represented in anoff64_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 usingO_LARGEFILE
) is the preferred method of accessing large files on 32-bit systems (seefeature_test_macros(7)
).O_NOATIME
- Do not update the file last access time (st_atime
in theinode
) when the file isread(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
- Ifpathname
refers to a terminal device --seetty(4)
-- it will not become the process's controlling terminal even if the process does not have one.O_NOFOLLOW
- Ifpathname
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 alsofifo(7)
. For a discussion of the effect ofO_NONBLOCK
in conjunction with mandatory file locks and with file leases, seefcntl(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., isO_RDWR
orO_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 ofO_TRUNC
is unspecified.
- See Also:
-
O_TRUNC
public static final int O_TRUNCEnum 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 withlseek(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 viafcntl(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 theFD_CLOEXEC
flag. Additionally, use of this flag is essential in some multithreaded programs since using a separatefcntl(2) F_SETFD
operation to set theFD_CLOEXEC
flag does not suffice to avoid race conditions where one thread opens a file descriptor at the same time as another thread does afork(2)
plusexecve(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
andsysvgroups
described inmount(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 theO_SYNC
flag that data and necessary metadata are transferred. To guarantee synchronous I/O,O_SYNC
must be used in addition toO_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 ofopendir(3)
.O_DSYNC
O_EXCL
- Ensure that this call creates the file: if this flag is specified in conjunction withO_CREAT
, and pathname already exists, thenopen()
will fail.When these two flags are specified, symbolic links are not followed: if
pathname
is a symbolic link, thenopen()
fails regardless of where the symbolic link points to.In general, the behavior of
O_EXCL
is undefined if it is used withoutO_CREAT
. There is one exception: on Linux 2.6 and later,O_EXCL
can be used withoutO_CREAT
ifpathname
refers to a block device. If the block device is in use by the system (e.g., mounted),open()
fails with the errorEBUSY
.On NFS,
O_EXCL
is only supported when using NFSv3 or later on kernel 2.6 or later. In NFS environments whereO_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 forO_EXCL
, can create a unique file on the same file system (e.g., incorporating hostname and PID), and uselink(2)
to make a link to the lockfile. Iflink(2)
returns 0, the lock is successful. Otherwise, usestat(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 anoff_t
(but can be represented in anoff64_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 usingO_LARGEFILE
) is the preferred method of accessing large files on 32-bit systems (seefeature_test_macros(7)
).O_NOATIME
- Do not update the file last access time (st_atime
in theinode
) when the file isread(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
- Ifpathname
refers to a terminal device --seetty(4)
-- it will not become the process's controlling terminal even if the process does not have one.O_NOFOLLOW
- Ifpathname
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 alsofifo(7)
. For a discussion of the effect ofO_NONBLOCK
in conjunction with mandatory file locks and with file leases, seefcntl(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., isO_RDWR
orO_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 ofO_TRUNC
is unspecified.
- See Also:
-
S_IFMT
public static final int S_IFMTFile types encoded in typemode_t
.Enum values:
- See Also:
-
S_IFBLK
public static final int S_IFBLKFile types encoded in typemode_t
.Enum values:
- See Also:
-
S_IFCHR
public static final int S_IFCHRFile types encoded in typemode_t
.Enum values:
- See Also:
-
S_IFIFO
public static final int S_IFIFOFile types encoded in typemode_t
.Enum values:
- See Also:
-
S_IFREG
public static final int S_IFREGFile types encoded in typemode_t
.Enum values:
- See Also:
-
S_IFDIR
public static final int S_IFDIRFile types encoded in typemode_t
.Enum values:
- See Also:
-
S_IFLNK
public static final int S_IFLNKFile types encoded in typemode_t
.Enum values:
- See Also:
-
S_IFSOCK
public static final int S_IFSOCKFile types encoded in typemode_t
.Enum values:
- See Also:
-
S_IRWXU
public static final int S_IRWXUFile mode bits encoded in typemode_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_IRUSRFile mode bits encoded in typemode_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_IWUSRFile mode bits encoded in typemode_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_IXUSRFile mode bits encoded in typemode_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_IRWXGFile mode bits encoded in typemode_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_IRGRPFile mode bits encoded in typemode_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_IWGRPFile mode bits encoded in typemode_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_IXGRPFile mode bits encoded in typemode_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_IRWXOFile mode bits encoded in typemode_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_IROTHFile mode bits encoded in typemode_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_IWOTHFile mode bits encoded in typemode_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_IXOTHFile mode bits encoded in typemode_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_ISUIDFile mode bits encoded in typemode_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_ISGIDFile mode bits encoded in typemode_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_ISVTXFile mode bits encoded in typemode_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_DUPFDfcntl(int, int)
commands.Enum values:
F_DUPFD
- Duplicate the file descriptorfd
using the lowest-numbered available file descriptor greater than or equal toarg
.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 byarg
.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 byarg
.File access mode (
O_RDONLY
,O_WRONLY
,O_RDWR
) and file creation flags (i.e.,O_CREAT
,O_EXCL
,O_NOCTTY
,O_TRUNC
) inarg
are ignored. On Linux, this command can change only theO_APPEND
,O_ASYNC
,O_DIRECT
,O_NOATIME
, andO_NONBLOCK
flags. It is not possible to change theO_DSYNC
andO_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 returnsF_UNLCK
in thel_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 thel_type
,l_whence
,l_start
, andl_len
fields of lock. If the conflicting lock is a traditional (process-associated) record lock, then thel_pid
field is set to thePID
of the process holding that lock. If the conflicting lock is an open file description lock, thenl_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 (whenl_type
isF_RDLCK
orF_WRLCK
) or release a lock (whenl_type
isF_UNLCK
) on the bytes specified by thel_whence
,l_start
, andl_len
fields of lock.If a conflicting lock is held by another process, this call returns -1 and sets
errno
toEACCES
orEAGAIN
. (The error returned in this case differs across implementations, so POSIX requires a portable application to check for both errors.)F_SETLKW
- As forF_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
; seesignal(7)
).F_SETOWN
- Set the process ID or process group ID that will receiveSIGIO
andSIGURG
signals for events on the file descriptorfd
.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 asgetpid(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 theO_ASYNC
file status flag on the file descriptor. Subsequently, aSIGIO
signal is sent whenever input or output becomes possible on the file descriptor. Thefcntl()
F_SETSIG
command can be used to obtain delivery of a signal other thanSIGIO
.Sending a signal to the owner process (group) specified by
F_SETOWN
is subject to the same permissions checks as are described forkill(2)
, where the sending process is the one that employsF_SETOWN
(but see BUGS below). If this permission check fails, then the signal is silently discarded. Note: TheF_SETOWN
operation records the caller's credentials at the time of thefcntl()
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 ofSIGURG
signals that are delivered when out-of-band data arrives on that socket. (SIGURG
is sent in any situation whereselect(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 toF_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 passF_SETOWN
the result ofgettid(2)
instead ofgetpid(2)
to get sensible results whenF_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 usegettid(2)
orgetpid(2)
in this scenario.) Note, however, that the statements in this paragraph do not apply to theSIGURG
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 toF_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 targetSIGIO
andSIGURG
signals at a particular thread.F_GETOWN
- Return (as the function result) the process ID or process group ID currently receivingSIGIO
andSIGURG
signals for events on file descriptorfd
.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 inarg
.A value of zero means to send the default
SIGIO
signal. Any other value (includingSIGIO
) is the signal to send instead, and in this case additional info is available to the signal handler if installed withSA_SIGINFO
.By using
F_SETSIG
with a nonzero value, and settingSA_SIGINFO
for the signal handler (seesigaction(2)
), extra information about I/O events is passed to the handler in asiginfo_t
structure. If thesi_code
field indicates the source isSI_SIGIO
, thesi_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)
withO_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 theF_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 thesi_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 ifSA_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)
andsignal(7)
) and if this limit is reached, then the kernel reverts to deliveringSIGIO
, 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 (includingSIGIO
) is the signal sent instead, and in this case additional info is available to the signal handler if installed withSA_SIGINFO
.arg
is ignored.F_SETOWN_EX
- This operation performs a similar task toF_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 aFOwnerEx
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 previousF_SETOWN_EX
operation.The information is returned in the
FOwnerEx
structure pointed to byarg
.The type field will have one of the values
F_OWNER_TID
,F_OWNER_PID
, orF_OWNER_PGRP
. Thepid
field is a positive integer representing a thread ID, process ID, or process group ID. SeeF_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 returnsF_UNLCK
in thel_type
field oflock
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 vialock
, as described above forF_GETLK
.F_OFD_SETLK
- Acquire an open file description lock (whenl_type
isF_RDLCK
orF_WRLCK
) or release an open file description lock (whenl_type
isF_UNLCK
) on the bytes specified by thel_whence
,l_start
, andl_len
fields oflock
.If a conflicting lock is held by another process, this call returns -1 and sets
errno
toEAGAIN
.F_OFD_SETLKW
- As forF_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 toEINTR
; seesignal(7)
).F_SETLEASE
- Set or remove a file lease according to which of the following values is specified in the integerarg
:F_RDLCK
,F_WRLCK
,F_UNLCK
F_GETLEASE
- Indicates what type of lease is associated with the file descriptorfd
by returning eitherF_RDLCK
,F_WRLCK
, orF_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 byfd
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 inarg
, then notification will remain in effect until explicitly removed.A series of
F_NOTIFY
requests is cumulative, with the events inarg
being added to the set already monitored. To disable notification of all events, make anF_NOTIFY
call specifyingarg
as 0.Notification occurs via delivery of a signal. The default signal is
SIGIO
, but this can be changed using theF_SETSIG
command tofcntl()
. (Note thatSIGIO
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 asiginfo_t
structure as its second argument (if the handler was established usingSA_SIGINFO
) and thesi_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. Seeinotify(7)
.F_SETPIPE_SZ
- Change the capacity of the pipe referred to byfd
to be at leastarg
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
(seeproc(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 errorEPERM
; 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 byfd
.F_ADD_SEALS
- Add the seals given in the bit-mask argumentarg
to the set of seals of theinode
referred to by the file descriptorfd
.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 withEPERM
. Adding a seal that is already set is a no-op, in caseF_SEAL_SEAL
is not set already. In order to place a seal, the file descriptorfd
must be writable.F_GET_SEALS
- Return (as the function result) the current set of seals of theinode
referred to byfd
.If no seals are set, 0 is returned. If the file does not support sealing, -1 is returned and
errno
is set toEINVAL
.F_GET_RW_HINT
- Returns the value of the read/write hint associated with the underlyinginode
referred to byfd
.F_SET_RW_HINT
- Sets the read/write hint value associated with the underlyinginode
referred to byfd
.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 byfd
.F_SET_FILE_RW_HINT
- Sets the read/write hint value associated with the open file description referred to byfd
.F_DUPFD_CLOEXEC
- As forF_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 theFD_CLOEXEC
flag. For an explanation of why this flag is useful, see the description ofO_CLOEXEC
inopen(2)
.
- See Also:
-
F_GETFD
public static final int F_GETFDfcntl(int, int)
commands.Enum values:
F_DUPFD
- Duplicate the file descriptorfd
using the lowest-numbered available file descriptor greater than or equal toarg
.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 byarg
.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 byarg
.File access mode (
O_RDONLY
,O_WRONLY
,O_RDWR
) and file creation flags (i.e.,O_CREAT
,O_EXCL
,O_NOCTTY
,O_TRUNC
) inarg
are ignored. On Linux, this command can change only theO_APPEND
,O_ASYNC
,O_DIRECT
,O_NOATIME
, andO_NONBLOCK
flags. It is not possible to change theO_DSYNC
andO_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 returnsF_UNLCK
in thel_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 thel_type
,l_whence
,l_start
, andl_len
fields of lock. If the conflicting lock is a traditional (process-associated) record lock, then thel_pid
field is set to thePID
of the process holding that lock. If the conflicting lock is an open file description lock, thenl_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 (whenl_type
isF_RDLCK
orF_WRLCK
) or release a lock (whenl_type
isF_UNLCK
) on the bytes specified by thel_whence
,l_start
, andl_len
fields of lock.If a conflicting lock is held by another process, this call returns -1 and sets
errno
toEACCES
orEAGAIN
. (The error returned in this case differs across implementations, so POSIX requires a portable application to check for both errors.)F_SETLKW
- As forF_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
; seesignal(7)
).F_SETOWN
- Set the process ID or process group ID that will receiveSIGIO
andSIGURG
signals for events on the file descriptorfd
.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 asgetpid(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 theO_ASYNC
file status flag on the file descriptor. Subsequently, aSIGIO
signal is sent whenever input or output becomes possible on the file descriptor. Thefcntl()
F_SETSIG
command can be used to obtain delivery of a signal other thanSIGIO
.Sending a signal to the owner process (group) specified by
F_SETOWN
is subject to the same permissions checks as are described forkill(2)
, where the sending process is the one that employsF_SETOWN
(but see BUGS below). If this permission check fails, then the signal is silently discarded. Note: TheF_SETOWN
operation records the caller's credentials at the time of thefcntl()
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 ofSIGURG
signals that are delivered when out-of-band data arrives on that socket. (SIGURG
is sent in any situation whereselect(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 toF_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 passF_SETOWN
the result ofgettid(2)
instead ofgetpid(2)
to get sensible results whenF_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 usegettid(2)
orgetpid(2)
in this scenario.) Note, however, that the statements in this paragraph do not apply to theSIGURG
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 toF_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 targetSIGIO
andSIGURG
signals at a particular thread.F_GETOWN
- Return (as the function result) the process ID or process group ID currently receivingSIGIO
andSIGURG
signals for events on file descriptorfd
.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 inarg
.A value of zero means to send the default
SIGIO
signal. Any other value (includingSIGIO
) is the signal to send instead, and in this case additional info is available to the signal handler if installed withSA_SIGINFO
.By using
F_SETSIG
with a nonzero value, and settingSA_SIGINFO
for the signal handler (seesigaction(2)
), extra information about I/O events is passed to the handler in asiginfo_t
structure. If thesi_code
field indicates the source isSI_SIGIO
, thesi_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)
withO_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 theF_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 thesi_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 ifSA_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)
andsignal(7)
) and if this limit is reached, then the kernel reverts to deliveringSIGIO
, 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 (includingSIGIO
) is the signal sent instead, and in this case additional info is available to the signal handler if installed withSA_SIGINFO
.arg
is ignored.F_SETOWN_EX
- This operation performs a similar task toF_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 aFOwnerEx
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 previousF_SETOWN_EX
operation.The information is returned in the
FOwnerEx
structure pointed to byarg
.The type field will have one of the values
F_OWNER_TID
,F_OWNER_PID
, orF_OWNER_PGRP
. Thepid
field is a positive integer representing a thread ID, process ID, or process group ID. SeeF_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 returnsF_UNLCK
in thel_type
field oflock
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 vialock
, as described above forF_GETLK
.F_OFD_SETLK
- Acquire an open file description lock (whenl_type
isF_RDLCK
orF_WRLCK
) or release an open file description lock (whenl_type
isF_UNLCK
) on the bytes specified by thel_whence
,l_start
, andl_len
fields oflock
.If a conflicting lock is held by another process, this call returns -1 and sets
errno
toEAGAIN
.F_OFD_SETLKW
- As forF_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 toEINTR
; seesignal(7)
).F_SETLEASE
- Set or remove a file lease according to which of the following values is specified in the integerarg
:F_RDLCK
,F_WRLCK
,F_UNLCK
F_GETLEASE
- Indicates what type of lease is associated with the file descriptorfd
by returning eitherF_RDLCK
,F_WRLCK
, orF_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 byfd
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 inarg
, then notification will remain in effect until explicitly removed.A series of
F_NOTIFY
requests is cumulative, with the events inarg
being added to the set already monitored. To disable notification of all events, make anF_NOTIFY
call specifyingarg
as 0.Notification occurs via delivery of a signal. The default signal is
SIGIO
, but this can be changed using theF_SETSIG
command tofcntl()
. (Note thatSIGIO
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 asiginfo_t
structure as its second argument (if the handler was established usingSA_SIGINFO
) and thesi_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. Seeinotify(7)
.F_SETPIPE_SZ
- Change the capacity of the pipe referred to byfd
to be at leastarg
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
(seeproc(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 errorEPERM
; 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 byfd
.F_ADD_SEALS
- Add the seals given in the bit-mask argumentarg
to the set of seals of theinode
referred to by the file descriptorfd
.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 withEPERM
. Adding a seal that is already set is a no-op, in caseF_SEAL_SEAL
is not set already. In order to place a seal, the file descriptorfd
must be writable.F_GET_SEALS
- Return (as the function result) the current set of seals of theinode
referred to byfd
.If no seals are set, 0 is returned. If the file does not support sealing, -1 is returned and
errno
is set toEINVAL
.F_GET_RW_HINT
- Returns the value of the read/write hint associated with the underlyinginode
referred to byfd
.F_SET_RW_HINT
- Sets the read/write hint value associated with the underlyinginode
referred to byfd
.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 byfd
.F_SET_FILE_RW_HINT
- Sets the read/write hint value associated with the open file description referred to byfd
.F_DUPFD_CLOEXEC
- As forF_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 theFD_CLOEXEC
flag. For an explanation of why this flag is useful, see the description ofO_CLOEXEC
inopen(2)
.
- See Also:
-
F_SETFD
public static final int F_SETFDfcntl(int, int)
commands.Enum values:
F_DUPFD
- Duplicate the file descriptorfd
using the lowest-numbered available file descriptor greater than or equal toarg
.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 byarg
.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 byarg
.File access mode (
O_RDONLY
,O_WRONLY
,O_RDWR
) and file creation flags (i.e.,O_CREAT
,O_EXCL
,O_NOCTTY
,O_TRUNC
) inarg
are ignored. On Linux, this command can change only theO_APPEND
,O_ASYNC
,O_DIRECT
,O_NOATIME
, andO_NONBLOCK
flags. It is not possible to change theO_DSYNC
andO_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 returnsF_UNLCK
in thel_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 thel_type
,l_whence
,l_start
, andl_len
fields of lock. If the conflicting lock is a traditional (process-associated) record lock, then thel_pid
field is set to thePID
of the process holding that lock. If the conflicting lock is an open file description lock, thenl_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 (whenl_type
isF_RDLCK
orF_WRLCK
) or release a lock (whenl_type
isF_UNLCK
) on the bytes specified by thel_whence
,l_start
, andl_len
fields of lock.If a conflicting lock is held by another process, this call returns -1 and sets
errno
toEACCES
orEAGAIN
. (The error returned in this case differs across implementations, so POSIX requires a portable application to check for both errors.)F_SETLKW
- As forF_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
; seesignal(7)
).F_SETOWN
- Set the process ID or process group ID that will receiveSIGIO
andSIGURG
signals for events on the file descriptorfd
.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 asgetpid(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 theO_ASYNC
file status flag on the file descriptor. Subsequently, aSIGIO
signal is sent whenever input or output becomes possible on the file descriptor. Thefcntl()
F_SETSIG
command can be used to obtain delivery of a signal other thanSIGIO
.Sending a signal to the owner process (group) specified by
F_SETOWN
is subject to the same permissions checks as are described forkill(2)
, where the sending process is the one that employsF_SETOWN
(but see BUGS below). If this permission check fails, then the signal is silently discarded. Note: TheF_SETOWN
operation records the caller's credentials at the time of thefcntl()
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 ofSIGURG
signals that are delivered when out-of-band data arrives on that socket. (SIGURG
is sent in any situation whereselect(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 toF_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 passF_SETOWN
the result ofgettid(2)
instead ofgetpid(2)
to get sensible results whenF_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 usegettid(2)
orgetpid(2)
in this scenario.) Note, however, that the statements in this paragraph do not apply to theSIGURG
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 toF_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 targetSIGIO
andSIGURG
signals at a particular thread.F_GETOWN
- Return (as the function result) the process ID or process group ID currently receivingSIGIO
andSIGURG
signals for events on file descriptorfd
.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 inarg
.A value of zero means to send the default
SIGIO
signal. Any other value (includingSIGIO
) is the signal to send instead, and in this case additional info is available to the signal handler if installed withSA_SIGINFO
.By using
F_SETSIG
with a nonzero value, and settingSA_SIGINFO
for the signal handler (seesigaction(2)
), extra information about I/O events is passed to the handler in asiginfo_t
structure. If thesi_code
field indicates the source isSI_SIGIO
, thesi_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)
withO_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 theF_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 thesi_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 ifSA_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)
andsignal(7)
) and if this limit is reached, then the kernel reverts to deliveringSIGIO
, 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 (includingSIGIO
) is the signal sent instead, and in this case additional info is available to the signal handler if installed withSA_SIGINFO
.arg
is ignored.F_SETOWN_EX
- This operation performs a similar task toF_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 aFOwnerEx
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 previousF_SETOWN_EX
operation.The information is returned in the
FOwnerEx
structure pointed to byarg
.The type field will have one of the values
F_OWNER_TID
,F_OWNER_PID
, orF_OWNER_PGRP
. Thepid
field is a positive integer representing a thread ID, process ID, or process group ID. SeeF_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 returnsF_UNLCK
in thel_type
field oflock
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 vialock
, as described above forF_GETLK
.F_OFD_SETLK
- Acquire an open file description lock (whenl_type
isF_RDLCK
orF_WRLCK
) or release an open file description lock (whenl_type
isF_UNLCK
) on the bytes specified by thel_whence
,l_start
, andl_len
fields oflock
.If a conflicting lock is held by another process, this call returns -1 and sets
errno
toEAGAIN
.F_OFD_SETLKW
- As forF_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 toEINTR
; seesignal(7)
).F_SETLEASE
- Set or remove a file lease according to which of the following values is specified in the integerarg
:F_RDLCK
,F_WRLCK
,F_UNLCK
F_GETLEASE
- Indicates what type of lease is associated with the file descriptorfd
by returning eitherF_RDLCK
,F_WRLCK
, orF_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 byfd
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 inarg
, then notification will remain in effect until explicitly removed.A series of
F_NOTIFY
requests is cumulative, with the events inarg
being added to the set already monitored. To disable notification of all events, make anF_NOTIFY
call specifyingarg
as 0.Notification occurs via delivery of a signal. The default signal is
SIGIO
, but this can be changed using theF_SETSIG
command tofcntl()
. (Note thatSIGIO
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 asiginfo_t
structure as its second argument (if the handler was established usingSA_SIGINFO
) and thesi_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. Seeinotify(7)
.F_SETPIPE_SZ
- Change the capacity of the pipe referred to byfd
to be at leastarg
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
(seeproc(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 errorEPERM
; 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 byfd
.F_ADD_SEALS
- Add the seals given in the bit-mask argumentarg
to the set of seals of theinode
referred to by the file descriptorfd
.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 withEPERM
. Adding a seal that is already set is a no-op, in caseF_SEAL_SEAL
is not set already. In order to place a seal, the file descriptorfd
must be writable.F_GET_SEALS
- Return (as the function result) the current set of seals of theinode
referred to byfd
.If no seals are set, 0 is returned. If the file does not support sealing, -1 is returned and
errno
is set toEINVAL
.F_GET_RW_HINT
- Returns the value of the read/write hint associated with the underlyinginode
referred to byfd
.F_SET_RW_HINT
- Sets the read/write hint value associated with the underlyinginode
referred to byfd
.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 byfd
.F_SET_FILE_RW_HINT
- Sets the read/write hint value associated with the open file description referred to byfd
.F_DUPFD_CLOEXEC
- As forF_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 theFD_CLOEXEC
flag. For an explanation of why this flag is useful, see the description ofO_CLOEXEC
inopen(2)
.
- See Also:
-
F_GETFL
public static final int F_GETFLfcntl(int, int)
commands.Enum values:
F_DUPFD
- Duplicate the file descriptorfd
using the lowest-numbered available file descriptor greater than or equal toarg
.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 byarg
.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 byarg
.File access mode (
O_RDONLY
,O_WRONLY
,O_RDWR
) and file creation flags (i.e.,O_CREAT
,O_EXCL
,O_NOCTTY
,O_TRUNC
) inarg
are ignored. On Linux, this command can change only theO_APPEND
,O_ASYNC
,O_DIRECT
,O_NOATIME
, andO_NONBLOCK
flags. It is not possible to change theO_DSYNC
andO_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 returnsF_UNLCK
in thel_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 thel_type
,l_whence
,l_start
, andl_len
fields of lock. If the conflicting lock is a traditional (process-associated) record lock, then thel_pid
field is set to thePID
of the process holding that lock. If the conflicting lock is an open file description lock, thenl_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 (whenl_type
isF_RDLCK
orF_WRLCK
) or release a lock (whenl_type
isF_UNLCK
) on the bytes specified by thel_whence
,l_start
, andl_len
fields of lock.If a conflicting lock is held by another process, this call returns -1 and sets
errno
toEACCES
orEAGAIN
. (The error returned in this case differs across implementations, so POSIX requires a portable application to check for both errors.)F_SETLKW
- As forF_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
; seesignal(7)
).F_SETOWN
- Set the process ID or process group ID that will receiveSIGIO
andSIGURG
signals for events on the file descriptorfd
.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 asgetpid(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 theO_ASYNC
file status flag on the file descriptor. Subsequently, aSIGIO
signal is sent whenever input or output becomes possible on the file descriptor. Thefcntl()
F_SETSIG
command can be used to obtain delivery of a signal other thanSIGIO
.Sending a signal to the owner process (group) specified by
F_SETOWN
is subject to the same permissions checks as are described forkill(2)
, where the sending process is the one that employsF_SETOWN
(but see BUGS below). If this permission check fails, then the signal is silently discarded. Note: TheF_SETOWN
operation records the caller's credentials at the time of thefcntl()
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 ofSIGURG
signals that are delivered when out-of-band data arrives on that socket. (SIGURG
is sent in any situation whereselect(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 toF_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 passF_SETOWN
the result ofgettid(2)
instead ofgetpid(2)
to get sensible results whenF_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 usegettid(2)
orgetpid(2)
in this scenario.) Note, however, that the statements in this paragraph do not apply to theSIGURG
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 toF_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 targetSIGIO
andSIGURG
signals at a particular thread.F_GETOWN
- Return (as the function result) the process ID or process group ID currently receivingSIGIO
andSIGURG
signals for events on file descriptorfd
.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 inarg
.A value of zero means to send the default
SIGIO
signal. Any other value (includingSIGIO
) is the signal to send instead, and in this case additional info is available to the signal handler if installed withSA_SIGINFO
.By using
F_SETSIG
with a nonzero value, and settingSA_SIGINFO
for the signal handler (seesigaction(2)
), extra information about I/O events is passed to the handler in asiginfo_t
structure. If thesi_code
field indicates the source isSI_SIGIO
, thesi_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)
withO_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 theF_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 thesi_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 ifSA_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)
andsignal(7)
) and if this limit is reached, then the kernel reverts to deliveringSIGIO
, 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 (includingSIGIO
) is the signal sent instead, and in this case additional info is available to the signal handler if installed withSA_SIGINFO
.arg
is ignored.F_SETOWN_EX
- This operation performs a similar task toF_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 aFOwnerEx
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 previousF_SETOWN_EX
operation.The information is returned in the
FOwnerEx
structure pointed to byarg
.The type field will have one of the values
F_OWNER_TID
,F_OWNER_PID
, orF_OWNER_PGRP
. Thepid
field is a positive integer representing a thread ID, process ID, or process group ID. SeeF_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 returnsF_UNLCK
in thel_type
field oflock
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 vialock
, as described above forF_GETLK
.F_OFD_SETLK
- Acquire an open file description lock (whenl_type
isF_RDLCK
orF_WRLCK
) or release an open file description lock (whenl_type
isF_UNLCK
) on the bytes specified by thel_whence
,l_start
, andl_len
fields oflock
.If a conflicting lock is held by another process, this call returns -1 and sets
errno
toEAGAIN
.F_OFD_SETLKW
- As forF_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 toEINTR
; seesignal(7)
).F_SETLEASE
- Set or remove a file lease according to which of the following values is specified in the integerarg
:F_RDLCK
,F_WRLCK
,F_UNLCK
F_GETLEASE
- Indicates what type of lease is associated with the file descriptorfd
by returning eitherF_RDLCK
,F_WRLCK
, orF_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 byfd
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 inarg
, then notification will remain in effect until explicitly removed.A series of
F_NOTIFY
requests is cumulative, with the events inarg
being added to the set already monitored. To disable notification of all events, make anF_NOTIFY
call specifyingarg
as 0.Notification occurs via delivery of a signal. The default signal is
SIGIO
, but this can be changed using theF_SETSIG
command tofcntl()
. (Note thatSIGIO
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 asiginfo_t
structure as its second argument (if the handler was established usingSA_SIGINFO
) and thesi_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. Seeinotify(7)
.F_SETPIPE_SZ
- Change the capacity of the pipe referred to byfd
to be at leastarg
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
(seeproc(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 errorEPERM
; 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 byfd
.F_ADD_SEALS
- Add the seals given in the bit-mask argumentarg
to the set of seals of theinode
referred to by the file descriptorfd
.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 withEPERM
. Adding a seal that is already set is a no-op, in caseF_SEAL_SEAL
is not set already. In order to place a seal, the file descriptorfd
must be writable.F_GET_SEALS
- Return (as the function result) the current set of seals of theinode
referred to byfd
.If no seals are set, 0 is returned. If the file does not support sealing, -1 is returned and
errno
is set toEINVAL
.F_GET_RW_HINT
- Returns the value of the read/write hint associated with the underlyinginode
referred to byfd
.F_SET_RW_HINT
- Sets the read/write hint value associated with the underlyinginode
referred to byfd
.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 byfd
.F_SET_FILE_RW_HINT
- Sets the read/write hint value associated with the open file description referred to byfd
.F_DUPFD_CLOEXEC
- As forF_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 theFD_CLOEXEC
flag. For an explanation of why this flag is useful, see the description ofO_CLOEXEC
inopen(2)
.
- See Also:
-
F_SETFL
public static final int F_SETFLfcntl(int, int)
commands.Enum values:
F_DUPFD
- Duplicate the file descriptorfd
using the lowest-numbered available file descriptor greater than or equal toarg
.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 byarg
.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 byarg
.File access mode (
O_RDONLY
,O_WRONLY
,O_RDWR
) and file creation flags (i.e.,O_CREAT
,O_EXCL
,O_NOCTTY
,O_TRUNC
) inarg
are ignored. On Linux, this command can change only theO_APPEND
,O_ASYNC
,O_DIRECT
,O_NOATIME
, andO_NONBLOCK
flags. It is not possible to change theO_DSYNC
andO_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 returnsF_UNLCK
in thel_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 thel_type
,l_whence
,l_start
, andl_len
fields of lock. If the conflicting lock is a traditional (process-associated) record lock, then thel_pid
field is set to thePID
of the process holding that lock. If the conflicting lock is an open file description lock, thenl_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 (whenl_type
isF_RDLCK
orF_WRLCK
) or release a lock (whenl_type
isF_UNLCK
) on the bytes specified by thel_whence
,l_start
, andl_len
fields of lock.If a conflicting lock is held by another process, this call returns -1 and sets
errno
toEACCES
orEAGAIN
. (The error returned in this case differs across implementations, so POSIX requires a portable application to check for both errors.)F_SETLKW
- As forF_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
; seesignal(7)
).F_SETOWN
- Set the process ID or process group ID that will receiveSIGIO
andSIGURG
signals for events on the file descriptorfd
.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 asgetpid(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 theO_ASYNC
file status flag on the file descriptor. Subsequently, aSIGIO
signal is sent whenever input or output becomes possible on the file descriptor. Thefcntl()
F_SETSIG
command can be used to obtain delivery of a signal other thanSIGIO
.Sending a signal to the owner process (group) specified by
F_SETOWN
is subject to the same permissions checks as are described forkill(2)
, where the sending process is the one that employsF_SETOWN
(but see BUGS below). If this permission check fails, then the signal is silently discarded. Note: TheF_SETOWN
operation records the caller's credentials at the time of thefcntl()
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 ofSIGURG
signals that are delivered when out-of-band data arrives on that socket. (SIGURG
is sent in any situation whereselect(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 toF_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 passF_SETOWN
the result ofgettid(2)
instead ofgetpid(2)
to get sensible results whenF_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 usegettid(2)
orgetpid(2)
in this scenario.) Note, however, that the statements in this paragraph do not apply to theSIGURG
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 toF_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 targetSIGIO
andSIGURG
signals at a particular thread.F_GETOWN
- Return (as the function result) the process ID or process group ID currently receivingSIGIO
andSIGURG
signals for events on file descriptorfd
.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 inarg
.A value of zero means to send the default
SIGIO
signal. Any other value (includingSIGIO
) is the signal to send instead, and in this case additional info is available to the signal handler if installed withSA_SIGINFO
.By using
F_SETSIG
with a nonzero value, and settingSA_SIGINFO
for the signal handler (seesigaction(2)
), extra information about I/O events is passed to the handler in asiginfo_t
structure. If thesi_code
field indicates the source isSI_SIGIO
, thesi_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)
withO_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 theF_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 thesi_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 ifSA_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)
andsignal(7)
) and if this limit is reached, then the kernel reverts to deliveringSIGIO
, 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 (includingSIGIO
) is the signal sent instead, and in this case additional info is available to the signal handler if installed withSA_SIGINFO
.arg
is ignored.F_SETOWN_EX
- This operation performs a similar task toF_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 aFOwnerEx
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 previousF_SETOWN_EX
operation.The information is returned in the
FOwnerEx
structure pointed to byarg
.The type field will have one of the values
F_OWNER_TID
,F_OWNER_PID
, orF_OWNER_PGRP
. Thepid
field is a positive integer representing a thread ID, process ID, or process group ID. SeeF_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 returnsF_UNLCK
in thel_type
field oflock
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 vialock
, as described above forF_GETLK
.F_OFD_SETLK
- Acquire an open file description lock (whenl_type
isF_RDLCK
orF_WRLCK
) or release an open file description lock (whenl_type
isF_UNLCK
) on the bytes specified by thel_whence
,l_start
, andl_len
fields oflock
.If a conflicting lock is held by another process, this call returns -1 and sets
errno
toEAGAIN
.F_OFD_SETLKW
- As forF_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 toEINTR
; seesignal(7)
).F_SETLEASE
- Set or remove a file lease according to which of the following values is specified in the integerarg
:F_RDLCK
,F_WRLCK
,F_UNLCK
F_GETLEASE
- Indicates what type of lease is associated with the file descriptorfd
by returning eitherF_RDLCK
,F_WRLCK
, orF_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 byfd
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 inarg
, then notification will remain in effect until explicitly removed.A series of
F_NOTIFY
requests is cumulative, with the events inarg
being added to the set already monitored. To disable notification of all events, make anF_NOTIFY
call specifyingarg
as 0.Notification occurs via delivery of a signal. The default signal is
SIGIO
, but this can be changed using theF_SETSIG
command tofcntl()
. (Note thatSIGIO
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 asiginfo_t
structure as its second argument (if the handler was established usingSA_SIGINFO
) and thesi_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. Seeinotify(7)
.F_SETPIPE_SZ
- Change the capacity of the pipe referred to byfd
to be at leastarg
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
(seeproc(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 errorEPERM
; 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 byfd
.F_ADD_SEALS
- Add the seals given in the bit-mask argumentarg
to the set of seals of theinode
referred to by the file descriptorfd
.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 withEPERM
. Adding a seal that is already set is a no-op, in caseF_SEAL_SEAL
is not set already. In order to place a seal, the file descriptorfd
must be writable.F_GET_SEALS
- Return (as the function result) the current set of seals of theinode
referred to byfd
.If no seals are set, 0 is returned. If the file does not support sealing, -1 is returned and
errno
is set toEINVAL
.F_GET_RW_HINT
- Returns the value of the read/write hint associated with the underlyinginode
referred to byfd
.F_SET_RW_HINT
- Sets the read/write hint value associated with the underlyinginode
referred to byfd
.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 byfd
.F_SET_FILE_RW_HINT
- Sets the read/write hint value associated with the open file description referred to byfd
.F_DUPFD_CLOEXEC
- As forF_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 theFD_CLOEXEC
flag. For an explanation of why this flag is useful, see the description ofO_CLOEXEC
inopen(2)
.
- See Also:
-
F_GETLK
public static final int F_GETLKfcntl(int, int)
commands.Enum values:
F_DUPFD
- Duplicate the file descriptorfd
using the lowest-numbered available file descriptor greater than or equal toarg
.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 byarg
.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 byarg
.File access mode (
O_RDONLY
,O_WRONLY
,O_RDWR
) and file creation flags (i.e.,O_CREAT
,O_EXCL
,O_NOCTTY
,O_TRUNC
) inarg
are ignored. On Linux, this command can change only theO_APPEND
,O_ASYNC
,O_DIRECT
,O_NOATIME
, andO_NONBLOCK
flags. It is not possible to change theO_DSYNC
andO_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 returnsF_UNLCK
in thel_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 thel_type
,l_whence
,l_start
, andl_len
fields of lock. If the conflicting lock is a traditional (process-associated) record lock, then thel_pid
field is set to thePID
of the process holding that lock. If the conflicting lock is an open file description lock, thenl_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 (whenl_type
isF_RDLCK
orF_WRLCK
) or release a lock (whenl_type
isF_UNLCK
) on the bytes specified by thel_whence
,l_start
, andl_len
fields of lock.If a conflicting lock is held by another process, this call returns -1 and sets
errno
toEACCES
orEAGAIN
. (The error returned in this case differs across implementations, so POSIX requires a portable application to check for both errors.)F_SETLKW
- As forF_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
; seesignal(7)
).F_SETOWN
- Set the process ID or process group ID that will receiveSIGIO
andSIGURG
signals for events on the file descriptorfd
.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 asgetpid(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 theO_ASYNC
file status flag on the file descriptor. Subsequently, aSIGIO
signal is sent whenever input or output becomes possible on the file descriptor. Thefcntl()
F_SETSIG
command can be used to obtain delivery of a signal other thanSIGIO
.Sending a signal to the owner process (group) specified by
F_SETOWN
is subject to the same permissions checks as are described forkill(2)
, where the sending process is the one that employsF_SETOWN
(but see BUGS below). If this permission check fails, then the signal is silently discarded. Note: TheF_SETOWN
operation records the caller's credentials at the time of thefcntl()
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 ofSIGURG
signals that are delivered when out-of-band data arrives on that socket. (SIGURG
is sent in any situation whereselect(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 toF_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 passF_SETOWN
the result ofgettid(2)
instead ofgetpid(2)
to get sensible results whenF_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 usegettid(2)
orgetpid(2)
in this scenario.) Note, however, that the statements in this paragraph do not apply to theSIGURG
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 toF_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 targetSIGIO
andSIGURG
signals at a particular thread.F_GETOWN
- Return (as the function result) the process ID or process group ID currently receivingSIGIO
andSIGURG
signals for events on file descriptorfd
.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 inarg
.A value of zero means to send the default
SIGIO
signal. Any other value (includingSIGIO
) is the signal to send instead, and in this case additional info is available to the signal handler if installed withSA_SIGINFO
.By using
F_SETSIG
with a nonzero value, and settingSA_SIGINFO
for the signal handler (seesigaction(2)
), extra information about I/O events is passed to the handler in asiginfo_t
structure. If thesi_code
field indicates the source isSI_SIGIO
, thesi_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)
withO_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 theF_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 thesi_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 ifSA_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)
andsignal(7)
) and if this limit is reached, then the kernel reverts to deliveringSIGIO
, 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 (includingSIGIO
) is the signal sent instead, and in this case additional info is available to the signal handler if installed withSA_SIGINFO
.arg
is ignored.F_SETOWN_EX
- This operation performs a similar task toF_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 aFOwnerEx
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 previousF_SETOWN_EX
operation.The information is returned in the
FOwnerEx
structure pointed to byarg
.The type field will have one of the values
F_OWNER_TID
,F_OWNER_PID
, orF_OWNER_PGRP
. Thepid
field is a positive integer representing a thread ID, process ID, or process group ID. SeeF_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 returnsF_UNLCK
in thel_type
field oflock
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 vialock
, as described above forF_GETLK
.F_OFD_SETLK
- Acquire an open file description lock (whenl_type
isF_RDLCK
orF_WRLCK
) or release an open file description lock (whenl_type
isF_UNLCK
) on the bytes specified by thel_whence
,l_start
, andl_len
fields oflock
.If a conflicting lock is held by another process, this call returns -1 and sets
errno
toEAGAIN
.F_OFD_SETLKW
- As forF_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 toEINTR
; seesignal(7)
).F_SETLEASE
- Set or remove a file lease according to which of the following values is specified in the integerarg
:F_RDLCK
,F_WRLCK
,F_UNLCK
F_GETLEASE
- Indicates what type of lease is associated with the file descriptorfd
by returning eitherF_RDLCK
,F_WRLCK
, orF_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 byfd
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 inarg
, then notification will remain in effect until explicitly removed.A series of
F_NOTIFY
requests is cumulative, with the events inarg
being added to the set already monitored. To disable notification of all events, make anF_NOTIFY
call specifyingarg
as 0.Notification occurs via delivery of a signal. The default signal is
SIGIO
, but this can be changed using theF_SETSIG
command tofcntl()
. (Note thatSIGIO
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 asiginfo_t
structure as its second argument (if the handler was established usingSA_SIGINFO
) and thesi_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. Seeinotify(7)
.F_SETPIPE_SZ
- Change the capacity of the pipe referred to byfd
to be at leastarg
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
(seeproc(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 errorEPERM
; 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 byfd
.F_ADD_SEALS
- Add the seals given in the bit-mask argumentarg
to the set of seals of theinode
referred to by the file descriptorfd
.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 withEPERM
. Adding a seal that is already set is a no-op, in caseF_SEAL_SEAL
is not set already. In order to place a seal, the file descriptorfd
must be writable.F_GET_SEALS
- Return (as the function result) the current set of seals of theinode
referred to byfd
.If no seals are set, 0 is returned. If the file does not support sealing, -1 is returned and
errno
is set toEINVAL
.F_GET_RW_HINT
- Returns the value of the read/write hint associated with the underlyinginode
referred to byfd
.F_SET_RW_HINT
- Sets the read/write hint value associated with the underlyinginode
referred to byfd
.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 byfd
.F_SET_FILE_RW_HINT
- Sets the read/write hint value associated with the open file description referred to byfd
.F_DUPFD_CLOEXEC
- As forF_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 theFD_CLOEXEC
flag. For an explanation of why this flag is useful, see the description ofO_CLOEXEC
inopen(2)
.
- See Also:
-
F_SETLK
public static final int F_SETLKfcntl(int, int)
commands.Enum values:
F_DUPFD
- Duplicate the file descriptorfd
using the lowest-numbered available file descriptor greater than or equal toarg
.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 byarg
.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 byarg
.File access mode (
O_RDONLY
,O_WRONLY
,O_RDWR
) and file creation flags (i.e.,O_CREAT
,O_EXCL
,O_NOCTTY
,O_TRUNC
) inarg
are ignored. On Linux, this command can change only theO_APPEND
,O_ASYNC
,O_DIRECT
,O_NOATIME
, andO_NONBLOCK
flags. It is not possible to change theO_DSYNC
andO_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 returnsF_UNLCK
in thel_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 thel_type
,l_whence
,l_start
, andl_len
fields of lock. If the conflicting lock is a traditional (process-associated) record lock, then thel_pid
field is set to thePID
of the process holding that lock. If the conflicting lock is an open file description lock, thenl_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 (whenl_type
isF_RDLCK
orF_WRLCK
) or release a lock (whenl_type
isF_UNLCK
) on the bytes specified by thel_whence
,l_start
, andl_len
fields of lock.If a conflicting lock is held by another process, this call returns -1 and sets
errno
toEACCES
orEAGAIN
. (The error returned in this case differs across implementations, so POSIX requires a portable application to check for both errors.)F_SETLKW
- As forF_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
; seesignal(7)
).F_SETOWN
- Set the process ID or process group ID that will receiveSIGIO
andSIGURG
signals for events on the file descriptorfd
.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 asgetpid(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 theO_ASYNC
file status flag on the file descriptor. Subsequently, aSIGIO
signal is sent whenever input or output becomes possible on the file descriptor. Thefcntl()
F_SETSIG
command can be used to obtain delivery of a signal other thanSIGIO
.Sending a signal to the owner process (group) specified by
F_SETOWN
is subject to the same permissions checks as are described forkill(2)
, where the sending process is the one that employsF_SETOWN
(but see BUGS below). If this permission check fails, then the signal is silently discarded. Note: TheF_SETOWN
operation records the caller's credentials at the time of thefcntl()
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 ofSIGURG
signals that are delivered when out-of-band data arrives on that socket. (SIGURG
is sent in any situation whereselect(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 toF_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 passF_SETOWN
the result ofgettid(2)
instead ofgetpid(2)
to get sensible results whenF_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 usegettid(2)
orgetpid(2)
in this scenario.) Note, however, that the statements in this paragraph do not apply to theSIGURG
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 toF_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 targetSIGIO
andSIGURG
signals at a particular thread.F_GETOWN
- Return (as the function result) the process ID or process group ID currently receivingSIGIO
andSIGURG
signals for events on file descriptorfd
.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 inarg
.A value of zero means to send the default
SIGIO
signal. Any other value (includingSIGIO
) is the signal to send instead, and in this case additional info is available to the signal handler if installed withSA_SIGINFO
.By using
F_SETSIG
with a nonzero value, and settingSA_SIGINFO
for the signal handler (seesigaction(2)
), extra information about I/O events is passed to the handler in asiginfo_t
structure. If thesi_code
field indicates the source isSI_SIGIO
, thesi_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)
withO_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 theF_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 thesi_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 ifSA_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)
andsignal(7)
) and if this limit is reached, then the kernel reverts to deliveringSIGIO
, 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 (includingSIGIO
) is the signal sent instead, and in this case additional info is available to the signal handler if installed withSA_SIGINFO
.arg
is ignored.F_SETOWN_EX
- This operation performs a similar task toF_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 aFOwnerEx
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 previousF_SETOWN_EX
operation.The information is returned in the
FOwnerEx
structure pointed to byarg
.The type field will have one of the values
F_OWNER_TID
,F_OWNER_PID
, orF_OWNER_PGRP
. Thepid
field is a positive integer representing a thread ID, process ID, or process group ID. SeeF_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 returnsF_UNLCK
in thel_type
field oflock
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 vialock
, as described above forF_GETLK
.F_OFD_SETLK
- Acquire an open file description lock (whenl_type
isF_RDLCK
orF_WRLCK
) or release an open file description lock (whenl_type
isF_UNLCK
) on the bytes specified by thel_whence
,l_start
, andl_len
fields oflock
.If a conflicting lock is held by another process, this call returns -1 and sets
errno
toEAGAIN
.F_OFD_SETLKW
- As forF_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 toEINTR
; seesignal(7)
).F_SETLEASE
- Set or remove a file lease according to which of the following values is specified in the integerarg
:F_RDLCK
,F_WRLCK
,F_UNLCK
F_GETLEASE
- Indicates what type of lease is associated with the file descriptorfd
by returning eitherF_RDLCK
,F_WRLCK
, orF_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 byfd
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 inarg
, then notification will remain in effect until explicitly removed.A series of
F_NOTIFY
requests is cumulative, with the events inarg
being added to the set already monitored. To disable notification of all events, make anF_NOTIFY
call specifyingarg
as 0.Notification occurs via delivery of a signal. The default signal is
SIGIO
, but this can be changed using theF_SETSIG
command tofcntl()
. (Note thatSIGIO
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 asiginfo_t
structure as its second argument (if the handler was established usingSA_SIGINFO
) and thesi_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. Seeinotify(7)
.F_SETPIPE_SZ
- Change the capacity of the pipe referred to byfd
to be at leastarg
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
(seeproc(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 errorEPERM
; 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 byfd
.F_ADD_SEALS
- Add the seals given in the bit-mask argumentarg
to the set of seals of theinode
referred to by the file descriptorfd
.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 withEPERM
. Adding a seal that is already set is a no-op, in caseF_SEAL_SEAL
is not set already. In order to place a seal, the file descriptorfd
must be writable.F_GET_SEALS
- Return (as the function result) the current set of seals of theinode
referred to byfd
.If no seals are set, 0 is returned. If the file does not support sealing, -1 is returned and
errno
is set toEINVAL
.F_GET_RW_HINT
- Returns the value of the read/write hint associated with the underlyinginode
referred to byfd
.F_SET_RW_HINT
- Sets the read/write hint value associated with the underlyinginode
referred to byfd
.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 byfd
.F_SET_FILE_RW_HINT
- Sets the read/write hint value associated with the open file description referred to byfd
.F_DUPFD_CLOEXEC
- As forF_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 theFD_CLOEXEC
flag. For an explanation of why this flag is useful, see the description ofO_CLOEXEC
inopen(2)
.
- See Also:
-
F_SETLKW
public static final int F_SETLKWfcntl(int, int)
commands.Enum values:
F_DUPFD
- Duplicate the file descriptorfd
using the lowest-numbered available file descriptor greater than or equal toarg
.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 byarg
.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 byarg
.File access mode (
O_RDONLY
,O_WRONLY
,O_RDWR
) and file creation flags (i.e.,O_CREAT
,O_EXCL
,O_NOCTTY
,O_TRUNC
) inarg
are ignored. On Linux, this command can change only theO_APPEND
,O_ASYNC
,O_DIRECT
,O_NOATIME
, andO_NONBLOCK
flags. It is not possible to change theO_DSYNC
andO_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 returnsF_UNLCK
in thel_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 thel_type
,l_whence
,l_start
, andl_len
fields of lock. If the conflicting lock is a traditional (process-associated) record lock, then thel_pid
field is set to thePID
of the process holding that lock. If the conflicting lock is an open file description lock, thenl_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 (whenl_type
isF_RDLCK
orF_WRLCK
) or release a lock (whenl_type
isF_UNLCK
) on the bytes specified by thel_whence
,l_start
, andl_len
fields of lock.If a conflicting lock is held by another process, this call returns -1 and sets
errno
toEACCES
orEAGAIN
. (The error returned in this case differs across implementations, so POSIX requires a portable application to check for both errors.)F_SETLKW
- As forF_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
; seesignal(7)
).F_SETOWN
- Set the process ID or process group ID that will receiveSIGIO
andSIGURG
signals for events on the file descriptorfd
.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 asgetpid(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 theO_ASYNC
file status flag on the file descriptor. Subsequently, aSIGIO
signal is sent whenever input or output becomes possible on the file descriptor. Thefcntl()
F_SETSIG
command can be used to obtain delivery of a signal other thanSIGIO
.Sending a signal to the owner process (group) specified by
F_SETOWN
is subject to the same permissions checks as are described forkill(2)
, where the sending process is the one that employsF_SETOWN
(but see BUGS below). If this permission check fails, then the signal is silently discarded. Note: TheF_SETOWN
operation records the caller's credentials at the time of thefcntl()
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 ofSIGURG
signals that are delivered when out-of-band data arrives on that socket. (SIGURG
is sent in any situation whereselect(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 toF_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 passF_SETOWN
the result ofgettid(2)
instead ofgetpid(2)
to get sensible results whenF_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 usegettid(2)
orgetpid(2)
in this scenario.) Note, however, that the statements in this paragraph do not apply to theSIGURG
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 toF_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 targetSIGIO
andSIGURG
signals at a particular thread.F_GETOWN
- Return (as the function result) the process ID or process group ID currently receivingSIGIO
andSIGURG
signals for events on file descriptorfd
.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 inarg
.A value of zero means to send the default
SIGIO
signal. Any other value (includingSIGIO
) is the signal to send instead, and in this case additional info is available to the signal handler if installed withSA_SIGINFO
.By using
F_SETSIG
with a nonzero value, and settingSA_SIGINFO
for the signal handler (seesigaction(2)
), extra information about I/O events is passed to the handler in asiginfo_t
structure. If thesi_code
field indicates the source isSI_SIGIO
, thesi_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)
withO_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 theF_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 thesi_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 ifSA_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)
andsignal(7)
) and if this limit is reached, then the kernel reverts to deliveringSIGIO
, 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 (includingSIGIO
) is the signal sent instead, and in this case additional info is available to the signal handler if installed withSA_SIGINFO
.arg
is ignored.F_SETOWN_EX
- This operation performs a similar task toF_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 aFOwnerEx
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 previousF_SETOWN_EX
operation.The information is returned in the
FOwnerEx
structure pointed to byarg
.The type field will have one of the values
F_OWNER_TID
,F_OWNER_PID
, orF_OWNER_PGRP
. Thepid
field is a positive integer representing a thread ID, process ID, or process group ID. SeeF_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 returnsF_UNLCK
in thel_type
field oflock
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 vialock
, as described above forF_GETLK
.F_OFD_SETLK
- Acquire an open file description lock (whenl_type
isF_RDLCK
orF_WRLCK
) or release an open file description lock (whenl_type
isF_UNLCK
) on the bytes specified by thel_whence
,l_start
, andl_len
fields oflock
.If a conflicting lock is held by another process, this call returns -1 and sets
errno
toEAGAIN
.F_OFD_SETLKW
- As forF_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 toEINTR
; seesignal(7)
).F_SETLEASE
- Set or remove a file lease according to which of the following values is specified in the integerarg
:F_RDLCK
,F_WRLCK
,F_UNLCK
F_GETLEASE
- Indicates what type of lease is associated with the file descriptorfd
by returning eitherF_RDLCK
,F_WRLCK
, orF_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 byfd
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 inarg
, then notification will remain in effect until explicitly removed.A series of
F_NOTIFY
requests is cumulative, with the events inarg
being added to the set already monitored. To disable notification of all events, make anF_NOTIFY
call specifyingarg
as 0.Notification occurs via delivery of a signal. The default signal is
SIGIO
, but this can be changed using theF_SETSIG
command tofcntl()
. (Note thatSIGIO
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 asiginfo_t
structure as its second argument (if the handler was established usingSA_SIGINFO
) and thesi_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. Seeinotify(7)
.F_SETPIPE_SZ
- Change the capacity of the pipe referred to byfd
to be at leastarg
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
(seeproc(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 errorEPERM
; 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 byfd
.F_ADD_SEALS
- Add the seals given in the bit-mask argumentarg
to the set of seals of theinode
referred to by the file descriptorfd
.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 withEPERM
. Adding a seal that is already set is a no-op, in caseF_SEAL_SEAL
is not set already. In order to place a seal, the file descriptorfd
must be writable.F_GET_SEALS
- Return (as the function result) the current set of seals of theinode
referred to byfd
.If no seals are set, 0 is returned. If the file does not support sealing, -1 is returned and
errno
is set toEINVAL
.F_GET_RW_HINT
- Returns the value of the read/write hint associated with the underlyinginode
referred to byfd
.F_SET_RW_HINT
- Sets the read/write hint value associated with the underlyinginode
referred to byfd
.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 byfd
.F_SET_FILE_RW_HINT
- Sets the read/write hint value associated with the open file description referred to byfd
.F_DUPFD_CLOEXEC
- As forF_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 theFD_CLOEXEC
flag. For an explanation of why this flag is useful, see the description ofO_CLOEXEC
inopen(2)
.
- See Also:
-
F_SETOWN
public static final int F_SETOWNfcntl(int, int)
commands.Enum values:
F_DUPFD
- Duplicate the file descriptorfd
using the lowest-numbered available file descriptor greater than or equal toarg
.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 byarg
.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 byarg
.File access mode (
O_RDONLY
,O_WRONLY
,O_RDWR
) and file creation flags (i.e.,O_CREAT
,O_EXCL
,O_NOCTTY
,O_TRUNC
) inarg
are ignored. On Linux, this command can change only theO_APPEND
,O_ASYNC
,O_DIRECT
,O_NOATIME
, andO_NONBLOCK
flags. It is not possible to change theO_DSYNC
andO_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 returnsF_UNLCK
in thel_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 thel_type
,l_whence
,l_start
, andl_len
fields of lock. If the conflicting lock is a traditional (process-associated) record lock, then thel_pid
field is set to thePID
of the process holding that lock. If the conflicting lock is an open file description lock, thenl_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 (whenl_type
isF_RDLCK
orF_WRLCK
) or release a lock (whenl_type
isF_UNLCK
) on the bytes specified by thel_whence
,l_start
, andl_len
fields of lock.If a conflicting lock is held by another process, this call returns -1 and sets
errno
toEACCES
orEAGAIN
. (The error returned in this case differs across implementations, so POSIX requires a portable application to check for both errors.)F_SETLKW
- As forF_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
; seesignal(7)
).F_SETOWN
- Set the process ID or process group ID that will receiveSIGIO
andSIGURG
signals for events on the file descriptorfd
.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 asgetpid(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 theO_ASYNC
file status flag on the file descriptor. Subsequently, aSIGIO
signal is sent whenever input or output becomes possible on the file descriptor. Thefcntl()
F_SETSIG
command can be used to obtain delivery of a signal other thanSIGIO
.Sending a signal to the owner process (group) specified by
F_SETOWN
is subject to the same permissions checks as are described forkill(2)
, where the sending process is the one that employsF_SETOWN
(but see BUGS below). If this permission check fails, then the signal is silently discarded. Note: TheF_SETOWN
operation records the caller's credentials at the time of thefcntl()
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 ofSIGURG
signals that are delivered when out-of-band data arrives on that socket. (SIGURG
is sent in any situation whereselect(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 toF_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 passF_SETOWN
the result ofgettid(2)
instead ofgetpid(2)
to get sensible results whenF_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 usegettid(2)
orgetpid(2)
in this scenario.) Note, however, that the statements in this paragraph do not apply to theSIGURG
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 toF_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 targetSIGIO
andSIGURG
signals at a particular thread.F_GETOWN
- Return (as the function result) the process ID or process group ID currently receivingSIGIO
andSIGURG
signals for events on file descriptorfd
.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 inarg
.A value of zero means to send the default
SIGIO
signal. Any other value (includingSIGIO
) is the signal to send instead, and in this case additional info is available to the signal handler if installed withSA_SIGINFO
.By using
F_SETSIG
with a nonzero value, and settingSA_SIGINFO
for the signal handler (seesigaction(2)
), extra information about I/O events is passed to the handler in asiginfo_t
structure. If thesi_code
field indicates the source isSI_SIGIO
, thesi_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)
withO_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 theF_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 thesi_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 ifSA_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)
andsignal(7)
) and if this limit is reached, then the kernel reverts to deliveringSIGIO
, 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 (includingSIGIO
) is the signal sent instead, and in this case additional info is available to the signal handler if installed withSA_SIGINFO
.arg
is ignored.F_SETOWN_EX
- This operation performs a similar task toF_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 aFOwnerEx
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 previousF_SETOWN_EX
operation.The information is returned in the
FOwnerEx
structure pointed to byarg
.The type field will have one of the values
F_OWNER_TID
,F_OWNER_PID
, orF_OWNER_PGRP
. Thepid
field is a positive integer representing a thread ID, process ID, or process group ID. SeeF_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 returnsF_UNLCK
in thel_type
field oflock
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 vialock
, as described above forF_GETLK
.F_OFD_SETLK
- Acquire an open file description lock (whenl_type
isF_RDLCK
orF_WRLCK
) or release an open file description lock (whenl_type
isF_UNLCK
) on the bytes specified by thel_whence
,l_start
, andl_len
fields oflock
.If a conflicting lock is held by another process, this call returns -1 and sets
errno
toEAGAIN
.F_OFD_SETLKW
- As forF_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 toEINTR
; seesignal(7)
).F_SETLEASE
- Set or remove a file lease according to which of the following values is specified in the integerarg
:F_RDLCK
,F_WRLCK
,F_UNLCK
F_GETLEASE
- Indicates what type of lease is associated with the file descriptorfd
by returning eitherF_RDLCK
,F_WRLCK
, orF_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 byfd
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 inarg
, then notification will remain in effect until explicitly removed.A series of
F_NOTIFY
requests is cumulative, with the events inarg
being added to the set already monitored. To disable notification of all events, make anF_NOTIFY
call specifyingarg
as 0.Notification occurs via delivery of a signal. The default signal is
SIGIO
, but this can be changed using theF_SETSIG
command tofcntl()
. (Note thatSIGIO
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 asiginfo_t
structure as its second argument (if the handler was established usingSA_SIGINFO
) and thesi_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. Seeinotify(7)
.F_SETPIPE_SZ
- Change the capacity of the pipe referred to byfd
to be at leastarg
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
(seeproc(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 errorEPERM
; 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 byfd
.F_ADD_SEALS
- Add the seals given in the bit-mask argumentarg
to the set of seals of theinode
referred to by the file descriptorfd
.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 withEPERM
. Adding a seal that is already set is a no-op, in caseF_SEAL_SEAL
is not set already. In order to place a seal, the file descriptorfd
must be writable.F_GET_SEALS
- Return (as the function result) the current set of seals of theinode
referred to byfd
.If no seals are set, 0 is returned. If the file does not support sealing, -1 is returned and
errno
is set toEINVAL
.F_GET_RW_HINT
- Returns the value of the read/write hint associated with the underlyinginode
referred to byfd
.F_SET_RW_HINT
- Sets the read/write hint value associated with the underlyinginode
referred to byfd
.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 byfd
.F_SET_FILE_RW_HINT
- Sets the read/write hint value associated with the open file description referred to byfd
.F_DUPFD_CLOEXEC
- As forF_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 theFD_CLOEXEC
flag. For an explanation of why this flag is useful, see the description ofO_CLOEXEC
inopen(2)
.
- See Also:
-
F_GETOWN
public static final int F_GETOWNfcntl(int, int)
commands.Enum values:
F_DUPFD
- Duplicate the file descriptorfd
using the lowest-numbered available file descriptor greater than or equal toarg
.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 byarg
.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 byarg
.File access mode (
O_RDONLY
,O_WRONLY
,O_RDWR
) and file creation flags (i.e.,O_CREAT
,O_EXCL
,O_NOCTTY
,O_TRUNC
) inarg
are ignored. On Linux, this command can change only theO_APPEND
,O_ASYNC
,O_DIRECT
,O_NOATIME
, andO_NONBLOCK
flags. It is not possible to change theO_DSYNC
andO_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 returnsF_UNLCK
in thel_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 thel_type
,l_whence
,l_start
, andl_len
fields of lock. If the conflicting lock is a traditional (process-associated) record lock, then thel_pid
field is set to thePID
of the process holding that lock. If the conflicting lock is an open file description lock, thenl_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 (whenl_type
isF_RDLCK
orF_WRLCK
) or release a lock (whenl_type
isF_UNLCK
) on the bytes specified by thel_whence
,l_start
, andl_len
fields of lock.If a conflicting lock is held by another process, this call returns -1 and sets
errno
toEACCES
orEAGAIN
. (The error returned in this case differs across implementations, so POSIX requires a portable application to check for both errors.)F_SETLKW
- As forF_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
; seesignal(7)
).F_SETOWN
- Set the process ID or process group ID that will receiveSIGIO
andSIGURG
signals for events on the file descriptorfd
.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 asgetpid(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 theO_ASYNC
file status flag on the file descriptor. Subsequently, aSIGIO
signal is sent whenever input or output becomes possible on the file descriptor. Thefcntl()
F_SETSIG
command can be used to obtain delivery of a signal other thanSIGIO
.Sending a signal to the owner process (group) specified by
F_SETOWN
is subject to the same permissions checks as are described forkill(2)
, where the sending process is the one that employsF_SETOWN
(but see BUGS below). If this permission check fails, then the signal is silently discarded. Note: TheF_SETOWN
operation records the caller's credentials at the time of thefcntl()
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 ofSIGURG
signals that are delivered when out-of-band data arrives on that socket. (SIGURG
is sent in any situation whereselect(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 toF_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 passF_SETOWN
the result ofgettid(2)
instead ofgetpid(2)
to get sensible results whenF_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 usegettid(2)
orgetpid(2)
in this scenario.) Note, however, that the statements in this paragraph do not apply to theSIGURG
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 toF_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 targetSIGIO
andSIGURG
signals at a particular thread.F_GETOWN
- Return (as the function result) the process ID or process group ID currently receivingSIGIO
andSIGURG
signals for events on file descriptorfd
.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 inarg
.A value of zero means to send the default
SIGIO
signal. Any other value (includingSIGIO
) is the signal to send instead, and in this case additional info is available to the signal handler if installed withSA_SIGINFO
.By using
F_SETSIG
with a nonzero value, and settingSA_SIGINFO
for the signal handler (seesigaction(2)
), extra information about I/O events is passed to the handler in asiginfo_t
structure. If thesi_code
field indicates the source isSI_SIGIO
, thesi_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)
withO_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 theF_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 thesi_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 ifSA_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)
andsignal(7)
) and if this limit is reached, then the kernel reverts to deliveringSIGIO
, 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 (includingSIGIO
) is the signal sent instead, and in this case additional info is available to the signal handler if installed withSA_SIGINFO
.arg
is ignored.F_SETOWN_EX
- This operation performs a similar task toF_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 aFOwnerEx
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 previousF_SETOWN_EX
operation.The information is returned in the
FOwnerEx
structure pointed to byarg
.The type field will have one of the values
F_OWNER_TID
,F_OWNER_PID
, orF_OWNER_PGRP
. Thepid
field is a positive integer representing a thread ID, process ID, or process group ID. SeeF_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 returnsF_UNLCK
in thel_type
field oflock
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 vialock
, as described above forF_GETLK
.F_OFD_SETLK
- Acquire an open file description lock (whenl_type
isF_RDLCK
orF_WRLCK
) or release an open file description lock (whenl_type
isF_UNLCK
) on the bytes specified by thel_whence
,l_start
, andl_len
fields oflock
.If a conflicting lock is held by another process, this call returns -1 and sets
errno
toEAGAIN
.F_OFD_SETLKW
- As forF_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 toEINTR
; seesignal(7)
).F_SETLEASE
- Set or remove a file lease according to which of the following values is specified in the integerarg
:F_RDLCK
,F_WRLCK
,F_UNLCK
F_GETLEASE
- Indicates what type of lease is associated with the file descriptorfd
by returning eitherF_RDLCK
,F_WRLCK
, orF_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 byfd
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 inarg
, then notification will remain in effect until explicitly removed.A series of
F_NOTIFY
requests is cumulative, with the events inarg
being added to the set already monitored. To disable notification of all events, make anF_NOTIFY
call specifyingarg
as 0.Notification occurs via delivery of a signal. The default signal is
SIGIO
, but this can be changed using theF_SETSIG
command tofcntl()
. (Note thatSIGIO
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 asiginfo_t
structure as its second argument (if the handler was established usingSA_SIGINFO
) and thesi_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. Seeinotify(7)
.F_SETPIPE_SZ
- Change the capacity of the pipe referred to byfd
to be at leastarg
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
(seeproc(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 errorEPERM
; 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 byfd
.F_ADD_SEALS
- Add the seals given in the bit-mask argumentarg
to the set of seals of theinode
referred to by the file descriptorfd
.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 withEPERM
. Adding a seal that is already set is a no-op, in caseF_SEAL_SEAL
is not set already. In order to place a seal, the file descriptorfd
must be writable.F_GET_SEALS
- Return (as the function result) the current set of seals of theinode
referred to byfd
.If no seals are set, 0 is returned. If the file does not support sealing, -1 is returned and
errno
is set toEINVAL
.F_GET_RW_HINT
- Returns the value of the read/write hint associated with the underlyinginode
referred to byfd
.F_SET_RW_HINT
- Sets the read/write hint value associated with the underlyinginode
referred to byfd
.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 byfd
.F_SET_FILE_RW_HINT
- Sets the read/write hint value associated with the open file description referred to byfd
.F_DUPFD_CLOEXEC
- As forF_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 theFD_CLOEXEC
flag. For an explanation of why this flag is useful, see the description ofO_CLOEXEC
inopen(2)
.
- See Also:
-
F_SETSIG
public static final int F_SETSIGfcntl(int, int)
commands.Enum values:
F_DUPFD
- Duplicate the file descriptorfd
using the lowest-numbered available file descriptor greater than or equal toarg
.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 byarg
.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 byarg
.File access mode (
O_RDONLY
,O_WRONLY
,O_RDWR
) and file creation flags (i.e.,O_CREAT
,O_EXCL
,O_NOCTTY
,O_TRUNC
) inarg
are ignored. On Linux, this command can change only theO_APPEND
,O_ASYNC
,O_DIRECT
,O_NOATIME
, andO_NONBLOCK
flags. It is not possible to change theO_DSYNC
andO_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 returnsF_UNLCK
in thel_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 thel_type
,l_whence
,l_start
, andl_len
fields of lock. If the conflicting lock is a traditional (process-associated) record lock, then thel_pid
field is set to thePID
of the process holding that lock. If the conflicting lock is an open file description lock, thenl_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 (whenl_type
isF_RDLCK
orF_WRLCK
) or release a lock (whenl_type
isF_UNLCK
) on the bytes specified by thel_whence
,l_start
, andl_len
fields of lock.If a conflicting lock is held by another process, this call returns -1 and sets
errno
toEACCES
orEAGAIN
. (The error returned in this case differs across implementations, so POSIX requires a portable application to check for both errors.)F_SETLKW
- As forF_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
; seesignal(7)
).F_SETOWN
- Set the process ID or process group ID that will receiveSIGIO
andSIGURG
signals for events on the file descriptorfd
.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 asgetpid(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 theO_ASYNC
file status flag on the file descriptor. Subsequently, aSIGIO
signal is sent whenever input or output becomes possible on the file descriptor. Thefcntl()
F_SETSIG
command can be used to obtain delivery of a signal other thanSIGIO
.Sending a signal to the owner process (group) specified by
F_SETOWN
is subject to the same permissions checks as are described forkill(2)
, where the sending process is the one that employsF_SETOWN
(but see BUGS below). If this permission check fails, then the signal is silently discarded. Note: TheF_SETOWN
operation records the caller's credentials at the time of thefcntl()
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 ofSIGURG
signals that are delivered when out-of-band data arrives on that socket. (SIGURG
is sent in any situation whereselect(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 toF_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 passF_SETOWN
the result ofgettid(2)
instead ofgetpid(2)
to get sensible results whenF_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 usegettid(2)
orgetpid(2)
in this scenario.) Note, however, that the statements in this paragraph do not apply to theSIGURG
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 toF_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 targetSIGIO
andSIGURG
signals at a particular thread.F_GETOWN
- Return (as the function result) the process ID or process group ID currently receivingSIGIO
andSIGURG
signals for events on file descriptorfd
.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 inarg
.A value of zero means to send the default
SIGIO
signal. Any other value (includingSIGIO
) is the signal to send instead, and in this case additional info is available to the signal handler if installed withSA_SIGINFO
.By using
F_SETSIG
with a nonzero value, and settingSA_SIGINFO
for the signal handler (seesigaction(2)
), extra information about I/O events is passed to the handler in asiginfo_t
structure. If thesi_code
field indicates the source isSI_SIGIO
, thesi_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)
withO_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 theF_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 thesi_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 ifSA_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)
andsignal(7)
) and if this limit is reached, then the kernel reverts to deliveringSIGIO
, 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 (includingSIGIO
) is the signal sent instead, and in this case additional info is available to the signal handler if installed withSA_SIGINFO
.arg
is ignored.F_SETOWN_EX
- This operation performs a similar task toF_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 aFOwnerEx
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 previousF_SETOWN_EX
operation.The information is returned in the
FOwnerEx
structure pointed to byarg
.The type field will have one of the values
F_OWNER_TID
,F_OWNER_PID
, orF_OWNER_PGRP
. Thepid
field is a positive integer representing a thread ID, process ID, or process group ID. SeeF_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 returnsF_UNLCK
in thel_type
field oflock
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 vialock
, as described above forF_GETLK
.F_OFD_SETLK
- Acquire an open file description lock (whenl_type
isF_RDLCK
orF_WRLCK
) or release an open file description lock (whenl_type
isF_UNLCK
) on the bytes specified by thel_whence
,l_start
, andl_len
fields oflock
.If a conflicting lock is held by another process, this call returns -1 and sets
errno
toEAGAIN
.F_OFD_SETLKW
- As forF_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 toEINTR
; seesignal(7)
).F_SETLEASE
- Set or remove a file lease according to which of the following values is specified in the integerarg
:F_RDLCK
,F_WRLCK
,F_UNLCK
F_GETLEASE
- Indicates what type of lease is associated with the file descriptorfd
by returning eitherF_RDLCK
,F_WRLCK
, orF_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 byfd
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 inarg
, then notification will remain in effect until explicitly removed.A series of
F_NOTIFY
requests is cumulative, with the events inarg
being added to the set already monitored. To disable notification of all events, make anF_NOTIFY
call specifyingarg
as 0.Notification occurs via delivery of a signal. The default signal is
SIGIO
, but this can be changed using theF_SETSIG
command tofcntl()
. (Note thatSIGIO
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 asiginfo_t
structure as its second argument (if the handler was established usingSA_SIGINFO
) and thesi_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. Seeinotify(7)
.F_SETPIPE_SZ
- Change the capacity of the pipe referred to byfd
to be at leastarg
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
(seeproc(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 errorEPERM
; 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 byfd
.F_ADD_SEALS
- Add the seals given in the bit-mask argumentarg
to the set of seals of theinode
referred to by the file descriptorfd
.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 withEPERM
. Adding a seal that is already set is a no-op, in caseF_SEAL_SEAL
is not set already. In order to place a seal, the file descriptorfd
must be writable.F_GET_SEALS
- Return (as the function result) the current set of seals of theinode
referred to byfd
.If no seals are set, 0 is returned. If the file does not support sealing, -1 is returned and
errno
is set toEINVAL
.F_GET_RW_HINT
- Returns the value of the read/write hint associated with the underlyinginode
referred to byfd
.F_SET_RW_HINT
- Sets the read/write hint value associated with the underlyinginode
referred to byfd
.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 byfd
.F_SET_FILE_RW_HINT
- Sets the read/write hint value associated with the open file description referred to byfd
.F_DUPFD_CLOEXEC
- As forF_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 theFD_CLOEXEC
flag. For an explanation of why this flag is useful, see the description ofO_CLOEXEC
inopen(2)
.
- See Also:
-
F_GETSIG
public static final int F_GETSIGfcntl(int, int)
commands.Enum values:
F_DUPFD
- Duplicate the file descriptorfd
using the lowest-numbered available file descriptor greater than or equal toarg
.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 byarg
.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 byarg
.File access mode (
O_RDONLY
,O_WRONLY
,O_RDWR
) and file creation flags (i.e.,O_CREAT
,O_EXCL
,O_NOCTTY
,O_TRUNC
) inarg
are ignored. On Linux, this command can change only theO_APPEND
,O_ASYNC
,O_DIRECT
,O_NOATIME
, andO_NONBLOCK
flags. It is not possible to change theO_DSYNC
andO_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 returnsF_UNLCK
in thel_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 thel_type
,l_whence
,l_start
, andl_len
fields of lock. If the conflicting lock is a traditional (process-associated) record lock, then thel_pid
field is set to thePID
of the process holding that lock. If the conflicting lock is an open file description lock, thenl_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 (whenl_type
isF_RDLCK
orF_WRLCK
) or release a lock (whenl_type
isF_UNLCK
) on the bytes specified by thel_whence
,l_start
, andl_len
fields of lock.If a conflicting lock is held by another process, this call returns -1 and sets
errno
toEACCES
orEAGAIN
. (The error returned in this case differs across implementations, so POSIX requires a portable application to check for both errors.)F_SETLKW
- As forF_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
; seesignal(7)
).F_SETOWN
- Set the process ID or process group ID that will receiveSIGIO
andSIGURG
signals for events on the file descriptorfd
.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 asgetpid(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 theO_ASYNC
file status flag on the file descriptor. Subsequently, aSIGIO
signal is sent whenever input or output becomes possible on the file descriptor. Thefcntl()
F_SETSIG
command can be used to obtain delivery of a signal other thanSIGIO
.Sending a signal to the owner process (group) specified by
F_SETOWN
is subject to the same permissions checks as are described forkill(2)
, where the sending process is the one that employsF_SETOWN
(but see BUGS below). If this permission check fails, then the signal is silently discarded. Note: TheF_SETOWN
operation records the caller's credentials at the time of thefcntl()
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 ofSIGURG
signals that are delivered when out-of-band data arrives on that socket. (SIGURG
is sent in any situation whereselect(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 toF_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 passF_SETOWN
the result ofgettid(2)
instead ofgetpid(2)
to get sensible results whenF_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 usegettid(2)
orgetpid(2)
in this scenario.) Note, however, that the statements in this paragraph do not apply to theSIGURG
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 toF_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 targetSIGIO
andSIGURG
signals at a particular thread.F_GETOWN
- Return (as the function result) the process ID or process group ID currently receivingSIGIO
andSIGURG
signals for events on file descriptorfd
.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 inarg
.A value of zero means to send the default
SIGIO
signal. Any other value (includingSIGIO
) is the signal to send instead, and in this case additional info is available to the signal handler if installed withSA_SIGINFO
.By using
F_SETSIG
with a nonzero value, and settingSA_SIGINFO
for the signal handler (seesigaction(2)
), extra information about I/O events is passed to the handler in asiginfo_t
structure. If thesi_code
field indicates the source isSI_SIGIO
, thesi_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)
withO_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 theF_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 thesi_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 ifSA_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)
andsignal(7)
) and if this limit is reached, then the kernel reverts to deliveringSIGIO
, 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 (includingSIGIO
) is the signal sent instead, and in this case additional info is available to the signal handler if installed withSA_SIGINFO
.arg
is ignored.F_SETOWN_EX
- This operation performs a similar task toF_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 aFOwnerEx
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 previousF_SETOWN_EX
operation.The information is returned in the
FOwnerEx
structure pointed to byarg
.The type field will have one of the values
F_OWNER_TID
,F_OWNER_PID
, orF_OWNER_PGRP
. Thepid
field is a positive integer representing a thread ID, process ID, or process group ID. SeeF_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 returnsF_UNLCK
in thel_type
field oflock
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 vialock
, as described above forF_GETLK
.F_OFD_SETLK
- Acquire an open file description lock (whenl_type
isF_RDLCK
orF_WRLCK
) or release an open file description lock (whenl_type
isF_UNLCK
) on the bytes specified by thel_whence
,l_start
, andl_len
fields oflock
.If a conflicting lock is held by another process, this call returns -1 and sets
errno
toEAGAIN
.F_OFD_SETLKW
- As forF_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 toEINTR
; seesignal(7)
).F_SETLEASE
- Set or remove a file lease according to which of the following values is specified in the integerarg
:F_RDLCK
,F_WRLCK
,F_UNLCK
F_GETLEASE
- Indicates what type of lease is associated with the file descriptorfd
by returning eitherF_RDLCK
,F_WRLCK
, orF_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 byfd
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 inarg
, then notification will remain in effect until explicitly removed.A series of
F_NOTIFY
requests is cumulative, with the events inarg
being added to the set already monitored. To disable notification of all events, make anF_NOTIFY
call specifyingarg
as 0.Notification occurs via delivery of a signal. The default signal is
SIGIO
, but this can be changed using theF_SETSIG
command tofcntl()
. (Note thatSIGIO
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 asiginfo_t
structure as its second argument (if the handler was established usingSA_SIGINFO
) and thesi_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. Seeinotify(7)
.F_SETPIPE_SZ
- Change the capacity of the pipe referred to byfd
to be at leastarg
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
(seeproc(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 errorEPERM
; 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 byfd
.F_ADD_SEALS
- Add the seals given in the bit-mask argumentarg
to the set of seals of theinode
referred to by the file descriptorfd
.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 withEPERM
. Adding a seal that is already set is a no-op, in caseF_SEAL_SEAL
is not set already. In order to place a seal, the file descriptorfd
must be writable.F_GET_SEALS
- Return (as the function result) the current set of seals of theinode
referred to byfd
.If no seals are set, 0 is returned. If the file does not support sealing, -1 is returned and
errno
is set toEINVAL
.F_GET_RW_HINT
- Returns the value of the read/write hint associated with the underlyinginode
referred to byfd
.F_SET_RW_HINT
- Sets the read/write hint value associated with the underlyinginode
referred to byfd
.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 byfd
.F_SET_FILE_RW_HINT
- Sets the read/write hint value associated with the open file description referred to byfd
.F_DUPFD_CLOEXEC
- As forF_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 theFD_CLOEXEC
flag. For an explanation of why this flag is useful, see the description ofO_CLOEXEC
inopen(2)
.
- See Also:
-
F_SETOWN_EX
public static final int F_SETOWN_EXfcntl(int, int)
commands.Enum values:
F_DUPFD
- Duplicate the file descriptorfd
using the lowest-numbered available file descriptor greater than or equal toarg
.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 byarg
.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 byarg
.File access mode (
O_RDONLY
,O_WRONLY
,O_RDWR
) and file creation flags (i.e.,O_CREAT
,O_EXCL
,O_NOCTTY
,O_TRUNC
) inarg
are ignored. On Linux, this command can change only theO_APPEND
,O_ASYNC
,O_DIRECT
,O_NOATIME
, andO_NONBLOCK
flags. It is not possible to change theO_DSYNC
andO_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 returnsF_UNLCK
in thel_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 thel_type
,l_whence
,l_start
, andl_len
fields of lock. If the conflicting lock is a traditional (process-associated) record lock, then thel_pid
field is set to thePID
of the process holding that lock. If the conflicting lock is an open file description lock, thenl_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 (whenl_type
isF_RDLCK
orF_WRLCK
) or release a lock (whenl_type
isF_UNLCK
) on the bytes specified by thel_whence
,l_start
, andl_len
fields of lock.If a conflicting lock is held by another process, this call returns -1 and sets
errno
toEACCES
orEAGAIN
. (The error returned in this case differs across implementations, so POSIX requires a portable application to check for both errors.)F_SETLKW
- As forF_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
; seesignal(7)
).F_SETOWN
- Set the process ID or process group ID that will receiveSIGIO
andSIGURG
signals for events on the file descriptorfd
.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 asgetpid(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 theO_ASYNC
file status flag on the file descriptor. Subsequently, aSIGIO
signal is sent whenever input or output becomes possible on the file descriptor. Thefcntl()
F_SETSIG
command can be used to obtain delivery of a signal other thanSIGIO
.Sending a signal to the owner process (group) specified by
F_SETOWN
is subject to the same permissions checks as are described forkill(2)
, where the sending process is the one that employsF_SETOWN
(but see BUGS below). If this permission check fails, then the signal is silently discarded. Note: TheF_SETOWN
operation records the caller's credentials at the time of thefcntl()
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 ofSIGURG
signals that are delivered when out-of-band data arrives on that socket. (SIGURG
is sent in any situation whereselect(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 toF_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 passF_SETOWN
the result ofgettid(2)
instead ofgetpid(2)
to get sensible results whenF_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 usegettid(2)
orgetpid(2)
in this scenario.) Note, however, that the statements in this paragraph do not apply to theSIGURG
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 toF_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 targetSIGIO
andSIGURG
signals at a particular thread.F_GETOWN
- Return (as the function result) the process ID or process group ID currently receivingSIGIO
andSIGURG
signals for events on file descriptorfd
.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 inarg
.A value of zero means to send the default
SIGIO
signal. Any other value (includingSIGIO
) is the signal to send instead, and in this case additional info is available to the signal handler if installed withSA_SIGINFO
.By using
F_SETSIG
with a nonzero value, and settingSA_SIGINFO
for the signal handler (seesigaction(2)
), extra information about I/O events is passed to the handler in asiginfo_t
structure. If thesi_code
field indicates the source isSI_SIGIO
, thesi_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)
withO_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 theF_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 thesi_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 ifSA_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)
andsignal(7)
) and if this limit is reached, then the kernel reverts to deliveringSIGIO
, 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 (includingSIGIO
) is the signal sent instead, and in this case additional info is available to the signal handler if installed withSA_SIGINFO
.arg
is ignored.F_SETOWN_EX
- This operation performs a similar task toF_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 aFOwnerEx
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 previousF_SETOWN_EX
operation.The information is returned in the
FOwnerEx
structure pointed to byarg
.The type field will have one of the values
F_OWNER_TID
,F_OWNER_PID
, orF_OWNER_PGRP
. Thepid
field is a positive integer representing a thread ID, process ID, or process group ID. SeeF_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 returnsF_UNLCK
in thel_type
field oflock
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 vialock
, as described above forF_GETLK
.F_OFD_SETLK
- Acquire an open file description lock (whenl_type
isF_RDLCK
orF_WRLCK
) or release an open file description lock (whenl_type
isF_UNLCK
) on the bytes specified by thel_whence
,l_start
, andl_len
fields oflock
.If a conflicting lock is held by another process, this call returns -1 and sets
errno
toEAGAIN
.F_OFD_SETLKW
- As forF_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 toEINTR
; seesignal(7)
).F_SETLEASE
- Set or remove a file lease according to which of the following values is specified in the integerarg
:F_RDLCK
,F_WRLCK
,F_UNLCK
F_GETLEASE
- Indicates what type of lease is associated with the file descriptorfd
by returning eitherF_RDLCK
,F_WRLCK
, orF_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 byfd
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 inarg
, then notification will remain in effect until explicitly removed.A series of
F_NOTIFY
requests is cumulative, with the events inarg
being added to the set already monitored. To disable notification of all events, make anF_NOTIFY
call specifyingarg
as 0.Notification occurs via delivery of a signal. The default signal is
SIGIO
, but this can be changed using theF_SETSIG
command tofcntl()
. (Note thatSIGIO
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 asiginfo_t
structure as its second argument (if the handler was established usingSA_SIGINFO
) and thesi_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. Seeinotify(7)
.F_SETPIPE_SZ
- Change the capacity of the pipe referred to byfd
to be at leastarg
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
(seeproc(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 errorEPERM
; 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 byfd
.F_ADD_SEALS
- Add the seals given in the bit-mask argumentarg
to the set of seals of theinode
referred to by the file descriptorfd
.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 withEPERM
. Adding a seal that is already set is a no-op, in caseF_SEAL_SEAL
is not set already. In order to place a seal, the file descriptorfd
must be writable.F_GET_SEALS
- Return (as the function result) the current set of seals of theinode
referred to byfd
.If no seals are set, 0 is returned. If the file does not support sealing, -1 is returned and
errno
is set toEINVAL
.F_GET_RW_HINT
- Returns the value of the read/write hint associated with the underlyinginode
referred to byfd
.F_SET_RW_HINT
- Sets the read/write hint value associated with the underlyinginode
referred to byfd
.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 byfd
.F_SET_FILE_RW_HINT
- Sets the read/write hint value associated with the open file description referred to byfd
.F_DUPFD_CLOEXEC
- As forF_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 theFD_CLOEXEC
flag. For an explanation of why this flag is useful, see the description ofO_CLOEXEC
inopen(2)
.
- See Also:
-
F_GETOWN_EX
public static final int F_GETOWN_EXfcntl(int, int)
commands.Enum values:
F_DUPFD
- Duplicate the file descriptorfd
using the lowest-numbered available file descriptor greater than or equal toarg
.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 byarg
.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 byarg
.File access mode (
O_RDONLY
,O_WRONLY
,O_RDWR
) and file creation flags (i.e.,O_CREAT
,O_EXCL
,O_NOCTTY
,O_TRUNC
) inarg
are ignored. On Linux, this command can change only theO_APPEND
,O_ASYNC
,O_DIRECT
,O_NOATIME
, andO_NONBLOCK
flags. It is not possible to change theO_DSYNC
andO_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 returnsF_UNLCK
in thel_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 thel_type
,l_whence
,l_start
, andl_len
fields of lock. If the conflicting lock is a traditional (process-associated) record lock, then thel_pid
field is set to thePID
of the process holding that lock. If the conflicting lock is an open file description lock, thenl_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 (whenl_type
isF_RDLCK
orF_WRLCK
) or release a lock (whenl_type
isF_UNLCK
) on the bytes specified by thel_whence
,l_start
, andl_len
fields of lock.If a conflicting lock is held by another process, this call returns -1 and sets
errno
toEACCES
orEAGAIN
. (The error returned in this case differs across implementations, so POSIX requires a portable application to check for both errors.)F_SETLKW
- As forF_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
; seesignal(7)
).F_SETOWN
- Set the process ID or process group ID that will receiveSIGIO
andSIGURG
signals for events on the file descriptorfd
.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 asgetpid(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 theO_ASYNC
file status flag on the file descriptor. Subsequently, aSIGIO
signal is sent whenever input or output becomes possible on the file descriptor. Thefcntl()
F_SETSIG
command can be used to obtain delivery of a signal other thanSIGIO
.Sending a signal to the owner process (group) specified by
F_SETOWN
is subject to the same permissions checks as are described forkill(2)
, where the sending process is the one that employsF_SETOWN
(but see BUGS below). If this permission check fails, then the signal is silently discarded. Note: TheF_SETOWN
operation records the caller's credentials at the time of thefcntl()
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 ofSIGURG
signals that are delivered when out-of-band data arrives on that socket. (SIGURG
is sent in any situation whereselect(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 toF_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 passF_SETOWN
the result ofgettid(2)
instead ofgetpid(2)
to get sensible results whenF_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 usegettid(2)
orgetpid(2)
in this scenario.) Note, however, that the statements in this paragraph do not apply to theSIGURG
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 toF_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 targetSIGIO
andSIGURG
signals at a particular thread.F_GETOWN
- Return (as the function result) the process ID or process group ID currently receivingSIGIO
andSIGURG
signals for events on file descriptorfd
.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 inarg
.A value of zero means to send the default
SIGIO
signal. Any other value (includingSIGIO
) is the signal to send instead, and in this case additional info is available to the signal handler if installed withSA_SIGINFO
.By using
F_SETSIG
with a nonzero value, and settingSA_SIGINFO
for the signal handler (seesigaction(2)
), extra information about I/O events is passed to the handler in asiginfo_t
structure. If thesi_code
field indicates the source isSI_SIGIO
, thesi_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)
withO_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 theF_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 thesi_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 ifSA_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)
andsignal(7)
) and if this limit is reached, then the kernel reverts to deliveringSIGIO
, 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 (includingSIGIO
) is the signal sent instead, and in this case additional info is available to the signal handler if installed withSA_SIGINFO
.arg
is ignored.F_SETOWN_EX
- This operation performs a similar task toF_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 aFOwnerEx
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 previousF_SETOWN_EX
operation.The information is returned in the
FOwnerEx
structure pointed to byarg
.The type field will have one of the values
F_OWNER_TID
,F_OWNER_PID
, orF_OWNER_PGRP
. Thepid
field is a positive integer representing a thread ID, process ID, or process group ID. SeeF_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 returnsF_UNLCK
in thel_type
field oflock
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 vialock
, as described above forF_GETLK
.F_OFD_SETLK
- Acquire an open file description lock (whenl_type
isF_RDLCK
orF_WRLCK
) or release an open file description lock (whenl_type
isF_UNLCK
) on the bytes specified by thel_whence
,l_start
, andl_len
fields oflock
.If a conflicting lock is held by another process, this call returns -1 and sets
errno
toEAGAIN
.F_OFD_SETLKW
- As forF_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 toEINTR
; seesignal(7)
).F_SETLEASE
- Set or remove a file lease according to which of the following values is specified in the integerarg
:F_RDLCK
,F_WRLCK
,F_UNLCK
F_GETLEASE
- Indicates what type of lease is associated with the file descriptorfd
by returning eitherF_RDLCK
,F_WRLCK
, orF_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 byfd
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 inarg
, then notification will remain in effect until explicitly removed.A series of
F_NOTIFY
requests is cumulative, with the events inarg
being added to the set already monitored. To disable notification of all events, make anF_NOTIFY
call specifyingarg
as 0.Notification occurs via delivery of a signal. The default signal is
SIGIO
, but this can be changed using theF_SETSIG
command tofcntl()
. (Note thatSIGIO
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 asiginfo_t
structure as its second argument (if the handler was established usingSA_SIGINFO
) and thesi_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. Seeinotify(7)
.F_SETPIPE_SZ
- Change the capacity of the pipe referred to byfd
to be at leastarg
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
(seeproc(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 errorEPERM
; 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 byfd
.F_ADD_SEALS
- Add the seals given in the bit-mask argumentarg
to the set of seals of theinode
referred to by the file descriptorfd
.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 withEPERM
. Adding a seal that is already set is a no-op, in caseF_SEAL_SEAL
is not set already. In order to place a seal, the file descriptorfd
must be writable.F_GET_SEALS
- Return (as the function result) the current set of seals of theinode
referred to byfd
.If no seals are set, 0 is returned. If the file does not support sealing, -1 is returned and
errno
is set toEINVAL
.F_GET_RW_HINT
- Returns the value of the read/write hint associated with the underlyinginode
referred to byfd
.F_SET_RW_HINT
- Sets the read/write hint value associated with the underlyinginode
referred to byfd
.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 byfd
.F_SET_FILE_RW_HINT
- Sets the read/write hint value associated with the open file description referred to byfd
.F_DUPFD_CLOEXEC
- As forF_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 theFD_CLOEXEC
flag. For an explanation of why this flag is useful, see the description ofO_CLOEXEC
inopen(2)
.
- See Also:
-
F_OFD_GETLK
public static final int F_OFD_GETLKfcntl(int, int)
commands.Enum values:
F_DUPFD
- Duplicate the file descriptorfd
using the lowest-numbered available file descriptor greater than or equal toarg
.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 byarg
.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 byarg
.File access mode (
O_RDONLY
,O_WRONLY
,O_RDWR
) and file creation flags (i.e.,O_CREAT
,O_EXCL
,O_NOCTTY
,O_TRUNC
) inarg
are ignored. On Linux, this command can change only theO_APPEND
,O_ASYNC
,O_DIRECT
,O_NOATIME
, andO_NONBLOCK
flags. It is not possible to change theO_DSYNC
andO_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 returnsF_UNLCK
in thel_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 thel_type
,l_whence
,l_start
, andl_len
fields of lock. If the conflicting lock is a traditional (process-associated) record lock, then thel_pid
field is set to thePID
of the process holding that lock. If the conflicting lock is an open file description lock, thenl_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 (whenl_type
isF_RDLCK
orF_WRLCK
) or release a lock (whenl_type
isF_UNLCK
) on the bytes specified by thel_whence
,l_start
, andl_len
fields of lock.If a conflicting lock is held by another process, this call returns -1 and sets
errno
toEACCES
orEAGAIN
. (The error returned in this case differs across implementations, so POSIX requires a portable application to check for both errors.)F_SETLKW
- As forF_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
; seesignal(7)
).F_SETOWN
- Set the process ID or process group ID that will receiveSIGIO
andSIGURG
signals for events on the file descriptorfd
.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 asgetpid(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 theO_ASYNC
file status flag on the file descriptor. Subsequently, aSIGIO
signal is sent whenever input or output becomes possible on the file descriptor. Thefcntl()
F_SETSIG
command can be used to obtain delivery of a signal other thanSIGIO
.Sending a signal to the owner process (group) specified by
F_SETOWN
is subject to the same permissions checks as are described forkill(2)
, where the sending process is the one that employsF_SETOWN
(but see BUGS below). If this permission check fails, then the signal is silently discarded. Note: TheF_SETOWN
operation records the caller's credentials at the time of thefcntl()
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 ofSIGURG
signals that are delivered when out-of-band data arrives on that socket. (SIGURG
is sent in any situation whereselect(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 toF_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 passF_SETOWN
the result ofgettid(2)
instead ofgetpid(2)
to get sensible results whenF_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 usegettid(2)
orgetpid(2)
in this scenario.) Note, however, that the statements in this paragraph do not apply to theSIGURG
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 toF_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 targetSIGIO
andSIGURG
signals at a particular thread.F_GETOWN
- Return (as the function result) the process ID or process group ID currently receivingSIGIO
andSIGURG
signals for events on file descriptorfd
.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 inarg
.A value of zero means to send the default
SIGIO
signal. Any other value (includingSIGIO
) is the signal to send instead, and in this case additional info is available to the signal handler if installed withSA_SIGINFO
.By using
F_SETSIG
with a nonzero value, and settingSA_SIGINFO
for the signal handler (seesigaction(2)
), extra information about I/O events is passed to the handler in asiginfo_t
structure. If thesi_code
field indicates the source isSI_SIGIO
, thesi_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)
withO_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 theF_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 thesi_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 ifSA_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)
andsignal(7)
) and if this limit is reached, then the kernel reverts to deliveringSIGIO
, 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 (includingSIGIO
) is the signal sent instead, and in this case additional info is available to the signal handler if installed withSA_SIGINFO
.arg
is ignored.F_SETOWN_EX
- This operation performs a similar task toF_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 aFOwnerEx
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 previousF_SETOWN_EX
operation.The information is returned in the
FOwnerEx
structure pointed to byarg
.The type field will have one of the values
F_OWNER_TID
,F_OWNER_PID
, orF_OWNER_PGRP
. Thepid
field is a positive integer representing a thread ID, process ID, or process group ID. SeeF_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 returnsF_UNLCK
in thel_type
field oflock
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 vialock
, as described above forF_GETLK
.F_OFD_SETLK
- Acquire an open file description lock (whenl_type
isF_RDLCK
orF_WRLCK
) or release an open file description lock (whenl_type
isF_UNLCK
) on the bytes specified by thel_whence
,l_start
, andl_len
fields oflock
.If a conflicting lock is held by another process, this call returns -1 and sets
errno
toEAGAIN
.F_OFD_SETLKW
- As forF_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 toEINTR
; seesignal(7)
).F_SETLEASE
- Set or remove a file lease according to which of the following values is specified in the integerarg
:F_RDLCK
,F_WRLCK
,F_UNLCK
F_GETLEASE
- Indicates what type of lease is associated with the file descriptorfd
by returning eitherF_RDLCK
,F_WRLCK
, orF_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 byfd
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 inarg
, then notification will remain in effect until explicitly removed.A series of
F_NOTIFY
requests is cumulative, with the events inarg
being added to the set already monitored. To disable notification of all events, make anF_NOTIFY
call specifyingarg
as 0.Notification occurs via delivery of a signal. The default signal is
SIGIO
, but this can be changed using theF_SETSIG
command tofcntl()
. (Note thatSIGIO
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 asiginfo_t
structure as its second argument (if the handler was established usingSA_SIGINFO
) and thesi_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. Seeinotify(7)
.F_SETPIPE_SZ
- Change the capacity of the pipe referred to byfd
to be at leastarg
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
(seeproc(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 errorEPERM
; 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 byfd
.F_ADD_SEALS
- Add the seals given in the bit-mask argumentarg
to the set of seals of theinode
referred to by the file descriptorfd
.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 withEPERM
. Adding a seal that is already set is a no-op, in caseF_SEAL_SEAL
is not set already. In order to place a seal, the file descriptorfd
must be writable.F_GET_SEALS
- Return (as the function result) the current set of seals of theinode
referred to byfd
.If no seals are set, 0 is returned. If the file does not support sealing, -1 is returned and
errno
is set toEINVAL
.F_GET_RW_HINT
- Returns the value of the read/write hint associated with the underlyinginode
referred to byfd
.F_SET_RW_HINT
- Sets the read/write hint value associated with the underlyinginode
referred to byfd
.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 byfd
.F_SET_FILE_RW_HINT
- Sets the read/write hint value associated with the open file description referred to byfd
.F_DUPFD_CLOEXEC
- As forF_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 theFD_CLOEXEC
flag. For an explanation of why this flag is useful, see the description ofO_CLOEXEC
inopen(2)
.
- See Also:
-
F_OFD_SETLK
public static final int F_OFD_SETLKfcntl(int, int)
commands.Enum values:
F_DUPFD
- Duplicate the file descriptorfd
using the lowest-numbered available file descriptor greater than or equal toarg
.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 byarg
.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 byarg
.File access mode (
O_RDONLY
,O_WRONLY
,O_RDWR
) and file creation flags (i.e.,O_CREAT
,O_EXCL
,O_NOCTTY
,O_TRUNC
) inarg
are ignored. On Linux, this command can change only theO_APPEND
,O_ASYNC
,O_DIRECT
,O_NOATIME
, andO_NONBLOCK
flags. It is not possible to change theO_DSYNC
andO_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 returnsF_UNLCK
in thel_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 thel_type
,l_whence
,l_start
, andl_len
fields of lock. If the conflicting lock is a traditional (process-associated) record lock, then thel_pid
field is set to thePID
of the process holding that lock. If the conflicting lock is an open file description lock, thenl_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 (whenl_type
isF_RDLCK
orF_WRLCK
) or release a lock (whenl_type
isF_UNLCK
) on the bytes specified by thel_whence
,l_start
, andl_len
fields of lock.If a conflicting lock is held by another process, this call returns -1 and sets
errno
toEACCES
orEAGAIN
. (The error returned in this case differs across implementations, so POSIX requires a portable application to check for both errors.)F_SETLKW
- As forF_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
; seesignal(7)
).F_SETOWN
- Set the process ID or process group ID that will receiveSIGIO
andSIGURG
signals for events on the file descriptorfd
.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 asgetpid(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 theO_ASYNC
file status flag on the file descriptor. Subsequently, aSIGIO
signal is sent whenever input or output becomes possible on the file descriptor. Thefcntl()
F_SETSIG
command can be used to obtain delivery of a signal other thanSIGIO
.Sending a signal to the owner process (group) specified by
F_SETOWN
is subject to the same permissions checks as are described forkill(2)
, where the sending process is the one that employsF_SETOWN
(but see BUGS below). If this permission check fails, then the signal is silently discarded. Note: TheF_SETOWN
operation records the caller's credentials at the time of thefcntl()
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 ofSIGURG
signals that are delivered when out-of-band data arrives on that socket. (SIGURG
is sent in any situation whereselect(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 toF_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 passF_SETOWN
the result ofgettid(2)
instead ofgetpid(2)
to get sensible results whenF_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 usegettid(2)
orgetpid(2)
in this scenario.) Note, however, that the statements in this paragraph do not apply to theSIGURG
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 toF_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 targetSIGIO
andSIGURG
signals at a particular thread.F_GETOWN
- Return (as the function result) the process ID or process group ID currently receivingSIGIO
andSIGURG
signals for events on file descriptorfd
.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 inarg
.A value of zero means to send the default
SIGIO
signal. Any other value (includingSIGIO
) is the signal to send instead, and in this case additional info is available to the signal handler if installed withSA_SIGINFO
.By using
F_SETSIG
with a nonzero value, and settingSA_SIGINFO
for the signal handler (seesigaction(2)
), extra information about I/O events is passed to the handler in asiginfo_t
structure. If thesi_code
field indicates the source isSI_SIGIO
, thesi_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)
withO_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 theF_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 thesi_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 ifSA_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)
andsignal(7)
) and if this limit is reached, then the kernel reverts to deliveringSIGIO
, 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 (includingSIGIO
) is the signal sent instead, and in this case additional info is available to the signal handler if installed withSA_SIGINFO
.arg
is ignored.F_SETOWN_EX
- This operation performs a similar task toF_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 aFOwnerEx
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 previousF_SETOWN_EX
operation.The information is returned in the
FOwnerEx
structure pointed to byarg
.The type field will have one of the values
F_OWNER_TID
,F_OWNER_PID
, orF_OWNER_PGRP
. Thepid
field is a positive integer representing a thread ID, process ID, or process group ID. SeeF_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 returnsF_UNLCK
in thel_type
field oflock
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 vialock
, as described above forF_GETLK
.F_OFD_SETLK
- Acquire an open file description lock (whenl_type
isF_RDLCK
orF_WRLCK
) or release an open file description lock (whenl_type
isF_UNLCK
) on the bytes specified by thel_whence
,l_start
, andl_len
fields oflock
.If a conflicting lock is held by another process, this call returns -1 and sets
errno
toEAGAIN
.F_OFD_SETLKW
- As forF_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 toEINTR
; seesignal(7)
).F_SETLEASE
- Set or remove a file lease according to which of the following values is specified in the integerarg
:F_RDLCK
,F_WRLCK
,F_UNLCK
F_GETLEASE
- Indicates what type of lease is associated with the file descriptorfd
by returning eitherF_RDLCK
,F_WRLCK
, orF_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 byfd
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 inarg
, then notification will remain in effect until explicitly removed.A series of
F_NOTIFY
requests is cumulative, with the events inarg
being added to the set already monitored. To disable notification of all events, make anF_NOTIFY
call specifyingarg
as 0.Notification occurs via delivery of a signal. The default signal is
SIGIO
, but this can be changed using theF_SETSIG
command tofcntl()
. (Note thatSIGIO
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 asiginfo_t
structure as its second argument (if the handler was established usingSA_SIGINFO
) and thesi_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. Seeinotify(7)
.F_SETPIPE_SZ
- Change the capacity of the pipe referred to byfd
to be at leastarg
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
(seeproc(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 errorEPERM
; 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 byfd
.F_ADD_SEALS
- Add the seals given in the bit-mask argumentarg
to the set of seals of theinode
referred to by the file descriptorfd
.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 withEPERM
. Adding a seal that is already set is a no-op, in caseF_SEAL_SEAL
is not set already. In order to place a seal, the file descriptorfd
must be writable.F_GET_SEALS
- Return (as the function result) the current set of seals of theinode
referred to byfd
.If no seals are set, 0 is returned. If the file does not support sealing, -1 is returned and
errno
is set toEINVAL
.F_GET_RW_HINT
- Returns the value of the read/write hint associated with the underlyinginode
referred to byfd
.F_SET_RW_HINT
- Sets the read/write hint value associated with the underlyinginode
referred to byfd
.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 byfd
.F_SET_FILE_RW_HINT
- Sets the read/write hint value associated with the open file description referred to byfd
.F_DUPFD_CLOEXEC
- As forF_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 theFD_CLOEXEC
flag. For an explanation of why this flag is useful, see the description ofO_CLOEXEC
inopen(2)
.
- See Also:
-
F_OFD_SETLKW
public static final int F_OFD_SETLKWfcntl(int, int)
commands.Enum values:
F_DUPFD
- Duplicate the file descriptorfd
using the lowest-numbered available file descriptor greater than or equal toarg
.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 byarg
.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 byarg
.File access mode (
O_RDONLY
,O_WRONLY
,O_RDWR
) and file creation flags (i.e.,O_CREAT
,O_EXCL
,O_NOCTTY
,O_TRUNC
) inarg
are ignored. On Linux, this command can change only theO_APPEND
,O_ASYNC
,O_DIRECT
,O_NOATIME
, andO_NONBLOCK
flags. It is not possible to change theO_DSYNC
andO_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 returnsF_UNLCK
in thel_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 thel_type
,l_whence
,l_start
, andl_len
fields of lock. If the conflicting lock is a traditional (process-associated) record lock, then thel_pid
field is set to thePID
of the process holding that lock. If the conflicting lock is an open file description lock, thenl_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 (whenl_type
isF_RDLCK
orF_WRLCK
) or release a lock (whenl_type
isF_UNLCK
) on the bytes specified by thel_whence
,l_start
, andl_len
fields of lock.If a conflicting lock is held by another process, this call returns -1 and sets
errno
toEACCES
orEAGAIN
. (The error returned in this case differs across implementations, so POSIX requires a portable application to check for both errors.)F_SETLKW
- As forF_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
; seesignal(7)
).F_SETOWN
- Set the process ID or process group ID that will receiveSIGIO
andSIGURG
signals for events on the file descriptorfd
.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 asgetpid(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 theO_ASYNC
file status flag on the file descriptor. Subsequently, aSIGIO
signal is sent whenever input or output becomes possible on the file descriptor. Thefcntl()
F_SETSIG
command can be used to obtain delivery of a signal other thanSIGIO
.Sending a signal to the owner process (group) specified by
F_SETOWN
is subject to the same permissions checks as are described forkill(2)
, where the sending process is the one that employsF_SETOWN
(but see BUGS below). If this permission check fails, then the signal is silently discarded. Note: TheF_SETOWN
operation records the caller's credentials at the time of thefcntl()
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 ofSIGURG
signals that are delivered when out-of-band data arrives on that socket. (SIGURG
is sent in any situation whereselect(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 toF_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 passF_SETOWN
the result ofgettid(2)
instead ofgetpid(2)
to get sensible results whenF_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 usegettid(2)
orgetpid(2)
in this scenario.) Note, however, that the statements in this paragraph do not apply to theSIGURG
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 toF_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 targetSIGIO
andSIGURG
signals at a particular thread.F_GETOWN
- Return (as the function result) the process ID or process group ID currently receivingSIGIO
andSIGURG
signals for events on file descriptorfd
.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 inarg
.A value of zero means to send the default
SIGIO
signal. Any other value (includingSIGIO
) is the signal to send instead, and in this case additional info is available to the signal handler if installed withSA_SIGINFO
.By using
F_SETSIG
with a nonzero value, and settingSA_SIGINFO
for the signal handler (seesigaction(2)
), extra information about I/O events is passed to the handler in asiginfo_t
structure. If thesi_code
field indicates the source isSI_SIGIO
, thesi_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)
withO_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 theF_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 thesi_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 ifSA_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)
andsignal(7)
) and if this limit is reached, then the kernel reverts to deliveringSIGIO
, 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 (includingSIGIO
) is the signal sent instead, and in this case additional info is available to the signal handler if installed withSA_SIGINFO
.arg
is ignored.F_SETOWN_EX
- This operation performs a similar task toF_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 aFOwnerEx
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 previousF_SETOWN_EX
operation.The information is returned in the
FOwnerEx
structure pointed to byarg
.The type field will have one of the values
F_OWNER_TID
,F_OWNER_PID
, orF_OWNER_PGRP
. Thepid
field is a positive integer representing a thread ID, process ID, or process group ID. SeeF_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 returnsF_UNLCK
in thel_type
field oflock
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 vialock
, as described above forF_GETLK
.F_OFD_SETLK
- Acquire an open file description lock (whenl_type
isF_RDLCK
orF_WRLCK
) or release an open file description lock (whenl_type
isF_UNLCK
) on the bytes specified by thel_whence
,l_start
, andl_len
fields oflock
.If a conflicting lock is held by another process, this call returns -1 and sets
errno
toEAGAIN
.F_OFD_SETLKW
- As forF_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 toEINTR
; seesignal(7)
).F_SETLEASE
- Set or remove a file lease according to which of the following values is specified in the integerarg
:F_RDLCK
,F_WRLCK
,F_UNLCK
F_GETLEASE
- Indicates what type of lease is associated with the file descriptorfd
by returning eitherF_RDLCK
,F_WRLCK
, orF_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 byfd
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 inarg
, then notification will remain in effect until explicitly removed.A series of
F_NOTIFY
requests is cumulative, with the events inarg
being added to the set already monitored. To disable notification of all events, make anF_NOTIFY
call specifyingarg
as 0.Notification occurs via delivery of a signal. The default signal is
SIGIO
, but this can be changed using theF_SETSIG
command tofcntl()
. (Note thatSIGIO
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 asiginfo_t
structure as its second argument (if the handler was established usingSA_SIGINFO
) and thesi_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. Seeinotify(7)
.F_SETPIPE_SZ
- Change the capacity of the pipe referred to byfd
to be at leastarg
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
(seeproc(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 errorEPERM
; 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 byfd
.F_ADD_SEALS
- Add the seals given in the bit-mask argumentarg
to the set of seals of theinode
referred to by the file descriptorfd
.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 withEPERM
. Adding a seal that is already set is a no-op, in caseF_SEAL_SEAL
is not set already. In order to place a seal, the file descriptorfd
must be writable.F_GET_SEALS
- Return (as the function result) the current set of seals of theinode
referred to byfd
.If no seals are set, 0 is returned. If the file does not support sealing, -1 is returned and
errno
is set toEINVAL
.F_GET_RW_HINT
- Returns the value of the read/write hint associated with the underlyinginode
referred to byfd
.F_SET_RW_HINT
- Sets the read/write hint value associated with the underlyinginode
referred to byfd
.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 byfd
.F_SET_FILE_RW_HINT
- Sets the read/write hint value associated with the open file description referred to byfd
.F_DUPFD_CLOEXEC
- As forF_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 theFD_CLOEXEC
flag. For an explanation of why this flag is useful, see the description ofO_CLOEXEC
inopen(2)
.
- See Also:
-
F_SETLEASE
public static final int F_SETLEASEfcntl(int, int)
commands.Enum values:
F_DUPFD
- Duplicate the file descriptorfd
using the lowest-numbered available file descriptor greater than or equal toarg
.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 byarg
.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 byarg
.File access mode (
O_RDONLY
,O_WRONLY
,O_RDWR
) and file creation flags (i.e.,O_CREAT
,O_EXCL
,O_NOCTTY
,O_TRUNC
) inarg
are ignored. On Linux, this command can change only theO_APPEND
,O_ASYNC
,O_DIRECT
,O_NOATIME
, andO_NONBLOCK
flags. It is not possible to change theO_DSYNC
andO_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 returnsF_UNLCK
in thel_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 thel_type
,l_whence
,l_start
, andl_len
fields of lock. If the conflicting lock is a traditional (process-associated) record lock, then thel_pid
field is set to thePID
of the process holding that lock. If the conflicting lock is an open file description lock, thenl_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 (whenl_type
isF_RDLCK
orF_WRLCK
) or release a lock (whenl_type
isF_UNLCK
) on the bytes specified by thel_whence
,l_start
, andl_len
fields of lock.If a conflicting lock is held by another process, this call returns -1 and sets
errno
toEACCES
orEAGAIN
. (The error returned in this case differs across implementations, so POSIX requires a portable application to check for both errors.)F_SETLKW
- As forF_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
; seesignal(7)
).F_SETOWN
- Set the process ID or process group ID that will receiveSIGIO
andSIGURG
signals for events on the file descriptorfd
.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 asgetpid(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 theO_ASYNC
file status flag on the file descriptor. Subsequently, aSIGIO
signal is sent whenever input or output becomes possible on the file descriptor. Thefcntl()
F_SETSIG
command can be used to obtain delivery of a signal other thanSIGIO
.Sending a signal to the owner process (group) specified by
F_SETOWN
is subject to the same permissions checks as are described forkill(2)
, where the sending process is the one that employsF_SETOWN
(but see BUGS below). If this permission check fails, then the signal is silently discarded. Note: TheF_SETOWN
operation records the caller's credentials at the time of thefcntl()
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 ofSIGURG
signals that are delivered when out-of-band data arrives on that socket. (SIGURG
is sent in any situation whereselect(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 toF_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 passF_SETOWN
the result ofgettid(2)
instead ofgetpid(2)
to get sensible results whenF_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 usegettid(2)
orgetpid(2)
in this scenario.) Note, however, that the statements in this paragraph do not apply to theSIGURG
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 toF_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 targetSIGIO
andSIGURG
signals at a particular thread.F_GETOWN
- Return (as the function result) the process ID or process group ID currently receivingSIGIO
andSIGURG
signals for events on file descriptorfd
.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 inarg
.A value of zero means to send the default
SIGIO
signal. Any other value (includingSIGIO
) is the signal to send instead, and in this case additional info is available to the signal handler if installed withSA_SIGINFO
.By using
F_SETSIG
with a nonzero value, and settingSA_SIGINFO
for the signal handler (seesigaction(2)
), extra information about I/O events is passed to the handler in asiginfo_t
structure. If thesi_code
field indicates the source isSI_SIGIO
, thesi_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)
withO_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 theF_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 thesi_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 ifSA_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)
andsignal(7)
) and if this limit is reached, then the kernel reverts to deliveringSIGIO
, 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 (includingSIGIO
) is the signal sent instead, and in this case additional info is available to the signal handler if installed withSA_SIGINFO
.arg
is ignored.F_SETOWN_EX
- This operation performs a similar task toF_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 aFOwnerEx
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 previousF_SETOWN_EX
operation.The information is returned in the
FOwnerEx
structure pointed to byarg
.The type field will have one of the values
F_OWNER_TID
,F_OWNER_PID
, orF_OWNER_PGRP
. Thepid
field is a positive integer representing a thread ID, process ID, or process group ID. SeeF_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 returnsF_UNLCK
in thel_type
field oflock
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 vialock
, as described above forF_GETLK
.F_OFD_SETLK
- Acquire an open file description lock (whenl_type
isF_RDLCK
orF_WRLCK
) or release an open file description lock (whenl_type
isF_UNLCK
) on the bytes specified by thel_whence
,l_start
, andl_len
fields oflock
.If a conflicting lock is held by another process, this call returns -1 and sets
errno
toEAGAIN
.F_OFD_SETLKW
- As forF_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 toEINTR
; seesignal(7)
).F_SETLEASE
- Set or remove a file lease according to which of the following values is specified in the integerarg
:F_RDLCK
,F_WRLCK
,F_UNLCK
F_GETLEASE
- Indicates what type of lease is associated with the file descriptorfd
by returning eitherF_RDLCK
,F_WRLCK
, orF_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 byfd
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 inarg
, then notification will remain in effect until explicitly removed.A series of
F_NOTIFY
requests is cumulative, with the events inarg
being added to the set already monitored. To disable notification of all events, make anF_NOTIFY
call specifyingarg
as 0.Notification occurs via delivery of a signal. The default signal is
SIGIO
, but this can be changed using theF_SETSIG
command tofcntl()
. (Note thatSIGIO
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 asiginfo_t
structure as its second argument (if the handler was established usingSA_SIGINFO
) and thesi_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. Seeinotify(7)
.F_SETPIPE_SZ
- Change the capacity of the pipe referred to byfd
to be at leastarg
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
(seeproc(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 errorEPERM
; 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 byfd
.F_ADD_SEALS
- Add the seals given in the bit-mask argumentarg
to the set of seals of theinode
referred to by the file descriptorfd
.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 withEPERM
. Adding a seal that is already set is a no-op, in caseF_SEAL_SEAL
is not set already. In order to place a seal, the file descriptorfd
must be writable.F_GET_SEALS
- Return (as the function result) the current set of seals of theinode
referred to byfd
.If no seals are set, 0 is returned. If the file does not support sealing, -1 is returned and
errno
is set toEINVAL
.F_GET_RW_HINT
- Returns the value of the read/write hint associated with the underlyinginode
referred to byfd
.F_SET_RW_HINT
- Sets the read/write hint value associated with the underlyinginode
referred to byfd
.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 byfd
.F_SET_FILE_RW_HINT
- Sets the read/write hint value associated with the open file description referred to byfd
.F_DUPFD_CLOEXEC
- As forF_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 theFD_CLOEXEC
flag. For an explanation of why this flag is useful, see the description ofO_CLOEXEC
inopen(2)
.
- See Also:
-
F_GETLEASE
public static final int F_GETLEASEfcntl(int, int)
commands.Enum values:
F_DUPFD
- Duplicate the file descriptorfd
using the lowest-numbered available file descriptor greater than or equal toarg
.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 byarg
.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 byarg
.File access mode (
O_RDONLY
,O_WRONLY
,O_RDWR
) and file creation flags (i.e.,O_CREAT
,O_EXCL
,O_NOCTTY
,O_TRUNC
) inarg
are ignored. On Linux, this command can change only theO_APPEND
,O_ASYNC
,O_DIRECT
,O_NOATIME
, andO_NONBLOCK
flags. It is not possible to change theO_DSYNC
andO_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 returnsF_UNLCK
in thel_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 thel_type
,l_whence
,l_start
, andl_len
fields of lock. If the conflicting lock is a traditional (process-associated) record lock, then thel_pid
field is set to thePID
of the process holding that lock. If the conflicting lock is an open file description lock, thenl_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 (whenl_type
isF_RDLCK
orF_WRLCK
) or release a lock (whenl_type
isF_UNLCK
) on the bytes specified by thel_whence
,l_start
, andl_len
fields of lock.If a conflicting lock is held by another process, this call returns -1 and sets
errno
toEACCES
orEAGAIN
. (The error returned in this case differs across implementations, so POSIX requires a portable application to check for both errors.)F_SETLKW
- As forF_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
; seesignal(7)
).F_SETOWN
- Set the process ID or process group ID that will receiveSIGIO
andSIGURG
signals for events on the file descriptorfd
.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 asgetpid(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 theO_ASYNC
file status flag on the file descriptor. Subsequently, aSIGIO
signal is sent whenever input or output becomes possible on the file descriptor. Thefcntl()
F_SETSIG
command can be used to obtain delivery of a signal other thanSIGIO
.Sending a signal to the owner process (group) specified by
F_SETOWN
is subject to the same permissions checks as are described forkill(2)
, where the sending process is the one that employsF_SETOWN
(but see BUGS below). If this permission check fails, then the signal is silently discarded. Note: TheF_SETOWN
operation records the caller's credentials at the time of thefcntl()
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 ofSIGURG
signals that are delivered when out-of-band data arrives on that socket. (SIGURG
is sent in any situation whereselect(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 toF_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 passF_SETOWN
the result ofgettid(2)
instead ofgetpid(2)
to get sensible results whenF_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 usegettid(2)
orgetpid(2)
in this scenario.) Note, however, that the statements in this paragraph do not apply to theSIGURG
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 toF_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 targetSIGIO
andSIGURG
signals at a particular thread.F_GETOWN
- Return (as the function result) the process ID or process group ID currently receivingSIGIO
andSIGURG
signals for events on file descriptorfd
.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 inarg
.A value of zero means to send the default
SIGIO
signal. Any other value (includingSIGIO
) is the signal to send instead, and in this case additional info is available to the signal handler if installed withSA_SIGINFO
.By using
F_SETSIG
with a nonzero value, and settingSA_SIGINFO
for the signal handler (seesigaction(2)
), extra information about I/O events is passed to the handler in asiginfo_t
structure. If thesi_code
field indicates the source isSI_SIGIO
, thesi_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)
withO_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 theF_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 thesi_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 ifSA_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)
andsignal(7)
) and if this limit is reached, then the kernel reverts to deliveringSIGIO
, 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 (includingSIGIO
) is the signal sent instead, and in this case additional info is available to the signal handler if installed withSA_SIGINFO
.arg
is ignored.F_SETOWN_EX
- This operation performs a similar task toF_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 aFOwnerEx
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 previousF_SETOWN_EX
operation.The information is returned in the
FOwnerEx
structure pointed to byarg
.The type field will have one of the values
F_OWNER_TID
,F_OWNER_PID
, orF_OWNER_PGRP
. Thepid
field is a positive integer representing a thread ID, process ID, or process group ID. SeeF_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 returnsF_UNLCK
in thel_type
field oflock
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 vialock
, as described above forF_GETLK
.F_OFD_SETLK
- Acquire an open file description lock (whenl_type
isF_RDLCK
orF_WRLCK
) or release an open file description lock (whenl_type
isF_UNLCK
) on the bytes specified by thel_whence
,l_start
, andl_len
fields oflock
.If a conflicting lock is held by another process, this call returns -1 and sets
errno
toEAGAIN
.F_OFD_SETLKW
- As forF_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 toEINTR
; seesignal(7)
).F_SETLEASE
- Set or remove a file lease according to which of the following values is specified in the integerarg
:F_RDLCK
,F_WRLCK
,F_UNLCK
F_GETLEASE
- Indicates what type of lease is associated with the file descriptorfd
by returning eitherF_RDLCK
,F_WRLCK
, orF_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 byfd
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 inarg
, then notification will remain in effect until explicitly removed.A series of
F_NOTIFY
requests is cumulative, with the events inarg
being added to the set already monitored. To disable notification of all events, make anF_NOTIFY
call specifyingarg
as 0.Notification occurs via delivery of a signal. The default signal is
SIGIO
, but this can be changed using theF_SETSIG
command tofcntl()
. (Note thatSIGIO
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 asiginfo_t
structure as its second argument (if the handler was established usingSA_SIGINFO
) and thesi_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. Seeinotify(7)
.F_SETPIPE_SZ
- Change the capacity of the pipe referred to byfd
to be at leastarg
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
(seeproc(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 errorEPERM
; 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 byfd
.F_ADD_SEALS
- Add the seals given in the bit-mask argumentarg
to the set of seals of theinode
referred to by the file descriptorfd
.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 withEPERM
. Adding a seal that is already set is a no-op, in caseF_SEAL_SEAL
is not set already. In order to place a seal, the file descriptorfd
must be writable.F_GET_SEALS
- Return (as the function result) the current set of seals of theinode
referred to byfd
.If no seals are set, 0 is returned. If the file does not support sealing, -1 is returned and
errno
is set toEINVAL
.F_GET_RW_HINT
- Returns the value of the read/write hint associated with the underlyinginode
referred to byfd
.F_SET_RW_HINT
- Sets the read/write hint value associated with the underlyinginode
referred to byfd
.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 byfd
.F_SET_FILE_RW_HINT
- Sets the read/write hint value associated with the open file description referred to byfd
.F_DUPFD_CLOEXEC
- As forF_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 theFD_CLOEXEC
flag. For an explanation of why this flag is useful, see the description ofO_CLOEXEC
inopen(2)
.
- See Also:
-
F_NOTIFY
public static final int F_NOTIFYfcntl(int, int)
commands.Enum values:
F_DUPFD
- Duplicate the file descriptorfd
using the lowest-numbered available file descriptor greater than or equal toarg
.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 byarg
.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 byarg
.File access mode (
O_RDONLY
,O_WRONLY
,O_RDWR
) and file creation flags (i.e.,O_CREAT
,O_EXCL
,O_NOCTTY
,O_TRUNC
) inarg
are ignored. On Linux, this command can change only theO_APPEND
,O_ASYNC
,O_DIRECT
,O_NOATIME
, andO_NONBLOCK
flags. It is not possible to change theO_DSYNC
andO_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 returnsF_UNLCK
in thel_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 thel_type
,l_whence
,l_start
, andl_len
fields of lock. If the conflicting lock is a traditional (process-associated) record lock, then thel_pid
field is set to thePID
of the process holding that lock. If the conflicting lock is an open file description lock, thenl_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 (whenl_type
isF_RDLCK
orF_WRLCK
) or release a lock (whenl_type
isF_UNLCK
) on the bytes specified by thel_whence
,l_start
, andl_len
fields of lock.If a conflicting lock is held by another process, this call returns -1 and sets
errno
toEACCES
orEAGAIN
. (The error returned in this case differs across implementations, so POSIX requires a portable application to check for both errors.)F_SETLKW
- As forF_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
; seesignal(7)
).F_SETOWN
- Set the process ID or process group ID that will receiveSIGIO
andSIGURG
signals for events on the file descriptorfd
.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 asgetpid(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 theO_ASYNC
file status flag on the file descriptor. Subsequently, aSIGIO
signal is sent whenever input or output becomes possible on the file descriptor. Thefcntl()
F_SETSIG
command can be used to obtain delivery of a signal other thanSIGIO
.Sending a signal to the owner process (group) specified by
F_SETOWN
is subject to the same permissions checks as are described forkill(2)
, where the sending process is the one that employsF_SETOWN
(but see BUGS below). If this permission check fails, then the signal is silently discarded. Note: TheF_SETOWN
operation records the caller's credentials at the time of thefcntl()
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 ofSIGURG
signals that are delivered when out-of-band data arrives on that socket. (SIGURG
is sent in any situation whereselect(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 toF_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 passF_SETOWN
the result ofgettid(2)
instead ofgetpid(2)
to get sensible results whenF_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 usegettid(2)
orgetpid(2)
in this scenario.) Note, however, that the statements in this paragraph do not apply to theSIGURG
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 toF_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 targetSIGIO
andSIGURG
signals at a particular thread.F_GETOWN
- Return (as the function result) the process ID or process group ID currently receivingSIGIO
andSIGURG
signals for events on file descriptorfd
.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 inarg
.A value of zero means to send the default
SIGIO
signal. Any other value (includingSIGIO
) is the signal to send instead, and in this case additional info is available to the signal handler if installed withSA_SIGINFO
.By using
F_SETSIG
with a nonzero value, and settingSA_SIGINFO
for the signal handler (seesigaction(2)
), extra information about I/O events is passed to the handler in asiginfo_t
structure. If thesi_code
field indicates the source isSI_SIGIO
, thesi_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)
withO_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 theF_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 thesi_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 ifSA_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)
andsignal(7)
) and if this limit is reached, then the kernel reverts to deliveringSIGIO
, 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 (includingSIGIO
) is the signal sent instead, and in this case additional info is available to the signal handler if installed withSA_SIGINFO
.arg
is ignored.F_SETOWN_EX
- This operation performs a similar task toF_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 aFOwnerEx
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 previousF_SETOWN_EX
operation.The information is returned in the
FOwnerEx
structure pointed to byarg
.The type field will have one of the values
F_OWNER_TID
,F_OWNER_PID
, orF_OWNER_PGRP
. Thepid
field is a positive integer representing a thread ID, process ID, or process group ID. SeeF_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 returnsF_UNLCK
in thel_type
field oflock
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 vialock
, as described above forF_GETLK
.F_OFD_SETLK
- Acquire an open file description lock (whenl_type
isF_RDLCK
orF_WRLCK
) or release an open file description lock (whenl_type
isF_UNLCK
) on the bytes specified by thel_whence
,l_start
, andl_len
fields oflock
.If a conflicting lock is held by another process, this call returns -1 and sets
errno
toEAGAIN
.F_OFD_SETLKW
- As forF_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 toEINTR
; seesignal(7)
).F_SETLEASE
- Set or remove a file lease according to which of the following values is specified in the integerarg
:F_RDLCK
,F_WRLCK
,F_UNLCK
F_GETLEASE
- Indicates what type of lease is associated with the file descriptorfd
by returning eitherF_RDLCK
,F_WRLCK
, orF_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 byfd
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 inarg
, then notification will remain in effect until explicitly removed.A series of
F_NOTIFY
requests is cumulative, with the events inarg
being added to the set already monitored. To disable notification of all events, make anF_NOTIFY
call specifyingarg
as 0.Notification occurs via delivery of a signal. The default signal is
SIGIO
, but this can be changed using theF_SETSIG
command tofcntl()
. (Note thatSIGIO
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 asiginfo_t
structure as its second argument (if the handler was established usingSA_SIGINFO
) and thesi_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. Seeinotify(7)
.F_SETPIPE_SZ
- Change the capacity of the pipe referred to byfd
to be at leastarg
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
(seeproc(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 errorEPERM
; 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 byfd
.F_ADD_SEALS
- Add the seals given in the bit-mask argumentarg
to the set of seals of theinode
referred to by the file descriptorfd
.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 withEPERM
. Adding a seal that is already set is a no-op, in caseF_SEAL_SEAL
is not set already. In order to place a seal, the file descriptorfd
must be writable.F_GET_SEALS
- Return (as the function result) the current set of seals of theinode
referred to byfd
.If no seals are set, 0 is returned. If the file does not support sealing, -1 is returned and
errno
is set toEINVAL
.F_GET_RW_HINT
- Returns the value of the read/write hint associated with the underlyinginode
referred to byfd
.F_SET_RW_HINT
- Sets the read/write hint value associated with the underlyinginode
referred to byfd
.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 byfd
.F_SET_FILE_RW_HINT
- Sets the read/write hint value associated with the open file description referred to byfd
.F_DUPFD_CLOEXEC
- As forF_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 theFD_CLOEXEC
flag. For an explanation of why this flag is useful, see the description ofO_CLOEXEC
inopen(2)
.
- See Also:
-
F_SETPIPE_SZ
public static final int F_SETPIPE_SZfcntl(int, int)
commands.Enum values:
F_DUPFD
- Duplicate the file descriptorfd
using the lowest-numbered available file descriptor greater than or equal toarg
.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 byarg
.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 byarg
.File access mode (
O_RDONLY
,O_WRONLY
,O_RDWR
) and file creation flags (i.e.,O_CREAT
,O_EXCL
,O_NOCTTY
,O_TRUNC
) inarg
are ignored. On Linux, this command can change only theO_APPEND
,O_ASYNC
,O_DIRECT
,O_NOATIME
, andO_NONBLOCK
flags. It is not possible to change theO_DSYNC
andO_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 returnsF_UNLCK
in thel_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 thel_type
,l_whence
,l_start
, andl_len
fields of lock. If the conflicting lock is a traditional (process-associated) record lock, then thel_pid
field is set to thePID
of the process holding that lock. If the conflicting lock is an open file description lock, thenl_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 (whenl_type
isF_RDLCK
orF_WRLCK
) or release a lock (whenl_type
isF_UNLCK
) on the bytes specified by thel_whence
,l_start
, andl_len
fields of lock.If a conflicting lock is held by another process, this call returns -1 and sets
errno
toEACCES
orEAGAIN
. (The error returned in this case differs across implementations, so POSIX requires a portable application to check for both errors.)F_SETLKW
- As forF_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
; seesignal(7)
).F_SETOWN
- Set the process ID or process group ID that will receiveSIGIO
andSIGURG
signals for events on the file descriptorfd
.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 asgetpid(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 theO_ASYNC
file status flag on the file descriptor. Subsequently, aSIGIO
signal is sent whenever input or output becomes possible on the file descriptor. Thefcntl()
F_SETSIG
command can be used to obtain delivery of a signal other thanSIGIO
.Sending a signal to the owner process (group) specified by
F_SETOWN
is subject to the same permissions checks as are described forkill(2)
, where the sending process is the one that employsF_SETOWN
(but see BUGS below). If this permission check fails, then the signal is silently discarded. Note: TheF_SETOWN
operation records the caller's credentials at the time of thefcntl()
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 ofSIGURG
signals that are delivered when out-of-band data arrives on that socket. (SIGURG
is sent in any situation whereselect(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 toF_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 passF_SETOWN
the result ofgettid(2)
instead ofgetpid(2)
to get sensible results whenF_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 usegettid(2)
orgetpid(2)
in this scenario.) Note, however, that the statements in this paragraph do not apply to theSIGURG
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 toF_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 targetSIGIO
andSIGURG
signals at a particular thread.F_GETOWN
- Return (as the function result) the process ID or process group ID currently receivingSIGIO
andSIGURG
signals for events on file descriptorfd
.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 inarg
.A value of zero means to send the default
SIGIO
signal. Any other value (includingSIGIO
) is the signal to send instead, and in this case additional info is available to the signal handler if installed withSA_SIGINFO
.By using
F_SETSIG
with a nonzero value, and settingSA_SIGINFO
for the signal handler (seesigaction(2)
), extra information about I/O events is passed to the handler in asiginfo_t
structure. If thesi_code
field indicates the source isSI_SIGIO
, thesi_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)
withO_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 theF_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 thesi_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 ifSA_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)
andsignal(7)
) and if this limit is reached, then the kernel reverts to deliveringSIGIO
, 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 (includingSIGIO
) is the signal sent instead, and in this case additional info is available to the signal handler if installed withSA_SIGINFO
.arg
is ignored.F_SETOWN_EX
- This operation performs a similar task toF_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 aFOwnerEx
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 previousF_SETOWN_EX
operation.The information is returned in the
FOwnerEx
structure pointed to byarg
.The type field will have one of the values
F_OWNER_TID
,F_OWNER_PID
, orF_OWNER_PGRP
. Thepid
field is a positive integer representing a thread ID, process ID, or process group ID. SeeF_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 returnsF_UNLCK
in thel_type
field oflock
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 vialock
, as described above forF_GETLK
.F_OFD_SETLK
- Acquire an open file description lock (whenl_type
isF_RDLCK
orF_WRLCK
) or release an open file description lock (whenl_type
isF_UNLCK
) on the bytes specified by thel_whence
,l_start
, andl_len
fields oflock
.If a conflicting lock is held by another process, this call returns -1 and sets
errno
toEAGAIN
.F_OFD_SETLKW
- As forF_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 toEINTR
; seesignal(7)
).F_SETLEASE
- Set or remove a file lease according to which of the following values is specified in the integerarg
:F_RDLCK
,F_WRLCK
,F_UNLCK
F_GETLEASE
- Indicates what type of lease is associated with the file descriptorfd
by returning eitherF_RDLCK
,F_WRLCK
, orF_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 byfd
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 inarg
, then notification will remain in effect until explicitly removed.A series of
F_NOTIFY
requests is cumulative, with the events inarg
being added to the set already monitored. To disable notification of all events, make anF_NOTIFY
call specifyingarg
as 0.Notification occurs via delivery of a signal. The default signal is
SIGIO
, but this can be changed using theF_SETSIG
command tofcntl()
. (Note thatSIGIO
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 asiginfo_t
structure as its second argument (if the handler was established usingSA_SIGINFO
) and thesi_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. Seeinotify(7)
.F_SETPIPE_SZ
- Change the capacity of the pipe referred to byfd
to be at leastarg
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
(seeproc(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 errorEPERM
; 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 byfd
.F_ADD_SEALS
- Add the seals given in the bit-mask argumentarg
to the set of seals of theinode
referred to by the file descriptorfd
.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 withEPERM
. Adding a seal that is already set is a no-op, in caseF_SEAL_SEAL
is not set already. In order to place a seal, the file descriptorfd
must be writable.F_GET_SEALS
- Return (as the function result) the current set of seals of theinode
referred to byfd
.If no seals are set, 0 is returned. If the file does not support sealing, -1 is returned and
errno
is set toEINVAL
.F_GET_RW_HINT
- Returns the value of the read/write hint associated with the underlyinginode
referred to byfd
.F_SET_RW_HINT
- Sets the read/write hint value associated with the underlyinginode
referred to byfd
.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 byfd
.F_SET_FILE_RW_HINT
- Sets the read/write hint value associated with the open file description referred to byfd
.F_DUPFD_CLOEXEC
- As forF_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 theFD_CLOEXEC
flag. For an explanation of why this flag is useful, see the description ofO_CLOEXEC
inopen(2)
.
- See Also:
-
F_GETPIPE_SZ
public static final int F_GETPIPE_SZfcntl(int, int)
commands.Enum values:
F_DUPFD
- Duplicate the file descriptorfd
using the lowest-numbered available file descriptor greater than or equal toarg
.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 byarg
.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 byarg
.File access mode (
O_RDONLY
,O_WRONLY
,O_RDWR
) and file creation flags (i.e.,O_CREAT
,O_EXCL
,O_NOCTTY
,O_TRUNC
) inarg
are ignored. On Linux, this command can change only theO_APPEND
,O_ASYNC
,O_DIRECT
,O_NOATIME
, andO_NONBLOCK
flags. It is not possible to change theO_DSYNC
andO_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 returnsF_UNLCK
in thel_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 thel_type
,l_whence
,l_start
, andl_len
fields of lock. If the conflicting lock is a traditional (process-associated) record lock, then thel_pid
field is set to thePID
of the process holding that lock. If the conflicting lock is an open file description lock, thenl_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 (whenl_type
isF_RDLCK
orF_WRLCK
) or release a lock (whenl_type
isF_UNLCK
) on the bytes specified by thel_whence
,l_start
, andl_len
fields of lock.If a conflicting lock is held by another process, this call returns -1 and sets
errno
toEACCES
orEAGAIN
. (The error returned in this case differs across implementations, so POSIX requires a portable application to check for both errors.)F_SETLKW
- As forF_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
; seesignal(7)
).F_SETOWN
- Set the process ID or process group ID that will receiveSIGIO
andSIGURG
signals for events on the file descriptorfd
.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 asgetpid(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 theO_ASYNC
file status flag on the file descriptor. Subsequently, aSIGIO
signal is sent whenever input or output becomes possible on the file descriptor. Thefcntl()
F_SETSIG
command can be used to obtain delivery of a signal other thanSIGIO
.Sending a signal to the owner process (group) specified by
F_SETOWN
is subject to the same permissions checks as are described forkill(2)
, where the sending process is the one that employsF_SETOWN
(but see BUGS below). If this permission check fails, then the signal is silently discarded. Note: TheF_SETOWN
operation records the caller's credentials at the time of thefcntl()
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 ofSIGURG
signals that are delivered when out-of-band data arrives on that socket. (SIGURG
is sent in any situation whereselect(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 toF_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 passF_SETOWN
the result ofgettid(2)
instead ofgetpid(2)
to get sensible results whenF_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 usegettid(2)
orgetpid(2)
in this scenario.) Note, however, that the statements in this paragraph do not apply to theSIGURG
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 toF_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 targetSIGIO
andSIGURG
signals at a particular thread.F_GETOWN
- Return (as the function result) the process ID or process group ID currently receivingSIGIO
andSIGURG
signals for events on file descriptorfd
.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 inarg
.A value of zero means to send the default
SIGIO
signal. Any other value (includingSIGIO
) is the signal to send instead, and in this case additional info is available to the signal handler if installed withSA_SIGINFO
.By using
F_SETSIG
with a nonzero value, and settingSA_SIGINFO
for the signal handler (seesigaction(2)
), extra information about I/O events is passed to the handler in asiginfo_t
structure. If thesi_code
field indicates the source isSI_SIGIO
, thesi_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)
withO_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 theF_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 thesi_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 ifSA_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)
andsignal(7)
) and if this limit is reached, then the kernel reverts to deliveringSIGIO
, 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 (includingSIGIO
) is the signal sent instead, and in this case additional info is available to the signal handler if installed withSA_SIGINFO
.arg
is ignored.F_SETOWN_EX
- This operation performs a similar task toF_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 aFOwnerEx
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 previousF_SETOWN_EX
operation.The information is returned in the
FOwnerEx
structure pointed to byarg
.The type field will have one of the values
F_OWNER_TID
,F_OWNER_PID
, orF_OWNER_PGRP
. Thepid
field is a positive integer representing a thread ID, process ID, or process group ID. SeeF_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 returnsF_UNLCK
in thel_type
field oflock
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 vialock
, as described above forF_GETLK
.F_OFD_SETLK
- Acquire an open file description lock (whenl_type
isF_RDLCK
orF_WRLCK
) or release an open file description lock (whenl_type
isF_UNLCK
) on the bytes specified by thel_whence
,l_start
, andl_len
fields oflock
.If a conflicting lock is held by another process, this call returns -1 and sets
errno
toEAGAIN
.F_OFD_SETLKW
- As forF_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 toEINTR
; seesignal(7)
).F_SETLEASE
- Set or remove a file lease according to which of the following values is specified in the integerarg
:F_RDLCK
,F_WRLCK
,F_UNLCK
F_GETLEASE
- Indicates what type of lease is associated with the file descriptorfd
by returning eitherF_RDLCK
,F_WRLCK
, orF_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 byfd
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 inarg
, then notification will remain in effect until explicitly removed.A series of
F_NOTIFY
requests is cumulative, with the events inarg
being added to the set already monitored. To disable notification of all events, make anF_NOTIFY
call specifyingarg
as 0.Notification occurs via delivery of a signal. The default signal is
SIGIO
, but this can be changed using theF_SETSIG
command tofcntl()
. (Note thatSIGIO
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 asiginfo_t
structure as its second argument (if the handler was established usingSA_SIGINFO
) and thesi_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. Seeinotify(7)
.F_SETPIPE_SZ
- Change the capacity of the pipe referred to byfd
to be at leastarg
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
(seeproc(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 errorEPERM
; 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 byfd
.F_ADD_SEALS
- Add the seals given in the bit-mask argumentarg
to the set of seals of theinode
referred to by the file descriptorfd
.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 withEPERM
. Adding a seal that is already set is a no-op, in caseF_SEAL_SEAL
is not set already. In order to place a seal, the file descriptorfd
must be writable.F_GET_SEALS
- Return (as the function result) the current set of seals of theinode
referred to byfd
.If no seals are set, 0 is returned. If the file does not support sealing, -1 is returned and
errno
is set toEINVAL
.F_GET_RW_HINT
- Returns the value of the read/write hint associated with the underlyinginode
referred to byfd
.F_SET_RW_HINT
- Sets the read/write hint value associated with the underlyinginode
referred to byfd
.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 byfd
.F_SET_FILE_RW_HINT
- Sets the read/write hint value associated with the open file description referred to byfd
.F_DUPFD_CLOEXEC
- As forF_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 theFD_CLOEXEC
flag. For an explanation of why this flag is useful, see the description ofO_CLOEXEC
inopen(2)
.
- See Also:
-
F_ADD_SEALS
public static final int F_ADD_SEALSfcntl(int, int)
commands.Enum values:
F_DUPFD
- Duplicate the file descriptorfd
using the lowest-numbered available file descriptor greater than or equal toarg
.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 byarg
.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 byarg
.File access mode (
O_RDONLY
,O_WRONLY
,O_RDWR
) and file creation flags (i.e.,O_CREAT
,O_EXCL
,O_NOCTTY
,O_TRUNC
) inarg
are ignored. On Linux, this command can change only theO_APPEND
,O_ASYNC
,O_DIRECT
,O_NOATIME
, andO_NONBLOCK
flags. It is not possible to change theO_DSYNC
andO_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 returnsF_UNLCK
in thel_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 thel_type
,l_whence
,l_start
, andl_len
fields of lock. If the conflicting lock is a traditional (process-associated) record lock, then thel_pid
field is set to thePID
of the process holding that lock. If the conflicting lock is an open file description lock, thenl_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 (whenl_type
isF_RDLCK
orF_WRLCK
) or release a lock (whenl_type
isF_UNLCK
) on the bytes specified by thel_whence
,l_start
, andl_len
fields of lock.If a conflicting lock is held by another process, this call returns -1 and sets
errno
toEACCES
orEAGAIN
. (The error returned in this case differs across implementations, so POSIX requires a portable application to check for both errors.)F_SETLKW
- As forF_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
; seesignal(7)
).F_SETOWN
- Set the process ID or process group ID that will receiveSIGIO
andSIGURG
signals for events on the file descriptorfd
.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 asgetpid(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 theO_ASYNC
file status flag on the file descriptor. Subsequently, aSIGIO
signal is sent whenever input or output becomes possible on the file descriptor. Thefcntl()
F_SETSIG
command can be used to obtain delivery of a signal other thanSIGIO
.Sending a signal to the owner process (group) specified by
F_SETOWN
is subject to the same permissions checks as are described forkill(2)
, where the sending process is the one that employsF_SETOWN
(but see BUGS below). If this permission check fails, then the signal is silently discarded. Note: TheF_SETOWN
operation records the caller's credentials at the time of thefcntl()
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 ofSIGURG
signals that are delivered when out-of-band data arrives on that socket. (SIGURG
is sent in any situation whereselect(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 toF_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 passF_SETOWN
the result ofgettid(2)
instead ofgetpid(2)
to get sensible results whenF_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 usegettid(2)
orgetpid(2)
in this scenario.) Note, however, that the statements in this paragraph do not apply to theSIGURG
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 toF_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 targetSIGIO
andSIGURG
signals at a particular thread.F_GETOWN
- Return (as the function result) the process ID or process group ID currently receivingSIGIO
andSIGURG
signals for events on file descriptorfd
.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 inarg
.A value of zero means to send the default
SIGIO
signal. Any other value (includingSIGIO
) is the signal to send instead, and in this case additional info is available to the signal handler if installed withSA_SIGINFO
.By using
F_SETSIG
with a nonzero value, and settingSA_SIGINFO
for the signal handler (seesigaction(2)
), extra information about I/O events is passed to the handler in asiginfo_t
structure. If thesi_code
field indicates the source isSI_SIGIO
, thesi_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)
withO_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 theF_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 thesi_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 ifSA_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)
andsignal(7)
) and if this limit is reached, then the kernel reverts to deliveringSIGIO
, 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 (includingSIGIO
) is the signal sent instead, and in this case additional info is available to the signal handler if installed withSA_SIGINFO
.arg
is ignored.F_SETOWN_EX
- This operation performs a similar task toF_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 aFOwnerEx
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 previousF_SETOWN_EX
operation.The information is returned in the
FOwnerEx
structure pointed to byarg
.The type field will have one of the values
F_OWNER_TID
,F_OWNER_PID
, orF_OWNER_PGRP
. Thepid
field is a positive integer representing a thread ID, process ID, or process group ID. SeeF_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 returnsF_UNLCK
in thel_type
field oflock
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 vialock
, as described above forF_GETLK
.F_OFD_SETLK
- Acquire an open file description lock (whenl_type
isF_RDLCK
orF_WRLCK
) or release an open file description lock (whenl_type
isF_UNLCK
) on the bytes specified by thel_whence
,l_start
, andl_len
fields oflock
.If a conflicting lock is held by another process, this call returns -1 and sets
errno
toEAGAIN
.F_OFD_SETLKW
- As forF_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 toEINTR
; seesignal(7)
).F_SETLEASE
- Set or remove a file lease according to which of the following values is specified in the integerarg
:F_RDLCK
,F_WRLCK
,F_UNLCK
F_GETLEASE
- Indicates what type of lease is associated with the file descriptorfd
by returning eitherF_RDLCK
,F_WRLCK
, orF_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 byfd
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 inarg
, then notification will remain in effect until explicitly removed.A series of
F_NOTIFY
requests is cumulative, with the events inarg
being added to the set already monitored. To disable notification of all events, make anF_NOTIFY
call specifyingarg
as 0.Notification occurs via delivery of a signal. The default signal is
SIGIO
, but this can be changed using theF_SETSIG
command tofcntl()
. (Note thatSIGIO
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 asiginfo_t
structure as its second argument (if the handler was established usingSA_SIGINFO
) and thesi_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. Seeinotify(7)
.F_SETPIPE_SZ
- Change the capacity of the pipe referred to byfd
to be at leastarg
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
(seeproc(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 errorEPERM
; 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 byfd
.F_ADD_SEALS
- Add the seals given in the bit-mask argumentarg
to the set of seals of theinode
referred to by the file descriptorfd
.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 withEPERM
. Adding a seal that is already set is a no-op, in caseF_SEAL_SEAL
is not set already. In order to place a seal, the file descriptorfd
must be writable.F_GET_SEALS
- Return (as the function result) the current set of seals of theinode
referred to byfd
.If no seals are set, 0 is returned. If the file does not support sealing, -1 is returned and
errno
is set toEINVAL
.F_GET_RW_HINT
- Returns the value of the read/write hint associated with the underlyinginode
referred to byfd
.F_SET_RW_HINT
- Sets the read/write hint value associated with the underlyinginode
referred to byfd
.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 byfd
.F_SET_FILE_RW_HINT
- Sets the read/write hint value associated with the open file description referred to byfd
.F_DUPFD_CLOEXEC
- As forF_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 theFD_CLOEXEC
flag. For an explanation of why this flag is useful, see the description ofO_CLOEXEC
inopen(2)
.
- See Also:
-
F_GET_SEALS
public static final int F_GET_SEALSfcntl(int, int)
commands.Enum values:
F_DUPFD
- Duplicate the file descriptorfd
using the lowest-numbered available file descriptor greater than or equal toarg
.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 byarg
.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 byarg
.File access mode (
O_RDONLY
,O_WRONLY
,O_RDWR
) and file creation flags (i.e.,O_CREAT
,O_EXCL
,O_NOCTTY
,O_TRUNC
) inarg
are ignored. On Linux, this command can change only theO_APPEND
,O_ASYNC
,O_DIRECT
,O_NOATIME
, andO_NONBLOCK
flags. It is not possible to change theO_DSYNC
andO_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 returnsF_UNLCK
in thel_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 thel_type
,l_whence
,l_start
, andl_len
fields of lock. If the conflicting lock is a traditional (process-associated) record lock, then thel_pid
field is set to thePID
of the process holding that lock. If the conflicting lock is an open file description lock, thenl_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 (whenl_type
isF_RDLCK
orF_WRLCK
) or release a lock (whenl_type
isF_UNLCK
) on the bytes specified by thel_whence
,l_start
, andl_len
fields of lock.If a conflicting lock is held by another process, this call returns -1 and sets
errno
toEACCES
orEAGAIN
. (The error returned in this case differs across implementations, so POSIX requires a portable application to check for both errors.)F_SETLKW
- As forF_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
; seesignal(7)
).F_SETOWN
- Set the process ID or process group ID that will receiveSIGIO
andSIGURG
signals for events on the file descriptorfd
.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 asgetpid(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 theO_ASYNC
file status flag on the file descriptor. Subsequently, aSIGIO
signal is sent whenever input or output becomes possible on the file descriptor. Thefcntl()
F_SETSIG
command can be used to obtain delivery of a signal other thanSIGIO
.Sending a signal to the owner process (group) specified by
F_SETOWN
is subject to the same permissions checks as are described forkill(2)
, where the sending process is the one that employsF_SETOWN
(but see BUGS below). If this permission check fails, then the signal is silently discarded. Note: TheF_SETOWN
operation records the caller's credentials at the time of thefcntl()
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 ofSIGURG
signals that are delivered when out-of-band data arrives on that socket. (SIGURG
is sent in any situation whereselect(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 toF_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 passF_SETOWN
the result ofgettid(2)
instead ofgetpid(2)
to get sensible results whenF_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 usegettid(2)
orgetpid(2)
in this scenario.) Note, however, that the statements in this paragraph do not apply to theSIGURG
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 toF_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 targetSIGIO
andSIGURG
signals at a particular thread.F_GETOWN
- Return (as the function result) the process ID or process group ID currently receivingSIGIO
andSIGURG
signals for events on file descriptorfd
.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 inarg
.A value of zero means to send the default
SIGIO
signal. Any other value (includingSIGIO
) is the signal to send instead, and in this case additional info is available to the signal handler if installed withSA_SIGINFO
.By using
F_SETSIG
with a nonzero value, and settingSA_SIGINFO
for the signal handler (seesigaction(2)
), extra information about I/O events is passed to the handler in asiginfo_t
structure. If thesi_code
field indicates the source isSI_SIGIO
, thesi_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)
withO_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 theF_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 thesi_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 ifSA_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)
andsignal(7)
) and if this limit is reached, then the kernel reverts to deliveringSIGIO
, 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 (includingSIGIO
) is the signal sent instead, and in this case additional info is available to the signal handler if installed withSA_SIGINFO
.arg
is ignored.F_SETOWN_EX
- This operation performs a similar task toF_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 aFOwnerEx
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 previousF_SETOWN_EX
operation.The information is returned in the
FOwnerEx
structure pointed to byarg
.The type field will have one of the values
F_OWNER_TID
,F_OWNER_PID
, orF_OWNER_PGRP
. Thepid
field is a positive integer representing a thread ID, process ID, or process group ID. SeeF_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 returnsF_UNLCK
in thel_type
field oflock
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 vialock
, as described above forF_GETLK
.F_OFD_SETLK
- Acquire an open file description lock (whenl_type
isF_RDLCK
orF_WRLCK
) or release an open file description lock (whenl_type
isF_UNLCK
) on the bytes specified by thel_whence
,l_start
, andl_len
fields oflock
.If a conflicting lock is held by another process, this call returns -1 and sets
errno
toEAGAIN
.F_OFD_SETLKW
- As forF_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 toEINTR
; seesignal(7)
).F_SETLEASE
- Set or remove a file lease according to which of the following values is specified in the integerarg
:F_RDLCK
,F_WRLCK
,F_UNLCK
F_GETLEASE
- Indicates what type of lease is associated with the file descriptorfd
by returning eitherF_RDLCK
,F_WRLCK
, orF_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 byfd
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 inarg
, then notification will remain in effect until explicitly removed.A series of
F_NOTIFY
requests is cumulative, with the events inarg
being added to the set already monitored. To disable notification of all events, make anF_NOTIFY
call specifyingarg
as 0.Notification occurs via delivery of a signal. The default signal is
SIGIO
, but this can be changed using theF_SETSIG
command tofcntl()
. (Note thatSIGIO
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 asiginfo_t
structure as its second argument (if the handler was established usingSA_SIGINFO
) and thesi_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. Seeinotify(7)
.F_SETPIPE_SZ
- Change the capacity of the pipe referred to byfd
to be at leastarg
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
(seeproc(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 errorEPERM
; 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 byfd
.F_ADD_SEALS
- Add the seals given in the bit-mask argumentarg
to the set of seals of theinode
referred to by the file descriptorfd
.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 withEPERM
. Adding a seal that is already set is a no-op, in caseF_SEAL_SEAL
is not set already. In order to place a seal, the file descriptorfd
must be writable.F_GET_SEALS
- Return (as the function result) the current set of seals of theinode
referred to byfd
.If no seals are set, 0 is returned. If the file does not support sealing, -1 is returned and
errno
is set toEINVAL
.F_GET_RW_HINT
- Returns the value of the read/write hint associated with the underlyinginode
referred to byfd
.F_SET_RW_HINT
- Sets the read/write hint value associated with the underlyinginode
referred to byfd
.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 byfd
.F_SET_FILE_RW_HINT
- Sets the read/write hint value associated with the open file description referred to byfd
.F_DUPFD_CLOEXEC
- As forF_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 theFD_CLOEXEC
flag. For an explanation of why this flag is useful, see the description ofO_CLOEXEC
inopen(2)
.
- See Also:
-
F_GET_RW_HINT
public static final int F_GET_RW_HINTfcntl(int, int)
commands.Enum values:
F_DUPFD
- Duplicate the file descriptorfd
using the lowest-numbered available file descriptor greater than or equal toarg
.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 byarg
.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 byarg
.File access mode (
O_RDONLY
,O_WRONLY
,O_RDWR
) and file creation flags (i.e.,O_CREAT
,O_EXCL
,O_NOCTTY
,O_TRUNC
) inarg
are ignored. On Linux, this command can change only theO_APPEND
,O_ASYNC
,O_DIRECT
,O_NOATIME
, andO_NONBLOCK
flags. It is not possible to change theO_DSYNC
andO_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 returnsF_UNLCK
in thel_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 thel_type
,l_whence
,l_start
, andl_len
fields of lock. If the conflicting lock is a traditional (process-associated) record lock, then thel_pid
field is set to thePID
of the process holding that lock. If the conflicting lock is an open file description lock, thenl_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 (whenl_type
isF_RDLCK
orF_WRLCK
) or release a lock (whenl_type
isF_UNLCK
) on the bytes specified by thel_whence
,l_start
, andl_len
fields of lock.If a conflicting lock is held by another process, this call returns -1 and sets
errno
toEACCES
orEAGAIN
. (The error returned in this case differs across implementations, so POSIX requires a portable application to check for both errors.)F_SETLKW
- As forF_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
; seesignal(7)
).F_SETOWN
- Set the process ID or process group ID that will receiveSIGIO
andSIGURG
signals for events on the file descriptorfd
.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 asgetpid(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 theO_ASYNC
file status flag on the file descriptor. Subsequently, aSIGIO
signal is sent whenever input or output becomes possible on the file descriptor. Thefcntl()
F_SETSIG
command can be used to obtain delivery of a signal other thanSIGIO
.Sending a signal to the owner process (group) specified by
F_SETOWN
is subject to the same permissions checks as are described forkill(2)
, where the sending process is the one that employsF_SETOWN
(but see BUGS below). If this permission check fails, then the signal is silently discarded. Note: TheF_SETOWN
operation records the caller's credentials at the time of thefcntl()
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 ofSIGURG
signals that are delivered when out-of-band data arrives on that socket. (SIGURG
is sent in any situation whereselect(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 toF_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 passF_SETOWN
the result ofgettid(2)
instead ofgetpid(2)
to get sensible results whenF_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 usegettid(2)
orgetpid(2)
in this scenario.) Note, however, that the statements in this paragraph do not apply to theSIGURG
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 toF_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 targetSIGIO
andSIGURG
signals at a particular thread.F_GETOWN
- Return (as the function result) the process ID or process group ID currently receivingSIGIO
andSIGURG
signals for events on file descriptorfd
.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 inarg
.A value of zero means to send the default
SIGIO
signal. Any other value (includingSIGIO
) is the signal to send instead, and in this case additional info is available to the signal handler if installed withSA_SIGINFO
.By using
F_SETSIG
with a nonzero value, and settingSA_SIGINFO
for the signal handler (seesigaction(2)
), extra information about I/O events is passed to the handler in asiginfo_t
structure. If thesi_code
field indicates the source isSI_SIGIO
, thesi_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)
withO_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 theF_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 thesi_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 ifSA_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)
andsignal(7)
) and if this limit is reached, then the kernel reverts to deliveringSIGIO
, 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 (includingSIGIO
) is the signal sent instead, and in this case additional info is available to the signal handler if installed withSA_SIGINFO
.arg
is ignored.F_SETOWN_EX
- This operation performs a similar task toF_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 aFOwnerEx
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 previousF_SETOWN_EX
operation.The information is returned in the
FOwnerEx
structure pointed to byarg
.The type field will have one of the values
F_OWNER_TID
,F_OWNER_PID
, orF_OWNER_PGRP
. Thepid
field is a positive integer representing a thread ID, process ID, or process group ID. SeeF_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 returnsF_UNLCK
in thel_type
field oflock
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 vialock
, as described above forF_GETLK
.F_OFD_SETLK
- Acquire an open file description lock (whenl_type
isF_RDLCK
orF_WRLCK
) or release an open file description lock (whenl_type
isF_UNLCK
) on the bytes specified by thel_whence
,l_start
, andl_len
fields oflock
.If a conflicting lock is held by another process, this call returns -1 and sets
errno
toEAGAIN
.F_OFD_SETLKW
- As forF_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 toEINTR
; seesignal(7)
).F_SETLEASE
- Set or remove a file lease according to which of the following values is specified in the integerarg
:F_RDLCK
,F_WRLCK
,F_UNLCK
F_GETLEASE
- Indicates what type of lease is associated with the file descriptorfd
by returning eitherF_RDLCK
,F_WRLCK
, orF_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 byfd
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 inarg
, then notification will remain in effect until explicitly removed.A series of
F_NOTIFY
requests is cumulative, with the events inarg
being added to the set already monitored. To disable notification of all events, make anF_NOTIFY
call specifyingarg
as 0.Notification occurs via delivery of a signal. The default signal is
SIGIO
, but this can be changed using theF_SETSIG
command tofcntl()
. (Note thatSIGIO
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 asiginfo_t
structure as its second argument (if the handler was established usingSA_SIGINFO
) and thesi_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. Seeinotify(7)
.F_SETPIPE_SZ
- Change the capacity of the pipe referred to byfd
to be at leastarg
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
(seeproc(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 errorEPERM
; 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 byfd
.F_ADD_SEALS
- Add the seals given in the bit-mask argumentarg
to the set of seals of theinode
referred to by the file descriptorfd
.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 withEPERM
. Adding a seal that is already set is a no-op, in caseF_SEAL_SEAL
is not set already. In order to place a seal, the file descriptorfd
must be writable.F_GET_SEALS
- Return (as the function result) the current set of seals of theinode
referred to byfd
.If no seals are set, 0 is returned. If the file does not support sealing, -1 is returned and
errno
is set toEINVAL
.F_GET_RW_HINT
- Returns the value of the read/write hint associated with the underlyinginode
referred to byfd
.F_SET_RW_HINT
- Sets the read/write hint value associated with the underlyinginode
referred to byfd
.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 byfd
.F_SET_FILE_RW_HINT
- Sets the read/write hint value associated with the open file description referred to byfd
.F_DUPFD_CLOEXEC
- As forF_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 theFD_CLOEXEC
flag. For an explanation of why this flag is useful, see the description ofO_CLOEXEC
inopen(2)
.
- See Also:
-
F_SET_RW_HINT
public static final int F_SET_RW_HINTfcntl(int, int)
commands.Enum values:
F_DUPFD
- Duplicate the file descriptorfd
using the lowest-numbered available file descriptor greater than or equal toarg
.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 byarg
.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 byarg
.File access mode (
O_RDONLY
,O_WRONLY
,O_RDWR
) and file creation flags (i.e.,O_CREAT
,O_EXCL
,O_NOCTTY
,O_TRUNC
) inarg
are ignored. On Linux, this command can change only theO_APPEND
,O_ASYNC
,O_DIRECT
,O_NOATIME
, andO_NONBLOCK
flags. It is not possible to change theO_DSYNC
andO_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 returnsF_UNLCK
in thel_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 thel_type
,l_whence
,l_start
, andl_len
fields of lock. If the conflicting lock is a traditional (process-associated) record lock, then thel_pid
field is set to thePID
of the process holding that lock. If the conflicting lock is an open file description lock, thenl_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 (whenl_type
isF_RDLCK
orF_WRLCK
) or release a lock (whenl_type
isF_UNLCK
) on the bytes specified by thel_whence
,l_start
, andl_len
fields of lock.If a conflicting lock is held by another process, this call returns -1 and sets
errno
toEACCES
orEAGAIN
. (The error returned in this case differs across implementations, so POSIX requires a portable application to check for both errors.)F_SETLKW
- As forF_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
; seesignal(7)
).F_SETOWN
- Set the process ID or process group ID that will receiveSIGIO
andSIGURG
signals for events on the file descriptorfd
.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 asgetpid(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 theO_ASYNC
file status flag on the file descriptor. Subsequently, aSIGIO
signal is sent whenever input or output becomes possible on the file descriptor. Thefcntl()
F_SETSIG
command can be used to obtain delivery of a signal other thanSIGIO
.Sending a signal to the owner process (group) specified by
F_SETOWN
is subject to the same permissions checks as are described forkill(2)
, where the sending process is the one that employsF_SETOWN
(but see BUGS below). If this permission check fails, then the signal is silently discarded. Note: TheF_SETOWN
operation records the caller's credentials at the time of thefcntl()
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 ofSIGURG
signals that are delivered when out-of-band data arrives on that socket. (SIGURG
is sent in any situation whereselect(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 toF_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 passF_SETOWN
the result ofgettid(2)
instead ofgetpid(2)
to get sensible results whenF_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 usegettid(2)
orgetpid(2)
in this scenario.) Note, however, that the statements in this paragraph do not apply to theSIGURG
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 toF_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 targetSIGIO
andSIGURG
signals at a particular thread.F_GETOWN
- Return (as the function result) the process ID or process group ID currently receivingSIGIO
andSIGURG
signals for events on file descriptorfd
.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 inarg
.A value of zero means to send the default
SIGIO
signal. Any other value (includingSIGIO
) is the signal to send instead, and in this case additional info is available to the signal handler if installed withSA_SIGINFO
.By using
F_SETSIG
with a nonzero value, and settingSA_SIGINFO
for the signal handler (seesigaction(2)
), extra information about I/O events is passed to the handler in asiginfo_t
structure. If thesi_code
field indicates the source isSI_SIGIO
, thesi_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)
withO_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 theF_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 thesi_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 ifSA_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)
andsignal(7)
) and if this limit is reached, then the kernel reverts to deliveringSIGIO
, 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 (includingSIGIO
) is the signal sent instead, and in this case additional info is available to the signal handler if installed withSA_SIGINFO
.arg
is ignored.F_SETOWN_EX
- This operation performs a similar task toF_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 aFOwnerEx
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 previousF_SETOWN_EX
operation.The information is returned in the
FOwnerEx
structure pointed to byarg
.The type field will have one of the values
F_OWNER_TID
,F_OWNER_PID
, orF_OWNER_PGRP
. Thepid
field is a positive integer representing a thread ID, process ID, or process group ID. SeeF_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 returnsF_UNLCK
in thel_type
field oflock
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 vialock
, as described above forF_GETLK
.F_OFD_SETLK
- Acquire an open file description lock (whenl_type
isF_RDLCK
orF_WRLCK
) or release an open file description lock (whenl_type
isF_UNLCK
) on the bytes specified by thel_whence
,l_start
, andl_len
fields oflock
.If a conflicting lock is held by another process, this call returns -1 and sets
errno
toEAGAIN
.F_OFD_SETLKW
- As forF_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 toEINTR
; seesignal(7)
).F_SETLEASE
- Set or remove a file lease according to which of the following values is specified in the integerarg
:F_RDLCK
,F_WRLCK
,F_UNLCK
F_GETLEASE
- Indicates what type of lease is associated with the file descriptorfd
by returning eitherF_RDLCK
,F_WRLCK
, orF_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 byfd
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 inarg
, then notification will remain in effect until explicitly removed.A series of
F_NOTIFY
requests is cumulative, with the events inarg
being added to the set already monitored. To disable notification of all events, make anF_NOTIFY
call specifyingarg
as 0.Notification occurs via delivery of a signal. The default signal is
SIGIO
, but this can be changed using theF_SETSIG
command tofcntl()
. (Note thatSIGIO
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 asiginfo_t
structure as its second argument (if the handler was established usingSA_SIGINFO
) and thesi_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. Seeinotify(7)
.F_SETPIPE_SZ
- Change the capacity of the pipe referred to byfd
to be at leastarg
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
(seeproc(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 errorEPERM
; 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 byfd
.F_ADD_SEALS
- Add the seals given in the bit-mask argumentarg
to the set of seals of theinode
referred to by the file descriptorfd
.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 withEPERM
. Adding a seal that is already set is a no-op, in caseF_SEAL_SEAL
is not set already. In order to place a seal, the file descriptorfd
must be writable.F_GET_SEALS
- Return (as the function result) the current set of seals of theinode
referred to byfd
.If no seals are set, 0 is returned. If the file does not support sealing, -1 is returned and
errno
is set toEINVAL
.F_GET_RW_HINT
- Returns the value of the read/write hint associated with the underlyinginode
referred to byfd
.F_SET_RW_HINT
- Sets the read/write hint value associated with the underlyinginode
referred to byfd
.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 byfd
.F_SET_FILE_RW_HINT
- Sets the read/write hint value associated with the open file description referred to byfd
.F_DUPFD_CLOEXEC
- As forF_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 theFD_CLOEXEC
flag. For an explanation of why this flag is useful, see the description ofO_CLOEXEC
inopen(2)
.
- See Also:
-
F_GET_FILE_RW_HINT
public static final int F_GET_FILE_RW_HINTfcntl(int, int)
commands.Enum values:
F_DUPFD
- Duplicate the file descriptorfd
using the lowest-numbered available file descriptor greater than or equal toarg
.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 byarg
.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 byarg
.File access mode (
O_RDONLY
,O_WRONLY
,O_RDWR
) and file creation flags (i.e.,O_CREAT
,O_EXCL
,O_NOCTTY
,O_TRUNC
) inarg
are ignored. On Linux, this command can change only theO_APPEND
,O_ASYNC
,O_DIRECT
,O_NOATIME
, andO_NONBLOCK
flags. It is not possible to change theO_DSYNC
andO_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 returnsF_UNLCK
in thel_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 thel_type
,l_whence
,l_start
, andl_len
fields of lock. If the conflicting lock is a traditional (process-associated) record lock, then thel_pid
field is set to thePID
of the process holding that lock. If the conflicting lock is an open file description lock, thenl_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 (whenl_type
isF_RDLCK
orF_WRLCK
) or release a lock (whenl_type
isF_UNLCK
) on the bytes specified by thel_whence
,l_start
, andl_len
fields of lock.If a conflicting lock is held by another process, this call returns -1 and sets
errno
toEACCES
orEAGAIN
. (The error returned in this case differs across implementations, so POSIX requires a portable application to check for both errors.)F_SETLKW
- As forF_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
; seesignal(7)
).F_SETOWN
- Set the process ID or process group ID that will receiveSIGIO
andSIGURG
signals for events on the file descriptorfd
.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 asgetpid(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 theO_ASYNC
file status flag on the file descriptor. Subsequently, aSIGIO
signal is sent whenever input or output becomes possible on the file descriptor. Thefcntl()
F_SETSIG
command can be used to obtain delivery of a signal other thanSIGIO
.Sending a signal to the owner process (group) specified by
F_SETOWN
is subject to the same permissions checks as are described forkill(2)
, where the sending process is the one that employsF_SETOWN
(but see BUGS below). If this permission check fails, then the signal is silently discarded. Note: TheF_SETOWN
operation records the caller's credentials at the time of thefcntl()
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 ofSIGURG
signals that are delivered when out-of-band data arrives on that socket. (SIGURG
is sent in any situation whereselect(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 toF_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 passF_SETOWN
the result ofgettid(2)
instead ofgetpid(2)
to get sensible results whenF_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 usegettid(2)
orgetpid(2)
in this scenario.) Note, however, that the statements in this paragraph do not apply to theSIGURG
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 toF_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 targetSIGIO
andSIGURG
signals at a particular thread.F_GETOWN
- Return (as the function result) the process ID or process group ID currently receivingSIGIO
andSIGURG
signals for events on file descriptorfd
.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 inarg
.A value of zero means to send the default
SIGIO
signal. Any other value (includingSIGIO
) is the signal to send instead, and in this case additional info is available to the signal handler if installed withSA_SIGINFO
.By using
F_SETSIG
with a nonzero value, and settingSA_SIGINFO
for the signal handler (seesigaction(2)
), extra information about I/O events is passed to the handler in asiginfo_t
structure. If thesi_code
field indicates the source isSI_SIGIO
, thesi_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)
withO_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 theF_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 thesi_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 ifSA_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)
andsignal(7)
) and if this limit is reached, then the kernel reverts to deliveringSIGIO
, 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 (includingSIGIO
) is the signal sent instead, and in this case additional info is available to the signal handler if installed withSA_SIGINFO
.arg
is ignored.F_SETOWN_EX
- This operation performs a similar task toF_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 aFOwnerEx
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 previousF_SETOWN_EX
operation.The information is returned in the
FOwnerEx
structure pointed to byarg
.The type field will have one of the values
F_OWNER_TID
,F_OWNER_PID
, orF_OWNER_PGRP
. Thepid
field is a positive integer representing a thread ID, process ID, or process group ID. SeeF_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 returnsF_UNLCK
in thel_type
field oflock
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 vialock
, as described above forF_GETLK
.F_OFD_SETLK
- Acquire an open file description lock (whenl_type
isF_RDLCK
orF_WRLCK
) or release an open file description lock (whenl_type
isF_UNLCK
) on the bytes specified by thel_whence
,l_start
, andl_len
fields oflock
.If a conflicting lock is held by another process, this call returns -1 and sets
errno
toEAGAIN
.F_OFD_SETLKW
- As forF_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 toEINTR
; seesignal(7)
).F_SETLEASE
- Set or remove a file lease according to which of the following values is specified in the integerarg
:F_RDLCK
,F_WRLCK
,F_UNLCK
F_GETLEASE
- Indicates what type of lease is associated with the file descriptorfd
by returning eitherF_RDLCK
,F_WRLCK
, orF_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 byfd
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 inarg
, then notification will remain in effect until explicitly removed.A series of
F_NOTIFY
requests is cumulative, with the events inarg
being added to the set already monitored. To disable notification of all events, make anF_NOTIFY
call specifyingarg
as 0.Notification occurs via delivery of a signal. The default signal is
SIGIO
, but this can be changed using theF_SETSIG
command tofcntl()
. (Note thatSIGIO
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 asiginfo_t
structure as its second argument (if the handler was established usingSA_SIGINFO
) and thesi_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. Seeinotify(7)
.F_SETPIPE_SZ
- Change the capacity of the pipe referred to byfd
to be at leastarg
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
(seeproc(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 errorEPERM
; 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 byfd
.F_ADD_SEALS
- Add the seals given in the bit-mask argumentarg
to the set of seals of theinode
referred to by the file descriptorfd
.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 withEPERM
. Adding a seal that is already set is a no-op, in caseF_SEAL_SEAL
is not set already. In order to place a seal, the file descriptorfd
must be writable.F_GET_SEALS
- Return (as the function result) the current set of seals of theinode
referred to byfd
.If no seals are set, 0 is returned. If the file does not support sealing, -1 is returned and
errno
is set toEINVAL
.F_GET_RW_HINT
- Returns the value of the read/write hint associated with the underlyinginode
referred to byfd
.F_SET_RW_HINT
- Sets the read/write hint value associated with the underlyinginode
referred to byfd
.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 byfd
.F_SET_FILE_RW_HINT
- Sets the read/write hint value associated with the open file description referred to byfd
.F_DUPFD_CLOEXEC
- As forF_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 theFD_CLOEXEC
flag. For an explanation of why this flag is useful, see the description ofO_CLOEXEC
inopen(2)
.
- See Also:
-
F_SET_FILE_RW_HINT
public static final int F_SET_FILE_RW_HINTfcntl(int, int)
commands.Enum values:
F_DUPFD
- Duplicate the file descriptorfd
using the lowest-numbered available file descriptor greater than or equal toarg
.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 byarg
.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 byarg
.File access mode (
O_RDONLY
,O_WRONLY
,O_RDWR
) and file creation flags (i.e.,O_CREAT
,O_EXCL
,O_NOCTTY
,O_TRUNC
) inarg
are ignored. On Linux, this command can change only theO_APPEND
,O_ASYNC
,O_DIRECT
,O_NOATIME
, andO_NONBLOCK
flags. It is not possible to change theO_DSYNC
andO_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 returnsF_UNLCK
in thel_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 thel_type
,l_whence
,l_start
, andl_len
fields of lock. If the conflicting lock is a traditional (process-associated) record lock, then thel_pid
field is set to thePID
of the process holding that lock. If the conflicting lock is an open file description lock, thenl_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 (whenl_type
isF_RDLCK
orF_WRLCK
) or release a lock (whenl_type
isF_UNLCK
) on the bytes specified by thel_whence
,l_start
, andl_len
fields of lock.If a conflicting lock is held by another process, this call returns -1 and sets
errno
toEACCES
orEAGAIN
. (The error returned in this case differs across implementations, so POSIX requires a portable application to check for both errors.)F_SETLKW
- As forF_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
; seesignal(7)
).F_SETOWN
- Set the process ID or process group ID that will receiveSIGIO
andSIGURG
signals for events on the file descriptorfd
.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 asgetpid(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 theO_ASYNC
file status flag on the file descriptor. Subsequently, aSIGIO
signal is sent whenever input or output becomes possible on the file descriptor. Thefcntl()
F_SETSIG
command can be used to obtain delivery of a signal other thanSIGIO
.Sending a signal to the owner process (group) specified by
F_SETOWN
is subject to the same permissions checks as are described forkill(2)
, where the sending process is the one that employsF_SETOWN
(but see BUGS below). If this permission check fails, then the signal is silently discarded. Note: TheF_SETOWN
operation records the caller's credentials at the time of thefcntl()
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 ofSIGURG
signals that are delivered when out-of-band data arrives on that socket. (SIGURG
is sent in any situation whereselect(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 toF_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 passF_SETOWN
the result ofgettid(2)
instead ofgetpid(2)
to get sensible results whenF_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 usegettid(2)
orgetpid(2)
in this scenario.) Note, however, that the statements in this paragraph do not apply to theSIGURG
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 toF_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 targetSIGIO
andSIGURG
signals at a particular thread.F_GETOWN
- Return (as the function result) the process ID or process group ID currently receivingSIGIO
andSIGURG
signals for events on file descriptorfd
.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 inarg
.A value of zero means to send the default
SIGIO
signal. Any other value (includingSIGIO
) is the signal to send instead, and in this case additional info is available to the signal handler if installed withSA_SIGINFO
.By using
F_SETSIG
with a nonzero value, and settingSA_SIGINFO
for the signal handler (seesigaction(2)
), extra information about I/O events is passed to the handler in asiginfo_t
structure. If thesi_code
field indicates the source isSI_SIGIO
, thesi_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)
withO_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 theF_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 thesi_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 ifSA_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)
andsignal(7)
) and if this limit is reached, then the kernel reverts to deliveringSIGIO
, 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 (includingSIGIO
) is the signal sent instead, and in this case additional info is available to the signal handler if installed withSA_SIGINFO
.arg
is ignored.F_SETOWN_EX
- This operation performs a similar task toF_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 aFOwnerEx
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 previousF_SETOWN_EX
operation.The information is returned in the
FOwnerEx
structure pointed to byarg
.The type field will have one of the values
F_OWNER_TID
,F_OWNER_PID
, orF_OWNER_PGRP
. Thepid
field is a positive integer representing a thread ID, process ID, or process group ID. SeeF_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 returnsF_UNLCK
in thel_type
field oflock
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 vialock
, as described above forF_GETLK
.F_OFD_SETLK
- Acquire an open file description lock (whenl_type
isF_RDLCK
orF_WRLCK
) or release an open file description lock (whenl_type
isF_UNLCK
) on the bytes specified by thel_whence
,l_start
, andl_len
fields oflock
.If a conflicting lock is held by another process, this call returns -1 and sets
errno
toEAGAIN
.F_OFD_SETLKW
- As forF_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 toEINTR
; seesignal(7)
).F_SETLEASE
- Set or remove a file lease according to which of the following values is specified in the integerarg
:F_RDLCK
,F_WRLCK
,F_UNLCK
F_GETLEASE
- Indicates what type of lease is associated with the file descriptorfd
by returning eitherF_RDLCK
,F_WRLCK
, orF_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 byfd
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 inarg
, then notification will remain in effect until explicitly removed.A series of
F_NOTIFY
requests is cumulative, with the events inarg
being added to the set already monitored. To disable notification of all events, make anF_NOTIFY
call specifyingarg
as 0.Notification occurs via delivery of a signal. The default signal is
SIGIO
, but this can be changed using theF_SETSIG
command tofcntl()
. (Note thatSIGIO
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 asiginfo_t
structure as its second argument (if the handler was established usingSA_SIGINFO
) and thesi_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. Seeinotify(7)
.F_SETPIPE_SZ
- Change the capacity of the pipe referred to byfd
to be at leastarg
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
(seeproc(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 errorEPERM
; 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 byfd
.F_ADD_SEALS
- Add the seals given in the bit-mask argumentarg
to the set of seals of theinode
referred to by the file descriptorfd
.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 withEPERM
. Adding a seal that is already set is a no-op, in caseF_SEAL_SEAL
is not set already. In order to place a seal, the file descriptorfd
must be writable.F_GET_SEALS
- Return (as the function result) the current set of seals of theinode
referred to byfd
.If no seals are set, 0 is returned. If the file does not support sealing, -1 is returned and
errno
is set toEINVAL
.F_GET_RW_HINT
- Returns the value of the read/write hint associated with the underlyinginode
referred to byfd
.F_SET_RW_HINT
- Sets the read/write hint value associated with the underlyinginode
referred to byfd
.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 byfd
.F_SET_FILE_RW_HINT
- Sets the read/write hint value associated with the open file description referred to byfd
.F_DUPFD_CLOEXEC
- As forF_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 theFD_CLOEXEC
flag. For an explanation of why this flag is useful, see the description ofO_CLOEXEC
inopen(2)
.
- See Also:
-
F_DUPFD_CLOEXEC
public static final int F_DUPFD_CLOEXECfcntl(int, int)
commands.Enum values:
F_DUPFD
- Duplicate the file descriptorfd
using the lowest-numbered available file descriptor greater than or equal toarg
.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 byarg
.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 byarg
.File access mode (
O_RDONLY
,O_WRONLY
,O_RDWR
) and file creation flags (i.e.,O_CREAT
,O_EXCL
,O_NOCTTY
,O_TRUNC
) inarg
are ignored. On Linux, this command can change only theO_APPEND
,O_ASYNC
,O_DIRECT
,O_NOATIME
, andO_NONBLOCK
flags. It is not possible to change theO_DSYNC
andO_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 returnsF_UNLCK
in thel_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 thel_type
,l_whence
,l_start
, andl_len
fields of lock. If the conflicting lock is a traditional (process-associated) record lock, then thel_pid
field is set to thePID
of the process holding that lock. If the conflicting lock is an open file description lock, thenl_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 (whenl_type
isF_RDLCK
orF_WRLCK
) or release a lock (whenl_type
isF_UNLCK
) on the bytes specified by thel_whence
,l_start
, andl_len
fields of lock.If a conflicting lock is held by another process, this call returns -1 and sets
errno
toEACCES
orEAGAIN
. (The error returned in this case differs across implementations, so POSIX requires a portable application to check for both errors.)F_SETLKW
- As forF_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
; seesignal(7)
).F_SETOWN
- Set the process ID or process group ID that will receiveSIGIO
andSIGURG
signals for events on the file descriptorfd
.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 asgetpid(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 theO_ASYNC
file status flag on the file descriptor. Subsequently, aSIGIO
signal is sent whenever input or output becomes possible on the file descriptor. Thefcntl()
F_SETSIG
command can be used to obtain delivery of a signal other thanSIGIO
.Sending a signal to the owner process (group) specified by
F_SETOWN
is subject to the same permissions checks as are described forkill(2)
, where the sending process is the one that employsF_SETOWN
(but see BUGS below). If this permission check fails, then the signal is silently discarded. Note: TheF_SETOWN
operation records the caller's credentials at the time of thefcntl()
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 ofSIGURG
signals that are delivered when out-of-band data arrives on that socket. (SIGURG
is sent in any situation whereselect(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 toF_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 passF_SETOWN
the result ofgettid(2)
instead ofgetpid(2)
to get sensible results whenF_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 usegettid(2)
orgetpid(2)
in this scenario.) Note, however, that the statements in this paragraph do not apply to theSIGURG
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 toF_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 targetSIGIO
andSIGURG
signals at a particular thread.F_GETOWN
- Return (as the function result) the process ID or process group ID currently receivingSIGIO
andSIGURG
signals for events on file descriptorfd
.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 inarg
.A value of zero means to send the default
SIGIO
signal. Any other value (includingSIGIO
) is the signal to send instead, and in this case additional info is available to the signal handler if installed withSA_SIGINFO
.By using
F_SETSIG
with a nonzero value, and settingSA_SIGINFO
for the signal handler (seesigaction(2)
), extra information about I/O events is passed to the handler in asiginfo_t
structure. If thesi_code
field indicates the source isSI_SIGIO
, thesi_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)
withO_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 theF_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 thesi_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 ifSA_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)
andsignal(7)
) and if this limit is reached, then the kernel reverts to deliveringSIGIO
, 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 (includingSIGIO
) is the signal sent instead, and in this case additional info is available to the signal handler if installed withSA_SIGINFO
.arg
is ignored.F_SETOWN_EX
- This operation performs a similar task toF_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 aFOwnerEx
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 previousF_SETOWN_EX
operation.The information is returned in the
FOwnerEx
structure pointed to byarg
.The type field will have one of the values
F_OWNER_TID
,F_OWNER_PID
, orF_OWNER_PGRP
. Thepid
field is a positive integer representing a thread ID, process ID, or process group ID. SeeF_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 returnsF_UNLCK
in thel_type
field oflock
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 vialock
, as described above forF_GETLK
.F_OFD_SETLK
- Acquire an open file description lock (whenl_type
isF_RDLCK
orF_WRLCK
) or release an open file description lock (whenl_type
isF_UNLCK
) on the bytes specified by thel_whence
,l_start
, andl_len
fields oflock
.If a conflicting lock is held by another process, this call returns -1 and sets
errno
toEAGAIN
.F_OFD_SETLKW
- As forF_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 toEINTR
; seesignal(7)
).F_SETLEASE
- Set or remove a file lease according to which of the following values is specified in the integerarg
:F_RDLCK
,F_WRLCK
,F_UNLCK
F_GETLEASE
- Indicates what type of lease is associated with the file descriptorfd
by returning eitherF_RDLCK
,F_WRLCK
, orF_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 byfd
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 inarg
, then notification will remain in effect until explicitly removed.A series of
F_NOTIFY
requests is cumulative, with the events inarg
being added to the set already monitored. To disable notification of all events, make anF_NOTIFY
call specifyingarg
as 0.Notification occurs via delivery of a signal. The default signal is
SIGIO
, but this can be changed using theF_SETSIG
command tofcntl()
. (Note thatSIGIO
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 asiginfo_t
structure as its second argument (if the handler was established usingSA_SIGINFO
) and thesi_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. Seeinotify(7)
.F_SETPIPE_SZ
- Change the capacity of the pipe referred to byfd
to be at leastarg
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
(seeproc(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 errorEPERM
; 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 byfd
.F_ADD_SEALS
- Add the seals given in the bit-mask argumentarg
to the set of seals of theinode
referred to by the file descriptorfd
.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 withEPERM
. Adding a seal that is already set is a no-op, in caseF_SEAL_SEAL
is not set already. In order to place a seal, the file descriptorfd
must be writable.F_GET_SEALS
- Return (as the function result) the current set of seals of theinode
referred to byfd
.If no seals are set, 0 is returned. If the file does not support sealing, -1 is returned and
errno
is set toEINVAL
.F_GET_RW_HINT
- Returns the value of the read/write hint associated with the underlyinginode
referred to byfd
.F_SET_RW_HINT
- Sets the read/write hint value associated with the underlyinginode
referred to byfd
.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 byfd
.F_SET_FILE_RW_HINT
- Sets the read/write hint value associated with the open file description referred to byfd
.F_DUPFD_CLOEXEC
- As forF_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 theFD_CLOEXEC
flag. For an explanation of why this flag is useful, see the description ofO_CLOEXEC
inopen(2)
.
- See Also:
-
FD_CLOEXEC
public static final int FD_CLOEXEC- See Also:
-
F_RDLCK
public static final int F_RDLCKFor posixfcntl(int, int)
andl_type
field of anFlock
forlockf()
.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_WRLCKFor posixfcntl(int, int)
andl_type
field of anFlock
forlockf()
.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_UNLCKFor posixfcntl(int, int)
andl_type
field of anFlock
forlockf()
.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_EXLCKFor posixfcntl(int, int)
andl_type
field of anFlock
forlockf()
.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_SHLCKFor posixfcntl(int, int)
andl_type
field of anFlock
forlockf()
.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_TIDFOwnerEx
::type
values.Enum values:
F_OWNER_TID
- Send the signal to the thread whose thread ID (the value returned by a call toclone(2)
orgettid(2)
) is specified inpid
.F_OWNER_PID
- Send the signal to the process whose ID is specified inpid
.F_OWNER_PGRP
- Send the signal to the process group whose ID is specified inpid
.(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_PIDFOwnerEx
::type
values.Enum values:
F_OWNER_TID
- Send the signal to the thread whose thread ID (the value returned by a call toclone(2)
orgettid(2)
) is specified inpid
.F_OWNER_PID
- Send the signal to the process whose ID is specified inpid
.F_OWNER_PGRP
- Send the signal to the process group whose ID is specified inpid
.(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_PGRPFOwnerEx
::type
values.Enum values:
F_OWNER_TID
- Send the signal to the thread whose thread ID (the value returned by a call toclone(2)
orgettid(2)
) is specified inpid
.F_OWNER_PID
- Send the signal to the process whose ID is specified inpid
.F_OWNER_PGRP
- Send the signal to the process group whose ID is specified inpid
.(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_SHEnum values:
LOCK_SH
- shared lockLOCK_EX
- exclusive lockLOCK_NB
- or'd with one of the above to prevent blockingLOCK_UN
- remove lockLOCK_MAND
- This is a mandatory flock...LOCK_READ
- which allows concurrent read operationsLOCK_WRITE
- which allows concurrent write operationsLOCK_RW
- which allows concurrent read & writes ops
- See Also:
-
LOCK_EX
public static final int LOCK_EXEnum values:
LOCK_SH
- shared lockLOCK_EX
- exclusive lockLOCK_NB
- or'd with one of the above to prevent blockingLOCK_UN
- remove lockLOCK_MAND
- This is a mandatory flock...LOCK_READ
- which allows concurrent read operationsLOCK_WRITE
- which allows concurrent write operationsLOCK_RW
- which allows concurrent read & writes ops
- See Also:
-
LOCK_NB
public static final int LOCK_NBEnum values:
LOCK_SH
- shared lockLOCK_EX
- exclusive lockLOCK_NB
- or'd with one of the above to prevent blockingLOCK_UN
- remove lockLOCK_MAND
- This is a mandatory flock...LOCK_READ
- which allows concurrent read operationsLOCK_WRITE
- which allows concurrent write operationsLOCK_RW
- which allows concurrent read & writes ops
- See Also:
-
LOCK_UN
public static final int LOCK_UNEnum values:
LOCK_SH
- shared lockLOCK_EX
- exclusive lockLOCK_NB
- or'd with one of the above to prevent blockingLOCK_UN
- remove lockLOCK_MAND
- This is a mandatory flock...LOCK_READ
- which allows concurrent read operationsLOCK_WRITE
- which allows concurrent write operationsLOCK_RW
- which allows concurrent read & writes ops
- See Also:
-
LOCK_MAND
public static final int LOCK_MANDEnum values:
LOCK_SH
- shared lockLOCK_EX
- exclusive lockLOCK_NB
- or'd with one of the above to prevent blockingLOCK_UN
- remove lockLOCK_MAND
- This is a mandatory flock...LOCK_READ
- which allows concurrent read operationsLOCK_WRITE
- which allows concurrent write operationsLOCK_RW
- which allows concurrent read & writes ops
- See Also:
-
LOCK_READ
public static final int LOCK_READEnum values:
LOCK_SH
- shared lockLOCK_EX
- exclusive lockLOCK_NB
- or'd with one of the above to prevent blockingLOCK_UN
- remove lockLOCK_MAND
- This is a mandatory flock...LOCK_READ
- which allows concurrent read operationsLOCK_WRITE
- which allows concurrent write operationsLOCK_RW
- which allows concurrent read & writes ops
- See Also:
-
LOCK_WRITE
public static final int LOCK_WRITEEnum values:
LOCK_SH
- shared lockLOCK_EX
- exclusive lockLOCK_NB
- or'd with one of the above to prevent blockingLOCK_UN
- remove lockLOCK_MAND
- This is a mandatory flock...LOCK_READ
- which allows concurrent read operationsLOCK_WRITE
- which allows concurrent write operationsLOCK_RW
- which allows concurrent read & writes ops
- See Also:
-
LOCK_RW
public static final int LOCK_RWEnum values:
LOCK_SH
- shared lockLOCK_EX
- exclusive lockLOCK_NB
- or'd with one of the above to prevent blockingLOCK_UN
- remove lockLOCK_MAND
- This is a mandatory flock...LOCK_READ
- which allows concurrent read operationsLOCK_WRITE
- which allows concurrent write operationsLOCK_RW
- which allows concurrent read & writes ops
- See Also:
-
DN_ACCESS
public static final int DN_ACCESSEnum 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_MODIFYEnum 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_CREATEEnum 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_DELETEEnum 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_RENAMEEnum 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_ATTRIBEnum 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_MULTISHOTEnum 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_SEALEnum values:
F_SEAL_SEAL
- If this seal is set, any further call tofcntl()
withF_ADD_SEALS
fails with the errorEPERM
.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 theO_TRUNC
flag as well astruncate(2)
andftruncate(2)
. Those calls fail withEPERM
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)
, andfallocate(2)
. These calls fail withEPERM
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)
andfallocate(2)
(only in combination with theFALLOC_FL_PUNCH_HOLE
flag). Those calls fail withEPERM
if this seal is set. Furthermore, trying to create new shared, writable memory-mappings viammap(2)
will also fail withEPERM
.Using the
F_ADD_SEALS
operation to set theF_SEAL_WRITE
seal fails withEBUSY
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 toF_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 withEPERM
. Likewise, an attempt to write to the file viawrite(2)
will fail withEPERM
.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_SHRINKEnum values:
F_SEAL_SEAL
- If this seal is set, any further call tofcntl()
withF_ADD_SEALS
fails with the errorEPERM
.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 theO_TRUNC
flag as well astruncate(2)
andftruncate(2)
. Those calls fail withEPERM
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)
, andfallocate(2)
. These calls fail withEPERM
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)
andfallocate(2)
(only in combination with theFALLOC_FL_PUNCH_HOLE
flag). Those calls fail withEPERM
if this seal is set. Furthermore, trying to create new shared, writable memory-mappings viammap(2)
will also fail withEPERM
.Using the
F_ADD_SEALS
operation to set theF_SEAL_WRITE
seal fails withEBUSY
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 toF_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 withEPERM
. Likewise, an attempt to write to the file viawrite(2)
will fail withEPERM
.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_GROWEnum values:
F_SEAL_SEAL
- If this seal is set, any further call tofcntl()
withF_ADD_SEALS
fails with the errorEPERM
.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 theO_TRUNC
flag as well astruncate(2)
andftruncate(2)
. Those calls fail withEPERM
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)
, andfallocate(2)
. These calls fail withEPERM
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)
andfallocate(2)
(only in combination with theFALLOC_FL_PUNCH_HOLE
flag). Those calls fail withEPERM
if this seal is set. Furthermore, trying to create new shared, writable memory-mappings viammap(2)
will also fail withEPERM
.Using the
F_ADD_SEALS
operation to set theF_SEAL_WRITE
seal fails withEBUSY
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 toF_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 withEPERM
. Likewise, an attempt to write to the file viawrite(2)
will fail withEPERM
.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_WRITEEnum values:
F_SEAL_SEAL
- If this seal is set, any further call tofcntl()
withF_ADD_SEALS
fails with the errorEPERM
.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 theO_TRUNC
flag as well astruncate(2)
andftruncate(2)
. Those calls fail withEPERM
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)
, andfallocate(2)
. These calls fail withEPERM
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)
andfallocate(2)
(only in combination with theFALLOC_FL_PUNCH_HOLE
flag). Those calls fail withEPERM
if this seal is set. Furthermore, trying to create new shared, writable memory-mappings viammap(2)
will also fail withEPERM
.Using the
F_ADD_SEALS
operation to set theF_SEAL_WRITE
seal fails withEBUSY
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 toF_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 withEPERM
. Likewise, an attempt to write to the file viawrite(2)
will fail withEPERM
.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_WRITEEnum values:
F_SEAL_SEAL
- If this seal is set, any further call tofcntl()
withF_ADD_SEALS
fails with the errorEPERM
.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 theO_TRUNC
flag as well astruncate(2)
andftruncate(2)
. Those calls fail withEPERM
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)
, andfallocate(2)
. These calls fail withEPERM
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)
andfallocate(2)
(only in combination with theFALLOC_FL_PUNCH_HOLE
flag). Those calls fail withEPERM
if this seal is set. Furthermore, trying to create new shared, writable memory-mappings viammap(2)
will also fail withEPERM
.Using the
F_ADD_SEALS
operation to set theF_SEAL_WRITE
seal fails withEBUSY
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 toF_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 withEPERM
. Likewise, an attempt to write to the file viawrite(2)
will fail withEPERM
.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_SETEnum values:
RWH_WRITE_LIFE_NOT_SET
- No specific hint has been set. This is the default value.RWH_WRITE_LIFE_NONE
- No specific write lifetime is associated with this file orinode
.RWH_WRITE_LIFE_SHORT
- Data written to thisinode
or via this open file description is expected to have a short lifetime.RWH_WRITE_LIFE_MEDIUM
- Data written to thisinode
or via this open file description is expected to have a lifetime longer than data written withRWH_WRITE_LIFE_SHORT
.RWH_WRITE_LIFE_LONG
- Data written to thisinode
or via this open file description is expected to have a lifetime longer than data written withRWH_WRITE_LIFE_MEDIUM
.RWH_WRITE_LIFE_EXTREME
- Data written to thisinode
or via this open file description is expected to have a lifetime longer than data written withRWH_WRITE_LIFE_LONG
.
- See Also:
-
RWH_WRITE_LIFE_NONE
public static final int RWH_WRITE_LIFE_NONEEnum values:
RWH_WRITE_LIFE_NOT_SET
- No specific hint has been set. This is the default value.RWH_WRITE_LIFE_NONE
- No specific write lifetime is associated with this file orinode
.RWH_WRITE_LIFE_SHORT
- Data written to thisinode
or via this open file description is expected to have a short lifetime.RWH_WRITE_LIFE_MEDIUM
- Data written to thisinode
or via this open file description is expected to have a lifetime longer than data written withRWH_WRITE_LIFE_SHORT
.RWH_WRITE_LIFE_LONG
- Data written to thisinode
or via this open file description is expected to have a lifetime longer than data written withRWH_WRITE_LIFE_MEDIUM
.RWH_WRITE_LIFE_EXTREME
- Data written to thisinode
or via this open file description is expected to have a lifetime longer than data written withRWH_WRITE_LIFE_LONG
.
- See Also:
-
RWH_WRITE_LIFE_SHORT
public static final int RWH_WRITE_LIFE_SHORTEnum values:
RWH_WRITE_LIFE_NOT_SET
- No specific hint has been set. This is the default value.RWH_WRITE_LIFE_NONE
- No specific write lifetime is associated with this file orinode
.RWH_WRITE_LIFE_SHORT
- Data written to thisinode
or via this open file description is expected to have a short lifetime.RWH_WRITE_LIFE_MEDIUM
- Data written to thisinode
or via this open file description is expected to have a lifetime longer than data written withRWH_WRITE_LIFE_SHORT
.RWH_WRITE_LIFE_LONG
- Data written to thisinode
or via this open file description is expected to have a lifetime longer than data written withRWH_WRITE_LIFE_MEDIUM
.RWH_WRITE_LIFE_EXTREME
- Data written to thisinode
or via this open file description is expected to have a lifetime longer than data written withRWH_WRITE_LIFE_LONG
.
- See Also:
-
RWH_WRITE_LIFE_MEDIUM
public static final int RWH_WRITE_LIFE_MEDIUMEnum values:
RWH_WRITE_LIFE_NOT_SET
- No specific hint has been set. This is the default value.RWH_WRITE_LIFE_NONE
- No specific write lifetime is associated with this file orinode
.RWH_WRITE_LIFE_SHORT
- Data written to thisinode
or via this open file description is expected to have a short lifetime.RWH_WRITE_LIFE_MEDIUM
- Data written to thisinode
or via this open file description is expected to have a lifetime longer than data written withRWH_WRITE_LIFE_SHORT
.RWH_WRITE_LIFE_LONG
- Data written to thisinode
or via this open file description is expected to have a lifetime longer than data written withRWH_WRITE_LIFE_MEDIUM
.RWH_WRITE_LIFE_EXTREME
- Data written to thisinode
or via this open file description is expected to have a lifetime longer than data written withRWH_WRITE_LIFE_LONG
.
- See Also:
-
RWH_WRITE_LIFE_LONG
public static final int RWH_WRITE_LIFE_LONGEnum values:
RWH_WRITE_LIFE_NOT_SET
- No specific hint has been set. This is the default value.RWH_WRITE_LIFE_NONE
- No specific write lifetime is associated with this file orinode
.RWH_WRITE_LIFE_SHORT
- Data written to thisinode
or via this open file description is expected to have a short lifetime.RWH_WRITE_LIFE_MEDIUM
- Data written to thisinode
or via this open file description is expected to have a lifetime longer than data written withRWH_WRITE_LIFE_SHORT
.RWH_WRITE_LIFE_LONG
- Data written to thisinode
or via this open file description is expected to have a lifetime longer than data written withRWH_WRITE_LIFE_MEDIUM
.RWH_WRITE_LIFE_EXTREME
- Data written to thisinode
or via this open file description is expected to have a lifetime longer than data written withRWH_WRITE_LIFE_LONG
.
- See Also:
-
RWH_WRITE_LIFE_EXTREME
public static final int RWH_WRITE_LIFE_EXTREMEEnum values:
RWH_WRITE_LIFE_NOT_SET
- No specific hint has been set. This is the default value.RWH_WRITE_LIFE_NONE
- No specific write lifetime is associated with this file orinode
.RWH_WRITE_LIFE_SHORT
- Data written to thisinode
or via this open file description is expected to have a short lifetime.RWH_WRITE_LIFE_MEDIUM
- Data written to thisinode
or via this open file description is expected to have a lifetime longer than data written withRWH_WRITE_LIFE_SHORT
.RWH_WRITE_LIFE_LONG
- Data written to thisinode
or via this open file description is expected to have a lifetime longer than data written withRWH_WRITE_LIFE_MEDIUM
.RWH_WRITE_LIFE_EXTREME
- Data written to thisinode
or via this open file description is expected to have a lifetime longer than data written withRWH_WRITE_LIFE_LONG
.
- See Also:
-
-
Method Details
-
nopen
public static int nopen(long pathname, int flags, int mode) Unsafe version of:open(java.nio.ByteBuffer, int, int)
-
open
Given apathname
for a file,open()
returns a file descriptor, a small, nonnegative integer for use in subsequent system calls (read(2)
,write(2)
,lseek(2)
,fcntl(2)
, etc.).The file descriptor returned by a successful call will be the lowest-numbered file descriptor not currently open for the process.
-
open
Given apathname
for a file,open()
returns a file descriptor, a small, nonnegative integer for use in subsequent system calls (read(2)
,write(2)
,lseek(2)
,fcntl(2)
, etc.).The file descriptor returned by a successful call will be the lowest-numbered file descriptor not currently open for the process.
-
nopenat
public static int nopenat(int dirfd, long pathname, int flags, int mode) Unsafe version of:openat(int, java.nio.ByteBuffer, int, int)
-
openat
Theopenat()
system call operates in exactly the same way asopen(2)
, except for the differences described in this manual page.If the pathname given in
pathname
is relative, then it is interpreted relative to the directory referred to by the file descriptordirfd
(rather than relative to the current working directory of the calling process, as is done byopen(2)
for a relative pathname).If
pathname
is relative anddirfd
is the special valueAT_FDCWD
, then pathname is interpreted relative to the current working directory of the calling process (likeopen(2)
).If
pathname
is absolute, thendirfd
is ignored. -
openat
Theopenat()
system call operates in exactly the same way asopen(2)
, except for the differences described in this manual page.If the pathname given in
pathname
is relative, then it is interpreted relative to the directory referred to by the file descriptordirfd
(rather than relative to the current working directory of the calling process, as is done byopen(2)
for a relative pathname).If
pathname
is relative anddirfd
is the special valueAT_FDCWD
, then pathname is interpreted relative to the current working directory of the calling process (likeopen(2)
).If
pathname
is absolute, thendirfd
is ignored. -
ncreat
public static int ncreat(long pathname, int mode) Unsafe version of:creat(java.nio.ByteBuffer, int)
-
creat
Equivalent toopen()
withflags
equal toO_CREAT|O_WRONLY|O_TRUNC
. -
creat
Equivalent toopen()
withflags
equal toO_CREAT|O_WRONLY|O_TRUNC
. -
fcntl
public static int fcntl(int fd, int cmd) Performs one of the operations determined bycmd
on the open file descriptorfd
.fcntl()
can take an optional third argument. Whether or not this argument is required is determined bycmd
. The required argument type is indicated in parentheses after eachcmd
name (in most cases, the required type isint
, and we identify the argument using the namearg
), orvoid
is specified if the argument is not required.LWJGL note: Use
fcntli(int, int, int)
orfcntlp(int, int, long)
to pass a third argument of the appropriate type.Certain of the operations below are supported only since a particular Linux kernel version. The preferred method of checking whether the host kernel supports a particular operation is to invoke
fcntl()
with the desiredcmd
value and then test whether the call failed withEINVAL
, indicating that the kernel does not recognize this value.- Parameters:
cmd
- one of:
-
nfcntli
public static int nfcntli(int fd, int cmd, int arg) Unsafe version of:fcntli(int, int, int)
-
fcntli
public static int fcntli(int fd, int cmd, int arg) fcntl(int, int)
overload that takes a third argument of typeint
.- Parameters:
cmd
- one of:
-
nfcntlp
public static int nfcntlp(int fd, int cmd, long arg) Unsafe version of:fcntlp(int, int, long)
-
fcntlp
public static int fcntlp(int fd, int cmd, long arg) fcntl(int, int)
overload that takes a third argument of typevoid *
.- Parameters:
cmd
- one of:
-