-This is ../info/lispref.info, produced by makeinfo version 4.0 from
+This is ../info/lispref.info, produced by makeinfo version 4.0b from
lispref/lispref.texi.
INFO-DIR-SECTION XEmacs Editor
Foundation instead of in the original English.
\1f
-File: lispref.info, Node: The Buffer List, Next: Creating Buffers, Prev: Read Only Buffers, Up: Buffers
+File: lispref.info, Node: Rename or Copy, Next: Numbered Backups, Prev: Making Backups, Up: Backup Files
-The Buffer List
-===============
+Backup by Renaming or by Copying?
+---------------------------------
- The "buffer list" is a list of all live buffers. Creating a buffer
-adds it to this list, and killing a buffer deletes it. The order of
-the buffers in the list is based primarily on how recently each buffer
-has been displayed in the selected window. Buffers move to the front
-of the list when they are selected and to the end when they are buried.
-Several functions, notably `other-buffer', use this ordering. A
-buffer list displayed for the user also follows this order.
+ There are two ways that XEmacs can make a backup file:
- Every frame has its own order for the buffer list. Switching to a
-new buffer inside of a particular frame changes the buffer list order
-for that frame, but does not affect the buffer list order of any other
-frames. In addition, there is a global, non-frame buffer list order
-that is independent of the buffer list orders for any particular frame.
+ * XEmacs can rename the original file so that it becomes a backup
+ file, and then write the buffer being saved into a new file.
+ After this procedure, any other names (i.e., hard links) of the
+ original file now refer to the backup file. The new file is owned
+ by the user doing the editing, and its group is the default for
+ new files written by the user in that directory.
- Note that the different buffer lists all contain the same elements.
-It is only the order of those elements that is different.
+ * XEmacs can copy the original file into a backup file, and then
+ overwrite the original file with new contents. After this
+ procedure, any other names (i.e., hard links) of the original file
+ still refer to the current version of the file. The file's owner
+ and group will be unchanged.
- - Function: buffer-list &optional frame
- This function returns a list of all buffers, including those whose
- names begin with a space. The elements are actual buffers, not
- their names. The order of the list is specific to FRAME, which
- defaults to the current frame. If FRAME is `t', the global,
- non-frame ordering is returned instead.
+ The first method, renaming, is the default.
- (buffer-list)
- => (#<buffer buffers.texi>
- #<buffer *Minibuf-1*> #<buffer buffer.c>
- #<buffer *Help*> #<buffer TAGS>)
-
- ;; Note that the name of the minibuffer
- ;; begins with a space!
- (mapcar (function buffer-name) (buffer-list))
- => ("buffers.texi" " *Minibuf-1*"
- "buffer.c" "*Help*" "TAGS")
+ The variable `backup-by-copying', if non-`nil', says to use the
+second method, which is to copy the original file and overwrite it with
+the new buffer contents. The variable `file-precious-flag', if
+non-`nil', also has this effect (as a sideline of its main
+significance). *Note Saving Buffers::.
- Buffers appear earlier in the list if they were current more
- recently.
+ - Variable: backup-by-copying
+ If this variable is non-`nil', XEmacs always makes backup files by
+ copying.
- This list is a copy of a list used inside XEmacs; modifying it has
- no effect on the buffers.
+ The following two variables, when non-`nil', cause the second method
+to be used in certain special cases. They have no effect on the
+treatment of files that don't fall into the special cases.
- - Function: other-buffer &optional buffer-or-name frame visible-ok
- This function returns the first buffer in the buffer list other
- than BUFFER-OR-NAME, in FRAME's ordering for the buffer list.
- (FRAME defaults to the current frame. If FRAME is `t', then the
- global, non-frame ordering is used.) Usually this is the buffer
- most recently shown in the selected window, aside from
- BUFFER-OR-NAME. Buffers are moved to the front of the list when
- they are selected and to the end when they are buried. Buffers
- whose names start with a space are not considered.
+ - Variable: backup-by-copying-when-linked
+ If this variable is non-`nil', XEmacs makes backups by copying for
+ files with multiple names (hard links).
- If BUFFER-OR-NAME is not supplied (or if it is not a buffer), then
- `other-buffer' returns the first buffer on the buffer list that is
- not visible in any window in a visible frame.
+ This variable is significant only if `backup-by-copying' is `nil',
+ since copying is always used when that variable is non-`nil'.
- If the selected frame has a non-`nil' `buffer-predicate' property,
- then `other-buffer' uses that predicate to decide which buffers to
- consider. It calls the predicate once for each buffer, and if the
- value is `nil', that buffer is ignored. *Note X Frame
- Properties::.
+ - Variable: backup-by-copying-when-mismatch
+ If this variable is non-`nil', XEmacs makes backups by copying in
+ cases where renaming would change either the owner or the group of
+ the file.
- If VISIBLE-OK is `nil', `other-buffer' avoids returning a buffer
- visible in any window on any visible frame, except as a last
- resort. If VISIBLE-OK is non-`nil', then it does not matter
- whether a buffer is displayed somewhere or not.
+ The value has no effect when renaming would not alter the owner or
+ group of the file; that is, for files which are owned by the user
+ and whose group matches the default for a new file created there
+ by the user.
- If no suitable buffer exists, the buffer `*scratch*' is returned
- (and created, if necessary).
+ This variable is significant only if `backup-by-copying' is `nil',
+ since copying is always used when that variable is non-`nil'.
- Note that in FSF Emacs 19, there is no FRAME argument, and
- VISIBLE-OK is the second argument instead of the third. FSF Emacs
- 19.
+\1f
+File: lispref.info, Node: Numbered Backups, Next: Backup Names, Prev: Rename or Copy, Up: Backup Files
- - Command: list-buffers &optional files-only
- This function displays a listing of the names of existing buffers.
- It clears the buffer `*Buffer List*', then inserts the listing
- into that buffer and displays it in a window. `list-buffers' is
- intended for interactive use, and is described fully in `The XEmacs
- Reference Manual'. It returns `nil'.
+Making and Deleting Numbered Backup Files
+-----------------------------------------
- - Command: bury-buffer &optional buffer-or-name
- This function puts BUFFER-OR-NAME at the end of the buffer list
- without changing the order of any of the other buffers on the list.
- This buffer therefore becomes the least desirable candidate for
- `other-buffer' to return.
+ If a file's name is `foo', the names of its numbered backup versions
+are `foo.~V~', for various integers V, like this: `foo.~1~', `foo.~2~',
+`foo.~3~', ..., `foo.~259~', and so on.
- If BUFFER-OR-NAME is `nil' or omitted, this means to bury the
- current buffer. In addition, if the buffer is displayed in the
- selected window, this switches to some other buffer (obtained using
- `other-buffer') in the selected window. But if the buffer is
- displayed in some other window, it remains displayed there.
+ - User Option: version-control
+ This variable controls whether to make a single non-numbered backup
+ file or multiple numbered backups.
- If you wish to replace a buffer in all the windows that display
- it, use `replace-buffer-in-windows'. *Note Buffers and Windows::.
+ `nil'
+ Make numbered backups if the visited file already has
+ numbered backups; otherwise, do not.
+
+ `never'
+ Do not make numbered backups.
+
+ ANYTHING ELSE
+ Make numbered backups.
+
+ The use of numbered backups ultimately leads to a large number of
+backup versions, which must then be deleted. XEmacs can do this
+automatically or it can ask the user whether to delete them.
+
+ - User Option: kept-new-versions
+ The value of this variable is the number of newest versions to keep
+ when a new numbered backup is made. The newly made backup is
+ included in the count. The default value is 2.
+
+ - User Option: kept-old-versions
+ The value of this variable is the number of oldest versions to keep
+ when a new numbered backup is made. The default value is 2.
+
+ If there are backups numbered 1, 2, 3, 5, and 7, and both of these
+variables have the value 2, then the backups numbered 1 and 2 are kept
+as old versions and those numbered 5 and 7 are kept as new versions;
+backup version 3 is excess. The function `find-backup-file-name'
+(*note Backup Names::) is responsible for determining which backup
+versions to delete, but does not delete them itself.
+
+ - User Option: delete-old-versions
+ If this variable is non-`nil', then saving a file deletes excess
+ backup versions silently. Otherwise, it asks the user whether to
+ delete them.
+
+ - User Option: dired-kept-versions
+ This variable specifies how many of the newest backup versions to
+ keep in the Dired command `.' (`dired-clean-directory'). That's
+ the same thing `kept-new-versions' specifies when you make a new
+ backup file. The default value is 2.
\1f
-File: lispref.info, Node: Creating Buffers, Next: Killing Buffers, Prev: The Buffer List, Up: Buffers
-
-Creating Buffers
-================
-
- This section describes the two primitives for creating buffers.
-`get-buffer-create' creates a buffer if it finds no existing buffer
-with the specified name; `generate-new-buffer' always creates a new
-buffer and gives it a unique name.
+File: lispref.info, Node: Backup Names, Prev: Numbered Backups, Up: Backup Files
- Other functions you can use to create buffers include
-`with-output-to-temp-buffer' (*note Temporary Displays::) and
-`create-file-buffer' (*note Visiting Files::). Starting a subprocess
-can also create a buffer (*note Processes::).
+Naming Backup Files
+-------------------
- - Function: get-buffer-create name
- This function returns a buffer named NAME. It returns an existing
- buffer with that name, if one exists; otherwise, it creates a new
- buffer. The buffer does not become the current buffer--this
- function does not change which buffer is current.
+ The functions in this section are documented mainly because you can
+customize the naming conventions for backup files by redefining them.
+If you change one, you probably need to change the rest.
- An error is signaled if NAME is not a string.
+ - Function: backup-file-name-p filename
+ This function returns a non-`nil' value if FILENAME is a possible
+ name for a backup file. A file with the name FILENAME need not
+ exist; the function just checks the name.
- (get-buffer-create "foo")
- => #<buffer foo>
+ (backup-file-name-p "foo")
+ => nil
+ (backup-file-name-p "foo~")
+ => 3
- The major mode for the new buffer is set to Fundamental mode. The
- variable `default-major-mode' is handled at a higher level. *Note
- Auto Major Mode::.
+ The standard definition of this function is as follows:
- - Function: generate-new-buffer name
- This function returns a newly created, empty buffer, but does not
- make it current. If there is no buffer named NAME, then that is
- the name of the new buffer. If that name is in use, this function
- adds suffixes of the form `<N>' to NAME, where N is an integer.
- It tries successive integers starting with 2 until it finds an
- available name.
+ (defun backup-file-name-p (file)
+ "Return non-nil if FILE is a backup file \
+ name (numeric or not)..."
+ (string-match "~$" file))
- An error is signaled if NAME is not a string.
+ Thus, the function returns a non-`nil' value if the file name ends
+ with a `~'. (We use a backslash to split the documentation
+ string's first line into two lines in the text, but produce just
+ one line in the string itself.)
- (generate-new-buffer "bar")
- => #<buffer bar>
- (generate-new-buffer "bar")
- => #<buffer bar<2>>
- (generate-new-buffer "bar")
- => #<buffer bar<3>>
+ This simple expression is placed in a separate function to make it
+ easy to redefine for customization.
- The major mode for the new buffer is set to Fundamental mode. The
- variable `default-major-mode' is handled at a higher level. *Note
- Auto Major Mode::.
+ - Function: make-backup-file-name filename
+ This function returns a string that is the name to use for a
+ non-numbered backup file for file FILENAME. On Unix, this is just
+ FILENAME with a tilde appended.
- See the related function `generate-new-buffer-name' in *Note
- Buffer Names::.
+ The standard definition of this function is as follows:
-\1f
-File: lispref.info, Node: Killing Buffers, Next: Indirect Buffers, Prev: Creating Buffers, Up: Buffers
+ (defun make-backup-file-name (file)
+ "Create the non-numeric backup file name for FILE.
+ ..."
+ (concat file "~"))
-Killing Buffers
-===============
+ You can change the backup-file naming convention by redefining this
+ function. The following example redefines `make-backup-file-name'
+ to prepend a `.' in addition to appending a tilde:
- "Killing a buffer" makes its name unknown to XEmacs and makes its
-text space available for other use.
-
- The buffer object for the buffer that has been killed remains in
-existence as long as anything refers to it, but it is specially marked
-so that you cannot make it current or display it. Killed buffers retain
-their identity, however; two distinct buffers, when killed, remain
-distinct according to `eq'.
-
- If you kill a buffer that is current or displayed in a window, XEmacs
-automatically selects or displays some other buffer instead. This means
-that killing a buffer can in general change the current buffer.
-Therefore, when you kill a buffer, you should also take the precautions
-associated with changing the current buffer (unless you happen to know
-that the buffer being killed isn't current). *Note Current Buffer::.
-
- If you kill a buffer that is the base buffer of one or more indirect
-buffers, the indirect buffers are automatically killed as well.
-
- The `buffer-name' of a killed buffer is `nil'. To test whether a
-buffer has been killed, you can either use this feature or the function
-`buffer-live-p'.
-
- - Function: buffer-live-p buffer
- This function returns `nil' if BUFFER is deleted, and `t'
- otherwise.
-
- - Command: kill-buffer buffer-or-name
- This function kills the buffer BUFFER-OR-NAME, freeing all its
- memory for use as space for other buffers. (Emacs version 18 and
- older was unable to return the memory to the operating system.)
- It returns `nil'.
-
- Any processes that have this buffer as the `process-buffer' are
- sent the `SIGHUP' signal, which normally causes them to terminate.
- (The basic meaning of `SIGHUP' is that a dialup line has been
- disconnected.) *Note Deleting Processes::.
-
- If the buffer is visiting a file and contains unsaved changes,
- `kill-buffer' asks the user to confirm before the buffer is killed.
- It does this even if not called interactively. To prevent the
- request for confirmation, clear the modified flag before calling
- `kill-buffer'. *Note Buffer Modification::.
-
- Killing a buffer that is already dead has no effect.
-
- (kill-buffer "foo.unchanged")
- => nil
- (kill-buffer "foo.changed")
-
- ---------- Buffer: Minibuffer ----------
- Buffer foo.changed modified; kill anyway? (yes or no) yes
- ---------- Buffer: Minibuffer ----------
+ (defun make-backup-file-name (filename)
+ (concat "." filename "~"))
- => nil
-
- - Variable: kill-buffer-query-functions
- After confirming unsaved changes, `kill-buffer' calls the functions
- in the list `kill-buffer-query-functions', in order of appearance,
- with no arguments. The buffer being killed is the current buffer
- when they are called. The idea is that these functions ask for
- confirmation from the user for various nonstandard reasons. If
- any of them returns `nil', `kill-buffer' spares the buffer's life.
-
- - Variable: kill-buffer-hook
- This is a normal hook run by `kill-buffer' after asking all the
- questions it is going to ask, just before actually killing the
- buffer. The buffer to be killed is current when the hook
- functions run. *Note Hooks::.
-
- - Variable: buffer-offer-save
- This variable, if non-`nil' in a particular buffer, tells
- `save-buffers-kill-emacs' and `save-some-buffers' to offer to save
- that buffer, just as they offer to save file-visiting buffers. The
- variable `buffer-offer-save' automatically becomes buffer-local
- when set for any reason. *Note Buffer-Local Variables::.
-
-\1f
-File: lispref.info, Node: Indirect Buffers, Prev: Killing Buffers, Up: Buffers
-
-Indirect Buffers
-================
+ (make-backup-file-name "backups.texi")
+ => ".backups.texi~"
- An "indirect buffer" shares the text of some other buffer, which is
-called the "base buffer" of the indirect buffer. In some ways it is
-the analogue, for buffers, of a symbolic link among files. The base
-buffer may not itself be an indirect buffer. One base buffer may have
-several "indirect children".
+ - Function: find-backup-file-name filename
+ This function computes the file name for a new backup file for
+ FILENAME. It may also propose certain existing backup files for
+ deletion. `find-backup-file-name' returns a list whose CAR is the
+ name for the new backup file and whose CDR is a list of backup
+ files whose deletion is proposed.
- The text of the indirect buffer is always identical to the text of
-its base buffer; changes made by editing either one are visible
-immediately in the other.
+ Two variables, `kept-old-versions' and `kept-new-versions',
+ determine which backup versions should be kept. This function
+ keeps those versions by excluding them from the CDR of the value.
+ *Note Numbered Backups::.
- But in all other respects, the indirect buffer and its base buffer
-are completely separate. They have different names, different values of
-point and mark, different narrowing, different markers and extents
-(though inserting or deleting text in either buffer relocates the
-markers and extents for both), different major modes, and different
-local variables. Unlike in FSF Emacs, XEmacs indirect buffers do not
-automatically share text properties among themselves and their base
-buffer.
+ In this example, the value says that `~rms/foo.~5~' is the name to
+ use for the new backup file, and `~rms/foo.~3~' is an "excess"
+ version that the caller should consider deleting now.
- An indirect buffer cannot visit a file, but its base buffer can. If
-you try to save the indirect buffer, that actually works by saving the
-base buffer.
+ (find-backup-file-name "~rms/foo")
+ => ("~rms/foo.~5~" "~rms/foo.~3~")
- Killing an indirect buffer has no effect on its base buffer. Killing
-the base buffer kills all its indirect children.
+ - Function: file-newest-backup filename
+ This function returns the name of the most recent backup file for
+ FILENAME, or `nil' if that file has no backup files.
- - Command: make-indirect-buffer base-buffer name
- This creates an indirect buffer named NAME whose base buffer is
- BASE-BUFFER. The argument BASE-BUFFER may be a buffer or a string.
+ Some file comparison commands use this function so that they can
+ automatically compare a file with its most recent backup.
- If BASE-BUFFER is an indirect buffer, its base buffer is used as
- the base for the new buffer.
-
- (make-indirect-buffer "*scratch*" "indirect")
- => #<buffer "indirect">
-
- - Function: buffer-base-buffer &optional buffer
- This function returns the base buffer of BUFFER. If BUFFER is not
- indirect, the value is `nil'. Otherwise, the value is another
- buffer, which is never an indirect buffer. If BUFFER is not
- supplied, it defaults to the current buffer.
+\1f
+File: lispref.info, Node: Auto-Saving, Next: Reverting, Prev: Backup Files, Up: Backups and Auto-Saving
+
+Auto-Saving
+===========
+
+ XEmacs periodically saves all files that you are visiting; this is
+called "auto-saving". Auto-saving prevents you from losing more than a
+limited amount of work if the system crashes. By default, auto-saves
+happen every 300 keystrokes, or after around 30 seconds of idle time.
+*Note Auto-Save: (xemacs)Auto-Save, for information on auto-save for
+users. Here we describe the functions used to implement auto-saving
+and the variables that control them.
+
+ - Variable: buffer-auto-save-file-name
+ This buffer-local variable is the name of the file used for
+ auto-saving the current buffer. It is `nil' if the buffer should
+ not be auto-saved.
+
+ buffer-auto-save-file-name
+ => "/xcssun/users/rms/lewis/#files.texi#"
+
+ - Command: auto-save-mode arg
+ When used interactively without an argument, this command is a
+ toggle switch: it turns on auto-saving of the current buffer if it
+ is off, and vice-versa. With an argument ARG, the command turns
+ auto-saving on if the value of ARG is `t', a nonempty list, or a
+ positive integer. Otherwise, it turns auto-saving off.
+
+ - Function: auto-save-file-name-p filename
+ This function returns a non-`nil' value if FILENAME is a string
+ that could be the name of an auto-save file. It works based on
+ knowledge of the naming convention for auto-save files: a name that
+ begins and ends with hash marks (`#') is a possible auto-save file
+ name. The argument FILENAME should not contain a directory part.
+
+ (make-auto-save-file-name)
+ => "/xcssun/users/rms/lewis/#files.texi#"
+ (auto-save-file-name-p "#files.texi#")
+ => 0
+ (auto-save-file-name-p "files.texi")
+ => nil
- (buffer-base-buffer (get-buffer "indirect"))
- => #<buffer "*scratch*">
+ The standard definition of this function is as follows:
+
+ (defun auto-save-file-name-p (filename)
+ "Return non-nil if FILENAME can be yielded by..."
+ (string-match "^#.*#$" filename))
+
+ This function exists so that you can customize it if you wish to
+ change the naming convention for auto-save files. If you redefine
+ it, be sure to redefine the function `make-auto-save-file-name'
+ correspondingly.
+
+ - Function: make-auto-save-file-name &optional filename
+ This function returns the file name to use for auto-saving the
+ current buffer. This is just the file name with hash marks (`#')
+ appended and prepended to it. This function does not look at the
+ variable `auto-save-visited-file-name' (described below); you
+ should check that before calling this function.
+
+ (make-auto-save-file-name)
+ => "/xcssun/users/rms/lewis/#backup.texi#"
+
+ The standard definition of this function is as follows:
+
+ (defun make-auto-save-file-name ()
+ "Return file name to use for auto-saves \
+ of current buffer.
+ ..."
+ (if buffer-file-name
+ (concat
+ (file-name-directory buffer-file-name)
+ "#"
+ (file-name-nondirectory buffer-file-name)
+ "#")
+ (expand-file-name
+ (concat "#%" (buffer-name) "#"))))
+
+ This exists as a separate function so that you can redefine it to
+ customize the naming convention for auto-save files. Be sure to
+ change `auto-save-file-name-p' in a corresponding way.
+
+ - Variable: auto-save-visited-file-name
+ If this variable is non-`nil', XEmacs auto-saves buffers in the
+ files they are visiting. That is, the auto-save is done in the
+ same file that you are editing. Normally, this variable is `nil',
+ so auto-save files have distinct names that are created by
+ `make-auto-save-file-name'.
+
+ When you change the value of this variable, the value does not take
+ effect until the next time auto-save mode is reenabled in any given
+ buffer. If auto-save mode is already enabled, auto-saves continue
+ to go in the same file name until `auto-save-mode' is called again.
+
+ - Function: recent-auto-save-p
+ This function returns `t' if the current buffer has been
+ auto-saved since the last time it was read in or saved.
+
+ - Function: set-buffer-auto-saved
+ This function marks the current buffer as auto-saved. The buffer
+ will not be auto-saved again until the buffer text is changed
+ again. The function returns `nil'.
+
+ - User Option: auto-save-interval
+ The value of this variable is the number of characters that XEmacs
+ reads from the keyboard between auto-saves. Each time this many
+ more characters are read, auto-saving is done for all buffers in
+ which it is enabled.
+
+ - User Option: auto-save-timeout
+ The value of this variable is the number of seconds of idle time
+ that should cause auto-saving. Each time the user pauses for this
+ long, XEmacs auto-saves any buffers that need it. (Actually, the
+ specified timeout is multiplied by a factor depending on the size
+ of the current buffer.)
+
+ - Variable: auto-save-hook
+ This normal hook is run whenever an auto-save is about to happen.
+
+ - User Option: auto-save-default
+ If this variable is non-`nil', buffers that are visiting files
+ have auto-saving enabled by default. Otherwise, they do not.
+
+ - Command: do-auto-save &optional no-message current-only
+ This function auto-saves all buffers that need to be auto-saved.
+ It saves all buffers for which auto-saving is enabled and that
+ have been changed since the previous auto-save.
+
+ Normally, if any buffers are auto-saved, a message that says
+ `Auto-saving...' is displayed in the echo area while auto-saving is
+ going on. However, if NO-MESSAGE is non-`nil', the message is
+ inhibited.
+
+ If CURRENT-ONLY is non-`nil', only the current buffer is
+ auto-saved.
+
+ - Function: delete-auto-save-file-if-necessary
+ This function deletes the current buffer's auto-save file if
+ `delete-auto-save-files' is non-`nil'. It is called every time a
+ buffer is saved.
+
+ - Variable: delete-auto-save-files
+ This variable is used by the function
+ `delete-auto-save-file-if-necessary'. If it is non-`nil', Emacs
+ deletes auto-save files when a true save is done (in the visited
+ file). This saves disk space and unclutters your directory.
+
+ - Function: rename-auto-save-file
+ This function adjusts the current buffer's auto-save file name if
+ the visited file name has changed. It also renames an existing
+ auto-save file. If the visited file name has not changed, this
+ function does nothing.
+
+ - Variable: buffer-saved-size
+ The value of this buffer-local variable is the length of the
+ current buffer as of the last time it was read in, saved, or
+ auto-saved. This is used to detect a substantial decrease in
+ size, and turn off auto-saving in response.
+
+ If it is -1, that means auto-saving is temporarily shut off in this
+ buffer due to a substantial deletion. Explicitly saving the buffer
+ stores a positive value in this variable, thus reenabling
+ auto-saving. Turning auto-save mode off or on also alters this
+ variable.
+
+ - Variable: auto-save-list-file-name
+ This variable (if non-`nil') specifies a file for recording the
+ names of all the auto-save files. Each time XEmacs does
+ auto-saving, it writes two lines into this file for each buffer
+ that has auto-saving enabled. The first line gives the name of
+ the visited file (it's empty if the buffer has none), and the
+ second gives the name of the auto-save file.
+
+ If XEmacs exits normally, it deletes this file. If XEmacs
+ crashes, you can look in the file to find all the auto-save files
+ that might contain work that was otherwise lost. The
+ `recover-session' command uses these files.
+
+ The default name for this file is in your home directory and
+ starts with `.saves-'. It also contains the XEmacs process ID and
+ the host name.
- - Function: buffer-indirect-children &optional buffer
- This function returns a list of all indirect buffers whose base
- buffer is BUFFER. If BUFFER is indirect, the return value will
- always be nil; see `make-indirect-buffer'. If BUFFER is not
- supplied, it defaults to the current buffer.
+\1f
+File: lispref.info, Node: Reverting, Prev: Auto-Saving, Up: Backups and Auto-Saving
+
+Reverting
+=========
+
+ If you have made extensive changes to a file and then change your
+mind about them, you can get rid of them by reading in the previous
+version of the file with the `revert-buffer' command. *Note Reverting
+a Buffer: (xemacs)Reverting.
+
+ - Command: revert-buffer &optional check-auto-save noconfirm
+ preserve-modes
+ This command replaces the buffer text with the text of the visited
+ file on disk. This action undoes all changes since the file was
+ visited or saved.
+
+ If the argument CHECK-AUTO-SAVE is non-`nil', and the latest
+ auto-save file is more recent than the visited file,
+ `revert-buffer' asks the user whether to use that instead.
+ Otherwise, it always uses the text of the visited file itself.
+ Interactively, CHECK-AUTO-SAVE is set if there is a numeric prefix
+ argument.
+
+ Normally, `revert-buffer' asks for confirmation before it changes
+ the buffer; but if the argument NOCONFIRM is non-`nil',
+ `revert-buffer' does not ask for confirmation.
+
+ Optional third argument PRESERVE-MODES non-`nil' means don't alter
+ the files modes. Normally we reinitialize them using
+ `normal-mode'.
+
+ Reverting tries to preserve marker positions in the buffer by
+ using the replacement feature of `insert-file-contents'. If the
+ buffer contents and the file contents are identical before the
+ revert operation, reverting preserves all the markers. If they
+ are not identical, reverting does change the buffer; then it
+ preserves the markers in the unchanged text (if any) at the
+ beginning and end of the buffer. Preserving any additional
+ markers would be problematical.
+
+ You can customize how `revert-buffer' does its work by setting these
+variables--typically, as buffer-local variables.
+
+ - Variable: revert-buffer-function
+ The value of this variable is the function to use to revert this
+ buffer. If non-`nil', it is called as a function with no
+ arguments to do the work of reverting. If the value is `nil',
+ reverting works the usual way.
+
+ Modes such as Dired mode, in which the text being edited does not
+ consist of a file's contents but can be regenerated in some other
+ fashion, give this variable a buffer-local value that is a
+ function to regenerate the contents.
+
+ - Variable: revert-buffer-insert-file-contents-function
+ The value of this variable, if non-`nil', is the function to use to
+ insert the updated contents when reverting this buffer. The
+ function receives two arguments: first the file name to use;
+ second, `t' if the user has asked to read the auto-save file.
+
+ - Variable: before-revert-hook
+ This normal hook is run by `revert-buffer' before actually
+ inserting the modified contents--but only if
+ `revert-buffer-function' is `nil'.
+
+ Font Lock mode uses this hook to record that the buffer contents
+ are no longer fontified.
+
+ - Variable: after-revert-hook
+ This normal hook is run by `revert-buffer' after actually inserting
+ the modified contents--but only if `revert-buffer-function' is
+ `nil'.
- (buffer-indirect-children (get-buffer "*scratch*"))
- => (#<buffer "indirect">)
+ Font Lock mode uses this hook to recompute the fonts for the
+ updated buffer contents.
\1f
-File: lispref.info, Node: Windows, Next: Frames, Prev: Buffers, Up: Top
+File: lispref.info, Node: Buffers, Next: Windows, Prev: Backups and Auto-Saving, Up: Top
-Windows
+Buffers
*******
- This chapter describes most of the functions and variables related to
-Emacs windows. See *Note Display::, for information on how text is
-displayed in windows.
+ A "buffer" is a Lisp object containing text to be edited. Buffers
+are used to hold the contents of files that are being visited; there may
+also be buffers that are not visiting files. While several buffers may
+exist at one time, exactly one buffer is designated the "current
+buffer" at any time. Most editing commands act on the contents of the
+current buffer. Each buffer, including the current buffer, may or may
+not be displayed in any window.
* Menu:
-* Basic Windows:: Basic information on using windows.
-* Splitting Windows:: Splitting one window into two windows.
-* Deleting Windows:: Deleting a window gives its space to other windows.
-* Selecting Windows:: The selected window is the one that you edit in.
-* Cyclic Window Ordering:: Moving around the existing windows.
-* Buffers and Windows:: Each window displays the contents of a buffer.
-* Displaying Buffers:: Higher-lever functions for displaying a buffer
- and choosing a window for it.
-* Choosing Window:: How to choose a window for displaying a buffer.
-* Window Point:: Each window has its own location of point.
-* Window Start:: The display-start position controls which text
- is on-screen in the window.
-* Vertical Scrolling:: Moving text up and down in the window.
-* Horizontal Scrolling:: Moving text sideways on the window.
-* Size of Window:: Accessing the size of a window.
-* Position of Window:: Accessing the position of a window.
-* Resizing Windows:: Changing the size of a window.
-* Window Configurations:: Saving and restoring the state of the screen.
+* Buffer Basics:: What is a buffer?
+* Current Buffer:: Designating a buffer as current
+ so primitives will access its contents.
+* Buffer Names:: Accessing and changing buffer names.
+* Buffer File Name:: The buffer file name indicates which file is visited.
+* Buffer Modification:: A buffer is "modified" if it needs to be saved.
+* Modification Time:: Determining whether the visited file was changed
+ ``behind XEmacs's back''.
+* Read Only Buffers:: Modifying text is not allowed in a read-only buffer.
+* The Buffer List:: How to look at all the existing buffers.
+* Creating Buffers:: Functions that create buffers.
+* Killing Buffers:: Buffers exist until explicitly killed.
+* Indirect Buffers:: An indirect buffer shares text with some other buffer.
\1f
-File: lispref.info, Node: Basic Windows, Next: Splitting Windows, Up: Windows
-
-Basic Concepts of Emacs Windows
-===============================
+File: lispref.info, Node: Buffer Basics, Next: Current Buffer, Up: Buffers
+
+Buffer Basics
+=============
+
+ A "buffer" is a Lisp object containing text to be edited. Buffers
+are used to hold the contents of files that are being visited; there may
+also be buffers that are not visiting files. While several buffers may
+exist at one time, exactly one buffer is designated the "current
+buffer" at any time. Most editing commands act on the contents of the
+current buffer. Each buffer, including the current buffer, may or may
+not be displayed in any windows.
+
+ Buffers in Emacs editing are objects that have distinct names and
+hold text that can be edited. Buffers appear to Lisp programs as a
+special data type. You can think of the contents of a buffer as an
+extendible string; insertions and deletions may occur in any part of
+the buffer. *Note Text::.
+
+ A Lisp buffer object contains numerous pieces of information. Some
+of this information is directly accessible to the programmer through
+variables, while other information is accessible only through
+special-purpose functions. For example, the visited file name is
+directly accessible through a variable, while the value of point is
+accessible only through a primitive function.
+
+ Buffer-specific information that is directly accessible is stored in
+"buffer-local" variable bindings, which are variable values that are
+effective only in a particular buffer. This feature allows each buffer
+to override the values of certain variables. Most major modes override
+variables such as `fill-column' or `comment-column' in this way. For
+more information about buffer-local variables and functions related to
+them, see *Note Buffer-Local Variables::.
+
+ For functions and variables related to visiting files in buffers, see
+*Note Visiting Files:: and *Note Saving Buffers::. For functions and
+variables related to the display of buffers in windows, see *Note
+Buffers and Windows::.
+
+ - Function: bufferp object
+ This function returns `t' if OBJECT is a buffer, `nil' otherwise.
- A "window" in XEmacs is the physical area of the screen in which a
-buffer is displayed. The term is also used to refer to a Lisp object
-that represents that screen area in XEmacs Lisp. It should be clear
-from the context which is meant.
-
- XEmacs groups windows into frames. A frame represents an area of
-screen available for XEmacs to use. Each frame always contains at least
-one window, but you can subdivide it vertically or horizontally into
-multiple nonoverlapping Emacs windows.
-
- In each frame, at any time, one and only one window is designated as
-"selected within the frame". The frame's cursor appears in that
-window. At ant time, one frame is the selected frame; and the window
-selected within that frame is "the selected window". The selected
-window's buffer is usually the current buffer (except when `set-buffer'
-has been used). *Note Current Buffer::.
-
- For practical purposes, a window exists only while it is displayed in
-a frame. Once removed from the frame, the window is effectively deleted
-and should not be used, _even though there may still be references to
-it_ from other Lisp objects. Restoring a saved window configuration is
-the only way for a window no longer on the screen to come back to life.
-(*Note Deleting Windows::.)
-
- Each window has the following attributes:
-
- * containing frame
-
- * window height
-
- * window width
-
- * window edges with respect to the frame or screen
-
- * the buffer it displays
-
- * position within the buffer at the upper left of the window
-
- * amount of horizontal scrolling, in columns
-
- * point
-
- * the mark
-
- * how recently the window was selected
+\1f
+File: lispref.info, Node: Current Buffer, Next: Buffer Names, Prev: Buffer Basics, Up: Buffers
+
+The Current Buffer
+==================
+
+ There are, in general, many buffers in an Emacs session. At any
+time, one of them is designated as the "current buffer". This is the
+buffer in which most editing takes place, because most of the primitives
+for examining or changing text in a buffer operate implicitly on the
+current buffer (*note Text::). Normally the buffer that is displayed on
+the screen in the selected window is the current buffer, but this is not
+always so: a Lisp program can designate any buffer as current
+temporarily in order to operate on its contents, without changing what
+is displayed on the screen.
+
+ The way to designate a current buffer in a Lisp program is by calling
+`set-buffer'. The specified buffer remains current until a new one is
+designated.
+
+ When an editing command returns to the editor command loop, the
+command loop designates the buffer displayed in the selected window as
+current, to prevent confusion: the buffer that the cursor is in when
+Emacs reads a command is the buffer that the command will apply to.
+(*Note Command Loop::.) Therefore, `set-buffer' is not the way to
+switch visibly to a different buffer so that the user can edit it. For
+this, you must use the functions described in *Note Displaying
+Buffers::.
+
+ However, Lisp functions that change to a different current buffer
+should not depend on the command loop to set it back afterwards.
+Editing commands written in XEmacs Lisp can be called from other
+programs as well as from the command loop. It is convenient for the
+caller if the subroutine does not change which buffer is current
+(unless, of course, that is the subroutine's purpose). Therefore, you
+should normally use `set-buffer' within a `save-excursion' that will
+restore the current buffer when your function is done (*note
+Excursions::). Here is an example, the code for the command
+`append-to-buffer' (with the documentation string abridged):
+
+ (defun append-to-buffer (buffer start end)
+ "Append to specified buffer the text of the region.
+ ..."
+ (interactive "BAppend to buffer: \nr")
+ (let ((oldbuf (current-buffer)))
+ (save-excursion
+ (set-buffer (get-buffer-create buffer))
+ (insert-buffer-substring oldbuf start end))))
+
+This function binds a local variable to the current buffer, and then
+`save-excursion' records the values of point, the mark, and the
+original buffer. Next, `set-buffer' makes another buffer current.
+Finally, `insert-buffer-substring' copies the string from the original
+current buffer to the new current buffer.
+
+ If the buffer appended to happens to be displayed in some window,
+the next redisplay will show how its text has changed. Otherwise, you
+will not see the change immediately on the screen. The buffer becomes
+current temporarily during the execution of the command, but this does
+not cause it to be displayed.
+
+ If you make local bindings (with `let' or function arguments) for a
+variable that may also have buffer-local bindings, make sure that the
+same buffer is current at the beginning and at the end of the local
+binding's scope. Otherwise you might bind it in one buffer and unbind
+it in another! There are two ways to do this. In simple cases, you may
+see that nothing ever changes the current buffer within the scope of the
+binding. Otherwise, use `save-excursion' to make sure that the buffer
+current at the beginning is current again whenever the variable is
+unbound.
+
+ It is not reliable to change the current buffer back with
+`set-buffer', because that won't do the job if a quit happens while the
+wrong buffer is current. Here is what _not_ to do:
+
+ (let (buffer-read-only
+ (obuf (current-buffer)))
+ (set-buffer ...)
+ ...
+ (set-buffer obuf))
+
+Using `save-excursion', as shown below, handles quitting, errors, and
+`throw', as well as ordinary evaluation.
+
+ (let (buffer-read-only)
+ (save-excursion
+ (set-buffer ...)
+ ...))
+
+ - Function: current-buffer
+ This function returns the current buffer.
+
+ (current-buffer)
+ => #<buffer buffers.texi>
+
+ - Function: set-buffer buffer-or-name
+ This function makes BUFFER-OR-NAME the current buffer. It does
+ not display the buffer in the currently selected window or in any
+ other window, so the user cannot necessarily see the buffer. But
+ Lisp programs can in any case work on it.
+
+ BUFFER-OR-NAME must be a buffer or the name of an existing
+ buffer-else an error is signaled. This function returns the buffer
+ identified by BUFFER-OR-NAME.
- Users create multiple windows so they can look at several buffers at
-once. Lisp libraries use multiple windows for a variety of reasons, but
-most often to display related information. In Rmail, for example, you
-can move through a summary buffer in one window while the other window
-shows messages one at a time as they are reached.
+\1f
+File: lispref.info, Node: Buffer Names, Next: Buffer File Name, Prev: Current Buffer, Up: Buffers
- The meaning of "window" in XEmacs is similar to what it means in the
-context of general-purpose window systems such as X, but not identical.
-The X Window System places X windows on the screen; XEmacs uses one or
-more X windows as frames, and subdivides them into Emacs windows. When
-you use XEmacs on a character-only terminal, XEmacs treats the whole
-terminal screen as one frame.
+Buffer Names
+============
- Most window systems support arbitrarily located overlapping windows.
-In contrast, Emacs windows are "tiled"; they never overlap, and
-together they fill the whole screen or frame. Because of the way in
-which XEmacs creates new windows and resizes them, you can't create
-every conceivable tiling of windows on an Emacs frame. *Note Splitting
-Windows::, and *Note Size of Window::.
+ Each buffer has a unique name, which is a string. Many of the
+functions that work on buffers accept either a buffer or a buffer name
+as an argument. Any argument called BUFFER-OR-NAME is of this sort,
+and an error is signaled if it is neither a string nor a buffer. Any
+argument called BUFFER must be an actual buffer object, not a name.
- *Note Display::, for information on how the contents of the window's
-buffer are displayed in the window.
+ Buffers that are ephemeral and generally uninteresting to the user
+have names starting with a space, so that the `list-buffers' and
+`buffer-menu' commands don't mention them. A name starting with space
+also initially disables recording undo information; see *Note Undo::.
- - Function: windowp object
- This function returns `t' if OBJECT is a window.
+ - Function: buffer-name &optional buffer
+ This function returns the name of BUFFER as a string. If BUFFER
+ is not supplied, it defaults to the current buffer.
-\1f
-File: lispref.info, Node: Splitting Windows, Next: Deleting Windows, Prev: Basic Windows, Up: Windows
+ If `buffer-name' returns `nil', it means that BUFFER has been
+ killed. *Note Killing Buffers::.
-Splitting Windows
-=================
-
- The functions described here are the primitives used to split a
-window into two windows. Two higher level functions sometimes split a
-window, but not always: `pop-to-buffer' and `display-buffer' (*note
-Displaying Buffers::).
-
- The functions described here do not accept a buffer as an argument.
-The two "halves" of the split window initially display the same buffer
-previously visible in the window that was split.
-
- - Function: one-window-p &optional no-mini all-frames
- This function returns non-`nil' if there is only one window. The
- argument NO-MINI, if non-`nil', means don't count the minibuffer
- even if it is active; otherwise, the minibuffer window is
- included, if active, in the total number of windows which is
- compared against one.
-
- The argument ALL-FRAME controls which set of windows are counted.
- * If it is `nil' or omitted, then count only the selected
- frame, plus the minibuffer it uses (which may be on another
- frame).
-
- * If it is `t', then windows on all frames that currently exist
- (including invisible and iconified frames) are counted.
-
- * If it is the symbol `visible', then windows on all visible
- frames are counted.
-
- * If it is the number 0, then windows on all visible and
- iconified frames are counted.
-
- * If it is any other value, then precisely the windows in
- WINDOW's frame are counted, excluding the minibuffer in use
- if it lies in some other frame.
-
- - Command: split-window &optional window size horizontal
- This function splits WINDOW into two windows. The original window
- WINDOW remains the selected window, but occupies only part of its
- former screen area. The rest is occupied by a newly created
- window which is returned as the value of this function.
-
- If HORIZONTAL is non-`nil', then WINDOW splits into two side by
- side windows. The original window WINDOW keeps the leftmost SIZE
- columns, and gives the rest of the columns to the new window.
- Otherwise, it splits into windows one above the other, and WINDOW
- keeps the upper SIZE lines and gives the rest of the lines to the
- new window. The original window is therefore the left-hand or
- upper of the two, and the new window is the right-hand or lower.
-
- If WINDOW is omitted or `nil', then the selected window is split.
- If SIZE is omitted or `nil', then WINDOW is divided evenly into
- two parts. (If there is an odd line, it is allocated to the new
- window.) When `split-window' is called interactively, all its
- arguments are `nil'.
-
- The following example starts with one window on a frame that is 50
- lines high by 80 columns wide; then the window is split.
-
- (setq w (selected-window))
- => #<window 8 on windows.texi>
- (window-edges) ; Edges in order:
- => (0 0 80 50) ; left-top-right-bottom
+ (buffer-name)
+ => "buffers.texi"
- ;; Returns window created
- (setq w2 (split-window w 15))
- => #<window 28 on windows.texi>
- (window-edges w2)
- => (0 15 80 50) ; Bottom window;
- ; top is line 15
- (window-edges w)
- => (0 0 80 15) ; Top window
-
- The frame looks like this:
-
- __________
- | | line 0
- | w |
- |__________|
- | | line 15
- | w2 |
- |__________|
- line 50
- column 0 column 80
-
- Next, the top window is split horizontally:
-
- (setq w3 (split-window w 35 t))
- => #<window 32 on windows.texi>
- (window-edges w3)
- => (35 0 80 15) ; Left edge at column 35
- (window-edges w)
- => (0 0 35 15) ; Right edge at column 35
- (window-edges w2)
- => (0 15 80 50) ; Bottom window unchanged
-
- Now, the screen looks like this:
-
- column 35
- __________
- | | | line 0
- | w | w3 |
- |___|______|
- | | line 15
- | w2 |
- |__________|
- line 50
- column 0 column 80
-
- Normally, Emacs indicates the border between two side-by-side
- windows with a scroll bar (*note Scroll Bars: X Frame Properties.)
- or `|' characters. The display table can specify alternative
- border characters; see *Note Display Tables::.
-
- - Command: split-window-vertically &optional size
- This function splits the selected window into two windows, one
- above the other, leaving the selected window with SIZE lines.
-
- This function is simply an interface to `split-windows'. Here is
- the complete function definition for it:
-
- (defun split-window-vertically (&optional arg)
- "Split current window into two windows, one above the other."
- (interactive "P")
- (split-window nil (and arg (prefix-numeric-value arg))))
-
- - Command: split-window-horizontally &optional size
- This function splits the selected window into two windows
- side-by-side, leaving the selected window with SIZE columns.
-
- This function is simply an interface to `split-windows'. Here is
- the complete definition for `split-window-horizontally' (except for
- part of the documentation string):
-
- (defun split-window-horizontally (&optional arg)
- "Split selected window into two windows, side by side..."
- (interactive "P")
- (split-window nil (and arg (prefix-numeric-value arg)) t))
-
- - Function: one-window-p &optional no-mini all-frames
- This function returns non-`nil' if there is only one window. The
- argument NO-MINI, if non-`nil', means don't count the minibuffer
- even if it is active; otherwise, the minibuffer window is
- included, if active, in the total number of windows, which is
- compared against one.
-
- The argument ALL-FRAMES specifies which frames to consider. Here
- are the possible values and their meanings:
-
- `nil'
- Count the windows in the selected frame, plus the minibuffer
- used by that frame even if it lies in some other frame.
+ (setq foo (get-buffer "temp"))
+ => #<buffer temp>
+ (kill-buffer foo)
+ => nil
+ (buffer-name foo)
+ => nil
+ foo
+ => #<killed buffer>
+
+ - Command: rename-buffer newname &optional unique
+ This function renames the current buffer to NEWNAME. An error is
+ signaled if NEWNAME is not a string, or if there is already a
+ buffer with that name. The function returns `nil'.
+
+ Ordinarily, `rename-buffer' signals an error if NEWNAME is already
+ in use. However, if UNIQUE is non-`nil', it modifies NEWNAME to
+ make a name that is not in use. Interactively, you can make
+ UNIQUE non-`nil' with a numeric prefix argument.
+
+ One application of this command is to rename the `*shell*' buffer
+ to some other name, thus making it possible to create a second
+ shell buffer under the name `*shell*'.
+
+ - Function: get-buffer buffer-or-name
+ This function returns the buffer named BUFFER-OR-NAME. If
+ BUFFER-OR-NAME is a string and there is no buffer with that name,
+ the value is `nil'. If BUFFER-OR-NAME is actually a buffer, it is
+ returned as given. (That is not very useful, so the argument is
+ usually a name.) For example:
+
+ (setq b (get-buffer "lewis"))
+ => #<buffer lewis>
+ (get-buffer b)
+ => #<buffer lewis>
+ (get-buffer "Frazzle-nots")
+ => nil
- `t'
- Count all windows in all existing frames.
+ See also the function `get-buffer-create' in *Note Creating
+ Buffers::.
- `visible'
- Count all windows in all visible frames.
+ - Function: generate-new-buffer-name starting-name &optional ignore
+ This function returns a name that would be unique for a new
+ buffer--but does not create the buffer. It starts with
+ STARTING-NAME, and produces a name not currently in use for any
+ buffer by appending a number inside of `<...>'.
- 0
- Count all windows in all visible or iconified frames.
+ If IGNORE is given, it specifies a name that is okay to use (if it
+ is in the sequence to be tried), even if a buffer with that name
+ exists.
- anything else
- Count precisely the windows in the selected frame, and no
- others.
+ See the related function `generate-new-buffer' in *Note Creating
+ Buffers::.
\1f
-File: lispref.info, Node: Deleting Windows, Next: Selecting Windows, Prev: Splitting Windows, Up: Windows
+File: lispref.info, Node: Buffer File Name, Next: Buffer Modification, Prev: Buffer Names, Up: Buffers
-Deleting Windows
+Buffer File Name
================
- A window remains visible on its frame unless you "delete" it by
-calling certain functions that delete windows. A deleted window cannot
-appear on the screen, but continues to exist as a Lisp object until
-there are no references to it. There is no way to cancel the deletion
-of a window aside from restoring a saved window configuration (*note
-Window Configurations::). Restoring a window configuration also
-deletes any windows that aren't part of that configuration.
-
- When you delete a window, the space it took up is given to one
-adjacent sibling. (In Emacs version 18, the space was divided evenly
-among all the siblings.)
-
- - Function: window-live-p window
- This function returns `nil' if WINDOW is deleted, and `t'
- otherwise.
-
- *Warning:* Erroneous information or fatal errors may result from
- using a deleted window as if it were live.
-
- - Command: delete-window &optional window
- This function removes WINDOW from the display. If WINDOW is
- omitted, then the selected window is deleted. An error is signaled
- if there is only one window when `delete-window' is called.
-
- This function returns `nil'.
-
- When `delete-window' is called interactively, WINDOW defaults to
- the selected window.
-
- - Command: delete-other-windows &optional window
- This function makes WINDOW the only window on its frame, by
- deleting the other windows in that frame. If WINDOW is omitted or
- `nil', then the selected window is used by default.
-
- The result is `nil'.
-
- - Command: delete-windows-on buffer &optional frame
- This function deletes all windows showing BUFFER. If there are no
- windows showing BUFFER, it does nothing.
-
- `delete-windows-on' operates frame by frame. If a frame has
- several windows showing different buffers, then those showing
- BUFFER are removed, and the others expand to fill the space. If
- all windows in some frame are showing BUFFER (including the case
- where there is only one window), then the frame reverts to having a
- single window showing another buffer chosen with `other-buffer'.
- *Note The Buffer List::.
-
- The argument FRAME controls which frames to operate on:
-
- * If it is `nil', operate on the selected frame.
-
- * If it is `t', operate on all frames.
-
- * If it is `visible', operate on all visible frames.
-
- * 0 If it is 0, operate on all visible or iconified frames.
-
- * If it is a frame, operate on that frame.
-
- This function always returns `nil'.
+ The "buffer file name" is the name of the file that is visited in
+that buffer. When a buffer is not visiting a file, its buffer file name
+is `nil'. Most of the time, the buffer name is the same as the
+nondirectory part of the buffer file name, but the buffer file name and
+the buffer name are distinct and can be set independently. *Note
+Visiting Files::.
+
+ - Function: buffer-file-name &optional buffer
+ This function returns the absolute file name of the file that
+ BUFFER is visiting. If BUFFER is not visiting any file,
+ `buffer-file-name' returns `nil'. If BUFFER is not supplied, it
+ defaults to the current buffer.
+
+ (buffer-file-name (other-buffer))
+ => "/usr/user/lewis/manual/files.texi"
+
+ - Variable: buffer-file-name
+ This buffer-local variable contains the name of the file being
+ visited in the current buffer, or `nil' if it is not visiting a
+ file. It is a permanent local, unaffected by
+ `kill-local-variables'.
+
+ buffer-file-name
+ => "/usr/user/lewis/manual/buffers.texi"
+
+ It is risky to change this variable's value without doing various
+ other things. See the definition of `set-visited-file-name' in
+ `files.el'; some of the things done there, such as changing the
+ buffer name, are not strictly necessary, but others are essential
+ to avoid confusing XEmacs.
+
+ - Variable: buffer-file-truename
+ This buffer-local variable holds the truename of the file visited
+ in the current buffer, or `nil' if no file is visited. It is a
+ permanent local, unaffected by `kill-local-variables'. *Note
+ Truenames::.
+
+ - Variable: buffer-file-number
+ This buffer-local variable holds the file number and directory
+ device number of the file visited in the current buffer, or `nil'
+ if no file or a nonexistent file is visited. It is a permanent
+ local, unaffected by `kill-local-variables'. *Note Truenames::.
+
+ The value is normally a list of the form `(FILENUM DEVNUM)'. This
+ pair of numbers uniquely identifies the file among all files
+ accessible on the system. See the function `file-attributes', in
+ *Note File Attributes::, for more information about them.
+
+ - Function: get-file-buffer filename
+ This function returns the buffer visiting file FILENAME. If there
+ is no such buffer, it returns `nil'. The argument FILENAME, which
+ must be a string, is expanded (*note File Name Expansion::), then
+ compared against the visited file names of all live buffers.
+
+ (get-file-buffer "buffers.texi")
+ => #<buffer buffers.texi>
+
+ In unusual circumstances, there can be more than one buffer
+ visiting the same file name. In such cases, this function returns
+ the first such buffer in the buffer list.
+
+ - Command: set-visited-file-name filename
+ If FILENAME is a non-empty string, this function changes the name
+ of the file visited in current buffer to FILENAME. (If the buffer
+ had no visited file, this gives it one.) The _next time_ the
+ buffer is saved it will go in the newly-specified file. This
+ command marks the buffer as modified, since it does not (as far as
+ XEmacs knows) match the contents of FILENAME, even if it matched
+ the former visited file.
+
+ If FILENAME is `nil' or the empty string, that stands for "no
+ visited file". In this case, `set-visited-file-name' marks the
+ buffer as having no visited file.
+
+ When the function `set-visited-file-name' is called interactively,
+ it prompts for FILENAME in the minibuffer.
+
+ See also `clear-visited-file-modtime' and
+ `verify-visited-file-modtime' in *Note Buffer Modification::.
+
+ - Variable: list-buffers-directory
+ This buffer-local variable records a string to display in a buffer
+ listing in place of the visited file name, for buffers that don't
+ have a visited file name. Dired buffers use this variable.
\1f
-File: lispref.info, Node: Selecting Windows, Next: Cyclic Window Ordering, Prev: Deleting Windows, Up: Windows
-
-Selecting Windows
-=================
-
- When a window is selected, the buffer in the window becomes the
-current buffer, and the cursor will appear in it.
-
- - Function: selected-window &optional device
- This function returns the selected window. This is the window in
- which the cursor appears and to which many commands apply. Each
- separate device can have its own selected window, which is
- remembered as focus changes from device to device. Optional
- argument DEVICE specifies which device to return the selected
- window for, and defaults to the selected device.
-
- - Function: select-window window &optional norecord
- This function makes WINDOW the selected window. The cursor then
- appears in WINDOW (on redisplay). The buffer being displayed in
- WINDOW is immediately designated the current buffer.
-
- If optional argument NORECORD is non-`nil' then the global and
- per-frame buffer orderings are not modified, as by the function
- `record-buffer'.
-
- The return value is WINDOW.
-
- (setq w (next-window))
- (select-window w)
- => #<window 65 on windows.texi>
-
- - Macro: save-selected-window forms...
- This macro records the selected window, executes FORMS in
- sequence, then restores the earlier selected window. It does not
- save or restore anything about the sizes, arrangement or contents
- of windows; therefore, if the FORMS change them, the changes are
- permanent.
+File: lispref.info, Node: Buffer Modification, Next: Modification Time, Prev: Buffer File Name, Up: Buffers
- The following functions choose one of the windows on the screen,
-offering various criteria for the choice.
-
- - Function: get-lru-window &optional frame
- This function returns the window least recently "used" (that is,
- selected). The selected window is always the most recently used
- window.
-
- The selected window can be the least recently used window if it is
- the only window. A newly created window becomes the least
- recently used window until it is selected. A minibuffer window is
- never a candidate.
-
- The argument FRAME controls which windows are considered.
-
- * If it is `nil', consider windows on the selected frame.
-
- * If it is `t', consider windows on all frames.
-
- * If it is `visible', consider windows on all visible frames.
-
- * If it is 0, consider windows on all visible or iconified
- frames.
-
- * If it is a frame, consider windows on that frame.
-
- - Function: get-largest-window &optional frame
- This function returns the window with the largest area (height
- times width). If there are no side-by-side windows, then this is
- the window with the most lines. A minibuffer window is never a
- candidate.
-
- If there are two windows of the same size, then the function
- returns the window that is first in the cyclic ordering of windows
- (see following section), starting from the selected window.
+Buffer Modification
+===================
- The argument FRAME controls which set of windows are considered.
- See `get-lru-window', above.
+ XEmacs keeps a flag called the "modified flag" for each buffer, to
+record whether you have changed the text of the buffer. This flag is
+set to `t' whenever you alter the contents of the buffer, and cleared
+to `nil' when you save it. Thus, the flag shows whether there are
+unsaved changes. The flag value is normally shown in the modeline
+(*note Modeline Variables::), and controls saving (*note Saving
+Buffers::) and auto-saving (*note Auto-Saving::).
+
+ Some Lisp programs set the flag explicitly. For example, the
+function `set-visited-file-name' sets the flag to `t', because the text
+does not match the newly-visited file, even if it is unchanged from the
+file formerly visited.
+
+ The functions that modify the contents of buffers are described in
+*Note Text::.
+
+ - Function: buffer-modified-p &optional buffer
+ This function returns `t' if the buffer BUFFER has been modified
+ since it was last read in from a file or saved, or `nil'
+ otherwise. If BUFFER is not supplied, the current buffer is
+ tested.
+
+ - Function: set-buffer-modified-p flag &optional buffer
+ This function marks BUFFER as modified if FLAG is non-`nil', or as
+ unmodified if the flag is `nil'. BUFFER defaults to the current
+ buffer.
+
+ Another effect of calling this function is to cause unconditional
+ redisplay of the modeline for the current buffer. In fact, the
+ function `redraw-modeline' works by doing this:
+
+ (set-buffer-modified-p (buffer-modified-p))
+
+ - Command: not-modified &optional arg
+ This command marks the current buffer as unmodified, and not
+ needing to be saved. (If ARG is non-`nil', the buffer is instead
+ marked as modified.) Don't use this function in programs, since it
+ prints a message in the echo area; use `set-buffer-modified-p'
+ (above) instead.
+
+ - Function: buffer-modified-tick &optional buffer
+ This function returns BUFFER`s modification-count. This is a
+ counter that increments every time the buffer is modified. If
+ BUFFER is `nil' (or omitted), the current buffer is used.
\1f
-File: lispref.info, Node: Cyclic Window Ordering, Next: Buffers and Windows, Prev: Selecting Windows, Up: Windows
-
-Cyclic Ordering of Windows
-==========================
-
- When you use the command `C-x o' (`other-window') to select the next
-window, it moves through all the windows on the screen in a specific
-cyclic order. For any given configuration of windows, this order never
-varies. It is called the "cyclic ordering of windows".
-
- This ordering generally goes from top to bottom, and from left to
-right. But it may go down first or go right first, depending on the
-order in which the windows were split.
-
- If the first split was vertical (into windows one above each other),
-and then the subwindows were split horizontally, then the ordering is
-left to right in the top of the frame, and then left to right in the
-next lower part of the frame, and so on. If the first split was
-horizontal, the ordering is top to bottom in the left part, and so on.
-In general, within each set of siblings at any level in the window tree,
-the order is left to right, or top to bottom.
-
- - Function: next-window &optional window minibuf all-frames
- This function returns the window following WINDOW in the cyclic
- ordering of windows. This is the window that `C-x o' would select
- if typed when WINDOW is selected. If WINDOW is the only window
- visible, then this function returns WINDOW. If omitted, WINDOW
- defaults to the selected window.
-
- The value of the argument MINIBUF determines whether the
- minibuffer is included in the window order. Normally, when
- MINIBUF is `nil', the minibuffer is included if it is currently
- active; this is the behavior of `C-x o'. (The minibuffer window
- is active while the minibuffer is in use. *Note Minibuffers::.)
-
- If MINIBUF is `t', then the cyclic ordering includes the
- minibuffer window even if it is not active.
-
- If MINIBUF is neither `t' nor `nil', then the minibuffer window is
- not included even if it is active.
-
- The argument ALL-FRAMES specifies which frames to consider. Here
- are the possible values and their meanings:
-
- `nil'
- Consider all the windows in WINDOW's frame, plus the
- minibuffer used by that frame even if it lies in some other
- frame.
-
- `t'
- Consider all windows in all existing frames.
-
- `visible'
- Consider all windows in all visible frames. (To get useful
- results, you must ensure WINDOW is in a visible frame.)
-
- 0
- Consider all windows in all visible or iconified frames.
-
- anything else
- Consider precisely the windows in WINDOW's frame, and no
- others.
+File: lispref.info, Node: Modification Time, Next: Read Only Buffers, Prev: Buffer Modification, Up: Buffers
- This example assumes there are two windows, both displaying the
- buffer `windows.texi':
-
- (selected-window)
- => #<window 56 on windows.texi>
- (next-window (selected-window))
- => #<window 52 on windows.texi>
- (next-window (next-window (selected-window)))
- => #<window 56 on windows.texi>
-
- - Function: previous-window &optional window minibuf all-frames
- This function returns the window preceding WINDOW in the cyclic
- ordering of windows. The other arguments specify which windows to
- include in the cycle, as in `next-window'.
-
- - Command: other-window count &optional frame
- This function selects the COUNTth following window in the cyclic
- order. If count is negative, then it selects the -COUNTth
- preceding window. It returns `nil'.
-
- In an interactive call, COUNT is the numeric prefix argument.
-
- The argument FRAME controls which set of windows are considered.
- * If it is `nil' or omitted, then windows on the selected frame
- are considered.
-
- * If it is a frame, then windows on that frame are considered.
-
- * If it is `t', then windows on all frames that currently exist
- (including invisible and iconified frames) are considered.
-
- * If it is the symbol `visible', then windows on all visible
- frames are considered.
-
- * If it is the number 0, then windows on all visible and
- iconified frames are considered.
-
- * If it is any other value, then the behavior is undefined.
-
- - Function: walk-windows proc &optional minibuf all-frames
- This function cycles through all windows, calling `proc' once for
- each window with the window as its sole argument.
+Comparison of Modification Time
+===============================
- The optional arguments MINIBUF and ALL-FRAMES specify the set of
- windows to include in the scan. See `next-window', above, for
- details.
+ Suppose that you visit a file and make changes in its buffer, and
+meanwhile the file itself is changed on disk. At this point, saving the
+buffer would overwrite the changes in the file. Occasionally this may
+be what you want, but usually it would lose valuable information.
+XEmacs therefore checks the file's modification time using the functions
+described below before saving the file.
+
+ - Function: verify-visited-file-modtime buffer
+ This function compares what BUFFER has recorded for the
+ modification time of its visited file against the actual
+ modification time of the file as recorded by the operating system.
+ The two should be the same unless some other process has written
+ the file since XEmacs visited or saved it.
+
+ The function returns `t' if the last actual modification time and
+ XEmacs's recorded modification time are the same, `nil' otherwise.
+
+ - Function: clear-visited-file-modtime
+ This function clears out the record of the last modification time
+ of the file being visited by the current buffer. As a result, the
+ next attempt to save this buffer will not complain of a
+ discrepancy in file modification times.
+
+ This function is called in `set-visited-file-name' and other
+ exceptional places where the usual test to avoid overwriting a
+ changed file should not be done.
+
+ - Function: visited-file-modtime
+ This function returns the buffer's recorded last file modification
+ time, as a list of the form `(HIGH . LOW)'. (This is the same
+ format that `file-attributes' uses to return time values; see
+ *Note File Attributes::.)
+
+ - Function: set-visited-file-modtime &optional time
+ This function updates the buffer's record of the last modification
+ time of the visited file, to the value specified by TIME if TIME
+ is not `nil', and otherwise to the last modification time of the
+ visited file.
+
+ If TIME is not `nil', it should have the form `(HIGH . LOW)' or
+ `(HIGH LOW)', in either case containing two integers, each of
+ which holds 16 bits of the time.
+
+ This function is useful if the buffer was not read from the file
+ normally, or if the file itself has been changed for some known
+ benign reason.
+
+ - Function: ask-user-about-supersession-threat filename
+ This function is used to ask a user how to proceed after an
+ attempt to modify an obsolete buffer visiting file FILENAME. An
+ "obsolete buffer" is an unmodified buffer for which the associated
+ file on disk is newer than the last save-time of the buffer. This
+ means some other program has probably altered the file.
+
+ Depending on the user's answer, the function may return normally,
+ in which case the modification of the buffer proceeds, or it may
+ signal a `file-supersession' error with data `(FILENAME)', in which
+ case the proposed buffer modification is not allowed.
+
+ This function is called automatically by XEmacs on the proper
+ occasions. It exists so you can customize XEmacs by redefining it.
+ See the file `userlock.el' for the standard definition.
+
+ See also the file locking mechanism in *Note File Locks::.
\1f
-File: lispref.info, Node: Buffers and Windows, Next: Displaying Buffers, Prev: Cyclic Window Ordering, Up: Windows
-
-Buffers and Windows
-===================
-
- This section describes low-level functions to examine windows or to
-display buffers in windows in a precisely controlled fashion. *Note
-Displaying Buffers::, for related functions that find a window to use
-and specify a buffer for it. The functions described there are easier
-to use than these, but they employ heuristics in choosing or creating a
-window; use these functions when you need complete control.
+File: lispref.info, Node: Read Only Buffers, Next: The Buffer List, Prev: Modification Time, Up: Buffers
- - Function: set-window-buffer window buffer-or-name
- This function makes WINDOW display BUFFER-OR-NAME as its contents.
- It returns `nil'.
-
- (set-window-buffer (selected-window) "foo")
- => nil
+Read-Only Buffers
+=================
- - Function: window-buffer &optional window
- This function returns the buffer that WINDOW is displaying. If
- WINDOW is omitted, this function returns the buffer for the
- selected window.
+ If a buffer is "read-only", then you cannot change its contents,
+although you may change your view of the contents by scrolling and
+narrowing.
+
+ Read-only buffers are used in two kinds of situations:
+
+ * A buffer visiting a write-protected file is normally read-only.
+
+ Here, the purpose is to show the user that editing the buffer with
+ the aim of saving it in the file may be futile or undesirable.
+ The user who wants to change the buffer text despite this can do
+ so after clearing the read-only flag with `C-x C-q'.
+
+ * Modes such as Dired and Rmail make buffers read-only when altering
+ the contents with the usual editing commands is probably a mistake.
+
+ The special commands of these modes bind `buffer-read-only' to
+ `nil' (with `let') or bind `inhibit-read-only' to `t' around the
+ places where they change the text.
+
+ - Variable: buffer-read-only
+ This buffer-local variable specifies whether the buffer is
+ read-only. The buffer is read-only if this variable is non-`nil'.
+
+ - Variable: inhibit-read-only
+ If this variable is non-`nil', then read-only buffers and read-only
+ characters may be modified. Read-only characters in a buffer are
+ those that have non-`nil' `read-only' properties (either text
+ properties or extent properties). *Note Extent Properties::, for
+ more information about text properties and extent properties.
+
+ If `inhibit-read-only' is `t', all `read-only' character
+ properties have no effect. If `inhibit-read-only' is a list, then
+ `read-only' character properties have no effect if they are members
+ of the list (comparison is done with `eq').
+
+ - Command: toggle-read-only &optional arg
+ This command changes whether the current buffer is read-only.
+ Interactively, if a prefix arg ARG is supplied, set the current
+ buffer read only if and only if ARG is positive.
+
+ This command is intended for interactive use only; don't use it in
+ programs. At any given point in a program, you should know
+ whether you want the read-only flag on or off; so you can set
+ `buffer-read-only' explicitly to the proper value, `t' or `nil'.
+
+ - Function: barf-if-buffer-read-only &optional buffer start end
+ This function signals a `buffer-read-only' error if BUFFER is
+ read-only. BUFFER defaults to the current buffer. *Note
+ Interactive Call::, for another way to signal an error if the
+ current buffer is read-only.
+
+ If optional argument START is non-`nil', all extents in the buffer
+ which overlap that part of the buffer are checked to ensure none
+ has a `read-only' property. (Extents that lie completely within the
+ range, however, are not checked.) END defaults to the value of
+ START.
+
+ If START and END are equal, the range checked is [START, END]
+ (i.e. closed on both ends); otherwise, the range checked is
+ (START, END) \(open on both ends), except that extents that lie
+ completely within [START, END] are not checked. See
+ `extent-in-region-p' for a fuller discussion.
- (window-buffer)
- => #<buffer windows.texi>
+\1f
+File: lispref.info, Node: The Buffer List, Next: Creating Buffers, Prev: Read Only Buffers, Up: Buffers
- - Function: get-buffer-window buffer-or-name &optional frame
- This function returns a window currently displaying
- BUFFER-OR-NAME, or `nil' if there is none. If there are several
- such windows, then the function returns the first one in the
- cyclic ordering of windows, starting from the selected window.
- *Note Cyclic Window Ordering::.
+The Buffer List
+===============
- The argument ALL-FRAMES controls which windows to consider.
+ The "buffer list" is a list of all live buffers. Creating a buffer
+adds it to this list, and killing a buffer deletes it. The order of
+the buffers in the list is based primarily on how recently each buffer
+has been displayed in the selected window. Buffers move to the front
+of the list when they are selected and to the end when they are buried.
+Several functions, notably `other-buffer', use this ordering. A
+buffer list displayed for the user also follows this order.
- * If it is `nil', consider windows on the selected frame.
+ Every frame has its own order for the buffer list. Switching to a
+new buffer inside of a particular frame changes the buffer list order
+for that frame, but does not affect the buffer list order of any other
+frames. In addition, there is a global, non-frame buffer list order
+that is independent of the buffer list orders for any particular frame.
- * If it is `t', consider windows on all frames.
+ Note that the different buffer lists all contain the same elements.
+It is only the order of those elements that is different.
- * If it is `visible', consider windows on all visible frames.
+ - Function: buffer-list &optional frame
+ This function returns a list of all buffers, including those whose
+ names begin with a space. The elements are actual buffers, not
+ their names. The order of the list is specific to FRAME, which
+ defaults to the current frame. If FRAME is `t', the global,
+ non-frame ordering is returned instead.
- * If it is 0, consider windows on all visible or iconified
- frames.
+ (buffer-list)
+ => (#<buffer buffers.texi>
+ #<buffer *Minibuf-1*> #<buffer buffer.c>
+ #<buffer *Help*> #<buffer TAGS>)
+
+ ;; Note that the name of the minibuffer
+ ;; begins with a space!
+ (mapcar (function buffer-name) (buffer-list))
+ => ("buffers.texi" " *Minibuf-1*"
+ "buffer.c" "*Help*" "TAGS")
- * If it is a frame, consider windows on that frame.
+ Buffers appear earlier in the list if they were current more
+ recently.
-\1f
-File: lispref.info, Node: Displaying Buffers, Next: Choosing Window, Prev: Buffers and Windows, Up: Windows
-
-Displaying Buffers in Windows
-=============================
-
- In this section we describe convenient functions that choose a window
-automatically and use it to display a specified buffer. These functions
-can also split an existing window in certain circumstances. We also
-describe variables that parameterize the heuristics used for choosing a
-window. *Note Buffers and Windows::, for low-level functions that give
-you more precise control.
-
- Do not use the functions in this section in order to make a buffer
-current so that a Lisp program can access or modify it; they are too
-drastic for that purpose, since they change the display of buffers in
-windows, which is gratuitous and will surprise the user. Instead, use
-`set-buffer' (*note Current Buffer::) and `save-excursion' (*note
-Excursions::), which designate buffers as current for programmed access
-without affecting the display of buffers in windows.
-
- - Command: switch-to-buffer buffer-or-name &optional norecord
- This function makes BUFFER-OR-NAME the current buffer, and also
- displays the buffer in the selected window. This means that a
- human can see the buffer and subsequent keyboard commands will
- apply to it. Contrast this with `set-buffer', which makes
- BUFFER-OR-NAME the current buffer but does not display it in the
- selected window. *Note Current Buffer::.
-
- If BUFFER-OR-NAME does not identify an existing buffer, then a new
- buffer by that name is created. The major mode for the new buffer
- is set according to the variable `default-major-mode'. *Note Auto
- Major Mode::.
-
- Normally the specified buffer is put at the front of the buffer
- list. This affects the operation of `other-buffer'. However, if
- NORECORD is non-`nil', this is not done. *Note The Buffer List::.
-
- The `switch-to-buffer' function is often used interactively, as
- the binding of `C-x b'. It is also used frequently in programs.
- It always returns `nil'.
-
- - Command: switch-to-buffer-other-window buffer-or-name
- This function makes BUFFER-OR-NAME the current buffer and displays
- it in a window not currently selected. It then selects that
- window. The handling of the buffer is the same as in
- `switch-to-buffer'.
-
- The currently selected window is absolutely never used to do the
- job. If it is the only window, then it is split to make a
- distinct window for this purpose. If the selected window is
- already displaying the buffer, then it continues to do so, but
- another window is nonetheless found to display it in as well.
-
- - Function: pop-to-buffer buffer-or-name &optional other-window
- on-frame
- This function makes BUFFER-OR-NAME the current buffer and switches
- to it in some window, preferably not the window previously
- selected. The "popped-to" window becomes the selected window
- within its frame.
-
- If the variable `pop-up-frames' is non-`nil', `pop-to-buffer'
- looks for a window in any visible frame already displaying the
- buffer; if there is one, it returns that window and makes it be
- selected within its frame. If there is none, it creates a new
- frame and displays the buffer in it.
-
- If `pop-up-frames' is `nil', then `pop-to-buffer' operates
- entirely within the selected frame. (If the selected frame has
- just a minibuffer, `pop-to-buffer' operates within the most
- recently selected frame that was not just a minibuffer.)
-
- If the variable `pop-up-windows' is non-`nil', windows may be
- split to create a new window that is different from the original
- window. For details, see *Note Choosing Window::.
-
- If OTHER-WINDOW is non-`nil', `pop-to-buffer' finds or creates
- another window even if BUFFER-OR-NAME is already visible in the
- selected window. Thus BUFFER-OR-NAME could end up displayed in
- two windows. On the other hand, if BUFFER-OR-NAME is already
- displayed in the selected window and OTHER-WINDOW is `nil', then
- the selected window is considered sufficient display for
- BUFFER-OR-NAME, so that nothing needs to be done.
-
- All the variables that affect `display-buffer' affect
- `pop-to-buffer' as well. *Note Choosing Window::.
-
- If BUFFER-OR-NAME is a string that does not name an existing
- buffer, a buffer by that name is created. The major mode for the
- new buffer is set according to the variable `default-major-mode'.
- *Note Auto Major Mode::.
-
- If ON-FRAME is non-`nil', it is the frame to pop to this buffer on.
-
- An example use of this function is found at the end of *Note
- Filter Functions::.
-
- - Command: replace-buffer-in-windows buffer
- This function replaces BUFFER with some other buffer in all
- windows displaying it. The other buffer used is chosen with
- `other-buffer'. In the usual applications of this function, you
- don't care which other buffer is used; you just want to make sure
- that BUFFER is no longer displayed.
-
- This function returns `nil'.
+ This list is a copy of a list used inside XEmacs; modifying it has
+ no effect on the buffers.
-\1f
-File: lispref.info, Node: Choosing Window, Next: Window Point, Prev: Displaying Buffers, Up: Windows
+ - Function: other-buffer &optional buffer-or-name frame visible-ok
+ This function returns the first buffer in the buffer list other
+ than BUFFER-OR-NAME, in FRAME's ordering for the buffer list.
+ (FRAME defaults to the current frame. If FRAME is `t', then the
+ global, non-frame ordering is used.) Usually this is the buffer
+ most recently shown in the selected window, aside from
+ BUFFER-OR-NAME. Buffers are moved to the front of the list when
+ they are selected and to the end when they are buried. Buffers
+ whose names start with a space are not considered.
-Choosing a Window for Display
-=============================
+ If BUFFER-OR-NAME is not supplied (or if it is not a buffer), then
+ `other-buffer' returns the first buffer on the buffer list that is
+ not visible in any window in a visible frame.
- This section describes the basic facility that chooses a window to
-display a buffer in--`display-buffer'. All the higher-level functions
-and commands use this subroutine. Here we describe how to use
-`display-buffer' and how to customize it.
+ If the selected frame has a non-`nil' `buffer-predicate' property,
+ then `other-buffer' uses that predicate to decide which buffers to
+ consider. It calls the predicate once for each buffer, and if the
+ value is `nil', that buffer is ignored. *Note X Frame
+ Properties::.
- - Command: display-buffer buffer-or-name &optional not-this-window
- This command makes BUFFER-OR-NAME appear in some window, like
- `pop-to-buffer', but it does not select that window and does not
- make the buffer current. The identity of the selected window is
- unaltered by this function.
+ If VISIBLE-OK is `nil', `other-buffer' avoids returning a buffer
+ visible in any window on any visible frame, except as a last
+ resort. If VISIBLE-OK is non-`nil', then it does not matter
+ whether a buffer is displayed somewhere or not.
- If NOT-THIS-WINDOW is non-`nil', it means to display the specified
- buffer in a window other than the selected one, even if it is
- already on display in the selected window. This can cause the
- buffer to appear in two windows at once. Otherwise, if
- BUFFER-OR-NAME is already being displayed in any window, that is
- good enough, so this function does nothing.
+ If no suitable buffer exists, the buffer `*scratch*' is returned
+ (and created, if necessary).
- `display-buffer' returns the window chosen to display
- BUFFER-OR-NAME.
+ Note that in FSF Emacs 19, there is no FRAME argument, and
+ VISIBLE-OK is the second argument instead of the third.
- Precisely how `display-buffer' finds or creates a window depends on
- the variables described below.
+ - Command: list-buffers &optional files-only
+ This function displays a listing of the names of existing buffers.
+ It clears the buffer `*Buffer List*', then inserts the listing
+ into that buffer and displays it in a window. `list-buffers' is
+ intended for interactive use, and is described fully in `The XEmacs
+ Reference Manual'. It returns `nil'.
- A window can be marked as "dedicated" to a particular buffer. Then
-XEmacs will not automatically change which buffer appears in the
-window, such as `display-buffer' might normally do.
+ - Command: bury-buffer &optional buffer-or-name before
+ This function puts BUFFER-OR-NAME at the end of the buffer list
+ without changing the order of any of the other buffers on the list.
+ This buffer therefore becomes the least desirable candidate for
+ `other-buffer' to return.
- - Function: window-dedicated-p window
- This function returns WINDOW's dedicated object, usually `t' or
- `nil'.
+ If BUFFER-OR-NAME is `nil' or omitted, this means to bury the
+ current buffer. In addition, if the buffer is displayed in the
+ selected window, this switches to some other buffer (obtained using
+ `other-buffer') in the selected window. But if the buffer is
+ displayed in some other window, it remains displayed there.
- - Function: set-window-buffer-dedicated window buffer
- This function makes WINDOW display BUFFER and be dedicated to that
- buffer. Then XEmacs will not automatically change which buffer
- appears in WINDOW. If BUFFER is `nil', this function makes WINDOW
- not be dedicated (but doesn't change which buffer appears in it
- currently).
-
- - User Option: pop-up-windows
- This variable controls whether `display-buffer' makes new windows.
- If it is non-`nil' and there is only one window, then that window
- is split. If it is `nil', then `display-buffer' does not split
- the single window, but uses it whole.
-
- - User Option: split-height-threshold
- This variable determines when `display-buffer' may split a window,
- if there are multiple windows. `display-buffer' always splits the
- largest window if it has at least this many lines. If the largest
- window is not this tall, it is split only if it is the sole window
- and `pop-up-windows' is non-`nil'.
-
- - User Option: pop-up-frames
- This variable controls whether `display-buffer' makes new frames.
- If it is non-`nil', `display-buffer' looks for an existing window
- already displaying the desired buffer, on any visible frame. If
- it finds one, it returns that window. Otherwise it makes a new
- frame. The variables `pop-up-windows' and
- `split-height-threshold' do not matter if `pop-up-frames' is
- non-`nil'.
-
- If `pop-up-frames' is `nil', then `display-buffer' either splits a
- window or reuses one.
-
- *Note Frames::, for more information.
-
- - Variable: pop-up-frame-function
- This variable specifies how to make a new frame if `pop-up-frames'
- is non-`nil'.
-
- Its value should be a function of no arguments. When
- `display-buffer' makes a new frame, it does so by calling that
- function, which should return a frame. The default value of the
- variable is a function that creates a frame using properties from
- `pop-up-frame-plist'.
-
- - Variable: pop-up-frame-plist
- This variable holds a plist specifying frame properties used when
- `display-buffer' makes a new frame. *Note Frame Properties::, for
- more information about frame properties.
-
- - Variable: special-display-buffer-names
- A list of buffer names for buffers that should be displayed
- specially. If the buffer's name is in this list, `display-buffer'
- handles the buffer specially.
-
- By default, special display means to give the buffer a dedicated
- frame.
-
- If an element is a list, instead of a string, then the CAR of the
- list is the buffer name, and the rest of the list says how to
- create the frame. There are two possibilities for the rest of the
- list. It can be a plist, specifying frame properties, or it can
- contain a function and arguments to give to it. (The function's
- first argument is always the buffer to be displayed; the arguments
- from the list come after that.)
-
- - Variable: special-display-regexps
- A list of regular expressions that specify buffers that should be
- displayed specially. If the buffer's name matches any of the
- regular expressions in this list, `display-buffer' handles the
- buffer specially.
-
- By default, special display means to give the buffer a dedicated
- frame.
-
- If an element is a list, instead of a string, then the CAR of the
- list is the regular expression, and the rest of the list says how
- to create the frame. See above, under
- `special-display-buffer-names'.
-
- - Variable: special-display-function
- This variable holds the function to call to display a buffer
- specially. It receives the buffer as an argument, and should
- return the window in which it is displayed.
-
- The default value of this variable is
- `special-display-popup-frame'.
-
- - Function: special-display-popup-frame buffer
- This function makes BUFFER visible in a frame of its own. If
- BUFFER is already displayed in a window in some frame, it makes
- the frame visible and raises it, to use that window. Otherwise, it
- creates a frame that will be dedicated to BUFFER.
-
- This function uses an existing window displaying BUFFER whether or
- not it is in a frame of its own; but if you set up the above
- variables in your init file, before BUFFER was created, then
- presumably the window was previously made by this function.
-
- - User Option: special-display-frame-plist
- This variable holds frame properties for
- `special-display-popup-frame' to use when it creates a frame.
-
- - Variable: same-window-buffer-names
- A list of buffer names for buffers that should be displayed in the
- selected window. If the buffer's name is in this list,
- `display-buffer' handles the buffer by switching to it in the
- selected window.
-
- - Variable: same-window-regexps
- A list of regular expressions that specify buffers that should be
- displayed in the selected window. If the buffer's name matches
- any of the regular expressions in this list, `display-buffer'
- handles the buffer by switching to it in the selected window.
-
- - Variable: display-buffer-function
- This variable is the most flexible way to customize the behavior of
- `display-buffer'. If it is non-`nil', it should be a function
- that `display-buffer' calls to do the work. The function should
- accept two arguments, the same two arguments that `display-buffer'
- received. It should choose or create a window, display the
- specified buffer, and then return the window.
-
- This hook takes precedence over all the other options and hooks
- described above.
-
- A window can be marked as "dedicated" to its buffer. Then
-`display-buffer' does not try to use that window.
-
- - Function: window-dedicated-p window
- This function returns `t' if WINDOW is marked as dedicated;
- otherwise `nil'.
-
- - Function: set-window-dedicated-p window flag
- This function marks WINDOW as dedicated if FLAG is non-`nil', and
- nondedicated otherwise.
+ If you wish to replace a buffer in all the windows that display
+ it, use `replace-buffer-in-windows'. *Note Buffers and Windows::.
projects / chise / xemacs-chise.git / blobdiff