file-attributes cleanup

Mostly, this replaces magic-number calls like (nth 4 A) with
more-informative calls like (file-attribute-access-time A).
It also fixes some documentation and minor timestamp coding
issues that I noticed while looking into this.
* doc/lispref/files.texi (File Attributes):
* lisp/files.el (file-attribute-size)
(file-attribute-inode-number, file-attribute-device-number):
* src/dired.c (Fdirectory_files_and_attributes)
(Ffile_attributes):
Mention which attributes must be integers, or nonnegative integers,
as opposed to merely being numbers.  Remove no-longer-correct
talk about representing large integers as conses of integers.
* doc/lispref/files.texi (Magic File Names):
* doc/misc/gnus.texi (Low-level interface to the spam-stat dictionary):
* lisp/autorevert.el (auto-revert-find-file-function)
(auto-revert-tail-mode, auto-revert-handler):
* lisp/auth-source.el (auth-source-netrc-parse):
* lisp/cedet/ede/files.el (ede--inode-for-dir):
* lisp/cedet/semantic/db-file.el (object-write):
* lisp/cedet/semantic/db-mode.el (semanticdb-kill-hook):
* lisp/cedet/semantic/db.el (semanticdb-needs-refresh-p)
(semanticdb-synchronize):
* lisp/cedet/srecode/table.el (srecode-mode-table-new):
* lisp/desktop.el (desktop-save, desktop-read):
* lisp/dired-aux.el (dired-file-set-difference)
(dired-do-chxxx, dired-do-chmod, dired-copy-file-recursive)
(dired-create-files):
* lisp/dired.el (dired-directory-changed-p, dired-readin):
* lisp/dos-w32.el (w32-direct-print-region-helper):
* lisp/emacs-lisp/autoload.el (autoload-generate-file-autoloads)
(autoload-find-destination, update-directory-autoloads):
* lisp/emacs-lisp/shadow.el (load-path-shadows-same-file-or-nonexistent):
* lisp/epg.el (epg--start, epg-wait-for-completion):
* lisp/eshell/em-ls.el (eshell-ls-filetype-p)
(eshell-ls-applicable, eshell-ls-size-string)
(eshell-ls-file, eshell-ls-dir, eshell-ls-files)
(eshell-ls-entries):
* lisp/eshell/em-pred.el (eshell-predicate-alist)
(eshell-pred-file-type, eshell-pred-file-links)
(eshell-pred-file-size):
* lisp/eshell/em-unix.el (eshell-shuffle-files, eshell/cat)
(eshell-du-sum-directory, eshell/du):
* lisp/eshell/esh-util.el (eshell-read-passwd)
(eshell-read-hosts):
* lisp/files.el (remote-file-name-inhibit-cache)
(find-file-noselect, insert-file-1, dir-locals-find-file)
(dir-locals-read-from-dir, backup-buffer)
(file-ownership-preserved-p, copy-directory)
(read-file-modes):
* lisp/find-lisp.el (find-lisp-format):
* lisp/gnus/gnus-agent.el (gnus-agent-unfetch-articles)
(gnus-agent-read-agentview, gnus-agent-expire-group-1)
(gnus-agent-request-article, gnus-agent-regenerate-group)
(gnus-agent-update-files-total-fetched-for)
(gnus-agent-update-view-total-fetched-for):
* lisp/gnus/gnus-cache.el (gnus-cache-read-active)
(gnus-cache-update-file-total-fetched-for)
(gnus-cache-update-overview-total-fetched-for):
* lisp/gnus/gnus-cloud.el (gnus-cloud-file-new-p):
* lisp/gnus/gnus-score.el (gnus-score-score-files):
* lisp/gnus/gnus-start.el (gnus-save-newsrc-file)
(gnus-master-read-slave-newsrc):
* lisp/gnus/gnus-sum.el (gnus-summary-import-article):
* lisp/gnus/gnus-util.el (gnus-file-newer-than)
(gnus-cache-file-contents):
* lisp/gnus/mail-source.el (mail-source-delete-old-incoming)
(mail-source-callback, mail-source-movemail):
* lisp/gnus/nneething.el (nneething-create-mapping)
(nneething-make-head):
* lisp/gnus/nnfolder.el (nnfolder-read-folder):
* lisp/gnus/nnheader.el (nnheader-file-size)
(nnheader-insert-nov-file):
* lisp/gnus/nnmail.el (nnmail-activate):
* lisp/gnus/nnmaildir.el (nnmaildir--group-maxnum)
(nnmaildir--new-number, nnmaildir--update-nov)
(nnmaildir--scan, nnmaildir-request-scan)
(nnmaildir-request-update-info)
(nnmaildir-request-expire-articles):
* lisp/gnus/nnmh.el (nnmh-request-list-1)
(nnmh-request-expire-articles, nnmh-update-gnus-unreads):
* lisp/gnus/nnml.el (nnml-request-expire-articles):
* lisp/gnus/spam-stat.el (spam-stat-save, spam-stat-load)
(spam-stat-process-directory, spam-stat-test-directory):
* lisp/ido.el (ido-directory-too-big-p)
(ido-file-name-all-completions):
* lisp/image-dired.el (image-dired-get-thumbnail-image)
(image-dired-create-thumb-1):
* lisp/info.el (info-insert-file-contents):
* lisp/ls-lisp.el (ls-lisp-insert-directory)
(ls-lisp-handle-switches, ls-lisp-classify-file)
(ls-lisp-format):
* lisp/mail/blessmail.el:
* lisp/mail/feedmail.el (feedmail-default-date-generator)
(feedmail-default-message-id-generator):
* lisp/mail/mailabbrev.el (mail-abbrevs-sync-aliases)
(mail-abbrevs-setup):
* lisp/mail/mspools.el (mspools-size-folder):
* lisp/mail/rmail.el (rmail-insert-inbox-text):
* lisp/mail/sendmail.el (sendmail-sync-aliases):
* lisp/mh-e/mh-alias.el (mh-alias-tstamp):
* lisp/net/ange-ftp.el (ange-ftp-parse-netrc)
(ange-ftp-write-region, ange-ftp-file-newer-than-file-p)
(ange-ftp-cf1):
* lisp/net/eudcb-mab.el (eudc-mab-query-internal):
* lisp/net/eww.el (eww-read-bookmarks):
* lisp/net/netrc.el (netrc-parse):
* lisp/net/newst-backend.el (newsticker--image-get):
* lisp/nxml/rng-loc.el (rng-get-parsed-schema-locating-file):
* lisp/obsolete/fast-lock.el (fast-lock-save-cache):
* lisp/obsolete/vc-arch.el (vc-arch-state)
(vc-arch-diff3-rej-p):
* lisp/org/ob-eval.el (org-babel--shell-command-on-region):
* lisp/org/org-attach.el (org-attach-commit):
* lisp/org/org-macro.el (org-macro-initialize-templates):
* lisp/org/org.el (org-babel-load-file)
(org-file-newer-than-p):
* lisp/org/ox-html.el (org-html-format-spec):
* lisp/org/ox-publish.el (org-publish-find-date)
(org-publish-cache-ctime-of-src):
* lisp/pcmpl-gnu.el (pcomplete/tar):
* lisp/pcmpl-rpm.el (pcmpl-rpm-packages):
* lisp/play/cookie1.el (cookie-snarf):
* lisp/progmodes/cmacexp.el (c-macro-expansion):
* lisp/ps-bdf.el (bdf-file-mod-time):
* lisp/server.el (server-ensure-safe-dir):
* lisp/simple.el (shell-command-on-region):
* lisp/speedbar.el (speedbar-item-info-file-helper)
(speedbar-check-obj-this-line):
* lisp/thumbs.el (thumbs-cleanup-thumbsdir):
* lisp/time.el (display-time-mail-check-directory)
(display-time-file-nonempty-p):
* lisp/url/url-cache.el (url-is-cached):
* lisp/url/url-file.el (url-file-asynch-callback):
* lisp/vc/diff-mode.el (diff-delete-if-empty):
* lisp/vc/pcvs-info.el (cvs-fileinfo-from-entries):
* lisp/vc/vc-bzr.el (vc-bzr-state-heuristic):
* lisp/vc/vc-cvs.el (vc-cvs-checkout-model)
(vc-cvs-state-heuristic, vc-cvs-merge-news)
(vc-cvs-retrieve-tag, vc-cvs-parse-status, vc-cvs-parse-entry):
* lisp/vc/vc-hg.el (vc-hg--slurp-hgignore-1)
(vc-hg--ignore-patterns-valid-p)
(vc-hg--cached-dirstate-search, vc-hg-state-fast):
* lisp/vc/vc-hooks.el (vc-after-save):
* lisp/vc/vc-rcs.el (vc-rcs-workfile-is-newer):
* lisp/vc/vc-svn.el (vc-svn-merge-news, vc-svn-parse-status):
* lisp/vc/vc.el (vc-checkout, vc-checkin, vc-revert-file):
* lisp/xdg.el (xdg-mime-apps):
Prefer (file-attribute-size A) to (nth 7 A), and similarly
for other file attributes accessors.
* doc/lispref/files.texi (File Attributes):
* doc/lispref/intro.texi (Version Info):
* doc/lispref/os.texi (Idle Timers):
* lisp/erc/erc.el (erc-string-to-emacs-time):
* lisp/files.el (file-attribute-access-time)
(file-attribute-modification-time)
(file-attribute-status-change-time):
* lisp/net/tramp-compat.el:
(tramp-compat-file-attribute-modification-time)
(tramp-compat-file-attribute-size):
* src/buffer.c (syms_of_buffer):
* src/editfns.c (Fget_internal_run_time):
* src/fileio.c (Fvisited_file_modtime)
(Fset_visited_file_modtime):
* src/keyboard.c (Fcurrent_idle_time):
* src/process.c (Fprocess_attributes):
Defer implementation details about timestamp format to the
section that talks about timestamp format, to make it easier
to change the documentation later if timestamp formats are
extended.
* lisp/gnus/gnus-util.el (gnus-file-newer-than):
* lisp/speedbar.el (speedbar-check-obj-this-line):
* lisp/vc/vc-rcs.el (vc-rcs-workfile-is-newer):
Prefer time-less-p to doing it by hand.
* lisp/ls-lisp.el (ls-lisp-format): Inode numbers are no longer conses.
* lisp/vc/vc-bzr.el (vc-bzr-state-heuristic):
Use eql, not eq, to compare integers that might be bignums.
* lisp/org/ox-publish.el (org-publish-cache-ctime-of-src):
Prefer float-time to doing time arithmetic by hand.

