요약·해설과 원문, 전문 번역을 서로 분리했습니다. API 이름, symbol, source path는 원문 표기를 사용합니다.
1. 요약·해설
원문의 핵심 논리와 kernel programming 관점의 보충 설명입니다. 아래의 전문 번역과는 별도로 작성했습니다.
2. 영어 원문 전체
번역 기준이 된 Linux v6.18.37 원문입니다. 줄 번호는 이 버전의 파일 좌표입니다.
원문 전체 펼치기
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
.. c:namespace:: CEC
.. _cec-func-poll:
**********
cec poll()
**********
Name
====
cec-poll - Wait for some event on a file descriptor
Synopsis
========
.. code-block:: c
#include <sys/poll.h>
.. c:function:: int poll( struct pollfd *ufds, unsigned int nfds, int timeout )
Arguments
=========
``ufds``
List of FD events to be watched
``nfds``
Number of FD events at the \*ufds array
``timeout``
Timeout to wait for events
Description
===========
With the :c:func:`poll()` function applications can wait for CEC
events.
On success :c:func:`poll()` returns the number of file descriptors
that have been selected (that is, file descriptors for which the
``revents`` field of the respective struct :c:type:`pollfd`
is non-zero). CEC devices set the ``POLLIN`` and ``POLLRDNORM`` flags in
the ``revents`` field if there are messages in the receive queue. If the
transmit queue has room for new messages, the ``POLLOUT`` and
``POLLWRNORM`` flags are set. If there are events in the event queue,
then the ``POLLPRI`` flag is set. When the function times out it returns
a value of zero, on failure it returns -1 and the ``errno`` variable is
set appropriately.
For more details see the :c:func:`poll()` manual page.
Return Value
============
On success, :c:func:`poll()` returns the number structures which have
non-zero ``revents`` fields, or zero if the call timed out. On error -1
is returned, and the ``errno`` variable is set appropriately:
``EBADF``
One or more of the ``ufds`` members specify an invalid file
descriptor.
``EFAULT``
``ufds`` references an inaccessible memory area.
``EINTR``
The call was interrupted by a signal.
``EINVAL``
The ``nfds`` value exceeds the ``RLIMIT_NOFILE`` value. Use
``getrlimit()`` to obtain this value.
3. 한국어 전문 번역
영어 원문의 문단 순서와 의미를 유지한 전체 번역입니다. 코드, 함수명, symbol과 URL은 원문 표기를 유지합니다.
이름과 선언
1-21`cec-poll`은 file descriptor에서 CEC event가 생길 때까지 기다립니다. `<sys/poll.h>`를 포함하며 함수 원형은 `int poll(struct pollfd *ufds, unsigned int nfds, int timeout)`입니다.
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
.. c:namespace:: CEC
.. _cec-func-poll:
**********
cec poll()
**********
Name
====
cec-poll - Wait for some event on a file descriptor
Synopsis
========
.. code-block:: c
#include <sys/poll.h>
인자
22-34`ufds`는 감시할 FD event 목록이고 `nfds`는 `ufds` 배열의 FD event 수입니다. `timeout`은 event를 기다릴 시간입니다.
감시 배열, 원소 수와 대기 시간을 전달합니다.
.. c:function:: int poll( struct pollfd *ufds, unsigned int nfds, int timeout )
Arguments
=========
``ufds``
List of FD events to be watched
``nfds``
Number of FD events at the \*ufds array
``timeout``
Timeout to wait for eventsCEC queue와 revents flag
35-54응용 프로그램은 `poll()`로 CEC event를 기다릴 수 있습니다. 성공하면 해당 `struct pollfd`의 `revents`가 0이 아닌, 선택된 file descriptor 수를 반환합니다.
receive queue에 message가 있으면 CEC device는 `POLLIN`과 `POLLRDNORM`을 설정합니다.
transmit queue에 새 message를 넣을 공간이 있으면 `POLLOUT`과 `POLLWRNORM`을 설정합니다.
event queue에 event가 있으면 `POLLPRI`를 설정합니다. timeout이면 0, 실패하면 -1을 반환하고 `errno`를 설정합니다. 더 자세한 내용은 `poll()` manual page를 참조합니다.
queue 상태를 revents flag로 매핑합니다.
반환된 revents에 따라 읽기·전송·event dequeue 경로를 선택합니다.
Description
===========
With the :c:func:`poll()` function applications can wait for CEC
events.
On success :c:func:`poll()` returns the number of file descriptors
that have been selected (that is, file descriptors for which the
``revents`` field of the respective struct :c:type:`pollfd`
is non-zero). CEC devices set the ``POLLIN`` and ``POLLRDNORM`` flags in
the ``revents`` field if there are messages in the receive queue. If the
transmit queue has room for new messages, the ``POLLOUT`` and
``POLLWRNORM`` flags are set. If there are events in the event queue,
then the ``POLLPRI`` flag is set. When the function times out it returns
a value of zero, on failure it returns -1 and the ``errno`` variable is
set appropriately.
For more details see the :c:func:`poll()` manual page.
반환값
55-60성공하면 `revents`가 0이 아닌 structure 수를 반환하고 timeout이면 0을 반환합니다. 오류이면 -1을 반환하고 `errno`를 설정합니다.
Return Value
============
On success, :c:func:`poll()` returns the number structures which have
non-zero ``revents`` fields, or zero if the call timed out. On error -1
is returned, and the ``errno`` variable is set appropriately:오류 code
61-74`EBADF`는 `ufds` 원소 하나 이상이 유효하지 않은 file descriptor를 지정했음을 뜻합니다. `EFAULT`는 `ufds`가 접근할 수 없는 memory 영역을 참조함을 뜻합니다.
`EINTR`은 signal로 호출이 중단됐음을 뜻합니다. `EINVAL`은 `nfds`가 `RLIMIT_NOFILE`을 넘었음을 뜻하며 `getrlimit()`으로 이 값을 확인할 수 있습니다.
descriptor, memory, signal, resource limit 오류입니다.
``EBADF``
One or more of the ``ufds`` members specify an invalid file
descriptor.
``EFAULT``
``ufds`` references an inaccessible memory area.
``EINTR``
The call was interrupted by a signal.
``EINVAL``
The ``nfds`` value exceeds the ``RLIMIT_NOFILE`` value. Use
``getrlimit()`` to obtain this value.
요약·해설
cec-func-poll.rst:1-74`poll()`의 receive queue, transmit queue, event queue를 각각 `POLLIN`, `POLLOUT`, `POLLPRI` 계열 flag로 구분합니다.