[src/trunk]: src/lib/libc/sys Note that open(O_ASYNC) does not work as advert...

[riastradh <riastradh%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/653e9e8357be
branches:  trunk
changeset: 1016750:653e9e8357be
user:      riastradh <riastradh%NetBSD.org@localhost>
date:      Mon Nov 30 00:21:35 2020 +0000

description:
Note that open(O_ASYNC) does not work as advertised.

This matches Linux, which also advertises the same semantics and
fails to implement it, according to:

https://man7.org/linux/man-pages/man2/fcntl.2.html

(At what point should we collectively stop advertising the semantics
that doesn't work and call the bug a feature?)

diffstat:

 lib/libc/sys/open.2 |  19 ++++++++++++++++++-
 1 files changed, 18 insertions(+), 1 deletions(-)

diffs (37 lines):

diff -r cffbe7126c3a -r 653e9e8357be lib/libc/sys/open.2
--- a/lib/libc/sys/open.2       Mon Nov 30 00:04:02 2020 +0000
+++ b/lib/libc/sys/open.2       Mon Nov 30 00:21:35 2020 +0000
@@ -1,4 +1,4 @@
-.\"    $NetBSD: open.2,v 1.62 2019/09/16 04:59:32 wiz Exp $
+.\"    $NetBSD: open.2,v 1.63 2020/11/30 00:21:35 riastradh Exp $
 .\"
 .\" Copyright (c) 1980, 1991, 1993
 .\"    The Regents of the University of California.  All rights reserved.
@@ -217,6 +217,13 @@
 signal to be sent to the process group
 when I/O is possible, e.g.,
 upon availability of data to be read.
+.Pp
+Note: This is broken in
+.Fn open ;
+it must be set explicitly with the
+.Dv F_SETFL
+command to
+.Xr fcntl 2 .
 .\"    (This block awaits a decision about the semantics of O_SEARCH)
 .\" .It Dv O_SEARCH
 .\" If opening a directory, search permission checks will not be performed on
@@ -509,3 +516,13 @@
 .Fn open
 function call appeared in
 .At v1 .
+.Sh BUGS
+.Dv O_ASYNC
+doesn't actually work as advertised with
+.Nm ;
+you must set
+.Dv O_ASYNC
+explicitly with the
+.Dv F_SETFL
+command to
+.Xr fcntl 2 .