Mercurial > emacs
comparison lispref/buffers.texi @ 12067:73dc8205d259
*** empty log message ***
author | Karl Heuer <kwzh@gnu.org> |
---|---|
date | Mon, 05 Jun 1995 12:23:13 +0000 |
parents | a91fcb58e8d2 |
children | a6eb5f12b0f3 |
comparison
equal
deleted
inserted
replaced
12066:b9b0b3f96dc2 | 12067:73dc8205d259 |
---|---|
15 current buffer. Each buffer, including the current buffer, may or may | 15 current buffer. Each buffer, including the current buffer, may or may |
16 not be displayed in any windows. | 16 not be displayed in any windows. |
17 | 17 |
18 @menu | 18 @menu |
19 * Buffer Basics:: What is a buffer? | 19 * Buffer Basics:: What is a buffer? |
20 * Current Buffer:: Designating a buffer as current | |
21 so primitives will access its contents. | |
20 * Buffer Names:: Accessing and changing buffer names. | 22 * Buffer Names:: Accessing and changing buffer names. |
21 * Buffer File Name:: The buffer file name indicates which file is visited. | 23 * Buffer File Name:: The buffer file name indicates which file is visited. |
22 * Buffer Modification:: A buffer is @dfn{modified} if it needs to be saved. | 24 * Buffer Modification:: A buffer is @dfn{modified} if it needs to be saved. |
23 * Modification Time:: Determining whether the visited file was changed | 25 * Modification Time:: Determining whether the visited file was changed |
24 ``behind Emacs's back''. | 26 ``behind Emacs's back''. |
25 * Read Only Buffers:: Modifying text is not allowed in a read-only buffer. | 27 * Read Only Buffers:: Modifying text is not allowed in a read-only buffer. |
26 * The Buffer List:: How to look at all the existing buffers. | 28 * The Buffer List:: How to look at all the existing buffers. |
27 * Creating Buffers:: Functions that create buffers. | 29 * Creating Buffers:: Functions that create buffers. |
28 * Killing Buffers:: Buffers exist until explicitly killed. | 30 * Killing Buffers:: Buffers exist until explicitly killed. |
29 * Current Buffer:: Designating a buffer as current | 31 * Indirect Buffers:: An indirect buffer shares text with some other buffer. |
30 so primitives will access its contents. | |
31 @end menu | 32 @end menu |
32 | 33 |
33 @node Buffer Basics | 34 @node Buffer Basics |
34 @comment node-name, next, previous, up | 35 @comment node-name, next, previous, up |
35 @section Buffer Basics | 36 @section Buffer Basics |
72 | 73 |
73 @defun bufferp object | 74 @defun bufferp object |
74 This function returns @code{t} if @var{object} is a buffer, | 75 This function returns @code{t} if @var{object} is a buffer, |
75 @code{nil} otherwise. | 76 @code{nil} otherwise. |
76 @end defun | 77 @end defun |
77 | |
78 @node Buffer Names | |
79 @section Buffer Names | |
80 @cindex buffer names | |
81 | |
82 Each buffer has a unique name, which is a string. Many of the | |
83 functions that work on buffers accept either a buffer or a buffer name | |
84 as an argument. Any argument called @var{buffer-or-name} is of this | |
85 sort, and an error is signaled if it is neither a string nor a buffer. | |
86 Any argument called @var{buffer} must be an actual buffer | |
87 object, not a name. | |
88 | |
89 Buffers that are ephemeral and generally uninteresting to the user | |
90 have names starting with a space, so that the @code{list-buffers} or | |
91 @code{buffer-menu} commands don't mention them. A name starting with | |
92 space also initially disables recording undo information; see | |
93 @ref{Undo}. | |
94 | |
95 @defun buffer-name &optional buffer | |
96 This function returns the name of @var{buffer} as a string. If | |
97 @var{buffer} is not supplied, it defaults to the current buffer. | |
98 | |
99 If @code{buffer-name} returns @code{nil}, it means that @var{buffer} | |
100 has been killed. @xref{Killing Buffers}. | |
101 | |
102 @example | |
103 @group | |
104 (buffer-name) | |
105 @result{} "buffers.texi" | |
106 @end group | |
107 | |
108 @group | |
109 (setq foo (get-buffer "temp")) | |
110 @result{} #<buffer temp> | |
111 @end group | |
112 @group | |
113 (kill-buffer foo) | |
114 @result{} nil | |
115 @end group | |
116 @group | |
117 (buffer-name foo) | |
118 @result{} nil | |
119 @end group | |
120 @group | |
121 foo | |
122 @result{} #<killed buffer> | |
123 @end group | |
124 @end example | |
125 @end defun | |
126 | |
127 @deffn Command rename-buffer newname &optional unique | |
128 This function renames the current buffer to @var{newname}. An error | |
129 is signaled if @var{newname} is not a string, or if there is already a | |
130 buffer with that name. The function returns @code{nil}. | |
131 | |
132 @c Emacs 19 feature | |
133 Ordinarily, @code{rename-buffer} signals an error if @var{newname} is | |
134 already in use. However, if @var{unique} is non-@code{nil}, it modifies | |
135 @var{newname} to make a name that is not in use. Interactively, you can | |
136 make @var{unique} non-@code{nil} with a numeric prefix argument. | |
137 | |
138 One application of this command is to rename the @samp{*shell*} buffer | |
139 to some other name, thus making it possible to create a second shell | |
140 buffer under the name @samp{*shell*}. | |
141 @end deffn | |
142 | |
143 @defun get-buffer buffer-or-name | |
144 This function returns the buffer specified by @var{buffer-or-name}. | |
145 If @var{buffer-or-name} is a string and there is no buffer with that | |
146 name, the value is @code{nil}. If @var{buffer-or-name} is a buffer, it | |
147 is returned as given. (That is not very useful, so the argument is usually | |
148 a name.) For example: | |
149 | |
150 @example | |
151 @group | |
152 (setq b (get-buffer "lewis")) | |
153 @result{} #<buffer lewis> | |
154 @end group | |
155 @group | |
156 (get-buffer b) | |
157 @result{} #<buffer lewis> | |
158 @end group | |
159 @group | |
160 (get-buffer "Frazzle-nots") | |
161 @result{} nil | |
162 @end group | |
163 @end example | |
164 | |
165 See also the function @code{get-buffer-create} in @ref{Creating Buffers}. | |
166 @end defun | |
167 | |
168 @c Emacs 19 feature | |
169 @defun generate-new-buffer-name starting-name | |
170 This function returns a name that would be unique for a new buffer---but | |
171 does not create the buffer. It starts with @var{starting-name}, and | |
172 produces a name not currently in use for any buffer by appending a | |
173 number inside of @samp{<@dots{}>}. | |
174 | |
175 See the related function @code{generate-new-buffer} in @ref{Creating | |
176 Buffers}. | |
177 @end defun | |
178 | |
179 @node Buffer File Name | |
180 @section Buffer File Name | |
181 @cindex visited file | |
182 @cindex buffer file name | |
183 @cindex file name of buffer | |
184 | |
185 The @dfn{buffer file name} is the name of the file that is visited in | |
186 that buffer. When a buffer is not visiting a file, its buffer file name | |
187 is @code{nil}. Most of the time, the buffer name is the same as the | |
188 nondirectory part of the buffer file name, but the buffer file name and | |
189 the buffer name are distinct and can be set independently. | |
190 @xref{Visiting Files}. | |
191 | |
192 @defun buffer-file-name &optional buffer | |
193 This function returns the absolute file name of the file that | |
194 @var{buffer} is visiting. If @var{buffer} is not visiting any file, | |
195 @code{buffer-file-name} returns @code{nil}. If @var{buffer} is not | |
196 supplied, it defaults to the current buffer. | |
197 | |
198 @example | |
199 @group | |
200 (buffer-file-name (other-buffer)) | |
201 @result{} "/usr/user/lewis/manual/files.texi" | |
202 @end group | |
203 @end example | |
204 @end defun | |
205 | |
206 @defvar buffer-file-name | |
207 This buffer-local variable contains the name of the file being visited | |
208 in the current buffer, or @code{nil} if it is not visiting a file. It | |
209 is a permanent local, unaffected by @code{kill-local-variables}. | |
210 | |
211 @example | |
212 @group | |
213 buffer-file-name | |
214 @result{} "/usr/user/lewis/manual/buffers.texi" | |
215 @end group | |
216 @end example | |
217 | |
218 It is risky to change this variable's value without doing various other | |
219 things. See the definition of @code{set-visited-file-name} in | |
220 @file{files.el}; some of the things done there, such as changing the | |
221 buffer name, are not strictly necessary, but others are essential to | |
222 avoid confusing Emacs. | |
223 @end defvar | |
224 | |
225 @defvar buffer-file-truename | |
226 This buffer-local variable holds the truename of the file visited in the | |
227 current buffer, or @code{nil} if no file is visited. It is a permanent | |
228 local, unaffected by @code{kill-local-variables}. @xref{Truenames}. | |
229 @end defvar | |
230 | |
231 @defvar buffer-file-number | |
232 This buffer-local variable holds the file number and directory device | |
233 number of the file visited in the current buffer, or @code{nil} if no | |
234 file or a nonexistent file is visited. It is a permanent local, | |
235 unaffected by @code{kill-local-variables}. @xref{Truenames}. | |
236 | |
237 The value is normally a list of the form @code{(@var{filenum} | |
238 @var{devnum})}. This pair of numbers uniquely identifies the file among | |
239 all files accessible on the system. See the function | |
240 @code{file-attributes}, in @ref{File Attributes}, for more information | |
241 about them. | |
242 @end defvar | |
243 | |
244 @defun get-file-buffer filename | |
245 This function returns the buffer visiting file @var{filename}. If | |
246 there is no such buffer, it returns @code{nil}. The argument | |
247 @var{filename}, which must be a string, is expanded (@pxref{File Name | |
248 Expansion}), then compared against the visited file names of all live | |
249 buffers. | |
250 | |
251 @example | |
252 @group | |
253 (get-file-buffer "buffers.texi") | |
254 @result{} #<buffer buffers.texi> | |
255 @end group | |
256 @end example | |
257 | |
258 In unusual circumstances, there can be more than one buffer visiting | |
259 the same file name. In such cases, this function returns the first | |
260 such buffer in the buffer list. | |
261 @end defun | |
262 | |
263 @deffn Command set-visited-file-name filename | |
264 If @var{filename} is a non-empty string, this function changes the | |
265 name of the file visited in current buffer to @var{filename}. (If the | |
266 buffer had no visited file, this gives it one.) The @emph{next time} | |
267 the buffer is saved it will go in the newly-specified file. This | |
268 command marks the buffer as modified, since it does not (as far as Emacs | |
269 knows) match the contents of @var{filename}, even if it matched the | |
270 former visited file. | |
271 | |
272 If @var{filename} is @code{nil} or the empty string, that stands for | |
273 ``no visited file''. In this case, @code{set-visited-file-name} marks | |
274 the buffer as having no visited file. | |
275 | |
276 @c Wordy to avoid overfull hbox. --rjc 16mar92 | |
277 When the function @code{set-visited-file-name} is called interactively, it | |
278 prompts for @var{filename} in the minibuffer. | |
279 | |
280 See also @code{clear-visited-file-modtime} and | |
281 @code{verify-visited-file-modtime} in @ref{Buffer Modification}. | |
282 @end deffn | |
283 | |
284 @defvar list-buffers-directory | |
285 This buffer-local variable records a string to display in a buffer | |
286 listing in place of the visited file name, for buffers that don't have a | |
287 visited file name. Dired buffers use this variable. | |
288 @end defvar | |
289 | |
290 @node Buffer Modification | |
291 @section Buffer Modification | |
292 @cindex buffer modification | |
293 @cindex modification flag (of buffer) | |
294 | |
295 Emacs keeps a flag called the @dfn{modified flag} for each buffer, to | |
296 record whether you have changed the text of the buffer. This flag is | |
297 set to @code{t} whenever you alter the contents of the buffer, and | |
298 cleared to @code{nil} when you save it. Thus, the flag shows whether | |
299 there are unsaved changes. The flag value is normally shown in the mode | |
300 line (@pxref{Mode Line Variables}), and controls saving (@pxref{Saving | |
301 Buffers}) and auto-saving (@pxref{Auto-Saving}). | |
302 | |
303 Some Lisp programs set the flag explicitly. For example, the function | |
304 @code{set-visited-file-name} sets the flag to @code{t}, because the text | |
305 does not match the newly-visited file, even if it is unchanged from the | |
306 file formerly visited. | |
307 | |
308 The functions that modify the contents of buffers are described in | |
309 @ref{Text}. | |
310 | |
311 @defun buffer-modified-p &optional buffer | |
312 This function returns @code{t} if the buffer @var{buffer} has been modified | |
313 since it was last read in from a file or saved, or @code{nil} | |
314 otherwise. If @var{buffer} is not supplied, the current buffer | |
315 is tested. | |
316 @end defun | |
317 | |
318 @defun set-buffer-modified-p flag | |
319 This function marks the current buffer as modified if @var{flag} is | |
320 non-@code{nil}, or as unmodified if the flag is @code{nil}. | |
321 | |
322 Another effect of calling this function is to cause unconditional | |
323 redisplay of the mode line for the current buffer. In fact, the | |
324 function @code{force-mode-line-update} works by doing this: | |
325 | |
326 @example | |
327 @group | |
328 (set-buffer-modified-p (buffer-modified-p)) | |
329 @end group | |
330 @end example | |
331 @end defun | |
332 | |
333 @deffn Command not-modified | |
334 This command marks the current buffer as unmodified, and not needing | |
335 to be saved. Don't use this function in programs, since it prints a | |
336 message in the echo area; use @code{set-buffer-modified-p} (above) instead. | |
337 @end deffn | |
338 | |
339 @c Emacs 19 feature | |
340 @defun buffer-modified-tick &optional buffer | |
341 This function returns @var{buffer}`s modification-count. This is a | |
342 counter that increments every time the buffer is modified. If | |
343 @var{buffer} is @code{nil} (or omitted), the current buffer is used. | |
344 @end defun | |
345 | |
346 @node Modification Time | |
347 @comment node-name, next, previous, up | |
348 @section Comparison of Modification Time | |
349 @cindex comparison of modification time | |
350 @cindex modification time, comparison of | |
351 | |
352 Suppose that you visit a file and make changes in its buffer, and | |
353 meanwhile the file itself is changed on disk. At this point, saving the | |
354 buffer would overwrite the changes in the file. Occasionally this may | |
355 be what you want, but usually it would lose valuable information. Emacs | |
356 therefore checks the file's modification time using the functions | |
357 described below before saving the file. | |
358 | |
359 @defun verify-visited-file-modtime buffer | |
360 This function compares what @var{buffer} has recorded for the | |
361 modification time of its visited file against the actual modification | |
362 time of the file as recorded by the operating system. The two should be | |
363 the same unless some other process has written the file since Emacs | |
364 visited or saved it. | |
365 | |
366 The function returns @code{t} if the last actual modification time and | |
367 Emacs's recorded modification time are the same, @code{nil} otherwise. | |
368 @end defun | |
369 | |
370 @defun clear-visited-file-modtime | |
371 This function clears out the record of the last modification time of | |
372 the file being visited by the current buffer. As a result, the next | |
373 attempt to save this buffer will not complain of a discrepancy in | |
374 file modification times. | |
375 | |
376 This function is called in @code{set-visited-file-name} and other | |
377 exceptional places where the usual test to avoid overwriting a changed | |
378 file should not be done. | |
379 @end defun | |
380 | |
381 @c Emacs 19 feature | |
382 @defun visited-file-modtime | |
383 This function returns the buffer's recorded last file modification time, | |
384 as a list of the form @code{(@var{high} . @var{low})}. (This is the | |
385 same format that @code{file-attributes} uses to return time values; see | |
386 @ref{File Attributes}.) | |
387 @end defun | |
388 | |
389 @c Emacs 19 feature | |
390 @defun set-visited-file-modtime &optional time | |
391 This function updates the buffer's record of the last modification time | |
392 of the visited file, to the value specified by @var{time} if @var{time} | |
393 is not @code{nil}, and otherwise to the last modification time of the | |
394 visited file. | |
395 | |
396 If @var{time} is not @code{nil}, it should have the form | |
397 @code{(@var{high} . @var{low})} or @code{(@var{high} @var{low})}, in | |
398 either case containing two integers, each of which holds 16 bits of the | |
399 time. | |
400 | |
401 This function is useful if the buffer was not read from the file | |
402 normally, or if the file itself has been changed for some known benign | |
403 reason. | |
404 @end defun | |
405 | |
406 @defun ask-user-about-supersession-threat filename | |
407 @cindex obsolete buffer | |
408 This function is used to ask a user how to proceed after an attempt to | |
409 modify an obsolete buffer visiting file @var{filename}. An | |
410 @dfn{obsolete buffer} is an unmodified buffer for which the associated | |
411 file on disk is newer than the last save-time of the buffer. This means | |
412 some other program has probably altered the file. | |
413 | |
414 @kindex file-supersession | |
415 Depending on the user's answer, the function may return normally, in | |
416 which case the modification of the buffer proceeds, or it may signal a | |
417 @code{file-supersession} error with data @code{(@var{filename})}, in which | |
418 case the proposed buffer modification is not allowed. | |
419 | |
420 This function is called automatically by Emacs on the proper | |
421 occasions. It exists so you can customize Emacs by redefining it. | |
422 See the file @file{userlock.el} for the standard definition. | |
423 | |
424 See also the file locking mechanism in @ref{File Locks}. | |
425 @end defun | |
426 | |
427 @node Read Only Buffers | |
428 @section Read-Only Buffers | |
429 @cindex read-only buffer | |
430 @cindex buffer, read-only | |
431 | |
432 If a buffer is @dfn{read-only}, then you cannot change its contents, | |
433 although you may change your view of the contents by scrolling and | |
434 narrowing. | |
435 | |
436 Read-only buffers are used in two kinds of situations: | |
437 | |
438 @itemize @bullet | |
439 @item | |
440 A buffer visiting a write-protected file is normally read-only. | |
441 | |
442 Here, the purpose is to show the user that editing the buffer with the | |
443 aim of saving it in the file may be futile or undesirable. The user who | |
444 wants to change the buffer text despite this can do so after clearing | |
445 the read-only flag with @kbd{C-M-q}. | |
446 | |
447 @item | |
448 Modes such as Dired and Rmail make buffers read-only when altering the | |
449 contents with the usual editing commands is probably a mistake. | |
450 | |
451 The special commands of these modes bind @code{buffer-read-only} to | |
452 @code{nil} (with @code{let}) or bind @code{inhibit-read-only} to | |
453 @code{t} around the places where they change the text. | |
454 @end itemize | |
455 | |
456 @defvar buffer-read-only | |
457 This buffer-local variable specifies whether the buffer is read-only. | |
458 The buffer is read-only if this variable is non-@code{nil}. | |
459 @end defvar | |
460 | |
461 @defvar inhibit-read-only | |
462 If this variable is non-@code{nil}, then read-only buffers and read-only | |
463 characters may be modified. Read-only characters in a buffer are those | |
464 that have non-@code{nil} @code{read-only} properties (either text | |
465 properties or overlay properties). @xref{Special Properties}, for more | |
466 information about text properties. @xref{Overlays}, for more | |
467 information about overlays and their properties. | |
468 | |
469 If @code{inhibit-read-only} is @code{t}, all @code{read-only} character | |
470 properties have no effect. If @code{inhibit-read-only} is a list, then | |
471 @code{read-only} character properties have no effect if they are members | |
472 of the list (comparison is done with @code{eq}). | |
473 @end defvar | |
474 | |
475 @deffn Command toggle-read-only | |
476 This command changes whether the current buffer is read-only. It is | |
477 intended for interactive use; don't use it in programs. At any given | |
478 point in a program, you should know whether you want the read-only flag | |
479 on or off; so you can set @code{buffer-read-only} explicitly to the | |
480 proper value, @code{t} or @code{nil}. | |
481 @end deffn | |
482 | |
483 @defun barf-if-buffer-read-only | |
484 This function signals a @code{buffer-read-only} error if the current | |
485 buffer is read-only. @xref{Interactive Call}, for another way to | |
486 signal an error if the current buffer is read-only. | |
487 @end defun | |
488 | |
489 @node The Buffer List | |
490 @section The Buffer List | |
491 @cindex buffer list | |
492 | |
493 The @dfn{buffer list} is a list of all live buffers. Creating a | |
494 buffer adds it to this list, and killing a buffer deletes it. The order | |
495 of the buffers in the list is based primarily on how recently each | |
496 buffer has been displayed in the selected window. Buffers move to the | |
497 front of the list when they are selected and to the end when they are | |
498 buried. Several functions, notably @code{other-buffer}, use this | |
499 ordering. A buffer list displayed for the user also follows this order. | |
500 | |
501 @defun buffer-list | |
502 This function returns a list of all buffers, including those whose names | |
503 begin with a space. The elements are actual buffers, not their names. | |
504 | |
505 @example | |
506 @group | |
507 (buffer-list) | |
508 @result{} (#<buffer buffers.texi> | |
509 #<buffer *Minibuf-1*> #<buffer buffer.c> | |
510 #<buffer *Help*> #<buffer TAGS>) | |
511 @end group | |
512 | |
513 @group | |
514 ;; @r{Note that the name of the minibuffer} | |
515 ;; @r{begins with a space!} | |
516 (mapcar (function buffer-name) (buffer-list)) | |
517 @result{} ("buffers.texi" " *Minibuf-1*" | |
518 "buffer.c" "*Help*" "TAGS") | |
519 @end group | |
520 @end example | |
521 | |
522 This list is a copy of a list used inside Emacs; modifying it has no | |
523 effect on the ordering of buffers. | |
524 @end defun | |
525 | |
526 @defun other-buffer &optional buffer-or-name visible-ok | |
527 This function returns the first buffer in the buffer list other than | |
528 @var{buffer-or-name}. Usually this is the buffer most recently shown in | |
529 the selected window, aside from @var{buffer-or-name}. Buffers whose | |
530 names start with a space are not considered. | |
531 | |
532 If @var{buffer-or-name} is not supplied (or if it is not a buffer), | |
533 then @code{other-buffer} returns the first buffer on the buffer list | |
534 that is not visible in any window in a visible frame. | |
535 | |
536 @c Emacs 19 feature | |
537 If @var{visible-ok} is @code{nil}, @code{other-buffer} avoids returning | |
538 a buffer visible in any window on any visible frame, except as a last | |
539 resort. If @var{visible-ok} is non-@code{nil}, then it does not matter | |
540 whether a buffer is displayed somewhere or not. | |
541 | |
542 If no suitable buffer exists, the buffer @samp{*scratch*} is returned | |
543 (and created, if necessary). | |
544 @end defun | |
545 | |
546 @deffn Command bury-buffer &optional buffer-or-name | |
547 This function puts @var{buffer-or-name} at the end of the buffer list | |
548 without changing the order of any of the other buffers on the list. | |
549 This buffer therefore becomes the least desirable candidate for | |
550 @code{other-buffer} to return. | |
551 | |
552 If @var{buffer-or-name} is @code{nil} or omitted, this means to bury the | |
553 current buffer. In addition, if the buffer is displayed in the selected | |
554 window, this switches to some other buffer (obtained using | |
555 @code{other-buffer}) in the selected window. But if the buffer is | |
556 displayed in some other window, it remains displayed there. | |
557 | |
558 If you wish to replace a buffer in all the windows that display it, use | |
559 @code{replace-buffer-in-windows}. @xref{Buffers and Windows}. | |
560 @end deffn | |
561 | |
562 @node Creating Buffers | |
563 @section Creating Buffers | |
564 @cindex creating buffers | |
565 @cindex buffers, creating | |
566 | |
567 This section describes the two primitives for creating buffers. | |
568 @code{get-buffer-create} creates a buffer if it finds no existing buffer | |
569 with the specified name; @code{generate-new-buffer} always creates a new | |
570 buffer and gives it a unique name. | |
571 | |
572 Other functions you can use to create buffers include | |
573 @code{with-output-to-temp-buffer} (@pxref{Temporary Displays}) and | |
574 @code{create-file-buffer} (@pxref{Visiting Files}). Starting a | |
575 subprocess can also create a buffer (@pxref{Processes}). | |
576 | |
577 @defun get-buffer-create name | |
578 This function returns a buffer named @var{name}. It returns an existing | |
579 buffer with that name, if one exists; otherwise, it creates a new | |
580 buffer. The buffer does not become the current buffer---this function | |
581 does not change which buffer is current. | |
582 | |
583 An error is signaled if @var{name} is not a string. | |
584 | |
585 @example | |
586 @group | |
587 (get-buffer-create "foo") | |
588 @result{} #<buffer foo> | |
589 @end group | |
590 @end example | |
591 | |
592 The major mode for the new buffer is set according to the variable | |
593 @code{default-major-mode}. @xref{Auto Major Mode}. | |
594 @end defun | |
595 | |
596 @defun generate-new-buffer name | |
597 This function returns a newly created, empty buffer, but does not make | |
598 it current. If there is no buffer named @var{name}, then that is the | |
599 name of the new buffer. If that name is in use, this function adds | |
600 suffixes of the form @samp{<@var{n}>} to @var{name}, where @var{n} is an | |
601 integer. It tries successive integers starting with 2 until it finds an | |
602 available name. | |
603 | |
604 An error is signaled if @var{name} is not a string. | |
605 | |
606 @example | |
607 @group | |
608 (generate-new-buffer "bar") | |
609 @result{} #<buffer bar> | |
610 @end group | |
611 @group | |
612 (generate-new-buffer "bar") | |
613 @result{} #<buffer bar<2>> | |
614 @end group | |
615 @group | |
616 (generate-new-buffer "bar") | |
617 @result{} #<buffer bar<3>> | |
618 @end group | |
619 @end example | |
620 | |
621 The major mode for the new buffer is set by the value of | |
622 @code{default-major-mode}. @xref{Auto Major Mode}. | |
623 | |
624 See the related function @code{generate-new-buffer-name} in @ref{Buffer | |
625 Names}. | |
626 @end defun | |
627 | |
628 @node Killing Buffers | |
629 @section Killing Buffers | |
630 @cindex killing buffers | |
631 @cindex buffers, killing | |
632 | |
633 @dfn{Killing a buffer} makes its name unknown to Emacs and makes its | |
634 text space available for other use. | |
635 | |
636 The buffer object for the buffer that has been killed remains in | |
637 existence as long as anything refers to it, but it is specially marked | |
638 so that you cannot make it current or display it. Killed buffers retain | |
639 their identity, however; two distinct buffers, when killed, remain | |
640 distinct according to @code{eq}. | |
641 | |
642 If you kill a buffer that is current or displayed in a window, Emacs | |
643 automatically selects or displays some other buffer instead. This means | |
644 that killing a buffer can in general change the current buffer. | |
645 Therefore, when you kill a buffer, you should also take the precautions | |
646 associated with changing the current buffer (unless you happen to know | |
647 that the buffer being killed isn't current). @xref{Current Buffer}. | |
648 | |
649 The @code{buffer-name} of a killed buffer is @code{nil}. You can use | |
650 this feature to test whether a buffer has been killed: | |
651 | |
652 @example | |
653 @group | |
654 (defun buffer-killed-p (buffer) | |
655 "Return t if BUFFER is killed." | |
656 (not (buffer-name buffer))) | |
657 @end group | |
658 @end example | |
659 | |
660 @deffn Command kill-buffer buffer-or-name | |
661 This function kills the buffer @var{buffer-or-name}, freeing all its | |
662 memory for use as space for other buffers. (Emacs version 18 and older | |
663 was unable to return the memory to the operating system.) It returns | |
664 @code{nil}. | |
665 | |
666 Any processes that have this buffer as the @code{process-buffer} are | |
667 sent the @code{SIGHUP} signal, which normally causes them to terminate. | |
668 (The basic meaning of @code{SIGHUP} is that a dialup line has been | |
669 disconnected.) @xref{Deleting Processes}. | |
670 | |
671 If the buffer is visiting a file and contains unsaved changes, | |
672 @code{kill-buffer} asks the user to confirm before the buffer is killed. | |
673 It does this even if not called interactively. To prevent the request | |
674 for confirmation, clear the modified flag before calling | |
675 @code{kill-buffer}. @xref{Buffer Modification}. | |
676 | |
677 Killing a buffer that is already dead has no effect. | |
678 | |
679 @smallexample | |
680 (kill-buffer "foo.unchanged") | |
681 @result{} nil | |
682 (kill-buffer "foo.changed") | |
683 | |
684 ---------- Buffer: Minibuffer ---------- | |
685 Buffer foo.changed modified; kill anyway? (yes or no) @kbd{yes} | |
686 ---------- Buffer: Minibuffer ---------- | |
687 | |
688 @result{} nil | |
689 @end smallexample | |
690 @end deffn | |
691 | |
692 @defvar kill-buffer-query-functions | |
693 After confirming unsaved changes, @code{kill-buffer} calls the functions | |
694 in the list @code{kill-buffer-query-functions}, in order of appearance, | |
695 with no arguments. The buffer being killed is the current buffer when | |
696 they are called. The idea is that these functions ask for confirmation | |
697 from the user for various nonstandard reasons. If any of them returns | |
698 @code{nil}, @code{kill-buffer} spares the buffer's life. | |
699 @end defvar | |
700 | |
701 @defvar kill-buffer-hook | |
702 This is a normal hook run by @code{kill-buffer} after asking all the | |
703 questions it is going to ask, just before actually killing the buffer. | |
704 The buffer to be killed is current when the hook functions run. | |
705 @xref{Hooks}. | |
706 @end defvar | |
707 | |
708 @defvar buffer-offer-save | |
709 This variable, if non-@code{nil} in a particular buffer, tells | |
710 @code{save-buffers-kill-emacs} and @code{save-some-buffers} to offer to | |
711 save that buffer, just as they offer to save file-visiting buffers. The | |
712 variable @code{buffer-offer-save} automatically becomes buffer-local | |
713 when set for any reason. @xref{Buffer-Local Variables}. | |
714 @end defvar | |
715 | 78 |
716 @node Current Buffer | 79 @node Current Buffer |
717 @section The Current Buffer | 80 @section The Current Buffer |
718 @cindex selecting a buffer | 81 @cindex selecting a buffer |
719 @cindex changing to another buffer | 82 @cindex changing to another buffer |
834 | 197 |
835 This function returns the buffer identified by @var{buffer-or-name}. | 198 This function returns the buffer identified by @var{buffer-or-name}. |
836 An error is signaled if @var{buffer-or-name} does not identify an | 199 An error is signaled if @var{buffer-or-name} does not identify an |
837 existing buffer. | 200 existing buffer. |
838 @end defun | 201 @end defun |
202 | |
203 @node Buffer Names | |
204 @section Buffer Names | |
205 @cindex buffer names | |
206 | |
207 Each buffer has a unique name, which is a string. Many of the | |
208 functions that work on buffers accept either a buffer or a buffer name | |
209 as an argument. Any argument called @var{buffer-or-name} is of this | |
210 sort, and an error is signaled if it is neither a string nor a buffer. | |
211 Any argument called @var{buffer} must be an actual buffer | |
212 object, not a name. | |
213 | |
214 Buffers that are ephemeral and generally uninteresting to the user | |
215 have names starting with a space, so that the @code{list-buffers} or | |
216 @code{buffer-menu} commands don't mention them. A name starting with | |
217 space also initially disables recording undo information; see | |
218 @ref{Undo}. | |
219 | |
220 @defun buffer-name &optional buffer | |
221 This function returns the name of @var{buffer} as a string. If | |
222 @var{buffer} is not supplied, it defaults to the current buffer. | |
223 | |
224 If @code{buffer-name} returns @code{nil}, it means that @var{buffer} | |
225 has been killed. @xref{Killing Buffers}. | |
226 | |
227 @example | |
228 @group | |
229 (buffer-name) | |
230 @result{} "buffers.texi" | |
231 @end group | |
232 | |
233 @group | |
234 (setq foo (get-buffer "temp")) | |
235 @result{} #<buffer temp> | |
236 @end group | |
237 @group | |
238 (kill-buffer foo) | |
239 @result{} nil | |
240 @end group | |
241 @group | |
242 (buffer-name foo) | |
243 @result{} nil | |
244 @end group | |
245 @group | |
246 foo | |
247 @result{} #<killed buffer> | |
248 @end group | |
249 @end example | |
250 @end defun | |
251 | |
252 @deffn Command rename-buffer newname &optional unique | |
253 This function renames the current buffer to @var{newname}. An error | |
254 is signaled if @var{newname} is not a string, or if there is already a | |
255 buffer with that name. The function returns @code{nil}. | |
256 | |
257 @c Emacs 19 feature | |
258 Ordinarily, @code{rename-buffer} signals an error if @var{newname} is | |
259 already in use. However, if @var{unique} is non-@code{nil}, it modifies | |
260 @var{newname} to make a name that is not in use. Interactively, you can | |
261 make @var{unique} non-@code{nil} with a numeric prefix argument. | |
262 | |
263 One application of this command is to rename the @samp{*shell*} buffer | |
264 to some other name, thus making it possible to create a second shell | |
265 buffer under the name @samp{*shell*}. | |
266 @end deffn | |
267 | |
268 @defun get-buffer buffer-or-name | |
269 This function returns the buffer specified by @var{buffer-or-name}. | |
270 If @var{buffer-or-name} is a string and there is no buffer with that | |
271 name, the value is @code{nil}. If @var{buffer-or-name} is a buffer, it | |
272 is returned as given. (That is not very useful, so the argument is usually | |
273 a name.) For example: | |
274 | |
275 @example | |
276 @group | |
277 (setq b (get-buffer "lewis")) | |
278 @result{} #<buffer lewis> | |
279 @end group | |
280 @group | |
281 (get-buffer b) | |
282 @result{} #<buffer lewis> | |
283 @end group | |
284 @group | |
285 (get-buffer "Frazzle-nots") | |
286 @result{} nil | |
287 @end group | |
288 @end example | |
289 | |
290 See also the function @code{get-buffer-create} in @ref{Creating Buffers}. | |
291 @end defun | |
292 | |
293 @c Emacs 19 feature | |
294 @defun generate-new-buffer-name starting-name | |
295 This function returns a name that would be unique for a new buffer---but | |
296 does not create the buffer. It starts with @var{starting-name}, and | |
297 produces a name not currently in use for any buffer by appending a | |
298 number inside of @samp{<@dots{}>}. | |
299 | |
300 See the related function @code{generate-new-buffer} in @ref{Creating | |
301 Buffers}. | |
302 @end defun | |
303 | |
304 @node Buffer File Name | |
305 @section Buffer File Name | |
306 @cindex visited file | |
307 @cindex buffer file name | |
308 @cindex file name of buffer | |
309 | |
310 The @dfn{buffer file name} is the name of the file that is visited in | |
311 that buffer. When a buffer is not visiting a file, its buffer file name | |
312 is @code{nil}. Most of the time, the buffer name is the same as the | |
313 nondirectory part of the buffer file name, but the buffer file name and | |
314 the buffer name are distinct and can be set independently. | |
315 @xref{Visiting Files}. | |
316 | |
317 @defun buffer-file-name &optional buffer | |
318 This function returns the absolute file name of the file that | |
319 @var{buffer} is visiting. If @var{buffer} is not visiting any file, | |
320 @code{buffer-file-name} returns @code{nil}. If @var{buffer} is not | |
321 supplied, it defaults to the current buffer. | |
322 | |
323 @example | |
324 @group | |
325 (buffer-file-name (other-buffer)) | |
326 @result{} "/usr/user/lewis/manual/files.texi" | |
327 @end group | |
328 @end example | |
329 @end defun | |
330 | |
331 @defvar buffer-file-name | |
332 This buffer-local variable contains the name of the file being visited | |
333 in the current buffer, or @code{nil} if it is not visiting a file. It | |
334 is a permanent local, unaffected by @code{kill-local-variables}. | |
335 | |
336 @example | |
337 @group | |
338 buffer-file-name | |
339 @result{} "/usr/user/lewis/manual/buffers.texi" | |
340 @end group | |
341 @end example | |
342 | |
343 It is risky to change this variable's value without doing various other | |
344 things. See the definition of @code{set-visited-file-name} in | |
345 @file{files.el}; some of the things done there, such as changing the | |
346 buffer name, are not strictly necessary, but others are essential to | |
347 avoid confusing Emacs. | |
348 @end defvar | |
349 | |
350 @defvar buffer-file-truename | |
351 This buffer-local variable holds the truename of the file visited in the | |
352 current buffer, or @code{nil} if no file is visited. It is a permanent | |
353 local, unaffected by @code{kill-local-variables}. @xref{Truenames}. | |
354 @end defvar | |
355 | |
356 @defvar buffer-file-number | |
357 This buffer-local variable holds the file number and directory device | |
358 number of the file visited in the current buffer, or @code{nil} if no | |
359 file or a nonexistent file is visited. It is a permanent local, | |
360 unaffected by @code{kill-local-variables}. @xref{Truenames}. | |
361 | |
362 The value is normally a list of the form @code{(@var{filenum} | |
363 @var{devnum})}. This pair of numbers uniquely identifies the file among | |
364 all files accessible on the system. See the function | |
365 @code{file-attributes}, in @ref{File Attributes}, for more information | |
366 about them. | |
367 @end defvar | |
368 | |
369 @defun get-file-buffer filename | |
370 This function returns the buffer visiting file @var{filename}. If | |
371 there is no such buffer, it returns @code{nil}. The argument | |
372 @var{filename}, which must be a string, is expanded (@pxref{File Name | |
373 Expansion}), then compared against the visited file names of all live | |
374 buffers. | |
375 | |
376 @example | |
377 @group | |
378 (get-file-buffer "buffers.texi") | |
379 @result{} #<buffer buffers.texi> | |
380 @end group | |
381 @end example | |
382 | |
383 In unusual circumstances, there can be more than one buffer visiting | |
384 the same file name. In such cases, this function returns the first | |
385 such buffer in the buffer list. | |
386 @end defun | |
387 | |
388 @deffn Command set-visited-file-name filename | |
389 If @var{filename} is a non-empty string, this function changes the | |
390 name of the file visited in current buffer to @var{filename}. (If the | |
391 buffer had no visited file, this gives it one.) The @emph{next time} | |
392 the buffer is saved it will go in the newly-specified file. This | |
393 command marks the buffer as modified, since it does not (as far as Emacs | |
394 knows) match the contents of @var{filename}, even if it matched the | |
395 former visited file. | |
396 | |
397 If @var{filename} is @code{nil} or the empty string, that stands for | |
398 ``no visited file''. In this case, @code{set-visited-file-name} marks | |
399 the buffer as having no visited file. | |
400 | |
401 @c Wordy to avoid overfull hbox. --rjc 16mar92 | |
402 When the function @code{set-visited-file-name} is called interactively, it | |
403 prompts for @var{filename} in the minibuffer. | |
404 | |
405 See also @code{clear-visited-file-modtime} and | |
406 @code{verify-visited-file-modtime} in @ref{Buffer Modification}. | |
407 @end deffn | |
408 | |
409 @defvar list-buffers-directory | |
410 This buffer-local variable records a string to display in a buffer | |
411 listing in place of the visited file name, for buffers that don't have a | |
412 visited file name. Dired buffers use this variable. | |
413 @end defvar | |
414 | |
415 @node Buffer Modification | |
416 @section Buffer Modification | |
417 @cindex buffer modification | |
418 @cindex modification flag (of buffer) | |
419 | |
420 Emacs keeps a flag called the @dfn{modified flag} for each buffer, to | |
421 record whether you have changed the text of the buffer. This flag is | |
422 set to @code{t} whenever you alter the contents of the buffer, and | |
423 cleared to @code{nil} when you save it. Thus, the flag shows whether | |
424 there are unsaved changes. The flag value is normally shown in the mode | |
425 line (@pxref{Mode Line Variables}), and controls saving (@pxref{Saving | |
426 Buffers}) and auto-saving (@pxref{Auto-Saving}). | |
427 | |
428 Some Lisp programs set the flag explicitly. For example, the function | |
429 @code{set-visited-file-name} sets the flag to @code{t}, because the text | |
430 does not match the newly-visited file, even if it is unchanged from the | |
431 file formerly visited. | |
432 | |
433 The functions that modify the contents of buffers are described in | |
434 @ref{Text}. | |
435 | |
436 @defun buffer-modified-p &optional buffer | |
437 This function returns @code{t} if the buffer @var{buffer} has been modified | |
438 since it was last read in from a file or saved, or @code{nil} | |
439 otherwise. If @var{buffer} is not supplied, the current buffer | |
440 is tested. | |
441 @end defun | |
442 | |
443 @defun set-buffer-modified-p flag | |
444 This function marks the current buffer as modified if @var{flag} is | |
445 non-@code{nil}, or as unmodified if the flag is @code{nil}. | |
446 | |
447 Another effect of calling this function is to cause unconditional | |
448 redisplay of the mode line for the current buffer. In fact, the | |
449 function @code{force-mode-line-update} works by doing this: | |
450 | |
451 @example | |
452 @group | |
453 (set-buffer-modified-p (buffer-modified-p)) | |
454 @end group | |
455 @end example | |
456 @end defun | |
457 | |
458 @deffn Command not-modified | |
459 This command marks the current buffer as unmodified, and not needing | |
460 to be saved. Don't use this function in programs, since it prints a | |
461 message in the echo area; use @code{set-buffer-modified-p} (above) instead. | |
462 @end deffn | |
463 | |
464 @c Emacs 19 feature | |
465 @defun buffer-modified-tick &optional buffer | |
466 This function returns @var{buffer}`s modification-count. This is a | |
467 counter that increments every time the buffer is modified. If | |
468 @var{buffer} is @code{nil} (or omitted), the current buffer is used. | |
469 @end defun | |
470 | |
471 @node Modification Time | |
472 @comment node-name, next, previous, up | |
473 @section Comparison of Modification Time | |
474 @cindex comparison of modification time | |
475 @cindex modification time, comparison of | |
476 | |
477 Suppose that you visit a file and make changes in its buffer, and | |
478 meanwhile the file itself is changed on disk. At this point, saving the | |
479 buffer would overwrite the changes in the file. Occasionally this may | |
480 be what you want, but usually it would lose valuable information. Emacs | |
481 therefore checks the file's modification time using the functions | |
482 described below before saving the file. | |
483 | |
484 @defun verify-visited-file-modtime buffer | |
485 This function compares what @var{buffer} has recorded for the | |
486 modification time of its visited file against the actual modification | |
487 time of the file as recorded by the operating system. The two should be | |
488 the same unless some other process has written the file since Emacs | |
489 visited or saved it. | |
490 | |
491 The function returns @code{t} if the last actual modification time and | |
492 Emacs's recorded modification time are the same, @code{nil} otherwise. | |
493 @end defun | |
494 | |
495 @defun clear-visited-file-modtime | |
496 This function clears out the record of the last modification time of | |
497 the file being visited by the current buffer. As a result, the next | |
498 attempt to save this buffer will not complain of a discrepancy in | |
499 file modification times. | |
500 | |
501 This function is called in @code{set-visited-file-name} and other | |
502 exceptional places where the usual test to avoid overwriting a changed | |
503 file should not be done. | |
504 @end defun | |
505 | |
506 @c Emacs 19 feature | |
507 @defun visited-file-modtime | |
508 This function returns the buffer's recorded last file modification time, | |
509 as a list of the form @code{(@var{high} . @var{low})}. (This is the | |
510 same format that @code{file-attributes} uses to return time values; see | |
511 @ref{File Attributes}.) | |
512 @end defun | |
513 | |
514 @c Emacs 19 feature | |
515 @defun set-visited-file-modtime &optional time | |
516 This function updates the buffer's record of the last modification time | |
517 of the visited file, to the value specified by @var{time} if @var{time} | |
518 is not @code{nil}, and otherwise to the last modification time of the | |
519 visited file. | |
520 | |
521 If @var{time} is not @code{nil}, it should have the form | |
522 @code{(@var{high} . @var{low})} or @code{(@var{high} @var{low})}, in | |
523 either case containing two integers, each of which holds 16 bits of the | |
524 time. | |
525 | |
526 This function is useful if the buffer was not read from the file | |
527 normally, or if the file itself has been changed for some known benign | |
528 reason. | |
529 @end defun | |
530 | |
531 @defun ask-user-about-supersession-threat filename | |
532 @cindex obsolete buffer | |
533 This function is used to ask a user how to proceed after an attempt to | |
534 modify an obsolete buffer visiting file @var{filename}. An | |
535 @dfn{obsolete buffer} is an unmodified buffer for which the associated | |
536 file on disk is newer than the last save-time of the buffer. This means | |
537 some other program has probably altered the file. | |
538 | |
539 @kindex file-supersession | |
540 Depending on the user's answer, the function may return normally, in | |
541 which case the modification of the buffer proceeds, or it may signal a | |
542 @code{file-supersession} error with data @code{(@var{filename})}, in which | |
543 case the proposed buffer modification is not allowed. | |
544 | |
545 This function is called automatically by Emacs on the proper | |
546 occasions. It exists so you can customize Emacs by redefining it. | |
547 See the file @file{userlock.el} for the standard definition. | |
548 | |
549 See also the file locking mechanism in @ref{File Locks}. | |
550 @end defun | |
551 | |
552 @node Read Only Buffers | |
553 @section Read-Only Buffers | |
554 @cindex read-only buffer | |
555 @cindex buffer, read-only | |
556 | |
557 If a buffer is @dfn{read-only}, then you cannot change its contents, | |
558 although you may change your view of the contents by scrolling and | |
559 narrowing. | |
560 | |
561 Read-only buffers are used in two kinds of situations: | |
562 | |
563 @itemize @bullet | |
564 @item | |
565 A buffer visiting a write-protected file is normally read-only. | |
566 | |
567 Here, the purpose is to show the user that editing the buffer with the | |
568 aim of saving it in the file may be futile or undesirable. The user who | |
569 wants to change the buffer text despite this can do so after clearing | |
570 the read-only flag with @kbd{C-M-q}. | |
571 | |
572 @item | |
573 Modes such as Dired and Rmail make buffers read-only when altering the | |
574 contents with the usual editing commands is probably a mistake. | |
575 | |
576 The special commands of these modes bind @code{buffer-read-only} to | |
577 @code{nil} (with @code{let}) or bind @code{inhibit-read-only} to | |
578 @code{t} around the places where they change the text. | |
579 @end itemize | |
580 | |
581 @defvar buffer-read-only | |
582 This buffer-local variable specifies whether the buffer is read-only. | |
583 The buffer is read-only if this variable is non-@code{nil}. | |
584 @end defvar | |
585 | |
586 @defvar inhibit-read-only | |
587 If this variable is non-@code{nil}, then read-only buffers and read-only | |
588 characters may be modified. Read-only characters in a buffer are those | |
589 that have non-@code{nil} @code{read-only} properties (either text | |
590 properties or overlay properties). @xref{Special Properties}, for more | |
591 information about text properties. @xref{Overlays}, for more | |
592 information about overlays and their properties. | |
593 | |
594 If @code{inhibit-read-only} is @code{t}, all @code{read-only} character | |
595 properties have no effect. If @code{inhibit-read-only} is a list, then | |
596 @code{read-only} character properties have no effect if they are members | |
597 of the list (comparison is done with @code{eq}). | |
598 @end defvar | |
599 | |
600 @deffn Command toggle-read-only | |
601 This command changes whether the current buffer is read-only. It is | |
602 intended for interactive use; don't use it in programs. At any given | |
603 point in a program, you should know whether you want the read-only flag | |
604 on or off; so you can set @code{buffer-read-only} explicitly to the | |
605 proper value, @code{t} or @code{nil}. | |
606 @end deffn | |
607 | |
608 @defun barf-if-buffer-read-only | |
609 This function signals a @code{buffer-read-only} error if the current | |
610 buffer is read-only. @xref{Interactive Call}, for another way to | |
611 signal an error if the current buffer is read-only. | |
612 @end defun | |
613 | |
614 @node The Buffer List | |
615 @section The Buffer List | |
616 @cindex buffer list | |
617 | |
618 The @dfn{buffer list} is a list of all live buffers. Creating a | |
619 buffer adds it to this list, and killing a buffer deletes it. The order | |
620 of the buffers in the list is based primarily on how recently each | |
621 buffer has been displayed in the selected window. Buffers move to the | |
622 front of the list when they are selected and to the end when they are | |
623 buried. Several functions, notably @code{other-buffer}, use this | |
624 ordering. A buffer list displayed for the user also follows this order. | |
625 | |
626 @defun buffer-list | |
627 This function returns a list of all buffers, including those whose names | |
628 begin with a space. The elements are actual buffers, not their names. | |
629 | |
630 @example | |
631 @group | |
632 (buffer-list) | |
633 @result{} (#<buffer buffers.texi> | |
634 #<buffer *Minibuf-1*> #<buffer buffer.c> | |
635 #<buffer *Help*> #<buffer TAGS>) | |
636 @end group | |
637 | |
638 @group | |
639 ;; @r{Note that the name of the minibuffer} | |
640 ;; @r{begins with a space!} | |
641 (mapcar (function buffer-name) (buffer-list)) | |
642 @result{} ("buffers.texi" " *Minibuf-1*" | |
643 "buffer.c" "*Help*" "TAGS") | |
644 @end group | |
645 @end example | |
646 | |
647 This list is a copy of a list used inside Emacs; modifying it has no | |
648 effect on the ordering of buffers. | |
649 @end defun | |
650 | |
651 @defun other-buffer &optional buffer-or-name visible-ok | |
652 This function returns the first buffer in the buffer list other than | |
653 @var{buffer-or-name}. Usually this is the buffer most recently shown in | |
654 the selected window, aside from @var{buffer-or-name}. Buffers whose | |
655 names start with a space are not considered. | |
656 | |
657 If @var{buffer-or-name} is not supplied (or if it is not a buffer), | |
658 then @code{other-buffer} returns the first buffer on the buffer list | |
659 that is not visible in any window in a visible frame. | |
660 | |
661 If the selected frame has a non-@code{nil} @code{buffer-predicate} | |
662 parameter, then @code{other-buffer} uses that predicate to decide which | |
663 buffers to consider. It calls the predicate once for each buffer, and | |
664 if the value is @code{nil}, that buffer is ignored. @xref{X Frame | |
665 Parameters}. | |
666 | |
667 @c Emacs 19 feature | |
668 If @var{visible-ok} is @code{nil}, @code{other-buffer} avoids returning | |
669 a buffer visible in any window on any visible frame, except as a last | |
670 resort. If @var{visible-ok} is non-@code{nil}, then it does not matter | |
671 whether a buffer is displayed somewhere or not. | |
672 | |
673 If no suitable buffer exists, the buffer @samp{*scratch*} is returned | |
674 (and created, if necessary). | |
675 @end defun | |
676 | |
677 @deffn Command bury-buffer &optional buffer-or-name | |
678 This function puts @var{buffer-or-name} at the end of the buffer list | |
679 without changing the order of any of the other buffers on the list. | |
680 This buffer therefore becomes the least desirable candidate for | |
681 @code{other-buffer} to return. | |
682 | |
683 If @var{buffer-or-name} is @code{nil} or omitted, this means to bury the | |
684 current buffer. In addition, if the buffer is displayed in the selected | |
685 window, this switches to some other buffer (obtained using | |
686 @code{other-buffer}) in the selected window. But if the buffer is | |
687 displayed in some other window, it remains displayed there. | |
688 | |
689 If you wish to replace a buffer in all the windows that display it, use | |
690 @code{replace-buffer-in-windows}. @xref{Buffers and Windows}. | |
691 @end deffn | |
692 | |
693 @node Creating Buffers | |
694 @section Creating Buffers | |
695 @cindex creating buffers | |
696 @cindex buffers, creating | |
697 | |
698 This section describes the two primitives for creating buffers. | |
699 @code{get-buffer-create} creates a buffer if it finds no existing buffer | |
700 with the specified name; @code{generate-new-buffer} always creates a new | |
701 buffer and gives it a unique name. | |
702 | |
703 Other functions you can use to create buffers include | |
704 @code{with-output-to-temp-buffer} (@pxref{Temporary Displays}) and | |
705 @code{create-file-buffer} (@pxref{Visiting Files}). Starting a | |
706 subprocess can also create a buffer (@pxref{Processes}). | |
707 | |
708 @defun get-buffer-create name | |
709 This function returns a buffer named @var{name}. It returns an existing | |
710 buffer with that name, if one exists; otherwise, it creates a new | |
711 buffer. The buffer does not become the current buffer---this function | |
712 does not change which buffer is current. | |
713 | |
714 An error is signaled if @var{name} is not a string. | |
715 | |
716 @example | |
717 @group | |
718 (get-buffer-create "foo") | |
719 @result{} #<buffer foo> | |
720 @end group | |
721 @end example | |
722 | |
723 The major mode for the new buffer is set to Fundamental mode. The | |
724 variable @code{default-major-mode} is handled at a higher level. | |
725 @xref{Auto Major Mode}. | |
726 @end defun | |
727 | |
728 @defun generate-new-buffer name | |
729 This function returns a newly created, empty buffer, but does not make | |
730 it current. If there is no buffer named @var{name}, then that is the | |
731 name of the new buffer. If that name is in use, this function adds | |
732 suffixes of the form @samp{<@var{n}>} to @var{name}, where @var{n} is an | |
733 integer. It tries successive integers starting with 2 until it finds an | |
734 available name. | |
735 | |
736 An error is signaled if @var{name} is not a string. | |
737 | |
738 @example | |
739 @group | |
740 (generate-new-buffer "bar") | |
741 @result{} #<buffer bar> | |
742 @end group | |
743 @group | |
744 (generate-new-buffer "bar") | |
745 @result{} #<buffer bar<2>> | |
746 @end group | |
747 @group | |
748 (generate-new-buffer "bar") | |
749 @result{} #<buffer bar<3>> | |
750 @end group | |
751 @end example | |
752 | |
753 The major mode for the new buffer is set to Fundamental mode. The | |
754 variable @code{default-major-mode} is handled at a higher level. | |
755 @xref{Auto Major Mode}. | |
756 | |
757 See the related function @code{generate-new-buffer-name} in @ref{Buffer | |
758 Names}. | |
759 @end defun | |
760 | |
761 @node Killing Buffers | |
762 @section Killing Buffers | |
763 @cindex killing buffers | |
764 @cindex buffers, killing | |
765 | |
766 @dfn{Killing a buffer} makes its name unknown to Emacs and makes its | |
767 text space available for other use. | |
768 | |
769 The buffer object for the buffer that has been killed remains in | |
770 existence as long as anything refers to it, but it is specially marked | |
771 so that you cannot make it current or display it. Killed buffers retain | |
772 their identity, however; two distinct buffers, when killed, remain | |
773 distinct according to @code{eq}. | |
774 | |
775 If you kill a buffer that is current or displayed in a window, Emacs | |
776 automatically selects or displays some other buffer instead. This means | |
777 that killing a buffer can in general change the current buffer. | |
778 Therefore, when you kill a buffer, you should also take the precautions | |
779 associated with changing the current buffer (unless you happen to know | |
780 that the buffer being killed isn't current). @xref{Current Buffer}. | |
781 | |
782 The @code{buffer-name} of a killed buffer is @code{nil}. You can use | |
783 this feature to test whether a buffer has been killed: | |
784 | |
785 @example | |
786 @group | |
787 (defun buffer-killed-p (buffer) | |
788 "Return t if BUFFER is killed." | |
789 (not (buffer-name buffer))) | |
790 @end group | |
791 @end example | |
792 | |
793 @deffn Command kill-buffer buffer-or-name | |
794 This function kills the buffer @var{buffer-or-name}, freeing all its | |
795 memory for use as space for other buffers. (Emacs version 18 and older | |
796 was unable to return the memory to the operating system.) It returns | |
797 @code{nil}. | |
798 | |
799 Any processes that have this buffer as the @code{process-buffer} are | |
800 sent the @code{SIGHUP} signal, which normally causes them to terminate. | |
801 (The basic meaning of @code{SIGHUP} is that a dialup line has been | |
802 disconnected.) @xref{Deleting Processes}. | |
803 | |
804 If the buffer is visiting a file and contains unsaved changes, | |
805 @code{kill-buffer} asks the user to confirm before the buffer is killed. | |
806 It does this even if not called interactively. To prevent the request | |
807 for confirmation, clear the modified flag before calling | |
808 @code{kill-buffer}. @xref{Buffer Modification}. | |
809 | |
810 Killing a buffer that is already dead has no effect. | |
811 | |
812 @smallexample | |
813 (kill-buffer "foo.unchanged") | |
814 @result{} nil | |
815 (kill-buffer "foo.changed") | |
816 | |
817 ---------- Buffer: Minibuffer ---------- | |
818 Buffer foo.changed modified; kill anyway? (yes or no) @kbd{yes} | |
819 ---------- Buffer: Minibuffer ---------- | |
820 | |
821 @result{} nil | |
822 @end smallexample | |
823 @end deffn | |
824 | |
825 @defvar kill-buffer-query-functions | |
826 After confirming unsaved changes, @code{kill-buffer} calls the functions | |
827 in the list @code{kill-buffer-query-functions}, in order of appearance, | |
828 with no arguments. The buffer being killed is the current buffer when | |
829 they are called. The idea is that these functions ask for confirmation | |
830 from the user for various nonstandard reasons. If any of them returns | |
831 @code{nil}, @code{kill-buffer} spares the buffer's life. | |
832 @end defvar | |
833 | |
834 @defvar kill-buffer-hook | |
835 This is a normal hook run by @code{kill-buffer} after asking all the | |
836 questions it is going to ask, just before actually killing the buffer. | |
837 The buffer to be killed is current when the hook functions run. | |
838 @xref{Hooks}. | |
839 @end defvar | |
840 | |
841 @defvar buffer-offer-save | |
842 This variable, if non-@code{nil} in a particular buffer, tells | |
843 @code{save-buffers-kill-emacs} and @code{save-some-buffers} to offer to | |
844 save that buffer, just as they offer to save file-visiting buffers. The | |
845 variable @code{buffer-offer-save} automatically becomes buffer-local | |
846 when set for any reason. @xref{Buffer-Local Variables}. | |
847 @end defvar | |
848 | |
849 @node Indirect Buffers | |
850 @section Indirect Buffers | |
851 @cindex indirect buffers | |
852 @cindex base buffer | |
853 | |
854 An @dfn{indirect buffer} shares the text of some other buffer, which | |
855 is called the @dfn{base buffer} of the indirect buffer. In some ways it | |
856 is the equivalent, for buffers, of a symbolic link among files. The base | |
857 buffer may not itself be an indirect buffer. | |
858 | |
859 The text of the indirect buffer is always identical to the text of its | |
860 base buffer; changes made by editing either one are visible immediately | |
861 in the other. This includes the text properties as well as the characters | |
862 themselves. | |
863 | |
864 But in all other respects, the indirect buffer and its base buffer are | |
865 completely separate. They have different names, different values of | |
866 point, different narrowing, different markers and overlays (though | |
867 inserting or deleting text in either buffer relocates the markers and | |
868 overlays for both), different major modes, and different local | |
869 variables. | |
870 | |
871 An indirect buffer cannot visit a file, but its base buffer can. If | |
872 you try to save the indirect buffer, that actually works by saving the | |
873 base buffer. | |
874 | |
875 Killing an indirect buffer has no effect on its base buffer. Killing | |
876 the base buffer effectively kills the indirect buffer in that it cannot | |
877 ever again be the current buffer. | |
878 | |
879 @deffn Command make-indirect-buffer base-buffer name | |
880 This creates an indirect buffer named @var{name} whose base buffer | |
881 is @var{base-buffer}. The argument @var{base-buffer} may be a buffer | |
882 or a string. | |
883 | |
884 If @var{base-buffer} is an indirect buffer, its base buffer is used as | |
885 the base for the new buffer. | |
886 @end deffn | |
887 | |
888 @defun buffer-base-buffer buffer | |
889 This function returns the base buffer of @var{buffer}. If @var{buffer} | |
890 is not indirect, the value is @code{nil}. Otherwise, the value is | |
891 another buffer, which is never an indirect buffer. | |
892 @end defun | |
893 |