1.\" $NetBSD: utimes.2,v 1.40 2013/10/05 21:24:36 ast 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.\" 32.Dd September 14, 2013 33.Dt UTIMES 2 34.Os 35.Sh NAME 36.Nm utimes , 37.Nm lutimes , 38.Nm futimes , 39.Nm utimens , 40.Nm lutimens , 41.Nm futimens , 42.Nm utimensat 43.Nd set file access and modification times 44.Sh LIBRARY 45.Lb libc 46.Sh SYNOPSIS 47.In sys/time.h 48.Ft int 49.Fn utimes "const char *path" "const struct timeval times[2]" 50.Ft int 51.Fn lutimes "const char *path" "const struct timeval times[2]" 52.Ft int 53.Fn futimes "int fd" "const struct timeval times[2]" 54.In sys/stat.h 55.Ft int 56.Fn utimens "const char *path" "const struct timespec times[2]" 57.Ft int 58.Fn lutimens "const char *path" "const struct timespec times[2]" 59.Ft int 60.Fn futimens "int fd" "const struct timespec times[2]" 61.In sys/stat.h 62.In fcntl.h 63.Ft int 64.Fn utimensat "int fd" "const char *path" "const struct timespec times[2]" \ 65 "int flag" 66.Sh DESCRIPTION 67The access and modification times of the file named by 68.Fa path 69or referenced by 70.Fa fd 71are changed as specified by the argument 72.Fa times . 73.Pp 74If 75.Fa times 76is 77.Dv NULL , 78the access and modification times are set to the current time. 79The caller must be the owner of the file, have permission to 80write the file, or be the super-user. 81.Pp 82If 83.Fa times 84is 85.Pf non- Dv NULL , 86it is assumed to point to an array of two timeval structures. 87The access time is set to the value of the first element, and the 88modification time is set to the value of the second element. 89For file systems that support file birth (creation) times (such as 90UFS2), the birth time will be set to the value of the second element 91if the second element is older than the currently set birth time. 92To set both a birth time and a modification time, two calls are 93required; the first to set the birth time and the second to set 94the (presumably newer) modification time. 95Ideally a new system call will be added that allows the setting of 96all three times at once. 97The caller must be the owner of the file or be the super-user. 98.Pp 99In either case, the inode-change-time of the file is set to the current 100time. 101.Pp 102.Fn lutimes 103is like 104.Fn utimes 105except in the case where the named file is a symbolic link, 106in which case 107.Fn lutimes 108changes the access and modification times of the link, 109while 110.Fn utimes 111changes the times of the file the link references. 112.Pp 113.Fn utimens , 114.Fn lutimens , 115and 116.Fn futimens 117are like 118.Fn utimes , 119.Fn lutimes , 120and 121.Fn futimes 122respectively except that time is specified with nanosecond instead of 123microsecond precision. 124.Pp 125.Fn utimensat 126works the same way as 127.Fn utimens 128except if 129.Fa path 130is relative. 131In that case, it is looked up from a directory whose file 132descriptor was passed as 133.Fa fd . 134Search permission is required on this directory. 135.\" (These alternatives await a decision about the semantics of O_SEARCH) 136.\" Search permission is required on this directory 137.\" except if 138.\" .Fa fd 139.\" was opened with the 140.\" .Dv O_SEARCH 141.\" flag. 142.\" - or - 143.\" This file descriptor must have been opened with the 144.\" .Dv O_SEARCH 145.\" flag. 146.Fa fd 147can be set to 148.Dv AT_FDCWD 149in order to specify the current directory. 150.Pp 151When it operates on a symbolic link, 152.Fn utimensat 153will change the target's time unless 154.Dv AT_SYMLINK_NOFOLLOW 155is set in 156.Fa flag . 157In that later case, the symbolic link's dates are changed. 158.Pp 159The nanosecond fields for 160.Fn utimens , 161.Fn lutimens , 162.Fn futimens , 163and 164.Fn utimensat 165can be set to the special value 166.Dv UTIME_NOW 167to set the current time, or to 168.Dv UTIME_OMIT 169to let the time unchanged (this allows changing access time but not 170modification time, and vice-versa). 171.Sh RETURN VALUES 172.Rv -std utimes lutimes futimes utimens lutimens futimens utimensat 173.Sh ERRORS 174.Fn utimes , 175.Fn lutimes , 176.Fn utimens , 177.Fn lutimens , 178and 179.Fn utimensat 180will fail if: 181.Bl -tag -width Er 182.It Bq Er EACCES 183Search permission is denied for a component of the path prefix; 184or the 185.Fa times 186argument is 187.Dv NULL 188and the effective user ID of the process does not 189match the owner of the file, and is not the super-user, and write 190access is denied. 191.It Bq Er EFAULT 192.Fa path 193or 194.Fa times 195points outside the process's allocated address space. 196.It Bq Er EIO 197An I/O error occurred while reading or writing the affected inode. 198.It Bq Er ELOOP 199Too many symbolic links were encountered in translating the pathname. 200.It Bq Er ENAMETOOLONG 201A component of a pathname exceeded 202.Brq Dv NAME_MAX 203characters, or an entire path name exceeded 204.Brq Dv PATH_MAX 205characters. 206.It Bq Er ENOENT 207The named file does not exist. 208.It Bq Er ENOTDIR 209A component of the path prefix is not a directory. 210.It Bq Er EPERM 211The 212.Fa times 213argument is not 214.Dv NULL 215and the calling process's effective user ID 216does not match the owner of the file and is not the super-user. 217.It Bq Er EROFS 218The file system containing the file is mounted read-only. 219.El 220.Pp 221In addition, 222.Fn utimensat 223will fail if: 224.Bl -tag -width Er 225.It Bq Er EBADF 226.Fa path 227does not specify an absolute path and 228.Fa fd 229is neither 230.Dv AT_FDCWD 231nor a valid file descriptor open for reading or searching. 232.It Bq Er ENOTDIR 233.Fa path 234is not an absolute path and 235.Fa fd 236is a file descriptor associated with a non-directory file. 237.El 238.Pp 239.Fn futimes 240and 241.Fn futimens 242will fail if: 243.Bl -tag -width Er 244.It Bq Er EACCES 245The 246.Fa times 247argument is 248.Dv NULL 249and the effective user ID of the process does not 250match the owner of the file, and is not the super-user, and write 251access is denied. 252.It Bq Er EBADF 253.Fa fd 254does not refer to a valid descriptor. 255.It Bq Er EFAULT 256.Fa times 257points outside the process's allocated address space. 258.It Bq Er EIO 259An I/O error occurred while reading or writing the affected inode. 260.It Bq Er EPERM 261The 262.Fa times 263argument is not 264.Dv NULL 265and the calling process's effective user ID 266does not match the owner of the file and is not the super-user. 267.It Bq Er EROFS 268The file system containing the file is mounted read-only. 269.El 270.Sh SEE ALSO 271.Xr stat 2 , 272.Xr utime 3 , 273.Xr symlink 7 274.Sh STANDARDS 275The 276.Fn utimes 277function conforms to 278.St -p1003.1-2001 . 279It was however marked as legacy in the 280.St -p1003.1-2004 281revision. 282.Fn futimens 283and 284.Fn utimensat 285functions conform to 286.St -p1003.1-2008 . 287.Sh HISTORY 288The 289.Fn utimes 290function call appeared in 291.Bx 4.2 . 292The 293.Fn futimes 294function call appeared in 295.Nx 1.2 . 296The 297.Fn lutimes 298function call appeared in 299.Nx 1.3 . 300Birthtime setting support was added in 301.Nx 5.0 . 302.Fn futimens 303and 304.Fn utimensat 305functions calls appeared in 306.Nx 6.0 . 307