.\" Copyright (C) 2008, Linux Foundation, written by Michael Kerrisk
.\" <mtk.manpages@gmail.com>
.\"
.\" %%%LICENSE_START(VERBATIM)
.\" Permission is granted to make and distribute verbatim copies of this
.\" manual provided the copyright notice and this permission notice are
.\" preserved on all copies.
.\"
.\" Permission is granted to copy and distribute modified versions of this
.\" manual under the conditions for verbatim copying, provided that the
.\" entire resulting derived work is distributed under the terms of a
.\" permission notice identical to this one.
.\"
.\" Since the Linux kernel and libraries are constantly changing, this
.\" manual page may be incorrect or out-of-date.  The author(s) assume no
.\" responsibility for errors or omissions, or for damages resulting from
.\" the use of the information contained herein.  The author(s) may not
.\" have taken the same level of care in the production of this manual,
.\" which is licensed free of charge, as they might when working
.\" professionally.
.\"
.\" Formatted or processed versions of this manual, if unaccompanied by
.\" the source, must acknowledge the copyright and authors of this work.
.\" %%%LICENSE_END
.\"
.\"*******************************************************************
.\"
.\" This file was generated with po4a. Translate the source file.
.\"
.\"*******************************************************************
.TH UTIMENSAT 2 2015\-01\-22 Linux "Linux Programmer's Manual"
.SH 名前
utimensat, futimens \- ファイルのタイムスタンプをナノ秒精度で変更する
.SH 書式
.nf
\fB#include <fcntl.h> /* AT_* 定数の定義 */\fP
\fB#include <sys/stat.h>\fP
.sp
\fBint utimensat(int \fP\fIdirfd\fP\fB, const char *\fP\fIpathname\fP\fB,\fP
\fB              const struct timespec \fP\fItimes\fP\fB[2], int \fP\fIflags\fP\fB);\fP

\fBint futimens(int \fP\fIfd\fP\fB, const struct timespec \fP\fItimes\fP\fB[2]);\fP
.fi
.sp
.in -4n
glibc 向けの機能検査マクロの要件 (\fBfeature_test_macros\fP(7)  参照):
.in
.ad l
.PD 0
.sp
\fButimensat\fP():
.RS 4
.TP  4
Since glibc 2.10:
_XOPEN_SOURCE\ >=\ 700 || _POSIX_C_SOURCE\ >=\ 200809L
.TP 
Before glibc 2.10:
_ATFILE_SOURCE
.RE
.PP
\fBfutimens\fP():
.RS 4
.TP 
Since glibc 2.10:
_XOPEN_SOURCE\ >=\ 700 || _POSIX_C_SOURCE\ >=\ 200809L
.TP 
Before glibc 2.10:
_GNU_SOURCE
.RE
.PD
.ad
.SH 説明
\fButimensat\fP() と \fBfutimens\fP() はファイルのタイムスタンプをナノ秒精度で更新する。
ファイルのタイムスタンプをセットする際に、 昔からある \fButime\fP(2) と \fButimes\fP(2)
で指定できるのはそれぞれ秒精度とマイクロ秒精度であり、 この点が異なる点である。

\fButimensat\fP() では、 ファイルは \fIpathname\fP で渡されるパス名で指定される。 \fBfutimens\fP() では、
タイムスタンプを更新するファイルはオープンしたファイルディスクリプター \fIfd\fP で指定される。

どちらのシステムコールでも、 ファイルの新しいタイムスタンプは配列 \fItimes\fP で指定される。 \fItimes\fP[0]
は新しい「最終アクセス時刻」 (\fIatime\fP) を指定し、 \fItimes\fP[1] は新しい「最終修正時刻」 (\fImtime\fP) を指定する。
\fItimes\fP の各要素では、 時刻を、 紀元 (Epoch; 1970\-01\-01 00:00:00 +0000 (UTC))
からの秒数とナノ秒として指定する。 この情報は以下の形式の構造体で渡す。
.in +4n
.nf

