1 .\" Copyright (C) 2008, Linux Foundation, written by Michael Kerrisk
2 .\" <mtk.manpages@gmail.com>
4 .\" %%%LICENSE_START(VERBATIM)
5 .\" Permission is granted to make and distribute verbatim copies of this
6 .\" manual provided the copyright notice and this permission notice are
7 .\" preserved on all copies.
9 .\" Permission is granted to copy and distribute modified versions of this
10 .\" manual under the conditions for verbatim copying, provided that the
11 .\" entire resulting derived work is distributed under the terms of a
12 .\" permission notice identical to this one.
14 .\" Since the Linux kernel and libraries are constantly changing, this
15 .\" manual page may be incorrect or out-of-date. The author(s) assume no
16 .\" responsibility for errors or omissions, or for damages resulting from
17 .\" the use of the information contained herein. The author(s) may not
18 .\" have taken the same level of care in the production of this manual,
19 .\" which is licensed free of charge, as they might when working
22 .\" Formatted or processed versions of this manual, if unaccompanied by
23 .\" the source, must acknowledge the copyright and authors of this work.
26 .\"*******************************************************************
28 .\" This file was generated with po4a. Translate the source file.
30 .\"*******************************************************************
31 .TH UTIMENSAT 2 2015\-01\-22 Linux "Linux Programmer's Manual"
33 utimensat, futimens \- ファイルのタイムスタンプをナノ秒精度で変更する
36 \fB#include <fcntl.h> /* AT_* 定数の定義 */\fP
37 \fB#include <sys/stat.h>\fP
39 \fBint utimensat(int \fP\fIdirfd\fP\fB, const char *\fP\fIpathname\fP\fB,\fP
40 \fB const struct timespec \fP\fItimes\fP\fB[2], int \fP\fIflags\fP\fB);\fP
42 \fBint futimens(int \fP\fIfd\fP\fB, const struct timespec \fP\fItimes\fP\fB[2]);\fP
46 glibc 向けの機能検査マクロの要件 (\fBfeature_test_macros\fP(7) 参照):
55 _XOPEN_SOURCE\ >=\ 700 || _POSIX_C_SOURCE\ >=\ 200809L
65 _XOPEN_SOURCE\ >=\ 700 || _POSIX_C_SOURCE\ >=\ 200809L
73 \fButimensat\fP() と \fBfutimens\fP() はファイルのタイムスタンプをナノ秒精度で更新する。
74 ファイルのタイムスタンプをセットする際に、 昔からある \fButime\fP(2) と \fButimes\fP(2)
75 で指定できるのはそれぞれ秒精度とマイクロ秒精度であり、 この点が異なる点である。
77 \fButimensat\fP() では、 ファイルは \fIpathname\fP で渡されるパス名で指定される。 \fBfutimens\fP() では、
78 タイムスタンプを更新するファイルはオープンしたファイルディスクリプター \fIfd\fP で指定される。
80 どちらのシステムコールでも、 ファイルの新しいタイムスタンプは配列 \fItimes\fP で指定される。 \fItimes\fP[0]
81 は新しい「最終アクセス時刻」 (\fIatime\fP) を指定し、 \fItimes\fP[1] は新しい「最終修正時刻」 (\fImtime\fP) を指定する。
82 \fItimes\fP の各要素では、 時刻を、 紀元 (Epoch; 1970\-01\-01 00:00:00 +0000 (UTC))
83 からの秒数とナノ秒として指定する。 この情報は以下の形式の構造体で渡す。
88 time_t tv_sec; /* 秒 */
89 long tv_nsec; /* ナノ秒 */
94 ファイルの更新後のタイムスタンプは、 指定された時刻を超えないファイルシステムがサポートする最大の値に設定される。
96 .\" 2.6.22 was broken: it is not ignored
97 それぞれの \fItimespec\fP 構造体の \fItv_nsec\fP フィールドには \fBUTIME_NOW\fP を指定することができ、
98 その場合はファイルの対応するタイムスタンプは現在時刻に設定される。 \fItimespec\fP 構造体の \fItv_nsec\fP フィールドには
99 \fBUTIME_OMIT\fP を指定することができ、 その場合はファイルの対応するタイムスタンプは変更されないままとなる。 このどちらの場合も、 対応する
100 \fItv_sec\fP フィールドの値は無視される。
103 \fItimes\fP が NULL の場合、 両方のタイムスタンプが現在時刻に設定される。
105 ファイルの両方のタイムスタンプを現在時刻に設定するためには (すなわち \fItimes\fP が NULL か、 両方の \fItv_nsec\fP フィールドに
106 \fBUTIME_NOW\fP が指定するためには)、 以下のいずれかが必要である。
108 .\" 2.6.22 was broken here -- for futimens() the check is
109 .\" based on whether or not the file descriptor is writable,
110 .\" not on whether the caller's effective UID has write
111 .\" permission for the file referred to by the descriptor.
112 呼び出し元がファイルに対する書き込み許可を持っている。
114 呼び出し元の実効ユーザー ID がファイルの所有者と一致している。
118 .\" 2.6.22 was broken here:
119 .\" both must be something other than *either* UTIME_OMIT *or* UTIME_NOW.
120 両方のタイムスタンプを現在時刻に設定する以外の変更するには (\fItimes\fP が NULL 以外、 または
121 どちらの \fItv_nsec\fP フィールドも \fBUTIME_NOW\fP でなくどちらの \fItv_nsec\fP フィールドも \fBUTIME_OMIT\fP
122 でもない場合)、 上記の条件 2 か条件 3 が必要である。
126 両方の \fItv_nsec\fP フィールドに \fBUTIME_OMIT\fP が指定された場合、 ファイルの所有権やアクセス許可のチェックは行われず、
127 ファイルのタイムスタンプは変更されないが、 それ以外のエラー条件はこの場合も検出される。
128 .SS "utimensat() 固有の内容"
129 .\" FIXME . Say something about O_SEARCH? (But it's not in current
130 .\" glibc (Mar 08), or kernel 2.6.25.)
131 \fIpathname\fP が相対パスの場合、 デフォルトでは、 オープンしたファイルディスクリプター \fIdirfd\fP
132 が参照するディレクトリに対する相対パスと解釈される (\fButimes\fP(2)
133 のようにカレントワーキングディレクトリに対する相対パスと解釈されるわけではない)。 なぜこのシステムコールが役に立つのかの説明は
136 \fIpathname\fP が相対パスで \fIdirfd\fP が特別な値 \fBAT_FDCWD\fP の場合、 \fIpathname\fP は
137 (\fButimes\fP(2) 同様) 呼び出したプロセスのカレントワーキングディレクトリに対する相対パスと解釈される。
139 \fIpathname\fP が絶対パスの場合、 \fIdirfd\fP は無視される。
141 \fIflags\fP フィールドはビットマスクで、 0 か \fI<fcntl.h>\fP で定義されている以下の定数を指定できる。
143 \fBAT_SYMLINK_NOFOLLOW\fP
144 \fIpathname\fP がシンボリックリンクの場合に、 リンクが参照するファイルではなくリンク自身のタイムスタンプを更新する。
146 成功すると、 \fButimensat\fP() と \fBfutimens\fP() は 0 を返す。 エラーの場合、 \-1 を返し、 \fIerrno\fP
151 \fItimes\fP が NULL か両方の \fItv_nsec\fP の値が \fBUTIME_NOW\fP で、 以下のいずれかにあてはまる。
155 .\" But Linux 2.6.22 was broken here.
156 .\" Traditionally, utime()/utimes() gives the error EACCES for the case
157 .\" where the timestamp pointer argument is NULL (i.e., set both timestamps
158 .\" to the current time), and the file is owned by a user other than the
159 .\" effective UID of the caller, and the file is not writable by the
160 .\" effective UID of the program. utimensat() also gives this error in the
161 .\" same case. However, in the same circumstances, when utimensat() is
162 .\" given a 'times' array in which both tv_nsec fields are UTIME_NOW, which
163 .\" provides equivalent functionality to specifying 'times' as NULL, the
164 .\" call succeeds. It should fail with the error EACCES in this case.
166 .\" POSIX.1-2008 has the following:
169 .\" .RB ( utimensat ())
171 .\" was not opened with
173 .\" and the permissions of the directory to which
175 .\" refers do not allow searches.
176 呼び出し元の実効ユーザー ID がファイルの所有者と一致せず、 呼び出し元がそのファイルに対する書き込みアクセス許可を持っておらず、
177 呼び出し元が特権を持っていない (Linux では、ケーパビリティー \fBCAP_FOWNER\fP か \fBCAP_DAC_OVERRIDE\fP
180 .\" EXT2_IMMUTABLE_FL and similar flags for other filesystems.
181 ファイルが immutable (変更不可) の属性が付いている (\fBchattr\fP(1) 参照)。
186 (\fBfutimens\fP()) \fIfd\fP が有効なファイルディスクリプターでない。
189 (\fButimensat\fP()) \fIpathname\fP が相対パスだが、 \fIdirfd\fP が \fBAT_FDCWD\fP
190 でも有効なファイルディスクリプターでもない。
193 \fItimes\fP が無効なアドレスを指している。 \fIdirfd\fP が \fBAT_FDCWD\fP で \fIpathname\fP が NULL
197 \fIflags\fP に無効な値が指定された。
200 \fItv_nsec\fP フィールドの一つが無効な値である (0 から 999,999,999 までの値の範囲外の値で、 \fBUTIME_NOW\fP でも
201 \fBUTIME_NOW\fP でもない)。 \fItv_sec\fP フィールドの一つが無効な値である。
204 .\" SUSv4 does not specify this error.
205 \fIpathname\fP が NULL で、 \fIdirfd\fP が \fBAT_FDCWD\fP ではなく、 \fIflags\fP に
206 \fBAT_SYMLINK_NOFOLLOW\fP が指定されている。
209 (\fButimensat\fP()) \fIpathname\fP を解決する際に遭遇したシンボリックリンクが多すぎた。
212 (\fButimensat\fP()) \fIpathname\fP が長すぎる。
215 (\fButimensat\fP()) \fIpathname\fP の構成要素が存在するディレクトリかファイルを参照していない。 \fIpathname\fP
219 (\fButimensat\fP()) \fIpathname\fP が相対パスだが、 \fIdirfd\fP が \fBAT_FDCWD\fP
220 でもディレクトリを参照するファイルディスクリプターでもない。 \fIpathname\fP の構成要素のディレクトリ部分がディレクトリではない。
223 呼び出し元がタイムスタンプの一方もしくは両方を現在時刻以外の値に更新しようとしたか、
224 もしくはタイムスタンプの一方を現在時刻に変更し、もう一方は変更しないままにしようとした (すなわち \fItimes\fP が NULL 以外で、 どちらの
225 \fItv_nsec\fP フィールドも \fBUTIME_NOW\fP でもなく、 どちらの \fItv_nsec\fP フィールドも \fBUTIME_OMIT\fP
226 でもない) 場合で、 以下のいずれかにあてはまる。
230 呼び出し元の実効ユーザー ID がファイルの所有者と一致せず、 呼び出し元が特権を持っていない (Linux では、ケーパビリティー
231 \fBCAP_FOWNER\fP を持っていない)。
233 .\" Linux 2.6.22 was broken here:
234 .\" it was not consistent with the old utimes() implementation,
235 .\" since the case when both tv_nsec fields are UTIME_NOW, was not
236 .\" treated like the (times == NULL) case.
237 .\" EXT2_IMMUTABLE_FL EXT_APPPEND_FL and similar flags for
238 .\" other filesystems.
240 .\" Why the inconsistency (which is described under NOTES) between
241 .\" EACCES and EPERM, where only EPERM tests for append-only.
242 .\" (This was also so for the older utimes() implementation.)
243 ファイルに追記のみか変更不可 (immutable) の属性が付いている (\fBchattr\fP(1) 参照)。
248 ファイルが読み込み専用のファイルシステム上にある。
251 (\fButimensat\fP()) \fIpathname\fP の構成要素のディレクトリ部分のいずれかで検索許可がなかった。
253 \fButimensat\fP() はカーネル 2.6.22 で Linux に追加された。 glibc のサポートはバージョン 2.6 で追加された。
255 \fBfutimens\fP() のサポートは glibc 2.6 で初めて登場した。
257 \fBfutimens\fP() と \fButimensat\fP() は POSIX.1\-2008 で規定されている。
259 \fButimensat\fP() が登場した結果、 \fBfutimesat\fP(2) は非推奨となった。
261 Linux では、 変更不可 (immutable) の属性が付いたファイルのタイムスタンプを変更することはできず、
262 また、 追記のみ (append\-only) の属性が付いたファイルで可能な変更は、 タイムスタンプを現在時刻に設定することだけである。 (これは
263 Linux の \fButime\fP(2) や \fButimes\fP() の昔からの動作と一貫性がある動作である)。
265 Linux では、 \fBfutimens\fP() は \fButimensat\fP() システムコールを使って実装されているライブラリ関数である。
266 これを可能にするため、 Linux の \fButimensat\fP() システムコールは非標準の機能を実装している。 \fIpathname\fP が NULL
267 の場合、 呼び出しはファイルディスクリプター \fIdirfd\fP が参照するファイルのタイムスタンプを変更する
268 (ファイルディスクリプターはどのタイプのファイルを参照していてもよい)。 この機能を利用して、 \fIfutimens(fd,\ times)\fP
272 utimensat(fd, NULL, times, 0);
275 両方の \fItv_nsec\fP フィールドに \fBUTIME_OMIT\fP が指定された場合、 \fButimensat\fP() の Linux 実装は、
276 \fIdirfd\fP と \fIpathname\fP が参照するファイルが存在しない場合でも成功する。
278 カーネル 2.6.26 より前では \fButimensat\fP() と \fBfutimens\fP() にはいくつかの悩ましいバグがあった。 これらのバグは、
279 ドラフト版の POSIX.1 規格との不整合や、 以前からの Linux での動作との違いである。
281 POSIX.1 では、 \fItv_nsec\fP フィールドの一つが \fBUTIME_NOW\fP か \fBUTIME_OMIT\fP の場合、 対応する
282 \fItv_sec\fP フィールドは無視されると規定されている。 しかし、 \fItv_sec\fP フィールドの値を 0 にする必要があった
283 (さもなければエラー \fBEINVAL\fP となった)。
285 .\" Below, the long description of the errors from the previous bullet
286 .\" point (abridged because it's too much detail for a man page).
296 .\" should occur if the process's effective user ID does not match
297 .\" the file owner and the process is not privileged.
298 .\" Instead, the call successfully changes one of the timestamps.
300 .\" If file is not writable by the effective user ID of the process and
301 .\" the process's effective user ID does not match the file owner and
302 .\" the process is not privileged,
305 .\" is NULL, then the error
308 .\" This error should also occur if
310 .\" points to an array of structures in which both
314 .\" Instead the call succeeds.
316 .\" If a file is marked as append-only (see
318 .\" then Linux traditionally
324 .\" argument to be used in order to update both timestamps to the current time.
329 .\" should also produce the same result when given a
331 .\" argument that points to an array of structures in which both
335 .\" Instead, the call fails with the error
338 .\" If a file is marked as immutable (see
340 .\" then Linux traditionally
353 .\" should also produce the same result when given a
355 .\" that points to an array of structures in which both
359 .\" Instead, the call fails with the error
361 いくつかのバグのため、 アクセス許可のチェックにおいて、両方の \fItv_nsec\fP フィールドが \fBUTIME_NOW\fP に設定された場合が、 常に
362 \fItimes\fP に NULL が設定された場合と同じに扱われるわけではなく、 \fItv_nsec\fP の一つが \fBUTIME_NOW\fP でもう一方が
363 \fBUTIME_OMIT\fP の場合が、 \fItimes\fP に任意の値が入った構造体の配列へのポインターが指定された場合と
364 同じように扱われるわけではない。 その結果、いくつかの場合では、 a) ファイルのタイムスタンプが、
365 更新を実行する許可を持たないプロセスによって更新されることがある、 b) ファイルのタンプスタンプが、
366 更新を実行する許可を持つプロセスによって更新できないことがある、 c) エラーの場合に間違った \fIerrno\fP 値が返る。
368 .\" This means that a process with a file descriptor that allows
369 .\" writing could change the timestamps of a file for which it
370 .\" does not have write permission;
371 .\" conversely, a process with a read-only file descriptor won't
372 .\" be able to update the timestamps of a file,
373 .\" even if it has write permission on the file.
374 POSIX.1 では、 \fIファイルの書き込み許可を持つ\fPプロセス (a process that has \fIwrite access to the
375 file\fP) は、そのファイルに対して \fItimes\fP に NULL や 両方の \fItv_nsec\fP フィールドが \fBUTIME_NOW\fP
376 の構造体の配列を指定して呼び出しを行い、 両方のタイムスタンプを現在時刻に更新することができると規定されている。 しかし、 \fBfutimens\fP()
377 では、 \fIファイルディスクリプターのアクセス許可が書き込みを許可しているか\fP (\fIaccess mode of the file
378 descriptor allows writing\fP)のチェックが行われる。
380 \fBchattr\fP(1), \fBfutimesat\fP(2), \fBopenat\fP(2), \fBstat\fP(2), \fButimes\fP(2),
381 \fBfutimes\fP(3), \fBpath_resolution\fP(7), \fBsymlink\fP(7)
383 この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 3.79 の一部
384 である。プロジェクトの説明とバグ報告に関する情報は
385 http://www.kernel.org/doc/man\-pages/ に書かれている。
OSDN Git Service
