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

[Theodore Ts'o]

On Mon, Apr 21, 2014 at 02:51:44PM -0400, Rich Felker wrote:
> I don't think "struct file" has any meaning to any userspace
> developers, and as such doesn't belong in documentation for userspace
> programming. It's an implementation detail of the kernel that
> userspace developers have no need to be aware of. There's already
> enough leakage of broken kernel internals (e.g. tid vs pid vs tgid)
> into userspace documentation that's immensely confusing for new
> developers without adding more of it.

Userspace programmers who are using dup(2) or dup(2) need to
understand this "implementation detail".  The fact that the file
descriptor is an integer index into an array which points to a "struct
file" object is a fundamental part of the Unix/POSIX interface.  So
the fact that it has leaked out there.

I think what you mean is that there is no need that we expose the name
"struct file".  My point is that "struct file" is actually a much
_better_ name than "file description".  Heck, "open file object" would
be better name than "file description".

Hmm, how about "open file object"?  And what I'd recommend is that we
try very hard to push that name across the documentation, into the
dup/dup2 man page, with an parenthetical explanation that if you read
reading POSIX specification, you may run across the term "file
description", which is the same thing.

Realistically, far more people are likely to be looking at the man
pages rather than the POSIX specification (if for no other reason than
you have to register your e-mail address to gain access to it
on-line).  So getting the man pages to be easily understandable is,
IMHO, more important than being in 100% alignment with POSIX.

						- Ted