Manpages

名 前

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 *timeout_ts, const sigset_t *sigmask);

説 明

poll() は select(2) と 同 様 の 仕 事 を 行 う 、 つ ま り 、 フ ァ イ ル デ ィ ス ク リ プ タ ー 集 合 の い ず れ か 一 つ が I/O を 実 行 可 能 な 状 態 に な る の を 待 つ 。 監 視 す る フ ァ イ ル デ ィ ス ク リ プ タ ー 集 合 は 、 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> で 定 義 さ れ て い る :

POLLPRI 読 み 出 し 可 能 な 緊 急 デ ー タ (urgent data) が あ る (例 え ば 、 TCP ソ ケ ッ ト の 帯 域 外 (out−of−band data) デ ー タ を 受 信 し た 場 合 や 、 パ ケ ッ ト モ ー ド の 擬 似 端 末 の マ ス タ が ス レ ー ブ 側 の 変 化 を 見 つ け た と き )。
POLLOUT 書 き 込 み が 可 能 に な っ た 。 た だ し 、 ソ ケ ッ ト や パ イ プ で 利 用 可 能 な 空 間 よ り も 大 き な デ ー タ を 書 き 込 ん だ 場 合 に は (O_NONBLOCK が セ ッ ト さ れ て い る 場 合 以 外 は ) や は り 停 止 す る こ と に な る 。
POLLRDHUP (Linux 2.6.17 以 降 ) ス ト リ ー ム ソ ケ ッ ト の 他 端 が 、 コ ネ ク シ ョ ン を close し た か 、 コ ネ ク シ ョ ン の 書 き 込 み 側 を shutdown し た 。 こ の 定 義 を 有 効 に す る に は 、 (「 ど の 」 ヘ ッ ダ ー フ ァ イ ル を イ ン ク ル ー ド す る よ り も 前 に ) _GNU_SOURCE 機 能 検 査 マ ク ロ を 定 義 し な け れ ば な ら な い 。
POLLERR エ ラ ー 状 態 (出 力 の 場 合 の み )。
POLLHUP ハ ン グ ア ッ プ し た (出 力 の 場 合 の み )。
POLLNVAL 不 正 な 要 求 : fd が オ ー プ ン さ れ て い な い (出 力 の 場 合 の み )。

_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, timeout_ts, &sigmask); 次 の 呼 び 出 し を atomic に 実 行 す る の と 等 価 で あ る 。

sigset_t origmask;
int timeout;

timeout = (timeout_ts == NULL) ? −1 :
(timeout_ts.tv_sec * 1000 + timeout_ts.tv_nsec / 1000000);
sigprocmask(SIG_SETMASK, &sigmask, &origmask);
ready = poll(&fds, nfds, timeout);
sigprocmask(SIG_SETMASK, &origmask, NULL); な ぜ ppoll() が 必 要 な の か に つ い て の 説 明 は pselect(2) の 説 明 を 参 照 の こ と 。

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

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

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

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

返 り 値

成 功 し た 場 合 は 正 の 数 を 返 す 。 こ の 数 は 0 以 外 の revents 要 素 を 持 つ 構 造 体 の 数 で あ る (別 の 言 い 方 を す る と 、 こ れ ら の デ ィ ス ク リ プ タ ー に は イ ベ ン ト か エ ラ ー 報 告 が あ る )。 値 0 は 、 タ イ ム ア ウ ト と な り 、 ど の フ ァ イ ル デ ィ ス ク リ プ タ ー で も イ ベ ン ト が 発 生 し な か っ た こ と を 示 す 。 エ ラ ー の 場 合 は −1 が 返 さ れ 、 errno が 適 切 に 設 定 さ れ る 。

エ ラ ー

signal(7) 参 照 。

フ ァ イ ル デ ィ ス ク リ プ タ ー テ ー ブ ル を 確 保 す る た め の メ モ リ ー が な い 。