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

[Alan Mackenzie]

Hello, Eli.

On Sun, Oct 03, 2021 at 18:25:57 +0300, Eli Zaretskii wrote:
> > Date: Sun, 3 Oct 2021 15:04:27 +0000
> > Cc: joaotavora@gmail.com, 50946@debbugs.gnu.org
> > From: Alan Mackenzie <acm@muc.de>

> > 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.

> Thanks, see below some comments.

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

> I think "Coding System Basics" is where we describe that encoding.

OK.

> > --- 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

> This isn't the whole story.  The problem is mainly with the
> autodetection of encoding: it can go awry if you give it only a
> portion of the file.  But if you bind coding-system-for-read, that
> problem goes away, and the only effect of using BEG and END arguments
> is limited to the first character/byte read.  In particular, if you
> read a file in chunks, the character at the boundary could end up as 2
> or more raw bytes -- but as long as you bind coding-system-for-read,
> no other parts are supposed to be affected.  And the problematic
> sequence of raw bytes can then be converted back to the original
> character with very simple Lisp.

OK, I've learnt something new.  Thanks!

> So the text you propose is too "frightening", in that it basically
> says "don't use that".  Which is too tough, because valid use cases to
> use that feature do exist, and if the programmer knows what he/she is
> doing it doesn't have to produce garbled buffers.  For the manual, we
> need more informative text, which mentions coding-system-for-read.

OK, how about this third version of my patch?



diff --git a/doc/lispref/files.texi b/doc/lispref/files.texi
index 2dc808e694..e73f53b040 100644
--- a/doc/lispref/files.texi
+++ b/doc/lispref/files.texi
@@ -563,7 +563,17 @@ Reading from Files
 @end example
 
 @noindent
-inserts the first 500 characters of a file.
+inserts the characters coded by the first 500 bytes of a file.
+
+If @var{beg} or @var{end} fails to be at a character boundary, Emacs's
+character code conversion will insert one or more raw-text characters
+(@pxref{Coding System Basics}) into the buffer.  If you want to read
+part of a file this way, you are recommended to bind
+@code{coding-system-for-read} to a suitable value around the call to
+this function (@pxref{Specifying Coding Systems}), and to write Lisp
+code which will check for raw-text characters at the boundaries, read
+the rest of these characters from the file, and convert them back to
+valid characters.
 
 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 +587,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).