Commit | Line | Data |
---|---|---|
b8d4c8d0 GM |
1 | @c -*-texinfo-*- |
2 | @c This is part of the GNU Emacs Lisp Reference Manual. | |
acaf905b | 3 | @c Copyright (C) 1990-1995, 1998-1999, 2001-2012 |
e9bffc61 | 4 | @c Free Software Foundation, Inc. |
b8d4c8d0 | 5 | @c See the file elisp.texi for copying conditions. |
ecc6530d | 6 | @node Buffers |
b8d4c8d0 GM |
7 | @chapter Buffers |
8 | @cindex buffer | |
9 | ||
10 | A @dfn{buffer} is a Lisp object containing text to be edited. Buffers | |
11 | are used to hold the contents of files that are being visited; there may | |
12 | also be buffers that are not visiting files. While several buffers may | |
13 | exist at one time, only one buffer is designated the @dfn{current | |
14 | buffer} at any time. Most editing commands act on the contents of the | |
15 | current buffer. Each buffer, including the current buffer, may or may | |
16 | not be displayed in any windows. | |
17 | ||
18 | @menu | |
19 | * Buffer Basics:: What is a buffer? | |
20 | * Current Buffer:: Designating a buffer as current | |
21 | so that primitives will access its contents. | |
22 | * Buffer Names:: Accessing and changing buffer names. | |
23 | * Buffer File Name:: The buffer file name indicates which file is visited. | |
24 | * Buffer Modification:: A buffer is @dfn{modified} if it needs to be saved. | |
25 | * Modification Time:: Determining whether the visited file was changed | |
cf988578 | 26 | "behind Emacs's back". |
b8d4c8d0 GM |
27 | * Read Only Buffers:: Modifying text is not allowed in a read-only buffer. |
28 | * The Buffer List:: How to look at all the existing buffers. | |
29 | * Creating Buffers:: Functions that create buffers. | |
30 | * Killing Buffers:: Buffers exist until explicitly killed. | |
31 | * Indirect Buffers:: An indirect buffer shares text with some other buffer. | |
2aaaf0dd | 32 | * Swapping Text:: Swapping text between two buffers. |
b8d4c8d0 GM |
33 | * Buffer Gap:: The gap in the buffer. |
34 | @end menu | |
35 | ||
36 | @node Buffer Basics | |
b8d4c8d0 GM |
37 | @section Buffer Basics |
38 | ||
39 | @ifnottex | |
40 | A @dfn{buffer} is a Lisp object containing text to be edited. Buffers | |
41 | are used to hold the contents of files that are being visited; there may | |
42 | also be buffers that are not visiting files. Although several buffers | |
43 | normally exist, only one buffer is designated the @dfn{current | |
44 | buffer} at any time. Most editing commands act on the contents of the | |
45 | current buffer. Each buffer, including the current buffer, may or may | |
46 | not be displayed in any windows. | |
47 | @end ifnottex | |
48 | ||
49 | Buffers in Emacs editing are objects that have distinct names and hold | |
50 | text that can be edited. Buffers appear to Lisp programs as a special | |
51 | data type. You can think of the contents of a buffer as a string that | |
52 | you can extend; insertions and deletions may occur in any part of the | |
53 | buffer. @xref{Text}. | |
54 | ||
55 | A Lisp buffer object contains numerous pieces of information. Some of | |
56 | this information is directly accessible to the programmer through | |
57 | variables, while other information is accessible only through | |
58 | special-purpose functions. For example, the visited file name is | |
59 | directly accessible through a variable, while the value of point is | |
60 | accessible only through a primitive function. | |
61 | ||
62 | Buffer-specific information that is directly accessible is stored in | |
63 | @dfn{buffer-local} variable bindings, which are variable values that are | |
64 | effective only in a particular buffer. This feature allows each buffer | |
65 | to override the values of certain variables. Most major modes override | |
66 | variables such as @code{fill-column} or @code{comment-column} in this | |
67 | way. For more information about buffer-local variables and functions | |
68 | related to them, see @ref{Buffer-Local Variables}. | |
69 | ||
70 | For functions and variables related to visiting files in buffers, see | |
71 | @ref{Visiting Files} and @ref{Saving Buffers}. For functions and | |
72 | variables related to the display of buffers in windows, see | |
73 | @ref{Buffers and Windows}. | |
74 | ||
75 | @defun bufferp object | |
76 | This function returns @code{t} if @var{object} is a buffer, | |
77 | @code{nil} otherwise. | |
78 | @end defun | |
79 | ||
80 | @node Current Buffer | |
81 | @section The Current Buffer | |
82 | @cindex selecting a buffer | |
83 | @cindex changing to another buffer | |
84 | @cindex current buffer | |
85 | ||
c1bcd0d5 CY |
86 | There are, in general, many buffers in an Emacs session. At any |
87 | time, one of them is designated the @dfn{current buffer}---the buffer | |
88 | in which most editing takes place. Most of the primitives for | |
89 | examining or changing text operate implicitly on the current buffer | |
90 | (@pxref{Text}). | |
91 | ||
92 | Normally, the buffer displayed in the selected window is the current | |
93 | buffer, but this is not always so: a Lisp program can temporarily | |
94 | designate any buffer as current in order to operate on its contents, | |
95 | without changing what is displayed on the screen. The most basic | |
96 | function for designating a current buffer is @code{set-buffer}. | |
97 | ||
98 | @defun current-buffer | |
99 | This function returns the current buffer. | |
100 | ||
101 | @example | |
102 | @group | |
103 | (current-buffer) | |
104 | @result{} #<buffer buffers.texi> | |
105 | @end group | |
106 | @end example | |
107 | @end defun | |
108 | ||
109 | @defun set-buffer buffer-or-name | |
110 | This function makes @var{buffer-or-name} the current buffer. | |
111 | @var{buffer-or-name} must be an existing buffer or the name of an | |
112 | existing buffer. The return value is the buffer made current. | |
113 | ||
114 | This function does not display the buffer in any window, so the user | |
115 | cannot necessarily see the buffer. But Lisp programs will now operate | |
116 | on it. | |
117 | @end defun | |
118 | ||
119 | When an editing command returns to the editor command loop, Emacs | |
120 | automatically calls @code{set-buffer} on the buffer shown in the | |
121 | selected window. This is to prevent confusion: it ensures that the | |
122 | buffer that the cursor is in, when Emacs reads a command, is the | |
123 | buffer to which that command applies (@pxref{Command Loop}). Thus, | |
124 | you should not use @code{set-buffer} to switch visibly to a different | |
0e406a72 | 125 | buffer; for that, use the functions described in @ref{Switching |
c1bcd0d5 CY |
126 | Buffers}. |
127 | ||
128 | When writing a Lisp function, do @emph{not} rely on this behavior of | |
129 | the command loop to restore the current buffer after an operation. | |
130 | Editing commands can also be called as Lisp functions by other | |
131 | programs, not just from the command loop; it is convenient for the | |
132 | caller if the subroutine does not change which buffer is current | |
133 | (unless, of course, that is the subroutine's purpose). | |
134 | ||
135 | To operate temporarily on another buffer, put the @code{set-buffer} | |
136 | within a @code{save-current-buffer} form. Here, as an example, is a | |
9257072f | 137 | simplified version of the command @code{append-to-buffer}: |
b8d4c8d0 GM |
138 | |
139 | @example | |
140 | @group | |
141 | (defun append-to-buffer (buffer start end) | |
c1bcd0d5 | 142 | "Append the text of the region to BUFFER." |
b8d4c8d0 GM |
143 | (interactive "BAppend to buffer: \nr") |
144 | (let ((oldbuf (current-buffer))) | |
145 | (save-current-buffer | |
146 | (set-buffer (get-buffer-create buffer)) | |
147 | (insert-buffer-substring oldbuf start end)))) | |
148 | @end group | |
149 | @end example | |
150 | ||
151 | @noindent | |
c1bcd0d5 CY |
152 | Here, we bind a local variable to record the current buffer, and then |
153 | @code{save-current-buffer} arranges to make it current again later. | |
154 | Next, @code{set-buffer} makes the specified buffer current, and | |
b8d4c8d0 | 155 | @code{insert-buffer-substring} copies the string from the original |
c1bcd0d5 CY |
156 | buffer to the specified (and now current) buffer. |
157 | ||
158 | Alternatively, we can use the @code{with-current-buffer} macro: | |
159 | ||
160 | @example | |
161 | @group | |
162 | (defun append-to-buffer (buffer start end) | |
163 | "Append the text of the region to BUFFER." | |
164 | (interactive "BAppend to buffer: \nr") | |
165 | (let ((oldbuf (current-buffer))) | |
166 | (with-current-buffer (get-buffer-create buffer) | |
167 | (insert-buffer-substring oldbuf start end)))) | |
168 | @end group | |
169 | @end example | |
170 | ||
171 | In either case, if the buffer appended to happens to be displayed in | |
172 | some window, the next redisplay will show how its text has changed. | |
173 | If it is not displayed in any window, you will not see the change | |
174 | immediately on the screen. The command causes the buffer to become | |
175 | current temporarily, but does not cause it to be displayed. | |
176 | ||
177 | If you make local bindings (with @code{let} or function arguments) | |
178 | for a variable that may also have buffer-local bindings, make sure | |
179 | that the same buffer is current at the beginning and at the end of the | |
180 | local binding's scope. Otherwise you might bind it in one buffer and | |
181 | unbind it in another! | |
b8d4c8d0 GM |
182 | |
183 | Do not rely on using @code{set-buffer} to change the current buffer | |
184 | back, because that won't do the job if a quit happens while the wrong | |
9257072f CY |
185 | buffer is current. For instance, in the previous example, it would |
186 | have been wrong to do this: | |
b8d4c8d0 GM |
187 | |
188 | @example | |
189 | @group | |
9257072f CY |
190 | (let ((oldbuf (current-buffer))) |
191 | (set-buffer (get-buffer-create buffer)) | |
192 | (insert-buffer-substring oldbuf start end) | |
193 | (set-buffer oldbuf)) | |
b8d4c8d0 GM |
194 | @end group |
195 | @end example | |
196 | ||
197 | @noindent | |
c1bcd0d5 CY |
198 | Using @code{save-current-buffer} or @code{with-current-buffer}, as we |
199 | did, correctly handles quitting, errors, and @code{throw}, as well as | |
200 | ordinary evaluation. | |
b8d4c8d0 GM |
201 | |
202 | @defspec save-current-buffer body@dots{} | |
203 | The @code{save-current-buffer} special form saves the identity of the | |
204 | current buffer, evaluates the @var{body} forms, and finally restores | |
205 | that buffer as current. The return value is the value of the last | |
206 | form in @var{body}. The current buffer is restored even in case of an | |
207 | abnormal exit via @code{throw} or error (@pxref{Nonlocal Exits}). | |
208 | ||
209 | If the buffer that used to be current has been killed by the time of | |
210 | exit from @code{save-current-buffer}, then it is not made current again, | |
211 | of course. Instead, whichever buffer was current just before exit | |
212 | remains current. | |
213 | @end defspec | |
214 | ||
215 | @defmac with-current-buffer buffer-or-name body@dots{} | |
216 | The @code{with-current-buffer} macro saves the identity of the current | |
217 | buffer, makes @var{buffer-or-name} current, evaluates the @var{body} | |
09460d9a MR |
218 | forms, and finally restores the current buffer. @var{buffer-or-name} |
219 | must specify an existing buffer or the name of an existing buffer. | |
b8d4c8d0 | 220 | |
09460d9a MR |
221 | The return value is the value of the last form in @var{body}. The |
222 | current buffer is restored even in case of an abnormal exit via | |
223 | @code{throw} or error (@pxref{Nonlocal Exits}). | |
b8d4c8d0 GM |
224 | @end defmac |
225 | ||
226 | @defmac with-temp-buffer body@dots{} | |
227 | @anchor{Definition of with-temp-buffer} | |
228 | The @code{with-temp-buffer} macro evaluates the @var{body} forms | |
229 | with a temporary buffer as the current buffer. It saves the identity of | |
230 | the current buffer, creates a temporary buffer and makes it current, | |
231 | evaluates the @var{body} forms, and finally restores the previous | |
232 | current buffer while killing the temporary buffer. By default, undo | |
233 | information (@pxref{Undo}) is not recorded in the buffer created by | |
234 | this macro (but @var{body} can enable that, if needed). | |
235 | ||
236 | The return value is the value of the last form in @var{body}. You can | |
237 | return the contents of the temporary buffer by using | |
238 | @code{(buffer-string)} as the last form. | |
239 | ||
240 | The current buffer is restored even in case of an abnormal exit via | |
241 | @code{throw} or error (@pxref{Nonlocal Exits}). | |
242 | ||
243 | See also @code{with-temp-file} in @ref{Definition of with-temp-file,, | |
244 | Writing to Files}. | |
245 | @end defmac | |
246 | ||
247 | @node Buffer Names | |
248 | @section Buffer Names | |
249 | @cindex buffer names | |
250 | ||
251 | Each buffer has a unique name, which is a string. Many of the | |
252 | functions that work on buffers accept either a buffer or a buffer name | |
253 | as an argument. Any argument called @var{buffer-or-name} is of this | |
254 | sort, and an error is signaled if it is neither a string nor a buffer. | |
255 | Any argument called @var{buffer} must be an actual buffer | |
256 | object, not a name. | |
257 | ||
258 | @cindex hidden buffers | |
259 | @cindex buffers without undo information | |
260 | Buffers that are ephemeral and generally uninteresting to the user | |
261 | have names starting with a space, so that the @code{list-buffers} and | |
262 | @code{buffer-menu} commands don't mention them (but if such a buffer | |
263 | visits a file, it @strong{is} mentioned). A name starting with | |
264 | space also initially disables recording undo information; see | |
265 | @ref{Undo}. | |
266 | ||
267 | @defun buffer-name &optional buffer | |
4d48fcdc MR |
268 | This function returns the name of @var{buffer} as a string. |
269 | @var{buffer} defaults to the current buffer. | |
b8d4c8d0 GM |
270 | |
271 | If @code{buffer-name} returns @code{nil}, it means that @var{buffer} | |
272 | has been killed. @xref{Killing Buffers}. | |
273 | ||
274 | @example | |
275 | @group | |
276 | (buffer-name) | |
277 | @result{} "buffers.texi" | |
278 | @end group | |
279 | ||
280 | @group | |
281 | (setq foo (get-buffer "temp")) | |
282 | @result{} #<buffer temp> | |
283 | @end group | |
284 | @group | |
285 | (kill-buffer foo) | |
286 | @result{} nil | |
287 | @end group | |
288 | @group | |
289 | (buffer-name foo) | |
290 | @result{} nil | |
291 | @end group | |
292 | @group | |
293 | foo | |
294 | @result{} #<killed buffer> | |
295 | @end group | |
296 | @end example | |
297 | @end defun | |
298 | ||
299 | @deffn Command rename-buffer newname &optional unique | |
300 | This function renames the current buffer to @var{newname}. An error | |
301 | is signaled if @var{newname} is not a string. | |
302 | ||
303 | @c Emacs 19 feature | |
304 | Ordinarily, @code{rename-buffer} signals an error if @var{newname} is | |
305 | already in use. However, if @var{unique} is non-@code{nil}, it modifies | |
306 | @var{newname} to make a name that is not in use. Interactively, you can | |
307 | make @var{unique} non-@code{nil} with a numeric prefix argument. | |
308 | (This is how the command @code{rename-uniquely} is implemented.) | |
309 | ||
310 | This function returns the name actually given to the buffer. | |
311 | @end deffn | |
312 | ||
313 | @defun get-buffer buffer-or-name | |
314 | This function returns the buffer specified by @var{buffer-or-name}. | |
315 | If @var{buffer-or-name} is a string and there is no buffer with that | |
316 | name, the value is @code{nil}. If @var{buffer-or-name} is a buffer, it | |
317 | is returned as given; that is not very useful, so the argument is usually | |
318 | a name. For example: | |
319 | ||
320 | @example | |
321 | @group | |
322 | (setq b (get-buffer "lewis")) | |
323 | @result{} #<buffer lewis> | |
324 | @end group | |
325 | @group | |
326 | (get-buffer b) | |
327 | @result{} #<buffer lewis> | |
328 | @end group | |
329 | @group | |
330 | (get-buffer "Frazzle-nots") | |
331 | @result{} nil | |
332 | @end group | |
333 | @end example | |
334 | ||
335 | See also the function @code{get-buffer-create} in @ref{Creating Buffers}. | |
336 | @end defun | |
337 | ||
338 | @c Emacs 19 feature | |
339 | @defun generate-new-buffer-name starting-name &optional ignore | |
340 | This function returns a name that would be unique for a new buffer---but | |
341 | does not create the buffer. It starts with @var{starting-name}, and | |
342 | produces a name not currently in use for any buffer by appending a | |
343 | number inside of @samp{<@dots{}>}. It starts at 2 and keeps | |
344 | incrementing the number until it is not the name of an existing buffer. | |
345 | ||
346 | If the optional second argument @var{ignore} is non-@code{nil}, it | |
347 | should be a string, a potential buffer name. It means to consider | |
348 | that potential buffer acceptable, if it is tried, even it is the name | |
349 | of an existing buffer (which would normally be rejected). Thus, if | |
350 | buffers named @samp{foo}, @samp{foo<2>}, @samp{foo<3>} and | |
351 | @samp{foo<4>} exist, | |
352 | ||
353 | @example | |
354 | (generate-new-buffer-name "foo") | |
355 | @result{} "foo<5>" | |
356 | (generate-new-buffer-name "foo" "foo<3>") | |
357 | @result{} "foo<3>" | |
358 | (generate-new-buffer-name "foo" "foo<6>") | |
359 | @result{} "foo<5>" | |
360 | @end example | |
361 | ||
362 | See the related function @code{generate-new-buffer} in @ref{Creating | |
363 | Buffers}. | |
364 | @end defun | |
365 | ||
366 | @node Buffer File Name | |
367 | @section Buffer File Name | |
368 | @cindex visited file | |
369 | @cindex buffer file name | |
370 | @cindex file name of buffer | |
371 | ||
372 | The @dfn{buffer file name} is the name of the file that is visited in | |
373 | that buffer. When a buffer is not visiting a file, its buffer file name | |
374 | is @code{nil}. Most of the time, the buffer name is the same as the | |
375 | nondirectory part of the buffer file name, but the buffer file name and | |
376 | the buffer name are distinct and can be set independently. | |
377 | @xref{Visiting Files}. | |
378 | ||
379 | @defun buffer-file-name &optional buffer | |
380 | This function returns the absolute file name of the file that | |
381 | @var{buffer} is visiting. If @var{buffer} is not visiting any file, | |
382 | @code{buffer-file-name} returns @code{nil}. If @var{buffer} is not | |
383 | supplied, it defaults to the current buffer. | |
384 | ||
385 | @example | |
386 | @group | |
387 | (buffer-file-name (other-buffer)) | |
388 | @result{} "/usr/user/lewis/manual/files.texi" | |
389 | @end group | |
390 | @end example | |
391 | @end defun | |
392 | ||
393 | @defvar buffer-file-name | |
394 | This buffer-local variable contains the name of the file being visited | |
395 | in the current buffer, or @code{nil} if it is not visiting a file. It | |
396 | is a permanent local variable, unaffected by | |
397 | @code{kill-all-local-variables}. | |
398 | ||
399 | @example | |
400 | @group | |
401 | buffer-file-name | |
402 | @result{} "/usr/user/lewis/manual/buffers.texi" | |
403 | @end group | |
404 | @end example | |
405 | ||
406 | It is risky to change this variable's value without doing various other | |
407 | things. Normally it is better to use @code{set-visited-file-name} (see | |
408 | below); some of the things done there, such as changing the buffer name, | |
409 | are not strictly necessary, but others are essential to avoid confusing | |
410 | Emacs. | |
411 | @end defvar | |
412 | ||
413 | @defvar buffer-file-truename | |
414 | This buffer-local variable holds the abbreviated truename of the file | |
415 | visited in the current buffer, or @code{nil} if no file is visited. | |
416 | It is a permanent local, unaffected by | |
417 | @code{kill-all-local-variables}. @xref{Truenames}, and | |
431ee44b | 418 | @ref{abbreviate-file-name}. |
b8d4c8d0 GM |
419 | @end defvar |
420 | ||
421 | @defvar buffer-file-number | |
422 | This buffer-local variable holds the file number and directory device | |
423 | number of the file visited in the current buffer, or @code{nil} if no | |
424 | file or a nonexistent file is visited. It is a permanent local, | |
425 | unaffected by @code{kill-all-local-variables}. | |
426 | ||
427 | The value is normally a list of the form @code{(@var{filenum} | |
428 | @var{devnum})}. This pair of numbers uniquely identifies the file among | |
429 | all files accessible on the system. See the function | |
430 | @code{file-attributes}, in @ref{File Attributes}, for more information | |
431 | about them. | |
432 | ||
433 | If @code{buffer-file-name} is the name of a symbolic link, then both | |
434 | numbers refer to the recursive target. | |
435 | @end defvar | |
436 | ||
437 | @defun get-file-buffer filename | |
438 | This function returns the buffer visiting file @var{filename}. If | |
439 | there is no such buffer, it returns @code{nil}. The argument | |
440 | @var{filename}, which must be a string, is expanded (@pxref{File Name | |
441 | Expansion}), then compared against the visited file names of all live | |
442 | buffers. Note that the buffer's @code{buffer-file-name} must match | |
443 | the expansion of @var{filename} exactly. This function will not | |
444 | recognize other names for the same file. | |
445 | ||
446 | @example | |
447 | @group | |
448 | (get-file-buffer "buffers.texi") | |
449 | @result{} #<buffer buffers.texi> | |
450 | @end group | |
451 | @end example | |
452 | ||
453 | In unusual circumstances, there can be more than one buffer visiting | |
454 | the same file name. In such cases, this function returns the first | |
455 | such buffer in the buffer list. | |
456 | @end defun | |
457 | ||
458 | @defun find-buffer-visiting filename &optional predicate | |
459 | This is like @code{get-file-buffer}, except that it can return any | |
460 | buffer visiting the file @emph{possibly under a different name}. That | |
461 | is, the buffer's @code{buffer-file-name} does not need to match the | |
462 | expansion of @var{filename} exactly, it only needs to refer to the | |
463 | same file. If @var{predicate} is non-@code{nil}, it should be a | |
464 | function of one argument, a buffer visiting @var{filename}. The | |
465 | buffer is only considered a suitable return value if @var{predicate} | |
466 | returns non-@code{nil}. If it can not find a suitable buffer to | |
467 | return, @code{find-buffer-visiting} returns @code{nil}. | |
468 | @end defun | |
469 | ||
470 | @deffn Command set-visited-file-name filename &optional no-query along-with-file | |
471 | If @var{filename} is a non-empty string, this function changes the | |
472 | name of the file visited in the current buffer to @var{filename}. (If the | |
473 | buffer had no visited file, this gives it one.) The @emph{next time} | |
474 | the buffer is saved it will go in the newly-specified file. | |
475 | ||
476 | This command marks the buffer as modified, since it does not (as far | |
477 | as Emacs knows) match the contents of @var{filename}, even if it | |
478 | matched the former visited file. It also renames the buffer to | |
479 | correspond to the new file name, unless the new name is already in | |
480 | use. | |
481 | ||
482 | If @var{filename} is @code{nil} or the empty string, that stands for | |
16152b76 | 483 | ``no visited file''. In this case, @code{set-visited-file-name} marks |
b8d4c8d0 GM |
484 | the buffer as having no visited file, without changing the buffer's |
485 | modified flag. | |
486 | ||
487 | Normally, this function asks the user for confirmation if there | |
488 | already is a buffer visiting @var{filename}. If @var{no-query} is | |
489 | non-@code{nil}, that prevents asking this question. If there already | |
490 | is a buffer visiting @var{filename}, and the user confirms or | |
491 | @var{query} is non-@code{nil}, this function makes the new buffer name | |
492 | unique by appending a number inside of @samp{<@dots{}>} to @var{filename}. | |
493 | ||
494 | If @var{along-with-file} is non-@code{nil}, that means to assume that | |
495 | the former visited file has been renamed to @var{filename}. In this | |
496 | case, the command does not change the buffer's modified flag, nor the | |
497 | buffer's recorded last file modification time as reported by | |
498 | @code{visited-file-modtime} (@pxref{Modification Time}). If | |
499 | @var{along-with-file} is @code{nil}, this function clears the recorded | |
500 | last file modification time, after which @code{visited-file-modtime} | |
501 | returns zero. | |
502 | ||
431ee44b CY |
503 | When the function @code{set-visited-file-name} is called |
504 | interactively, it prompts for @var{filename} in the minibuffer. | |
b8d4c8d0 GM |
505 | @end deffn |
506 | ||
507 | @defvar list-buffers-directory | |
508 | This buffer-local variable specifies a string to display in a buffer | |
509 | listing where the visited file name would go, for buffers that don't | |
510 | have a visited file name. Dired buffers use this variable. | |
511 | @end defvar | |
512 | ||
513 | @node Buffer Modification | |
514 | @section Buffer Modification | |
515 | @cindex buffer modification | |
516 | @cindex modification flag (of buffer) | |
517 | ||
518 | Emacs keeps a flag called the @dfn{modified flag} for each buffer, to | |
519 | record whether you have changed the text of the buffer. This flag is | |
520 | set to @code{t} whenever you alter the contents of the buffer, and | |
521 | cleared to @code{nil} when you save it. Thus, the flag shows whether | |
522 | there are unsaved changes. The flag value is normally shown in the mode | |
523 | line (@pxref{Mode Line Variables}), and controls saving (@pxref{Saving | |
524 | Buffers}) and auto-saving (@pxref{Auto-Saving}). | |
525 | ||
526 | Some Lisp programs set the flag explicitly. For example, the function | |
527 | @code{set-visited-file-name} sets the flag to @code{t}, because the text | |
528 | does not match the newly-visited file, even if it is unchanged from the | |
529 | file formerly visited. | |
530 | ||
531 | The functions that modify the contents of buffers are described in | |
532 | @ref{Text}. | |
533 | ||
534 | @defun buffer-modified-p &optional buffer | |
535 | This function returns @code{t} if the buffer @var{buffer} has been modified | |
536 | since it was last read in from a file or saved, or @code{nil} | |
537 | otherwise. If @var{buffer} is not supplied, the current buffer | |
538 | is tested. | |
539 | @end defun | |
540 | ||
541 | @defun set-buffer-modified-p flag | |
542 | This function marks the current buffer as modified if @var{flag} is | |
543 | non-@code{nil}, or as unmodified if the flag is @code{nil}. | |
544 | ||
545 | Another effect of calling this function is to cause unconditional | |
546 | redisplay of the mode line for the current buffer. In fact, the | |
547 | function @code{force-mode-line-update} works by doing this: | |
548 | ||
549 | @example | |
550 | @group | |
551 | (set-buffer-modified-p (buffer-modified-p)) | |
552 | @end group | |
553 | @end example | |
554 | @end defun | |
555 | ||
556 | @defun restore-buffer-modified-p flag | |
557 | Like @code{set-buffer-modified-p}, but does not force redisplay | |
558 | of mode lines. | |
559 | @end defun | |
560 | ||
561 | @deffn Command not-modified &optional arg | |
562 | This command marks the current buffer as unmodified, and not needing | |
563 | to be saved. If @var{arg} is non-@code{nil}, it marks the buffer as | |
564 | modified, so that it will be saved at the next suitable occasion. | |
565 | Interactively, @var{arg} is the prefix argument. | |
566 | ||
567 | Don't use this function in programs, since it prints a message in the | |
568 | echo area; use @code{set-buffer-modified-p} (above) instead. | |
569 | @end deffn | |
570 | ||
571 | @defun buffer-modified-tick &optional buffer | |
572 | This function returns @var{buffer}'s modification-count. This is a | |
573 | counter that increments every time the buffer is modified. If | |
574 | @var{buffer} is @code{nil} (or omitted), the current buffer is used. | |
575 | The counter can wrap around occasionally. | |
576 | @end defun | |
577 | ||
578 | @defun buffer-chars-modified-tick &optional buffer | |
579 | This function returns @var{buffer}'s character-change modification-count. | |
580 | Changes to text properties leave this counter unchanged; however, each | |
581 | time text is inserted or removed from the buffer, the counter is reset | |
569382c2 | 582 | to the value that would be returned by @code{buffer-modified-tick}. |
b8d4c8d0 GM |
583 | By comparing the values returned by two @code{buffer-chars-modified-tick} |
584 | calls, you can tell whether a character change occurred in that buffer | |
585 | in between the calls. If @var{buffer} is @code{nil} (or omitted), the | |
586 | current buffer is used. | |
587 | @end defun | |
588 | ||
589 | @node Modification Time | |
b8d4c8d0 GM |
590 | @section Buffer Modification Time |
591 | @cindex comparing file modification time | |
592 | @cindex modification time of buffer | |
593 | ||
594 | Suppose that you visit a file and make changes in its buffer, and | |
595 | meanwhile the file itself is changed on disk. At this point, saving the | |
596 | buffer would overwrite the changes in the file. Occasionally this may | |
597 | be what you want, but usually it would lose valuable information. Emacs | |
598 | therefore checks the file's modification time using the functions | |
599 | described below before saving the file. (@xref{File Attributes}, | |
600 | for how to examine a file's modification time.) | |
601 | ||
ec1b9b17 GM |
602 | @defun verify-visited-file-modtime &optional buffer |
603 | This function compares what @var{buffer} (by default, the | |
604 | current-buffer) has recorded for the modification time of its visited | |
605 | file against the actual modification time of the file as recorded by the | |
606 | operating system. The two should be the same unless some other process | |
607 | has written the file since Emacs visited or saved it. | |
b8d4c8d0 GM |
608 | |
609 | The function returns @code{t} if the last actual modification time and | |
610 | Emacs's recorded modification time are the same, @code{nil} otherwise. | |
611 | It also returns @code{t} if the buffer has no recorded last | |
612 | modification time, that is if @code{visited-file-modtime} would return | |
613 | zero. | |
614 | ||
615 | It always returns @code{t} for buffers that are not visiting a file, | |
616 | even if @code{visited-file-modtime} returns a non-zero value. For | |
617 | instance, it always returns @code{t} for dired buffers. It returns | |
618 | @code{t} for buffers that are visiting a file that does not exist and | |
619 | never existed, but @code{nil} for file-visiting buffers whose file has | |
620 | been deleted. | |
621 | @end defun | |
622 | ||
623 | @defun clear-visited-file-modtime | |
624 | This function clears out the record of the last modification time of | |
625 | the file being visited by the current buffer. As a result, the next | |
626 | attempt to save this buffer will not complain of a discrepancy in | |
627 | file modification times. | |
628 | ||
629 | This function is called in @code{set-visited-file-name} and other | |
630 | exceptional places where the usual test to avoid overwriting a changed | |
631 | file should not be done. | |
632 | @end defun | |
633 | ||
634 | @c Emacs 19 feature | |
635 | @defun visited-file-modtime | |
636 | This function returns the current buffer's recorded last file | |
72ec96fb PE |
637 | modification time, as a list of the form @code{(@var{high} @var{low} |
638 | @var{microsec} @var{picosec})}. | |
b8d4c8d0 GM |
639 | (This is the same format that @code{file-attributes} uses to return |
640 | time values; see @ref{File Attributes}.) | |
641 | ||
642 | If the buffer has no recorded last modification time, this function | |
643 | returns zero. This case occurs, for instance, if the buffer is not | |
644 | visiting a file or if the time has been explicitly cleared by | |
645 | @code{clear-visited-file-modtime}. Note, however, that | |
646 | @code{visited-file-modtime} returns a list for some non-file buffers | |
647 | too. For instance, in a Dired buffer listing a directory, it returns | |
648 | the last modification time of that directory, as recorded by Dired. | |
649 | ||
650 | For a new buffer visiting a not yet existing file, @var{high} is | |
651 | @minus{}1 and @var{low} is 65535, that is, | |
652 | @ifnottex | |
653 | @w{2**16 - 1.} | |
654 | @end ifnottex | |
655 | @tex | |
656 | @math{2^{16}-1}. | |
657 | @end tex | |
658 | @end defun | |
659 | ||
660 | @c Emacs 19 feature | |
661 | @defun set-visited-file-modtime &optional time | |
662 | This function updates the buffer's record of the last modification time | |
663 | of the visited file, to the value specified by @var{time} if @var{time} | |
664 | is not @code{nil}, and otherwise to the last modification time of the | |
665 | visited file. | |
666 | ||
667 | If @var{time} is neither @code{nil} nor zero, it should have the form | |
72ec96fb PE |
668 | @code{(@var{high} @var{low} @var{microsec} @var{picosec})}, |
669 | the format used by @code{current-time} (@pxref{Time of Day}). | |
b8d4c8d0 GM |
670 | |
671 | This function is useful if the buffer was not read from the file | |
672 | normally, or if the file itself has been changed for some known benign | |
673 | reason. | |
674 | @end defun | |
675 | ||
676 | @defun ask-user-about-supersession-threat filename | |
677 | This function is used to ask a user how to proceed after an attempt to | |
678 | modify an buffer visiting file @var{filename} when the file is newer | |
679 | than the buffer text. Emacs detects this because the modification | |
680 | time of the file on disk is newer than the last save-time of the | |
681 | buffer. This means some other program has probably altered the file. | |
682 | ||
683 | @kindex file-supersession | |
684 | Depending on the user's answer, the function may return normally, in | |
685 | which case the modification of the buffer proceeds, or it may signal a | |
686 | @code{file-supersession} error with data @code{(@var{filename})}, in which | |
687 | case the proposed buffer modification is not allowed. | |
688 | ||
689 | This function is called automatically by Emacs on the proper | |
690 | occasions. It exists so you can customize Emacs by redefining it. | |
691 | See the file @file{userlock.el} for the standard definition. | |
692 | ||
693 | See also the file locking mechanism in @ref{File Locks}. | |
694 | @end defun | |
695 | ||
696 | @node Read Only Buffers | |
697 | @section Read-Only Buffers | |
698 | @cindex read-only buffer | |
699 | @cindex buffer, read-only | |
700 | ||
701 | If a buffer is @dfn{read-only}, then you cannot change its contents, | |
702 | although you may change your view of the contents by scrolling and | |
703 | narrowing. | |
704 | ||
705 | Read-only buffers are used in two kinds of situations: | |
706 | ||
707 | @itemize @bullet | |
708 | @item | |
709 | A buffer visiting a write-protected file is normally read-only. | |
710 | ||
711 | Here, the purpose is to inform the user that editing the buffer with the | |
712 | aim of saving it in the file may be futile or undesirable. The user who | |
713 | wants to change the buffer text despite this can do so after clearing | |
714 | the read-only flag with @kbd{C-x C-q}. | |
715 | ||
716 | @item | |
717 | Modes such as Dired and Rmail make buffers read-only when altering the | |
718 | contents with the usual editing commands would probably be a mistake. | |
719 | ||
720 | The special commands of these modes bind @code{buffer-read-only} to | |
721 | @code{nil} (with @code{let}) or bind @code{inhibit-read-only} to | |
722 | @code{t} around the places where they themselves change the text. | |
723 | @end itemize | |
724 | ||
725 | @defvar buffer-read-only | |
726 | This buffer-local variable specifies whether the buffer is read-only. | |
727 | The buffer is read-only if this variable is non-@code{nil}. | |
728 | @end defvar | |
729 | ||
730 | @defvar inhibit-read-only | |
731 | If this variable is non-@code{nil}, then read-only buffers and, | |
732 | depending on the actual value, some or all read-only characters may be | |
b68b3337 CY |
733 | modified. Read-only characters in a buffer are those that have a |
734 | non-@code{nil} @code{read-only} text property. @xref{Special | |
735 | Properties}, for more information about text properties. | |
b8d4c8d0 GM |
736 | |
737 | If @code{inhibit-read-only} is @code{t}, all @code{read-only} character | |
738 | properties have no effect. If @code{inhibit-read-only} is a list, then | |
739 | @code{read-only} character properties have no effect if they are members | |
740 | of the list (comparison is done with @code{eq}). | |
741 | @end defvar | |
742 | ||
e109c4a6 CY |
743 | @deffn Command read-only-mode &optional arg |
744 | This is the mode command for Read Only minor mode, a buffer-local | |
745 | minor mode. When the mode is enabled, @code{buffer-read-only} is | |
746 | non-@code{nil} in the buffer; when disabled, @code{buffer-read-only} | |
747 | is @code{nil} in the buffer. The calling convention is the same as | |
748 | for other minor mode commands (@pxref{Minor Mode Conventions}). | |
749 | ||
750 | This minor mode mainly serves as a wrapper for | |
751 | @code{buffer-read-only}; unlike most minor modes, there is no separate | |
752 | @code{read-only-mode} variable. Even when Read Only mode is disabled, | |
753 | characters with non-@code{nil} @code{read-only} text properties remain | |
754 | read-only. To temporarily ignore all read-only states, bind | |
755 | @code{inhibit-read-only}, as described above. | |
756 | ||
757 | When enabling Read Only mode, this mode command also enables View mode | |
b68b3337 CY |
758 | if the option @code{view-read-only} is non-@code{nil}. @xref{Misc |
759 | Buffer,,Miscellaneous Buffer Operations, emacs, The GNU Emacs Manual}. | |
e109c4a6 CY |
760 | When disabling Read Only mode, it disables View mode if View mode was |
761 | enabled. | |
b8d4c8d0 GM |
762 | @end deffn |
763 | ||
764 | @defun barf-if-buffer-read-only | |
765 | This function signals a @code{buffer-read-only} error if the current | |
766 | buffer is read-only. @xref{Using Interactive}, for another way to | |
767 | signal an error if the current buffer is read-only. | |
768 | @end defun | |
769 | ||
770 | @node The Buffer List | |
771 | @section The Buffer List | |
772 | @cindex buffer list | |
773 | ||
174dc00c MR |
774 | The @dfn{buffer list} is a list of all live buffers. The order of the |
775 | buffers in this list is based primarily on how recently each buffer has | |
776 | been displayed in a window. Several functions, notably | |
777 | @code{other-buffer}, use this ordering. A buffer list displayed for the | |
778 | user also follows this order. | |
779 | ||
0e406a72 CY |
780 | Creating a buffer adds it to the end of the buffer list, and killing |
781 | a buffer removes it from that list. A buffer moves to the front of | |
782 | this list whenever it is chosen for display in a window | |
783 | (@pxref{Switching Buffers}) or a window displaying it is selected | |
784 | (@pxref{Selecting Windows}). A buffer moves to the end of the list | |
785 | when it is buried (see @code{bury-buffer}, below). There are no | |
786 | functions available to the Lisp programmer which directly manipulate | |
787 | the buffer list. | |
174dc00c MR |
788 | |
789 | In addition to the fundamental buffer list just described, Emacs | |
790 | maintains a local buffer list for each frame, in which the buffers that | |
791 | have been displayed (or had their windows selected) in that frame come | |
792 | first. (This order is recorded in the frame's @code{buffer-list} frame | |
793 | parameter; see @ref{Buffer Parameters}.) Buffers never displayed in | |
794 | that frame come afterward, ordered according to the fundamental buffer | |
795 | list. | |
b8d4c8d0 GM |
796 | |
797 | @defun buffer-list &optional frame | |
798 | This function returns the buffer list, including all buffers, even those | |
799 | whose names begin with a space. The elements are actual buffers, not | |
800 | their names. | |
801 | ||
174dc00c MR |
802 | If @var{frame} is a frame, this returns @var{frame}'s local buffer list. |
803 | If @var{frame} is @code{nil} or omitted, the fundamental buffer list is | |
804 | used: the buffers appear in order of most recent display or selection, | |
805 | regardless of which frames they were displayed on. | |
b8d4c8d0 GM |
806 | |
807 | @example | |
808 | @group | |
809 | (buffer-list) | |
810 | @result{} (#<buffer buffers.texi> | |
811 | #<buffer *Minibuf-1*> #<buffer buffer.c> | |
812 | #<buffer *Help*> #<buffer TAGS>) | |
813 | @end group | |
814 | ||
815 | @group | |
816 | ;; @r{Note that the name of the minibuffer} | |
817 | ;; @r{begins with a space!} | |
818 | (mapcar (function buffer-name) (buffer-list)) | |
819 | @result{} ("buffers.texi" " *Minibuf-1*" | |
820 | "buffer.c" "*Help*" "TAGS") | |
821 | @end group | |
822 | @end example | |
823 | @end defun | |
824 | ||
174dc00c MR |
825 | The list returned by @code{buffer-list} is constructed specifically; |
826 | it is not an internal Emacs data structure, and modifying it has no | |
827 | effect on the order of buffers. If you want to change the order of | |
828 | buffers in the fundamental buffer list, here is an easy way: | |
b8d4c8d0 GM |
829 | |
830 | @example | |
831 | (defun reorder-buffer-list (new-list) | |
832 | (while new-list | |
833 | (bury-buffer (car new-list)) | |
834 | (setq new-list (cdr new-list)))) | |
835 | @end example | |
836 | ||
837 | With this method, you can specify any order for the list, but there is | |
838 | no danger of losing a buffer or adding something that is not a valid | |
839 | live buffer. | |
840 | ||
174dc00c MR |
841 | To change the order or value of a specific frame's buffer list, set |
842 | that frame's @code{buffer-list} parameter with | |
843 | @code{modify-frame-parameters} (@pxref{Parameter Access}). | |
b8d4c8d0 GM |
844 | |
845 | @defun other-buffer &optional buffer visible-ok frame | |
846 | This function returns the first buffer in the buffer list other than | |
174dc00c MR |
847 | @var{buffer}. Usually, this is the buffer appearing in the most |
848 | recently selected window (in frame @var{frame} or else the selected | |
849 | frame, @pxref{Input Focus}), aside from @var{buffer}. Buffers whose | |
850 | names start with a space are not considered at all. | |
b8d4c8d0 | 851 | |
174dc00c | 852 | If @var{buffer} is not supplied (or if it is not a live buffer), then |
b8d4c8d0 | 853 | @code{other-buffer} returns the first buffer in the selected frame's |
174dc00c MR |
854 | local buffer list. (If @var{frame} is non-@code{nil}, it returns the |
855 | first buffer in @var{frame}'s local buffer list instead.) | |
b8d4c8d0 GM |
856 | |
857 | If @var{frame} has a non-@code{nil} @code{buffer-predicate} parameter, | |
858 | then @code{other-buffer} uses that predicate to decide which buffers to | |
859 | consider. It calls the predicate once for each buffer, and if the value | |
860 | is @code{nil}, that buffer is ignored. @xref{Buffer Parameters}. | |
861 | ||
862 | @c Emacs 19 feature | |
863 | If @var{visible-ok} is @code{nil}, @code{other-buffer} avoids returning | |
864 | a buffer visible in any window on any visible frame, except as a last | |
174dc00c | 865 | resort. If @var{visible-ok} is non-@code{nil}, then it does not matter |
b8d4c8d0 GM |
866 | whether a buffer is displayed somewhere or not. |
867 | ||
2bb0eca1 | 868 | If no suitable buffer exists, the buffer @file{*scratch*} is returned |
b8d4c8d0 GM |
869 | (and created, if necessary). |
870 | @end defun | |
871 | ||
174dc00c MR |
872 | @defun last-buffer &optional buffer visible-ok frame |
873 | This function returns the last buffer in @var{frame}'s buffer list other | |
874 | than @var{BUFFER}. If @var{frame} is omitted or @code{nil}, it uses the | |
875 | selected frame's buffer list. | |
876 | ||
877 | The argument @var{visible-ok} is handled as with @code{other-buffer}, | |
878 | see above. If no suitable buffer can be found, the buffer | |
2bb0eca1 | 879 | @file{*scratch*} is returned. |
174dc00c MR |
880 | @end defun |
881 | ||
b8d4c8d0 | 882 | @deffn Command bury-buffer &optional buffer-or-name |
174dc00c | 883 | This command puts @var{buffer-or-name} at the end of the buffer list, |
b8d4c8d0 GM |
884 | without changing the order of any of the other buffers on the list. |
885 | This buffer therefore becomes the least desirable candidate for | |
886 | @code{other-buffer} to return. The argument can be either a buffer | |
887 | itself or the name of one. | |
888 | ||
0d4bb04f | 889 | This function operates on each frame's @code{buffer-list} parameter as |
d83dc65b MR |
890 | well as the fundamental buffer list; therefore, the buffer that you bury |
891 | will come last in the value of @code{(buffer-list @var{frame})} and in | |
892 | the value of @code{(buffer-list)}. In addition, it also puts the buffer | |
893 | at the end of the list of buffer of the selected window (@pxref{Window | |
894 | History}) provided it is shown in that window. | |
895 | ||
896 | If @var{buffer-or-name} is @code{nil} or omitted, this means to bury the | |
897 | current buffer. In addition, if the current buffer is displayed in the | |
898 | selected window, this makes sure that the window is either deleted or | |
0d4bb04f MR |
899 | another buffer is shown in it. More precisely, if the selected window |
900 | is dedicated (@pxref{Dedicated Windows}) and there are other windows on | |
901 | its frame, the window is deleted. If it is the only window on its frame | |
902 | and that frame is not the only frame on its terminal, the frame is | |
903 | ``dismissed'' by calling the function specified by | |
904 | @code{frame-auto-hide-function} (@pxref{Quitting Windows}). Otherwise, | |
905 | it calls @code{switch-to-prev-buffer} (@pxref{Window History}) to show | |
906 | another buffer in that window. If @var{buffer-or-name} is displayed in | |
907 | some other window, it remains displayed there. | |
b8d4c8d0 GM |
908 | |
909 | To replace a buffer in all the windows that display it, use | |
d83dc65b | 910 | @code{replace-buffer-in-windows}, @xref{Buffers and Windows}. |
b8d4c8d0 GM |
911 | @end deffn |
912 | ||
174dc00c | 913 | @deffn Command unbury-buffer |
0e406a72 CY |
914 | This command switches to the last buffer in the local buffer list of |
915 | the selected frame. More precisely, it calls the function | |
916 | @code{switch-to-buffer} (@pxref{Switching Buffers}), to display the | |
431ee44b | 917 | buffer returned by @code{last-buffer} (see above), in the selected |
174dc00c MR |
918 | window. |
919 | @end deffn | |
920 | ||
921 | ||
b8d4c8d0 GM |
922 | @node Creating Buffers |
923 | @section Creating Buffers | |
924 | @cindex creating buffers | |
925 | @cindex buffers, creating | |
926 | ||
927 | This section describes the two primitives for creating buffers. | |
928 | @code{get-buffer-create} creates a buffer if it finds no existing buffer | |
929 | with the specified name; @code{generate-new-buffer} always creates a new | |
930 | buffer and gives it a unique name. | |
931 | ||
932 | Other functions you can use to create buffers include | |
933 | @code{with-output-to-temp-buffer} (@pxref{Temporary Displays}) and | |
934 | @code{create-file-buffer} (@pxref{Visiting Files}). Starting a | |
935 | subprocess can also create a buffer (@pxref{Processes}). | |
936 | ||
4d48fcdc | 937 | @defun get-buffer-create buffer-or-name |
09460d9a MR |
938 | This function returns a buffer named @var{buffer-or-name}. The buffer |
939 | returned does not become the current buffer---this function does not | |
940 | change which buffer is current. | |
941 | ||
942 | @var{buffer-or-name} must be either a string or an existing buffer. If | |
943 | it is a string and a live buffer with that name already exists, | |
944 | @code{get-buffer-create} returns that buffer. If no such buffer exists, | |
945 | it creates a new buffer. If @var{buffer-or-name} is a buffer instead of | |
946 | a string, it is returned as given, even if it is dead. | |
b8d4c8d0 GM |
947 | |
948 | @example | |
949 | @group | |
950 | (get-buffer-create "foo") | |
951 | @result{} #<buffer foo> | |
952 | @end group | |
953 | @end example | |
954 | ||
955 | The major mode for a newly created buffer is set to Fundamental mode. | |
4e3b4528 SM |
956 | (The default value of the variable @code{major-mode} is handled at a higher |
957 | level; see @ref{Auto Major Mode}.) If the name begins with a space, the | |
b8d4c8d0 GM |
958 | buffer initially disables undo information recording (@pxref{Undo}). |
959 | @end defun | |
960 | ||
961 | @defun generate-new-buffer name | |
962 | This function returns a newly created, empty buffer, but does not make | |
431ee44b CY |
963 | it current. The name of the buffer is generated by passing @var{name} |
964 | to the function @code{generate-new-buffer-name} (@pxref{Buffer | |
965 | Names}). Thus, if there is no buffer named @var{name}, then that is | |
966 | the name of the new buffer; if that name is in use, a suffix of the | |
967 | form @samp{<@var{n}>}, where @var{n} is an integer, is appended to | |
968 | @var{name}. | |
b8d4c8d0 GM |
969 | |
970 | An error is signaled if @var{name} is not a string. | |
971 | ||
972 | @example | |
973 | @group | |
974 | (generate-new-buffer "bar") | |
975 | @result{} #<buffer bar> | |
976 | @end group | |
977 | @group | |
978 | (generate-new-buffer "bar") | |
979 | @result{} #<buffer bar<2>> | |
980 | @end group | |
981 | @group | |
982 | (generate-new-buffer "bar") | |
983 | @result{} #<buffer bar<3>> | |
984 | @end group | |
985 | @end example | |
986 | ||
4e3b4528 SM |
987 | The major mode for the new buffer is set to Fundamental mode. The default |
988 | value of the variable @code{major-mode} is handled at a higher level. | |
b8d4c8d0 | 989 | @xref{Auto Major Mode}. |
b8d4c8d0 GM |
990 | @end defun |
991 | ||
992 | @node Killing Buffers | |
993 | @section Killing Buffers | |
994 | @cindex killing buffers | |
995 | @cindex buffers, killing | |
996 | ||
997 | @dfn{Killing a buffer} makes its name unknown to Emacs and makes the | |
998 | memory space it occupied available for other use. | |
999 | ||
1000 | The buffer object for the buffer that has been killed remains in | |
1001 | existence as long as anything refers to it, but it is specially marked | |
1002 | so that you cannot make it current or display it. Killed buffers retain | |
1003 | their identity, however; if you kill two distinct buffers, they remain | |
1004 | distinct according to @code{eq} although both are dead. | |
1005 | ||
1006 | If you kill a buffer that is current or displayed in a window, Emacs | |
431ee44b CY |
1007 | automatically selects or displays some other buffer instead. This |
1008 | means that killing a buffer can change the current buffer. Therefore, | |
1009 | when you kill a buffer, you should also take the precautions | |
b8d4c8d0 GM |
1010 | associated with changing the current buffer (unless you happen to know |
1011 | that the buffer being killed isn't current). @xref{Current Buffer}. | |
1012 | ||
1013 | If you kill a buffer that is the base buffer of one or more indirect | |
431ee44b CY |
1014 | @iftex |
1015 | buffers, | |
1016 | @end iftex | |
1017 | @ifnottex | |
1018 | buffers (@pxref{Indirect Buffers}), | |
1019 | @end ifnottex | |
1020 | the indirect buffers are automatically killed as well. | |
b8d4c8d0 | 1021 | |
431ee44b CY |
1022 | @cindex live buffer |
1023 | The @code{buffer-name} of a buffer is @code{nil} if, and only if, | |
1024 | the buffer is killed. A buffer that has not been killed is called a | |
1025 | @dfn{live} buffer. To test whether a buffer is live or killed, use | |
1026 | the function @code{buffer-live-p} (see below). | |
b8d4c8d0 | 1027 | |
f76f8246 | 1028 | @deffn Command kill-buffer &optional buffer-or-name |
b8d4c8d0 GM |
1029 | This function kills the buffer @var{buffer-or-name}, freeing all its |
1030 | memory for other uses or to be returned to the operating system. If | |
f76f8246 MR |
1031 | @var{buffer-or-name} is @code{nil} or omitted, it kills the current |
1032 | buffer. | |
b8d4c8d0 GM |
1033 | |
1034 | Any processes that have this buffer as the @code{process-buffer} are | |
431ee44b CY |
1035 | sent the @code{SIGHUP} (``hangup'') signal, which normally causes them |
1036 | to terminate. @xref{Signals to Processes}. | |
b8d4c8d0 GM |
1037 | |
1038 | If the buffer is visiting a file and contains unsaved changes, | |
1039 | @code{kill-buffer} asks the user to confirm before the buffer is killed. | |
1040 | It does this even if not called interactively. To prevent the request | |
1041 | for confirmation, clear the modified flag before calling | |
1042 | @code{kill-buffer}. @xref{Buffer Modification}. | |
1043 | ||
02043db0 EZ |
1044 | This function calls @code{replace-buffer-in-windows} for cleaning up |
1045 | all windows currently displaying the buffer to be killed. | |
f76f8246 | 1046 | |
b8d4c8d0 GM |
1047 | Killing a buffer that is already dead has no effect. |
1048 | ||
1049 | This function returns @code{t} if it actually killed the buffer. It | |
1050 | returns @code{nil} if the user refuses to confirm or if | |
1051 | @var{buffer-or-name} was already dead. | |
1052 | ||
1053 | @smallexample | |
1054 | (kill-buffer "foo.unchanged") | |
1055 | @result{} t | |
1056 | (kill-buffer "foo.changed") | |
1057 | ||
1058 | ---------- Buffer: Minibuffer ---------- | |
1059 | Buffer foo.changed modified; kill anyway? (yes or no) @kbd{yes} | |
1060 | ---------- Buffer: Minibuffer ---------- | |
1061 | ||
1062 | @result{} t | |
1063 | @end smallexample | |
1064 | @end deffn | |
1065 | ||
1066 | @defvar kill-buffer-query-functions | |
1067 | After confirming unsaved changes, @code{kill-buffer} calls the functions | |
1068 | in the list @code{kill-buffer-query-functions}, in order of appearance, | |
1069 | with no arguments. The buffer being killed is the current buffer when | |
1070 | they are called. The idea of this feature is that these functions will | |
1071 | ask for confirmation from the user. If any of them returns @code{nil}, | |
1072 | @code{kill-buffer} spares the buffer's life. | |
1073 | @end defvar | |
1074 | ||
1075 | @defvar kill-buffer-hook | |
1076 | This is a normal hook run by @code{kill-buffer} after asking all the | |
1077 | questions it is going to ask, just before actually killing the buffer. | |
1078 | The buffer to be killed is current when the hook functions run. | |
1079 | @xref{Hooks}. This variable is a permanent local, so its local binding | |
1080 | is not cleared by changing major modes. | |
1081 | @end defvar | |
1082 | ||
01f17ae2 | 1083 | @defopt buffer-offer-save |
b8d4c8d0 GM |
1084 | This variable, if non-@code{nil} in a particular buffer, tells |
1085 | @code{save-buffers-kill-emacs} and @code{save-some-buffers} (if the | |
1086 | second optional argument to that function is @code{t}) to offer to | |
1087 | save that buffer, just as they offer to save file-visiting buffers. | |
1088 | @xref{Definition of save-some-buffers}. The variable | |
1089 | @code{buffer-offer-save} automatically becomes buffer-local when set | |
1090 | for any reason. @xref{Buffer-Local Variables}. | |
01f17ae2 | 1091 | @end defopt |
b8d4c8d0 GM |
1092 | |
1093 | @defvar buffer-save-without-query | |
1094 | This variable, if non-@code{nil} in a particular buffer, tells | |
1095 | @code{save-buffers-kill-emacs} and @code{save-some-buffers} to save | |
1096 | this buffer (if it's modified) without asking the user. The variable | |
1097 | automatically becomes buffer-local when set for any reason. | |
1098 | @end defvar | |
1099 | ||
1100 | @defun buffer-live-p object | |
431ee44b CY |
1101 | This function returns @code{t} if @var{object} is a live buffer (a |
1102 | buffer which has not been killed), @code{nil} otherwise. | |
b8d4c8d0 GM |
1103 | @end defun |
1104 | ||
1105 | @node Indirect Buffers | |
1106 | @section Indirect Buffers | |
1107 | @cindex indirect buffers | |
1108 | @cindex base buffer | |
1109 | ||
1110 | An @dfn{indirect buffer} shares the text of some other buffer, which | |
1111 | is called the @dfn{base buffer} of the indirect buffer. In some ways it | |
1112 | is the analogue, for buffers, of a symbolic link among files. The base | |
1113 | buffer may not itself be an indirect buffer. | |
1114 | ||
1115 | The text of the indirect buffer is always identical to the text of its | |
1116 | base buffer; changes made by editing either one are visible immediately | |
1117 | in the other. This includes the text properties as well as the characters | |
1118 | themselves. | |
1119 | ||
1120 | In all other respects, the indirect buffer and its base buffer are | |
1121 | completely separate. They have different names, independent values of | |
1122 | point, independent narrowing, independent markers and overlays (though | |
1123 | inserting or deleting text in either buffer relocates the markers and | |
1124 | overlays for both), independent major modes, and independent | |
1125 | buffer-local variable bindings. | |
1126 | ||
1127 | An indirect buffer cannot visit a file, but its base buffer can. If | |
1128 | you try to save the indirect buffer, that actually saves the base | |
1129 | buffer. | |
1130 | ||
1131 | Killing an indirect buffer has no effect on its base buffer. Killing | |
1132 | the base buffer effectively kills the indirect buffer in that it cannot | |
1133 | ever again be the current buffer. | |
1134 | ||
1135 | @deffn Command make-indirect-buffer base-buffer name &optional clone | |
1136 | This creates and returns an indirect buffer named @var{name} whose | |
1137 | base buffer is @var{base-buffer}. The argument @var{base-buffer} may | |
1138 | be a live buffer or the name (a string) of an existing buffer. If | |
1139 | @var{name} is the name of an existing buffer, an error is signaled. | |
1140 | ||
1141 | If @var{clone} is non-@code{nil}, then the indirect buffer originally | |
1142 | shares the ``state'' of @var{base-buffer} such as major mode, minor | |
1143 | modes, buffer local variables and so on. If @var{clone} is omitted | |
1144 | or @code{nil} the indirect buffer's state is set to the default state | |
1145 | for new buffers. | |
1146 | ||
1147 | If @var{base-buffer} is an indirect buffer, its base buffer is used as | |
1148 | the base for the new buffer. If, in addition, @var{clone} is | |
1149 | non-@code{nil}, the initial state is copied from the actual base | |
1150 | buffer, not from @var{base-buffer}. | |
1151 | @end deffn | |
1152 | ||
5854c267 | 1153 | @deffn Command clone-indirect-buffer newname display-flag &optional norecord |
b8d4c8d0 GM |
1154 | This function creates and returns a new indirect buffer that shares |
1155 | the current buffer's base buffer and copies the rest of the current | |
1156 | buffer's attributes. (If the current buffer is not indirect, it is | |
1157 | used as the base buffer.) | |
1158 | ||
1159 | If @var{display-flag} is non-@code{nil}, that means to display the new | |
1160 | buffer by calling @code{pop-to-buffer}. If @var{norecord} is | |
1161 | non-@code{nil}, that means not to put the new buffer to the front of | |
1162 | the buffer list. | |
106e6894 | 1163 | @end deffn |
b8d4c8d0 GM |
1164 | |
1165 | @defun buffer-base-buffer &optional buffer | |
1166 | This function returns the base buffer of @var{buffer}, which defaults | |
1167 | to the current buffer. If @var{buffer} is not indirect, the value is | |
1168 | @code{nil}. Otherwise, the value is another buffer, which is never an | |
1169 | indirect buffer. | |
1170 | @end defun | |
1171 | ||
2aaaf0dd EZ |
1172 | @node Swapping Text |
1173 | @section Swapping Text Between Two Buffers | |
1174 | @cindex swap text between buffers | |
1175 | @cindex virtual buffers | |
1176 | ||
1177 | Specialized modes sometimes need to let the user access from the | |
1178 | same buffer several vastly different types of text. For example, you | |
1179 | may need to display a summary of the buffer text, in addition to | |
1180 | letting the user access the text itself. | |
1181 | ||
1182 | This could be implemented with multiple buffers (kept in sync when | |
1183 | the user edits the text), or with narrowing (@pxref{Narrowing}). But | |
1184 | these alternatives might sometimes become tedious or prohibitively | |
1185 | expensive, especially if each type of text requires expensive | |
1186 | buffer-global operations in order to provide correct display and | |
1187 | editing commands. | |
1188 | ||
1189 | Emacs provides another facility for such modes: you can quickly swap | |
1190 | buffer text between two buffers with @code{buffer-swap-text}. This | |
1191 | function is very fast because it doesn't move any text, it only | |
1192 | changes the internal data structures of the buffer object to point to | |
1193 | a different chunk of text. Using it, you can pretend that a group of | |
1194 | two or more buffers are actually a single virtual buffer that holds | |
1195 | the contents of all the individual buffers together. | |
1196 | ||
1197 | @defun buffer-swap-text buffer | |
85d14563 SM |
1198 | This function swaps the text of the current buffer and that of its |
1199 | argument @var{buffer}. It signals an error if one of the two buffers | |
1200 | is an indirect buffer (@pxref{Indirect Buffers}) or is a base buffer | |
1201 | of an indirect buffer. | |
2aaaf0dd EZ |
1202 | |
1203 | All the buffer properties that are related to the buffer text are | |
1204 | swapped as well: the positions of point and mark, all the markers, the | |
1205 | overlays, the text properties, the undo list, the value of the | |
1206 | @code{enable-multibyte-characters} flag (@pxref{Text Representations, | |
1207 | enable-multibyte-characters}), etc. | |
1208 | @end defun | |
1209 | ||
137987ab RS |
1210 | If you use @code{buffer-swap-text} on a file-visiting buffer, you |
1211 | should set up a hook to save the buffer's original text rather than | |
1212 | what it was swapped with. @code{write-region-annotate-functions} | |
1213 | works for this purpose. You should probably set | |
1214 | @code{buffer-saved-size} to @minus{}2 in the buffer, so that changes | |
1215 | in the text it is swapped with will not interfere with auto-saving. | |
1216 | ||
b8d4c8d0 GM |
1217 | @node Buffer Gap |
1218 | @section The Buffer Gap | |
1219 | ||
1220 | Emacs buffers are implemented using an invisible @dfn{gap} to make | |
1221 | insertion and deletion faster. Insertion works by filling in part of | |
1222 | the gap, and deletion adds to the gap. Of course, this means that the | |
1223 | gap must first be moved to the locus of the insertion or deletion. | |
1224 | Emacs moves the gap only when you try to insert or delete. This is why | |
1225 | your first editing command in one part of a large buffer, after | |
1226 | previously editing in another far-away part, sometimes involves a | |
1227 | noticeable delay. | |
1228 | ||
1229 | This mechanism works invisibly, and Lisp code should never be affected | |
1230 | by the gap's current location, but these functions are available for | |
1231 | getting information about the gap status. | |
1232 | ||
1233 | @defun gap-position | |
1234 | This function returns the current gap position in the current buffer. | |
1235 | @end defun | |
1236 | ||
1237 | @defun gap-size | |
1238 | This function returns the current gap size of the current buffer. | |
1239 | @end defun |