Man page - poll(2)

Packages contains this manual

Available languages:

en fr ja

Manual

POLL

名 前
書 式
説 明
ppoll()
返 り 値
エ ラ ー
バ ー ジ ョ ン
準 拠
注 意
C ラ イ ブ ラ リ と カ ー ネ ル の 違 い
バ グ
例
プ ロ グ ラ ム の ソ ー ス
関 連 項 目
こ の 文 書 に つ い て

名 前

poll, ppoll - フ ァ イ ル デ ィ ス ク リ プ タ ー に お け る イ ベ ン ト を 待 つ

書 式

#include <poll.h>

int poll(struct pollfd * fds , nfds_t nfds , int timeout );

#define _GNU_SOURCE /* feature_test_macros(7) 参 照 */
#include <signal.h>
#include <poll.h>

int ppoll(struct pollfd * fds , nfds_t nfds ,
const struct timespec * tmo_p , const sigset_t * sigmask );

説 明

poll () performs a similar task to select (2): it waits for one of a set of file descriptors to become ready to perform I/O. The Linux-specific epoll (7) API performs a similar task, but offers features beyond those found in poll ().

監 視 す る フ ァ イ ル デ ィ ス ク リ プ タ ー 集 合 は 、 fds 引 数 で 指 定 す る 。 fds は 、 以 下 の 型 の 構 造 体 の 配 列 で あ る 。

struct pollfd {
int fd; /* file descriptor */
short events; /* requested events */
short revents; /* returned events */
};

nfds に は 、 fds 配 列 の 要 素 数 を 指 定 す る 。

fd フ ィ ー ル ド に は 、 オ ー プ ン さ れ た フ ァ イ ル の フ ァ イ ル デ ィ ス ク リ プ タ ー が 入 る 。 こ の フ ィ ー ル ド が 負 の 場 合 、 対 応 す る events フ ィ ー ル ド は 無 視 さ れ 、 revents に は 0 が 返 さ れ る 。 (こ の 機 能 に よ り 、 一 つ の poll () の 呼 び 出 し で 簡 単 に あ る フ ァ イ ル デ ィ ス ク リ プ タ ー を 無 視 す る こ と が で き る 。 単 に fd フ ィ ー ル ド の 符 号 を 反 転 す る だ け で よ い 。 た だ し 、 こ の 方 法 は フ ァ イ ル デ ィ ス ク リ プ タ ー 0 を 無 視 す る の に は 使 用 で き な い 点 に 注 意 す る こ と 。 )

構 造 体 の events 要 素 は 入 力 パ ラ メ ー タ ー で 、 フ ァ イ ル デ ィ ス ク リ プ タ ー fd に 関 し て 、 ア プ リ ケ ー シ ョ ン が 興 味 を 持 っ て い る イ ベ ン ト の ビ ッ ト マ ス ク を 指 定 す る 。 こ の フ ィ ー ル ド に は 0 を 指 定 す る こ と も で き 、 そ の 場 合 revents で 返 さ れ る イ ベ ン ト は POLLHUP , POLLERR , POLLNVAL だ け で あ る (下 記 参 照 )。

revents 要 素 は 出 力 パ ラ メ ー タ ー で 、 実 際 に 起 こ っ た イ ベ ン ト が カ ー ネ ル に よ り 設 定 さ れ る 。 revents で 返 さ れ る ビ ッ ト 列 に は 、 events で 指 定 し た も の の ど れ か 、 も し く は POLLERR , POLLHUP , POLLNVAL の う ち の 一 つ が 含 ま れ る ( POLLERR , POLLHUP , POLLNVAL の 3つ の ビ ッ ト は events に 指 定 し て も 意 味 が な く 、 対 応 し た 状 態 が 真 の 場 合 に revents に 設 定 さ れ る )。

ど の フ ァ イ ル デ ィ ス ク リ プ タ ー に も 要 求 し た イ ベ ン ト が 発 生 し て お ら ず 、 エ ラ ー も 起 こ ら な い 場 合 、 poll () は イ ベ ン ト の う ち い ず れ か 一 つ が 発 生 す る ま で 停 止 (block) す る 。

timeout 引 数 は 、 フ ァ イ ル デ ィ ス ク リ プ タ ー が 利 用 可 能 に な る ま で poll () が 停 止 す る 時 間 を ミ リ 秒 で 指 定 す る 。 poll () の 呼 び 出 し は 以 下 の い ず れ か に な る ま で 停 止 す る 。

•

フ ァ イ ル デ ィ ス ク リ プ タ ー が 利 用 可 能 に な る

•

呼 び 出 し が シ グ ナ ル ハ ン ド ラ ー に よ り 割 り 込 ま れ た

•

タ イ ム ア ウ ト が 満 了 す る

