1.\" $NetBSD: utimes.2,v 1.13 1999/03/22 19:45:11 garbled Exp $ 2.\" 3.\" Copyright (c) 1990, 1993 4.\" The Regents of the University of California. All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 3. Neither the name of the University nor the names of its contributors 15.\" may be used to endorse or promote products derived from this software 16.\" without specific prior written permission. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 19.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 20.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 21.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 22.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 23.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 24.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 25.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 26.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 27.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 28.\" SUCH DAMAGE. 29.\" 30.Dd March 30, 2020 31.Dt UTIMES 2 32.Os 33.Sh NAME 34.Nm utimes , 35.Nm lutimes , 36.Nm futimes , 37.Nm futimesat 38.Nd set file access and modification times 39.Sh LIBRARY 40.Lb libc 41.Sh SYNOPSIS 42.In sys/time.h 43.Ft int 44.Fn utimes "const char *path" "const struct timeval *times" 45.Ft int 46.Fn lutimes "const char *path" "const struct timeval *times" 47.Ft int 48.Fn futimes "int fd" "const struct timeval *times" 49.Ft int 50.Fn futimesat "int fd" "const char *path" "const struct timeval times[2]" 51.Sh DESCRIPTION 52.Bf -symbolic 53These interfaces are obsoleted by 54.Xr futimens 2 55and 56.Xr utimensat 2 57because they are not accurate to nanoseconds. 58.Ef 59.Pp 60The access and modification times of the file named by 61.Fa path 62or referenced by 63.Fa fd 64are changed as specified by the argument 65.Fa times . 66.Pp 67If 68.Fa times 69is 70.Dv NULL , 71the access and modification times are set to the current time. 72The caller must be the owner of the file, have permission to 73write the file, or be the super-user. 74.Pp 75If 76.Fa times 77is 78.No non- Ns Dv NULL , 79it is assumed to point to an array of two timeval structures. 80The access time is set to the value of the first element, and the 81modification time is set to the value of the second element. 82For file systems that support file birth (creation) times (such as 83.Dv UFS2 ) , 84the birth time will be set to the value of the second element 85if the second element is older than the currently set birth time. 86To set both a birth time and a modification time, 87two calls are required; the first to set the birth time 88and the second to set the (presumably newer) modification time. 89Ideally a new system call will be added that allows the setting 90of all three times at once. 91The caller must be the owner of the file or be the super-user. 92.Pp 93In either case, the inode-change-time of the file is set to the current 94time. 95.Pp 96The 97.Fn lutimes 98system call 99is like 100.Fn utimes 101except in the case where the named file is a symbolic link, 102in which case 103.Fn lutimes 104changes the access and modification times of the link, 105while 106.Fn utimes 107changes the times of the file the link references. 108.Pp 109The 110.Fn futimesat 111system call is equivalent to 112.Fn utimes 113except in the case where 114.Fa path 115specifies a relative path. 116In this case the access and modification time 117is set to that of a file relative to the directory associated with the file 118descriptor 119.Fa fd 120instead of the current working directory. 121If 122.Fn futimesat 123is passed the special value 124.Dv AT_FDCWD 125in the 126.Fa fd 127parameter, the current working directory is used and the behavior 128is identical to a call to 129.Fn utimes . 130.Sh RETURN VALUES 131.Rv -std 132.Sh ERRORS 133All of the system call will fail if: 134.Bl -tag -width Er 135.It Bq Er EACCES 136Search permission is denied for a component of the path prefix. 137.It Bq Er EACCES 138The 139.Fa times 140argument is 141.Dv NULL 142and the effective user ID of the process does not 143match the owner of the file, and is not the super-user, and write 144access is denied. 145.It Bq Er EFAULT 146The 147.Fa path 148or 149.Fa times 150argument 151points outside the process's allocated address space. 152.It Bq Er EFAULT 153The 154.Fa times 155argument 156points outside the process's allocated address space. 157.It Bq Er EINVAL 158The 159.Va tv_usec 160component of at least one of the values specified by the 161.Fa times 162argument has a value less than 0 or greater than 999999. 163.It Bq Er EIO 164An I/O error occurred while reading or writing the affected inode. 165.It Bq Er EINTEGRITY 166Corrupted data was detected while reading from the file system. 167.It Bq Er ELOOP 168Too many symbolic links were encountered in translating the pathname. 169.It Bq Er ENAMETOOLONG 170A component of a pathname exceeded 171.Dv NAME_MAX 172characters, or an entire path name exceeded 173.Dv PATH_MAX 174characters. 175.It Bq Er ENOENT 176The named file does not exist. 177.It Bq Er ENOTDIR 178A component of the path prefix is not a directory. 179.It Bq Er EPERM 180The 181.Fa times 182argument is not 183.Dv NULL 184and the calling process's effective user ID 185does not match the owner of the file and is not the super-user. 186.It Bq Er EPERM 187The named file has its immutable or append-only flags set. 188See the 189.Xr chflags 2 190manual page for more information. 191.It Bq Er EROFS 192The file system containing the file is mounted read-only. 193.El 194.Pp 195The 196.Fn futimes 197system call 198will fail if: 199.Bl -tag -width Er 200.It Bq Er EBADF 201The 202.Fa fd 203argument 204does not refer to a valid descriptor. 205.El 206.Pp 207In addition to the errors returned by the 208.Fn utimes , 209the 210.Fn futimesat 211may fail if: 212.Bl -tag -width Er 213.It Bq Er EBADF 214The 215.Fa path 216argument does not specify an absolute path and the 217.Fa fd 218argument is neither 219.Dv AT_FDCWD 220nor a valid file descriptor open for searching. 221.It Bq Er ENOTDIR 222The 223.Fa path 224argument is not an absolute path and 225.Fa fd 226is neither 227.Dv AT_FDCWD 228nor a file descriptor associated with a directory. 229.El 230.Sh SEE ALSO 231.Xr chflags 2 , 232.Xr stat 2 , 233.Xr utimensat 2 , 234.Xr utime 3 235.Sh STANDARDS 236The 237.Fn utimes 238function is expected to conform to 239.St -xpg4.2 . 240The 241.Fn futimesat 242system call follows The Open Group Extended API Set 2 specification 243but was replaced by 244.Fn utimensat 245in 246.St -p1003.1-2008 . 247.Sh HISTORY 248The 249.Fn utimes 250system call appeared in 251.Bx 4.2 . 252The 253.Fn futimes 254and 255.Fn lutimes 256system calls first appeared in 257.Fx 3.0 . 258The 259.Fn futimesat 260system call appeared in 261.Fx 8.0 . 262