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