bug#50946: insert-file-contents can corrupt buffers.

[Alan Mackenzie]

Hello, Eli.

On Sun, Oct 03, 2021 at 15:40:24 +0300, Eli Zaretskii wrote:
> > Date: Sun, 3 Oct 2021 12:10:19 +0000
> > Cc: joaotavora@gmail.com, 50946@debbugs.gnu.org
> > From: Alan Mackenzie <acm@muc.de>

[ .... ]

> > There are bugs in the documentation of insert-file-contents in the elisp
> > manual.  It confuses bytes with characters, and it fails to mention the
> > need to keep BEG and END at character boundaries.  I propose installing
> > the following patch to the release branch:

> Thanks, I will review this later.  However:

> > @@ -580,7 +583,8 @@ Reading from Files
> >  This function works like @code{insert-file-contents} except that it
> >  does not run @code{after-insert-file-functions}, and does not do
> >  format decoding, character code conversion, automatic uncompression,
> > -and so on.
> > +and so on.  @var{beg} and @var{end}, if non-@code{nil}, should be at
> > +character boundaries, as in @code{insert-file-contents}.
> >  @end defun

> I don't think I understand why you made this second correction:
> insert-file-contents-literally deals with bytes to begin with.

> > The doc strings of insert-file-contents\(-literally\)? will also need to
> > be updated.

> In some sense, yes.

Here is an updated patch, superseding my patch from midday.  I have
amended the descriptions of the two functions, replacing "corruption" of
the buffer by "inserting raw-text characters" in the first function, and
added explanation to the second.

I wasn't able to find a suitable target for a cross-reference explaining
"raw-text".



diff --git a/doc/lispref/files.texi b/doc/lispref/files.texi
index 2dc808e694..63eaf24769 100644
--- a/doc/lispref/files.texi
+++ b/doc/lispref/files.texi
@@ -556,14 +556,18 @@ Reading from Files
 
 If @var{beg} and @var{end} are non-@code{nil}, they should be numbers
 that are byte offsets specifying the portion of the file to insert.
-In this case, @var{visit} must be @code{nil}.  For example,
+In this case, @var{visit} must be @code{nil}.  Be careful to ensure
+that these byte positions are at character boundaries.  Otherwise,
+Emacs's character code conversion will insert one or more raw-text
+characters into the buffer, which is probably not what you want.  For
+example,
 
 @example
 (insert-file-contents filename nil 0 500)
 @end example
 
 @noindent
-inserts the first 500 characters of a file.
+inserts the characters coded by the first 500 bytes of a file.
 
 If the argument @var{replace} is non-@code{nil}, it means to replace the
 contents of the buffer (actually, just the accessible portion) with the
@@ -577,10 +581,11 @@ Reading from Files
 @end defun
 
 @defun insert-file-contents-literally filename &optional visit beg end replace
-This function works like @code{insert-file-contents} except that it
-does not run @code{after-insert-file-functions}, and does not do
-format decoding, character code conversion, automatic uncompression,
-and so on.
+This function works like @code{insert-file-contents} except that each
+byte in the file is handled separately, being converted into a
+raw-text character if needed.  It does not run
+@code{after-insert-file-functions}, and does not do format decoding,
+character code conversion, automatic uncompression, and so on.
 @end defun
 
 If you want to pass a file name to another process so that another


-- 
Alan Mackenzie (Nuremberg, Germany).