요약·해설과 원문, 전문 번역을 서로 분리했습니다. 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-write:
************
LIRC write()
************
Name
====
lirc-write - Write to a LIRC device
Synopsis
========
.. code-block:: c
#include <unistd.h>
.. c:function:: ssize_t write( int fd, void *buf, size_t count )
Arguments
=========
``fd``
File descriptor returned by ``open()``.
``buf``
Buffer with data to be written
``count``
Number of bytes at the buffer
Description
===========
:c:func:`write()` writes up to ``count`` bytes to the device
referenced by the file descriptor ``fd`` from the buffer starting at
``buf``.
The exact format of the data depends on what mode a driver is in, use
:ref:`lirc_get_features` to get the supported modes and use
:ref:`lirc_set_send_mode` set the mode.
When in :ref:`LIRC_MODE_PULSE <lirc-mode-PULSE>` mode, the data written to
the chardev is a pulse/space sequence of integer values. Pulses and spaces
are only marked implicitly by their position. The data must start and end
with a pulse, therefore, the data must always include an uneven number of
samples. The write function blocks until the data has been transmitted
by the hardware. If more data is provided than the hardware can send, the
driver returns ``EINVAL``.
When in :ref:`LIRC_MODE_SCANCODE <lirc-mode-scancode>` mode, one
``struct lirc_scancode`` must be written to the chardev at a time, else
``EINVAL`` is returned. Set the desired scancode in the ``scancode`` member,
and the :ref:`IR protocol <Remote_controllers_Protocols>` in the
:c:type:`rc_proto`: member. All other members must be
set to 0, else ``EINVAL`` is returned. If there is no protocol encoder
for the protocol or the scancode is not valid for the specified protocol,
``EINVAL`` is returned. The write function blocks until the scancode
is transmitted by the hardware.
Return Value
============
On success, the number of bytes written 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. The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.
3. 한국어 전문 번역
영어 원문의 문단 순서와 의미를 유지한 전체 번역입니다. 코드, 함수명, symbol과 URL은 원문 표기를 유지합니다.
이름, 선언과 인자
1-35LIRC `write()`는 application buffer의 송신 data를 열린 LIRC 장치에 기록합니다.
#include <unistd.h>
ssize_t write(int fd, void *buf, size_t count);장치, data buffer와 byte 수를 전달합니다.
.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later
.. c:namespace:: RC
.. _lirc-write:
************
LIRC write()
************
Name
====
lirc-write - Write to a LIRC device
Synopsis
========
.. code-block:: c
#include <unistd.h>
.. c:function:: ssize_t write( int fd, void *buf, size_t count )
Arguments
=========
``fd``
File descriptor returned by ``open()``.
``buf``
Buffer with data to be written
``count``
Number of bytes at the buffer
공통 쓰기 동작과 mode 선택
36-46`write()`는 `buf`에서 최대 `count` byte를 `fd`가 가리키는 LIRC 장치로 씁니다. 정확한 형식은 현재 transmit mode에 따라 달라집니다.
먼저 `LIRC_GET_FEATURES`로 driver가 지원하는 송신 mode를 확인하고 `LIRC_SET_SEND_MODE`로 PULSE 또는 SCANCODE mode를 선택해야 합니다.
Capability와 활성 mode를 맞춘 뒤 data를 기록합니다.
Description
===========
:c:func:`write()` writes up to ``count`` bytes to the device
referenced by the file descriptor ``fd`` from the buffer starting at
``buf``.
The exact format of the data depends on what mode a driver is in, use
:ref:`lirc_get_features` to get the supported modes and use
:ref:`lirc_set_send_mode` set the mode.
LIRC_MODE_PULSE 송신
47-54`LIRC_MODE_PULSE`에서 buffer는 정수 pulse/space 길이의 sequence입니다. Pulse와 space는 별도 tag 없이 배열 위치로 구분되며 첫 값과 마지막 값은 pulse여야 합니다.
따라서 sample 개수는 반드시 홀수입니다. `write()`는 hardware가 전체 data를 송신할 때까지 block하며 hardware가 처리할 수 있는 양보다 많은 data를 주면 `EINVAL`을 반환합니다.
암시적 위치 규칙을 위반하면 올바른 waveform이 되지 않습니다.
When in :ref:`LIRC_MODE_PULSE <lirc-mode-PULSE>` mode, the data written to
the chardev is a pulse/space sequence of integer values. Pulses and spaces
are only marked implicitly by their position. The data must start and end
with a pulse, therefore, the data must always include an uneven number of
samples. The write function blocks until the data has been transmitted
by the hardware. If more data is provided than the hardware can send, the
driver returns ``EINVAL``.
LIRC_MODE_SCANCODE 송신
55-64`LIRC_MODE_SCANCODE`에서는 한 번에 `struct lirc_scancode` 하나만 써야 하며 크기가 다르면 `EINVAL`입니다. `scancode` member에 원하는 값, `rc_proto`에 IR protocol을 설정합니다.
나머지 모든 member는 0이어야 하며 그렇지 않으면 `EINVAL`입니다. 지정 protocol의 encoder가 없거나 scan code가 그 protocol에서 유효하지 않아도 `EINVAL`을 반환합니다.
검증을 통과한 뒤 `write()`는 hardware가 scan code를 실제 송신할 때까지 block합니다.
Structure 크기, member와 encoder를 모두 검사합니다.
When in :ref:`LIRC_MODE_SCANCODE <lirc-mode-scancode>` mode, one
``struct lirc_scancode`` must be written to the chardev at a time, else
``EINVAL`` is returned. Set the desired scancode in the ``scancode`` member,
and the :ref:`IR protocol <Remote_controllers_Protocols>` in the
:c:type:`rc_proto`: member. All other members must be
set to 0, else ``EINVAL`` is returned. If there is no protocol encoder
for the protocol or the scancode is not valid for the specified protocol,
``EINVAL`` is returned. The write function blocks until the scancode
is transmitted by the hardware.
반환값과 short write
65-72성공하면 실제로 쓴 byte 수를 반환합니다. 요청한 byte 수나 한 frame 분량보다 작은 short write도 그 자체로 오류는 아닙니다.
오류이면 -1을 반환하고 `errno`를 설정합니다. Application은 반환 byte 수를 확인하고 일반적인 short write 처리 원칙을 따라야 하며 공통 오류는 Generic Error Codes 절을 참조합니다.
Return Value
============
On success, the number of bytes written 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. The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.
요약·해설
lirc-write.rst:1-72PULSE mode는 홀수 개 pulse/space sample, SCANCODE mode는 나머지 member가 0인 structure 하나를 요구합니다. 두 mode 모두 hardware 송신 완료까지 block하며 반환 byte 수를 확인해야 합니다.