annotate lispref/buffers.texi @ 19131:962be4e083c2

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