diff options
Diffstat (limited to 'usr/src/man/man4i/audio.4i')
| -rw-r--r-- | usr/src/man/man4i/audio.4i | 999 |
1 files changed, 999 insertions, 0 deletions
diff --git a/usr/src/man/man4i/audio.4i b/usr/src/man/man4i/audio.4i new file mode 100644 index 0000000000..5059b4746a --- /dev/null +++ b/usr/src/man/man4i/audio.4i @@ -0,0 +1,999 @@ +.\" Copyright (c) 2009 Sun Microsystems, Inc. All rights reserved. +.\" Copyright 2018, Joyent, Inc. +.\" The contents of this file are subject to the terms of the +.\" Common Development and Distribution License (the "License"). +.\" You may not use this file except in compliance with the License. +.\" +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE +.\" or http://www.opensolaris.org/os/licensing. +.\" See the License for the specific language governing permissions +.\" and limitations under the License. +.\" +.\" When distributing Covered Code, include this CDDL HEADER in each +.\" file and include the License file at usr/src/OPENSOLARIS.LICENSE. +.\" If applicable, add the following below this CDDL HEADER, with the +.\" fields enclosed by brackets "[]" replaced with your own identifying +.\" information: Portions Copyright [yyyy] [name of copyright owner] +.Dd July 8, 2018 +.Dt AUDIO 4I +.Os +.Sh NAME +.Nm audio +.Nd generic audio device interface +.Sh SYNOPSIS +.In sys/audio.h +.Sh OVERVIEW +An audio device is used to play and/or record a stream of audio data. +Since a +specific audio device may not support all functionality described below, refer +to the device-specific manual pages for a complete description of each hardware +device. +An application can use the +.Dv AUDIO_GETDEV +.Xr ioctl 2 +to determine the current audio hardware associated with +.Pa /dev/audio . +.Pp +The audio framework provides a software mixing engine (audio mixer) for all +audio devices, allowing more than one process to play or record audio at the +same time. +.Ss "Backward Compatibility" +It is no longer possible to disable the mixing function. +Applications must not +assume that they have exclusive access to the audio device. +.Ss "Multi-Stream Codecs" +The audio mixer supports multi-stream Codecs. +These devices have DSP engines +that provide sample rate conversion, hardware mixing, and other features. +The use of such hardware features is opaque to applications. +.Sh AUDIO FORMATS +Digital audio data represents a quantized approximation of an analog audio +signal waveform. +In the simplest case, these quantized numbers represent the +amplitude of the input waveform at particular sampling intervals. +To achieve the best approximation of an input signal, the highest possible sampling +frequency and precision should be used. +However, increased accuracy comes at a cost of increased data storage requirements. +For instance, one minute of +monaural audio recorded in \(*m-Law format (pronounced +.Em mew-law ) +at 8 KHz requires nearly 0.5 megabytes of storage, while the standard Compact Disc +audio format (stereo 16-bit linear +.Sy PCM +data sampled at 44.1 KHz) requires approximately 10 megabytes per minute. +.Pp +Audio data may be represented in several different formats. +An audio device's +current audio data format can be determined by using the +.Dv AUDIO_GETINFO +.Xr ioctl 2 +described below. +.Pp +An audio data format is characterized in the audio driver by four parameters: +Sample Rate, Encoding, Precision, and Channels. +Refer to the device-specific +manual pages for a list of the audio formats that each device supports. +In addition to the formats that the audio device supports directly, other formats +provide higher data compression. +Applications may convert audio data to and +from these formats when playing or recording. +.Ss "Sample Rate" +Sample rate is a number that represents the sampling frequency (in samples per +second) of the audio data. +.Pp +The audio mixer always configures the hardware for the highest possible sample +rate for both play and record. +This ensures that none of the audio streams +require compute-intensive low pass filtering. +The result is that high sample rate audio streams are not degraded by filtering. +.Pp +Sample rate conversion can be a compute-intensive operation, depending on the +number of channels and a device's sample rate. +For example, an 8KHz signal can +be easily converted to 48KHz, requiring a low cost up sampling by 6. +However, +converting from 44.1KHz to 48KHz is compute intensive because it must be up +sampled by 160 and then down sampled by 147. +This is only done using integer multipliers. +.Pp +Applications can greatly reduce the impact of sample rate conversion by +carefully picking the sample rate. +Applications should always use the highest +sample rate the device supports. +An application can also do its own sample rate +conversion (to take advantage of floating point and accelerated instruction or +use small integers for up and down sampling. +.Pp +All modern audio devices run at 48 kHz or a multiple thereof, hence just using +48 kHz may be a reasonable compromise if the application is not prepared to +select higher sample rates. +.Ss "Encodings" +An encoding parameter specifies the audio data representation. +\(*m-Law +encoding corresponds to +.Em CCITT G.711 , +and is the standard for voice data +used by telephone companies in the United States, Canada, and Japan. +A-Law encoding is also part of +.Em CCITT G.711 +and is the standard encoding for telephony elsewhere in the world. +A-Law and \(*m-Law audio data are sampled at +a rate of 8000 samples per second with 12-bit precision, with the data +compressed to 8-bit samples. +The resulting audio data quality is equivalent to +that of standard analog telephone service. +.Pp +Linear Pulse Code Modulation (PCM) is an uncompressed, signed audio format in +which sample values are directly proportional to audio signal voltages. +Each sample is a 2's complement number that represents a positive or negative +amplitude. +.Ss "Precision" +Precision indicates the number of bits used to store each audio sample. +For instance, \(*m-Law and A-Law data are stored with 8-bit precision. +.Sy PCM +data may be stored at various precisions, though 16-bit is the most common. +.Ss "Channels" +Multiple channels of audio may be interleaved at sample boundaries. +A sample frame consists of a single sample from each active channel. +For example, a sample frame of stereo 16-bit +.Sy PCM +data consists of two 16-bit samples, +corresponding to the left and right channel data. +.Pp +The audio mixer sets the hardware to the maximum number of channels supported. +If a mono signal is played or recorded, it is mixed on the first two (usually +the left and right) channels only. +Silence is mixed on the remaining channels +.Ss "Supported Formats" +The audio mixer supports the following audio formats: +.Bl -column "Signed Linear PCM" "Precision" "Mono or Stereo" -offset 2n +.It Encoding Ta Precision Ta Channels +.It "Signed Linear PCM" Ta "32-bit" Ta "Mono or Stereo" +.It "Signed Linear PCM" Ta "16-bit" Ta "Mono or Stereo" +.It "Signed Linear PCM" Ta "8-bit" Ta "Mono or Stereo" +.It "\(*m-Law" Ta "8-bit" Ta "Mono or Stereo" +.It "A-Law" Ta "8-bit" Ta "Mono or Stereo" +.El +.Pp +The audio mixer converts all audio streams to 24-bit Linear PCM before mixing. +After mixing, conversion is made to the best possible Codec format. +The +conversion process is not compute intensive and audio applications can choose +the encoding format that best meets their needs. +.Pp +Note that the mixer discards the low order 8 bits of 32-bit Signed Linear PCM +in order to perform mixing. +(This is done to allow for possible overflows to +fit into 32-bits when mixing multiple streams together.) +Hence, the maximum effective precision is 24-bits. +.Sh DESCRIPTION +The device +.Pa /dev/audio +is a device driver that dispatches audio requests +to the appropriate underlying audio hardware. +The audio driver is implemented as a +.Sy STREAMS +driver. +In order to record audio input, applications +.Xr open 2 +the +.Pa /dev/audio +device and read data from it using the +.Xr read 2 +system call. +Similarly, sound data is queued to the audio output port by using the +.Xr write 2 +system call. +Device configuration is performed using the +.Xr ioctl 2 +interface. +.Pp +Because some systems may contain more than one audio device, application +writers are encouraged to query the +.Ev AUDIODEV +environment variable. +If this variable is present in the environment, its value should identify the +path name of the default audio device. +.Ss "Opening the Audio Device" +The audio device is not treated as an exclusive resource. +Each process may open the audio device once. +.Pp +Each +.Xr open 2 +completes as long as there are channels available to be allocated. +If no channels are available to be allocated: +.Bl -bullet -offset indent +.It +if either the +.Dv O_NDELAY +or +.Dv O_NONBLOCK +flags are set in the +.Xr open 2 +.Fa oflag +argument, then -1 is immediately returned, with +.Va errno +set to +.Er EBUSY . +.It +if neither the +.Dv O_NDELAY +nor the +.Dv O_NONBLOCK +flag are set, then +.Xr open 2 +hangs until the device is available or a signal is delivered to +the process, in which case a -1 is returned with +.Va errno +set to +.Er EINTR . +.El +.Pp +Upon the initial +.Xr open 2 +of the audio channel, the audio mixer sets the data +format of the audio channel to the default state of 8-bit, 8Khz, mono \(*m-Law +data. +.Pp +If the audio device does not support this configuration, it informs the +audio mixer of the initial configuration. +Audio applications should explicitly set the encoding characteristics to match the +audio data requirements, and not depend on the default configuration. +.Ss "Recording Audio Data" +The +.Xr read 2 +system call copies data from the system's buffers to the application. +Ordinarily, +.Xr read 2 +blocks until the user buffer is filled. +The +.Dv I_NREAD +.Sy ioctl +(see +.Xr streamio 4I ) +may be used to determine the amount of data that may be read without blocking. +The device may alternatively be set to a non-blocking mode, in which case +.Xr read 2 +completes immediately, but may return fewer bytes than requested. +Refer to the +.Xr read 2 +manual page for a complete description of this behavior. +.Pp +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 +.Pq Dv O_WRONLY . +.Pp +The transfer of input data to +.Sy STREAMS +buffers may be paused (or resumed) by using the +.Dv AUDIO_SETINFO +.Sy ioctl +to set (or clear) the +.Fa record.pause +flag in the audio information structure (see below). +All unread input data in the +.Sy STREAMS +queue may be discarded by using the +.Dv I_FLUSH +.Sy STREAMS +ioctl. +See +.Xr streamio 4I . +When changing record parameters, the input stream should be paused and flushed +before the change, and resumed afterward. +Otherwise, subsequent reads 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. +.Pp +Input data can accumulate in +.Sy STREAMS +buffers very quickly. +At a minimum, +it will accumulate at 8000 bytes per second for 8-bit, 8 KHz, mono, \(*m-Law data. +If the device is configured 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, the +.Sy STREAMS +queue may become full. +When this occurs, the +.Fa record.error +flag is set in the audio information structure and input sampling ceases until +there is room in the input queue for additional 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. +.Ss "Playing Audio Data" +The +.Xr write 2 +system call copies data from an application's buffer to the +.Sy STREAMS +output queue. +Ordinarily, +.Xr write 2 +blocks until the entire user buffer is transferred. +The device may alternatively be set to a non-blocking mode, in which case +.Xr write 2 +completes immediately, but may have transferred fewer bytes than requested. +See +.Xr write 2 . +.Pp +Although +.Xr write 2 +returns when the data is successfully queued, the actual +completion of audio output may take considerably longer. +The +.Dv AUDIO_DRAIN +ioctl may be issued to allow an application to block until all of the +queued output data has been played. +Alternatively, a process may request +asynchronous notification of output completion by writing a zero-length buffer +(end-of-file record) to the output stream. +When such a buffer has been +processed, the +.Fa play.eof +flag in the audio information structure is incremented. +.Pp +The final +.Xr close 2 +of the file descriptor hangs until all of the audio +output has drained. +If a signal interrupts the +.Xr 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. +.Pp +The consumption of output data may be paused (or resumed) by using the +.Dv AUDIO_SETINFO +ioctl to set (or clear) the +.Fa play.pause +flag in the audio information structure. +Queued output data may be discarded by using +the +.Dv I_FLUSH +.Sy STREAMS +ioctl. +(See +.Xr streamio 4I ) . +.Pp +Output data is played from the +.Sy STREAMS +buffers at a default rate of at +least 8000 bytes per second for \(*m-Law, A-Law or 8-bit PCM data (faster for +16-bit linear data or higher sampling rates). +If the output queue becomes +empty, the +.Fa play.error +flag is set in the audio information structure and +output is stopped until additional data is written. +If an application attempts +to write a number of bytes that is not a multiple of the current sample frame +size, an error is generated and the bad data is thrown away. +Additional writes are allowed. +.Ss "Asynchronous I/O" +The +.Dv I_SETSIG +.Sy STREAMS +ioctl +enables asynchronous notification, through the +.Dv SIGPOLL +signal, of input and output ready condition changes. +The +.Dv O_NONBLOCK +flag may be set using the +.Dv F_SETFL +.Xr fcntl 2 +to +enable non-blocking +.Xr read 2 +and +.Xr write 2 +requests. +This is normally +sufficient for applications to maintain an audio stream in the background. +.Ss "Audio Control Pseudo-Device" +It is sometimes convenient to have an application, such as a volume control +panel, modify certain characteristics of the audio device while it is being +used by an unrelated process. +.Pp +The +.Pa /dev/audioctl +pseudo-device is provided for this purpose. +Any number of processes may open +.Pa /dev/audioctl +simultaneously. +However, +.Xr read 2 +and +.Xr write 2 +system calls are ignored by +.Pa /dev/audioctl . +The +.Dv AUDIO_GETINFO +and +.Dv AUDIO_SETINFO +ioctl commands may be issued to +.Pa /dev/audioctl +to determine the status or alter the behavior of +.Pa /dev/audio . +Note: In general, the audio control device name is +constructed by appending the letters +.Qq Sy ctl +to the path name of the audio device. +.Ss "Audio Status Change Notification" +Applications that open the audio control pseudo-device may request asynchronous +notification of changes in the state of the audio device by setting the +.Dv S_MSG +flag in an +.Dv I_SETSIG +.Sy STREAMS +ioctl. +Such processes receive a +.Dv SIGPOLL +signal when any of the following events occur: +.Bl -bullet -offset indent +.It +An +.Dv AUDIO_SETINFO +ioctl has altered the device state. +.It +An input overflow or output underflow has occurred. +.It +An end-of-file record (zero-length buffer) has been processed on output. +.It +An +.Xr open 2 +or +.Xr close 2 +of +.Pa /dev/audio +has altered the device state. +.It +An external event (such as speakerbox's volume control) has altered the device +state. +.El +.Sh IOCTLS +.Ss "Audio Information Structure" +The state of the audio device may be polled or modified using the +.Dv AUDIO_GETINFO +and +.Dv AUDIO_SETINFO +ioctl commands. +These commands operate on the +.Vt audio_info +structure as defined, in +.In sys/audio.h , +as follows: +.Bd -literal -offset 2n +/* + * This structure contains state information for audio device + * IO streams + */ + +struct audio_prinfo { + /* + * The following values describe the + * audio data encoding + */ + uint_t sample_rate; /* samples per second */ + uint_t channels; /* number of interleaved channels */ + uint_t precision; /* number of bits per sample */ + uint_t encoding; /* data encoding method */ + + /* + * The following values control audio device + * configuration + */ + uint_t gain; /* volume level */ + uint_t port; /* selected I/O port */ + uint_t buffer_size; /* I/O buffer size */ + + /* + * The following values describe the current device + * state + */ + uint_t samples; /* number of samples converted */ + uint_t eof; /* End Of File counter (play only) */ + uchar_t pause; /* non-zero if paused, zero to resume */ + uchar_t error; /* non-zero if overflow/underflow */ + uchar_t waiting; /* non-zero if a process wants access */ + uchar_t balance; /* stereo channel balance */ + + /* + * The following values are read-only device state + * information + */ + uchar_t open; /* non-zero if open access granted */ + uchar_t active; /* non-zero if I/O active */ + uint_t avail_ports; /* available I/O ports */ + uint_t mod_ports; /* modifiable I/O ports */ +}; +typedef struct audio_prinfo audio_prinfo_t; + +/* + * This structure is used in AUDIO_GETINFO and AUDIO_SETINFO ioctl + * commands + */ +struct audio_info { + audio_prinfo_t record;/* input status info */ + audio_prinfo_t play; /* output status info */ + uint_t monitor_gain; /* input to output mix */ + uchar_toutput_muted; /* non-zero if output muted */ + uint_t hw_features; /* supported H/W features */ + uint_t sw_features; /* supported S/W features */ + uint_t sw_features_enabled; + /* supported S/W features enabled */ +}; +typedef struct audio_info audio_info_t; + +/* Audio encoding types */ +#define AUDIO_ENCODING_ULAW (1) /* u-Law encoding */ +#define AUDIO_ENCODING_ALAW (2) /* A-Law encoding */ +#define AUDIO_ENCODING_LINEAR (3) /* Signed Linear PCM encoding */ + +/* + * These ranges apply to record, play, and + * monitor gain values + */ +#define AUDIO_MIN_GAIN (0)/* minimum gain value */ +#define AUDIO_MAX_GAIN (255) /* maximum gain value */ + +/* + * These values apply to the balance field to adjust channel + * gain values + */ +#define AUDIO_LEFT_BALANCE (0) /* left channel only */ +#define AUDIO_MID_BALANCE (32) /* equal left/right balance */ +#define AUDIO_RIGHT_BALANCE (64) /* right channel only */ + +/* + * Define some convenient audio port names + * (for port, avail_ports and mod_ports) + */ + +/* output ports (several might be enabled at once) */ +#define AUDIO_SPEAKER (0x01) /* built-in speaker */ +#define AUDIO_HEADPHONE (0x02) /* headphone jack */ +#define AUDIO_LINE_OUT (0x04) /* line out */ +#define AUDIO_SPDIF_OUT (0x08) /* SPDIF port */ +#define AUDIO_AUX1_OUT (0x10) /* aux1 out */ +#define AUDIO_AUX2_OUT (0x20) /* aux2 out */ + +/* + * input ports (usually only one may be enabled at a time) + */ +#define AUDIO_MICROPHONE (0x01) /* microphone */ +#define AUDIO_LINE_IN (0x02) /* line in */ +#define AUDIO_CD (0x04) /* on-board CD inputs */ +#define AUDIO_SPDIF_IN (0x08) /* SPDIF port */ +#define AUDIO_AUX1_IN (0x10) /* aux1 in */ +#define AUDIO_AUX2_IN (0x20) /* aux2 in */ +#define AUDIO_CODEC_LOOPB_IN (0x40) /* Codec inter. loopback */ + +/* These defines are for hardware features */ +#define AUDIO_HWFEATURE_DUPLEX (0x00000001u) +/* simult. play & cap. supported */ + +#define AUDIO_HWFEATURE_MSCODEC (0x00000002u) +/* multi-stream Codec */ + +/* These defines are for software features * +#define AUDIO_SWFEATURE_MIXER (0x00000001u) +/* audio mixer audio pers. mod. */ + +/* + * Parameter for the AUDIO_GETDEV ioctl + * to determine current audio devices + */ +#define MAX_AUDIO_DEV_LEN (16) +struct audio_device { + char name[MAX_AUDIO_DEV_LEN]; + char version[MAX_AUDIO_DEV_LEN]; + char config[MAX_AUDIO_DEV_LEN]; +}; +typedef struct audio_device audio_device_t; +.Ed +.Pp +The +.Fa play.gain +and +.Fa record.gain +fields specify the output and input volume levels. +A value of +.Dv AUDIO_MAX_GAIN +indicates maximum volume. +Audio output may also be temporarily muted by setting a non-zero value in the +.Fa output_muted +field. +Clearing this field restores audio output to the normal state. +.Pp +The +.Va monitor_gain +field is present for compatibility, and is no longer supported. +See +.Xr dsp 4I +for more detail. +.Pp +Likewise, the +.Fa play.port , +.Fa play.ports , +.Fa play.mod_ports , +.Fa record.port , +.Fa record.ports , +and +.Fa record.mod_ports +are no longer supported. +See +.Xr dsp 4I +for more detail. +.Pp +The +.Fa play.balance +and +.Fa record.balance +fields are fixed to +.Dv AUDIO_MID_BALANCE . +Changes to volume levels for different channels can be +made using the interfaces in +.Xr dsp 4I . +.Pp +The +.Fa play.pause +and +.Fa record.pause +flags may be used to pause and +resume the transfer of data between the audio device and the +.Sy STREAMS +buffers. +The +.Fa play.error +and +.Fa record.error +flags indicate that data underflow or overflow has occurred. +The +.Fa play.active +and +.Fa record.active +flags indicate that data transfer is currently active in the corresponding +direction. +.Pp +The +.Fa play.open +and +.Fa record.open +flags indicate that the device is +currently open with the corresponding access permission. +The +.Fa play.waiting +and +.Fa record.waiting +flags provide an indication that a process may be waiting to access the device. +These flags are set automatically when a process blocks on +.Xr open 2 , +though they may also be set using the +.Dv AUDIO_SETINFO +ioctl command. +They are cleared only when a process relinquishes access by closing the device. +.Pp +The +.Fa play.samples +and +.Fa record.samples +fields are zeroed at +.Xr open 2 +and are incremented each time a data sample is copied to or from +the associated +.Sy STREAMS +queue. +Some audio drivers may be limited to counting +buffers of samples, instead of single samples for their samples accounting. +For this reason, applications should not assume that the samples fields contain a +perfectly accurate count. +The +.Fa play.eof +field increments whenever a zero-length output buffer is synchronously processed. +Applications may use this +field to detect the completion of particular segments of audio output. +.Pp +The +.Fa record.buffer_size +field controls the amount of input data that is +buffered in the device driver during record operations. +Applications that have +particular requirements for low latency should set the value appropriately. +Note however that smaller input buffer sizes may result in higher system +overhead. +The value of this field is specified in bytes and drivers will +constrain it to be a multiple of the current sample frame size. +Some drivers may place other requirements on the value of this field. +Refer to the audio device-specific manual page for more details. +If an application changes the +format of the audio device and does not modify the +.Fa record.buffer_size +field, the device driver may use a default value to compensate for the new data +rate. +Therefore, if an application is going to modify this field, it should +modify it during or after the format change itself, not before. +When changing +the +.Fa record.buffer_size +parameters, the input stream should be paused and +flushed before the change, and resumed afterward. +Otherwise, subsequent reads +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. +If you change the +.Fa record.buffer_size +for the first packet, this protocol must be followed or the first buffer will +be the default buffer size for the device, followed by packets of the requested +change size. +.Pp +The +.Fa record.buffer_size +field may be modified only on the +.Pa /dev/audio +device by processes that have it opened for reading. +.Pp +The +.Fa play.buffer_size +field is currently not supported. +.Pp +The audio data format is indicated by the +.Fa sample_rate , +.Fa channels , +.Fa precision , +and +.Fa encoding +fields. +The values of these fields correspond to the +descriptions in the +.Sx "AUDIO FORMATS" +section of this man page. +Refer to the +audio device-specific manual pages for a list of supported data format +combinations. +.Pp +The data format fields can be modified only on the +.Pa /dev/audio +device. +.Pp +If the parameter changes requested by an +.Dv AUDIO_SETINFO +ioctl cannot all be accommodated, +.Xr ioctl 2 +returns with +.Va errno +set to +.Er EINVAL +and no changes are made to the device state. +.Ss "Streamio IOCTLS" +All of the +.Xr streamio 4I +.Xr ioctl 2 +commands may be issued for the +.Pa /dev/audio +device. +Because the +.Pa /dev/audioctl +device has its own +.Sy STREAMS +queues, most of these commands neither modify nor report the +state of +.Pa /dev/audio +if issued for the +.Pa /dev/audioctl +device. +The +.Dv I_SETSIG +ioctl may be issued for +.Pa /dev/audioctl +to enable the notification of audio status changes, as described above. +.Ss "Audio IOCTLS" +The audio device additionally supports the following +.Xr ioctl 2 +commands: +.Bl -tag -width "AUDIO_GETINFO" +.It Dv AUDIO_DRAIN +The argument is ignored. +This command suspends the calling process until the +output STREAMS queue is empty and all queued samples have been played, or until +a signal is delivered to the calling process. +It may not be issued for the +.Pa /dev/audioctl +device. +An implicit +.Dv AUDIO_DRAIN +is performed on the final +.Xr close 2 +of +.Pa /dev/audio . +.It Dv AUDIO_GETDEV +The argument is a pointer to an +.Vt audio_device_t +structure. +This command may be issued for either +.Pa /dev/audio +or +.Pa /dev/audioctl . +The returned +value in the name field will be a string that will identify the current +.Pa /dev/audio +hardware device, the value in version will be a string +indicating the current version of the hardware, and +.Fa config +will be a device-specific string identifying the properties of the audio stream +associated with that file descriptor. +Refer to the audio device-specific manual +pages to determine the actual strings returned by the device driver. +.It Dv AUDIO_GETINFO +The argument is a pointer to an +.Vt audio_info_t +structure. +This command may be issued for either +.Pa /dev/audio +or +.Pa /dev/audioctl . +The current state of the +.Pa /dev/audio +device is returned in the structure. +Values return pertain to a logical view of the device as seen by and private to +the process, and do not necessarily reflect the actual hardware device itself. +.It Dv AUDIO_SETINFO +The argument is a pointer to an +.Vt audio_info_t +structure. +This command may be issued for either the +.Pa /dev/audio +or the +.Pa /dev/audioctl +device with some restrictions. +This command configures the audio device according to +the supplied structure and overwrites the existing structure with the new state +of the device. +Note: The +.Fa play.samples , +.Fa record.samples , +.Fa play.error , +.Fa record.error , +and +.Fa play.eof +fields are modified to reflect the state of the device when the +.Dv AUDIO_SETINFO +is issued. +This allows programs to automatically modify these fields while retrieving the +previous value. +.Pp +As with +.Dv AUDIO_SETINFO , +the settings managed by this ioctl deal with a +logical view of the device which is private to the process, and don't +necessarily have any impact on the hardware device itself. +.El +.Pp +Certain fields in the audio information structure, such as the pause flags, are +treated as read-only when +.Pa /dev/audio +is not open with the corresponding access permission. +Other fields, such as the gain levels and encoding +information, may have a restricted set of acceptable values. +Applications that +attempt to modify such fields should check the returned values to be sure that +the corresponding change took effect. +The +.Fa sample_rate , +.Fa channels , +.Fa precision , +and +.Fa encoding +fields treated as read-only for +.Pa /dev/audioctl , +so that applications can be guaranteed that the existing +audio format will stay in place until they relinquish the audio device. +.Dv AUDIO_SETINFO +will return +.Er EINVAL +when the desired configuration is not possible, or +.Er EBUSY +when another process has control of the audio device. +.Pp +All of the logical device state is reset when the corresponding I/O stream of +.Pa /dev/audio +is closed. +.Pp +The +.Vt audio_info_t +structure may be initialized through the use of the +.Dv AUDIO_INITINFO +macro. +This macro sets all fields in the structure to +values that are ignored by the +.Dv AUDIO_SETINFO +command. +For instance, the following code switches the output port from the built-in +speaker to the headphone jack without modifying any other audio parameters: +.Bd -literal -offset 2n +audio_info_t info; +AUDIO_INITINFO(); +info.play.port = AUDIO_HEADPHONE; +err = ioctl(audio_fd, AUDIO_SETINFO, ); +.Ed +.Pp +This technique eliminates problems associated with using a sequence of +.Dv AUDIO_GETINFO +followed by +.Dv AUDIO_SETINFO . +.Sh FILES +The physical audio device names are system dependent and are rarely used by +programmers. +Programmers should use the following generic device names: +.Bl -tag -width "/usr/share/audio/samples" +.It Pa /dev/audio +Symbolic link to the system's primary audio device +.It Pa /dev/audioctl +Symbolic link to the control device for +.Pa /dev/audio +.It Pa /dev/sound/0 +First audio device in the system +.It Pa /dev/sound/0ctl +Audio control device for +.Pa /dev/sound/0 +.It Pa /usr/share/audio/samples +Audio files +.El +.Sh ERRORS +An +.Xr open 2 +call will fail if: +.Bl -tag -width "EINTR" +.It Er EBUSY +The requested play or record access is busy and either the +.Dv O_NDELAY +or +.Dv O_NONBLOCK +flag was set in the +.Xr open 2 +request. +.It Er EINTR +The requested play or record access is busy and a signal interrupted the +.Xr open 2 +request. +.El +.Pp +An +.Xr ioctl 2 +call will fail if: +.Bl -tag -width "EINVAL" +.It Er EINVAL +The parameter changes requested in the +.Dv AUDIO_SETINFO +ioctl are invalid or are not supported by the device. +.El +.Sh ARCHITECTURE +SPARC +X86 +.Sh INTERFACE STABILITY +Obsolete Uncommitted +.Sh SEE ALSO +.Xr close 2 , +.Xr fcntl 2 , +.Xr ioctl 2 , +.Xr open 2 , +.Xr poll 2 , +.Xr read 2 , +.Xr write 2 , +.Xr dsp 4I , +.Xr streamio 4I , +.Xr attributes 7 +.Sh BUGS +Due to a feature of the +.Sy STREAMS +implementation, programs that are terminated or +exit without closing the audio device may hang for a short period while audio +output drains. +In general, programs that produce audio output should catch the +.Dv SIGINT +signal and flush the output stream before exiting. |