struct timespec {
    time_t tv_sec;        /* 秒 */
    long   tv_nsec;       /* ナノ秒 */
};
.fi
.in
.PP
ファイルの更新後のタイムスタンプは、 指定された時刻を超えないファイルシステムがサポートする最大の値に設定される。

.\" 2.6.22 was broken: it is not ignored
それぞれの \fItimespec\fP 構造体の \fItv_nsec\fP フィールドには \fBUTIME_NOW\fP を指定することができ、
その場合はファイルの対応するタイムスタンプは現在時刻に設定される。 \fItimespec\fP 構造体の \fItv_nsec\fP フィールドには
\fBUTIME_OMIT\fP を指定することができ、 その場合はファイルの対応するタイムスタンプは変更されないままとなる。 このどちらの場合も、 対応する
\fItv_sec\fP フィールドの値は無視される。

.\"
\fItimes\fP が NULL の場合、 両方のタイムスタンプが現在時刻に設定される。
.SS アクセス許可の要件
ファイルの両方のタイムスタンプを現在時刻に設定するためには (すなわち \fItimes\fP が NULL か、 両方の \fItv_nsec\fP フィールドに
\fBUTIME_NOW\fP が指定するためには)、 以下のいずれかが必要である。
.IP 1. 3
.\" 2.6.22 was broken here -- for futimens() the check is
.\" based on whether or not the file descriptor is writable,
.\" not on whether the caller's effective UID has write
.\" permission for the file referred to by the descriptor.
呼び出し元がファイルに対する書き込み許可を持っている。
.IP 2.
呼び出し元の実効ユーザー ID がファイルの所有者と一致している。
.IP 3.
呼び出し元が適切な特権を持っている。
.PP
.\" 2.6.22 was broken here:
.\" both must be something other than *either* UTIME_OMIT *or* UTIME_NOW.
両方のタイムスタンプを現在時刻に設定する以外の変更するには (\fItimes\fP が NULL 以外、 または
どちらの \fItv_nsec\fP フィールドも \fBUTIME_NOW\fP でなくどちらの \fItv_nsec\fP フィールドも \fBUTIME_OMIT\fP
でもない場合)、 上記の条件 2 か条件 3 が必要である。

.\"
.\"
両方の \fItv_nsec\fP フィールドに \fBUTIME_OMIT\fP が指定された場合、 ファイルの所有権やアクセス許可のチェックは行われず、
ファイルのタイムスタンプは変更されないが、 それ以外のエラー条件はこの場合も検出される。
.SS "utimensat() 固有の内容"
.\" FIXME . Say something about O_SEARCH?  (But it's not in current
.\" glibc (Mar 08), or kernel 2.6.25.)
\fIpathname\fP が相対パスの場合、 デフォルトでは、 オープンしたファイルディスクリプター \fIdirfd\fP
が参照するディレクトリに対する相対パスと解釈される (\fButimes\fP(2)
のようにカレントワーキングディレクトリに対する相対パスと解釈されるわけではない)。 なぜこのシステムコールが役に立つのかの説明は
\fBopenat\fP(2) を参照。

\fIpathname\fP が相対パスで \fIdirfd\fP が特別な値 \fBAT_FDCWD\fP の場合、 \fIpathname\fP は
(\fButimes\fP(2) 同様) 呼び出したプロセスのカレントワーキングディレクトリに対する相対パスと解釈される。

\fIpathname\fP が絶対パスの場合、 \fIdirfd\fP は無視される。