6 files changed, 23 insertions, 31 deletions

diff --git a/src/buffer.c b/src/buffer.c
index 1f18dbd11a8..024e64f0d74 100644
--- a/src/buffer.c
+++ b/src/buffer.c
@@ -6010,11 +6010,11 @@ An entry (TEXT . POSITION) represents the deletion of the string TEXT
 from (abs POSITION).  If POSITION is positive, point was at the front
 of the text being deleted; if negative, point was at the end.
 
-An entry (t HIGH LOW USEC PSEC) indicates that the buffer was previously
-unmodified; (HIGH LOW USEC PSEC) is in the same style as (current-time)
-and is the visited file's modification time, as of that time.  If the
-modification time of the most recent save is different, this entry is
-obsolete.
+An entry (t . TIMESTAMP), where TIMESTAMP is in the style of
+`current-time', indicates that the buffer was previously unmodified;
+TIMESTAMP is the visited file's modification time, as of that time.
+If the modification time of the most recent save is different, this
+entry is obsolete.
 
 An entry (t . 0) means the buffer was previously unmodified but
 its time stamp was unknown because it was not associated with a file.
diff --git a/src/dired.c b/src/dired.c
index 70c5bb24b4e..7ad401c728b 100644
--- a/src/dired.c
+++ b/src/dired.c
@@ -347,7 +347,7 @@ DEFUN ("directory-files-and-attributes", Fdirectory_files_and_attributes,
        doc: /* Return a list of names of files and their attributes in DIRECTORY.
 Value is a list of the form:
 
-  ((FILE1 FILE1-ATTRS) (FILE2 FILE2-ATTRS) ...)
+  ((FILE1 . FILE1-ATTRS) (FILE2 . FILE2-ATTRS) ...)
 
 where each FILEn-ATTRS is the attributes of FILEn as returned
 by `file-attributes'.
