From 310b79194aa02b9bdc41b428c18e0863106e09b0 Mon Sep 17 00:00:00 2001 From: Michael Kerrisk Date: Tue, 19 Jul 2005 07:15:17 +0000 Subject: [PATCH] Consistent use of st_atime, st_ctime, st_mtime, with explanatory text, instead if atime/ctime/mtime. --- Changes | 3 +++ man2/fsync.2 | 9 ++++++--- man2/open.2 | 14 +++++++++----- man2/read.2 | 5 +++-- man2/truncate.2 | 30 +++++++++++++++++------------- 5 files changed, 38 insertions(+), 23 deletions(-) diff --git a/Changes b/Changes index d69452653..4e83ff5e6 100644 --- a/Changes +++ b/Changes @@ -31,6 +31,9 @@ there was a mix of x.yBSD and BSD x.y). pid --> PID id --> ID +Consistent use of st_atime, st_ctime, st_mtime, with explanatory text, +instead if atime/ctime/mtime. + Typographical or grammatical errors have been corrected in several places. diff --git a/man2/fsync.2 b/man2/fsync.2 index 1d37aa1da..29b7484bc 100644 --- a/man2/fsync.2 +++ b/man2/fsync.2 @@ -54,8 +54,11 @@ on the file descriptor of the directory is also needed. .B fdatasync does the same as .B fsync -but only flushes user data, not the meta data like the mtime or atime. - +but only flushes user data, not the meta data like the st_atime or +st_mtime +(respectively, time of last access and +time of last modification; see +.BR stat (2)) . .SH "RETURN VALUE" On success, zero is returned. On error, \-1 is returned, and .I errno @@ -98,7 +101,7 @@ POSIX.1b (formerly POSIX.4) .SH "SEE ALSO" .BR bdflush (2), .BR open (2), -.BR sync (2) +.BR sync (2), .BR mount (8), .BR sync (8), .BR update (8) diff --git a/man2/open.2 b/man2/open.2 index ce76fa390..fc74447cb 100644 --- a/man2/open.2 +++ b/man2/open.2 @@ -194,7 +194,8 @@ to be opened. .TP .B O_NOATIME (Since Linux 2.6.8) -Do not update the file last access time when the file is +Do not update the file last access time (st_atime in the inode) +when the file is .BR read (2). This flag is intended for use by indexing or backup programs, where its use can significantly reduce the amount of disk activity. @@ -333,12 +334,15 @@ This is because the client performs \fBopen\fP() by checking the permissions, but UID mapping is performed by the server upon read and write requests. -If the file is newly created, its atime, ctime, mtime fields are set -to the current time, and so are the ctime and mtime fields of the +If the file is newly created, its st_atime, st_ctime, st_mtime fields +(respectively, time of last access, time of last status change, and +time of last modification; see +.BR stat (2)) +are set +to the current time, and so are the st_ctime and st_mtime fields of the parent directory. Otherwise, if the file is modified because of the O_TRUNC flag, -its ctime and mtime fields are set to the current time. - +its st_ctime and st_mtime fields are set to the current time. .SH ERRORS .TP .B EACCES diff --git a/man2/read.2 b/man2/read.2 index 3051000db..e7d775f7b 100644 --- a/man2/read.2 +++ b/man2/read.2 @@ -116,8 +116,9 @@ SVr4, SVID, AT&T, POSIX, X/OPEN, 4.3BSD On NFS file systems, reading small amounts of data will only update the time stamp the first time, subsequent calls may not do so. This is caused by client side attribute caching, because most if not all NFS clients -leave atime updates to the server and client side reads satisfied from the -client's cache will not cause atime updates on the server as there are no +leave st_atime (last file access time) +updates to the server and client side reads satisfied from the +client's cache will not cause st_atime updates on the server as there are no server side reads. UNIX semantics can be obtained by disabling client side attribute caching, but in most situations this will substantially increase server load and decrease performance. diff --git a/man2/truncate.2 b/man2/truncate.2 index 9ad000f5c..bbf16e273 100644 --- a/man2/truncate.2 +++ b/man2/truncate.2 @@ -51,9 +51,9 @@ truncate, ftruncate \- truncate a file to a specified length .BI "int ftruncate(int " fd ", off_t " length ); .SH DESCRIPTION The -.B truncate +.BR truncate () and -.B ftruncate +.BR ftruncate () functions cause the regular file named by .I path or referenced by @@ -68,14 +68,17 @@ the extended part reads as zero bytes. .LP The file offset is not changed. .LP -If the size changed, then the ctime and mtime fields for the file -are updated, -and set-user-ID and set-group-ID permission bits may be cleared. +If the size changed, then the st_ctime and st_mtime fields +(respectively, time of last status change and +time of last modification; see +.BR stat (2)) +for the file are updated, +and the set-user-ID and set-group-ID permission bits may be cleared. .LP With -.BR ftruncate , +.BR ftruncate (), the file must be open for writing; with -.BR truncate , +.BR truncate (), the file must be writable. .SH "RETURN VALUE" On success, zero is returned. On error, \-1 is returned, and @@ -134,7 +137,7 @@ The named file resides on a read-only file system. The file is a pure procedure (shared text) file that is being executed. .PP For -.B ftruncate +.BR ftruncate () the same errors apply, but instead of things that can be wrong with .IR path , we now have things that can be wrong with @@ -163,24 +166,25 @@ POSIX 1003.1-2001 also has as an XSI extension. .LP SVr4 documents additional -.B truncate +.BR truncate () error conditions EMFILE, EMULTIHP, ENFILE, ENOLINK. SVr4 documents for -.B ftruncate +.BR ftruncate () an additional EAGAIN error condition. .SH NOTES The above description is for XSI-compliant systems. For non-XSI-compliant systems, the POSIX standard allows two behaviours for -.B ftruncate +.BR ftruncate () when .I length exceeds the file length (note that -.B truncate +.BR truncate () is not specified at all in such an environment): either returning an error, or extending the file. (Most Unices follow the XSI requirement.) .\" At the very least: OSF/1, Solaris 7, and FreeBSD conform, mtk, Jan 2002 .SH "SEE ALSO" .BR open (2), -.BR path_resolution (2) +.BR path_resolution (2), +.BR stat (2)