.\" manual under the conditions for verbatim copying, provided that the
.\" entire resulting derived work is distributed under the terms of a
.\" permission notice identical to this one.
-.\"
+.\"
.\" Since the Linux kernel and libraries are constantly changing, this
.\" manual page may be incorrect or out-of-date. The author(s) assume no
.\" responsibility for errors or omissions, or for damages resulting from
.\" have taken the same level of care in the production of this manual,
.\" which is licensed free of charge, as they might when working
.\" professionally.
-.\"
+.\"
.\" Formatted or processed versions of this manual, if unaccompanied by
.\" the source, must acknowledge the copyright and authors of this work.
.\"
.\" Modified, 27 May 2004, Michael Kerrisk <mtk-manpages@gmx.net>
.\" Added notes on capability requirements
.\" Modified 2004-12-08, added O_NOATIME after note from Martin Pool
-.\" 2004-12-10, mtk, noted F_GETOWN bug after suggestion from aeb.
+.\" 2004-12-10, mtk, noted F_GETOWN bug after suggestion from aeb.
.\" 2005-04-08 Jamie Lokier <jamie@shareable.org>, mtk
.\" Described behaviour of F_SETOWN/F_SETSIG in
.\" multi-threaded processes, and generally cleaned
.\" up the discussion of F_SETOWN.
-.\" 2005-05-20, Johannes Nicolai <johannes.nicolai@hpi.uni-potsdam.de>,
+.\" 2005-05-20, Johannes Nicolai <johannes.nicolai@hpi.uni-potsdam.de>,
.\" mtk: Noted F_SETOWN bug for socket file descriptor in Linux 2.4
.\" and earlier. Added text on permissions required to send signal.
.\"
for further details.
.SS "File descriptor flags"
The following commands manipulate the flags associated with
-a file descriptor.
+a file descriptor.
Currently, only one such flag is defined:
.BR FD_CLOEXEC ,
the close-on-exec flag.
.\" .BR creat (2),
and possibly modified by
.BR fcntl (2).
-Duplicated file descriptors
+Duplicated file descriptors
(made with
.BR dup (),
.BR fcntl (F_DUPFD),
.B F_SETFL
Set the file status flags to the value specified by
.IR arg .
-File access mode
+File access mode
.RB ( O_RDONLY ", " O_WRONLY ", " O_RDWR )
and file creation flags
(i.e.,
.I arg
are ignored.
On Linux this command can only change the
-.BR O_APPEND ,
+.BR O_APPEND ,
.BR O_ASYNC ,
.BR O_DIRECT ,
.BR O_NOATIME ,
-and
-.BR O_NONBLOCK
+and
+.BR O_NONBLOCK
flags.
.\" FIXME According to POSIX.1-2001, O_SYNC should also be modifiable
.\" via fcntl(2), but currently Linux does not permit this
library, the use of record locking with routines in that package
should be avoided; use
.BR read (2)
-and
+and
.BR write (2)
instead.
.SS "Mandatory locking"
and are advisory by default.
Advisory locks are not enforced and are useful only between
-cooperating processes.
+cooperating processes.
-Mandatory locks are enforced for all processes.
+Mandatory locks are enforced for all processes.
If a process tries to perform an incompatible access (e.g.,
.BR read (2)
or
then the result depends upon whether the
.B O_NONBLOCK
flag is enabled for its open file description.
-If the
+If the
.B O_NONBLOCK
flag is not enabled, then
system call is blocked until the lock is removed
or converted to a mode that is compatible with the access.
-If the
-.B O_NONBLOCK
+If the
+.B O_NONBLOCK
flag is enabled, then the system call fails with the error
-.BR EAGAIN
+.BR EAGAIN
or
.BR EWOULDBLOCK.
To make use of mandatory locks, mandatory locking must be enabled
-both on the file system that contains the file to be locked,
+both on the file system that contains the file to be locked,
and on the file itself.
Mandatory locking is enabled on a file system
using the "\-o mand" option to
.BR mount (8),
-or the
+or the
.B MS_MANDLOCK
-flag for
+flag for
.BR mount (2).
Mandatory locking is enabled on a file by disabling
group execute permission on the file and enabling the set-group-ID
permission bit (see
.BR chmod (1)
-and
+and
.BR chmod (2)).
.SS "Managing signals"
.BR F_GETOWN ", " F_SETOWN ", " F_GETSIG " and " F_SETSIG
.B O_ASYNC
status flag on a file descriptor (either by providing this flag with the
.BR open (2)
-.\" FIXME The statement that O_ASYNC can be used in open() does not
-.\" match reality; setting O_ASYNC via open() does not seem to be
+.\" FIXME The statement that O_ASYNC can be used in open() does not
+.\" match reality; setting O_ASYNC via open() does not seem to be
.\" effective.
.\" See http://bugzilla.kernel.org/show_bug.cgi?id=5993
call, or by using the
is subject to the same permissions checks as are described for
.BR kill (2),
where the sending process is the one that employs
-.BR F_SETOWN
+.BR F_SETOWN
(but see BUGS below).
.sp
If the file descriptor
.B F_SETOWN
also selects
the recipient of SIGURG signals that are delivered when out-of-band
-data arrives on that socket. (SIGURG is sent in any situation where
+data arrives on that socket.
+(SIGURG is sent in any situation where
.BR select (2)
would report the socket as having an "exceptional condition".)
.\" The following appears to be rubbish. It doesn't seem to
-.\" be true according to the kernel source, and I can write
+.\" be true according to the kernel source, and I can write
.\" a program that gets a terminal-generated SIGIO even though
.\" it is not the foreground process group of the terminal.
.\" -- MTK, 8 Apr 05
-.\"
+.\"
.\" If the file descriptor
.\" .I fd
.\" refers to a terminal device, then SIGIO
.B F_SETSIG
in a multi-threaded process running with a threading library
that supports thread groups (e.g., NPTL),
-then a positive value given to
+then a positive value given to
.B F_SETOWN
has a different meaning:
-.\" The relevant place in the (2.6) kernel source is the
+.\" The relevant place in the (2.6) kernel source is the
.\" 'switch' in fs/fcntl.c::send_sigio_to_task() -- MTK, Apr 2005
instead of being a process ID identifying a whole process,
it is a thread ID identifying a specific thread within a process.
this signal is always sent to either a process or a process group,
depending on the value given to
.BR F_SETOWN .
-.\" send_sigurg()/send_sigurg_to_task() bypasses
+.\" send_sigurg()/send_sigurg_to_task() bypasses
.\" kill_fasync()/send_sigio()/send_sigio_to_task()
-.\" to directly call send_group_sig_info()
+.\" to directly call send_group_sig_info()
.\" -- MTK, Apr 2005 (kernel 2.6.11)
Note also that Linux imposes a limit on the
number of real-time signals that may be queued to a
.BR getrlimit (2)
and
.BR signal (7))
-and if this limit is reached, then the kernel reverts to
+and if this limit is reached, then the kernel reverts to
delivering SIGIO, and this signal is delivered to the entire
process rather than to a specific thread.
.\" See fs/fcntl.c::send_sigio_to_task() (2.4/2.6) sources -- MTK, Apr 05
.TP
.B F_GETSIG
-Get the signal sent when input or output becomes possible. A value of
-zero means SIGIO is sent. Any other value (including SIGIO) is the
+Get the signal sent when input or output becomes possible.
+A value of zero means SIGIO is sent.
+Any other value (including SIGIO) is the
signal sent instead, and in this case additional info is available to
the signal handler if installed with SA_SIGINFO.
.TP
.B F_SETSIG
-Sets the signal sent when input or output becomes possible. A value of
-zero means to send the default SIGIO signal. Any other value (including
+Sets the signal sent when input or output becomes possible.
+A value of zero means to send the default SIGIO signal.
+Any other value (including
SIGIO) is the signal to send instead, and in this case additional info
is available to the signal handler if installed with SA_SIGINFO.
.sp
changes the signal recipient from a whole process to a specific thread
within a process.
See the description of
-.B F_SETOWN
+.B F_SETOWN
for more details.
.sp
By using
.I si_code
field indicates the source is SI_SIGIO, the
.I si_fd
-field gives the file descriptor associated with the event. Otherwise,
+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
.RB ( select (2),
set etc.) to determine which file descriptors are available for I/O.
.sp
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
+I/O events may be queued using the same signal numbers.
+(Queuing is dependent on available memory).
+Extra information is available
if SA_SIGINFO is set for the signal handler, as above.
.PP
Using these mechanisms, a program can implement fully asynchronous I/O
.B F_GETSIG
and
.B F_SETSIG
-are Linux specific. POSIX has asynchronous I/O and the
+are Linux specific.
+POSIX has asynchronous I/O and the
.I aio_sigevent
structure to achieve similar things; these are also available
in Linux as part of the GNU C Library (Glibc).
the file is opened for writing or is truncated.
.\" The following became true in kernel 2.6.10:
.\" See the man-pages-2.09 Changelog for further info.
-A read lease can only be placed on a file descriptor that
+A read lease can only be placed on a file descriptor that
is opened read-only.
.TP
.B F_WRLCK
Take out a write lease.
-This will cause the caller to be notified when
+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 no other process
currently has the file open.
the kernel permits the lease breaker's system call to proceed.
If the lease breaker's blocked
-.BR open ()
-or
+.BR open ()
+or
.BR truncate ()
-is interrupted by a signal handler,
-then the system call fails with the error
-.BR EINTR ,
+is interrupted by a signal handler,
+then the system call fails with the error
+.BR EINTR ,
but the other steps still occur as described above.
-If the lease breaker is killed by a signal while blocked in
-.BR open ()
-or
+If the lease breaker is killed by a signal while blocked in
+.BR open ()
+or
.BR truncate (),
then the other steps still occur as described above.
-If the lease breaker specifies the
-.B O_NONBLOCK
-flag when calling
+If the lease breaker specifies the
+.B O_NONBLOCK
+flag when calling
.BR open (),
-then the call immediately fails with the error
-.BR EWOULDBLOCK ,
+then the call immediately fails with the error
+.BR EWOULDBLOCK ,
but the other steps still occur as described above.
The default signal used to notify the lease holder is SIGIO,
(chown, chmod, utime[s])
.TE
.sp
-(In order to obtain these definitions, the _GNU_SOURCE feature test macro
+(In order to obtain these definitions, the _GNU_SOURCE feature test macro
must be defined.)
.sp
Directory notifications are normally "one-shot", and the application
.B NOTE:
New applications should consider using the
-.I inotify
+.I inotify
interface (available since kernel 2.6.13),
-which provides a superior interface for obtaining notifications of
-file system events. See
+which provides a superior interface for obtaining notifications of
+file system events.
+See
.BR inotify (7).
.SH "RETURN VALUE"
For a successful call, the return value depends on the operation:
For
.BR F_GETLK " and " F_SETLK ,
the command was interrupted by a signal before the lock was checked or
-acquired. Most likely when locking a remote file (e.g. locking over
+acquired.
+Most likely when locking a remote file (e.g. locking over
NFS), but can sometimes happen locally.
.TP
.B EINVAL
For
.BR F_DUPFD ,
.I arg
-is negative or is greater than the maximum allowable value. For
+is negative or is greater than the maximum allowable value.
+For
.BR F_SETSIG ,
.I arg
is not an allowable signal number.
POSIX.1-2001 allows
.I l_len
-to be negative. (And if it is, the interval described by the lock
+to be negative.
+(And if it is, the interval described by the lock
covers bytes
.IR l_start + l_len
up to and including
when an unprivileged process uses
.B F_SETOWN
to specify the owner
-of a socket file descriptor
+of a socket file descriptor
as a process (group) other than the caller.
In this case,
.BR fcntl ()
Despite this error return, the file descriptor owner is set,
and signals will be sent to the owner.
.SH "CONFORMING TO"
-SVr4, 4.3BSD, POSIX.1-2001.
+SVr4, 4.3BSD, POSIX.1-2001.
Only the operations F_DUPFD,
-F_GETFD, F_SETFD, F_GETFL, F_SETFL, F_GETLK, F_SETLK, F_SETLKW,
+F_GETFD, F_SETFD, F_GETFL, F_SETFL, F_GETLK, F_SETLK, F_SETLKW,
F_GETOWN, and F_SETOWN are specified in POSIX.1-2001.
F_GETSIG, F_SETSIG, F_NOTIFY, F_GETLEASE, and F_SETLEASE
projects / thirdparty / man-pages.git / blobdiff