| .\" Copyright (c) 1992 Drew Eckhardt (drew@cs.colorado.edu), March 28, 1992 |
| .\" |
| .\" %%%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 |
| .\" |
| .\" 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 2017-09-15 "Linux" "Linux Programmer's Manual" |
| .SH NAME |
| utime, utimes \- change file last access and modification times |
| .SH SYNOPSIS |
| .nf |
| .B #include <sys/types.h> |
| .B #include <utime.h> |
| .PP |
| .BI "int utime(const char *" filename ", const struct utimbuf *" times ); |
| .PP |
| .B #include <sys/time.h> |
| .PP |
| .BI "int utimes(const char *" filename ", const struct timeval " times [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. |
| .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 |
| .IR times [0] |
| specifies the new access time, and |
| .IR 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 appropriately. |
| .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 CONFORMING TO |
| .BR utime (): |
| SVr4, POSIX.1-2001. |
| POSIX.1-2008 marks |
| .BR utime () |
| as obsolete. |
| .PP |
| .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) |