Manpages

名 前

timerfd_create, timerfd_settime, timerfd_gettime − フ ァ イ ル デ ィ ス ク リ プ タ ー 経 由 で 通 知 す る タ イ マ ー

書 式

#include <sys/timerfd.h>

int timerfd_create(int clockid, int flags);

int timerfd_settime(int fd, int flags,
const struct itimerspec *new_value,
struct itimerspec *old_value);

int timerfd_gettime(int fd, struct itimerspec *curr_value);

説 明

こ れ ら の シ ス テ ム コ ー ル は 、 満 了 通 知 を フ ァ イ ル デ ィ ス ク リ プ タ ー 経 由 で 配 送 す る タ イ マ ー の 生 成 と 操 作 を 行 う 。 こ れ ら は 、 setitimer(2) や timer_create(2) を 用 い る 方 法 の 代 わ り と な る も の で あ り 、 こ の フ ァ イ ル デ ィ ス ク リ プ タ ー を select(2), poll(2), epoll(7) で 監 視 で き る と い う 利 点 が あ る 。 こ れ ら の シ ス テ ム コ ー ル を 使 う の は 、 そ れ ぞ れ timer_create(2), timer_settime(2), timer_gettime(2) を 使 う の と 同 様 で あ る (timer_getoverrun(2) に 対 応 す る も の は な く 、 以 下 で 説 明 す る よ う に こ の 機 能 は read(2) に よ り 提 供 さ れ る )。

timerfd_create()
timerfd_create() は 新 規 の タ イ マ ー オ ブ ジ ェ ク ト を 生 成 し 、 そ の タ イ マ ー を 参 照 す る フ ァ イ ル デ ィ ス ク リ プ タ ー を 返 す 。 clockid 引 き 数 は 、 タ イ マ ー の 進 捗 を 管 理 す る た め の ク ロ ッ ク を 指 定 す る も の で 、 CLOCK_REALTIME か CLOCK_MONOTONIC の い ず れ か で な け れ ば な ら な い 。 CLOCK_REALTIME は シ ス テ ム 全 体 で 使 用 さ れ る ク ロ ッ ク で 、 こ の ク ロ ッ ク は 変 更 可 能 で あ る 。 CLOCK_MONOTONIC は 変 更 さ れ る こ と の な い ク ロ ッ ク で 、 (シ ス テ ム 時 刻 の 手 動 で の 変 更 な ど の ) シ ス テ ム ク ロ ッ ク の 不 連 続 な 変 化 の 影 響 を 受 け な い 。 こ れ ら の ク ロ ッ ク の 現 在 の 値 は clock_gettime(2) を 使 っ て 取 得 で き る 。

Linux 2.6.27 以 降 で は 、 以 下 の 値 の い く つ か を ビ ッ ト 単 位 の 論 理 和 (OR) で 指 定 す る こ と で 、 timerfd_create() の 振 舞 い を 変 更 す る こ と が で き る 。

description) の O_NONBLOCK フ ァ イ ル ス テ ー タ ス フ ラ グ を セ ッ ト す る 。 こ の フ ラ グ を 使 う こ と で 、 O_NONBLOCK を セ ッ ト す る た め に fcntl(2) を 追 加 で 呼 び 出 す 必 要 が な く な る 。

(FD_CLOEXEC) フ ラ グ を セ ッ ト す る 。 こ の フ ラ グ が 役 に 立 つ 理 由 に つ い て は 、 open(2) の O_CLOEXEC フ ラ グ の 説 明 を 参 照 の こ と 。 バ ー ジ ョ ン 2.6.26 以 前 の Linux で は 、 flags 引 き 数 は 未 使 用 で あ り 、 0 を 指 定 し な け れ ば な ら な い 。

timerfd_settime()
timerfd_settime() は 、 フ ァ イ ル デ ィ ス ク リ プ タ ー fd に よ り 参 照 さ れ る タ イ マ ー を 開 始 し た り 停 止 し た り す る 。

new_value 引 き 数 は 、 タ イ マ ー の 満 了 時 間 (expiration) の 初 期 値 と 間 隔 (interval) を 指 定 す る 。 こ の 引 き 数 で 使 用 さ れ て い る itimerspec 構 造 体 に は 2 つ の フ ィ ー ル ド が あ り 、 各 フ ィ ー ル ド は timespec 型 の 構 造 体 で あ る 。

struct timespec {
time_t tv_sec; /* Seconds */
long tv_nsec; /* Nanoseconds */ };

struct itimerspec {
struct timespec it_interval; /* Interval for periodic timer */
struct timespec it_value; /* Initial expiration */ };

