This is an old revision of the document!
Some of this is taken directly from the 4Front Technologies documentation, so portions © 4Front Technologies.
ioctls listed in current OSS v4.0 documentation
- [#todo Still missing]
- [#hmpf Still missing, and not fully documented]
- [#stub Stubbed]
- [#complete Already supported]
- [#obsolete Missing, but obsolete]
| Anchor(todo) Still missing | |||||
| ioctl | compatibility | summary | notes | argument | |
| Anchor(SNDCTL_DSP_COOKEDMODE)SNDCTL_DSP_COOKEDMODE | ossv4 | {Dis,en}able “on fly” format conversions | int enabled | ||
| SNDCTL_DSP_GET_CHNORDER | ossv4-draft | Get the channel ordering of a multi channel device | Under construction; “returns the interleaving order of a multichannel stream” | unsigned long long map | |
| SNDCTL_DSP_GETERROR | ~ossv3.8 | Returns audio device error information | Returns errors (ex: under/overrun) reported by device/driver. OSS docs discourage its use. | audio_errinfo | |
| SNDCTL_DSP_POLICY | ossv4 | Sets the timing policy of an audio device | User picks integer 0..10 where 0 uses minimum buffer sizes & 10 uses maximum sizes. Tradeoffs are latency vs. CPU usage. Quoth OSS, “easier to use version of SNDCTL_DSP_SETFRAGMENT.” | int policy | |
| SNDCTL_DSP_READCTL | ossv4 | Reads the S/PDIF interface status. | WIP? Missing formal documentation, but soundcard.h structure comments might be enough. | oss_digital_control | |
| SNDCTL_DSP_SYNCGROUP | ossv4 | Creates a synchronization group. | Tricky. Sync groups span across applications. What's their lifetime? How many group handles should there be? Etc. | oss_syncgroup group | |
| SNDCTL_DSP_SYNCSTART | ossv4 | Starts all devices added to a synchronization group. | int id | ||
| SNDCTL_DSP_WRITECTL | ossv4 | Alters the S/PDIF interface setup. | See READCTL | oss_digital_control ctl | |
| SNDCTL_MIX_ENUMINFO | ossv4 | Not fully documented. See $OSS/sndkit/samples/mixext.readme. oss_mixer_enuminfo is provided in soundcard.h, and can inspect ossmix.c (example program) for hints. | oss_mixer_enuminfo | ||
| SNDCTL_MIX_EXTINFO | ossv4 | Not fully documented. See $OSS/sndkit/samples/mixext.readme. | oss_mixext | ||
| SNDCTL_CARDINFO | ossv4? | Returns information about a sound card or pseudo device | “The usability of this call is very limited. It's provided only for completeness of the API. OSS API doesn't have any concept of card. Any information returned by this ioctl calld is reserved exclusively for the utility programs included in the OSS package. Applications should not try to use for this information in any ways.” | oss_card_info | |
| SNDCTL_MIXERINFO | ossv4 | Returns information about a mixer device | Ioctl call supported by all OSS devices. (See SNDCTL_AUDIOINFO.) | oss_mixerinfo | |
| Anchor(hmpf) Still missing, and not fully documented (inspect ioctl definitions, 4Front drivers) | |||||
| ioctl | compatibility | summary | notes | argument | |
| SNDCTL_GETLABEL | ossv4 | Returns label assigned to this device | No sample available. | oss_label_t | |
| SNDCTL_GETSONG | ossv4 | Returns the current song name (if given) related with this device | Referenced in softsynth_gtk.c. | oss_longname_t | |
| SNDCTL_MIDIINFO | ossv4 | Returns information about a MIDI device | No sample available. “Under construction.” | oss_midi_info | |
| SNDCTL_SETLABEL | ossv4 | Sets the label for this device | No sample available. | oss_label_t | |
| SNDCTL_SETNAME | ossv4 | Sets the name of this device (if changeable) | Referenced in softsynth_gtk.c. | oss_longname_t | |
| SNDCTL_SETSONG | ossv4 | Sets the song name related with this device. | Referenced in softsynth_gtk.c. | oss_longname_t | |
| Anchor(stub) Stubbed | |||||
| ioctl | compatibility | summary | notes | argument | |
| SNDCTL_DSP_CURRENT_IPTR | ossv4 | Returns current recording position | oss_count_t | ||
| SNDCTL_DSP_CURRENT_OPTR | ossv4 | Returns current playback position | oss_count_t | ||
| SNDCTL_DSP_GETIPEAKS | ossv4 | Returns peak levels for all recording channels | Returns peaks since last call in array of short integers. Not supported by all devices. If multiple applications are using this call w/ the same device, some peaks may be undetected b/c counters are reset w/ each call. | oss_peaks_t | |
| SNDCTL_DSP_GETOPEAKS | ossv4 | The peak levels for all playback channels | See GETIPEAKS. Same caveats (ex: multiple applications monitoring the same device). | oss_peaks_t | |
| SNDCTL_DSP_GET_PLAYTGT_NAMES | ossv4 | Returns labels for the currently available output routings | [http://manuals.opensound.com/developer/recsrc.c.html#LOC6 Example] | oss_mixer_enuminfo | |
| SNDCTL_DSP_GET_PLAYTGT | ossv4 | Returns the current output routing | [http://manuals.opensound.com/developer/recsrc.c.html#LOC6 Example] | int route | |
| SNDCTL_DSP_GETPLAYVOL | ossv4 | Returns the current audio playback volume | Quoth OSS, “This ioctl replaces the SOUND_MIXER_PCM method.” | int level | |
| SNDCTL_DSP_GET_RECSRC_NAMES | ossv4 | Returns labels for the currently available recording sources | See GET_PLAYTGT_NAMES. | oss_mixer_enuminfo | |
| SNDCTL_DSP_GET_RECSRC | ossv4 | Returns the current recording source | See GET_PLAYTGT. | int route | |
| SNDCTL_DSP_GETRECVOL | ossv4 | Returns the current audio recording level | Quoth OSS, “This ioctl call replaces the SOUND_MIXER_IGAIN/RECLEV method used with earlier OSS versions.” | int level | |
| SNDCTL_DSP_HALT_INPUT | ossv4 | Aborts audio recording operation | Quoth OSS, “In the earlier OSS versions this ioctl call was called as SNDCTL_DSP_RESET_INPUT. This name is still valid but for clarity reasons it is not recommended in new programs.” Usually used when changing audio format while recording is in progress. | NULL | |
| SNDCTL_DSP_HALT_OUTPUT | ossv4 | Aborts audio playback operation | Similar notes as HALT_INPUT. | NULL | |
| SNDCTL_DSP_LOW_WATER | ossv4 | Sets the trigger threshold for select() | int nbytes | ||
| SNDCTL_DSP_SET_PLAYTGT | ossv4 | Sets the current output routing | See GET_PLAYTGT_NAMES. | int route | |
| SNDCTL_DSP_SETPLAYVOL | ossv4 | Changes the current audio playback volume | “This ioctl call replaces the SOUND_MIXER_PCM method used with earlier OSS versions.” | int level | |
| SNDCTL_DSP_SET_RECSRC | ossv4 | Sets the current recording source | See GET_RECSRC_NAMES. | int route | |
| SNDCTL_DSP_SETRECVOL | ossv4 | Changes the current audio recording level | “This ioctl call replaces the SOUND_MIXER_IGAIN/RECLEV method used with earlier OSS versions.” | int level | |
| SNDCTL_DSP_SILENCE | ossv4 | Clears the playback buffer with silence | “Can be used to implement playback pause.” Resume w/ SNDCTL_DSP_SKIP. (So sound samples are just lost?) | NULL | |
| SNDCTL_DSP_SKIP | ossv4 | Discards all samples in the playback buffer | “This ioctl call discards all unplayed samples in the playback buffer by moving the current write position immediately before the point where the device is currently reading the samples. This feature can be used to emulate resume function after playback pause.” | NULL | |
| [wiki:Self:RyanBeasley/ioctlref/SNDCTL_AUDIOINFO SNDCTL_AUDIOINFO] | ossv4 | Return information about an audio device | Valid on audio, mixer, and MIDI devices. User can request info on any device, not just the one associated with the ioctl file descriptor. In that case, user must use SNDCTL_SYSINFO first to determine OSS device numbers. Supposed to return info directly from card driver, ie. hardware-only features. Should we cheat? | oss_audioinfo | |
| [wiki:Self:RyanBeasley/ioctlref/SNDCTL_SYSINFO SNDCTL_SYSINFO] | ossv4 | Return information about OSS and the devices | Supported by all devices. | oss_sysinfo | |
| Anchor(complete) Already supported | |||||
| ioctl | compatibility | summary | notes | argument | |
| Anchor(SNDCTL_DSP_CHANNELS)SNDCTL_DSP_CHANNELS | all versions | Set the number of audio channels | API doesn't limit number of channels; depends on device. (ex 1=mono, 2=stereo) | ||
| SNDCTL_DSP_GETBLKSIZE | all versions | Get the current fragment size | Obsoleted byBRSNDCTL_DSP_GETOSPACEBRSNDCTL_DSP_GETISPACEBR | int fragsize | |
| SNDCTL_DSP_GETCAPS | ~ossv3.5 | Returns the capabilities of an audio device | See [http://manuals.opensound.com/developer/audio_capabilities.html Audio device capabilties]BR | int caps | |
| SNDCTL_DSP_GETFMTS | all versions | Returns a list of natively supported sample formats | Supposed to report only native formats, but FreeBSD also reports emulated formats by default (toggled via sysctl). | ||
| SNDCTL_DSP_GETIPTR | all versions | Returns the current recording pointer | Useful only w/ mmap. Obsoleted by BR[#SNDCTL_DSP_CURRENT_IPTR SNDCTL_DSP_CURRENT_IPTR]. | count_info | |
| SNDCTL_DSP_GETISPACE | all versions | Returns the number of currently recorded bytes | Can be used to determine # of bytes that can be recorded w/o blocking. OSS docs state it's “out of fashion.” | audio_buf_info | |
| SNDCTL_DSP_GETODELAY | all versions | Returns the playback buffering delay | int delay | ||
| SNDCTL_DSP_GETOPTR | all versions | Returns the current playback pointer | Similar comments to GETIPTR. | count_info | |
| SNDCTL_DSP_GETOSPACE | all versions | Returns the number of currently recorded bytes | Can be used to determine # of bytes that can play w/o blocking. Quoth OSS docs, “This ioctl is out of fashion.” | audio_buf_info | |
| SNDCTL_DSP_GETTRIGGER | ??? | Returns the current trigger bits | Obsolete. “Will be removed from the API in distant future.” | ||
| SNDCTL_DSP_HALT | all versions | Aborts audio recording and/or playback operation | Quoth OSS, though I think there may be a copy/paste mistake somewhere, “There is no need to use this call after opening the device. In the earlier OSS versions this ioctl call was called as SNDCTL_DSP_RESET_OUTPUT.” | NULL | |
| SNDCTL_DSP_SETFRAGMENT | all versions | Sets the buffer size hint | User can hint at max # of fragments, size of fragments | int frag = (max_fragments « 16) | (size_selector) | |
| SNDCTL_DSP_POST | all versions | Forces audio playback to start | According to OSS, useless. FreeBSD just calls chn_start. | NULL | |
| SNDCTL_DSP_SETDUPLEX | all versions | Turns on the duplex mode | NULL | ||
| SNDCTL_DSP_SETFMT | all versions | Select the sample format | [http://manuals.opensound.com/developer/formats.html Supported formats]BRTODO: compare to presently supported formats (expecting no major differences) | int format | |
| SNDCTL_DSP_SETSYNCRO | ??? | Slaves the audio device to the /dev/sequencer driver | OSS: “obsolete”. | NULL | |
| SNDCTL_DSP_SETTRIGGER | all versions | Starts audio recording and/or playback in sync | OSS: “However in some cases it's necessary to start it manually. There are exactly three cases when it's necessary. 1) When using mmap() this is the only way to start the device. 2) When recording and playback needs to be started exactly at the same moment. 3) When doing normal recording but when even the first read cannot block.” | int mask | |
| SNDCTL_DSP_SPEED | all versions | Set the sampling rate | int rate | ||
| SNDCTL_DSP_SUBDIVIDE | pre-ossv4 | Requests the device to use smaller fragments | “Obsolete call. Not implemented in OSS 4.0 and later. Use SNDCTL_DSP_SETFRAGMENT instead.” | ||
| SNDCTL_DSP_SYNC | all versions | Suspend the application until all samples have been played | NULL | ||
| Anchor(obsolete) Missing, but obsolete | |||||
| ioctl | compatibility | summary | notes | argument | |
| Anchor(SNDCTL_DSP_BIND_CHANNEL)SNDCTL_DSP_BIND_CHANNEL | unofficial, obsolete | Route stereo output to the specified channels | Obsoleted byBR[#SNDCTL_DSP_SET_PLAYTGT SNDCTL_DSP_SET_PLAYTGT]BR[#SNDCTL_DSP_GET_PLAYTGT SNDCTL_DSP_GET_PLAYTGT]BR[#SNDCTL_DSP_GET_PLAYTGT_NAMES SNDCTL_DSP_GET_PLAYTGT_NAMES] | ||
| SNDCTL_DSP_GETCHANNELMASK | unofficial | Returns the bindings supported by the device | Same as [#SNDCTL_DSP_BIND_CHANNEL SNDCTL_DSP_BIND_CHANNEL] | ||
| SNDCTL_DSP_SAMPLESIZE | ??? | Sets the sample size | “This ioctl call is obsolete. You should use SNDCTL_DSP_SETFMT instead.” | ||