Hi Peter,
Peter J. Philipp wrote on Tue, Oct 24, 2017 at 04:35:12PM +0200:
> Index: open.2
> ===================================================================
> RCS file: /cvs/src/lib/libc/sys/open.2,v
> retrieving revision 1.49
> diff -u -p -u -r1.49 open.2
> --- open.2 19 Jan 2015 15:54:11 -0000 1.49
> +++ open.2 24 Oct 2017 14:28:30 -0000
> @@ -235,6 +235,10 @@ and
> .Fn openat
> functions will fail if:
> .Bl -tag -width Er
> +.It Bq Er EPERM
> +When opening a special file and the program has requested certain
> +.Xr pledge 2
> +promises.
> .It Bq Er ENOTDIR
> A component of the path prefix is not a directory.
> .It Bq Er ENOTDIR
I'm not convinced.
1) I don't like the idea of scattering pledge(2) documentation
all over the place.
2) To me, this feel like a detail that might easily change without
notice, and then we risk leaving a bug behind in the manual.
3) ERRORS sections are in a bad shape in general, both in POSIX
and in our manuals. In POSIX, they are quite incomplete, which
makes POSIX quite confusing if you really want to code errno
checks in a portable manner. We have huge amounts of extensions
in this area, many of them allowed by the standard, some
forbidden, many documented, many undocumented, some documented
in ways that are outright wrong, and we explain almost nowhere
which ERRORS are standard and which are extensions. We should,
because otherwise people can't check them portably, and telling
people to read POSIX itself just isn't realistic with respect
to ERRORS, given the mess people will find there.
What you add here is an extremely minor detail in an area that is
severely under-documented and disorganized in much more relevant
respects. Besides, the number of ERRORS entries in the open(2)
manual in particular is already excessive without this addition.
So your patch feels a bit like lipstick on a grazing hippo, somewhere
near the rear end, in the late afternoon shortly before it goes
back into the water.
I'm not saying such stuff should remain undocumented, but i *am*
at a loss where to start. Probably not with this particular detail.
Yours,
Ingo
