| b.liu | e958203 | 2025-04-17 19:18:16 +0800 | [diff] [blame^] | 1 | .. Permission is granted to copy, distribute and/or modify this |
| 2 | .. document under the terms of the GNU Free Documentation License, |
| 3 | .. Version 1.1 or any later version published by the Free Software |
| 4 | .. Foundation, with no Invariant Sections, no Front-Cover Texts |
| 5 | .. and no Back-Cover Texts. A copy of the license is included at |
| 6 | .. Documentation/media/uapi/fdl-appendix.rst. |
| 7 | .. |
| 8 | .. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections |
| 9 | |
| 10 | .. _gen_errors: |
| 11 | |
| 12 | ******************* |
| 13 | Generic Error Codes |
| 14 | ******************* |
| 15 | |
| 16 | |
| 17 | .. _gen-errors: |
| 18 | |
| 19 | .. tabularcolumns:: |p{2.5cm}|p{15.0cm}| |
| 20 | |
| 21 | .. flat-table:: Generic error codes |
| 22 | :header-rows: 0 |
| 23 | :stub-columns: 0 |
| 24 | :widths: 1 16 |
| 25 | |
| 26 | |
| 27 | - - ``EAGAIN`` (aka ``EWOULDBLOCK``) |
| 28 | |
| 29 | - The ioctl can't be handled because the device is in state where it |
| 30 | can't perform it. This could happen for example in case where |
| 31 | device is sleeping and ioctl is performed to query statistics. It |
| 32 | is also returned when the ioctl would need to wait for an event, |
| 33 | but the device was opened in non-blocking mode. |
| 34 | |
| 35 | - - ``EBADF`` |
| 36 | |
| 37 | - The file descriptor is not a valid. |
| 38 | |
| 39 | - - ``EBUSY`` |
| 40 | |
| 41 | - The ioctl can't be handled because the device is busy. This is |
| 42 | typically return while device is streaming, and an ioctl tried to |
| 43 | change something that would affect the stream, or would require |
| 44 | the usage of a hardware resource that was already allocated. The |
| 45 | ioctl must not be retried without performing another action to fix |
| 46 | the problem first (typically: stop the stream before retrying). |
| 47 | |
| 48 | - - ``EFAULT`` |
| 49 | |
| 50 | - There was a failure while copying data from/to userspace, probably |
| 51 | caused by an invalid pointer reference. |
| 52 | |
| 53 | - - ``EINVAL`` |
| 54 | |
| 55 | - One or more of the ioctl parameters are invalid or out of the |
| 56 | allowed range. This is a widely used error code. See the |
| 57 | individual ioctl requests for specific causes. |
| 58 | |
| 59 | - - ``ENODEV`` |
| 60 | |
| 61 | - Device not found or was removed. |
| 62 | |
| 63 | - - ``ENOMEM`` |
| 64 | |
| 65 | - There's not enough memory to handle the desired operation. |
| 66 | |
| 67 | - - ``ENOTTY`` |
| 68 | |
| 69 | - The ioctl is not supported by the driver, actually meaning that |
| 70 | the required functionality is not available, or the file |
| 71 | descriptor is not for a media device. |
| 72 | |
| 73 | - - ``ENOSPC`` |
| 74 | |
| 75 | - On USB devices, the stream ioctl's can return this error, meaning |
| 76 | that this request would overcommit the usb bandwidth reserved for |
| 77 | periodic transfers (up to 80% of the USB bandwidth). |
| 78 | |
| 79 | - - ``EPERM`` |
| 80 | |
| 81 | - Permission denied. Can be returned if the device needs write |
| 82 | permission, or some special capabilities is needed (e. g. root) |
| 83 | |
| 84 | - - ``EIO`` |
| 85 | |
| 86 | - I/O error. Typically used when there are problems communicating with |
| 87 | a hardware device. This could indicate broken or flaky hardware. |
| 88 | It's a 'Something is wrong, I give up!' type of error. |
| 89 | |
| 90 | - - ``ENXIO`` |
| 91 | |
| 92 | - No device corresponding to this device special file exists. |
| 93 | |
| 94 | |
| 95 | .. note:: |
| 96 | |
| 97 | #. This list is not exhaustive; ioctls may return other error codes. |
| 98 | Since errors may have side effects such as a driver reset, |
| 99 | applications should abort on unexpected errors, or otherwise |
| 100 | assume that the device is in a bad state. |
| 101 | |
| 102 | #. Request-specific error codes are listed in the individual |
| 103 | requests descriptions. |