*** empty log message ***
[emacs.git] / lispref / buffers.texi
blobb0c79cd28d5efc87a06242ba792ec379c6bf35aa
1 @c -*-texinfo-*-
2 @c This is part of the GNU Emacs Lisp Reference Manual.
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999
4 @c   Free Software Foundation, Inc. 
5 @c See the file elisp.texi for copying conditions.
6 @setfilename ../info/buffers
7 @node Buffers, Windows, Backups and Auto-Saving, Top
8 @chapter Buffers
9 @cindex buffer
11   A @dfn{buffer} is a Lisp object containing text to be edited.  Buffers
12 are used to hold the contents of files that are being visited; there may
13 also be buffers that are not visiting files.  While several buffers may
14 exist at one time, only one buffer is designated the @dfn{current
15 buffer} at any time.  Most editing commands act on the contents of the
16 current buffer.  Each buffer, including the current buffer, may or may
17 not be displayed in any windows.
19 @menu
20 * Buffer Basics::       What is a buffer?
21 * Current Buffer::      Designating a buffer as current
22                           so that primitives will access its contents.
23 * Buffer Names::        Accessing and changing buffer names.
24 * Buffer File Name::    The buffer file name indicates which file is visited.
25 * Buffer Modification:: A buffer is @dfn{modified} if it needs to be saved.
26 * Modification Time::   Determining whether the visited file was changed
27                          ``behind Emacs's back''.
28 * Read Only Buffers::   Modifying text is not allowed in a read-only buffer.
29 * The Buffer List::     How to look at all the existing buffers.
30 * Creating Buffers::    Functions that create buffers.
31 * Killing Buffers::     Buffers exist until explicitly killed.
32 * Indirect Buffers::    An indirect buffer shares text with some other buffer.
33 * Buffer Gap::          The gap in the buffer.
34 @end menu
36 @node Buffer Basics
37 @comment  node-name,  next,  previous,  up
38 @section Buffer Basics
40 @ifnottex
41   A @dfn{buffer} is a Lisp object containing text to be edited.  Buffers
42 are used to hold the contents of files that are being visited; there may
43 also be buffers that are not visiting files.  Although several buffers
44 normally exist, only one buffer is designated the @dfn{current
45 buffer} at any time.  Most editing commands act on the contents of the
46 current buffer.  Each buffer, including the current buffer, may or may
47 not be displayed in any windows.
48 @end ifnottex
50   Buffers in Emacs editing are objects that have distinct names and hold
51 text that can be edited.  Buffers appear to Lisp programs as a special
52 data type.  You can think of the contents of a buffer as a string that
53 you can extend; insertions and deletions may occur in any part of the
54 buffer.  @xref{Text}.
56   A Lisp buffer object contains numerous pieces of information.  Some of
57 this information is directly accessible to the programmer through
58 variables, while other information is accessible only through
59 special-purpose functions.  For example, the visited file name is
60 directly accessible through a variable, while the value of point is
61 accessible only through a primitive function.
63   Buffer-specific information that is directly accessible is stored in
64 @dfn{buffer-local} variable bindings, which are variable values that are
65 effective only in a particular buffer.  This feature allows each buffer
66 to override the values of certain variables.  Most major modes override
67 variables such as @code{fill-column} or @code{comment-column} in this
68 way.  For more information about buffer-local variables and functions
69 related to them, see @ref{Buffer-Local Variables}.
71   For functions and variables related to visiting files in buffers, see
72 @ref{Visiting Files} and @ref{Saving Buffers}.  For functions and
73 variables related to the display of buffers in windows, see
74 @ref{Buffers and Windows}.
76 @defun bufferp object
77 This function returns @code{t} if @var{object} is a buffer,
78 @code{nil} otherwise.
79 @end defun
81 @node Current Buffer
82 @section The Current Buffer
83 @cindex selecting a buffer
84 @cindex changing to another buffer
85 @cindex current buffer
87   There are, in general, many buffers in an Emacs session.  At any time,
88 one of them is designated as the @dfn{current buffer}.  This is the
89 buffer in which most editing takes place, because most of the primitives
90 for examining or changing text in a buffer operate implicitly on the
91 current buffer (@pxref{Text}).  Normally the buffer that is displayed on
92 the screen in the selected window is the current buffer, but this is not
93 always so: a Lisp program can temporarily designate any buffer as
94 current in order to operate on its contents, without changing what is
95 displayed on the screen.
97   The way to designate a current buffer in a Lisp program is by calling
98 @code{set-buffer}.  The specified buffer remains current until a new one
99 is designated.
101   When an editing command returns to the editor command loop, the
102 command loop designates the buffer displayed in the selected window as
103 current, to prevent confusion: the buffer that the cursor is in when
104 Emacs reads a command is the buffer that the command will apply to.
105 (@xref{Command Loop}.)  Therefore, @code{set-buffer} is not the way to
106 switch visibly to a different buffer so that the user can edit it.  For
107 that, you must use the functions described in @ref{Displaying Buffers}.
109   @strong{Note:} Lisp functions that change to a different current buffer
110 should not depend on the command loop to set it back afterwards.
111 Editing commands written in Emacs Lisp can be called from other programs
112 as well as from the command loop; it is convenient for the caller if
113 the subroutine does not change which buffer is current (unless, of
114 course, that is the subroutine's purpose).  Therefore, you should
115 normally use @code{set-buffer} within a @code{save-current-buffer} or
116 @code{save-excursion} (@pxref{Excursions}) form that will restore the
117 current buffer when your function is done.  Here is an example, the
118 code for the command @code{append-to-buffer} (with the documentation
119 string abridged):
121 @example
122 @group
123 (defun append-to-buffer (buffer start end)
124   "Append to specified buffer the text of the region.
125 @dots{}"
126   (interactive "BAppend to buffer: \nr")
127   (let ((oldbuf (current-buffer)))
128     (save-current-buffer
129       (set-buffer (get-buffer-create buffer))
130       (insert-buffer-substring oldbuf start end))))
131 @end group
132 @end example
134 @noindent
135 This function binds a local variable to record the current buffer, and
136 then @code{save-current-buffer} arranges to make it current again.
137 Next, @code{set-buffer} makes the specified buffer current.  Finally,
138 @code{insert-buffer-substring} copies the string from the original
139 current buffer to the specified (and now current) buffer.
141   If the buffer appended to happens to be displayed in some window, 
142 the next redisplay will show how its text has changed.  Otherwise, you
143 will not see the change immediately on the screen.  The buffer becomes
144 current temporarily during the execution of the command, but this does
145 not cause it to be displayed.
147   If you make local bindings (with @code{let} or function arguments) for
148 a variable that may also have buffer-local bindings, make sure that the
149 same buffer is current at the beginning and at the end of the local
150 binding's scope.  Otherwise you might bind it in one buffer and unbind
151 it in another!  There are two ways to do this.  In simple cases, you may
152 see that nothing ever changes the current buffer within the scope of the
153 binding.  Otherwise, use @code{save-current-buffer} or
154 @code{save-excursion} to make sure that the buffer current at the
155 beginning is current again whenever the variable is unbound.
157   Do not rely on using @code{set-buffer} to change the current buffer
158 back, because that won't do the job if a quit happens while the wrong
159 buffer is current.  Here is what @emph{not} to do:
161 @example
162 @group
163 (let (buffer-read-only
164       (obuf (current-buffer)))
165   (set-buffer @dots{})
166   @dots{}
167   (set-buffer obuf))
168 @end group
169 @end example
171 @noindent
172 Using @code{save-current-buffer}, as shown here, handles quitting,
173 errors, and @code{throw}, as well as ordinary evaluation.
175 @example
176 @group
177 (let (buffer-read-only)
178   (save-current-buffer
179     (set-buffer @dots{})
180     @dots{}))
181 @end group
182 @end example
184 @defun current-buffer
185 This function returns the current buffer.
187 @example
188 @group
189 (current-buffer)
190      @result{} #<buffer buffers.texi>
191 @end group
192 @end example
193 @end defun
195 @defun set-buffer buffer-or-name
196 This function makes @var{buffer-or-name} the current buffer.  This does
197 not display the buffer in any window, so the user cannot necessarily see
198 the buffer.  But Lisp programs will now operate on it.
200 This function returns the buffer identified by @var{buffer-or-name}.
201 An error is signaled if @var{buffer-or-name} does not identify an
202 existing buffer.
203 @end defun
205 @defspec save-current-buffer body...
206 The @code{save-current-buffer} macro saves the identity of the current
207 buffer, evaluates the @var{body} forms, and finally restores that buffer
208 as current.  The return value is the value of the last form in
209 @var{body}.  The current buffer is restored even in case of an abnormal
210 exit via @code{throw} or error (@pxref{Nonlocal Exits}).
212 If the buffer that used to be current has been killed by the time of
213 exit from @code{save-current-buffer}, then it is not made current again,
214 of course.  Instead, whichever buffer was current just before exit
215 remains current.
216 @end defspec
218 @defmac with-current-buffer buffer body...
219 The @code{with-current-buffer} macro saves the identity of the current
220 buffer, makes @var{buffer} current, evaluates the @var{body} forms, and
221 finally restores the buffer.  The return value is the value of the last
222 form in @var{body}.  The current buffer is restored even in case of an
223 abnormal exit via @code{throw} or error (@pxref{Nonlocal Exits}).
224 @end defmac
226 @defmac with-temp-buffer body...
227 The @code{with-temp-buffer} macro evaluates the @var{body} forms
228 with a temporary buffer as the current buffer.  It saves the identity of
229 the current buffer, creates a temporary buffer and makes it current,
230 evaluates the @var{body} forms, and finally restores the previous
231 current buffer while killing the temporary buffer.
233 The return value is the value of the last form in @var{body}.  You can
234 return the contents of the temporary buffer by using
235 @code{(buffer-string)} as the last form.
237 The current buffer is restored even in case of an abnormal exit via
238 @code{throw} or error (@pxref{Nonlocal Exits}).
239 @end defmac
241 See also @code{with-temp-file} in @ref{Writing to Files}.
243 @node Buffer Names
244 @section Buffer Names
245 @cindex buffer names
247   Each buffer has a unique name, which is a string.  Many of the
248 functions that work on buffers accept either a buffer or a buffer name
249 as an argument.  Any argument called @var{buffer-or-name} is of this
250 sort, and an error is signaled if it is neither a string nor a buffer.
251 Any argument called @var{buffer} must be an actual buffer
252 object, not a name.
254   Buffers that are ephemeral and generally uninteresting to the user
255 have names starting with a space, so that the @code{list-buffers} and
256 @code{buffer-menu} commands don't mention them (but if such a buffer
257 visits a file, it @strong{is} mentioned).  A name starting with
258 space also initially disables recording undo information; see
259 @ref{Undo}.
261 @defun buffer-name &optional buffer
262 This function returns the name of @var{buffer} as a string.  If
263 @var{buffer} is not supplied, it defaults to the current buffer.
265 If @code{buffer-name} returns @code{nil}, it means that @var{buffer}
266 has been killed.  @xref{Killing Buffers}.
268 @example
269 @group
270 (buffer-name)
271      @result{} "buffers.texi"
272 @end group
274 @group
275 (setq foo (get-buffer "temp"))
276      @result{} #<buffer temp>
277 @end group
278 @group
279 (kill-buffer foo)
280      @result{} nil
281 @end group
282 @group
283 (buffer-name foo)
284      @result{} nil
285 @end group
286 @group
288      @result{} #<killed buffer>
289 @end group
290 @end example
291 @end defun
293 @deffn Command rename-buffer newname &optional unique
294 This function renames the current buffer to @var{newname}.  An error
295 is signaled if @var{newname} is not a string, or if there is already a
296 buffer with that name.  The function returns @var{newname}.
298 @c Emacs 19 feature
299 Ordinarily, @code{rename-buffer} signals an error if @var{newname} is
300 already in use.  However, if @var{unique} is non-@code{nil}, it modifies
301 @var{newname} to make a name that is not in use.  Interactively, you can
302 make @var{unique} non-@code{nil} with a numeric prefix argument.
303 (This is how the command @code{rename-uniquely} is implemented.)
304 @end deffn
306 @defun get-buffer buffer-or-name
307 This function returns the buffer specified by @var{buffer-or-name}.
308 If @var{buffer-or-name} is a string and there is no buffer with that
309 name, the value is @code{nil}.  If @var{buffer-or-name} is a buffer, it
310 is returned as given; that is not very useful, so the argument is usually 
311 a name.  For example:
313 @example
314 @group
315 (setq b (get-buffer "lewis"))
316      @result{} #<buffer lewis>
317 @end group
318 @group
319 (get-buffer b)
320      @result{} #<buffer lewis>
321 @end group
322 @group
323 (get-buffer "Frazzle-nots")
324      @result{} nil
325 @end group
326 @end example
328 See also the function @code{get-buffer-create} in @ref{Creating Buffers}.
329 @end defun
331 @c Emacs 19 feature
332 @defun generate-new-buffer-name starting-name &rest ignore
333 This function returns a name that would be unique for a new buffer---but
334 does not create the buffer.  It starts with @var{starting-name}, and
335 produces a name not currently in use for any buffer by appending a
336 number inside of @samp{<@dots{}>}.
338 If the optional second argument @var{ignore} is non-@code{nil}, it
339 should be a string; it makes a difference if it is a name in the
340 sequence of names to be tried.  That name will be considered acceptable,
341 if it is tried, even if a buffer with that name exists.  Thus, if
342 buffers named @samp{foo}, @samp{foo<2>}, @samp{foo<3>} and @samp{foo<4>}
343 exist,
345 @example
346 (generate-new-buffer-name "foo")
347      @result{} "foo<5>"
348 (generate-new-buffer-name "foo" "foo<3>")
349      @result{} "foo<3>"
350 (generate-new-buffer-name "foo" "foo<6>")
351      @result{} "foo<5>"
352 @end example
354 See the related function @code{generate-new-buffer} in @ref{Creating
355 Buffers}.
356 @end defun
358 @node Buffer File Name
359 @section Buffer File Name
360 @cindex visited file
361 @cindex buffer file name
362 @cindex file name of buffer
364   The @dfn{buffer file name} is the name of the file that is visited in
365 that buffer.  When a buffer is not visiting a file, its buffer file name
366 is @code{nil}.  Most of the time, the buffer name is the same as the
367 nondirectory part of the buffer file name, but the buffer file name and
368 the buffer name are distinct and can be set independently.
369 @xref{Visiting Files}.
371 @defun buffer-file-name &optional buffer
372 This function returns the absolute file name of the file that
373 @var{buffer} is visiting.  If @var{buffer} is not visiting any file,
374 @code{buffer-file-name} returns @code{nil}.  If @var{buffer} is not
375 supplied, it defaults to the current buffer.
377 @example
378 @group
379 (buffer-file-name (other-buffer))
380      @result{} "/usr/user/lewis/manual/files.texi"
381 @end group
382 @end example
383 @end defun
385 @defvar buffer-file-name
386 This buffer-local variable contains the name of the file being visited
387 in the current buffer, or @code{nil} if it is not visiting a file.  It
388 is a permanent local variable, unaffected by
389 @code{kill-all-local-variables}.
391 @example
392 @group
393 buffer-file-name
394      @result{} "/usr/user/lewis/manual/buffers.texi"
395 @end group
396 @end example
398 It is risky to change this variable's value without doing various other
399 things.  Normally it is better to use @code{set-visited-file-name} (see
400 below); some of the things done there, such as changing the buffer name,
401 are not strictly necessary, but others are essential to avoid confusing
402 Emacs.
403 @end defvar
405 @defvar buffer-file-truename
406 This buffer-local variable holds the truename of the file visited in the
407 current buffer, or @code{nil} if no file is visited.  It is a permanent
408 local, unaffected by @code{kill-all-local-variables}.  @xref{Truenames}.
409 @end defvar
411 @defvar buffer-file-number
412 This buffer-local variable holds the file number and directory device
413 number of the file visited in the current buffer, or @code{nil} if no
414 file or a nonexistent file is visited.  It is a permanent local,
415 unaffected by @code{kill-all-local-variables}.
417 The value is normally a list of the form @code{(@var{filenum}
418 @var{devnum})}.  This pair of numbers uniquely identifies the file among
419 all files accessible on the system.  See the function
420 @code{file-attributes}, in @ref{File Attributes}, for more information
421 about them.
422 @end defvar
424 @defun get-file-buffer filename
425 This function returns the buffer visiting file @var{filename}.  If
426 there is no such buffer, it returns @code{nil}.  The argument
427 @var{filename}, which must be a string, is expanded (@pxref{File Name
428 Expansion}), then compared against the visited file names of all live
429 buffers.
431 @example
432 @group
433 (get-file-buffer "buffers.texi")
434     @result{} #<buffer buffers.texi>
435 @end group
436 @end example
438 In unusual circumstances, there can be more than one buffer visiting
439 the same file name.  In such cases, this function returns the first
440 such buffer in the buffer list.
441 @end defun
443 @deffn Command set-visited-file-name filename &optional no-query along-with-file
444 If @var{filename} is a non-empty string, this function changes the
445 name of the file visited in the current buffer to @var{filename}.  (If the
446 buffer had no visited file, this gives it one.)  The @emph{next time}
447 the buffer is saved it will go in the newly-specified file.  This
448 command marks the buffer as modified, since it does not (as far as Emacs
449 knows) match the contents of @var{filename}, even if it matched the
450 former visited file.
452 If @var{filename} is @code{nil} or the empty string, that stands for
453 ``no visited file''.  In this case, @code{set-visited-file-name} marks
454 the buffer as having no visited file.
456 Normally, this function asks the user for confirmation if the specified
457 file already exists.  If @var{no-query} is non-@code{nil}, that prevents
458 asking this question.
460 If @var{along-with-file} is non-@code{nil}, that means to assume that the
461 former visited file has been renamed to @var{filename}.
463 @c Wordy to avoid overfull hbox.  --rjc 16mar92
464 When the function @code{set-visited-file-name} is called interactively, it
465 prompts for @var{filename} in the minibuffer.
466 @end deffn
468 @defvar list-buffers-directory
469 This buffer-local variable specifies a string to display in a buffer
470 listing where the visited file name would go, for buffers that don't
471 have a visited file name.  Dired buffers use this variable.
472 @end defvar
474 @node Buffer Modification
475 @section Buffer Modification
476 @cindex buffer modification
477 @cindex modification flag (of buffer)
479   Emacs keeps a flag called the @dfn{modified flag} for each buffer, to
480 record whether you have changed the text of the buffer.  This flag is
481 set to @code{t} whenever you alter the contents of the buffer, and
482 cleared to @code{nil} when you save it.  Thus, the flag shows whether
483 there are unsaved changes.  The flag value is normally shown in the mode
484 line (@pxref{Mode Line Variables}), and controls saving (@pxref{Saving
485 Buffers}) and auto-saving (@pxref{Auto-Saving}).
487   Some Lisp programs set the flag explicitly.  For example, the function
488 @code{set-visited-file-name} sets the flag to @code{t}, because the text
489 does not match the newly-visited file, even if it is unchanged from the
490 file formerly visited.
492   The functions that modify the contents of buffers are described in
493 @ref{Text}.
495 @defun buffer-modified-p &optional buffer
496 This function returns @code{t} if the buffer @var{buffer} has been modified
497 since it was last read in from a file or saved, or @code{nil}
498 otherwise.  If @var{buffer} is not supplied, the current buffer
499 is tested.
500 @end defun
502 @defun set-buffer-modified-p flag
503 This function marks the current buffer as modified if @var{flag} is
504 non-@code{nil}, or as unmodified if the flag is @code{nil}.
506 Another effect of calling this function is to cause unconditional
507 redisplay of the mode line for the current buffer.  In fact, the
508 function @code{force-mode-line-update} works by doing this:
510 @example
511 @group
512 (set-buffer-modified-p (buffer-modified-p))
513 @end group
514 @end example
515 @end defun
517 @deffn Command not-modified
518 This command marks the current buffer as unmodified, and not needing to
519 be saved.  With prefix arg, it marks the buffer as modified, so that it
520 will be saved at the next suitable occasion.
522 Don't use this function in programs, since it prints a message in the
523 echo area; use @code{set-buffer-modified-p} (above) instead.
524 @end deffn
526 @c Emacs 19 feature
527 @defun buffer-modified-tick &optional buffer
528 This function returns @var{buffer}'s modification-count.  This is a
529 counter that increments every time the buffer is modified.  If
530 @var{buffer} is @code{nil} (or omitted), the current buffer is used.
531 @end defun
533 @node Modification Time
534 @comment  node-name,  next,  previous,  up
535 @section Comparison of Modification Time
536 @cindex comparison of modification time
537 @cindex modification time, comparison of 
539   Suppose that you visit a file and make changes in its buffer, and
540 meanwhile the file itself is changed on disk.  At this point, saving the
541 buffer would overwrite the changes in the file.  Occasionally this may
542 be what you want, but usually it would lose valuable information.  Emacs
543 therefore checks the file's modification time using the functions
544 described below before saving the file.
546 @defun verify-visited-file-modtime buffer
547 This function compares what @var{buffer} has recorded for the
548 modification time of its visited file against the actual modification
549 time of the file as recorded by the operating system.  The two should be
550 the same unless some other process has written the file since Emacs
551 visited or saved it.
553 The function returns @code{t} if the last actual modification time and
554 Emacs's recorded modification time are the same, @code{nil} otherwise.
555 @end defun
557 @defun clear-visited-file-modtime
558 This function clears out the record of the last modification time of
559 the file being visited by the current buffer.  As a result, the next
560 attempt to save this buffer will not complain of a discrepancy in
561 file modification times.
563 This function is called in @code{set-visited-file-name} and other
564 exceptional places where the usual test to avoid overwriting a changed
565 file should not be done.
566 @end defun
568 @c Emacs 19 feature
569 @defun visited-file-modtime
570 This function returns the buffer's recorded last file modification time,
571 as a list of the form @code{(@var{high} . @var{low})}.  (This is the
572 same format that @code{file-attributes} uses to return time values; see
573 @ref{File Attributes}.)
574 @end defun
576 @c Emacs 19 feature
577 @defun set-visited-file-modtime &optional time
578 This function updates the buffer's record of the last modification time
579 of the visited file, to the value specified by @var{time} if @var{time}
580 is not @code{nil}, and otherwise to the last modification time of the
581 visited file.
583 If @var{time} is not @code{nil}, it should have the form
584 @code{(@var{high} . @var{low})} or @code{(@var{high} @var{low})}, in
585 either case containing two integers, each of which holds 16 bits of the
586 time.
588 This function is useful if the buffer was not read from the file
589 normally, or if the file itself has been changed for some known benign
590 reason.
591 @end defun
593 @defun ask-user-about-supersession-threat filename
594 @cindex obsolete buffer
595 This function is used to ask a user how to proceed after an attempt to
596 modify an obsolete buffer visiting file @var{filename}.  An
597 @dfn{obsolete buffer} is an unmodified buffer for which the associated
598 file on disk is newer than the last save-time of the buffer.  This means
599 some other program has probably altered the file.
601 @kindex file-supersession
602 Depending on the user's answer, the function may return normally, in
603 which case the modification of the buffer proceeds, or it may signal a
604 @code{file-supersession} error with data @code{(@var{filename})}, in which
605 case the proposed buffer modification is not allowed.  
607 This function is called automatically by Emacs on the proper
608 occasions.  It exists so you can customize Emacs by redefining it.
609 See the file @file{userlock.el} for the standard definition.
611 See also the file locking mechanism in @ref{File Locks}.
612 @end defun
614 @node Read Only Buffers
615 @section Read-Only Buffers
616 @cindex read-only buffer
617 @cindex buffer, read-only
619   If a buffer is @dfn{read-only}, then you cannot change its contents,
620 although you may change your view of the contents by scrolling and 
621 narrowing.
623   Read-only buffers are used in two kinds of situations:
625 @itemize @bullet
626 @item
627 A buffer visiting a write-protected file is normally read-only.
629 Here, the purpose is to inform the user that editing the buffer with the
630 aim of saving it in the file may be futile or undesirable.  The user who
631 wants to change the buffer text despite this can do so after clearing
632 the read-only flag with @kbd{C-x C-q}.
634 @item
635 Modes such as Dired and Rmail make buffers read-only when altering the
636 contents with the usual editing commands would probably be a mistake.
638 The special commands of these modes bind @code{buffer-read-only} to
639 @code{nil} (with @code{let}) or bind @code{inhibit-read-only} to
640 @code{t} around the places where they themselves change the text.
641 @end itemize
643 @defvar buffer-read-only
644 This buffer-local variable specifies whether the buffer is read-only.
645 The buffer is read-only if this variable is non-@code{nil}.
646 @end defvar
648 @defvar inhibit-read-only
649 If this variable is non-@code{nil}, then read-only buffers and read-only
650 characters may be modified.  Read-only characters in a buffer are those
651 that have non-@code{nil} @code{read-only} properties (either text
652 properties or overlay properties).  @xref{Special Properties}, for more
653 information about text properties.  @xref{Overlays}, for more
654 information about overlays and their properties.
656 If @code{inhibit-read-only} is @code{t}, all @code{read-only} character
657 properties have no effect.  If @code{inhibit-read-only} is a list, then
658 @code{read-only} character properties have no effect if they are members
659 of the list (comparison is done with @code{eq}).
660 @end defvar
662 @deffn Command toggle-read-only
663 This command changes whether the current buffer is read-only.  It is
664 intended for interactive use; do not use it in programs.  At any given
665 point in a program, you should know whether you want the read-only flag
666 on or off; so you can set @code{buffer-read-only} explicitly to the
667 proper value, @code{t} or @code{nil}.
668 @end deffn
670 @defun barf-if-buffer-read-only
671 This function signals a @code{buffer-read-only} error if the current
672 buffer is read-only.  @xref{Interactive Call}, for another way to
673 signal an error if the current buffer is read-only.
674 @end defun
676 @node The Buffer List
677 @section The Buffer List
678 @cindex buffer list
680   The @dfn{buffer list} is a list of all live buffers.  Creating a
681 buffer adds it to this list, and killing a buffer excises it.  The order
682 of the buffers in the list is based primarily on how recently each
683 buffer has been displayed in the selected window.  Buffers move to the
684 front of the list when they are selected and to the end when they are
685 buried (see @code{bury-buffer}, below).  Several functions, notably
686 @code{other-buffer}, use this ordering.  A buffer list displayed for the
687 user also follows this order.
689   In addition to the fundamental Emacs buffer list, each frame has its
690 own version of the buffer list, in which the buffers that have been
691 selected in that frame come first, starting with the buffers most
692 recently selected @emph{in that frame}.  (This order is recorded in
693 @var{frame}'s @code{buffer-list} frame parameter; see @ref{Window Frame
694 Parameters}.)  The buffers that were never selected in @var{frame} come
695 afterward, ordered according to the fundamental Emacs buffer list.
697 @defun buffer-list &optional frame
698 This function returns the buffer list, including all buffers, even those
699 whose names begin with a space.  The elements are actual buffers, not
700 their names.
702 If @var{frame} is a frame, this returns @var{frame}'s buffer list.  If
703 @var{frame} is @code{nil}, the fundamental Emacs buffer list is used:
704 all the buffers appear in order of most recent selection, regardless of
705 which frames they were selected in.
707 @example
708 @group
709 (buffer-list)
710      @result{} (#<buffer buffers.texi>
711          #<buffer  *Minibuf-1*> #<buffer buffer.c>
712          #<buffer *Help*> #<buffer TAGS>)
713 @end group
715 @group
716 ;; @r{Note that the name of the minibuffer}
717 ;;   @r{begins with a space!}
718 (mapcar (function buffer-name) (buffer-list))
719     @result{} ("buffers.texi" " *Minibuf-1*" 
720         "buffer.c" "*Help*" "TAGS")
721 @end group
722 @end example
723 @end defun
725   The list that @code{buffer-list} returns is constructed specifically
726 by @code{buffer-list}; it is not an internal Emacs data structure, and
727 modifying it has no effect on the order of buffers.  If you want to
728 change the order of buffers in the frame-independent buffer list, here
729 is an easy way:
731 @example
732 (defun reorder-buffer-list (new-list)
733   (while new-list
734     (bury-buffer (car new-list))
735     (setq new-list (cdr new-list))))
736 @end example
738   With this method, you can specify any order for the list, but there is
739 no danger of losing a buffer or adding something that is not a valid
740 live buffer.
742   To change the order or value of a frame's buffer list, set the frame's
743 @code{buffer-list} frame parameter with @code{modify-frame-parameters}
744 (@pxref{Parameter Access}).
746 @defun other-buffer &optional buffer visible-ok frame
747 This function returns the first buffer in the buffer list other than
748 @var{buffer}.  Usually this is the buffer selected most recently (in
749 frame @var{frame} or else the currently selected frame, @pxref{Input
750 Focus}), aside from @var{buffer}.  Buffers whose names start with a
751 space are not considered at all.
753 If @var{buffer} is not supplied (or if it is not a buffer), then
754 @code{other-buffer} returns the first buffer in the selected frame's
755 buffer list that is not now visible in any window in a visible frame.
757 If @var{frame} has a non-@code{nil} @code{buffer-predicate} parameter,
758 then @code{other-buffer} uses that predicate to decide which buffers to
759 consider.  It calls the predicate once for each buffer, and if the value
760 is @code{nil}, that buffer is ignored.  @xref{Window Frame Parameters}.
762 @c Emacs 19 feature
763 If @var{visible-ok} is @code{nil}, @code{other-buffer} avoids returning
764 a buffer visible in any window on any visible frame, except as a last
765 resort.   If @var{visible-ok} is non-@code{nil}, then it does not matter
766 whether a buffer is displayed somewhere or not.
768 If no suitable buffer exists, the buffer @samp{*scratch*} is returned
769 (and created, if necessary).
770 @end defun
772 @deffn Command bury-buffer &optional buffer-or-name
773 This function puts @var{buffer-or-name} at the end of the buffer list,
774 without changing the order of any of the other buffers on the list.
775 This buffer therefore becomes the least desirable candidate for
776 @code{other-buffer} to return.
778 @code{bury-buffer} operates on each frame's @code{buffer-list} parameter
779 as well as the frame-independent Emacs buffer list; therefore, the
780 buffer that you bury will come last in the value of @code{(buffer-list
781 @var{frame})} and in the value of @code{(buffer-list nil)}.
783 If @var{buffer-or-name} is @code{nil} or omitted, this means to bury the
784 current buffer.  In addition, if the buffer is displayed in the selected
785 window, this switches to some other buffer (obtained using
786 @code{other-buffer}) in the selected window.  But if the buffer is
787 displayed in some other window, it remains displayed there.
789 To replace a buffer in all the windows that display it, use
790 @code{replace-buffer-in-windows}.  @xref{Buffers and Windows}.
791 @end deffn
793 @node Creating Buffers
794 @section Creating Buffers
795 @cindex creating buffers
796 @cindex buffers, creating
798   This section describes the two primitives for creating buffers.
799 @code{get-buffer-create} creates a buffer if it finds no existing buffer
800 with the specified name; @code{generate-new-buffer} always creates a new
801 buffer and gives it a unique name.
803   Other functions you can use to create buffers include
804 @code{with-output-to-temp-buffer} (@pxref{Temporary Displays}) and
805 @code{create-file-buffer} (@pxref{Visiting Files}).  Starting a
806 subprocess can also create a buffer (@pxref{Processes}).
808 @defun get-buffer-create name
809 This function returns a buffer named @var{name}.  It returns an existing
810 buffer with that name, if one exists; otherwise, it creates a new
811 buffer.  The buffer does not become the current buffer---this function
812 does not change which buffer is current.
814 An error is signaled if @var{name} is not a string.
816 @example
817 @group
818 (get-buffer-create "foo")
819      @result{} #<buffer foo>
820 @end group
821 @end example
823 The major mode for the new buffer is set to Fundamental mode.  The
824 variable @code{default-major-mode} is handled at a higher level.
825 @xref{Auto Major Mode}.
826 @end defun
828 @defun generate-new-buffer name
829 This function returns a newly created, empty buffer, but does not make
830 it current.  If there is no buffer named @var{name}, then that is the
831 name of the new buffer.  If that name is in use, this function adds
832 suffixes of the form @samp{<@var{n}>} to @var{name}, where @var{n} is an
833 integer.  It tries successive integers starting with 2 until it finds an
834 available name.
836 An error is signaled if @var{name} is not a string.
838 @example
839 @group
840 (generate-new-buffer "bar")
841      @result{} #<buffer bar>
842 @end group
843 @group
844 (generate-new-buffer "bar")
845      @result{} #<buffer bar<2>>
846 @end group
847 @group
848 (generate-new-buffer "bar")
849      @result{} #<buffer bar<3>>
850 @end group
851 @end example
853 The major mode for the new buffer is set to Fundamental mode.  The
854 variable @code{default-major-mode} is handled at a higher level.
855 @xref{Auto Major Mode}.
857 See the related function @code{generate-new-buffer-name} in @ref{Buffer
858 Names}.
859 @end defun
861 @node Killing Buffers
862 @section Killing Buffers
863 @cindex killing buffers
864 @cindex buffers, killing
866   @dfn{Killing a buffer} makes its name unknown to Emacs and makes its
867 text space available for other use.
869   The buffer object for the buffer that has been killed remains in
870 existence as long as anything refers to it, but it is specially marked
871 so that you cannot make it current or display it.  Killed buffers retain
872 their identity, however; if you kill two distinct buffers, they remain
873 distinct according to @code{eq} although both are dead.
875   If you kill a buffer that is current or displayed in a window, Emacs
876 automatically selects or displays some other buffer instead.  This means
877 that killing a buffer can in general change the current buffer.
878 Therefore, when you kill a buffer, you should also take the precautions
879 associated with changing the current buffer (unless you happen to know
880 that the buffer being killed isn't current).  @xref{Current Buffer}.
882   If you kill a buffer that is the base buffer of one or more indirect
883 buffers, the indirect buffers are automatically killed as well.
885   The @code{buffer-name} of a killed buffer is @code{nil}.  You can use
886 this feature to test whether a buffer has been killed:
888 @example
889 @group
890 (defun buffer-killed-p (buffer)
891   "Return t if BUFFER is killed."
892   (not (buffer-name buffer)))
893 @end group
894 @end example
896 @deffn Command kill-buffer buffer-or-name
897 This function kills the buffer @var{buffer-or-name}, freeing all its
898 memory for other uses or to be returned to the operating system.  It
899 returns @code{nil}.
901 Any processes that have this buffer as the @code{process-buffer} are
902 sent the @code{SIGHUP} signal, which normally causes them to terminate.
903 (The basic meaning of @code{SIGHUP} is that a dialup line has been
904 disconnected.)  @xref{Signals to Processes}.
906 If the buffer is visiting a file and contains unsaved changes,
907 @code{kill-buffer} asks the user to confirm before the buffer is killed.
908 It does this even if not called interactively.  To prevent the request
909 for confirmation, clear the modified flag before calling
910 @code{kill-buffer}.  @xref{Buffer Modification}.
912 Killing a buffer that is already dead has no effect.
914 @smallexample
915 (kill-buffer "foo.unchanged")
916      @result{} nil
917 (kill-buffer "foo.changed")
919 ---------- Buffer: Minibuffer ----------
920 Buffer foo.changed modified; kill anyway? (yes or no) @kbd{yes}
921 ---------- Buffer: Minibuffer ----------
923      @result{} nil
924 @end smallexample
925 @end deffn
927 @defvar kill-buffer-query-functions
928 After confirming unsaved changes, @code{kill-buffer} calls the functions
929 in the list @code{kill-buffer-query-functions}, in order of appearance,
930 with no arguments.  The buffer being killed is the current buffer when
931 they are called.  The idea of this feature is that these functions will
932 ask for confirmation from the user.  If any of them returns @code{nil},
933 @code{kill-buffer} spares the buffer's life.
934 @end defvar
936 @defvar kill-buffer-hook
937 This is a normal hook run by @code{kill-buffer} after asking all the
938 questions it is going to ask, just before actually killing the buffer.
939 The buffer to be killed is current when the hook functions run.
940 @xref{Hooks}.
941 @end defvar
943 @defvar buffer-offer-save
944 This variable, if non-@code{nil} in a particular buffer, tells
945 @code{save-buffers-kill-emacs} and @code{save-some-buffers} to offer to
946 save that buffer, just as they offer to save file-visiting buffers.  The
947 variable @code{buffer-offer-save} automatically becomes buffer-local
948 when set for any reason.  @xref{Buffer-Local Variables}.
949 @end defvar
951 @node Indirect Buffers
952 @section Indirect Buffers
953 @cindex indirect buffers
954 @cindex base buffer
956   An @dfn{indirect buffer} shares the text of some other buffer, which
957 is called the @dfn{base buffer} of the indirect buffer.  In some ways it
958 is the analogue, for buffers, of a symbolic link among files.  The base
959 buffer may not itself be an indirect buffer.
961   The text of the indirect buffer is always identical to the text of its
962 base buffer; changes made by editing either one are visible immediately
963 in the other.  This includes the text properties as well as the characters
964 themselves.
966   In all other respects, the indirect buffer and its base buffer are
967 completely separate.  They have different names, different values of
968 point, different narrowing, different markers and overlays (though
969 inserting or deleting text in either buffer relocates the markers and
970 overlays for both), different major modes, and different buffer-local
971 variables.
973   An indirect buffer cannot visit a file, but its base buffer can.  If
974 you try to save the indirect buffer, that actually saves the base
975 buffer.
977   Killing an indirect buffer has no effect on its base buffer.  Killing
978 the base buffer effectively kills the indirect buffer in that it cannot
979 ever again be the current buffer.
981 @deffn Command make-indirect-buffer base-buffer name
982 This creates an indirect buffer named @var{name} whose base buffer
983 is @var{base-buffer}.  The argument @var{base-buffer} may be a buffer
984 or a string.
986 If @var{base-buffer} is an indirect buffer, its base buffer is used as
987 the base for the new buffer.
988 @end deffn
990 @defun buffer-base-buffer buffer
991 This function returns the base buffer of @var{buffer}.  If @var{buffer}
992 is not indirect, the value is @code{nil}.  Otherwise, the value is
993 another buffer, which is never an indirect buffer.
994 @end defun
996 @node Buffer Gap
997 @section The Buffer Gap
999   Emacs buffers are implemented using an invisible @dfn{gap} to make
1000 insertion and deletion faster.  Insertion works by filling in part of
1001 the gap, and deletion adds to the gap.  Of course, this means that the
1002 gap must first be moved to the locus of the insertion or deletion.
1003 Emacs moves the gap only when you try to insert or delete.  This is why
1004 your first editing command in one part of a large buffer, after
1005 previously editing in another far-away part, sometimes involves a
1006 noticeable delay.
1008   This mechanism works invisibly, and Lisp code should never be affected
1009 by the gap's current location, but these functions are available for
1010 getting information about the gap status.
1012 @defun gap-position
1013 This function returns the current gap position in the current buffer.
1014 @end defun
1016 @defun gap-size
1017 This function returns the current gap size of the current buffer.
1018 @end defun