2 @c This is part of the SXEmacs Lisp Reference Manual.
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc.
4 @c Copyright (C) 2005 Sebastian Freundt <hroptatyr@sxemacs.org>
5 @c See the file lispref.texi for copying conditions.
6 @setfilename ../../info/buffers.info
8 @node Buffers, Windows, Backups and Auto-Saving, Top
12 A @dfn{buffer} is a Lisp object containing text to be edited. Buffers
13 are used to hold the contents of files that are being visited; there may
14 also be buffers that are not visiting files. While several buffers may
15 exist at one time, exactly one buffer is designated the @dfn{current
16 buffer} at any time. Most editing commands act on the contents of the
17 current buffer. Each buffer, including the current buffer, may or may
18 not be displayed in any window.
21 * Buffer Basics:: What is a buffer?
22 * Current Buffer:: Designating a buffer as current
23 so primitives will access its contents.
24 * Buffer Names:: Accessing and changing buffer names.
25 * Buffer File Name:: The buffer file name indicates which file is visited.
26 * Buffer Modification:: A buffer is @dfn{modified} if it needs to be saved.
27 * Modification Time:: Determining whether the visited file was changed
28 ``behind SXEmacs's back''.
29 * Read Only Buffers:: Modifying text is not allowed in a read-only buffer.
30 * The Buffer List:: How to look at all the existing buffers.
31 * Creating Buffers:: Functions that create buffers.
32 * Killing Buffers:: Buffers exist until explicitly killed.
33 * Indirect Buffers:: An indirect buffer shares text with some other buffer.
38 @section Buffer Basics
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. While several buffers may
44 exist at one time, exactly 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.
50 Buffers in SXEmacs editing are objects that have distinct names and
51 hold text that can be edited. Buffers appear to Lisp programs as a
52 special data type. You can think of the contents of a buffer as an
53 extendible string; insertions and deletions may occur in any part of the
57 A Lisp buffer object contains numerous pieces of information. Some of
58 this information is directly accessible to the programmer through
59 variables, while other information is accessible only through
60 special-purpose functions. For example, the visited file name is
61 directly accessible through a variable, while the value of point is
62 accessible only through a primitive function.
64 Buffer-specific information that is directly accessible is stored in
65 @dfn{buffer-local} variable bindings, which are variable values that are
66 effective only in a particular buffer. This feature allows each buffer
67 to override the values of certain variables. Most major modes override
68 variables such as @code{fill-column} or @code{comment-column} in this
69 way. For more information about buffer-local variables and functions
70 related to them, see @ref{Buffer-Local Variables}.
72 For functions and variables related to visiting files in buffers, see
73 @ref{Visiting Files} and @ref{Saving Buffers}. For functions and
74 variables related to the display of buffers in windows, see
75 @ref{Buffers and Windows}.
78 This function returns @code{t} if @var{object} is a buffer,
83 @section The Current Buffer
84 @cindex selecting a buffer
85 @cindex changing to another buffer
86 @cindex current buffer
88 There are, in general, many buffers in a SXEmacs session. At any time,
89 one of them is designated as the @dfn{current buffer}. This is the
90 buffer in which most editing takes place, because most of the primitives
91 for examining or changing text in a buffer operate implicitly on the
92 current buffer (@pxref{Text}).
94 If you span your SXEmacs session on multiple displays it may happen
95 that you appear to have more than one current buffer, but it remains one
96 current buffer per display. Spanning SXEmacs in this sense also spans
97 a scope where some (probably many) buffers are non-current and one among
98 them is current in this scope.
100 Normally the buffer that is displayed on the screen in the selected
101 window is the current buffer, but this is not always so: a Lisp program
102 can designate any buffer as current temporarily in order to operate on
103 its contents, without changing what is displayed on the screen.
105 The way to designate a current buffer in a Lisp program is by calling
106 @code{set-buffer}. The specified buffer remains current until a new one
109 When an editing command returns to the editor command loop, the
110 command loop designates the buffer displayed in the selected window as
111 current, to prevent confusion: the buffer that the cursor is in when
112 Emacs reads a command is the buffer that the command will apply to.
113 (@xref{Command Loop}.) Therefore, @code{set-buffer} is not the way to
114 switch visibly to a different buffer so that the user can edit it. For
115 this, you must use the functions described in @ref{Displaying Buffers}.
117 However, Lisp functions that change to a different current buffer
118 should not depend on the command loop to set it back afterwards.
119 Editing commands written in SXEmacs Lisp can be called from other
120 programs as well as from the command loop. It is convenient for the
121 caller if the subroutine does not change which buffer is current
122 (unless, of course, that is the subroutine's purpose). Therefore, you
123 should normally use @code{set-buffer} within a @code{save-excursion}
124 that will restore the current buffer when your function is done
125 (@pxref{Excursions}). Here is an example, the code for the command
126 @code{append-to-buffer} (with the documentation string abridged):
130 (defun append-to-buffer (buffer start end)
131 "Append to specified buffer the text of the region.
133 (interactive "BAppend to buffer: \nr")
134 (let ((oldbuf (current-buffer)))
136 (set-buffer (get-buffer-create buffer))
137 (insert-buffer-substring oldbuf start end))))
142 This function binds a local variable to the current buffer, and then
143 @code{save-excursion} records the values of point, the mark, and the
144 original buffer. Next, @code{set-buffer} makes another buffer current.
145 Finally, @code{insert-buffer-substring} copies the string from the
146 original current buffer to the new current buffer.
148 If the buffer appended to happens to be displayed in some window,
149 the next redisplay will show how its text has changed. Otherwise, you
150 will not see the change immediately on the screen. The buffer becomes
151 current temporarily during the execution of the command, but this does
152 not cause it to be displayed.
154 If you make local bindings (with @code{let} or function arguments) for
155 a variable that may also have buffer-local bindings, make sure that the
156 same buffer is current at the beginning and at the end of the local
157 binding's scope. Otherwise you might bind it in one buffer and unbind
158 it in another! There are two ways to do this. In simple cases, you may
159 see that nothing ever changes the current buffer within the scope of the
160 binding. Otherwise, use @code{save-excursion} to make sure that the
161 buffer current at the beginning is current again whenever the variable
164 It is not reliable to change the current buffer back with
165 @code{set-buffer}, because that won't do the job if a quit happens while
166 the wrong buffer is current. Here is what @emph{not} to do:
170 (let (buffer-read-only
171 (obuf (current-buffer)))
179 Using @code{save-excursion}, as shown below, handles quitting, errors,
180 and @code{throw}, as well as ordinary evaluation.
184 (let (buffer-read-only)
191 @defun current-buffer
192 This function returns the current buffer.
197 @result{} #<buffer buffers.texi>
202 @defun set-buffer buffer-or-name
203 This function makes @var{buffer-or-name} the current buffer. It does
204 not display the buffer in the currently selected window or in any other
205 window, so the user cannot necessarily see the buffer. But Lisp
206 programs can in any case work on it.
208 @var{buffer-or-name} must be a buffer or the name of an existing
209 buffer--else an error is signaled. This function returns the buffer
210 identified by @var{buffer-or-name}.
215 @section Buffer Names
218 Each buffer has a unique name, which is a string. Many of the
219 functions that work on buffers accept either a buffer or a buffer name
220 as an argument. Any argument called @var{buffer-or-name} is of this
221 sort, and an error is signaled if it is neither a string nor a buffer.
222 Any argument called @var{buffer} must be an actual buffer
225 Buffers that are ephemeral and generally uninteresting to the user
226 have names starting with a space, so that the @code{list-buffers} and
227 @code{buffer-menu} commands don't mention them. A name starting with
228 space also initially disables recording undo information; see
231 @defun buffer-name &optional buffer
232 This function returns the name of @var{buffer} as a string. If
233 @var{buffer} is not supplied, it defaults to the current buffer.
235 If @code{buffer-name} returns @code{nil}, it means that @var{buffer}
236 has been killed. @xref{Killing Buffers}.
241 @result{} "buffers.texi"
245 (setq foo (get-buffer "temp"))
246 @result{} #<buffer temp>
258 @result{} #<killed buffer>
263 @deffn Command rename-buffer newname &optional unique
264 This function renames the current buffer to @var{newname}. An error
265 is signaled if @var{newname} is not a string, or if there is already a
266 buffer with that name. The function returns @code{nil}.
269 Ordinarily, @code{rename-buffer} signals an error if @var{newname} is
270 already in use. However, if @var{unique} is non-@code{nil}, it modifies
271 @var{newname} to make a name that is not in use. Interactively, you can
272 make @var{unique} non-@code{nil} with a numeric prefix argument.
274 One application of this command is to rename the @samp{*shell*} buffer
275 to some other name, thus making it possible to create a second shell
276 buffer under the name @samp{*shell*}.
279 @defun get-buffer buffer-or-name
280 This function returns the buffer named @var{buffer-or-name}. If
281 @var{buffer-or-name} is a string and there is no buffer with that name,
282 the value is @code{nil}. If @var{buffer-or-name} is actually a buffer,
283 it is returned as given. (That is not very useful, so the argument is
284 usually a name.) For example:
288 (setq b (get-buffer "lewis"))
289 @result{} #<buffer lewis>
293 @result{} #<buffer lewis>
296 (get-buffer "Frazzle-nots")
301 See also the function @code{get-buffer-create} in @ref{Creating Buffers}.
304 @defun generate-new-buffer-name starting-name &optional ignore
305 This function returns a name that would be unique for a new buffer---but
306 does not create the buffer. It starts with @var{starting-name}, and
307 produces a name not currently in use for any buffer by appending a
308 number inside of @samp{<@dots{}>}.
310 If @var{ignore} is given, it specifies a name that is okay to use (if it
311 is in the sequence to be tried), even if a buffer with that name exists.
313 See the related function @code{generate-new-buffer} in @ref{Creating
318 @node Buffer File Name
319 @section Buffer File Name
321 @cindex buffer file name
322 @cindex file name of buffer
324 The @dfn{buffer file name} is the name of the file that is visited in
325 that buffer. When a buffer is not visiting a file, its buffer file name
326 is @code{nil}. Most of the time, the buffer name is the same as the
327 nondirectory part of the buffer file name, but the buffer file name and
328 the buffer name are distinct and can be set independently.
329 @xref{Visiting Files}.
331 @defun buffer-file-name &optional buffer
332 This function returns the absolute file name of the file that
333 @var{buffer} is visiting. If @var{buffer} is not visiting any file,
334 @code{buffer-file-name} returns @code{nil}. If @var{buffer} is not
335 supplied, it defaults to the current buffer.
339 (buffer-file-name (other-buffer))
340 @result{} "/usr/user/lewis/manual/files.texi"
345 @defvar buffer-file-name
346 This buffer-local variable contains the name of the file being visited
347 in the current buffer, or @code{nil} if it is not visiting a file. It
348 is a permanent local, unaffected by @code{kill-local-variables}.
353 @result{} "/usr/user/lewis/manual/buffers.texi"
357 It is risky to change this variable's value without doing various other
358 things. See the definition of @code{set-visited-file-name} in
359 @file{files.el}; some of the things done there, such as changing the
360 buffer name, are not strictly necessary, but others are essential to
361 avoid confusing SXEmacs.
364 @defvar buffer-file-truename
365 This buffer-local variable holds the truename of the file visited in the
366 current buffer, or @code{nil} if no file is visited. It is a permanent
367 local, unaffected by @code{kill-local-variables}. @xref{Truenames}.
370 @defvar buffer-file-number
371 This buffer-local variable holds the file number and directory device
372 number of the file visited in the current buffer, or @code{nil} if no
373 file or a nonexistent file is visited. It is a permanent local,
374 unaffected by @code{kill-local-variables}. @xref{Truenames}.
376 The value is normally a list of the form @code{(@var{filenum}
377 @var{devnum})}. This pair of numbers uniquely identifies the file among
378 all files accessible on the system. See the function
379 @code{file-attributes}, in @ref{File Attributes}, for more information
383 @defun get-file-buffer filename
384 This function returns the buffer visiting file @var{filename}. If
385 there is no such buffer, it returns @code{nil}. The argument
386 @var{filename}, which must be a string, is expanded (@pxref{File Name
387 Expansion}), then compared against the visited file names of all live
392 (get-file-buffer "buffers.texi")
393 @result{} #<buffer buffers.texi>
397 In unusual circumstances, there can be more than one buffer visiting
398 the same file name. In such cases, this function returns the first
399 such buffer in the buffer list.
402 @deffn Command set-visited-file-name filename
403 If @var{filename} is a non-empty string, this function changes the
404 name of the file visited in current buffer to @var{filename}. (If the
405 buffer had no visited file, this gives it one.) The @emph{next time}
406 the buffer is saved it will go in the newly-specified file. This
407 command marks the buffer as modified, since it does not (as far as
408 SXEmacs knows) match the contents of @var{filename}, even if it matched
409 the former visited file.
411 If @var{filename} is @code{nil} or the empty string, that stands for
412 ``no visited file''. In this case, @code{set-visited-file-name} marks
413 the buffer as having no visited file.
415 @c Wordy to avoid overfull hbox. --rjc 16mar92
416 When the function @code{set-visited-file-name} is called interactively,
417 it prompts for @var{filename} in the minibuffer.
419 See also @code{clear-visited-file-modtime} and
420 @code{verify-visited-file-modtime} in @ref{Buffer Modification}.
423 @defvar list-buffers-directory
424 This buffer-local variable records a string to display in a buffer
425 listing in place of the visited file name, for buffers that don't have a
426 visited file name. Dired buffers use this variable.
430 @node Buffer Modification
431 @section Buffer Modification
432 @cindex buffer modification
433 @cindex modification flag (of buffer)
435 SXEmacs keeps a flag called the @dfn{modified flag} for each buffer, to
436 record whether you have changed the text of the buffer. This flag is
437 set to @code{t} whenever you alter the contents of the buffer, and
438 cleared to @code{nil} when you save it. Thus, the flag shows whether
439 there are unsaved changes. The flag value is normally shown in the
440 modeline (@pxref{Modeline Variables}), and controls saving
441 (@pxref{Saving Buffers}) and auto-saving (@pxref{Auto-Saving}).
443 Some Lisp programs set the flag explicitly. For example, the function
444 @code{set-visited-file-name} sets the flag to @code{t}, because the text
445 does not match the newly-visited file, even if it is unchanged from the