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!

SNDCTL_DSP_SETTRIGGER

Starts audio recording and/or playback in sync

Usage

int mask = The direction mask;

ioctl(fd, SNDCTL_DSP_SETTRIGGER, &mask);

The above code fragment lacks all error checks for clarity. Real world applications must always check for the errors and handle them as described below. Also most OSS ioctl calls will return information in the argument variable and it's usually necessary to check it too.

Description

In normal operation the read and/or write call will automatically start the actual recording or playback operation. However in some cases it's necessary to start it manually. There are exactly three cases when it's necessary. 1) When using mmap() this is the only way to start the device. 2) When recording and playback needs to be started exactly at the same moment. 3) When doing normal recording but when even the first read cannot block. In this case recording needs to be triggered manually.

There are two direction bits (PCM_ENABLE_INPUT and PCM_ENABLE_OUTPUT) for recording and playback (respectively). {para This ioctl call needs to be called twice. Otherwise the call will not have any effect. The first call is used to clear the direction bits. The second call returns them back to enabled which starts the device operation immediately.}

Before re-enabling playback (but after disabling PCM_ENABLE_OUTPUT) the application must write at least one fragment of data to the device. Otherwise the trigger operation will not start playback.

The following example shows how the application can trigger both recording and playback at the same time.



int trig;



trig=0; /* Both directions disabled */

ioctl(fd, SNDCTL_DSP_SETTRIGGER, &#38;trig);



write(fd, buf, len); /* Write some data to the playback buffer */



trig=PCM_ENABLE_INPUT|PCM_ENABLE_OUTPUT; /* Both directions enabled */

ioctl(fd, SNDCTL_DSP_SETTRIGGER, &#38;trig);

This ioctl call cannot be used to stop and restart the device after the playback has been started (this may work with some OSS implementations but fail wit the the rest of them). It is necessary to use the SNDCTL_DSP_HALT family for this purpose.

This ioctl call doesn't work very well with multiple devices. The SNDCTL_DSP_SYNCGROUP and SNDCTL_DSP_SYNCSTART calls provide a method to do this.

Compatibility issues

This call is supported by all OSS vesions. However the application must use this ioctl in a proper way. Wrong usage may cause serious incompatibility problems with different OSS implementations.

Please look at the When OSS audio ioctl calls can be made section for information about DSP ioctl call ordering.

OSS ioctl return values

The return value from the OSS ioctl calls will be -1 if a fatal error occurred. Other values mean that the ioctl call was more or less successful. However in most cases the application must check the value returned in the argument to see what was the accepted value.

Please see the Possible error codes (errno) returned by OSS calls section for more info about the error codes returned by OSS.

Sample programs

fulldup.c	Full duplex sample program using the single device approach.
mmap_duplex.c	A simple sample program for doing dull duplex using mmap
mmap_test.c	A sample program for using mmap()
iosync.c	Measuring the hardware level latencies.
synctest.c	A program that demonstrates use of syncronization groups.