| | Open Sound System |
| Do you have problems with sound/audio application development? Don't panic! Click here for help! |
If an error occurred the errno variable (see man errno for more info) will be set. The application should report the errno value (see man perror or man strerror) and the system call (or ioctl code) that caused the error. Without this information it's practically impossible to find out what happened.
| errno | Possible cause |
| EINVAL | The ioctl call was not supported by the OSS version being used or the argument value (or some of it's fields) was illegal. |
| EACCES | The user doesn't have permissions to access the device. |
| EAGAIN | It was not possible to read or write anything without blocking. This is not an error but a normal condition when using non-blocking I/O (O_NONBLOCK). |
| EBUSY | The device or resource is busy at this moment. Some other application is using it. |
| EFAULT | Bad address was passed to some of the system calls. Please check the console log for more info. Some systems don't support the EIDRM error code. In such cases OSS will return EFAULT instead of EIDRM. |
| EIDRM | A mixer ioctl call failed because the resource being accessed has been removed. This may happen for example when a device is switched to a different operation mode. The application should terminate or re-load the mixer structure information and start from the beginning. In some systems that don't support EIDRM the EFAULT error code will be returned instead. |
| EINTR | Some signal was received in the middle of a read or write call. |
| EIO | Some kind of hardware level error occurred. It's also possible that the application tried to perform some operation that is not possible because the device is in wrong state. |
| ENODEV | This error means that there is no driver loaded for this device. This situation can be fixed by starting OSS. |
| ENOSPC | It was not possible to allocate buffers for the device. Rebooting the system may help. |
| ENOMEM | General memory allocation error. |
| ENOTSUP | The device is not capable to do the requested operation. For example recording was attempted or some recording related ioctl call was made on device that cannot do recording (or the device was not opened for recording). |
| ENXIO | The requested device doesn't exist. This error usually occurs when trying to open a nonexistent device. Some ioctl calls may return this error if the device number field of the argument was out of bounds. |
| EPERM | An operation failed because the user doesn't have the required privileges (such as super user rights). OSS versions older than 4.0 may also return this error for some other reasons. |
| EPIPE | A hot-pluggable device was unplugged in the middle of operation. |
| ENOENT | This error is not returned by OSS but by the file system. It means that the device file (for example /dev/dsp doesn't exist in the /dev directory. With the OSS devices the most likely reason is that OSS is not installed at all or it's version is too old. It's also possible that there is a typo in the application (or it's configuration). |
| ECONNRESET | This is not necessarily an error but rather a kind of end of stream indicator returned by read(). It's used by special devices like loopback audio/MIDI to tell that the remote end of the pipe was closed. For example many media players (client side) may close or reset the device at file boundaries. The application listening the server side may close the current file after receiving this error code and reopen the device for a new file. In addition to loopback pseudo devices this error code may also be returned by other kind of special devices such as audio tape/disk readers. Write call may return this error too. In that case it means that there was some kind of communication channel dropdown. |
In addition to the errno numbers mentioned above some future drivers may return additional error codes.
Most OSS ioctl calls don't return an error if a minor error occurred. For example if the requested sampling rate is not possible the nearest possible rate will be used. In this case the ioctl return value will not indicate an error. However the argument value will be silently modified to contain the actual sampling rate being used. The application must inspect the argument after the call to see if it can live with the returned value.
Many of the ioctl calls described in this manual are new and not implemented by older OSS versions such as ALSA or the OSS/Free drivers included in the Linux kernels. In such cases the ioctl call will return errno=EINVAL. It would be very stupid if the application aborts just because some non-important ioctl function was not there. Please read the possible compatibility issues chapters of the individual ioctl calls before using them.