@c -*-texinfo-*-@c This is part of the GNU Emacs Lisp Reference Manual.@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999@c 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. Buffersare used to hold the contents of files that are being visited; there mayalso be buffers that are not visiting files. While several buffers mayexist at one time, only one buffer is designated the @dfn{currentbuffer} at any time. Most editing commands act on the contents of thecurrent buffer. Each buffer, including the current buffer, may or maynot 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. Buffersare used to hold the contents of files that are being visited; there mayalso be buffers that are not visiting files. Although several buffersnormally exist, only one buffer is designated the @dfn{currentbuffer} at any time. Most editing commands act on the contents of thecurrent buffer. Each buffer, including the current buffer, may or maynot be displayed in any windows.@end ifnottex Buffers in Emacs editing are objects that have distinct names and holdtext that can be edited. Buffers appear to Lisp programs as a specialdata type. You can think of the contents of a buffer as a string thatyou can extend; insertions and deletions may occur in any part of thebuffer. @xref{Text}. A Lisp buffer object contains numerous pieces of information. Some ofthis information is directly accessible to the programmer throughvariables, while other information is accessible only throughspecial-purpose functions. For example, the visited file name isdirectly accessible through a variable, while the value of point isaccessible 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 areeffective only in a particular buffer. This feature allows each bufferto override the values of certain variables. Most major modes overridevariables such as @code{fill-column} or @code{comment-column} in thisway. For more information about buffer-local variables and functionsrelated 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 andvariables related to the display of buffers in windows, see@ref{Buffers and Windows}.@defun bufferp objectThis 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 thebuffer in which most editing takes place, because most of the primitivesfor examining or changing text in a buffer operate implicitly on thecurrent buffer (@pxref{Text}). Normally the buffer that is displayed onthe screen in the selected window is the current buffer, but this is notalways so: a Lisp program can temporarily designate any buffer ascurrent in order to operate on its contents, without changing what isdisplayed 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 oneis designated. When an editing command returns to the editor command loop, thecommand loop designates the buffer displayed in the selected window ascurrent, to prevent confusion: the buffer that the cursor is in whenEmacs reads a command is the buffer that the command will apply to.(@xref{Command Loop}.) Therefore, @code{set-buffer} is not the way toswitch visibly to a different buffer so that the user can edit it. Forthat, you must use the functions described in @ref{Displaying Buffers}. @strong{Warning:} Lisp functions that change to a different current buffershould not depend on the command loop to set it back afterwards.Editing commands written in Emacs Lisp can be called from other programsas well as from the command loop; it is convenient for the caller ifthe subroutine does not change which buffer is current (unless, ofcourse, that is the subroutine's purpose). Therefore, you shouldnormally use @code{set-buffer} within a @code{save-current-buffer} or@code{save-excursion} (@pxref{Excursions}) form that will restore thecurrent buffer when your function is done. Here is an example, thecode for the command @code{append-to-buffer} (with the documentationstring 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@noindentThis function binds a local variable to record the current buffer, andthen @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 originalcurrent 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, youwill not see the change immediately on the screen. The buffer becomescurrent temporarily during the execution of the command, but this doesnot cause it to be displayed. If you make local bindings (with @code{let} or function arguments) fora variable that may also have buffer-local bindings, make sure that thesame buffer is current at the beginning and at the end of the localbinding's scope. Otherwise you might bind it in one buffer and unbindit in another! There are two ways to do this. In simple cases, you maysee that nothing ever changes the current buffer within the scope of thebinding. Otherwise, use @code{save-current-buffer} or@code{save-excursion} to make sure that the buffer current at thebeginning is current again whenever the variable is unbound. Do not rely on using @code{set-buffer} to change the current bufferback, because that won't do the job if a quit happens while the wrongbuffer 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@noindentUsing @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-bufferThis function returns the current buffer.@example@group(current-buffer) @result{} #<buffer buffers.texi>@end group@end example@end defun@defun set-buffer buffer-or-nameThis function makes @var{buffer-or-name} the current buffer. This doesnot display the buffer in any window, so the user cannot necessarily seethe 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 anexisting buffer.@end defun@defspec save-current-buffer body...The @code{save-current-buffer} special form saves the identity of thecurrent buffer, evaluates the @var{body} forms, and finally restoresthat buffer as current. The return value is the value of the lastform in @var{body}. The current buffer is restored even in case of anabnormal exit via @code{throw} or error (@pxref{Nonlocal Exits}).If the buffer that used to be current has been killed by the time ofexit from @code{save-current-buffer}, then it is not made current again,of course. Instead, whichever buffer was current just before exitremains current.@end defspec@defmac with-current-buffer buffer-or-name body...The @code{with-current-buffer} macro saves the identity of the currentbuffer, makes @var{buffer-or-name} current, evaluates the @var{body}forms, and finally restores the buffer. The return value is the valueof the last form in @var{body}. The current buffer is restored evenin case of an abnormal exit via @code{throw} or error (@pxref{NonlocalExits}).An error is signaled if @var{buffer-or-name} does not identify anexisting buffer.@end defmac@anchor{Definition of with-temp-buffer}@defmac with-temp-buffer body...The @code{with-temp-buffer} macro evaluates the @var{body} formswith a temporary buffer as the current buffer. It saves the identity ofthe current buffer, creates a temporary buffer and makes it current,evaluates the @var{body} forms, and finally restores the previouscurrent buffer while killing the temporary buffer.The return value is the value of the last form in @var{body}. You canreturn 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 thefunctions that work on buffers accept either a buffer or a buffer nameas an argument. Any argument called @var{buffer-or-name} is of thissort, and an error is signaled if it is neither a string nor a buffer.Any argument called @var{buffer} must be an actual bufferobject, not a name. Buffers that are ephemeral and generally uninteresting to the userhave names starting with a space, so that the @code{list-buffers} and@code{buffer-menu} commands don't mention them (but if such a buffervisits a file, it @strong{is} mentioned). A name starting withspace also initially disables recording undo information; see@ref{Undo}.@defun buffer-name &optional bufferThis 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{} #<buffer temp>@end group@group(kill-buffer foo) @result{} nil@end group@group(buffer-name foo) @result{} nil@end group@groupfoo @result{} #<killed buffer>@end group@end example@end defun@deffn Command rename-buffer newname &optional uniqueThis function renames the current buffer to @var{newname}. An erroris signaled if @var{newname} is not a string.@c Emacs 19 featureOrdinarily, @code{rename-buffer} signals an error if @var{newname} isalready 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 canmake @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-nameThis function returns the buffer specified by @var{buffer-or-name}.If @var{buffer-or-name} is a string and there is no buffer with thatname, the value is @code{nil}. If @var{buffer-or-name} is a buffer, itis returned as given; that is not very useful, so the argument is usuallya name. For example:@example@group(setq b (get-buffer "lewis")) @result{} #<buffer lewis>@end group@group(get-buffer b) @result{} #<buffer lewis>@end group@group(get-buffer "Frazzle-nots") @result{} nil@end group@end exampleSee 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 ignoreThis function returns a name that would be unique for a new buffer---butdoes not create the buffer. It starts with @var{starting-name}, andproduces a name not currently in use for any buffer by appending anumber inside of @samp{<@dots{}>}. It starts at 2 and keepsincrementing the number until it is not the name of an existing buffer.If the optional second argument @var{ignore} is non-@code{nil}, itshould be a string; it makes a difference if it is a name in thesequence of names to be tried. That name will be considered acceptable,if it is tried, even if a buffer with that name exists. Thus, ifbuffers 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 exampleSee the related function @code{generate-new-buffer} in @ref{CreatingBuffers}.@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 inthat buffer. When a buffer is not visiting a file, its buffer file nameis @code{nil}. Most of the time, the buffer name is the same as thenondirectory part of the buffer file name, but the buffer file name andthe buffer name are distinct and can be set independently.@xref{Visiting Files}.@defun buffer-file-name &optional bufferThis 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 notsupplied, 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-nameThis buffer-local variable contains the name of the file being visitedin the current buffer, or @code{nil} if it is not visiting a file. Itis a permanent local variable, unaffected by@code{kill-all-local-variables}.@example@groupbuffer-file-name @result{} "/usr/user/lewis/manual/buffers.texi"@end group@end exampleIt is risky to change this variable's value without doing various otherthings. Normally it is better to use @code{set-visited-file-name} (seebelow); some of the things done there, such as changing the buffer name,are not strictly necessary, but others are essential to avoid confusingEmacs.@end defvar@defvar buffer-file-truenameThis buffer-local variable holds the abbreviated truename of the filevisited 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-numberThis buffer-local variable holds the file number and directory devicenumber of the file visited in the current buffer, or @code{nil} if nofile 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 amongall files accessible on the system. See the function@code{file-attributes}, in @ref{File Attributes}, for more informationabout them.If @code{buffer-file-name} is the name of a symbolic link, then bothnumbers refer to the recursive target.@end defvar@defun get-file-buffer filenameThis function returns the buffer visiting file @var{filename}. Ifthere is no such buffer, it returns @code{nil}. The argument@var{filename}, which must be a string, is expanded (@pxref{File NameExpansion}), then compared against the visited file names of all livebuffers. Note that the buffer's @code{buffer-file-name} must matchthe expansion of @var{filename} exactly. This function will notrecognize other names for the same file.@example@group(get-file-buffer "buffers.texi") @result{} #<buffer buffers.texi>@end group@end exampleIn unusual circumstances, there can be more than one buffer visitingthe same file name. In such cases, this function returns the firstsuch buffer in the buffer list.@end defun@defun find-buffer-visiting filename &optional predicateThis is like @code{get-file-buffer}, except that it can return anybuffer visiting the file @emph{possibly under a different name}. Thatis, the buffer's @code{buffer-file-name} does not need to match theexpansion of @var{filename} exactly, it only needs to refer to thesame file. If @var{predicate} is non-@code{nil}, it should be afunction of one argument, a buffer visiting @var{filename}. Thebuffer is only considered a suitable return value if @var{predicate}returns non-@code{nil}. If it can not find a suitable buffer toreturn, @code{find-buffer-visiting} returns @code{nil}.@end defun@deffn Command set-visited-file-name filename &optional no-query along-with-fileIf @var{filename} is a non-empty string, this function changes thename of the file visited in the current buffer to @var{filename}. (If thebuffer 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 faras Emacs knows) match the contents of @var{filename}, even if itmatched the former visited file. It also renames the buffer tocorrespond to the new file name, unless the new name is already inuse.If @var{filename} is @code{nil} or the empty string, that stands for``no visited file''. In this case, @code{set-visited-file-name} marksthe buffer as having no visited file, without changing the buffer'smodified flag.Normally, this function asks the user for confirmation if therealready is a buffer visiting @var{filename}. If @var{no-query} isnon-@code{nil}, that prevents asking this question. If there alreadyis a buffer visiting @var{filename}, and the user confirms or@var{query} is non-@code{nil}, this function makes the new buffer nameunique by appending a number inside of @samp{<@dots{}>} to @var{filename}.If @var{along-with-file} is non-@code{nil}, that means to assume thatthe former visited file has been renamed to @var{filename}. In thiscase, the command does not change the buffer's modified flag, nor thebuffer'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 recordedlast file modification time, after which @code{visited-file-modtime}returns zero.@c Wordy to avoid overfull hbox. --rjc 16mar92When the function @code{set-visited-file-name} is called interactively, itprompts for @var{filename} in the minibuffer.@end deffn@defvar list-buffers-directoryThis buffer-local variable specifies a string to display in a bufferlisting where the visited file name would go, for buffers that don'thave 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, torecord whether you have changed the text of the buffer. This flag isset to @code{t} whenever you alter the contents of the buffer, andcleared to @code{nil} when you save it. Thus, the flag shows whetherthere are unsaved changes. The flag value is normally shown in the modeline (@pxref{Mode Line Variables}), and controls saving (@pxref{SavingBuffers}) 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 textdoes not match the newly-visited file, even if it is unchanged from thefile formerly visited. The functions that modify the contents of buffers are described in@ref{Text}.@defun buffer-modified-p &optional bufferThis function returns @code{t} if the buffer @var{buffer} has been modifiedsince it was last read in from a file or saved, or @code{nil}otherwise. If @var{buffer} is not supplied, the current bufferis tested.@end defun@defun set-buffer-modified-p flagThis function marks the current buffer as modified if @var{flag} isnon-@code{nil}, or as unmodified if the flag is @code{nil}.Another effect of calling this function is to cause unconditionalredisplay of the mode line for the current buffer. In fact, thefunction @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 flagLike @code{set-buffer-modified-p}, but does not force redisplayof mode lines.@end defun@deffn Command not-modified &optional argThis command marks the current buffer as unmodified, and not needingto be saved. If @var{arg} is non-@code{nil}, it marks the buffer asmodified, 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 theecho area; use @code{set-buffer-modified-p} (above) instead.@end deffn@c Emacs 19 feature@defun buffer-modified-tick &optional bufferThis function returns @var{buffer}'s modification-count. This is acounter 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@node Modification Time@comment node-name, next, previous, up@section Comparison of Modification Time@cindex comparison of modification time@cindex modification time, comparison of Suppose that you visit a file and make changes in its buffer, andmeanwhile the file itself is changed on disk. At this point, saving thebuffer would overwrite the changes in the file. Occasionally this maybe what you want, but usually it would lose valuable information. Emacstherefore checks the file's modification time using the functionsdescribed below before saving the file.@defun verify-visited-file-modtime bufferThis function compares what @var{buffer} has recorded for themodification time of its visited file against the actual modificationtime of the file as recorded by the operating system. The two should bethe same unless some other process has written the file since Emacsvisited or saved it.The function returns @code{t} if the last actual modification time andEmacs's recorded modification time are the same, @code{nil} otherwise.It also returns @code{t} if the buffer has no recorded lastmodification time, that is if @code{visited-file-modtime} would returnzero.It always returns @code{t} for buffers that are not visiting a file,even if @code{visited-file-modtime} returns a non-zero value. Forinstance, it always returns @code{t} for dired buffers. It returns@code{t} for buffers that are visiting a file that does not exist andnever existed, but @code{nil} for file-visiting buffers whose file hasbeen deleted.@end defun@defun clear-visited-file-modtimeThis function clears out the record of the last modification time ofthe file being visited by the current buffer. As a result, the nextattempt to save this buffer will not complain of a discrepancy infile modification times.This function is called in @code{set-visited-file-name} and otherexceptional places where the usual test to avoid overwriting a changedfile should not be done.@end defun@c Emacs 19 feature@defun visited-file-modtimeThis function returns the current buffer's recorded last filemodification 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}.)The function returns zero if the buffer has no recorded lastmodification time, which can happen, for instance, if the record hasbeen explicitly cleared by @code{clear-visited-file-modtime} or if thebuffer is not visiting a file. Note, however, that@code{visited-file-modtime} can return a non-zero value for somebuffers that are not visiting files, but are nevertheless closelyassociated with a file. This happens, for instance, with diredbuffers listing a directory. For such buffers,@code{visited-file-modtime} returns the last modification time of thatdirectory, 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 timeThis function updates the buffer's record of the last modification timeof 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 thevisited 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})}, ineither case containing two integers, each of which holds 16 bits of thetime.This function is useful if the buffer was not read from the filenormally, or if the file itself has been changed for some known benignreason.@end defun@defun ask-user-about-supersession-threat filename@cindex obsolete bufferThis function is used to ask a user how to proceed after an attempt tomodify an obsolete buffer visiting file @var{filename}. An@dfn{obsolete buffer} is an unmodified buffer for which the associatedfile on disk is newer than the last save-time of the buffer. This meanssome other program has probably altered the file.@kindex file-supersessionDepending on the user's answer, the function may return normally, inwhich case the modification of the buffer proceeds, or it may signal a@code{file-supersession} error with data @code{(@var{filename})}, in whichcase the proposed buffer modification is not allowed.This function is called automatically by Emacs on the properoccasions. 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 andnarrowing. Read-only buffers are used in two kinds of situations:@itemize @bullet@itemA buffer visiting a write-protected file is normally read-only.Here, the purpose is to inform the user that editing the buffer with theaim of saving it in the file may be futile or undesirable. The user whowants to change the buffer text despite this can do so after clearingthe read-only flag with @kbd{C-x C-q}.@itemModes such as Dired and Rmail make buffers read-only when altering thecontents 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-onlyThis 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-onlyIf this variable is non-@code{nil}, then read-only buffers and,depending on the actual value, some or all read-only characters may bemodified. Read-only characters in a buffer are those that havenon-@code{nil} @code{read-only} properties (either text properties oroverlay properties). @xref{Special Properties}, for more informationabout text properties. @xref{Overlays}, for more information aboutoverlays and their properties.If @code{inhibit-read-only} is @code{t}, all @code{read-only} characterproperties have no effect. If @code{inhibit-read-only} is a list, then@code{read-only} character properties have no effect if they are membersof the list (comparison is done with @code{eq}).@end defvar@deffn Command toggle-read-only &optional argThis command toggles whether the current buffer is read-only. It isintended for interactive use; do not use it in programs. At any givenpoint in a program, you should know whether you want the read-only flagon or off; so you can set @code{buffer-read-only} explicitly to theproper 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} ifthe numeric value of that prefix argument is positive and to@code{nil} otherwise. @xref{Prefix Command Arguments}.@end deffn@defun barf-if-buffer-read-onlyThis function signals a @code{buffer-read-only} error if the currentbuffer is read-only. @xref{Using Interactive}, for another way tosignal 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. Creating abuffer adds it to this list, and killing a buffer removes it. Theorder of the buffers in the list is based primarily on how recentlyeach buffer has been displayed in the selected window. Buffers moveto the front of the list when they are selected (selecting a windowthat already displays the buffer counts as selecting the buffer), andto the end when they are buried (see @code{bury-buffer}, below).Several functions, notably @code{other-buffer}, use this ordering. Abuffer list displayed for the user also follows this order. In addition to the fundamental Emacs buffer list, each frame has itsown version of the buffer list, in which the buffers that have beenselected in that frame come first, starting with the buffers mostrecently selected @emph{in that frame}. (This order is recorded in@var{frame}'s @code{buffer-list} frame parameter; see @ref{Window FrameParameters}.) The buffers that were never selected in @var{frame} comeafterward, ordered according to the fundamental Emacs buffer list.@defun buffer-list &optional frameThis function returns the buffer list, including all buffers, even thosewhose names begin with a space. The elements are actual buffers, nottheir 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 ofwhich frames they were selected in.@example@group(buffer-list) @result{} (#<buffer buffers.texi> #<buffer *Minibuf-1*> #<buffer buffer.c> #<buffer *Help*> #<buffer TAGS>)@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 specificallyby @code{buffer-list}; it is not an internal Emacs data structure, andmodifying it has no effect on the order of buffers. If you want tochange the order of buffers in the frame-independent buffer list, hereis 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 isno danger of losing a buffer or adding something that is not a validlive 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 frameThis function returns the first buffer in the buffer list other than@var{buffer}. Usually this is the buffer selected most recently (inframe @var{frame} or else the currently selected frame, @pxref{InputFocus}), aside from @var{buffer}. Buffers whose names start with aspace 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'sbuffer 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 toconsider. It calls the predicate once for each buffer, and if the valueis @code{nil}, that buffer is ignored. @xref{Window Frame Parameters}.@c Emacs 19 featureIf @var{visible-ok} is @code{nil}, @code{other-buffer} avoids returninga buffer visible in any window on any visible frame, except as a lastresort. If @var{visible-ok} is non-@code{nil}, then it does not matterwhether 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-nameThis 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.@code{bury-buffer} operates on each frame's @code{buffer-list} parameteras well as the frame-independent Emacs buffer list; therefore, thebuffer 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 thecurrent buffer. In addition, if the buffer is displayed in the selectedwindow, this switches to some other buffer (obtained using@code{other-buffer}) in the selected window. But if the buffer isdisplayed 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 bufferwith the specified name; @code{generate-new-buffer} always creates a newbuffer 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 asubprocess can also create a buffer (@pxref{Processes}).@defun get-buffer-create nameThis function returns a buffer named @var{name}. It returns a livebuffer with that name, if one exists; otherwise, it creates a newbuffer. The buffer does not become the current buffer---this functiondoes not change which buffer is current.If @var{name} is a buffer instead of a string, it is returned, even ifit is dead. An error is signaled if @var{name} is neither a stringnor a buffer.@example@group(get-buffer-create "foo") @result{} #<buffer foo>@end group@end exampleThe major mode for a newly created buffer is set to Fundamental mode.The variable @code{default-major-mode} is handled at a higher level.@xref{Auto Major Mode}.@end defun@defun generate-new-buffer nameThis function returns a newly created, empty buffer, but does not makeit current. If there is no buffer named @var{name}, then that is thename of the new buffer. If that name is in use, this function addssuffixes of the form @samp{<@var{n}>} to @var{name}, where @var{n} is aninteger. It tries successive integers starting with 2 until it finds anavailable name.An error is signaled if @var{name} is not a string.@example@group(generate-new-buffer "bar") @result{} #<buffer bar>@end group@group(generate-new-buffer "bar") @result{} #<buffer bar<2>>@end group@group(generate-new-buffer "bar") @result{} #<buffer bar<3>>@end group@end exampleThe major mode for the new buffer is set to Fundamental mode. Thevariable @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{BufferNames}.@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 itstext space available for other use. The buffer object for the buffer that has been killed remains inexistence as long as anything refers to it, but it is specially markedso that you cannot make it current or display it. Killed buffers retaintheir identity, however; if you kill two distinct buffers, they remaindistinct according to @code{eq} although both are dead. If you kill a buffer that is current or displayed in a window, Emacsautomatically selects or displays some other buffer instead. This meansthat killing a buffer can in general change the current buffer.Therefore, when you kill a buffer, you should also take the precautionsassociated with changing the current buffer (unless you happen to knowthat the buffer being killed isn't current). @xref{Current Buffer}. If you kill a buffer that is the base buffer of one or more indirectbuffers, the indirect buffers are automatically killed as well. The @code{buffer-name} of a killed buffer is @code{nil}. You can usethis 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-nameThis function kills the buffer @var{buffer-or-name}, freeing all itsmemory 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} aresent the @code{SIGHUP} signal, which normally causes them to terminate.(The basic meaning of @code{SIGHUP} is that a dialup line has beendisconnected.) @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 requestfor 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. Itreturns @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-functionsAfter confirming unsaved changes, @code{kill-buffer} calls the functionsin the list @code{kill-buffer-query-functions}, in order of appearance,with no arguments. The buffer being killed is the current buffer whenthey are called. The idea of this feature is that these functions willask 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-hookThis is a normal hook run by @code{kill-buffer} after asking all thequestions 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 bindingis not cleared by changing major modes.@end defvar@defvar buffer-offer-saveThis variable, if non-@code{nil} in a particular buffer, tells@code{save-buffers-kill-emacs} and @code{save-some-buffers} (if thesecond optional argument to that function is @code{t}) to offer tosave 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 setfor any reason. @xref{Buffer-Local Variables}.@end defvar@defun buffer-live-p objectThis function returns @code{t} if @var{object} is a buffer which hasnot 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, whichis called the @dfn{base buffer} of the indirect buffer. In some ways itis the analogue, for buffers, of a symbolic link among files. The basebuffer may not itself be an indirect buffer. The text of the indirect buffer is always identical to the text of itsbase buffer; changes made by editing either one are visible immediatelyin the other. This includes the text properties as well as the charactersthemselves. In all other respects, the indirect buffer and its base buffer arecompletely separate. They have different names, different values ofpoint, different narrowing, different markers and overlays (thoughinserting or deleting text in either buffer relocates the markers andoverlays for both), different major modes, and different buffer-localvariables. An indirect buffer cannot visit a file, but its base buffer can. Ifyou try to save the indirect buffer, that actually saves the basebuffer. Killing an indirect buffer has no effect on its base buffer. Killingthe base buffer effectively kills the indirect buffer in that it cannotever again be the current buffer.@deffn Command make-indirect-buffer base-buffer name &optional cloneThis creates and returns an indirect buffer named @var{name} whosebase buffer is @var{base-buffer}. The argument @var{base-buffer} maybe 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 originallyshares the ``state'' of @var{base-buffer} such as major mode, minormodes, buffer local variables and so on. If @var{clone} is omittedor @code{nil} the indirect buffer's state is set to the default statefor new buffers.If @var{base-buffer} is an indirect buffer, its base buffer is used asthe base for the new buffer. If, in addition, @var{clone} isnon-@code{nil}, the initial state is copied from the actual basebuffer, not from @var{base-buffer}.@end deffn@defun buffer-base-buffer &optional bufferThis function returns the base buffer of @var{buffer}, which defaultsto the current buffer. If @var{buffer} is not indirect, the value is@code{nil}. Otherwise, the value is another buffer, which is never anindirect buffer.@end defun@node Buffer Gap@section The Buffer Gap Emacs buffers are implemented using an invisible @dfn{gap} to makeinsertion and deletion faster. Insertion works by filling in part ofthe gap, and deletion adds to the gap. Of course, this means that thegap 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 whyyour first editing command in one part of a large buffer, afterpreviously editing in another far-away part, sometimes involves anoticeable delay. This mechanism works invisibly, and Lisp code should never be affectedby the gap's current location, but these functions are available forgetting information about the gap status.@defun gap-positionThis function returns the current gap position in the current buffer.@end defun@defun gap-sizeThis function returns the current gap size of the current buffer.@end defun@ignore arch-tag: 2e53cfab-5691-41f6-b5a8-9c6a3462399c@end ignore