This is the mail archive of the
libc-alpha@sourceware.org
mailing list for the glibc project.
Re: [PATCH] locks: rename file-private locks to file-description locks
- From: Theodore Ts'o <tytso at mit dot edu>
- To: Rich Felker <dalias at libc dot org>
- Cc: "Michael Kerrisk (man-pages)" <mtk dot manpages at gmail dot com>, Jeff Layton <jlayton at redhat dot com>, linux-fsdevel at vger dot kernel dot org, linux-kernel at vger dot kernel dot org, samba-technical at lists dot samba dot org, Ganesha NFS List <nfs-ganesha-devel at lists dot sourceforge dot net>, Carlos O'Donell <carlos at redhat dot com>, libc-alpha <libc-alpha at sourceware dot org>, "Stefan (metze) Metzmacher" <metze at samba dot org>, Christoph Hellwig <hch at infradead dot org>
- Date: Mon, 21 Apr 2014 15:04:10 -0400
- Subject: Re: [PATCH] locks: rename file-private locks to file-description locks
- Authentication-results: sourceware.org; auth=none
- References: <1398087935-14001-1-git-send-email-jlayton at redhat dot com> <20140421140246 dot GB26358 at brightrain dot aerifal dot cx> <535529FA dot 8070709 at gmail dot com> <20140421161004 dot GC26358 at brightrain dot aerifal dot cx> <5355644C dot 7000801 at gmail dot com> <20140421184841 dot GA5105 at thunk dot org> <20140421185144 dot GF26358 at brightrain dot aerifal dot cx>
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