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