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