Manpages

名 前

utimensat, futimens − フ ァ イ ル の タ イ ム ス タ ン プ を ナ ノ 秒 精 度 で 変 更 す る

書 式

#include <fcntl.h> /* AT_* 定 数 の 定 義 */
#include <sys/stat.h>

int utimensat(int dirfd, const char *pathname,
const struct timespec
times[2], int flags);

int futimens(int fd, const struct timespec times[2]);

glibc 向 け の 機 能 検 査 マ ク ロ の 要 件 (feature_test_macros(7) 参 照 ):

utimensat():

Since glibc 2.10:

_XOPEN_SOURCE >= 700 || _POSIX_C_SOURCE >= 200809L

Before glibc 2.10:

_ATFILE_SOURCE

futimens():

Since glibc 2.10:

_XOPEN_SOURCE >= 700 || _POSIX_C_SOURCE >= 200809L

Before glibc 2.10:

_GNU_SOURCE

説 明

utimensat() と futimens() は フ ァ イ ル の タ イ ム ス タ ン プ を ナ ノ 秒 精 度 で 更 新 す る 。 フ ァ イ ル の タ イ ム ス タ ン プ を セ ッ ト す る 際 に 、 昔 か ら あ る utime(2)utimes(2) で 指 定 で き る の は そ れ ぞ れ 秒 精 度 と マ イ ク ロ 秒 精 度 で あ り 、 こ の 点 が 異 な る 点 で あ る 。

utimensat() で は 、 フ ァ イ ル は pathname で 渡 さ れ る パ ス 名 で 指 定 さ れ る 。 futimens() で は 、 タ イ ム ス タ ン プ を 更 新 す る フ ァ イ ル は オ ー プ ン し た フ ァ イ ル デ ィ ス ク リ プ タ ー fd で 指 定 さ れ る 。 ど ち ら の シ ス テ ム コ ー ル で も 、 フ ァ イ ル の 新 し い タ イ ム ス タ ン プ は 配 列 times で 指 定 さ れ る 。 times[0] は 新 し い 「 最 終 ア ク セ ス 時 刻 」 (atime) を 指 定 し 、 times[1] は 新 し い 「 最 終 修 正 時 刻 」 (mtime) を 指 定 す る 。 times の 各 要 素 で は 、 時 刻 を 、 紀 元 (Epoch; 1970−01−01 00:00:00 +0000 (UTC)) か ら の 秒 数 と ナ ノ 秒 と し て 指 定 す る 。 こ の 情 報 は 以 下 の 形 式 の 構 造 体 で 渡 す 。

struct timespec {
time_t tv_sec; /* 秒 */
long tv_nsec; /* ナ ノ 秒 */ }; フ ァ イ ル の 更 新 後 の タ イ ム ス タ ン プ は 、 指 定 さ れ た 時 刻 を 超 え な い フ ァ イ ル シ ス テ ム が サ ポ ー ト す る 最 大 の 値 に 設 定 さ れ る 。 そ れ ぞ れ の timespec 構 造 体 の tv_nsec フ ィ ー ル ド に は UTIME_NOW を 指 定 す る こ と が で き 、 そ の 場 合 は フ ァ イ ル の 対 応 す る タ イ ム ス タ ン プ は 現 在 時 刻 に 設 定 さ れ る 。 timespec 構 造 体 の tv_nsec フ ィ ー ル ド に は UTIME_OMIT を 指 定 す る こ と が で き 、 そ の 場 合 は フ ァ イ ル の 対 応 す る タ イ ム ス タ ン プ は 変 更 さ れ な い ま ま と な る 。 こ の ど ち ら の 場 合 も 、 対 応 す る tv_sec フ ィ ー ル ド の 値 は 無 視 さ れ る 。

times が NULL の 場 合 、 両 方 の タ イ ム ス タ ン プ が 現 在 時 刻 に 設 定 さ れ る 。 ア ク セ ス 許 可 の 要 件 フ ァ イ ル の 両 方 の タ イ ム ス タ ン プ を 現 在 時 刻 に 設 定 す る た め に は (す な わ ち times が NULL か 、 両 方 の tv_nsec フ ィ ー ル ド に UTIME_NOW が 指 定 す る た め に は )、 以 下 の い ず れ か が 必 要 で あ る 。

1. 呼 び 出 し 元 が フ ァ イ ル に 対 す る 書 き 込 み 許 可 を 持 っ て い る 。

