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

[Rich Felker]

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".

> 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.

> >> 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

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"
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.

Rich