X-Git-Url: https://code.delx.au/gnu-emacs/blobdiff_plain/b9345dfd4b5479ec624f1870723a8ea5c9c719e7..d5d8ca30e5f481a32414c42bcc3b5a042061ff07:/doc/lispref/backups.texi diff --git a/doc/lispref/backups.texi b/doc/lispref/backups.texi index aad0cbc146..63f8f227c8 100644 --- a/doc/lispref/backups.texi +++ b/doc/lispref/backups.texi @@ -1,9 +1,9 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1995, 1999, 2001-2011 Free Software Foundation, Inc. +@c Copyright (C) 1990-1995, 1999, 2001-2014 Free Software Foundation, +@c Inc. @c See the file elisp.texi for copying conditions. -@setfilename ../../info/backups -@node Backups and Auto-Saving, Buffers, Files, Top +@node Backups and Auto-Saving @chapter Backups and Auto-Saving @cindex backups and auto-saving @@ -57,12 +57,15 @@ buffer, if appropriate. It is called by @code{save-buffer} before saving the buffer the first time. If a backup was made by renaming, the return value is a cons cell of -the form (@var{modes} . @var{backupname}), where @var{modes} are the -mode bits of the original file, as returned by @code{file-modes} -(@pxref{File Attributes,, Other Information about Files}), and -@var{backupname} is the name of the backup. In all other cases, that -is, if a backup was made by copying or if no backup was made, this -function returns @code{nil}. +the form (@var{modes} @var{extra-alist} @var{backupname}), where +@var{modes} are the mode bits of the original file, as returned by +@code{file-modes} (@pxref{Testing Accessibility}), @var{extra-alist} +is an alist describing the original file's extended attributes, as +returned by @code{file-extended-attributes} (@pxref{Extended +Attributes}), and @var{backupname} is the name of the backup. + +In all other cases (i.e., if a backup was made by copying or if no +backup was made), this function returns @code{nil}. @end defun @defvar buffer-backed-up @@ -87,8 +90,7 @@ save disk space. (You would put this code in your init file.) @smallexample @group (add-hook 'rmail-mode-hook - (lambda () - (set (make-local-variable 'make-backup-files) nil))) + (lambda () (setq-local make-backup-files nil))) @end group @end smallexample @end defopt @@ -139,21 +141,20 @@ For the common case of all backups going into one directory, the alist should contain a single element pairing @samp{"."} with the appropriate directory name. -If this variable is @code{nil}, or it fails to match a filename, the -backup is made in the original file's directory. +If this variable is @code{nil} (the default), or it fails to match a +filename, the backup is made in the original file's directory. On MS-DOS filesystems without long names this variable is always ignored. @end defopt @defopt make-backup-file-name-function -This variable's value is a function to use for making backups instead -of the default @code{make-backup-file-name}. A value of @code{nil} -gives the default @code{make-backup-file-name} behavior. +This variable's value is a function to use for making backup file names. +The function @code{make-backup-file-name} calls it. @xref{Backup Names,, Naming Backup Files}. This could be buffer-local to do something special for specific -files. If you define it, you may need to change +files. If you change it, you may need to change @code{backup-file-name-p} and @code{file-name-sans-versions} too. @end defopt @@ -191,7 +192,7 @@ significance). @xref{Saving Buffers}. @defopt backup-by-copying If this variable is non-@code{nil}, Emacs always makes backup files by -copying. +copying. The default is @code{nil}. @end defopt The following three variables, when non-@code{nil}, cause the second @@ -200,7 +201,7 @@ treatment of files that don't fall into the special cases. @defopt backup-by-copying-when-linked If this variable is non-@code{nil}, Emacs makes backups by copying for -files with multiple names (hard links). +files with multiple names (hard links). The default is @code{nil}. This variable is significant only if @code{backup-by-copying} is @code{nil}, since copying is always used when that variable is @@ -208,8 +209,9 @@ non-@code{nil}. @end defopt @defopt backup-by-copying-when-mismatch -If this variable is non-@code{nil}, Emacs makes backups by copying in cases -where renaming would change either the owner or the group of the file. +If this variable is non-@code{nil} (the default), Emacs 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 @@ -440,11 +442,14 @@ buffer-auto-save-file-name @end defvar @deffn 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 @var{arg}, the command turns auto-saving -on if the value of @var{arg} is @code{t}, a nonempty list, or a positive -integer. Otherwise, it turns auto-saving off. +This is the mode command for Auto Save mode, a buffer-local minor +mode. When Auto Save mode is enabled, auto-saving is enabled in the +buffer. The calling convention is the same as for other minor mode +commands (@pxref{Minor Mode Conventions}). + +Unlike most minor modes, there is no @code{auto-save-mode} variable. +Auto Save mode is enabled if @code{buffer-auto-save-file-name} is +non-@code{nil} and @code{buffer-saved-size} (see below) is non-zero. @end deffn @defun auto-save-file-name-p filename @@ -657,7 +662,7 @@ host name. After Emacs reads your init file, it initializes @code{auto-save-list-file-name} (if you have not already set it non-@code{nil}) based on this prefix, adding the host name and process -ID. If you set this to @code{nil} in your init file, then Emacs does +ID@. If you set this to @code{nil} in your init file, then Emacs does not initialize @code{auto-save-list-file-name}. @end defopt @@ -698,6 +703,11 @@ the markers in the unchanged text (if any) at the beginning and end of the buffer. Preserving any additional markers would be problematical. @end deffn +@defvar revert-buffer-in-progress-p +@code{revert-buffer} binds this variable to a non-@code{nil} value +while it is working. +@end defvar + You can customize how @code{revert-buffer} does its work by setting the variables described in the rest of this section. @@ -715,25 +725,24 @@ buffer-local bindings for these variables: @defvar revert-buffer-function @anchor{Definition of revert-buffer-function} The value of this variable is the function to use to revert this -buffer. If non-@code{nil}, it should be a function with two optional +buffer. It should be a function with two optional arguments to do the work of reverting. The two optional arguments, @var{ignore-auto} and @var{noconfirm}, are the arguments that -@code{revert-buffer} received. If the value is @code{nil}, reverting -works the usual way. +@code{revert-buffer} received. 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, can give this variable a buffer-local value that is a function to -regenerate the contents. +fashion, can give this variable a buffer-local value that is a special +function to regenerate the contents. @end defvar @defvar revert-buffer-insert-file-contents-function -The value of this variable, if non-@code{nil}, specifies the function to use to +The value of this variable specifies 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, @code{t} if the user has asked to read the auto-save file. -The reason for a mode to set this variable instead of +The reason for a mode to change this variable instead of @code{revert-buffer-function} is to avoid duplicating or replacing the rest of what @code{revert-buffer} does: asking for confirmation, clearing the undo list, deciding the proper major mode, and running the @@ -741,13 +750,27 @@ hooks listed below. @end defvar @defvar before-revert-hook -This normal hook is run by @code{revert-buffer} before -inserting the modified contents---but only if -@code{revert-buffer-function} is @code{nil}. +This normal hook is run by the default @code{revert-buffer-function} +before inserting the modified contents. A custom @code{revert-buffer-function} +may or may not run this hook. @end defvar @defvar after-revert-hook -This normal hook is run by @code{revert-buffer} after inserting -the modified contents---but only if @code{revert-buffer-function} is -@code{nil}. +This normal hook is run by the default @code{revert-buffer-function} +after inserting the modified contents. A custom @code{revert-buffer-function} +may or may not run this hook. +@end defvar + +@c FIXME? Move this section from arevert-xtra to here? +@defvar buffer-stale-function +The value of this variable specifies a function to call to check +whether a buffer needs reverting. The default value only handles +buffers that are visiting files, by checking their modification time. +Buffers that are not visiting files require a custom function +@iftex +(@pxref{Supporting additional buffers,,, emacs-xtra, Specialized Emacs Features}). +@end iftex +@ifnottex +(@pxref{Supporting additional buffers,,, emacs}). +@end ifnottex @end defvar