요약·해설과 원문, 전문 번역을 서로 분리했습니다. API 이름, symbol, source path는 원문 표기를 사용합니다.
1. 요약·해설
원문의 핵심 논리와 kernel programming 관점의 보충 설명입니다. 아래의 전문 번역과는 별도로 작성했습니다.
2. 영어 원문 전체
번역 기준이 된 Linux v6.18.37 원문입니다. 줄 번호는 이 버전의 파일 좌표입니다.
원문 전체 펼치기
.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later
.. c:namespace:: RC
.. _lirc-read:
***********
LIRC read()
***********
Name
====
lirc-read - Read from a LIRC device
Synopsis
========
.. code-block:: c
#include <unistd.h>
.. c:function:: ssize_t read( int fd, void *buf, size_t count )
Arguments
=========
``fd``
File descriptor returned by ``open()``.
``buf``
Buffer to be filled
``count``
Max number of bytes to read
Description
===========
:c:func:`read()` attempts to read up to ``count`` bytes from file
descriptor ``fd`` into the buffer starting at ``buf``. If ``count`` is zero,
:c:func:`read()` returns zero and has no other results. If ``count``
is greater than ``SSIZE_MAX``, the result is unspecified.
The exact format of the data depends on what :ref:`lirc_modes` a driver
uses. Use :ref:`lirc_get_features` to get the supported mode, and use
:ref:`lirc_set_rec_mode` set the current active mode.
The mode :ref:`LIRC_MODE_MODE2 <lirc-mode-mode2>` is for raw IR,
in which packets containing an unsigned int value describing an IR signal are
read from the chardev.
Alternatively, :ref:`LIRC_MODE_SCANCODE <lirc-mode-scancode>` can be available,
in this mode scancodes which are either decoded by software decoders, or
by hardware decoders. The :c:type:`rc_proto` member is set to the
:ref:`IR protocol <Remote_controllers_Protocols>`
used for transmission, and ``scancode`` to the decoded scancode,
and the ``keycode`` set to the keycode or ``KEY_RESERVED``.
Return Value
============
On success, the number of bytes read is returned. It is not an error if
this number is smaller than the number of bytes requested, or the amount
of data required for one frame. On error, -1 is returned, and the ``errno``
variable is set appropriately.
3. 한국어 전문 번역
영어 원문의 문단 순서와 의미를 유지한 전체 번역입니다. 코드, 함수명, symbol과 URL은 원문 표기를 유지합니다.
이름, 선언과 인자
1-35LIRC `read()`는 열린 LIRC 장치에서 데이터를 읽어 application buffer를 채웁니다.
#include <unistd.h>
ssize_t read(int fd, void *buf, size_t count);읽을 장치, 결과 buffer와 최대 byte 수를 전달합니다.
.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later
.. c:namespace:: RC
.. _lirc-read:
***********
LIRC read()
***********
Name
====
lirc-read - Read from a LIRC device
Synopsis
========
.. code-block:: c
#include <unistd.h>
.. c:function:: ssize_t read( int fd, void *buf, size_t count )
Arguments
=========
``fd``
File descriptor returned by ``open()``.
``buf``
Buffer to be filled
``count``
Max number of bytes to read
읽기 동작과 mode별 data 형식
36-58`read()`는 `fd`에서 최대 `count` byte를 `buf`로 읽습니다. `count`가 0이면 다른 효과 없이 0을 반환하며, `SSIZE_MAX`보다 크면 결과가 정의되지 않습니다.
정확한 data 형식은 driver의 활성 LIRC mode에 달려 있습니다. `LIRC_GET_FEATURES`로 지원 mode를 확인하고 `LIRC_SET_REC_MODE`로 현재 수신 mode를 선택합니다.
`LIRC_MODE_MODE2`에서는 raw IR 신호를 설명하는 unsigned int packet을 문자 장치에서 읽습니다. Packet은 pulse, space, frequency, timeout 또는 overflow type과 payload를 담습니다.
`LIRC_MODE_SCANCODE`에서는 software 또는 hardware decoder가 만든 scan code를 읽습니다. `rc_proto`에는 사용한 IR protocol, `scancode`에는 decode 값, `keycode`에는 대응 key code가 들어가며 mapping이 없으면 `KEY_RESERVED`입니다.
활성 receive mode에 따라 buffer element가 달라집니다.
Description
===========
:c:func:`read()` attempts to read up to ``count`` bytes from file
descriptor ``fd`` into the buffer starting at ``buf``. If ``count`` is zero,
:c:func:`read()` returns zero and has no other results. If ``count``
is greater than ``SSIZE_MAX``, the result is unspecified.
The exact format of the data depends on what :ref:`lirc_modes` a driver
uses. Use :ref:`lirc_get_features` to get the supported mode, and use
:ref:`lirc_set_rec_mode` set the current active mode.
The mode :ref:`LIRC_MODE_MODE2 <lirc-mode-mode2>` is for raw IR,
in which packets containing an unsigned int value describing an IR signal are
read from the chardev.
Alternatively, :ref:`LIRC_MODE_SCANCODE <lirc-mode-scancode>` can be available,
in this mode scancodes which are either decoded by software decoders, or
by hardware decoders. The :c:type:`rc_proto` member is set to the
:ref:`IR protocol <Remote_controllers_Protocols>`
used for transmission, and ``scancode`` to the decoded scancode,
and the ``keycode`` set to the keycode or ``KEY_RESERVED``.
반환값과 short read
59-65성공하면 실제로 읽은 byte 수를 반환합니다. 요청한 byte 수보다 작거나 한 frame에 필요한 data보다 적은 short read도 오류가 아닙니다. 오류이면 -1을 반환하고 `errno`를 설정합니다.
Application은 한 번의 `read()`가 완전한 frame을 보장한다고 가정하지 말고, 반환 byte 수에 따라 남은 data를 이어서 읽어야 합니다.
Return Value
============
On success, the number of bytes read is returned. It is not an error if
this number is smaller than the number of bytes requested, or the amount
of data required for one frame. On error, -1 is returned, and the ``errno``
variable is set appropriately.
요약·해설
lirc-read.rst:1-65`read()`의 buffer 형식은 현재 receive mode에 달려 있으며 short read는 정상입니다. MODE2와 SCANCODE structure를 구분하고 반환 byte 수를 기준으로 frame을 조립해야 합니다.