timeout 時 間 は シ ス テ ム ク ロ ッ ク の 粒 度 に 切 り 上 げ ら れ 、 カ ー ネ ル の ス ケ ジ ュ ー リ ン グ 遅 延 に よ り 少 し だ け 長 く な る 可 能 性 が あ る 点 に 注 意 す る こ と 。 timeout に 負 の 値 を 指 定 し た 場 合 、 タ イ ム ア ウ ト 時 間 が 無 限 大 を 意 味 す る 。 timeout を 0 に 指 定 し た 場 合 、 I/O 可 能 な フ ァ イ ル デ ィ ス ク リ プ タ ー が な い 場 合 で あ っ て も 、 poll () は す ぐ に 返 る 。

events に 指 定 し た り 、 revents で 返 さ れ る ビ ッ ト は <poll.h> で 定 義 さ れ て い る :

POLLIN

読 み 出 し 可 能 な デ ー タ が あ る 。

POLLPRI

There is some exceptional condition on the file descriptor. Possibilities include:

•

There is out-of-band data on a TCP socket (see tcp (7)).

•

A pseudoterminal master in packet mode has seen a state change on the slave (see ioctl_tty (2)).

•

A cgroup.events file has been modified (see cgroups (7)).

POLLOUT

書 き 込 み が 可 能 に な っ た 。 た だ し 、 ソ ケ ッ ト や パ イ プ で 利 用 可 能 な 空 間 よ り も 大 き な デ ー タ を 書 き 込 ん だ 場 合 に は ( O_NONBLOCK が セ ッ ト さ れ て い る 場 合 以 外 は ) や は り 停 止 す る こ と に な る 。

POLLRDHUP (Linux 2.6.17 以 降 )

ス ト リ ー ム ソ ケ ッ ト の 他 端 が 、 コ ネ ク シ ョ ン を close し た か 、 コ ネ ク シ ョ ン の 書 き 込 み 側 を shutdown し た 。 こ の 定 義 を 有 効 に す る に は 、 (「 ど の 」 ヘ ッ ダ ー フ ァ イ ル を イ ン ク ル ー ド す る よ り も 前 に ) _GNU_SOURCE 機 能 検 査 マ ク ロ を 定 義 し な け れ ば な ら な い 。

POLLERR

Error condition (only returned in revents ; ignored in events ). This bit is also set for a file descriptor referring to the write end of a pipe when the read end has been closed.

POLLHUP

Hang up (only returned in revents ; ignored in events ). Note that when reading from a channel such as a pipe or a stream socket, this event merely indicates that the peer closed its end of the channel. Subsequent reads from the channel will return 0 (end of file) only after all outstanding data in the channel has been consumed.

POLLNVAL

Invalid request: fd not open (only returned in revents ; ignored in events ).

_XOPEN_SOURCE を 定 義 し て コ ン パ イ ル し た 場 合 に は 、 以 下 の 定 義 も 行 わ れ る 。 た だ し 、 上 記 の リ ス ト に あ る ビ ッ ト 以 上 の 情 報 が 得 ら れ る 訳 で は な い 。
POLLRDNORM

POLLIN と 同 じ 。

POLLRDBAND

優 先 帯 域 デ ー タ (priority band data) が 読 み 出 し 可 能 で あ る (普 通 は Linux で は 使 用 さ れ な い )。

POLLWRNORM

POLLOUT と 同 じ 。

POLLWRBAND

優 先 帯 域 デ ー タ (priority data) が 書 き 込 み 可 能 で あ る 。

Linux で は POLLMSG も 定 義 さ れ て い る が 、 使 用 さ れ て い な い 。

ppoll()

poll () と ppoll () の 関 係 は select (2) と pselect (2) の 関 係 と 同 じ よ う な も の で あ る : pselect (2) と 同 様 に 、 ppoll () を 使 う と 、 ア プ リ ケ ー シ ョ ン は フ ァ イ ル デ ィ ス ク リ プ タ ー の 状 態 変 化 も し く は シ グ ナ ル の 捕 捉 を 安 全 に 待 つ こ と が で き る 。

timeout 引 数 の 精 度 の 違 い を 除 く と 、 以 下 の ppoll () の 呼 び 出 し は 、

ready = ppoll(&fds, nfds, tmo_p, &sigmask);

次 の 呼 び 出 し を atomic に 実 行 す る の と ほ ぼ 等 価 で あ る 。

sigset_t origmask;
int timeout;

timeout = (tmo_p == NULL) ? -1 :
(tmo_p->tv_sec * 1000 + tmo_p->tv_nsec / 1000000);
pthread_sigmask(SIG_SETMASK, &sigmask, &origmask);
ready = poll(&fds, nfds, timeout);
pthread_sigmask(SIG_SETMASK, &origmask, NULL);