\fIflags\fP フィールドはビットマスクで、 0 か \fI<fcntl.h>\fP で定義されている以下の定数を指定できる。
.TP 
\fBAT_SYMLINK_NOFOLLOW\fP
\fIpathname\fP がシンボリックリンクの場合に、 リンクが参照するファイルではなくリンク自身のタイムスタンプを更新する。
.SH 返り値
成功すると、 \fButimensat\fP() と \fBfutimens\fP() は 0 を返す。 エラーの場合、 \-1 を返し、 \fIerrno\fP
にエラーを示す値を設定する。
.SH エラー
.TP 
\fBEACCES\fP
\fItimes\fP が NULL か両方の \fItv_nsec\fP の値が \fBUTIME_NOW\fP で、 以下のいずれかにあてはまる。
.PD 0
.RS
.IP * 2
.\" But Linux 2.6.22 was broken here.
.\" Traditionally, utime()/utimes() gives the error EACCES for the case
.\" where the timestamp pointer argument is NULL (i.e., set both timestamps
.\" to the current time), and the file is owned by a user other than the
.\" effective UID of the caller, and the file is not writable by the
.\" effective UID of the program.  utimensat() also gives this error in the
.\" same case.  However, in the same circumstances, when utimensat() is
.\" given a 'times' array in which both tv_nsec fields are UTIME_NOW, which
.\" provides equivalent functionality to specifying 'times' as NULL, the
.\" call succeeds.  It should fail with the error EACCES in this case.
.\"
.\" POSIX.1-2008 has the following:
.\" .TP
.\" .B EACCES
.\" .RB ( utimensat ())
.\" .I fd
.\" was not opened with
.\" .B O_SEARCH
.\" and the permissions of the directory to which
.\" .I fd
.\" refers do not allow searches.
呼び出し元の実効ユーザー ID がファイルの所有者と一致せず、 呼び出し元がそのファイルに対する書き込みアクセス許可を持っておらず、
呼び出し元が特権を持っていない (Linux では、ケーパビリティー \fBCAP_FOWNER\fP か \fBCAP_DAC_OVERRIDE\fP
を持っていない)。
.IP *
.\" EXT2_IMMUTABLE_FL and similar flags for other filesystems.
ファイルが immutable (変更不可) の属性が付いている (\fBchattr\fP(1) 参照)。
.RE
.PD
.TP 
\fBEBADF\fP
(\fBfutimens\fP()) \fIfd\fP が有効なファイルディスクリプターでない。
.TP 
\fBEBADF\fP
(\fButimensat\fP()) \fIpathname\fP が相対パスだが、 \fIdirfd\fP が \fBAT_FDCWD\fP
でも有効なファイルディスクリプターでもない。
.TP 
\fBEFAULT\fP
\fItimes\fP が無効なアドレスを指している。 \fIdirfd\fP が \fBAT_FDCWD\fP で \fIpathname\fP が NULL
か無効なアドレスである。
.TP 
\fBEINVAL\fP
\fIflags\fP に無効な値が指定された。
.TP 
\fBEINVAL\fP
\fItv_nsec\fP フィールドの一つが無効な値である (0 から 999,999,999 までの値の範囲外の値で、 \fBUTIME_NOW\fP でも
\fBUTIME_NOW\fP でもない)。 \fItv_sec\fP フィールドの一つが無効な値である。
.TP 
\fBEINVAL\fP
.\" SUSv4 does not specify this error.
\fIpathname\fP が NULL で、 \fIdirfd\fP が \fBAT_FDCWD\fP ではなく、 \fIflags\fP に
\fBAT_SYMLINK_NOFOLLOW\fP が指定されている。
.TP 
\fBELOOP\fP
(\fButimensat\fP()) \fIpathname\fP を解決する際に遭遇したシンボリックリンクが多すぎた。
.TP 
\fBENAMETOOLONG\fP
(\fButimensat\fP()) \fIpathname\fP が長すぎる。
.TP 
\fBENOENT\fP
(\fButimensat\fP()) \fIpathname\fP の構成要素が存在するディレクトリかファイルを参照していない。 \fIpathname\fP
が空文字列である。
.TP 
\fBENOTDIR\fP
(\fButimensat\fP()) \fIpathname\fP が相対パスだが、 \fIdirfd\fP が \fBAT_FDCWD\fP
でもディレクトリを参照するファイルディスクリプターでもない。 \fIpathname\fP の構成要素のディレクトリ部分がディレクトリではない。
.TP 
\fBEPERM\fP
呼び出し元がタイムスタンプの一方もしくは両方を現在時刻以外の値に更新しようとしたか、
もしくはタイムスタンプの一方を現在時刻に変更し、もう一方は変更しないままにしようとした (すなわち \fItimes\fP が NULL 以外で、 どちらの
\fItv_nsec\fP フィールドも \fBUTIME_NOW\fP でもなく、 どちらの \fItv_nsec\fP フィールドも \fBUTIME_OMIT\fP
でもない) 場合で、 以下のいずれかにあてはまる。
.PD 0
.RS
.IP * 2
呼び出し元の実効ユーザー ID がファイルの所有者と一致せず、 呼び出し元が特権を持っていない (Linux では、ケーパビリティー
\fBCAP_FOWNER\fP を持っていない)。
.IP *
.\" Linux 2.6.22 was broken here:
.\" it was not consistent with the old utimes() implementation,
.\" since the case when both tv_nsec fields are UTIME_NOW, was not
.\" treated like the (times == NULL) case.
.\" EXT2_IMMUTABLE_FL EXT_APPPEND_FL and similar flags for
.\" other filesystems.
.\"
.\" Why the inconsistency (which is described under NOTES) between
.\" EACCES and EPERM, where only EPERM tests for append-only.
.\" (This was also so for the older utimes() implementation.)
ファイルに追記のみか変更不可 (immutable) の属性が付いている (\fBchattr\fP(1) 参照)。
.RE
.PD
.TP 
\fBEROFS\fP
ファイルが読み込み専用のファイルシステム上にある。
.TP 
\fBESRCH\fP
(\fButimensat\fP()) \fIpathname\fP の構成要素のディレクトリ部分のいずれかで検索許可がなかった。
.SH バージョン
\fButimensat\fP() はカーネル 2.6.22 で Linux に追加された。 glibc のサポートはバージョン 2.6 で追加された。

