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