diff options
Diffstat (limited to 'man2/utimensat.2')
| -rw-r--r-- | man2/utimensat.2 | 74 |
1 files changed, 47 insertions, 27 deletions
diff --git a/man2/utimensat.2 b/man2/utimensat.2 index 77456fc..d69539d 100644 --- a/man2/utimensat.2 +++ b/man2/utimensat.2 @@ -4,7 +4,7 @@ .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" -.TH utimensat 2 2023-07-20 "Linux man-pages 6.05.01" +.TH utimensat 2 2024-01-01 "Linux man-pages 6.7" .SH NAME utimensat, futimens \- change file timestamps with nanosecond precision .SH LIBRARY @@ -14,17 +14,17 @@ Standard C library .nf .BR "#include <fcntl.h>" " /* Definition of " AT_* " constants */" .B #include <sys/stat.h> -.PP +.P .BI "int utimensat(int " dirfd ", const char *" pathname , .BI " const struct timespec " times "[_Nullable 2], int " flags ); .BI "int futimens(int " fd ", const struct timespec " times "[_Nullable 2]);" .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR utimensat (): .nf Since glibc 2.10: @@ -32,7 +32,7 @@ Feature Test Macro Requirements for glibc (see Before glibc 2.10: _ATFILE_SOURCE .fi -.PP +.P .BR futimens (): .nf Since glibc 2.10: @@ -51,7 +51,7 @@ and .BR utimes (2), which permit only second and microsecond precision, respectively, when setting file timestamps. -.PP +.P With .BR utimensat () the file is specified via the pathname given in @@ -61,7 +61,7 @@ With the file whose timestamps are to be updated is specified via an open file descriptor, .IR fd . -.PP +.P For both calls, the new file timestamps are specified in the array .IR times : .I times[0] @@ -75,10 +75,10 @@ since the Epoch, 1970-01-01 00:00:00 +0000 (UTC). This information is conveyed in a .BR timespec (3) structure. -.PP +.P Updated file timestamps are set to the greatest value supported by the filesystem that is not greater than the specified time. -.PP +.P If the .I tv_nsec field of one of the @@ -97,12 +97,12 @@ In both of these cases, the value of the corresponding .I tv_sec .\" 2.6.22 was broken: it is not ignored field is ignored. -.PP +.P If .I times is NULL, then both timestamps are set to the current time. .\" -.PP +.P The status change time (ctime) will be set to the current time, even if the other time stamps don't actually change. .SS Permissions requirements @@ -123,7 +123,7 @@ the caller must have write access to the file; the caller's effective user ID must match the owner of the file; or .IP \[bu] the caller must have appropriate privileges. -.PP +.P To make any change other than setting both timestamps to the current time (i.e., .I times @@ -138,7 +138,7 @@ and neither field is .BR UTIME_OMIT ), either condition 2 or 3 above must apply. -.PP +.P If both .I tv_nsec fields are specified as @@ -161,7 +161,7 @@ for a relative pathname). See .BR openat (2) for an explanation of why this can be useful. -.PP +.P If .I pathname is relative and @@ -173,19 +173,40 @@ then is interpreted relative to the current working directory of the calling process (like .BR utimes (2)). -.PP +.P If .I pathname is absolute, then .I dirfd is ignored. -.PP +.P The .I flags -field is a bit mask that may be 0, or include the following constant, -defined in +argument is a bit mask created by ORing together zero or more of +the following values defined in .IR <fcntl.h> : .TP +.BR AT_EMPTY_PATH " (since Linux 5.8)" +If +.I pathname +is an empty string, operate on the file referred to by +.I dirfd +(which may have been obtained using the +.BR open (2) +.B O_PATH +flag). +In this case, +.I dirfd +can refer to any type of file, not just a directory. +If +.I dirfd +is +.BR AT_FDCWD , +the call operates on the current working directory. +This flag is Linux-specific; define +.B _GNU_SOURCE +to obtain its definition. +.TP .B AT_SYMLINK_NOFOLLOW If .I pathname @@ -383,7 +404,6 @@ T{ .BR futimens () T} Thread safety MT-Safe .TE -.sp 1 .SH VERSIONS .SS C library/kernel ABI differences On Linux, @@ -402,13 +422,13 @@ the file referred to by the file descriptor Using this feature, the call .I "futimens(fd,\ times)" is implemented as: -.PP +.P .in +4n .EX utimensat(fd, NULL, times, 0); .EE .in -.PP +.P Note, however, that the glibc wrapper for .BR utimensat () disallows passing NULL as the value for @@ -432,7 +452,7 @@ POSIX.1-2008. .BR utimensat () obsoletes .BR futimesat (2). -.PP +.P On Linux, timestamps cannot be changed for a file marked immutable, and the only change permitted for files marked append-only is to set the timestamps to the current time. @@ -441,7 +461,7 @@ set the timestamps to the current time. and .BR utimes (2) on Linux.) -.PP +.P If both .I tv_nsec fields are specified as @@ -504,7 +524,7 @@ c) the wrong value is returned in case of an error. .\" Below, the long description of the errors from the previous bullet .\" point (abridged because it's too much detail for a man page). -.\" .IP * +.\" .IP \[bu] .\" If one of the .\" .I tv_nsec .\" fields is @@ -516,7 +536,7 @@ value is returned in case of an error. .\" 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 * +.\" .IP \[bu] .\" 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, @@ -532,7 +552,7 @@ value is returned in case of an error. .\" fields are .\" .BR UTIME_NOW . .\" Instead the call succeeds. -.\" .IP * +.\" .IP \[bu] .\" If a file is marked as append-only (see .\" .BR chattr (1)), .\" then Linux traditionally @@ -554,7 +574,7 @@ value is returned in case of an error. .\" .BR UTIME_NOW . .\" Instead, the call fails with the error .\" .BR EPERM . -.\" .IP * +.\" .IP \[bu] .\" If a file is marked as immutable (see .\" .BR chattr (1)), .\" then Linux traditionally |