25.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-'. See section 27.4 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. See section 25.3 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.

The body of the find-file function is very simple and looks like this:

(switch-to-buffer (find-file-noselect filename))

(See switch-to-buffer in 28.7 Displaying Buffers in Windows.)

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.

Function: find-file-noselect filename &optional nowarn rawfile wildcards

This function is the guts of all the file-visiting functions. It finds or creates a buffer visiting the file filename, and returns it. It uses an existing buffer if there is one, and otherwise creates a new buffer and reads the file into it. You may make the buffer current or display it in a window if you wish, but this function does not do so.

If wildcards is non-nil, then find-file-noselect expands wildcard characters in filename and visits all the matching files.

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, then this function asks the user whether to reread the changed file. If the user says `yes', any changes previously made in the buffer are lost.

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 (see section 25.1.2 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-hooks.

If the optional argument rawfile is non-nil, then after-find-file is not called, and the find-file-not-found-hooks are not run in case of failure. What's more, a non-nil rawfile value suppresses coding system conversion (see section 33.10 Coding Systems) and format conversion (see section 25.12 File 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 28.7 Displaying Buffers in Windows.

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. See section 27.7 Read-Only Buffers, for related functions and variables.

When this command is called interactively, it prompts for filename.

Command: view-file filename

This command visits filename using View mode, returning to the previous buffer when you exit View mode. View mode is a minor mode that provides commands to skim rapidly through the file, but does not let you modify the text. Entering View mode runs the normal hook view-mode-hook. See section 23.6 Hooks.

When view-file is called interactively, it prompts for filename.

Variable: 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. If this is nil, then wildcard characters are not treated specially.

Variable: find-file-hooks

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 works just like a normal hook, but we think that renaming it would not be advisable. See section 23.6 Hooks.

Variable: find-file-not-found-hooks

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.