futimes(2)

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

標準 C ライブラリ (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() はリンクが参照するファイル の時刻を変更します。

成功して終了したときには値 0 を返します。そうでない場合、値 -1 が返され、 グローバル変数 errno が設定されてエラーを示します。

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

指定されたパスには、検索が許可されていないディレクトリ が含まれています。あるいは 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]
そのファイルを含むファイルシステムが読取り専用でマウン トされています。

関連項目

stat(2), utime(3)

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

FreeBSD 10.0 June 4, 1993 FreeBSD 10.0