[PATCH] locks: rename file-private locks to file-description locks

Mon Apr 28 04:23:21 MDT 2014

On Sun, 27 Apr 2014 14:51:25 +1000
NeilBrown <neilb at suse.de> wrote:

> On Tue, 22 Apr 2014 06:54:36 +0200 "Michael Kerrisk (man-pages)"
> <mtk.manpages at gmail.com> wrote:
> 
> > On 04/21/2014 11:15 PM, Stefan (metze) Metzmacher wrote:
> > > Am 21.04.2014 21:55, schrieb Jeff Layton:
> > >> On Mon, 21 Apr 2014 21:39:12 +0200
> > >> "Michael Kerrisk (man-pages)" <mtk.manpages at gmail.com> wrote:
> > >>
> > >>> On 04/21/2014 08:46 PM, Rich Felker wrote:
> > >>>> On Mon, Apr 21, 2014 at 08:32:44PM +0200, Michael Kerrisk (man-pages) wrote:
> > >>>>> On 04/21/2014 06:10 PM, Rich Felker wrote:
> > >>>>>> I'm well aware of that. The problem is that the proposed API is using
> > >>>>>> the two-letter abbreviation FD, which ALWAYS means file descriptor and
> > >>>>>> NEVER means file description (in existing usage) to mean file
> > >>>>>> description. That's what's wrong.
> > >>>>>
> > >>>>> So, can you *please* answer this question: what do you call (i.e., 
> > >>>>> what  everyday technical language term do use for) the thing
> > >>>>> that sits between a file descriptor and an i-node? 
> > >>>>>
> > >>>>> (Please don't say 'struct file' -- that is not is an implementation 
> > >>>>> detail, and does not qualify as the kind of term that I could use 
> > >>>>> when documenting this feature in man pages.)
> > >>>>
> > >>>> "Open file description".
> > >>>
> > >>> Oh! I didn't realize we agreed :-).
> > >>>
> > >>>>> POSIX uses (or invented, I am not sure which) the term file description
> > >>>>> for a good reason: it is unambiguous, and therefore precise. I do agree
> > >>>>> that there's a risk of confusion between 'open file descriptor" and 
> > >>>>> 'and file description'--it's the same kind of risk as between English 
> > >>>>> terms such as 'arbitrator' and 'arbitration' (and any number of other
> > >>>>> examples), and as language speakers we deal with this every day.
> > >>>>
> > >>>> There's not a problem when the full word is used. On the other hand,
> > >>>> if you use "arb" as an abbreviation for "arbitration" in a context
> > >>>> where it was already universally understood as meaning "arbitrator",
> > >>>> that would be a big problem.
> > >>>>
> > >>>> Likewise the problem here isn't that "open file description" is a bad
> > >>>> term. It's that using "FD" to mean "[open] file description" is
> > >>>> utterly confusing, even moreso than just making up a new completely
> > >>>> random word.
> > >>>
> > >>> Ohh -- I had thought you a problem not just with "FD" but also
> > >>> "(open) file description".
> > >>>
> > >>>>>>> 2) The new API constants (F_SETLKP, F_SETLKPW, F_GETLKP) have names
> > >>>>>>>    that are visually very close to the traditional POSIX lock names 
> > >>>>>>>    (F_SETLK, F_SETLKW, F_GETLK). That's an accident waiting to happen
> > >>>>>>>    when someone mistypes in code and/or misses such a misttyping
> > >>>>>>>    when reading code. That really must be fixed.
> > >>>>>>
> > >>>>>> I agree, but I don't think making it worse is a solution.
> > >>>>>
> > >>>>> I don't agree that it's making it worse. The real problem here is 
> > >>>>> that people use no good unambiguous term for the thing between a file
> > >>>>> descriptor and an inode. POSIX provides us with a solution that may
> > >>>>> not seem perfect, but it is unambiguous, and I think it might feel
> > >>>>> more comfortable if we used it often enough.
> > >>>>
> > >>>> I would like to see it used more too, and in particular, I think it
> > >>>> belongs in the documentation for these new locking interfaces. But
> > >>>> that still doesn't answer the question of what to call them (the
> > >>>> macros) unless you want:
> > >>>>
> > >>>> F_OPEN_FILE_DESCRIPTION_GETLK
> > >>>> F_OPEN_FILE_DESCRIPTION_SETLK
> > >>>> F_OPEN_FILE_DESCRIPTION_SETLKW
> > >>>
> > >>> Or just 'F_OFD_*'?
> > >>>
> > >>>> Perhaps "OP" (for open-private, i.e. private to the particular open)
> > >>>> would be a sensible choice; OTOH people are likely to misread it as
> > >>>> OPeration. The general principle I have in mind though is that it
> > >>>> might be nice to highlight the word "open" in "open file description"
> > >>>
> > >>> (Fair enough.)
> > >>>
> > >>>> since it (1) contrasts with file descriptor, despite file descriptors
> > >>>> also dealing with open files, and (2) contrasts well with legacy fcntl
> > >>>> locks, which are (this is the whole bug) associated with the
> > >>>> underlying file and not the open file description.
> > >>>
> > >>> Makes sense to me. (We are in more agreement that I realized.)
> > >>>
> > >>> Cheers,
> > >>>
> > >>> Michael
> > >>>
> > >>>
> > >>>
> > >>
> > >> So the motion is to call them "open file description locks" and change
> > >> the macros to read *_OFD_*. Does anyone object?
> > > 
> > > Works fine for me...
> > 
> > And works for me.
> > 
> > 
> 
> I think the word "open" is important here.
> I find that "description" is not a word I would have every thought was
> relevant here - it is obviously too long since I have read the man pages.
> 
> I would prefer
>   per-open locks
> which are contrasted with
>   per-process locks
> 
> An alternative might be "flock-like" as locks created with "flock" have
> exactly the property we are trying to describe.  Reading the man page for
> "flock" then suggests "open file table entry locks" which is even more of a
> mouthful.  "oftel" is pronounceable though.  Then we could talk about "oftel
> locks" in the same sentence as "pin numbers" and "RAM memory".
> 
> But maybe I came too late to this party, and the boat has sailed?
> 
> Note to Michael: The text
>    flock() does not lock files over NFS.
> in flock(2) is no longer accurate.  The reality is ... complex.
> See nfs(5), and search for "local_lock".
> 
> 
> NeilBrown
> 
> (I don't care what the macros are - XX would work as well any anything else
> for me).

I sent a pull request to Linus last week and he merged the patches over
the weekend. So yes, this ship has sailed unless someone feels strongly
enough about it to roll up the patches to change it.

I think we'll probably come to know these as "O.F.D. locks" over the long
run. Not a wonderful name, but I can live with it.

Thanks,
-- 
Jeff Layton <jlayton at redhat.com>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 836 bytes
Desc: not available
URL: <http://lists.samba.org/pipermail/samba-technical/attachments/20140428/ca71b555/attachment.pgp>