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.\" Copyright (c) 2012, Jilles Tjoelker 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.\" $FreeBSD$ 33.\" 34.Dd January 17, 2016 35.Dt UTIMENSAT 2 36.Os 37.Sh NAME 38.Nm futimens , 39.Nm utimensat 40.Nd set file access and modification times 41.Sh SYNOPSIS 42.In sys/stat.h 43.Ft int 44.Fn futimens "int fd" "const struct timespec times[2]" 45.Ft int 46.Fo utimensat 47.Fa "int fd" 48.Fa "const char *path" 49.Fa "const struct timespec times[2]" 50.Fa "int flag" 51.Fc 52.Sh DESCRIPTION 53The access and modification times of the file named by 54.Fa path 55or referenced by 56.Fa fd 57are changed as specified by the argument 58.Fa times . 59The inode-change-time of the file is set to the current time. 60.Pp 61If 62.Fa path 63specifies a relative path, 64it is relative to the current working directory if 65.Fa fd 66is 67.Dv AT_FDCWD 68and otherwise relative to the directory associated with the file descriptor 69.Fa fd . 70.Pp 71The 72.Va tv_nsec 73field of a 74.Vt timespec 75structure 76can be set to the special value 77.Dv UTIME_NOW 78to set the current time, or to 79.Dv UTIME_OMIT 80to leave the time unchanged. 81In either case, the 82.Va tv_sec 83field is ignored. 84.Pp 85If 86.Fa times 87is 88.No non- Ns Dv NULL , 89it is assumed to point to an array of two timespec structures. 90The access time is set to the value of the first element, and the 91modification time is set to the value of the second element. 92If 93.Fa times 94is 95.Dv NULL , 96this is equivalent to passing 97a pointer to an array of two timespec structures 98with both 99.Va tv_nsec 100fields set to 101.Dv UTIME_NOW . 102.Pp 103If both 104.Va tv_nsec 105fields are 106.Dv UTIME_OMIT , 107the timestamps remain unchanged and 108no permissions are needed for the file itself, 109although search permissions may be required for the path prefix. 110The call may or may not succeed if the named file does not exist. 111.Pp 112If both 113.Va tv_nsec 114fields are 115.Dv UTIME_NOW , 116the caller must be the owner of the file, have permission to 117write the file, or be the super-user. 118.Pp 119For all other values of the timestamps, 120the caller must be the owner of the file or be the super-user. 121.Pp 122The values for the 123.Fa flag 124argument of the 125.Fn utimensat 126system call 127are constructed by a bitwise-inclusive OR of flags from the following list, 128defined in 129.In fcntl.h : 130.Bl -tag -width indent 131.It Dv AT_SYMLINK_NOFOLLOW 132If 133.Fa path 134names a symbolic link, the symbolic link's times are changed. 135By default, 136.Fn utimensat 137changes the times of the file referenced by the symbolic link. 138.El 139.Sh RETURN VALUES 140.Rv -std 141.Sh ERRORS 142These system calls will fail if: 143.Bl -tag -width Er 144.It Bq Er EACCES 145The 146.Fa times 147argument is 148.Dv NULL , 149or both 150.Va tv_nsec 151values are 152.Dv UTIME_NOW , 153and the effective user ID of the process does not 154match the owner of the file, and is not the super-user, and write 155access is denied. 156.It Bq Er EINVAL 157The 158.Va tv_nsec 159component of at least one of the values specified by the 160.Fa times 161argument has a value less than 0 or greater than 999999999 and is not equal to 162.Dv UTIME_NOW 163or 164.Dv UTIME_OMIT . 165.It Bq Er EIO 166An I/O error occurred while reading or writing the affected inode. 167.It Bq Er EPERM 168The 169.Fa times 170argument is not 171.Dv NULL 172nor are both 173.Va tv_nsec 174values 175.Dv UTIME_NOW , 176nor are both 177.Va tv_nsec 178values 179.Dv UTIME_OMIT 180and the calling process's effective user ID 181does not match the owner of the file and is not the super-user. 182.It Bq Er EPERM 183The named file has its immutable or append-only flag set, see the 184.Xr chflags 2 185manual page for more information. 186.It Bq Er EROFS 187The file system containing the file is mounted read-only. 188.El 189.Pp 190The 191.Fn futimens 192system call 193will fail if: 194.Bl -tag -width Er 195.It Bq Er EBADF 196The 197.Fa fd 198argument 199does not refer to a valid descriptor. 200.El 201.Pp 202The 203.Fn utimensat 204system call 205will fail if: 206.Bl -tag -width Er 207.It Bq Er EACCES 208Search permission is denied for a component of the path prefix. 209.It Bq Er EBADF 210The 211.Fa path 212argument does not specify an absolute path and the 213.Fa fd 214argument is neither 215.Dv AT_FDCWD 216nor a valid file descriptor. 217.It Bq Er EFAULT 218The 219.Fa path 220argument 221points outside the process's allocated address space. 222.It Bq Er ELOOP 223Too many symbolic links were encountered in translating the pathname. 224.It Bq Er ENAMETOOLONG 225A component of a pathname exceeded 226.Dv NAME_MAX 227characters, or an entire path name exceeded 228.Dv PATH_MAX 229characters. 230.It Bq Er ENOENT 231The named file does not exist. 232.It Bq Er ENOTDIR 233A component of the path prefix is not a directory. 234.It Bq Er ENOTDIR 235The 236.Fa path 237argument is not an absolute path and 238.Fa fd 239is neither 240.Dv AT_FDCWD 241nor a file descriptor associated with a directory. 242.El 243.Sh SEE ALSO 244.Xr chflags 2 , 245.Xr stat 2 , 246.Xr symlink 2 , 247.Xr utimes 2 , 248.Xr utime 3 , 249.Xr symlink 7 250.Sh STANDARDS 251The 252.Fn futimens 253and 254.Fn utimensat 255system calls are expected to conform to 256.St -p1003.1-2008 . 257