[src/trunk]: src/lib/libossaudio ossaudio.3: More information about the histo...

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

details:   https://anonhg.NetBSD.org/src/rev/7dff9f77fef5
branches:  trunk
changeset: 940757:7dff9f77fef5
user:      nia <nia%NetBSD.org@localhost>
date:      Fri Oct 16 16:30:53 2020 +0000

description:
ossaudio.3: More information about the history and status of this API

diffstat:

 lib/libossaudio/ossaudio.3 |  56 +++++++++++++++++++++++++++++++++++++--------
 1 files changed, 46 insertions(+), 10 deletions(-)

diffs (102 lines):

diff -r 32605970d629 -r 7dff9f77fef5 lib/libossaudio/ossaudio.3
--- a/lib/libossaudio/ossaudio.3        Fri Oct 16 16:17:23 2020 +0000
+++ b/lib/libossaudio/ossaudio.3        Fri Oct 16 16:30:53 2020 +0000
@@ -1,6 +1,6 @@
-.\"    $NetBSD: ossaudio.3,v 1.20 2009/03/12 12:33:46 joerg Exp $
+.\"    $NetBSD: ossaudio.3,v 1.21 2020/10/16 16:30:53 nia Exp $
 .\"
-.\" Copyright (c) 1997 The NetBSD Foundation, Inc.
+.\" Copyright (c) 1997, 2020 The NetBSD Foundation, Inc.
 .\" All rights reserved.
 .\"
 .\" This code is derived from software contributed to The NetBSD Foundation
@@ -27,12 +27,12 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 .\" POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd February 3, 2009
+.Dd October 16, 2020
 .Dt OSSAUDIO 3
 .Os
 .Sh NAME
 .Nm ossaudio
-.Nd OSS audio emulation
+.Nd Open Sound System emulation
 .Sh LIBRARY
 .Lb libossaudio
 .Sh SYNOPSIS
@@ -40,11 +40,14 @@
 .Sh DESCRIPTION
 The
 .Nm
-library provides an emulation of the OSS (Linux) audio
-interface.
+library provides an emulation of the Open Sound System audio interface.
 .Pp
-Use the native interface for new programs and the emulation
-library only for porting programs.
+Use the native
+.Xr audio 4
+and
+.Xr mixer 4
+interfaces for new programs, and this emulation library only for
+building code written for other operating systems.
 .Ss Mixer Control Map
 The following table summarizes the mappings from native interface
 device names to OSS mixer controls.
@@ -67,20 +70,53 @@
 .It *.midi Ta SOUND_MIXER_SYNTH
 .El
 .Sh SEE ALSO
+.Xr ioctl 2 ,
 .Xr audio 4 ,
-.Xr midi 4
+.Xr midi 4 ,
+.Xr mixer 4
 .Sh HISTORY
 The
 .Nm
 library first appeared in
 .Nx 1.3 .
+.Pp
+The Open Sound System up to version 3 was originally the preferred
+API for writing audio code under Linux until ALSA became the new default
+in Linux 2.6.
+It remains the preferred API in FreeBSD and Solaris, and a large body
+of code exists supporting it.
+.Sh COMPATIBILITY
+The
+.Nm
+interface aims to be compatible with the Open Sound System version 4, as
+described in:
+.Pp
+.Rs
+.%A 4Front Technologies
+.%T OSS 4.x Programmer's Guide 
+.%U http://manuals.opensound.com/developer/
+.%D 2007
 .Sh BUGS
+.Pp
+The emulation is incomplete.
+Some obscure features are not included, but the essential ioctls used
+by the majority of software are covered.
+.Pp
 The emulation uses a #define for
 .Fn ioctl
 so some obscure programs
 can fail to compile.
 .Pp
-The emulation is incomplete.
+Linux, FreeBSD, and Solaris provide
+.Pa /dev/dsp
+and
+.Pa /dev/mixer
+devices in place of the
+.Pa /dev/audio
+and
+.Pa /dev/mixer
+devices this compatibility layer must be accessed through on NetBSD.
+However, changing this is typically trivial when porting programs.
 .Pp
 The emulation only covers
 .Fn ioctl ,