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