\fBfutimens\fP() のサポートは glibc 2.6 で初めて登場した。
.SH 準拠
\fBfutimens\fP() と \fButimensat\fP() は POSIX.1\-2008 で規定されている。
.SH 注意
\fButimensat\fP() が登場した結果、 \fBfutimesat\fP(2) は非推奨となった。

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

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

    utimensat(fd, NULL, times, 0);
.fi

両方の \fItv_nsec\fP フィールドに \fBUTIME_OMIT\fP が指定された場合、 \fButimensat\fP() の Linux 実装は、
\fIdirfd\fP と \fIpathname\fP が参照するファイルが存在しない場合でも成功する。
.SH バグ
カーネル 2.6.26 より前では \fButimensat\fP() と \fBfutimens\fP() にはいくつかの悩ましいバグがあった。 これらのバグは、
ドラフト版の POSIX.1 規格との不整合や、 以前からの Linux での動作との違いである。
.IP * 2
POSIX.1 では、 \fItv_nsec\fP フィールドの一つが \fBUTIME_NOW\fP か \fBUTIME_OMIT\fP の場合、 対応する
\fItv_sec\fP フィールドは無視されると規定されている。 しかし、 \fItv_sec\fP フィールドの値を 0 にする必要があった
(さもなければエラー \fBEINVAL\fP となった)。
.IP *
.\" Below, the long description of the errors from the previous bullet
.\" point (abridged because it's too much detail for a man page).
.\" .IP *
.\" If one of the
.\" .I tv_nsec
.\" fields is
.\" .BR UTIME_OMIT
.\" and the other is
.\" .BR UTIME_NOW ,
.\" then the error
.\" .B EPERM
.\" should occur if the process's effective user ID does not match
.\" the file owner and the process is not privileged.
.\" Instead, the call successfully changes one of the timestamps.
.\" .IP *
.\" If file is not writable by the effective user ID of the process and
.\" the process's effective user ID does not match the file owner and
.\" the process is not privileged,
.\" and
.\" .I times
.\" is NULL, then the error
.\" .B EACCES
.\" results.
.\" This error should also occur if
.\" .I times
.\" points to an array of structures in which both
.\" .I tv_nsec
.\" fields are
.\" .BR UTIME_NOW .
.\" Instead the call succeeds.
.\" .IP *
.\" If a file is marked as append-only (see
.\" .BR chattr (1)),
.\" then Linux traditionally
.\" (i.e.,
.\" .BR utime (2),
.\" .BR utimes (2)),
.\" permits a NULL
.\" .I times
.\" argument to be used in order to update both timestamps to the current time.
.\" For consistency,
.\" .BR utimensat ()
.\" and
.\" .BR futimens ()
.\" should also produce the same result when given a
.\" .I times
.\" argument that points to an array of structures in which both
.\" .I tv_nsec
.\" fields are
.\" .BR UTIME_NOW .
.\" Instead, the call fails with the error
.\" .BR EPERM .
.\" .IP *
.\" If a file is marked as immutable (see
.\" .BR chattr (1)),
.\" then Linux traditionally
.\" (i.e.,
.\" .BR utime (2),
.\" .BR utimes (2)),
.\" gives an
.\" .B EACCES
.\" error if
.\" .I times
.\" is NULL.
.\" For consistency,
.\" .BR utimensat ()
.\" and
.\" .BR futimens ()
.\" should also produce the same result when given a
.\" .I times
.\" that points to an array of structures in which both
.\" .I tv_nsec
.\" fields are
.\" .BR UTIME_NOW .
.\" Instead, the call fails with the error
.\" .BR EPERM .
いくつかのバグのため、 アクセス許可のチェックにおいて、両方の \fItv_nsec\fP フィールドが \fBUTIME_NOW\fP に設定された場合が、 常に
\fItimes\fP に NULL が設定された場合と同じに扱われるわけではなく、 \fItv_nsec\fP の一つが \fBUTIME_NOW\fP でもう一方が
\fBUTIME_OMIT\fP の場合が、 \fItimes\fP に任意の値が入った構造体の配列へのポインターが指定された場合と
同じように扱われるわけではない。 その結果、いくつかの場合では、 a) ファイルのタイムスタンプが、
更新を実行する許可を持たないプロセスによって更新されることがある、 b) ファイルのタンプスタンプが、
更新を実行する許可を持つプロセスによって更新できないことがある、 c) エラーの場合に間違った \fIerrno\fP 値が返る。
.IP *
.\" This means that a process with a file descriptor that allows
.\" writing could change the timestamps of a file for which it
.\" does not have write permission;
.\" conversely, a process with a read-only file descriptor won't
.\" be able to update the timestamps of a file,
.\" even if it has write permission on the file.
POSIX.1 では、 \fIファイルの書き込み許可を持つ\fPプロセス (a process that has \fIwrite access to the
file\fP) は、そのファイルに対して \fItimes\fP に NULL や 両方の \fItv_nsec\fP フィールドが \fBUTIME_NOW\fP
の構造体の配列を指定して呼び出しを行い、 両方のタイムスタンプを現在時刻に更新することができると規定されている。 しかし、 \fBfutimens\fP()
では、 \fIファイルディスクリプターのアクセス許可が書き込みを許可しているか\fP (\fIaccess mode of the file
descriptor allows writing\fP)のチェックが行われる。
.SH 関連項目
\fBchattr\fP(1), \fBfutimesat\fP(2), \fBopenat\fP(2), \fBstat\fP(2), \fButimes\fP(2),
\fBfutimes\fP(3), \fBpath_resolution\fP(7), \fBsymlink\fP(7)
.SH この文書について
この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 3.79 の一部
である。プロジェクトの説明とバグ報告に関する情報は
http://www.kernel.org/doc/man\-pages/ に書かれている。