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