Man page - utimensat(2)

Packages contains this manual

Available languages:

en fr ja ru

Manual

UTIMENSAT

名 前
書 式
説 明
ア ク セ ス 許 可 の 要 件
utimensat() 固 有 の 内 容
返 り 値
エ ラ ー
バ ー ジ ョ ン
属 性
準 拠
注 意
C library/kernel ABI differences
バ グ
関 連 項 目
こ の 文 書 に つ い て

名 前

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:

_POSIX_C_SOURCE >= 200809L

Before glibc 2.10:

_ATFILE_SOURCE

futimens ():

Since glibc 2.10:

_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 is NULL, or both tv_nsec values are UTIME_NOW , and the effective user ID of the caller does not match the owner of the file, the caller does not have write access to the file, and the caller is not privileged (Linux: does not have either the CAP_FOWNER or the CAP_DAC_OVERRIDE capability).

EBADF

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

EBADF

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

EFAULT

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

EINVAL

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

EINVAL

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

EINVAL

pathname が NULL で 、 dirfd が AT_FDCWD で は な く 、 flags に AT_SYMLINK_NOFOLLOW が 指 定 さ れ て い る 。

ELOOP

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

ENAMETOOLONG

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

ENOENT

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

ENOTDIR

( utimensat ()) pathname が 相 対 パ ス だ が 、 dirfd が AT_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 で 初 め て 登 場 し た 。

属 性

こ の 節 で 使 用 さ れ て い る 用 語 の 説 明 に つ い て は 、 attributes (7) を 参 照 。

Image grohtml-4716-1.png

準 拠

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

注 意

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

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

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

C library/kernel ABI differences

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

utimensat(fd, NULL, times, 0);

Note, however, that the glibc wrapper for utimensat () disallows passing NULL as the value for pathname : the wrapper function returns the error EINVAL in this case.

バ グ

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

*

POSIX.1 で は 、 tv_nsec フ ィ ー ル ド の 一 つ が UTIME_NOW か UTIME_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), touch (1), futimesat (2), openat (2), stat (2), utimes (2), futimes (3), inode (7), path_resolution (7), symlink (7)

こ の 文 書 に つ い て

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