2. 呼 び 出 し 元 の 実 効 ユ ー ザ ー

ID が フ ァ イ ル の 所 有 者 と 一 致 し て い る 。

3. 呼 び 出 し 元 が 適 切 な 特 権 を 持 っ て い る 。 両 方 の タ イ ム ス タ ン プ を 現 在 時 刻 に 設 定 す る 以 外 の 変 更 す る に は

(times

NULL 以 外 、 ま た は ど ち ら の tv_nsec フ ィ ー ル ド も UTIME_NOW で な く ど ち ら の tv_nsec フ ィ ー ル ド も UTIME_OMIT で も な い 場 合 )、 上 記 の 条 件 2 か 条 件 3 が 必 要 で あ る 。 両 方 の tv_nsec フ ィ ー ル ド に UTIME_OMIT が 指 定 さ れ た 場 合 、 フ ァ イ ル の 所 有 権 や ア ク セ ス 許 可 の チ ェ ッ ク は 行 わ れ ず 、 フ ァ イ ル の タ イ ム ス タ ン プ は 変 更 さ れ な い が 、 そ れ 以 外 の エ ラ ー 条 件 は こ の 場 合 も 検 出 さ れ る 。

utimensat() 固 有 の 内 容
pathname
が 相 対 パ ス の 場 合 、 デ フ ォ ル ト で は 、 オ ー プ ン し た フ ァ イ ル デ ィ ス ク リ プ タ ー dirfd が 参 照 す る デ ィ レ ク ト リ に 対 す る 相 対 パ ス と 解 釈 さ れ る (utimes(2) の よ う に カ レ ン ト ワ ー キ ン グ デ ィ レ ク ト リ に 対 す る 相 対 パ ス と 解 釈 さ れ る わ け で は な い )。 な ぜ こ の シ ス テ ム コ ー ル が 役 に 立 つ の か の 説 明 は openat(2) を 参 照 。

pathname が 相 対 パ ス で dirfd が 特 別 な 値 AT_FDCWD の 場 合 、 pathname は (utimes(2) 同 様 ) 呼 び 出 し た プ ロ セ ス の カ レ ン ト ワ ー キ ン グ デ ィ レ ク ト リ に 対 す る 相 対 パ ス と 解 釈 さ れ る 。

pathname が 絶 対 パ ス の 場 合 、 dirfd は 無 視 さ れ る 。

flags フ ィ ー ル ド は ビ ッ ト マ ス ク で 、 0 か <fcntl.h> で 定 義 さ れ て い る 以 下 の 定 数 を 指 定 で き る 。
AT_SYMLINK_NOFOLLOW

pathname が シ ン ボ リ ッ ク リ ン ク の 場 合 に 、 リ ン ク が 参 照 す る フ ァ イ ル で は な く リ ン ク 自 身 の タ イ ム ス タ ン プ を 更 新 す る 。

返 り 値

成 功 す る と 、 utimensat() と futimens() は 0 を 返 す 。 エ ラ ー の 場 合 、 −1 を 返 し 、 errno に エ ラ ー を 示 す 値 を 設 定 す る 。

エ ラ ー

EACCES

times が NULL か 両 方 の tv_nsec の 値 が UTIME_NOW で 、 以 下 の い ず れ か に あ て は ま る 。

* 呼 び 出 し 元 の 実 効 ユ ー ザ ー

ID が フ ァ イ ル の 所 有 者 と 一 致 せ ず 、 呼 び 出 し 元 が そ の フ ァ イ ル に 対 す る 書 き 込 み ア ク セ ス 許 可 を 持 っ て お ら ず 、 呼 び 出 し 元 が 特 権 を 持 っ て い な い (Linux で は 、 ケ ー パ ビ リ テ ィ ー CAP_FOWNERCAP_DAC_OVERRIDE を 持 っ て い な い )。

*

フ ァ イ ル が immutable (変 更 不 可 ) の 属 性 が 付 い て い る (chattr(1) 参 照 )。

EBADF

(futimens()) fd が 有 効 な フ ァ イ ル デ ィ ス ク リ プ タ ー で な い 。

EBADF

(utimensat()) pathname が 相 対 パ ス だ が 、 dirfdAT_FDCWD で も 有 効 な フ ァ イ ル デ ィ ス ク リ プ タ ー で も な い 。

EFAULT

