Print this page
10528 Convert mixer(7I) to mandoc
| Split |
Close |
| Expand all |
| Collapse all |
--- old/usr/src/man/man7i/mixer.7i.man.txt
+++ new/usr/src/man/man7i/mixer.7i.man.txt
1 1 MIXER(7I) Ioctl Requests MIXER(7I)
2 2
3 -
4 -
5 3 NAME
6 - mixer - generic mixer device interface
4 + mixer - generic mixer device interface
7 5
8 6 SYNOPSIS
9 - #include <sys/soundcard.h>
7 + #include <sys/soundcard.h>
10 8
11 -
12 9 DESCRIPTION
13 - .
14 -
15 10 Mixer Pseudo-Device
16 - The /dev/mixer pseudo-device is provided for two purposes:
11 + The /dev/mixer pseudo-device is provided for two purposes:
17 12
18 - o The first purpose is for applications that wish to learn
19 - about the list of audio devices on the system, so that they
20 - can select (or provide for users to select) an appropriate
21 - audio device. The /dev/mixer pseudo-device provides
22 - interfaces to enumerate all of the audio devices on the
23 - system.
13 + o The first purpose is for applications that wish to learn about
14 + the list of audio devices on the system, so that they can
15 + select (or provide for users to select) an appropriate audio
16 + device. The /dev/mixer pseudo-device provides interfaces to
17 + enumerate all of the audio devices on the system.
24 18
25 - o The second purpose is for mixer panel type applications
26 - which need to control master settings for the audio hardware
27 - in the system, such as gain levels, balance, port
28 - functionality, and other device features.
19 + o The second purpose is for mixer panel type applications which
20 + need to control master settings for the audio hardware in the
21 + system, such as gain levels, balance, port functionality, and
22 + other device features.
29 23
24 + Ordinary audio applications should not attempt to adjust their playback
25 + or record volumes or other device settings using this device. Instead,
26 + they should use the SNDCTL_DSP_SETPLAYVOL and SNDCTL_DSP_SETRECVOL ioctls
27 + that are documented in dsp(7I).
30 28
31 - Ordinary audio applications should not attempt to adjust their playback
32 - or record volumes or other device settings using this device. Instead,
33 - they should use the SNDCTL_DSP_SETPLAYVOL and SNDCTL_DSP_SETRECVOL
34 - ioctls that are documented in dsp(7I).
35 -
36 29 Sndstat Device
37 - The /dev/sndstat device supports read(2), and can be read to retrieve
38 - human-readable information about the audio devices on the system.
39 - Software should not attempt to interpret the contents of this device.
30 + The /dev/sndstat device supports read(2), and can be read to retrieve
31 + human-readable information about the audio devices on the system.
32 + Software should not attempt to interpret the contents of this device.
40 33
41 34 IOCTLS
42 35 Information IOCTLs
43 - The following ioctls are intended to aid applications in identifying
44 - the audio devices available on the system. These ioctls can be issued
45 - against either the pseudo-device /dev/mixer, or a against a file
46 - descriptor open to any other audio device in the system.
36 + The following ioctls are intended to aid applications in identifying the
37 + audio devices available on the system. These ioctls can be issued
38 + against either the pseudo-device /dev/mixer, or a against a file
39 + descriptor open to any other audio device in the system.
47 40
41 + Applications should issue SNDCTL_SYSINFO first to learn what audio
42 + devices and mixers are available on the system, and then use
43 + SNDCTL_AUDIOINFO or SNDCTL_MIXERINFO to obtain more information about the
44 + audio devices or mixers, respectively.
48 45
49 - Applications should issue SNDCTL_SYSINFO first to learn what audio
50 - devices and mixers are available on the system, and then use
51 - SNDCTL_AUDIOINFO or SNDCTL_MIXERINFO to obtain more information about
52 - the audio devices or mixers, respectively.
46 + OSS_GETVERSION The argument is a pointer to an integer, which
47 + retrieves the version of the OSS API used. The value
48 + is encoded with the major version (currently 4) encoded
49 + in the most significant 16 bits, and a minor version
50 + encoded in the lower 16 bits.
53 51
54 - OSS_GETVERSION
55 - The argument is a pointer to an integer, which
56 - retrieves the version of the OSS API used. The
57 - value is encoded with the major version (currently
58 - 4) encoded in the most significant 16 bits, and a
59 - minor version encoded in the lower 16 bits.
52 + SNDCTL_SYSINFO The argument is a pointer to an oss_sysinfo structure,
53 + which has the following definition:
60 54
55 + typedef struct oss_sysinfo {
56 + char product[32]; /* E.g. SunOS Audio */
57 + char version[32]; /* E.g. 4.0a */
58 + int versionnum; /* See OSS_GETVERSION */
59 + char options[128]; /* NOT SUPPORTED */
61 60
62 - SNDCTL_SYSINFO
63 - The argument is a pointer to an oss_sysinfo
64 - structure, which has the following definition:
61 + int numaudios; /* # of audio/dsp devices */
62 + int openedaudio[8]; /* Reserved, always 0 */
65 63
66 - typedef struct oss_sysinfo {
67 - char product[32]; /* E.g. SunOS Audio */
68 - char version[32]; /* E.g. 4.0a */
69 - int versionnum; /* See OSS_GETVERSION */
70 - char options[128]; /* NOT SUPPORTED */
64 + int numsynths; /* NOT SUPPORTED, always 0 */
65 + int nummidis; /* NOT SUPPORTED, always 0 */
66 + int numtimers; /* NOT SUPPORTED, always 0 */
67 + int nummixers; /* # of mixer devices */
71 68
72 - int numaudios; /* # of audio/dsp devices */
73 - int openedaudio[8]; /* Reserved, always 0 */
69 + /* Mask of midi devices are busy */
70 + int openedmidi[8];
74 71
75 - int numsynths; /* NOT SUPPORTED, always 0 */
76 - int nummidis; /* NOT SUPPORTED, always 0 */
77 - int numtimers; /* NOT SUPPORTED, always 0 */
78 - int nummixers; /* # of mixer devices */
72 + /* Number of sound cards in the system */
73 + int numcards;
79 74
80 - int openedmidi[8]; /* Mask of midi devices are
81 - busy */
82 - int numcards; /* Number of sound cards in
83 - the system */
84 - int numaudioengines; /* Number of audio engines in
85 - the system */
86 - char license[16]; /* E.g. "GPL" or "CDDL" */
87 - char revision_info[256]; /* Reserved */
88 - int filler[172]; /* Reserved */
89 - } oss_sysinfo;
75 + /* Number of audio engines in the system */
76 + int numaudioengines;
77 + char license[16]; /* E.g. "GPL" or "CDDL" */
78 + char revision_info[256]; /* Reserved */
79 + int filler[172]; /* Reserved */
80 + } oss_sysinfo;
90 81
82 + The important fields here are numaudios, which is used
83 + to determine the number of audio devices that can be
84 + queried with SNDCTL_AUDIOINFO, nummixers which provides
85 + a count of mixers on the system, and numcards which
86 + counts to total number of aggregate devices. A card
87 + can consist of one or more audio devices and one or
88 + more mixers, although more typically there is exactly
89 + one audio device and one mixer for each card.
91 90
92 - The important fields here are numaudios, which is
93 - used to determine the number of audio devices that
94 - can be queried with SNDCTL_AUDIOINFO, nummixers
95 - which provides a count of mixers on the system, and
96 - numcards which counts to total number of aggregate
97 - devices. A card can consist of one or more audio
98 - devices and one or more mixers, although more
99 - typically there is exactly one audio device and one
100 - mixer for each card.
91 + SNDCTL_AUDIOINFO The argument is a pointer to an oss_audioinfo
92 + structure, which has the following structure:
101 93
94 + typedef struct oss_audioinfo {
95 + int dev; /* Device to query */
96 + char name[64]; /* Human readable name */
97 + int busy; /* reserved */
98 + int pid; /* reserved */
102 99
103 - SNDCTL_AUDIOINFO
104 - The argument is a pointer to an oss_audioinfo
105 - structure, which has the following structure:
100 + /* PCM_CAP_INPUT, PCM_CAP_OUTPUT */
101 + int caps;
102 + int iformats; /* Supported input formats */
103 + int oformats; /* Supported output formats */
104 + int magic; /* reserved */
105 + char cmd[64]; /* reserved */
106 + int card_number;
107 + int port_number; /* reserved */
108 + int mixer_dev;
106 109
107 - typedef struct oss_audioinfo {
108 - int dev; /* Device to query */
109 - char name[64]; /* Human readable name */
110 - int busy; /* reserved */
111 - int pid; /* reserved */
112 - int caps; /* PCM_CAP_INPUT, PCM_CAP_OUTPUT */
113 - int iformats; /* Supported input formats */
114 - int oformats; /* Supported output formats */
115 - int magic; /* reserved */
116 - char cmd[64]; /* reserved */
117 - int card_number;
118 - int port_number; /* reserved */
119 - int mixer_dev;
120 - int legacy_device; /* Obsolete field.
121 - Replaced by devnode */
122 - int enabled; /* reserved */
123 - int flags; /* reserved */
124 - int min_rate; /* Minimum sample rate */
125 - int max_rate; /* Maximum sample rate */
126 - int min_channels; /* Minimum number
127 - of channels */
128 - int max_channels; /* Maximum number
129 - of channels */
130 - int binding; /* reserved */
131 - int rate_source; /* reserved */
132 - char handle[32]; /* reserved */
133 - unsigned int nrates; /* reserved */
134 - unsigned int rates[20]; /* reserved */
135 - char song_name[64]; /* reserved */
136 - char label[16]; /* reserved */
137 - int latency; /* reserved */
138 - char devnode[32]; /* Device special file
139 - name (absolute path) */
140 - int next_play_engine; /* reserved */
141 - int next_rec_engine; /* reserved */
142 - int filler[184]; /* reserved */
143 - } oss_audioinfo;
110 + /* Obsolete field. Replaced by devnode */
111 + int legacy_device;
112 + int enabled; /* reserved */
113 + int flags; /* reserved */
114 + int min_rate; /* Minimum sample rate */
115 + int max_rate; /* Maximum sample rate */
116 + int min_channels; /* Minimum number of channels */
117 + int max_channels; /* Maximum number of channels */
118 + int binding; /* reserved */
119 + int rate_source; /* reserved */
120 + char handle[32]; /* reserved */
121 + unsigned int nrates; /* reserved */
122 + unsigned int rates[20]; /* reserved */
123 + char song_name[64]; /* reserved */
124 + char label[16]; /* reserved */
125 + int latency; /* reserved */
144 126
127 + /* Device special file name (absolute path) */
128 + char devnode[32];
129 + int next_play_engine; /* reserved */
130 + int next_rec_engine; /* reserved */
131 + int filler[184]; /* reserved */
132 + } oss_audioinfo;
145 133
146 - In the above structure, all of the fields are
147 - reserved except the following: dev, name,
148 - card_number, mixer_dev, caps, min_rate, max_rate,
149 - min_channels, max_channels, and devnode. The
150 - reserved fields are provided for compatibility with
151 - other OSS implementations, and available for legacy
152 - applications. New applications should not attempt
153 - to use these fields.
134 + In the above structure, all of the fields are reserved
135 + except the following: dev, name, card_number,
136 + mixer_dev, caps, min_rate, max_rate, min_channels,
137 + max_channels, and devnode. The reserved fields are
138 + provided for compatibility with other OSS
139 + implementations, and available for legacy applications.
140 + New applications should not attempt to use these
141 + fields.
154 142
155 - The dev field should be initialized by the
156 - application to the number of the device to query.
157 - This is a number between zero (inclusive) and value
158 - of numaudios (exclusive) returned by
159 - SNDCTL_SYSINFO. Alternatively, when issuing the
160 - ioctl against a real mixer or dsp device, the
161 - special value -1 can be used to indicate that the
162 - query is being made against the device opened. If
163 - -1 is used, the field is overwritten with the
164 - device number for the current device on successful
165 - return.
143 + The dev field should be initialized by the application
144 + to the number of the device to query. This is a number
145 + between zero (inclusive) and value of numaudios
146 + (exclusive) returned by SNDCTL_SYSINFO. Alternatively,
147 + when issuing the ioctl against a real mixer or dsp
148 + device, the special value -1 can be used to indicate
149 + that the query is being made against the device opened.
150 + If -1 is used, the field is overwritten with the device
151 + number for the current device on successful return.
166 152
167 - No other fields are significant upon entry, but a
168 - successful return contains details of the device.
153 + No other fields are significant upon entry, but a
154 + successful return contains details of the device.
169 155
170 - The name field is a human readable name
171 - representing the device. Applications should not
172 - try to interpret it.
156 + The name field is a human readable name representing
157 + the device. Applications should not try to interpret
158 + it.
173 159
174 - The card_number field indicates the number assigned
175 - to the aggregate device. This can be used with the
176 - SNDCTL_CARDINFO ioctl.
160 + The card_number field indicates the number assigned to
161 + the aggregate device. This can be used with the
162 + SNDCTL_CARDINFO ioctl.
177 163
178 - The mixer_dev is the mixer device number for the
179 - mixing device associated with the audio device.
180 - This can be used with the SNDCTL_MIXERINFO ioctl.
164 + The mixer_dev is the mixer device number for the mixing
165 + device associated with the audio device. This can be
166 + used with the SNDCTL_MIXERINFO ioctl.
181 167
182 - The caps field contains any of the bits
183 - PCM_CAP_INPUT, PCM_CAP_OUTPUT, and PCM_CAP_DUPLEX.
184 - Indicating whether the device support input,
185 - output, and whether input and output can be used
186 - simultaneously. All other bits are reserved.
168 + The caps field contains any of the bits PCM_CAP_INPUT,
169 + PCM_CAP_OUTPUT, and PCM_CAP_DUPLEX. Indicating whether
170 + the device support input, output, and whether input and
171 + output can be used simultaneously. All other bits are
172 + reserved.
187 173
188 - The min_rate and max_rate fields indicate the
189 - minimum and maximum sample rates supported by the
190 - device. Most applications should try to use the
191 - maximum supported rate for the best audio quality
192 - and lowest system resource consumption.
174 + The min_rate and max_rate fields indicate the minimum
175 + and maximum sample rates supported by the device. Most
176 + applications should try to use the maximum supported
177 + rate for the best audio quality and lowest system
178 + resource consumption.
193 179
194 - The min_channels and max_channels provide an
195 - indication of the number of channels (1 for mono, 2
196 - for stereo, 6 for 5.1, etc.) supported by the
197 - device.
180 + The min_channels and max_channels provide an indication
181 + of the number of channels (1 for mono, 2 for stereo, 6
182 + for 5.1, etc.) supported by the device.
198 183
199 - The devnode field contains the actual full path to
200 - the device node for this device, such as
201 - /dev/sound/audio810:0dsp. Applications should open
202 - this file to access the device.
184 + The devnode field contains the actual full path to the
185 + device node for this device, such as
186 + /dev/sound/audio810:0dsp. Applications should open
187 + this file to access the device.
203 188
189 + SNDCTL_CARDINFO The argument is a pointer to a struct oss_card_info,
190 + which has the following definition:
204 191
205 - SNDCTL_CARDINFO
206 - The argument is a pointer to a struct
207 - oss_card_info, which has the following definition:
192 + typedef struct oss_card_info {
193 + int card;
194 + char shortname[16];
195 + char longname[128];
196 + int flags; /* reserved */
197 + char hw_info[400];
198 + int intr_count; /* reserved */
199 + int ack_count; /* reserved */
200 + int filler[154];
201 + } oss_card_info;
208 202
209 - typedef struct oss_card_info {
210 - int card;
211 - char shortname[16];
212 - char longname[128];
213 - int flags;/* reserved */
214 - char hw_info[400];
215 - int intr_count;/* reserved */
216 - int ack_count;/* reserved */
217 - int filler[154];
218 - } oss_card_info;
203 + This ioctl is used to query for information about the
204 + aggregate audio device.
219 205
206 + The card field should be initialized by the application
207 + to the number of the card to query. This is a number
208 + between zero (inclusive) and value of numcards
209 + (exclusive) returned by SNDCTL_SYSINFO. Alternatively,
210 + when issuing the ioctl against a real mixer or dsp
211 + device, the special value -1 can be used to indicate
212 + that the query is being made against the device opened.
213 + If -1 is used, the field is overwritten with the number
214 + for the current hardware device on successful return.
220 215
221 - This ioctl is used to query for information about
222 - the aggregate audio device.
216 + The shortname, longname, and hw_info contain ASCIIZ
217 + strings describing the device in more detail. The
218 + hw_info member can contain multiple lines of detail,
219 + each line ending in a NEWLINE.
223 220
224 - The card field should be initialized by the
225 - application to the number of the card to query.
226 - This is a number between zero inclusive and value
227 - of numcards (exclusive) returned by
228 - SNDCTL_SYSINFO.) Alternatively, when issuing the
229 - ioctl against a real mixer or dsp device, the
230 - special value -1 can be used to indicate that the
231 - query is being made against the device opened. If
232 - -1 is used, the field is overwritten with the
233 - number for the current hardware device on
234 - successful return.
221 + The flag, intr_count, and ack_count fields are not used
222 + by this implementation.
235 223
236 - The shortname, longname, and hw_info contain ASCIIZ
237 - strings describing the device in more detail. The
238 - hw_info member can contain multiple lines of
239 - detail, each line ending in a NEWLINE.
224 + SNDCTL_MIXERINFO The argument is a pointer to a struct oss_mixer_info,
225 + which has the following definition:
240 226
241 - The flag, intr_count, and ack_count fields are not
242 - used by this implementation.
227 + typedef struct oss_mixerinfo {
228 + int dev;
229 + char id[16]; /* Reserved */
230 + char name[32];
231 + int modify_counter;
232 + int card_number;
233 + int port_number; /* Reserved */
234 + char handle[32]; /* Reserved */
235 + int magic; /* Reserved */
236 + int enabled; /* Reserved */
237 + int caps; /* Reserved */
238 + int flags; /* Reserved */
239 + int nrext;
240 + int priority;
243 241
242 + /* Deice special file name (absolute path) */
243 + char devnode[32];
244 + int legacy_device; /* Reserved */
245 + int filler[245]; /* Reserved */
246 + } oss_mixerinfo;
244 247
245 - SNDCTL_MIXERINFO
246 - The argument is a pointer to a struct
247 - oss_mixer_info, which has the following definition:
248 + In the above structure, all of the fields are reserved
249 + except the following: dev, name, modify_counter,
250 + card_number, nrext, priority, and devnode. The
251 + reserved fields are provided for compatibility with
252 + other OSS implementations, and available for legacy
253 + applications. New applications should not attempt to
254 + use these fields.
248 255
249 - typedef struct oss_mixerinfo {
250 - int dev;
251 - char id[16];/* Reserved */
252 - char name[32];
253 - int modify_counter;
254 - int card_number;
255 - int port_number;/* Reserved */
256 - char handle[32];/* Reserved */
257 - int magic;/* Reserved */
258 - int enabled;/* Reserved */
259 - int caps;/* Reserved */
260 - int flags;/* Reserved */
261 - int nrext;
262 - int priority;
263 - char devnode[32];/* Device special file name
264 - (absolute path) */
265 - int legacy_device;/* Reserved */
266 - int filler[245];/* Reserved */
267 - } oss_mixerinfo;
256 + The dev field should be initialized by the application
257 + to the number of the device to query. This is a number
258 + between zero inclusive and value of nummixers
259 + (exclusive) returned by SNDCTL_SYSINFO, or by
260 + SNDCTL_MIX_NRMIX. Alternatively, when issuing the
261 + ioctl against a real mixer or dsp device, the special
262 + value -1 can be used to indicate that the query is
263 + being made against the device opened. If -1 is used,
264 + the field is overwritten with the mixer number for the
265 + current open file on successful return.
268 266
267 + No other fields are significant upon entry, but on
268 + successful return contains details of the device.
269 269
270 - In the above structure, all of the fields are
271 - reserved except the following: dev, name,
272 - modify_counter, card_number, nrext, priority, and
273 - devnode. The reserved fields are provided for
274 - compatibility with other OSS implementations, and
275 - available for legacy applications. New
276 - applications should not attempt to use these
277 - fields.
270 + The name field is a human readable name representing
271 + the device. Applications should not try to interpret
272 + it.
278 273
279 - The dev field should be initialized by the
280 - application to the number of the device to query.
281 - This is a number between zero inclusive and value
282 - of nummixers (exclusive) returned by
283 - SNDCTL_SYSINFO, or by SNDCTL_MIX_NRMIX.
284 - Alternatively, when issuing the ioctl against a
285 - real mixer or dsp device, the special value -1 can
286 - be used to indicate that the query is being made
287 - against the device opened. If -1 is used, the field
288 - is overwritten with the mixer number for the
289 - current open file on successful return.
274 + The modify_counter is changed by the mixer framework
275 + each time the settings for the various controls or
276 + extensions of the device are changed. Applications can
277 + poll this value to learn if any other changes need to
278 + be searched for.
290 279
291 - No other fields are significant upon entry, but on
292 - successful return contains details of the device.
280 + The card_number field is the number of the aggregate
281 + audio device this mixer is located on. It can be used
282 + with the SNDCTL_CARDINFO ioctl.
293 283
294 - The name field is a human readable name
295 - representing the device. Applications should not
296 - try to interpret it.
284 + The nrext field is the number of mixer extensions
285 + available on this mixer. See the SNDCTL_MIX_NREXT
286 + description.
297 287
298 - The modify_counter is changed by the mixer
299 - framework each time the settings for the various
300 - controls or extensions of the device are changed.
301 - Applications can poll this value to learn if any
302 - other changes need to be searched for.
288 + The priority is used by the framework to assign a
289 + preference that applications can use in choosing a
290 + device. Higher values are preferable. Mixers with
291 + priorities less than -1 should never be selected by
292 + default.
303 293
304 - The card_number field is the number of the
305 - aggregate audio device this mixer is located on. It
306 - can be used with the SNDCTL_CARDINFO ioctl.
294 + The devnode field contains the actual full path to the
295 + device node for the physical mixer, such as
296 + /dev/sound/audio810:0mixer. Applications should open
297 + this file to access the mixer settings.
307 298
308 - The nrext field is the number of mixer extensions
309 - available on this mixer. See the SNDCTL_MIX_NREXT
310 - description.
311 -
312 - The priority is used by the framework to assign a
313 - preference that applications can use in choosing a
314 - device. Higher values are preferable. Mixers with
315 - priorities less than -1 should never be selected by
316 - default.
317 -
318 - The devnode field contains the actual full path to
319 - the device node for the physical mixer, such as
320 - /dev/sound/audio810:0mixer. Applications should
321 - open this file to access the mixer settings.
322 -
323 -
324 299 Mixer Extension IOCTLs
325 - The pseudo /dev/mixer device supports ioctls that can change the
326 - various settings for the audio hardware in the system.
300 + The pseudo /dev/mixer device supports ioctls that can change the oarious
301 + settings for the audio hardware in the system.
327 302
303 + Those ioctls should only be used by dedicated mixer applications or
304 + desktop olumme controls, and not by typical ordinary audio applications
305 + such as media players. Ordinary applications that wish to adjust their
306 + own volume settings should use the SNDCTL_DSP_SETPLAYVOL or
307 + SNDCTL_DSP_SETRECVOL ioctls for that purpose. See dsp(7I) for more
308 + information. Ordinary applications should never attempt to change master
309 + port selection or hardware settings such as monitor gain settings.
328 310
329 - Those ioctls should only be used by dedicated mixer applications or
330 - desktop volume controls, and not by typical ordinary audio applications
331 - such as media players. Ordinary applications that wish to adjust their
332 - own volume settings should use the SNDCTL_DSP_SETPLAYVOL or
333 - SNDCTL_DSP_SETRECVOL ioctls for that purpose. See dsp(7I) for more
334 - information. Ordinary applications should never attempt to change
335 - master port selection or hardware settings such as monitor gain
336 - settings.
311 + The ioctls in this section can only be used to access the mixer device
312 + that is associated with the current file descriptor.
337 313
314 + Applications should not assume that a single /dev/mixer node is able to
315 + access any physical settings. Instead, they should use the ioctl
316 + SNDCTL_MIXERINFO to determine the device path for the real mixer device,
317 + and issue ioctls on a file descriptor opened against the corresponding
318 + devnode field.
338 319
339 - The ioctls in this section can only be used to access the mixer device
340 - that is associated with the current file descriptor.
320 + When a dev member is specified in each of the following ioctls, the
321 + application should specify -1, although for compatibility the mixer
322 + allows the application to specify the mixer device number.
341 323
324 + SNDCTL_MIX_NRMIX The argument is a pointer to an integer, which
325 + receives the number of mixer devices in the system.
326 + Each can be queried by using its number with the
327 + SNDCTL_MIXERINFO ioctl. The same information is
328 + available using the SNDCTL_SYSINFO ioctl.
342 329
343 - Applications should not assume that a single /dev/mixer node is able to
344 - access any physical settings. Instead, they should use the ioctl
345 - SNDCTL_MIXERINFO to determine the device path for the real mixer
346 - device, and issue ioctls on a file descriptor opened against the
347 - corresponding devnode field.
330 + SNDCTL_MIX_NREXT The argument is a pointer to an integer. On entry,
331 + the integer should contain the special value -1. On
332 + return the argument receives the number of mixer
333 + extensions (or mixer controls) supported by the
334 + mixer device. More details about each extension can
335 + be obtained by SNDCTL_MIX_EXTINFO ioctl.
348 336
337 + SNDCTL_MIX_EXTINFO The argument is a pointer to an oss_mixext structure
338 + which is defined as follows:
349 339
350 - When a dev member is specified in each of the following ioctls, the
351 - application should specify -1, although for compatibility the mixer
352 - allows the application to specify the mixer device number.
340 + typedef struct oss_mixext {
341 + int dev; /* Mixer device number */
342 + int ctrl; /* Extension number */
343 + int type; /* Entry type */
344 + int maxvalue;
345 + int minvalue;
346 + int flags;
347 + char id[16]; /* Mnemonic ID (internal use) */
348 + int parent; /* Entry# of parent (-1 if root) */
349 + int dummy; /* NOT SUPPORTED */
350 + int timestamp;
351 + char data[64]; /* Reserved */
353 352
354 - SNDCTL_MIX_NRMIX
355 - The argument is a pointer to an integer, which
356 - receives the number of mixer devices in the
357 - system. Each can be queried by using its number
358 - with the SNDCTL_MIXERINFO ioctl. The same
359 - information is available using the
360 - SNDCTL_SYSINFO ioctl.
353 + /* Mask of allowed enum values */
354 + unsigned char enum_present[32];
355 + int control_no; /* Reserved */
356 + unsigned int desc; /* NOT SUPPORTED */
357 + char extname[32];
358 + int update_counter;
359 + int filler[7]; /* Reserved */
360 + } oss_mixext;
361 361
362 + On entry, the dev field should be initialized to the
363 + value -1, and the ctrl field should be initialized
364 + with the number of the extension being accessed.
365 + Between 0, inclusive, and the value returned by
366 + SNDCTL_MIX_NREXT, exclusive.
362 367
363 - SNDCTL_MIX_NREXT
364 - The argument is a pointer to an integer. On
365 - entry, the integer should contain the special
366 - value -1. On return the argument receives the
367 - number of mixer extensions (or mixer controls)
368 - supported by the mixer device. More details
369 - about each extension can be obtained by
370 - SNDCTL_MIX_EXTINFO ioctl.
368 + Mixer extensions are organized as a logical tree,
369 + starting with a root node. The root node always has
370 + a ctrl value of zero. The structure of the tree can
371 + be determined by looking at the parent field, which
372 + contains the extension number of the parent
373 + extension, or -1 if the extension is the root
374 + extension.
371 375
376 + The type indicates the type of extension used. This
377 + implementation supports the following values:
372 378
373 - SNDCTL_MIX_EXTINFO
374 - The argument is a pointer to an oss_mixext
375 - structure which is defined as follows:
379 + MIXT_DEVROOT Root node for extension tree
380 + MIXT_GROUP Logical grouping of controls
381 + MXIT_ONOFF Boolean value, 0 = off, 1 = on.
382 + MIXT_ENUM Enumerated value, 0 to maxvalue.
383 + MIXT_MONOSLIDER Monophonic slider, 0 to 255.
384 + MIXT_STEREOSLIDER Stereophonic slider, 0 to 255
385 + (encoded as lower two bytes in
386 + value.)
387 + MIXT_MARKER Place holder, can ignore.
376 388
377 - typedef struct oss_mixext {
378 - int dev; /* Mixer device number */
379 - int ctrl; /* Extension number */
380 - int type; /* Entry type */
381 - int maxvalue;
382 - int minvalue;
383 - int flags;
384 - char id[16]; /* Mnemonic ID (internal use) */
385 - int parent; /* Entry# of parent
386 - (-1 if root) */
387 - int dummy; /* NOT SUPPORTED */
388 - int timestamp;
389 - char data[64]; /* Reserved */
390 - unsigned char enum_present[32]; /* Mask
391 - of allowed
392 - enum
393 - values */
394 - int control_no; /* Reserved */
395 - unsigned int desc; /* NOT SUPPORTED */
396 - char extname[32];
397 - int update_counter;
398 - int filler[7]; /* Reserved */
399 - } oss_mixext;
389 + The flags field is a bit array. This implementation
390 + makes use of the following possible bits:
400 391
392 + MIXF_READABLE Extension's value is readable.
393 + MIXF_WRITEABLE Extension's value is modifiable.
394 + MIXF_POLL Extension can self-update.
395 + MIXF_PCMVOL Extension is for master PCM
396 + playback volume.
397 + MIXF_MAINVOL Extension is for a typical analog
398 + volume
399 + MIXF_RECVOL Extension is for master record
400 + gain.
401 + MIXF_MONVOL Extension is for a monitor
402 + source's gain.
401 403
402 - On entry, the dev field should be initialized to
403 - the value -1, and the ctrl field should be
404 - initialized with the number of the extension
405 - being accessed. Between 0, inclusive, and the
406 - value returned by SNDCTL_MIX_NREXT, exclusive.
404 + The id field contains an ASCIIZ identifier for the
405 + extension.
407 406
408 - Mixer extensions are organized as a logical
409 - tree, starting with a root node. The root node
410 - always has a ctrl value of zero. The structure
411 - of the tree can be determined by looking at the
412 - parent field, which contains the extension
413 - number of the parent extension, or -1 if the
414 - extension is the root extension.
407 + The timestamp field is set when the extension tree
408 + is first initialized. Applications must use the
409 + same timestamp value when attempting to change the
410 + values. A change in the timestamp indicates a
411 + change a in the structure of the extension tree.
415 412
416 - The type indicates the type of extension used.
417 - This implementation supports the following
418 - values:
413 + The enum_present field is a bit mask of possible
414 + enumeration values. If a bit is present in the
415 + enum_present mask, then the corresponding
416 + enumeration value is legal. The mask is in little
417 + endian order.
419 418
420 - MIXT_DEVROOT Root node for extension tree
421 - MIXT_GROUP Logical grouping of controls
422 - MXIT_ONOFF Boolean value, 0 = off, 1 = on.
423 - MIXT_ENUM Enumerated value, 0 to maxvalue.
424 - MIXT_MONOSLIDER Monophonic slider, 0 to 255.
425 - MIXT_STEREOSLIDER Stereophonic slider, 0 to 255
426 - (encoded as
427 - lower two bytes in value.)
428 - MIXT_MARKER Place holder, can ignore.
419 + The desc field provides information about scoping,
420 + which can be useful as layout hints to applications.
421 + The following hints are available:
429 422
423 + MIXEXT_SCOPE_MASK Mask of possible scope
424 + values.
425 + MIXEXT_SCOPE_INPUT Extension is an input
426 + control.
427 + MIXEXT_SCOPE_OUTPUT Extension is an output
428 + control.
429 + MIXEXT_SCOPE_MONITOR Extension relates to input
430 + monitoring.
431 + MIXEXT_SCOPE_OTHER scoping hint provided.
430 432
431 - The flags field is a bit array. This
432 - implementation makes use of the following
433 - possible bits:
433 + The extname is the full name of the extension.
434 434
435 - MIXF_READABLE Extension's value is readable.
436 - MIXF_WRITEABLE Extension's value is modifiable.
437 - MIXF_POLL Extension can self-update.
438 - MIXF_PCMVOL Extension is for master
439 - PCM playback volume.
440 - MIXF_MAINVOL Extension is for a typical
441 - analog volume
442 - MIXF_RECVOL Extension is for master
443 - record gain.
444 - MIXF_MONVOL Extension is for a monitor
445 - source's gain.
435 + The update_counter is incremented each time the
436 + control's value is changed.
446 437
438 + SNDCTL_MIX_ENUMINFO The argument is a pointer to an oss_mixer_enuminfo
439 + structure, which is defined as follows:
447 440
448 - The id field contains an ASCIIZ identifier for
449 - the extension.
441 + typedef struct oss_mixer_enuminfo {
442 + int dev;
443 + int ctrl;
444 + int nvalues;
445 + int version;
446 + short strindex[255];
447 + char strings[3000];
448 + } oss_mixer_enuminfo;
450 449
451 - The timestamp field is set when the extension
452 - tree is first initialized. Applications must
453 - use the same timestamp value when attempting to
454 - change the values. A change in the timestamp
455 - indicates a change a in the structure of the
456 - extension tree.
450 + On entry, the dev field should be initialized to the
451 + value -1, and the ctrl field should be initialized
452 + with the number of the extension being accessed.
453 + Between 0, inclusive, and the value returned by
454 + SNDCTL_MIX_NREXT, exclusive.
457 455
458 - The enum_present field is a bit mask of possible
459 - enumeration values. If a bit is present in the
460 - enum_present mask, then the corresponding
461 - enumeration value is legal. The mask is in
462 - little endian order.
456 + On return the nvalues field contains the number of
457 + values, and strindex contains an array of indices
458 + into the strings member, each index pointing to an
459 + ASCIIZ describing the enumeration value.
463 460
464 - The desc field provides information about
465 - scoping, which can be useful as layout hints to
466 - applications. The following hints are available:
461 + SNDCTL_MIX_READ
462 + SNDCTL_MIX_WRITE The argument is a pointer to an oss_mixer_value
463 + structure, defined as follows:
467 464
468 - MIXEXT_SCOPE_MASK Mask of possible scope
469 - values.
470 - MIXEXT_SCOPE_INPUT Extension is an input
471 - control.
472 - MIXEXT_SCOPE_OUTPUT Extension is an
473 - output control.
474 - MIXEXT_SCOPE_MONITOR Extension relates to
475 - input monitoring.
476 - MIXEXT_SCOPE_OTHER No scoping hint provided.
465 + typedef struct oss_mixer_value {
466 + int dev;
467 + int ctrl;
468 + int value;
477 469
470 + /* Reserved for future use. Initialize to 0 */
471 + int flags;
478 472
479 - The extname is the full name of the extension.
473 + /* Must be set to oss_mixext.timestamp */
474 + int timestamp;
480 475
481 - The update_counter is incremented each time the
482 - control's value is changed.
476 + /* Reserved for future use. Initialize to 0 */
477 + int filler[8];
478 + } oss_mixer_value;
483 479
480 + On entry, the dev field should be initialized to the
481 + value -1, and the ctrl field should be initialized
482 + with the number of the extension being accessed.
483 + Between 0, inclusive, and the value returned by
484 + SNDCTL_MIX_NREXT, exclusive. Additionally, the
485 + timestamp member must be initialized to the same
486 + value as was supplied in the oss_mixext structure
487 + used with SNDCTL_MIX_EXTINFO.
484 488
485 - SNDCTL_MIX_ENUMINFO
486 - The argument is a pointer to an
487 - oss_mixer_enuminfo structure, which is defined
488 - as follows:
489 + For SNDCTL_MIX_WRITE, the application should supply
490 + the new value for the extension. For
491 + SNDCTL_MIX_READ, the mixer returns the extensions
492 + current value in value.
489 493
490 - typedef struct oss_mixer_enuminfo {
491 - int dev;
492 - int ctrl;
493 - int nvalues;
494 - int version;
495 - short strindex[255];
496 - char strings[3000];
497 - } oss_mixer_enuminfo;
498 -
499 -
500 - On entry, the dev field should be initialized to
501 - the value -1, and the ctrl field should be
502 - initialized with the number of the extension
503 - being accessed. Between 0, inclusive, and the
504 - value returned by SNDCTL_MIX_NREXT, exclusive.
505 -
506 - On return the nvalues field contains the number
507 - of values, and strindex contains an array of
508 - indices into the strings member, each index
509 - pointing to an ASCIIZ describing the enumeration
510 - value.
511 -
512 -
513 - SNDCTL_MIX_READ
514 - SNDCTL_MIX_WRITE
515 - The argument is a pointer to an oss_mixer_value
516 - structure, defined as follows:
517 -
518 - typedef struct oss_mixer_value {
519 - int dev;
520 - int ctrl;
521 - int value;
522 - int flags; /* Reserved for future use.
523 - Initialize to 0 */
524 - int timestamp; /* Must be set to
525 - oss_mixext.timestamp */
526 - int filler[8]; /* Reserved for future use.
527 - Initialize to 0 */
528 - } oss_mixer_value;
529 -
530 -
531 - On entry, the dev field should be initialized to
532 - the value -1, and the ctrl field should be
533 - initialized with the number of the extension
534 - being accessed. Between 0, inclusive, and the
535 - value returned by SNDCTL_MIX_NREXT, exclusive.
536 - Additionally, the timestamp member must be
537 - initialized to the same value as was supplied in
538 - the oss_mixext structure used with
539 - SNDCTL_MIX_EXTINFO.
540 -
541 - For SNDCTL_MIX_WRITE, the application should
542 - supply the new value for the extension. For
543 - SNDCTL_MIX_READ, the mixer returns the
544 - extensions current value in value.
545 -
546 -
547 494 Compatibility IOCTLs
548 - The following ioctls are for compatibility use only:
495 + The following ioctls are for compatibility use only:
549 496
550 - SOUND_MIXER_READ_VOLUME
551 - SOUND_MIXER_READ_PCM
552 - SOUND_MIXER_READ_OGAIN
553 - SOUND_MIXER_READ_RECGAIN
554 - SOUND_MIXER_READ_RECLEV
555 - SOUND_MIXER_READ_IGAIN
556 - SOUND_MIXER_READ_RECSRC
557 - SOUND_MIXER_READ_RECMASK
558 - SOUND_MIXER_READ_DEVMASK
559 - SOUND_MIXER_READ_STEREODEVS
560 - SOUND_MIXER_WRITE_VOLUME
561 - SOUND_MIXER_WRITE_PCM
562 - SOUND_MIXER_WRITE_OGAIN
563 - SOUND_MIXER_WRITE_RECGAIN
564 - SOUND_MIXER_WRITE_RECLEV
565 - SOUND_MIXER_WRITE_IGAIN
566 - SOUND_MIXER_WRITE_RECSRC
567 - SOUND_MIXER_WRITE_RECMASK
568 - SOUND_MIXER_INFO
569 - SNDCTL_AUDIOINFO_EX
570 - SNDCTL_ENGINEINFO
497 + SOUND_MIXER_READ_VOLUME
498 + SOUND_MIXER_READ_PCM
499 + SOUND_MIXER_READ_OGAIN
500 + SOUND_MIXER_READ_RECGAIN
501 + SOUND_MIXER_READ_RECLEV
502 + SOUND_MIXER_READ_IGAIN
503 + SOUND_MIXER_READ_RECSRC
504 + SOUND_MIXER_READ_RECMASK
505 + SOUND_MIXER_READ_DEVMASK
506 + SOUND_MIXER_READ_STEREODEVS
507 + SOUND_MIXER_WRITE_VOLUME
508 + SOUND_MIXER_WRITE_PCM
509 + SOUND_MIXER_WRITE_OGAIN
510 + SOUND_MIXER_WRITE_RECGAIN
511 + SOUND_MIXER_WRITE_RECLEV
512 + SOUND_MIXER_WRITE_IGAIN
513 + SOUND_MIXER_WRITE_RECSRC
514 + SOUND_MIXER_WRITE_RECMASK
515 + SOUND_MIXER_INFO
516 + SNDCTL_AUDIOINFO_EX
517 + SNDCTL_ENGINEINFO
571 518
519 + These ioctls can affect the software volume levels associated with the
520 + calling process. They have no effect on the physical hardware levels or
521 + settings. They should not be used in new applications.
572 522
523 +FILES
524 + /dev/mixer Symbolic link to the pseudo mixer device for the system
573 525
526 + /dev/sndstat Sound status device
574 527
575 - These ioctls can affect the software volume levels associated with the
576 - calling process. They have no effect on the physical hardware levels or
577 - settings. They should not be used in new applications.
578 -
579 528 ERRORS
580 - An ioctl() fails if:
529 + An ioctl(2) fails if:
581 530
582 - EINVAL
583 - The parameter changes requested in the ioctl are invalid or
584 - are not supported by the device.
531 + EINVAL The parameter changes requested in the ioctl are invalid or are
532 + not supported by the device.
585 533
534 + ENXIO The device or extension referenced does not exist.
586 535
587 - ENXIO
588 - The device or extension referenced does not exist.
536 +ARCHITECTURE
537 + SPARC x86
589 538
539 +INTERFACE STABILITY
540 + The information and mixer extension IOCTLs are Uncommitted. The
541 + Compatibility IOCTLs are Obsolete Uncommitted. The extension names are
542 + Uncommitted.
590 543
591 -FILES
592 - /dev/mixer
593 - Symbolic link to the pseudo mixer device for the system
594 -
595 -
596 - /dev/sndstat
597 - Sound status device
598 -
599 -
600 -ATTRIBUTES
601 - See attributes(5) for a description of the following attributes:
602 -
603 -
604 -
605 -
606 - +----------------+-----------------+
607 - |ATTRIBUTE TYPE | ATTRIBUTE VALUE |
608 - +----------------+-----------------+
609 - |Architecture | SPARC, x86 |
610 - +----------------+-----------------+
611 - |Stability Level | See below. |
612 - +----------------+-----------------+
613 -
614 -
615 - The information and mixer extension IOCTLs are Uncommitted. The
616 - Compatibility IOCTLs are Obsolete Uncommitted. The extension names are
617 - Uncommitted.
618 -
619 544 SEE ALSO
620 - close(2), ioctl(2), open(2), , read(2), attributes(5), dsp(7I)
545 + close(2), ioctl(2), open(2), read(2), attributes(5), dsp(7I)
621 546
622 547 BUGS
623 - The names of mixer extensions are not guaranteed to be predictable.
548 + The names of mixer extensions are not guaranteed to be predictable.
624 549
625 -
626 -
627 - May 21, 2009 MIXER(7I)
550 +illumos February 1, 2019 illumos
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX