요약·해설과 원문, 전문 번역을 서로 분리했습니다. API 이름, symbol, source path는 원문 표기를 사용합니다.
1. 요약·해설
원문의 핵심 논리와 kernel programming 관점의 보충 설명입니다. 아래의 전문 번역과는 별도로 작성했습니다.
2. 영어 원문 전체
번역 기준이 된 Linux v6.18.37 원문입니다. 줄 번호는 이 버전의 파일 좌표입니다.
원문 전체 펼치기
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
.. c:namespace:: DTV.dmx
.. _DMX_QUERYBUF:
******************
ioctl DMX_QUERYBUF
******************
Name
====
DMX_QUERYBUF - Query the status of a buffer
.. warning:: this API is still experimental
Synopsis
========
.. c:macro:: DMX_QUERYBUF
``int ioctl(int fd, DMX_QUERYBUF, struct dvb_buffer *argp)``
Arguments
=========
``fd``
File descriptor returned by :c:func:`open()`.
``argp``
Pointer to struct :c:type:`dvb_buffer`.
Description
===========
This ioctl is part of the mmap streaming I/O method. It can
be used to query the status of a buffer at any time after buffers have
been allocated with the :ref:`DMX_REQBUFS` ioctl.
Applications set the ``index`` field. Valid index numbers range from zero
to the number of buffers allocated with :ref:`DMX_REQBUFS`
(struct :c:type:`dvb_requestbuffers` ``count``) minus one.
After calling :ref:`DMX_QUERYBUF` with a pointer to this structure,
drivers return an error code or fill the rest of the structure.
On success, the ``offset`` will contain the offset of the buffer from the
start of the device memory, the ``length`` field its size, and the
``bytesused`` the number of bytes occupied by data in the buffer (payload).
Return Value
============
On success 0 is returned, the ``offset`` will contain the offset of the
buffer from the start of the device memory, the ``length`` field its size,
and the ``bytesused`` the number of bytes occupied by data in the buffer
(payload).
On error it returns -1 and the ``errno`` variable is set
appropriately. The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.
EINVAL
The ``index`` is out of bounds.
3. 한국어 전문 번역
영어 원문의 문단 순서와 의미를 유지한 전체 번역입니다. 코드, 함수명, symbol과 URL은 원문 표기를 유지합니다.
이름, 실험 상태와 호출 형식
1-22이 문서는 GFDL-1.1-no-invariants-or-later 라이선스와 `DTV.dmx` C namespace를 사용하며 `DMX_QUERYBUF` ioctl을 설명합니다.
이 ioctl은 버퍼 상태를 조회하는 실험적 API이며, 원문 호출 형식은 `int ioctl(int fd, DMX_QUERYBUF, struct dvb_buffer *argp)`입니다.
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
.. c:namespace:: DTV.dmx
.. _DMX_QUERYBUF:
******************
ioctl DMX_QUERYBUF
******************
Name
====
DMX_QUERYBUF - Query the status of a buffer
.. warning:: this API is still experimental
Synopsis
========
.. c:macro:: DMX_QUERYBUF
``int ioctl(int fd, DMX_QUERYBUF, struct dvb_buffer *argp)``인자와 선행 조건
23-38`fd`는 `open()`이 반환한 file descriptor이고, `argp`는 원문에 명시된 `struct dvb_buffer`를 가리킵니다.
`DMX_QUERYBUF`는 mmap streaming I/O 방식의 일부입니다. `DMX_REQBUFS`로 버퍼를 할당한 뒤에는 언제든 특정 버퍼의 상태를 조회할 수 있습니다.
장치 버퍼를 먼저 확보한 뒤 상태를 질의합니다.
Arguments
=========
``fd``
File descriptor returned by :c:func:`open()`.
``argp``
Pointer to struct :c:type:`dvb_buffer`.
Description
===========
This ioctl is part of the mmap streaming I/O method. It can
be used to query the status of a buffer at any time after buffers have
been allocated with the :ref:`DMX_REQBUFS` ioctl.인덱스와 반환 필드
39-50애플리케이션은 `index`를 설정하며 유효 범위는 0부터 `DMX_REQBUFS`로 할당한 버퍼 수, 즉 원문에 표시된 `struct dvb_requestbuffers.count`에서 1을 뺀 값까지입니다.
구조체 포인터로 호출하면 드라이버는 오류를 반환하거나 나머지 필드를 채웁니다.
성공 시 `offset`은 장치 메모리 시작점에서 버퍼까지의 오프셋, `length`는 버퍼 크기, `bytesused`는 버퍼에서 실제 payload가 차지하는 바이트 수를 담습니다.
mmap과 payload 처리에 필요한 핵심 필드입니다.
Applications set the ``index`` field. Valid index numbers range from zero
to the number of buffers allocated with :ref:`DMX_REQBUFS`
(struct :c:type:`dvb_requestbuffers` ``count``) minus one.
After calling :ref:`DMX_QUERYBUF` with a pointer to this structure,
drivers return an error code or fill the rest of the structure.
On success, the ``offset`` will contain the offset of the buffer from the
start of the device memory, the ``length`` field its size, and the
``bytesused`` the number of bytes occupied by data in the buffer (payload).
반환값과 EINVAL
51-64성공하면 0을 반환하며 `offset`, `length`, `bytesused`를 위 의미대로 채웁니다.
오류가 발생하면 -1을 반환하고 `errno`를 적절히 설정합니다. 공통 오류 코드는 `Generic Error Codes <gen-errors>` 장에서 설명합니다.
문서가 명시한 인덱스 오류입니다.
Return Value
============
On success 0 is returned, the ``offset`` will contain the offset of the
buffer from the start of the device memory, the ``length`` field its size,
and the ``bytesused`` the number of bytes occupied by data in the buffer
(payload).
On error it returns -1 and the ``errno`` variable is set
appropriately. The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.
EINVAL
The ``index`` is out of bounds.
요약·해설
dmx-querybuf.rst:1-64QUERYBUF는 REQBUFS 이후 index별 버퍼 상태와 mmap에 필요한 offset·length, 실제 payload 크기 bytesused를 반환합니다.