Signed-off-by: Jeff Layton <jlayton@xxxxxxxxxx>
---
ChangeLog | 1 +
manual/llio.texi | 175 ++++++++++++++++++++++++++++++++++++++++++++++++++++++-
2 files changed, 174 insertions(+), 2 deletions(-)
diff --git a/ChangeLog b/ChangeLog
index db5b90385e2c..d2f9a52dd283 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,6 +1,7 @@
2014-02-11 Jeff Layton <jlayton@xxxxxxxxxx>
* add new fcntl cmd macros for file-private locks
+ * add manual section about file-private locks
2014-02-11 Stefan Liebler <stli@xxxxxxxxxxxxxxxxxx>
diff --git a/manual/llio.texi b/manual/llio.texi
index 69b54c2838c9..533992a5b40b 100644
--- a/manual/llio.texi
+++ b/manual/llio.texi
@@ -57,6 +57,8 @@ directly.)
flags associated with open files.
* File Locks:: Fcntl commands for implementing
file locking.
+* File-private Locks:: Fcntl commands for implementing
+ file-private locking.
* Interrupt Input:: Getting an asynchronous signal when
input arrives.
* IOCTLs:: Generic I/O Control operations.
@@ -2890,7 +2892,7 @@ Get flags associated with the open file. @xref{File Status Flags}.
Set flags associated with the open file. @xref{File Status Flags}.
@item F_GETLK
-Get a file lock. @xref{File Locks}.
+Get (test) a file lock. @xref{File Locks}.
@item F_SETLK
Set or clear a file lock. @xref{File Locks}.
@@ -2898,6 +2900,15 @@ Set or clear a file lock. @xref{File Locks}.
@item F_SETLKW
Like @code{F_SETLK}, but wait for completion. @xref{File Locks}.
+@item F_GETLKP
+Get (test) a file-private lock. @xref{File Locks}.
+
+@item F_SETLKP
+Set or clear a file lock. @xref{File Locks}.
+
+@item F_SETLKPW
+Like @code{F_SETLKP}, but wait for completion. @xref{File Locks}.
+
@item F_GETOWN
Get process or process group ID to receive @code{SIGIO} signals.
@xref{Interrupt Input}.
@@ -3576,6 +3587,10 @@ set_nonblock_flag (int desc, int value)
@cindex file locks
@cindex record locking
+This section describes "classic" record locks. There is also a newer type
+of record lock that is associated with the open file table entry instead
+of the process. @xref{File-private Locks}
+
The remaining @code{fcntl} commands are used to support @dfn{record
locking}, which permits multiple cooperating programs to prevent each
other from simultaneously accessing parts of a file in error-prone
@@ -3641,7 +3656,9 @@ the file.
@item pid_t l_pid
This field is the process ID (@pxref{Process Creation Concepts}) of the
process holding the lock. It is filled in by calling @code{fcntl} with
-the @code{F_GETLK} command, but is ignored when making a lock.
+the @code{F_GETLK} command, but is ignored when making a lock. If the
+conflicting lock is a File-private lock (@pxref{File-private Locks}),
+then this field will be set to @math{-1}.
@end table
@end deftp
@@ -3817,6 +3834,160 @@ Remember that file locks are only a @emph{voluntary} protocol for
controlling access to a file. There is still potential for access to
the file by programs that don't use the lock protocol.
+@node File-private Locks
+@section File-private Locks
+
+In contrast to classic record locks (@pxref{File Locks}), file-private
+locks are associated with an open file table entry rather than a
+process. File-private locks set on an open file descriptor will never
+conflict with existing file-private locks set on that file descriptor.
+
+File-private locks are also inherited by child processes across
+@code{fork} (@pxref{Creating a Process}), along with the file
+descriptor. For this reason, the @code{l_pid} field in @code{struct
+flock} is meaningless for file private locks. For the @code{F_GETLK} and
+@code{F_GETLKP} commands, the @code{l_pid} value is always set to
+@math{-1} if the blocking lock is a file-private one.
+
+Note that using @code{dup} (@pxref{Duplicating Descriptors}) to clone a
+file descriptor does not give you a new instance of the open file, but
+instead just clones a reference to an existing open file. Thus,
+file-private locks set on a file descriptor cloned by @code{dup} will
+never conflict with file-private locks set on the original descriptor.
+
+File-private locks always conflict with classic record locks, even if
+acquired by the same process or on the same open file descriptor.
+
+File-private locks use the same @code{struct flock} as classic POSIX
+locks as an argument (@pxref{File Locks}) and the macros for the
+cmd values are also declared in the header file @file{fcntl.h}.
+@pindex fcntl.h.
+
+@deftypevr Macro int F_GETLKP
+This macro is used as the @var{command} argument to @code{fcntl}, to
+specify that it should get information about a lock. This command
+requires a third argument of type @w{@code{struct flock *}} to be passed
+to @code{fcntl}, so that the form of the call is:
+
+If there is a lock already in place that would block the lock described
+by the @var{lockp} argument, information about that lock overwrites
+@code{*@var{lockp}}. Existing locks are not reported if they are
+compatible with making a new lock as specified. Thus, you should
+specify a lock type of @code{F_WRLCK} if you want to find out about both
+read and write locks, or @code{F_RDLCK} if you want to find out about
+write locks only.
+
+There might be more than one lock affecting the region specified by the
+@var{lockp} argument, but @code{fcntl} only returns information about
+one of them. The @code{l_whence} member of the @var{lockp} structure is
+set to @code{SEEK_SET} and the @code{l_start} and @code{l_len} fields
+set to identify the locked region.
+
+If no lock applies, the only change to the @var{lockp} structure is to
+update the @code{l_type} to a value of @code{F_UNLCK}.
+
+The normal return value from @code{fcntl} with this command is an
+unspecified value other than @math{-1}, which is reserved to indicate an
+error. The following @code{errno} error conditions are defined for
+this command:
+
+@table @code
+@item EBADF
+The @var{filedes} argument is invalid.
+
+@item EINVAL
+Either the @var{lockp} argument doesn't specify valid lock information,
+or the file associated with @var{filedes} doesn't support locks.
+@end table
+@end deftypevr
+
+@comment fcntl.h
+@comment POSIX.1
+@deftypevr Macro int F_SETLKP
+This macro is used as the @var{command} argument to @code{fcntl}, to
+specify that it should set or clear a lock. This command requires a
+third argument of type @w{@code{struct flock *}} to be passed to
+@code{fcntl}, so that the form of the call is:
+
+@smallexample
+fcntl (@var{filedes}, F_SETLK, @var{lockp})
+@end smallexample
+
+If the opened file already has a lock on any part of the
+region, the old lock on that part is replaced with the new lock. You
+can remove a lock by specifying a lock type of @code{F_UNLCK}.
+
+If the lock cannot be set, @code{fcntl} returns immediately with a value
+of @math{-1}. This function does not block waiting for other tasks
+to release locks. If @code{fcntl} succeeds, it returns a value other
+than @math{-1}.
+
+The following @code{errno} error conditions are defined for this
+function:
+
+@table @code
+@item EAGAIN
+@itemx EACCES
+The lock cannot be set because it is blocked by an existing lock on the
+file. Some systems use @code{EAGAIN} in this case, and other systems
+use @code{EACCES}; your program should treat them alike, after
+@code{F_SETLKP}. (@gnulinuxhurdsystems{} always use @code{EAGAIN}.)
+
+@item EBADF
+Either: the @var{filedes} argument is invalid; you requested a read lock
+but the @var{filedes} is not open for read access; or, you requested a
+write lock but the @var{filedes} is not open for write access.
+
+@item EINVAL
+Either the @var{lockp} argument doesn't specify valid lock information,
+or the file associated with @var{filedes} doesn't support locks.
+
+@item ENOLCK
+The system has run out of file lock resources; there are already too
+many file locks in place.
+
+Well-designed file systems never report this error, because they have no
+limitation on the number of locks. However, you must still take account
+of the possibility of this error, as it could result from network access
+to a file system on another machine.
+@end table
+@end deftypevr
+
+@comment fcntl.h
+@comment POSIX.1
+@deftypevr Macro int F_SETLKPW
+This macro is used as the @var{command} argument to @code{fcntl}, to
+specify that it should set or clear a lock. It is just like the
+@code{F_SETLKP} command, but causes the process to block (or wait)
+until the request can be specified.
+
+This command requires a third argument of type @code{struct flock *}, as
+for the @code{F_SETLKP} command.
+
+The @code{fcntl} return values and errors are the same as for the
+@code{F_SETLKP} command, but these additional @code{errno} error conditions
+are defined for this command:
+
+@table @code
+@item EINTR
+The function was interrupted by a signal while it was waiting.
+@xref{Interrupted Primitives}.
+
+@end table
+@end deftypevr
+
+File-private locks are useful in the same sorts of situations as classic
+record locks. They can also be used to synchronize file access between
+threads within the same process by giving each thread its own open file
+instance.
+
+Because they are only released automatically when the last reference to
+an open file is destroyed, file-private locks allow more assurance that
+the locks will not be released due to a library routine opening and
+closing a file without the application being aware.
+
+Like with classic record locks, file-private locks are also voluntary.
+
@node Interrupt Input
@section Interrupt-Driven Input
--
1.8.5.3
--
To unsubscribe from this list: send the line "unsubscribe linux-fsdevel" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html
