Clarify details in description of file leases.

Minor wording edits.
This commit is contained in:
Michael Kerrisk 2007-11-19 01:21:58 +00:00
parent 608497637a
commit ea53895cb8
1 changed files with 24 additions and 15 deletions

View File

@ -592,9 +592,9 @@ in Linux as part of the GNU C Library (Glibc).
.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
(Linux 2.4 onwards) are used (respectively) to establish a new lease,
and retrieve the current lease, on the open file description
referred to by the file descriptor
.IR fd .
A file lease provides a mechanism whereby the process holding
the lease (the "lease holder") is notified (via delivery of a signal)
@ -602,13 +602,12 @@ when a process (the "lease breaker") tries to
.BR open (2)
or
.BR truncate (2)
that file.
the file referred to by that file descriptor.
.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
@ -624,30 +623,39 @@ is opened read-only.
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 no other process
currently has the file open.
A write lease may be placed on a file only if there are no
other open file descriptors for the file.
.TP
.B F_UNLCK
Remove our lease from the file.
.RE
.P
A process may hold only one type of lease on a file.
Leases are associated with an open file description (see
.BR open (2)).
This means that duplicate file descriptors (created by, for example,
.BR fork (2)
or
.BR dup (2))
refer to the same lease, and this lease may be modified
or released using any of these descriptors.
Furthermore, the lease is released by either an explicit
.B F_UNLCK
operation on any of these duplicate descriptors, or when all
such descriptors have been closed.
.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.
UID (owner) 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
Indicates what type of lease is associated with the file descriptor
.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.
indicating, respectively, a read lease , a write lease, or no lease.
(The third argument to
.BR fcntl ()
is omitted.)
@ -672,9 +680,10 @@ command specifying
.I arg
as
.BR F_UNLCK .
If we currently hold a write lease on the file,
If the lease holder currently holds 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.
then it is sufficient for the lease holder to downgrade
the lease to a read lease.
This is done by performing an
.B F_SETLEASE
command specifying