Improve documentation of set-default-file-modes

* src/fileio.c (Fset_default_file_modes): Doc fix.  (Bug#28875)

* doc/lispref/files.texi (Changing Files): Clarify how the bits in
the argument of set-default-file-modes are used for setting file
permissions.

2 files changed, 12 insertions, 2 deletions

diff --git a/doc/lispref/files.texi b/doc/lispref/files.texi
index f49b02de97c..254eab03ea5 100644
--- a/doc/lispref/files.texi
+++ b/doc/lispref/files.texi
@@ -1821,7 +1821,9 @@ has these permissions, or a subset of them (@code{write-region} will
 not grant execute permissions even if the default file permissions
 allow execution).  On GNU and other POSIX-like systems, the default
 permissions are given by the bitwise complement of the @samp{umask}
-value.
+value, i.e.@: each bit that is set in the argument @var{mode} will be
+@emph{reset} in the default permissions with which Emacs creates
+files.
 
 The argument @var{mode} should be an integer which specifies the
 permissions, similar to @code{set-file-modes} above.  Only the lowest
diff --git a/src/fileio.c b/src/fileio.c
index b7df38c8570..92cc39496c4 100644
--- a/src/fileio.c
+++ b/src/fileio.c
@@ -3125,7 +3125,15 @@ symbolic notation, like the `chmod' command from GNU Coreutils.  */)
 DEFUN ("set-default-file-modes", Fset_default_file_modes, Sset_default_file_modes, 1, 1, 0,
        doc: /* Set the file permission bits for newly created files.
 The argument MODE should be an integer; only the low 9 bits are used.
-This setting is inherited by subprocesses.  */)
+On Posix hosts, this setting is inherited by subprocesses.
+
+This function works by setting the Emacs's file mode creation mask.
+Each bit that is set in the mask means that the corresponding bit
+in the the permissions of newly created files will be disabled.
+
+Note that when `write-region' creates a file, it resets the
+execute bit, even if the mask set by this function allows that bit
+by having the corresponding bit in the mask reset.  */)
   (Lisp_Object mode)
 {
   mode_t oldrealmask, oldumask, newumask;