1dsp(7I) Ioctl Requests dsp(7I)
2
6 dsp - generic audio device interface
7
9 #include <sys/soundcard.h>
10
13 To record audio input, applications open() the appropriate device and
14 read data from it using the read() system call. Similarly, sound data
15 is queued to the audio output port by using the write(2) system call.
16 Device configuration is performed using the ioctl(2) interface.
17 Because some systems can contain more than one audio device, applica‐
20 tion writers are encouraged to open the /dev/mixer device and determine
21 the physical devices present on the system using the SNDCTL_SYSINFO and
22 SNDCTL_AUDIOINFO ioctls. See mixer(7I). The user should be provided a
23 the ability to select a different audio device, or alternatively, an
24 environment variable such as AUDIODSP can be used. In the absence of
25 any specific configuration from the user, the generic device file,
26 /dev/dsp, can be used. This normally points to a reasonably appropri‐
27 ate default audio device for the system.
28 Opening the Audio Device
30 The audio device is not treated as an exclusive resource.
31 Each open() completes as long as there are channels available to be
34 allocated. If no channels are available to be allocated, the call
35 returns -1 with the errno set to EBUSY.
36 Audio applications should explicitly set the encoding characteristics
39 to match the audio data requirements after opening the device, and not
40 depend on any default configuration.
41 Recording Audio Data
43 The read() system call copies data from the system's buffers to the
44 application. Ordinarily, read() blocks until the user buffer is filled.
45 The poll(2) system call can be used to determine the presence of data
46 that can be read without blocking. The device can alternatively be set
47 to a non-blocking mode, in which case read() completes immediately, but
48 can return fewer bytes than requested. Refer to the read(2) manual page
49 for a complete description of this behavior.
50 When the audio device is opened with read access, the device driver
53 allocates resources for recording. Since this consumes system
54 resources, processes that do not record audio data should open the
55 device write-only (O_WRONLY).
56 The recording process can be stopped by using the SNDCTL_DSP_HALT_INPUT
59 ioctl, which also discards all pending record data in underlying device
60 FIFOs.
61 Before changing record parameters, the input should be stopped using
64 the SNDCTL_DSP_HALT_INPUT ioctl, which also flushes the any underlying
65 device input FIFOs. (This is not necessary if the process never started
66 recording by calling read(2). Otherwise, subsequent reads can return
67 samples in the old format followed by samples in the new format. This
68 is particularly important when new parameters result in a changed sam‐
69 ple size.
70 Input data can accumulate in device buffers very quickly. At a minimum,
73 it accumulates at 8000 bytes per second for 8-bit, 8 KHz, mono, u-Law
74 data. If the device is configured for more channels, higher sample res‐
75 olution, or higher sample rates, it accumulates even faster. If the
76 application that consumes the data cannot keep up with this data rate,
77 the underlying FIFOs can become full. When this occurs, any new incom‐
78 ing data is lost until the application makes room available by consum‐
79 ing data. Additionally, a record overrun is noted, which can be
80 retrieved using the SNDCTL_DSP_GETERROR ioctl.
81 Record volume for a stream can be adjusted by issuing the SND‐
84 CTL_DSP_SETRECVOL ioctl. The volume can also be retrieved using the
85 SNDCTL_DSP_GETRECVOL.
86 Playing Audio Data
88 The write() system call copies data from an application's buffer to the
89 device output FIFO. Ordinarily, write() blocks until the entire user
90 buffer is transferred. The device can alternatively be set to a non-
91 blocking mode, in which case write()completes immediately, but might
92 have transferred fewer bytes than requested. See write(2).
93 Although write() returns when the data is successfully queued, the
96 actual completion of audio output might take considerably longer. The
97 SNDCTL_DSP_SYNC ioctl can be issued to allow an application to block
98 until all of the queued output data has been played.
99 The final close(2) of the file descriptor waits until all of the audio
102 output has drained. If a signal interrupts the close(), or if the
103 process exits without closing the device, any remaining data queued for
104 audio output is flushed and the device is closed immediately.
105 The output of playback data can be halted entirely, by calling the SND‐
108 CTL_DSP_HALT_OUTPUT ioctl. This also discards any data that is queued
109 for playback in device FIFOs.
110 Before changing playback parameters, the output should be drained using
113 the SNDCTL_DSP_SYNC ioctl, and then stopped using the SND‐
114 CTL_DSP_HALT_OUTPUT ioctl, which also flushes the any underlying device
115 output FIFOs. This is not necessary if the process never started play‐
116 back, such as by calling write(2). This is particularly important when
117 new parameters result in a changed sample size.
118 Output data is played from the playback buffers at a default rate of at
121 least 8000 bytes per second for u-Law, A-Law or 8-bit PCM data (faster
122 for 16-bit linear data or higher sampling rates). If the output FIFO
123 becomes empty, the framework plays silence, resulting in audible stall
124 or click in the output, until more data is supplied by the application.
125 The condition is also noted as a play underrun, which can be determined
126 using the SNDCTL_DSP_GETERROR ioctl.
127 Playback volume for a stream can be adjusted by issuing the SND‐
130 CTL_DSP_SETPLAYVOL ioctl. The volume can also be retrieved using the
131 SNDCTL_DSP_GETPLAYVOL.
132 Asynchronous I/O
134 The O_NONBLOCK flag can be set using the F_SETFL fcntl(2) to enable
135 non-blocking read() and write() requests. This is normally sufficient
136 for applications to maintain an audio stream in the background.
137 It is also possible to determine the amount of data that can be trans‐
140 ferred for playback or recording without blocking using the SND‐
141 CTL_DSP_GETOSPACE or SNDCTL_DSP_GETISPACE ioctls, respectively.
142 Mixer Pseudo-Device
144 The /dev/mixer provides access to global hardware settings such as mas‐
145 ter volume settings, etc. It is also the interface used for determining
146 the hardware configuration on the system.
147 Applications should open(2) /dev/mixer, and use the SNDCTL_SYSINFO and
150 SNDCTL_AUDIOINFO ioctls to determine the device node names of audio
151 devices on the system. See mixer(7I) for additional details.
152
154 Information IOCTLs
155 The following ioctls are supported on the audio device, as well as the
156 mixer device. See mixer(7I) for details.
157 OSS_GETVERSION
159 SNDCTL_SYSINFO
160 SNDCTL_AUDIOINFO
161 SNDCTL_MIXERINFO
162 SNDCTL_CARDINFO
163 Audio IOCTLs
166 The dsp device supports the following ioctl commands:
167 SNDCTL_DSP_SYNC The argument is ignored. This command sus‐
169 pends the calling process until the output
170 FIFOs are empty and all queued samples have
171 been played, or until a signal is delivered
172 to the calling process. An implicit SND‐
173 CTL_DSP_SYNC is performed on the final
174 close() of the dsp device.
175 This ioctl should not be used unnecessarily,
177 as if it is used in the middle of playback
178 it causes a small click or pause, as the
179 FIFOs are drained. The correct use of this
180 ioctl is just before changing sample for‐
181 mats.
182 SNDCTL_DSP_HALT The argument is ignored. All input or output
185 SNDCTL_DSP_HALT_INPUT (or both) associated with the file is
186 SNDCTL_DSP_HALT_OUTPUT halted, and any pending data is discarded.
187 SNDCTL_DSP_SPEED The argument is a pointer to an integer,
190 indicating the sample rate (in Hz) to be
191 used. The rate applies to both input and
192 output for the file descriptor. On return
193 the actual rate, which can differ from that
194 requested, is stored in the integer pointed
195 to by the argument. To query the configured
196 speed without changing it the value 0 can be
197 used by the application
198 SNDCTL_DSP_GETFMTS The argument is a pointer to an integer,
201 which receives a bit mask of encodings sup‐
202 ported by the device. Possible values are
203 AFMT_MU_LAW 8-bit unsigned u-Law
205 AFMT_A_LAW 8-bit unsigned a-Law
206 AFMT_U8 8-bit unsigned linear PCM
207 AFMT_S16_LE 16-bit signed
208 little-endian linear PCM
209 AFMT_S16_BE 16-bit signed
210 big-endian linear PCM
211 AFMT_S16_NE 16-bit signed native-endian
212 linear PCM
213 AFMT_U16_LE 16-bit unsigned
214 little-endian linear PCM
215 AFMT_U16_BE 16-bit unsigned big-endian
216 linear PCM
217 AFMT_U16_NE 16-bit unsigned big-endian
218 linear PCM
219 AFMT_S24_LE 24-bit signed little-endian
220 linear PCM, 32-bit aligned
221 AFMT_S24_BE 24-bit signed big-endian
222 linear PCM, 32-bit aligned
223 AFMT_S24_NE 24-bit signed native-endian
224 linear PCM, 32-bit aligned
225 AFMT_S32_LE 32-bit signed little-endian
226 linear PCM
227 AFMT_S32_BE 32-bit signed big-endian
228 linear PCM
229 AFMT_S32_NE 32-bit signed native-endian
230 linear PCM
231 AFMT_S24_PACKED 24-bit signed little-endian
232 packed linear PCM
233 Not all devices support all of these encod‐
236 ings. This implementation uses AFMT_S24_LE
237 or AFMT_S24_BE, whichever is native, inter‐
238 nally.
239 SNDCTL_DSP_SETFMT The argument is a pointer to an integer,
242 which indicates the encoding to be used. The
243 same values as for SNDCTL_DSP_GETFMT can be
244 used, but the caller can only specify a sin‐
245 gle option. The encoding is used for both
246 input and output performed on the file
247 descriptor.
248 SNDCTL_DSP_CHANNELS The argument is a pointer to an integer,
251 indicating the number of channels to be used
252 (1 for mono, 2 for stereo, etc.) The value
253 applies to both input and output for the
254 file descriptor. On return the actual chan‐
255 nel configuration (which can differ from
256 that requested) is stored in the integer
257 pointed to by the argument. To query the
258 configured channels without changing it the
259 value 0 can be used by the application.
260 SNDDCTL_DSP_GETCAPS The argument is a pointer to an integer bit
263 mask, which indicates the capabilities of
264 the device. The bits returned can include
265 PCM_CAP_OUTPUT Device supports playback
267 PCM_CAP_INPUT Device supports recording
268 PCM_CAP_DUPLEX Device supports simultaneous
269 playback and recording
270 SNDCTL_DSP_GETPLAYVOL The argument is a pointer to an integer to
275 SNDCTL_DSP_GETRECVOL receive the volume level for either playback
276 or record. The value is encoded as a stereo
277 value with the values for two channels in
278 the least significant two bytes. The value
279 for each channel thus has a range of 0-100.
280 In this implementation, only the low order
281 byte is used, as the value is treated as a
282 monophonic value, but a stereo value (with
283 both channel levels being identical) is
284 returned for compatibility.
285 SNDCTL_DSP_SETPLAYVOL The argument is a pointer to an integer
288 SNDCTL_DSP_SETRECVOL indicating volume level for either playback
289 or record. The value is encoded as a stereo
290 value with the values for two channels in
291 the least significant two bytes. The value
292 for each channel has a range of 0-100. Note
293 that in this implementation, only the low
294 order byte is used, as the value is treated
295 as a monophonic value. Portable applications
296 should assign the same value to both bytes
297 SNDCTL_DSP_GETISPACE The argument is a pointer to a struct
300 SNDCTL_DSP_GETOSPACE audio_buf_info, which has the following
301 structure:
302 typedef struct audio_buf_info {
304 int fragments;* /# of available fragments */
305 int fragstotal;
306 /* Total # of fragments allocated */
307 int fragsize;
308 /* Size of a fragment in bytes */
309 int bytes;
310 /* Available space in bytes */
311 /* Note! 'bytes' could be more than
312 fragments*fragsize */
313 } audio_buf_info;
314 The fields fragments, fragstotal, and frag‐
317 size are intended for use with compatible
318 applications (and in the future with
319 mmap(2)) only, and need not be used by typi‐
320 cal applications. On successful return the
321 bytes member contains the number of bytes
322 that can be transferred without blocking.
323 SNDCTL_DSP_CURRENT_IPTR The argument is a pointer to an oss_count_t,
326 SNDCTL_DSP_CURRENT_OPTR which has the following definition:
327 typedef struct {
329 long long samples;
330 /* Total # of samples */
331 int fifo_samples;
332 /* Samples in device FIFO */
333 int filler[32];/* For future use */
334 } oss_count_t;
335 The samples field contains the total number
338 of samples transferred by the device so far.
339 The fifo_samples is the depth of any hard‐
340 ware FIFO. This structure can be useful for
341 accurate stream positioning and latency cal‐
342 culations.
343 SNDCTL_DSP_GETIPTR The argument is a pointer to a struct
346 SNDCTL_DSP_GETOPTR count_info, which has the following defini‐
347 tion:
348 typedef struct count_info {
350 unsigned int bytes;
351 /* Total # of bytes processed */
352 int blocks;
353 /* # of fragment transitions since
354 last time */
355 int ptr;/* Current DMA pointer value */
356 } count_info;
357 These ioctls are primarily supplied for com‐
360 patibility, and should not be used by most
361 applications.
362 SNDCTL_DSP_GETODELAY The argument is a pointer to an integer. On
365 return, the integer contains the number of
366 bytes still to be played before the next
367 byte written are played. This can be used
368 for accurate determination of device
369 latency. The result can differ from actual
370 value by up the depth of the internal device
371 FIFO, which is typically 64 bytes.
372 SNDCTL_DSP_GETERROR The argument is a pointer to a struct
375 audio_errinfo, defined as follows:
376 typedef struct audio_errinfo {
378 int play_underruns;
379 int rec_overruns;
380 unsigned int play_ptradjust;
381 unsigned int rec_ptradjust;
382 int play_errorcount;
383 int rec_errorcount;
384 int play_lasterror;
385 int rec_lasterror;
386 int play_errorparm;
387 int rec_errorparm;
388 int filler[16];
389 } audio_errinfo;
390 For this implementation, only the
393 play_underruns and rec_overruns values are
394 significant. No other fields are used in
395 this implementation.
396 These fields are reset to zero each time
398 their value is retrieved using this ioctl.
399 Compatibility IOCTLS
402 These ioctls are supplied exclusively for compatibility with existing
403 applications. Their use is not recommended, and they are not documented
404 here. Many of these are implemented as simple no-ops.
405 SNDCTL_DSP_POST
407 SNDCTL_DSP_STEREO
408 SNDCTL_DSP_SETDUPLEX
409 SNDCTL_DSP_LOW_WATER
410 SNDCTL_DSP_PROFILE
411 SNDCTL_DSP_GETBLKSIZE
412 SNDCTL_DSP_SUBDIVIDE
413 SNDCTL_DSP_SETFRAGMENT
414 SNDCTL_DSP_COOKEDMODE
415 SNDCTL_DSP_READCTL
416 SNDCTL_DSP_WRITECTL
417 SNDCTL_DSP_SILENCE
418 SNDCTL_DSP_SKIP
419 SNDCTL_DSP_POST
420 SNDCTL_DSP_GET_RECSRC
421 SNDCTL_DSP_SET_RECSRC
422 SNDCTL_DSP_SET_RECSRC_NAMES
423 SNDCTL_DSP_GET_PLAYTGT
424 SNDCTL_DSP_SET_PLAYTGT
425 SNDCTL_DSP_SET_PLAYTGT_NAMES
426 SNDCTL_DSP_GETTRIGGER
427 SNDCTL_DSP_SETTRIGGER
428 SNDCTL_AUDIOINFO_EX
429 SNDCTL_ENGINEINFO
430
434 An open() fails if:
435 EBUSY The requested play or record access isbusy and either the
437 O_NDELAY or O_NONBLOCK flag was set in the open() request.
438 EINTR The requested play or record access is busy and a signal
441 interrupted the open() request.
442 EINVAL The device cannot support the requested play or record
445 access.
446 An ioctl() fails if:
450 EINVAL The parameter changes requested in the ioctl are invalid or
452 are not supported by the device.
453
456 The physical audio device names are system dependent and are rarely
457 used by programmers. Programmers should use the generic device names
458 listed below.
459 /dev/dsp Symbolic link to the system's primary audio
461 device
462 /dev/mixer Symbolic link to the pseudo mixer device
465 for the system
466 /dev/sndstat Symbolic link to the pseudo mixer device
469 for the system
470 /usr/share/audio/samples Audio files
473
476 See attributes(5) for a description of the following attributes:
477 ┌────────────────────┬──────────────────────────────────────┐
482 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
483 ├────────────────────┼──────────────────────────────────────┤
484 │Architecture │SPARC, x86 │
485 ├────────────────────┼──────────────────────────────────────┤
486 │Availability │SUNWcsu, SUNWaudd, SUNWaudh │
487 ├────────────────────┼──────────────────────────────────────┤
488 │Stability Level │Uncommitted │
489 └────────────────────┴──────────────────────────────────────┘
490
492 close(2), fcntl(2), ioctl(2), mmap(2), open(2), poll(2), read(2),
493 write(2), attributes(5), audio(7D), mixer(7I)
494SunOS 5.11 11 May 2009 dsp(7I)