The above code segment is described as nearly equivalent because whereas a negative timeout value for poll () is interpreted as an infinite timeout, a negative value expressed in *tmo_p results in an error from ppoll ().

な ぜ ppoll () が 必 要 な の か に つ い て の 説 明 は pselect (2) の 説 明 を 参 照 の こ と 。

sigmask 引 数 に NULL が 指 定 さ れ た 場 合 、 シ グ ナ ル マ ス ク の 操 作 は 行 わ れ な い (し た が っ て 、 ppoll () の poll () と の 違 い は timeout 引 数 の 精 度 だ け と な る )。

tmo_p 引 数 は ppoll () が 停 止 す る 時 間 の 上 限 を 指 定 す る も の で あ る 。 こ の 引 数 に は 以 下 の 型 の 構 造 体 へ の ポ イ ン タ ー を 指 定 す る 。

struct timespec {
long tv_sec; /* seconds */
long tv_nsec; /* nanoseconds */
};

tmo_p に NULL が 指 定 さ れ た 場 合 、 ppoll は 無 限 に 停 止 す る こ と が あ り 得 る 。

返 り 値

On success, poll () returns a nonnegative value which is the number of elements in the pollfds whose revents fields have been set to a nonzero value (indicating an event or an error). A return value of zero indicates that the system call timed out before any file descriptors became read.

On error, -1 is returned, and errno is set to indicate the cause of the error.

エ ラ ー

EFAULT

fds points outside the process’s accessible address space. The array given as argument was not contained in the calling program’s address space.

EINTR

要 求 さ れ た イ ベ ン ト の ど れ か が 起 こ る 前 に シ グ ナ ル が 発 生 し た 。 signal (7) 参 照 。

EINVAL

nfds の 値 が RLIMIT_NOFILE を 超 え た 。

EINVAL

( ppoll ()) The timeout value expressed in *ip is invalid (negative).

ENOMEM

Unable to allocate memory for kernel data structures.

バ ー ジ ョ ン

poll () シ ス テ ム コ ー ル は Linux 2.1.23 で 導 入 さ れ た 。 こ の シ ス テ ム コ ー ル が 存 在 し な い 古 い カ ー ネ ル で は 、 glibc は select (2) を 使 用 し て poll () ラ ッ パ ー 関 数 の エ ミ ュ レ ー シ ョ ン を 行 う 。

ppoll () シ ス テ ム コ ー ル は カ ー ネ ル 2.6.16 で Linux に 追 加 さ れ た 。 ppoll () ラ イ ブ ラ リ コ ー ル は glibc 2.4 に 追 加 さ れ た 。

準 拠

poll () は POSIX.1-2001 と POSIX.1-2008 に 準 拠 し て い る 。 ppoll () は Linux 固 有 で あ る 。

注 意

The operation of poll () and ppoll () is not affected by the O_NONBLOCK flag.

On some other UNIX systems, poll () can fail with the error EAGAIN if the system fails to allocate kernel-internal resources, rather than ENOMEM as Linux does. POSIX permits this behavior. Portable programs may wish to check for EAGAIN and loop, just as with EINTR .

い く つ か の 実 装 で は 、 値 -1 を 持 っ た 非 標 準 の 定 数 INFTIM が 定 義 さ れ て お り 、 poll () の timeout の 指 定 に 使 用 で き る 。 こ の 定 数 は glibc で は 定 義 さ れ て い な い 。

poll () で 監 視 中 の フ ァ イ ル デ ィ ス ク リ プ タ ー が 別 の ス レ ッ ド に よ っ て ク ロ ー ズ さ れ た 場 合 に 何 が 起 こ る か の 議 論 に つ い て は 、 select (2) を 参 照 し て ほ し い 。

C ラ イ ブ ラ リ と カ ー ネ ル の 違 い

Linux の ppoll () シ ス テ ム コ ー ル は tmo_p 引 数 を 変 更 す る 。 し か し 、 glibc の ラ ッ パ ー 関 数 は 、 シ ス テ ム コ ー ル に 渡 す timeout 引 数 と し て ロ ー カ ル 変 数 を 使 う こ と で こ の 動 作 を 隠 蔽 し て い る 。 こ の た め 、 glibc の ppoll () 関 数 で は tmo_p 引 数 は 変 更 さ れ な い 。

The raw ppoll () system call has a fifth argument, size_t sigsetsize , which specifies the size in bytes of the sigmask argument. The glibc ppoll () wrapper function specifies this argument as a fixed value (equal to sizeof(kernel_sigset_t) ). See sigprocmask (2) for a discussion on the differences between the kernel and the libc notion of the sigset.

バ グ

