changeset 105460:7221464893e9

(File Attributes): Fix description of file attributes. (Bug#4638) Update attributes of files.texi example to be more representative.

--- a/doc/lispref/files.texi	Mon Oct 05 08:35:41 2009 +0000
+++ b/doc/lispref/files.texi	Mon Oct 05 08:44:33 2009 +0000
@@ -1176,14 +1176,20 @@
 The time of last access, as a list of two integers.
 The first integer has the high-order 16 bits of time,
 the second has the low 16 bits.  (This is similar to the
-value of @code{current-time}; see @ref{Time of Day}.)
-
+value of @code{current-time}; see @ref{Time of Day}.)  Note that on
+some FAT-based filesystems, only the date of last access is recorded,
+so this time will always hold the midnight of the day of last access.
+
+@cindex modification time of file
 @item
 The time of last modification as a list of two integers (as above).
-@cindex modification time of file
+This is the last time when the file's contents were modified.
 
 @item
 The time of last status change as a list of two integers (as above).
+This is the time of the last change to the file's access mode bits,
+its owner and group, and other information recorded in the filesystem
+for the file, beyond the file's contents.
 
 @item
 The size of the file in bytes.  If the size is too large to fit in a
@@ -1198,18 +1204,22 @@
 deleted and recreated; @code{nil} otherwise.
 
 @item
-The file's inode number.  If possible, this is an integer.  If the inode
-number is too large to be represented as an integer in Emacs Lisp, then
-the value has the form @code{(@var{high} . @var{low})}, where @var{low}
-holds the low 16 bits.
+The file's inode number.  If possible, this is an integer.  If the
+inode number is too large to be represented as an integer in Emacs
+Lisp, but still fits into a 32-bit integer, then the value has the
+form @code{(@var{high} . @var{low})}, where @var{low} holds the low 16
+bits.  If the inode is wider than 32 bits, the value is of the form
+@code{(@var{high} @var{middle} . @var{low})}, where @code{high} holds
+the high 24 bits, @var{middle} the next 24 bits, and @var{low} the low
+16 bits.
 
 @item
-The file system number of the file system that the file is in.
-Depending on the magnitude of the value, this can be either an integer
-or a cons cell, in the same manner as the inode number.  This element
-and the file's inode number together give enough information to
-distinguish any two files on the system---no two files can have the same
-values for both of these numbers.
+The filesystem number of the device that the file is on.  Depending on
+the magnitude of the value, this can be either an integer or a cons
+cell, in the same manner as the inode number.  This element and the
+file's inode number together give enough information to distinguish
+any two files on the system---no two files can have the same values
+for both of these numbers.
 @end enumerate
 
 For example, here are the file attributes for @file{files.texi}:
@@ -1218,11 +1228,12 @@
 @group
 (file-attributes "files.texi" 'string)
      @result{}  (nil 1 "lh" "users"
-          (8489 20284)
-          (8489 20284)
-          (8489 20285)
-          14906 "-rw-rw-rw-"
-          nil 129500 -32252)
+          (19145 42977)
+          (19141 59576)
+          (18340 17300)
+          122295 "-rw-rw-rw-"
+          nil  (5888 2 . 43978)
+          (15479 . 46724))
 @end group
 @end example
 
@@ -1243,18 +1254,19 @@
 @item "users"
 is in the group with name "users".
 
-@item (8489 20284)
-was last accessed on Aug 19 00:09.
-
-@item (8489 20284)
-was last modified on Aug 19 00:09.
-
-@item (8489 20285)
-last had its inode changed on Aug 19 00:09.
-
-@item 14906
-is 14906 bytes long.  (It may not contain 14906 characters, though,
-if some of the bytes belong to multibyte sequences.)
+@item (19145 42977)
+was last accessed on Oct 5 2009, at 10:01:37.
+
+@item (19141 59576)
+last had its contents modified on Oct 2 2009, at 13:49:12.
+
+@item (18340 17300)
+last had its status changed on Feb 2 2008, at 12:19:00.
+
+@item 122295
+is 122295 bytes long.  (It may not contain 122295 characters, though,
+if some of the bytes belong to multibyte sequences, and also if the
+end-of-line format is CR-LF.)
 
 @item "-rw-rw-rw-"
 has a mode of read and write access for the owner, group, and world.
@@ -1262,10 +1274,11 @@
 @item nil
 would retain the same @acronym{GID} if it were recreated.
 
-@item 129500
-has an inode number of 129500.
-@item -32252
-is on file system number -32252.
+@item (5888 2 . 43978)
+has an inode number of 6473924464520138.
+
+@item (15479 . 46724)
+is on the file-system device whose number is 1014478468.
 @end table
 @end defun
 
@@ -2483,8 +2496,7 @@
 
 @node Create/Delete Dirs
 @section Creating, Copying and Deleting Directories
-@cindex creating and deleting directories
-@cindex copying directories
+@cindex creating, copying and deleting directories
 @c Emacs 19 features
 
   Most Emacs Lisp file-manipulation functions get errors when used on