요약·해설과 원문, 전문 번역을 서로 분리했습니다. API 이름, symbol, source path는 원문 표기를 사용합니다.
1. 요약·해설
원문의 핵심 논리와 kernel programming 관점의 보충 설명입니다. 아래의 전문 번역과는 별도로 작성했습니다.
2. 영어 원문 전체
번역 기준이 된 Linux v6.18.37 원문입니다. 줄 번호는 이 버전의 파일 좌표입니다.
원문 전체 펼치기
1
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
2
.. c:namespace:: V4L
4
.. _func-open:
6
***********
7
V4L2 open()
8
***********
10
Name
11
====
13
v4l2-open - Open a V4L2 device
15
Synopsis
16
========
18
.. code-block:: c
20
#include <fcntl.h>
22
.. c:function:: int open( const char *device_name, int flags )
24
Arguments
25
=========
27
``device_name``
28
Device to be opened.
30
``flags``
31
Open flags. Access mode must be ``O_RDWR``. This is just a
32
technicality, input devices still support only reading and output
33
devices only writing.
35
When the ``O_NONBLOCK`` flag is given, the :c:func:`read()`
36
function and the :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl will
37
return the ``EAGAIN`` error code when no data is available or no
38
buffer is in the driver outgoing queue, otherwise these functions
39
block until data becomes available. All V4L2 drivers exchanging data
40
with applications must support the ``O_NONBLOCK`` flag.
42
Other flags have no effect.
44
Description
45
===========
47
To open a V4L2 device applications call :c:func:`open()` with the
48
desired device name. This function has no side effects; all data format
49
parameters, current input or output, control values or other properties
50
remain unchanged. At the first :c:func:`open()` call after loading the
51
driver they will be reset to default values, drivers are never in an
52
undefined state.
54
Return Value
55
============
57
On success :c:func:`open()` returns the new file descriptor. On error
58
-1 is returned, and the ``errno`` variable is set appropriately.
59
Possible error codes are:
61
EACCES
62
The caller has no permission to access the device.
64
EBUSY
65
The driver does not support multiple opens and the device is already
66
in use.
68
ENODEV
69
Device not found or was removed.
71
ENOMEM
72
Not enough kernel memory was available to complete the request.
74
EMFILE
75
The process already has the maximum number of files open.
77
ENFILE
78
The limit on the total number of files open on the system has been
79
reached.
3. 한국어 전문 번역
영어 원문의 문단 순서와 의미를 유지한 전체 번역입니다. 코드, 함수명, symbol과 URL은 원문 표기를 유지합니다.
장치 열기 선언과 flag
1-43`v4l2-open`은 V4L2 장치를 엽니다. `<fcntl.h>`를 포함하고 `int open(const char *device_name, int flags)`를 호출합니다. `device_name`은 열 장치 경로입니다.
Access mode는 기술적인 이유로 반드시 `O_RDWR`여야 합니다. 그렇더라도 input device는 읽기만, output device는 쓰기만 지원합니다. `O_NONBLOCK`을 설정하면 data가 없거나 driver outgoing queue에 꺼낼 buffer가 없을 때 `read()`와 `VIDIOC_DQBUF`가 기다리지 않고 `EAGAIN`을 반환합니다. 설정하지 않으면 data가 준비될 때까지 block합니다.
Application과 data를 교환하는 모든 V4L2 driver는 `O_NONBLOCK`을 지원해야 합니다. 그 밖의 open flag는 효과가 없습니다.
항목설명
`O_RDWR`필수 access mode입니다. 실제 data 방향 제약은 장치 종류가 결정합니다.
`O_NONBLOCK`Data나 dequeuable buffer가 없을 때 `EAGAIN`을 즉시 반환합니다.
기타 flagV4L2 장치 동작에는 영향을 주지 않습니다.
V4L2 장치에서는 access mode와 blocking policy만 의미가 있습니다.
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
.. c:namespace:: V4L
.. _func-open:
***********
V4L2 open()
***********
Name
====
v4l2-open - Open a V4L2 device
Synopsis
========
.. code-block:: c
#include <fcntl.h>
.. c:function:: int open( const char *device_name, int flags )
Arguments
=========
``device_name``
Device to be opened.
``flags``
Open flags. Access mode must be ``O_RDWR``. This is just a
technicality, input devices still support only reading and output
devices only writing.
When the ``O_NONBLOCK`` flag is given, the :c:func:`read()`
function and the :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl will
return the ``EAGAIN`` error code when no data is available or no
buffer is in the driver outgoing queue, otherwise these functions
block until data becomes available. All V4L2 drivers exchanging data
with applications must support the ``O_NONBLOCK`` flag.
Other flags have no effect.
상태 보존과 오류
44-79원하는 장치 이름으로 `open()`을 호출하는 것 자체에는 side effect가 없습니다. Data format parameter, 현재 input/output, control value와 다른 속성은 바뀌지 않습니다. 단, driver를 load한 뒤 최초 `open()`에서는 이 값들이 default로 reset되며 driver 상태가 undefined인 경우는 없습니다.
성공하면 새 file descriptor를, 실패하면 -1과 적절한 `errno`를 반환합니다.
항목설명
`EACCES`호출자에게 장치 접근 권한이 없습니다.
`EBUSY`Driver가 multiple open을 지원하지 않고 장치가 이미 사용 중입니다.
`ENODEV`장치를 찾을 수 없거나 제거됐습니다.
`ENOMEM`요청을 처리할 kernel memory가 부족합니다.
`EMFILE`현재 process가 열 수 있는 file 수 한도에 도달했습니다.
`ENFILE`System 전체 open file 수 한도에 도달했습니다.
권한, 장치 점유·제거, memory와 descriptor limit를 구분합니다.
Description
===========
To open a V4L2 device applications call :c:func:`open()` with the
desired device name. This function has no side effects; all data format
parameters, current input or output, control values or other properties
remain unchanged. At the first :c:func:`open()` call after loading the
driver they will be reset to default values, drivers are never in an
undefined state.
Return Value
============
On success :c:func:`open()` returns the new file descriptor. On error
-1 is returned, and the ``errno`` variable is set appropriately.
Possible error codes are:
EACCES
The caller has no permission to access the device.
EBUSY
The driver does not support multiple opens and the device is already
in use.
ENODEV
Device not found or was removed.
ENOMEM
Not enough kernel memory was available to complete the request.
EMFILE
The process already has the maximum number of files open.
ENFILE
The limit on the total number of files open on the system has been
reached.
요약·해설
func-open.rst:1-79V4L2 장치는 O_RDWR로 열고 필요하면 O_NONBLOCK을 추가합니다. 일반 open은 설정을 바꾸지 않지만 driver load 뒤 최초 open은 정의된 default를 복원합니다.