Return-Path: Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1754583AbaDOUZu (ORCPT ); Tue, 15 Apr 2014 16:25:50 -0400 Received: from mx1.redhat.com ([209.132.183.28]:13959 "EHLO mx1.redhat.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1751124AbaDOUZq (ORCPT ); Tue, 15 Apr 2014 16:25:46 -0400 Date: Tue, 15 Apr 2014 16:25:32 -0400 From: Jeff Layton To: mtk.manpages@gmail.com Cc: linux-man , "linux-fsdevel@vger.kernel.org" , Ganesha NFS List , samba-technical@lists.samba.org, lkml Subject: Re: [PATCH RFC] fcntl.2: update manpage with verbiage about file-private locks Message-ID: <20140415162532.11257c8a@tlielax.poochiereds.net> In-Reply-To: References: <1389277387-18530-1-git-send-email-jlayton@redhat.com> MIME-Version: 1.0 Content-Type: text/plain; charset=US-ASCII Content-Transfer-Encoding: 7bit Sender: linux-kernel-owner@vger.kernel.org List-ID: X-Mailing-List: linux-kernel@vger.kernel.org On Tue, 15 Apr 2014 22:08:50 +0200 "Michael Kerrisk (man-pages)" wrote: > Hello Jeff, > > On Thu, Jan 9, 2014 at 3:23 PM, Jeff Layton wrote: > > Please don't merge this yet, as the kernel patches are still a work in > > progress... > > Now that this has hit mainline, is this man page patch still current? > > Cheers, > > Michael > No, it needs a bit of a revision. I'm sorting through the glibc patches now, and will plan to send a respin of this once that's complete. Thanks! > > Signed-off-by: Jeff Layton > > --- > > man2/fcntl.2 | 97 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++-- > > 1 file changed, 94 insertions(+), 3 deletions(-) > > > > diff --git a/man2/fcntl.2 b/man2/fcntl.2 > > index 72dcd7b..74c67b6 100644 > > --- a/man2/fcntl.2 > > +++ b/man2/fcntl.2 > > @@ -208,7 +208,7 @@ struct flock { > > 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) */ > > + (F_GETLK and F_GETLKP only) */ > > ... > > }; > > .fi > > @@ -344,9 +344,13 @@ 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 > > +. > > +If the conflicting lock is a traditional POSIX lock, then the > > .I l_pid > > -to be the PID of the process holding that lock. > > +will be set to the PID of the process holding that lock. If the > > +conflicting lock is a file-private lock, then the > > +.I l_pid > > +will be set to -1. > > .P > > In order to place a read lock, > > .I fd > > @@ -386,6 +390,93 @@ should be avoided; use > > and > > .BR write (2) > > instead. > > +.SS File-private locking > > +(Currently non-POSIX, but being proposed) > > +.PP > > +.BR F_GETLKP ", " F_SETLKP " and " F_SETLKPW > > +are used to acquire, release and test file-private record locks. These > > +are byte-range locks that work identically to the traditional advisory > > +record locks described above, but are associated with the open file on > > +which they were acquired rather than the process, much like locks > > +acquired with > > +.BR flock (2) > > +. > > +.PP > > +Unlike traditional advisory record locks, these locks are inherited > > +across > > +.BR fork (2) ", " dup (2) " and " dup2 (2) > > +and are only released on the last close of the open file instead of being > > +released on any close of the file. > > +.PP > > +File-private locks always conflict with traditional record locks, even > > +when they are acquired by the same process on the same file descriptor. > > +They only conflict with each other when they are acquired on different > > +open file descriptors. > > +.TP > > +.BR F_SETLKP " (\fIstruct flock *\fP)" > > +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 > > +.BR F_SETLKPW " (\fIstruct flock *\fP)" > > +As for > > +.BR F_SETLKP , > > +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 ; > > +see > > +.BR signal (7)). > > +.TP > > +.BR F_GETLKP " (\fIstruct flock *\fP)" > > +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 > > +. > > +If the conflicting lock is a traditional POSIX lock, then the > > +.I l_pid > > +will be set to the PID of the process holding that lock. If the > > +conflicting lock is a file-private lock, then the > > +.I l_pid > > +will be set to -1. > > .SS Mandatory locking > > (Non-POSIX.) > > The above record locks may be either advisory or mandatory, > > -- > > 1.8.4.2 > > > > -- > > To unsubscribe from this list: send the line "unsubscribe linux-man" in > > the body of a message to majordomo@vger.kernel.org > > More majordomo info at http://vger.kernel.org/majordomo-info.html > > > -- Jeff Layton -- To unsubscribe from this list: send the line "unsubscribe linux-kernel" in the body of a message to majordomo@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/