manページ  — UTIMES

utimes, lutimes, futimes – ファイルアクセス時刻と更新時刻の設定

ライブラリ 書式 解説 戻り値 エラー 関連項目 歴史

Standard C Library (libc, -lc)

#include <sys/time.h>

int
utimes(const char *path, const struct timeval *times);

int
lutimes(const char *path, const struct timeval *times);

int
futimes(int fd, const struct timeval *times);

path で指定したファイルか fd が参照するファイルのアクセス時刻と更新時刻を、引数 times で指定されたように変更します。

times が NULL である場合、アクセス時刻と更新時刻は現在の時刻に設定されます。 呼び出し側はファイルの所有者でファイルの書込み権があるか、 スーパユーザである必要があります。

times が NULL 以外である場合、 times は 2 つの timeval 構造体の配列を指していることが前提となります。 アクセス時刻は最初の要素に、更新時刻は次の要素に 設定します。 ( UFS2 のように) ファイルの誕生 (生成) 時刻をサポートしている ファイルシステムでは、2 番目の要素が現在設定されている誕生時刻よりも 前であれば、誕生時刻は 2 番目の要素の値で設定されます。 誕生時刻と更新時刻の両方を設定する場合は、2 回の呼び出しが必要です。 最初に誕生時刻を設定し、次に (より新しいであろう) 更新時刻を設定します。 理想的には、一度に 3 つの時刻すべてを設定できるシステムコールが 追加されるでしょう。 呼び出し側はファイルの所有者であるかスーパユーザである必要があります。

どちらの場合でも、ファイルの inode 変更時刻は現在の時刻に設定されます。

lutimes() システムコールは指定したファイルがシンボリックリンク以外では utimes() と同じです。 シンボリックリンクの場合 lutimes() はリンクのアクセス時刻と更新時刻を変更するのに対し、 utimes() はリンクが参照するファイルの時刻を変更します。

Upon successful completion, the value 0 is returned; otherwise the value -1 is returned and the global variable errno is set to indicate the error.

utimes() システムコールと lutimes() システムコールは、以下のような場合にエラーとなります:

[EACCES]
	指定されたパスには、検索が許可されていないディレクトリが含まれています。 あるいは times 引数が NULL で、プロセスの実効ユーザ ID がファイルの所有者と一致せず、 しかもスーパユーザでもなく、書込みアクセスが拒否されました。
[EFAULT]
	path 引数または times 引数は、プロセスに割り当てられたアドレス空間の範囲外を指しています。
[EIO]	変更される inode の読み書きの間に入出力エラーが発生しました。
[ELOOP]
	パス名を変換するときに検出されたシンボリックリンクが多すぎます。
[ENAMETOOLONG]
	パス名の構成要素が NAME_MAX 文字を越えているか、またはパス名全体 PATH_MAX 文字を越えています。
[ENOENT]
	指定したファイルが存在しません。
[ENOTDIR]
	パスの構成要素中にディレクトリ以外のものが含まれています。
[EPERM]
	times 引数が NULL ではなく、呼び出し側プロセスの実効ユーザ ID が、 ファイルの所有者と一致せず、しかもスーパユーザではありません。
[EROFS]
	そのファイルを含むファイルシステムが、 読取り専用でマウントされています。

futimes() システムコールは、以下の場合にエラーとなります:

[EBADF]
	fd 引数が、有効な記述子を参照していません。

すべてのシステムコールは、以下の場合にエラーとなります。

[EACCES]
	times 引数が NULL であり、プロセスの実効ユーザ ID がファイルの所有者と一致せず、 しかもスーパユーザでもなく、書込みアクセスが拒否されました。
[EFAULT]
	times 引数は、プロセスに割り当てられたアドレス空間の範囲外を指しています。
[EIO]	変更される inode の読み書き中に入出力エラーが発生しました。
[EPERM]
	times 引数が NULL ではなく、呼び出し側プロセスの実効ユーザ ID が、 ファイルの所有者と一致せず、しかもスーパユーザでもありません。
[EROFS]
	そのファイルを含むファイルシステムが読取り専用でマウントされています。

utimes() システムコールは BSD 4.2 で登場しました。 futimes() システムコールと lutimes() システムコールは FreeBSD 3.0 ではじめて登場しました。