Hi Theo, Theo de Raadt wrote on Mon, Dec 23, 2019 at 11:11:41AM -0700: > Ingo Schwarze <[email protected]> wrote:
>> +.Pp >> +The driver of the device that is being read from >> +may return additional errors. >> +Such device-specific errors may be documented >> +in the section 4 manual pages of the respective drivers. > I'm unhappy with the wording "the driver of the device". It is overly > precise and inaccurate. Additional errors may come from drivers, but > also from subsystems like netinet, net, scsi, etc. So neither driver > nor device applies -- additional errors can percolate upwards from a > vast list of underlying code. I see. So we should refrain from trying to list sources of errors. > I also worry that programmers won't know what action to take for > specific errors. Some may feel they must expect all error values and > handle them in different ways (some to be ignored, others as fatal). > What is the correct strategy for handling potentially arbitrary errors? A good rule of thumb is: treat unexpected errors in the same way as the most severe errors that are expected. Usually, that doesn't require additional code, and i expect that in most cases, it will be a secure course of action. (Though in exceptional cases, it may be better to treat unexpected errors as even worse than the most serious expected errors, but that can only be decided on a case-by-case basis.) > This text is leading people to expect anything, that this is the new > normal, and it is worrisome. That conclusion from that argument would be to avoid explicitly drawing attention to the fact that additional errors can occur and simply use a wording that can less easily be misconstrued as introducing a complete list. Even without saying "additional errors may occur", programmers will usually (hopefully) expect that because experience teaches that most listings of error conditions in documentation are not exhaustive, in particular when they don't expliciutly claim to be exhaustive. > It is sad that so many extra errnos have been exposed over the years. > > Many low-level errors should have been abstracted into existing > higher-level catagories, if the effect and disposition are the same, then > map the internal condition to the same errno. > > Or the low-level error should not exist in the first place, the lower > level code is simply being sloppy, and the abstraction is incomplete. I agree that proliferation of error codes can be distracting, confusing, and annoying, but with the above rule of thumb, the practical problem is usually manageable. So, here is a proposal to merely avoid explicitly claiming completeness for system calls that take file descriptors (using the hint from guenther@ that this is a useful criterion). The second chunk in read.2 merely removes a gratuitious and potentially confusing wording difference. Yours, Ingo Index: read.2 =================================================================== RCS file: /cvs/src/lib/libc/sys/read.2,v retrieving revision 1.36 diff -u -r1.36 read.2 --- read.2 30 Sep 2016 10:53:11 -0000 1.36 +++ read.2 24 Dec 2019 13:28:29 -0000 @@ -143,7 +143,7 @@ .Fn pread , and .Fn preadv -will succeed unless: +will fail if: .Bl -tag -width Er .It Bq Er EBADF .Fa d @@ -210,7 +210,7 @@ .Fn readv and .Fn preadv -may return one of the following errors: +may return the following errors: .Bl -tag -width Er .It Bq Er EINVAL .Fa iovcnt Index: symlink.2 =================================================================== RCS file: /cvs/src/lib/libc/sys/symlink.2,v retrieving revision 1.20 diff -u -r1.20 symlink.2 --- symlink.2 10 Sep 2015 17:55:21 -0000 1.20 +++ symlink.2 24 Dec 2019 13:28:30 -0000 @@ -87,7 +87,7 @@ .Sh RETURN VALUES .Rv -std .Sh ERRORS -The symbolic link succeeds unless: +The symbolic link will fail if: .Bl -tag -width Er .It Bq Er ENOTDIR A component of the Index: truncate.2 =================================================================== RCS file: /cvs/src/lib/libc/sys/truncate.2,v retrieving revision 1.19 diff -u -r1.19 truncate.2 --- truncate.2 28 Feb 2016 14:38:25 -0000 1.19 +++ truncate.2 24 Dec 2019 13:28:30 -0000 @@ -64,7 +64,7 @@ .Fn truncate and .Fn ftruncate -will succeed unless: +will fail if: .Bl -tag -width Er .It Bq Er EINVAL The
