9776 mandoc(1) does not support an ERRORS section for 7I man pages

9778 Convert agpgart_io(7I) to mandoc
9779 Convert audio(7I) to mandoc
9780 Convert cdio(7I) to mandoc
9777 Convert dsp(7I) to mandoc
Reviewed by: Gergő Mihály Doma <domag02@gmail.com>
Approved by: Richard Lowe <richlowe@richlowe.net>

5 files changed, 2420 insertions, 2751 deletions

diff --git a/usr/src/cmd/mandoc/mdoc_validate.c b/usr/src/cmd/mandoc/mdoc_validate.c
index b36d3c0a92..52545e3c46 100644
--- a/usr/src/cmd/mandoc/mdoc_validate.c
+++ b/usr/src/cmd/mandoc/mdoc_validate.c
@@ -3,6 +3,7 @@
  * Copyright (c) 2008-2012 Kristaps Dzonsons <kristaps@bsd.lv>
  * Copyright (c) 2010-2018 Ingo Schwarze <schwarze@openbsd.org>
  * Copyright (c) 2010 Joerg Sonnenberger <joerg@netbsd.org>
+ * Copyright 2018, Joyent, Inc.
  *
  * Permission to use, copy, modify, and distribute this software for any
  * purpose with or without fee is hereby granted, provided that the above
@@ -2427,7 +2428,9 @@ post_sh_head(POST_ARGS)
 	case SEC_ERRORS:
 		if (*mdoc->meta.msec == '4')
 			break;
-		goodsec = "2, 3, 4, 9";
+		if (*mdoc->meta.msec == '7' && *(mdoc->meta.msec + 1) == 'I')
+			break;
+		goodsec = "2, 3, 4, 7I, 9";
 		/* FALLTHROUGH */
 	case SEC_RETURN_VALUES:
 	case SEC_LIBRARY:
diff --git a/usr/src/man/man7i/agpgart_io.7i b/usr/src/man/man7i/agpgart_io.7i
index e0470bb2f0..3f98510498 100644
--- a/usr/src/man/man7i/agpgart_io.7i
+++ b/usr/src/man/man7i/agpgart_io.7i
@@ -1,753 +1,527 @@
-'\" te
 .\" Copyright (c) 2008, Sun Microsystems, Inc.  All Rights Reserved
-.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
-.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
-.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
-.TH AGPGART_IO 7I "Sep 10, 2013"
-.SH NAME
-agpgart_io \- Solaris agpgart driver I/O control operations
-.SH SYNOPSIS
-.LP
-.nf
-#include <sys/agpgart.h>
-.fi
-
-.SH DESCRIPTION
-.sp
-.LP
+.\" Copyright 2018, Joyent, Inc.
+.\" The contents of this file are subject to the terms of the
+.\" Common Development and Distribution License (the "License").
+.\" You may not use this file except in compliance with the License.
+.\"
+.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
+.\" or http://www.opensolaris.org/os/licensing.
+.\" See the License for the specific language governing permissions
+.\" and limitations under the License.
+.\"
+.\" When distributing Covered Code, include this CDDL HEADER in each
+.\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
+.\" If applicable, add the following below this CDDL HEADER, with the
+.\" fields enclosed by brackets "[]" replaced with your own identifying
+.\" information: Portions Copyright [yyyy] [name of copyright owner]
+.Dd July 8, 2018
+.Dt AGPGART_IO 7I
+.Os
+.Sh NAME
+.Nm agpgart_io
+.Nd Solaris agpgart driver I/O control operations
+.Sh SYNOPSIS
+.In sys/agpgart.h
+.Sh DESCRIPTION
 The Accelerated Graphics Port (AGP) is a PCI bus technology enhancement that
-improves 3D graphics performance by using low-cost system memory. AGP chipsets
+improves 3D graphics performance by using low-cost system memory.
+AGP chipsets
 use the Graphics Address Remapping Table (GART) to map discontiguous system
 memory into a contiguous PCI memory range (known as the AGP Aperture), enabling
 the graphics card to utilize the mapped aperture range as video memory.
-.sp
-.LP
-The \fBagpgart\fR driver creates a pseudo device node at \fB/dev/agpgart\fR and
-provides a set of ioctls for managing  allocation/deallocation of system
+.Pp
+The
+.Sy agpgart
+driver creates a pseudo device node at
+.Pa /dev/agpgart
+and provides a set of ioctls for managing allocation/deallocation of system
 memory, setting mappings between system memory and aperture range, and setting
-up AGP devices. The \fBagpgart\fR driver manages both pseudo and real device
-nodes, but to initiate AGP-related operations you operate only on the
-\fB/dev/agpgart\fR pseudo device node. To do this, open \fB/dev/agpgart\fR. The
-macro defined for the pseudo device node name is:
-.sp
-.in +2
-.nf
+up AGP devices.
+The
+.Sy agpgart
+driver manages both pseudo and real device nodes, but to initiate AGP-related
+operations you operate only on the
+.Pa /dev/agpgart
+pseudo device node.
+To do this, open
+.Pa /dev/agpgart .
+The macro defined for the pseudo device node name is:
+.Bd -literal -offset 2n
 #define  AGP_DEVICE      "/dev/agpgart"
-.fi
-.in -2
-
-.sp
-.LP
-The \fBagpgart_io\fR driver implementation is AGP architecture-dependent and
-cannot be made generic. Currently, the \fBagpgart_io\fR driver only supports
-specific AGP  systems. To determine if a system is supported, run an
-\fBopen\fR(2) system  call on the AGP_DEVICE node. (Note that  \fBopen\fR(2)
-fails if a system is not supported). After the AGP_DEVICE is opened, you can
-use \fBkstat\fR(1M) to  read the system architecture  type.
-.sp
-.LP
-In addition to AGP system support, the \fBagpgart\fR ioctls can also be used on
-Intel integrated graphics devices (IGD). IGD devices usually have no dedicated
-video memory and must  use system memory as video memory. IGD devices contain
-translation tables (referred to as \fBGTT\fR tables) that are similar to the
-GART translation table for address mapping purposes.
-.sp
-.LP
-Processes must open the \fBagpgart_io\fR driver utilizing a GRAPHICS_ACCESS
-privilege. Then all the ioctls  can be called  by this processes with the saved
-file descriptor. With the exception of AGPIOC_INFO, the AGPIOC_ACQUIRE ioctl
-must be called before any other ioctl. Once a process has acquired GART, it
+.Ed
+.Pp
+The
+.Nm
+driver implementation is AGP architecture-dependent and cannot be made generic.
+Currently, the
+.Nm
+driver only supports specific AGP systems.
+To determine if a system is supported, run an
+.Xr open 2
+system call on the
+.Dv AGP_DEVICE
+node.
+(Note that
+.Xr open 2
+fails if a system is not supported).
+After the
+.Dv AGP_DEVICE
+is opened, you can use
+.Xr kstat 1M
+to read the system architecture type.
+.Pp
+In addition to AGP system support, the
+.Sy agpgart
+ioctls can also be used on Intel integrated graphics devices (IGD).
+IGD devices usually have no dedicated video memory and must use system memory as video memory.
+IGD devices contain
+translation tables (referred to as
+.Sy GTT
+tables) that are similar to the GART translation table for address mapping purposes.
+.Pp
+Processes must open the
+.Nm
+driver utilizing a
+.Brq Sy GRAPHICS_ACCESS
+privilege.
+Then all the ioctls can be called by this processes with the saved file descriptor.
+With the exception of
+.Dv AGPIOC_INFO ,
+the
+.Dv AGPIOC_ACQUIRE
+ioctl must be called before any other ioctl.
+Once a process has acquired GART, it
 cannot be acquired by another process until the former process calls
-AGPIOC_RELEASE.
-.sp
-.LP
-If the AGP_DEVICE fails to open, it may be due to one of the following reasons:
-.sp
-.ne 2
-.na
-\fBEAGAIN\fR
-.ad
-.sp .6
-.RS 4n
+.Dv AGPIOC_RELEASE .
+.Pp
+If the
+.Dv AGP_DEVICE
+fails to open, it may be due to one of the following reasons:
+.Bl -tag -width "EAGAIN" -offset 2n -compact
+.It Er EAGAIN
 GART table allocation failed.
-.RE
-
-.sp
-.ne 2
-.na
-\fBEIO\fR
-.ad
-.sp .6
-.RS 4n
+.It Er EIO
 Internal hardware initialization failed.
-.RE
-
-.sp
-.ne 2
-.na
-\fBENXIO\fR
-.ad
-.sp .6
-.RS 4n
-Getting device soft state error. (This is unlikely to happen.)
-.RE
-
-.sp
-.ne 2
-.na
-\fB EPERM\fR
-.ad
-.sp .6
-.RS 4n
+.It Er ENXIO
+Getting device soft state error.
+(This is unlikely to happen.)
+.It Er EPERM
 Without enough privilege.
