diff --git a/libsndio/sio.c b/libsndio/sio.c
index 0195f70..4f53811 100644
--- a/libsndio/sio.c
+++ b/libsndio/sio.c
@@ -53,7 +53,12 @@ sio_open(const char *str, unsigned int mode, int nbio)
 	if (str == NULL) /* backward compat */
 		str = devany;
 	if (strcmp(str, devany) == 0 && !issetugid()) {
-		str = getenv("AUDIODEVICE");
+		if ((mode & SIO_PLAY) == 0)
+			str = getenv("AUDIORECDEVICE");
+		if ((mode & SIO_REC) == 0)
+			str = getenv("AUDIOPLAYDEVICE");
+		if (mode == (SIO_PLAY | SIO_REC) || str == NULL)
+			str = getenv("AUDIODEVICE");
 		if (str == NULL)
 			str = devany;
 	}
diff --git a/libsndio/sio_open.3 b/libsndio/sio_open.3
index ab7dd1a..28ab270 100644
--- a/libsndio/sio_open.3
+++ b/libsndio/sio_open.3
@@ -34,7 +34,8 @@
 .Nm sio_eof ,
 .Nm sio_setvol ,
 .Nm sio_onvol ,
-.Nm sio_initpar
+.Nm sio_initpar ,
+.Nm SIO_BPS
 .Nd sndio interface to audio devices
 .Sh SYNOPSIS
 .In sndio.h
@@ -80,8 +81,8 @@
 .Fc
 .Ft "void"
 .Fn sio_initpar "struct sio_par *par"
-.\"Fd #define SIO_BPS(bits)
-.\"Fd #define SIO_LE_NATIVE
+.Ft unsigned int
+.Fn SIO_BPS "unsigned int bits"
 .Sh DESCRIPTION
 The
 .Nm sndio
@@ -270,7 +271,7 @@ To ease filling the
 structure, the
 following macros can be used:
 .Bl -tag -width "SIO_BPS(bits)"
-.It Dv SIO_BPS Ns Pq Fa bits
+.It Fn SIO_BPS bits
 Return the smallest value for
 .Fa bps
 that is a power of two and that is large enough to
@@ -280,6 +281,7 @@ hold
 Can be used to set the
 .Fa le
 parameter when native byte order is required.
+It is 1 if the native byte order is little endian or 0 otherwise.
 .El
 .Ss Getting device capabilities
 There's no way to get an exhaustive list of all parameter
@@ -385,17 +387,17 @@ bitmasks should always be used.
 .Ss Starting and stopping the device
 The
 .Fn sio_start
-function puts the device in a waiting state:
-the device will wait for playback data to be provided
-(using the
-.Fn sio_write
-function).
-Once enough data is queued to ensure that play buffers
-will not underrun, actual playback is started automatically.
-If record mode only is selected, then recording starts
-immediately.
+function prepares the device to start.
+Once the play buffer is full, i.e.\&
+.Fa sio_par.bufsz
+samples are queued with
+.Fn sio_write ,
+playback starts automatically.
+If record-only mode is selected, then
+.Fn sio_start
+starts recording immediately.
 In full-duplex mode, playback and recording will start
-synchronously as soon as enough data to play is available.
+synchronously as soon as the play buffer is full.
 .Pp
 The
 .Fn sio_stop
@@ -579,7 +581,7 @@ parameter of the
 structure, the audio subsystem will behave as follows:
 .Bl -tag -width "SIO_IGNORE"
 .It Dv SIO_IGNORE
-The devices pauses during overruns and underruns,
+The device pauses during overruns and underruns,
 thus the current position (obtained through
 .Fn sio_onmove )
 stops being incremented.
@@ -735,10 +737,17 @@ The debug level:
 may be a value between 0 and 2.
 .El
 .Sh SEE ALSO
+.Xr mio_open 3 ,
+.Xr sioctl_open 3 ,
 .Xr audio 4 ,
 .Xr sndio 7 ,
 .Xr sndiod 8 ,
 .Xr audio 9
