Manpages

名 前

epoll_ctl − epoll デ ィ ス ク リ プ タ ー の イ ン タ ー フ ェ ー ス を 操 作 す る

書 式

#include <sys/epoll.h>

int epoll_ctl(int epfd, int op, int fd, struct epoll_event *event);

説 明

こ の シ ス テ ム コ ー ル は 、 フ ァ イ ル デ ィ ス ク リ プ タ ー epfd が 参 照 す る epoll(7) イ ン ス タ ン ス に 対 す る 操 作 を 行 う 。 対 象 の フ ァ イ ル デ ィ ス ク リ プ タ ー fd に 対 し て 、 操 作 op の 実 行 が 要 求 さ れ る 。

op 引 き 数 に 指 定 で き る 有 効 な 値 は 以 下 の 通 り で あ る 。
EPOLL_CTL_ADD
対 象 の フ ァ イ ル デ ィ ス ク リ プ タ ー fd を フ ァ イ ル デ ィ ス ク リ プ タ ー epfd が 参 照 す る epoll イ ン ス タ ン ス に 登 録 し 、 イ ベ ン ト eventfd に 結 び 付 け ら れ た 内 部 フ ァ イ ル に 関 連 付 け る 。
EPOLL_CTL_MOD
イ ベ ン ト event を 対 象 の フ ァ イ ル デ ィ ス ク リ プ タ ー fd に 関 連 付 け る よ う に 変 更 す る 。
EPOLL_CTL_DEL
対 象 の フ ァ イ ル デ ィ ス ク リ プ タ ー fdepfd が 参 照 す る epoll イ ン ス タ ン ス か ら 削 除 す る 。 event 引 き 数 は 無 視 さ れ る の で 、 NULL に す る こ と も で き る (但 し 、 下 記 の 「 バ グ 」 を 参 照 )。

event 引 き 数 は 、 フ ァ イ ル デ ィ ス ク リ プ タ ー fd に リ ン ク さ れ た オ ブ ジ ェ ク ト を 表 す 。 struct epoll_event は 以 下 の よ う に 定 義 さ れ る 。

typedef union epoll_data {
void *ptr;
int fd;
uint32_t u32;
uint64_t u64; }
epoll_data_t;

struct epoll_event {
uint32_t events; /* epoll イ ベ ン ト */
epoll_data_t data; /* ユ ー ザ ー デ ー タ 変 数 */ };

events メ ン バ は 、 以 下 の よ う な 使 用 可 能 な イ ベ ン ト タ イ プ を 使 っ て 構 成 さ れ た ビ ッ ト セ ッ ト で あ る 。
EPOLLIN
関 連 付 け ら れ た フ ァ イ ル に 対 し て 、 read(2) 操 作 が 可 能 で あ る 。
EPOLLOUT
関 連 付 け ら れ た フ ァ イ ル に 対 し て 、 write(2) 操 作 が 可 能 で あ る 。
EPOLLRDHUP"
(Linux2.6.17以 降 )" ス ト リ ー ム ソ ケ ッ ト の 他 端 が 、 コ ネ ク シ ョ ン の close 、 ま た は コ ネ ク シ ョ ン の 書 き 込 み 側 の shutdown を 行 っ た 。 (こ の フ ラ グ を 使 う と 、 エ ッ ジ ト リ ガ ー の 監 視 を 行 う 場 合 に 、 通 信 の も う 一 端 が 閉 じ ら れ た こ と を 検 知 す る コ ー ド を 非 常 に 簡 潔 に 書 く こ と が で き る 。 )
EPOLLPRI

read(2) 操 作 が 可 能 な 緊 急 (urgent) デ ー タ が あ る 。

