MIXER(7I) Ioctl Requests MIXER(7I) NNAAMMEE mmiixxeerr - generic mixer device interface SSYYNNOOPPSSIISS ##iinncclluuddee <> DDEESSCCRRIIPPTTIIOONN MMiixxeerr PPsseeuuddoo--DDeevviiccee The _/_d_e_v_/_m_i_x_e_r pseudo-device is provided for two purposes: ++oo 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 _/_d_e_v_/_m_i_x_e_r pseudo-device provides interfaces to enumerate all of the audio devices on the system. ++oo 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 functionality, and other device features. Ordinary audio applications should _n_o_t 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). SSnnddssttaatt DDeevviiccee The _/_d_e_v_/_s_n_d_s_t_a_t device supports read(2), and can be read to retrieve human-readable information about the audio devices on the system. Software should not attempt to interpret the contents of this device. IIOOCCTTLLSS IInnffoorrmmaattiioonn IIOOCCTTLLss 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 _/_d_e_v_/_m_i_x_e_r, 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 SNDCTL_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 OOSSSS AAPPII 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 _o_s_s___s_y_s_i_n_f_o structure, 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 */ /* Mask of midi devices are busy */ int openedmidi[8]; /* Number of sound cards in the system */ int numcards; /* Number of audio engines in the system */ int numaudioengines; char license[16]; /* E.g. "GPL" or "CDDL" */ char revision_info[256]; /* Reserved */ int filler[172]; /* Reserved */ } oss_sysinfo; The important fields here are _n_u_m_a_u_d_i_o_s, which is used to determine the number of audio devices that can be queried with SNDCTL_AUDIOINFO, _n_u_m_m_i_x_e_r_s which provides a count of mixers on the system, and _n_u_m_c_a_r_d_s which counts to total number of aggregate devices. A ccaarrdd can consist of one or more audio devices and one or more mixers, although more typically there is exactly one audio device and one mixer for each card. SNDCTL_AUDIOINFO The argument is a pointer to an _o_s_s___a_u_d_i_o_i_n_f_o 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 */ /* PCM_CAP_INPUT, PCM_CAP_OUTPUT */ int caps; 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; /* Obsolete field. Replaced by devnode */ int legacy_device; 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 */ /* Device special file name (absolute path) */ char devnode[32]; 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: _d_e_v, _n_a_m_e, _c_a_r_d___n_u_m_b_e_r, _m_i_x_e_r___d_e_v, _c_a_p_s, _m_i_n___r_a_t_e, _m_a_x___r_a_t_e, _m_i_n___c_h_a_n_n_e_l_s, _m_a_x___c_h_a_n_n_e_l_s, and _d_e_v_n_o_d_e. 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 _d_e_v field should be initialized by the application to the number of the device to query. This is a number between zero (inclusive) and value of _n_u_m_a_u_d_i_o_s (exclusive) returned by SNDCTL_SYSINFO. Alternatively, when issuing the ioctl against a real mixer or ddsspp device, the special value --11 can be used to indicate that the query is being made against the device opened. If --11 is used, the field is overwritten with the device number for the current device on successful return. No other fields are significant upon entry, but a successful return contains details of the device. The _n_a_m_e field is a human readable name representing the device. Applications should not try to interpret it. The _c_a_r_d___n_u_m_b_e_r field indicates the number assigned to the aggregate device. This can be used with the SNDCTL_CARDINFO ioctl. The _m_i_x_e_r___d_e_v is the mixer device number for the mixing device associated with the audio device. This can be used with the SNDCTL_MIXERINFO ioctl. The _c_a_p_s field contains any of the bits PCM_CAP_INPUT, PCM_CAP_OUTPUT, and PCM_CAP_DUPLEX. Indicating whether the device support input, output, and whether input and output can be used simultaneously. All other bits are reserved. The _m_i_n___r_a_t_e and _m_a_x___r_a_t_e fields indicate the minimum 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 _m_i_n___c_h_a_n_n_e_l_s and _m_a_x___c_h_a_n_n_e_l_s provide an indication of the number of channels (1 for mono, 2 for stereo, 6 for 5.1, etc.) supported by the device. The _d_e_v_n_o_d_e field contains the actual full path to the device node for this device, such as _/_d_e_v_/_s_o_u_n_d_/_a_u_d_i_o_8_1_0_:_0_d_s_p. Applications should open this file to access the device. SNDCTL_CARDINFO The argument is a pointer to a _s_t_r_u_c_t _o_s_s___c_a_r_d___i_n_f_o, 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 _c_a_r_d field should be initialized by the application to the number of the card to query. This is a number between zero (inclusive) and value of _n_u_m_c_a_r_d_s (exclusive) returned by SNDCTL_SYSINFO. Alternatively, when issuing the ioctl against a real mixer or ddsspp device, the special value --11 can be used to indicate that the query is being made against the device opened. If --11 is used, the field is overwritten with the number for the current hardware device on successful return. The _s_h_o_r_t_n_a_m_e, _l_o_n_g_n_a_m_e, and _h_w___i_n_f_o contain AASSCCIIIIZZ strings describing the device in more detail. The _h_w___i_n_f_o member can contain multiple lines of detail, each line ending in a NEWLINE. The _f_l_a_g, _i_n_t_r___c_o_u_n_t, and _a_c_k___c_o_u_n_t fields are not used by this implementation. SNDCTL_MIXERINFO The argument is a pointer to a _s_t_r_u_c_t _o_s_s___m_i_x_e_r___i_n_f_o, 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; /* Deice special file name (absolute path) */ char devnode[32]; int legacy_device; /* Reserved */ int filler[245]; /* Reserved */ } oss_mixerinfo; In the above structure, all of the fields are reserved except the following: _d_e_v, _n_a_m_e, _m_o_d_i_f_y___c_o_u_n_t_e_r, _c_a_r_d___n_u_m_b_e_r, _n_r_e_x_t, _p_r_i_o_r_i_t_y, and _d_e_v_n_o_d_e. 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 _d_e_v field should be initialized by the application to the number of the device to query. This is a number between zero inclusive and value of _n_u_m_m_i_x_e_r_s (exclusive) returned by SNDCTL_SYSINFO, or by SNDCTL_MIX_NRMIX. Alternatively, when issuing the ioctl against a real mixer or ddsspp device, the special value --11 can be used to indicate that the query is being made against the device opened. If --11 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 _n_a_m_e field is a human readable name representing the device. Applications should not try to interpret it. The _m_o_d_i_f_y___c_o_u_n_t_e_r is changed by the mixer framework each time the settings for the various controls or extensions of the device are changed. Applications can poll this value to learn if any other changes need to be searched for. The _c_a_r_d___n_u_m_b_e_r field is the number of the aggregate audio device this mixer is located on. It can be used with the SNDCTL_CARDINFO ioctl. The _n_r_e_x_t 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 _d_e_v_n_o_d_e field contains the actual full path to the device node for the physical mixer, such as _/_d_e_v_/_s_o_u_n_d_/_a_u_d_i_o_8_1_0_:_0_m_i_x_e_r. Applications should open this file to access the mixer settings. MMiixxeerr EExxtteennssiioonn IIOOCCTTLLss The pseudo _/_d_e_v_/_m_i_x_e_r device supports ioctls that can change the oarious settings for the audio hardware in the system. Those ioctls should only be used by dedicated mixer applications or desktop olumme 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 SNDCTL_DSP_SETRECVOL ioctls for that purpose. See dsp(7I) for more information. 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 _/_d_e_v_/_m_i_x_e_r node is able to access any physical settings. Instead, they should use the ioctl SNDCTL_MIXERINFO to determine the device path for the real mixer device, and issue ioctls on a file descriptor opened against the corresponding _d_e_v_n_o_d_e field. When a _d_e_v member is specified in each of the following ioctls, the application should specify --11, 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 system. Each can be queried by using its number with the SNDCTL_MIXERINFO ioctl. The same information is available using the _S_N_D_C_T_L___S_Y_S_I_N_F_O ioctl. SNDCTL_MIX_NREXT The argument is a pointer to an integer. On entry, the integer should contain the special value --11. 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 _S_N_D_C_T_L___M_I_X___E_X_T_I_N_F_O ioctl. SNDCTL_MIX_EXTINFO The argument is a pointer to an _o_s_s___m_i_x_e_x_t 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 */ /* Mask of allowed enum values */ unsigned char enum_present[32]; int control_no; /* Reserved */ unsigned int desc; /* NOT SUPPORTED */ char extname[32]; int update_counter; int filler[7]; /* Reserved */ } oss_mixext; On entry, the _d_e_v field should be initialized to the value --11, and the _c_t_r_l field should be initialized 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 _c_t_r_l value of zero. The structure of the tree can be determined by looking at the parent field, which contains the extension number of the parent extension, or --11 if the extension is the root extension. The type indicates the type of extension used. This implementation supports the following values: 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 implementation 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 _i_d field contains an AASSCCIIIIZZ 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 _e_n_u_m___p_r_e_s_e_n_t field is a bit mask of possible enumeration values. If a bit is present in the _e_n_u_m___p_r_e_s_e_n_t mask, then the corresponding enumeration value is legal. The mask is in little endian order. The _d_e_s_c field provides information about scoping, 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 scoping hint provided. The _e_x_t_n_a_m_e is the full name of the extension. The _u_p_d_a_t_e___c_o_u_n_t_e_r is incremented each time the control's value is changed. SNDCTL_MIX_ENUMINFO The argument is a pointer to an _o_s_s___m_i_x_e_r___e_n_u_m_i_n_f_o 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 _d_e_v field should be initialized to the value --11, and the _c_t_r_l field should be initialized with the number of the extension being accessed. Between 0, inclusive, and the value returned by SNDCTL_MIX_NREXT, exclusive. On return the _n_v_a_l_u_e_s field contains the number of values, and _s_t_r_i_n_d_e_x contains an array of indices into the strings member, each index pointing to an AASSCCIIIIZZ describing the enumeration value. SNDCTL_MIX_READ SNDCTL_MIX_WRITE The argument is a pointer to an _o_s_s___m_i_x_e_r___v_a_l_u_e structure, defined as follows: typedef struct oss_mixer_value { int dev; int ctrl; int value; /* Reserved for future use. Initialize to 0 */ int flags; /* Must be set to oss_mixext.timestamp */ int timestamp; /* Reserved for future use. Initialize to 0 */ int filler[8]; } oss_mixer_value; On entry, the _d_e_v field should be initialized to the value --11, and the _c_t_r_l field should be initialized with the number of the extension being accessed. Between 0, inclusive, and the value returned by SNDCTL_MIX_NREXT, exclusive. Additionally, the timestamp member must be initialized to the same value as was supplied in the _o_s_s___m_i_x_e_x_t structure used with SNDCTL_MIX_EXTINFO. For SNDCTL_MIX_WRITE, the application should supply the new value for the extension. For SNDCTL_MIX_READ, the mixer returns the extensions current value in value. CCoommppaattiibbiilliittyy IIOOCCTTLLss 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. FFIILLEESS _/_d_e_v_/_m_i_x_e_r Symbolic link to the pseudo mixer device for the system _/_d_e_v_/_s_n_d_s_t_a_t Sound status device EERRRROORRSS An ioctl(2) 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. AARRCCHHIITTEECCTTUURREE SPARC x86 IINNTTEERRFFAACCEE SSTTAABBIILLIITTYY The information and mixer extension IOCTLs are Uncommitted. The Compatibility IOCTLs are Obsolete Uncommitted. The extension names are Uncommitted. SSEEEE AALLSSOO close(2), ioctl(2), open(2), read(2), attributes(5), dsp(7I) BBUUGGSS The names of mixer extensions are not guaranteed to be predictable. illumos February 1, 2019 illumos