+.Sh HISTORY
+These functions first appeared in
+.Ox 4.5 .
+.Sh AUTHORS
+.An Alexandre Ratchov Aq Mt ratchov@openbsd.org
 .Sh BUGS
 The
 .Xr audio 4
diff --git a/libsndio/sndio.7 b/libsndio/sndio.7
index cdfb2c8..26c2296 100644
--- a/libsndio/sndio.7
+++ b/libsndio/sndio.7
@@ -19,7 +19,7 @@
 .Os
 .Sh NAME
 .Nm sndio
-.Nd interface to audio and MIDI
+.Nd audio and MIDI device descriptors
 .Sh DESCRIPTION
 Programs access audio and MIDI hardware using the
 .Nm sndio
@@ -62,8 +62,9 @@ Additionally,
 exposes a MIDI port used to control audio programs using
 standard MIDI Machine Control (MMC), MIDI Time Code (MTC),
 and master volume messages.
-.Sh AUDIO AND MIDI DESCRIPTORS
-From the user's perspective every audio device or MIDI port
+.Ss Server device descriptors
+From the user's perspective, every audio device or MIDI port exposed by
+.Xr sndiod 8
 has a descriptor of the form:
 .Bd -literal -offset center
 type[@hostname][,servnum]/devnum[.option]
@@ -77,14 +78,6 @@ The type of the audio device or MIDI port.
 Possible values are:
 .Pp
 .Bl -tag -width "midithru" -offset 3n -compact
-.It Cm rsnd
-Raw
-.Xr audio 4
-device.
-.It Cm rmidi
-Raw
-.Xr midi 4
-port.
 .It Cm snd
 Audio device exposed by
 .Xr sndiod 8 .
@@ -94,8 +87,6 @@ MIDI thru port created with
 .It Cm midi
 MIDI port exposed by
 .Xr sndiod 8 .
-.It Cm default
-Default audio device or MIDI port (see below).
 .El
 .It Ar hostname
 The hostname or address where the remote
@@ -113,47 +104,49 @@ Useful only if multiple
 servers are running on the same system.
 .It Ar devnum
 Device number.
-For hardware audio or MIDI ports, this corresponds to
-the character device minor number.
-For audio devices or MIDI ports created with
+It corresponds to the number of the corresponding
+.Fl f
+or
+.Fl q
+option on the
 .Xr sndiod 8
-it corresponds to the number of the corresponding
-.Fl fq
-option on the command line.
+command line.
 .It Ar option
 Corresponds to the sub-device string registered using the
 .Fl s
 option of
 .Xr sndiod 8 .
 .El
+.Ss Raw device descriptors
+Every raw audio device or MIDI port has a descriptor of the form:
 .Pp
-For example:
+.D1 Ar type Ns / Ns Ar devnum
 .Pp
-.Bl -tag -width "snd/0.rear" -offset 3n -compact
-.It Li rsnd/0
-Raw access to first audio device.
-.It Li rmidi/5
-Raw access to MIDI port number 5.
-.It Li snd/0
-Audio device referred by first
-.Fl f
-option of
-.Xr sndiod 8 .
-.It Li snd/0.rear
-Sub-device registered with
-.Fl s Fa rear .
-.It Li midithru/0
-First MIDI thru port created with
-.Xr sndiod 8 .
-.El
-.Sh DEFAULTS
-If
+The
+.Ar type
+can be either
+.Cm rsnd
+or
+.Cm rmidi .
+The rsnd/0 device descriptor accesses the
+.Pa /dev/audio0
+device, rsnd/1 accesses
+.Pa /dev/audio1 ,
+and so on.
+Similarly, rmidi/0 accesses
+.Pa /dev/rmidi0
+and so on.
+.Ss Default Audio and MIDI devices
+When no audio device descriptor is provided to a program
+or when the reserved word
 .Cm default
 is used as the audio device, the program will use the
 one specified in the
