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