EPOLLERR 関 連 付 け ら れ た フ ァ イ ル デ ィ ス ク リ プ タ ー に エ ラ ー 条 件 が 起 こ っ た 。 epoll_wait(2) は 常 に こ の イ ベ ン ト を 待 つ の で 、 events に 設 定 す る 必 要 は な い 。
EPOLLHUP
関 連 付 け ら れ た フ ァ イ ル デ ィ ス ク リ プ タ ー に ハ ン グ ア ッ プ が 起 こ っ た 。 epoll_wait(2) は 常 に こ の イ ベ ン ト を 待 つ の で 、 events に 設 定 す る 必 要 は な い 。
EPOLLET
関 連 付 け ら れ た フ ァ イ ル デ ィ ス ク リ プ タ ー に エ ッ ジ ト リ ガ ー 動 作 (Edge Triggered behavior) を 設 定 す る 。 epoll の デ フ ォ ル ト の 動 作 は 、 レ ベ ル ト リ ガ ー (Level Triggered) で あ る 。 エ ッ ジ ト リ ガ ー と レ ベ ル ト リ ガ ー に よ る イ ベ ン ト 分 配 機 構 (event distribution architectures) に つ い て の 詳 細 な 情 報 は 、 epoll(7) を 参 照 す る こ と 。
EPOLLONESHOT
(Linux 2.6.2 以 降 ) 関 連 付 け ら れ た フ ァ イ ル デ ィ ス ク リ プ タ ー に 一 撃 動 作 (One−Shot behavior) を 設 定 す る 。 こ れ は イ ベ ン ト が epoll_wait(2) に よ っ て 引 き 出 さ れ た 後 、 関 連 付 け ら れ た フ ァ イ ル デ ィ ス ク リ プ タ ー が 内 部 的 に 破 棄 さ れ 、 epoll イ ン タ ー フ ェ ー ス に よ っ て イ ベ ン ト が 報 告 さ れ な く な る こ と を 意 味 す る 。 新 し い イ ベ ン ト マ ス ク で フ ァ イ ル デ ィ ス ク リ プ タ ー を 再 度 有 効 に す る た め に は 、 epoll_ctl() に EPOLL_CTL_MOD を 指 定 し て 呼 び 出 さ な け れ ば な ら な い 。 op 引 き 数 に 指 定 で き る 有 効 な 値 は 、 以 下 の 通 り :
EPOLLWAKEUP
(Linux 3.5 以 降 )

EPOLLONESHOTEPOLLET が ク リ ア さ れ て お り 、 プ ロ セ ス が CAP_BLOCK_SUSPEND ケ ー パ ビ リ テ ィ を 持 っ て い る 場 合 、 イ ベ ン ト が 処 理 待 ち か 処 理 中 か に か か わ ら ず 、 必 ず シ ス テ ム が "suspend" や "hibernate" に 入 ら な い よ う に す る こ と 。 epoll_wait(2) の 呼 び 出 し が 返 っ た 時 点 か ら 、 同 じ epoll(7) フ ァ イ ル デ ィ ス ク リ プ タ ー に 対 し て epoll_wait(2) が 次 に 呼 び 出 さ れ る か 、 そ の フ ァ イ ル デ ィ ス ク リ プ タ ー が 閉 じ ら れ る か 、 イ ベ ン ト フ ァ イ ル デ ィ ス ク リ プ タ ー が EPOLL_CTL_DEL で 削 除 さ れ る か 、 EPOLL_CTL_MOD で イ ベ ン ト フ ァ イ ル デ ィ ス ク リ プ タ ー の EPOLLWAKEUP が ク リ ア さ れ る か 、 の い ず れ か に な る ま で 、 イ ベ ン ト は 「 処 理 中 」 で あ る と み な さ れ る 。 「 バ グ 」 の 節 も 参 照 の こ と 。

返 り 値

成 功 し た 場 合 、 epoll_ctl() は 0 を 返 す 。 エ ラ ー が 起 こ っ た 場 合 、 epoll_ctl() は −1 を 返 し 、 errno を 適 切 に 設 定 す る 。

エ ラ ー

EBADF

epfdfd が 有 効 な フ ァ イ ル デ ィ ス ク リ プ タ ー で な い 。

EEXIST

opEPOLL_CTL_ADD で あ り 、 か つ 与 え ら れ た フ ァ イ ル デ ィ ス ク リ プ タ ー fd が こ の epoll イ ン ス タ ン ス に 既 に 登 録 さ れ て い る 。

EINVAL

epfdepoll フ ァ イ ル デ ィ ス ク リ プ タ ー で な い 。 ま た は fdepfd と 同 一 で あ る 。 ま た は 要 求 さ れ た 操 作 op が こ の イ ン タ ー フ ェ ー ス で サ ポ ー ト さ れ て い な い 。