times が 無 効 な ア ド レ ス を 指 し て い る 。 dirfdAT_FDCWDpathname が NULL か 無 効 な ア ド レ ス で あ る 。

EINVAL

flags に 無 効 な 値 が 指 定 さ れ た 。

EINVAL

tv_nsec フ ィ ー ル ド の 一 つ が 無 効 な 値 で あ る (0 か ら 999,999,999 ま で の 値 の 範 囲 外 の 値 で 、 UTIME_NOW で も UTIME_NOW で も な い )。 tv_sec フ ィ ー ル ド の 一 つ が 無 効 な 値 で あ る 。

EINVAL

pathname が NULL で 、 dirfdAT_FDCWD で は な く 、 flagsAT_SYMLINK_NOFOLLOW が 指 定 さ れ て い る 。

ELOOP

(utimensat()) pathname を 解 決 す る 際 に 遭 遇 し た シ ン ボ リ ッ ク リ ン ク が 多 す ぎ た 。

ENAMETOOLONG

(utimensat()) pathname が 長 す ぎ る 。

ENOENT

(utimensat()) pathname の 構 成 要 素 が 存 在 す る デ ィ レ ク ト リ か フ ァ イ ル を 参 照 し て い な い 。 pathname が 空 文 字 列 で あ る 。

ENOTDIR

(utimensat()) pathname が 相 対 パ ス だ が 、 dirfdAT_FDCWD で も デ ィ レ ク ト リ を 参 照 す る フ ァ イ ル デ ィ ス ク リ プ タ ー で も な い 。 pathname の 構 成 要 素 の デ ィ レ ク ト リ 部 分 が デ ィ レ ク ト リ で は な い 。

EPERM 呼 び 出 し 元 が タ イ ム ス タ ン プ の 一 方 も し く は 両 方 を 現 在 時 刻 以 外 の 値 に 更 新 し よ う と し た か 、 も し く は タ イ ム ス タ ン プ の 一 方 を 現 在 時 刻 に 変 更 し 、 も う 一 方 は 変 更 し な い ま ま に し よ う と し た

(す な わ ち times が NULL 以 外 で 、 ど ち ら の tv_nsec フ ィ ー ル ド も UTIME_NOW で も な く 、 ど ち ら の tv_nsec フ ィ ー ル ド も UTIME_OMIT で も な い ) 場 合 で 、 以 下 の い ず れ か に あ て は ま る 。

* 呼 び 出 し 元 の 実 効 ユ ー ザ ー

ID が フ ァ イ ル の 所 有 者 と 一 致 せ ず 、 呼

び 出 し 元 が 特 権 を 持 っ て い な い (Linux で は 、 ケ ー パ ビ リ テ ィ ー CAP_FOWNER を 持 っ て い な い )。

* フ ァ イ ル に 追 記 の み か 変 更 不 可

(immutable) の 属 性 が 付 い て い る

(chattr(1) 参 照 )。

EROFS フ ァ イ ル が 読 み 込 み 専 用 の フ ァ イ ル シ ス テ ム 上 に あ る 。

ESRCH

(utimensat()) pathname の 構 成 要 素 の デ ィ レ ク ト リ 部 分 の い ず れ か で 検 索 許 可 が な か っ た 。

バ ー ジ ョ ン

utimensat() は カ ー ネ ル 2.6.22 で Linux に 追 加 さ れ た 。 glibc の サ ポ ー ト は バ ー ジ ョ ン 2.6 で 追 加 さ れ た 。

futimens() の サ ポ ー ト は glibc 2.6 で 初 め て 登 場 し た 。

準 拠

futimens() と utimensat() は POSIX.1−2008 で 規 定 さ れ て い る 。

注 意

utimensat() が 登 場 し た 結 果 、 futimesat(2) は 非 推 奨 と な っ た 。

Linux で は 、 変 更 不 可 (immutable) の 属 性 が 付 い た フ ァ イ ル の タ イ ム ス タ ン プ を 変 更 す る こ と は で き ず 、 ま た 、 追 記 の み (append−only) の 属 性 が 付 い た フ ァ イ ル で 可 能 な 変 更 は 、 タ イ ム ス タ ン プ を 現 在 時 刻 に 設 定 す る こ と だ け で あ る 。 (こ れ は Linux の utime(2)utimes() の 昔 か ら の 動 作 と 一 貫 性 が あ る 動 作 で あ る )。

