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_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_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_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_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 | |
| 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 | ||
| Anchor(stub) Stubbed | |||||
| ioctl | compatibility | summary | notes | argument | |
| SNDCTL_DSP_CURRENT_IPTR | ossv4 | Returns current recording position | Same caveat as SNDCTL_DSP_CURRENT_OPTR. | oss_count_t | |
| SNDCTL_DSP_CURRENT_OPTR | ossv4 | Returns current playback position | This operation queries the pre-feeder software buffer, not the actual hardware buffer. As such, the current pointer location isn't exactly accurate. This could be fixed by: (a) translating from hardware pointer location to this buffer; (b) fixing the COOKEDMODE ioctl command and using the hardware buffer pointer locations. (Just using the hardware locations is feasible, but not very useful to a userland application.) | oss_count_t | |
| SNDCTL_DSP_GETERROR | ~ossv3.8 | Returns audio device error information | FreeBSD impl. should work as advertised. | audio_errinfo | |
| SNDCTL_DSP_GETIPEAKS | ossv4 | Returns peak levels for all recording channels | Currently does next to nothing. Appears to be intended for devices with their own peak meters, so drivers must be twiddled. I'm considering doing analysis in-kernel as an off-by-default option, but I imagine any applications needing this functionality would also perform analysis themselves if the hardware wasn't available. | oss_peaks_t | |
| SNDCTL_DSP_GETOPEAKS | ossv4 | The peak levels for all playback channels | Same restrictions as SNDCTL_DSP_GETIPEAKS. | oss_peaks_t | |
| SNDCTL_DSP_GET_PLAYTGT_NAMES | ossv4 | Returns labels for the currently available output routings | Works, but is missing corresponding *SET* ioctl cmds. | oss_mixer_enuminfo | |
| SNDCTL_DSP_GET_PLAYTGT | ossv4 | Returns the current output routing | For now, each device node only corresponds to a single channel, so this will always return 0. (Same for SNDCTL_DSP_SET_PLAYTGT, too.) | int route | |
| SNDCTL_DSP_GETPLAYVOL | ossv4 | Returns the current audio playback volume | 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 SNDCTL_DSP_GET_PLAYTGT. | int route | |
| SNDCTL_DSP_GETRECVOL | ossv4 | Returns the current audio recording level | 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() | This is initially set to the device fragment size, but what happens when that is changed *after* calling this? Does a change in fragment size overwrite this? | 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 | 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 | There are two problems: 1. Channel assignment/allocation is non-deterministic, so opening an audio device node may not result in getting the corresponding hardware or virtual channel. 2. Is meant to query drivers directly to get rates, capabilities, etc., while _getcaps includes software-emulated formats. | oss_audioinfo | |
| [wiki:Self:RyanBeasley/ioctlref/SNDCTL_SYSINFO SNDCTL_SYSINFO] | ossv4 | Return information about OSS and the devices | For now, only gathers information about audio devices. (Is supposed to compile information about MIDI and mixer devices, too.) | 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.” | ||