ENOENT

opEPOLL_CTL_MOD ま た は EPOLL_CTL_DEL で 、 か つ fd が こ の epoll イ ン ス タ ン ス に 登 録 さ れ て い な い 。

ENOMEM

要 求 さ れ た op 制 御 操 作 を 扱 う の に 十 分 な メ モ リ ー が な い 。
ENOSPC

epoll イ ン ス タ ン ス に 新 し い フ ァ イ ル デ ィ ス ク リ プ タ ー を 登 録 (EPOLL_CTL_ADD) し よ う と し た 際 に 、 /proc/sys/fs/epoll/max_user_watches で 決 ま る 上 限 に 達 し た 。 詳 細 は epoll(7) を 参 照 。

EPERM

対 象 フ ァ イ ル fdepoll に 対 応 し て い な い 。 こ の エ ラ ー は fd が 例 え ば 通 常 フ ァ イ ル や デ ィ レ ク ト リ を 参 照 し て い る 場 合 に も 起 こ り 得 る 。

バ ー ジ ョ ン

epoll_ctl() は カ ー ネ ル 2.6 で 追 加 さ れ た 。

準 拠

epoll_ctl() は Linux 独 自 で あ る 。 ラ イ ブ ラ リ に よ る サ ポ ー ト は glibc バ ー ジ ョ ン 2.3.2 以 降 で 提 供 さ れ て い る 。

注 意

epoll イ ン タ ー フ ェ ー ス は 、 poll(2) に 対 応 し て い る 全 て の フ ァ イ ル デ ィ ス ク リ プ タ ー に 対 応 し て い る 。

バ グ

Linux 2.6.9 よ り 前 で は 、 EPOLL_CTL_DEL 操 作 の 際 、 引 き 数 event に (た と え 無 視 さ れ る 場 合 で あ っ て も ) NULL で な い ポ イ ン タ ー を 渡 す 必 要 が あ っ た 。 カ ー ネ ル 2.6.9 以 降 で は 、 EPOLL_CTL_DEL を 使 う 際 に event に NULL を 指 定 で き る よ う に な っ て い る 。 2.6.9 よ り 前 の カ ー ネ ル へ の 移 植 性 が 必 要 な ア プ リ ケ ー シ ョ ン で は 、 event に NULL で な い ポ イ ン タ ー を 指 定 す べ き で あ る 。

flagsEPOLLWAKEUP が 指 定 さ れ た が 、 呼 び 出 し 元 が CAP_BLOCK_SUSPEND ケ ー パ ビ リ テ ィ を 持 っ て い な い 場 合 、 EPOLLWAKEUP フ ラ グ は 黙 っ て 無 視 さ れ る 。 元 の 実 装 で は flags 引 き 数 に 対 す る 正 当 性 チ ェ ッ ク が 実 行 さ れ て い な い た め 、 こ の 残 念 な 動 作 は 必 要 で あ る 。 ま た 、 呼 び 出 し 元 が CAP_BLOCK_SUSPEND ケ ー パ ビ リ テ ィ を 持 っ て い な か っ た 場 合 に 呼 び 出 し を 失 敗 さ せ る よ う に チ ェ ッ ク を EPOLLWAKEUP に 追 加 す る と 、 少 な く と も ひ と つ は 動 か な く な る 既 存 の ユ ー ザ ー 空 間 ア プ リ ケ ー シ ョ ン が あ っ た 。 そ の ア プ リ ケ ー シ ョ ン は た ま た ま (し か も 意 味 も な く ) こ の ビ ッ ト を 指 定 し て い た 。 し た が っ て 、 信 頼 性 が 求 め ら れ る ア プ リ ケ ー シ ョ ン で は 、 EPOLLWAKEUP フ ラ グ を 使 お う す る 場 合 に は CAP_BLOCK_SUSPEND ケ ー パ ビ リ テ ィ を 持 っ て い る か も 確 認 す る よ う に す べ き で あ る 。

関 連 項 目

epoll_create(2), epoll_wait(2), poll(2), epoll(7)

こ の 文 書 に つ い て

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

COMMENTS