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 が 指 定 す る た め に は )、 以 下 の い ず れ か が 必 要 で あ る 。

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

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 に エ ラ ー を 示 す 値 を 設 定 す る 。

エ ラ ー