From 399644e47874bff147afb19c89228901ac39340e Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Mon, 15 Apr 2024 21:40:15 +0200 Subject: Adding upstream version 6.05.01. Signed-off-by: Daniel Baumann --- man2/utime.2 | 179 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 179 insertions(+) create mode 100644 man2/utime.2 (limited to 'man2/utime.2') diff --git a/man2/utime.2 b/man2/utime.2 new file mode 100644 index 0000000..86760ab --- /dev/null +++ b/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 +.\" Modified 1993-07-24 by Rik Faith +.\" Modified 1995-06-10 by Andries Brouwer +.\" Modified 2004-06-23 by Michael Kerrisk +.\" Modified 2004-10-10 by Andries Brouwer +.\" +.TH utime 2 2023-03-30 "Linux man-pages 6.05.01" +.SH NAME +utime, utimes \- change file last access and modification times +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int utime(const char *" filename , +.BI " const struct utimbuf *_Nullable " times ); +.PP +.B #include +.PP +.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). +.PP +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. +.PP +If +.I times +is NULL, then the access and modification times of the file are set +to the current time. +.PP +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. +.PP +The +.I utimbuf +structure is: +.PP +.in +4n +.EX +struct utimbuf { + time_t actime; /* access time */ + time_t modtime; /* modification time */ +}; +.EE +.in +.PP +The +.BR utime () +system call +allows specification of timestamps with a resolution of 1 second. +.PP +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: +.PP +.in +4n +.EX +struct timeval { + long tv_sec; /* seconds */ + long tv_usec; /* microseconds */ +}; +.EE +.in +.PP +.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) -- cgit v1.2.3