To copy the contents of a file into a buffer, use the function
insert-file-contents
. (Don’t use the command
insert-file
in a Lisp program, as that sets the mark.)
insert-file-contents
filename &optional visit beg end replace ¶This function inserts the contents of file filename into the current buffer after point. It returns a list of the absolute file name and the length of the data inserted. An error is signaled if filename is not the name of a file that can be read.
This function checks the file contents against the defined file
formats, and converts the file contents if appropriate and also calls
the functions in the list after-insert-file-functions
.
See File Format Conversion. Normally, one of the functions in the
after-insert-file-functions
list determines the coding system
(see Coding Systems) used for decoding the file’s contents,
including end-of-line conversion. However, if the file contains null
bytes, it is by default visited without any code conversions.
See inhibit-null-byte-detection.
If visit is non-nil
, this function additionally marks the
buffer as unmodified and sets up various fields in the buffer so that it
is visiting the file filename: these include the buffer’s visited
file name and its last save file modtime. This feature is used by
find-file-noselect
and you probably should not use it yourself.
If beg and end are non-nil
, they should be numbers
that are byte offsets specifying the portion of the file to insert.
In this case, visit must be nil
. For example,
(insert-file-contents filename nil 0 500)
inserts the characters coded by the first 500 bytes of a file.
If beg or end happens to be in the middle of a character’s
multibyte sequence, Emacs’s character code conversion will insert one
or more eight-bit characters (a.k.a. “raw bytes”)
(see Character Sets) into the buffer. If you want to read part of
a file this way, we recommend to bind coding-system-for-read
to
a suitable value around the call to this function (see Specifying a Coding System for One Operation), and to write Lisp code which will check for raw
bytes at the boundaries, read the entire sequence of these bytes, and
convert them back to valid characters.
If the argument replace is non-nil
, it means to replace the
contents of the buffer (actually, just the accessible portion) with the
contents of the file. This is better than simply deleting the buffer
contents and inserting the whole file, because (1) it preserves some
marker positions and (2) it puts less data in the undo list.
It is possible to read a special file (such as a FIFO or an I/O
device) with insert-file-contents
, as long as replace,
and visit and beg are nil
. However, you should
normally use an end argument for these files to avoid inserting
(potentially) unlimited data into the buffer (for instance, when
inserting data from /dev/urandom).
insert-file-contents-literally
filename &optional visit beg end replace ¶This function works like insert-file-contents
except that each
byte in the file is handled separately, being converted into an
eight-bit character if needed. It does not run
after-insert-file-functions
, and does not do format decoding,
character code conversion, automatic uncompression, and so on.
If you want to pass a file name to another process so that another
program can read the file, use the function file-local-copy
; see
Making Certain File Names “Magic”.