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
9
10.. _gen_errors:
11
12*******************
13Generic 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.
104