@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990-1995, 1998-1999, 2001-2012
-@c Free Software Foundation, Inc.
+@c Copyright (C) 1990-1995, 1998-1999, 2001-2015 Free Software
+@c Foundation, Inc.
@c See the file elisp.texi for copying conditions.
-@node Buffers, Windows, Backups and Auto-Saving, Top
+@node Buffers
@chapter Buffers
@cindex buffer
* Buffer File Name:: The buffer file name indicates which file is visited.
* Buffer Modification:: A buffer is @dfn{modified} if it needs to be saved.
* Modification Time:: Determining whether the visited file was changed
- ``behind Emacs's back''.
+ behind Emacs'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.
+* 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.
@end menu
@node Buffer Basics
-@comment node-name, next, previous, up
@section Buffer Basics
@ifnottex
use.
If @var{filename} is @code{nil} or the empty string, that stands for
-``no visited file.'' In this case, @code{set-visited-file-name} marks
+``no visited file''. In this case, @code{set-visited-file-name} marks
the buffer as having no visited file, without changing the buffer's
modified flag.
already is a buffer visiting @var{filename}. If @var{no-query} is
non-@code{nil}, that prevents asking this question. If there already
is a buffer visiting @var{filename}, and the user confirms or
-@var{query} is non-@code{nil}, this function makes the new buffer name
-unique by appending a number inside of @samp{<@dots{}>} to @var{filename}.
+@var{no-query} is non-@code{nil}, this function makes the new
+buffer name unique by appending a number inside of @samp{<@dots{}>} to
+@var{filename}.
If @var{along-with-file} is non-@code{nil}, that means to assume that
the former visited file has been renamed to @var{filename}. In this
@end defun
@node Modification Time
-@comment node-name, next, previous, up
@section Buffer Modification Time
@cindex comparing file modification time
@cindex modification time of buffer
file should not be done.
@end defun
-@c Emacs 19 feature
@defun visited-file-modtime
This function returns the current buffer's recorded last file
-modification time, as a list of the form @code{(@var{high} @var{low})}.
-(This is the same format that @code{file-attributes} uses to return
-time values; see @ref{File Attributes}.)
+modification time, as a list of the form @code{(@var{high} @var{low}
+@var{microsec} @var{picosec})}. (This is the same format that
+@code{file-attributes} uses to return time values; @pxref{File
+Attributes}.)
If the buffer has no recorded last modification time, this function
returns zero. This case occurs, for instance, if the buffer is not
too. For instance, in a Dired buffer listing a directory, it returns
the last modification time of that directory, as recorded by Dired.
-For a new buffer visiting a not yet existing file, @var{high} is
-@minus{}1 and @var{low} is 65535, that is,
-@ifnottex
-@w{2**16 - 1.}
-@end ifnottex
-@tex
-@math{2^{16}-1}.
-@end tex
+If the buffer is not visiting a file, this function returns -1.
@end defun
-@c Emacs 19 feature
@defun set-visited-file-modtime &optional time
This function updates the buffer's record of the last modification time
of the visited file, to the value specified by @var{time} if @var{time}
visited file.
If @var{time} is neither @code{nil} nor zero, it should have the form
-@code{(@var{high} . @var{low})} or @code{(@var{high} @var{low})}, in
-either case containing two integers, each of which holds 16 bits of the
-time.
+@code{(@var{high} @var{low} @var{microsec} @var{picosec})},
+the format used by @code{current-time} (@pxref{Time of Day}).
This function is useful if the buffer was not read from the file
normally, or if the file itself has been changed for some known benign
@defvar buffer-read-only
This buffer-local variable specifies whether the buffer is read-only.
-The buffer is read-only if this variable is non-@code{nil}.
+The buffer is read-only if this variable is non-@code{nil}. However,
+characters that have the @code{inhibit-read-only} text property can
+still be modified. @xref{Special Properties, inhibit-read-only}.
@end defvar
@defvar inhibit-read-only
If this variable is non-@code{nil}, then read-only buffers and,
depending on the actual value, some or all read-only characters may be
-modified. Read-only characters in a buffer are those that have
-non-@code{nil} @code{read-only} properties (either text properties or
-overlay properties). @xref{Special Properties}, for more information
-about text properties. @xref{Overlays}, for more information about
-overlays and their properties.
+modified. Read-only characters in a buffer are those that have a
+non-@code{nil} @code{read-only} text property. @xref{Special
+Properties}, for more information about text properties.
If @code{inhibit-read-only} is @code{t}, all @code{read-only} character
properties have no effect. If @code{inhibit-read-only} is a list, then
of the list (comparison is done with @code{eq}).
@end defvar
-@deffn Command toggle-read-only &optional arg
-This command toggles whether the current buffer is read-only. It is
-intended for interactive use; do not use it in programs (it may have
-side-effects, such as enabling View mode, and does not affect
-read-only text properties). To change the read-only state of a buffer in
-a program, explicitly set @code{buffer-read-only} to the proper value.
-To temporarily ignore a read-only state, bind @code{inhibit-read-only}.
-
-If @var{arg} is non-@code{nil}, it should be a raw prefix argument.
-@code{toggle-read-only} sets @code{buffer-read-only} to @code{t} if
-the numeric value of that prefix argument is positive and to
-@code{nil} otherwise. @xref{Prefix Command Arguments}.
+@deffn Command read-only-mode &optional arg
+This is the mode command for Read Only minor mode, a buffer-local
+minor mode. When the mode is enabled, @code{buffer-read-only} is
+non-@code{nil} in the buffer; when disabled, @code{buffer-read-only}
+is @code{nil} in the buffer. The calling convention is the same as
+for other minor mode commands (@pxref{Minor Mode Conventions}).
+
+This minor mode mainly serves as a wrapper for
+@code{buffer-read-only}; unlike most minor modes, there is no separate
+@code{read-only-mode} variable. Even when Read Only mode is disabled,
+characters with non-@code{nil} @code{read-only} text properties remain
+read-only. To temporarily ignore all read-only states, bind
+@code{inhibit-read-only}, as described above.
+
+When enabling Read Only mode, this mode command also enables View mode
+if the option @code{view-read-only} is non-@code{nil}. @xref{Misc
+Buffer,,Miscellaneous Buffer Operations, emacs, The GNU Emacs Manual}.
+When disabling Read Only mode, it disables View mode if View mode was
+enabled.
@end deffn
@defun barf-if-buffer-read-only
signal an error if the current buffer is read-only.
@end defun
-@node The Buffer List
+@node Buffer List
@section The Buffer List
@cindex buffer list
+@cindex listing all buffers
The @dfn{buffer list} is a list of all live buffers. The order of the
buffers in this list is based primarily on how recently each buffer has
If @var{buffer} is not supplied (or if it is not a live buffer), then
@code{other-buffer} returns the first buffer in the selected frame's
-local buffer list. (If @var{frame} is non-@code{nil}, it returns the
+local buffer list. (If @var{frame} is non-@code{nil}, it returns the
first buffer in @var{frame}'s local buffer list instead.)
If @var{frame} has a non-@code{nil} @code{buffer-predicate} parameter,
@defun last-buffer &optional buffer visible-ok frame
This function returns the last buffer in @var{frame}'s buffer list other
-than @var{BUFFER}. If @var{frame} is omitted or @code{nil}, it uses the
+than @var{buffer}. If @var{frame} is omitted or @code{nil}, it uses the
selected frame's buffer list.
The argument @var{visible-ok} is handled as with @code{other-buffer},
@code{other-buffer} to return. The argument can be either a buffer
itself or the name of one.
-This functions operates on each frame's @code{buffer-list} parameter as
+This function operates on each frame's @code{buffer-list} parameter as
well as the fundamental buffer list; therefore, the buffer that you bury
will come last in the value of @code{(buffer-list @var{frame})} and in
the value of @code{(buffer-list)}. In addition, it also puts the buffer
If @var{buffer-or-name} is @code{nil} or omitted, this means to bury the
current buffer. In addition, if the current buffer is displayed in the
selected window, this makes sure that the window is either deleted or
-another buffer is shown in it. More precisely, if the window is
-dedicated (@pxref{Dedicated Windows}) and there are other windows on its
-frame, the window is deleted. If the window is both dedicated and the
-only window on its frame's terminal, the function specified by
-@code{frame-auto-hide-function} (@pxref{Quitting Windows}) will deal
-with the window. If the window is not dedicated to its buffer, it calls
-@code{switch-to-prev-buffer} (@pxref{Window History}) to show another
-buffer in that window. If @var{buffer-or-name} is displayed in some
-other window, it remains displayed there.
+another buffer is shown in it. More precisely, if the selected window
+is dedicated (@pxref{Dedicated Windows}) and there are other windows on
+its frame, the window is deleted. If it is the only window on its frame
+and that frame is not the only frame on its terminal, the frame is
+dismissed by calling the function specified by
+@code{frame-auto-hide-function} (@pxref{Quitting Windows}). Otherwise,
+it calls @code{switch-to-prev-buffer} (@pxref{Window History}) to show
+another buffer in that window. If @var{buffer-or-name} is displayed in
+some other window, it remains displayed there.
To replace a buffer in all the windows that display it, use
@code{replace-buffer-in-windows}, @xref{Buffers and Windows}.
window.
@end deffn
+@defvar buffer-list-update-hook
+This is a normal hook run whenever the buffer list changes. Functions
+(implicitly) running this hook are @code{get-buffer-create}
+(@pxref{Creating Buffers}), @code{rename-buffer} (@pxref{Buffer Names}),
+@code{kill-buffer} (@pxref{Killing Buffers}), @code{bury-buffer} (see
+above) and @code{select-window} (@pxref{Selecting Windows}).
+@end defvar
@node Creating Buffers
@section Creating Buffers
buffer.
Any processes that have this buffer as the @code{process-buffer} are
-sent the @code{SIGHUP} (``hangup'') signal, which normally causes them
+sent the @code{SIGHUP} (hangup) signal, which normally causes them
to terminate. @xref{Signals to Processes}.
If the buffer is visiting a file and contains unsaved changes,
@end deffn
@defvar kill-buffer-query-functions
-After confirming unsaved changes, @code{kill-buffer} calls the functions
+Before confirming unsaved changes, @code{kill-buffer} calls the functions
in the list @code{kill-buffer-query-functions}, in order of appearance,
with no arguments. The buffer being killed is the current buffer when
they are called. The idea of this feature is that these functions will
@var{name} is the name of an existing buffer, an error is signaled.
If @var{clone} is non-@code{nil}, then the indirect buffer originally
-shares the ``state'' of @var{base-buffer} such as major mode, minor
+shares the state of @var{base-buffer} such as major mode, minor
modes, buffer local variables and so on. If @var{clone} is omitted
or @code{nil} the indirect buffer's state is set to the default state
for new buffers.
@node Buffer Gap
@section The Buffer Gap
+@cindex buffer gap
Emacs buffers are implemented using an invisible @dfn{gap} to make
insertion and deletion faster. Insertion works by filling in part of
@defun gap-size
This function returns the current gap size of the current buffer.
@end defun
-