select (2) の 「 バ グ 」 の 節 に 書 か れ て い る 、 誤 っ た 準 備 完 了 通 知 (spurious readiness notifications) に つ い て の 議 論 を 参 照 の こ と 。

例

The program below opens each of the files named in its command-line arguments and monitors the resulting file descriptors for readiness to read ( POLLIN ). The program loops, repeatedly using poll () to monitor the file descriptors, printing the number of ready file descriptors on return. For each ready file descriptor, the program:

•

displays the returned revents field in a human-readable form;

•

if the file descriptor is readable, reads some data from it, and displays that data on standard output; and

•

if the file descriptors was not readable, but some other event occurred (presumably POLLHUP ), closes the file descriptor.

Suppose we run the program in one terminal, asking it to open a FIFO:

$ mkfifo myfifo
$ ./poll_input myfifo

In a second terminal window, we then open the FIFO for writing, write some data to it, and close the FIFO:

$ echo aaaaabbbbbccccc > myfifo

In the terminal where we are running the program, we would then see:

Opened "myfifo" on fd 3
About to poll()
Ready: 1
fd=3; events: POLLIN POLLHUP
read 10 bytes: aaaaabbbbb
About to poll()
Ready: 1
fd=3; events: POLLIN POLLHUP
read 6 bytes: ccccc

About to poll()
Ready: 1
fd=3; events: POLLHUP
closing fd 3
All file descriptors closed; bye

In the above output, we see that poll () returned three times:

•

On the first return, the bits returned in the revents field were POLLIN , indicating that the file descriptor is readable, and POLLHUP , indicating that the other end of the FIFO has been closed. The program then consumed some of the available input.

•

The second return from poll () also indicated POLLIN and POLLHUP ; the program then consumed the last of the available input.

•

On the final return, poll () indicated only POLLHUP on the FIFO, at which point the file descriptor was closed and the program terminated.

プ ロ グ ラ ム の ソ ー ス

/* poll_input.c

Licensed under GNU General Public License v2 or later.
*/
#include <poll.h>
#include <fcntl.h>
#include <sys/types.h>
#include <stdio.h>
#include <stdlib.h>
#include <unistd.h>

#define errExit(msg) do { perror(msg); exit(EXIT_FAILURE); \
} while (0)

int
main(int argc, char *argv[])
{
int nfds, num_open_fds;
struct pollfd *pfds;

if (argc < 2) {
fprintf(stderr, "Usage: %s file...\n", argv[0]);
exit(EXIT_FAILURE);
}

num_open_fds = nfds = argc - 1;
pfds = calloc(nfds, sizeof(struct pollfd));
if (pfds == NULL)
errExit("malloc");

/* Open each file on command line, and add it 'pfds' array */

for (int j = 0; j < nfds; j++) {
pfds[j].fd = open(argv[j + 1], O_RDONLY);
if (pfds[j].fd == -1)
errExit("open");

printf("Opened \"%s\" on fd %d\n", argv[j + 1], pfds[j].fd);

pfds[j].events = POLLIN;
}

/* Keep calling poll() as long as at least one file descriptor is
open */

while (num_open_fds > 0) {
int ready;

printf("About to poll()\n");
ready = poll(pfds, nfds, -1);
if (ready == -1)
errExit("poll");

printf("Ready: %d\n", ready);

/* Deal with array returned by poll() */

for (int j = 0; j < nfds; j++) {
char buf[10];

if (pfds[j].revents != 0) {
printf(" fd=%d; events: %s%s%s\n", pfds[j].fd,
(pfds[j].revents & POLLIN) ? "POLLIN " : "",
(pfds[j].revents & POLLHUP) ? "POLLHUP " : "",
(pfds[j].revents & POLLERR) ? "POLLERR " : "");

if (pfds[j].revents & POLLIN) {
ssize_t s = read(pfds[j].fd, buf, sizeof(buf));
if (s == -1)
errExit("read");
printf(" read %zd bytes: %.*s\n",
s, (int) s, buf);
} else { /* POLLERR | POLLHUP */
printf(" closing fd %d\n", pfds[j].fd);
if (close(pfds[j].fd) == -1)
errExit("close");
num_open_fds--;
}
}
}
}

printf("All file descriptors closed; bye\n");
exit(EXIT_SUCCESS);
}

関 連 項 目

restart_syscall (2), select (2), select_tut (2), epoll (7), time (7)

こ の 文 書 に つ い て

こ の man ペ ー ジ は Linux man-pages プ ロ ジ ェ ク ト の リ リ ー ス 5.10 の 一 部 で あ る 。 プ ロ ジ ェ ク ト の 説 明 と バ グ 報 告 に 関 す る 情 報 は https://www.kernel.org/doc/man-pages/ に 書 か れ て い る 。