lib/libc/sys/utimensat.2

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