@@ -866,26 +866,22 @@ provided: `file-attribute-type', `file-attribute-link-number',
 Elements of the attribute list are:
  0. t for directory, string (name linked to) for symbolic link, or nil.
  1. Number of links to file.
- 2. File uid as a string or a number.  If a string value cannot be
-  looked up, an integer value is returned, which could be a fixnum,
-  if it's small enough, otherwise a bignum.
+ 2. File uid as a string or (if ID-FORMAT is `integer' or a string value
+  cannot be looked up) as an integer.
  3. File gid, likewise.
- 4. Last access time, as a list of integers (HIGH LOW USEC PSEC) in the
-  same style as (current-time).
+ 4. Last access time, in the style of `current-time'.
   (See a note below about access time on FAT-based filesystems.)
  5. Last modification time, likewise.  This is the time of the last
   change to the file's contents.
  6. Last status change time, likewise.  This is the time of last change
   to the file's attributes: owner and group, access mode bits, etc.
- 7. Size in bytes, which could be a fixnum, if it's small enough,
-  otherwise a bignum.
+ 7. Size in bytes, as an integer.
  8. File modes, as a string of ten letters or dashes as in ls -l.
  9. An unspecified value, present only for backward compatibility.
-10. inode number, which could be a fixnum, if it's small enough,
-  otherwise a bignum.
-11. Filesystem device number.  If it is larger than what a fixnum
-  can hold, it is a bignum.
+10. inode number, as a nonnegative integer.
+11. Filesystem device number, as an integer.
 
+Large integers are bignums, so `eq' might not work on them.
 On most filesystems, the combination of the inode and the device
 number uniquely identifies the file.
 
diff --git a/src/editfns.c b/src/editfns.c
index 047a73f0b8c..ec6e8ba98d6 100644
--- a/src/editfns.c
+++ b/src/editfns.c
@@ -1656,8 +1656,7 @@ See `current-time-string' for the various forms of a time value.  */)
 DEFUN ("get-internal-run-time", Fget_internal_run_time, Sget_internal_run_time,
        0, 0, 0,
        doc: /* Return the current run time used by Emacs.
-The time is returned as a list (HIGH LOW USEC PSEC), using the same
-style as (current-time).
+The time is returned as in the style of `current-time'.
 
 On systems that can't determine the run time, `get-internal-run-time'
 does the same thing as `current-time'.  */)
diff --git a/src/fileio.c b/src/fileio.c
index 5ca7c595f7d..7fb865809f5 100644
--- a/src/fileio.c
+++ b/src/fileio.c
@@ -5454,10 +5454,9 @@ See Info node `(elisp)Modification Time' for more details.  */)
 DEFUN ("visited-file-modtime", Fvisited_file_modtime,
        Svisited_file_modtime, 0, 0, 0,
        doc: /* Return the current buffer's recorded visited file modification time.
-The value is a list of the form (HIGH LOW USEC PSEC), like the time values that
-`file-attributes' returns.  If the current buffer has no recorded file
-modification time, this function returns 0.  If the visited file
-doesn't exist, return -1.
+Return a Lisp timestamp (as in `current-time') if the current buffer
+has a recorded file modification time, 0 if it doesn't, and -1 if the
+visited file doesn't exist.
 See Info node `(elisp)Modification Time' for more details.  */)
   (void)
 {
@@ -5473,9 +5472,8 @@ DEFUN ("set-visited-file-modtime", Fset_visited_file_modtime,
 Useful if the buffer was not read from the file normally
 or if the file itself has been changed for some known benign reason.
 An argument specifies the modification time value to use
-\(instead of that of the visited file), in the form of a list
-\(HIGH LOW USEC PSEC) or an integer flag as returned by
-`visited-file-modtime'.  */)
+\(instead of that of the visited file), in the form of a time value as
+in `current-time' or an integer flag as returned by `visited-file-modtime'.  */)
   (Lisp_Object time_flag)
 {
   if (!NILP (time_flag))
diff --git a/src/keyboard.c b/src/keyboard.c
index 008d3b9d7c0..1c1f1514ae8 100644
--- a/src/keyboard.c
+++ b/src/keyboard.c
@@ -4377,8 +4377,8 @@ timer_check (void)
 
 DEFUN ("current-idle-time", Fcurrent_idle_time, Scurrent_idle_time, 0, 0, 0,
        doc: /* Return the current length of Emacs idleness, or nil.
-The value when Emacs is idle is a list of four integers (HIGH LOW USEC PSEC)
-in the same style as (current-time).
+The value when Emacs is idle is a Lisp timestamp in the style of
+`current-time'.
 
 The value when Emacs is not idle is nil.
 
diff --git a/src/process.c b/src/process.c
index b4ba641f31b..a9638dfc2df 100644
--- a/src/process.c
+++ b/src/process.c
@@ -7934,8 +7934,7 @@ integer or floating point values.
  majflt  -- number of major page faults (number)
  cminflt -- cumulative number of minor page faults (number)
  cmajflt -- cumulative number of major page faults (number)
- utime   -- user time used by the process, in (current-time) format,
-              which is a list of integers (HIGH LOW USEC PSEC)
+ utime   -- user time used by the process, in `current-time' format
  stime   -- system time used by the process (current-time)
  time    -- sum of utime and stime (current-time)
  cutime  -- user time used by the process and its children (current-time)
@@ -7947,7 +7946,7 @@ integer or floating point values.
  start   -- time the process started (current-time)
  vsize   -- virtual memory size of the process in KB's (number)
  rss     -- resident set size of the process in KB's (number)
- etime   -- elapsed time the process is running, in (HIGH LOW USEC PSEC) format
+ etime   -- elapsed time the process is running (current-time)
  pcpu    -- percents of CPU time used by the process (floating-point number)
  pmem    -- percents of total physical memory used by process's resident set
               (floating-point number)