Open Sound System
OSS 4.x Programmer's Guide

Do you have problems with sound/audio application development? Don't panic! Click here for help!

The ioctl() system call

All OSS system calls follow the familiar Posix/Unix semantics. Please look at the standard manual page (man ioctl) for more informtion. This section will only explain some OSS related details. The error codes returned by OSS as well as their meaning will be described in the Possible error codes (errno) returned by OSS calls section.

The available ioctl call set depends on the device and the calls will be described in the chapters for each device type. All ioctl calls are non-blocking ones except few exceptions that are used to wait until the device has played all of the data written to it.

Some of the ioctl calls have no parameters at all. However most of them have one parameter that is a pointer to an integer variavle or to some structure. The function return of the ioctl() system call has no defined meaning. However return value of -1 means that an error has occurred. In that case the errno system variable will contain the exact error code (see above).

Even if the ioctl call didn't return error it's necessary to check the argument value to see if the device accepted the requested value. Many ioctl calls will use the nearest possible value of the one requested by the application was not supported. For example if an application requests sampling rate of 44000 Hz the device may change it to 44100 Hz. It's responsibility of the application to check if the returned value is suitable for it's purposes.

Most ioctl calls will return only when the application did something seriously wrong. Another reason to an error is that the device is not working properly. If a minor error occurred the ioctl call will just silently modify the argument to the value being actually used.

With OSS the return value of ioctl() is used only for error reporting. The return value has no defined meaning when the call was successful (and it will be 0 in most cases). Applications that use the ioctl return value are likely to fail under different OSS implementations.

Ioctl calls available on audio devices

SNDCTL_DSP_BIND_CHANNELRoute stereo output to the specified channels (obsolete)
SNDCTL_DSP_CHANNELSSet the number of audio channels
SNDCTL_DSP_COOKEDMODEDisable/enable the "on fly" format conversions made by the OSS software
SNDCTL_DSP_CURRENT_IPTRReturns the current recording position
SNDCTL_DSP_CURRENT_OPTRReturns the current playback position
SNDCTL_DSP_GETBLKSIZEGet the current fragment size (obsolete)
SNDCTL_DSP_GETCAPSReturns the capabilities of an audio device
SNDCTL_DSP_GETCHANNELMASKReturns the bindings supported by the device (obsolete)
SNDCTL_DSP_GET_CHNORDERGet the channel ordering of a multi channel device
SNDCTL_DSP_GETERRORReturns audio device error information
SNDCTL_DSP_GETFMTSReturns a list of natively supported sample formats
SNDCTL_DSP_GETIPEAKSThe peak levels for all recording channels
SNDCTL_DSP_GETIPTRReturns the current recording pointer (obsolete)
SNDCTL_DSP_GETISPACEReturns the amount of recorded data that can be read without blocking.
SNDCTL_DSP_GETODELAYReturns the playback buffering delay
SNDCTL_DSP_GETOPEAKSThe peak levels for all playback channels
SNDCTL_DSP_GETOPTRReturns the current playback pointer (obsolete)
SNDCTL_DSP_GETOSPACEReturns the amount of playback data that can be written without blocking.
SNDCTL_DSP_GET_PLAYTGT_NAMESReturns labels for the currently available output routings
SNDCTL_DSP_GET_PLAYTGTReturns the current output routing
SNDCTL_DSP_GETPLAYVOLReturns the current audio playback volume
SNDCTL_DSP_GET_RECSRC_NAMESReturns labels for the currently available recording sources
SNDCTL_DSP_GET_RECSRCReturns the current recording source
SNDCTL_DSP_GETRECVOLReturns the current audio recording level
SNDCTL_DSP_GETTRIGGERReturns the current trigger bits (obsolete)
SNDCTL_DSP_HALT_INPUTAborts audio recording operation
SNDCTL_DSP_HALT_OUTPUTAborts audio playback operation
SNDCTL_DSP_HALTAborts audio recording and/or playback operation
SNDCTL_DSP_LOW_WATERSets the trigger treshold for select()
SNDCTL_DSP_NONBLOCKForce non-blocking mode
SNDCTL_DSP_POLICYSets the timing policy of an audio device
SNDCTL_DSP_POSTForces audio playback to start (obsolete)
SNDCTL_DSP_READCTLReads the S/PDIF interface status.
SNDCTL_DSP_SAMPLESIZESets the sample size (obsolete)
SNDCTL_DSP_SETDUPLEXTurns on the duplex mode
SNDCTL_DSP_SETFMTSelect the sample format
SNDCTL_DSP_SETFRAGMENTSets the buffer size hint
SNDCTL_DSP_SET_PLAYTGTSets the current output routing
SNDCTL_DSP_SETPLAYVOLChanges the current audio playback volume
SNDCTL_DSP_SET_RECSRCSets the current recording source
SNDCTL_DSP_SETRECVOLChanges the current audio recording level
SNDCTL_DSP_SETSYNCROSlaves the audio device to the /dev/sequencer driver (obsolete)
SNDCTL_DSP_SETTRIGGERStarts audio recording and/or playback in sync
SNDCTL_DSP_SILENCEClears the playback buffer with silence
SNDCTL_DSP_SKIPDiscards all samples in the playback buffer
SNDCTL_DSP_SPEEDSet the sampling rate
SNDCTL_DSP_SUBDIVIDERequests the device to use smaller fragments (obsolete)
SNDCTL_DSP_SYNCGROUPCreates a synchronization group.
SNDCTL_DSP_SYNCSuspend the application until all samples have been played
SNDCTL_DSP_SYNCSTARTStarts all devices added to a synchronization group.
SNDCTL_DSP_WRITECTLAlters the S/PDIF interface setup.

Ioctl calls available on Mixer devices

SNDCTL_MIX_DESCRIPTIONGet description text for a mixer control
SNDCTL_MIX_ENUMINFOGet choice list for a MIXT_ENUM control
SNDCTL_MIX_EXTINFOGet a mixer extension descriptor.
SNDCTL_MIX_NREXTGet number of mixer extension descriptor records
SNDCTL_MIX_NRMIXGet number of mixer devices in the system
SNDCTL_MIX_READRead the current value of a mixer control
SNDCTL_MIX_WRITEChange value of a mixer control

Ioctl calls available on MIDI devices

midi_timingUsing the timed mode MIDI interface
SNDCTL_MIDI_EXPRESS_WRITEInserts MIDI messages to the beginning of the device output buffer.
SNDCTL_MIDI_INFOGet information about a MIDI device (OBSOLETE)
SNDCTL_MIDI_MPUCMDObsolete ioctl call
SNDCTL_MIDI_MPUMODEObsolete ioctl call
SNDCTL_MIDI_PRETIMESet the pre character wait time.
SNDCTL_MIDI_SETMODESet the interface mode

Device information ioctl calls

OSS_GETVERSIONReturns the OSS API version number of current system
SNDCTL_AUDIOINFOReturn information about an audio device
SNDCTL_CARDINFOReturns information about a sound card or pseudo device
SNDCTL_GETLABELReturns label assigned to this device
SNDCTL_GETSONGReturns the current song name (if given) related with this device
SNDCTL_MIDIINFOReturns information about a MIDI device
SNDCTL_MIXERINFOReturns information about a mixer device
SNDCTL_SETLABELSets the label for this device
SNDCTL_SETNAMESets the name of this device (if changeable)
SNDCTL_SETSONGSets the song name related with this device.
SNDCTL_SYSINFOReturn information about OSS and the devices

Copyright (C) 4Front Technologies, 2007. All rights reserved.
Back to index OSS web site