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