EN JA
UTIMES(2)
UTIMES(2) FreeBSD System Calls Manual UTIMES(2)

名称

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

ライブラリ

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);

int
futimesat( int fd, const char *path, const struct timeval times[2]);

解説

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

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

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

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

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

futimesat() システムコールは、 path が相対パスを指定する場合を除いて、 utimes() と同等です。この場合、アクセス時刻と更新時刻は、カレントワーキングディレクトリの代わりにファイル記述子 fd に関連しているディレクトリに相対的なファイルのものに設定されます。 futimesat() が、 fd パラメータの特別な値 AT_FDCWD を渡されるなら、カレントワーキングディレクトリが、使用され、振る舞いは、 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 が、ファイルの所有者と一致せず、しかもスーパユーザではありません。
[ EPERM]
指定されたファイルには、不変、または、追加専用フラグが設定されています、詳細については、 chflags(2) マニュアルページを参照してください。
[ EROFS]
そのファイルを含むファイルシステムが、読み込み専用でマウントされています。

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

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

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

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

utimes() によって返されたエラーに加えて futimesat() は、次の場合に失敗します:

[ EBADF]
path 引数が、絶対パスを指定していません、そして fd 引数は、 AT_FDCWD でもなく検索のためにオープンされた有効なファイル記述子でもありません。
[ ENOTDIR]
path 引数が、絶対パスではありません、そして fd が、 AT_FDCWD でもなくディレクトリに関連しているファイル記述子でもありません。

関連項目

chflags(2), stat(2), utime(3)

規格

utimes() 関数は、 X/Open Portability Guide Issue 4, Version 2 (“XPG4.2”) に適合するはずです。 futimesat() システムコールは、The Open Group Extended API Set 2 仕様に適合しています。

歴史

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