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