Technical data

audio(7I) Ioctl Requests SunOS 5.5

immediately, but may 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 immediately starts

buffering audio input data. Since this consumes system resources, processes that do not

record audio data should open the device write-only (O_WRONLY).

The transfer of input data to STREAMS buffers may be paused (or resumed) by using the

AUDIO_SETINFO ioctl to set (or clear) the record.pause ﬂag in the audio information struc-

ture (see below). All unread input data in theSTREAMS queue may be discarded by

using theI_FLUSH STREAMS ioctl (see streamio(7I)). When changingrecord parameters,

the input stream should be paused and ﬂushed before the change, and resumed after-

ward. Otherwise, subsequentreads may 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 inSTREAMS buffers very quickly. At a minimum, it will accu-

mulate at 8000 bytes per second for 8-bit, 8 KHz, mono, µ-law data. If the device is

conﬁgured for 16-bit linear or higher sample rates, it will accumulate even faster. If the

application that consumes the data cannot keep up with this data rate, theSTREAMS

queue may become full. When this occurs, the record.error ﬂag is set in the audio informa-

tion structure and input sampling ceases until there is room in the inputqueue for addi-

tional data. In such cases, the input data stream contains a discontinuity. For this reason,

audio recording applications should open the audio device when they are prepared to

begin reading data, rather than at the start of extensive initialization.

Playing Audio Data The write() system call copies data from an applications buffer to the STREAMS output

queue. Ordinarily, write() blocks until the entire user buffer is transferred. The device

may alternatively be set to a non-blocking mode, in which case write( ) completes

immediately, but may have transferred fewer bytes than requested (see write(2)).

Although write( ) returns when the data is successfully queued, the actual completion of

audio output may take considerably longer. TheAUDIO_DRAIN ioctl may be issued to

allow an application to block until all of the queued output data has been played. Alter-

natively, a process may request asynchronous notiﬁcation of output completion by writ-

ing a zero-length buffer (end-of-ﬁle record) to the output stream. When such a buffer has

been processed, the play.eof ﬂag in the audio information structure (see below) is incre-

mented.

The ﬁnal close(2) of the ﬁle descriptor hangs until audio output has drained. If a signal

interrupts the close(), or if the process exits without closing the device, any remaining

data queued for audio output is ﬂushed and the device is closed immediately.

The conversion of output data may be paused (or resumed) by using the

AUDIO_SETINFO ioctl to set (or clear) the play.pause ﬂag in the audio information struc-

ture. Queued output data may be discarded by using theI_FLUSH STREAMS ioctl.

Output data will be played from the STREAMS buffers at a rate of at least 8000 bytes per

second for µ-law or A-law data (faster for 16-bit linear data or higher sampling rates). If

the output queue becomes empty, the play.error ﬂag is set in the audio information

7I-26 modiﬁed 21 Mar 1995