| | Open Sound System |
| Do you have problems with sound/audio application development? Don't panic! Click here for help! |
audio_errinfo ei;
ioctl(fd, SNDCTL_DSP_GETERROR, &ei);
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.
This ioctl call returns detailed information about errors detected by the audio device or it's driver. The application may check this information after the playback and/or recording operation is finished to see if everything went OK. All errors and counters will automatically be cleared to zeroes after the call so each call will return only the errors that occurred after the previous invocation.
The following fields are included in the audio_errinfo structure.
| Field | Meaning |
| play_underruns | The number of buffer underrun errors. A buffer underrun happens when the application fails to write new audio data fast enough and the buffer becomes empty. When this happens a short pause or click will occur in output. |
| rec_overruns | The number of buffer overrun errors. A buffer overrun happens when the application fails to read audio data fast enough and the buffer becomes full. One fragment of recorded data will be lost each time an overrun happens. |
| play_ptradjust | The bytes field of the SNDCTL_DSP_GETOPTR will overflow after 2^32 bytes have been played. OSS 4.0 just lets the bytes field to wrap. However older OSS versions will substract some value from the pointer before the overflow occurs. The substracted value will be returned in this field. With OSS 4.0 this field will always be zero. |
| rec_ptradjust | The bytes field of the SNDCTL_DSP_GETIPTR will overflow after 2^32 bytes have been recorded. OSS 4.0 just lets the bytes field to wrap. However older OSS versions will substract some value from the pointer before the overflow occurs. The substracted value will be returned in this field. With OSS 4.0 this field will always be zero. |
| play_errorcount | Number of playback related errors occurred. |
| rec_errorcount | Number of recording related errors occurred. |
| play_lasterror | Code of the last playback related errors occurred. See the discussion below for more info. |
| rec_lasterror | Code of the last recording related errors occurred. See the discussion below for more info. |
| play_errorparm | Parameter related with play_lasterror. |
| rec_errorparm | Parameter related with rec_lasterror. |
The play_errorparm field must be shown too if the application reports play_lasterror. The same is true with rec_lasterror and rec_errorparm.
Some OSS implementations provide more detailed error codes in addition to the oss_errno codes returned by many system calls. The play_lasterror/play_errorparm and the rec_lasterror/rec_errorparm contain the previous error that was related with playback and/or recording (respectively). Unlike some other fields returned by this ioctl call these fields will not be cleared after the call. The same information will be reported by subsequent calls until a new error occurs. The play_errorcount and rec_errorcount fields will be incremented every time an error occurs so the application may use this to find out if the error is new.
Errors may be detected asynchronously for example by the device itself. So the errors may not be directly related with the last OSS system call executed by the application itself.
These "errors" are usually not real errors or even warnings. This mechanism just provides additional information that can be used to debug application errors. Applications should not check the last play/rec errors unless something else has failed. Reporting these codes unnecessarily may confuse the user even there is no real problem.
A good practice for reporting these error codes is after an OSS system call has failed and the application terminates (or stops using audio). Even then the most important piece of information is name of the ioctl or system call that failed and the errno value. The rec/play error codes just provide additional debugging information that may not even be related with the actual problem.
Currently defined error codes returned by the official OSS 4.0 implementation by 4Front Technologies is given in the OSS error code list . Please note that other OSS implementations may use entirely different error codes. By convention the error codes should be printed using 5 digits with leading zeroes (%05d in C/C++). For example 01123. Value of 0 means no error in all implementations.
The error numbers returned in play_lasterror and rec_lasterror are implementation dependent. There are several implementations of the OSS API and they may use the same numeric values for different purposes. The error codes may even change between versions.
Applications may report the play_lasterror/play_errorparm and rec_lasterror/rec_errorparm fields after some system call on OSS devices has returned an error. These fields may return additional information which may help in debugging the problem. However applications must in no case look for specific error codes and adjust their operation based on that.
It is not always clear if an error should be reported as a playback or recording error. In such cases OSS will report it as a playback error. Equally well the application cannot always know if it should check the play or record error.
This ioctl call only reports the last error that occurred. OSS implementations may provide other methods for retrieving more error codes. For example the ossinfo program may do this (in the future).
This ioctl call is implemented by all official OSS versions since 3.8 but it's not known how many freeware implementations support it. For this reason the application must check that the call returned OK before using the values raported by it.
Before OSS 4.0 all error information was reset back to empty/zero after this ioctl call. However starting from OSS 4.0 only the underrun/overrun counts and the pointer adjust values will be reset. The play/record error information fields may not be reset in all cases because other error reporting mechanisms may require this info too. Some OSS implementations may still reset these fields in the future.
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.
| dsp_geterror_demo.c | A simple demonstration of |
| ioctl_test.c | This program has been used to verify that some of the ioctl calls work |