Print this page
10528 Convert mixer(7I) to mandoc
   1 '\" te
   2 .\"  Copyright (c) 2009 Sun Microsystems, Inc. All rights reserved.
   3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.
   4 .\"  See the License for the specific language governing permissions and limitations under the License. When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the
   5 .\" fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   6 .TH MIXER 7I "May 21, 2009"
   7 .SH NAME
   8 mixer \- generic mixer device interface
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 \fB#include\fR \fB<sys/soundcard.h>\fR
  13 .fi
  14 
  15 .SH DESCRIPTION
  16 .sp
  17 .LP
  18 \&.
  19 .SS "Mixer Pseudo-Device"
  20 .sp
  21 .LP
  22 The \fB/dev/mixer\fR pseudo-device is provided for two purposes:
  23 .RS +4
  24 .TP
  25 .ie t \(bu
  26 .el o






  27 The first purpose is for applications that wish to learn about the list of
  28 audio devices on the system, so that they can select (or provide for users to
  29 select) an appropriate audio device. The \fB/dev/mixer\fR pseudo-device



  30 provides interfaces to enumerate all of the audio devices on the system.
  31 .RE
  32 .RS +4
  33 .TP
  34 .ie t \(bu
  35 .el o
  36 The second purpose is for mixer panel type applications which need to control
  37 master settings for the audio hardware in the system, such as gain levels,
  38 balance, port functionality, and other device features.
  39 .RE
  40 .sp
  41 .LP
  42 Ordinary audio applications should \fBnot\fR attempt to adjust their playback
  43 or record volumes or other device settings using this device. Instead, they
  44 should use the \fBSNDCTL_DSP_SETPLAYVOL\fR and \fBSNDCTL_DSP_SETRECVOL\fR
  45 ioctls that are documented in \fBdsp\fR(7I).
  46 .SS "Sndstat Device"
  47 .sp
  48 .LP
  49 The \fB/dev/sndstat\fR device supports \fBread\fR(2), and can be read to








  50 retrieve human-readable information about the audio devices on the system.
  51 Software should not attempt to interpret the contents of this device.
  52 .SH IOCTLS
  53 .SS "Information IOCTLs"
  54 .sp
  55 .LP
  56 The following ioctls are intended to aid applications in identifying the audio
  57 devices available on the system. These ioctls can be issued against either the
  58 pseudo-device \fB/dev/mixer\fR, or a against a file descriptor open to any



  59 other audio device in the system.
  60 .sp
  61 .LP
  62 Applications should issue \fBSNDCTL_SYSINFO\fR first to learn what audio

  63 devices and mixers are available on the system, and then use
  64 \fBSNDCTL_AUDIOINFO\fR or \fBSNDCTL_MIXERINFO\fR to obtain more information



  65 about the audio devices or mixers, respectively.
  66 .sp
  67 .ne 2
  68 .na
  69 \fB\fBOSS_GETVERSION\fR\fR
  70 .ad
  71 .RS 20n
  72 The argument is a pointer to an integer, which retrieves the version of the
  73 \fBOSS API\fR used. The value is encoded with the major version (currently 4)


  74 encoded in the most significant 16 bits, and a minor version encoded in the
  75 lower 16 bits.
  76 .RE
  77 
  78 .sp
  79 .ne 2
  80 .na
  81 \fB\fBSNDCTL_SYSINFO\fR\fR
  82 .ad
  83 .RS 20n
  84 The argument is a pointer to an \fBoss_sysinfo\fR structure, which has the
  85 following definition:
  86 .sp
  87 .in +2
  88 .nf
  89 typedef struct oss_sysinfo {
  90    char product[32];   /* E.g. SunOS Audio */
  91    char version[32];   /* E.g. 4.0a */
  92    int versionnum;     /* See OSS_GETVERSION */
  93    char options[128];  /* NOT SUPPORTED */
  94 
  95    int numaudios;      /* # of audio/dsp devices */
  96    int openedaudio[8]; /* Reserved, always 0 */
  97 
  98  int numsynths;        /* NOT SUPPORTED, always 0 */
  99  int nummidis;         /* NOT SUPPORTED, always 0 */
 100  int numtimers;        /* NOT SUPPORTED, always 0 */
 101  int nummixers;        /* # of mixer devices */
 102 
 103  int openedmidi[8];    /* Mask of midi devices are
 104                           busy */
 105  int numcards;         /* Number of sound cards in
 106                           the system */
 107  int numaudioengines;  /* Number of audio engines in
 108                           the system */


 109  char license[16];     /* E.g. "GPL" or "CDDL" */
 110  char revision_info[256];  /* Reserved */
 111  int filler[172];          /* Reserved */
 112 } oss_sysinfo;
 113 .fi
 114 .in -2
 115 .sp
 116 
 117 The important fields here are \fBnumaudios\fR, which is used to determine the
 118 number of audio devices that can be queried with \fBSNDCTL_AUDIOINFO\fR,
 119 \fBnummixers\fR which provides a count of mixers on the system, and
 120 \fBnumcards\fR which counts to total number of aggregate devices. A \fBcard\fR





 121 can consist of one or more audio devices and one or more mixers, although more
 122 typically there is exactly one audio device and one mixer for each card.
 123 .RE
 124 
 125 .sp
 126 .ne 2
 127 .na
 128 \fB\fBSNDCTL_AUDIOINFO\fR\fR
 129 .ad
 130 .RS 20n
 131 The argument is a pointer to an \fBoss_audioinfo\fR structure, which has the
 132 following structure:
 133 .sp
 134 .in +2
 135 .nf
 136 typedef struct oss_audioinfo {
 137    int dev;  /* Device to query */
 138    char name[64];  /* Human readable name */
 139    int busy;  /* reserved */
 140    int pid;  /* reserved */
 141    int caps;  /* PCM_CAP_INPUT, PCM_CAP_OUTPUT */


 142    int iformats;  /* Supported input formats */
 143    int oformats;  /* Supported output formats */
 144    int magic;  /* reserved */
 145    char cmd[64];  /* reserved */
 146    int card_number;
 147    int port_number;  /* reserved */
 148    int mixer_dev;
 149    int legacy_device; /* Obsolete field.
 150                          Replaced by devnode */

 151    int enabled;  /* reserved */
 152    int flags;  /* reserved */
 153    int min_rate;  /* Minimum sample rate */
 154    int max_rate;  /* Maximum sample rate */
 155    int min_channels;  /* Minimum number
 156                          of channels */
 157    int max_channels;  /* Maximum number
 158                          of channels */
 159    int binding;  /* reserved */
 160    int rate_source;  /* reserved */
 161    char handle[32];  /* reserved */
 162    unsigned int nrates;  /* reserved */
 163    unsigned int rates[20];  /* reserved */
 164    char song_name[64];  /* reserved */
 165    char label[16];  /* reserved */
 166    int latency;  /* reserved */
 167    char devnode[32];  /* Device special file
 168                          name (absolute path) */

 169    int next_play_engine;  /* reserved */
 170    int next_rec_engine;  /* reserved */
 171    int filler[184];  /* reserved */
 172 } oss_audioinfo;
 173 .fi
 174 .in -2
 175 .sp
 176 
 177 In the above structure, all of the fields are reserved except the following:
 178 d\fBev, name, card_number, mixer_dev, caps, min_rate, max_rate, min_channels,
 179 max_channels,\fR and \fBdevnode\fR. The reserved fields are provided for
 180 compatibility with other OSS implementations, and available for legacy
 181 applications. New applications should not attempt to use these fields.
 182 .sp
 183 The \fBdev\fR field should be initialized by the application to the number of
 184 the device to query. This is a number between zero (inclusive) and value of
 185 \fBnumaudios\fR (exclusive) returned by \fBSNDCTL_SYSINFO\fR. Alternatively,
 186 when issuing the ioctl against a real mixer or \fBdsp\fR device, the special
 187 value \fB-1\fR can be used to indicate that the query is being made against the
 188 device opened. If \fB-1\fR is used, the field is overwritten with the device






















 189 number for the current device on successful return.
 190 .sp
 191 No other fields are significant upon entry, but a successful return contains
 192 details of the device.
 193 .sp
 194 The \fBname\fR field is a human readable name representing the device.


 195 Applications should not try to interpret it.
 196 .sp
 197 The \fBcard_number\fR field indicates the number assigned to the aggregate
 198 device. This can be used with the \fBSNDCTL_CARDINFO\fR ioctl.
 199 .sp
 200 The \fBmixer_dev\fR is the mixer device number for the mixing device associated
 201 with the audio device. This can be used with the \fBSNDCTL_MIXERINFO\fR ioctl.
 202 .sp
 203 The caps field contains any of the bits \fBPCM_CAP_INPUT\fR,
 204 \fBPCM_CAP_OUTPUT\fR, and \fBPCM_CAP_DUPLEX\fR. Indicating whether the device















 205 support input, output, and whether input and output can be used simultaneously.
 206 All other bits are reserved.
 207 .sp
 208 The \fBmin_rate\fR and \fBmax_rate\fR fields indicate the minimum and maximum
 209 sample rates supported by the device. Most applications should try to use the
 210 maximum supported rate for the best audio quality and lowest system resource
 211 consumption.
 212 .sp
 213 The \fBmin_channels\fR and \fBmax_channels\fR provide an indication of the
 214 number of channels (1 for mono, 2 for stereo, 6 for 5.1, etc.) supported by the
 215 device.
 216 .sp
 217 The \fBdevnode\fR field contains the actual full path to the device node for
 218 this device, such as \fB/dev/sound/audio810:0dsp\fR. Applications should open
 219 this file to access the device.
 220 .RE
 221 
 222 .sp
 223 .ne 2
 224 .na
 225 \fB\fBSNDCTL_CARDINFO\fR\fR
 226 .ad
 227 .RS 20n
 228 The argument is a pointer to a \fBstruct oss_card_info\fR, which has the
 229 following definition:
 230 .sp
 231 .in +2
 232 .nf
 233 typedef struct oss_card_info {
 234 int card;
 235  char shortname[16];
 236  char longname[128];
 237  int flags;/* reserved */
 238  char hw_info[400];
 239  int intr_count;/* reserved */
 240  int ack_count;/* reserved */
 241  int filler[154];
 242 } oss_card_info;
 243 .fi
 244 .in -2
 245 .sp
 246 
 247 This ioctl is used to query for information about the aggregate audio device.
 248 .sp
 249 The \fBcard\fR field should be initialized by the application to the number of
 250 the card to query. This is a number between zero inclusive and value of
 251 \fBnumcards\fR (exclusive) returned by \fBSNDCTL_SYSINFO\fR.) Alternatively,
 252 when issuing the ioctl against a real mixer or \fBdsp\fR device, the special
 253 value \fB-1\fR can be used to indicate that the query is being made against the
 254 device opened. If \fB-1\fR is used, the field is overwritten with the number














 255 for the current hardware device on successful return.
 256 .sp
 257 The \fBshortname\fR, \fBlongname\fR, and \fBhw_info\fR contain \fBASCIIZ\fR
 258 strings describing the device in more detail. The \fBhw_info\fR member can
 259 contain multiple lines of detail, each line ending in a NEWLINE.
 260 .sp
 261 The flag, intr_count, and ack_count fields are not used by this implementation.
 262 .RE
 263 
 264 .sp
 265 .ne 2
 266 .na
 267 \fB\fBSNDCTL_MIXERINFO\fR\fR
 268 .ad
 269 .RS 20n
 270 The argument is a pointer to a \fBstruct oss_mixer_info\fR, which has the
 271 following definition:
 272 .sp
 273 .in +2
 274 .nf





 275 typedef struct oss_mixerinfo {
 276   int dev;
 277   char id[16];/* Reserved */
 278   char name[32];
 279   int modify_counter;
 280   int card_number;
 281   int port_number;/* Reserved */
 282   char handle[32];/* Reserved */
 283   int magic;/* Reserved */
 284   int enabled;/* Reserved */
 285   int caps;/* Reserved */
 286   int flags;/* Reserved */
 287   int nrext;
 288   int priority;
 289   char devnode[32];/* Device special file name
 290                      (absolute path) */
 291   int legacy_device;/* Reserved */
 292   int filler[245];/* Reserved */
 293 } oss_mixerinfo;
 294 .fi
 295 .in -2
 296 .sp
 297 







 298 In the above structure, all of the fields are reserved except the following:
 299 \fBdev, name, modify_counter, card_number, nrext, priority,\fR and
 300 \fBdevnode\fR. The reserved fields are provided for compatibility with other
 301 OSS implementations, and available for legacy applications.  New applications
 302 should not attempt to use these fields.
 303 .sp
 304 The \fBdev\fR field should be initialized by the application to the number of
 305 the device to query. This is a number between zero inclusive and value of
 306 \fBnummixers\fR (exclusive) returned by \fBSNDCTL_SYSINFO\fR, or by
 307 \fBSNDCTL_MIX_NRMIX\fR. Alternatively, when issuing the ioctl against a real
 308 mixer or \fBdsp\fR device, the special value \fB-1\fR can be used to indicate
 309 that the query is being made against the device opened. If \fB-1\fR is used,




















 310 the field is overwritten with the mixer number for the current open file on
 311 successful return.
 312 .sp
 313 No other fields are significant upon entry, but on successful return contains
 314 details of the device.
 315 .sp
 316 The \fBname\fR field is a human readable name representing the device.


 317 Applications should not try to interpret it.
 318 .sp
 319 The \fBmodify_counter\fR is changed by the mixer framework each time the


 320 settings for the various controls or extensions of the device are changed.
 321 Applications can poll this value to learn if any other changes need to be
 322 searched for.
 323 .sp
 324 The \fBcard_number\fR field is the number of the aggregate audio device this
 325 mixer is located on. It can be used with the \fBSNDCTL_CARDINFO\fR ioctl.
 326 .sp
 327 The \fBnrext\fR field is the number of mixer extensions available on this
 328 mixer. See the \fBSNDCTL_MIX_NREXT\fR description.
 329 .sp









 330 The priority is used by the framework to assign a preference that applications
 331 can use in choosing a device. Higher values are preferable. Mixers with
 332 priorities less than -1 should never be selected by default.
 333 .sp
 334 The \fBdevnode\fR field contains the actual full path to the device node for
 335 the physical mixer, such as \fB/dev/sound/audio810:0mixer\fR. Applications





 336 should open this file to access the mixer settings.
 337 .RE
 338 
 339 .SS "Mixer Extension IOCTLs"
 340 .sp
 341 .LP
 342 The pseudo \fB/dev/mixer\fR device supports ioctls that can change     the
 343 various settings for the audio hardware in the system.
 344 .sp
 345 .LP
 346 Those ioctls should only be used by dedicated mixer applications  or desktop
 347 volume controls, and not by typical ordinary audio applications such as media
 348 players. Ordinary applications that wish to adjust their own volume settings
 349 should use the \fBSNDCTL_DSP_SETPLAYVOL\fR or \fBSNDCTL_DSP_SETRECVOL\fR ioctls
 350 for that purpose.  See \fBdsp\fR(7I) for more information.  Ordinary








 351 applications should never attempt to change master port selection or hardware
 352 settings such as monitor gain settings.
 353 .sp
 354 .LP
 355 The ioctls in this section can only be used to access the mixer device that is
 356 associated with the current file descriptor.
 357 .sp
 358 .LP
 359 Applications should not assume that a single \fB/dev/mixer\fR node is able to
 360 access any physical settings. Instead, they should use the ioctl
 361 \fBSNDCTL_MIXERINFO\fR to determine the device path for the real mixer device,


 362 and issue ioctls on a file descriptor opened against the corresponding
 363 \fBdevnode\fR field.
 364 .sp
 365 .LP
 366 When a \fBdev\fR member is specified in each of the following ioctls, the
 367 application should specify \fB-1\fR, although for compatibility the mixer




 368 allows the application to specify the mixer device number.
 369 .sp
 370 .ne 2
 371 .na
 372 \fB\fBSNDCTL_MIX_NRMIX\fR\fR
 373 .ad
 374 .RS 23n
 375 The argument is a pointer to an integer, which receives the number of mixer
 376 devices in the system. Each can be queried by using its number with the
 377 \fBSNDCTL_MIXERINFO\fR ioctl. The same information is available using the
 378 \fBSNDCTL_SYSINFO\fR ioctl.
 379 .RE
 380 
 381 .sp
 382 .ne 2
 383 .na
 384 \fB\fBSNDCTL_MIX_NREXT\fR\fR
 385 .ad
 386 .RS 23n
 387 The argument is a pointer to an integer. On entry, the integer should contain
 388 the special value \fB-1\fR. On return the argument receives the number of mixer
 389 extensions (or mixer controls) supported by the mixer device. More details
 390 about each extension can be obtained by \fBSNDCTL_MIX_EXTINFO\fR ioctl.
 391 .RE
 392 
 393 .sp
 394 .ne 2
 395 .na
 396 \fB\fBSNDCTL_MIX_EXTINFO\fR\fR
 397 .ad
 398 .RS 23n
 399 The argument is a pointer to an \fBoss_mixext\fR structure which is defined as
 400 follows:
 401 .sp
 402 .in +2
 403 .nf
 404 typedef struct oss_mixext {
 405    int dev;  /* Mixer device number */
 406    int ctrl;  /* Extension number */
 407    int type;  /* Entry type */
 408    int maxvalue;
 409    int minvalue;
 410    int flags;
 411    char id[16];  /* Mnemonic ID (internal use) */
 412    int parent;   /* Entry# of parent
 413                     (-1 if root) */
 414    int dummy;   /* NOT SUPPORTED */
 415    int timestamp;
 416    char data[64];  /* Reserved */
 417    unsigned char enum_present[32];  /* Mask
 418                                        of allowed
 419                                        enum
 420                                        values */
 421    int control_no;  /* Reserved */
 422    unsigned int desc;  /* NOT SUPPORTED */
 423    char extname[32];
 424    int update_counter;
 425    int filler[7];  /* Reserved */
 426 } oss_mixext;
 427 .fi
 428 .in -2
 429 .sp
 430 
 431 On entry, the \fBdev\fR field should be initialized to the value \fB-1\fR, and
 432 the \fBctrl\fR field should be initialized with the number of the extension
 433 being accessed. Between 0, inclusive, and the value returned by
 434 \fBSNDCTL_MIX_NREXT\fR, exclusive.
 435 .sp






 436 Mixer extensions are organized as a logical tree, starting with a root node.
 437 The root node always has a \fBctrl\fR value of zero. The structure of the tree
 438 can be determined by looking at the parent field, which contains the extension
 439 number of the parent extension, or \fB-1\fR if the extension is the root
 440 extension.
 441 .sp
 442 The type indicates the type of extension used. This implementation supports the
 443 following values:
 444 .sp
 445 .in +2
 446 .nf
 447 MIXT_DEVROOT      Root node for extension tree
 448 MIXT_GROUP        Logical grouping of controls
 449 MXIT_ONOFF        Boolean value, 0 = off, 1 = on.
 450 MIXT_ENUM         Enumerated value, 0 to maxvalue.
 451 MIXT_MONOSLIDER   Monophonic slider, 0 to 255.
 452 MIXT_STEREOSLIDER Stereophonic slider, 0 to 255
 453                   (encoded as
 454                   lower two bytes in value.)
 455 MIXT_MARKER       Place holder, can ignore.
 456 .fi
 457 .in -2
 458 .sp
 459 
 460 The flags field is a bit array. This implementation makes use of the following
 461 possible bits:
 462 .sp
 463 .in +2
 464 .nf
 465 MIXF_READABLE    Extension's value is readable.
 466 MIXF_WRITEABLE   Extension's value is modifiable.
 467 MIXF_POLL        Extension can self-update.
 468 MIXF_PCMVOL      Extension is for master
 469                  PCM playback volume.
 470 MIXF_MAINVOL     Extension is for a typical
 471                  analog volume
 472 MIXF_RECVOL      Extension is for master
 473                  record gain.
 474 MIXF_MONVOL      Extension is for a monitor
 475                  source's gain.
 476 .fi
 477 .in -2
 478 .sp
 479 
 480 The \fBid\fR field contains an \fBASCIIZ\fR identifier for the extension.
 481 .sp
 482 The timestamp field is set when the extension tree is first initialized.
 483 Applications must use the same timestamp value when attempting to change the
 484 values. A change in the timestamp indicates a change a in the structure of the

 485 extension tree.
 486 .sp
 487 The \fBenum_present\fR field is a bit mask of possible enumeration values. If a
 488 bit is present in the \fBenum_present\fR mask, then the corresponding
 489 enumeration value is legal. The mask is in little endian order.
 490 .sp
 491 The \fBdesc\fR field provides information about scoping, which can be useful as
 492 layout hints to applications. The following hints are available:
 493 .sp
 494 .in +2
 495 .nf
 496 MIXEXT_SCOPE_MASK    Mask of possible scope
 497                      values.
 498 MIXEXT_SCOPE_INPUT   Extension is an input
 499                      control.
 500 MIXEXT_SCOPE_OUTPUT  Extension is an
 501                      output control.
 502 MIXEXT_SCOPE_MONITOR Extension relates to
 503                      input monitoring.
 504 MIXEXT_SCOPE_OTHER   No scoping hint provided.
 505 .fi
 506 .in -2
 507 .sp
 508 
 509 The \fBextname\fR is the full name of the extension.
 510 .sp
 511 The \fBupdate_counter\fR is incremented each time the control's value is
 512 changed.
 513 .RE
 514 
 515 .sp
 516 .ne 2
 517 .na
 518 \fB\fBSNDCTL_MIX_ENUMINFO\fR\fR
 519 .ad
 520 .RS 23n
 521 The argument is a pointer to an \fBoss_mixer_enuminfo\fR structure, which is
 522 defined as follows:
 523 .sp
 524 .in +2
 525 .nf
 526 typedef struct oss_mixer_enuminfo {
 527    int dev;
 528    int ctrl;
 529    int nvalues;
 530    int version;
 531    short strindex[255];
 532    char strings[3000];
 533 } oss_mixer_enuminfo;
 534 .fi
 535 .in -2
 536 .sp
 537 
 538 On entry, the \fBdev\fR field should be initialized to the value \fB-1\fR, and
 539 the \fBctrl\fR field should be initialized with the number of the extension
 540 being accessed. Between 0, inclusive, and the value returned by
 541 \fBSNDCTL_MIX_NREXT\fR, exclusive.
 542 .sp
 543 On return the \fBnvalues\fR field contains the number of values, and
 544 \fBstrindex\fR contains an array of indices into the strings member, each index
 545 pointing to an \fBASCIIZ\fR describing the enumeration value.
 546 .RE
 547 
 548 .sp
 549 .ne 2
 550 .na
 551 \fB\fBSNDCTL_MIX_READ\fR\fR
 552 .ad
 553 .br
 554 .na
 555 \fB\fBSNDCTL_MIX_WRITE\fR\fR
 556 .ad
 557 .RS 23n
 558 The argument is a pointer to an \fBoss_mixer_value\fR structure, defined as
 559 follows:
 560 .sp
 561 .in +2
 562 .nf
 563 typedef struct oss_mixer_value {
 564    int dev;
 565    int ctrl;
 566    int value;
 567    int flags;  /* Reserved for future use.
 568                   Initialize to 0 */
 569    int timestamp;  /* Must be set to
 570                       oss_mixext.timestamp */
 571    int filler[8];  /* Reserved for future use.
 572                       Initialize to 0 */
 573 } oss_mixer_value;
 574 .fi
 575 .in -2
 576 .sp
 577 
 578 On entry, the \fBdev\fR field should be initialized to the value \fB-1\fR, and
 579 the \fBctrl\fR field should be initialized with the number of the extension
 580 being accessed. Between 0, inclusive, and the value returned by
 581 \fBSNDCTL_MIX_NREXT\fR, exclusive. Additionally, the timestamp member must be
 582 initialized to the same value as was supplied in the \fBoss_mixext\fR structure
 583 used with \fBSNDCTL_MIX_EXTINFO\fR.
 584 .sp
 585 For \fBSNDCTL_MIX_WRITE\fR, the application should supply the new value for the
 586 extension. For \fBSNDCTL_MIX_READ\fR, the mixer returns the extensions current
 587 value in value.
 588 .RE
 589 
 590 .SS "Compatibility IOCTLs"
 591 .sp
 592 .LP
 593 The following ioctls are for compatibility use only:
 594 .sp
 595 .in +2
 596 .nf
 597 SOUND_MIXER_READ_VOLUME
 598 SOUND_MIXER_READ_PCM
 599 SOUND_MIXER_READ_OGAIN
 600 SOUND_MIXER_READ_RECGAIN
 601 SOUND_MIXER_READ_RECLEV
 602 SOUND_MIXER_READ_IGAIN
 603 SOUND_MIXER_READ_RECSRC
 604 SOUND_MIXER_READ_RECMASK
 605 SOUND_MIXER_READ_DEVMASK
 606 SOUND_MIXER_READ_STEREODEVS
 607 SOUND_MIXER_WRITE_VOLUME
 608 SOUND_MIXER_WRITE_PCM
 609 SOUND_MIXER_WRITE_OGAIN
 610 SOUND_MIXER_WRITE_RECGAIN
 611 SOUND_MIXER_WRITE_RECLEV
 612 SOUND_MIXER_WRITE_IGAIN
 613 SOUND_MIXER_WRITE_RECSRC
 614 SOUND_MIXER_WRITE_RECMASK
 615 SOUND_MIXER_INFO
 616 SNDCTL_AUDIOINFO_EX
 617 SNDCTL_ENGINEINFO
 618 .fi
 619 .in -2
 620 .sp
 621 
 622 .sp
 623 .LP























































 624 These ioctls can affect the software volume levels associated with the calling
 625 process. They have no effect on the physical hardware levels or settings. They
 626 should not be used in new applications.
 627 .SH ERRORS
 628 .sp
 629 .LP
 630 An \fBioctl()\fR fails if:
 631 .sp
 632 .ne 2
 633 .na
 634 \fB\fBEINVAL\fR\fR
 635 .ad
 636 .RS 10n




 637 The parameter changes requested in the ioctl are invalid or are not supported
 638 by the device.
 639 .RE
 640 
 641 .sp
 642 .ne 2
 643 .na
 644 \fB\fBENXIO\fR\fR
 645 .ad
 646 .RS 10n
 647 The device or extension referenced does not exist.
 648 .RE
 649 
 650 .SH FILES
 651 .sp
 652 .ne 2
 653 .na
 654 \fB\fB/dev/mixer\fR\fR
 655 .ad
 656 .RS 16n
 657 Symbolic link to the pseudo mixer device for the system
 658 .RE
 659 
 660 .sp
 661 .ne 2
 662 .na
 663 \fB\fB/dev/sndstat\fR\fR
 664 .ad
 665 .RS 16n
 666 Sound status device
 667 .RE
 668 
 669 .SH ATTRIBUTES
 670 .sp
 671 .LP
 672 See \fBattributes\fR(5) for a description of the following attributes:
 673 .sp
 674 
 675 .sp
 676 .TS
 677 box;
 678 c | c
 679 l | l .
 680 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 681 _
 682 Architecture    SPARC, x86
 683 _
 684 Stability Level See below.
 685 .TE
 686 
 687 .sp
 688 .LP
 689 The information and mixer extension IOCTLs are Uncommitted. The Compatibility
 690 IOCTLs are Obsolete Uncommitted. The extension names are Uncommitted.
 691 .SH SEE ALSO
 692 .sp
 693 .LP
 694 \fBclose\fR(2), \fBioctl\fR(2), \fBopen\fR(2), , \fBread\fR(2),
 695 \fBattributes\fR(5), \fBdsp\fR(7I)
 696 .SH BUGS
 697 .sp
 698 .LP
 699 The names of mixer extensions are not guaranteed to be predictable.

   1 .\"  Copyright (c) 2009 Sun Microsystems, Inc. All rights reserved.
   2 .\" Copyright 2019, Joyent, Inc.
   3 .\" The contents of this file are subject to the terms of the
   4 .\" Common Development and Distribution License (the "License").
   5 .\" You may not use this file except in compliance with the License.
   6 .\"
   7 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
   8 .\" or http://www.opensolaris.org/os/licensing.
   9 .\" See the License for the specific language governing permissions
  10 .\" and limitations under the License.
  11 .\"
  12 .\" When distributing Covered Code, include this CDDL HEADER in each
  13 .\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
  14 .\" If applicable, add the following below this CDDL HEADER, with the
  15 .\" fields enclosed by brackets "[]" replaced with your own identifying
  16 .\" information: Portions Copyright [yyyy] [name of copyright owner]
  17 .Dd February 1, 2019
  18 .Dt MIXER 7I
  19 .Os
  20 .Sh NAME
  21 .Nm mixer
  22 .Nd generic mixer device interface
  23 .Sh SYNOPSIS
  24 .In sys/soundcard.h
  25 .Sh DESCRIPTION
  26 .Ss "Mixer Pseudo-Device"
  27 The
  28 .Pa /dev/mixer
  29 pseudo-device is provided for two purposes:
  30 .Bl -bullet -offset indent
  31 .It
  32 The first purpose is for applications that wish to learn about the list of
  33 audio devices on the system, so that they can select (or provide for users to
  34 select) an appropriate audio device.
  35 The
  36 .Pa /dev/mixer
  37 pseudo-device
  38 provides interfaces to enumerate all of the audio devices on the system.
  39 .It




  40 The second purpose is for mixer panel type applications which need to control
  41 master settings for the audio hardware in the system, such as gain levels,
  42 balance, port functionality, and other device features.
  43 .El
  44 .Pp
  45 Ordinary audio applications should
  46 .Em not
  47 attempt to adjust their playback
  48 or record volumes or other device settings using this device.
  49 Instead, they
  50 should use the
  51 .Dv SNDCTL_DSP_SETPLAYVOL
  52 and
  53 .Dv SNDCTL_DSP_SETRECVOL
  54 ioctls that are documented in
  55 .Xr dsp 7I .
  56 .Ss "Sndstat Device"
  57 The
  58 .Pa /dev/sndstat
  59 device supports
  60 .Xr read 2 ,
  61 and can be read to
  62 retrieve human-readable information about the audio devices on the system.
  63 Software should not attempt to interpret the contents of this device.
  64 .Sh IOCTLS
  65 .Ss "Information IOCTLs"


  66 The following ioctls are intended to aid applications in identifying the audio
  67 devices available on the system.
  68 These ioctls can be issued against either the
  69 pseudo-device
  70 .Pa /dev/mixer ,
  71 or a against a file descriptor open to any
  72 other audio device in the system.
  73 .Pp
  74 Applications should issue
  75 .Dv SNDCTL_SYSINFO
  76 first to learn what audio
  77 devices and mixers are available on the system, and then use
  78 .Dv SNDCTL_AUDIOINFO
  79 or
  80 .Dv SNDCTL_MIXERINFO
  81 to obtain more information
  82 about the audio devices or mixers, respectively.
  83 .Bl -tag -width SNDCTL_AUDIOINFO
  84 .It Dv OSS_GETVERSION




  85 The argument is a pointer to an integer, which retrieves the version of the
  86 .Sy OSS API
  87 used.
  88 The value is encoded with the major version (currently 4)
  89 encoded in the most significant 16 bits, and a minor version encoded in the
  90 lower 16 bits.
  91 .It Dv SNDCTL_SYSINFO
  92 The argument is a pointer to an
  93 .Vt oss_sysinfo
  94 structure, which has the following definition:
  95 .Bd -literal -offset 2n








  96 typedef struct oss_sysinfo {
  97    char product[32];     /* E.g. SunOS Audio */
  98    char version[32];     /* E.g. 4.0a */
  99    int versionnum;       /* See OSS_GETVERSION */
 100    char options[128];    /* NOT SUPPORTED */
 101 
 102    int numaudios;        /* # of audio/dsp devices */
 103    int openedaudio[8];   /* Reserved, always 0 */
 104 
 105    int numsynths;        /* NOT SUPPORTED, always 0 */
 106    int nummidis;         /* NOT SUPPORTED, always 0 */
 107    int numtimers;        /* NOT SUPPORTED, always 0 */
 108    int nummixers;        /* # of mixer devices */
 109 
 110    /* Mask of midi devices are busy */
 111    int openedmidi[8];
 112 
 113    /* Number of sound cards in the system */
 114    int numcards;
 115 
 116    /* Number of audio engines in the system */
 117    int numaudioengines;
 118    char license[16];         /* E.g. "GPL" or "CDDL" */
 119    char revision_info[256];  /* Reserved */
 120    int filler[172];          /* Reserved */
 121 } oss_sysinfo;
 122 .Ed
 123 .Pp
 124 The important fields here are
 125 .Fa numaudios ,
 126 which is used to determine the
 127 number of audio devices that can be queried with
 128 .Dv SNDCTL_AUDIOINFO ,
 129 .Fa nummixers
 130 which provides a count of mixers on the system, and
 131 .Fa numcards
 132 which counts to total number of aggregate devices.
 133 A
 134 .Sy card
 135 can consist of one or more audio devices and one or more mixers, although more
 136 typically there is exactly one audio device and one mixer for each card.
 137 .It Dv SNDCTL_AUDIOINFO
 138 The argument is a pointer to an
 139 .Vt oss_audioinfo
 140 structure, which has the following structure:
 141 .Bd -literal -offset 2n








 142 typedef struct oss_audioinfo {
 143    int dev;             /* Device to query */
 144    char name[64];       /* Human readable name */
 145    int busy;            /* reserved */
 146    int pid;             /* reserved */
 147 
 148    /* PCM_CAP_INPUT, PCM_CAP_OUTPUT */
 149    int caps;
 150    int iformats;        /* Supported input formats */
 151    int oformats;        /* Supported output formats */
 152    int magic;           /* reserved */
 153    char cmd[64];        /* reserved */
 154    int card_number;
 155    int port_number;     /* reserved */
 156    int mixer_dev;
 157 
 158    /* Obsolete field.  Replaced by devnode */
 159    int legacy_device;
 160    int enabled;         /* reserved */
 161    int flags;           /* reserved */
 162    int min_rate;        /* Minimum sample rate */
 163    int max_rate;        /* Maximum sample rate */
 164    int min_channels;  /* Minimum number of channels */
 165    int max_channels;  /* Maximum number of channels */


 166    int binding;         /* reserved */
 167    int rate_source;     /* reserved */
 168    char handle[32];     /* reserved */
 169    unsigned int nrates;     /* reserved */
 170    unsigned int rates[20];  /* reserved */
 171    char song_name[64];  /* reserved */
 172    char label[16];      /* reserved */
 173    int latency;         /* reserved */
 174 
 175    /* Device special file name (absolute path) */
 176    char devnode[32];
 177    int next_play_engine;    /* reserved */
 178    int next_rec_engine;     /* reserved */
 179    int filler[184];         /* reserved */
 180 } oss_audioinfo;
 181 .Ed
 182 .Pp


 183 In the above structure, all of the fields are reserved except the following:
 184 .Fa dev ,
 185 .Fa name ,
 186 .Fa card_number ,
 187 .Fa mixer_dev ,
 188 .Fa caps ,
 189 .Fa min_rate ,
 190 .Fa max_rate ,
 191 .Fa min_channels ,
 192 .Fa max_channels ,
 193 and
 194 .Fa devnode .
 195 The reserved fields are provided for compatibility with other OSS
 196 implementations, and available for legacy applications.
 197 New applications should not attempt to use these fields.
 198 .Pp
 199 The
 200 .Fa dev
 201 field should be initialized by the application to the number of
 202 the device to query.
 203 This is a number between zero (inclusive) and value of
 204 .Fa numaudios
 205 (exclusive) returned by
 206 .Dv SNDCTL_SYSINFO .
 207 Alternatively,
 208 when issuing the ioctl against a real mixer or
 209 .Sy dsp
 210 device, the special
 211 value
 212 .Sy -1
 213 can be used to indicate that the query is being made against the device opened.
 214 If
 215 .Sy -1
 216 is used, the field is overwritten with the device
 217 number for the current device on successful return.
 218 .Pp
 219 No other fields are significant upon entry, but a successful return contains
 220 details of the device.
 221 .Pp
 222 The
 223 .Fa name
 224 field is a human readable name representing the device.
 225 Applications should not try to interpret it.
 226 .Pp
 227 The
 228 .Fa card_number
 229 field indicates the number assigned to the aggregate device.
 230 This can be used with the
 231 .Dv SNDCTL_CARDINFO
 232 ioctl.
 233 .Pp
 234 The
 235 .Fa mixer_dev
 236 is the mixer device number for the mixing device associated
 237 with the audio device.
 238 This can be used with the
 239 .Dv SNDCTL_MIXERINFO
 240 ioctl.
 241 .Pp
 242 The
 243 .Fa caps
 244 field contains any of the bits
 245 .Dv PCM_CAP_INPUT ,
 246 .Dv PCM_CAP_OUTPUT ,
 247 and
 248 .Dv PCM_CAP_DUPLEX .
 249 Indicating whether the device
 250 support input, output, and whether input and output can be used simultaneously.
 251 All other bits are reserved.
 252 .Pp
 253 The
 254 .Fa min_rate
 255 and
 256 .Fa max_rate
 257 fields indicate the minimum and maximum sample rates supported by the device.
 258 Most applications should try to use the maximum supported rate for the best
 259 audio quality and lowest system resource consumption.
 260 .Pp
 261 The
 262 .Fa min_channels
 263 and
 264 .Fa max_channels
 265 provide an indication of the number of channels (1 for mono, 2 for stereo,
 266 6 for 5\&.1, etc\&.) supported by the device.
 267 .Pp
 268 The
 269 .Fa devnode
 270 field contains the actual full path to the device node for this device, such as
 271 .Pa /dev/sound/audio810:0dsp .
 272 Applications should open this file to access the device.
 273 .It Dv SNDCTL_CARDINFO
 274 The argument is a pointer to a
 275 .Vt struct oss_card_info ,
 276 which has the following definition:
 277 .Bd -literal -offset 2n
 278 typedef struct oss_card_info {
 279    int card;
 280    char shortname[16];
 281    char longname[128];
 282    int flags;          /* reserved */
 283    char hw_info[400];
 284    int intr_count;     /* reserved */
 285    int ack_count;      /* reserved */
 286    int filler[154];
 287 } oss_card_info;
 288 .Ed
 289 .Pp


 290 This ioctl is used to query for information about the aggregate audio device.
 291 .Pp
 292 The
 293 .Fa card
 294 field should be initialized by the application to the number of
 295 the card to query.
 296 This is a number between zero
 297 .Pq inclusive
 298 and value of
 299 .Fa numcards
 300 .Pq exclusive
 301 returned by
 302 .Dv SNDCTL_SYSINFO .
 303 Alternatively,
 304 when issuing the ioctl against a real mixer or
 305 .Sy dsp
 306 device, the special value
 307 .Sy -1
 308 can be used to indicate that the query is being made against the device opened.
 309 If
 310 .Sy -1
 311 is used, the field is overwritten with the number
 312 for the current hardware device on successful return.
 313 .Pp
 314 The
 315 .Fa shortname ,
 316 .Fa longname ,
 317 and
 318 .Fa hw_info
 319 contain
 320 .Sy ASCIIZ
 321 strings describing the device in more detail.
 322 The
 323 .Fa hw_info
 324 member can contain multiple lines of detail, each line ending in a NEWLINE.
 325 .Pp
 326 The
 327 .Fa flag ,
 328 .Fa intr_count ,
 329 and
 330 .Fa ack_count
 331 fields are not used by this implementation.
 332 .It Dv SNDCTL_MIXERINFO
 333 The argument is a pointer to a
 334 .Vt struct oss_mixer_info ,
 335 which has the following definition:
 336 .Bd -literal -offset 2n
 337 typedef struct oss_mixerinfo {
 338     int dev;
 339     char id[16];        /* Reserved */
 340     char name[32];
 341     int modify_counter;
 342     int card_number;
 343     int port_number;    /* Reserved */
 344     char handle[32];    /* Reserved */
 345     int magic;          /* Reserved */
 346     int enabled;        /* Reserved */
 347     int caps;           /* Reserved */
 348     int flags;          /* Reserved */
 349     int nrext;
 350     int priority;








 351 
 352     /* Deice special file name (absolute path) */
 353     char devnode[32];
 354     int legacy_device;  /* Reserved */
 355     int filler[245];    /* Reserved */
 356 } oss_mixerinfo;
 357 .Ed
 358 .Pp
 359 In the above structure, all of the fields are reserved except the following:
 360 .Fa dev ,
 361 .Fa name ,
 362 .Fa modify_counter ,
 363 .Fa card_number ,
 364 .Fa nrext ,
 365 .Fa priority ,
 366 and
 367 .Fa devnode .
 368 The reserved fields are provided for compatibility with other
 369 OSS implementations, and available for legacy applications.
 370 New applications should not attempt to use these fields.
 371 .Pp
 372 The
 373 .Fa dev
 374 field should be initialized by the application to the number of
 375 the device to query.
 376 This is a number between zero inclusive and value of
 377 .Fa nummixers
 378 (exclusive) returned by
 379 .Dv SNDCTL_SYSINFO ,
 380 or by
 381 .Dv SNDCTL_MIX_NRMIX .
 382 Alternatively, when issuing the ioctl against a real mixer or
 383 .Sy dsp
 384 device, the special value
 385 .Sy -1
 386 can be used to indicate
 387 that the query is being made against the device opened.
 388 If
 389 .Sy -1
 390 is used,
 391 the field is overwritten with the mixer number for the current open file on
 392 successful return.
 393 .Pp
 394 No other fields are significant upon entry, but on successful return contains
 395 details of the device.
 396 .Pp
 397 The
 398 .Fa name
 399 field is a human readable name representing the device.
 400 Applications should not try to interpret it.
 401 .Pp
 402 The
 403 .Fa modify_counter
 404 is changed by the mixer framework each time the
 405 settings for the various controls or extensions of the device are changed.
 406 Applications can poll this value to learn if any other changes need to be
 407 searched for.
 408 .Pp
 409 The
 410 .Fa card_number
 411 field is the number of the aggregate audio device this
 412 mixer is located on.
 413 It can be used with the
 414 .Dv SNDCTL_CARDINFO
 415 ioctl.
 416 .Pp
 417 The
 418 .Fa nrext
 419 field is the number of mixer extensions available on this mixer.
 420 See the
 421 .Dv SNDCTL_MIX_NREXT
 422 description.
 423 .Pp
 424 The priority is used by the framework to assign a preference that applications
 425 can use in choosing a device.
 426 Higher values are preferable.
 427 Mixers with priorities less than -1 should never be selected by default.
 428 .Pp
 429 The
 430 .Fa devnode
 431 field contains the actual full path to the device node for
 432 the physical mixer, such as
 433 .Pa /dev/sound/audio810:0mixer .
 434 Applications
 435 should open this file to access the mixer settings.
 436 .El
 437 .Ss "Mixer Extension IOCTLs"
 438 The pseudo
 439 .Pa /dev/mixer
 440 device supports ioctls that can change the
 441 oarious settings for the audio hardware in the system.
 442 .Pp


 443 Those ioctls should only be used by dedicated mixer applications or desktop
 444 olumme controls, and not by typical ordinary audio applications such as media
 445 players.
 446 Ordinary applications that wish to adjust their own volume settings
 447 should use the
 448 .Dv SNDCTL_DSP_SETPLAYVOL
 449 or
 450 .Dv SNDCTL_DSP_SETRECVOL
 451 ioctls for that purpose.
 452 See
 453 .Xr dsp 7I
 454 for more information.
 455 Ordinary
 456 applications should never attempt to change master port selection or hardware
 457 settings such as monitor gain settings.
 458 .Pp

 459 The ioctls in this section can only be used to access the mixer device that is
 460 associated with the current file descriptor.
 461 .Pp
 462 Applications should not assume that a single
 463 .Pa /dev/mixer
 464 node is able to access any physical settings.
 465 Instead, they should use the ioctl
 466 .Dv SNDCTL_MIXERINFO
 467 to determine the device path for the real mixer device,
 468 and issue ioctls on a file descriptor opened against the corresponding
 469 .Fa devnode
 470 field.
 471 .Pp
 472 When a
 473 .Fa dev
 474 member is specified in each of the following ioctls, the
 475 application should specify
 476 .Sy -1 ,
 477 although for compatibility the mixer
 478 allows the application to specify the mixer device number.
 479 .Pp
 480 .Bl -tag -width SNDCTL_MIX_ENUMINFO -compact
 481 .It Dv SNDCTL_MIX_NRMIX



 482 The argument is a pointer to an integer, which receives the number of mixer
 483 devices in the system.
 484 Each can be queried by using its number with the
 485 .Dv SNDCTL_MIXERINFO
 486 ioctl.
 487 The same information is available using the
 488 .Fa SNDCTL_SYSINFO
 489 ioctl.
 490 .Pp
 491 .It Dv SNDCTL_MIX_NREXT
 492 The argument is a pointer to an integer.
 493 On entry, the integer should contain
 494 the special value
 495 .Sy -1 .
 496 On return the argument receives the number of mixer
 497 extensions (or mixer controls) supported by the mixer device.
 498 More details
 499 about each extension can be obtained by
 500 .Fa SNDCTL_MIX_EXTINFO
 501 ioctl.
 502 .Pp
 503 .It Dv SNDCTL_MIX_EXTINFO
 504 The argument is a pointer to an
 505 .Vt oss_mixext
 506 structure which is defined as follows:
 507 .Bd -literal -offset 2n



 508 typedef struct oss_mixext {
 509    int dev;            /* Mixer device number */
 510    int ctrl;           /* Extension number */
 511    int type;           /* Entry type */
 512    int maxvalue;
 513    int minvalue;
 514    int flags;
 515    char id[16];  /* Mnemonic ID (internal use) */
 516    int parent;   /* Entry# of parent (-1 if root) */

 517    int dummy;          /* NOT SUPPORTED */
 518    int timestamp;
 519    char data[64];      /* Reserved */
 520 
 521    /* Mask of allowed enum values */
 522    unsigned char enum_present[32];

 523    int control_no;     /* Reserved */
 524    unsigned int desc;  /* NOT SUPPORTED */
 525    char extname[32];
 526    int update_counter;
 527    int filler[7];      /* Reserved */
 528 } oss_mixext;
 529 .Ed
 530 .Pp
 531 On entry, the
 532 .Fa dev
 533 field should be initialized to the value
 534 .Sy -1 ,
 535 and
 536 the
 537 .Fa ctrl
 538 field should be initialized with the number of the extension
 539 being accessed.
 540 Between 0, inclusive, and the value returned by
 541 .Dv SNDCTL_MIX_NREXT ,
 542 exclusive.
 543 .Pp
 544 Mixer extensions are organized as a logical tree, starting with a root node.
 545 The root node always has a
 546 .Fa ctrl
 547 value of zero.
 548 The structure of the tree can be determined by looking at the parent field,
 549 which contains the extension number of the parent extension, or
 550 .Sy -1
 551 if the extension is the root extension.
 552 .Pp
 553 The type indicates the type of extension used.
 554 This implementation supports the following values:
 555 .Bl -column -offset 2n "MIXT_STEREOSLIDER" "Enumerated value, 0 to maxvalue"
 556 .It Dv MIXT_DEVROOT      Ta Root node for extension tree
 557 .It Dv MIXT_GROUP        Ta Logical grouping of controls
 558 .It Dv MXIT_ONOFF        Ta Boolean value, 0 = off, 1 = on.
 559 .It Dv MIXT_ENUM         Ta Enumerated value, 0 to maxvalue.
 560 .It Dv MIXT_MONOSLIDER   Ta Monophonic slider, 0 to 255.
 561 .It Dv MIXT_STEREOSLIDER Ta Stereophonic slider, 0 to 255 (encoded as lower two bytes in value.)
 562 .It Dv MIXT_MARKER       Ta Place holder, can ignore.
 563 .El
 564 .Pp
 565 The flags field is a bit array.
 566 This implementation makes use of the following


 567 possible bits:
 568 .Bl -column -offset 2n "MIXF_WRITEABLE" "Extensions value is modifiable"
 569 .It Dv MIXF_READABLE  Ta Extension's value is readable.
 570 .It Dv MIXF_WRITEABLE Ta Extension's value is modifiable.
 571 .It Dv MIXF_POLL      Ta Extension can self-update.
 572 .It Dv MIXF_PCMVOL    Ta Extension is for master PCM playback volume.
 573 .It Dv MIXF_MAINVOL   Ta Extension is for a typical analog volume
 574 .It Dv MIXF_RECVOL    Ta Extension is for master record gain.
 575 .It Dv MIXF_MONVOL    Ta Extension is for a monitor source's gain.
 576 .El
 577 .Pp
 578 The
 579 .Fa id
 580 field contains an
 581 .Sy ASCIIZ
 582 identifier for the extension.
 583 .Pp




 584 The timestamp field is set when the extension tree is first initialized.
 585 Applications must use the same timestamp value when attempting to change the
 586 values.
 587 A change in the timestamp indicates a change a in the structure of the
 588 extension tree.
 589 .Pp
 590 The
 591 .Fa enum_present
 592 field is a bit mask of possible enumeration values.
 593 If a
 594 bit is present in the
 595 .Fa enum_present
 596 mask, then the corresponding enumeration value is legal.
 597 The mask is in little endian order.
 598 .Pp
 599 The
 600 .Fa desc
 601 field provides information about scoping, which can be useful as
 602 layout hints to applications.
 603 The following hints are available:
 604 .Bl -column -offset 2n "MIXEXT_SCOPE_MONITOR" "No scoping hint provided."
 605 .It Dv MIXEXT_SCOPE_MASK    Ta Mask of possible scope values.
 606 .It Dv MIXEXT_SCOPE_INPUT   Ta Extension is an input control.
 607 .It Dv MIXEXT_SCOPE_OUTPUT  Ta Extension is an output control.
 608 .It Dv MIXEXT_SCOPE_MONITOR Ta Extension relates to input monitoring.
 609 .It Dv MIXEXT_SCOPE_OTHER   Ta No scoping hint provided.
 610 .El
 611 .Pp
 612 The
 613 .Fa extname
 614 is the full name of the extension.
 615 .Pp
 616 The
 617 .Fa update_counter
 618 is incremented each time the control's value is changed.
 619 .Pp
 620 .It Dv SNDCTL_MIX_ENUMINFO
 621 The argument is a pointer to an
 622 .Vt oss_mixer_enuminfo
 623 structure, which is defined as follows:
 624 .Bd -literal -offset 2n




 625 typedef struct oss_mixer_enuminfo {
 626    int dev;
 627    int ctrl;
 628    int nvalues;
 629    int version;
 630    short strindex[255];
 631    char strings[3000];
 632 } oss_mixer_enuminfo;
 633 .Ed
 634 .Pp
 635 On entry, the
 636 .Fa dev
 637 field should be initialized to the value
 638 .Sy -1 ,
 639 and
 640 the
 641 .Fa ctrl
 642 field should be initialized with the number of the extension being accessed.
 643 Between 0, inclusive, and the value returned by
 644 .Dv SNDCTL_MIX_NREXT ,
 645 exclusive.
 646 .Pp
 647 On return the
 648 .Fa nvalues
 649 field contains the number of values, and
 650 .Fa strindex
 651 contains an array of indices into the strings member, each index
 652 pointing to an
 653 .Sy ASCIIZ
 654 describing the enumeration value.
 655 .Pp
 656 .It Dv SNDCTL_MIX_READ
 657 .It Dv SNDCTL_MIX_WRITE
 658 The argument is a pointer to an
 659 .Vt oss_mixer_value
 660 structure, defined as follows:
 661 .Bd -literal -offset 2n
 662 typedef struct oss_mixer_value {
 663    int dev;
 664    int ctrl;
 665    int value;










 666 
 667    /* Reserved for future use.  Initialize to 0 */
 668    int flags;









 669 
 670    /* Must be set to oss_mixext.timestamp */
 671    int timestamp;





























 672 
 673    /* Reserved for future use.  Initialize to 0 */
 674    int filler[8];
 675 } oss_mixer_value;
 676 .Pp
 677 .Ed
 678 On entry, the
 679 .Fa dev
 680 field should be initialized to the value
 681 .Sy -1 ,
 682 and the
 683 .Fa ctrl
 684 field should be initialized with the number of the extension
 685 being accessed.
 686 Between 0, inclusive, and the value returned by
 687 .Dv SNDCTL_MIX_NREXT ,
 688 exclusive.
 689 Additionally, the timestamp member must be
 690 initialized to the same value as was supplied in the
 691 .Vt oss_mixext
 692 structure
 693 used with
 694 .Dv SNDCTL_MIX_EXTINFO .
 695 .Pp
 696 For
 697 .Dv SNDCTL_MIX_WRITE ,
 698 the application should supply the new value for the extension.
 699 For
 700 .Dv SNDCTL_MIX_READ ,
 701 the mixer returns the extensions current value in value.
 702 .El
 703 .Ss "Compatibility IOCTLs"
 704 The following ioctls are for compatibility use only:
 705 .Pp
 706 .Bl -tag -offset 2n -width SNDCTL_MIX_ENUMINFO -compact
 707 .It Dv SOUND_MIXER_READ_VOLUME
 708 .It Dv SOUND_MIXER_READ_PCM
 709 .It Dv SOUND_MIXER_READ_OGAIN
 710 .It Dv SOUND_MIXER_READ_RECGAIN
 711 .It Dv SOUND_MIXER_READ_RECLEV
 712 .It Dv SOUND_MIXER_READ_IGAIN
 713 .It Dv SOUND_MIXER_READ_RECSRC
 714 .It Dv SOUND_MIXER_READ_RECMASK
 715 .It Dv SOUND_MIXER_READ_DEVMASK
 716 .It Dv SOUND_MIXER_READ_STEREODEVS
 717 .It Dv SOUND_MIXER_WRITE_VOLUME
 718 .It Dv SOUND_MIXER_WRITE_PCM
 719 .It Dv SOUND_MIXER_WRITE_OGAIN
 720 .It Dv SOUND_MIXER_WRITE_RECGAIN
 721 .It Dv SOUND_MIXER_WRITE_RECLEV
 722 .It Dv SOUND_MIXER_WRITE_IGAIN
 723 .It Dv SOUND_MIXER_WRITE_RECSRC
 724 .It Dv SOUND_MIXER_WRITE_RECMASK
 725 .It Dv SOUND_MIXER_INFO
 726 .It Dv SNDCTL_AUDIOINFO_EX
 727 .It Dv SNDCTL_ENGINEINFO
 728 .El
 729 .Pp
 730 These ioctls can affect the software volume levels associated with the calling
 731 process.
 732 They have no effect on the physical hardware levels or settings.
 733 They should not be used in new applications.
 734 .Sh FILES
 735 .Bl -tag -width /dev/sndstat
 736 .It Pa /dev/mixer
 737 Symbolic link to the pseudo mixer device for the system
 738 .It Pa /dev/sndstat
 739 Sound status device
 740 .El
 741 .Sh ERRORS
 742 An
 743 .Xr ioctl 2
 744 fails if:
 745 .Bl -tag -width EINVAL
 746 .It Er EINVAL
 747 The parameter changes requested in the ioctl are invalid or are not supported
 748 by the device.
 749 .It Er ENXIO







 750 The device or extension referenced does not exist.
 751 .El
 752 .Sh ARCHITECTURE
 753 SPARC
 754 x86
 755 .Sh INTERFACE STABILITY
 756 The information and mixer extension IOCTLs are Uncommitted.
 757 The Compatibility IOCTLs are Obsolete Uncommitted.
 758 The extension names are Uncommitted.
 759 .Sh SEE ALSO
 760 .Xr close 2 ,
 761 .Xr ioctl 2 ,
 762 .Xr open 2 ,
 763 .Xr read 2 ,
 764 .Xr attributes 5 ,
 765 .Xr dsp 7I
 766 .Sh BUGS



































 767 The names of mixer extensions are not guaranteed to be predictable.