-.Ev AUDIODEVICE
-environment variable.
-If it is not set, the program first tries to connect to
+.Ev AUDIODEVICE , AUDIOPLAYDEVICE
+and/or
+.Ev AUDIORECDEVICE
+environment variables.
+If they are not set, the program first tries to connect to
 .Li snd/0 .
 If that fails, it then tries to use
 .Li rsnd/0 .
@@ -175,7 +168,7 @@ is running, this allows programs to exchange MIDI data on
 machines with no MIDI hardware by default, e.g. a MIDI player
 could use a software synthesizer with no manual configuration
 required.
-.Sh AUTHENTICATION
+.Ss Authentication
 For privacy reasons only one user may have connections to
 .Xr sndiod 8
 at a given time.
@@ -190,10 +183,20 @@ and contains 128 bits of raw random data.
 If a session needs to be shared between multiple users, they
 can connect to the server using the same cookie.
 .Sh ENVIRONMENT
-.Bl -tag -width "AUDIODEVICEXXX" -compact
+.Bl -tag -width "AUDIOPLAYDEVICE" -compact
 .It Ev AUDIODEVICE
 Audio device descriptor to use
 when no descriptor is explicitly specified to a program.
+.It Ev AUDIOPLAYDEVICE
+Audio device descriptor to use for play-only mode
+when no descriptor is explicitly specified to a program.
+Overrides
+.Ev AUDIODEVICE .
+.It Ev AUDIORECDEVICE
+Audio device descriptor to use for record-only mode
+when no descriptor is explicitly specified to a program.
+Overrides
+.Ev AUDIODEVICE .
 .It Ev MIDIDEVICE
 MIDI port descriptor to use
 when no descriptor is explicitly specified to a program.
@@ -207,9 +210,31 @@ if the program has the set-user-ID or set-group-ID bits set.
 .It Pa ~/.sndio/cookie
 User's session authentication cookie.
 .It Pa /dev/audioN
-Audio devices.
+Raw audio devices.
 .It Pa /dev/rmidiN
-MIDI ports.
+Raw MIDI ports.
+.El
+.Sh EXAMPLES
+.Bl -tag -width "snd/0.rear" -compact
+.It Li snd/0
+Audio device referred to by the first
+.Fl f
+option of
+.Xr sndiod 8 .
+.It Li snd/0.rear
+Sub-device registered with
+.Dq -s rear .
+.It Li midithru/0
+First MIDI thru port created with
+.Xr sndiod 8 .
+.It Li default
+Default audio or MIDI device.
+.It Li rsnd/0
+Direct hardware access to
+.Pa /dev/audio0 .
+.It Li rmidi/5
+Direct hardware access to
+.Pa /dev/rmidi5 .
 .El
 .Sh SEE ALSO
 .Xr aucat 1 ,
diff --git a/sndioctl/sndioctl.1 b/sndioctl/sndioctl.1
index 929345c..a0c2955 100644
--- a/sndioctl/sndioctl.1
+++ b/sndioctl/sndioctl.1
@@ -72,8 +72,8 @@ The set of available controls depends on the audio device.
 Commands use the following two formats to display and change
 controls respectively:
 .Pp
-.Dl group/stream[channel].function
-.Dl group/stream[channel].function=value
+.Dl [group/]stream[channel].function
+.Dl [group/]stream[channel].function=value
 .Pp
 On the left-hand side are specified the control group (if any),
 the affected stream name, and the optional channel number.
@@ -119,5 +119,13 @@ Toggle the above
 control:
 .Pp
 .Dl $ sndioctl output.mute=!
+.Pp
+Allow audio recording and set all
+.Cm input
+channels to 50%:
+.Bd -literal -offset indent
+# sysctl kern.audio.record=1
+$ sndioctl input.mute=0 input.level=0.5
+.Ed
 .Sh SEE ALSO
 .Xr sioctl_open 3