elisp: Visiting Functions
24.1.1 Functions for Visiting Files
-----------------------------------
This section describes the functions normally used to visit files. For
historical reasons, these functions have names starting with ‘find-’
rather than ‘visit-’. 
Buffer File Name, for functions and
variables that access the visited file name of a buffer or that find an
existing buffer by its visited file name.
In a Lisp program, if you want to look at the contents of a file but
not alter it, the fastest way is to use ‘insert-file-contents’ in a
temporary buffer. Visiting the file is not necessary and takes longer.
Reading from Files.
-- Command: find-file filename &optional wildcards
This command selects a buffer visiting the file FILENAME, using an
existing buffer if there is one, and otherwise creating a new
buffer and reading the file into it. It also returns that buffer.
Aside from some technical details, the body of the ‘find-file’
function is basically equivalent to:
(switch-to-buffer (find-file-noselect filename nil nil wildcards))
(See ‘switch-to-buffer’ in Switching Buffers.)
If WILDCARDS is non-‘nil’, which is always true in an interactive
call, then ‘find-file’ expands wildcard characters in FILENAME and
visits all the matching files.
When ‘find-file’ is called interactively, it prompts for FILENAME
in the minibuffer.
-- Command: find-file-literally filename
This command visits FILENAME, like ‘find-file’ does, but it does
not perform any format conversions (Format Conversion),
character code conversions (Coding Systems), or end-of-line
conversions (End of line conversion Coding System Basics.).
The buffer visiting the file is made unibyte, and its major mode is
Fundamental mode, regardless of the file name. File local variable
specifications in the file (File Local Variables) are
ignored, and automatic decompression and adding a newline at the
end of the file due to ‘require-final-newline’ (
require-final-newline Saving Buffers.) are also disabled.
Note that if Emacs already has a buffer visiting the same file
non-literally, it will not visit the same file literally, but
instead just switch to the existing buffer. If you want to be sure
of accessing a file’s contents literally, you should create a
temporary buffer and then read the file contents into it using
‘insert-file-contents-literally’ (Reading from Files).
-- Function: find-file-noselect filename &optional nowarn rawfile
wildcards
This function is the guts of all the file-visiting functions. It
returns a buffer visiting the file FILENAME. You may make the
buffer current or display it in a window if you wish, but this
function does not do so.
The function returns an existing buffer if there is one; otherwise
it creates a new buffer and reads the file into it. When
‘find-file-noselect’ uses an existing buffer, it first verifies
that the file has not changed since it was last visited or saved in
that buffer. If the file has changed, this function asks the user
whether to reread the changed file. If the user says ‘yes’, any
edits previously made in the buffer are lost.
Reading the file involves decoding the file’s contents (
Coding Systems), including end-of-line conversion, and format
conversion (Format Conversion). If WILDCARDS is non-‘nil’,
then ‘find-file-noselect’ expands wildcard characters in FILENAME
and visits all the matching files.
This function displays warning or advisory messages in various
peculiar cases, unless the optional argument NOWARN is non-‘nil’.
For example, if it needs to create a buffer, and there is no file
named FILENAME, it displays the message ‘(New file)’ in the echo
area, and leaves the buffer empty.
The ‘find-file-noselect’ function normally calls ‘after-find-file’
after reading the file (Subroutines of Visiting). That
function sets the buffer major mode, parses local variables, warns
the user if there exists an auto-save file more recent than the
file just visited, and finishes by running the functions in
‘find-file-hook’.
If the optional argument RAWFILE is non-‘nil’, then
‘after-find-file’ is not called, and the
‘find-file-not-found-functions’ are not run in case of failure.
What’s more, a non-‘nil’ RAWFILE value suppresses coding system
conversion and format conversion.
The ‘find-file-noselect’ function usually returns the buffer that
is visiting the file FILENAME. But, if wildcards are actually used
and expanded, it returns a list of buffers that are visiting the
various files.
(find-file-noselect "/etc/fstab")
⇒ #<buffer fstab>
-- Command: find-file-other-window filename &optional wildcards
This command selects a buffer visiting the file FILENAME, but does
so in a window other than the selected window. It may use another
existing window or split a window; see Switching Buffers.
When this command is called interactively, it prompts for FILENAME.
-- Command: find-file-read-only filename &optional wildcards
This command selects a buffer visiting the file FILENAME, like
‘find-file’, but it marks the buffer as read-only. Read Only
Buffers, for related functions and variables.
When this command is called interactively, it prompts for FILENAME.
-- User Option: find-file-wildcards
If this variable is non-‘nil’, then the various ‘find-file’
commands check for wildcard characters and visit all the files that
match them (when invoked interactively or when their WILDCARDS
argument is non-‘nil’). If this option is ‘nil’, then the
‘find-file’ commands ignore their WILDCARDS argument and never
treat wildcard characters specially.
-- User Option: find-file-hook
The value of this variable is a list of functions to be called
after a file is visited. The file’s local-variables specification
(if any) will have been processed before the hooks are run. The
buffer visiting the file is current when the hook functions are
run.
This variable is a normal hook. Hooks.
-- Variable: find-file-not-found-functions
The value of this variable is a list of functions to be called when
‘find-file’ or ‘find-file-noselect’ is passed a nonexistent file
name. ‘find-file-noselect’ calls these functions as soon as it
detects a nonexistent file. It calls them in the order of the
list, until one of them returns non-‘nil’. ‘buffer-file-name’ is
already set up.
This is not a normal hook because the values of the functions are
used, and in many cases only some of the functions are called.
-- Variable: find-file-literally
This buffer-local variable, if set to a non-‘nil’ value, makes
‘save-buffer’ behave as if the buffer were visiting its file
literally, i.e., without conversions of any kind. The command
‘find-file-literally’ sets this variable’s local value, but other
equivalent functions and commands can do that as well, e.g., to
avoid automatic addition of a newline at the end of the file. This
variable is permanent local, so it is unaffected by changes of
major modes.
Info Catalog
elisp: Visiting Files
elisp: Subroutines of Visiting