1mixer(7I)                       Ioctl Requests                       mixer(7I)
2
3
4

NAME

6       mixer - generic mixer device interface
7

SYNOPSIS

9       #include <sys/soundcard.h>
10
11

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  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

IOCTLS

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

ERRORS

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

FILES

571       /dev/mixer      Symbolic link to the pseudo mixer device for the system
572
573
574       /dev/sndstat    Sound status device
575
576

ATTRIBUTES

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

SEE ALSO

599       close(2), ioctl(2), open(2), , read(2), attributes(5), dsp(7I)
600

BUGS

602       The names of mixer extensions are not guaranteed to be predictable.
603
604
605
606SunOS 5.11                        21 May 2009                        mixer(7I)
Impressum