mixer(7I) Ioctl Requests mixer(7I)NAMEmixer - generic mixer device interface
SYNOPSIS
#include <sys/soundcard.h>
DESCRIPTION
.
Mixer Pseudo-Device
The /dev/mixer pseudo-device is provided for two purposes:
o The first purpose is for applications that wish to learn
about the list of audio devices on the system, so that they
can select (or provide for users to select) an appropriate
audio device. The /dev/mixer pseudo-device provides inter‐
faces to enumerate all of the audio devices on the system.
o The second purpose is for mixer panel type applications
which need to control master settings for the audio hardware
in the system, such as gain levels, balance, port function‐
ality, and other device features.
Ordinary audio applications should not attempt to adjust their playback
or record volumes or other device settings using this device. Instead,
they should use the SNDCTL_DSP_SETPLAYVOL and SNDCTL_DSP_SETRECVOL
ioctls that are documented in dsp(7I).
Sndstat Device
The /dev/sndstat device supports read(2), and can be read to retrieve
human-readable information about the audio devices on the system. Soft‐
ware should not attempt to interpret the contents of this device.
IOCTLS
Information IOCTLs
The following ioctls are intended to aid applications in identifying
the audio devices available on the system. These ioctls can be issued
against either the pseudo-device /dev/mixer, or a against a file
descriptor open to any other audio device in the system.
Applications should issue SNDCTL_SYSINFO first to learn what audio
devices and mixers are available on the system, and then use SND‐
CTL_AUDIOINFO or SNDCTL_MIXERINFO to obtain more information about the
audio devices or mixers, respectively.
OSS_GETVERSION The argument is a pointer to an integer, which
retrieves the version of the OSS API used. The
value is encoded with the major version (currently
4) encoded in the most significant 16 bits, and a
minor version encoded in the lower 16 bits.
SNDCTL_SYSINFO The argument is a pointer to an oss_sysinfo struc‐
ture, which has the following definition:
typedef struct oss_sysinfo {
char product[32]; /* E.g. SunOS Audio */
char version[32]; /* E.g. 4.0a */
int versionnum; /* See OSS_GETVERSION */
char options[128]; /* NOT SUPPORTED */
int numaudios; /* # of audio/dsp devices */
int openedaudio[8]; /* Reserved, always 0 */
int numsynths; /* NOT SUPPORTED, always 0 */
int nummidis; /* NOT SUPPORTED, always 0 */
int numtimers; /* NOT SUPPORTED, always 0 */
int nummixers; /* # of mixer devices */
int openedmidi[8]; /* Mask of midi devices are
busy */
int numcards; /* Number of sound cards in
the system */
int numaudioengines; /* Number of audio engines in
the system */
char license[16]; /* E.g. "GPL" or "CDDL" */
char revision_info[256]; /* Reserved */
int filler[172]; /* Reserved */
} oss_sysinfo;
The important fields here are numaudios, which is
used to determine the number of audio devices that
can be queried with SNDCTL_AUDIOINFO, nummixers
which provides a count of mixers on the system, and
numcards which counts to total number of aggregate
devices. A card can consist of one or more audio
devices and one or more mixers, although more typi‐
cally there is exactly one audio device and one
mixer for each card.
SNDCTL_AUDIOINFO The argument is a pointer to an oss_audioinfo
structure, which has the following structure:
typedef struct oss_audioinfo {
int dev; /* Device to query */
char name[64]; /* Human readable name */
int busy; /* reserved */
int pid; /* reserved */
int caps; /* PCM_CAP_INPUT, PCM_CAP_OUTPUT */
int iformats; /* Supported input formats */
int oformats; /* Supported output formats */
int magic; /* reserved */
char cmd[64]; /* reserved */
int card_number;
int port_number; /* reserved */
int mixer_dev;
int legacy_device; /* Obsolete field.
Replaced by devnode */
int enabled; /* reserved */
int flags; /* reserved */
int min_rate; /* Minimum sample rate */
int max_rate; /* Maximum sample rate */
int min_channels; /* Minimum number
of channels */
int max_channels; /* Maximum number
of channels */
int binding; /* reserved */
int rate_source; /* reserved */
char handle[32]; /* reserved */
unsigned int nrates; /* reserved */
unsigned int rates[20]; /* reserved */
char song_name[64]; /* reserved */
char label[16]; /* reserved */
int latency; /* reserved */
char devnode[32]; /* Device special file
name (absolute path) */
int next_play_engine; /* reserved */
int next_rec_engine; /* reserved */
int filler[184]; /* reserved */
} oss_audioinfo;
In the above structure, all of the fields are
reserved except the following: dev, name, card_num‐
ber, mixer_dev, caps, min_rate, max_rate, min_chan‐
nels, max_channels, and devnode. The reserved
fields are provided for compatibility with other
OSS implementations, and available for legacy
applications. New applications should not attempt
to use these fields.
The dev field should be initialized by the applica‐
tion to the number of the device to query. This is
a number between zero (inclusive) and value of
numaudios (exclusive) returned by SNDCTL_SYSINFO.
Alternatively, when issuing the ioctl against a
real mixer or dsp device, the special value -1 can
be used to indicate that the query is being made
against the device opened. If -1 is used, the field
is overwritten with the device number for the cur‐
rent device on successful return.
No other fields are significant upon entry, but a
successful return contains details of the device.
The name field is a human readable name represent‐
ing the device. Applications should not try to
interpret it.
The card_number field indicates the number assigned
to the aggregate device. This can be used with the
SNDCTL_CARDINFO ioctl.
The mixer_dev is the mixer device number for the
mixing device associated with the audio device.
This can be used with the SNDCTL_MIXERINFO ioctl.
The caps field contains any of the bits
PCM_CAP_INPUT, PCM_CAP_OUTPUT, and PCM_CAP_DUPLEX.
Indicating whether the device support input, out‐
put, and whether input and output can be used
simultaneously. All other bits are reserved.
The min_rate and max_rate fields indicate the mini‐
mum and maximum sample rates supported by the
device. Most applications should try to use the
maximum supported rate for the best audio quality
and lowest system resource consumption.
The min_channels and max_channels provide an indi‐
cation of the number of channels (1 for mono, 2 for
stereo, 6 for 5.1, etc.) supported by the device.
The devnode field contains the actual full path to
the device node for this device, such as
/dev/sound/audio810:0dsp. Applications should open
this file to access the device.
SNDCTL_CARDINFO The argument is a pointer to a struct
oss_card_info, which has the following definition:
typedef struct oss_card_info {
int card;
char shortname[16];
char longname[128];
int flags;/* reserved */
char hw_info[400];
int intr_count;/* reserved */
int ack_count;/* reserved */
int filler[154];
} oss_card_info;
This ioctl is used to query for information about
the aggregate audio device.
The card field should be initialized by the appli‐
cation to the number of the card to query. This is
a number between zero inclusive and value of num‐
cards (exclusive) returned by SNDCTL_SYSINFO.)
Alternatively, when issuing the ioctl against a
real mixer or dsp device, the special value -1 can
be used to indicate that the query is being made
against the device opened. If -1 is used, the field
is overwritten with the number for the current
hardware device on successful return.
The shortname, longname, and hw_info contain ASCIIZ
strings describing the device in more detail. The
hw_info member can contain multiple lines of
detail, each line ending in a NEWLINE.
The flag, intr_count, and ack_count fields are not
used by this implementation.
SNDCTL_MIXERINFO The argument is a pointer to a struct
oss_mixer_info, which has the following definition:
typedef struct oss_mixerinfo {
int dev;
char id[16];/* Reserved */
char name[32];
int modify_counter;
int card_number;
int port_number;/* Reserved */
char handle[32];/* Reserved */
int magic;/* Reserved */
int enabled;/* Reserved */
int caps;/* Reserved */
int flags;/* Reserved */
int nrext;
int priority;
char devnode[32];/* Device special file name
(absolute path) */
int legacy_device;/* Reserved */
int filler[245];/* Reserved */
} oss_mixerinfo;
In the above structure, all of the fields are
reserved except the following: dev, name, mod‐
ify_counter, card_number, nrext, priority, and
devnode. The reserved fields are provided for com‐
patibility with other OSS implementations, and
available for legacy applications. New applica‐
tions should not attempt to use these fields.
The dev field should be initialized by the applica‐
tion to the number of the device to query. This is
a number between zero inclusive and value of num‐
mixers (exclusive) returned by SNDCTL_SYSINFO, or
by SNDCTL_MIX_NRMIX. Alternatively, when issuing
the ioctl against a real mixer or dsp device, the
special value -1 can be used to indicate that the
query is being made against the device opened. If
-1 is used, the field is overwritten with the mixer
number for the current open file on successful
return.
No other fields are significant upon entry, but on
successful return contains details of the device.
The name field is a human readable name represent‐
ing the device. Applications should not try to
interpret it.
The modify_counter is changed by the mixer frame‐
work each time the settings for the various con‐
trols or extensions of the device are changed.
Applications can poll this value to learn if any
other changes need to be searched for.
The card_number field is the number of the aggre‐
gate audio device this mixer is located on. It can
be used with the SNDCTL_CARDINFO ioctl.
The nrext field is the number of mixer extensions
available on this mixer. See the SNDCTL_MIX_NREXT
description.
The priority is used by the framework to assign a
preference that applications can use in choosing a
device. Higher values are preferable. Mixers with
priorities less than -1 should never be selected by
default.
The devnode field contains the actual full path to
the device node for the physical mixer, such as
/dev/sound/audio810:0mixer. Applications should
open this file to access the mixer settings.
Mixer Extension IOCTLs
The pseudo /dev/mixer device supports ioctls that can change the
various settings for the audio hardware in the system.
Those ioctls should only be used by dedicated mixer applications or
desktop volume controls, and not by typical ordinary audio applications
such as media players. Ordinary applications that wish to adjust their
own volume settings should use the SNDCTL_DSP_SETPLAYVOL or SND‐
CTL_DSP_SETRECVOL ioctls for that purpose. See dsp(7I) for more infor‐
mation. Ordinary applications should never attempt to change master
port selection or hardware settings such as monitor gain settings.
The ioctls in this section can only be used to access the mixer device
that is associated with the current file descriptor.
Applications should not assume that a single /dev/mixer node is able to
access any physical settings. Instead, they should use the ioctl SND‐
CTL_MIXERINFO to determine the device path for the real mixer device,
and issue ioctls on a file descriptor opened against the corresponding
devnode field.
When a dev member is specified in each of the following ioctls, the
application should specify -1, although for compatibility the mixer
allows the application to specify the mixer device number.
SNDCTL_MIX_NRMIX The argument is a pointer to an integer, which
receives the number of mixer devices in the sys‐
tem. Each can be queried by using its number
with the SNDCTL_MIXERINFO ioctl. The same infor‐
mation is available using the SNDCTL_SYSINFO
ioctl.
SNDCTL_MIX_NREXT The argument is a pointer to an integer. On
entry, the integer should contain the special
value -1. On return the argument receives the
number of mixer extensions (or mixer controls)
supported by the mixer device. More details
about each extension can be obtained by SND‐
CTL_MIX_EXTINFO ioctl.
SNDCTL_MIX_EXTINFO The argument is a pointer to an oss_mixext
structure which is defined as follows:
typedef struct oss_mixext {
int dev; /* Mixer device number */
int ctrl; /* Extension number */
int type; /* Entry type */
int maxvalue;
int minvalue;
int flags;
char id[16]; /* Mnemonic ID (internal use) */
int parent; /* Entry# of parent
(-1 if root) */
int dummy; /* NOT SUPPORTED */
int timestamp;
char data[64]; /* Reserved */
unsigned char enum_present[32]; /* Mask
of allowed
enum
values */
int control_no; /* Reserved */
unsigned int desc; /* NOT SUPPORTED */
char extname[32];
int update_counter;
int filler[7]; /* Reserved */
} oss_mixext;
On entry, the dev field should be initialized to
the value -1, and the ctrl field should be ini‐
tialized with the number of the extension being
accessed. Between 0, inclusive, and the value
returned by SNDCTL_MIX_NREXT, exclusive.
Mixer extensions are organized as a logical
tree, starting with a root node. The root node
always has a ctrl value of zero. The structure
of the tree can be determined by looking at the
parent field, which contains the extension num‐
ber of the parent extension, or -1 if the exten‐
sion is the root extension.
The type indicates the type of extension used.
This implementation supports the following val‐
ues:
MIXT_DEVROOT Root node for extension tree
MIXT_GROUP Logical grouping of controls
MXIT_ONOFF Boolean value, 0 = off, 1 = on.
MIXT_ENUM Enumerated value, 0 to maxvalue.
MIXT_MONOSLIDER Monophonic slider, 0 to 255.
MIXT_STEREOSLIDER Stereophonic slider, 0 to 255
(encoded as
lower two bytes in value.)
MIXT_MARKER Place holder, can ignore.
The flags field is a bit array. This implementa‐
tion makes use of the following possible bits:
MIXF_READABLE Extension's value is readable.
MIXF_WRITEABLE Extension's value is modifiable.
MIXF_POLL Extension can self-update.
MIXF_PCMVOL Extension is for master
PCM playback volume.
MIXF_MAINVOL Extension is for a typical
analog volume
MIXF_RECVOL Extension is for master
record gain.
MIXF_MONVOL Extension is for a monitor
source's gain.
The id field contains an ASCIIZ identifier for
the extension.
The timestamp field is set when the extension
tree is first initialized. Applications must use
the same timestamp value when attempting to
change the values. A change in the timestamp
indicates a change a in the structure of the
extension tree.
The enum_present field is a bit mask of possible
enumeration values. If a bit is present in the
enum_present mask, then the corresponding enu‐
meration value is legal. The mask is in little
endian order.
The desc field provides information about scop‐
ing, which can be useful as layout hints to
applications. The following hints are available:
MIXEXT_SCOPE_MASK Mask of possible scope
values.
MIXEXT_SCOPE_INPUT Extension is an input
control.
MIXEXT_SCOPE_OUTPUT Extension is an
output control.
MIXEXT_SCOPE_MONITOR Extension relates to
input monitoring.
MIXEXT_SCOPE_OTHER No scoping hint provided.
The extname is the full name of the extension.
The update_counter is incremented each time the
control's value is changed.
SNDCTL_MIX_ENUMINFO The argument is a pointer to an oss_mixer_enu‐
minfo structure, which is defined as follows:
typedef struct oss_mixer_enuminfo {
int dev;
int ctrl;
int nvalues;
int version;
short strindex[255];
char strings[3000];
} oss_mixer_enuminfo;
On entry, the dev field should be initialized to
the value -1, and the ctrl field should be ini‐
tialized with the number of the extension being
accessed. Between 0, inclusive, and the value
returned by SNDCTL_MIX_NREXT, exclusive.
On return the nvalues field contains the number
of values, and strindex contains an array of
indices into the strings member, each index
pointing to an ASCIIZ describing the enumeration
value.
SNDCTL_MIX_READ The argument is a pointer to an oss_mixer_value
SNDCTL_MIX_WRITE structure, defined as follows:
typedef struct oss_mixer_value {
int dev;
int ctrl;
int value;
int flags; /* Reserved for future use.
Initialize to 0 */
int timestamp; /* Must be set to
oss_mixext.timestamp */
int filler[8]; /* Reserved for future use.
Initialize to 0 */
} oss_mixer_value;
On entry, the dev field should be initialized to
the value -1, and the ctrl field should be ini‐
tialized with the number of the extension being
accessed. Between 0, inclusive, and the value
returned by SNDCTL_MIX_NREXT, exclusive. Addi‐
tionally, the timestamp member must be initial‐
ized to the same value as was supplied in the
oss_mixext structure used with SND‐
CTL_MIX_EXTINFO.
For SNDCTL_MIX_WRITE, the application should
supply the new value for the extension. For SND‐
CTL_MIX_READ, the mixer returns the extensions
current value in value.
Compatibility IOCTLs
The following ioctls are for compatibility use only:
SOUND_MIXER_READ_VOLUME
SOUND_MIXER_READ_PCM
SOUND_MIXER_READ_OGAIN
SOUND_MIXER_READ_RECGAIN
SOUND_MIXER_READ_RECLEV
SOUND_MIXER_READ_IGAIN
SOUND_MIXER_READ_RECSRC
SOUND_MIXER_READ_RECMASK
SOUND_MIXER_READ_DEVMASK
SOUND_MIXER_READ_STEREODEVS
SOUND_MIXER_WRITE_VOLUME
SOUND_MIXER_WRITE_PCM
SOUND_MIXER_WRITE_OGAIN
SOUND_MIXER_WRITE_RECGAIN
SOUND_MIXER_WRITE_RECLEV
SOUND_MIXER_WRITE_IGAIN
SOUND_MIXER_WRITE_RECSRC
SOUND_MIXER_WRITE_RECMASK
SOUND_MIXER_INFO
SNDCTL_AUDIOINFO_EX
SNDCTL_ENGINEINFO
These ioctls can affect the software volume levels associated with the
calling process. They have no effect on the physical hardware levels or
settings. They should not be used in new applications.
ERRORS
An ioctl() fails if:
EINVAL The parameter changes requested in the ioctl are invalid or
are not supported by the device.
ENXIO The device or extension referenced does not exist.
FILES
/dev/mixer Symbolic link to the pseudo mixer device for the system
/dev/sndstat Sound status device
ATTRIBUTES
See attributes(5) for a description of the following attributes:
┌────────────────────┬───────────────────────────────────────┐
│ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
├────────────────────┼───────────────────────────────────────┤
│Architecture │ SPARC, x86 │
├────────────────────┼───────────────────────────────────────┤
│Availability │ SUNWcs, driver/audio, sys‐ │
│ │ tem/header/header-audio │
├────────────────────┼───────────────────────────────────────┤
│Interface Stability │ See below. │
└────────────────────┴───────────────────────────────────────┘
The information and mixer extension IOCTLs are Uncommitted. The Compat‐
ibility IOCTLs are Obsolete Uncommitted. The extension names are Uncom‐
mitted.
SEE ALSOclose(2), ioctl(2), open(2), , read(2), attributes(5), dsp(7I)BUGS
The names of mixer extensions are not guaranteed to be predictable.
SunOS 5.11 21 May 2009 mixer(7I)
