man2/utime.2

   1 .\" Copyright (c) 1992 Drew Eckhardt (drew@cs.colorado.edu), March 28, 1992
   2 .\"
   3 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   4 .\"
   5 .\" Modified by Michael Haardt <michael@moria.de>
   6 .\" Modified 1993-07-24 by Rik Faith <faith@cs.unc.edu>
   7 .\" Modified 1995-06-10 by Andries Brouwer <aeb@cwi.nl>
   8 .\" Modified 2004-06-23 by Michael Kerrisk <mtk.manpages@gmail.com>
   9 .\" Modified 2004-10-10 by Andries Brouwer <aeb@cwi.nl>
  10 .\"
  11 .TH utime 2 (date) "Linux man-pages (unreleased)"
  12 .SH NAME
  13 utime, utimes \- change file last access and modification times
  14 .SH LIBRARY
  15 Standard C library
  16 .RI ( libc ", " \-lc )
  17 .SH SYNOPSIS
  18 .nf
  19 .B #include <utime.h>
  20 .P
  21 .BI "int utime(const char *" filename ,
  22 .BI "          const struct utimbuf *_Nullable " times );
  23 .P
  24 .B #include <sys/time.h>
  25 .P
  26 .BI "int utimes(const char *" filename ,
  27 .BI "          const struct timeval " times "[_Nullable 2]);"
  28 .fi
  29 .SH DESCRIPTION
  30 .B Note:
  31 modern applications may prefer to use the interfaces described in
  32 .BR utimensat (2).
  33 .P
  34 The
  35 .BR utime ()
  36 system call
  37 changes the access and modification times of the inode specified by
  38 .I filename
  39 to the
  40 .IR actime " and " modtime
  41 fields of
  42 .I times
  43 respectively.
  44 The status change time (ctime) will be set to the current time, even if the
  45 other time stamps don't actually change.
  46 .P
  47 If
  48 .I times
  49 is NULL, then the access and modification times of the file are set
  50 to the current time.
  51 .P
  52 Changing timestamps is permitted when: either
  53 the process has appropriate privileges,
  54 or the effective user ID equals the user ID
  55 of the file, or
  56 .I times
  57 is NULL and the process has write permission for the file.
  58 .P
  59 The
  60 .I utimbuf
  61 structure is:
  62 .P
  63 .in +4n
  64 .EX
  65 struct utimbuf {
  66     time_t actime;       /* access time */
  67     time_t modtime;      /* modification time */
  68 };
  69 .EE
  70 .in
  71 .P
  72 The
  73 .BR utime ()
  74 system call
  75 allows specification of timestamps with a resolution of 1 second.
  76 .P
  77 The
  78 .BR utimes ()
  79 system call
  80 is similar, but the
  81 .I times
  82 argument refers to an array rather than a structure.
  83 The elements of this array are
  84 .I timeval
  85 structures, which allow a precision of 1 microsecond for specifying timestamps.
  86 The
  87 .I timeval
  88 structure is:
  89 .P
  90 .in +4n
  91 .EX
  92 struct timeval {
  93     long tv_sec;        /* seconds */
  94     long tv_usec;       /* microseconds */
  95 };
  96 .EE
  97 .in
  98 .P
  99 .I times[0]
 100 specifies the new access time, and
 101 .I times[1]
 102 specifies the new modification time.
 103 If
 104 .I times
 105 is NULL, then analogously to
 106 .BR utime (),
 107 the access and modification times of the file are
 108 set to the current time.
 109 .SH RETURN VALUE
 110 On success, zero is returned.
 111 On error, \-1 is returned, and
 112 .I errno
 113 is set to indicate the error.
 114 .SH ERRORS
 115 .TP
 116 .B EACCES
 117 Search permission is denied for one of the directories in
 118 the path prefix of
 119 .I path
 120 (see also
 121 .BR path_resolution (7)).
 122 .TP
 123 .B EACCES
 124 .I times
 125 is NULL,
 126 the caller's effective user ID does not match the owner of the file,
 127 the caller does not have write access to the file,
 128 and the caller is not privileged
 129 (Linux: does not have either the
 130 .B CAP_DAC_OVERRIDE
 131 or the
 132 .B CAP_FOWNER
 133 capability).
 134 .TP
 135 .B ENOENT
 136 .I filename
 137 does not exist.
 138 .TP
 139 .B EPERM
 140 .I times
 141 is not NULL,
 142 the caller's effective UID does not match the owner of the file,
 143 and the caller is not privileged
 144 (Linux: does not have the
 145 .B CAP_FOWNER
 146 capability).
 147 .TP
 148 .B EROFS
 149 .I path
 150 resides on a read-only filesystem.
 151 .SH STANDARDS
 152 POSIX.1-2008.
 153 .SH HISTORY
 154 .TP
 155 .BR utime ()
 156 SVr4, POSIX.1-2001.
 157 POSIX.1-2008 marks it as obsolete.
 158 .TP
 159 .BR utimes ()
 160 4.3BSD, POSIX.1-2001.
 161 .SH NOTES
 162 Linux does not allow changing the timestamps on an immutable file,
 163 or setting the timestamps to something other than the current time
 164 on an append-only file.
 165 .\"
 166 .\" In libc4 and libc5,
 167 .\" .BR utimes ()
 168 .\" is just a wrapper for
 169 .\" .BR utime ()
 170 .\" and hence does not allow a subsecond resolution.
 171 .SH SEE ALSO
 172 .BR chattr (1),
 173 .BR touch (1),
 174 .BR futimesat (2),
 175 .BR stat (2),
 176 .BR utimensat (2),
 177 .BR futimens (3),
 178 .BR futimes (3),
 179 .BR inode (7)