[src/trunk]: src/share/man/man4 audio.4: Remove reference to using O_NONBLOCK

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

details:   https://anonhg.NetBSD.org/src/rev/953a9f2915ce
branches:  trunk
changeset: 1008253:953a9f2915ce
user:      nia <nia%NetBSD.org@localhost>
date:      Mon Mar 16 08:50:06 2020 +0000

description:
audio.4: Remove reference to using O_NONBLOCK

It doesn't work properly, but this turns out to not be a problem in most
code (code where it is generally uses threads)...

Don't provide misleading information about using it, or programmers
might start wondering why their code doesn't work.

Noted by Yorick Hardy on current-users

diffstat:

 share/man/man4/audio.4 |  16 ++++++----------
 1 files changed, 6 insertions(+), 10 deletions(-)

diffs (41 lines):

diff -r 196d257745ef -r 953a9f2915ce share/man/man4/audio.4
--- a/share/man/man4/audio.4    Mon Mar 16 08:48:05 2020 +0000
+++ b/share/man/man4/audio.4    Mon Mar 16 08:50:06 2020 +0000
@@ -1,4 +1,4 @@
-.\"    $NetBSD: audio.4,v 1.95 2019/12/08 10:57:17 wiz Exp $
+.\"    $NetBSD: audio.4,v 1.96 2020/03/16 08:50:06 nia Exp $
 .\"
 .\" Copyright (c) 1996 The NetBSD Foundation, Inc.
 .\" All rights reserved.
@@ -27,7 +27,7 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 .\" POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd November 12, 2019
+.Dd March 16, 2020
 .Dt AUDIO 4
 .Os
 .Sh NAME
@@ -157,14 +157,6 @@
 .Dv AUDIO_ENCODINGFLAG_EMULATED
 are able to
 .Xr mmap 2 .
-.Pp
-The audio device, like most devices, can be used in
-.Xr select 2 ,
-can be set in non-blocking mode and can be set (with a
-.Dv FIOASYNC
-ioctl) to send a
-.Dv SIGIO
-when I/O is possible.
 The mixer device can be set to generate a
 .Dv SIGIO
 whenever a mixer value is changed.
@@ -825,3 +817,7 @@
 If the device is used in
 .Xr mmap 2
 it is currently always mapped for writing (playing) due to VM system weirdness.
+.Sh CAVEATS
+The audio device cannot be reliably used with O_NONBLOCK or event notification
+mechanisms. Users are generally expected to only read and write a limited number
+of samples at a time, limiting the time spent in the system call.