Defect report from : Paul Eggert , UCLA
(Please direct followup comments direct to yyyyyyyyyyyyyy@xxxxxxxxxxxxx)
@ page 423 line 15014 section futimespecat objection {20060612d}
Problem:
Edition of Specification (Year): 2004
Defect code : 2. Omission
This Aardvark follows up on XSH ERN 138 (Defect in XSH utimes), and
addresses issues involving the proposed new system call. It
incorporates subsequent discussion in austin-review-l and
austin-group-l. I also looked at the FreeBSD primitives lutimes and
futimes, and at one other common complaint about the existing
interfaces (namely, there is no way to set only the modification time,
or only the access time, without running into race conditions).
The proposed call is not existing practice, but it does specify
behavior that would be quite useful in implementing applications like
tar, cp -p, and touch, which must copy file timestamps reliably.
These applications cannot be implemented with current standard
interfaces (or even with nonstandard but widely available interfaces).
This action proposes the name 'futimespecat' instead of 'futimesat'
for the new primitive that uses struct timespec to specify the file
timestamps. One might argue that the name should be
'posix_futimespecat' since it would be a committee invention. I chose
the name 'futimespecat' to make it similar to the ones proposed in the
Extended API Set Part 2 (January 2006), but don't have a strong
feeling about the name. Similarly for the name 'futimespec' proposed
below.
Action:
1. Remove the LEGACY marking from utimes(), and add it instead to
utime(). Move the "Future Directions" of utimes() to utime().
2. Remove utimes().
3. Remove futimesat() as proposed by Extended API Set Part 2 (January
2006), page 17, lines 370-411.
4. After XBD page 423 line 15014 insert:
The structure utimespec shall be defined, which shall include the
following members:
struct timespec actime Access time.
struct timespec modtime Modification time.
The timespec structure shall be defined as described in <time.h>.
Values for tv_nsec used by futimespec() and futimespecat()
(the following values are unique, and shall be negative 'int's)
are as follows:
UTIME_OMIT
UTIME_NOW
After line 15019 insert:
int futimespec(int, const struct utimespec *);
int futimespecat(int, const char *, const struct utimespec *, int);
5. Introduce two new functions as follows:
NAME
futimespec, futimespecat - set file access and modification times
SYNOPSIS
#include <utime.h>
int futimespec(int filedes, const struct utimespec *times);
int futimespecat(int filedes, const char *path,
const struct utimespec *times, int flag);
DESCRIPTION
The futimespec() function shall set the last access and last data
modification times of the file associated with the open file
descriptor filedes to the value specified by 'times'.
The futimespecat() function shall set the last access and last
data modification times of the file named by the path argument,
relative to the directory associated with file descriptor filedes,
to the value specified by 'times'. If filedes is set
to the special value AT_FDCWD, defined in <fcntl.h>, relative
pathnames are relative to the current working directory. If the
path is an absolute path, the filedes argument is ignored.
'flag' is reserved for future use and should be zero.
If the tv_nsec field of a struct timespec has the special value
UTIME_NOW, defined in <utime.h>, the structure stands for the
current time. If it has the special value UTIME_OMIT, the file's
time is not changed. In either case, the tv_sec field is ignored.
If either times->actime.tv_nsec or times->modtime.tv_nsec is
UTIME_NOW, the effective user ID of the process shall match the
owner of the file, or the process shall have write permission to
the file or shall have appropriate privileges, to use these
functions in this manner.
If times->actime.tv_nsec is neither UTIME_OMIT nor UTIME_NOW, the
last access time shall be set to the value specified by
times->actime. Similarly, times->modtime.tv_nsec is neither
UTIME_OMIT nor UTIME_NOW, the last data modification time shall be
set to the value specified by times->modtime. Only a process with
the effective user ID equal to the user ID of the file or a
process with appropriate privileges may use these functions this
way.
The utimespec structure is defined in the <utime.h> header. The
times in the structure utimespec are measured in seconds since the
Epoch.
Upon successful completion, these functions shall mark the time of
the last file status change, st_ctim, for update; see
<sys/stat.h>.
RETURN VALUE
Upon successful completion, 0 shall be returned. Otherwise, -1
shall be returned and errno shall be set to indicate the error,
and the file times shall not be affected.
ERRORS
The futimespec() and futimespecat() functions shall fail if:
[EPERM]
Neither UTIME_ANOW nor UTIME_ANOW is specified, or neither
UTIME_MNOW nor UTIME_MNOW is specified; and the calling
process' effective user ID has write access to the file but
does not match the owner of the file; and the calling process
does not have the appropriate privileges.
[EROFS]
The file resides on a read-only file system.
The futimespec() and futimespecat() functions may fail if:
[EINVAL]
The value of the flag argument is not valid.
[EINVAL]
A new file timestamp would be a value whose tv_sec component
is not a value supported by file system.
[EINVAL]
times->actime.tv_nsec is neither UTIME_NOW nor UTIME_OMIT,
and is either negative or greater than 999999.
[EINVAL]
times->modtime.tv_nsec is neither UTIME_NOW nor UTIME_OMIT,
and is either negative or greater than 999999.
The futimespec() function shall fail if:
[EBADF]
The filedes argument is not an open file descriptor.
The futimespecat() function shall fail if:
[EACCES]
Search permission is denied by a component of the path prefix;
or the 'times' argument is a null pointer and the effective
user ID of the process does not match the owner of the file,
the process does not have write permission for the file, and
the process does not have appropriate privileges.
[EBADF]
The path argument does not specify an absolute path and the
filedes argument is neither AT_FDCWD nor a valid file
descriptor.
[ELOOP]
A loop exists in symbolic links encountered during resolution
of the path argument.
[ENAMETOOLONG]
The length of the path argument exceeds {PATH_MAX} or a
pathname component is longer than {NAME_MAX}.
[ENOENT]
A component of 'path' does not name an existing file or 'path'
is an empty string.
[ENOTDIR]
A component of the path prefix is not a directory.
The futimespecat() function may fail if:
[ENOTDIR]
The path argument is not an absolute path and filedes is
neither AT_FDCWD nor a file descriptor associated with a
directory.
[ELOOP]
More than {SYMLOOP_MAX} symbolic links were encountered during
resolution of the path argument.
[ENAMETOOLONG]
As a result of encountering a symbolic link in resolution of
the path argument, the length of the substituted pathname
string exceeded {PATH_MAX}.
SEE ALSO
utime()
RATIONALE
The 'flag' argument of futimespecat() is intended for future
extension or implementation-defined use. For example, if symbolic
links have timestamps, a 'flag' of AT_SYMLINK_NOFOLLOW might cause
futimespecat() to not follow symbolic links.
|