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.Bl -tag -width indent 139.It Dv AT_SYMLINK_NOFOLLOW_ANY 140If 141.Fa path 142names a symbolic link, the symbolic link's times are changed. 143In addition, if any symbolic link is enountered during pathname 144resolution, an error is returned. 145By default, 146.Fn utimensat 147changes the times of the file referenced by the symbolic link. 148.El 149.Sh RETURN VALUES 150.Rv -std 151.Sh ERRORS 152These system calls will fail if: 153.Bl -tag -width Er 154.It Bq Er EACCES 155The 156.Fa times 157argument is 158.Dv NULL , 159or both 160.Va tv_nsec 161values are 162.Dv UTIME_NOW , 163and the effective user ID of the process does not 164match the owner of the file, and is not the super-user, and write 165access is denied. 166.It Bq Er EINVAL 167The 168.Va tv_nsec 169component of at least one of the values specified by the 170.Fa times 171argument has a value less than 0 or greater than 999999999 and is not equal to 172.Dv UTIME_NOW 173or 174.Dv UTIME_OMIT . 175.It Bq Er EIO 176An I/O error occurred while reading or writing the affected inode. 177.It Bq Er EPERM 178The 179.Fa times 180argument is not 181.Dv NULL 182nor are both 183.Va tv_nsec 184values 185.Dv UTIME_NOW , 186nor are both 187.Va tv_nsec 188values 189.Dv UTIME_OMIT 190and the calling process's effective user ID 191does not match the owner of the file and is not the super-user. 192.It Bq Er EPERM 193The named file has its immutable or append-only flag set, see the 194.Xr chflags 2 195manual page for more information. 196.It Bq Er EROFS 197The file system containing the file is mounted read-only. 198.El 199.Pp 200The 201.Fn futimens 202system call 203will fail if: 204.Bl -tag -width Er 205.It Bq Er EBADF 206The 207.Fa fd 208argument 209does not refer to a valid descriptor. 210.El 211.Pp 212The 213.Fn utimensat 214system call 215will fail if: 216.Bl -tag -width Er 217.It Bq Er EACCES 218Search permission is denied for a component of the path prefix. 219.It Bq Er EBADF 220The 221.Fa path 222argument does not specify an absolute path and the 223.Fa fd 224argument is neither 225.Dv AT_FDCWD 226nor a valid file descriptor. 227.It Bq Er EFAULT 228The 229.Fa path 230argument 231points outside the process's allocated address space. 232.It Bq Er ELOOP 233Too many symbolic links were encountered in translating the pathname. 234.It Bq Er ENAMETOOLONG 235A component of a pathname exceeded 236.Dv NAME_MAX 237characters, or an entire path name exceeded 238.Dv PATH_MAX 239characters. 240.It Bq Er ENOENT 241The named file does not exist. 242.It Bq Er ENOTDIR 243A component of the path prefix is not a directory. 244.It Bq Er ENOTDIR 245The 246.Fa path 247argument is not an absolute path and 248.Fa fd 249is neither 250.Dv AT_FDCWD 251nor a file descriptor associated with a directory. 252.El 253.Sh SEE ALSO 254.Xr chflags 2 , 255.Xr stat 2 , 256.Xr symlink 2 , 257.Xr utimes 2 , 258.Xr utime 3 , 259.Xr symlink 7 260.Sh STANDARDS 261The 262.Fn futimens 263and 264.Fn utimensat 265system calls are expected to conform to 266.St -p1003.1-2008 . 267