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.\" 4. 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 May 26, 2015 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_usec 166component of at least one of the values specified by the 167.Fa times 168argument has a value less than 0 or greater than 999999. 169.It Bq Er EIO 170An I/O error occurred while reading or writing the affected inode. 171.It Bq Er EPERM 172The 173.Fa times 174argument is not 175.Dv NULL 176nor are both 177.Va tv_nsec 178values 179.Dv UTIME_NOW , 180nor are both 181.Va tv_nsec 182values 183.Dv UTIME_OMIT 184and the calling process's effective user ID 185does not match the owner of the file and is not the super-user. 186.It Bq Er EPERM 187The named file has its immutable or append-only flag set, see the 188.Xr chflags 2 189manual page for more information. 190.It Bq Er EROFS 191The file system containing the file is mounted read-only. 192.El 193.Pp 194The 195.Fn futimens 196system call 197will fail if: 198.Bl -tag -width Er 199.It Bq Er EBADF 200The 201.Fa fd 202argument 203does not refer to a valid descriptor. 204.El 205.Pp 206The 207.Fn utimensat 208system call 209will fail if: 210.Bl -tag -width Er 211.It Bq Er EACCES 212Search permission is denied for a component of the path prefix. 213.It Bq Er EBADF 214The 215.Fa path 216argument does not specify an absolute path and the 217.Fa fd 218argument is neither 219.Dv AT_FDCWD 220nor a valid file descriptor. 221.It Bq Er EFAULT 222The 223.Fa path 224argument 225points outside the process's allocated address space. 226.It Bq Er ELOOP 227Too many symbolic links were encountered in translating the pathname. 228.It Bq Er ENAMETOOLONG 229A component of a pathname exceeded 230.Dv NAME_MAX 231characters, or an entire path name exceeded 232.Dv PATH_MAX 233characters. 234.It Bq Er ENOENT 235The named file does not exist. 236.It Bq Er ENOTDIR 237A component of the path prefix is not a directory. 238.It Bq Er ENOTDIR 239The 240.Fa path 241argument is not an absolute path and 242.Fa fd 243is neither 244.Dv AT_FDCWD 245nor a file descriptor associated with a directory. 246.It Bq Er ENOTSUP 247The running kernel does not support this system call and 248.Dv AT_SYMLINK_NOFOLLOW 249is used with a path relative to a file descriptor. 250.El 251.Sh SEE ALSO 252.Xr chflags 2 , 253.Xr stat 2 , 254.Xr symlink 2 , 255.Xr utimes 2 , 256.Xr utime 3 , 257.Xr symlink 7 258.Sh STANDARDS 259The 260.Fn futimens 261and 262.Fn utimensat 263system calls are expected to conform to 264.St -p1003.1-2008 . 265.Sh HISTORY 266The 267.Fn futimens 268and 269.Fn utimensat 270system calls appeared in 271.Dx 4.1 . 272