2004-11-03 13:51:07 +00:00
|
|
|
'\" t
|
|
|
|
.\" Hey Emacs! This file is -*- nroff -*- source.
|
|
|
|
.\"
|
|
|
|
.\" This manpage is Copyright (C) 1992 Drew Eckhardt;
|
|
|
|
.\" 1993 Michael Haardt, Ian Jackson;
|
|
|
|
.\" 1998 Jamie Lokier;
|
|
|
|
.\" 2002 Michael Kerrisk.
|
|
|
|
.\"
|
|
|
|
.\" Permission is granted to make and distribute verbatim copies of this
|
|
|
|
.\" manual provided the copyright notice and this permission notice are
|
|
|
|
.\" preserved on all copies.
|
|
|
|
.\"
|
|
|
|
.\" Permission is granted to copy and distribute modified versions of this
|
|
|
|
.\" 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
|
|
|
|
.\" the use of the information contained herein. The author(s) may not
|
|
|
|
.\" 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 1993-07-24 by Rik Faith <faith@cs.unc.edu>
|
|
|
|
.\" Modified 1995-09-26 by Andries Brouwer <aeb@cwi.nl>
|
|
|
|
.\" and again on 960413 and 980804 and 981223.
|
|
|
|
.\" Modified 1998-12-11 by Jamie Lokier <jamie@imbolc.ucc.ie>
|
|
|
|
.\" Applied correction by Christian Ehrhardt - aeb, 990712
|
2004-11-03 14:43:40 +00:00
|
|
|
.\" Modified 2002-04-23 by Michael Kerrisk <mtk-manpages@gmx.net>
|
2004-11-03 13:51:07 +00:00
|
|
|
.\" Added note on F_SETFL and O_DIRECT
|
|
|
|
.\" Complete rewrite + expansion of material on file locking
|
|
|
|
.\" Incorporated description of F_NOTIFY, drawing on
|
|
|
|
.\" Stephen Rothwell's notes in Documentation/dnotify.txt.
|
|
|
|
.\" Added description of F_SETLEASE and F_GETLEASE
|
|
|
|
.\" Corrected and polished, aeb, 020527.
|
2004-11-03 14:43:40 +00:00
|
|
|
.\" Modified 2004-03-03 by Michael Kerrisk <mtk-manpages@gmx.net>
|
2004-11-03 13:51:07 +00:00
|
|
|
.\" Modified description of file leases: fixed some errors of detail
|
|
|
|
.\" Replaced the term "lease contestant" by "lease breaker"
|
2004-11-03 14:43:40 +00:00
|
|
|
.\" Modified, 27 May 2004, Michael Kerrisk <mtk-manpages@gmx.net>
|
2004-11-03 13:51:07 +00:00
|
|
|
.\" Added notes on capability requirements
|
2004-12-08 16:41:10 +00:00
|
|
|
.\" Modified 2004-12-08, added O_NOATIME after note from Martin Pool
|
[Further notes on that F_GETOWN bug]
Hi Andries,
[Just for my own reference, I reinclude the pointer to Philippe
Troin's patch
http://marc.theaimsgroup.com/?l=linux-kernel&m=108380640603164&w=2
]
> > > Except of course for fcntl(fd, F_GETOWN) where the owner is a
> > > (negative) process group... If the owning process group has a "low
> > > enough" PGID, it collides with errors and glibc reports an error and
> > > sets errno to -PGID. One might argue that in this instance, that the
> > > BSD's overloading of the pid field with pgids is at fault, but the
> > > bug
> > > still remains :-)
> >
> > I believe that practically speaking this is a non-issue. The
> > lowest PID / PGID that can be allocated to a process other than
> > init or a kernel thread is 300. (RESERVED_PID in kernel/pid.c
> > in 2.6, details differ, but same limit in <= 2.4.)
>
> Hmm. RESERVED_PIDS is used as starting value after overflow,
> not as a starting value at the beginning. I think you are mistaken.
Hmm -- yes. And I was in any case assuming the notion
of a process that might do an F_SETOWN assigning
its own PGID to the socket -- but that might not be so.
And I was overlooking a comment in the fs/fcntl.c
sources that reiterates the point:
case F_GETOWN:
/*
* XXX If f_owner is a process group, the
* negative return value will get converted
* into an error. Oops. If we keep the
* current syscall conventions, the only way
* to fix this will be in libc.
*/
err = filp->f_owner.pid;
force_successful_syscall_return();
break;
And now I've actually created the error in userland code.
It seems that whenever the -PGID retrieved by F_GETOWN is
smaller than 4096, then it is interpreted as an error.
Now I see the relevant code in
sysdeps/unix/sysv/linux/i386/sysdep.h:
==
/* Linux uses a negative return value to indicate syscall errors,
unlike most Unices, which use the condition codes' carry flag.
Since version 2.1 the return value of a system call might be
negative even if the call succeeded. E.g., the `lseek' system call
might return a large offset. Therefore we must not anymore test
for < 0, but test for a real error by making sure the value in %eax
is a real error number. Linus said he will make sure the no syscall
returns a value in -1 .. -4095 as a valid result so we can savely
test with -4095. */
[...]
DO_CALL (syscall_name, args);
cmpl $-4095, %eax;
jae SYSCALL_ERROR_LABEL;
==
Ugh.
2004-12-10 16:28:25 +00:00
|
|
|
.\" 2004-12-10, mtk, noted F_GETOWN bug after suggestion from aeb.
|
2005-04-08 13:42:00 +00:00
|
|
|
.\" 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.
|
2004-11-03 13:51:07 +00:00
|
|
|
.\"
|
2004-12-08 16:41:10 +00:00
|
|
|
.TH FCNTL 2 2004-12-08 "Linux 2.6.9" "Linux Programmer's Manual"
|
2004-11-03 13:51:07 +00:00
|
|
|
.SH NAME
|
|
|
|
fcntl \- manipulate file descriptor
|
|
|
|
.SH SYNOPSIS
|
|
|
|
.nf
|
|
|
|
.B #include <unistd.h>
|
|
|
|
.B #include <fcntl.h>
|
|
|
|
.sp
|
|
|
|
.BI "int fcntl(int " fd ", int " cmd );
|
|
|
|
.BI "int fcntl(int " fd ", int " cmd ", long " arg );
|
|
|
|
.BI "int fcntl(int " fd ", int " cmd ", struct flock *" lock );
|
|
|
|
.fi
|
|
|
|
.SH DESCRIPTION
|
|
|
|
.B fcntl
|
|
|
|
performs one of various miscellaneous operations on
|
|
|
|
.IR fd .
|
|
|
|
The operation in question is determined by
|
|
|
|
.IR cmd .
|
|
|
|
.SS "Handling close-on-exec"
|
|
|
|
.TP
|
|
|
|
.B F_DUPFD
|
|
|
|
Find the lowest numbered available file descriptor
|
|
|
|
greater than or equal to
|
|
|
|
.I arg
|
|
|
|
and make it be a copy of
|
|
|
|
.IR fd .
|
|
|
|
This is different form
|
|
|
|
.BR dup2 (2)
|
|
|
|
which uses exactly the descriptor specified.
|
|
|
|
.sp
|
|
|
|
The old and new descriptors may be used interchangeably. They share locks,
|
|
|
|
file position pointers and flags; for example, if the file position is
|
|
|
|
modified by using
|
|
|
|
.B lseek
|
|
|
|
on one of the descriptors, the position is also changed for the other.
|
|
|
|
.sp
|
|
|
|
The two descriptors do not share the close-on-exec flag, however.
|
|
|
|
The close-on-exec flag of the copy is off, meaning that it will
|
|
|
|
not be closed on exec.
|
|
|
|
.sp
|
|
|
|
On success, the new descriptor is returned.
|
|
|
|
.TP
|
|
|
|
.B F_GETFD
|
|
|
|
Read the close-on-exec flag. If the
|
|
|
|
.B FD_CLOEXEC
|
|
|
|
bit is 0, the file will remain open across
|
|
|
|
.BR exec ,
|
|
|
|
otherwise it will be closed.
|
|
|
|
.TP
|
|
|
|
.B F_SETFD
|
|
|
|
Set the close-on-exec flag to the value specified by the
|
|
|
|
.B FD_CLOEXEC
|
|
|
|
bit of
|
|
|
|
.IR arg .
|
|
|
|
.SS "The file status flags"
|
|
|
|
A file descriptor has certain associated flags, initialized by
|
|
|
|
.BR open (2)
|
|
|
|
.\" or
|
|
|
|
.\" .BR creat (2),
|
|
|
|
and possibly modified by
|
|
|
|
.BR fcntl (2).
|
|
|
|
The flags are shared between copies (made with
|
|
|
|
.BR dup (2),
|
|
|
|
.BR fork (2),
|
|
|
|
etc.) of the same file descriptor.
|
|
|
|
.sp
|
|
|
|
The flags and their semantics are described in
|
|
|
|
.BR open (2).
|
|
|
|
.TP
|
|
|
|
.B F_GETFL
|
|
|
|
Read the file descriptor's flags.
|
|
|
|
.TP
|
|
|
|
.B F_SETFL
|
|
|
|
Set the file status flags part of the descriptor's flags to the value
|
|
|
|
specified by
|
|
|
|
.IR arg .
|
|
|
|
Remaining bits (access mode, file creation flags) in
|
|
|
|
.I arg
|
|
|
|
are ignored.
|
2004-12-08 16:41:10 +00:00
|
|
|
On Linux this command can only change the
|
|
|
|
.BR O_APPEND ,
|
|
|
|
.BR O_ASYNC ,
|
|
|
|
.BR O_DIRECT ,
|
|
|
|
.BR O_NOATIME ,
|
|
|
|
and
|
|
|
|
.BR O_NONBLOCK
|
|
|
|
flags.
|
|
|
|
.\" FIXME But according to SUSv3, O_SYNC should also be modifiable via
|
|
|
|
.\" fcntl(2) -- MTK, Dec 04
|
2004-11-03 13:51:07 +00:00
|
|
|
.P
|
|
|
|
.SS "Advisory locking"
|
|
|
|
.BR F_GETLK ", " F_SETLK " and " F_SETLKW
|
|
|
|
are used to acquire, release, and test for the existence of record
|
|
|
|
locks (also known as file-segment or file-region locks).
|
|
|
|
The third argument
|
|
|
|
.I lock
|
|
|
|
is a pointer to a structure that has at least the following fields
|
|
|
|
(in unspecified order).
|
|
|
|
.in +2n
|
|
|
|
.nf
|
|
|
|
.sp
|
|
|
|
struct flock {
|
|
|
|
...
|
|
|
|
short l_type; /* Type of lock: F_RDLCK,
|
|
|
|
F_WRLCK, F_UNLCK */
|
|
|
|
short l_whence; /* How to interpret l_start:
|
|
|
|
SEEK_SET, SEEK_CUR, SEEK_END */
|
|
|
|
off_t l_start; /* Starting offset for lock */
|
|
|
|
off_t l_len; /* Number of bytes to lock */
|
|
|
|
pid_t l_pid; /* PID of process blocking our lock
|
|
|
|
(F_GETLK only) */
|
|
|
|
...
|
|
|
|
};
|
|
|
|
.fi
|
|
|
|
.in -2n
|
|
|
|
.P
|
|
|
|
The
|
|
|
|
.IR l_whence ", " l_start ", and " l_len
|
|
|
|
fields of this structure specify the range of bytes we wish to lock.
|
|
|
|
.I l_start
|
|
|
|
is the starting offset for the lock, and is interpreted
|
|
|
|
relative to either:
|
|
|
|
the start of the file (if
|
|
|
|
.I l_whence
|
|
|
|
is
|
|
|
|
.BR SEEK_SET );
|
|
|
|
the current file offset (if
|
|
|
|
.I l_whence
|
|
|
|
is
|
|
|
|
.BR SEEK_CUR );
|
|
|
|
or the end of the file (if
|
|
|
|
.I l_whence
|
|
|
|
is
|
|
|
|
.BR SEEK_END ).
|
|
|
|
In the final two cases,
|
|
|
|
.I l_start
|
|
|
|
can be a negative number provided the
|
|
|
|
offset does not lie before the start of the file.
|
|
|
|
.I l_len
|
|
|
|
is a non-negative integer (but see the NOTES below) specifying
|
|
|
|
the number of bytes to be locked.
|
|
|
|
Bytes past the end of the file may be locked,
|
|
|
|
but not bytes before the start of the file.
|
|
|
|
Specifying 0 for
|
|
|
|
.I l_len
|
|
|
|
has the special meaning: lock all bytes starting at the
|
|
|
|
location specified by
|
|
|
|
.IR l_whence " and " l_start
|
|
|
|
through to the end of file, no matter how large the file grows.
|
|
|
|
.P
|
|
|
|
The
|
|
|
|
.I l_type
|
|
|
|
field can be used to place a read
|
|
|
|
.RB ( F_RDLCK )
|
|
|
|
or a write
|
2004-12-06 13:39:28 +00:00
|
|
|
.RB ( F_WRLCK )
|
2004-11-03 13:51:07 +00:00
|
|
|
lock on a file.
|
|
|
|
Any number of processes may hold a read lock (shared lock)
|
|
|
|
on a file region, but only one process may hold a write lock
|
|
|
|
(exclusive lock). An exclusive lock excludes all other locks,
|
|
|
|
both shared and exclusive.
|
|
|
|
A single process can hold only one type of lock on a file region;
|
|
|
|
if a new lock is applied to an already-locked region,
|
|
|
|
then the existing lock is converted to the the new lock type.
|
|
|
|
(Such conversions may involve splitting, shrinking, or coalescing with
|
|
|
|
an existing lock if the byte range specified by the new lock does not
|
|
|
|
precisely coincide with the range of the existing lock.)
|
|
|
|
.TP
|
|
|
|
.B F_SETLK
|
|
|
|
Acquire a lock (when
|
|
|
|
.I l_type
|
|
|
|
is
|
|
|
|
.B F_RDLCK
|
|
|
|
or
|
|
|
|
.BR F_WRLCK )
|
|
|
|
or release a lock (when
|
|
|
|
.I l_type
|
|
|
|
is
|
|
|
|
.BR F_UNLCK )
|
|
|
|
on the bytes specified by the
|
|
|
|
.IR l_whence ", " l_start ", and " l_len
|
|
|
|
fields of
|
|
|
|
.IR lock .
|
|
|
|
If a conflicting lock is held by another process,
|
|
|
|
this call returns \-1 and sets
|
|
|
|
.I errno
|
|
|
|
to
|
|
|
|
.B EACCES
|
|
|
|
or
|
|
|
|
.BR EAGAIN .
|
|
|
|
.TP
|
|
|
|
.B F_SETLKW
|
|
|
|
As for
|
|
|
|
.BR F_SETLK ,
|
|
|
|
but if a conflicting lock is held on the file, then wait for that
|
|
|
|
lock to be released.
|
|
|
|
If a signal is caught while waiting, then the call is interrupted
|
|
|
|
and (after the signal handler has returned)
|
|
|
|
returns immediately (with return value \-1 and
|
|
|
|
.I errno
|
|
|
|
set to
|
|
|
|
.BR EINTR ).
|
|
|
|
.TP
|
|
|
|
.B F_GETLK
|
|
|
|
On input to this call,
|
|
|
|
.I lock
|
|
|
|
describes a lock we would like to place on the file.
|
|
|
|
If the lock could be placed,
|
|
|
|
.BR fcntl ()
|
|
|
|
does not actually place it, but returns
|
|
|
|
.B F_UNLCK
|
|
|
|
in the
|
|
|
|
.I l_type
|
|
|
|
field of
|
|
|
|
.I lock
|
|
|
|
and leaves the other fields of the structure unchanged.
|
|
|
|
If one or more incompatible locks would prevent
|
|
|
|
this lock being placed, then
|
|
|
|
.BR fcntl ()
|
|
|
|
returns details about one of these locks in the
|
|
|
|
.IR l_type ", " l_whence ", " l_start ", and " l_len
|
|
|
|
fields of
|
|
|
|
.I lock
|
|
|
|
and sets
|
|
|
|
.I l_pid
|
|
|
|
to be the PID of the process holding that lock.
|
|
|
|
.P
|
|
|
|
In order to place a read lock,
|
|
|
|
.I fd
|
|
|
|
must be open for reading.
|
|
|
|
In order to place a write lock,
|
|
|
|
.I fd
|
|
|
|
must be open for writing.
|
|
|
|
To place both types of lock, open a file read-write.
|
|
|
|
.P
|
|
|
|
As well as being removed by an explicit
|
|
|
|
.BR F_UNLCK ,
|
|
|
|
record locks are automatically released when the process
|
|
|
|
terminates or if it closes
|
|
|
|
.I any
|
|
|
|
file descriptor referring to a file on which locks are held.
|
|
|
|
.\" (Additional file descriptors referring to the same file
|
|
|
|
.\" may have been obtained by calls to
|
|
|
|
.\" .BR open "(2), " dup "(2), " dup2 "(2), or " fcntl (2).)
|
|
|
|
This is bad: it means that a process can lose the locks on
|
|
|
|
a file like
|
|
|
|
.I /etc/passwd
|
|
|
|
or
|
|
|
|
.I /etc/mtab
|
|
|
|
when for some reason a library function decides to open, read
|
|
|
|
and close it.
|
|
|
|
.P
|
|
|
|
Record locks are not inherited by a child created via
|
|
|
|
.BR fork (2),
|
|
|
|
but are preserved across an
|
|
|
|
.BR execve (2).
|
|
|
|
.P
|
|
|
|
Because of the buffering performed by the
|
|
|
|
.BR stdio (3)
|
|
|
|
library, the use of record locking with routines in that package
|
|
|
|
should be avoided; use
|
|
|
|
.BR read "(2) and " write (2)
|
|
|
|
instead.
|
|
|
|
.P
|
|
|
|
.SS "Mandatory locking"
|
|
|
|
(Non-POSIX.)
|
|
|
|
The above record locks may be either advisory or mandatory,
|
|
|
|
and are advisory by default.
|
|
|
|
To make use of mandatory locks, mandatory locking must be enabled
|
|
|
|
(using the "-o mand" option to
|
|
|
|
.BR mount (8))
|
|
|
|
for the file system containing the
|
|
|
|
file to be locked and enabled on the file itself (by disabling
|
|
|
|
group execute permission on the file and enabling the set-GID
|
|
|
|
permission bit).
|
|
|
|
|
|
|
|
Advisory locks are not enforced and are useful only between
|
|
|
|
cooperating processes. Mandatory locks are enforced for all
|
|
|
|
processes.
|
|
|
|
.P
|
|
|
|
.SS "Managing signals"
|
|
|
|
.BR F_GETOWN ", " F_SETOWN ", " F_GETSIG " and " F_SETSIG
|
|
|
|
are used to manage I/O availability signals:
|
|
|
|
.TP
|
|
|
|
.B F_GETOWN
|
|
|
|
Get the process ID or process group currently receiving SIGIO
|
|
|
|
and SIGURG signals for events on file descriptor
|
|
|
|
.IR fd .
|
2005-04-08 13:42:00 +00:00
|
|
|
Process IDs are returned as positive values;
|
|
|
|
process group IDs are returned as negative values (but see BUGS below).
|
2004-11-03 13:51:07 +00:00
|
|
|
.TP
|
|
|
|
.B F_SETOWN
|
2005-04-08 13:42:00 +00:00
|
|
|
Set the process ID or process group ID that will receive SIGIO
|
2004-11-03 13:51:07 +00:00
|
|
|
and SIGURG signals for events on file descriptor
|
|
|
|
.IR fd .
|
2005-04-08 13:42:00 +00:00
|
|
|
A process ID is specified as a positive value;
|
|
|
|
a process group ID is specified as a negative value.
|
2004-11-03 13:51:07 +00:00
|
|
|
|
|
|
|
.\" From glibc.info:
|
|
|
|
If you set the
|
|
|
|
.B O_ASYNC
|
|
|
|
status flag on a file descriptor (either by providing this flag with the
|
2005-04-08 13:42:00 +00:00
|
|
|
.BR open (2)
|
|
|
|
.\" FIXME setting O_ASYNC via open() does not seem to be effective -- MTK
|
2004-11-03 13:51:07 +00:00
|
|
|
call, or by using the
|
|
|
|
.B F_SETFL
|
|
|
|
command of
|
|
|
|
.BR fcntl ),
|
|
|
|
a SIGIO signal is sent whenever input or output becomes possible
|
|
|
|
on that file descriptor.
|
2005-04-08 13:42:00 +00:00
|
|
|
.B F_SETSIG
|
|
|
|
can be used to obtain delivery of a signal other than SIGIO.
|
2004-11-03 13:51:07 +00:00
|
|
|
.sp
|
2005-04-08 13:42:00 +00:00
|
|
|
If the file descriptor
|
|
|
|
.I fd
|
|
|
|
refers to a socket,
|
2004-11-03 13:51:07 +00:00
|
|
|
.B F_SETOWN
|
2005-04-08 13:42:00 +00:00
|
|
|
also selects
|
2004-11-03 13:51:07 +00:00
|
|
|
the recipient of SIGURG signals that are delivered when out-of-band
|
|
|
|
data arrives on that socket. (SIGURG is sent in any situation where
|
|
|
|
.BR select (2)
|
|
|
|
would report the socket as having an "exceptional condition".)
|
2005-04-08 13:42:00 +00:00
|
|
|
.\" The following appears to be rubbish. It doesn't seem to
|
|
|
|
.\" 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
|
|
|
|
.\" signals are sent to the foreground process group of the terminal.
|
|
|
|
|
|
|
|
If a non-zero value is given to
|
|
|
|
.B F_SETSIG
|
|
|
|
in a multi-threaded process, then a positive value value given to
|
|
|
|
.B F_SETOWN
|
|
|
|
has a different meaning:
|
|
|
|
.\" 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.
|
|
|
|
Consequently, it may be necessary to pass
|
|
|
|
.B F_SETOWN
|
|
|
|
the result of
|
|
|
|
.BR gettid ()
|
|
|
|
instead of
|
|
|
|
.BR getpid ()
|
|
|
|
to get sensible results when
|
|
|
|
.B F_SETSIG
|
|
|
|
is used.
|
|
|
|
(In current Linux threading implementations,
|
|
|
|
a main thread's thread ID is the same as its process ID.
|
|
|
|
This means that a single-threaded program can equally use
|
|
|
|
.BR gettid ()
|
|
|
|
or
|
|
|
|
.BR getpid ()
|
|
|
|
in this scenario.)
|
|
|
|
Note, however, that the statements in this paragraph do not apply
|
|
|
|
to the SIGURG signal generated for out-of-band data on a socket:
|
|
|
|
this signal is always sent to either a process or a process group,
|
|
|
|
depending on the value given to
|
|
|
|
.BR F_SETOWN .
|
|
|
|
.\" send_sigurg()/send_sigurg_to_task() bypasses
|
|
|
|
.\" kill_fasync()/send_sigio()/send_sigio_to_task()
|
|
|
|
.\" to directly call send_group_sig_info()
|
|
|
|
.\" -- MTK, Apr 2005 (kernel 2.6.11)
|
2004-11-03 13:51:07 +00:00
|
|
|
.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
|
|
|
|
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
|
|
|
|
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
|
2005-04-08 13:42:00 +00:00
|
|
|
Additionally, passing a non-zero value to
|
|
|
|
.B F_SETSIG
|
|
|
|
changes the signal recipient from a whole process to a specific thread
|
|
|
|
within a process.
|
|
|
|
See the desciption of
|
|
|
|
.B F_SETOWN
|
|
|
|
for more details.
|
|
|
|
.sp
|
|
|
|
By using
|
|
|
|
.B F_SETSIG
|
|
|
|
with a non-zero value, and setting SA_SIGINFO for the
|
2004-11-03 13:51:07 +00:00
|
|
|
signal handler (see
|
|
|
|
.BR sigaction (2)),
|
|
|
|
extra information about I/O events is passed to
|
|
|
|
the handler in a
|
|
|
|
.I siginfo_t
|
|
|
|
structure.
|
|
|
|
If the
|
|
|
|
.I si_code
|
|
|
|
field indicates the source is SI_SIGIO, the
|
|
|
|
.I si_fd
|
|
|
|
field gives the file descriptor associated with the event. Otherwise,
|
|
|
|
there is no indication which file descriptors are pending, and you
|
|
|
|
should use the usual mechanisms
|
|
|
|
.RB ( select (2),
|
|
|
|
.BR poll (2),
|
|
|
|
.BR read (2)
|
|
|
|
with
|
|
|
|
.B O_NONBLOCK
|
|
|
|
set etc.) to determine which file descriptors are available for I/O.
|
|
|
|
.sp
|
|
|
|
By selecting a POSIX.1b real time signal (value >= SIGRTMIN), multiple
|
|
|
|
I/O events may be queued using the same signal numbers. (Queuing is
|
|
|
|
dependent on available memory). Extra information is available
|
|
|
|
if SA_SIGINFO is set for the signal handler, as above.
|
|
|
|
.PP
|
|
|
|
Using these mechanisms, a program can implement fully asynchronous I/O
|
|
|
|
without using
|
|
|
|
.BR select (2)
|
|
|
|
or
|
|
|
|
.BR poll (2)
|
|
|
|
most of the time.
|
|
|
|
.PP
|
|
|
|
The use of
|
|
|
|
.BR O_ASYNC ,
|
|
|
|
.BR F_GETOWN ,
|
|
|
|
.B F_SETOWN
|
|
|
|
is specific to BSD and Linux.
|
|
|
|
.B F_GETSIG
|
|
|
|
and
|
|
|
|
.B F_SETSIG
|
|
|
|
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).
|
|
|
|
.P
|
|
|
|
.SS Leases
|
|
|
|
.B F_SETLEASE
|
|
|
|
and
|
|
|
|
.B F_GETLEASE
|
|
|
|
(Linux 2.4 onwards) are used (respectively) to establish and
|
|
|
|
retrieve the current setting of the calling process's lease on
|
|
|
|
the file referred to by
|
|
|
|
.IR fd .
|
|
|
|
A file lease provides a mechanism whereby the process holding
|
|
|
|
the lease (the "lease holder") is notified (via delivery of a signal)
|
|
|
|
when another process (the "lease breaker") tries to
|
|
|
|
.BR open (2)
|
|
|
|
or
|
|
|
|
.BR truncate (2)
|
|
|
|
that file.
|
|
|
|
.TP
|
|
|
|
.B F_SETLEASE
|
|
|
|
Set or remove a file lease according to which of the following
|
|
|
|
values is specified in the integer
|
|
|
|
.IR arg :
|
|
|
|
|
|
|
|
.RS
|
|
|
|
.TP
|
|
|
|
.B F_RDLCK
|
|
|
|
Take out a read lease.
|
|
|
|
This will cause us to be notified when
|
|
|
|
another process opens the file for writing or truncates it.
|
|
|
|
.TP
|
|
|
|
.B F_WRLCK
|
|
|
|
Take out a write lease.
|
|
|
|
This will cause us to be notified when
|
|
|
|
another process opens the file (for reading or writing) or truncates it.
|
|
|
|
A write lease may be placed on a file only if no other process
|
|
|
|
currently has the file open.
|
|
|
|
.TP
|
|
|
|
.B F_UNLCK
|
|
|
|
Remove our lease from the file.
|
|
|
|
.RE
|
|
|
|
.P
|
|
|
|
A process may hold only one type of lease on a file.
|
|
|
|
.P
|
|
|
|
Leases may only be taken out on regular files.
|
|
|
|
An unprivileged process may only take out a lease on a file whose
|
|
|
|
UID matches the file system UID of the process.
|
|
|
|
A process with the
|
|
|
|
.B CAP_LEASE
|
|
|
|
capability may take out leases on arbitrary files.
|
|
|
|
.TP
|
|
|
|
.B F_GETLEASE
|
|
|
|
Indicates what type of lease we hold on the file
|
|
|
|
referred to by
|
|
|
|
.I fd
|
|
|
|
by returning either
|
|
|
|
.BR F_RDLCK ", " F_WRLCK ", or " F_UNLCK,
|
|
|
|
indicating, respectively, that the calling process holds a
|
|
|
|
read, a write, or no lease on the file.
|
|
|
|
(The third argument to
|
|
|
|
.BR fcntl ()
|
|
|
|
is omitted.)
|
|
|
|
.PP
|
|
|
|
When a process (the "lease breaker") performs an
|
|
|
|
.BR open ()
|
|
|
|
or
|
|
|
|
.BR truncate ()
|
|
|
|
that conflicts with a lease established via
|
|
|
|
.BR F_SETLEASE ,
|
|
|
|
the system call is blocked by the kernel, unless the
|
|
|
|
.B O_NONBLOCK
|
|
|
|
flag was specified to
|
|
|
|
.BR open (),
|
|
|
|
in which case the system call will return with the error
|
|
|
|
.BR EWOULDBLOCK .
|
|
|
|
The kernel notifies the lease holder by sending it a signal
|
|
|
|
(SIGIO by default).
|
|
|
|
The lease holder should respond to receipt of this signal by doing
|
|
|
|
whatever cleanup is required in preparation for the file to be
|
|
|
|
accessed by another process (e.g., flushing cached buffers) and
|
|
|
|
then either remove or downgrade its lease.
|
|
|
|
A lease is removed by performing an
|
|
|
|
.B F_SETLEASE
|
|
|
|
command specifying
|
|
|
|
.I arg
|
|
|
|
as
|
|
|
|
.BR F_UNLCK .
|
|
|
|
If we currently hold a write lease on the file,
|
|
|
|
and the lease breaker is opening the file for reading,
|
|
|
|
then it is sufficient to downgrade the lease to a read lease.
|
|
|
|
This is done by performing an
|
|
|
|
.B F_SETLEASE
|
|
|
|
command specifying
|
|
|
|
.I arg
|
|
|
|
as
|
|
|
|
.BR F_RDLCK .
|
|
|
|
|
|
|
|
If the lease holder fails to downgrade or remove the lease within
|
|
|
|
the number of seconds specified in
|
|
|
|
.I /proc/sys/fs/lease-break-time
|
|
|
|
then the kernel forcibly removes or downgrades the lease holder's lease.
|
|
|
|
|
|
|
|
Once the lease has been voluntarily or forcibly removed or downgraded,
|
|
|
|
and assuming the lease breaker has not unblocked its system call,
|
|
|
|
the kernel permits the lease breaker's system call to proceed.
|
|
|
|
|
|
|
|
The default signal used to notify the lease holder is SIGIO,
|
|
|
|
but this can be changed using the
|
|
|
|
.B F_SETSIG
|
|
|
|
command to
|
|
|
|
.B fcntl ().
|
|
|
|
If a
|
|
|
|
.B F_SETSIG
|
|
|
|
command is performed (even one specifying SIGIO), and the signal
|
|
|
|
handler is established using SA_SIGINFO, then the handler will
|
|
|
|
receive a
|
|
|
|
.I siginfo_t
|
|
|
|
sructure as its second argument, and the
|
|
|
|
.I si_fd
|
|
|
|
field of this argument will hold the descriptor of the leased file
|
|
|
|
that has been accessed by another process.
|
|
|
|
(This is useful if the caller holds leases against multiple files).
|
|
|
|
.SS "File and directory change notification"
|
|
|
|
.TP
|
|
|
|
.B F_NOTIFY
|
|
|
|
(Linux 2.4 onwards)
|
|
|
|
Provide notification when the directory referred to by
|
|
|
|
.I fd
|
|
|
|
or any of the files that it contains is changed.
|
|
|
|
The events to be notified are specified in
|
|
|
|
.IR arg ,
|
|
|
|
which is a bit mask specified by ORing together zero or more of
|
|
|
|
the following bits:
|
|
|
|
|
|
|
|
.TS
|
|
|
|
l l
|
|
|
|
----
|
|
|
|
lB l.
|
|
|
|
Bit Description (event in directory)
|
|
|
|
DN_ACCESS A file was accessed (read, pread, readv)
|
|
|
|
DN_MODIFY A file was modified (write, pwrite,
|
|
|
|
writev, truncate, ftruncate)
|
|
|
|
DN_CREATE A file was created (open, creat, mknod,
|
|
|
|
mkdir, link, symlink, rename)
|
|
|
|
DN_DELETE A file was unlinked (unlink, rename to
|
|
|
|
another directory, rmdir)
|
|
|
|
DN_RENAME A file was renamed within this
|
|
|
|
directory (rename)
|
|
|
|
DN_ATTRIB The attributes of a file were changed
|
|
|
|
(chown, chmod, utime[s])
|
|
|
|
.TE
|
|
|
|
.sp
|
|
|
|
(In order to obtain these definitions, the _GNU_SOURCE macro must be
|
|
|
|
defined before including <fcntl.h>.)
|
|
|
|
.sp
|
|
|
|
Directory notifications are normally "one-shot", and the application
|
|
|
|
must re-register to receive further notifications.
|
|
|
|
Alternatively, if
|
|
|
|
.B DN_MULTISHOT
|
|
|
|
is included in
|
|
|
|
.IR arg ,
|
|
|
|
then notification will remain in effect until explicitly removed.
|
|
|
|
|
|
|
|
.\" The following does seem a poor API-design choice...
|
|
|
|
A series of
|
|
|
|
.B F_NOTIFY
|
|
|
|
requests is cumulative, with the events in
|
|
|
|
.I arg
|
|
|
|
being added to the set already monitored.
|
|
|
|
To disable notification of all events, make an
|
|
|
|
.B F_NOTIFY
|
|
|
|
call specifying
|
|
|
|
.I arg
|
|
|
|
as 0.
|
|
|
|
.sp
|
|
|
|
Notification occurs via delivery of a signal.
|
|
|
|
The default signal is SIGIO, but this can be changed using the
|
|
|
|
.B F_SETSIG
|
|
|
|
command to
|
|
|
|
.BR fcntl ().
|
|
|
|
In the latter case, the signal handler receives a
|
|
|
|
.I siginfo_t
|
|
|
|
structure as its second argument (if the handler was
|
|
|
|
established using SA_SIGINFO) and the
|
|
|
|
.I si_fd
|
|
|
|
field of this structure contains the file descriptor which
|
|
|
|
generated the notification (useful when establishing notification
|
|
|
|
on multiple directories).
|
|
|
|
.sp
|
|
|
|
Especially when using
|
|
|
|
.BR DN_MULTISHOT ,
|
|
|
|
a POSIX.1b real time signal should be used for notication,
|
|
|
|
so that multiple notifications can be queued.
|
|
|
|
.SH "RETURN VALUE"
|
|
|
|
For a successful call, the return value depends on the operation:
|
|
|
|
.TP 0.9i
|
|
|
|
.B F_DUPFD
|
|
|
|
The new descriptor.
|
|
|
|
.TP
|
|
|
|
.B F_GETFD
|
|
|
|
Value of flag.
|
|
|
|
.TP
|
|
|
|
.B F_GETFL
|
|
|
|
Value of flags.
|
|
|
|
.TP
|
|
|
|
.B F_GETOWN
|
|
|
|
Value of descriptor owner.
|
|
|
|
.TP
|
|
|
|
.B F_GETSIG
|
|
|
|
Value of signal sent when read or write becomes possible, or zero
|
|
|
|
for traditional SIGIO behaviour.
|
|
|
|
.TP
|
|
|
|
All other commands
|
|
|
|
Zero.
|
|
|
|
.PP
|
|
|
|
On error, \-1 is returned, and
|
|
|
|
.I errno
|
|
|
|
is set appropriately.
|
|
|
|
.SH ERRORS
|
|
|
|
.TP
|
|
|
|
.BR EACCES " or " EAGAIN
|
|
|
|
Operation is prohibited by locks held by other processes.
|
|
|
|
Or, operation is prohibited because the file has been memory-mapped by
|
|
|
|
another process.
|
|
|
|
.TP
|
|
|
|
.B EBADF
|
|
|
|
.I fd
|
|
|
|
is not an open file descriptor, or the command was
|
|
|
|
.B F_SETLK
|
|
|
|
or
|
|
|
|
.B F_SETLKW
|
|
|
|
and the file descriptor open mode doesn't match with the
|
|
|
|
type of lock requested.
|
|
|
|
.TP
|
|
|
|
.B EDEADLK
|
|
|
|
It was detected that the specified
|
|
|
|
.B F_SETLKW
|
|
|
|
command would cause a deadlock.
|
|
|
|
.TP
|
|
|
|
.B EFAULT
|
|
|
|
.I lock
|
|
|
|
is outside your accessible address space.
|
|
|
|
.TP
|
|
|
|
.B EINTR
|
|
|
|
For
|
|
|
|
.BR F_SETLKW ,
|
|
|
|
the command was interrupted by a signal.
|
|
|
|
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
|
|
|
|
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
|
|
|
|
.BR F_SETSIG ,
|
|
|
|
.I arg
|
|
|
|
is not an allowable signal number.
|
|
|
|
.TP
|
|
|
|
.B EMFILE
|
|
|
|
For
|
|
|
|
.BR F_DUPFD ,
|
|
|
|
the process already has the maximum number of file descriptors open.
|
|
|
|
.TP
|
|
|
|
.B ENOLCK
|
|
|
|
Too many segment locks open, lock table is full, or a remote locking
|
|
|
|
protocol failed (e.g. locking over NFS).
|
|
|
|
.TP
|
|
|
|
.B EPERM
|
|
|
|
Attempted to clear the
|
|
|
|
.B O_APPEND
|
|
|
|
flag on a file that has the append-only attribute set.
|
|
|
|
.SH NOTES
|
|
|
|
The errors returned by
|
|
|
|
.B dup2
|
|
|
|
are different from those returned by
|
|
|
|
.BR F_DUPFD .
|
|
|
|
|
|
|
|
Since kernel 2.0, there is no interaction between the types of lock
|
|
|
|
placed by
|
|
|
|
.BR flock (2)
|
|
|
|
and
|
|
|
|
.BR fcntl (2).
|
|
|
|
|
|
|
|
POSIX 1003.1-2001 allows
|
|
|
|
.I l_len
|
|
|
|
to be negative. (And if it is, the interval described by the lock
|
|
|
|
covers bytes
|
|
|
|
.IR l_start + l_len
|
|
|
|
up to and including
|
|
|
|
.IR l_start -1.)
|
|
|
|
This is supported by Linux since Linux 2.4.21 and 2.5.49.
|
|
|
|
|
|
|
|
Several systems have more fields in
|
|
|
|
.I "struct flock"
|
|
|
|
such as e.g.
|
|
|
|
.IR l_sysid .
|
|
|
|
Clearly,
|
|
|
|
.I l_pid
|
|
|
|
alone is not going to be very useful if the process holding the lock
|
|
|
|
may live on a different machine.
|
2004-12-10 16:26:28 +00:00
|
|
|
.SH BUGS
|
Date: Mon, 13 Dec 2004 12:09:43 +0100 (MET)
From: "Michael Kerrisk" <mtk-manpages@gmx.net>
To: Andries Brouwer <Andries.Brouwer@cwi.nl>
Subject: Re: errno
Hi Andries,
> On Fri, Dec 10, 2004 at 05:07:36PM +0100, Michael Kerrisk wrote:
>
> > I added this text to fcntl.2:
> >
> > BUGS
> > A limitation of the Linux system call conventions means that
> > if a (negative) process group ID to be returned by F_GETOWN
> > falls in the range -1 to -4095, then the return value is
> > wrongly interpreted by glibc as an error in the system call;
> > that is, the return value of fcntl() will be -1, and errno
> > will contain the (positive) process group ID.
>
> Yes.
>
> (Maybe glibc always did this, early libc considered any negative
> return value an error. On the other hand, not all the world is an i386 -
> IBM has just decided that we don't need any i386's anymore
> and sold their stuff to the Chinese - we must use PPC, as Linus
> does already - and on other architectures we do not have this
> ugliness, I think.)
>
> You might consider adding "i386" somewhere:
> A limitation of the Linux i386 system call conventions ...
Some testing on ia64 (RedHat EL 3.0, 2.4.21) and
alpha (2.4.18, Debian 3.0) showed that any negative PGID value
causes F_GETOWN to fail.
My limited reading of the ia64 source:
sysdeps/unix/sysv/linux/ia64/sysdep.h
shows that there is a comment about the -4095 value there,
but that doesn't seem to reflect the reality of the code.
Reading the source, the -4095 limit seems to hold on some
other architectures, e.g.:
sysdeps/unix/sysv/linux/m68k/sysdep.h
sysdeps/unix/sysv/linux/hppa/sysdep.h
sysdeps/unix/sysv/linux/s390/s390-32/sysdep.h
sysdeps/unix/sysv/linux/s390/s390-64/sysdep.h
sysdeps/unix/sysv/linux/x86_64/sysdep.h
Unfortunately, I have no non-x86 systems other than the above
alpha and ia64 (HP-testdrive) on which I can test.
I modified the text a little:
BUGS
A limitation of the Linux system call conventions on some
architectures (notably x86) means that if a (negative) pro‐
cess group ID to be returned by F_GETOWN falls in the range
-1 to -4095, then the return value is wrongly interpreted
by glibc as an error in the system call; that is, the
return value of fcntl() will be -1, and errno will contain
the (positive) process group ID.
I've left a FIXME in the man page source noting that details have
yet to be sorted out for ia64, alpha, etc.
2004-12-13 11:32:37 +00:00
|
|
|
A limitation of the Linux system call conventions on some
|
|
|
|
architectures (notably x86) means that if a (negative)
|
|
|
|
process group ID to be returned by
|
2004-12-10 16:26:28 +00:00
|
|
|
.B F_GETOWN
|
|
|
|
falls in the range -1 to -4095, then the return value is wrongly
|
|
|
|
interpreted by glibc as an error in the system call;
|
Date: Mon, 13 Dec 2004 12:09:43 +0100 (MET)
From: "Michael Kerrisk" <mtk-manpages@gmx.net>
To: Andries Brouwer <Andries.Brouwer@cwi.nl>
Subject: Re: errno
Hi Andries,
> On Fri, Dec 10, 2004 at 05:07:36PM +0100, Michael Kerrisk wrote:
>
> > I added this text to fcntl.2:
> >
> > BUGS
> > A limitation of the Linux system call conventions means that
> > if a (negative) process group ID to be returned by F_GETOWN
> > falls in the range -1 to -4095, then the return value is
> > wrongly interpreted by glibc as an error in the system call;
> > that is, the return value of fcntl() will be -1, and errno
> > will contain the (positive) process group ID.
>
> Yes.
>
> (Maybe glibc always did this, early libc considered any negative
> return value an error. On the other hand, not all the world is an i386 -
> IBM has just decided that we don't need any i386's anymore
> and sold their stuff to the Chinese - we must use PPC, as Linus
> does already - and on other architectures we do not have this
> ugliness, I think.)
>
> You might consider adding "i386" somewhere:
> A limitation of the Linux i386 system call conventions ...
Some testing on ia64 (RedHat EL 3.0, 2.4.21) and
alpha (2.4.18, Debian 3.0) showed that any negative PGID value
causes F_GETOWN to fail.
My limited reading of the ia64 source:
sysdeps/unix/sysv/linux/ia64/sysdep.h
shows that there is a comment about the -4095 value there,
but that doesn't seem to reflect the reality of the code.
Reading the source, the -4095 limit seems to hold on some
other architectures, e.g.:
sysdeps/unix/sysv/linux/m68k/sysdep.h
sysdeps/unix/sysv/linux/hppa/sysdep.h
sysdeps/unix/sysv/linux/s390/s390-32/sysdep.h
sysdeps/unix/sysv/linux/s390/s390-64/sysdep.h
sysdeps/unix/sysv/linux/x86_64/sysdep.h
Unfortunately, I have no non-x86 systems other than the above
alpha and ia64 (HP-testdrive) on which I can test.
I modified the text a little:
BUGS
A limitation of the Linux system call conventions on some
architectures (notably x86) means that if a (negative) pro‐
cess group ID to be returned by F_GETOWN falls in the range
-1 to -4095, then the return value is wrongly interpreted
by glibc as an error in the system call; that is, the
return value of fcntl() will be -1, and errno will contain
the (positive) process group ID.
I've left a FIXME in the man page source noting that details have
yet to be sorted out for ia64, alpha, etc.
2004-12-13 11:32:37 +00:00
|
|
|
.\" glibc source: sysdeps/unix/sysv/linux/i386/sysdep.h
|
2004-12-10 16:26:28 +00:00
|
|
|
that is, the return value of
|
|
|
|
.BR fcntl ()
|
|
|
|
will be \-1, and
|
|
|
|
.I errno
|
|
|
|
will contain the (positive) process group ID.
|
Date: Mon, 13 Dec 2004 12:09:43 +0100 (MET)
From: "Michael Kerrisk" <mtk-manpages@gmx.net>
To: Andries Brouwer <Andries.Brouwer@cwi.nl>
Subject: Re: errno
Hi Andries,
> On Fri, Dec 10, 2004 at 05:07:36PM +0100, Michael Kerrisk wrote:
>
> > I added this text to fcntl.2:
> >
> > BUGS
> > A limitation of the Linux system call conventions means that
> > if a (negative) process group ID to be returned by F_GETOWN
> > falls in the range -1 to -4095, then the return value is
> > wrongly interpreted by glibc as an error in the system call;
> > that is, the return value of fcntl() will be -1, and errno
> > will contain the (positive) process group ID.
>
> Yes.
>
> (Maybe glibc always did this, early libc considered any negative
> return value an error. On the other hand, not all the world is an i386 -
> IBM has just decided that we don't need any i386's anymore
> and sold their stuff to the Chinese - we must use PPC, as Linus
> does already - and on other architectures we do not have this
> ugliness, I think.)
>
> You might consider adding "i386" somewhere:
> A limitation of the Linux i386 system call conventions ...
Some testing on ia64 (RedHat EL 3.0, 2.4.21) and
alpha (2.4.18, Debian 3.0) showed that any negative PGID value
causes F_GETOWN to fail.
My limited reading of the ia64 source:
sysdeps/unix/sysv/linux/ia64/sysdep.h
shows that there is a comment about the -4095 value there,
but that doesn't seem to reflect the reality of the code.
Reading the source, the -4095 limit seems to hold on some
other architectures, e.g.:
sysdeps/unix/sysv/linux/m68k/sysdep.h
sysdeps/unix/sysv/linux/hppa/sysdep.h
sysdeps/unix/sysv/linux/s390/s390-32/sysdep.h
sysdeps/unix/sysv/linux/s390/s390-64/sysdep.h
sysdeps/unix/sysv/linux/x86_64/sysdep.h
Unfortunately, I have no non-x86 systems other than the above
alpha and ia64 (HP-testdrive) on which I can test.
I modified the text a little:
BUGS
A limitation of the Linux system call conventions on some
architectures (notably x86) means that if a (negative) pro‐
cess group ID to be returned by F_GETOWN falls in the range
-1 to -4095, then the return value is wrongly interpreted
by glibc as an error in the system call; that is, the
return value of fcntl() will be -1, and errno will contain
the (positive) process group ID.
I've left a FIXME in the man page source noting that details have
yet to be sorted out for ia64, alpha, etc.
2004-12-13 11:32:37 +00:00
|
|
|
.\" FIXME Dec 04: some limited testing on alpha and ia64 seems to
|
|
|
|
.\" indicate that ANY negative PGID value will cause F_GETOWN
|
|
|
|
.\" to misintepret the return as an error.Some other architectures
|
|
|
|
.\" seem to have the same range check as x86. -- MTK
|
2004-11-03 13:51:07 +00:00
|
|
|
.SH "CONFORMING TO"
|
|
|
|
SVr4, SVID, POSIX, X/OPEN, BSD 4.3. Only the operations F_DUPFD,
|
|
|
|
F_GETFD, F_SETFD, F_GETFL, F_SETFL, F_GETLK, F_SETLK and F_SETLKW are
|
|
|
|
specified in POSIX.1. F_GETOWN and F_SETOWN are BSDisms not supported
|
|
|
|
in SVr4; F_GETSIG and F_SETSIG are specific to Linux.
|
|
|
|
.BR F_NOTIFY ", " F_GETLEASE ", and " F_SETLEASE
|
|
|
|
are Linux specific.
|
|
|
|
(Define the _GNU_SOURCE macro before including <fcntl.h> to
|
|
|
|
obtain these definitions.)
|
|
|
|
The flags legal for F_GETFL/F_SETFL are those supported by
|
|
|
|
.BR open (2)
|
|
|
|
and vary between these systems; O_APPEND, O_NONBLOCK, O_RDONLY,
|
|
|
|
and O_RDWR are specified in POSIX.1. SVr4 supports several other
|
|
|
|
options and flags not documented here.
|
|
|
|
.PP
|
|
|
|
SVr4 documents additional EIO, ENOLINK and EOVERFLOW error conditions.
|
|
|
|
.SH "SEE ALSO"
|
|
|
|
.BR dup2 (2),
|
|
|
|
.BR flock (2),
|
|
|
|
.BR open (2),
|
|
|
|
.BR socket (2),
|
|
|
|
.BR lockf (3),
|
|
|
|
.BR capabilities (7)
|
|
|
|
.P
|
|
|
|
See also locks.txt, mandatory.txt, and dnotify.txt in
|
|
|
|
/usr/src/linux/Documentation.
|