1.\" $OpenBSD: utimes.2,v 1.27 2016/01/05 17:40:26 millert 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: January 5 2016 $ 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" 46.Ft int 47.Fn futimes "int fd" "const struct timeval *times" 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.Sh SEE ALSO 253.Xr clock_gettime 2 , 254.Xr stat 2 , 255.Xr utime 3 256.Sh STANDARDS 257The 258.Fn utimes , 259.Fn utimensat , 260and 261.Fn futimens 262functions conform to 263.St -p1003.1-2008 . 264.Sh HISTORY 265The predecessors of 266.Fn utimes 267were 268.Fn smdate 269in 270.At v1 , 271.Fn mdate 272in 273.At v3 , 274and 275.Fn utime 276in 277.At v7 ; 278the latter first supported the concept of an access time 279in addition to the modification time. 280.Pp 281The 282.Fn utimes 283function call appeared in 284.Bx 4.2 . 285The 286.Fn futimes 287function call appeared in 288.Nx 1.2 . 289The 290.Fn utimensat 291and 292.Fn futimens 293function calls appeared in 294.Ox 5.0 . 295.Sh CAVEATS 296Some filesystems, such as FAT, use the same timestamp for both 297modification and file status change; 298on those filesystems, the file status change timestamp will not be 299updated if 300.Dv UTIME_OMIT 301is specified for the modification timestamp argument. 302Similarly, on NFS the file status change timestamp will not be 303updated if 304.Dv UTIME_OMIT 305is specified for both the access and the modification timestamp arguments. 306