1 MIXER(7I) Ioctl Requests MIXER(7I)
2
3
4
5 NAME
6 mixer - generic mixer device interface
7
8 SYNOPSIS
9 #include <sys/soundcard.h>
10
11
12 DESCRIPTION
13 .
14
15 Mixer Pseudo-Device
16 The /dev/mixer pseudo-device is provided for two purposes:
17
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.
24
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.
29
30
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 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.
40
41 IOCTLS
42 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.
47
48
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.
53
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.
60
61
62 SNDCTL_SYSINFO
63 The argument is a pointer to an oss_sysinfo
64 structure, which has the following definition:
65
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 */
71
72 int numaudios; /* # of audio/dsp devices */
73 int openedaudio[8]; /* Reserved, always 0 */
74
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 */
79
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;
90
91
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.
101
102
103 SNDCTL_AUDIOINFO
104 The argument is a pointer to an oss_audioinfo
105 structure, which has the following structure:
106
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;
144
145
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.
154
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.
166
167 No other fields are significant upon entry, but a
168 successful return contains details of the device.
169
170 The name field is a human readable name
171 representing the device. Applications should not
172 try to interpret it.
173
174 The card_number field indicates the number assigned
175 to the aggregate device. This can be used with the
176 SNDCTL_CARDINFO ioctl.
177
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.
181
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.
187
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.
193
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.
198
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.
203
204
205 SNDCTL_CARDINFO
206 The argument is a pointer to a struct
207 oss_card_info, which has the following definition:
208
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;
219
220
221 This ioctl is used to query for information about
222 the aggregate audio device.
223
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.
235
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.
240
241 The flag, intr_count, and ack_count fields are not
242 used by this implementation.
243
244
245 SNDCTL_MIXERINFO
246 The argument is a pointer to a struct
247 oss_mixer_info, which has the following definition:
248
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;
268
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.
278
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.
290
291 No other fields are significant upon entry, but on
292 successful return contains details of the device.
293
294 The name field is a human readable name
295 representing the device. Applications should not
296 try to interpret it.
297
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.
303
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.
307
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 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.
327
328
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.
337
338
339 The ioctls in this section can only be used to access the mixer device
340 that is associated with the current file descriptor.
341
342
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.
348
349
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.
353
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.
361
362
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.
371
372
373 SNDCTL_MIX_EXTINFO
374 The argument is a pointer to an oss_mixext
375 structure which is defined as follows:
376
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;
400
401
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.
407
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.
415
416 The type indicates the type of extension used.
417 This implementation supports the following
418 values:
419
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.
429
430
431 The flags field is a bit array. This
432 implementation makes use of the following
433 possible bits:
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.
446
447
448 The id field contains an ASCIIZ identifier for
449 the extension.
450
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.
457
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.
463
464 The desc field provides information about
465 scoping, which can be useful as layout hints to
466 applications. The following hints are available:
467
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.
477
478
479 The extname is the full name of the extension.
480
481 The update_counter is incremented each time the
482 control's value is changed.
483
484
485 SNDCTL_MIX_ENUMINFO
486 The argument is a pointer to an
487 oss_mixer_enuminfo structure, which is defined
488 as follows:
489
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 Compatibility IOCTLs
548 The following ioctls are for compatibility use only:
549
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
571
572
573
574
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 ERRORS
580 An ioctl() fails if:
581
582 EINVAL
583 The parameter changes requested in the ioctl are invalid or
584 are not supported by the device.
585
586
587 ENXIO
588 The device or extension referenced does not exist.
589
590
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 SEE ALSO
620 close(2), ioctl(2), open(2), , read(2), attributes(5), dsp(7I)
621
622 BUGS
623 The names of mixer extensions are not guaranteed to be predictable.
624
625
626
627 May 21, 2009 MIXER(7I)
|
1 MIXER(7I) Ioctl Requests MIXER(7I)
2
3 NAME
4 mixer - generic mixer device interface
5
6 SYNOPSIS
7 #include <sys/soundcard.h>
8
9 DESCRIPTION
10 Mixer Pseudo-Device
11 The /dev/mixer pseudo-device is provided for two purposes:
12
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.
18
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.
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).
28
29 Sndstat 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.
33
34 IOCTLS
35 Information IOCTLs
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.
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.
45
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.
51
52 SNDCTL_SYSINFO The argument is a pointer to an oss_sysinfo structure,
53 which has the following definition:
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 */
60
61 int numaudios; /* # of audio/dsp devices */
62 int openedaudio[8]; /* Reserved, always 0 */
63
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 */
68
69 /* Mask of midi devices are busy */
70 int openedmidi[8];
71
72 /* Number of sound cards in the system */
73 int numcards;
74
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;
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.
90
91 SNDCTL_AUDIOINFO The argument is a pointer to an oss_audioinfo
92 structure, which has the following structure:
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 */
99
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;
109
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 */
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;
133
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.
142
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.
152
153 No other fields are significant upon entry, but a
154 successful return contains details of the device.
155
156 The name field is a human readable name representing
157 the device. Applications should not try to interpret
158 it.
159
160 The card_number field indicates the number assigned to
161 the aggregate device. This can be used with the
162 SNDCTL_CARDINFO ioctl.
163
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.
167
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.
173
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.
179
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.
183
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.
188
189 SNDCTL_CARDINFO The argument is a pointer to a struct oss_card_info,
190 which has the following definition:
191
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;
202
203 This ioctl is used to query for information about the
204 aggregate audio device.
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.
215
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.
220
221 The flag, intr_count, and ack_count fields are not used
222 by this implementation.
223
224 SNDCTL_MIXERINFO The argument is a pointer to a struct oss_mixer_info,
225 which has the following definition:
226
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;
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;
247
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.
255
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.
266
267 No other fields are significant upon entry, but on
268 successful return contains details of the device.
269
270 The name field is a human readable name representing
271 the device. Applications should not try to interpret
272 it.
273
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.
279
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.
283
284 The nrext field is the number of mixer extensions
285 available on this mixer. See the SNDCTL_MIX_NREXT
286 description.
287
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.
293
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.
298
299 Mixer Extension IOCTLs
300 The pseudo /dev/mixer device supports ioctls that can change the oarious
301 settings for the audio hardware in the system.
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.
310
311 The ioctls in this section can only be used to access the mixer device
312 that is associated with the current file descriptor.
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.
319
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.
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.
329
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.
336
337 SNDCTL_MIX_EXTINFO The argument is a pointer to an oss_mixext structure
338 which is defined as follows:
339
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 */
352
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
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.
367
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.
375
376 The type indicates the type of extension used. This
377 implementation supports the following values:
378
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.
388
389 The flags field is a bit array. This implementation
390 makes use of the following possible bits:
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.
403
404 The id field contains an ASCIIZ identifier for the
405 extension.
406
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.
412
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.
418
419 The desc field provides information about scoping,
420 which can be useful as layout hints to applications.
421 The following hints are available:
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.
432
433 The extname is the full name of the extension.
434
435 The update_counter is incremented each time the
436 control's value is changed.
437
438 SNDCTL_MIX_ENUMINFO The argument is a pointer to an oss_mixer_enuminfo
439 structure, which is defined as follows:
440
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;
449
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.
455
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.
460
461 SNDCTL_MIX_READ
462 SNDCTL_MIX_WRITE The argument is a pointer to an oss_mixer_value
463 structure, defined as follows:
464
465 typedef struct oss_mixer_value {
466 int dev;
467 int ctrl;
468 int value;
469
470 /* Reserved for future use. Initialize to 0 */
471 int flags;
472
473 /* Must be set to oss_mixext.timestamp */
474 int timestamp;
475
476 /* Reserved for future use. Initialize to 0 */
477 int filler[8];
478 } oss_mixer_value;
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.
488
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.
493
494 Compatibility IOCTLs
495 The following ioctls are for compatibility use only:
496
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
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.
522
523 FILES
524 /dev/mixer Symbolic link to the pseudo mixer device for the system
525
526 /dev/sndstat Sound status device
527
528 ERRORS
529 An ioctl(2) fails if:
530
531 EINVAL The parameter changes requested in the ioctl are invalid or are
532 not supported by the device.
533
534 ENXIO The device or extension referenced does not exist.
535
536 ARCHITECTURE
537 SPARC x86
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.
543
544 SEE ALSO
545 close(2), ioctl(2), open(2), read(2), attributes(5), dsp(7I)
546
547 BUGS
548 The names of mixer extensions are not guaranteed to be predictable.
549
550 illumos February 1, 2019 illumos
|