@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
@chapter Buffers
* Modification Time:: Determining whether the visited file was changed
"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.
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
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
of the list (comparison is done with @code{eq}).
@end defvar
-@deffn Command toggle-read-only &optional arg message
-This command toggles whether the current buffer is read-only, by
-setting the variable @code{buffer-read-only}. If @var{arg} is
-non-@code{nil}, it should be a raw prefix argument; the command then
-makes the buffer read-only if the numeric value of that prefix
-argument is positive, and makes the buffer writable otherwise.
-@xref{Prefix Command Arguments}.
-
-If called interactively, or if called from Lisp with @var{message} is
-non-@code{nil}, the command prints a message reporting the buffer's
-new read-only status.
-
-When making the buffer read-only, this command also enables View mode
+@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 making the buffer writable, it disables View mode if View mode
-was enabled.
-
-Lisp programs should only call @code{toggle-read-only} if they really
-intend to do the same thing as the user command, including possibly
-enabling or disabling View mode. Note also that this command works by
-setting @code{buffer-read-only}, so even if you make the buffer
-writable, characters with non-@code{nil} @code{read-only} text
-properties will remain read-only. To temporarily ignore all read-only
-states, bind @code{inhibit-read-only}, as described above.
+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
@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
@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
@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
-