← Documents Documentation/userspace-api/media/gen-errors.rst GitHub 원문 ↗

Linux 6.18.37 · Userspace API / Media / Reference

Generic Error Codes

Media ioctl에서 공통으로 쓰는 errno와 복구 의미를 설명합니다.

Source pathDocumentation/userspace-api/media/gen-errors.rst
Source versionLinux v6.18.37
TranslationDUJINLABS 전문 번역 + 해설

요약·해설과 원문, 전문 번역을 서로 분리했습니다. API 이름, symbol, source path는 원문 표기를 사용합니다.

1. 요약·해설

원문의 핵심 논리와 kernel programming 관점의 보충 설명입니다. 아래의 전문 번역과는 별도로 작성했습니다.

요약·해설

gen-errors.rst:1-94

공통 errno는 상태 수정 후 재시도 가능한 경우와 device가 나쁜 상태라고 간주해야 하는 경우를 구분해 읽어야 합니다.

2. 영어 원문 전체

번역 기준이 된 Linux v6.18.37 원문입니다. 줄 번호는 이 버전의 파일 좌표입니다.

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

3. 한국어 전문 번역

영어 원문의 문단 순서와 의미를 유지한 전체 번역입니다. 코드, 함수명, symbol과 URL은 원문 표기를 유지합니다.

Media ioctl 공통 errno

1-94

Media ioctl이 공통으로 반환할 수 있는 대표 `errno`와 재시도·복구 의미입니다. 각 ioctl에는 여기 없는 추가 오류가 있을 수 있습니다.

Generic error code
errno의미와 대응
EAGAIN / EWOULDBLOCK현재 device 상태에서 ioctl을 수행할 수 없거나, non-blocking mode에서 event를 기다려야 합니다. 예: sleep 중인 device의 statistics query.
EBADFfile descriptor가 유효하지 않습니다.
EBUSYdevice가 busy입니다. Streaming 중 stream에 영향을 주는 변경 또는 이미 할당된 hardware resource 요청이 흔한 원인입니다. 먼저 stream stop 같은 조치를 해야 하며 그대로 재시도하면 안 됩니다.
EFAULTuserspace와 data를 복사하는 중 실패했습니다. 잘못된 pointer reference가 흔한 원인입니다.
EINVALioctl parameter 하나 이상이 잘못됐거나 허용 범위를 벗어났습니다. 구체 원인은 개별 ioctl 설명을 확인합니다.
ENODEVdevice를 찾을 수 없거나 제거됐습니다.
ENOMEM요청한 동작을 처리할 memory가 부족합니다.
ENOTTY해당 file descriptor가 ioctl을 지원하지 않습니다.
ENOSPCUSB periodic transfer에 예약 가능한 bandwidth, 전체의 최대 80%를 초과합니다.
EPERM권한이 없습니다. Write permission 또는 root 같은 특별 capability가 필요할 수 있습니다.
EIOhardware communication I/O 오류입니다. 고장 또는 불안정한 hardware를 나타낼 수 있습니다.
ENXIO이 device special file에 대응하는 device가 없습니다.

상태를 고친 뒤 재시도해야 하는 오류와 즉시 중단해야 할 오류를 구분합니다.

이 목록은 완전하지 않습니다. 오류가 driver reset 같은 side effect를 일으킬 수 있으므로 예상하지 못한 오류에서는 응용 프로그램을 중단하거나 device가 나쁜 상태라고 가정해야 합니다.

Request별 오류 code는 각 ioctl request 설명에 별도로 기재됩니다.

.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later

.. _gen_errors:

*******************
Generic Error Codes
*******************


.. _gen-errors:

.. tabularcolumns:: |p{2.5cm}|p{15.0cm}|

.. flat-table:: Generic error codes
    :header-rows:  0
    :stub-columns: 0
    :widths: 1 16


    -  -  ``EAGAIN`` (aka ``EWOULDBLOCK``)

       -  The ioctl can't be handled because the device is in state where it
	  can't perform it. This could happen for example in case where
	  device is sleeping and ioctl is performed to query statistics. It
	  is also returned when the ioctl would need to wait for an event,
	  but the device was opened in non-blocking mode.

    -  -  ``EBADF``

       -  The file descriptor is not a valid.

    -  -  ``EBUSY``

       -  The ioctl can't be handled because the device is busy. This is
	  typically return while device is streaming, and an ioctl tried to
	  change something that would affect the stream, or would require
	  the usage of a hardware resource that was already allocated. The
	  ioctl must not be retried without performing another action to fix
	  the problem first (typically: stop the stream before retrying).

    -  -  ``EFAULT``

       -  There was a failure while copying data from/to userspace, probably
	  caused by an invalid pointer reference.

    -  -  ``EINVAL``

       -  One or more of the ioctl parameters are invalid or out of the
	  allowed range. This is a widely used error code. See the
	  individual ioctl requests for specific causes.

    -  -  ``ENODEV``

       -  Device not found or was removed.

    -  -  ``ENOMEM``

       -  There's not enough memory to handle the desired operation.

    -  -  ``ENOTTY``

       -  The ioctl is not supported by the file descriptor.

    -  -  ``ENOSPC``

       -  On USB devices, the stream ioctl's can return this error, meaning
	  that this request would overcommit the usb bandwidth reserved for
	  periodic transfers (up to 80% of the USB bandwidth).

    -  -  ``EPERM``

       -  Permission denied. Can be returned if the device needs write
	  permission, or some special capabilities is needed (e. g. root)

    -  -  ``EIO``

       -  I/O error. Typically used when there are problems communicating with
          a hardware device. This could indicate broken or flaky hardware.
	  It's a 'Something is wrong, I give up!' type of error.

    -  - ``ENXIO``

       -  No device corresponding to this device special file exists.


.. note::

  #. This list is not exhaustive; ioctls may return other error codes.
     Since errors may have side effects such as a driver reset,
     applications should abort on unexpected errors, or otherwise
     assume that the device is in a bad state.

  #. Request-specific error codes are listed in the individual
     requests descriptions.