; Clarify documentation of 'file-modes-number-to-symbolic'

* doc/lispref/files.texi (Changing Files):
* lisp/files.el (file-modes-number-to-symbolic): Clarify the
confusion with "symbolic" forms of file modes.  (Bug#61709)

diff --git a/doc/lispref/files.texi b/doc/lispref/files.texi
index 5062b1697b58e1e9f35278e97f7606529bca7364..f8781d4895bd6e093a090b5f233247b5bed49fc1 100644 (file)
--- a/doc/lispref/files.texi
+++ b/doc/lispref/files.texi
@@ -1985,7 +1985,11 @@ all.
 
 @defun file-modes-number-to-symbolic modes
 This function converts a numeric file mode specification in
-@var{modes} into the equivalent symbolic form.
+@var{modes} into the equivalent string form.  The string which this
+function returns is in the same format produced by the shell command
+@kbd{ls -l} and by @code{file-attributes}, @emph{not} the symbolic
+form accepted by @code{file-modes-symbolic-to-number} and the
+@command{chmod} shell command.
 @end defun
 
 @defun set-file-times filename &optional time flag

diff --git a/lisp/files.el b/lisp/files.el
index 57e013403591b3cb23e0a8f6a916767b263749f1..db3f348c4b58710b606c56efb0d65edb73eb7a4a 100644 (file)
--- a/lisp/files.el
+++ b/lisp/files.el
@@ -8391,11 +8391,14 @@ as in \"og+rX-w\"."
     num-rights))
 
 (defun file-modes-number-to-symbolic (mode &optional filetype)
-  "Return a string describing a file's MODE.
+  "Return a description of a file's MODE as a string of 10 letters and dashes.
+The returned string is like the mode description produced by \"ls -l\".
 For instance, if MODE is #o700, then it produces `-rwx------'.
-FILETYPE if provided should be a character denoting the type of file,
-such as `?d' for a directory, or `?l' for a symbolic link and will override
-the leading `-' char."
+Note that this is NOT the same as the \"chmod\" style symbolic description
+accepted by `file-modes-symbolic-to-number'.
+FILETYPE, if provided, should be a character denoting the type of file,
+such as `?d' for a directory, or `?l' for a symbolic link, and will override
+the leading `-' character."
   (string
    (or filetype
        (pcase (ash mode -12)