+File: lispref.info, Node: Rename or Copy, Next: Numbered Backups, Prev: Making Backups, Up: Backup Files
+
+Backup by Renaming or by Copying?
+---------------------------------
+
+ There are two ways that XEmacs can make a backup file:
+
+ * XEmacs can rename the original file so that it becomes a backup
+ file, and then write the buffer being saved into a new file.
+ After this procedure, any other names (i.e., hard links) of the
+ original file now refer to the backup file. The new file is owned
+ by the user doing the editing, and its group is the default for
+ new files written by the user in that directory.
+
+ * XEmacs can copy the original file into a backup file, and then
+ overwrite the original file with new contents. After this
+ procedure, any other names (i.e., hard links) of the original file
+ still refer to the current version of the file. The file's owner
+ and group will be unchanged.
+
+ The first method, renaming, is the default.
+
+ The variable `backup-by-copying', if non-`nil', says to use the
+second method, which is to copy the original file and overwrite it with
+the new buffer contents. The variable `file-precious-flag', if
+non-`nil', also has this effect (as a sideline of its main
+significance). *Note Saving Buffers::.
+
+ - Variable: backup-by-copying
+ If this variable is non-`nil', XEmacs always makes backup files by
+ copying.
+
+ The following two variables, when non-`nil', cause the second method
+to be used in certain special cases. They have no effect on the
+treatment of files that don't fall into the special cases.
+
+ - Variable: backup-by-copying-when-linked
+ If this variable is non-`nil', XEmacs makes backups by copying for
+ files with multiple names (hard links).
+
+ This variable is significant only if `backup-by-copying' is `nil',
+ since copying is always used when that variable is non-`nil'.
+
+ - Variable: backup-by-copying-when-mismatch
+ If this variable is non-`nil', XEmacs makes backups by copying in
+ cases where renaming would change either the owner or the group of
+ the file.
+
+ The value has no effect when renaming would not alter the owner or
+ group of the file; that is, for files which are owned by the user
+ and whose group matches the default for a new file created there
+ by the user.
+
+ This variable is significant only if `backup-by-copying' is `nil',
+ since copying is always used when that variable is non-`nil'.
+
+\1f
+File: lispref.info, Node: Numbered Backups, Next: Backup Names, Prev: Rename or Copy, Up: Backup Files
+
+Making and Deleting Numbered Backup Files
+-----------------------------------------
+
+ If a file's name is `foo', the names of its numbered backup versions
+are `foo.~V~', for various integers V, like this: `foo.~1~', `foo.~2~',
+`foo.~3~', ..., `foo.~259~', and so on.
+
+ - User Option: version-control
+ This variable controls whether to make a single non-numbered backup
+ file or multiple numbered backups.
+
+ `nil'
+ Make numbered backups if the visited file already has
+ numbered backups; otherwise, do not.
+
+ `never'
+ Do not make numbered backups.
+
+ ANYTHING ELSE
+ Make numbered backups.
+
+ The use of numbered backups ultimately leads to a large number of
+backup versions, which must then be deleted. XEmacs can do this
+automatically or it can ask the user whether to delete them.
+
+ - User Option: kept-new-versions
+ The value of this variable is the number of newest versions to keep
+ when a new numbered backup is made. The newly made backup is
+ included in the count. The default value is 2.
+
+ - User Option: kept-old-versions
+ The value of this variable is the number of oldest versions to keep
+ when a new numbered backup is made. The default value is 2.
+
+ If there are backups numbered 1, 2, 3, 5, and 7, and both of these
+variables have the value 2, then the backups numbered 1 and 2 are kept
+as old versions and those numbered 5 and 7 are kept as new versions;
+backup version 3 is excess. The function `find-backup-file-name'
+(*note Backup Names::) is responsible for determining which backup
+versions to delete, but does not delete them itself.
+
+ - User Option: delete-old-versions
+ If this variable is non-`nil', then saving a file deletes excess
+ backup versions silently. Otherwise, it asks the user whether to
+ delete them.
+
+ - User Option: dired-kept-versions
+ This variable specifies how many of the newest backup versions to
+ keep in the Dired command `.' (`dired-clean-directory'). That's
+ the same thing `kept-new-versions' specifies when you make a new
+ backup file. The default value is 2.
+
+\1f
+File: lispref.info, Node: Backup Names, Prev: Numbered Backups, Up: Backup Files
+
+Naming Backup Files
+-------------------
+
+ The functions in this section are documented mainly because you can
+customize the naming conventions for backup files by redefining them.
+If you change one, you probably need to change the rest.
+
+ - Function: backup-file-name-p filename
+ This function returns a non-`nil' value if FILENAME is a possible
+ name for a backup file. A file with the name FILENAME need not
+ exist; the function just checks the name.
+
+ (backup-file-name-p "foo")
+ => nil
+ (backup-file-name-p "foo~")
+ => 3
+
+ The standard definition of this function is as follows:
+
+ (defun backup-file-name-p (file)
+ "Return non-nil if FILE is a backup file \
+ name (numeric or not)..."
+ (string-match "~$" file))
+
+ Thus, the function returns a non-`nil' value if the file name ends
+ with a `~'. (We use a backslash to split the documentation
+ string's first line into two lines in the text, but produce just
+ one line in the string itself.)
+
+ This simple expression is placed in a separate function to make it
+ easy to redefine for customization.
+
+ - Function: make-backup-file-name filename
+ This function returns a string that is the name to use for a
+ non-numbered backup file for file FILENAME. On Unix, this is just
+ FILENAME with a tilde appended.
+
+ The standard definition of this function is as follows:
+
+ (defun make-backup-file-name (file)
+ "Create the non-numeric backup file name for FILE.
+ ..."
+ (concat file "~"))
+
+ You can change the backup-file naming convention by redefining this
+ function. The following example redefines `make-backup-file-name'
+ to prepend a `.' in addition to appending a tilde:
+
+ (defun make-backup-file-name (filename)
+ (concat "." filename "~"))
+
+ (make-backup-file-name "backups.texi")
+ => ".backups.texi~"
+
+ - Function: find-backup-file-name filename
+ This function computes the file name for a new backup file for
+ FILENAME. It may also propose certain existing backup files for
+ deletion. `find-backup-file-name' returns a list whose CAR is the
+ name for the new backup file and whose CDR is a list of backup
+ files whose deletion is proposed.
+
+ Two variables, `kept-old-versions' and `kept-new-versions',
+ determine which backup versions should be kept. This function
+ keeps those versions by excluding them from the CDR of the value.
+ *Note Numbered Backups::.
+
+ In this example, the value says that `~rms/foo.~5~' is the name to
+ use for the new backup file, and `~rms/foo.~3~' is an "excess"
+ version that the caller should consider deleting now.
+
+ (find-backup-file-name "~rms/foo")
+ => ("~rms/foo.~5~" "~rms/foo.~3~")
+
+ - Function: file-newest-backup filename
+ This function returns the name of the most recent backup file for
+ FILENAME, or `nil' if that file has no backup files.
+
+ Some file comparison commands use this function so that they can
+ automatically compare a file with its most recent backup.
+
+\1f
+File: lispref.info, Node: Auto-Saving, Next: Reverting, Prev: Backup Files, Up: Backups and Auto-Saving
+
+Auto-Saving
+===========
+
+ XEmacs periodically saves all files that you are visiting; this is
+called "auto-saving". Auto-saving prevents you from losing more than a
+limited amount of work if the system crashes. By default, auto-saves
+happen every 300 keystrokes, or after around 30 seconds of idle time.
+*Note Auto-Save: (xemacs)Auto-Save, for information on auto-save for
+users. Here we describe the functions used to implement auto-saving
+and the variables that control them.
+
+ - Variable: buffer-auto-save-file-name
+ This buffer-local variable is the name of the file used for
+ auto-saving the current buffer. It is `nil' if the buffer should
+ not be auto-saved.
+
+ buffer-auto-save-file-name
+ => "/xcssun/users/rms/lewis/#files.texi#"
+
+ - Command: auto-save-mode arg
+ When used interactively without an argument, this command is a
+ toggle switch: it turns on auto-saving of the current buffer if it
+ is off, and vice-versa. With an argument ARG, the command turns
+ auto-saving on if the value of ARG is `t', a nonempty list, or a
+ positive integer. Otherwise, it turns auto-saving off.
+
+ - Function: auto-save-file-name-p filename
+ This function returns a non-`nil' value if FILENAME is a string
+ that could be the name of an auto-save file. It works based on
+ knowledge of the naming convention for auto-save files: a name that
+ begins and ends with hash marks (`#') is a possible auto-save file
+ name. The argument FILENAME should not contain a directory part.
+
+ (make-auto-save-file-name)
+ => "/xcssun/users/rms/lewis/#files.texi#"
+ (auto-save-file-name-p "#files.texi#")
+ => 0
+ (auto-save-file-name-p "files.texi")
+ => nil
+
+ The standard definition of this function is as follows:
+
+ (defun auto-save-file-name-p (filename)
+ "Return non-nil if FILENAME can be yielded by..."
+ (string-match "^#.*#$" filename))
+
+ This function exists so that you can customize it if you wish to
+ change the naming convention for auto-save files. If you redefine
+ it, be sure to redefine the function `make-auto-save-file-name'
+ correspondingly.
+
+ - Function: make-auto-save-file-name &optional filename
+ This function returns the file name to use for auto-saving the
+ current buffer. This is just the file name with hash marks (`#')
+ appended and prepended to it. This function does not look at the
+ variable `auto-save-visited-file-name' (described below); you
+ should check that before calling this function.
+
+ (make-auto-save-file-name)
+ => "/xcssun/users/rms/lewis/#backup.texi#"
+
+ The standard definition of this function is as follows:
+
+ (defun make-auto-save-file-name ()
+ "Return file name to use for auto-saves \
+ of current buffer.
+ ..."
+ (if buffer-file-name
+ (concat
+ (file-name-directory buffer-file-name)
+ "#"
+ (file-name-nondirectory buffer-file-name)
+ "#")
+ (expand-file-name
+ (concat "#%" (buffer-name) "#"))))
+
+ This exists as a separate function so that you can redefine it to
+ customize the naming convention for auto-save files. Be sure to
+ change `auto-save-file-name-p' in a corresponding way.
+
+ - Variable: auto-save-visited-file-name
+ If this variable is non-`nil', XEmacs auto-saves buffers in the
+ files they are visiting. That is, the auto-save is done in the
+ same file that you are editing. Normally, this variable is `nil',
+ so auto-save files have distinct names that are created by
+ `make-auto-save-file-name'.
+
+ When you change the value of this variable, the value does not take
+ effect until the next time auto-save mode is reenabled in any given
+ buffer. If auto-save mode is already enabled, auto-saves continue
+ to go in the same file name until `auto-save-mode' is called again.
+
+ - Function: recent-auto-save-p
+ This function returns `t' if the current buffer has been
+ auto-saved since the last time it was read in or saved.
+
+ - Function: set-buffer-auto-saved
+ This function marks the current buffer as auto-saved. The buffer
+ will not be auto-saved again until the buffer text is changed
+ again. The function returns `nil'.
+
+ - User Option: auto-save-interval
+ The value of this variable is the number of characters that XEmacs
+ reads from the keyboard between auto-saves. Each time this many
+ more characters are read, auto-saving is done for all buffers in
+ which it is enabled.
+
+ - User Option: auto-save-timeout
+ The value of this variable is the number of seconds of idle time
+ that should cause auto-saving. Each time the user pauses for this
+ long, XEmacs auto-saves any buffers that need it. (Actually, the
+ specified timeout is multiplied by a factor depending on the size
+ of the current buffer.)
+
+ - Variable: auto-save-hook
+ This normal hook is run whenever an auto-save is about to happen.
+
+ - User Option: auto-save-default
+ If this variable is non-`nil', buffers that are visiting files
+ have auto-saving enabled by default. Otherwise, they do not.
+
+ - Command: do-auto-save &optional no-message current-only
+ This function auto-saves all buffers that need to be auto-saved.
+ It saves all buffers for which auto-saving is enabled and that
+ have been changed since the previous auto-save.
+
+ Normally, if any buffers are auto-saved, a message that says
+ `Auto-saving...' is displayed in the echo area while auto-saving is
+ going on. However, if NO-MESSAGE is non-`nil', the message is
+ inhibited.
+
+ If CURRENT-ONLY is non-`nil', only the current buffer is
+ auto-saved.
+
+ - Function: delete-auto-save-file-if-necessary
+ This function deletes the current buffer's auto-save file if
+ `delete-auto-save-files' is non-`nil'. It is called every time a
+ buffer is saved.
+
+ - Variable: delete-auto-save-files
+ This variable is used by the function
+ `delete-auto-save-file-if-necessary'. If it is non-`nil', Emacs
+ deletes auto-save files when a true save is done (in the visited
+ file). This saves disk space and unclutters your directory.
+
+ - Function: rename-auto-save-file
+ This function adjusts the current buffer's auto-save file name if
+ the visited file name has changed. It also renames an existing
+ auto-save file. If the visited file name has not changed, this
+ function does nothing.
+
+ - Variable: buffer-saved-size
+ The value of this buffer-local variable is the length of the
+ current buffer as of the last time it was read in, saved, or
+ auto-saved. This is used to detect a substantial decrease in
+ size, and turn off auto-saving in response.
+
+ If it is -1, that means auto-saving is temporarily shut off in this
+ buffer due to a substantial deletion. Explicitly saving the buffer
+ stores a positive value in this variable, thus reenabling
+ auto-saving. Turning auto-save mode off or on also alters this
+ variable.
+
+ - Variable: auto-save-list-file-name
+ This variable (if non-`nil') specifies a file for recording the
+ names of all the auto-save files. Each time XEmacs does
+ auto-saving, it writes two lines into this file for each buffer
+ that has auto-saving enabled. The first line gives the name of
+ the visited file (it's empty if the buffer has none), and the
+ second gives the name of the auto-save file.
+
+ If XEmacs exits normally, it deletes this file. If XEmacs
+ crashes, you can look in the file to find all the auto-save files
+ that might contain work that was otherwise lost. The
+ `recover-session' command uses these files.
+
+ The default name for this file is in your home directory and
+ starts with `.saves-'. It also contains the XEmacs process ID and
+ the host name.
+
+\1f
+File: lispref.info, Node: Reverting, Prev: Auto-Saving, Up: Backups and Auto-Saving
+
+Reverting
+=========
+
+ If you have made extensive changes to a file and then change your
+mind about them, you can get rid of them by reading in the previous
+version of the file with the `revert-buffer' command. *Note Reverting
+a Buffer: (xemacs)Reverting.
+
+ - Command: revert-buffer &optional check-auto-save noconfirm
+ preserve-modes
+ This command replaces the buffer text with the text of the visited
+ file on disk. This action undoes all changes since the file was
+ visited or saved.
+
+ If the argument CHECK-AUTO-SAVE is non-`nil', and the latest
+ auto-save file is more recent than the visited file,
+ `revert-buffer' asks the user whether to use that instead.
+ Otherwise, it always uses the text of the visited file itself.
+ Interactively, CHECK-AUTO-SAVE is set if there is a numeric prefix
+ argument.
+
+ Normally, `revert-buffer' asks for confirmation before it changes
+ the buffer; but if the argument NOCONFIRM is non-`nil',
+ `revert-buffer' does not ask for confirmation.
+
+ Optional third argument PRESERVE-MODES non-`nil' means don't alter
+ the files modes. Normally we reinitialize them using
+ `normal-mode'.
+
+ Reverting tries to preserve marker positions in the buffer by
+ using the replacement feature of `insert-file-contents'. If the
+ buffer contents and the file contents are identical before the
+ revert operation, reverting preserves all the markers. If they
+ are not identical, reverting does change the buffer; then it
+ preserves the markers in the unchanged text (if any) at the
+ beginning and end of the buffer. Preserving any additional
+ markers would be problematical.
+
+ You can customize how `revert-buffer' does its work by setting these
+variables--typically, as buffer-local variables.
+
+ - Variable: revert-buffer-function
+ The value of this variable is the function to use to revert this
+ buffer. If non-`nil', it is called as a function with no
+ arguments to do the work of reverting. If the value is `nil',
+ reverting works the usual way.
+
+ Modes such as Dired mode, in which the text being edited does not
+ consist of a file's contents but can be regenerated in some other
+ fashion, give this variable a buffer-local value that is a
+ function to regenerate the contents.
+
+ - Variable: revert-buffer-insert-file-contents-function
+ The value of this variable, if non-`nil', is the function to use to
+ insert the updated contents when reverting this buffer. The
+ function receives two arguments: first the file name to use;
+ second, `t' if the user has asked to read the auto-save file.
+
+ - Variable: before-revert-hook
+ This normal hook is run by `revert-buffer' before actually
+ inserting the modified contents--but only if
+ `revert-buffer-function' is `nil'.
+
+ Font Lock mode uses this hook to record that the buffer contents
+ are no longer fontified.
+
+ - Variable: after-revert-hook
+ This normal hook is run by `revert-buffer' after actually inserting
+ the modified contents--but only if `revert-buffer-function' is
+ `nil'.
+
+ Font Lock mode uses this hook to recompute the fonts for the
+ updated buffer contents.
+
+\1f
+File: lispref.info, Node: Buffers, Next: Windows, Prev: Backups and Auto-Saving, Up: Top
+
+Buffers
+*******
+
+ A "buffer" is a Lisp object containing text to be edited. Buffers
+are used to hold the contents of files that are being visited; there may
+also be buffers that are not visiting files. While several buffers may
+exist at one time, exactly one buffer is designated the "current
+buffer" at any time. Most editing commands act on the contents of the
+current buffer. Each buffer, including the current buffer, may or may
+not be displayed in any window.
+
+* Menu:
+
+* Buffer Basics:: What is a buffer?
+* Current Buffer:: Designating a buffer as current
+ so primitives will access its contents.
+* Buffer Names:: Accessing and changing buffer names.
+* Buffer File Name:: The buffer file name indicates which file is visited.
+* Buffer Modification:: A buffer is "modified" if it needs to be saved.
+* Modification Time:: Determining whether the visited file was changed
+ ``behind XEmacs's back''.
+* Read Only Buffers:: Modifying text is not allowed in a read-only buffer.
+* The Buffer List:: How to look at all the existing buffers.
+* Creating Buffers:: Functions that create buffers.
+* Killing Buffers:: Buffers exist until explicitly killed.
+* Indirect Buffers:: An indirect buffer shares text with some other buffer.
+
+\1f
+File: lispref.info, Node: Buffer Basics, Next: Current Buffer, Up: Buffers
+
+Buffer Basics
+=============
+
+ A "buffer" is a Lisp object containing text to be edited. Buffers
+are used to hold the contents of files that are being visited; there may
+also be buffers that are not visiting files. While several buffers may
+exist at one time, exactly one buffer is designated the "current
+buffer" at any time. Most editing commands act on the contents of the
+current buffer. Each buffer, including the current buffer, may or may
+not be displayed in any windows.
+
+ Buffers in Emacs editing are objects that have distinct names and
+hold text that can be edited. Buffers appear to Lisp programs as a
+special data type. You can think of the contents of a buffer as an
+extendible string; insertions and deletions may occur in any part of
+the buffer. *Note Text::.
+
+ A Lisp buffer object contains numerous pieces of information. Some
+of this information is directly accessible to the programmer through
+variables, while other information is accessible only through
+special-purpose functions. For example, the visited file name is
+directly accessible through a variable, while the value of point is
+accessible only through a primitive function.
+
+ Buffer-specific information that is directly accessible is stored in
+"buffer-local" variable bindings, which are variable values that are
+effective only in a particular buffer. This feature allows each buffer
+to override the values of certain variables. Most major modes override
+variables such as `fill-column' or `comment-column' in this way. For
+more information about buffer-local variables and functions related to
+them, see *Note Buffer-Local Variables::.
+
+ For functions and variables related to visiting files in buffers, see
+*Note Visiting Files:: and *Note Saving Buffers::. For functions and
+variables related to the display of buffers in windows, see *Note
+Buffers and Windows::.
+
+ - Function: bufferp object
+ This function returns `t' if OBJECT is a buffer, `nil' otherwise.
+
+\1f