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.\" @(#)utimes.2 8.1 (Berkeley) 6/4/93 31.\" $FreeBSD$ 32.\" 33.Dd March 30, 2020 34.Dt UTIMES 2 35.Os 36.Sh NAME 37.Nm utimes , 38.Nm lutimes , 39.Nm futimes , 40.Nm futimesat 41.Nd set file access and modification times 42.Sh LIBRARY 43.Lb libc 44.Sh SYNOPSIS 45.In sys/time.h 46.Ft int 47.Fn utimes "const char *path" "const struct timeval *times" 48.Ft int 49.Fn lutimes "const char *path" "const struct timeval *times" 50.Ft int 51.Fn futimes "int fd" "const struct timeval *times" 52.Ft int 53.Fn futimesat "int fd" "const char *path" "const struct timeval times[2]" 54.Sh DESCRIPTION 55.Bf -symbolic 56These interfaces are obsoleted by 57.Xr futimens 2 58and 59.Xr utimensat 2 60because they are not accurate to nanoseconds. 61.Ef 62.Pp 63The access and modification times of the file named by 64.Fa path 65or referenced by 66.Fa fd 67are changed as specified by the argument 68.Fa times . 69.Pp 70If 71.Fa times 72is 73.Dv NULL , 74the access and modification times are set to the current time. 75The caller must be the owner of the file, have permission to 76write the file, or be the super-user. 77.Pp 78If 79.Fa times 80is 81.No non- Ns Dv NULL , 82it is assumed to point to an array of two timeval structures. 83The access time is set to the value of the first element, and the 84modification time is set to the value of the second element. 85For file systems that support file birth (creation) times (such as 86.Dv UFS2 ) , 87the birth time will be set to the value of the second element 88if the second element is older than the currently set birth time. 89To set both a birth time and a modification time, 90two calls are required; the first to set the birth time 91and the second to set the (presumably newer) modification time. 92Ideally a new system call will be added that allows the setting 93of all three times at once. 94The caller must be the owner of the file or be the super-user. 95.Pp 96In either case, the inode-change-time of the file is set to the current 97time. 98.Pp 99The 100.Fn lutimes 101system call 102is like 103.Fn utimes 104except in the case where the named file is a symbolic link, 105in which case 106.Fn lutimes 107changes the access and modification times of the link, 108while 109.Fn utimes 110changes the times of the file the link references. 111.Pp 112The 113.Fn futimesat 114system call is equivalent to 115.Fn utimes 116except in the case where 117.Fa path 118specifies a relative path. 119In this case the access and modification time 120is set to that of a file relative to the directory associated with the file 121descriptor 122.Fa fd 123instead of the current working directory. 124If 125.Fn futimesat 126is passed the special value 127.Dv AT_FDCWD 128in the 129.Fa fd 130parameter, the current working directory is used and the behavior 131is identical to a call to 132.Fn utimes . 133.Sh RETURN VALUES 134.Rv -std 135.Sh ERRORS 136All of the system call will fail if: 137.Bl -tag -width Er 138.It Bq Er EACCES 139Search permission is denied for a component of the path prefix. 140.It Bq Er EACCES 141The 142.Fa times 143argument is 144.Dv NULL 145and the effective user ID of the process does not 146match the owner of the file, and is not the super-user, and write 147access is denied. 148.It Bq Er EFAULT 149The 150.Fa path 151or 152.Fa times 153argument 154points outside the process's allocated address space. 155.It Bq Er EFAULT 156The 157.Fa times 158argument 159points outside the process's allocated address space. 160.It Bq Er EINVAL 161The 162.Va tv_usec 163component of at least one of the values specified by the 164.Fa times 165argument has a value less than 0 or greater than 999999. 166.It Bq Er EIO 167An I/O error occurred while reading or writing the affected inode. 168.It Bq Er EINTEGRITY 169Corrupted data was detected while reading from the file system. 170.It Bq Er ELOOP 171Too many symbolic links were encountered in translating the pathname. 172.It Bq Er ENAMETOOLONG 173A component of a pathname exceeded 174.Dv NAME_MAX 175characters, or an entire path name exceeded 176.Dv PATH_MAX 177characters. 178.It Bq Er ENOENT 179The named file does not exist. 180.It Bq Er ENOTDIR 181A component of the path prefix is not a directory. 182.It Bq Er EPERM 183The 184.Fa times 185argument is not 186.Dv NULL 187and the calling process's effective user ID 188does not match the owner of the file and is not the super-user. 189.It Bq Er EPERM 190The named file has its immutable or append-only flags set. 191See the 192.Xr chflags 2 193manual page for more information. 194.It Bq Er EROFS 195The file system containing the file is mounted read-only. 196.El 197.Pp 198The 199.Fn futimes 200system call 201will fail if: 202.Bl -tag -width Er 203.It Bq Er EBADF 204The 205.Fa fd 206argument 207does not refer to a valid descriptor. 208.El 209.Pp 210In addition to the errors returned by the 211.Fn utimes , 212the 213.Fn futimesat 214may fail if: 215.Bl -tag -width Er 216.It Bq Er EBADF 217The 218.Fa path 219argument does not specify an absolute path and the 220.Fa fd 221argument is neither 222.Dv AT_FDCWD 223nor a valid file descriptor open for searching. 224.It Bq Er ENOTDIR 225The 226.Fa path 227argument is not an absolute path and 228.Fa fd 229is neither 230.Dv AT_FDCWD 231nor a file descriptor associated with a directory. 232.El 233.Sh SEE ALSO 234.Xr chflags 2 , 235.Xr stat 2 , 236.Xr utimensat 2 , 237.Xr utime 3 238.Sh STANDARDS 239The 240.Fn utimes 241function is expected to conform to 242.St -xpg4.2 . 243The 244.Fn futimesat 245system call follows The Open Group Extended API Set 2 specification 246but was replaced by 247.Fn utimensat 248in 249.St -p1003.1-2008 . 250.Sh HISTORY 251The 252.Fn utimes 253system call appeared in 254.Bx 4.2 . 255The 256.Fn futimes 257and 258.Fn lutimes 259system calls first appeared in 260.Fx 3.0 . 261The 262.Fn futimesat 263system call appeared in 264.Fx 8.0 . 265