Merging upstream version 6.8.

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 179 insertions, 0 deletions

diff --git a/man/man2/utime.2 b/man/man2/utime.2
new file mode 100644
index 0000000..4d7082d
--- /dev/null
+++ b/man/man2/utime.2
@@ -0,0 +1,179 @@
+.\" Copyright (c) 1992 Drew Eckhardt (drew@cs.colorado.edu), March 28, 1992
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.\" Modified by Michael Haardt <michael@moria.de>
+.\" Modified 1993-07-24 by Rik Faith <faith@cs.unc.edu>
+.\" Modified 1995-06-10 by Andries Brouwer <aeb@cwi.nl>
+.\" Modified 2004-06-23 by Michael Kerrisk <mtk.manpages@gmail.com>
+.\" Modified 2004-10-10 by Andries Brouwer <aeb@cwi.nl>
+.\"
+.TH utime 2 2024-05-02 "Linux man-pages (unreleased)"
+.SH NAME
+utime, utimes \- change file last access and modification times
+.SH LIBRARY
+Standard C library
+.RI ( libc ", " \-lc )
+.SH SYNOPSIS
+.nf
+.B #include <utime.h>
+.P
+.BI "int utime(const char *" filename ,
+.BI "          const struct utimbuf *_Nullable " times );
+.P
+.B #include <sys/time.h>
+.P
+.BI "int utimes(const char *" filename ,
+.BI "          const struct timeval " times "[_Nullable 2]);"
+.fi
+.SH DESCRIPTION
+.B Note:
+modern applications may prefer to use the interfaces described in
+.BR utimensat (2).
+.P
+The
+.BR utime ()
+system call
+changes the access and modification times of the inode specified by
+.I filename
+to the
+.IR actime " and " modtime
+fields of
+.I times
+respectively.
+The status change time (ctime) will be set to the current time, even if the
+other time stamps don't actually change.
+.P
+If
+.I times
+is NULL, then the access and modification times of the file are set
+to the current time.
+.P
+Changing timestamps is permitted when: either
+the process has appropriate privileges,
+or the effective user ID equals the user ID
+of the file, or
+.I times
+is NULL and the process has write permission for the file.
+.P
+The
+.I utimbuf
+structure is:
+.P
+.in +4n
+.EX
+struct utimbuf {
+    time_t actime;       /* access time */
+    time_t modtime;      /* modification time */
+};
+.EE
+.in
+.P
+The
+.BR utime ()
+system call
+allows specification of timestamps with a resolution of 1 second.
+.P
+The
+.BR utimes ()
+system call
+is similar, but the
+.I times
+argument refers to an array rather than a structure.
+The elements of this array are
+.I timeval
+structures, which allow a precision of 1 microsecond for specifying timestamps.
+The
+.I timeval
+structure is:
+.P
+.in +4n
+.EX
+struct timeval {
+    long tv_sec;        /* seconds */
+    long tv_usec;       /* microseconds */
+};
+.EE
+.in
+.P
+.I times[0]
+specifies the new access time, and
+.I times[1]
+specifies the new modification time.
+If
+.I times
+is NULL, then analogously to
+.BR utime (),
+the access and modification times of the file are
+set to the current time.
+.SH RETURN VALUE
+On success, zero is returned.
+On error, \-1 is returned, and
+.I errno
+is set to indicate the error.
+.SH ERRORS
+.TP
+.B EACCES
+Search permission is denied for one of the directories in
+the path prefix of
+.I path
+(see also
+.BR path_resolution (7)).
+.TP
+.B EACCES
+.I times
+is NULL,
+the caller's effective user ID does not match the owner of the file,
+the caller does not have write access to the file,
+and the caller is not privileged
+(Linux: does not have either the
+.B CAP_DAC_OVERRIDE
+or the
+.B CAP_FOWNER
+capability).
+.TP
+.B ENOENT
+.I filename
+does not exist.
+.TP
+.B EPERM
+.I times
+is not NULL,
+the caller's effective UID does not match the owner of the file,
+and the caller is not privileged
+(Linux: does not have the
+.B CAP_FOWNER
+capability).
+.TP
+.B EROFS
+.I path
+resides on a read-only filesystem.
+.SH STANDARDS
+POSIX.1-2008.
+.SH HISTORY
+.TP
+.BR utime ()
+SVr4, POSIX.1-2001.
+POSIX.1-2008 marks it as obsolete.
+.TP
+.BR utimes ()
+4.3BSD, POSIX.1-2001.
+.SH NOTES
+Linux does not allow changing the timestamps on an immutable file,
+or setting the timestamps to something other than the current time
+on an append-only file.
+.\"
+.\" In libc4 and libc5,
+.\" .BR utimes ()
+.\" is just a wrapper for
+.\" .BR utime ()
+.\" and hence does not allow a subsecond resolution.
+.SH SEE ALSO
+.BR chattr (1),
+.BR touch (1),
+.BR futimesat (2),
+.BR stat (2),
+.BR utimensat (2),
+.BR futimens (3),
+.BR futimes (3),
+.BR inode (7)