요약·해설과 원문, 전문 번역을 서로 분리했습니다. API 이름, symbol, source path는 원문 표기를 사용합니다.
1. 요약·해설
원문의 핵심 논리와 kernel programming 관점의 보충 설명입니다. 아래의 전문 번역과는 별도로 작성했습니다.
2. 영어 원문 전체
번역 기준이 된 Linux v6.18.37 원문입니다. 줄 번호는 이 버전의 파일 좌표입니다.
원문 전체 펼치기
1
.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later
2
.. c:namespace:: MC
4
.. _request-func-ioctl:
6
***************
7
request ioctl()
8
***************
10
Name
11
====
13
request-ioctl - Control a request file descriptor
15
Synopsis
16
========
18
.. code-block:: c
20
#include <sys/ioctl.h>
22
``int ioctl(int fd, int cmd, void *argp)``
24
Arguments
25
=========
27
``fd``
28
File descriptor returned by :ref:`MEDIA_IOC_REQUEST_ALLOC`.
30
``cmd``
31
The request ioctl command code as defined in the media.h header file, for
32
example :ref:`MEDIA_REQUEST_IOC_QUEUE`.
34
``argp``
35
Pointer to a request-specific structure.
37
Description
38
===========
40
The :ref:`ioctl() <request-func-ioctl>` function manipulates request
41
parameters. The argument ``fd`` must be an open file descriptor.
43
The ioctl ``cmd`` code specifies the request function to be called. It
44
has encoded in it whether the argument is an input, output or read/write
45
parameter, and the size of the argument ``argp`` in bytes.
47
Macros and structures definitions specifying request ioctl commands and
48
their parameters are located in the media.h header file. All request ioctl
49
commands, their respective function and parameters are specified in
50
:ref:`media-user-func`.
52
Return Value
53
============
55
On success 0 is returned, on error -1 and the ``errno`` variable is set
56
appropriately. The generic error codes are described at the
57
:ref:`Generic Error Codes <gen-errors>` chapter.
59
Command-specific error codes are listed in the individual command
60
descriptions.
62
When an ioctl that takes an output or read/write parameter fails, the
63
parameter remains unmodified.
3. 한국어 전문 번역
영어 원문의 문단 순서와 의미를 유지한 전체 번역입니다. 코드, 함수명, symbol과 URL은 원문 표기를 유지합니다.
이름, 선언과 인자
1-36Request `ioctl()`은 request file descriptor의 parameter와 상태를 command별로 제어합니다.
#include <sys/ioctl.h>
int ioctl(int fd, int cmd, void *argp);인자설명
fdMEDIA_IOC_REQUEST_ALLOC이 반환한 열린 request fd
cmdmedia.h에 정의된 request ioctl command, 예: MEDIA_REQUEST_IOC_QUEUE
argpCommand별 request-specific structure pointer
Command code가 argument 방향과 크기까지 encode합니다.
.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later
.. c:namespace:: MC
.. _request-func-ioctl:
***************
request ioctl()
***************
Name
====
request-ioctl - Control a request file descriptor
Synopsis
========
.. code-block:: c
#include <sys/ioctl.h>
``int ioctl(int fd, int cmd, void *argp)``
Arguments
=========
``fd``
File descriptor returned by :ref:`MEDIA_IOC_REQUEST_ALLOC`.
``cmd``
The request ioctl command code as defined in the media.h header file, for
example :ref:`MEDIA_REQUEST_IOC_QUEUE`.
``argp``
Pointer to a request-specific structure.
Command encoding과 media.h
37-51`fd`는 열린 file descriptor여야 하며 `cmd`가 호출할 request function을 지정합니다.
Command code에는 argument가 input, output, read/write 중 무엇인지와 `argp` argument의 byte 크기가 encode되어 있습니다.
Request ioctl command와 parameter를 정의하는 macro 및 structure는 `media.h`에 있습니다. 모든 command의 function과 parameter는 media user function 목록에 정의됩니다.
Description
===========
The :ref:`ioctl() <request-func-ioctl>` function manipulates request
parameters. The argument ``fd`` must be an open file descriptor.
The ioctl ``cmd`` code specifies the request function to be called. It
has encoded in it whether the argument is an input, output or read/write
parameter, and the size of the argument ``argp`` in bytes.
Macros and structures definitions specifying request ioctl commands and
their parameters are located in the media.h header file. All request ioctl
commands, their respective function and parameters are specified in
:ref:`media-user-func`.
반환값과 parameter 불변성
52-63성공하면 0, 오류이면 -1을 반환하고 `errno`를 설정합니다. 공통 오류는 Generic Error Codes에, command별 오류는 각 command 설명에 나옵니다.
Output 또는 read/write parameter를 받는 ioctl이 실패하면 그 parameter는 변경되지 않습니다. Application은 실패한 output structure에서 부분 결과를 읽어서는 안 됩니다.
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.
Command-specific error codes are listed in the individual command
descriptions.
When an ioctl that takes an output or read/write parameter fails, the
parameter remains unmodified.
요약·해설
request-func-ioctl.rst:1-63Command code는 argument 방향과 크기를 encode합니다. Output 또는 read/write ioctl 실패 시 parameter가 변경되지 않는다는 ABI 보장을 지켜야 합니다.