1 This is ../info/lispref.info, produced by makeinfo version 4.0 from
4 INFO-DIR-SECTION XEmacs Editor
6 * Lispref: (lispref). XEmacs Lisp Reference Manual.
11 GNU Emacs Lisp Reference Manual Second Edition (v2.01), May 1993 GNU
12 Emacs Lisp Reference Manual Further Revised (v2.02), August 1993 Lucid
13 Emacs Lisp Reference Manual (for 19.10) First Edition, March 1994
14 XEmacs Lisp Programmer's Manual (for 19.12) Second Edition, April 1995
15 GNU Emacs Lisp Reference Manual v2.4, June 1995 XEmacs Lisp
16 Programmer's Manual (for 19.13) Third Edition, July 1995 XEmacs Lisp
17 Reference Manual (for 19.14 and 20.0) v3.1, March 1996 XEmacs Lisp
18 Reference Manual (for 19.15 and 20.1, 20.2, 20.3) v3.2, April, May,
19 November 1997 XEmacs Lisp Reference Manual (for 21.0) v3.3, April 1998
21 Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Free Software
22 Foundation, Inc. Copyright (C) 1994, 1995 Sun Microsystems, Inc.
23 Copyright (C) 1995, 1996 Ben Wing.
25 Permission is granted to make and distribute verbatim copies of this
26 manual provided the copyright notice and this permission notice are
27 preserved on all copies.
29 Permission is granted to copy and distribute modified versions of
30 this manual under the conditions for verbatim copying, provided that the
31 entire resulting derived work is distributed under the terms of a
32 permission notice identical to this one.
34 Permission is granted to copy and distribute translations of this
35 manual into another language, under the above conditions for modified
36 versions, except that this permission notice may be stated in a
37 translation approved by the Foundation.
39 Permission is granted to copy and distribute modified versions of
40 this manual under the conditions for verbatim copying, provided also
41 that the section entitled "GNU General Public License" is included
42 exactly as in the original, and provided that the entire resulting
43 derived work is distributed under the terms of a permission notice
44 identical to this one.
46 Permission is granted to copy and distribute translations of this
47 manual into another language, under the above conditions for modified
48 versions, except that the section entitled "GNU General Public License"
49 may be included in a translation approved by the Free Software
50 Foundation instead of in the original English.
53 File: lispref.info, Node: Buffer Basics, Next: Current Buffer, Up: Buffers
58 A "buffer" is a Lisp object containing text to be edited. Buffers
59 are used to hold the contents of files that are being visited; there may
60 also be buffers that are not visiting files. While several buffers may
61 exist at one time, exactly one buffer is designated the "current
62 buffer" at any time. Most editing commands act on the contents of the
63 current buffer. Each buffer, including the current buffer, may or may
64 not be displayed in any windows.
66 Buffers in Emacs editing are objects that have distinct names and
67 hold text that can be edited. Buffers appear to Lisp programs as a
68 special data type. You can think of the contents of a buffer as an
69 extendable string; insertions and deletions may occur in any part of
70 the buffer. *Note Text::.
72 A Lisp buffer object contains numerous pieces of information. Some
73 of this information is directly accessible to the programmer through
74 variables, while other information is accessible only through
75 special-purpose functions. For example, the visited file name is
76 directly accessible through a variable, while the value of point is
77 accessible only through a primitive function.
79 Buffer-specific information that is directly accessible is stored in
80 "buffer-local" variable bindings, which are variable values that are
81 effective only in a particular buffer. This feature allows each buffer
82 to override the values of certain variables. Most major modes override
83 variables such as `fill-column' or `comment-column' in this way. For
84 more information about buffer-local variables and functions related to
85 them, see *Note Buffer-Local Variables::.
87 For functions and variables related to visiting files in buffers, see
88 *Note Visiting Files:: and *Note Saving Buffers::. For functions and
89 variables related to the display of buffers in windows, see *Note
90 Buffers and Windows::.
92 - Function: bufferp object
93 This function returns `t' if OBJECT is a buffer, `nil' otherwise.
96 File: lispref.info, Node: Current Buffer, Next: Buffer Names, Prev: Buffer Basics, Up: Buffers
101 There are, in general, many buffers in an Emacs session. At any
102 time, one of them is designated as the "current buffer". This is the
103 buffer in which most editing takes place, because most of the primitives
104 for examining or changing text in a buffer operate implicitly on the
105 current buffer (*note Text::). Normally the buffer that is displayed on
106 the screen in the selected window is the current buffer, but this is not
107 always so: a Lisp program can designate any buffer as current
108 temporarily in order to operate on its contents, without changing what
109 is displayed on the screen.
111 The way to designate a current buffer in a Lisp program is by calling
112 `set-buffer'. The specified buffer remains current until a new one is
115 When an editing command returns to the editor command loop, the
116 command loop designates the buffer displayed in the selected window as
117 current, to prevent confusion: the buffer that the cursor is in when
118 Emacs reads a command is the buffer that the command will apply to.
119 (*Note Command Loop::.) Therefore, `set-buffer' is not the way to
120 switch visibly to a different buffer so that the user can edit it. For
121 this, you must use the functions described in *Note Displaying
124 However, Lisp functions that change to a different current buffer
125 should not depend on the command loop to set it back afterwards.
126 Editing commands written in XEmacs Lisp can be called from other
127 programs as well as from the command loop. It is convenient for the
128 caller if the subroutine does not change which buffer is current
129 (unless, of course, that is the subroutine's purpose). Therefore, you
130 should normally use `set-buffer' within a `save-excursion' that will
131 restore the current buffer when your function is done (*note
132 Excursions::). Here is an example, the code for the command
133 `append-to-buffer' (with the documentation string abridged):
135 (defun append-to-buffer (buffer start end)
136 "Append to specified buffer the text of the region.
138 (interactive "BAppend to buffer: \nr")
139 (let ((oldbuf (current-buffer)))
141 (set-buffer (get-buffer-create buffer))
142 (insert-buffer-substring oldbuf start end))))
144 This function binds a local variable to the current buffer, and then
145 `save-excursion' records the values of point, the mark, and the
146 original buffer. Next, `set-buffer' makes another buffer current.
147 Finally, `insert-buffer-substring' copies the string from the original
148 current buffer to the new current buffer.
150 If the buffer appended to happens to be displayed in some window,
151 the next redisplay will show how its text has changed. Otherwise, you
152 will not see the change immediately on the screen. The buffer becomes
153 current temporarily during the execution of the command, but this does
154 not cause it to be displayed.
156 If you make local bindings (with `let' or function arguments) for a
157 variable that may also have buffer-local bindings, make sure that the
158 same buffer is current at the beginning and at the end of the local
159 binding's scope. Otherwise you might bind it in one buffer and unbind
160 it in another! There are two ways to do this. In simple cases, you may
161 see that nothing ever changes the current buffer within the scope of the
162 binding. Otherwise, use `save-excursion' to make sure that the buffer
163 current at the beginning is current again whenever the variable is
166 It is not reliable to change the current buffer back with
167 `set-buffer', because that won't do the job if a quit happens while the
168 wrong buffer is current. Here is what _not_ to do:
170 (let (buffer-read-only
171 (obuf (current-buffer)))
176 Using `save-excursion', as shown below, handles quitting, errors, and
177 `throw', as well as ordinary evaluation.
179 (let (buffer-read-only)
184 - Function: current-buffer
185 This function returns the current buffer.
188 => #<buffer buffers.texi>
190 - Function: set-buffer buffer-or-name
191 This function makes BUFFER-OR-NAME the current buffer. It does
192 not display the buffer in the currently selected window or in any
193 other window, so the user cannot necessarily see the buffer. But
194 Lisp programs can in any case work on it.
196 This function returns the buffer identified by BUFFER-OR-NAME. An
197 error is signaled if BUFFER-OR-NAME does not identify an existing
201 File: lispref.info, Node: Buffer Names, Next: Buffer File Name, Prev: Current Buffer, Up: Buffers
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 BUFFER-OR-NAME is of this sort,
209 and an error is signaled if it is neither a string nor a buffer. Any
210 argument called BUFFER must be an actual buffer object, not a name.
212 Buffers that are ephemeral and generally uninteresting to the user
213 have names starting with a space, so that the `list-buffers' and
214 `buffer-menu' commands don't mention them. A name starting with space
215 also initially disables recording undo information; see *Note Undo::.
217 - Function: buffer-name &optional buffer
218 This function returns the name of BUFFER as a string. If BUFFER
219 is not supplied, it defaults to the current buffer.
221 If `buffer-name' returns `nil', it means that BUFFER has been
222 killed. *Note Killing Buffers::.
227 (setq foo (get-buffer "temp"))
236 - Command: rename-buffer newname &optional unique
237 This function renames the current buffer to NEWNAME. An error is
238 signaled if NEWNAME is not a string, or if there is already a
239 buffer with that name. The function returns `nil'.
241 Ordinarily, `rename-buffer' signals an error if NEWNAME is already
242 in use. However, if UNIQUE is non-`nil', it modifies NEWNAME to
243 make a name that is not in use. Interactively, you can make
244 UNIQUE non-`nil' with a numeric prefix argument.
246 One application of this command is to rename the `*shell*' buffer
247 to some other name, thus making it possible to create a second
248 shell buffer under the name `*shell*'.
250 - Function: get-buffer buffer-or-name
251 This function returns the buffer specified by BUFFER-OR-NAME. If
252 BUFFER-OR-NAME is a string and there is no buffer with that name,
253 the value is `nil'. If BUFFER-OR-NAME is a buffer, it is returned
254 as given. (That is not very useful, so the argument is usually a
257 (setq b (get-buffer "lewis"))
261 (get-buffer "Frazzle-nots")
264 See also the function `get-buffer-create' in *Note Creating
267 - Function: generate-new-buffer-name starting-name &optional ignore
268 This function returns a name that would be unique for a new
269 buffer--but does not create the buffer. It starts with
270 STARTING-NAME, and produces a name not currently in use for any
271 buffer by appending a number inside of `<...>'.
273 If IGNORE is given, it specifies a name that is okay to use (if it
274 is in the sequence to be tried), even if a buffer with that name
277 See the related function `generate-new-buffer' in *Note Creating
281 File: lispref.info, Node: Buffer File Name, Next: Buffer Modification, Prev: Buffer Names, Up: Buffers
286 The "buffer file name" is the name of the file that is visited in
287 that buffer. When a buffer is not visiting a file, its buffer file name
288 is `nil'. Most of the time, the buffer name is the same as the
289 nondirectory part of the buffer file name, but the buffer file name and
290 the buffer name are distinct and can be set independently. *Note
293 - Function: buffer-file-name &optional buffer
294 This function returns the absolute file name of the file that
295 BUFFER is visiting. If BUFFER is not visiting any file,
296 `buffer-file-name' returns `nil'. If BUFFER is not supplied, it
297 defaults to the current buffer.
299 (buffer-file-name (other-buffer))
300 => "/usr/user/lewis/manual/files.texi"
302 - Variable: buffer-file-name
303 This buffer-local variable contains the name of the file being
304 visited in the current buffer, or `nil' if it is not visiting a
305 file. It is a permanent local, unaffected by
306 `kill-local-variables'.
309 => "/usr/user/lewis/manual/buffers.texi"
311 It is risky to change this variable's value without doing various
312 other things. See the definition of `set-visited-file-name' in
313 `files.el'; some of the things done there, such as changing the
314 buffer name, are not strictly necessary, but others are essential
315 to avoid confusing XEmacs.
317 - Variable: buffer-file-truename
318 This buffer-local variable holds the truename of the file visited
319 in the current buffer, or `nil' if no file is visited. It is a
320 permanent local, unaffected by `kill-local-variables'. *Note
323 - Variable: buffer-file-number
324 This buffer-local variable holds the file number and directory
325 device number of the file visited in the current buffer, or `nil'
326 if no file or a nonexistent file is visited. It is a permanent
327 local, unaffected by `kill-local-variables'. *Note Truenames::.
329 The value is normally a list of the form `(FILENUM DEVNUM)'. This
330 pair of numbers uniquely identifies the file among all files
331 accessible on the system. See the function `file-attributes', in
332 *Note File Attributes::, for more information about them.
334 - Function: get-file-buffer filename
335 This function returns the buffer visiting file FILENAME. If there
336 is no such buffer, it returns `nil'. The argument FILENAME, which
337 must be a string, is expanded (*note File Name Expansion::), then
338 compared against the visited file names of all live buffers.
340 (get-file-buffer "buffers.texi")
341 => #<buffer buffers.texi>
343 In unusual circumstances, there can be more than one buffer
344 visiting the same file name. In such cases, this function returns
345 the first such buffer in the buffer list.
347 - Command: set-visited-file-name filename
348 If FILENAME is a non-empty string, this function changes the name
349 of the file visited in current buffer to FILENAME. (If the buffer
350 had no visited file, this gives it one.) The _next time_ the
351 buffer is saved it will go in the newly-specified file. This
352 command marks the buffer as modified, since it does not (as far as
353 XEmacs knows) match the contents of FILENAME, even if it matched
354 the former visited file.
356 If FILENAME is `nil' or the empty string, that stands for "no
357 visited file". In this case, `set-visited-file-name' marks the
358 buffer as having no visited file.
360 When the function `set-visited-file-name' is called interactively,
361 it prompts for FILENAME in the minibuffer.
363 See also `clear-visited-file-modtime' and
364 `verify-visited-file-modtime' in *Note Buffer Modification::.
366 - Variable: list-buffers-directory
367 This buffer-local variable records a string to display in a buffer
368 listing in place of the visited file name, for buffers that don't
369 have a visited file name. Dired buffers use this variable.
372 File: lispref.info, Node: Buffer Modification, Next: Modification Time, Prev: Buffer File Name, Up: Buffers
377 XEmacs keeps a flag called the "modified flag" for each buffer, to
378 record whether you have changed the text of the buffer. This flag is
379 set to `t' whenever you alter the contents of the buffer, and cleared
380 to `nil' when you save it. Thus, the flag shows whether there are
381 unsaved changes. The flag value is normally shown in the modeline
382 (*note Modeline Variables::), and controls saving (*note Saving
383 Buffers::) and auto-saving (*note Auto-Saving::).
385 Some Lisp programs set the flag explicitly. For example, the
386 function `set-visited-file-name' sets the flag to `t', because the text
387 does not match the newly-visited file, even if it is unchanged from the
388 file formerly visited.
390 The functions that modify the contents of buffers are described in
393 - Function: buffer-modified-p &optional buffer
394 This function returns `t' if the buffer BUFFER has been modified
395 since it was last read in from a file or saved, or `nil'
396 otherwise. If BUFFER is not supplied, the current buffer is
399 - Function: set-buffer-modified-p flag
400 This function marks the current buffer as modified if FLAG is
401 non-`nil', or as unmodified if the flag is `nil'.
403 Another effect of calling this function is to cause unconditional
404 redisplay of the modeline for the current buffer. In fact, the
405 function `redraw-modeline' works by doing this:
407 (set-buffer-modified-p (buffer-modified-p))
409 - Command: not-modified &optional arg
410 This command marks the current buffer as unmodified, and not
411 needing to be saved. (If ARG is non-`nil', the buffer is instead
412 marked as modified.) Don't use this function in programs, since it
413 prints a message in the echo area; use `set-buffer-modified-p'
416 - Function: buffer-modified-tick &optional buffer
417 This function returns BUFFER`s modification-count. This is a
418 counter that increments every time the buffer is modified. If
419 BUFFER is `nil' (or omitted), the current buffer is used.
422 File: lispref.info, Node: Modification Time, Next: Read Only Buffers, Prev: Buffer Modification, Up: Buffers
424 Comparison of Modification Time
425 ===============================
427 Suppose that you visit a file and make changes in its buffer, and
428 meanwhile the file itself is changed on disk. At this point, saving the
429 buffer would overwrite the changes in the file. Occasionally this may
430 be what you want, but usually it would lose valuable information.
431 XEmacs therefore checks the file's modification time using the functions
432 described below before saving the file.
434 - Function: verify-visited-file-modtime buffer
435 This function compares what BUFFER has recorded for the
436 modification time of its visited file against the actual
437 modification time of the file as recorded by the operating system.
438 The two should be the same unless some other process has written
439 the file since XEmacs visited or saved it.
441 The function returns `t' if the last actual modification time and
442 XEmacs's recorded modification time are the same, `nil' otherwise.
444 - Function: clear-visited-file-modtime
445 This function clears out the record of the last modification time
446 of the file being visited by the current buffer. As a result, the
447 next attempt to save this buffer will not complain of a
448 discrepancy in file modification times.
450 This function is called in `set-visited-file-name' and other
451 exceptional places where the usual test to avoid overwriting a
452 changed file should not be done.
454 - Function: visited-file-modtime
455 This function returns the buffer's recorded last file modification
456 time, as a list of the form `(HIGH . LOW)'. (This is the same
457 format that `file-attributes' uses to return time values; see
458 *Note File Attributes::.)
460 - Function: set-visited-file-modtime &optional time
461 This function updates the buffer's record of the last modification
462 time of the visited file, to the value specified by TIME if TIME
463 is not `nil', and otherwise to the last modification time of the
466 If TIME is not `nil', it should have the form `(HIGH . LOW)' or
467 `(HIGH LOW)', in either case containing two integers, each of
468 which holds 16 bits of the time.
470 This function is useful if the buffer was not read from the file
471 normally, or if the file itself has been changed for some known
474 - Function: ask-user-about-supersession-threat filename
475 This function is used to ask a user how to proceed after an
476 attempt to modify an obsolete buffer visiting file FILENAME. An
477 "obsolete buffer" is an unmodified buffer for which the associated
478 file on disk is newer than the last save-time of the buffer. This
479 means some other program has probably altered the file.
481 Depending on the user's answer, the function may return normally,
482 in which case the modification of the buffer proceeds, or it may
483 signal a `file-supersession' error with data `(FILENAME)', in which
484 case the proposed buffer modification is not allowed.
486 This function is called automatically by XEmacs on the proper
487 occasions. It exists so you can customize XEmacs by redefining it.
488 See the file `userlock.el' for the standard definition.
490 See also the file locking mechanism in *Note File Locks::.
493 File: lispref.info, Node: Read Only Buffers, Next: The Buffer List, Prev: Modification Time, Up: Buffers
498 If a buffer is "read-only", then you cannot change its contents,
499 although you may change your view of the contents by scrolling and
502 Read-only buffers are used in two kinds of situations:
504 * A buffer visiting a write-protected file is normally read-only.
506 Here, the purpose is to show the user that editing the buffer with
507 the aim of saving it in the file may be futile or undesirable.
508 The user who wants to change the buffer text despite this can do
509 so after clearing the read-only flag with `C-x C-q'.
511 * Modes such as Dired and Rmail make buffers read-only when altering
512 the contents with the usual editing commands is probably a mistake.
514 The special commands of these modes bind `buffer-read-only' to
515 `nil' (with `let') or bind `inhibit-read-only' to `t' around the
516 places where they change the text.
518 - Variable: buffer-read-only
519 This buffer-local variable specifies whether the buffer is
520 read-only. The buffer is read-only if this variable is non-`nil'.
522 - Variable: inhibit-read-only
523 If this variable is non-`nil', then read-only buffers and read-only
524 characters may be modified. Read-only characters in a buffer are
525 those that have non-`nil' `read-only' properties (either text
526 properties or extent properties). *Note Extent Properties::, for
527 more information about text properties and extent properties.
529 If `inhibit-read-only' is `t', all `read-only' character
530 properties have no effect. If `inhibit-read-only' is a list, then
531 `read-only' character properties have no effect if they are members
532 of the list (comparison is done with `eq').
534 - Command: toggle-read-only
535 This command changes whether the current buffer is read-only. It
536 is intended for interactive use; don't use it in programs. At any
537 given point in a program, you should know whether you want the
538 read-only flag on or off; so you can set `buffer-read-only'
539 explicitly to the proper value, `t' or `nil'.
541 - Function: barf-if-buffer-read-only
542 This function signals a `buffer-read-only' error if the current
543 buffer is read-only. *Note Interactive Call::, for another way to
544 signal an error if the current buffer is read-only.
547 File: lispref.info, Node: The Buffer List, Next: Creating Buffers, Prev: Read Only Buffers, Up: Buffers
552 The "buffer list" is a list of all live buffers. Creating a buffer
553 adds it to this list, and killing a buffer deletes it. The order of
554 the buffers in the list is based primarily on how recently each buffer
555 has been displayed in the selected window. Buffers move to the front
556 of the list when they are selected and to the end when they are buried.
557 Several functions, notably `other-buffer', use this ordering. A
558 buffer list displayed for the user also follows this order.
560 Every frame has its own order for the buffer list. Switching to a
561 new buffer inside of a particular frame changes the buffer list order
562 for that frame, but does not affect the buffer list order of any other
563 frames. In addition, there is a global, non-frame buffer list order
564 that is independent of the buffer list orders for any particular frame.
566 Note that the different buffer lists all contain the same elements.
567 It is only the order of those elements that is different.
569 - Function: buffer-list &optional frame
570 This function returns a list of all buffers, including those whose
571 names begin with a space. The elements are actual buffers, not
572 their names. The order of the list is specific to FRAME, which
573 defaults to the current frame. If FRAME is `t', the global,
574 non-frame ordering is returned instead.
577 => (#<buffer buffers.texi>
578 #<buffer *Minibuf-1*> #<buffer buffer.c>
579 #<buffer *Help*> #<buffer TAGS>)
581 ;; Note that the name of the minibuffer
582 ;; begins with a space!
583 (mapcar (function buffer-name) (buffer-list))
584 => ("buffers.texi" " *Minibuf-1*"
585 "buffer.c" "*Help*" "TAGS")
587 Buffers appear earlier in the list if they were current more
590 This list is a copy of a list used inside XEmacs; modifying it has
591 no effect on the buffers.
593 - Function: other-buffer &optional buffer-or-name frame visible-ok
594 This function returns the first buffer in the buffer list other
595 than BUFFER-OR-NAME, in FRAME's ordering for the buffer list.
596 (FRAME defaults to the current frame. If FRAME is `t', then the
597 global, non-frame ordering is used.) Usually this is the buffer
598 most recently shown in the selected window, aside from
599 BUFFER-OR-NAME. Buffers are moved to the front of the list when
600 they are selected and to the end when they are buried. Buffers
601 whose names start with a space are not considered.
603 If BUFFER-OR-NAME is not supplied (or if it is not a buffer), then
604 `other-buffer' returns the first buffer on the buffer list that is
605 not visible in any window in a visible frame.
607 If the selected frame has a non-`nil' `buffer-predicate' property,
608 then `other-buffer' uses that predicate to decide which buffers to
609 consider. It calls the predicate once for each buffer, and if the
610 value is `nil', that buffer is ignored. *Note X Frame
613 If VISIBLE-OK is `nil', `other-buffer' avoids returning a buffer
614 visible in any window on any visible frame, except as a last
615 resort. If VISIBLE-OK is non-`nil', then it does not matter
616 whether a buffer is displayed somewhere or not.
618 If no suitable buffer exists, the buffer `*scratch*' is returned
619 (and created, if necessary).
621 Note that in FSF Emacs 19, there is no FRAME argument, and
622 VISIBLE-OK is the second argument instead of the third. FSF Emacs
625 - Command: list-buffers &optional files-only
626 This function displays a listing of the names of existing buffers.
627 It clears the buffer `*Buffer List*', then inserts the listing
628 into that buffer and displays it in a window. `list-buffers' is
629 intended for interactive use, and is described fully in `The XEmacs
630 Reference Manual'. It returns `nil'.
632 - Command: bury-buffer &optional buffer-or-name
633 This function puts BUFFER-OR-NAME at the end of the buffer list
634 without changing the order of any of the other buffers on the list.
635 This buffer therefore becomes the least desirable candidate for
636 `other-buffer' to return.
638 If BUFFER-OR-NAME is `nil' or omitted, this means to bury the
639 current buffer. In addition, if the buffer is displayed in the
640 selected window, this switches to some other buffer (obtained using
641 `other-buffer') in the selected window. But if the buffer is
642 displayed in some other window, it remains displayed there.
644 If you wish to replace a buffer in all the windows that display
645 it, use `replace-buffer-in-windows'. *Note Buffers and Windows::.
648 File: lispref.info, Node: Creating Buffers, Next: Killing Buffers, Prev: The Buffer List, Up: Buffers
653 This section describes the two primitives for creating buffers.
654 `get-buffer-create' creates a buffer if it finds no existing buffer
655 with the specified name; `generate-new-buffer' always creates a new
656 buffer and gives it a unique name.
658 Other functions you can use to create buffers include
659 `with-output-to-temp-buffer' (*note Temporary Displays::) and
660 `create-file-buffer' (*note Visiting Files::). Starting a subprocess
661 can also create a buffer (*note Processes::).
663 - Function: get-buffer-create name
664 This function returns a buffer named NAME. It returns an existing
665 buffer with that name, if one exists; otherwise, it creates a new
666 buffer. The buffer does not become the current buffer--this
667 function does not change which buffer is current.
669 An error is signaled if NAME is not a string.
671 (get-buffer-create "foo")
674 The major mode for the new buffer is set to Fundamental mode. The
675 variable `default-major-mode' is handled at a higher level. *Note
678 - Function: generate-new-buffer name
679 This function returns a newly created, empty buffer, but does not
680 make it current. If there is no buffer named NAME, then that is
681 the name of the new buffer. If that name is in use, this function
682 adds suffixes of the form `<N>' to NAME, where N is an integer.
683 It tries successive integers starting with 2 until it finds an
686 An error is signaled if NAME is not a string.
688 (generate-new-buffer "bar")
690 (generate-new-buffer "bar")
692 (generate-new-buffer "bar")
695 The major mode for the new buffer is set to Fundamental mode. The
696 variable `default-major-mode' is handled at a higher level. *Note
699 See the related function `generate-new-buffer-name' in *Note
703 File: lispref.info, Node: Killing Buffers, Next: Indirect Buffers, Prev: Creating Buffers, Up: Buffers
708 "Killing a buffer" makes its name unknown to XEmacs and makes its
709 text space available for other use.
711 The buffer object for the buffer that has been killed remains in
712 existence as long as anything refers to it, but it is specially marked
713 so that you cannot make it current or display it. Killed buffers retain
714 their identity, however; two distinct buffers, when killed, remain
715 distinct according to `eq'.
717 If you kill a buffer that is current or displayed in a window, XEmacs
718 automatically selects or displays some other buffer instead. This means
719 that killing a buffer can in general change the current buffer.
720 Therefore, when you kill a buffer, you should also take the precautions
721 associated with changing the current buffer (unless you happen to know
722 that the buffer being killed isn't current). *Note Current Buffer::.
724 If you kill a buffer that is the base buffer of one or more indirect
725 buffers, the indirect buffers are automatically killed as well.
727 The `buffer-name' of a killed buffer is `nil'. To test whether a
728 buffer has been killed, you can either use this feature or the function
731 - Function: buffer-live-p buffer
732 This function returns `nil' if BUFFER is deleted, and `t'
735 - Command: kill-buffer buffer-or-name
736 This function kills the buffer BUFFER-OR-NAME, freeing all its
737 memory for use as space for other buffers. (Emacs version 18 and
738 older was unable to return the memory to the operating system.)
741 Any processes that have this buffer as the `process-buffer' are
742 sent the `SIGHUP' signal, which normally causes them to terminate.
743 (The basic meaning of `SIGHUP' is that a dialup line has been
744 disconnected.) *Note Deleting Processes::.
746 If the buffer is visiting a file and contains unsaved changes,
747 `kill-buffer' asks the user to confirm before the buffer is killed.
748 It does this even if not called interactively. To prevent the
749 request for confirmation, clear the modified flag before calling
750 `kill-buffer'. *Note Buffer Modification::.
752 Killing a buffer that is already dead has no effect.
754 (kill-buffer "foo.unchanged")
756 (kill-buffer "foo.changed")
758 ---------- Buffer: Minibuffer ----------
759 Buffer foo.changed modified; kill anyway? (yes or no) yes
760 ---------- Buffer: Minibuffer ----------
764 - Variable: kill-buffer-query-functions
765 After confirming unsaved changes, `kill-buffer' calls the functions
766 in the list `kill-buffer-query-functions', in order of appearance,
767 with no arguments. The buffer being killed is the current buffer
768 when they are called. The idea is that these functions ask for
769 confirmation from the user for various nonstandard reasons. If
770 any of them returns `nil', `kill-buffer' spares the buffer's life.
772 - Variable: kill-buffer-hook
773 This is a normal hook run by `kill-buffer' after asking all the
774 questions it is going to ask, just before actually killing the
775 buffer. The buffer to be killed is current when the hook
776 functions run. *Note Hooks::.
778 - Variable: buffer-offer-save
779 This variable, if non-`nil' in a particular buffer, tells
780 `save-buffers-kill-emacs' and `save-some-buffers' to offer to save
781 that buffer, just as they offer to save file-visiting buffers. The
782 variable `buffer-offer-save' automatically becomes buffer-local
783 when set for any reason. *Note Buffer-Local Variables::.
786 File: lispref.info, Node: Indirect Buffers, Prev: Killing Buffers, Up: Buffers
791 An "indirect buffer" shares the text of some other buffer, which is
792 called the "base buffer" of the indirect buffer. In some ways it is
793 the analogue, for buffers, of a symbolic link among files. The base
794 buffer may not itself be an indirect buffer. One base buffer may have
795 several "indirect children".
797 The text of the indirect buffer is always identical to the text of
798 its base buffer; changes made by editing either one are visible
799 immediately in the other.
801 But in all other respects, the indirect buffer and its base buffer
802 are completely separate. They have different names, different values of
803 point and mark, different narrowing, different markers and extents
804 (though inserting or deleting text in either buffer relocates the
805 markers and extents for both), different major modes, and different
806 local variables. Unlike in FSF Emacs, XEmacs indirect buffers do not
807 automatically share text properties among themselves and their base
810 An indirect buffer cannot visit a file, but its base buffer can. If
811 you try to save the indirect buffer, that actually works by saving the
814 Killing an indirect buffer has no effect on its base buffer. Killing
815 the base buffer kills all its indirect children.
817 - Command: make-indirect-buffer base-buffer name
818 This creates an indirect buffer named NAME whose base buffer is
819 BASE-BUFFER. The argument BASE-BUFFER may be a buffer or a string.
821 If BASE-BUFFER is an indirect buffer, its base buffer is used as
822 the base for the new buffer.
824 (make-indirect-buffer "*scratch*" "indirect")
825 => #<buffer "indirect">
827 - Function: buffer-base-buffer &optional buffer
828 This function returns the base buffer of BUFFER. If BUFFER is not
829 indirect, the value is `nil'. Otherwise, the value is another
830 buffer, which is never an indirect buffer. If BUFFER is not
831 supplied, it defaults to the current buffer.
833 (buffer-base-buffer (get-buffer "indirect"))
834 => #<buffer "*scratch*">
836 - Function: buffer-indirect-children &optional buffer
837 This function returns a list of all indirect buffers whose base
838 buffer is BUFFER. If BUFFER is indirect, the return value will
839 always be nil; see `make-indirect-buffer'. If BUFFER is not
840 supplied, it defaults to the current buffer.
842 (buffer-indirect-children (get-buffer "*scratch*"))
843 => (#<buffer "indirect">)
846 File: lispref.info, Node: Windows, Next: Frames, Prev: Buffers, Up: Top
851 This chapter describes most of the functions and variables related to
852 Emacs windows. See *Note Display::, for information on how text is
853 displayed in windows.
857 * Basic Windows:: Basic information on using windows.
858 * Splitting Windows:: Splitting one window into two windows.
859 * Deleting Windows:: Deleting a window gives its space to other windows.
860 * Selecting Windows:: The selected window is the one that you edit in.
861 * Cyclic Window Ordering:: Moving around the existing windows.
862 * Buffers and Windows:: Each window displays the contents of a buffer.
863 * Displaying Buffers:: Higher-lever functions for displaying a buffer
864 and choosing a window for it.
865 * Choosing Window:: How to choose a window for displaying a buffer.
866 * Window Point:: Each window has its own location of point.
867 * Window Start:: The display-start position controls which text
868 is on-screen in the window.
869 * Vertical Scrolling:: Moving text up and down in the window.
870 * Horizontal Scrolling:: Moving text sideways on the window.
871 * Size of Window:: Accessing the size of a window.
872 * Position of Window:: Accessing the position of a window.
873 * Resizing Windows:: Changing the size of a window.
874 * Window Configurations:: Saving and restoring the state of the screen.
877 File: lispref.info, Node: Basic Windows, Next: Splitting Windows, Up: Windows
879 Basic Concepts of Emacs Windows
880 ===============================
882 A "window" in XEmacs is the physical area of the screen in which a
883 buffer is displayed. The term is also used to refer to a Lisp object
884 that represents that screen area in XEmacs Lisp. It should be clear
885 from the context which is meant.
887 XEmacs groups windows into frames. A frame represents an area of
888 screen available for XEmacs to use. Each frame always contains at least
889 one window, but you can subdivide it vertically or horizontally into
890 multiple nonoverlapping Emacs windows.
892 In each frame, at any time, one and only one window is designated as
893 "selected within the frame". The frame's cursor appears in that
894 window. At ant time, one frame is the selected frame; and the window
895 selected within that frame is "the selected window". The selected
896 window's buffer is usually the current buffer (except when `set-buffer'
897 has been used). *Note Current Buffer::.
899 For practical purposes, a window exists only while it is displayed in
900 a frame. Once removed from the frame, the window is effectively deleted
901 and should not be used, _even though there may still be references to
902 it_ from other Lisp objects. Restoring a saved window configuration is
903 the only way for a window no longer on the screen to come back to life.
904 (*Note Deleting Windows::.)
906 Each window has the following attributes:
914 * window edges with respect to the frame or screen
916 * the buffer it displays
918 * position within the buffer at the upper left of the window
920 * amount of horizontal scrolling, in columns
926 * how recently the window was selected
928 Users create multiple windows so they can look at several buffers at
929 once. Lisp libraries use multiple windows for a variety of reasons, but
930 most often to display related information. In Rmail, for example, you
931 can move through a summary buffer in one window while the other window
932 shows messages one at a time as they are reached.
934 The meaning of "window" in XEmacs is similar to what it means in the
935 context of general-purpose window systems such as X, but not identical.
936 The X Window System places X windows on the screen; XEmacs uses one or
937 more X windows as frames, and subdivides them into Emacs windows. When
938 you use XEmacs on a character-only terminal, XEmacs treats the whole
939 terminal screen as one frame.
941 Most window systems support arbitrarily located overlapping windows.
942 In contrast, Emacs windows are "tiled"; they never overlap, and
943 together they fill the whole screen or frame. Because of the way in
944 which XEmacs creates new windows and resizes them, you can't create
945 every conceivable tiling of windows on an Emacs frame. *Note Splitting
946 Windows::, and *Note Size of Window::.
948 *Note Display::, for information on how the contents of the window's
949 buffer are displayed in the window.
951 - Function: windowp object
952 This function returns `t' if OBJECT is a window.
955 File: lispref.info, Node: Splitting Windows, Next: Deleting Windows, Prev: Basic Windows, Up: Windows
960 The functions described here are the primitives used to split a
961 window into two windows. Two higher level functions sometimes split a
962 window, but not always: `pop-to-buffer' and `display-buffer' (*note
963 Displaying Buffers::).
965 The functions described here do not accept a buffer as an argument.
966 The two "halves" of the split window initially display the same buffer
967 previously visible in the window that was split.
969 - Function: one-window-p &optional no-mini all-frames
970 This function returns non-`nil' if there is only one window. The
971 argument NO-MINI, if non-`nil', means don't count the minibuffer
972 even if it is active; otherwise, the minibuffer window is
973 included, if active, in the total number of windows which is
974 compared against one.
976 The argument ALL-FRAME controls which set of windows are counted.
977 * If it is `nil' or omitted, then count only the selected
978 frame, plus the minibuffer it uses (which may be on another
981 * If it is `t', then windows on all frames that currently exist
982 (including invisible and iconified frames) are counted.
984 * If it is the symbol `visible', then windows on all visible
987 * If it is the number 0, then windows on all visible and
988 iconified frames are counted.
990 * If it is any other value, then precisely the windows in
991 WINDOW's frame are counted, excluding the minibuffer in use
992 if it lies in some other frame.
994 - Command: split-window &optional window size horizontal
995 This function splits WINDOW into two windows. The original window
996 WINDOW remains the selected window, but occupies only part of its
997 former screen area. The rest is occupied by a newly created
998 window which is returned as the value of this function.
1000 If HORIZONTAL is non-`nil', then WINDOW splits into two side by
1001 side windows. The original window WINDOW keeps the leftmost SIZE
1002 columns, and gives the rest of the columns to the new window.
1003 Otherwise, it splits into windows one above the other, and WINDOW
1004 keeps the upper SIZE lines and gives the rest of the lines to the
1005 new window. The original window is therefore the left-hand or
1006 upper of the two, and the new window is the right-hand or lower.
1008 If WINDOW is omitted or `nil', then the selected window is split.
1009 If SIZE is omitted or `nil', then WINDOW is divided evenly into
1010 two parts. (If there is an odd line, it is allocated to the new
1011 window.) When `split-window' is called interactively, all its
1012 arguments are `nil'.
1014 The following example starts with one window on a frame that is 50
1015 lines high by 80 columns wide; then the window is split.
1017 (setq w (selected-window))
1018 => #<window 8 on windows.texi>
1019 (window-edges) ; Edges in order:
1020 => (0 0 80 50) ; left-top-right-bottom
1022 ;; Returns window created
1023 (setq w2 (split-window w 15))
1024 => #<window 28 on windows.texi>
1026 => (0 15 80 50) ; Bottom window;
1029 => (0 0 80 15) ; Top window
1031 The frame looks like this:
1043 Next, the top window is split horizontally:
1045 (setq w3 (split-window w 35 t))
1046 => #<window 32 on windows.texi>
1048 => (35 0 80 15) ; Left edge at column 35
1050 => (0 0 35 15) ; Right edge at column 35
1052 => (0 15 80 50) ; Bottom window unchanged
1054 Now, the screen looks like this:
1067 Normally, Emacs indicates the border between two side-by-side
1068 windows with a scroll bar (*note Scroll Bars: X Frame Properties.)
1069 or `|' characters. The display table can specify alternative
1070 border characters; see *Note Display Tables::.
1072 - Command: split-window-vertically &optional size
1073 This function splits the selected window into two windows, one
1074 above the other, leaving the selected window with SIZE lines.
1076 This function is simply an interface to `split-windows'. Here is
1077 the complete function definition for it:
1079 (defun split-window-vertically (&optional arg)
1080 "Split current window into two windows, one above the other."
1082 (split-window nil (and arg (prefix-numeric-value arg))))
1084 - Command: split-window-horizontally &optional size
1085 This function splits the selected window into two windows
1086 side-by-side, leaving the selected window with SIZE columns.
1088 This function is simply an interface to `split-windows'. Here is
1089 the complete definition for `split-window-horizontally' (except for
1090 part of the documentation string):
1092 (defun split-window-horizontally (&optional arg)
1093 "Split selected window into two windows, side by side..."
1095 (split-window nil (and arg (prefix-numeric-value arg)) t))
1097 - Function: one-window-p &optional no-mini all-frames
1098 This function returns non-`nil' if there is only one window. The
1099 argument NO-MINI, if non-`nil', means don't count the minibuffer
1100 even if it is active; otherwise, the minibuffer window is
1101 included, if active, in the total number of windows, which is
1102 compared against one.
1104 The argument ALL-FRAMES specifies which frames to consider. Here
1105 are the possible values and their meanings:
1108 Count the windows in the selected frame, plus the minibuffer
1109 used by that frame even if it lies in some other frame.
1112 Count all windows in all existing frames.
1115 Count all windows in all visible frames.
1118 Count all windows in all visible or iconified frames.
1121 Count precisely the windows in the selected frame, and no
1125 File: lispref.info, Node: Deleting Windows, Next: Selecting Windows, Prev: Splitting Windows, Up: Windows
1130 A window remains visible on its frame unless you "delete" it by
1131 calling certain functions that delete windows. A deleted window cannot
1132 appear on the screen, but continues to exist as a Lisp object until
1133 there are no references to it. There is no way to cancel the deletion
1134 of a window aside from restoring a saved window configuration (*note
1135 Window Configurations::). Restoring a window configuration also
1136 deletes any windows that aren't part of that configuration.
1138 When you delete a window, the space it took up is given to one
1139 adjacent sibling. (In Emacs version 18, the space was divided evenly
1140 among all the siblings.)
1142 - Function: window-live-p window
1143 This function returns `nil' if WINDOW is deleted, and `t'
1146 *Warning:* Erroneous information or fatal errors may result from
1147 using a deleted window as if it were live.
1149 - Command: delete-window &optional window
1150 This function removes WINDOW from the display. If WINDOW is
1151 omitted, then the selected window is deleted. An error is signaled
1152 if there is only one window when `delete-window' is called.
1154 This function returns `nil'.
1156 When `delete-window' is called interactively, WINDOW defaults to
1157 the selected window.
1159 - Command: delete-other-windows &optional window
1160 This function makes WINDOW the only window on its frame, by
1161 deleting the other windows in that frame. If WINDOW is omitted or
1162 `nil', then the selected window is used by default.
1164 The result is `nil'.
1166 - Command: delete-windows-on buffer &optional frame
1167 This function deletes all windows showing BUFFER. If there are no
1168 windows showing BUFFER, it does nothing.
1170 `delete-windows-on' operates frame by frame. If a frame has
1171 several windows showing different buffers, then those showing
1172 BUFFER are removed, and the others expand to fill the space. If
1173 all windows in some frame are showing BUFFER (including the case
1174 where there is only one window), then the frame reverts to having a
1175 single window showing another buffer chosen with `other-buffer'.
1176 *Note The Buffer List::.
1178 The argument FRAME controls which frames to operate on:
1180 * If it is `nil', operate on the selected frame.
1182 * If it is `t', operate on all frames.
1184 * If it is `visible', operate on all visible frames.
1186 * 0 If it is 0, operate on all visible or iconified frames.
1188 * If it is a frame, operate on that frame.
1190 This function always returns `nil'.