From patchwork Fri Apr 11 12:55:45 2014 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Jeff Layton X-Patchwork-Id: 338507 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Received: from sourceware.org (server1.sourceware.org [209.132.180.131]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by ozlabs.org (Postfix) with ESMTPS id 744C514008A for ; Fri, 11 Apr 2014 22:56:20 +1000 (EST) DomainKey-Signature: a=rsa-sha1; c=nofws; d=sourceware.org; h=list-id :list-unsubscribe:list-subscribe:list-archive:list-post :list-help:sender:from:to:subject:date:message-id:in-reply-to :references; q=dns; s=default; b=pcFAXEJT71E7df8Sg+Wq8rY+HAPHmbz NX/Z07p2UafFfDexWdEsaua7GxA19uE1kvN09Zd9RpIaOC/logK971Wg3nfL97Ki kbZ7Bw5JLdBQAlX2gYgHaI/v/DeZTqbDaZcW0YowYENqF8kpmgIglOlTHvEn/4WH 6XXAXVfLXecA= DKIM-Signature: v=1; a=rsa-sha1; c=relaxed; d=sourceware.org; h=list-id :list-unsubscribe:list-subscribe:list-archive:list-post :list-help:sender:from:to:subject:date:message-id:in-reply-to :references; s=default; bh=Gjp2TRZLUPSms6k/2FqxyxjHwfE=; b=MrUDJ CgNyJgKaAnokjTEh/v38TuEMQ5HZdeqMsPF5MLwnmFBqn4acyQpYfro8NWnfgeMS 73/xGZZ8/+VPiZR76eMVOMuSFNU9XDqQy1pKKbCjbxV0cKomVo0XaGz/GEiRtKKK T6mYJnCY040XUZp1H2ZS+cyGhsnLT6yuPqJA00= Received: (qmail 11779 invoked by alias); 11 Apr 2014 12:56:00 -0000 Mailing-List: contact libc-alpha-help@sourceware.org; run by ezmlm Precedence: bulk List-Id: List-Unsubscribe: List-Subscribe: List-Archive: List-Post: List-Help: , Sender: libc-alpha-owner@sourceware.org Delivered-To: mailing list libc-alpha@sourceware.org Received: (qmail 11723 invoked by uid 89); 11 Apr 2014 12:55:59 -0000 Authentication-Results: sourceware.org; auth=none X-Virus-Found: No X-Spam-SWARE-Status: No, score=-1.9 required=5.0 tests=BAYES_00, RCVD_IN_DNSWL_NONE autolearn=ham version=3.3.2 X-HELO: mail-qg0-f42.google.com X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20130820; h=x-gm-message-state:sender:from:to:subject:date:message-id :in-reply-to:references; bh=Qo/SYCj7wWvzp2FT+tp4Vr7qoVNnKb8bPyKyBAXTLoQ=; b=LiCPu7+kwrI8S3YG2LNFIprepN9QVoA5y/+tItD8iYSWHoZXljfskbQZh6zor3ELi+ VHVM1GAA3MLddf1K3Q7nczrLo1wrAZbydE0DyvgllbcjrrCW861vOrgP7x4rVqqEGUOg e16s9erbTNuqhbJIXdtStKsDh96Y0BTDypRj/MD4whb3OMAp2dA7ALGN+6ReV663+4EF N2VprC2wf3RUPxhO28lrRId6Ppx772D891lyI903vy7ycRc/JYIbsWWfusCxiiBNZV/b jUZonzZBEJdGhHD5IimPx2PPhLnb5wtl+Q3kf657Vym9Wnnhk1adh6iMERpOE6mRXkdr FJVA== X-Gm-Message-State: ALoCoQmpZA8gJwx+OAdJKK0x543l77aMWAq6XDGTY2bhlQ40BF9V5frx3+20Dx+W04EJegE8tjZ5 X-Received: by 10.140.83.37 with SMTP id i34mr1880561qgd.100.1397220953340; Fri, 11 Apr 2014 05:55:53 -0700 (PDT) From: Jeff Layton To: libc-alpha@sourceware.org Subject: [PATCH v2 2/2] manual/llio.texi: update manual to document file-private locks Date: Fri, 11 Apr 2014 08:55:45 -0400 Message-Id: <1397220945-11926-3-git-send-email-jlayton@redhat.com> In-Reply-To: <1397220945-11926-1-git-send-email-jlayton@redhat.com> References: <1397220945-11926-1-git-send-email-jlayton@redhat.com> Signed-off-by: Jeff Layton --- ChangeLog | 1 + manual/llio.texi | 183 ++++++++++++++++++++++++++++++++++++++++++++++++++++++- 2 files changed, 182 insertions(+), 2 deletions(-) diff --git a/ChangeLog b/ChangeLog index 55a84e598e46..622315629a44 100644 --- a/ChangeLog +++ b/ChangeLog @@ -2,6 +2,7 @@ * sysdeps/unix/sysv/linux/bits/fcntl-linux.h: (F_GETLKP, F_SETLKP, F_SETLKPW): New macros. + * manual/llio.texi: add section about file-private locks 2014-04-11 Stefan Liebler diff --git a/manual/llio.texi b/manual/llio.texi index 6f8adfc607d7..bcaf0e419a90 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,168 @@ 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}. To +use them, the macro @code{_GNU_SOURCE} must be defined prior to +including @file{fcntl.h}. + +In contrast to the @code{F_SETLK} or @code{F_SETLKW} commands, any +@code{struct flock} used as an argument to the @code{F_SETLKP} or +@code{F_SETLKPW} commands must have the @code{l_pid} value set to +@math{0}. + +@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_SETLKP, @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. + +As with classic record locks, file-private locks are also voluntary. + @node Interrupt Input @section Interrupt-Driven Input