1.\" $OpenBSD: utimes.2,v 1.17 2011/11/17 14:26:14 schwarze 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: November 17 2011 $ 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.Fd #include <sys/time.h> 44.Ft int 45.Fn utimes "const char *file" "const struct timeval *times" 46.Ft int 47.Fn futimes "int fd" "const struct timeval *times" 48.Fd #include <sys/stat.h> 49.Fd #include <fcntl.h> 50.Ft int 51.Fn utimensat "int fd" "const char *file" "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 inode-change-time of the file is set to the current 79time. 80.Pp 81The 82.Fn utimensat 83and 84.Fn futimens 85are equivalent to 86.Fn utimes 87and 88.Fn futimes , 89respectively, with the following differences. 90.Pp 91Both 92.Fn utimensat 93and 94.Fn futimens 95take two timespec values instead of two timeval values. 96Further, either of the 97.Fa tv_nsec 98fields can be set to one of the following special values defined in 99.In sys/stat.h : 100.Pp 101.Bl -tag -width UTIME_OMIT -offset indent -compact 102.It Dv UTIME_NOW 103Set the respective timestamp to the greatest value supported 104that is not greater than the current time. 105.It Dv UTIME_OMIT 106Do not change the respective timestamp. 107.El 108.Pp 109Additionally, if the 110.Fa path 111argument to 112.Fn utimensat 113specifies a relative path, 114the file whose timestamps are changed is determined relative to 115the directory associated with file descriptor 116.Fa fd 117instead of the current working directory. 118.Pp 119If 120.Fn utimensat 121is passed the special value 122.Dv AT_FDCWD 123(defined in 124.In fcntl.h ) 125in the 126.Fa fd 127parameter, the current working directory is used. 128.Pp 129Values for 130.Fa flag 131are constructed by bitwise-inclusive 132.Tn OR Ns ing 133flags from the following list defined in 134.In fcntl.h : 135.Pp 136.Bl -tag -width AT_SYMLINK_NOFOLLOW -offset indent -compact 137.It Dv AT_SYMLINK_NOFOLLOW 138If 139.Fa path 140names a symbolic link, then the timestamps of the symbolic link are changed. 141.El 142.Sh RETURN VALUES 143Upon successful completion, a value of 0 is returned. 144Otherwise, a value of \-1 is returned and 145.Va errno 146is set to indicate the error. 147.Sh ERRORS 148.Fn utimes 149and 150.Fn utimensat 151will fail if: 152.Bl -tag -width Er 153.It Bq Er EACCES 154Search permission is denied for a component of the path prefix; 155or the 156.Fa times 157argument is 158.Dv NULL 159and the effective user ID of the process does not 160match the owner of the file, and is not the superuser, and write 161access is denied. 162.It Bq Er EFAULT 163.Pa File 164or 165.Fa times 166points outside the process's allocated address space. 167.It Bq Er EIO 168An I/O error occurred while reading or writing the affected inode. 169.It Bq Er ELOOP 170Too many symbolic links were encountered in translating the pathname. 171.It Bq Er ENAMETOOLONG 172A component of a pathname exceeded 173.Dv {NAME_MAX} 174characters, or an entire path name exceeded 175.Dv {PATH_MAX} 176characters. 177.It Bq Er ENOENT 178The named file does not exist. 179.It Bq Er ENOTDIR 180A component of the path prefix is not a directory. 181.It Bq Er EPERM 182The 183.Fa times 184argument is not 185.Dv NULL 186and the calling process's effective user ID 187does not match the owner of the file and is not the superuser. 188.It Bq Er EROFS 189The file system containing the file is mounted read-only. 190.El 191.Pp 192Additionally, 193.Fn utimensat 194will fail if: 195.Bl -tag -width Er 196.It Bq Er EBADF 197The 198.Fa path 199argument does not specify an absolute path and the 200.Fa fd 201argument is neither 202.Dv AT_FDCWD 203nor a valid file descriptor open for reading. 204.El 205.Pp 206.Fn futimes 207and 208.Fn futimens 209will fail if: 210.Bl -tag -width Er 211.It Bq Er EBADF 212.Fa fd 213does not refer to a valid descriptor. 214.It Bq Er EACCES 215The 216.Fa times 217argument is 218.Dv NULL 219and the effective user ID of the process does not 220match the owner of the file, and is not the superuser, and write 221access is denied. 222.It Bq Er EFAULT 223.Fa times 224points outside the process's allocated address space. 225.It Bq Er EIO 226An I/O error occurred while reading or writing the affected inode. 227.It Bq Er EPERM 228The 229.Fa times 230argument is not 231.Dv NULL 232and the calling process's effective user ID 233does not match the owner of the file and is not the superuser. 234.It Bq Er EROFS 235The file system containing the file is mounted read-only. 236.El 237.Sh SEE ALSO 238.Xr stat 2 , 239.Xr utime 3 240.Sh STANDARDS 241The 242.Fn utimes , 243.Fn utimensat , 244and 245.Fn futimens 246functions conform to 247.St -p1003.1-2008 . 248.Sh HISTORY 249The predecessors of 250.Fn utimes 251were 252.Fn smdate 253in 254.At v1 , 255.Fn mdate 256in 257.At v3 , 258and 259.Fn utime 260in 261.At v7 ; 262the latter first supported the concept of an access time 263in addition to the modification time. 264.Pp 265The 266.Fn utimes 267function call appeared in 268.Bx 4.2 . 269The 270.Fn futimes 271function call appeared in 272.Nx 1.2 . 273The 274.Fn utimensat 275and 276.Fn futimens 277function calls appeared in 278.Ox 5.0 . 279.Sh CAVEATS 280.St -p1003.1-2008 281specifies that 282.Fn utimensat 283and 284.Fn futimens 285shall mark the last file status change timestamp (i.e.\& 286.Fa st_ctim ) 287for update upon successful completion. 288However, currently some filesystems (e.g. UFS) 289will not do so if 290.Dv UTIME_OMIT 291is specified for the modification timestamp argument. 292