VMS Help
CRTL, utime
*Conan The Librarian
|
Sets file access and modification times.
Format
#include <utime.h>
int utime (const char *path, const struct utimbuf *times);
path
A pointer to a file.
times
A NULL pointer or a pointer to a utimbuf structure.
The utime function sets the access and modification times of the
filenamed by the path argument. The file must be openable for
write-access to use this function.
If times is a NULL pointer, the access and modification times of
the file are set to the current time. To use utime in this way,
the effective user ID of the process must match the owner of the
file, or the process must have write permission to the file or
have appropriate privileges.
If times is not a NULL pointer, it is interpreted as a pointer
to a utimbuf structure, and the access and modification times
are set to the values in the specified structure. Only a process
with an effective user ID equal to the user ID of the file or a
process with appropriate privileges can use utime this way.
The utimbuf structure is defined by the <utime.h> header. The
times in the utimbuf structure are measured in seconds since the
Epoch.
Upon successful completion, utime marks the time of the last file
status change, st_ctime, to be updated. See the <stat.h> header
file.
NOTE (Integrity servers, Alpha)
On OpenVMS Alpha and Integrity server systems, the stat,
fstat, utime, and utimes functions have been enhanced to
take advantage of the new file-system support for POSIX
compliant file timestamps.
This support is available only on ODS-5 devices on OpenVMS
Alpha systems beginning with a version of OpenVMS Alpha
after Version 7.3.
Before this change, stat and fstat set the values of the st_
ctime, st_mtime, and st_atime fields based on the following
file attributes:
st_ctime - ATR$C_CREDATE (file creation time)
st_mtime - ATR$C_REVDATE (file revision time)
st_atime - was always set to st_mtime because no support
for file access time was available
Also, for the file-modification time, utime and utimes were
modifying the ATR$C_REVDATE file attribute, and ignoring the
file-access-time argument.
After the change, for a file on an ODS-5 device, the stat
and fstat functions set the values of the st_ctime, st_
mtime, and st_atime fields based on the following new file
attributes:
st_ctime - ATR$C_ATTDATE (last attribute modification
time)
st_mtime - ATR$C_MODDATE (last data modification time)
st_atime - ATR$C_ACCDATE (last access time)
If ATR$C_ACCDATE is 0, as on an ODS-2 device, the stat and
fstat functions set st_atime to st_mtime.
For the file-modification time, the utime and utimes
functions modify both the ATR$C_REVDATE and ATR$C_MODDATE
file attributes. For the file-access time, these functions
modify the ATR$C_ACCDATE file attribute. Setting the ATR$C_
MODDATE and ATR$C_ACCDATE file attributes on an ODS-2 device
has no effect.
For compatibility, the old behavior of stat, fstat, utime,
and utimes remains the default, regardless of the kind of
device.
The new behavior must be explicitly enabled by defining the
DECC$EFS_FILE_TIMESTAMPS logical name to "ENABLE" before
invoking the application. Setting this logical does not
affect the behavior of stat, fstat, utime, and utimes for
files on an ODS-2 device.
0 Successful execution.
-1 Indicates an error. The function sets errno to
one of the following values:
The utime function will fail if:
o 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.
o ELOOP - Too many symbolic links were
encountered in resolving path.
o ENAMETOOLONG - The length of the path
argument exceeds PATH_MAX, a pathname
component is longer than NAME_MAX, or a
pathname resolution of a symbolic link
produced an intermediate result whose
length exceeds PATH_MAX.
o ENOENT - path does not name an existing
file, or path is an empty string.
o ENOTDIR - A component of the path prefix is
not a directory.
o EPERM - times is not a NULL pointer and
the calling process's 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.
o EROFS - The file system containing the file
is read-only.