Clarify structure of file-attribute's device number

* doc/lispref/buffers.texi (Buffer File Name): Fix description of
buffer-file-number.

* doc/lispref/files.texi (File Attributes): Clarify type of device
number.  Describe file-attribute-file-number.  (Bug#58446)

* etc/NEWS: Mention file-attribute-file-number.

* lisp/files.el (buffer-file-number, file-attribute-device-number)
(file-attribute-collect): Fix docstring.
(file-attribute-file-number): New defsubst.
(find-buffer-visiting, find-file-noselect)
(set-visited-file-name, basic-save-buffer):
* lisp/startup.el (normal-top-level-add-subdirs-to-load-path):
* lisp/eshell/em-unix.el (eshell-shuffle-files): Use it.

* src/dired.c (Ffile_attributes): Fix docstring.

1 files changed, 15 insertions, 9 deletions

diff --git a/lisp/files.el b/lisp/files.el
index 94d110f0b7d..1a301485517 100644
--- a/lisp/files.el
+++ b/lisp/files.el
@@ -208,8 +208,8 @@ if the file has changed on disk and you have not edited the buffer."
   :group 'find-file)
 
 (defvar-local buffer-file-number nil
-  "The device number and file number of the file visited in the current buffer.
-The value is a list of the form (FILENUM DEVNUM).
+  "The inode and device numbers of the file visited in the current buffer.
+The value is a list of the form (INODENUM DEVNUM).
 This pair of numbers uniquely identifies the file.
 If the buffer is visiting a new file, the value is nil.")
 (put 'buffer-file-number 'permanent-local t)
@@ -2163,7 +2163,7 @@ If there is no such live buffer, return nil."
             (setq list (cdr list)))
           found)
         (let* ((attributes (file-attributes truename))
-               (number (nthcdr 10 attributes))
+               (number (file-attribute-file-number attributes))
                (list (buffer-list)) found)
           (and buffer-file-numbers-unique
                (car-safe number)       ;Make sure the inode is not just nil.
@@ -2366,7 +2366,7 @@ the various files."
       (let* ((buf (get-file-buffer filename))
 	     (truename (abbreviate-file-name (file-truename filename)))
 	     (attributes (file-attributes truename))
-	     (number (nthcdr 10 attributes))
+	     (number (file-attribute-file-number attributes))
 	     ;; Find any buffer for a file that has same truename.
 	     (other (and (not buf)
                          (find-buffer-visiting
@@ -4744,7 +4744,7 @@ the old visited file has been renamed to the new name FILENAME."
 	      (setq buffer-file-name truename))))
     (setq buffer-file-number
 	  (if filename
-	      (nthcdr 10 (file-attributes buffer-file-name))
+	      (file-attribute-file-number (file-attributes buffer-file-name))
 	    nil))
     ;; write-file-functions is normally used for things like ftp-find-file
     ;; that visit things that are not local files as if they were files.
@@ -5733,7 +5733,7 @@ Before and after saving the buffer, this function runs
 		  (setq save-buffer-coding-system last-coding-system-used)
 	        (setq buffer-file-coding-system last-coding-system-used))
 	      (setq buffer-file-number
-		    (nthcdr 10 (file-attributes buffer-file-name)))
+		    (file-attribute-file-number (file-attributes buffer-file-name)))
 	      (if setmodes
 		  (condition-case ()
 		      (progn
@@ -8658,19 +8658,25 @@ It is a nonnegative integer."
 
 (defsubst file-attribute-device-number (attributes)
   "The file system device number in ATTRIBUTES returned by `file-attributes'.
-It is an integer."
+It is an integer or a cons cell of integers."
   (nth 11 attributes))
 
+(defsubst file-attribute-file-number (attributes)
+  "The inode and device numbers in ATTRIBUTES returned by `file-attributes'.
+The value is a list of the form (INODENUM DEVNUM).
+This pair of numbers uniquely identifies the file."
+  (nthcdr 10 attributes))
+
 (defun file-attribute-collect (attributes &rest attr-names)
   "Return a sublist of ATTRIBUTES returned by `file-attributes'.
 ATTR-NAMES are symbols with the selected attribute names.
 
 Valid attribute names are: type, link-number, user-id, group-id,
 access-time, modification-time, status-change-time, size, modes,
-inode-number and device-number."
+inode-number, device-number and file-number."
   (let ((all '(type link-number user-id group-id access-time
                modification-time status-change-time
-               size modes inode-number device-number))
+               size modes inode-number device-number file-number))
         result)
     (while attr-names
       (let ((attr (pop attr-names)))