Defect report from : Nick Stoughton , USENIX Association
(Please direct followup comments direct to yyyyyyyyyyyyyy@xxxxxxxxxxxxx)
@ page 1591 line 49509 section utimes objection {nms-finegrain}
Problem:
Edition of Specification (Year): 2004
Defect code : 2. Omission
The utimes() function is currently marked as being a part of the "LEGACY"
option-group of the XSI option. As such, it is a candidate for removal
at the next revision (which is now in progress). The future directions
on line 49559 also state this. However, it provides a method for
setting file access and modification times with micro-second accuracy.
The "replacement" function, utime() (see p1592, lines 49554-49555)
provides less functionality, in that it has only 1 second granularity.
As system clocks gets faster and faster, the need for sub-second accuracy
on file time stamps gets more and more urgent. Removing utimes() in
favor of utime() would be a major mistake.
Instead, interfaces should be added or extended to provide nano-second
granularity.
Action:
1. Remove the LEGACY marking from utimes(), and add it instead to utime().
Move the "Future Directions" of utimes() to utime().
2. Introduce a new function, posix_utimens_at() [[or posix_utime_at()]]:
NAME
posix_utimens_at - set file access and modification times
SYNOPSIS
#include <sys/time.h>
int posix_utimens_at(int fd, const char *path, const struct timespec
times[2]);
DESCRIPTION
The posix_utimens_at() function shall set the access and modification
times of the file pointed to by the path argument, relative to
the directory associated with file descriptor fd, to the value of
the times argument. If fd is set to the special value AT_FDCWD,
relative pathnames are relative to the current working directory. If
the path is an absolute path, the fd argument is ignored. The
posix_utimens_at() function allows time specifications accurate to
the nanosecond.
For posix_utimens_at(), the times argument is an array of timespec
structures. The first array member represents the date and time of
last access, and the second member represents the date and time of
last modification. The times in the timespec structure are measured
in seconds and nanoseconds since the Epoch, although rounding toward
the nearest second may occur.
If the times argument is a null pointer, the access and modification
times of the file shall be set to the current time. The effective
user ID of the process shall match the owner of the file, or has
write access to the file or appropriate privileges to use this call
in this manner. Upon completion, posix_utimens_at() shall mark the time
of the last file status change, st_ctime, for update.
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 posix_utimens_at() 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 and write
access is denied.
[EBADF]
The path argument does not specify an absolute path and the fd 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.
[EPERM]
The times argument is not a null pointer 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 system containing the file is read-only.
The posix_utimens_at() function may fail if:
[EINVAL] The value of the flag argument is not valid.
[ENOTDIR] The path argument is not an absolute path and fd 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]
Pathname resolution of a symbolic link produced an intermediate result
whose length exceeds {PATH_MAX}.
The following sections are informative.
EXAMPLES
None.
APPLICATION USAGE
None.
RATIONALE
None.
FUTURE DIRECTIONS
None.
SEE ALSO
utime(), the Base Definitions volume of IEEE Std 1003.1-2001, <sys/time.h>
utimes(), the Base Definitions volume of IEEE Std 1003.1-2001, <sys/time.h>
futimesat(), the Open Group API extensions
CHANGE HISTORY
First released in Issue 7, Version 1.
3. Also, since there has long been a method to set file timestamps to
subsecond accuracy (and with the change above, to nanosecond accuracy),
a method to fetch timestamps with a similar degree of accuracy is highly
desirable. The spec currently hints at this on line 12723, where
permission is given for namespace pollution with the timespec structure.
All known implementations currently do have the space in
the stat structure to also return this subsecond accurate
information. Therefore, make the following change to the sys/stat.h
page: XBD 360, line 12713-12715:
Change the following:
time_t st_atime Time of last access.
time_t st_mtime Time of last data modification.
time_t st_ctime Time of last status change.
to:
time_t st_atime Time of last access, seconds part
time_t st_mtime Time of last data modification, seconds part
time_t st_ctime Time of last status change, seconds part
long st_atime_nsec Time of last access, nanoseconds part
long st_mtime_nsec Time of last data modification, nanoseconds part
long st_ctime_nsec Time of last status change, nanoseconds part
Add at line 12723:
The names "st_atimespec", "st_mtimespec", and "st_ctimespec" are used in this
specification to refer to the combination of the seconds and nanoseconds parts
of the respective time value. However, the specification does not require
these names to actually exist.
GLOBAL-CHANGE: st_ctime to st_ctimespec, st_mtime to st_mtimespec, and st_atime
to st_atimespec
|