123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308 |
- .\" $NetBSD: utimes.2,v 1.13 1999/03/22 19:45:11 garbled Exp $
- .\"
- .\" Copyright (c) 1990, 1993
- .\" The Regents of the University of California. All rights reserved.
- .\" Copyright (c) 2012, Jilles Tjoelker
- .\"
- .\" Redistribution and use in source and binary forms, with or without
- .\" modification, are permitted provided that the following conditions
- .\" are met:
- .\" 1. Redistributions of source code must retain the above copyright
- .\" notice, this list of conditions and the following disclaimer.
- .\" 2. Redistributions in binary form must reproduce the above copyright
- .\" notice, this list of conditions and the following disclaimer in the
- .\" documentation and/or other materials provided with the distribution.
- .\" 3. Neither the name of the University nor the names of its contributors
- .\" may be used to endorse or promote products derived from this software
- .\" without specific prior written permission.
- .\"
- .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
- .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
- .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
- .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
- .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
- .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
- .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
- .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
- .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
- .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
- .\" SUCH DAMAGE.
- .\"
- .Dd June 12, 2022
- .Dt UTIMENSAT 2
- .Os
- .Sh NAME
- .Nm futimens ,
- .Nm utimensat
- .Nd set file access and modification times
- .Sh LIBRARY
- .Lb libc
- .Sh SYNOPSIS
- .In sys/stat.h
- .Ft int
- .Fn futimens "int fd" "const struct timespec times[2]"
- .Ft int
- .Fo utimensat
- .Fa "int fd"
- .Fa "const char *path"
- .Fa "const struct timespec times[2]"
- .Fa "int flag"
- .Fc
- .Sh DESCRIPTION
- The access and modification times of the file named by
- .Fa path
- or referenced by
- .Fa fd
- are changed as specified by the argument
- .Fa times .
- The inode-change-time of the file is set to the current time.
- .Pp
- If
- .Fa path
- specifies a relative path,
- it is relative to the current working directory if
- .Fa fd
- is
- .Dv AT_FDCWD
- and otherwise relative to the directory associated with the file descriptor
- .Fa fd .
- .Pp
- The
- .Va tv_nsec
- field of a
- .Vt timespec
- structure
- can be set to the special value
- .Dv UTIME_NOW
- to set the current time, or to
- .Dv UTIME_OMIT
- to leave the time unchanged.
- In either case, the
- .Va tv_sec
- field is ignored.
- .Pp
- If
- .Fa times
- is
- .No non- Ns Dv NULL ,
- it is assumed to point to an array of two timespec structures.
- The access time is set to the value of the first element, and the
- modification time is set to the value of the second element.
- For file systems that support file birth (creation) times (such as
- .Dv UFS2 ) ,
- the birth time will be set to the value of the second element
- if the second element is older than the currently set birth time.
- To set both a birth time and a modification time,
- two calls are required; the first to set the birth time
- and the second to set the (presumably newer) modification time.
- Ideally a new system call will be added that allows the setting
- of all three times at once.
- If
- .Fa times
- is
- .Dv NULL ,
- this is equivalent to passing
- a pointer to an array of two timespec structures
- with both
- .Va tv_nsec
- fields set to
- .Dv UTIME_NOW .
- .Pp
- If both
- .Va tv_nsec
- fields are
- .Dv UTIME_OMIT ,
- the timestamps remain unchanged and
- no permissions are needed for the file itself,
- although search permissions may be required for the path prefix.
- The call may or may not succeed if the named file does not exist.
- .Pp
- If both
- .Va tv_nsec
- fields are
- .Dv UTIME_NOW ,
- the caller must be the owner of the file, have permission to
- write the file, or be the super-user.
- .Pp
- For all other values of the timestamps,
- the caller must be the owner of the file or be the super-user.
- .Pp
- The values for the
- .Fa flag
- argument of the
- .Fn utimensat
- system call
- are constructed by a bitwise-inclusive OR of flags from the following list,
- defined in
- .In fcntl.h :
- .Bl -tag -width indent
- .It Dv AT_SYMLINK_NOFOLLOW
- If
- .Fa path
- names a symbolic link, the symbolic link's times are changed.
- By default,
- .Fn utimensat
- changes the times of the file referenced by the symbolic link.
- .It Dv AT_RESOLVE_BENEATH
- Only walk paths below the directory specified by the
- .Ar fd
- descriptor.
- See the description of the
- .Dv O_RESOLVE_BENEATH
- flag in the
- .Xr open 2
- manual page.
- .It Dv AT_EMPTY_PATH
- If the
- .Fa path
- argument is an empty string, operate on the file or directory
- referenced by the descriptor
- .Fa fd .
- If
- .Fa fd
- is equal to
- .Dv AT_FDCWD ,
- operate on the current working directory.
- .El
- .Sh RETURN VALUES
- .Rv -std
- .Sh ERRORS
- These system calls will fail if:
- .Bl -tag -width Er
- .It Bq Er EACCES
- The
- .Fa times
- argument is
- .Dv NULL ,
- or both
- .Va tv_nsec
- values are
- .Dv UTIME_NOW ,
- and the effective user ID of the process does not
- match the owner of the file, and is not the super-user, and write
- access is denied.
- .It Bq Er EFAULT
- The
- .Fa times
- argument
- points outside the process's allocated address space.
- .It Bq Er EINVAL
- The
- .Va tv_nsec
- component of at least one of the values specified by the
- .Fa times
- argument has a value less than 0 or greater than 999999999 and is not equal to
- .Dv UTIME_NOW
- or
- .Dv UTIME_OMIT .
- .It Bq Er EIO
- An I/O error occurred while reading or writing the affected inode.
- .It Bq Er EINTEGRITY
- Corrupted data was detected while reading from the file system.
- .It Bq Er EPERM
- The
- .Fa times
- argument is not
- .Dv NULL
- nor are both
- .Va tv_nsec
- values
- .Dv UTIME_NOW ,
- nor are both
- .Va tv_nsec
- values
- .Dv UTIME_OMIT
- and the calling process's effective user ID
- does not match the owner of the file and is not the super-user.
- .It Bq Er EPERM
- The named file has its immutable or append-only flag set, see the
- .Xr chflags 2
- manual page for more information.
- .It Bq Er EROFS
- The file system containing the file is mounted read-only.
- .El
- .Pp
- The
- .Fn futimens
- system call
- will fail if:
- .Bl -tag -width Er
- .It Bq Er EBADF
- The
- .Fa fd
- argument
- does not refer to a valid descriptor.
- .El
- .Pp
- The
- .Fn utimensat
- system call
- will fail if:
- .Bl -tag -width Er
- .It Bq Er EACCES
- Search permission is denied for a component of the path prefix.
- .It Bq Er EBADF
- The
- .Fa path
- argument does not specify an absolute path and the
- .Fa fd
- argument is neither
- .Dv AT_FDCWD
- nor a valid file descriptor.
- .It Bq Er EFAULT
- The
- .Fa path
- argument
- points outside the process's allocated address space.
- .It Bq Er ELOOP
- Too many symbolic links were encountered in translating the pathname.
- .It Bq Er ENAMETOOLONG
- A component of a pathname exceeded
- .Dv NAME_MAX
- characters, or an entire path name exceeded
- .Dv PATH_MAX
- characters.
- .It Bq Er ENOENT
- The named file does not exist.
- .It Bq Er ENOTDIR
- A component of the path prefix is not a directory.
- .It Bq Er ENOTDIR
- The
- .Fa path
- argument is not an absolute path and
- .Fa fd
- is neither
- .Dv AT_FDCWD
- nor a file descriptor associated with a directory.
- .It Bq Er ENOTCAPABLE
- .Fa path
- is an absolute path,
- or contained a ".." component leading to a
- directory outside of the directory hierarchy specified by
- .Fa fd ,
- and the process is in capability mode or the
- .Dv AT_RESOLVE_BENEATH
- flag was specified.
- .El
- .Sh SEE ALSO
- .Xr chflags 2 ,
- .Xr stat 2 ,
- .Xr symlink 2 ,
- .Xr utimes 2 ,
- .Xr utime 3 ,
- .Xr symlink 7
- .Sh STANDARDS
- The
- .Fn futimens
- and
- .Fn utimensat
- system calls are expected to conform to
- .St -p1003.1-2008 .
- .Sh HISTORY
- The
- .Fn futimens
- and
- .Fn utimensat
- system calls appeared in
- .Fx 10.3 .
|