1.\" $OpenBSD: utimes.2,v 1.28 2020/09/30 16:27:16 deraadt Exp $ 2.\" $NetBSD: utimes.2,v 1.9 1996/04/23 10:34:16 mycroft Exp $ 3.\" 4.\" Copyright (c) 1990, 1993 5.\" The Regents of the University of California. All rights reserved. 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 10.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" 2. Redistributions in binary form must reproduce the above copyright 13.\" notice, this list of conditions and the following disclaimer in the 14.\" documentation and/or other materials provided with the distribution. 15.\" 3. Neither the name of the University nor the names of its contributors 16.\" may be used to endorse or promote products derived from this software 17.\" without specific prior written permission. 18.\" 19.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 20.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 21.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 22.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 23.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 24.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 25.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 26.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 27.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 28.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 29.\" SUCH DAMAGE. 30.\" 31.\" @(#)utimes.2 8.1 (Berkeley) 6/4/93 32.\" 33.Dd $Mdocdate: September 30 2020 $ 34.Dt UTIMES 2 35.Os 36.Sh NAME 37.Nm utimes , 38.Nm futimes , 39.Nm utimensat , 40.Nm futimens 41.Nd set file access and modification times 42.Sh SYNOPSIS 43.In sys/time.h 44.Ft int 45.Fn utimes "const char *path" "const struct timeval times[2]" 46.Ft int 47.Fn futimes "int fd" "const struct timeval times[2]" 48.In sys/stat.h 49.In fcntl.h 50.Ft int 51.Fn utimensat "int fd" "const char *path" "const struct timespec times[2]" "int flag" 52.Ft int 53.Fn futimens "int fd" "const struct timespec times[2]" 54.Sh DESCRIPTION 55The access and modification times of the file named by 56.Fa path 57or referenced by 58.Fa fd 59are changed as specified by the argument 60.Fa times . 61.Pp 62If 63.Fa times 64is 65.Dv NULL , 66the access and modification times are set to the current time. 67The caller must be the owner of the file, have permission to 68write the file, or be the superuser. 69.Pp 70If 71.Fa times 72is non-null, 73it is assumed to point to an array of two timeval structures. 74The access time is set to the value of the first element, and the 75modification time is set to the value of the second element. 76The caller must be the owner of the file or be the superuser. 77.Pp 78In either case, the file status change time is set to the current time. 79.Pp 80The 81.Fn utimensat 82and 83.Fn futimens 84are equivalent to 85.Fn utimes 86and 87.Fn futimes , 88respectively, with the following differences. 89.Pp 90Both 91.Fn utimensat 92and 93.Fn futimens 94take two timespec values instead of two timeval values. 95Further, either of the 96.Fa tv_nsec 97fields can be set to one of the following special values defined in 98.In sys/stat.h , 99in which case the value of 100.Fa tv_sec 101is ignored: 102.Pp 103.Bl -tag -width UTIME_OMIT -offset indent -compact 104.It Dv UTIME_NOW 105Set the respective timestamp to the greatest value supported 106that is not greater than the current time. 107.It Dv UTIME_OMIT 108Do not change the respective timestamp. 109.El 110.Pp 111Additionally, if the 112.Fa path 113argument to 114.Fn utimensat 115specifies a relative path, 116the file whose timestamps are changed is determined relative to 117the directory associated with file descriptor 118.Fa fd 119instead of the current working directory. 120.Pp 121If 122.Fn utimensat 123is passed the special value 124.Dv AT_FDCWD 125(defined in 126.In fcntl.h ) 127in the 128.Fa fd 129parameter, the current working directory is used. 130.Pp 131The 132.Fa flag 133argument is the bitwise OR of zero or more of the following values: 134.Pp 135.Bl -tag -width AT_SYMLINK_NOFOLLOW -offset indent -compact 136.It Dv AT_SYMLINK_NOFOLLOW 137If 138.Fa path 139names a symbolic link, then the timestamps of the symbolic link are changed. 140.El 141.Sh RETURN VALUES 142.Rv -std 143.Sh ERRORS 144.Fn utimes 145and 146.Fn utimensat 147will fail if: 148.Bl -tag -width Er 149.It Bq Er EACCES 150Search permission is denied for a component of the path prefix; 151or the 152.Fa times 153argument is 154.Dv NULL 155and the effective user ID of the process does not 156match the owner of the file, and is not the superuser, and write 157access is denied. 158.It Bq Er EFAULT 159.Fa path 160or 161.Fa times 162points outside the process's allocated address space. 163.It Bq Er EIO 164An I/O error occurred while reading or writing the affected inode. 165.It Bq Er ELOOP 166Too many symbolic links were encountered in translating the pathname. 167.It Bq Er ENAMETOOLONG 168A component of a pathname exceeded 169.Dv NAME_MAX 170characters, or an entire pathname (including the terminating NUL) 171exceeded 172.Dv PATH_MAX 173bytes. 174.It Bq Er ENOENT 175The named file does not exist. 176.It Bq Er ENOTDIR 177A component of the path prefix is not a directory. 178.It Bq Er EPERM 179The 180.Fa times 181argument is not 182.Dv NULL 183and the calling process's effective user ID 184does not match the owner of the file and is not the superuser. 185.It Bq Er EROFS 186The file system containing the file is mounted read-only. 187.El 188.Pp 189Additionally, 190.Fn utimensat 191will fail if: 192.Bl -tag -width Er 193.It Bq Er EINVAL 194The value of the 195.Fa flag 196argument was neither zero nor 197.Dv AT_SYMLINK_NOFOLLOW . 198.It Bq Er EBADF 199The 200.Fa path 201argument specifies a relative path and the 202.Fa fd 203argument is neither 204.Dv AT_FDCWD 205nor a valid file descriptor. 206.It Bq Er ENOTDIR 207The 208.Fa path 209argument specifies a relative path and the 210.Fa fd 211argument is a valid file descriptor but it does not reference a directory. 212.It Bq Er EACCES 213The 214.Fa path 215argument specifies a relative path but search permission is denied 216for the directory which the 217.Fa fd 218file descriptor references. 219.El 220.Pp 221.Fn futimes 222and 223.Fn futimens 224will fail if: 225.Bl -tag -width Er 226.It Bq Er EBADF 227.Fa fd 228does not refer to a valid descriptor. 229.It Bq Er EACCES 230The 231.Fa times 232argument is 233.Dv NULL 234and the effective user ID of the process does not 235match the owner of the file, and is not the superuser, and write 236access is denied. 237.It Bq Er EFAULT 238.Fa times 239points outside the process's allocated address space. 240.It Bq Er EIO 241An I/O error occurred while reading or writing the affected inode. 242.It Bq Er EPERM 243The 244.Fa times 245argument is not 246.Dv NULL 247and the calling process's effective user ID 248does not match the owner of the file and is not the superuser. 249.It Bq Er EROFS 250The file system containing the file is mounted read-only. 251.El 252.Pp 253.Fn utimes 254and 255.Fn futimes 256will fail if: 257.Bl -tag -width Er 258.It Bq Er EINVAL 259Either of the 260.Fa times 261arguments specified a microsecond value less than zero or greater 262than or equal to 1 million, or a second value less than zero. 263.El 264.Pp 265.Fn utimesat 266and 267.Fn futimens 268will fail if: 269.Bl -tag -width Er 270.It Bq Er EINVAL 271Either of the 272.Fa times 273argument specified a nanosecond value less than zero or greater 274than or equal to 1000 million, or a second value less than zero. 275.El 276.Sh SEE ALSO 277.Xr clock_gettime 2 , 278.Xr stat 2 , 279.Xr utime 3 280.Sh STANDARDS 281The 282.Fn utimes , 283.Fn utimensat , 284and 285.Fn futimens 286functions conform to 287.St -p1003.1-2008 . 288.Sh HISTORY 289The predecessors of 290.Fn utimes 291were 292.Fn smdate 293in 294.At v1 , 295.Fn mdate 296in 297.At v3 , 298and 299.Fn utime 300in 301.At v7 ; 302the latter first supported the concept of an access time 303in addition to the modification time. 304.Pp 305The 306.Fn utimes 307function call appeared in 308.Bx 4.2 . 309The 310.Fn futimes 311function call appeared in 312.Nx 1.2 . 313The 314.Fn utimensat 315and 316.Fn futimens 317function calls appeared in 318.Ox 5.0 . 319.Sh CAVEATS 320Some filesystems, such as FAT, use the same timestamp for both 321modification and file status change; 322on those filesystems, the file status change timestamp will not be 323updated if 324.Dv UTIME_OMIT 325is specified for the modification timestamp argument. 326Similarly, on NFS the file status change timestamp will not be 327updated if 328.Dv UTIME_OMIT 329is specified for both the access and the modification timestamp arguments. 330