Integrated File System APIs--Time Stamp Updates

Each object (file and directory) has three time values associated with it:

Access Time The time that the data in the object is accessed.
Change Time The time that the attributes of the object are changed.
Modify Time The time that the data in the object is changed.

These values are returned by the stat(), fstat(), lstat(), and QlgStat() APIs.

When it is stated that an API sets or updates one of these time values, the value may be "marked for update" by the API rather than actually updated. When a subsequent stat(), fstat(), lstat(), and QlgStat() API is called, or the file is closed by all processes, the times that were previously "marked for update" are updated and the update marks are cleared.

The value of these times is measured in seconds since the Epoch. The Epoch is the time 0 hours, 0 minutes, 0 seconds, January 1, 1970, Coordinated Universal Time. If the system date is set prior to 1970, all time values will be zero. The following table shows which of these times are "marked for update" by each of the APIs.

Time Stamp Updates for Integrated File System APIs
Function Access Change Modify
access No No No
accessx No No No
chdir No No No
chmod No Yes No
chown No Yes No
close No No No
closedir No No No
creat1 (new file) Yes Yes Yes
creat1 (parent directory of new file) No Yes Yes
creat2 (existing file) No Yes Yes
DosSetFileLocks No No No
DosSetRelMaxFH No No No
dup No No No
dup2 No No No
faccessx No No No
fchdir No No No
fchmod No Yes No
fchown No Yes No
fclear No Yes Yes
fclear64 No Yes Yes
fcntl No No No
fpathconf No No No
fstat No No No
fstatvfs No No No
fsync No No No
ftruncate No Yes Yes
getcwd Yes3 No No
getegid No No No
geteuid No No No
getgid No No No
getgrgid No No No
getgrgid_r No No No
getgrnam No No No
getgrnam_r No No No
getgroups No No No
getpwnam No No No
getpwnam_r No No No
getpwuid No No No
getpwuid_r No No No
getuid No No No
givedescriptor No No No
ioctl No No No
lchown No Yes No
link4 (file) No Yes No
link4 (parent directory) No Yes Yes
lseek No No No
lstat No No No
mkdir5 (new directory) Yes Yes Yes
mkdir5 (parent directory) No Yes Yes
mkfifo6 (new directory) Yes Yes Yes
mkfifo6 (parent directory) No Yes Yes
open O_CREAT7 (new file) Yes Yes Yes
open O_CREAT7 (parent directory) No Yes Yes
open O_TRUNC8 (existing file) No Yes Yes
open9 (existing file) No No No
opendir No No No
pathconf No No No
pread Yes14 No No
pread64 Yes14 No No
pwrite No Yes Yes
pwrite64 No Yes Yes
QlgAccess No No No
QlgAccessx No No No
QlgChdir No No No
QlgChmod No Yes No
QlgChown No Yes No
QlgCreat1 (new file) Yes Yes Yes
QlgCreat1 (parent directory of new file) No Yes Yes
QlgCreat2 (existing file) No Yes Yes
QlgCvtPathToQSYSObjName No No No
QlgGetAttr No Yes No
QlgGetcwd Yes3 No No
QlgGetPathFromFileID Yes10 No No
QlgLchown No Yes No
QlgLink4 (file) No Yes No
QlgLink4 (parent directory) No Yes Yes
QlgLstat No No No
QlgMkdir5 (new directory) Yes Yes Yes
QlgMkdir5 (parent directory) No Yes Yes
QlgMkfifo5 (new directory) Yes Yes Yes
QlgMkfifo5 (parent directory) No Yes Yes
QlgOpen O_CREAT7 (new file) Yes Yes Yes
QlgOpen O_CREAT7 (parent directory) No Yes Yes
QlgOpen O_TRUNC8 (existing file) No Yes Yes
QlgOpen9 (existing file) No No No
QlgOpendir No No No
QlgPathconf No No No
QlgProcessSubtree Yes No No
QlgReaddir Yes No No
QlgReaddir_r Yes No No
QlgReadlink Yes No No
QlgRenameKeep (parent directories) No Yes Yes
QlgRenameUnlink (parent directories) No Yes Yes
QlgRmdir (parent directory) No Yes Yes
QlgSetAttr No Yes No
QlgStat No No No
QlgStatvfs No No No
QlgSymlink11 (new link) Yes Yes Yes
QlgSymlink11 (parent directory) No Yes Yes
QlgUtime13 No Yes No
QlgUnlink12 (file) No Yes No
QlgUnlink12 (parent directory) No Yes Yes
QP0FPTOS Yes No No
QP0LCHSG No No No
Qp0lCvtPathToQSYSObjName No No No
Qp0lGetAttr No Yes No
Qp0lGetPathFromFileID Yes10 No No
Qp0lProcessSubtree Yes No No
Qp0lRenameKeep (parent directories) No Yes Yes
Qp0lRenameUnlink (parent directories) No Yes Yes
QP0LROR No No No
QP0LRRO No No No
QP0LRTSG No No No
Qp0lSetAttr No Yes No
qsysetegid() No No No
qsyseteuid() No No No
qsysetgid() No No No
qsysetregid() No No No
qsysetreuid() No No No
qsysetuid() No No No
read Yes14 No No
readv Yes14 No No
readdir Yes No No
readdir_r Yes No No
readlink Yes No No
rewinddir No No No
rmdir (parent directory) No Yes Yes
select No No No
stat No No No
statvfs No No No
symlink11 (new link) Yes Yes Yes
symlink11 (parent directory) No Yes Yes
sysconf No No No
takedescriptor No No No
umask No No No
unlink12 (file) No Yes No
unlink12 (parent directory) No Yes Yes
utime13 No Yes No
write No Yes Yes
writev No Yes Yes
Notes:
  1. When the file did not previously exist, a successful creat() or QlgCreat() set the access, change, and modification times for the new file. It also sets the change and modification times of the directory that contains the new file (parent directory).

  2. When the file previously existed, a successful creat() or QlgCreat() sets the change and modification times for the file.

  3. The access time of each directory in the absolute path name of the current directory (excluding the current directory itself) is updated.

  4. A successful link() or QlgLink() sets the change time of the file and the change and modification times of the directory that contains the new link (parent directory).

  5. A successful mkdir() or QlgMkdir() sets the access, change, and modification times for the new directory. It also sets the change and modification times of the directory that contains the new directory (parent directory).

  6. A successful mkfifo() or QlgMkfifo() sets the access, change, and modification times for the new FIFO (first-in-first-out) special file. It also sets the change and modification times of the parent directory that contains the new FIFO file.

  7. When O_CREAT is specified and the file did not previously exist, a successful open() or QlgOpen() sets the access, change, and modification times for the new file. It also sets the change and modification times of the directory that contains the new file (parent directory).

  8. When O_TRUNC is specified and the file previously existed, a successful open() or QlgOpen() sets the change and modification times for the file.

  9. When O_CREAT and O_TRUNC are not specified, open() or QlgOpen() does not update any time stamps.

  10. A successful Qp0lGetPathFromFileID() or QlgGetPathFromFileID() sets the access time of each directory in the absolute path name to the file.

  11. A successful symlink() or QlgSymlink() sets the access, change, and modification times for the new symbolic link. It also sets the change and modification times of the directory that contains the new directory (parent directory).

  12. A successful unlink() or QlgUnlink() sets the change and modification times of the directory that contains the file being unlinked (parent directory). If the link count for the file is not zero, the change time for the file is set.

  13. A successful utime() or QlgUtime() sets the access and modify times of the file as specified by the application. The change time of the file is set to the current time.

  14. If the read operation was done using a scan descriptor passed to one of the integrated file system scan related exit programs, the Access time is not updated. See Integrated File System Scan on Open Exit Programs and Integrated File System Scan on Close Exit Programs for more information.


[ Back to top | >UNIX-Type APIs | APIs by category ]