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 June 9, 2016 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 ELOOP 169Too many symbolic links were encountered in translating the pathname. 170.It Bq Er ENAMETOOLONG 171A component of a pathname exceeded 172.Dv NAME_MAX 173characters, or an entire path name exceeded 174.Dv PATH_MAX 175characters. 176.It Bq Er ENOENT 177The named file does not exist. 178.It Bq Er ENOTDIR 179A component of the path prefix is not a directory. 180.It Bq Er EPERM 181The 182.Fa times 183argument is not 184.Dv NULL 185and the calling process's effective user ID 186does not match the owner of the file and is not the super-user. 187.It Bq Er EPERM 188The named file has its immutable or append-only flags set. 189See the 190.Xr chflags 2 191manual page for more information. 192.It Bq Er EROFS 193The file system containing the file is mounted read-only. 194.El 195.Pp 196The 197.Fn futimes 198system call 199will fail if: 200.Bl -tag -width Er 201.It Bq Er EBADF 202The 203.Fa fd 204argument 205does not refer to a valid descriptor. 206.El 207.Pp 208In addition to the errors returned by the 209.Fn utimes , 210the 211.Fn futimesat 212may fail if: 213.Bl -tag -width Er 214.It Bq Er EBADF 215The 216.Fa path 217argument does not specify an absolute path and the 218.Fa fd 219argument is neither 220.Dv AT_FDCWD 221nor a valid file descriptor open for searching. 222.It Bq Er ENOTDIR 223The 224.Fa path 225argument is not an absolute path and 226.Fa fd 227is neither 228.Dv AT_FDCWD 229nor a file descriptor associated with a directory. 230.El 231.Sh SEE ALSO 232.Xr chflags 2 , 233.Xr stat 2 , 234.Xr utimensat 2 , 235.Xr utime 3 236.Sh STANDARDS 237The 238.Fn utimes 239function is expected to conform to 240.St -xpg4.2 . 241The 242.Fn futimesat 243system call follows The Open Group Extended API Set 2 specification 244but was replaced by 245.Fn utimensat 246in 247.St -p1003.1-2008 . 248.Sh HISTORY 249The 250.Fn utimes 251system call appeared in 252.Bx 4.2 . 253The 254.Fn futimes 255and 256.Fn lutimes 257system calls first appeared in 258.Fx 3.0 . 259The 260.Fn futimesat 261system call appeared in 262.Fx 8.0 . 263