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