From 9074103fbff70a30664b291f5ea3af443f88e4d8 Mon Sep 17 00:00:00 2001 From: Eli Zaretskii Date: Fri, 14 Oct 2022 10:12:03 +0300 Subject: [PATCH] ; Fix recent change in documentation of "device number" * src/dired.c (Ffile_attributes): * lisp/files.el (buffer-file-number, file-attribute-file-number): Fix wording of the doc strings. * etc/NEWS: * doc/lispref/buffers.texi (Buffer File Name): * doc/lispref/files.texi (File Attributes): Fix a typo and wording. (Bug#58446) --- doc/lispref/buffers.texi | 8 ++++---- doc/lispref/files.texi | 12 ++++++------ etc/NEWS | 6 ++++-- lisp/files.el | 12 +++++++----- src/dired.c | 6 +++--- 5 files changed, 24 insertions(+), 20 deletions(-) diff --git a/doc/lispref/buffers.texi b/doc/lispref/buffers.texi index b46b6c52d86..c40e088293e 100644 --- a/doc/lispref/buffers.texi +++ b/doc/lispref/buffers.texi @@ -427,19 +427,19 @@ It is a permanent local, unaffected by @end defvar @defvar buffer-file-number -This buffer-local variable holds the inode number and directory device -number of the file visited in the current buffer, or @code{nil} if no +This buffer-local variable holds the inode number and device +identifier of the file visited in the current buffer, or @code{nil} if no file or a nonexistent file is visited. It is a permanent local, unaffected by @code{kill-all-local-variables}. The value is normally a list of the form @code{(@var{inodenum} -@var{devnum})}. This pair of numbers uniquely identifies the file among +@var{device})}. This tuple uniquely identifies the file among all files accessible on the system. See the function @code{file-attributes}, in @ref{File Attributes}, for more information about them. If @code{buffer-file-name} is the name of a symbolic link, then both -numbers refer to the recursive target. +@var{inodenum} and @var{device} refer to the recursive target of the link. @end defvar @defun get-file-buffer filename diff --git a/doc/lispref/files.texi b/doc/lispref/files.texi index b9d4e87dc73..2467364dc6e 100644 --- a/doc/lispref/files.texi +++ b/doc/lispref/files.texi @@ -1404,16 +1404,16 @@ The file's inode number (@code{file-attribute-inode-number}), a nonnegative integer. @item -The filesystem number of the device that the file is on +The filesystem's identifier of the device that the file is on (@code{file-attribute-device-number}), an integer or a cons cell of -integers. The latter is sometimes used by remote files, in order to -distinguish the remote filesystems from the local ones. +two integers. The latter is sometimes used by remote files, in order +to distinguish remote filesystems from local ones. @end enumerate -The file's inode and device numbers together give enough information +The file's inode and device 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. This tupel is returned by -@code{file-attribute-file-number}. +same values for both of these attributes. This tuple that uniquely +identifies the file is returned by @code{file-attribute-file-number}. For example, here are the file attributes for @file{files.texi}: diff --git a/etc/NEWS b/etc/NEWS index 7808c3beb20..464cb2719f5 100644 --- a/etc/NEWS +++ b/etc/NEWS @@ -3149,8 +3149,10 @@ The following generalized variables have been made obsolete: +++ ** New accessor function 'file-attribute-file-number'. -It returns the list of the inode and device numbers retrieved by -'file-attributes'. This value can be used to identify a file uniquely. +It returns the list of the inode number and device identifier +retrieved by 'file-attributes'. This value can be used to identify a +file uniquely. The device identifier can be a single number or (for +remote files) a cons of 2 numbers. +++ ** New macro 'while-let'. diff --git a/lisp/files.el b/lisp/files.el index 1a301485517..dd10f7399cc 100644 --- a/lisp/files.el +++ b/lisp/files.el @@ -208,9 +208,10 @@ if the file has changed on disk and you have not edited the buffer." :group 'find-file) (defvar-local buffer-file-number nil - "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. + "The inode number and the device of the file visited in the current buffer. +The value is a list of the form (INODENUM DEVICE), where DEVICE can be +either a single number or a cons cell of two numbers. +This tuple 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) @@ -8663,8 +8664,9 @@ It is an integer or a cons cell of integers." (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." +The value is a list of the form (INODENUM DEVICE), where DEVICE could be +either a single number or a cons cell of two numbers. +This tuple of numbers uniquely identifies the file." (nthcdr 10 attributes)) (defun file-attribute-collect (attributes &rest attr-names) diff --git a/src/dired.c b/src/dired.c index 32c083ad7b0..1b4edf20483 100644 --- a/src/dired.c +++ b/src/dired.c @@ -923,12 +923,12 @@ Elements of the attribute list are: 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, as a nonnegative integer. -11. Filesystem device number, as an integer or a cons cell of integers. +11. Filesystem device identifier, as an integer or a cons cell of integers. 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. This is provided by the access -function `file-attribute-file-number'. +identifier uniquely identifies the file. This unique file identification +is provided by the access function `file-attribute-file-number'. On MS-Windows, performance depends on `w32-get-true-file-attributes', which see. -- 2.39.5