-.RE
-
-.SH IOCTLS
-.sp
-.LP
-With the exception of GPIOC_INFO, all ioctls shown in this section are
-protected by GRAPHICS_ACCESS privilege. (Only processes with GRAPHICS_ACCESS
+.El
+.Sh IOCTLS
+With the exception of
+.Dv GPIOC_INFO ,
+all ioctls shown in this section are
+protected by
+.Brq Sy GRAPHICS_ACCESS
+privilege.
+(Only processes with
+.Brq Sy GRAPHICS_ACCESS
 privilege in its effective set can access the privileged ioctls).
-.sp
-.LP
-Common ioctl error codes are shown below. (Additional error codes may be
+.Pp
+Common ioctl error codes are shown below.
+(Additional error codes may be
 displayed by individual ioctls.)
-.sp
-.ne 2
-.na
-\fBENXIO\fR
-.ad
-.sp .6
-.RS 4n
+.Bl -tag -width Er
+.It Er ENXIO
 Ioctl command not supported or getting device soft state error.
-.RE
-
-.sp
-.ne 2
-.na
-\fBEPERM\fR
-.ad
-.sp .6
-.RS 4n
+.It Er EPERM
 Process not privileged.
-.RE
-
-.sp
-.ne 2
-.na
-\fB\fBAGPIOC_INFO\fR\fR
-.ad
-.sp .6
-.RS 4n
-Get system wide AGP or IGD hardware information. This command can be called by
-any process from user or kernel context.
-.sp
-.in +2
-.nf
-The argument is a pointer to agp_info_t structure.
-
- typedef struct  _agp_info {
+.El
+.Bl -tag -width " "
+.It Dv AGPIOC_INFO
+.Pp
+Get system wide AGP or IGD hardware information.
+This command can be called by any process from user or kernel context.
+The argument is a pointer to
+.Vt agp_info_t
+structure.
+.Bd -literal -offset 2n
+typedef struct  _agp_info {
        agp_version_t agpi_version; /* OUT: AGP version supported */
        uint32_t agpi_devid;    /* OUT: bridge vendor + device */
        uint32_t agpi_mode;     /* OUT: mode of bridge */
        ulong_t  agpi_aperbase; /* OUT: base of aperture */
        size_t   agpi_apersize; /* OUT: aperture size in MB */
-       uint32_t agpi_pgtotal;  /* OUT: max aperture pages avail. */
+       uint32_t agpi_pgtotal;  /* OUT: max aperture pages avail.  */
        uint32_t agpi_pgsystem; /* OUT: same as pg_total */
-       uint32_t agpi_pgused; /* OUT: no. of currently used pages */
- } agp_info_t;
-
-agpi_version  The version of AGP protocol the bridge device is
-              compatible with, for example, major 3 and minor 0
-              means AGP version 3.0.
-
-              typedef struct _agp_version {
-                      uint16_t   agpv_major;
-                      uint16_t   agpv_minor;
-              } agp_version_t;
-
-agpi_devid    AGP bridge vendor and device ID.
-agpi_mode     Current AGP mode, read from AGP status register of
-              target device. The main bits are defined as below.
-              /* AGP status register bits definition */
-
-                #define AGPSTAT_RQ_MASK         0xff000000
-                #define AGPSTAT_SBA             (0x1 << 9)
-                #define AGPSTAT_OVER4G          (0x1 << 5)
-                #define AGPSTAT_FW              (0x1 << 4)
-                #define AGPSTAT_RATE_MASK       0x7
-                /* AGP 3.0 only bits */
-                #define AGPSTAT_ARQSZ_MASK      (0x7 << 13)
-                #define AGPSTAT_CAL_MASK        (0x7 << 10)
-                #define AGPSTAT_GART64B         (0x1 << 7)
-                #define AGPSTAT_MODE3           (0x1 << 3)
-                /* rate for 2.0 mode */
-                #define AGP2_RATE_1X                    0x1
-                #define AGP2_RATE_2X                    0x2
-                #define AGP2_RATE_4X                    0x4
-                /* rate for 3.0 mode */
-                #define AGP3_RATE_4X                    0x1
-                #define AGP3_RATE_8X                    0x2
-
-agpi_aperbase   The base address of aperture in PCI memory space.
-agpi_apersize   The size of the aperture in megabytes.
-agpi_pgtotal    Represents the maximum memory
-                pages the system can allocate
-                according to aperture size and
-                system memory size (which may differ
-                from the maximum locked memory a process
-                can have. The latter  is subject
-                to the memory resource limit imposed
-                by the  resource_controls(5) for each
-                project(4)):
-
-                  project.max-device-locked-memory
-
-                This value can be modified through system
-                utilities like prctl(1).
-
-agpi_pgsystem  Same as pg_total.
-agpi_pgused    System pages already allocated by the driver.
-
+       uint32_t agpi_pgused; /* OUT: no.  of currently used pages */
+} agp_info_t;
+.Ed
+.Bl -tag -width "agpi_pgsystem" -offset 2n
+.It Fa agpi_version
+The version of AGP protocol the bridge device is
+compatible with, for example, major 3 and minor 0 means AGP version 3.0.
+.Bd -literal
+typedef struct _agp_version {
+        uint16_t   agpv_major;
+        uint16_t   agpv_minor;
+} agp_version_t;
+.Ed
+.It Fa agpi_devid
+AGP bridge vendor and device ID.
+.It Fa agpi_mode
+Current AGP mode, read from AGP status register of target device.
+The main bits are defined as below.
+.Bd -literal
+/* AGP status register bits definition */
+
+#define AGPSTAT_RQ_MASK         0xff000000
+#define AGPSTAT_SBA             (0x1 << 9)
+#define AGPSTAT_OVER4G          (0x1 << 5)
+#define AGPSTAT_FW              (0x1 << 4)
+#define AGPSTAT_RATE_MASK       0x7
+/* AGP 3.0 only bits */
+#define AGPSTAT_ARQSZ_MASK      (0x7 << 13)
+#define AGPSTAT_CAL_MASK        (0x7 << 10)
+#define AGPSTAT_GART64B         (0x1 << 7)
+#define AGPSTAT_MODE3           (0x1 << 3)
+/* rate for 2.0 mode */
+#define AGP2_RATE_1X                    0x1
+#define AGP2_RATE_2X                    0x2
+#define AGP2_RATE_4X                    0x4
+/* rate for 3.0 mode */
+#define AGP3_RATE_4X                    0x1
+#define AGP3_RATE_8X                    0x2
+.Ed
+.It Fa agpi_aperbase
+The base address of aperture in PCI memory space.
+.It Fa agpi_apersize
+The size of the aperture in megabytes.
+.It Fa agpi_pgtotal
+Represents the maximum memory pages the system can allocate
+according to aperture size and system memory size (which may differ
+from the maximum locked memory a process can have.
+The latter is subject to the memory resource limit imposed
+by the
+.Xr resource_controls 5
+for each
+.Xr project 4 Ns ):
+.Bd -literal -offset 2n
+project.max-device-locked-memory
+.Ed
+.Pp
+This value can be modified through system utilities like
+.Xr prctl 1 .
+.It Fa agpi_pgsystem
+Same as pg_total.
+.It Fa agpi_pgused
+System pages already allocated by the driver.
+.El
+.Pp
 Return Values:
-
-           EFAULT  Argument copy out error
-           EINVAL  Command invalid
-           0       Success
-.fi
-.in -2
-
-.RE
-
-.sp
-.ne 2
-.na
-\fB\fBAGPIOC_ACQUIRE\fR\fR
-.ad
-.sp .6
-.RS 4n
-Acquire control of GART. With the exception of AGPIOC_INFO, a process must
-acquire GART before can it call other agpgart ioctl commands. Additionally,
-only processes with GRAPHICS_ACCESS privilege may access this ioctl. In the
-current agpgart implementation, GART access is exclusive, meaning that only one
-process can perform GART operations at a time. To release control over GART,
-call AGPIOC_RELEASE. This command can be called from user or kernel context.
-.sp
-The argument should be NULL.
-.sp
+.Bl -tag -width "EFAULT" -offset indent -compact
+.It Er EFAULT
+Argument copy out error
+.It Er EINVAL
+Command invalid
+.It 0
+Success
+.El
+.It Dv AGPIOC_ACQUIRE
+.Pp
+Acquire control of GART.
+With the exception of
+.Dv AGPIOC_INFO ,
+a process must acquire GART before can it call other agpgart ioctl commands.
+Additionally, only processes with
+.Brq Sy GRAPHICS_ACCESS
+privilege may access this ioctl.
+In the current agpgart implementation, GART access is exclusive, meaning that only one
+process can perform GART operations at a time.
+To release control over GART, call
+.Dv AGPIOC_RELEASE .
+This command can be called from user or kernel context.
+.Pp
+The argument should be
+.Sy NULL .
+.Pp
 Return values:
-.sp
-.ne 2
-.na
-\fBEBUSY\fR
-.ad
-.RS 9n
+.Bl -tag -width "EBUSY" -offset indent -compact
+.It Er EBUSY
 GART has been acquired
-.RE
-
-.sp
-.ne 2
-.na
-\fB0\fR
-.ad
-.RS 9n
+.It Er 0
 Success.
-.RE
-
-.RE
-
-.sp
-.ne 2
-.na
-\fB\fBAGPIOC_RELEASE\fR\fR
-.ad
-.sp .6
-.RS 4n
-Release GART control. If a process releases GART control, it cannot perform
-additional GART operations until GART is reacquired. Note that this command
-does not free allocated memory or clear GART entries. (All clear jobs are done
-by direct calls or by closing the device). When a process exits without making
-this ioctl, the final \fBclose\fR(2) performs this automatically. This command
-can be called from user or kernel context.
-.sp
-The argument should be NULL.
-.sp
+.El
+.It Dv AGPIOC_RELEASE
+.Pp
+Release GART control.
+If a process releases GART control, it cannot perform
+additional GART operations until GART is reacquired.
+Note that this command does not free allocated memory or clear GART entries.
+(All clear jobs are done
+by direct calls or by closing the device).
+When a process exits without making
+this ioctl, the final
+.Xr close 2
+performs this automatically.
+This command can be called from user or kernel context.
+.Pp
+The argument should be
+.Sy NULL .
+.Pp
 Return values:
-.sp
-.ne 2
-.na
-\fBEPERM\fR
-.ad
-.RS 9n
+.Bl -tag -width "EPERM" -offset indent -compact
+.It Er EPERM
 Not owner of GART.
-.RE
-
-.sp
-.ne 2
-.na
-\fB0\fR
-.ad
-.RS 9n
+.It 0
 Success.
-.RE
-
-.RE
-
-.sp
-.ne 2
-.na
-\fB\fBAGPIOC_SETUP\fR\fR
-.ad
-.sp .6
-.RS 4n
-Setup AGPCMD register. An AGPCMD register resides in both  the  AGP master and
-target devices. The AGPCMD register controls the working mode of the AGP master
-and target devices. Each device must be  configured  using the same mode. This
-command can be called from user or kernel context.
-.sp
-.in +2
-.nf
-The argument is a pointer to agp_setup_t structure:
-
-     typedef struct _agp_setup {
-           uint32_t agps_mode; /* IN: value to be set for AGPCMD */
-     } agp_setup_t;
-
-agps_mode  Specifying the mode to be set. Each bit of the value may have
-           a specific meaning, please refer to AGP 2.0/3.0 specification
-           or hardware datasheets for details.
-
-               /* AGP command register bits definition */
-               #define     AGPCMD_RQ_MASK          0xff000000
-               #define     AGPCMD_SBAEN            (0x1 << 9)
-               #define     AGPCMD_AGPEN            (0x1 << 8)
-               #define     AGPCMD_OVER4GEN         (0x1 << 5)
-               #define     AGPCMD_FWEN             (0x1 << 4)
-               #define     AGPCMD_RATE_MASK        0x7
-               /* AGP 3.0 only bits */
-               #define     AGP3_CMD_ARQSZ_MASK     (0x7 << 13)
-               #define     AGP3_CMD_CAL_MASK       (0x7 << 10)
-               #define     AGP3_CMD_GART64BEN      (0x1 << 7)
-.fi
-.in -2
-
+.El
+.It Dv AGPIOC_SETUP
+.Pp
+Setup AGPCMD register.
+An AGPCMD register resides in both the AGP master and target devices.
+The AGPCMD register controls the working mode of the AGP master and target devices.
+Each device must be configured using the same mode.
+This command can be called from user or kernel context.
+.Pp
+The argument is a pointer to
+.Vt agp_setup_t
+structure:
+.Bd -literal -offset 2n
+typedef struct _agp_setup {
+       uint32_t agps_mode; /* IN: value to be set for AGPCMD */
+} agp_setup_t;
+.Ed
+.Bl -tag -width "agps_mode" -offset 2n
+.It Fa agps_mode
+Specifying the mode to be set.
+Each bit of the value may have a specific meaning, please refer to AGP 2.0/3.0
+specification or hardware datasheets for details.
+.Bd -literal
+/* AGP command register bits definition */
+#define     AGPCMD_RQ_MASK          0xff000000
+#define     AGPCMD_SBAEN            (0x1 << 9)
+#define     AGPCMD_AGPEN            (0x1 << 8)
+#define     AGPCMD_OVER4GEN         (0x1 << 5)
+#define     AGPCMD_FWEN             (0x1 << 4)
+#define     AGPCMD_RATE_MASK        0x7
+/* AGP 3.0 only bits */
+#define     AGP3_CMD_ARQSZ_MASK     (0x7 << 13)
+#define     AGP3_CMD_CAL_MASK       (0x7 << 10)
+#define     AGP3_CMD_GART64BEN      (0x1 << 7)
+.Ed
+.El
+.Pp
 The final values set to the AGPCMD register of the master/target devices are
 decided by the agps_mode value and AGPSTAT of the master and target devices.
-.sp
+.Pp
 Return Values:
-.sp
-.ne 2
-.na
-\fBEPERM\fR
-.ad
-.RS 10n
+.Bl -tag -width "EFAULT" -offset indent -compact
+.It Er EPERM
 Not owner of GART.
-.RE
-
-.sp
-.ne 2
-.na
-\fBEFAULT\fR
-.ad
-.RS 10n
+.It Er EFAULT
 Argument copy in error.
-.RE
-
-.sp
-.ne 2
-.na
-\fBEINVAL\fR
-.ad
-.RS 10n
+.It Er EINVAL
 Command invalid for non-AGP system.
-.RE
-
-.sp
-.ne 2
-.na
-\fBEIO\fR
-.ad
-.RS 10n
+.It Er EIO
 Hardware setup error.
-.RE
-
-.sp
-.ne 2
-.na
-\fB0\fR
-.ad
-.RS 10n
+.It 0
 Success.
-.RE
-
-.RE
-
-.sp
-.ne 2
-.na
-\fB\fBAGPIOC_ALLOCATE\fR\fR
-.ad
-.sp .6
-.RS 4n
-Allocate system memory for graphics device. This command returns a unique ID
+.El
+.It Dv AGPIOC_ALLOCATE
+.Pp
+Allocate system memory for graphics device.
+This command returns a unique ID
 which can be used in subsequent operations to represent the allocated memory.
-The memory is made up of discontiguous physical pages. In rare cases, special
-memory types may be required. The allocated memory must be bound to the GART
-table before it can be used by graphics device. Graphics applications can also
-\fBmmap\fR(2) the memory to userland for data storing. Memory should be freed
-when it is no longer used by calling AGPIOC_DEALLOCATE or simply by closing the
-device. This command can be called from user or kernel context.
-.sp
-.in +2
-.nf
-The argument is a pointer to agp_allocate_t structure.
-
-     typedef struct _agp_allocate {
-           int32_t  agpa_key;     /* OUT:ID of allocated memory */
-           uint32_t agpa_pgcount;/* IN: no. of pages to be allocated */
-           uint32_t agpa_type;/* IN: type of memory to be allocated */
-           uint32_t agpa_physical; /* OUT: reserved */
-     } agp_allocate_t;
-.fi
-.in -2
-
-.sp
-.ne 2
-.na
-\fBagpa_key\fR
-.ad
-.RS 21n
+The memory is made up of discontiguous physical pages.
+In rare cases, special memory types may be required.
+The allocated memory must be bound to the GART
+table before it can be used by graphics device.
+Graphics applications can also
+.Xr mmap 2
+the memory to userland for data storing.
+Memory should be freed when it is no longer used by calling
+.Dv AGPIOC_DEALLOCATE
+or simply by closing the device.
+This command can be called from user or kernel context.
+.Pp
+The argument is a pointer to
+.Vt agp_allocate_t
+structure.
+.Bd -literal -offset 2n
+typedef struct _agp_allocate {
+      int32_t  agpa_key;     /* OUT:ID of allocated memory */
+      uint32_t agpa_pgcount; /* IN: no.  of pages to be allocated */
+      uint32_t agpa_type;    /* IN: type of memory to be allocated */
+      uint32_t agpa_physical; /* OUT: reserved */
+} agp_allocate_t;
+.Ed
+.Bl -tag -width "agpa_physical" -offset 2n
+.It Fa agpa_key
 Unique ID of the allocated memory.
-.RE
-
-.sp
-.ne 2
-.na
-\fBagpa_pgcount\fR
-.ad
-.RS 21n
-Number of pages to be allocated. The driver currently supports only 4K pages.
-The value cannot exceed the agpi_pgtotal value returned by AGPIOC_INFO ioct and
-is subject to the limit of project.max-device-locked-memory. If the memory
-needed is larger than the resource limit but not larger than agpi_pgtotal, use
-\fBprctl\fR(1) or other system utilities to change the default value of memory
+.It Fa agpa_pgcount
+Number of pages to be allocated.
+The driver currently supports only 4K pages.
+The value cannot exceed the
+.Fa agpi_pgtotal
+value returned by the
+.Dv AGPIOC_INFO
+ioctl and is subject to the limit of
+.Sy project.max-device-locked-memory .
+If the memory needed is larger than the resource limit but not larger than
+.Fa agpi_pgtotal ,
+use
+.Xr prctl 1
+or other system utilities to change the default value of memory
 resource limit beforehand.
-.RE
-
-.sp
-.ne 2
-.na
-\fBagpa_type\fR
-.ad
-.RS 21n
-Type of memory to be allocated. The valid value of agpa_type should be
-AGP_NORMAL. It is defined as:
-.sp
-.in +2
-.nf
-         #define AGP_NORMAL      0
-.fi
-.in -2
-
-Above, AGP_NORMAL represents the discontiguous non-cachable physical memory
+.It Fa agpa_type
+Type of memory to be allocated.
+The valid value of
+.Fa agpa_type
+should be
+.Dv AGP_NORMAL .
+It is defined as:
+.Bd -literal -offset indent
+#define AGP_NORMAL      0
+.Ed
+.Pp
+Above,
+.Dv AGP_NORMAL
+represents the discontiguous non-cachable physical memory
 which doesn't consume kernel virtual space but can be mapped to user space by
-\fBmmap\fR(2). This command may support more type values in the future.
-.RE
-
-.sp
-.ne 2
-.na
-\fBagpa_physical\fR
-.ad
-.RS 21n
-Reserved for special uses. In normal operations, the value is undefined.
-.sp
+.Xr mmap 2 .
+This command may support more type values in the future.
+.It Fa agpa_physical
+Reserved for special uses.
+In normal operations, the value is undefined.
+.El
+.Pp
 Return Values:
-.sp
-.ne 2
-.na
-\fBEPERM\fR
-.ad
-.RS 10n
+.Bl -tag -width EINVAL -offset indent -compact
+.It Er EPERM
 Not owner of GART.
-.RE
-
-.sp
-.ne 2
-.na
-\fBEINVAL\fR
-.ad
-.RS 10n
+.It Er EINVAL
 Argument not valid.
-.RE
-
-.sp
-.ne 2
-.na
-\fBEFAULT\fR
-.ad
-.RS 10n
+.It Er EFAULT
 Argument copy in/out error.
-.RE
-
-.sp
-.ne 2
-.na
-\fBENOMEM\fR
-.ad
-.RS 10n
+.It Er ENOMEM
 Memory allocation error.
-.RE
-
-.sp
-.ne 2
-.na
-\fB0\fR
-.ad
-.RS 10n
+.It 0
 Success.
-.RE
-
-.RE
-
-.sp
-.ne 2
-.na
-\fBAGPIOC_DEALLOCATE\fR
-.ad
-.RS 21n
-Deallocate the memory identified by a key assigned in a previous allocation. If
-the memory isn't unbound from GART, this command unbinds it automatically. The
-memory should no longer be used and those still in mapping to userland cannot
-be deallocated. Always call AGPIOC_DEALLOCATE explicitly (instead of
-deallocating  implicitly by closing the device), as the system won't carry out
-the job until the last reference to the device file is dropped. This command
-from user or kernel context.
-.sp
-The input argument is a key of type int32_t, no output argument.
-.sp
+.El
+.It Dv AGPIOC_DEALLOCATE
+.Pp
+Deallocate the memory identified by a key assigned in a previous allocation.
+If the memory isn't unbound from GART, this command unbinds it automatically.
+The memory should no longer be used and those still in mapping to userland cannot
+be deallocated.
+Always call
+.Dv AGPIOC_DEALLOCATE
+explicitly (instead of
+deallocating implicitly by closing the device), as the system won't carry out
+the job until the last reference to the device file is dropped.
+This command can be called from user or kernel context.
+.Pp
+The input argument is a key of type
+.Vt int32_t ,
+no output argument.
+.Pp
 Return Values:
-.sp
-.ne 2
-.na
-\fBEPERM\fR
-.ad
-.RS 10n
+.Bl -tag -width EINVAL -offset indent -compact
+.It Er EPERM
 Not owner of GART.
-.RE
-
-.sp
-.ne 2
-.na
-\fBEINVAL\fR
-.ad
-.RS 10n
+.It Er EINVAL
 Key not valid or memory in use.
-.RE
-
-.sp
-.ne 2
-.na
-\fB0\fR
-.ad
-.RS 10n
+.It 0
 Success.
-.RE
-
-.RE
-
-.sp
-.ne 2
-.na
-\fBAGPIOC_BIND\fR
-.ad
-.RS 21n
-Bind allocated memory.  This  command binds the allocated   memory  identified
-by a key to  a specific offset of the GART table, which enables GART   to
-translate the aperture  range at the offset to system memory. Each GART entry
-represents one physical page. If the GART range is previously bound to other
-system memory, it returns an error. Once the memory is bound, it cannot be
-bound to other offsets unless it is unbound. To unbind the memory, call
-AGPIOC_UNBIND or deallocate the memory. This command can be called from user or
-kernel context.
-.sp
-.in +2
-.nf
-The argument is a pointer to agp_bind_t structure:
-
-     typedef struct _agp_bind {
-           int32_t  agpb_key;      /* IN: ID of memory to be bound */
-           uint32_t agpb_pgstart;  /* IN: offset in aperture */
-     } agp_bind_t;
-.fi
-.in -2
-
-.sp
-.ne 2
-.na
-\fBagpb_key\fR
-.ad
-.RS 20n
+.El
+.It Dv AGPIOC_BIND
+.Pp
+Bind allocated memory.
+This command binds the allocated memory identified
+by a key to a specific offset of the GART table, which enables GART to
+translate the aperture range at the offset to system memory.
+Each GART entry represents one physical page.
+If the GART range is previously bound to other
+system memory, it returns an error.
+Once the memory is bound, it cannot be
+bound to other offsets unless it is unbound.
+To unbind the memory, call
+.Dv AGPIOC_UNBIND
+or deallocate the memory.
+This command can be called from user or kernel context.
+.Pp
+The argument is a pointer to
+.Vt agp_bind_t
+structure:
+.Bd -literal -offset 2n
+typedef struct _agp_bind {
+      int32_t  agpb_key;      /* IN: ID of memory to be bound */
+      uint32_t agpb_pgstart;  /* IN: offset in aperture */
+} agp_bind_t;
+.Ed
+.Bl -tag -width "agpb_pgstart" -offset 2n
+.It Fa agpb_key
 The unique ID of the memory to be bound, which is previously allocated by
 calling AGPIOC_ALLOCATE.
-.RE
-
-.sp
-.ne 2
-.na
-\fBagpb_pgstart\fR
-.ad
-.RS 20n
+.It Fa agpb_pgstart
 The starting page offset to be bound in aperture space.
-.RE
-
+.El
+.Pp
 Return Values:
-.sp
-.ne 2
-.na
-\fBEPERM\fR
-.ad
-.RS 20n
+.Bl -tag -width "EINVAL" -offset indent -compact
+.It Er EPERM
 Not owner of GART.
-.RE
-
-.sp
-.ne 2
-.na
-\fBEFAULT\fR
-.ad
-.RS 20n
+.It Er EFAULT
 Argument copy in error.
-.RE
-
-.sp
-.ne 2
-.na
-\fBEINVAL\fR
-.ad
-.RS 20n
+.It Er EINVAL
 Argument not valid.
-.RE
-
-.sp
-.ne 2
-.na
-\fBEIO\fR
-.ad
-.RS 20n
+.It Er EIO
 Binding to the GTT table of IGD devices failed.
-.RE
-
-.sp
-.ne 2
-.na
-\fB0\fR
-.ad
-.RS 20n
+.It 0
 Success.
-.RE
-
-.RE
-
-.sp
-.ne 2
-.na
-\fBAGPIOC_UNBIND\fR
-.ad
-.RS 21n
-Unbind memory identified by a key from the GART. This command clears the
-corresponding entries in the GART table. Only the memory not in mapping to
-userland is allowed to be unbound.
-.sp
+.El
+.It Dv AGPIOC_UNBIND
+.Pp
+Unbind memory identified by a key from the GART.
+This command clears the corresponding entries in the GART table.
+Only the memory not in mapping to userland is allowed to be unbound.
 This ioctl command can be called from user or kernel context.
-.sp
-.in +2
-.nf
-The argument is a pointer to agp_unbind_t structure.
-
-     typedef struct _agp_unbind {
-           int32_t  agpu_key; /* IN: key of memory to be unbound*/
-           uint32_t agpu_pri; /* Not used: for compat. with Xorg */
-     } agp_unbind_t;
-.fi
-.in -2
-
-.sp
-.ne 2
-.na
-\fBagpu_key\fR
-.ad
-.RS 20n
+.Pp
+The argument is a pointer to
+.Vt agp_unbind_t
+structure.
+.Bd -literal -offset 2n
+typedef struct _agp_unbind {
+      int32_t  agpu_key; /* IN: key of memory to be unbound*/
+      uint32_t agpu_pri; /* Not used: for compat. with Xorg */
+} agp_unbind_t;
+.Ed
+.Bl -tag -width "agpu_key" -offset 2n
+.It Fa agpu_key
 Unique ID of the memory to be unbound which was previously bound by calling
-AGPIOC_BIND.
-.RE
-
-.sp
-.ne 2
-.na
-\fBagpu_pri\fR
-.ad
-.RS 20n
+.Dv AGPIOC_BIND .
+.It Fa agpu_pri
 Reserved for compatibility with X.org/XFree86, not used.
-.RE
-
+.El
+.Pp
 Return Values:
-.sp
-.ne 2
-.na
-\fBEPERM\fR
-.ad
-.RS 20n
+.Bl -tag -width EINVAL -offset indent -compact
+.It Er EPERM
 Not owner of GART.
-.RE
-
-.sp
-.ne 2
-.na
-\fBEFAULT\fR
-.ad
-.RS 20n
+.It Er EFAULT
 Argument copy in error.
-.RE
-
-.sp
-.ne 2
-.na
-\fBEINVAL\fR
-.ad
-.RS 20n
+.It Er EINVAL
 Argument not valid or memory in use.
-.RE
-
-.sp
-.ne 2
-.na
-\fBEIO\fR
-.ad
-.RS 20n
+.It Er EIO
 Unbinding from the GTT table of IGD devices failed.
-.RE
-
-.sp
-.ne 2
-.na
-\fB0\fR
-.ad
-.RS 20n
+.It 0
 Success
-.RE
-
-.RE
-
-.RE
-
-.SH EXAMPLE
-.sp
-.LP
+.El
+.El
+.Sh FILES
+.Bl -tag -width " "
+.It Pa /dev/agpgart
+Symbolic link to the pseudo agpgart device.
+.It Pa /platform/i86pc/kernel/drv/agpgart
+agpgart pseudo driver.
+.It Pa /platform/i86pc/kernel/drv/agpgart.conf
+Driver configuration file.
+.El
+.Sh EXAMPLES
 Below is an sample program showing how agpgart ioctls can be used:
-.sp
-.in +2
-.nf
+.Bd -literal -offset 2n
 #include <stdio.h>
 #include <stdlib.h>
 #include <unistd.h
@@ -772,7 +546,7 @@ int main(int argc, char *argv[])
         size_t maplen;
 
         if((fd = open(AGP_DEVICE, O_RDWR))== -1) {
-                printf("open AGP_DEVICE error with %d\en", errno);\e
+                printf("open AGP_DEVICE error with %d\en", errno);
                 exit(-1);
         }
         printf("device opened\en");
@@ -796,7 +570,7 @@ int main(int argc, char *argv[])
         modesetup.agps_mode = agpinfo.agpi_mode;
         ret = ioctl(fd, AGPIOC_SETUP, &modesetup);
         if(ret == -1) {
-                printf("set up AGP mode error\en", errno);
+                printf("set up AGP mode error %d\en", errno);
                 exit(-1);
         }
 
@@ -866,61 +640,19 @@ int main(int argc, char *argv[])
 
         close(fd);
 }
-.fi
-.in -2
-
-.SH FILES
-.sp
-.ne 2
-.na
-\fB\fB/dev/agpgart\fR\fR
-.ad
-.sp .6
-.RS 4n
-Symbolic link to the pseudo agpgart device.
-.RE
-
-.sp
-.ne 2
-.na
-\fB\fB/platform/i86pc/kernel/drv/agpgart\fR\fR
-.ad
-.sp .6
-.RS 4n
-agpgart pseudo driver.
-.RE
-
-.sp
-.ne 2
-.na
-\fB\fB/platform/i86pc/kernel/drv/agpgart.conf\fR\fR
-.ad
-.sp .6
-.RS 4n
-Driver configuration file.
-.RE
-
-.SH ATTRIBUTES
-.sp
-.LP
-See \fBattributes\fR(5) for descriptions of the following attributes:
-.sp
-
-.sp
-.TS
-box;
-c | c
-l | l .
-ATTRIBUTE TYPE	ATTRIBUTE VALUE
-_
-Architecture	X86
-_
-Stability level	Unstable
-.TE
-
-.SH SEE ALSO
-.sp
-.LP
-\fBprctl\fR(1), \fBkstat\fR(1M), \fBclose\fR(2), \fBioctl\fR(2), \fBopen\fR(2),
-\fBmmap\fR(2), \fBproject\fR(4), \fBprivileges\fR(5), \fBattributes\fR(5),
-\fBresource_controls\fR(5)
+.Ed
+.Sh ARCHITECTURE
+X86
+.Sh INTERFACE STABILITY
+Uncommitted
+.Sh SEE ALSO
+.Xr prctl 1 ,
+.Xr kstat 1M ,
+.Xr close 2 ,
+.Xr ioctl 2 ,
+.Xr mmap 2 ,
+.Xr open 2 ,
+.Xr project 4 ,
+.Xr attributes 5 ,
+.Xr privileges 5 ,
+.Xr resource_controls 5
diff --git a/usr/src/man/man7i/audio.7i b/usr/src/man/man7i/audio.7i
index 5a6a54ffec..fcee1683f8 100644
--- a/usr/src/man/man7i/audio.7i
+++ b/usr/src/man/man7i/audio.7i
@@ -1,423 +1,530 @@
-'\" te
 .\"  Copyright (c) 2009 Sun Microsystems, Inc. All rights reserved.
-.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.
-.\"  See the License for the specific language governing permissions and limitations under the License. When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the
-.\" fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
-.TH AUDIO 7I "May 6, 2009"
-.SH NAME
-audio \- generic audio device interface
-.SH SYNOPSIS
-.LP
-.nf
-\fB#include\fR \fB<sys/audio.h>\fR
-.fi
-
-.SH OVERVIEW
-.sp
-.LP
-An audio device is used to play and/or record a stream of audio data. Since a
+.\" Copyright 2018, Joyent, Inc.
+.\" The contents of this file are subject to the terms of the
+.\" Common Development and Distribution License (the "License").
+.\" You may not use this file except in compliance with the License.
+.\"
+.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
+.\" or http://www.opensolaris.org/os/licensing.
+.\" See the License for the specific language governing permissions
+.\" and limitations under the License.
+.\"
+.\" When distributing Covered Code, include this CDDL HEADER in each
+.\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
+.\" If applicable, add the following below this CDDL HEADER, with the
+.\" fields enclosed by brackets "[]" replaced with your own identifying
+.\" information: Portions Copyright [yyyy] [name of copyright owner]
+.Dd July 8, 2018
+.Dt AUDIO 7I
+.Os
+.Sh NAME
+.Nm audio
+.Nd generic audio device interface
+.Sh SYNOPSIS
+.In sys/audio.h
+.Sh OVERVIEW
+An audio device is used to play and/or record a stream of audio data.
+Since a
 specific audio device may not support all functionality described below, refer
 to the device-specific manual pages for a complete description of each hardware
-device. An application can use the \fBAUDIO_GETDEV\fR \fBioctl\fR(2) to
-determine the current audio hardware associated with \fB/dev/audio\fR.
-.sp
-.LP
+device.
+An application can use the
+.Dv AUDIO_GETDEV
+.Xr ioctl 2
+to determine the current audio hardware associated with
+.Pa /dev/audio .
+.Pp
 The audio framework provides a software mixing engine (audio mixer) for all
 audio devices, allowing more than one process to play or record audio at the
 same time.
-.SS "Backward Compatibility"
-.sp
-.LP
-It is no longer possible to disable the mixing function. Applications must not
+.Ss "Backward Compatibility"
+It is no longer possible to disable the mixing function.
+Applications must not
 assume that they have exclusive access to the audio device.
-.SS "Multi-Stream Codecs"
-.sp
-.LP
-The audio mixer supports multi-stream Codecs. These devices have DSP engines
-that provide sample rate conversion, hardware mixing, and other features. The
-use of such hardware features is opaque to applications.
-.SH AUDIO FORMATS
-.sp
-.LP
+.Ss "Multi-Stream Codecs"
+The audio mixer supports multi-stream Codecs.
+These devices have DSP engines
+that provide sample rate conversion, hardware mixing, and other features.
+The use of such hardware features is opaque to applications.
+.Sh AUDIO FORMATS
 Digital audio data represents a quantized approximation of an analog audio
-signal waveform. In the simplest case, these quantized numbers represent the
-amplitude of the input waveform at particular sampling intervals. To achieve
-the best approximation of an input signal, the highest possible sampling
-frequency and precision should be used. However, increased accuracy comes at a
-cost of increased data storage requirements. For instance, one minute of
-monaural audio recorded in \(*m-Law format (pronounced \fBmew-law\fR) at 8 KHz
-requires nearly 0.5 megabytes of storage, while the standard Compact Disc audio
-format (stereo 16-bit linear \fBPCM\fR data sampled at 44.1 KHz) requires
-approximately 10 megabytes per minute.
-.sp
-.LP
-Audio data may be represented in several different formats. An audio device's
-current audio data format can be determined by using the \fBAUDIO_GETINFO\fR
-\fBioctl\fR(2) described below.
-.sp
-.LP
+signal waveform.
+In the simplest case, these quantized numbers represent the
+amplitude of the input waveform at particular sampling intervals.
+To achieve the best approximation of an input signal, the highest possible sampling
+frequency and precision should be used.
+However, increased accuracy comes at a cost of increased data storage requirements.
+For instance, one minute of
+monaural audio recorded in \(*m-Law format (pronounced
+.Em mew-law )
+at 8 KHz requires nearly 0.5 megabytes of storage, while the standard Compact Disc
+audio format (stereo 16-bit linear
+.Sy PCM
+data sampled at 44.1 KHz) requires approximately 10 megabytes per minute.
+.Pp
+Audio data may be represented in several different formats.
+An audio device's
+current audio data format can be determined by using the
+.Dv AUDIO_GETINFO
+.Xr ioctl 2
+described below.
+.Pp
 An audio data format is characterized in the audio driver by four parameters:
-Sample Rate, Encoding, Precision, and Channels. Refer to the device-specific
-manual pages for a list of the audio formats that each device supports. In
-addition to the formats that the audio device supports directly, other formats
-provide higher data compression. Applications may convert audio data to and
+Sample Rate, Encoding, Precision, and Channels.
+Refer to the device-specific
+manual pages for a list of the audio formats that each device supports.
+In addition to the formats that the audio device supports directly, other formats
+provide higher data compression.
+Applications may convert audio data to and
 from these formats when playing or recording.
-.SS "Sample Rate"
-.sp
-.LP
+.Ss "Sample Rate"
 Sample rate is a number that represents the sampling frequency (in samples per
 second) of the audio data.
-.sp
-.LP
+.Pp
 The audio mixer always configures the hardware for the highest possible sample
-rate for both play and record. This ensures that none of the audio streams
-require compute-intensive low pass filtering. The result is that high sample
-rate audio streams are not degraded by filter ing.
-.sp
-.LP
+rate for both play and record.
+This ensures that none of the audio streams
+require compute-intensive low pass filtering.
+The result is that high sample rate audio streams are not degraded by filtering.
+.Pp
 Sample rate conversion can be a compute-intensive operation, depending on the
-number of channels and a device's sample rate. For example, an 8KHz signal can
-be easily converted to 48KHz, requiring a low cost up sampling by 6. However,
-converting from 44.1KHz to 48KHz is compute  intensive because it must be up
-sampled by 160 and then down sampled by 147. This is only done using integer
-multipliers.
-.sp
-.LP
+number of channels and a device's sample rate.
+For example, an 8KHz signal can
+be easily converted to 48KHz, requiring a low cost up sampling by 6.
+However,
+converting from 44.1KHz to 48KHz is compute intensive because it must be up
+sampled by 160 and then down sampled by 147.
+This is only done using integer multipliers.
+.Pp
 Applications can greatly reduce the impact of sample rate conversion by
-carefully picking the sample rate. Applications should always use the highest
-sample rate the device supports. An application can also do its own sample rate
-conversion (to take advantage of floating  point and accelerated instruction or
+carefully picking the sample rate.
+Applications should always use the highest
+sample rate the device supports.
+An application can also do its own sample rate
+conversion (to take advantage of floating point and accelerated instruction or
 use small integers for up and down sampling.
-.sp
-.LP
+.Pp
 All modern audio devices run at 48 kHz or a multiple thereof, hence just using
 48 kHz may be a reasonable compromise if the application is not prepared to
 select higher sample rates.
-.SS "Encodings"
-.sp
-.LP
-An encoding parameter specifies the audio data representation. \(*m-Law
-encoding corresponds to \fICCITT G.711\fR, and is the standard for voice data
-used by telephone companies in the United States, Canada, and Japan. A-Law
-encoding is also part of \fICCITT G.711\fR and is the standard encoding for
-telephony elsewhere in the world. A-Law and \(*m-Law audio data are sampled at
+.Ss "Encodings"
+An encoding parameter specifies the audio data representation.
+\(*m-Law
+encoding corresponds to
+.Em CCITT G.711 ,
+and is the standard for voice data
+used by telephone companies in the United States, Canada, and Japan.
+A-Law encoding is also part of
+.Em CCITT G.711
+and is the standard encoding for telephony elsewhere in the world.
+A-Law and \(*m-Law audio data are sampled at
 a rate of 8000 samples per second with 12-bit precision, with the data
-compressed to 8-bit samples. The resulting audio data quality is equivalent to
+compressed to 8-bit samples.
+The resulting audio data quality is equivalent to
 that of standard analog telephone service.
-.sp
-.LP
+.Pp
 Linear Pulse Code Modulation (PCM) is an uncompressed, signed audio format in
-which sample values are directly proportional to audio signal voltages. Each
-sample is a 2's complement number that represents a positive or negative
+which sample values are directly proportional to audio signal voltages.
+Each sample is a 2's complement number that represents a positive or negative
 amplitude.
-.SS "Precision"
-.sp
-.LP
-Precision indicates the number of bits used to store each audio sample. For
-instance, u-Law and A-Law data are stored with 8-bit precision. \fBPCM\fR data
-may be stored at various precisions, though 16-bit is the most common.
-.SS "Channels"
-.sp
-.LP
-Multiple channels of audio may be interleaved at sample boundaries. A sample
-frame consists of a single sample from each active channel. For example, a
-sample frame of stereo 16-bit \fBPCM\fR data consists of two 16-bit samples,
+.Ss "Precision"
+Precision indicates the number of bits used to store each audio sample.
+For instance, \(*m-Law and A-Law data are stored with 8-bit precision.
+.Sy PCM
+data may be stored at various precisions, though 16-bit is the most common.
+.Ss "Channels"
+Multiple channels of audio may be interleaved at sample boundaries.
+A sample frame consists of a single sample from each active channel.
+For example, a sample frame of stereo 16-bit
+.Sy PCM
+data consists of two 16-bit samples,
 corresponding to the left and right channel data.
-.sp
-.LP
+.Pp
 The audio mixer sets the hardware to the maximum number of channels supported.
 If a mono signal is played or recorded, it is mixed on the first two (usually
-the left and right) channels only. Silence is mixed on the remaining channels
-.SS "Supported Formats"
-.sp
-.LP
+the left and right) channels only.
+Silence is mixed on the remaining channels
+.Ss "Supported Formats"
 The audio mixer supports the following audio formats:
-.sp
-.in +2
-.nf
-Encoding           Precision   Channels
-Signed Linear PCM  32-bit      Mono or Stereo
-Signed Linear PCM  16-bit      Mono or Stereo
-Signed Linear PCM   8-bit      Mono or Stereo
-u-Law               8-bit      Mono or Stereo
-A-Law               8-bit      Mono or Stereo
-.fi
-.in -2
-.sp
-
-.sp
-.LP
+.Bl -column "Signed Linear PCM" "Precision" "Mono or Stereo" -offset 2n
+.It Encoding Ta Precision Ta Channels
+.It "Signed Linear PCM" Ta "32-bit" Ta "Mono or Stereo"
+.It "Signed Linear PCM" Ta "16-bit" Ta "Mono or Stereo"
+.It "Signed Linear PCM" Ta "8-bit" Ta "Mono or Stereo"
+.It "\(*m-Law" Ta "8-bit" Ta "Mono or Stereo"
+.It "A-Law" Ta "8-bit" Ta "Mono or Stereo"
+.El
+.Pp
 The audio mixer converts all audio streams to 24-bit Linear PCM before mixing.
-After mixing, conversion is made to the best possible Codec format. The
+After mixing, conversion is made to the best possible Codec format.
+The
 conversion process is not compute intensive and audio applications can choose
 the encoding format that best meets their needs.
-.sp
-.LP
+.Pp
 Note that the mixer discards the low order 8 bits of 32-bit Signed Linear PCM
-in order to perform mixing. (This is done to allow for possible overflows to
-fit into 32-bits when mixing multiple streams together.) Hence, the maximum
-effective precision is 24-bits.
-.SH DESCRIPTION
-.sp
-.LP
-The device \fB/dev/audio\fR is a device driver that dispatches audio requests
-to the appropriate underlying audio hardware. The audio driver is implemented
-as a \fBSTREAMS\fR driver. In order to record audio input, applications
-\fBopen\fR(2) the \fB/dev/audio\fR device and read data from it using the
-\fBread\fR(2) system call. Similarly, sound data is queued to the audio output
-port by using the \fBwrite\fR(2) system call. Device configuration is performed
-using the \fBioctl\fR(2) interface.
-.sp
-.LP
+in order to perform mixing.
+(This is done to allow for possible overflows to
+fit into 32-bits when mixing multiple streams together.)
+Hence, the maximum effective precision is 24-bits.
+.Sh DESCRIPTION
+The device
+.Pa /dev/audio
+is a device driver that dispatches audio requests
+to the appropriate underlying audio hardware.
+The audio driver is implemented as a
+.Sy STREAMS
+driver.
+In order to record audio input, applications
+.Xr open 2
+the
+.Pa /dev/audio
+device and read data from it using the
+.Xr read 2
+system call.
+Similarly, sound data is queued to the audio output port by using the
+.Xr write 2
+system call.
+Device configuration is performed using the
+.Xr ioctl 2
+interface.
+.Pp
 Because some systems may contain more than one audio device, application
-writers are encouraged to query the \fBAUDIODEV\fR environment variable. If
-this variable is present in the environment, its value should identify the path
-name of the default audio device.
-.SS "Opening the Audio Device"
-.sp
-.LP
-The audio device is not treated as an exclusive resource. Each process may open
-the audio device once.
-.sp
-.LP
-Each \fBopen()\fR completes as long as there are channels available to be
-allocated. If no channels are available to be allocated:
-.RS +4
-.TP
-.ie t \(bu
-.el o
-if either the \fBO_NDELAY\fR or \fBO_NONBLOCK\fR flags are set in the
-\fBopen()\fR \fIoflag\fR argument, then -1 is immediately returned, with
-\fIerrno\fR set to \fBEBUSY.\fR
-.RE
-.RS +4
-.TP
-.ie t \(bu
-.el o
-if neither the \fBO_NDELAY\fR nor the \fBO_NONBLOCK\fR flag are set, then
-\fBopen()\fR hangs until the device is available or a signal is delivered to
-the process, in which case a -1 is returned with \fIerrno\fR set to
-\fBEINTR.\fR
-.RE
-.sp
-.LP
-Upon the initial open() of the audio channel, the audio mixer sets the data
-format of the audio channel to the default state of 8-bit, 8Khz, mono u-Law
-data. If the audio device does not support this configuration, it informs the
-audio mixer of the initial configuration. Audio applications should explicitly
-set the encoding characteristics to match the audio data requirements, and not
-depend on the default configuration.
-.SS "Recording Audio Data"
-.sp
-.LP
-The \fBread()\fR system call copies data from the system's buffers to the
-application. Ordinarily, \fBread()\fR blocks until the user buffer is filled.
-The \fBI_NREAD\fR \fBioctl\fR (see \fBstreamio\fR(7I)) may be used to determine
-the amount of data that may be read without blocking. The device may
-alternatively be set to a non-blocking mode, in which case \fBread()\fR
-completes immediately, but may return fewer bytes than requested. Refer to the
-\fBread\fR(2) manual page for a complete description of this behavior.
-.sp
-.LP
+writers are encouraged to query the
+.Ev AUDIODEV
+environment variable.
+If this variable is present in the environment, its value should identify the
+path name of the default audio device.
+.Ss "Opening the Audio Device"
+The audio device is not treated as an exclusive resource.
+Each process may open the audio device once.
+.Pp
+Each
+.Xr open 2
+completes as long as there are channels available to be allocated.
+If no channels are available to be allocated:
+.Bl -bullet -offset indent
+.It
+if either the
+.Dv O_NDELAY
+or
+.Dv O_NONBLOCK
+flags are set in the
+.Xr open 2
+.Fa oflag
+argument, then -1 is immediately returned, with
+.Va errno
+set to
+.Er EBUSY .
+.It
+if neither the
+.Dv O_NDELAY
+nor the
+.Dv O_NONBLOCK
+flag are set, then
+.Xr open 2
+hangs until the device is available or a signal is delivered to
+the process, in which case a -1 is returned with
+.Va errno
+set to
+.Er EINTR .
+.El
+.Pp
+Upon the initial
+.Xr open 2
+of the audio channel, the audio mixer sets the data
+format of the audio channel to the default state of 8-bit, 8Khz, mono \(*m-Law
+data.
+.Pp
+If the audio device does not support this configuration, it informs the
+audio mixer of the initial configuration.
+Audio applications should explicitly set the encoding characteristics to match the
+audio data requirements, and not depend on the default configuration.
+.Ss "Recording Audio Data"
+The
+.Xr read 2
+system call copies data from the system's buffers to the application.
+Ordinarily,
+.Xr read 2
+blocks until the user buffer is filled.
+The
+.Dv I_NREAD
+.Sy ioctl
+(see
+.Xr streamio 7I )
+may be used to determine the amount of data that may be read without blocking.
+The device may alternatively be set to a non-blocking mode, in which case
+.Xr read 2
+completes immediately, but may return fewer bytes than requested.
+Refer to the
+.Xr read 2
+manual page for a complete description of this behavior.
+.Pp
 When the audio device is opened with read access, the device driver immediately
-starts buffering audio input data. Since this consumes system resources,
+starts buffering audio input data.
+Since this consumes system resources,
 processes that do not record audio data should open the device write-only
-(\fBO_WRONLY\fR).
-.sp
-.LP
-The transfer of input data to \fBSTREAMS\fR buffers may be paused (or resumed)
-by using the \fBAUDIO_SETINFO\fR \fBioctl\fR to set (or clear) the
-\fIrecord.pause\fR flag in the audio information structure (see below). All
-unread input data in the \fBSTREAMS\fR queue may be discarded by using the
-\fBI_FLUSH\fR \fBSTREAMS\fR \fBioctl\fR. See \fBstreamio\fR(7I). When changing
-record parameters, the input stream should be paused and flushed before the
-change, and resumed afterward. Otherwise, subsequent reads may return samples
-in the old format followed by samples in the new format. This is particularly
-important when new parameters result in a changed sample size.
-.sp
-.LP
-Input data can accumulate in \fBSTREAMS\fR buffers very quickly. At a minimum,
-it will accumulate at 8000 bytes per second for 8-bit, 8 KHz, mono, u-Law data.
+.Pq Dv O_WRONLY .
+.Pp
+The transfer of input data to
+.Sy STREAMS
+buffers may be paused (or resumed) by using the
+.Dv AUDIO_SETINFO
+.Sy ioctl
+to set (or clear) the
+.Fa record.pause
+flag in the audio information structure (see below).
+All unread input data in the
+.Sy STREAMS
+queue may be discarded by using the
+.Dv I_FLUSH
+.Sy STREAMS
+ioctl.
+See
+.Xr streamio 7I .
+When changing record parameters, the input stream should be paused and flushed
+before the change, and resumed afterward.
+Otherwise, subsequent reads may return samples
+in the old format followed by samples in the new format.
+This is particularly important when new parameters result in a changed sample size.
+.Pp
+Input data can accumulate in
+.Sy STREAMS
+buffers very quickly.
+At a minimum,
+it will accumulate at 8000 bytes per second for 8-bit, 8 KHz, mono, \(*m-Law data.
 If the device is configured for 16-bit linear or higher sample rates, it will
-accumulate even faster. If the application that consumes the data cannot keep
-up with this data rate, the \fBSTREAMS\fR queue may become full. When this
-occurs, the \fIrecord.error\fR flag is set in the audio information structure
-and input sampling ceases until there is room in the input queue for additional
-data. In such cases, the input data stream contains a discontinuity. For this
-reason, audio recording applications should open the audio device when they are
-prepared to begin reading data, rather than at the start of extensive
+accumulate even faster.
+If the application that consumes the data cannot keep
+up with this data rate, the
+.Sy STREAMS
+queue may become full.
+When this occurs, the
+.Fa record.error
+flag is set in the audio information structure and input sampling ceases until
+there is room in the input queue for additional data.
+In such cases, the input data stream contains a discontinuity.
+For this reason, audio recording applications should open the audio device when
+they are prepared to begin reading data, rather than at the start of extensive
 initialization.
-.SS "Playing Audio Data"
-.sp
-.LP
-The \fBwrite()\fR system call copies data from an application's buffer to the
-\fBSTREAMS\fR output queue. Ordinarily, \fBwrite()\fR blocks until the entire
-user buffer is transferred. The device may alternatively be set to a
-non-blocking mode, in which case \fBwrite()\fR completes immediately, but may
-have transferred fewer bytes than requested. See \fBwrite\fR(2).
-.sp
-.LP
-Although \fBwrite()\fR returns when the data is successfully queued, the actual
-completion of audio output may take considerably longer. The \fBAUDIO_DRAIN\fR
-\fBioctl\fR may be issued to allow an application to block until all of the
-queued output data has been played. Alternatively, a process may request
+.Ss "Playing Audio Data"
+The
+.Xr write 2
+system call copies data from an application's buffer to the
+.Sy STREAMS
+output queue.
+Ordinarily,
+.Xr write 2
+blocks until the entire user buffer is transferred.
+The device may alternatively be set to a non-blocking mode, in which case
+.Xr write 2
+completes immediately, but may have transferred fewer bytes than requested.
+See
+.Xr write 2 .
+.Pp
+Although
+.Xr write 2
+returns when the data is successfully queued, the actual
+completion of audio output may take considerably longer.
+The
+.Dv AUDIO_DRAIN
+ioctl may be issued to allow an application to block until all of the
+queued output data has been played.
+Alternatively, a process may request
 asynchronous notification of output completion by writing a zero-length buffer
-(end-of-file record) to the output stream. When such a buffer has been
-processed, the \fIplay.eof\fR flag in the audio information structure is
-incremented.
-.sp
-.LP
-The final \fBclose\fR(2) of the file descriptor hangs until all of the audio
-output has drained. If a signal interrupts the \fBclose()\fR, or if the process
-exits without closing the device, any remaining data queued for audio output is
-flushed and the device is closed immediately.
-.sp
-.LP
+(end-of-file record) to the output stream.
+When such a buffer has been
+processed, the
+.Fa play.eof
+flag in the audio information structure is incremented.
+.Pp
+The final
+.Xr close 2
+of the file descriptor hangs until all of the audio
+output has drained.
+If a signal interrupts the
+.Xr close 2 ,
+or if the process exits without closing the device, any remaining data queued
+for audio output is flushed and the device is closed immediately.
+.Pp
 The consumption of output data may be paused (or resumed) by using the
-\fBAUDIO_SETINFO\fR \fBioctl\fR to set (or clear) the \fIplay.pause\fR flag in
-the audio information structure. Queued output data may be discarded by using
-the \fBI_FLUSH\fR \fBSTREAMS\fR \fBioctl\fR. (See \fBstreamio\fR(7I)).
-.sp
-.LP
-Output data is played from the \fBSTREAMS\fR buffers at a default rate of at
+.Dv AUDIO_SETINFO
+ioctl to set (or clear) the
+.Fa play.pause
+flag in the audio information structure.
+Queued output data may be discarded by using
+the
+.Dv I_FLUSH
+.Sy STREAMS
+ioctl.
+(See
+.Xr streamio 7I ) .
+.Pp
+Output data is played from the
+.Sy STREAMS
+buffers at a default rate of at
 least 8000 bytes per second for \(*m-Law, A-Law or 8-bit PCM data (faster for
-16-bit linear data or higher sampling rates). If the output queue becomes
-empty, the \fIplay.error\fR flag is set in the audio information structure and
-output is stopped until additional data is written. If an application attempts
+16-bit linear data or higher sampling rates).
+If the output queue becomes
+empty, the
+.Fa play.error
+flag is set in the audio information structure and
+output is stopped until additional data is written.
+If an application attempts
 to write a number of bytes that is not a multiple of the current sample frame
-size, an error is generated and the bad data is thrown away. Additional writes
-are allowed.
-.SS "Asynchronous I/O"
-.sp
-.LP
-The \fBI_SETSIG\fR \fBSTREAMS\fR \fBioctl\fR enables asynchronous notification,
-through the \fBSIGPOLL\fR signal, of input and output ready condition changes.
-The \fBO_NONBLOCK\fR flag may be set using the \fBF_SETFL\fR \fBfcntl\fR(2) to
-enable non-blocking \fBread()\fR and \fBwrite()\fR requests. This is normally
+size, an error is generated and the bad data is thrown away.
+Additional writes are allowed.
+.Ss "Asynchronous I/O"
+The
+.Dv I_SETSIG
+.Sy STREAMS
+ioctl
+enables asynchronous notification, through the
+.Dv SIGPOLL
+signal, of input and output ready condition changes.
+The
+.Dv O_NONBLOCK
+flag may be set using the
+.Dv F_SETFL
+.Xr fcntl 2
+to
+enable non-blocking
+.Xr read 2
+and
+.Xr write 2
+requests.
+This is normally
 sufficient for applications to maintain an audio stream in the background.
-.SS "Audio Control Pseudo-Device"
-.sp
-.LP
+.Ss "Audio Control Pseudo-Device"
 It is sometimes convenient to have an application, such as a volume control
 panel, modify certain characteristics of the audio device while it is being
 used by an unrelated process.
-.sp
-.LP
-The \fB/dev/audioctl\fR pseudo-device is provided for this purpose. Any number
-of processes may open \fB/dev/audioctl\fR simultaneously. However, \fBread()\fR
-and \fBwrite()\fR system calls are ignored by \fB/dev/audioctl\fR. The
-\fBAUDIO_GETINFO\fR and \fBAUDIO_SETINFO\fR \fBioctl\fR commands may be issued
-to \fB/dev/audioctl\fR to determine the status or alter the behavior of
-\fB/dev/audio\fR. Note: In general, the audio control device name is
-constructed by appending the letters \fB"ctl"\fR to the path name of the audio
-device.
-.SS "Audio Status Change Notification"
-.sp
-.LP
+.Pp
+The
+.Pa /dev/audioctl
+pseudo-device is provided for this purpose.
+Any number of processes may open
+.Pa /dev/audioctl
+simultaneously.
+However,
+.Xr read 2
+and
+.Xr write 2
+system calls are ignored by
+.Pa /dev/audioctl .
+The
+.Dv AUDIO_GETINFO
+and
+.Dv AUDIO_SETINFO
+ioctl commands may be issued to
+.Pa /dev/audioctl
+to determine the status or alter the behavior of
+.Pa /dev/audio .
+Note: In general, the audio control device name is
+constructed by appending the letters
+.Qq Sy ctl
+to the path name of the audio device.
+.Ss "Audio Status Change Notification"
 Applications that open the audio control pseudo-device may request asynchronous
 notification of changes in the state of the audio device by setting the
-\fBS_MSG\fR flag in an \fBI_SETSIG\fR \fBSTREAMS\fR \fBioctl\fR. Such processes
-receive a \fBSIGPOLL\fR signal when any of the following events occur:
-.RS +4
-.TP
-.ie t \(bu
-.el o
-An \fBAUDIO_SETINFO\fR \fBioctl\fR has altered the device state.
-.RE
-.RS +4
-.TP
-.ie t \(bu
-.el o
+.Dv S_MSG
+flag in an
+.Dv I_SETSIG
+.Sy STREAMS
+ioctl.
+Such processes receive a
+.Dv SIGPOLL
+signal when any of the following events occur:
+.Bl -bullet -offset indent
+.It
+An
+.Dv AUDIO_SETINFO
+ioctl has altered the device state.
+.It
 An input overflow or output underflow has occurred.
-.RE
-.RS +4
-.TP
-.ie t \(bu
-.el o
+.It
 An end-of-file record (zero-length buffer) has been processed on output.
-.RE
-.RS +4
-.TP
-.ie t \(bu
-.el o
-An \fBopen()\fR or \fBclose()\fR of \fB/dev/audio\fR has altered the device
-state.
-.RE
-.RS +4
-.TP
-.ie t \(bu
-.el o
+.It
+An
+.Xr open 2
+or
+.Xr close 2
+of
+.Pa /dev/audio
+has altered the device state.
+.It
 An external event (such as speakerbox's volume control) has altered the device
 state.
-.RE
-.SH IOCTLS
-.SS "Audio Information Structure"
-.sp
-.LP
+.El
+.Sh IOCTLS
+.Ss "Audio Information Structure"
 The state of the audio device may be polled or modified using the
-\fBAUDIO_GETINFO\fR and \fBAUDIO_SETINFO\fR \fBioctl\fR commands. These
-commands operate on the \fBaudio_info\fR structure as defined, in
-\fB<sys/audio.h>\fR, as follows:
-.sp
-.in +2
-.nf
+.Dv AUDIO_GETINFO
+and
+.Dv AUDIO_SETINFO
+ioctl commands.
+These commands operate on the
+.Vt audio_info
+structure as defined, in
+.In sys/audio.h ,
+as follows:
+.Bd -literal -offset 2n
 /*
-* This structure contains state information for audio device
-* IO streams
-*/
+ * This structure contains state information for audio device
+ * IO streams
+ */
 
 struct audio_prinfo {
-  /*
-  * The following values describe the
-  * audio data encoding
-  */
- uint_t sample_rate; /* samples per second */
- uint_t channels;  /* number of interleaved channels */
- uint_t precision; /* number of bits per sample */
- uint_t encoding;  /* data encoding method */
-
-
-  /*
-  * The following values control audio device
-  * configuration
-  */
- uint_t gain; /* volume level */
- uint_t port; /* selected I/O port */
- uint_t buffer_size; /* I/O buffer size */
-
-  /*
-  * The following values describe the current device
-  * state
-  */
- uint_t samples; /* number of samples converted */
- uint_t eof;  /* End Of File counter (play only) */
- uchar_t pause;  /* non-zero if paused, zero to resume */
- uchar_t error; /* non-zero if overflow/underflow */
- uchar_t waiting; /* non-zero if a process wants access */
- uchar_t balance; /* stereo channel balance */
-   /*
-   * The following values are read-only device state
-   * information
-   */
- uchar_t open;/* non-zero if open access granted */
- uchar_t active; /* non-zero if I/O active */
- uint_t avail_ports; /* available I/O ports */
- uint_t mod_ports; /* modifiable I/O ports */
+     /*
+      * The following values describe the
+      * audio data encoding
+      */
+      uint_t sample_rate; /* samples per second */
+      uint_t channels;    /* number of interleaved channels */
+      uint_t precision;   /* number of bits per sample */
+      uint_t encoding;    /* data encoding method */
+
+      /*
+       * The following values control audio device
+       * configuration
+       */
+      uint_t gain; /* volume level */
+      uint_t port; /* selected I/O port */
+      uint_t buffer_size; /* I/O buffer size */
+
+     /*
+      * The following values describe the current device
+      * state
+      */
+     uint_t samples; /* number of samples converted */
+     uint_t eof;     /* End Of File counter (play only) */
+     uchar_t pause;  /* non-zero if paused, zero to resume */
+     uchar_t error;  /* non-zero if overflow/underflow */
+     uchar_t waiting; /* non-zero if a process wants access */
+     uchar_t balance; /* stereo channel balance */
+
+     /*
+      * The following values are read-only device state
+      * information
+      */
+      uchar_t open;   /* non-zero if open access granted */
+      uchar_t active; /* non-zero if I/O active */
+      uint_t avail_ports; /* available I/O ports */
+      uint_t mod_ports; /* modifiable I/O ports */
 };
 typedef struct audio_prinfo audio_prinfo_t;
 
-  /*
-  * This structure is used in AUDIO_GETINFO and AUDIO_SETINFO ioctl
-  * commands
-  */
+/*
+ * This structure is used in AUDIO_GETINFO and AUDIO_SETINFO ioctl
+ * commands
+ */
 struct audio_info {
- audio_prinfo_t record;/* input status info */
- audio_prinfo_t play;/* output status info */
- uint_t monitor_gain; /* input to output mix */
- uchar_toutput_muted; /* non-zero if output muted */
- uint_t hw_features; /* supported H/W features */
- uint_t sw_features;/* supported S/W features */
- uint_t sw_features_enabled;
+    audio_prinfo_t record;/* input status info */
+    audio_prinfo_t play; /* output status info */
+    uint_t monitor_gain; /* input to output mix */
+    uchar_toutput_muted; /* non-zero if output muted */
+    uint_t hw_features;  /* supported H/W features */
+    uint_t sw_features;  /* supported S/W features */
+    uint_t sw_features_enabled;
                 /* supported S/W features enabled */
 };
 typedef struct audio_info audio_info_t;
@@ -426,392 +533,467 @@ typedef struct audio_info audio_info_t;
 #define AUDIO_ENCODING_ULAW (1) /* u-Law encoding */
 #define AUDIO_ENCODING_ALAW (2) /* A-Law encoding */
 #define AUDIO_ENCODING_LINEAR (3) /* Signed Linear PCM encoding */
+
 /*
-* These ranges apply to record, play, and
-* monitor gain values
+ * These ranges apply to record, play, and
+ * monitor gain values
  */
 #define AUDIO_MIN_GAIN (0)/* minimum gain value */
 #define AUDIO_MAX_GAIN (255) /* maximum gain value */
 
 /*
-* These values apply to the balance field to adjust channel
-* gain values
+ * These values apply to the balance field to adjust channel
+ * gain values
  */
-#define AUDIO_LEFT_BALANCE(0) /* left channel only */
-#define AUDIO_MID_BALANCE (32) /* equal left/right balance */
+#define AUDIO_LEFT_BALANCE   (0) /* left channel only */
+#define AUDIO_MID_BALANCE   (32) /* equal left/right balance */
 #define AUDIO_RIGHT_BALANCE (64) /* right channel only */
 
 /*
-* Define some convenient audio port names
-* (for port, avail_ports and mod_ports)
+ * Define some convenient audio port names
+ * (for port, avail_ports and mod_ports)
  */
 
 /* output ports (several might be enabled at once) */
-#define AUDIO_SPEAKER (0x01)/* built-in speaker */
-#define AUDIO_HEADPHONE (0x02)/* headphone jack */
-#define AUDIO_LINE_OUT (0x04)/* line out */
-#define AUDIO_SPDIF_OUT (0x08)/* SPDIF port */
-#define AUDIO_AUX1_OUT (0x10)/* aux1 out */
-#define AUDIO_AUX2_OUT (0x20)/* aux2 out */
+#define AUDIO_SPEAKER   (0x01) /* built-in speaker */
+#define AUDIO_HEADPHONE (0x02) /* headphone jack */
+#define AUDIO_LINE_OUT  (0x04) /* line out */
+#define AUDIO_SPDIF_OUT (0x08) /* SPDIF port */
+#define AUDIO_AUX1_OUT  (0x10) /* aux1 out */
+#define AUDIO_AUX2_OUT  (0x20) /* aux2 out */
 
-/* input ports (usually only one may be
-* enabled at a time)
+/*
+ * input ports (usually only one may be enabled at a time)
  */
 #define AUDIO_MICROPHONE (0x01) /* microphone */
-#define AUDIO_LINE_IN (0x02) /* line in */
-#define AUDIO_CD(0x04) /* on-board CD inputs */
+#define AUDIO_LINE_IN  (0x02) /* line in */
+#define AUDIO_CD       (0x04) /* on-board CD inputs */
 #define AUDIO_SPDIF_IN (0x08) /* SPDIF port */
-#define AUDIO_AUX1_IN (0x10) /* aux1 in */
-#define AUDIO_AUX2_IN (0x20) /* aux2 in */
-#define AUDIO_CODEC_LOOPB_IN (0x40) /* Codec inter.loopback */
+#define AUDIO_AUX1_IN  (0x10) /* aux1 in */
+#define AUDIO_AUX2_IN  (0x20) /* aux2 in */
+#define AUDIO_CODEC_LOOPB_IN (0x40) /* Codec inter. loopback */
 
 /* These defines are for hardware features */
 #define AUDIO_HWFEATURE_DUPLEX (0x00000001u)
-/*simult. play & cap. supported */
+/* simult. play & cap. supported */
 
 #define AUDIO_HWFEATURE_MSCODEC (0x00000002u)
 /* multi-stream Codec */
 
 /* These defines are for software features *
 #define AUDIO_SWFEATURE_MIXER (0x00000001u)
- /* audio mixer audio pers. mod. */
+/* audio mixer audio pers. mod. */
 
 /*
-* Parameter for the AUDIO_GETDEV ioctl
-* to determine current audio devices
-*/#define MAX_AUDIO_DEV_LEN(16)
+ * Parameter for the AUDIO_GETDEV ioctl
+ * to determine current audio devices
+ */
+#define MAX_AUDIO_DEV_LEN (16)
 struct audio_device {
- char name[MAX_AUDIO_DEV_LEN];
- char version[MAX_AUDIO_DEV_LEN];
- char config[MAX_AUDIO_DEV_LEN];
+    char name[MAX_AUDIO_DEV_LEN];
+    char version[MAX_AUDIO_DEV_LEN];
+    char config[MAX_AUDIO_DEV_LEN];
 };
 typedef struct audio_device audio_device_t;
-.fi
-.in -2
-
-.sp
-.LP
-The \fIplay.gain\fR and \fIrecord.gain\fR fields specify the output and input
-volume levels. A value of \fBAUDIO_MAX_GAIN\fR indicates maximum volume. Audio
-output may also be temporarily muted by setting a non-zero value in the
-\fIoutput_muted\fR field. Clearing this field restores audio output  to the
-normal state.
-.sp
-.LP
-The \fImonitor_gain\fR field is present for compatibility, and is no longer
-supported. See \fBdsp\fR(7I) for more detail.
-.sp
-.LP
-Likewise, the \fIplay.port\fR, \fIplay.ports\fR, \fIplay.mod_ports\fR,
-\fIrecord.port\fR, \fIrecord.ports\fR, and \fIrecord.mod_ports\fR are no longer
-supported. See \fBdsp\fR(7I) for more detail.
-.sp
-.LP
-The \fIplay.balance\fR and \fIrecord.balance\fR fields are fixed to
-\fBAUDIO_MID_BALANCE\fR. Changes to volume levels for different channels can be
-made using the interfaces in \fBdsp\fR(7I).
-.sp
-.LP
-The \fIplay.pause\fR and \fIrecord.pause\fR flags may be used to pause and
-resume the transfer of data between the audio device and the STREAMS buffers.
-The \fIplay.error\fR and \fIrecord.error\fR flags indicate that data underflow
-or overflow has occurred. The \fIplay.active\fR and \fIrecord.active\fR flags
-indicate  that data transfer is currently active in the corresponding
+.Ed
+.Pp
+The
+.Fa play.gain
+and
+.Fa record.gain
+fields specify the output and input volume levels.
+A value of
+.Dv AUDIO_MAX_GAIN
+indicates maximum volume.
+Audio output may also be temporarily muted by setting a non-zero value in the
+.Fa output_muted
+field.
+Clearing this field restores audio output to the normal state.
+.Pp
+The
+.Va monitor_gain
+field is present for compatibility, and is no longer supported.
+See
+.Xr dsp 7I
+for more detail.
+.Pp
+Likewise, the
+.Fa play.port ,
+.Fa play.ports ,
+.Fa play.mod_ports ,
+.Fa record.port ,
+.Fa record.ports ,
+and
+.Fa record.mod_ports
+are no longer supported.
+See
+.Xr dsp 7I
+for more detail.
+.Pp
+The
+.Fa play.balance
+and
+.Fa record.balance
+fields are fixed to
+.Dv AUDIO_MID_BALANCE .
+Changes to volume levels for different channels can be
+made using the interfaces in
+.Xr dsp 7I .
+.Pp
+The
+.Fa play.pause
+and
+.Fa record.pause
+flags may be used to pause and
+resume the transfer of data between the audio device and the
+.Sy STREAMS
+buffers.
+The
+.Fa play.error
+and
+.Fa record.error
+flags indicate that data underflow or overflow has occurred.
+The
+.Fa play.active
+and
+.Fa record.active
+flags indicate that data transfer is currently active in the corresponding
 direction.
-.sp
-.LP
-The \fIplay.open\fR and \fIrecord.open\fR flags indicate that the device is
-currently open with the corresponding access permission. The \fIplay.waiting\fR
-and \fIrecord.waiting\fR flags provide an indication that a process may be
-waiting to access the device. These flags are set automatically when a process
-blocks on \fBopen()\fR, though they may also be set using the
-\fBAUDIO_SETINFO\fR ioctl command. They are cleared only when a process
-relinquishes access by closing the device.
-.sp
-.LP
-The \fIplay.samples\fR and \fIrecord.samples\fR fields are zeroed at
-\fBopen()\fR and are incremented each time a data sample is copied to or from
-the associated STREAMS queue. Some audio drivers may be limited to counting
-buffers of samples, instead of single samples for their samples accounting. For
-this reason, applications should not assume that the samples fields contain a
-perfectly accurate count. The \fIplay.eof\fR field increments whenever a
-zero-length output buffer is synchronously processed. Applications may use this
-field to detect  the completion of particular segments of audio output.
-.sp
-.LP
-The \fIrecord.buffer_size\fR field controls the amount of input data that is
-buffered in the device driver during record operations. Applications that have
+.Pp
+The
+.Fa play.open
+and
+.Fa record.open
+flags indicate that the device is
+currently open with the corresponding access permission.
+The
+.Fa play.waiting
+and
+.Fa record.waiting
+flags provide an indication that a process may be waiting to access the device.
+These flags are set automatically when a process blocks on
+.Xr open 2 ,
+though they may also be set using the
+.Dv AUDIO_SETINFO
+ioctl command.
+They are cleared only when a process relinquishes access by closing the device.
+.Pp
+The
+.Fa play.samples
+and
+.Fa record.samples
+fields are zeroed at
+.Xr open 2
+and are incremented each time a data sample is copied to or from
+the associated
+.Sy STREAMS
+queue.
+Some audio drivers may be limited to counting
+buffers of samples, instead of single samples for their samples accounting.
+For this reason, applications should not assume that the samples fields contain a
+perfectly accurate count.
+The
+.Fa play.eof
+field increments whenever a zero-length output buffer is synchronously processed.
+Applications may use this
+field to detect the completion of particular segments of audio output.
+.Pp
+The
+.Fa record.buffer_size
+field controls the amount of input data that is
+buffered in the device driver during record operations.
+Applications that have
 particular requirements for low latency should set the value appropriately.
 Note however that smaller input buffer sizes may result in higher system
-overhead. The value of this field is specified in bytes and drivers will
-constrain it to be a multiple of the current sample frame size. Some drivers
-may place other requirements on the value of this field. Refer to the audio
-device-specific manual page for more details. If an application changes the
-format of the audio device and does not modify the \fIrecord.buffer_size\fR
+overhead.
+The value of this field is specified in bytes and drivers will
+constrain it to be a multiple of the current sample frame size.
+Some drivers may place other requirements on the value of this field.
+Refer to the audio device-specific manual page for more details.
+If an application changes the
+format of the audio device and does not modify the
+.Fa record.buffer_size
 field, the device driver may use a default value to compensate for the new data
-rate. Therefore, if an application is going to modify this field, it should
-modify it during or after the format change itself, not before. When changing
-the \fIrecord.buffer_size\fR parameters, the input stream should be paused and
-flushed before the change, and resumed afterward. Otherwise,  subsequent reads
+rate.
+Therefore, if an application is going to modify this field, it should
+modify it during or after the format change itself, not before.
+When changing
+the
+.Fa record.buffer_size
+parameters, the input stream should be paused and
+flushed before the change, and resumed afterward.
+Otherwise, subsequent reads
 may return samples in the old format followed by samples in the new format.
 This is particularly important when new parameters result in a changed sample
-size. If you change the \fIrecord.buffer_size\fR for the first packet, this
-protocol must be followed or the first buffer will be the default buffer size
-for the device, followed by packets of the requested change size.
-.sp
-.LP
-The \fIrecord.buffer_size\fR field may be modified only on the \fB/dev/audio\fR
+size.
+If you change the
+.Fa record.buffer_size
+for the first packet, this protocol must be followed or the first buffer will
+be the default buffer size for the device, followed by packets of the requested
+change size.
+.Pp
+The
+.Fa record.buffer_size
+field may be modified only on the
+.Pa /dev/audio
 device by processes that have it opened for reading.
-.sp
-.LP
-The \fIplay.buffer_size\fR field is currently not supported.
-.sp
-.LP
-The audio data format is indicated by the \fIsample_rate, channels,
-precision\fR and encoding fields. The values of these fields correspond to the
-descriptions in the \fBAUDIO FORMATS\fR section of this man page. Refer to the
+.Pp
+The
+.Fa play.buffer_size
+field is currently not supported.
+.Pp
+The audio data format is indicated by the
+.Fa sample_rate ,
+.Fa channels ,
+.Fa precision ,
+and
+.Fa encoding
+fields.
+The values of these fields correspond to the
+descriptions in the
+.Sx "AUDIO FORMATS"
+section of this man page.
+Refer to the
 audio device-specific manual pages for a list of supported data format
 combinations.
-.sp
-.LP
-The data format fields can be modified only on the \fB/dev/audio\fR device.
-.sp
-.LP
-If the parameter changes requested by an \fBAUDIO_SETINFO\fR ioctl cannot all
-be accommodated, \fBioctl()\fR returns with \fBerrno\fR set to \fBEINVAL\fR and
-no changes are made to the device state.
-.SS "Streamio IOCTLS"
-.sp
-.LP
-All of the \fBstreamio\fR(7I) \fBioctl\fR commands may be issued for the
-\fB/dev/audio\fR device. Because the \fB/dev/audioctl\fR device has its own
-\fBSTREAMS\fR queues, most of these commands neither modify nor report the
-state of \fB/dev/audio\fR if issued for the \fB/dev/audioctl\fR device. The
-\fBI_SETSIG\fR \fBioctl\fR may be issued for \fB/dev/audioctl\fR to enable the
-notification of audio status changes, as described above.
-.SS "Audio IOCTLS"
-.sp
-.LP
-The audio device additionally supports the following \fBioctl\fR commands:
-.sp
-.ne 2
-.na
-\fB\fBAUDIO_DRAIN\fR\fR
-.ad
-.RS 17n
-The argument is ignored. This command suspends the calling process until the
+.Pp
+The data format fields can be modified only on the
+.Pa /dev/audio
+device.
+.Pp
+If the parameter changes requested by an
+.Dv AUDIO_SETINFO
+ioctl cannot all be accommodated,
+.Xr ioctl 2
+returns with
+.Va errno
+set to
+.Er EINVAL
+and no changes are made to the device state.
+.Ss "Streamio IOCTLS"
+All of the
+.Xr streamio 7I
+.Xr ioctl 2
+commands may be issued for the
+.Pa /dev/audio
+device.
+Because the
+.Pa /dev/audioctl
+device has its own
+.Sy STREAMS
+queues, most of these commands neither modify nor report the
+state of
+.Pa /dev/audio
+if issued for the
+.Pa /dev/audioctl
+device.
+The
+.Dv I_SETSIG
+ioctl may be issued for
+.Pa /dev/audioctl
+to enable the notification of audio status changes, as described above.
+.Ss "Audio IOCTLS"
+The audio device additionally supports the following
+.Xr ioctl 2
+commands:
+.Bl -tag -width "AUDIO_GETINFO"
+.It Dv AUDIO_DRAIN
+The argument is ignored.
+This command suspends the calling process until the
 output STREAMS queue is empty and all queued samples have been played, or until
-a signal is delivered to the calling process. It may not be issued for the
-\fB/dev/audioctldevice\fR.  An implicit \fBAUDIO_DRAIN\fR is performed on the
-final \fBclose()\fR of \fB/dev/audio\fR.
-.RE
-
-.sp
-.ne 2
-.na
-\fB\fBAUDIO_GETDEV\fR\fR
-.ad
-.RS 17n
-The argument is a pointer to an \fBaudio_device_t\fR structure. This command
-may be issued for either \fB/dev/audio\fR or \fB/dev/audioctl\fR. The returned
+a signal is delivered to the calling process.
+It may not be issued for the
+.Pa /dev/audioctl
+device.
+An implicit
+.Dv AUDIO_DRAIN
+is performed on the final
+.Xr close 2
+of
+.Pa /dev/audio .
+.It Dv AUDIO_GETDEV
+The argument is a pointer to an
+.Vt audio_device_t
+structure.
+This command may be issued for either
+.Pa /dev/audio
+or
+.Pa /dev/audioctl .
+The returned
 value in the name field will be a string that will identify the current
-\fB/dev/audio\fR hardware device, the value in version will be a string
-indicating the current version of the hardware, and \fBconfig\fR will be a
-device-specific string identifying the properties of the audio stream
-associated with that file descriptor. Refer to the audio device-specific manual
+.Pa /dev/audio
+hardware device, the value in version will be a string
+indicating the current version of the hardware, and
+.Fa config
+will be a device-specific string identifying the properties of the audio stream
+associated with that file descriptor.
+Refer to the audio device-specific manual
 pages to determine the actual strings returned by the device driver.
-.RE
-
-.sp
-.ne 2
-.na
-\fB\fBAUDIO_GETINFO\fR\fR
-.ad
-.RS 17n
-The argument is a pointer to an \fBaudio_info_t\fR structure. This command may
-be issued for either \fB/dev/audio\fR or \fB/dev/audioctl\fR. The current state
-of the \fB/dev/audio\fR device is returned in the structure.
-.sp
+.It Dv AUDIO_GETINFO
+The argument is a pointer to an
+.Vt audio_info_t
+structure.
+This command may be issued for either
+.Pa /dev/audio
+or
+.Pa /dev/audioctl .
+The current state of the
+.Pa /dev/audio
+device is returned in the structure.
 Values return pertain to a logical view of the device as seen by and private to
 the process, and do not necessarily reflect the actual hardware device itself.
-.RE
-
-.sp
-.ne 2
-.na
-\fB\fBAUDIO_SETINFO\fR\fR
-.ad
-.RS 17n
-The argument is a pointer to an \fBaudio_info_t\fR structure. This command may
-be issued for either the \fB/dev/audio\fR or the \fB/dev/audioctl\fR device
-with some restrictions. This command configures the audio device according to
+.It Dv AUDIO_SETINFO
+The argument is a pointer to an
+.Vt audio_info_t
+structure.
+This command may be issued for either the
+.Pa /dev/audio
+or the
+.Pa /dev/audioctl
+device with some restrictions.
+This command configures the audio device according to
 the supplied structure and overwrites the existing structure with the new state
-of the device. Note: The \fIplay.samples\fR, \fIrecord.samples\fR,
-\fIplay.error\fR, \fIrecord.error\fR, and \fIplay.eof\fR fields are modified to
-reflect the state of the device when the \fBAUDIO_SETINFO\fR is issued. This
-allows programs to automatically modify  these fields while retrieving the
+of the device.
+Note: The
+.Fa play.samples ,
+.Fa record.samples ,
+.Fa play.error ,
+.Fa record.error ,
+and
+.Fa play.eof
+fields are modified to reflect the state of the device when the
+.Dv AUDIO_SETINFO
+is issued.
+This allows programs to automatically modify these fields while retrieving the
 previous value.
-.sp
-As with \fBAUDIO_SETINFO\fR, the settings managed by this ioctl deal with a
+.Pp
+As with
+.Dv AUDIO_SETINFO ,
+the settings managed by this ioctl deal with a
 logical view of the device which is private to the process, and don't
 necessarily have any impact on the hardware device itself.
-.RE
-
-.sp
-.LP
+.El
+.Pp
 Certain fields in the audio information structure, such as the pause flags, are
-treated as read-only when \fB/dev/audio\fR is not open with the corresponding
-access permission. Other fields, such as the gain levels and encoding
-information, may have a restricted set of acceptable values. Applications that
+treated as read-only when
+.Pa /dev/audio
+is not open with the corresponding access permission.
+Other fields, such as the gain levels and encoding
+information, may have a restricted set of acceptable values.
+Applications that
 attempt to modify such fields should check the returned values to be sure that
-the corresponding change took effect. The \fIsample_rate\fR, \fIchannels\fR,
-\fIprecision\fR, and \fIencoding\fR fields treated as read-only for
-\fB/dev/audioctl\fR, so that applications  can be guaranteed that the existing
+the corresponding change took effect.
+The
+.Fa sample_rate ,
+.Fa channels ,
+.Fa precision ,
+and
+.Fa encoding
+fields treated as read-only for
+.Pa /dev/audioctl ,
+so that applications can be guaranteed that the existing
 audio format will stay in place until they relinquish the audio device.
-\fBAUDIO_SETINFO\fR will return \fBEINVAL\fR when the desired configuration is
-not possible, or \fBEBUSY\fR when another process has control of the audio
-device.
-.sp
-.LP
+.Dv AUDIO_SETINFO
+will return
+.Er EINVAL
+when the desired configuration is not possible, or
+.Er EBUSY
+when another process has control of the audio device.
+.Pp
 All of the logical device state is reset when the corresponding I/O stream of
-\fB/dev/audio\fR is closed.
-.sp
-.LP
-The \fBaudio_info_t\fR structure may be initialized through the use of the
-\fBAUDIO_INITINFO\fR macro. This macro sets all fields in the structure to
-values that are ignored by the \fBAUDIO_SETINFO\fR command. For instance, the
-following code switches the output port from the built-in speaker to the
-headphone jack without modifying any other audio parameters:
-.sp
-.in +2
-.nf
+.Pa /dev/audio
+is closed.
+.Pp
+The
+.Vt audio_info_t
+structure may be initialized through the use of the
+.Dv AUDIO_INITINFO
+macro.
+This macro sets all fields in the structure to
+values that are ignored by the
+.Dv AUDIO_SETINFO
+command.
+For instance, the following code switches the output port from the built-in
+speaker to the headphone jack without modifying any other audio parameters:
+.Bd -literal -offset 2n
 audio_info_t info;
 AUDIO_INITINFO();
 info.play.port = AUDIO_HEADPHONE;
 err = ioctl(audio_fd, AUDIO_SETINFO, );
-.fi
-.in -2
-.sp
-
-.sp
-.LP
+.Ed
+.Pp
 This technique eliminates problems associated with using a sequence of
-\fBAUDIO_GETINFO\fR followed by \fBAUDIO_SETINFO\fR.
-.SH ERRORS
-.sp
-.LP
-An \fBopen()\fR will fail if:
-.sp
-.ne 2
-.na
-\fB\fBEBUSY\fR\fR
-.ad
-.RS 9n
-The requested play or record access is busy and either the \fBO_NDELAY\fR or
-\fBO_NONBLOCK\fR flag was set in the \fBopen()\fR request.
-.RE
-
-.sp
-.ne 2
-.na
-\fB\fBEINTR\fR\fR
-.ad
-.RS 9n
-The requested play or record access is busy and a signal interrupted the
-\fBopen()\fR request.
-.RE
-
-.sp
-.LP
-An \fBioctl()\fR will fail if:
-.sp
-.ne 2
-.na
-\fB\fBEINVAL\fR\fR
-.ad
-.RS 10n
-The parameter changes requested in the \fBAUDIO_SETINFO()\fR ioctl are invalid
-or are not supported by the device.
-.RE
-
-.SH FILES
-.sp
-.LP
+.Dv AUDIO_GETINFO
+followed by
+.Dv AUDIO_SETINFO .
+.Sh FILES
 The physical audio device names are system dependent and are rarely used by
-programmers. Programmers should use the following generic device names:
-.sp
-.ne 2
-.na
-\fB\fB/dev/audio\fR\fR
-.ad
-.RS 28n
+programmers.
+Programmers should use the following generic device names:
+.Bl -tag -width "/usr/share/audio/samples"
+.It Pa /dev/audio
 Symbolic link to the system's primary audio device
-.RE
-
-.sp
-.ne 2
-.na
-\fB\fB/dev/audioctl\fR\fR
-.ad
-.RS 28n
-Symbolic link to the control device for \fB/dev/audio\fR
-.RE
-
-.sp
-.ne 2
-.na
-\fB\fB/dev/sound/0\fR\fR
-.ad
-.RS 28n
+.It Pa /dev/audioctl
+Symbolic link to the control device for
+.Pa /dev/audio
+.It Pa /dev/sound/0
 First audio device in the system
-.RE
-
-.sp
-.ne 2
-.na
-\fB\fB/dev/sound/0ctl\fR\fR
-.ad
-.RS 28n
-Audio control device for \fB/dev/sound/0\fR
-.RE
-
-.sp
-.ne 2
-.na
-\fB\fB/usr/share/audio/samples\fR\fR
-.ad
-.RS 28n
+.It Pa /dev/sound/0ctl
+Audio control device for
+.Pa /dev/sound/0
+.It Pa /usr/share/audio/samples
 Audio files
-.RE
-
-.SH ATTRIBUTES
-.sp
-.LP
-See \fBattributes\fR(5) for a description of the following attributes:
-.sp
-
-.sp
-.TS
-box;
-c | c
-l | l .
-ATTRIBUTE TYPE	ATTRIBUTE VALUE
-_
-Architecture	SPARC, x86
-_
-Stability Level	Obsolete Uncommitted
-.TE
-
-.SH SEE ALSO
-.sp
-.LP
-\fBclose\fR(2), \fBfcntl\fR(2), \fBioctl\fR(2), \fBopen\fR(2), \fBpoll\fR(2),
-\fBread\fR(2), \fBwrite\fR(2), \fBattributes\fR(5), \fBdsp\fR(7I),
-\fBstreamio\fR(7I)
-.SH BUGS
-.sp
-.LP
-Due to a feature of the STREAMS implementation, programs that are terminated or
+.El
+.Sh ERRORS
+An
+.Xr open 2
+call will fail if:
+.Bl -tag -width "EINTR"
+.It Er EBUSY
+The requested play or record access is busy and either the
+.Dv O_NDELAY
+or
+.Dv O_NONBLOCK
+flag was set in the
+.Xr open 2
+request.
+.It Er EINTR
+The requested play or record access is busy and a signal interrupted the
+.Xr open 2
+request.
+.El
+.Pp
+An
+.Xr ioctl 2
+call will fail if:
+.Bl -tag -width "EINVAL"
+.It Er EINVAL
+The parameter changes requested in the
+.Dv AUDIO_SETINFO
+ioctl are invalid or are not supported by the device.
+.El
+.Sh ARCHITECTURE
+SPARC
+X86
+.Sh INTERFACE STABILITY
+Obsolete Uncommitted
+.Sh SEE ALSO
+.Xr close 2 ,
+.Xr fcntl 2 ,
+.Xr ioctl 2 ,
+.Xr open 2 ,
+.Xr poll 2 ,
+.Xr read 2 ,
+.Xr write 2 ,
+.Xr attributes 5 ,
+.Xr dsp 7I ,
+.Xr streamio 7I
+.Sh BUGS
+Due to a feature of the
+.Sy STREAMS
+implementation, programs that are terminated or
 exit without closing the audio device may hang for a short period while audio
-output drains. In general, programs that produce audio output should catch the
-\fBSIGINT\fR signal and flush the output stream before exiting.
+output drains.
+In general, programs that produce audio output should catch the
+.Dv SIGINT
+signal and flush the output stream before exiting.
diff --git a/usr/src/man/man7i/cdio.7i b/usr/src/man/man7i/cdio.7i
index 5a10b12bb7..40a14ee94b 100644
--- a/usr/src/man/man7i/cdio.7i
+++ b/usr/src/man/man7i/cdio.7i
@@ -1,180 +1,189 @@
-'\" te
 .\"  Copyright (c) 2001, Sun Microsystems, Inc.  All Rights Reserved
-.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
-.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
-.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
-.TH CDIO 7I "Oct 4, 2001"
-.SH NAME
-cdio \- CD-ROM control operations
-.SH SYNOPSIS
-.LP
-.nf
-\fB#include <sys/cdio.h>\fR
-.fi
-
-.SH DESCRIPTION
-.sp
-.LP
-The set of \fBioctl\fR(2) commands described below are used to perform audio
-and \fBCD-ROM\fR specific operations. Basic to these \fBcdio\fR ioctl requests
-are the definitions in \fB<sys/cdio.h>\fR\&.
-.sp
-.LP
-Several \fBCD-ROM\fR specific commands can report addresses either in \fBLBA\fR
-(Logical Block Address) format or in \fBMSF\fR (Minute, Second, Frame) format.
-The \fBREAD HEADER\fR, \fBREAD SUBCHANNEL\fR, and \fBREAD TABLE OF CONTENTS\fR
+.\"  Copryright 2017, Joyent, Inc.
+.\" The contents of this file are subject to the terms of the
+.\" Common Development and Distribution License (the "License").
+.\" You may not use this file except in compliance with the License.
+.\"
+.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
+.\" or http://www.opensolaris.org/os/licensing.
+.\" See the License for the specific language governing permissions
+.\" and limitations under the License.
+.\"
+.\" When distributing Covered Code, include this CDDL HEADER in each
+.\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
+.\" If applicable, add the following below this CDDL HEADER, with the
+.\" fields enclosed by brackets "[]" replaced with your own identifying
+.\" information: Portions Copyright [yyyy] [name of copyright owner]
+.Dd October 22, 2017
+.Dt CDIO 7I
+.Os
+.Sh NAME
+.Nm cdio
+.Nd CD-ROM control operations
+.Sh SYNOPSIS
+.In sys/cdio.h
+.Sh DESCRIPTION
+The set of
+.Xr ioctl 2
+commands described below are used to perform audio and
+.Sy CD-ROM
+specific operations.
+Basic to these
+.Sy cdio
+ioctl requests are the definitions in
+.In sys/cdio.h .
+.Pp
+Several
+.Sy CD-ROM
+specific commands can report addresses either in
+.Sy LBA
+(Logical Block Address) format or in
+.Sy MSF
+(Minute, Second, Frame) format.
+The
+.Sy READ HEADER ,
+.Sy BREAD SUBCHANNEL ,
+and
+.Sy BREAD TABLE OF CONTENTS
 commands have this feature.
-.sp
-.LP
-\fBLBA\fR format represents the logical block address for the \fBCD-ROM\fR
+.Pp
+.Sy LBA
+format represents the logical block address for the
+.Sy CD-ROM
 absolute address field or for the offset from the beginning of the current
-track expressed as a number of logical blocks in a \fBCD-ROM\fR track relative
-address field. \fBMSF\fR format represents the physical address written on
-\fBCD-ROM\fR discs, expressed as a sector count relative to either the
+track expressed as a number of logical blocks in a
+.Sy CD-ROM
+track relative address field.
+.Sy MSF
+format represents the physical address written on
+.Sy CD-ROM
+discs, expressed as a sector count relative to either the
 beginning of the medium or the beginning of the current track.
-.SH IOCTLS
-.sp
-.LP
-The following \fBI/O\fR controls do not have any additional data passed into or
-received from them.
-.sp
-.ne 2
-.na
-\fB\fBCDROMSTART\fR\fR
-.ad
-.RS 18n
-This \fBioctl()\fR spins up the disc and seeks to the last address requested.
-.RE
-
-.sp
-.ne 2
-.na
-\fB\fBCDROMSTOP\fR\fR
-.ad
-.RS 18n
-This \fBioctl()\fR spins down the disc.
-.RE
-
-.sp
-.ne 2
-.na
-\fB\fBCDROMPAUSE\fR\fR
-.ad
-.RS 18n
-This \fBioctl()\fR pauses the current audio play operation.
-.RE
-
-.sp
-.ne 2
-.na
-\fB\fBCDROMRESUME\fR\fR
-.ad
-.RS 18n
-This \fBioctl()\fR resumes the paused audio play operation.
-.RE
-
-.sp
-.ne 2
-.na
-\fB\fBCDROMEJECT\fR\fR
-.ad
-.RS 18n
-This \fBioctl()\fR ejects the caddy with the disc.
-.RE
-
-.sp
-.ne 2
-.na
-\fB\fBCDROMCLOSETRAY\fR\fR
-.ad
-.RS 18n
-This \fBioctl()\fR closes the caddy with the disc.
-.RE
-
-.sp
-.LP
-The following \fBI/O\fR controls require a pointer to the structure for that
-\fBioctl()\fR, with data being passed into the \fBioctl()\fR.
-.sp
-.ne 2
-.na
-\fB\fBCDROMPLAYMSF\fR\fR
-.ad
-.RS 19n
-This \fBioctl()\fR command requests the drive to output the audio signals at
+.Sh IOCTLS
+The following
+.Sy I/O
+controls do not have any additional data passed into or received from them.
+.Bl -tag -width CDROMCLOSETRAY
+.It Dv CDROMSTART
+This
+.Xr ioctl 2
+spins up the disc and seeks to the last address requested.
+.It Dv CDROMSTOP
+This
+.Xr ioctl 2
+spins down the disc.
+.It Dv CDROMPAUSE
+This
+.Xr ioctl 2
+pauses the current audio play operation.
+.It Dv CDROMRESUME
+This
+.Xr ioctl 2
+resumes the paused audio play operation.
+.It Dv CDROMEJECT
+This
+.Xr ioctl 2
+ejects the caddy with the disc.
+.It Dv CDROMCLOSETRAY
+This
+.Xr ioctl 2
+closes the caddy with the disc.
+.El
+.Pp
+The following
+.Sy I/O
+controls require a pointer to the structure for that
+.Xr ioctl 2 ,
+with data being passed into the
+.Xr ioctl 2 .
+.Bl -tag -width CDROMPLAYTRKIND
+.It Dv CDROMPLAYMSF
+This
+.Xr ioctl 2
+command requests the drive to output the audio signals at
 the specified starting address and continue the audio play until the specified
-ending address is detected. The address is in \fBMSF\fR format. The third
-argument of this \fBioctl()\fR call is a pointer to the type \fBstruct
-cdrom_msf\fR.
-.sp
-.in +2
-.nf
+ending address is detected.
+The address is in
+.Sy MSF
+format.
+The third argument of this
+.Xr ioctl 2
+call is a pointer to the type
+.Vt "struct cdrom_msf" .
+.Bd -literal -offset 2n
 /*
  * definition of play audio msf structure
  */
 struct cdrom_msf {
-	unsigned char	cdmsf_min0;	/* starting minute*/
-	unsigned char	cdmsf_sec0;	/* starting second*/
-	unsigned char	cdmsf_frame0;	/*starting frame*/
-	unsigned char	cdmsf_min1;	/* ending minute */
-	unsigned char	cdmsf_sec1;	/* ending second */
-	unsigned char	cdmsf_frame1;	/* ending frame */
+	/* starting minute */
+	unsigned char	cdmsf_min0;
+	/* starting second */
+	unsigned char	cdmsf_sec0;
+	/* starting frame */
+	unsigned char	cdmsf_frame0;
+	/* ending minute */
+	unsigned char	cdmsf_min1;
+	/* ending second */
+	unsigned char	cdmsf_sec1;
+	/* ending frame */
+	unsigned char	cdmsf_frame1;
 };
-.fi
-.in -2
-
-The \fBCDROMREADTOCENTRY\fR ioctl request may be used to obtain the start time
-for a track. An approximation of the finish time can be obtained by using the
-\fBCDROMREADTOCENTRY\fR ioctl request to retrieve the start time of the track
+.Ed
+.Pp
+The
+.Dv CDROMREADTOCENTRY
+ioctl request may be used to obtain the start time for a track.
+An approximation of the finish time can be obtained by using the
+.Dv CDROMREADTOCENTRY
+ioctl request to retrieve the start time of the track
 following the current track.
-.sp
+.Pp
 The leadout track is the next consecutive track after the last audio track.
 Hence, the start time of the leadout track may be used as the effective finish
 time of the  last audio track.
-.RE
-
-.sp
-.ne 2
-.na
-\fB\fBCDROMPLAYTRKIND\fR\fR
-.ad
-.RS 19n
-This \fBioctl()\fR command is similar to  \fBCDROMPLAYMSF\fR. The starting and
-ending address is in track/index format. The third argument of the
-\fBioctl()\fR call is a pointer to the type \fBstruct cdrom_ti\fR.
-.sp
-.in +2
-.nf
+.It Dv CDROMPLAYTRKIND
+This
+.Xr ioctl 2
+command is similar to
+.Dv CDROMPLAYMSF .
+The starting and ending address is in track/index format.
+The third argument of the
+.Xr ioctl 2
+call is a pointer to the type
+.Vt "struct cdrom_ti" .
+.Bd -literal -offset 2n
 /*
  * definition of play audio track/index structure
  */
 struct cdrom_ti {
-	unsigned char	cdti_trk0;	/* starting track*/
-	unsigned char	cdti_ind0;	/* starting index*/
-	unsigned char	cdti_trk1;	/* ending track */
-	unsigned char	cdti_ind1;	/* ending index */
+	/* starting track */
+	unsigned char	cdti_trk0;
+	/* starting index */
+	unsigned char	cdti_ind0;
+	/* ending track */
+	unsigned char	cdti_trk1;
+	/* ending index */
+	unsigned char	cdti_ind1;
 };
-.fi
-.in -2
-
-.RE
-
-.sp
-.ne 2
-.na
-\fB\fBCDROMVOLCTRL\fR\fR
-.ad
-.RS 19n
-This \fBioctl()\fR command controls the audio output level. The \fBSCSI\fR
-command allows the control of up to four channels. The current implementation
-of the supported \fBCD-ROM\fR drive only uses channel 0 and channel 1. The
-valid values of volume control are between 0x00 and 0xFF, with a value of 0xFF
-indicating maximum volume. The third argument of the \fBioctl()\fR call is a
-pointer to \fBstruct\fR \fBcdrom_volctrl\fR which contains the output volume
-values.
-.sp
-.in +2
-.nf
+.Ed
+.It Dv CDROMVOLCTRL
+This
+.Xr ioctl 2
+command controls the audio output level.
+The
+.Sy SCSI
+command allows the control of up to four channels.
+The current implementation of the supported
+.Sy CD-ROM
+drive only uses channel 0 and channel 1.
+The valid values of volume control are between 0x00 and 0xFF, with a value of
+0xFF indicating maximum volume.
+The third argument of the
+.Xr ioctl 2
+call is a pointer to
+.Vt "struct cdrom_volctrl"
+which contains the output volume values.
+.Bd -literal -offset 2n
 /*
  * definition of audio volume control structure
  */
@@ -184,63 +193,61 @@ struct cdrom_volctrl {
 	unsigned char	channel2;
 	unsigned char	channel3;
 };
-.fi
-.in -2
-
-.RE
-
-.sp
-.LP
-The following \fBI/O\fR controls take a pointer that will have data returned to
-the user program from the \fBCD-ROM\fR driver.
-.sp
-.ne 2
-.na
-\fB\fBCDROMREADTOCHDR\fR\fR
-.ad
-.RS 21n
-This \fBioctl()\fR command returns the header of the  table of contents (TOC).
-The header consists of the starting tracking number and the ending track number
-of the disc. These two numbers are returned through a pointer of  \fBstruct
-cdrom_tochdr\fR. While the disc can start at any number, all tracks between the
+.Ed
+.El
+.Pp
+The following
+.Sy I/O
+controls take a pointer that will have data returned to
+the user program from the
+.Sy CD-ROM
+driver.
+.Bl -tag -width CDROMREADOFFSET
+.It Dv CDROMREADTOCHDR
+This
+.Xr ioctl 2
+command returns the header of the  table of contents (TOC).
+The header consists of the starting track number and the ending track number
+of the disc.
+These two numbers are returned through a pointer of
+.Vt "struct cdrom_tochdr" .
+While the disc can start at any number, all tracks between the
 first and last tracks are in contiguous ascending order.
-.sp
-.in +2
-.nf
+.Bd -literal -offset 2n
 /*
  * definition of read toc header structure
  */
 struct cdrom_tochdr {
-	unsigned char	cdth_trk0;	/* starting track*/
-	unsigned char	cdth_trk1;	/* ending track*/
+	unsigned char	cdth_trk0; /* starting track */
+	unsigned char	cdth_trk1; /* ending track */
 };
-.fi
-.in -2
-
-.RE
-
-.sp
-.ne 2
-.na
-\fB\fBCDROMREADTOCENTRY\fR\fR
-.ad
-.RS 21n
-This \fBioctl()\fR command returns the information of a specified track. The
-third argument of the function call is a pointer to the type \fBstruct
-cdrom_tocentry\fR. The caller needs to supply the track number and the address
-format. This command will return a 4-bit  \fBadr\fR field, a 4-bit \fBctrl\fR
-field, the starting address in \fBMSF\fR format or \fBLBA\fR format, and the
-data mode if the track is a data track. The \fBctrl\fR field specifies whether
-the track is data or audio.
-.sp
-.in +2
-.nf
+.Ed
+.It Dv CDROMREADTOCENTRY
+This
+.Xr ioctl 2
+command returns the information of a specified track.
+The third argument of the function call is a pointer to the type
+.Vt "struct cdrom_tocentry" .
+The caller needs to supply the track number and the address format.
+This command will return a 4-bit
+.Sy adr
+field, a 4-bit
+.Sy ctrl
+field, the starting address in
+.Sy MSF
+format or
+.Sy LBA
+format, and the data mode if the track is a data track.
+The
+.Sy ctrl
+field specifies whether the track is data or audio.
+.Bd -literal -offset 2n
 /*
  * definition of read toc entry structure
  */
 struct cdrom_tocentry {
 	unsigned char  cdte_track;
-	unsigned char  cdte_adr   :4;
+	unsigned char  cdte_adr    :4;
 	unsigned char  cdte_ctrl   :4;
 	unsigned char  cdte_format;
 	union {
@@ -253,178 +260,126 @@ struct cdrom_tocentry {
 	} cdte_addr;
 	unsigned char  cdte_datamode;
 };
-.fi
-.in -2
-
+.Ed
+.Pp
 To get the information from the leadout track, the following value is
-appropriate for the \fBcdte_track\fR field:
-.sp
-.ne 2
-.na
-\fB\fBCDROM_LEADOUT\fR\fR
-.ad
-.RS 17n
+appropriate for the
+.Fa cdte_track
+field:
+.\" These next few lists all use the same width so they align better
+.Bl -tag -offset indent -width CDROM_DATA_TRACK
+.It Dv CDROM_LEADOUT
 Leadout track
-.RE
-
+.El
+.Pp
 To get the information from the data track, the following value is appropriate
-for the \fBcdte_ctrl\fR field:
-.sp
-.ne 2
-.na
-\fB\fBCDROM_DATA_TRACK\fR\fR
-.ad
-.RS 20n
+for the
+.Fa cdte_ctrl
+field:
+.Bl -tag -offset indent -width CDROM_DATA_TRACK
+.It Dv CDROM_DATA_TRACK
 Data track
-.RE
-
-The following values are appropriate for the  \fBcdte_format\fR field:
-.sp
-.ne 2
-.na
-\fB\fBCDROM_LBA\fR\fR
-.ad
-.RS 13n
-\fBLBA\fR format
-.RE
-
-.sp
-.ne 2
-.na
-\fB\fBCDROM_MSF\fR\fR
-.ad
-.RS 13n
-\fBMSF\fR format
-.RE
-
-.RE
-
-.sp
-.ne 2
-.na
-\fB\fBCDROMSUBCHNL\fR\fR
-.ad
-.RS 21n
-This \fBioctl()\fR command reads the Q sub-channel data of the current block.
-The subchannel data includes track number, index number, absolute \fBCD-ROM\fR
-address, track relative  \fBCD-ROM\fR address, control data and audio status.
-All information is returned through a pointer to  \fBstruct cdrom_subchnl\fR.
+.El
+.Pp
+The following values are appropriate for the
+.Fa cdte_format
+field:
+.Bl -tag -offset indent -width CDROM_DATA_TRACK
+.It Dv CDROM_LBA
+.Sy LBA
+format
+.It Dv CDROM_MSF
+.Sy MSF
+format
+.El
+.It Dv CDROMSUBCHNL
+This
+.Xr ioctl 2
+command reads the Q sub-channel data of the current block.
+The subchannel data includes track number, index number, absolute
+.Sy CD-ROM
+address, track relative
+.Sy CD-ROM
+address, control data and audio status.
+All information is returned through a pointer to
+.Vt "struct cdrom_subchnl" .
 The caller needs to supply the address format for the returned address.
-.sp
-.in +2
-.nf
+.Bd -literal -offset 2n
 struct cdrom_subchnl {
 	unsigned char	cdsc_format;
 	unsigned char	cdsc_audiostatus;
-	unsigned char	cdsc_adr:	4;
-	unsigned char	cdsc_ctrl:	4;
+	unsigned char	cdsc_adr      :4;
+	unsigned char	cdsc_ctrl     :4;
 	unsigned char	cdsc_trk;
 	unsigned char	cdsc_ind;
 	union {
 		struct {
-			unsigned char 	minute;
-			unsigned char 	second;
-			unsigned char 	frame;
+			unsigned char	minute;
+			unsigned char	second;
+			unsigned char	frame;
 		} msf;
 		int	lba;
 	} cdsc_absaddr;
 	union {
 		struct {
-			unsigned char 	minute;
-			unsigned char 	second;
-			unsigned char 	frame;
+			unsigned char	minute;
+			unsigned char	second;
+			unsigned char	frame;
 		} msf;
 		int	lba;
 	} cdsc_reladdr;
 };
-.fi
-.in -2
-
+.Ed
+.Pp
 The following values are valid for the audio status field returned from
-\fBREAD\fR \fBSUBCHANNEL\fR command:
-.sp
-.ne 2
-.na
-\fB\fBCDROM_AUDIO_INVALID\fR\fR
-.ad
-.RS 25n
+.Sy "READ SUBCHANNEL"
+command:
+.Bl -tag -width CDROM_AUDIO_NO_STATUS
+.It Dv CDROM_AUDIO_INVALID
 Audio status not supported.
-.RE
-
-.sp
-.ne 2
-.na
-\fB\fBCDROM_AUDIO_PLAY\fR\fR
-.ad
-.RS 25n
+.It Dv CDROM_AUDIO_PLAY
 Audio play operation in progress.
-.RE
-
-.sp
-.ne 2
-.na
-\fB\fBCDROM_AUDIO_PAUSED\fR\fR
-.ad
-.RS 25n
+.It Dv CDROM_AUDIO_PAUSED
 Audio play operation paused.
-.RE
-
-.sp
-.ne 2
-.na
-\fB\fBCDROM_AUDIO_COMPLETED\fR\fR
-.ad
-.RS 25n
+.It Dv CDROM_AUDIO_COMPLETED
 Audio play successfully completed.
-.RE
-
-.sp
-.ne 2
-.na
-\fB\fBCDROM_AUDIO_ERROR\fR\fR
-.ad
-.RS 25n
+.It Dv CDROM_AUDIO_ERROR
 Audio play stopped due to error.
-.RE
-
-.sp
-.ne 2
-.na
-\fB\fBCDROM_AUDIO_NO_STATUS\fR\fR
-.ad
-.RS 25n
+.It Dv CDROM_AUDIO_NO_STATUS
 No current audio status to return.
-.RE
-
-.RE
-
-.sp
-.ne 2
-.na
-\fB\fBCDROMREADOFFSET\fR\fR
-.ad
-.RS 21n
-This \fBioctl()\fR command returns the absolute \fBCD-ROM\fR address of the
-first track in the last session of a Multi-Session \fBCD-ROM\fR. The third
-argument of the \fBioctl()\fR call is a pointer to an \fBint\fR.
-.RE
-
-.sp
-.ne 2
-.na
-\fB\fBCDROMCDDA\fR\fR
-.ad
-.RS 21n
-This \fBioctl()\fR command returns the \fBCD-DA\fR data or the subcode data.
-The third argument of the \fBioctl()\fR call is a pointer to the type \fBstruct
-cdrom_cdda\fR. In addition to allocating memory and supplying its address, the
+.El
+.It Dv CDROMREADOFFSET
+This
+.Xr ioctl 2
+command returns the absolute
+.Sy CD-ROM
+address of the first track in the last session of a Multi-Session
+.Sy CD-ROM .
+The third argument of the
+.Xr ioctl 2
+call is a pointer to an
+.Vt int .
+.It Dv CDROMCDDA
+This
+.Xr ioctl 2
+command returns the
+.Sy CD-DA
+data or the subcode data.
+The third argument of the
+.Xr ioctl 2
+call is a pointer to the type
+.Vt "struct cdrom_cdda" .
+In addition to allocating memory and supplying its address, the
 caller needs to supply the starting address of the data, the transfer length in
-terms of the number of blocks to be transferred, and the subcode options. The
-caller also needs to issue the \fBCDROMREADTOCENTRY\fR \fBioctl()\fR to find
-out which tracks contain \fBCD-DA\fR data before issuing this \fBioctl()\fR.
-.sp
-.in +2
-.nf
+terms of the number of blocks to be transferred, and the subcode options.
+The caller also needs to issue the
+.Dv CDROMREADTOCENTRY
+.Xr ioctl 2
+to find out which tracks contain
+.Sy CD-DA
+data before issuing this
+.Xr ioctl 2 .
+.Bd -literal -offset 2n
 /*
  * Definition of CD-DA structure
  */
@@ -434,113 +389,72 @@ struct cdrom_cdda {
 	caddr_t		cdda_data;
 	unsigned char	cdda_subcode;
 };
-.fi
-.in -2
-
-\fBcdda_addr\fR signifies the starting logical block address.
-.sp
-\fBcdda_length\fR signifies the transfer length in blocks. The length of the
-block depends on the \fBcdda_subcode\fR selection, which is explained below.
-.sp
-To get the subcode information related to  \fBCD-DA\fR data, the following
-values are appropriate for the  \fBcdda_subcode\fR field:
-.sp
-.ne 2
-.na
-\fB\fBCDROM_DA_NO_SUBCODE\fR\fR
-.ad
-.RS 25n
-\fBCD-DA\fR data with no subcode.
-.RE
-
-.sp
-.ne 2
-.na
-\fB\fBCDROM_DA_SUBQ\fR\fR
-.ad
-.RS 25n
-\fBCD-DA\fR data with sub Q code.
-.RE
-
-.sp
-.ne 2
-.na
-\fB\fBCDROM_DA_ALL_SUBCODE\fR\fR
-.ad
-.RS 25n
-\fBCD-DA\fR data with all subcode.
-.RE
-
-.sp
-.ne 2
-.na
-\fB\fBCDROM_DA_SUBCODE_ONLY\fR\fR
-.ad
-.RS 25n
+.Ed
+.Pp
+.Sy cdda_addr
+signifies the starting logical block address.
+.Sy cdda_length
+signifies the transfer length in blocks.
+The length of the block depends on the
+.Sy cdda_subcode
+selection, which is explained below.
+To get the subcode information related to
+.Sy CD-DA
+data, the following values are appropriate for the
+.Sy cdda_subcode
+field:
+.Bl -tag -width CDROM_DA_SUBCODE_ONLY
+.It Sy CDROM_DA_NO_SUBCODE
+.Sy CD-DA
+data with no subcode.
+.It Sy CDROM_DA_SUBQ
+.Sy CD-DA
+data with sub Q code.
+.It Sy CDROM_DA_ALL_SUBCODE
+.Sy CD-DA
+data with all subcode.
+.It Sy CDROM_DA_SUBCODE_ONLY
 All subcode only.
-.RE
-
-To allocate the memory related to  \fBCD-DA\fR and/or subcode data, the
+.El
+.Pp
+To allocate the memory related to
+.Sy CD-DA
+and/or subcode data, the
 following values are appropriate for each data  block transferred:
-.sp
-.ne 2
-.na
-\fB\fBCD-DA\fR data with no subcode\fR
-.ad
-.sp .6
-.RS 4n
+.Bl -tag -width "CD-DA data with all subcode"
+.It Sy CD-DA data with no subcode
 2352 bytes
-.RE
-
-.sp
-.ne 2
-.na
-\fB\fBCD-DA\fR data with sub Q code\fR
-.ad
-.sp .6
-.RS 4n
+.It Sy CD-DA data with sub Q code
 2368 bytes
-.RE
-
-.sp
-.ne 2
-.na
-\fB\fBCD-DA\fR data with all subcode\fR
-.ad
-.sp .6
-.RS 4n
+.It Sy CD-DA data with all subcode
 2448 bytes
-.RE
-
-.sp
-.ne 2
-.na
-\fBAll subcode only\fR
-.ad
-.sp .6
-.RS 4n
+.It Sy "All subcode only"
 96 bytes
-.RE
-
-.RE
-
-.sp
-.ne 2
-.na
-\fB\fBCDROMCDXA\fR\fR
-.ad
-.RS 21n
-This \fBioctl()\fR command returns the \fBCD-ROM\fR \fBXA\fR (CD-ROM Extended
-Architecture) data according to  \fBCD-ROM\fR \fBXA\fR format. The third
-argument of the \fBioctl()\fR call is a pointer to the type \fBstruct
-cdrom_cdxa\fR. In addition to allocating memory and supplying its address, the
+.El
+.It Dv CDROMCDXA
+This
+.Xr ioctl 2
+command returns the
+.Sy "CD-ROM XA"
+(CD-ROM Extended Architecture) data according to
+.Sy "CD-ROM XA"
+format.
+The third argument of the
+.Xr ioctl 2
+call is a pointer to the type
+.Vt "struct cdrom_cdxa" .
+In addition to allocating memory and supplying its address, the
 caller needs  to supply the starting address of the data, the transfer length
-in terms of number of blocks, and the format. The caller also needs to issue
-the \fBCDROMREADTOCENTRY\fR \fBioctl()\fR to find out which tracks contain
-\fBCD-ROM\fR \fBXA\fR data before issuing this \fBioctl()\fR.
-.sp
-.in +2
-.nf
+in terms of number of blocks, and the format.
+The caller also needs to issue
+the
+.Sy CDROMREADTOCENTRY
+.Xr ioctl 2
+to find out which tracks contain
+.Sy "CD-ROM XA"
+data before issuing this
+.Xr ioctl 2 .
+.Bd -literal -offset 2n
 /*
  * Definition of CD-ROM XA structure
  */
@@ -550,88 +464,52 @@ struct cdrom_cdxa {
 	caddr_t		cdxa_data;
 	unsigned char	cdxa_format;
 };
-.fi
-.in -2
-
-To get the proper  \fBCD-ROM\fR \fBXA\fR data, the following values are
-appropriate for the  \fBcdxa_format\fR field:
-.sp
-.ne 2
-.na
-\fB\fBCDROM_XA_DATA\fR\fR
-.ad
-.RS 25n
-\fBCD-ROM\fR \fBXA\fR data only
-.RE
-
-.sp
-.ne 2
-.na
-\fB\fBCDROM_XA_SECTOR_DATA\fR\fR
-.ad
-.RS 25n
-\fBCD-ROM\fR \fBXA\fR all sector data
-.RE
-
-.sp
-.ne 2
-.na
-\fB\fBCDROM_XA_DATA_W_ERROR\fR\fR
-.ad
-.RS 25n
-\fBCD-ROM\fR \fBXA\fR data with error flags data
-.RE
-
-To allocate the memory related to  \fBCD-ROM\fR \fBXA\fR format, the following
-values are appropriate for each data  block transferred:
-.sp
-.ne 2
-.na
-\fB\fBCD-ROM XA\fR data only\fR
-.ad
-.sp .6
-.RS 4n
+.Ed
+.Pp
+To get the proper
+.Sy "CD-ROM XA"
+data, the following values are appropriate for the
+.Fa cdxa_format
+field:
+.Bl -tag -width CDROM_XA_DATA_W_ERROR
+.It Dv CDROM_XA_DATA
+.Sy "CD-ROM XA"
+data only
+.It Dv CDROM_XA_SECTOR_DATA
+.Sy "CD-ROM XA"
+all sector data
+.It Dv CDROM_XA_DATA_W_ERROR
+.Sy CD-ROM \fBXA\fR
+data with error flags data
+.El
+.Pp
+To allocate the memory related to
+.Sy "CD-ROM XA"
+format, the following values are appropriate for each data  block transferred:
+.Bl -tag -width "CD-ROM XA data with error flags data"
+.It Sy "CD-ROM XA" data only
 2048 bytes
-.RE
-
-.sp
-.ne 2
-.na
-\fB\fBCD-ROM XA\fR all sector data\fR
-.ad
-.sp .6
-.RS 4n
+.It Sy "CD-ROM XA" all sector data
 2352 bytes
-.RE
-
-.sp
-.ne 2
-.na
-\fB\fBCD-ROM XA\fR data with error flags data\fR
-.ad
-.sp .6
-.RS 4n
+.It Sy "CD-ROM XA" data with error flags data
 2646 bytes
-.RE
-
-.RE
-
-.sp
-.ne 2
-.na
-\fB\fBCDROMSUBCODE\fR\fR
-.ad
-.RS 21n
-This  \fBioctl()\fR command returns raw subcode data (subcodes P ~ W are
-described in  the "Red Book," see \fBSEE ALSO\fR) to the initiator while the
-target is  playing audio. The third argument of the  \fBioctl()\fR call is a
-pointer to the type \fBstruct cdrom_subcode\fR. The caller needs to supply the
-transfer length in terms of number of blocks and allocate memory  for subcode
-data. The memory allocated should be a multiple of 96  bytes depending on the
+.El
+.It Dv CDROMSUBCODE
+This
+.Xr ioctl 2
+command returns raw subcode data (subcodes P ~ W are
+described in the "Red Book," see
+.Sx SEE ALSO )
+to the initiator while the target is playing audio.
+The third argument of the
+.Xr ioctl 2
+call is a pointer to the type
+.Vt "struct cdrom_subcode" .
+The caller needs to supply the transfer length in terms of number of blocks and
+allocate memory for subcode data.
+The memory allocated should be a multiple of 96 bytes depending on the
 transfer length.
-.sp
-.in +2
-.nf
+.Bd -literal -offset 2n
 /*
  * Definition of subcode structure
  */
@@ -639,252 +517,176 @@ struct cdrom_subcode {
 	unsigned int	cdsc_length;
 	caddr_t		cdsc_addr;
 };
-.fi
-.in -2
-
-.RE
-
-.sp
-.LP
-The next group of \fBI/O\fR controls get and set various \fBCD-ROM\fR drive
-parameters.
-.sp
-.ne 2
-.na
-\fB\fBCDROMGBLKMODE\fR\fR
-.ad
-.RS 18n
-This  \fBioctl()\fR command returns the current block size used by the
-\fBCD-ROM\fR drive.  The third argument of the \fBioctl()\fR call is a pointer
-to an integer.
-.RE
-
-.sp
-.ne 2
-.na
-\fB\fBCDROMSBLKMODE\fR\fR
-.ad
-.RS 18n
-This  \fBioctl()\fR command requests the \fBCD-ROM\fR drive to change from the
-current block size to the requested block size. The third argument of the
-\fBioctl()\fR call is an integer which contains the requested block size.
-.sp
-This \fBioctl()\fR command operates in exclusive-use mode only. The caller must
-ensure  that no other processes can operate on the same  \fBCD-ROM\fR device
-before issuing this  \fBioctl()\fR. \fBread\fR(2) behavior subsequent to this
-\fBioctl()\fR remains the same: the caller is still constrained to read the raw
+.Ed
+.El
+.Pp
+The next group of
+.Sy I/O
+controls get and set various
+.Sy CD-ROM
+drive parameters.
+.Bl -tag -width CDROMGDRVSPEED
+.It Dv CDROMGBLKMODE
+This
+.Xr ioctl 2
+command returns the current block size used by the
+.Sy CD-ROM
+drive.
+The third argument of the
+.Xr ioctl 2
+call is a pointer to an integer.
+.It Dv CDROMSBLKMODE
+This
+.Xr ioctl 2
+command requests the
+.Sy CD-ROM
+drive to change from the current block size to the requested block size.
+The third argument of the
+.Xr ioctl 2
+call is an integer which contains the requested block size.
+This
+.Xr ioctl 2
+command operates in exclusive-use mode only.
+The caller must ensure  that no other processes can operate on the same
+.Sy CD-ROM
+device before issuing this
+.Xr ioctl 2 .
+.Xr read 2
+behavior subsequent to this
+.Xr ioctl 2
+remains the same: the caller is still constrained to read the raw
 device on block boundaries and in block multiples.
-.sp
 To set the proper block size, the following values are appropriate:
-.sp
-.ne 2
-.na
-\fB\fBCDROM_BLK_512\fR\fR
-.ad
-.RS 18n
+.Bl -tag -width CDROM_BLK_1024
+.It Dv CDROM_BLK_512
 512 bytes
-.RE
-
-.sp
-.ne 2
-.na
-\fB\fBCDROM_BLK_1024\fR\fR
-.ad
-.RS 18n
+.It Dv CDROM_BLK_1024
 1024 bytes
-.RE
-
-.sp
-.ne 2
-.na
-\fB\fBCDROM_BLK_2048\fR\fR
-.ad
-.RS 18n
+.It Dv CDROM_BLK_2048
 2048 bytes
-.RE
-
-.sp
-.ne 2
-.na
-\fB\fBCDROM_BLK_2056\fR\fR
-.ad
-.RS 18n
+.It Dv CDROM_BLK_2056
 2056 bytes
-.RE
-
-.sp
-.ne 2
-.na
-\fB\fBCDROM_BLK_2336\fR\fR
-.ad
-.RS 18n
+.It Dv CDROM_BLK_2336
 2336 bytes
-.RE
-
-.sp
-.ne 2
-.na
-\fB\fBCDROM_BLK_2340\fR\fR
-.ad
-.RS 18n
+.It Dv CDROM_BLK_2340
 2340 bytes
-.RE
-
-.sp
-.ne 2
-.na
-\fB\fBCDROM_BLK_2352\fR\fR
-.ad
-.RS 18n
+.It Dv CDROM_BLK_2352
 2352 bytes
-.RE
-
-.sp
-.ne 2
-.na
-\fB\fBCDROM_BLK_2368\fR\fR
-.ad
-.RS 18n
+.It Dv CDROM_BLK_2368
 2368 bytes
-.RE
-
-.sp
-.ne 2
-.na
-\fB\fBCDROM_BLK_2448\fR\fR
-.ad
-.RS 18n
+.It Dv CDROM_BLK_2448
 2448 bytes
-.RE
-
-.sp
-.ne 2
-.na
-\fB\fBCDROM_BLK_2646\fR\fR
-.ad
-.RS 18n
+.It Dv CDROM_BLK_2646
 2646 bytes
-.RE
-
-.sp
-.ne 2
-.na
-\fB\fBCDROM_BLK_2647\fR\fR
-.ad
-.RS 18n
+.It Dv CDROM_BLK_2647
 2647 bytes
-.RE
-
-.RE
-
-.sp
-.ne 2
-.na
-\fB\fBCDROMGDRVSPEED\fR\fR
-.ad
-.RS 18n
-This \fBioctl()\fR command returns the current \fBCD-ROM\fR drive speed. The
-third argument of the  \fBioctl()\fR call is a pointer to an integer.
-.RE
-
-.sp
-.ne 2
-.na
-\fB\fBCDROMSDRVSPEED\fR\fR
-.ad
-.RS 18n
-This  \fBioctl()\fR command requests the \fBCD-ROM\fR drive to change the
-current drive speed to the requested drive speed. This speed setting is only
-applicable when reading data areas. The third argument of the  \fBioctl()\fR is
-an integer which contains the requested drive speed.
-.sp
-To set the  \fBCD-ROM\fR drive to the proper speed, the following values are
-appropriate:
-.sp
-.ne 2
-.na
-\fB\fBCDROM_NORMAL_SPEED\fR\fR
-.ad
-.RS 23n
+.El
+.It Dv CDROMGDRVSPEED
+This
+.Xr ioctl 2
+command returns the current
+.Sy CD-ROM
+drive speed.
+The third argument of the
+.Xr ioctl 2
+call is a pointer to an integer.
+.It Dv CDROMSDRVSPEED
+This
+.Xr ioctl 2
+command requests the
+.Sy CD-ROM
+drive to change the current drive speed to the requested drive speed.
+This speed setting is only applicable when reading data areas.
+The third argument of the
+.Xr ioctl 2
+is an integer which contains the requested drive speed.
+To set the
+.Sy CD-ROM
+drive to the proper speed, the following values are appropriate:
+.Bl -tag -width CDROM_MAXIMUM_SPEED
+.It Dv CDROM_NORMAL_SPEED
 150k/second
-.RE
-
-.sp
-.ne 2
-.na
-\fB\fBCDROM_DOUBLE_SPEED\fR\fR
-.ad
-.RS 23n
+.It Dv CDROM_DOUBLE_SPEED
 300k/second
-.RE
-
-.sp
-.ne 2
-.na
-\fB\fBCDROM_QUAD_SPEED\fR\fR
-.ad
-.RS 23n
+.It Dv CDROM_QUAD_SPEED
 600k/second
-.RE
-
-.sp
-.ne 2
-.na
-\fB\fBCDROM_MAXIMUM_SPEED\fR\fR
-.ad
-.RS 23n
-300k/second (2x drive) 600k/second (4x drive)
-.RE
-
-Note that these numbers are only accurate when reading 2048 byte blocks. The
-\fBCD-ROM\fR drive will automatically switch to normal speed when playing audio
-tracks  and will switch back to the speed setting when accessing data.
-.RE
-
-.SH SEE ALSO
-.sp
-.LP
-\fBioctl\fR(2), \fBread\fR(2)
-.sp
-.LP
-N. V. Phillips and Sony Corporation, \fISystem Description Compact Disc Digital
-Audio\fR, ("Red Book").
-.sp
-.LP
-N. V. Phillips and Sony Corporation, \fISystem Description of Compact Disc Read
-Only Memory\fR, ("Yellow Book").
-.sp
-.LP
-N. V. Phillips, Microsoft, and Sony Corporation, \fISystem Description CD-ROM
-XA\fR, 1991.
-.sp
-.LP
-\fIVolume and File Structure of CD-ROM for Information Interchange\fR, ISO
-9660:1988(E).
-.sp
-.LP
-\fISCSI-2\fR \fIStandard,\fR \fIdocument\fR \fIX3T9.2/86-109\fR
-.sp
-.LP
-\fISCSI Multimedia Commands, Version 2 (MMC-2)\fR
-.SH NOTES
-.sp
-.LP
-The  \fBCDROMCDDA\fR, \fBCDROMCDXA\fR, \fBCDROMSUBCODE\fR,
-\fBCDROMGDRVSPEED\fR, \fBCDROMSDRVSPEED\fR, and some of the block sizes in
-\fBCDROMSBLKMODE\fR are designed for new Sun-supported \fBCD-ROM\fR drives and
-might not work on some of the older \fBCD-ROM\fR drives.
-.sp
-.LP
-CDROMCDDA, CDROMCDXA and CDROMSUBCODE will return error if the transfer length
-exceeds valid limits as determined appropriate. Example: for MMC-2 drives,
-length can not exceed 3 bytes (i.e. 0xffffff).  The same restriction is
-enforced for older, pre-MMC-2 drives, as no limit was published for these older
-drives (and 3 bytes is reasonable for all media). Note that enforcing this
-limit does not imply that values passed in below this limit will actually be
-applicable for each and every piece of media.
-.sp
-.LP
+.It Dv CDROM_MAXIMUM_SPEED
+300k/second (2x drive)
+.Pp
+600k/second (4x drive)
+.El
+.Pp
+Note that these numbers are only accurate when reading 2048 byte blocks.
+The
+.Sy CD-ROM
+drive will automatically switch to normal speed when playing audio
+tracks and will switch back to the speed setting when accessing data.
+.El
+.Sh ARCHITECTURE
+All
+.Sh INTERFACE STABILITY
+Uncommitted
+.Sh SEE ALSO
+.Xr ioctl 2 ,
+.Xr read 2 ,
+.Xr attributes 5
+.Rs
+.%Q N. V. Phillips
+.%Q Sony Corporation
+.%B System Description Compact Disc Digital Audio
+.%O ("Red Book")
+.Re
+.Rs
+.%Q N. V. Phillips
+.%Q Sony Corporation
+.%B System Description of Compact Disc Read Only Memory
+.%O ("Yellow Book")
+.Re
+.Rs
+.%Q N. V. Phillips
+.%Q Microsoft
+.%Q Sony Corporation
+.%B System Description CD-ROM XA
+.%D 1991
+.Re
+.Rs
+.%T Volume and File Structure of CD-ROM for Information Interchange
+.%N ISO 9660:1988(E)
+.Re
+.Rs
+.%T SCSI-2 Standard
+.%N document X3T9.2/86-109
+.Re
+.Rs
+.%T SCSI Multimedia Commands, Version 2 (MMC-2)
+.Re
+.Sh NOTES
+The
+.Dv CDROMCDDA ,
+.Dv CDROMCDXA ,
+.Dv CDROMSUBCODE ,
+.Dv CDROMGDRVSPEED ,
+.Dv CDROMSDRVSPEED ,
+and some of the block sizes in
+.Dv CDROMSBLKMODE
+are designed for new Sun-supported
+.Sy CD-ROM
+drives and might not work on some of the older
+.Sy CD-ROM
+drives.
+.Pp
+.Dv CDROMCDDA ,
+.Dv CDROMCDXA ,
+and
+.Dv CDROMSUBCODE
+will return error if the transfer length exceeds valid limits as determined appropriate.
+Example: for MMC-2 drives, length can not exceed 3 bytes (i\&.e\&. 0xffffff).
+The same restriction is enforced for older, pre-MMC-2 drives, as no limit was
+published for these older drives (and 3 bytes is reasonable for all media).
+Note that enforcing this limit does not imply that values passed in below this
+limit will actually be applicable for each and every piece of media.
+.Pp
 The interface to this device is preliminary and subject to change in future
-releases. Programs should be written in  a modular fashion so that future
+releases.
+Programs should be written in a modular fashion so that future
 changes can be easily incorporated.
diff --git a/usr/src/man/man7i/dsp.7i b/usr/src/man/man7i/dsp.7i
index d4cee9fba3..1c0fa9fc07 100644
--- a/usr/src/man/man7i/dsp.7i
+++ b/usr/src/man/man7i/dsp.7i
@@ -1,483 +1,488 @@
-'\" te
 .\"  Copyright (c) 2009 Sun Microsystems, Inc. All rights reserved.
-.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.
-.\"  See the License for the specific language governing permissions and limitations under the License. When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the
-.\" fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
-.TH DSP 7I "May 11, 2009"
-.SH NAME
-dsp \- generic audio device interface
-.SH SYNOPSIS
-.LP
-.nf
-\fB#include\fR \fB<sys/soundcard.h>\fR
-.fi
-
-.SH DESCRIPTION
-.sp
-.LP
-To record audio input, applications \fBopen()\fR the appropriate device and
-read data from it using the \fBread()\fR system call. Similarly, sound data is
-queued to the audio output port by using the \fBwrite\fR(2) system call. Device
-configuration is performed using the \fBioctl\fR(2) interface.
-.sp
-.LP
+.\" Copyright 2018, Joyent, Inc.
+.\" The contents of this file are subject to the terms of the
+.\" Common Development and Distribution License (the "License").
+.\" You may not use this file except in compliance with the License.
+.\"
+.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
+.\" or http://www.opensolaris.org/os/licensing.
+.\" See the License for the specific language governing permissions
+.\" and limitations under the License.
+.\"
+.\" When distributing Covered Code, include this CDDL HEADER in each
+.\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
+.\" If applicable, add the following below this CDDL HEADER, with the
+.\" fields enclosed by brackets "[]" replaced with your own identifying
+.\" information: Portions Copyright [yyyy] [name of copyright owner]
+.Dd July 9, 2018
+.Dt DSP 7I
+.Os
+.Sh NAME
+.Nm dsp
+.Nd generic audio device interface
+.Sh SYNOPSIS
+.In sys/soundcard.h
+.Sh DESCRIPTION
+To record audio input, applications
+.Xr open 2
+the appropriate device and
+read data from it using the
+.Xr read 2
+system call.
+Similarly, sound data is queued to the audio output port by using the
+.Xr write 2
+system call.
+Device configuration is performed using the
+.Xr ioctl 2
+interface.
+.Pp
 Because some systems can contain more than one audio device, application
-writers are encouraged to open the \fB/dev/mixer\fR device and determine the
-physical devices present on the system using the \fBSNDCTL_SYSINFO\fR and
-\fBSNDCTL_AUDIOINFO\fR ioctls. See \fBmixer\fR(7I). The user should be provided
-a the ability to select a different audio device, or alternatively, an
-environment variable such as \fBAUDIODSP\fR can be used. In the absence of any
-specific configuration from the user, the generic device file, \fB/dev/dsp\fR,
-can be used.  This normally points to a reasonably appropriate default audio
+writers are encouraged to open the
+.Pa /dev/mixer
+device and determine the
+physical devices present on the system using the
+.Dv SNDCTL_SYSINFO
+and
+.Dv SNDCTL_AUDIOINFO
+ioctls.
+See
+.Xr mixer 7I .
+The user should be provided
+wth the ability to select a different audio device, or alternatively, an
+environment variable such as
+.Ev AUDIODSP
+can be used.
+In the absence of any
+specific configuration from the user, the generic device file,
+.Pa /dev/dsp ,
+can be used.
+This normally points to a reasonably appropriate default audio
 device for the system.
-.SS "Opening the Audio Device"
-.sp
-.LP
+.Ss "Opening the Audio Device"
 The audio device is not treated as an exclusive resource.
-.sp
-.LP
-Each \fBopen()\fR completes as long as there are channels available to be
-allocated. If no channels are available to be allocated, the call returns
-\fB-1\fR with the \fBerrno\fR set to \fBEBUSY\fR.
-.sp
-.LP
+.Pp
+Each
+.Xr open 2
+completes as long as there are channels available to be allocated.
+If no channels are available to be allocated, the call returns
+.Sy -1
+with the
+.Va errno
+set to
+.Er EBUSY .
+.Pp
 Audio applications should explicitly set the encoding characteristics to match
 the audio data requirements after opening the device, and not depend on any
 default configuration.
-.SS "Recording Audio Data"
-.sp
-.LP
-The \fBread()\fR system call copies data from the system's buffers to the
-application. Ordinarily, \fBread()\fR blocks until the user buffer is filled.
-The \fBpoll\fR(2) system call can be used to determine the presence of data
-that can be read without blocking. The device can alternatively be set to a
-non-blocking mode, in which case \fBread()\fR completes immediately, but can
-return fewer bytes than requested. Refer to the \fBread\fR(2) manual page for a
-complete description of this behavior.
-.sp
-.LP
+.Ss "Recording Audio Data"
+The
+.Xr read 2
+system call copies data from the system's buffers to the application.
+Ordinarily,
+.Xr read 2
+blocks until the user buffer is filled.
+The
+.Xr poll 2
+system call can be used to determine the presence of data
+that can be read without blocking.
+The device can alternatively be set to a
+non-blocking mode, in which case
+.Xr read 2
+completes immediately, but can return fewer bytes than requested.
+Refer to the
+.Xr read 2
+manual page for a complete description of this behavior.
+.Pp
 When the audio device is opened with read access, the device driver allocates
-resources for recording. Since this consumes system resources, processes that
-do not record audio data should open the device write-only (\fBO_WRONLY\fR).
-.sp
-.LP
-The recording process can be stopped by using the \fBSNDCTL_DSP_HALT_INPUT\fR
+resources for recording.
+Since this consumes system resources, processes that
+do not record audio data should open the device write-only
+.Pq Dv O_WRONLY .
+.Pp
+The recording process can be stopped by using the
+.Dv SNDCTL_DSP_HALT_INPUT
 ioctl, which also discards all pending record data in underlying device FIFOs.
-.sp
-.LP
+.Pp
 Before changing record parameters, the input should be stopped using the
-\fBSNDCTL_DSP_HALT_INPUT\fR ioctl, which also flushes the any underlying device
-input FIFOs. (This is not necessary if the process never started recording by
-calling \fBread\fR(2). Otherwise, subsequent reads can return samples in the
-old format followed by samples in the new format. This is particularly
+.Dv SNDCTL_DSP_HALT_INPUT
+ioctl, which also flushes the any underlying device input FIFOs.
+(This is not necessary if the process never started recording by calling
+.Xr read 2 .
+Otherwise, subsequent reads can return samples in the
+old format followed by samples in the new format.
+This is particularly
 important when new parameters result in a changed sample size.
-.sp
-.LP
-Input data can accumulate in device buffers very quickly. At a minimum, it
-accumulates at 8000 bytes per second for 8-bit, 8 KHz, mono, \fBu-Law\fR data.
+.Pp
+Input data can accumulate in device buffers very quickly.
+At a minimum, it accumulates at 8000 bytes per second for 8-bit, 8 KHz, mono,
+.Sy \(*m-Law
+data.
 If the device is configured for more channels, higher sample resolution, or
-higher sample rates, it accumulates even faster. If the application that
-consumes the data cannot keep up with this data rate, the underlying FIFOs can
-become full. When this occurs, any new incoming data is lost until the
-application makes room available by consuming data. Additionally, a record
-overrun is noted, which can be retrieved using the \fBSNDCTL_DSP_GETERROR\fR
+higher sample rates, it accumulates even faster.
+If the application that consumes the data cannot keep up with this data rate,
+the underlying FIFOs can become full.
+When this occurs, any new incoming data is lost until the
+application makes room available by consuming data.
+Additionally, a record overrun is noted, which can be retrieved using the
+.Dv SNDCTL_DSP_GETERROR
 ioctl.
-.sp
-.LP
+.Pp
 Record volume for a stream can be adjusted by issuing the
-\fBSNDCTL_DSP_SETRECVOL\fR ioctl. The volume can also be retrieved using the
-\fBSNDCTL_DSP_GETRECVOL\fR.
-.SS "Playing Audio Data"
-.sp
-.LP
-The \fBwrite()\fR system call copies data from an application's buffer to the
-device output FIFO. Ordinarily, \fBwrite()\fR blocks until the entire user
-buffer is transferred. The device can alternatively be set to a non-blocking
-mode, in which case \fBwrite()\fRcompletes immediately, but might have
-transferred fewer bytes than requested. See \fBwrite\fR(2).
-.sp
-.LP
-Although \fBwrite()\fR returns when the data is successfully queued, the actual
-completion of audio output might take considerably longer. The
-\fBSNDCTL_DSP_SYNC\fR ioctl can be issued to allow an application to block
+.Dv SNDCTL_DSP_SETRECVOL
+ioctl.
+The volume can also be retrieved using the
+.Dv SNDCTL_DSP_GETRECVOL .
+.Ss "Playing Audio Data"
+The
+.Xr write 1
+system call copies data from an application's buffer to the device output FIFO.
+Ordinarily,
+.Xr write 2
+blocks until the entire user
+buffer is transferred.
+The device can alternatively be set to a non-blocking
+mode, in which case
+.Xr write 2
+completes immediately, but might have
+transferred fewer bytes than requested.
+See
+.Xr write 2 .
+.Pp
+Although
+.Xr write 2
+returns when the data is successfully queued, the actual
+completion of audio output might take considerably longer.
+The
+.Dv SNDCTL_DSP_SYNC
+ioctl can be issued to allow an application to block
 until all of the queued output data has been played.
-.sp
-.LP
-The final \fBclose\fR(2) of the file descriptor waits until all of the audio
-output has drained. If a signal interrupts the \fBclose()\fR, or if the process
+.Pp
+The final
+.Xr close 2
+of the file descriptor waits until all of the audio output has drained.
+If a signal interrupts the
+.Xr close 2 ,
+or if the process
 exits without closing the device, any remaining data queued for audio output is
 flushed and the device is closed immediately.
-.sp
-.LP
+.Pp
 The output of playback data can be halted entirely, by calling the
-\fBSNDCTL_DSP_HALT_OUTPUT\fR ioctl. This also discards any data that is queued
-for playback in device FIFOs.
-.sp
-.LP
+.Dv SNDCTL_DSP_HALT_OUTPUT
+ioctl.
+This also discards any data that is queued for playback in device FIFOs.
+.Pp
 Before changing playback parameters, the output should be drained using the
-\fBSNDCTL_DSP_SYNC\fR ioctl, and then stopped using the
-\fBSNDCTL_DSP_HALT_OUTPUT\fR ioctl, which also flushes the any underlying
-device output FIFOs. This is not necessary if the process never started
-playback, such as by calling \fBwrite\fR(2). This is particularly important
+.Dv SNDCTL_DSP_SYNC
+ioctl, and then stopped using the
+.Dv SNDCTL_DSP_HALT_OUTPUT
+ioctl, which also flushes the any underlying device output FIFOs.
+This is not necessary if the process never started playback, such as by calling
+.Xr write 2 .
+This is particularly important
 when new parameters result in a changed sample size.
-.sp
-.LP
+.Pp
 Output data is played from the playback buffers at a default rate of at least
-8000 bytes per second for u-Law, A-Law or 8-bit PCM data (faster for 16-bit
-linear data or higher sampling rates). If the output FIFO becomes empty, the
+8000 bytes per second for \(*m-Law, A-Law or 8-bit PCM data (faster for 16-bit
+linear data or higher sampling rates).
+If the output FIFO becomes empty, the
 framework plays silence, resulting in audible stall or click in the output,
-until more data is supplied by the application. The condition is also noted as
-a play underrun, which can be determined using the \fBSNDCTL_DSP_GETERROR\fR
+until more data is supplied by the application.
+The condition is also noted as
+a play underrun, which can be determined using the
+.Dv SNDCTL_DSP_GETERROR
 ioctl.
-.sp
-.LP
+.Pp
 Playback volume for a stream can be adjusted by issuing the
-\fBSNDCTL_DSP_SETPLAYVOL\fR ioctl. The volume can also be retrieved using the
-\fBSNDCTL_DSP_GETPLAYVOL\fR.
-.SS "Asynchronous I/O"
-.sp
-.LP
-The \fBO_NONBLOCK\fR flag can be set using the \fBF_SETFL\fR \fBfcntl\fR(2) to
-enable non-blocking \fBread()\fR and \fBwrite()\fR requests. This is normally
+.Dv SNDCTL_DSP_SETPLAYVOL
+ioctl.
+The volume can also be retrieved using the
+.Dv SNDCTL_DSP_GETPLAYVOL .
+.Ss "Asynchronous I/O"
+The
+.Dv O_NONBLOCK
+flag can be set using the
+.Dv F_SETFL
+.Xr fcntl 2
+to enable non-blocking
+.Xr read 2
+and
+.Xr write 2
+requests.
+This is normally
 sufficient for applications to maintain an audio stream in the background.
-.sp
-.LP
+.Pp
 It is also possible to determine the amount of data that can be transferred for
-playback or recording without blocking using the \fBSNDCTL_DSP_GETOSPACE\fR or
-\fBSNDCTL_DSP_GETISPACE\fR ioctls, respectively.
-.SS "Mixer Pseudo-Device"
-.sp
-.LP
-The \fB/dev/mixer\fR provides access to global hardware settings such as master
-volume settings, etc. It is also the interface used for determining the
+playback or recording without blocking using the
+.Dv SNDCTL_DSP_GETOSPACE
+or
+.Dv SNDCTL_DSP_GETISPACE
+ioctls, respectively.
+.Ss "Mixer Pseudo-Device"
+The
+.Pa /dev/mixer
+provides access to global hardware settings such as master volume settings, etc.
+It is also the interface used for determining the
 hardware configuration on the system.
-.sp
-.LP
-Applications should \fBopen\fR(2) \fB/dev/mixer\fR, and use the
-\fBSNDCTL_SYSINFO\fR and \fBSNDCTL_AUDIOINFO\fR ioctls to determine the device
-node names of audio devices on the system. See \fBmixer\fR(7I) for additional
-details.
-.SH IOCTLS
-.SS "Information IOCTLs"
-.sp
-.LP
+.Pp
+Applications should
+.Xr open 2
+.Pa /dev/mixer ,
+and use the
+.Dv SNDCTL_SYSINFO
+and
+.Dv SNDCTL_AUDIOINFO
+ioctls to determine the device node names of audio devices on the system.
+See
+.Xr mixer 7I
+for additional details.
+.Sh IOCTLS
+.Ss "Information IOCTLs"
 The following ioctls are supported on the audio device, as well as the mixer
-device. See \fBmixer\fR(7I) for details.
-.sp
-.in +2
-.nf
-OSS_GETVERSION
-SNDCTL_SYSINFO
-SNDCTL_AUDIOINFO
-SNDCTL_MIXERINFO
-SNDCTL_CARDINFO
-.fi
-.in -2
-
-.SS "Audio IOCTLs"
-.sp
-.LP
-The \fBdsp\fR device supports the following ioctl commands:
-.sp
-.ne 2
-.na
-\fB\fBSNDCTL_DSP_SYNC\fR\fR
-.ad
-.RS 27n
-The argument is ignored. This command suspends the calling process until the
+device.
+See
+.Xr mixer 7I
+for details.
+.Bd -literal -offset 2n
+.Dv OSS_GETVERSION
+.Dv SNDCTL_SYSINFO
+.Dv SNDCTL_AUDIOINFO
+.Dv SNDCTL_MIXERINFO
+.Dv SNDCTL_CARDINFO
+.Ed
+.Ss "Audio IOCTLs"
+The
+.Nm
+device supports the following ioctl commands:
+.Pp
+.\" A compact list is used so that items with multiple tags don't have
+.\" vertical whitespace.  However that means explicit .Pp statements must
+.\" be added.
+.Bl -tag -width "SNDCTL_DSP_CURRENT_IPTR" -compact
+.It Dv SNDCTL_DSP_SYNC
+The argument is ignored.
+This command suspends the calling process until the
 output FIFOs are empty and all queued samples have been played, or until a
-signal is delivered to the calling process. An implicit \fBSNDCTL_DSP_SYNC\fR
-is performed on the final \fBclose()\fR of the \fBdsp\fR device.
-.sp
+signal is delivered to the calling process.
+An implicit
+.Dv SNDCTL_DSP_SYNC
+is performed on the final
+.Xr close 2
+of the
+.Nm
+device.
+.Pp
 This ioctl should not be used unnecessarily, as if it is used in the middle of
-playback it causes a small click or pause, as the FIFOs are drained. The
-correct use of this ioctl is just before changing sample formats.
-.RE
-
-.sp
-.ne 2
-.na
-\fB\fBSNDCTL_DSP_HALT\fR\fR
-.ad
-.br
-.na
-\fB\fBSNDCTL_DSP_HALT_INPUT\fR\fR
-.ad
-.br
-.na
-\fB\fBSNDCTL_DSP_HALT_OUTPUT\fR\fR
-.ad
-.RS 27n
-The argument is ignored. All input or output (or both) associated with the file
+playback it causes a small click or pause, as the FIFOs are drained.
+The correct use of this ioctl is just before changing sample formats.
+.Pp
+.It Dv SNDCTL_DSP_HALT
+.It Dv SNDCTL_DSP_HALT_INPUT
+.It Dv SNDCTL_DSP_HALT_OUTPUT
+The argument is ignored.
+All input or output (or both) associated with the file
 is halted, and any pending data is discarded.
-.RE
-
-.sp
-.ne 2
-.na
-\fB\fBSNDCTL_DSP_SPEED\fR\fR
-.ad
-.RS 27n
+.Pp
+.It Dv SNDCTL_DSP_SPEED
 The argument is a pointer to an integer, indicating the sample rate (in Hz) to
-be used. The rate applies to both input and output for the file descriptor. On
-return the actual rate, which can differ from that requested, is stored in the
-integer pointed to by the argument. To query the configured speed without
-changing it the value 0 can be used by the application
-.RE
-
-.sp
-.ne 2
-.na
-\fB\fBSNDCTL_DSP_GETFMTS\fR\fR
-.ad
-.RS 27n
+be used.
+The rate applies to both input and output for the file descriptor.
+On return the actual rate, which can differ from that requested, is stored in
+the integer pointed to by the argument.
+To query the configured speed without
+changing it the value 0 can be used by the application.
+.Pp
+.It Dv SNDCTL_DSP_GETFMTS
 The argument is a pointer to an integer, which receives a bit mask of encodings
-supported by the device. Possible values are
-.sp
-.in +2
-.nf
-AFMT_MU_LAW      8-bit unsigned u-Law
-AFMT_A_LAW       8-bit unsigned a-Law
-AFMT_U8          8-bit unsigned linear PCM
-AFMT_S16_LE      16-bit signed
-                  little-endian linear PCM
-AFMT_S16_BE      16-bit signed
-                  big-endian linear PCM
-AFMT_S16_NE      16-bit signed native-endian
-                  linear PCM
-AFMT_U16_LE      16-bit unsigned
-                  little-endian linear PCM
-AFMT_U16_BE      16-bit unsigned big-endian
-                  linear PCM
-AFMT_U16_NE      16-bit unsigned big-endian
-                  linear PCM
-AFMT_S24_LE      24-bit signed little-endian
-                  linear PCM, 32-bit aligned
-AFMT_S24_BE      24-bit signed big-endian
-                  linear PCM, 32-bit aligned
-AFMT_S24_NE      24-bit signed native-endian
-                  linear PCM, 32-bit aligned
-AFMT_S32_LE      32-bit signed little-endian
-                  linear PCM
-AFMT_S32_BE      32-bit signed big-endian
-                   linear PCM
-AFMT_S32_NE      32-bit signed native-endian
-                   linear PCM
-AFMT_S24_PACKED  24-bit signed little-endian
-                   packed linear PCM
-.fi
-.in -2
-.sp
-
-Not all devices support all of these encodings. This implementation uses
-\fBAFMT_S24_LE\fR or \fBAFMT_S24_BE\fR, whichever is native, internally.
-.RE
-
-.sp
-.ne 2
-.na
-\fB\fBSNDCTL_DSP_SETFMT\fR\fR
-.ad
-.RS 27n
+supported by the device.
+Possible values are:
+.Pp
+.Bl -tag -width "AFMT_S24_PACKED" -compact -offset 2n
+.It Dv AFMT_MU_LAW
+8-bit unsigned \(*m-Law
+.It Dv AFMT_A_LAW
+8-bit unsigned a-Law
+.It Dv AFMT_U8
+8-bit unsigned linear PCM
+.It Dv AFMT_S16_LE
+16-bit signed little-endian linear PCM
+.It Dv AFMT_S16_BE
+16-bit signed big-endian linear PCM
+.It Dv AFMT_S16_NE
+16-bit signed native-endian linear PCM
+.It Dv AFMT_U16_LE
+16-bit unsigned little-endian linear PCM
+.It Dv AFMT_U16_BE
+16-bit unsigned big-endian linear PCM
+.It Dv AFMT_U16_NE
+16-bit unsigned native-endian linear PCM
+.It Dv AFMT_S24_LE
+24-bit signed little-endian linear PCM, 32-bit aligned
+.It Dv AFMT_S24_BE
+24-bit signed big-endian linear PCM, 32-bit aligned
+.It Dv AFMT_S24_NE
+24-bit signed native-endian linear PCM, 32-bit aligned
+.It Dv AFMT_S32_LE
+32-bit signed little-endian linear PCM
+.It Dv AFMT_S32_BE
+32-bit signed big-endian linear PCM
+.It Dv AFMT_S32_NE
+32-bit signed native-endian linear PCM
+.It Dv AFMT_S24_PACKED
+24-bit signed little-endian packed linear PCM
+.El
+.Pp
+Not all devices support all of these encodings.
+This implementation uses
+.Dv AFMT_S24_LE
+or
+.Dv AFMT_S24_BE ,
+whichever is native, internally.
+.Pp
+.It Dv SNDCTL_DSP_SETFMT
 The argument is a pointer to an integer, which indicates the encoding to be
-used. The same values as for \fBSNDCTL_DSP_GETFMT\fR can be used, but the
-caller can only specify a single option. The encoding is used for both input
+used.
+The same values as for
+.Dv SNDCTL_DSP_GETFMT
+can be used, but the caller can only specify a single option.
+The encoding is used for both input
 and output performed on the file descriptor.
-.RE
-
-.sp
-.ne 2
-.na
-\fB\fBSNDCTL_DSP_CHANNELS\fR\fR
-.ad
-.RS 27n
+.Pp
+.It Dv SNDCTL_DSP_CHANNELS
 The argument is a pointer to an integer, indicating the number of channels to
-be used (1 for mono, 2 for stereo, etc.) The value applies to both input and
-output for the file descriptor. On return the actual channel configuration
-(which can differ from that requested) is stored in the integer pointed to by
-the argument. To query the configured channels without changing it the value 0
+be used (1 for mono, 2 for stereo, etc.)
+The value applies to both input and output for the file descriptor.
+On return the actual channel configuration (which can differ from that
+requested) is stored in the integer pointed to by the argument.
+To query the configured channels without changing it the value 0
 can be used by the application.
-.RE
-
-.sp
-.ne 2
-.na
-\fB\fBSNDDCTL_DSP_GETCAPS\fR\fR
-.ad
-.RS 27n
+.Pp
+.It Dv SNDDCTL_DSP_GETCAPS
 The argument is a pointer to an integer bit mask, which indicates the
-capabilities of the device. The bits returned can include
-.sp
-.in +2
-.nf
-PCM_CAP_OUTPUT  Device supports playback
-PCM_CAP_INPUT   Device supports recording
-PCM_CAP_DUPLEX  Device supports simultaneous
-                    playback and recording
-.fi
-.in -2
-.sp
-
-.RE
-
-.sp
-.ne 2
-.na
-\fB\fBSNDCTL_DSP_GETPLAYVOL\fR\fR
-.ad
-.br
-.na
-\fB\fBSNDCTL_DSP_GETRECVOL\fR\fR
-.ad
-.RS 27n
+capabilities of the device.
+The bits returned can include:
+.Pp
+.Bl -tag -width "PCM_CAP_DUPLEX" -compact -offset 2n
+.It Dv PCM_CAP_OUTPUT
+Device supports playback
+.It Dv PCM_CAP_INPUT
+Device supports recording
+.It Dv PCM_CAP_DUPLEX
+Device supports simultaneous playback and recording
+.El
+.Pp
+.It Dv SNDCTL_DSP_GETPLAYVOL
+.It Dv SNDCTL_DSP_GETRECVOL
 The argument is a pointer to an integer to receive the volume level for either
-playback or record. The value is encoded as a stereo value with the values for
-two channels in the least significant two bytes. The value for each channel
-thus has a range of 0-100.  In this implementation, only the low order byte is
+playback or record.
+The value is encoded as a stereo value with the values for
+two channels in the least significant two bytes.
+The value for each channel thus has a range of 0-100.
+In this implementation, only the low order byte is
 used, as the value is treated as a monophonic value, but a stereo value (with
 both channel levels being identical) is returned for compatibility.
-.RE
-
-.sp
-.ne 2
-.na
-\fB\fBSNDCTL_DSP_SETPLAYVOL\fR\fR
-.ad
-.br
-.na
-\fB\fBSNDCTL_DSP_SETRECVOL\fR\fR
-.ad
-.RS 27n
+.Pp
+.It Dv SNDCTL_DSP_SETPLAYVOL
+.It Dv SNDCTL_DSP_SETRECVOL
 The argument is a pointer to an integer indicating volume level for either
-playback or record. The value is encoded as a stereo value with the values for
-two channels in the least significant two bytes. The value for each channel has
-a range of 0-100. Note that in this implementation, only the low order byte is
-used, as the value is treated as a monophonic value. Portable applications
-should assign the same value to both bytes
-.RE
-
-.sp
-.ne 2
-.na
-\fB\fBSNDCTL_DSP_GETISPACE\fR\fR
-.ad
-.br
-.na
-\fB\fBSNDCTL_DSP_GETOSPACE\fR\fR
-.ad
-.RS 27n
-The argument is a pointer to a \fBstruct audio_buf_info\fR, which has the
-following structure:
-.sp
-.in +2
-.nf
+playback or record.
+The value is encoded as a stereo value with the values for
+two channels in the least significant two bytes.
+The value for each channel has a range of 0-100.
+Note that in this implementation, only the low order byte is
+used, as the value is treated as a monophonic value.
+Portable applications should assign the same value to both bytes.
+.Pp
+.It Dv SNDCTL_DSP_GETISPACE
+.It Dv SNDCTL_DSP_GETOSPACE
+The argument is a pointer to a
+.Vt struct audio_buf_info ,
+which has the following structure:
+.Bd -literal -offset 2n
 typedef struct audio_buf_info {
-   int fragments;* /# of available fragments */
+   int fragments; /* # of available fragments */
    int fragstotal;
         /* Total # of fragments allocated */
    int fragsize;
         /* Size of a fragment in bytes */
    int bytes;
        /* Available space in bytes */
-   /* Note! 'bytes' could be more than
-      fragments*fragsize */
+   /*
+    * Note! 'bytes' could be more than
+    * fragments*fragsize
+    */
 } audio_buf_info;
-.fi
-.in -2
-.sp
-
-The fields fragments, \fBfragstotal\fR, and \fBfragsize\fR are intended for use
-with compatible applications (and in the future with \fBmmap\fR(2)) only, and
-need not be used by typical applications. On successful return the bytes member
-contains the number of bytes that can be transferred  without blocking.
-.RE
-
-.sp
-.ne 2
-.na
-\fB\fBSNDCTL_DSP_CURRENT_IPTR\fR\fR
-.ad
-.br
-.na
-\fB\fBSNDCTL_DSP_CURRENT_OPTR\fR\fR
-.ad
-.RS 27n
-The argument is a pointer to an \fBoss_count_t\fR, which has the following
-definition:
-.sp
-.in +2
-.nf
+.Ed
+.Pp
+The fields
+.Fa fragments ,
+.Fa fragstotal ,
+and
+.Fa fragsize
+are intended for use with compatible applications (and in the future with
+.Xr mmap 2 )
+only, and need not be used by typical applications.
+On successful return the bytes member
+contains the number of bytes that can be transferred without blocking.
+.Pp
+.It Dv SNDCTL_DSP_CURRENT_IPTR
+.It Dv SNDCTL_DSP_CURRENT_OPTR
+The argument is a pointer to an
+.Vt oss_count_t ,
+which has the following definition:
+.Bd -literal -offset 2n
 typedef struct {
     long long samples;
        /* Total # of samples */
     int fifo_samples;
        /* Samples in device FIFO */
-    int filler[32];/* For future use */
+    int filler[32]; /* For future use */
 } oss_count_t;
-.fi
-.in -2
-.sp
-
-The \fBsamples\fR field contains the total number of samples transferred by the
-device so far. The \fBfifo_samples\fR is the depth of any hardware FIFO. This
-structure can be useful for accurate stream positioning and latency
+.Ed
+.Pp
+The
+.Fa samples
+field contains the total number of samples transferred by the
+device so far.
+The
+.Fa fifo_samples
+is the depth of any hardware FIFO.
+This structure can be useful for accurate stream positioning and latency
 calculations.
-.RE
-
-.sp
-.ne 2
-.na
-\fB\fBSNDCTL_DSP_GETIPTR\fR\fR
-.ad
-.br
-.na
-\fB\fBSNDCTL_DSP_GETOPTR\fR\fR
-.ad
-.RS 27n
-The argument is a pointer to a \fBstruct count_info\fR, which has the following
-definition:
-.sp
-.in +2
-.nf
+.Pp
+.It Dv SNDCTL_DSP_GETIPTR
+.It Dv SNDCTL_DSP_GETOPTR
+The argument is a pointer to a
+.Vt struct count_info ,
+which has the following definition:
+.Bd -literal -offset 2n
 typedef struct count_info {
     unsigned int bytes;
       /* Total # of bytes processed */
     int blocks;
-      /* # of fragment transitions since
-      last time */
-    int ptr;/* Current DMA pointer value */
+      /*
+       * # of fragment transitions since
+       * last time
+       */
+    int ptr; /* Current DMA pointer value */
 } count_info;
-.fi
-.in -2
-.sp
-
+.Ed
+.Pp
 These ioctls are primarily supplied for compatibility, and should not be used
 by most applications.
-.RE
-
-.sp
-.ne 2
-.na
-\fB\fBSNDCTL_DSP_GETODELAY\fR\fR
-.ad
-.RS 27n
-The argument is a pointer to an integer. On return, the integer contains the
+.Pp
+.It Dv SNDCTL_DSP_GETODELAY
+The argument is a pointer to an integer.
+On return, the integer contains the
 number of bytes still to be played before the next byte written are played.
-This can be used for accurate determination of device latency. The result can
-differ from actual value by up the depth of the internal device FIFO, which is
-typically 64 bytes.
-.RE
-
-.sp
-.ne 2
-.na
-\fB\fBSNDCTL_DSP_GETERROR\fR\fR
-.ad
-.RS 27n
-The argument is a pointer to a \fBstruct audio_errinfo\fR, defined as follows:
-.sp
-.in +2
-.nf
+This can be used for accurate determination of device latency.
+The result can differ from actual value by up the depth of the internal device
+FIFO, which is typically 64 bytes.
+.Pp
+.It Dv SNDCTL_DSP_GETERROR
+The argument is a pointer to a
+.Vt struct audio_errinfo ,
+defined as follows:
+.Bd -literal -offset 2n
 typedef struct audio_errinfo {
      int play_underruns;
      int rec_overruns;
@@ -491,162 +496,107 @@ typedef struct audio_errinfo {
      int rec_errorparm;
      int filler[16];
 } audio_errinfo;
-.fi
-.in -2
-.sp
-
-For this implementation, only the \fBplay_underruns\fR and \fBrec_overruns\fR
-values are significant. No other fields are used in this implementation.
-.sp
+.Ed
+.Pp
+For this implementation, only the
+.Fa play_underruns
+and
+.Fa rec_overruns
+values are significant.
+No other fields are used in this implementation.
+.Pp
 These fields are reset to zero each time their value is retrieved using this
 ioctl.
-.RE
-
-.SS "Compatibility IOCTLS"
-.sp
-.LP
+.El
+.Ss "Compatibility IOCTLS"
 These ioctls are supplied exclusively for compatibility with existing
-applications. Their use is not recommended, and they are not documented here.
+applications.
+Their use is not recommended, and they are not documented here.
 Many of these are implemented as simple no-ops.
-.sp
-.in +2
-.nf
-SNDCTL_DSP_POST
-SNDCTL_DSP_STEREO
-SNDCTL_DSP_SETDUPLEX
-SNDCTL_DSP_LOW_WATER
-SNDCTL_DSP_PROFILE
-SNDCTL_DSP_GETBLKSIZE
-SNDCTL_DSP_SUBDIVIDE
-SNDCTL_DSP_SETFRAGMENT
-SNDCTL_DSP_COOKEDMODE
-SNDCTL_DSP_READCTL
-SNDCTL_DSP_WRITECTL
-SNDCTL_DSP_SILENCE
-SNDCTL_DSP_SKIP
-SNDCTL_DSP_POST
-SNDCTL_DSP_GET_RECSRC
-SNDCTL_DSP_SET_RECSRC
-SNDCTL_DSP_SET_RECSRC_NAMES
-SNDCTL_DSP_GET_PLAYTGT
-SNDCTL_DSP_SET_PLAYTGT
-SNDCTL_DSP_SET_PLAYTGT_NAMES
-SNDCTL_DSP_GETTRIGGER
-SNDCTL_DSP_SETTRIGGER
-SNDCTL_AUDIOINFO_EX
-SNDCTL_ENGINEINFO
-.fi
-.in -2
-.sp
-
-.SH ERRORS
-.sp
-.LP
-An \fBopen()\fR fails if:
-.sp
-.ne 2
-.na
-\fB\fBEBUSY\fR\fR
-.ad
-.RS 10n
-The requested play or record access isbusy and either the \fBO_NDELAY\fR or
-\fBO_NONBLOCK\fR flag was set in the \fBopen()\fR request.
-.RE
-
-.sp
-.ne 2
-.na
-\fB\fBEINTR\fR\fR
-.ad
-.RS 10n
-The requested play or record access is busy and a signal interrupted the
-\fBopen()\fR request.
-.RE
-
-.sp
-.ne 2
-.na
-\fB\fBEINVAL\fR\fR
-.ad
-.RS 10n
-The device cannot support the requested play or record access.
-.RE
-
-.sp
-.LP
-An \fBioctl()\fR fails if:
-.sp
-.ne 2
-.na
-\fB\fBEINVAL\fR\fR
-.ad
-.RS 10n
-The parameter changes requested in the ioctl are invalid or are not supported
-by the device.
-.RE
-
-.SH FILES
-.sp
-.LP
+.Pp
+.Bl -tag -width "Dv" -offset 2n -compact
+.It Dv SNDCTL_DSP_POST
+.It Dv SNDCTL_DSP_STEREO
+.It Dv SNDCTL_DSP_SETDUPLEX
+.It Dv SNDCTL_DSP_LOW_WATER
+.It Dv SNDCTL_DSP_PROFILE
+.It Dv SNDCTL_DSP_GETBLKSIZE
+.It Dv SNDCTL_DSP_SUBDIVIDE
+.It Dv SNDCTL_DSP_SETFRAGMENT
+.It Dv SNDCTL_DSP_COOKEDMODE
+.It Dv SNDCTL_DSP_READCTL
+.It Dv SNDCTL_DSP_WRITECTL
+.It Dv SNDCTL_DSP_SILENCE
+.It Dv SNDCTL_DSP_SKIP
+.It Dv SNDCTL_DSP_POST
+.It Dv SNDCTL_DSP_GET_RECSRC
+.It Dv SNDCTL_DSP_SET_RECSRC
+.It Dv SNDCTL_DSP_SET_RECSRC_NAMES
+.It Dv SNDCTL_DSP_GET_PLAYTGT
+.It Dv SNDCTL_DSP_SET_PLAYTGT
+.It Dv SNDCTL_DSP_SET_PLAYTGT_NAMES
+.It Dv SNDCTL_DSP_GETTRIGGER
+.It Dv SNDCTL_DSP_SETTRIGGER
+.It Dv SNDCTL_AUDIOINFO_EX
+.It Dv SNDCTL_ENGINEINFO
+.El
+.Sh FILES
 The physical audio device names are system dependent and are rarely used by
-programmers. Programmers should use the generic device names listed below.
-.sp
-.ne 2
-.na
-\fB\fB/dev/dsp\fR\fR
-.ad
-.RS 28n
+programmers.
+Programmers should use the generic device names listed below.
+.Bl -tag -width "/usr/share/audio/samples"
+.It Pa /dev/dsp
 Symbolic link to the system's primary audio device
-.RE
-
-.sp
-.ne 2
-.na
-\fB\fB/dev/mixer\fR\fR
-.ad
-.RS 28n
+.It Pa /dev/mixer
 Symbolic link to the pseudo mixer device for the system
-.RE
-
-.sp
-.ne 2
-.na
-\fB\fB/dev/sndstat\fR\fR
-.ad
-.RS 28n
+.It Pa /dev/sndstat
 Symbolic link to the pseudo mixer device for the system
-.RE
-
-.sp
-.ne 2
-.na
-\fB\fB/usr/share/audio/samples\fR\fR
-.ad
-.RS 28n
+.It Pa /usr/share/audio/samples
 Audio files
-.RE
-
-.SH ATTRIBUTES
-.sp
-.LP
-See \fBattributes\fR(5) for a description of the following attributes:
-.sp
-
-.sp
-.TS
-box;
-c | c
-l | l .
-ATTRIBUTE TYPE	ATTRIBUTE VALUE
-_
-Architecture	SPARC, x86
-_
-Stability Level	Uncommitted
-.TE
-
-.SH SEE ALSO
-.sp
-.LP
-\fBclose\fR(2), \fBfcntl\fR(2), \fBioctl\fR(2), \fBmmap\fR(2), \fBopen\fR(2),
-\fBpoll\fR(2), \fBread\fR(2), \fBwrite\fR(2), \fBattributes\fR(5),
-\fBaudio\fR(7D), \fBmixer\fR(7I)
+.El
+.Sh ERRORS
+An
+.Xr open 2
+call fails if:
+.Bl -tag -width "EINVAL"
+.It Er EBUSY
+The requested play or record access is busy and either the
+.Dv O_NDELAY
+or
+.Dv O_NONBLOCK
+flag was set in the
+.Xr open 2
+request.
+.It Er EINTR
+The requested play or record access is busy and a signal interrupted the
+.Xr open 2
+request.
+.It Er EINVAL
+The device cannot support the requested play or record access.
+.El
+.Pp
+An
+.Xr ioctl 2
+call fails if:
+.Bl -tag -width "EINVAL"
+.It Er EINVAL
+The parameter changes requested in the ioctl are invalid or are not supported
+by the device.
+.El
+.Sh ARCHITECTURE
+SPARC
+X86
+.Sh INTERFACE STABILITY
+Uncommitted
+.Sh SEE ALSO
+.Xr close 2 ,
+.Xr fcntl 2 ,
+.Xr ioctl 2 ,
+.Xr mmap 2 ,
+.Xr open 2 ,
+.Xr poll 2 ,
+.Xr read 2 ,
+.Xr write 2 ,
+.Xr attributes 5 ,
+.Xr audio 7D ,
+.Xr mixer 7I