@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001, 2002,
-@c 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012 Free Software Foundation, Inc.
+@c Copyright (C) 1990-1995, 1998-1999, 2001-2014 Free Software
+@c Foundation, Inc.
@c See the file elisp.texi for copying conditions.
-@setfilename ../../info/buffers
-@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
buffer that the cursor is in, when Emacs reads a command, is the
buffer to which that command applies (@pxref{Command Loop}). Thus,
you should not use @code{set-buffer} to switch visibly to a different
-buffer; for that, use the functions described in @ref{Displaying
+buffer; for that, use the functions described in @ref{Switching
Buffers}.
When writing a Lisp function, do @emph{not} rely on this behavior of
visited in the current buffer, or @code{nil} if no file is visited.
It is a permanent local, unaffected by
@code{kill-all-local-variables}. @xref{Truenames}, and
-@ref{Definition of abbreviate-file-name}.
+@ref{abbreviate-file-name}.
@end defvar
@defvar buffer-file-number
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
last file modification time, after which @code{visited-file-modtime}
returns zero.
-@c Wordy to avoid overfull hbox. --rjc 16mar92
-When the function @code{set-visited-file-name} is called interactively, it
-prompts for @var{filename} in the minibuffer.
+When the function @code{set-visited-file-name} is called
+interactively, it prompts for @var{filename} in the minibuffer.
@end deffn
@defvar list-buffers-directory
@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
described below before saving the file. (@xref{File Attributes},
for how to examine a file's modification time.)
-@defun verify-visited-file-modtime buffer
-This function compares what @var{buffer} has recorded for the
-modification time of its visited file against the actual modification
-time of the file as recorded by the operating system. The two should be
-the same unless some other process has written the file since Emacs
-visited or saved it.
+@defun verify-visited-file-modtime &optional buffer
+This function compares what @var{buffer} (by default, the
+current-buffer) has recorded for the modification time of its visited
+file against the actual modification time of the file as recorded by the
+operating system. The two should be the same unless some other process
+has written the file since Emacs visited or saved it.
The function returns @code{t} if the last actual modification time and
Emacs's recorded modification time are the same, @code{nil} otherwise.
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 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. At any given
-point in a program, you should know whether you want the read-only flag
-on or off; so you can set @code{buffer-read-only} explicitly to the
-proper value, @code{t} or @code{nil}.
-
-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
@code{other-buffer}, use this ordering. A buffer list displayed for the
user also follows this order.
- Creating a buffer adds it to the end of the buffer list, and killing a
-buffer removes it from that list. A buffer moves to the front of this
-list whenever it is chosen for display in a window (@pxref{Displaying
-Buffers}) or a window displaying it is selected (@pxref{Selecting
-Windows}). A buffer moves to the end of the list when it is buried (see
-@code{bury-buffer}, below). There are no functions available to the
-Lisp programmer which directly manipulate the buffer list.
+ Creating a buffer adds it to the end of the buffer list, and killing
+a buffer removes it from that list. A buffer moves to the front of
+this list whenever it is chosen for display in a window
+(@pxref{Switching Buffers}) or a window displaying it is selected
+(@pxref{Selecting Windows}). A buffer moves to the end of the list
+when it is buried (see @code{bury-buffer}, below). There are no
+functions available to the Lisp programmer which directly manipulate
+the buffer list.
In addition to the fundamental buffer list just described, Emacs
maintains a local buffer list for each frame, in which the buffers that
resort. If @var{visible-ok} is non-@code{nil}, then it does not matter
whether a buffer is displayed somewhere or not.
-If no suitable buffer exists, the buffer @samp{*scratch*} is returned
+If no suitable buffer exists, the buffer @file{*scratch*} is returned
(and created, if necessary).
@end defun
The argument @var{visible-ok} is handled as with @code{other-buffer},
see above. If no suitable buffer can be found, the buffer
-@samp{*scratch*} is returned.
+@file{*scratch*} is returned.
@end defun
@deffn Command bury-buffer &optional buffer-or-name
@code{other-buffer} to return. The argument can be either a buffer
itself or the name of one.
-@code{bury-buffer} 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)}.
+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
+at the end of the list of buffer of the selected window (@pxref{Window
+History}) provided it is shown in that window.
If @var{buffer-or-name} is @code{nil} or omitted, this means to bury the
-current buffer. In addition, if the buffer is displayed in the selected
-window, this switches to some other buffer (obtained using
-@code{other-buffer}) in the selected window. @xref{Displaying Buffers}.
-But if the selected window is dedicated to its buffer, it deletes that
-window if there are other windows left on its frame. Otherwise, if the
-selected window is the only window on its frame, it iconifies that
-frame. If @var{buffer-or-name} is displayed in some other window, it
-remains displayed there.
+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 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}.
+@code{replace-buffer-in-windows}, @xref{Buffers and Windows}.
@end deffn
@deffn Command unbury-buffer
-This command switches to the last buffer in the local buffer list of the
-selected frame. More precisely, it calls the function
-@code{switch-to-buffer} (@pxref{Displaying Buffers}), to display the
-buffer returned by @code{last-buffer}, see above, in the selected
+This command switches to the last buffer in the local buffer list of
+the selected frame. More precisely, it calls the function
+@code{switch-to-buffer} (@pxref{Switching Buffers}), to display the
+buffer returned by @code{last-buffer} (see above), in the selected
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
@defun generate-new-buffer name
This function returns a newly created, empty buffer, but does not make
-it current. If there is no buffer named @var{name}, then that is the
-name of the new buffer. If that name is in use, this function adds
-suffixes of the form @samp{<@var{n}>} to @var{name}, where @var{n} is an
-integer. It tries successive integers starting with 2 until it finds an
-available name.
+it current. The name of the buffer is generated by passing @var{name}
+to the function @code{generate-new-buffer-name} (@pxref{Buffer
+Names}). Thus, if there is no buffer named @var{name}, then that is
+the name of the new buffer; if that name is in use, a suffix of the
+form @samp{<@var{n}>}, where @var{n} is an integer, is appended to
+@var{name}.
An error is signaled if @var{name} is not a string.
The major mode for the new buffer is set to Fundamental mode. The default
value of the variable @code{major-mode} is handled at a higher level.
@xref{Auto Major Mode}.
-
-See the related function @code{generate-new-buffer-name} in @ref{Buffer
-Names}.
@end defun
@node Killing Buffers
distinct according to @code{eq} although both are dead.
If you kill a buffer that is current or displayed in a window, Emacs
-automatically selects or displays some other buffer instead. This means
-that killing a buffer can in general change the current buffer.
-Therefore, when you kill a buffer, you should also take the precautions
+automatically selects or displays some other buffer instead. This
+means that killing a buffer can change the current buffer. Therefore,
+when you kill a buffer, you should also take the precautions
associated with changing the current buffer (unless you happen to know
that the buffer being killed isn't current). @xref{Current Buffer}.
If you kill a buffer that is the base buffer of one or more indirect
-buffers, the indirect buffers are automatically killed as well.
-
- The @code{buffer-name} of a killed buffer is @code{nil}. You can use
-this feature to test whether a buffer has been killed:
+@iftex
+buffers,
+@end iftex
+@ifnottex
+buffers (@pxref{Indirect Buffers}),
+@end ifnottex
+the indirect buffers are automatically killed as well.
-@example
-@group
-(defun buffer-killed-p (buffer)
- "Return t if BUFFER is killed."
- (not (buffer-name buffer)))
-@end group
-@end example
+@cindex live buffer
+ The @code{buffer-name} of a buffer is @code{nil} if, and only if,
+the buffer is killed. A buffer that has not been killed is called a
+@dfn{live} buffer. To test whether a buffer is live or killed, use
+the function @code{buffer-live-p} (see below).
@deffn Command kill-buffer &optional buffer-or-name
This function kills the buffer @var{buffer-or-name}, freeing all its
buffer.
Any processes that have this buffer as the @code{process-buffer} are
-sent the @code{SIGHUP} signal, which normally causes them to terminate.
-(The basic meaning of @code{SIGHUP} is that a dialup line has been
-disconnected.) @xref{Signals to Processes}.
+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,
@code{kill-buffer} asks the user to confirm before the buffer is killed.
@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
@end defvar
@defun buffer-live-p object
-This function returns @code{t} if @var{object} is a buffer which has
-not been killed, @code{nil} otherwise.
+This function returns @code{t} if @var{object} is a live buffer (a
+buffer which has not been killed), @code{nil} otherwise.
@end defun
@node Indirect Buffers
@defun gap-size
This function returns the current gap size of the current buffer.
@end defun
-
-@ignore
- arch-tag: 2e53cfab-5691-41f6-b5a8-9c6a3462399c
-@end ignore
HCoop / bpt / emacs.git / blobdiff