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