GNU Info

(elisp)Visiting Functions

---

Next: Subroutines of Visiting Up: Visiting Files

---

Enter node , (file) or (file)node

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-'.  Note: 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.
Note: 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 Note: Displaying 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.

 - 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 (Note: 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 (Note: Coding Systems) and format conversion (Note:
     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 Note: Displaying 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.  Note: 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'.  Note: 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.  Note: 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.