Opening the Audio Device

The audio device is not treated as an exclusive resource.

Each open(2) completes as long as there are channels available to be allocated. If no channels are available to be allocated, the call returns -1 with the errno set to EBUSY.

Audio applications should explicitly set the encoding characteristics to match the audio data requirements after opening the device, and not depend on any default configuration.

Recording Audio Data

The read(2) system call copies data from the system's buffers to the application. Ordinarily, read(2) blocks until the user buffer is filled. The poll(2) system call can be used to determine the presence of data that can be read without blocking. The device can alternatively be set to a non-blocking mode, in which case read(2) completes immediately, but can return fewer bytes than requested. Refer to the read(2) manual page for a complete description of this behavior.

When the audio device is opened with read access, the device driver allocates resources for recording. Since this consumes system resources, processes that do not record audio data should open the device write-only (O_WRONLY).

The recording process can be stopped by using the SNDCTL_DSP_HALT_INPUT ioctl, which also discards all pending record data in underlying device FIFOs.

Before changing record parameters, the input should be stopped using the SNDCTL_DSP_HALT_INPUT ioctl, which also flushes the any underlying device input FIFOs. (This is not necessary if the process never started recording by calling read(2). Otherwise, subsequent reads can return samples in the old format followed by samples in the new format. This is particularly important when new parameters result in a changed sample size.

Input data can accumulate in device buffers very quickly. At a minimum, it accumulates at 8000 bytes per second for 8-bit, 8 KHz, mono, μ-Law data. If the device is configured for more channels, higher sample resolution, or higher sample rates, it accumulates even faster. If the application that consumes the data cannot keep up with this data rate, the underlying FIFOs can become full. When this occurs, any new incoming data is lost until the application makes room available by consuming data. Additionally, a record overrun is noted, which can be retrieved using the SNDCTL_DSP_GETERROR ioctl.

Record volume for a stream can be adjusted by issuing the SNDCTL_DSP_SETRECVOL ioctl. The volume can also be retrieved using the SNDCTL_DSP_GETRECVOL.

Playing Audio Data

The write(1) system call copies data from an application's buffer to the device output FIFO. Ordinarily, write(2) blocks until the entire user buffer is transferred. The device can alternatively be set to a non-blocking mode, in which case write(2) completes immediately, but might have transferred fewer bytes than requested. See write(2).

Although write(2) returns when the data is successfully queued, the actual completion of audio output might take considerably longer. The SNDCTL_DSP_SYNC ioctl can be issued to allow an application to block until all of the queued output data has been played.

The final close(2) of the file descriptor waits until all of the audio output has drained. If a signal interrupts the close(2), or if the process exits without closing the device, any remaining data queued for audio output is flushed and the device is closed immediately.

The output of playback data can be halted entirely, by calling the SNDCTL_DSP_HALT_OUTPUT ioctl. This also discards any data that is queued for playback in device FIFOs.

Before changing playback parameters, the output should be drained using the SNDCTL_DSP_SYNC ioctl, and then stopped using the SNDCTL_DSP_HALT_OUTPUT ioctl, which also flushes the any underlying device output FIFOs. This is not necessary if the process never started playback, such as by calling write(2). This is particularly important when new parameters result in a changed sample size.

Output data is played from the playback buffers at a default rate of at least 8000 bytes per second for μ-Law, A-Law or 8-bit PCM data (faster for 16-bit linear data or higher sampling rates). If the output FIFO becomes empty, the framework plays silence, resulting in audible stall or click in the output, until more data is supplied by the application. The condition is also noted as a play underrun, which can be determined using the SNDCTL_DSP_GETERROR ioctl.

Playback volume for a stream can be adjusted by issuing the SNDCTL_DSP_SETPLAYVOL ioctl. The volume can also be retrieved using the SNDCTL_DSP_GETPLAYVOL.

Asynchronous I/O

The O_NONBLOCK flag can be set using the F_SETFL fcntl(2) to enable non-blocking read(2) and write(2) requests. This is normally sufficient for applications to maintain an audio stream in the background.

It is also possible to determine the amount of data that can be transferred for playback or recording without blocking using the SNDCTL_DSP_GETOSPACE or SNDCTL_DSP_GETISPACE ioctls, respectively.

Mixer Pseudo-Device

The /dev/mixer provides access to global hardware settings such as master volume settings, etc. It is also the interface used for determining the hardware configuration on the system.

Applications should open(2) /dev/mixer, and use the SNDCTL_SYSINFO and SNDCTL_AUDIOINFO ioctls to determine the device node names of audio devices on the system. See mixer(4I) for additional details.

Information IOCTLs

The following ioctls are supported on the audio device, as well as the mixer device. See mixer(4I) for details.

OSS_GETVERSION
SNDCTL_SYSINFO
SNDCTL_AUDIOINFO
SNDCTL_MIXERINFO
SNDCTL_CARDINFO

Audio IOCTLs

The dsp device supports the following ioctl commands:

SNDCTL_DSP_SYNC

The argument is ignored. This command suspends the calling process until the output FIFOs are empty and all queued samples have been played, or until a signal is delivered to the calling process. An implicit SNDCTL_DSP_SYNC is performed on the final close(2) of the dsp device.

This ioctl should not be used unnecessarily, as if it is used in the middle of playback it causes a small click or pause, as the FIFOs are drained. The correct use of this ioctl is just before changing sample formats.

SNDCTL_DSP_HALT

 

SNDCTL_DSP_HALT_INPUT

 

SNDCTL_DSP_HALT_OUTPUT

The argument is ignored. All input or output (or both) associated with the file is halted, and any pending data is discarded.

SNDCTL_DSP_SPEED

The argument is a pointer to an integer, indicating the sample rate (in Hz) to be used. The rate applies to both input and output for the file descriptor. On return the actual rate, which can differ from that requested, is stored in the integer pointed to by the argument. To query the configured speed without changing it the value 0 can be used by the application.

SNDCTL_DSP_GETFMTS

The argument is a pointer to an integer, which receives a bit mask of encodings supported by the device. Possible values are:

AFMT_MU_LAW

8-bit unsigned μ-Law

AFMT_A_LAW

8-bit unsigned a-Law

AFMT_U8

8-bit unsigned linear PCM

AFMT_S16_LE

16-bit signed little-endian linear PCM

AFMT_S16_BE

16-bit signed big-endian linear PCM

AFMT_S16_NE

16-bit signed native-endian linear PCM

AFMT_U16_LE

16-bit unsigned little-endian linear PCM

AFMT_U16_BE

16-bit unsigned big-endian linear PCM

AFMT_U16_NE

16-bit unsigned native-endian linear PCM

AFMT_S24_LE

24-bit signed little-endian linear PCM, 32-bit aligned

AFMT_S24_BE

24-bit signed big-endian linear PCM, 32-bit aligned

AFMT_S24_NE

24-bit signed native-endian linear PCM, 32-bit aligned

AFMT_S32_LE

32-bit signed little-endian linear PCM

AFMT_S32_BE

32-bit signed big-endian linear PCM

AFMT_S32_NE

32-bit signed native-endian linear PCM

AFMT_S24_PACKED

24-bit signed little-endian packed linear PCM

Not all devices support all of these encodings. This implementation uses AFMT_S24_LE or AFMT_S24_BE, whichever is native, internally.

SNDCTL_DSP_SETFMT

The argument is a pointer to an integer, which indicates the encoding to be used. The same values as for SNDCTL_DSP_GETFMT can be used, but the caller can only specify a single option. The encoding is used for both input and output performed on the file descriptor.

SNDCTL_DSP_CHANNELS

The argument is a pointer to an integer, indicating the number of channels to be used (1 for mono, 2 for stereo, etc.) The value applies to both input and output for the file descriptor. On return the actual channel configuration (which can differ from that requested) is stored in the integer pointed to by the argument. To query the configured channels without changing it the value 0 can be used by the application.

SNDDCTL_DSP_GETCAPS

The argument is a pointer to an integer bit mask, which indicates the capabilities of the device. The bits returned can include:

PCM_CAP_OUTPUT

Device supports playback

PCM_CAP_INPUT

Device supports recording

PCM_CAP_DUPLEX

Device supports simultaneous playback and recording

SNDCTL_DSP_GETPLAYVOL

 

SNDCTL_DSP_GETRECVOL

The argument is a pointer to an integer to receive the volume level for either playback or record. The value is encoded as a stereo value with the values for two channels in the least significant two bytes. The value for each channel thus has a range of 0-100. In this implementation, only the low order byte is used, as the value is treated as a monophonic value, but a stereo value (with both channel levels being identical) is returned for compatibility.

SNDCTL_DSP_SETPLAYVOL

 

SNDCTL_DSP_SETRECVOL

The argument is a pointer to an integer indicating volume level for either playback or record. The value is encoded as a stereo value with the values for two channels in the least significant two bytes. The value for each channel has a range of 0-100. Note that in this implementation, only the low order byte is used, as the value is treated as a monophonic value. Portable applications should assign the same value to both bytes.

SNDCTL_DSP_GETISPACE

 

SNDCTL_DSP_GETOSPACE

The argument is a pointer to a struct audio_buf_info, which has the following structure:

typedef struct audio_buf_info {
   int fragments; /* # of available fragments */
   int fragstotal;
        /* Total # of fragments allocated */
   int fragsize;
        /* Size of a fragment in bytes */
   int bytes;
       /* Available space in bytes */
   /*
    * Note! 'bytes' could be more than
    * fragments*fragsize
    */
} audio_buf_info;

The fields fragments, fragstotal, and fragsize are intended for use with compatible applications (and in the future with mmap(2)) only, and need not be used by typical applications. On successful return the bytes member contains the number of bytes that can be transferred without blocking.

SNDCTL_DSP_CURRENT_IPTR

 

SNDCTL_DSP_CURRENT_OPTR

The argument is a pointer to an oss_count_t, which has the following definition:

typedef struct {
    long long samples;
       /* Total # of samples */
    int fifo_samples;
       /* Samples in device FIFO */
    int filler[32]; /* For future use */
} oss_count_t;

The samples field contains the total number of samples transferred by the device so far. The fifo_samples is the depth of any hardware FIFO. This structure can be useful for accurate stream positioning and latency calculations.

SNDCTL_DSP_GETIPTR

 

SNDCTL_DSP_GETOPTR

The argument is a pointer to a struct count_info, which has the following definition:

typedef struct count_info {
    unsigned int bytes;
      /* Total # of bytes processed */
    int blocks;
      /*
       * # of fragment transitions since
       * last time
       */
    int ptr; /* Current DMA pointer value */
} count_info;

These ioctls are primarily supplied for compatibility, and should not be used by most applications.

SNDCTL_DSP_GETODELAY

The argument is a pointer to an integer. On return, the integer contains the number of bytes still to be played before the next byte written are played. This can be used for accurate determination of device latency. The result can differ from actual value by up the depth of the internal device FIFO, which is typically 64 bytes.

SNDCTL_DSP_GETERROR

The argument is a pointer to a struct audio_errinfo, defined as follows:

typedef struct audio_errinfo {
     int play_underruns;
     int rec_overruns;
     unsigned int play_ptradjust;
     unsigned int rec_ptradjust;
     int play_errorcount;
     int rec_errorcount;
     int play_lasterror;
     int rec_lasterror;
     int play_errorparm;
     int rec_errorparm;
     int filler[16];
} audio_errinfo;

For this implementation, only the play_underruns and rec_overruns values are significant. No other fields are used in this implementation.

These fields are reset to zero each time their value is retrieved using this ioctl.

Compatibility IOCTLS

These ioctls are supplied exclusively for compatibility with existing applications. Their use is not recommended, and they are not documented here. Many of these are implemented as simple no-ops.