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

[NeilBrown]

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).
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 828 bytes
Desc: not available
URL: <http://lists.samba.org/pipermail/samba-technical/attachments/20140427/cb31637a/attachment.pgp>