Linux で は 、 futimens() は utimensat() シ ス テ ム コ ー ル を 使 っ て 実 装 さ れ て い る ラ イ ブ ラ リ 関 数 で あ る 。 こ れ を 可 能 に す る た め 、 Linux の utimensat() シ ス テ ム コ ー ル は 非 標 準 の 機 能 を 実 装 し て い る 。 pathname が NULL の 場 合 、 呼 び 出 し は フ ァ イ ル デ ィ ス ク リ プ タ ー dirfd が 参 照 す る フ ァ イ ル の タ イ ム ス タ ン プ を 変 更 す る (フ ァ イ ル デ ィ ス ク リ プ タ ー は ど の タ イ プ の フ ァ イ ル を 参 照 し て い て も よ い )。 こ の 機 能 を 利 用 し て 、 futimens(fd, times) は 以 下 の よ う に 実 装 さ れ て い る 。

utimensat(fd, NULL, times, 0); 両 方 の tv_nsec フ ィ ー ル ド に UTIME_OMIT が 指 定 さ れ た 場 合 、 utimensat() の Linux 実 装 は 、 dirfdpathname が 参 照 す る フ ァ イ ル が 存 在 し な い 場 合 で も 成 功 す る 。

バ グ

カ ー ネ ル 2.6.26 よ り 前 で は utimensat() と futimens() に は い く つ か の 悩 ま し い バ グ が あ っ た 。 こ れ ら の バ グ は 、 ド ラ フ ト 版 の POSIX.1 規 格 と の 不 整 合 や 、 以 前 か ら の Linux で の 動 作 と の 違 い で あ る 。

*

POSIX.1 で は 、 tv_nsec フ ィ ー ル ド の 一 つ が UTIME_NOWUTIME_OMIT の 場 合 、 対 応 す る tv_sec フ ィ ー ル ド は 無 視 さ れ る と 規 定 さ れ て い る 。 し か し 、 tv_sec フ ィ ー ル ド の 値 を 0 に す る 必 要 が あ っ た (さ も な け れ ば エ ラ ー EINVAL と な っ た )。

*

い く つ か の バ グ の た め 、 ア ク セ ス 許 可 の チ ェ ッ ク に お い て 、 両 方 の tv_nsec フ ィ ー ル ド が UTIME_NOW に 設 定 さ れ た 場 合 が 、 常 に times に NULL が 設 定 さ れ た 場 合 と 同 じ に 扱 わ れ る わ け で は な く 、 tv_nsec の 一 つ が UTIME_NOW で も う 一 方 が UTIME_OMIT の 場 合 が 、 times に 任 意 の 値 が 入 っ た 構 造 体 の 配 列 へ の ポ イ ン タ ー が 指 定 さ れ た 場 合 と 同 じ よ う に 扱 わ れ る わ け で は な い 。 そ の 結 果 、 い く つ か の 場 合 で は 、 a) フ ァ イ ル の タ イ ム ス タ ン プ が 、 更 新 を 実 行 す る 許 可 を 持 た な い プ ロ セ ス に よ っ て 更 新 さ れ る こ と が あ る 、 b) フ ァ イ ル の タ ン プ ス タ ン プ が 、 更 新 を 実 行 す る 許 可 を 持 つ プ ロ セ ス に よ っ て 更 新 で き な い こ と が あ る 、 c) エ ラ ー の 場 合 に 間 違 っ た errno 値 が 返 る 。
*

POSIX.1 で は 、 フ ァ イ ル の 書 き 込 み 許 可 を 持 つ プ ロ セ ス (a process that has write access to the file) は 、 そ の フ ァ イ ル に 対 し て times に NULL や 両 方 の tv_nsec フ ィ ー ル ド が UTIME_NOW の 構 造 体 の 配 列 を 指 定 し て 呼 び 出 し を 行 い 、 両 方 の タ イ ム ス タ ン プ を 現 在 時 刻 に 更 新 す る こ と が で き る と 規 定 さ れ て い る 。 し か し 、 futimens() で は 、 フ ァ イ ル デ ィ ス ク リ プ タ ー の ア ク セ ス 許 可 が 書 き 込 み を 許 可 し て い る か (access mode of the file descriptor allows writing)の チ ェ ッ ク が 行 わ れ る 。

関 連 項 目

chattr(1), futimesat(2), openat(2), stat(2), utimes(2), futimes(3), path_resolution(7), symlink(7)

こ の 文 書 に つ い て

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

COMMENTS