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