new_value.it_value は タ イ マ ー の 満 了 時 間 の 初 期 値 を 、 秒 と ナ ノ 秒 で 指 定 す る 。 new_value.it_value の フ ィ ー ル ド の う ち 少 な く と も 一 方 に 0 以 外 の 値 を 設 定 す る と 、 タ イ マ ー が 開 始 さ れ る 。 両 方 の フ ィ ー ル ド に 0 を 設 定 す る と 、 タ イ マ ー が 停 止 す る 。

new_value.it_interval は タ イ マ ー の 一 回 目 の 満 了 後 に 繰 り 返 し タ イ マ ー の 満 了 間 隔 を 、 秒 と ナ ノ 秒 で 指 定 す る 。 new_value.it_interval の フ ィ ー ル ド の う ち 少 な く と も 一 方 に 0 以 外 の 値 を 設 定 す る と 、 繰 り 返 し タ イ マ ー が 有 効 に な る 。 両 方 の フ ィ ー ル ド に 0 を 設 定 し た 場 合 、 タ イ マ ー は new_value.it_value で 指 定 さ れ た 時 間 後 に 、 一 回 だ け 満 了 し て 停 止 す る 。

flags 引 き 数 に は 0 か TFD_TIMER_ABSTIME を 指 定 す る 。 0 は 相 対 時 刻 タ イ マ ー を 意 味 し 、 new_value.it_value で は clockid で 指 定 さ れ た ク ロ ッ ク の 現 在 の 値 か ら の 相 対 的 な 時 刻 を 指 定 す る 。 TFD_TIMER_ABSTIME は 絶 対 時 刻 タ イ マ ー を 意 味 し 、 new_value.it_interval で は clockid で 指 定 さ れ た ク ロ ッ ク の 絶 対 時 刻 を 指 定 す る 。 つ ま り 、 ク ロ ッ ク の 値 が new_value.it_interval で 指 定 さ れ た 時 刻 に 達 し た ら 、 タ イ マ ー が 満 了 す る 。

old_value 引 き 数 が NULL で な い 場 合 、 old_value 引 き 数 が 指 す itimerspec 構 造 体 は 、 timerfd_settime() を 呼 び 出 し た 時 点 で の タ イ マ ー の 設 定 を 返 す の に 使 用 さ れ る 。 下 記 の timerfd_gettime() の 説 明 を 参 照 。

timerfd_gettime()
timerfd_gettime() は 、 フ ァ イ ル デ ィ ス ク リ プ タ ー fd で 参 照 さ れ る タ イ マ ー の 現 在 の 設 定 が 入 っ た itimerspec 構 造 体 を 、 curr_value に 格 納 し て 返 す 。

it_value フ ィ ー ル ド は 、 タ イ マ ー が 次 に 満 了 す る ま で の 残 り 時 間 を 返 す 。 こ の 構 造 体 の 両 方 の フ ィ ー ル ド が 0 で あ れ ば 、 タ イ マ ー は 現 在 停 止 し て い る 。 タ イ マ ー 設 定 時 に TFD_TIMER_ABSTIME フ ラ グ が 指 定 さ れ た か に 関 わ ら ず 、 こ の フ ィ ー ル ド は 常 に 相 対 値 が 格 納 さ れ る 。

it_interval フ ィ ー ル ド は 、 タ イ マ ー の 間 隔 を 返 す 。 こ の 構 造 体 の 両 方 の フ ィ ー ル ド が 0 で あ れ ば 、 タ イ マ ー は new_value.it_value で 指 定 さ れ た 時 間 後 に 一 回 だ け 満 了 し て 停 止 す る よ う に 設 定 さ れ て い る 。 タ イ マ ー フ ァ イ ル デ ィ ス ク リ プ タ ー に 対 す る 操 作
timerfd_create() が 返 す フ ァ イ ル デ ィ ス ク リ プ タ ー は 以 下 の 操 作 を サ ポ ー ト し て い る 。
read(2)

timerfd_settime() を 使 っ て タ イ マ ー の 設 定 が 最 後 変 更 さ れ て 以 降 、 ま た は read(2) の 呼 び 出 し に 最 後 に 成 功 し て 以 降 に 、 タ イ マ ー の 満 了 が 一 回 以 上 発 生 し て い れ ば 、 read(2) に 渡 さ れ た バ ッ フ ァ ー に 、 タ イ マ ー 満 了 回 数 を 示 す 8 バ イ ト の unsigned 型 の 整 数 (uint64_t) が 返 さ れ る (返 さ れ る 値 は ホ ス ト バ イ ト オ ー ダ 、 つ ま り そ の ホ ス ト マ シ ン に お け る 整 数 の 通 常 の バ イ ト オ ー ダ で あ る )。