annotate doc/lispref/buffers.texi @ 98978:f570df2cc52d

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