# HG changeset patch # User Glenn Morris # Date 1189052301 0 # Node ID 5655f2e3736d75ab6f08b57de840f9fa5c5cb1d2 # Parent 718f78440e5317910591906871a284353d1741b4 Move here from ../../lispref diff -r 718f78440e53 -r 5655f2e3736d doc/lispref/buffers.texi --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/lispref/buffers.texi Thu Sep 06 04:18:21 2007 +0000 @@ -0,0 +1,1165 @@ +@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 Free Software Foundation, Inc. +@c See the file elisp.texi for copying conditions. +@setfilename ../info/buffers +@node Buffers, Windows, Backups and Auto-Saving, Top +@chapter Buffers +@cindex buffer + + A @dfn{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, only one buffer is designated the @dfn{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. + +@menu +* Buffer Basics:: What is a buffer? +* Current Buffer:: Designating a buffer as current + so that 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 @dfn{modified} if it needs to be saved. +* 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. +* Creating Buffers:: Functions that create buffers. +* Killing Buffers:: Buffers exist until explicitly killed. +* Indirect Buffers:: An indirect buffer shares text with some other buffer. +* Buffer Gap:: The gap in the buffer. +@end menu + +@node Buffer Basics +@comment node-name, next, previous, up +@section Buffer Basics + +@ifnottex + A @dfn{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. Although several buffers +normally exist, only one buffer is designated the @dfn{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. +@end ifnottex + + 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 a string that +you can extend; insertions and deletions may occur in any part of the +buffer. @xref{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 +@dfn{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 @code{fill-column} or @code{comment-column} in this +way. For more information about buffer-local variables and functions +related to them, see @ref{Buffer-Local Variables}. + + For functions and variables related to visiting files in buffers, see +@ref{Visiting Files} and @ref{Saving Buffers}. For functions and +variables related to the display of buffers in windows, see +@ref{Buffers and Windows}. + +@defun bufferp object +This function returns @code{t} if @var{object} is a buffer, +@code{nil} otherwise. +@end defun + +@node Current Buffer +@section The Current Buffer +@cindex selecting a buffer +@cindex changing to another buffer +@cindex current buffer + + There are, in general, many buffers in an Emacs session. At any time, +one of them is designated as the @dfn{current buffer}. This is the +buffer in which most editing takes place, because most of the primitives +for examining or changing text in a buffer operate implicitly on the +current buffer (@pxref{Text}). Normally the buffer that is displayed on +the screen in the selected window is the current buffer, but this is not +always so: a Lisp program can temporarily designate any buffer as +current in order to operate on its contents, without changing what is +displayed on the screen. + + The way to designate a current buffer in a Lisp program is by calling +@code{set-buffer}. The specified buffer remains current until a new one +is designated. + + When an editing command returns to the editor command loop, the +command loop designates the buffer displayed in the selected window as +current, to prevent confusion: the buffer that the cursor is in when +Emacs reads a command is the buffer that the command will apply to. +(@xref{Command Loop}.) Therefore, @code{set-buffer} is not the way to +switch visibly to a different buffer so that the user can edit it. For +that, you must use the functions described in @ref{Displaying Buffers}. + + @strong{Warning:} Lisp functions that change to a different current buffer +should not depend on the command loop to set it back afterwards. +Editing commands written in Emacs Lisp can be called from other programs +as well as from the command loop; it is convenient for the caller if +the subroutine does not change which buffer is current (unless, of +course, that is the subroutine's purpose). Therefore, you should +normally use @code{set-buffer} within a @code{save-current-buffer} or +@code{save-excursion} (@pxref{Excursions}) form that will restore the +current buffer when your function is done. Here is an example, the +code for the command @code{append-to-buffer} (with the documentation +string abridged): + +@example +@group +(defun append-to-buffer (buffer start end) + "Append to specified buffer the text of the region. +@dots{}" + (interactive "BAppend to buffer: \nr") + (let ((oldbuf (current-buffer))) + (save-current-buffer + (set-buffer (get-buffer-create buffer)) + (insert-buffer-substring oldbuf start end)))) +@end group +@end example + +@noindent +This function binds a local variable to record the current buffer, and +then @code{save-current-buffer} arranges to make it current again. +Next, @code{set-buffer} makes the specified buffer current. Finally, +@code{insert-buffer-substring} copies the string from the original +current buffer to the specified (and now current) buffer. + + If the buffer appended to happens to be displayed in some window, +the next redisplay will show how its text has changed. Otherwise, you +will not see the change immediately on the screen. The buffer becomes +current temporarily during the execution of the command, but this does +not cause it to be displayed. + + If you make local bindings (with @code{let} or function arguments) for +a variable that may also have buffer-local bindings, make sure that the +same buffer is current at the beginning and at the end of the local +binding's scope. Otherwise you might bind it in one buffer and unbind +it in another! There are two ways to do this. In simple cases, you may +see that nothing ever changes the current buffer within the scope of the +binding. Otherwise, use @code{save-current-buffer} or +@code{save-excursion} to make sure that the buffer current at the +beginning is current again whenever the variable is unbound. + + Do not rely on using @code{set-buffer} to change the current buffer +back, because that won't do the job if a quit happens while the wrong +buffer is current. Here is what @emph{not} to do: + +@example +@group +(let (buffer-read-only + (obuf (current-buffer))) + (set-buffer @dots{}) + @dots{} + (set-buffer obuf)) +@end group +@end example + +@noindent +Using @code{save-current-buffer}, as shown here, handles quitting, +errors, and @code{throw}, as well as ordinary evaluation. + +@example +@group +(let (buffer-read-only) + (save-current-buffer + (set-buffer @dots{}) + @dots{})) +@end group +@end example + +@defun current-buffer +This function returns the current buffer. + +@example +@group +(current-buffer) + @result{} # +@end group +@end example +@end defun + +@defun set-buffer buffer-or-name +This function makes @var{buffer-or-name} the current buffer. This does +not display the buffer in any window, so the user cannot necessarily see +the buffer. But Lisp programs will now operate on it. + +This function returns the buffer identified by @var{buffer-or-name}. +An error is signaled if @var{buffer-or-name} does not identify an +existing buffer. +@end defun + +@defspec save-current-buffer body@dots{} +The @code{save-current-buffer} special form saves the identity of the +current buffer, evaluates the @var{body} forms, and finally restores +that buffer as current. The return value is the value of the last +form in @var{body}. The current buffer is restored even in case of an +abnormal exit via @code{throw} or error (@pxref{Nonlocal Exits}). + +If the buffer that used to be current has been killed by the time of +exit from @code{save-current-buffer}, then it is not made current again, +of course. Instead, whichever buffer was current just before exit +remains current. +@end defspec + +@defmac with-current-buffer buffer-or-name body@dots{} +The @code{with-current-buffer} macro saves the identity of the current +buffer, makes @var{buffer-or-name} current, evaluates the @var{body} +forms, and finally restores the buffer. The return value is the value +of the last form in @var{body}. The current buffer is restored even +in case of an abnormal exit via @code{throw} or error (@pxref{Nonlocal +Exits}). + +An error is signaled if @var{buffer-or-name} does not identify an +existing buffer. +@end defmac + +@defmac with-temp-buffer body@dots{} +@anchor{Definition of with-temp-buffer} +The @code{with-temp-buffer} macro evaluates the @var{body} forms +with a temporary buffer as the current buffer. It saves the identity of +the current buffer, creates a temporary buffer and makes it current, +evaluates the @var{body} forms, and finally restores the previous +current buffer while killing the temporary buffer. By default, undo +information (@pxref{Undo}) is not recorded in the buffer created by +this macro (but @var{body} can enable that, if needed). + +The return value is the value of the last form in @var{body}. You can +return the contents of the temporary buffer by using +@code{(buffer-string)} as the last form. + +The current buffer is restored even in case of an abnormal exit via +@code{throw} or error (@pxref{Nonlocal Exits}). + +See also @code{with-temp-file} in @ref{Definition of with-temp-file,, +Writing to Files}. +@end defmac + +@node Buffer Names +@section Buffer Names +@cindex buffer names + + Each buffer has a unique name, which is a string. Many of the +functions that work on buffers accept either a buffer or a buffer name +as an argument. Any argument called @var{buffer-or-name} is of this +sort, and an error is signaled if it is neither a string nor a buffer. +Any argument called @var{buffer} must be an actual buffer +object, not a name. + +@cindex hidden buffers +@cindex buffers without undo information + Buffers that are ephemeral and generally uninteresting to the user +have names starting with a space, so that the @code{list-buffers} and +@code{buffer-menu} commands don't mention them (but if such a buffer +visits a file, it @strong{is} mentioned). A name starting with +space also initially disables recording undo information; see +@ref{Undo}. + +@defun buffer-name &optional buffer +This function returns the name of @var{buffer} as a string. If +@var{buffer} is not supplied, it defaults to the current buffer. + +If @code{buffer-name} returns @code{nil}, it means that @var{buffer} +has been killed. @xref{Killing Buffers}. + +@example +@group +(buffer-name) + @result{} "buffers.texi" +@end group + +@group +(setq foo (get-buffer "temp")) + @result{} # +@end group +@group +(kill-buffer foo) + @result{} nil +@end group +@group +(buffer-name foo) + @result{} nil +@end group +@group +foo + @result{} # +@end group +@end example +@end defun + +@deffn Command rename-buffer newname &optional unique +This function renames the current buffer to @var{newname}. An error +is signaled if @var{newname} is not a string. + +@c Emacs 19 feature +Ordinarily, @code{rename-buffer} signals an error if @var{newname} is +already in use. However, if @var{unique} is non-@code{nil}, it modifies +@var{newname} to make a name that is not in use. Interactively, you can +make @var{unique} non-@code{nil} with a numeric prefix argument. +(This is how the command @code{rename-uniquely} is implemented.) + +This function returns the name actually given to the buffer. +@end deffn + +@defun get-buffer buffer-or-name +This function returns the buffer specified by @var{buffer-or-name}. +If @var{buffer-or-name} is a string and there is no buffer with that +name, the value is @code{nil}. If @var{buffer-or-name} is a buffer, it +is returned as given; that is not very useful, so the argument is usually +a name. For example: + +@example +@group +(setq b (get-buffer "lewis")) + @result{} # +@end group +@group +(get-buffer b) + @result{} # +@end group +@group +(get-buffer "Frazzle-nots") + @result{} nil +@end group +@end example + +See also the function @code{get-buffer-create} in @ref{Creating Buffers}. +@end defun + +@c Emacs 19 feature +@defun generate-new-buffer-name starting-name &optional ignore +This function returns a name that would be unique for a new buffer---but +does not create the buffer. It starts with @var{starting-name}, and +produces a name not currently in use for any buffer by appending a +number inside of @samp{<@dots{}>}. It starts at 2 and keeps +incrementing the number until it is not the name of an existing buffer. + +If the optional second argument @var{ignore} is non-@code{nil}, it +should be a string, a potential buffer name. It means to consider +that potential buffer acceptable, if it is tried, even it is the name +of an existing buffer (which would normally be rejected). Thus, if +buffers named @samp{foo}, @samp{foo<2>}, @samp{foo<3>} and +@samp{foo<4>} exist, + +@example +(generate-new-buffer-name "foo") + @result{} "foo<5>" +(generate-new-buffer-name "foo" "foo<3>") + @result{} "foo<3>" +(generate-new-buffer-name "foo" "foo<6>") + @result{} "foo<5>" +@end example + +See the related function @code{generate-new-buffer} in @ref{Creating +Buffers}. +@end defun + +@node Buffer File Name +@section Buffer File Name +@cindex visited file +@cindex buffer file name +@cindex file name of buffer + + The @dfn{buffer file name} is the name of the file that is visited in +that buffer. When a buffer is not visiting a file, its buffer file name +is @code{nil}. Most of the time, the buffer name is the same as the +nondirectory part of the buffer file name, but the buffer file name and +the buffer name are distinct and can be set independently. +@xref{Visiting Files}. + +@defun buffer-file-name &optional buffer +This function returns the absolute file name of the file that +@var{buffer} is visiting. If @var{buffer} is not visiting any file, +@code{buffer-file-name} returns @code{nil}. If @var{buffer} is not +supplied, it defaults to the current buffer. + +@example +@group +(buffer-file-name (other-buffer)) + @result{} "/usr/user/lewis/manual/files.texi" +@end group +@end example +@end defun + +@defvar buffer-file-name +This buffer-local variable contains the name of the file being visited +in the current buffer, or @code{nil} if it is not visiting a file. It +is a permanent local variable, unaffected by +@code{kill-all-local-variables}. + +@example +@group +buffer-file-name + @result{} "/usr/user/lewis/manual/buffers.texi" +@end group +@end example + +It is risky to change this variable's value without doing various other +things. Normally it is better to use @code{set-visited-file-name} (see +below); some of the things done there, such as changing the buffer name, +are not strictly necessary, but others are essential to avoid confusing +Emacs. +@end defvar + +@defvar buffer-file-truename +This buffer-local variable holds the abbreviated truename of the file +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}. +@end defvar + +@defvar buffer-file-number +This buffer-local variable holds the file number and directory device +number of the file visited in the current buffer, or @code{nil} if no +file or a nonexistent file is visited. It is a permanent local, +unaffected by @code{kill-all-local-variables}. + +The value is normally a list of the form @code{(@var{filenum} +@var{devnum})}. This pair of numbers uniquely identifies the file among +all files accessible on the system. See the function +@code{file-attributes}, in @ref{File Attributes}, for more information +about them. + +If @code{buffer-file-name} is the name of a symbolic link, then both +numbers refer to the recursive target. +@end defvar + +@defun get-file-buffer filename +This function returns the buffer visiting file @var{filename}. If +there is no such buffer, it returns @code{nil}. The argument +@var{filename}, which must be a string, is expanded (@pxref{File Name +Expansion}), then compared against the visited file names of all live +buffers. Note that the buffer's @code{buffer-file-name} must match +the expansion of @var{filename} exactly. This function will not +recognize other names for the same file. + +@example +@group +(get-file-buffer "buffers.texi") + @result{} # +@end group +@end example + +In unusual circumstances, there can be more than one buffer visiting +the same file name. In such cases, this function returns the first +such buffer in the buffer list. +@end defun + +@defun find-buffer-visiting filename &optional predicate +This is like @code{get-file-buffer}, except that it can return any +buffer visiting the file @emph{possibly under a different name}. That +is, the buffer's @code{buffer-file-name} does not need to match the +expansion of @var{filename} exactly, it only needs to refer to the +same file. If @var{predicate} is non-@code{nil}, it should be a +function of one argument, a buffer visiting @var{filename}. The +buffer is only considered a suitable return value if @var{predicate} +returns non-@code{nil}. If it can not find a suitable buffer to +return, @code{find-buffer-visiting} returns @code{nil}. +@end defun + +@deffn Command set-visited-file-name filename &optional no-query along-with-file +If @var{filename} is a non-empty string, this function changes the +name of the file visited in the current buffer to @var{filename}. (If the +buffer had no visited file, this gives it one.) The @emph{next time} +the buffer is saved it will go in the newly-specified file. + +This command marks the buffer as modified, since it does not (as far +as Emacs knows) match the contents of @var{filename}, even if it +matched the former visited file. It also renames the buffer to +correspond to the new file name, unless the new name is already in +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 +the buffer as having no visited file, without changing the buffer's +modified flag. + +Normally, this function asks the user for confirmation if there +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}. + +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 +case, the command does not change the buffer's modified flag, nor the +buffer's recorded last file modification time as reported by +@code{visited-file-modtime} (@pxref{Modification Time}). If +@var{along-with-file} is @code{nil}, this function clears the recorded +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. +@end deffn + +@defvar list-buffers-directory +This buffer-local variable specifies a string to display in a buffer +listing where the visited file name would go, for buffers that don't +have a visited file name. Dired buffers use this variable. +@end defvar + +@node Buffer Modification +@section Buffer Modification +@cindex buffer modification +@cindex modification flag (of buffer) + + Emacs keeps a flag called the @dfn{modified flag} for each buffer, to +record whether you have changed the text of the buffer. This flag is +set to @code{t} whenever you alter the contents of the buffer, and +cleared to @code{nil} when you save it. Thus, the flag shows whether +there are unsaved changes. The flag value is normally shown in the mode +line (@pxref{Mode Line Variables}), and controls saving (@pxref{Saving +Buffers}) and auto-saving (@pxref{Auto-Saving}). + + Some Lisp programs set the flag explicitly. For example, the function +@code{set-visited-file-name} sets the flag to @code{t}, because the text +does not match the newly-visited file, even if it is unchanged from the +file formerly visited. + + The functions that modify the contents of buffers are described in +@ref{Text}. + +@defun buffer-modified-p &optional buffer +This function returns @code{t} if the buffer @var{buffer} has been modified +since it was last read in from a file or saved, or @code{nil} +otherwise. If @var{buffer} is not supplied, the current buffer +is tested. +@end defun + +@defun set-buffer-modified-p flag +This function marks the current buffer as modified if @var{flag} is +non-@code{nil}, or as unmodified if the flag is @code{nil}. + +Another effect of calling this function is to cause unconditional +redisplay of the mode line for the current buffer. In fact, the +function @code{force-mode-line-update} works by doing this: + +@example +@group +(set-buffer-modified-p (buffer-modified-p)) +@end group +@end example +@end defun + +@defun restore-buffer-modified-p flag +Like @code{set-buffer-modified-p}, but does not force redisplay +of mode lines. +@end defun + +@deffn Command not-modified &optional arg +This command marks the current buffer as unmodified, and not needing +to be saved. If @var{arg} is non-@code{nil}, it marks the buffer as +modified, so that it will be saved at the next suitable occasion. +Interactively, @var{arg} is the prefix argument. + +Don't use this function in programs, since it prints a message in the +echo area; use @code{set-buffer-modified-p} (above) instead. +@end deffn + +@defun buffer-modified-tick &optional buffer +This function returns @var{buffer}'s modification-count. This is a +counter that increments every time the buffer is modified. If +@var{buffer} is @code{nil} (or omitted), the current buffer is used. +The counter can wrap around occasionally. +@end defun + +@defun buffer-chars-modified-tick &optional buffer +This function returns @var{buffer}'s character-change modification-count. +Changes to text properties leave this counter unchanged; however, each +time text is inserted or removed from the buffer, the counter is reset +to the value that would be returned @code{buffer-modified-tick}. +By comparing the values returned by two @code{buffer-chars-modified-tick} +calls, you can tell whether a character change occurred in that buffer +in between the calls. If @var{buffer} is @code{nil} (or omitted), the +current buffer is used. +@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 + + Suppose that you visit a file and make changes in its buffer, and +meanwhile the file itself is changed on disk. At this point, saving the +buffer would overwrite the changes in the file. Occasionally this may +be what you want, but usually it would lose valuable information. Emacs +therefore checks the file's modification time using the functions +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. + +The function returns @code{t} if the last actual modification time and +Emacs's recorded modification time are the same, @code{nil} otherwise. +It also returns @code{t} if the buffer has no recorded last +modification time, that is if @code{visited-file-modtime} would return +zero. + +It always returns @code{t} for buffers that are not visiting a file, +even if @code{visited-file-modtime} returns a non-zero value. For +instance, it always returns @code{t} for dired buffers. It returns +@code{t} for buffers that are visiting a file that does not exist and +never existed, but @code{nil} for file-visiting buffers whose file has +been deleted. +@end defun + +@defun clear-visited-file-modtime +This function clears out the record of the last modification time of +the file being visited by the current buffer. As a result, the next +attempt to save this buffer will not complain of a discrepancy in +file modification times. + +This function is called in @code{set-visited-file-name} and other +exceptional places where the usual test to avoid overwriting a changed +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}.) + +If the buffer has no recorded last modification time, this function +returns zero. This case occurs, for instance, if the buffer is not +visiting a file or if the time has been explicitly cleared by +@code{clear-visited-file-modtime}. Note, however, that +@code{visited-file-modtime} returns a list for some non-file buffers +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 +@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} +is not @code{nil}, and otherwise to the last modification time of the +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. + +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 +reason. +@end defun + +@defun ask-user-about-supersession-threat filename +This function is used to ask a user how to proceed after an attempt to +modify an buffer visiting file @var{filename} when the file is newer +than the buffer text. Emacs detects this because the modification +time of the file on disk is newer than the last save-time of the +buffer. This means some other program has probably altered the file. + +@kindex file-supersession +Depending on the user's answer, the function may return normally, in +which case the modification of the buffer proceeds, or it may signal a +@code{file-supersession} error with data @code{(@var{filename})}, in which +case the proposed buffer modification is not allowed. + +This function is called automatically by Emacs on the proper +occasions. It exists so you can customize Emacs by redefining it. +See the file @file{userlock.el} for the standard definition. + +See also the file locking mechanism in @ref{File Locks}. +@end defun + +@node Read Only Buffers +@section Read-Only Buffers +@cindex read-only buffer +@cindex buffer, read-only + + If a buffer is @dfn{read-only}, then you cannot change its contents, +although you may change your view of the contents by scrolling and +narrowing. + + Read-only buffers are used in two kinds of situations: + +@itemize @bullet +@item +A buffer visiting a write-protected file is normally read-only. + +Here, the purpose is to inform the user that editing the buffer with the +aim of saving it in the file may be futile or undesirable. The user who +wants to change the buffer text despite this can do so after clearing +the read-only flag with @kbd{C-x C-q}. + +@item +Modes such as Dired and Rmail make buffers read-only when altering the +contents with the usual editing commands would probably be a mistake. + +The special commands of these modes bind @code{buffer-read-only} to +@code{nil} (with @code{let}) or bind @code{inhibit-read-only} to +@code{t} around the places where they themselves change the text. +@end itemize + +@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}. +@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. + +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 +@code{read-only} character properties have no effect if they are members +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}. +@end deffn + +@defun barf-if-buffer-read-only +This function signals a @code{buffer-read-only} error if the current +buffer is read-only. @xref{Using Interactive}, for another way to +signal an error if the current buffer is read-only. +@end defun + +@node The Buffer List +@section The Buffer List +@cindex buffer list + + The @dfn{buffer list} is a list of all live buffers. The order of +the buffers in the list is based primarily on how recently each buffer +has been displayed in a window. Several functions, notably +@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. Buffers move to the front of the list when they +are selected for display in a window (@pxref{Displaying Buffers}), and +to the end when they are 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 Emacs buffer list, each frame has its +own version of the buffer list, in which the buffers that have been +selected in that frame come first, starting with the buffers most +recently selected @emph{in that frame}. (This order is recorded in +@var{frame}'s @code{buffer-list} frame parameter; see @ref{Buffer +Parameters}.) The buffers that were never selected in @var{frame} come +afterward, ordered according to the fundamental Emacs buffer list. + +@defun buffer-list &optional frame +This function returns the buffer list, including all buffers, even those +whose names begin with a space. The elements are actual buffers, not +their names. + +If @var{frame} is a frame, this returns @var{frame}'s buffer list. If +@var{frame} is @code{nil}, the fundamental Emacs buffer list is used: +all the buffers appear in order of most recent selection, regardless of +which frames they were selected in. + +@example +@group +(buffer-list) + @result{} (# + # # + # #) +@end group + +@group +;; @r{Note that the name of the minibuffer} +;; @r{begins with a space!} +(mapcar (function buffer-name) (buffer-list)) + @result{} ("buffers.texi" " *Minibuf-1*" + "buffer.c" "*Help*" "TAGS") +@end group +@end example +@end defun + + The list that @code{buffer-list} returns is constructed specifically +by @code{buffer-list}; it is not an internal Emacs data structure, and +modifying it has no effect on the order of buffers. If you want to +change the order of buffers in the frame-independent buffer list, here +is an easy way: + +@example +(defun reorder-buffer-list (new-list) + (while new-list + (bury-buffer (car new-list)) + (setq new-list (cdr new-list)))) +@end example + + With this method, you can specify any order for the list, but there is +no danger of losing a buffer or adding something that is not a valid +live buffer. + + To change the order or value of a frame's buffer list, set the frame's +@code{buffer-list} frame parameter with @code{modify-frame-parameters} +(@pxref{Parameter Access}). + +@defun other-buffer &optional buffer visible-ok frame +This function returns the first buffer in the buffer list other than +@var{buffer}. Usually this is the buffer selected most recently (in +frame @var{frame} or else the currently selected frame, @pxref{Input +Focus}), aside from @var{buffer}. Buffers whose names start with a +space are not considered at all. + +If @var{buffer} is not supplied (or if it is not a buffer), then +@code{other-buffer} returns the first buffer in the selected frame's +buffer list that is not now visible in any window in a visible frame. + +If @var{frame} has a non-@code{nil} @code{buffer-predicate} parameter, +then @code{other-buffer} uses that predicate to decide which buffers to +consider. It calls the predicate once for each buffer, and if the value +is @code{nil}, that buffer is ignored. @xref{Buffer Parameters}. + +@c Emacs 19 feature +If @var{visible-ok} is @code{nil}, @code{other-buffer} avoids returning +a buffer visible in any window on any visible frame, except as a last +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 +(and created, if necessary). +@end defun + +@deffn Command bury-buffer &optional buffer-or-name +This function puts @var{buffer-or-name} at the end of the buffer list, +without changing the order of any of the other buffers on the list. +This buffer therefore becomes the least desirable candidate for +@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 frame-independent Emacs 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 nil)}. + +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. But if the buffer 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}. +@end deffn + +@node Creating Buffers +@section Creating Buffers +@cindex creating buffers +@cindex buffers, creating + + This section describes the two primitives for creating buffers. +@code{get-buffer-create} creates a buffer if it finds no existing buffer +with the specified name; @code{generate-new-buffer} always creates a new +buffer and gives it a unique name. + + Other functions you can use to create buffers include +@code{with-output-to-temp-buffer} (@pxref{Temporary Displays}) and +@code{create-file-buffer} (@pxref{Visiting Files}). Starting a +subprocess can also create a buffer (@pxref{Processes}). + +@defun get-buffer-create name +This function returns a buffer named @var{name}. It returns a live +buffer with that name, if one exists; otherwise, it creates a new +buffer. The buffer does not become the current buffer---this function +does not change which buffer is current. + +If @var{name} is a buffer instead of a string, it is returned, even if +it is dead. An error is signaled if @var{name} is neither a string +nor a buffer. + +@example +@group +(get-buffer-create "foo") + @result{} # +@end group +@end example + +The major mode for a newly created buffer is set to Fundamental mode. +(The variable @code{default-major-mode} is handled at a higher level; +see @ref{Auto Major Mode}.) If the name begins with a space, the +buffer initially disables undo information recording (@pxref{Undo}). +@end defun + +@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. + +An error is signaled if @var{name} is not a string. + +@example +@group +(generate-new-buffer "bar") + @result{} # +@end group +@group +(generate-new-buffer "bar") + @result{} #> +@end group +@group +(generate-new-buffer "bar") + @result{} #> +@end group +@end example + +The major mode for the new buffer is set to Fundamental mode. The +variable @code{default-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 +@section Killing Buffers +@cindex killing buffers +@cindex buffers, killing + + @dfn{Killing a buffer} makes its name unknown to Emacs and makes the +memory space it occupied available for other use. + + The buffer object for the buffer that has been killed remains in +existence as long as anything refers to it, but it is specially marked +so that you cannot make it current or display it. Killed buffers retain +their identity, however; if you kill two distinct buffers, they remain +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 +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: + +@example +@group +(defun buffer-killed-p (buffer) + "Return t if BUFFER is killed." + (not (buffer-name buffer))) +@end group +@end example + +@deffn Command kill-buffer buffer-or-name +This function kills the buffer @var{buffer-or-name}, freeing all its +memory for other uses or to be returned to the operating system. If +@var{buffer-or-name} is @code{nil}, it kills the current 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}. + +If the buffer is visiting a file and contains unsaved changes, +@code{kill-buffer} asks the user to confirm before the buffer is killed. +It does this even if not called interactively. To prevent the request +for confirmation, clear the modified flag before calling +@code{kill-buffer}. @xref{Buffer Modification}. + +Killing a buffer that is already dead has no effect. + +This function returns @code{t} if it actually killed the buffer. It +returns @code{nil} if the user refuses to confirm or if +@var{buffer-or-name} was already dead. + +@smallexample +(kill-buffer "foo.unchanged") + @result{} t +(kill-buffer "foo.changed") + +---------- Buffer: Minibuffer ---------- +Buffer foo.changed modified; kill anyway? (yes or no) @kbd{yes} +---------- Buffer: Minibuffer ---------- + + @result{} t +@end smallexample +@end deffn + +@defvar kill-buffer-query-functions +After 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 +ask for confirmation from the user. If any of them returns @code{nil}, +@code{kill-buffer} spares the buffer's life. +@end defvar + +@defvar kill-buffer-hook +This is a normal hook run by @code{kill-buffer} after asking all the +questions it is going to ask, just before actually killing the buffer. +The buffer to be killed is current when the hook functions run. +@xref{Hooks}. This variable is a permanent local, so its local binding +is not cleared by changing major modes. +@end defvar + +@defvar buffer-offer-save +This variable, if non-@code{nil} in a particular buffer, tells +@code{save-buffers-kill-emacs} and @code{save-some-buffers} (if the +second optional argument to that function is @code{t}) to offer to +save that buffer, just as they offer to save file-visiting buffers. +@xref{Definition of save-some-buffers}. The variable +@code{buffer-offer-save} automatically becomes buffer-local when set +for any reason. @xref{Buffer-Local Variables}. +@end defvar + +@defvar buffer-save-without-query +This variable, if non-@code{nil} in a particular buffer, tells +@code{save-buffers-kill-emacs} and @code{save-some-buffers} to save +this buffer (if it's modified) without asking the user. The variable +automatically becomes buffer-local when set for any reason. +@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. +@end defun + +@node Indirect Buffers +@section Indirect Buffers +@cindex indirect buffers +@cindex base buffer + + An @dfn{indirect buffer} shares the text of some other buffer, which +is called the @dfn{base buffer} of the indirect buffer. In some ways it +is the analogue, for buffers, of a symbolic link among files. The base +buffer may not itself be an indirect buffer. + + The text of the indirect buffer is always identical to the text of its +base buffer; changes made by editing either one are visible immediately +in the other. This includes the text properties as well as the characters +themselves. + + In all other respects, the indirect buffer and its base buffer are +completely separate. They have different names, independent values of +point, independent narrowing, independent markers and overlays (though +inserting or deleting text in either buffer relocates the markers and +overlays for both), independent major modes, and independent +buffer-local variable bindings. + + An indirect buffer cannot visit a file, but its base buffer can. If +you try to save the indirect buffer, that actually saves the base +buffer. + + Killing an indirect buffer has no effect on its base buffer. Killing +the base buffer effectively kills the indirect buffer in that it cannot +ever again be the current buffer. + +@deffn Command make-indirect-buffer base-buffer name &optional clone +This creates and returns an indirect buffer named @var{name} whose +base buffer is @var{base-buffer}. The argument @var{base-buffer} may +be a live buffer or the name (a string) of an existing buffer. If +@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 +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. + +If @var{base-buffer} is an indirect buffer, its base buffer is used as +the base for the new buffer. If, in addition, @var{clone} is +non-@code{nil}, the initial state is copied from the actual base +buffer, not from @var{base-buffer}. +@end deffn + +@defun clone-indirect-buffer newname display-flag &optional norecord +This function creates and returns a new indirect buffer that shares +the current buffer's base buffer and copies the rest of the current +buffer's attributes. (If the current buffer is not indirect, it is +used as the base buffer.) + +If @var{display-flag} is non-@code{nil}, that means to display the new +buffer by calling @code{pop-to-buffer}. If @var{norecord} is +non-@code{nil}, that means not to put the new buffer to the front of +the buffer list. +@end defun + +@defun buffer-base-buffer &optional buffer +This function returns the base buffer of @var{buffer}, which defaults +to the current buffer. If @var{buffer} is not indirect, the value is +@code{nil}. Otherwise, the value is another buffer, which is never an +indirect buffer. +@end defun + +@node Buffer Gap +@section The Buffer Gap + + Emacs buffers are implemented using an invisible @dfn{gap} to make +insertion and deletion faster. Insertion works by filling in part of +the gap, and deletion adds to the gap. Of course, this means that the +gap must first be moved to the locus of the insertion or deletion. +Emacs moves the gap only when you try to insert or delete. This is why +your first editing command in one part of a large buffer, after +previously editing in another far-away part, sometimes involves a +noticeable delay. + + This mechanism works invisibly, and Lisp code should never be affected +by the gap's current location, but these functions are available for +getting information about the gap status. + +@defun gap-position +This function returns the current gap position in the current buffer. +@end defun + +@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