25.3 Reading from Files

You can copy a file from the disk and insert it into a buffer using the insert-file-contents function. Don't use the user-level command insert-file in a Lisp program, as that sets the mark.

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

The function insert-file-contents checks the file contents against the defined file formats, and converts the file contents if appropriate. See section 25.12 File Format Conversion. It also calls the functions in the list after-insert-file-functions; see 32.19.7 Saving Text Properties in Files. Normally, one of the functions in the after-insert-file-functions list determines the coding system (see section 33.10 Coding Systems) used for decoding the file's contents.

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 integers 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 first 500 characters of a file.

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

Function: insert-file-contents-literally filename &optional visit beg end replace

This function works like insert-file-contents except that it does not do format decoding (see section 25.12 File Format Conversion), does not do character code conversion (see section 33.10 Coding Systems), does not run find-file-hooks, does not perform 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 25.11 Making Certain File Names "Magic".