← Documents Documentation/userspace-api/media/v4l/vidioc-remove-bufs.rst GitHub 원문 ↗

Linux 6.18.37 · 사용자 공간 API

VIDIOC_REMOVE_BUFS ioctl

Queue의 연속 buffer 범위를 부분 제거하는 지원 조건, 구조체, DEQUEUED 제약과 원자적 오류를 설명합니다.

Source pathDocumentation/userspace-api/media/v4l/vidioc-remove-bufs.rst
Source versionLinux v6.18.37
TranslationDUJINLABS 전문 번역 + 해설

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

1. 요약·해설

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

요약·해설

vidioc-remove-bufs.rst:1-86

부분 제거는 전체 범위가 유효하고 dequeue된 경우에만 성공하며 실패 시 아무 buffer도 해제하지 않습니다.

2. 영어 원문 전체

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

원문 전체 펼치기
1 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
2 .. c:namespace:: V4L
3
4 .. _VIDIOC_REMOVE_BUFS:
5
6 ************************
7 ioctl VIDIOC_REMOVE_BUFS
8 ************************
9
10 Name
11 ====
12
13 VIDIOC_REMOVE_BUFS - Removes buffers from a queue
14
15 Synopsis
16 ========
17
18 .. c:macro:: VIDIOC_REMOVE_BUFS
19
20 ``int ioctl(int fd, VIDIOC_REMOVE_BUFS, struct v4l2_remove_buffers *argp)``
21
22 Arguments
23 =========
24
25 ``fd``
26 File descriptor returned by :c:func:`open()`.
27
28 ``argp``
29 Pointer to struct :c:type:`v4l2_remove_buffers`.
30
31 Description
32 ===========
33
34 Applications can optionally call the :ref:`VIDIOC_REMOVE_BUFS` ioctl to
35 remove buffers from a queue.
36 :ref:`VIDIOC_CREATE_BUFS` ioctl support is mandatory to enable :ref:`VIDIOC_REMOVE_BUFS`.
37 This ioctl is available if the ``V4L2_BUF_CAP_SUPPORTS_REMOVE_BUFS`` capability
38 is set on the queue when :c:func:`VIDIOC_REQBUFS` or :c:func:`VIDIOC_CREATE_BUFS`
39 are invoked.
40
41 .. c:type:: v4l2_remove_buffers
42
43 .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}|
44
45 .. flat-table:: struct v4l2_remove_buffers
46 :header-rows: 0
47 :stub-columns: 0
48 :widths: 1 1 2
49
50 * - __u32
51 - ``index``
52 - The starting buffer index to remove. This field is ignored if count == 0.
53 * - __u32
54 - ``count``
55 - The number of buffers to be removed with indices 'index' until 'index + count - 1'.
56 All buffers in this range must be valid and in DEQUEUED state.
57 :ref:`VIDIOC_REMOVE_BUFS` will always check the validity of ``type`, if it is
58 invalid it returns ``EINVAL`` error code.
59 If count is set to 0 :ref:`VIDIOC_REMOVE_BUFS` will do nothing and return 0.
60 * - __u32
61 - ``type``
62 - Type of the stream or buffers, this is the same as the struct
63 :c:type:`v4l2_format` ``type`` field. See
64 :c:type:`v4l2_buf_type` for valid values.
65 * - __u32
66 - ``reserved``\ [13]
67 - A place holder for future extensions. Drivers and applications
68 must set the array to zero.
69
70 Return Value
71 ============
72
73 On success 0 is returned, on error -1 and the ``errno`` variable is set
74 appropriately. The generic error codes are described at the
75 :ref:`Generic Error Codes <gen-errors>` chapter. If an error occurs, no
76 buffers will be freed and one of the error codes below will be returned:
77
78 EBUSY
79 File I/O is in progress.
80 One or more of the buffers in the range ``index`` to ``index + count - 1`` are not
81 in DEQUEUED state.
82
83 EINVAL
84 One or more of the buffers in the range ``index`` to ``index + count - 1`` do not
85 exist in the queue.
86 The buffer type (``type`` field) is not valid.
87

3. 한국어 전문 번역

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

목적, 호출 형식과 인자

1-30

`VIDIOC_REMOVE_BUFS`는 queue에서 연속된 일부 buffer를 선택적으로 제거합니다. `struct v4l2_remove_buffers`가 제거 범위와 buffer type을 지정합니다.

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

.. _VIDIOC_REMOVE_BUFS:

************************
ioctl VIDIOC_REMOVE_BUFS
************************

Name
====

VIDIOC_REMOVE_BUFS - Removes buffers from a queue

Synopsis
========

.. c:macro:: VIDIOC_REMOVE_BUFS

``int ioctl(int fd, VIDIOC_REMOVE_BUFS, struct v4l2_remove_buffers *argp)``

Arguments
=========

``fd``
    File descriptor returned by :c:func:`open()`.

``argp``
    Pointer to struct :c:type:`v4l2_remove_buffers`.

지원 조건

31-40

이 기능을 활성화하려면 드라이버가 `VIDIOC_CREATE_BUFS`를 지원해야 합니다. `VIDIOC_REQBUFS` 또는 `VIDIOC_CREATE_BUFS` 결과에서 queue capability `V4L2_BUF_CAP_SUPPORTS_REMOVE_BUFS`가 설정돼 있어야 호출할 수 있습니다.

Description
===========

Applications can optionally call the :ref:`VIDIOC_REMOVE_BUFS` ioctl to
remove buffers from a queue.
:ref:`VIDIOC_CREATE_BUFS` ioctl support is mandatory to enable :ref:`VIDIOC_REMOVE_BUFS`.
This ioctl is available if the ``V4L2_BUF_CAP_SUPPORTS_REMOVE_BUFS`` capability
is set on the queue when :c:func:`VIDIOC_REQBUFS` or :c:func:`VIDIOC_CREATE_BUFS`
are invoked.

struct v4l2_remove_buffers

41-69
제거 범위 필드
형식필드의미
`__u32``index`제거 시작 buffer index. `count == 0`이면 무시
`__u32``count`제거할 buffer 수. 범위의 모든 buffer가 존재하고 `DEQUEUED` 상태여야 함
`__u32``type``v4l2_format.type`과 같은 stream/buffer type
`__u32[13]``reserved[13]`향후 확장용. 드라이버와 애플리케이션이 모두 0으로 설정

`index`부터 `index + count - 1`까지의 연속 구간을 지정합니다.

`count = 0`이면 buffer를 제거하지 않고 0을 반환하지만 `type`의 유효성은 항상 검사하므로 잘못된 type에는 `EINVAL`입니다.

.. c:type:: v4l2_remove_buffers

.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}|

.. flat-table:: struct v4l2_remove_buffers
    :header-rows:  0
    :stub-columns: 0
    :widths:       1 1 2

    * - __u32
      - ``index``
      - The starting buffer index to remove. This field is ignored if count == 0.
    * - __u32
      - ``count``
      - The number of buffers to be removed with indices 'index' until 'index + count - 1'.
        All buffers in this range must be valid and in DEQUEUED state.
        :ref:`VIDIOC_REMOVE_BUFS` will always check the validity of ``type`, if it is
        invalid it returns ``EINVAL`` error code.
        If count is set to 0 :ref:`VIDIOC_REMOVE_BUFS` will do nothing and return 0.
    * - __u32
      - ``type``
      - Type of the stream or buffers, this is the same as the struct
	:c:type:`v4l2_format` ``type`` field. See
	:c:type:`v4l2_buf_type` for valid values.
    * - __u32
      - ``reserved``\ [13]
      - A place holder for future extensions. Drivers and applications
	must set the array to zero.

반환값과 원자적 오류

70-86

성공하면 0을 반환합니다. 오류가 하나라도 발생하면 buffer를 전혀 해제하지 않는 원자적 동작이며 -1과 `errno`를 반환합니다.

REMOVE_BUFS 오류
errno조건
`EBUSY`file I/O가 진행 중이거나 범위의 하나 이상이 `DEQUEUED` 상태가 아님
`EINVAL`범위의 하나 이상이 queue에 존재하지 않거나 `type`이 유효하지 않음

상태 또는 범위가 잘못되면 전체 요청을 거부합니다.

Return Value
============

On success 0 is returned, on error -1 and the ``errno`` variable is set
appropriately. The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter. If an error occurs, no
buffers will be freed and one of the error codes below will be returned:

EBUSY
    File I/O is in progress.
    One or more of the buffers in the range ``index`` to ``index + count - 1`` are not
    in DEQUEUED state.

EINVAL
    One or more of the buffers in the range ``index`` to ``index + count - 1`` do not
    exist in the queue.
    The buffer type (``type`` field) is not valid.