This is ../info/lispref.info, produced by makeinfo version 4.7 from
lispref/lispref.texi.

INFO-DIR-SECTION XEmacs Editor
START-INFO-DIR-ENTRY
* Lispref: (lispref).		XEmacs Lisp Reference Manual.
END-INFO-DIR-ENTRY

   Edition History:

   GNU Emacs Lisp Reference Manual Second Edition (v2.01), May 1993 GNU
Emacs Lisp Reference Manual Further Revised (v2.02), August 1993 Lucid
Emacs Lisp Reference Manual (for 19.10) First Edition, March 1994
XEmacs Lisp Programmer's Manual (for 19.12) Second Edition, April 1995
GNU Emacs Lisp Reference Manual v2.4, June 1995 XEmacs Lisp
Programmer's Manual (for 19.13) Third Edition, July 1995 XEmacs Lisp
Reference Manual (for 19.14 and 20.0) v3.1, March 1996 XEmacs Lisp
Reference Manual (for 19.15 and 20.1, 20.2, 20.3) v3.2, April, May,
November 1997 XEmacs Lisp Reference Manual (for 21.0) v3.3, April 1998

   Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Free Software
Foundation, Inc.  Copyright (C) 1994, 1995 Sun Microsystems, Inc.
Copyright (C) 1995, 1996 Ben Wing.

   Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

   Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided that the
entire resulting derived work is distributed under the terms of a
permission notice identical to this one.

   Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions, except that this permission notice may be stated in a
translation approved by the Foundation.

   Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided also
that the section entitled "GNU General Public License" is included
exactly as in the original, and provided that the entire resulting
derived work is distributed under the terms of a permission notice
identical to this one.

   Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions, except that the section entitled "GNU General Public License"
may be included in a translation approved by the Free Software
Foundation instead of in the original English.


File: lispref.info,  Node: Testing Accessibility,  Next: Kinds of Files,  Up: Information about Files

35.6.1 Testing Accessibility
----------------------------

These functions test for permission to access a file in specific ways.

 -- Function: file-exists-p filename
     This function returns `t' if a file named FILENAME appears to
     exist.  This does not mean you can necessarily read the file, only
     that you can find out its attributes.  (On Unix, this is true if
     the file exists and you have execute permission on the containing
     directories, regardless of the protection of the file itself.)

     If the file does not exist, or if fascist access control policies
     prevent you from finding the attributes of the file, this function
     returns `nil'.

 -- Function: file-readable-p filename
     This function returns `t' if a file named FILENAME exists and you
     can read it.  It returns `nil' otherwise.

          (file-readable-p "files.texi")
               => t
          (file-exists-p "/usr/spool/mqueue")
               => t
          (file-readable-p "/usr/spool/mqueue")
               => nil

 -- Function: file-executable-p filename
     This function returns `t' if a file named FILENAME exists and you
     can execute it.  It returns `nil' otherwise.  If the file is a
     directory, execute permission means you can check the existence and
     attributes of files inside the directory, and open those files if
     their modes permit.

 -- Function: file-writable-p filename
     This function returns `t' if the file FILENAME can be written or
     created by you, and `nil' otherwise.  A file is writable if the
     file exists and you can write it.  It is creatable if it does not
     exist, but the specified directory does exist and you can write in
     that directory.

     In the third example below, `foo' is not writable because the
     parent directory does not exist, even though the user could create
     such a directory.

          (file-writable-p "~/foo")
               => t
          (file-writable-p "/foo")
               => nil
          (file-writable-p "~/no-such-dir/foo")
               => nil

 -- Function: file-accessible-directory-p dirname
     This function returns `t' if you have permission to open existing
     files in the directory whose name as a file is DIRNAME; otherwise
     (or if there is no such directory), it returns `nil'.  The value
     of DIRNAME may be either a directory name or the file name of a
     directory.

     Example: after the following,

          (file-accessible-directory-p "/foo")
               => nil

     we can deduce that any attempt to read a file in `/foo/' will give
     an error.

 -- Function: file-ownership-preserved-p filename
     This function returns `t' if deleting the file FILENAME and then
     creating it anew would keep the file's owner unchanged.

 -- Function: file-newer-than-file-p filename1 filename2
     This function returns `t' if the file FILENAME1 is newer than file
     FILENAME2.  If FILENAME1 does not exist, it returns `nil'.  If
     FILENAME2 does not exist, it returns `t'.

     In the following example, assume that the file `aug-19' was written
     on the 19th, `aug-20' was written on the 20th, and the file
     `no-file' doesn't exist at all.

          (file-newer-than-file-p "aug-19" "aug-20")
               => nil
          (file-newer-than-file-p "aug-20" "aug-19")
               => t
          (file-newer-than-file-p "aug-19" "no-file")
               => t
          (file-newer-than-file-p "no-file" "aug-19")
               => nil

     You can use `file-attributes' to get a file's last modification
     time as a list of two numbers.  *Note File Attributes::.


File: lispref.info,  Node: Kinds of Files,  Next: Truenames,  Prev: Testing Accessibility,  Up: Information about Files

35.6.2 Distinguishing Kinds of Files
------------------------------------

This section describes how to distinguish various kinds of files, such
as directories, symbolic links, and ordinary files.

 -- Function: file-symlink-p filename
     If the file FILENAME is a symbolic link, the `file-symlink-p'
     function returns the file name to which it is linked.  This may be
     the name of a text file, a directory, or even another symbolic
     link, or it may be a nonexistent file name.

     If the file FILENAME is not a symbolic link (or there is no such
     file), `file-symlink-p' returns `nil'.

          (file-symlink-p "foo")
               => nil
          (file-symlink-p "sym-link")
               => "foo"
          (file-symlink-p "sym-link2")
               => "sym-link"
          (file-symlink-p "/bin")
               => "/pub/bin"


 -- Function: file-directory-p filename
     This function returns `t' if FILENAME is the name of an existing
     directory, `nil' otherwise.

          (file-directory-p "~rms")
               => t
          (file-directory-p "~rms/lewis/files.texi")
               => nil
          (file-directory-p "~rms/lewis/no-such-file")
               => nil
          (file-directory-p "$HOME")
               => nil
          (file-directory-p
           (substitute-in-file-name "$HOME"))
               => t

 -- Function: file-regular-p filename
     This function returns `t' if the file FILENAME exists and is a
     regular file (not a directory, symbolic link, named pipe,
     terminal, or other I/O device).


File: lispref.info,  Node: Truenames,  Next: File Attributes,  Prev: Kinds of Files,  Up: Information about Files

35.6.3 Truenames
----------------

The "truename" of a file is the name that you get by following symbolic
links until none remain, then expanding to get rid of `.' and `..' as
components.  Strictly speaking, a file need not have a unique truename;
the number of distinct truenames a file has is equal to the number of
hard links to the file.  However, truenames are useful because they
eliminate symbolic links as a cause of name variation.

 -- Function: file-truename filename &optional default
     The function `file-truename' returns the true name of the file
     FILENAME.  This is the name that you get by following symbolic
     links until none remain.

     If the filename is relative, DEFAULT is the directory to start
     with.  If DEFAULT is `nil' or missing, the current buffer's value
     of `default-directory' is used.

   *Note Buffer File Name::, for related information.


File: lispref.info,  Node: File Attributes,  Prev: Truenames,  Up: Information about Files

35.6.4 Other Information about Files
------------------------------------

This section describes the functions for getting detailed information
about a file, other than its contents.  This information includes the
mode bits that control access permission, the owner and group numbers,
the number of names, the inode number, the size, and the times of access
and modification.

 -- Function: file-modes filename
     This function returns the mode bits of FILENAME, as an integer.
     The mode bits are also called the file permissions, and they
     specify access control in the usual Unix fashion.  If the
     low-order bit is 1, then the file is executable by all users, if
     the second-lowest-order bit is 1, then the file is writable by all
     users, etc.

     The highest value returnable is 4095 (7777 octal), meaning that
     everyone has read, write, and execute permission, that the SUID bit
     is set for both others and group, and that the sticky bit is set.

          (file-modes "~/junk/diffs")
               => 492               ; Decimal integer.
          (format "%o" 492)
               => "754"             ; Convert to octal.

          (set-file-modes "~/junk/diffs" 438)
               => nil

          (format "%o" 438)
               => "666"             ; Convert to octal.

          % ls -l diffs
            -rw-rw-rw-  1 lewis 0 3063 Oct 30 16:00 diffs

 -- Function: file-nlinks filename
     This functions returns the number of names (i.e., hard links) that
     file FILENAME has.  If the file does not exist, then this function
     returns `nil'.  Note that symbolic links have no effect on this
     function, because they are not considered to be names of the files
     they link to.

          % ls -l foo*
          -rw-rw-rw-  2 rms       4 Aug 19 01:27 foo
          -rw-rw-rw-  2 rms       4 Aug 19 01:27 foo1

          (file-nlinks "foo")
               => 2
          (file-nlinks "doesnt-exist")
               => nil

 -- Function: file-attributes filename
     This function returns a list of attributes of file FILENAME.  If
     the specified file cannot be opened, it returns `nil'.

     The elements of the list, in order, are:

       0. `t' for a directory, a string for a symbolic link (the name
          linked to), or `nil' for a text file.

       1. The number of names the file has.  Alternate names, also
          known as hard links, can be created by using the
          `add-name-to-file' function (*note Changing File
          Attributes::).

       2. The file's UID.

       3. The file's GID.

       4. The time of last access, as a list of two integers.  The
          first integer has the high-order 16 bits of time, the second
          has the low 16 bits.  (This is similar to the value of
          `current-time'; see *Note Time of Day::.)

       5. The time of last modification as a list of two integers (as
          above).

       6. The time of last status change as a list of two integers (as
          above).

       7. The size of the file in bytes.

       8. The file's modes, as a string of ten letters or dashes, as in
          `ls -l'.

       9. `t' if the file's GID would change if file were deleted and
          recreated; `nil' otherwise.

      10. The file's inode number.

      11. The file system number of the file system that the file is
          in.  This element and the file's inode number together give
          enough information to distinguish any two files on the
          system--no two files can have the same values for both of
          these numbers.

     For example, here are the file attributes for `files.texi':

          (file-attributes "files.texi")
               =>  (nil
                    1
                    2235
                    75
                    (8489 20284)
                    (8489 20284)
                    (8489 20285)
                    14906
                    "-rw-rw-rw-"
                    nil
                    129500
                    -32252)

     and here is how the result is interpreted:

    `nil'
          is neither a directory nor a symbolic link.

    `1'
          has only one name (the name `files.texi' in the current
          default directory).

    `2235'
          is owned by the user with UID 2235.

    `75'
          is in the group with GID 75.

    `(8489 20284)'
          was last accessed on Aug 19 00:09. Use `format-time-string' to
          ! convert this number into a time string.  *Note Time
          Conversion::.

    `(8489 20284)'
          was last modified on Aug 19 00:09.

    `(8489 20285)'
          last had its inode changed on Aug 19 00:09.

    `14906'
          is 14906 characters long.

    `"-rw-rw-rw-"'
          has a mode of read and write access for the owner, group, and
          world.

    `nil'
          would retain the same GID if it were recreated.

    `129500'
          has an inode number of 129500.

    `-32252'
          is on file system number -32252.


File: lispref.info,  Node: Changing File Attributes,  Next: File Names,  Prev: Information about Files,  Up: Files

35.7 Changing File Names and Attributes
=======================================

The functions in this section rename, copy, delete, link, and set the
modes of files.

   In the functions that have arguments NEWNAME and
OK-IF-ALREADY-EXISTS, if a file by the name of NEWNAME already exists,
the actions taken depend on the value of OK-IF-ALREADY-EXISTS:

   * Signal a `file-already-exists' error if OK-IF-ALREADY-EXISTS is
     `nil'.

   * Request confirmation if OK-IF-ALREADY-EXISTS is a number.  This is
     what happens when the function is invoked interactively.

   * Replace the old file without confirmation if OK-IF-ALREADY-EXISTS
     is any other value.

 -- Command: add-name-to-file filename newname &optional
          ok-if-already-exists
     This function gives the file named FILENAME the additional name
     NEWNAME.  This means that NEWNAME becomes a new "hard link" to
     FILENAME.  Both these arguments must be strings.

     In the first part of the following example, we list two files,
     `foo' and `foo3'.

          % ls -l fo*
          -rw-rw-rw-  1 rms       29 Aug 18 20:32 foo
          -rw-rw-rw-  1 rms       24 Aug 18 20:31 foo3

     Then we evaluate the form `(add-name-to-file "~/lewis/foo"
     "~/lewis/foo2")'.  Again we list the files.  This shows two names,
     `foo' and `foo2'.

          (add-name-to-file "~/lewis/foo1" "~/lewis/foo2")
               => nil

          % ls -l fo*
          -rw-rw-rw-  2 rms       29 Aug 18 20:32 foo
          -rw-rw-rw-  2 rms       29 Aug 18 20:32 foo2
          -rw-rw-rw-  1 rms       24 Aug 18 20:31 foo3

     Finally, we evaluate the following:

          (add-name-to-file "~/lewis/foo" "~/lewis/foo3" t)

     and list the files again.  Now there are three names for one file:
     `foo', `foo2', and `foo3'.  The old contents of `foo3' are lost.

          (add-name-to-file "~/lewis/foo1" "~/lewis/foo3")
               => nil

          % ls -l fo*
          -rw-rw-rw-  3 rms       29 Aug 18 20:32 foo
          -rw-rw-rw-  3 rms       29 Aug 18 20:32 foo2
          -rw-rw-rw-  3 rms       29 Aug 18 20:32 foo3

     This function is meaningless on non-Unix systems, where multiple
     names for one file are not allowed.

     See also `file-nlinks' in *Note File Attributes::.

 -- Command: rename-file filename newname &optional ok-if-already-exists
     This command renames the file FILENAME as NEWNAME.

     If FILENAME has additional names aside from FILENAME, it continues
     to have those names.  In fact, adding the name NEWNAME with
     `add-name-to-file' and then deleting FILENAME has the same effect
     as renaming, aside from momentary intermediate states.

     In an interactive call, this function prompts for FILENAME and
     NEWNAME in the minibuffer; also, it requests confirmation if
     NEWNAME already exists.

 -- Command: copy-file filename newname &optional ok-if-already-exists
          time
     This command copies the file FILENAME to NEWNAME.  An error is
     signaled if FILENAME does not exist.

     If TIME is non-`nil', then this functions gives the new file the
     same last-modified time that the old one has.  (This works on only
     some operating systems.)

     In an interactive call, this function prompts for FILENAME and
     NEWNAME in the minibuffer; also, it requests confirmation if
     NEWNAME already exists.

 -- Command: delete-file filename
     This command deletes the file FILENAME, like the shell command `rm
     FILENAME'.  If the file has multiple names, it continues to exist
     under the other names.

     A suitable kind of `file-error' error is signaled if the file does
     not exist, or is not deletable.  (On Unix, a file is deletable if
     its directory is writable.)

     See also `delete-directory' in *Note Create/Delete Dirs::.

 -- Command: make-symbolic-link filename newname &optional
          ok-if-already-exists
     This command makes a symbolic link to FILENAME, named NEWNAME.
     This is like the shell command `ln -s FILENAME NEWNAME'.

     In an interactive call, this function prompts for FILENAME and
     NEWNAME in the minibuffer; also, it requests confirmation if
     NEWNAME already exists.

 -- Function: set-file-modes filename mode
     This function sets mode bits of FILENAME to MODE (which must be an
     integer).  Only the low 12 bits of MODE are used.

 -- Function: set-default-file-modes mode
     This function sets the default file protection for new files
     created by XEmacs and its subprocesses.  Every file created with
     XEmacs initially has this protection.  On Unix, the default
     protection is the bitwise complement of the "umask" value.

     The argument MODE must be an integer.  Only the low 9 bits of MODE
     are used.

     Saving a modified version of an existing file does not count as
     creating the file; it does not change the file's mode, and does
     not use the default file protection.

 -- Function: default-file-modes
     This function returns the current default protection value.

   On MS-DOS, there is no such thing as an "executable" file mode bit.
So Emacs considers a file executable if its name ends in `.com', `.bat'
or `.exe'.  This is reflected in the values returned by `file-modes'
and `file-attributes'.


File: lispref.info,  Node: File Names,  Next: Contents of Directories,  Prev: Changing File Attributes,  Up: Files

35.8 File Names
===============

Files are generally referred to by their names, in XEmacs as elsewhere.
File names in XEmacs are represented as strings.  The functions that
operate on a file all expect a file name argument.

   In addition to operating on files themselves, XEmacs Lisp programs
often need to operate on the names; i.e., to take them apart and to use
part of a name to construct related file names.  This section describes
how to manipulate file names.

   The functions in this section do not actually access files, so they
can operate on file names that do not refer to an existing file or
directory.

   On MS-DOS, these functions understand MS-DOS file-name syntax as
well as Unix syntax. This is so that all the standard Lisp libraries
can specify file names in Unix syntax and work properly on all systems
without change.  Similarly for other operating systems.

* Menu:

* File Name Components::  The directory part of a file name, and the rest.
* Directory Names::       A directory's name as a directory
                            is different from its name as a file.
* Relative File Names::   Some file names are relative to a current directory.
* File Name Expansion::   Converting relative file names to absolute ones.
* Unique File Names::     Generating names for temporary files.
* File Name Completion::  Finding the completions for a given file name.
* User Name Completion::  Finding the completions for a given user name.


File: lispref.info,  Node: File Name Components,  Next: Directory Names,  Up: File Names

35.8.1 File Name Components
---------------------------

The operating system groups files into directories.  To specify a file,
you must specify the directory and the file's name within that
directory.  Therefore, XEmacs considers a file name as having two main
parts: the "directory name" part, and the "nondirectory" part (or "file
name within the directory").  Either part may be empty.  Concatenating
these two parts reproduces the original file name.

   On Unix, the directory part is everything up to and including the
last slash; the nondirectory part is the rest.

   For some purposes, the nondirectory part is further subdivided into
the name proper and the "version number".  On Unix, only backup files
have version numbers in their names.

 -- Function: file-name-directory filename
     This function returns the directory part of FILENAME (or `nil' if
     FILENAME does not include a directory part).  On Unix, the
     function returns a string ending in a slash.

          (file-name-directory "lewis/foo")  ; Unix example
               => "lewis/"
          (file-name-directory "foo")        ; Unix example
               => nil

 -- Function: file-name-nondirectory filename
     This function returns the nondirectory part of FILENAME.

          (file-name-nondirectory "lewis/foo")
               => "foo"
          (file-name-nondirectory "foo")
               => "foo"

 -- Function: file-name-sans-versions filename &optional
          keep-backup-version
     This function returns FILENAME without any file version numbers,
     backup version numbers, or trailing tildes.

     If KEEP-BACKUP-VERSION is non-`nil', we do not remove backup
     version numbers, only true file version numbers.

          (file-name-sans-versions "~rms/foo.~1~")
               => "~rms/foo"
          (file-name-sans-versions "~rms/foo~")
               => "~rms/foo"
          (file-name-sans-versions "~rms/foo")
               => "~rms/foo"

 -- Function: file-name-sans-extension filename
     This function returns FILENAME minus its "extension," if any.  The
     extension, in a file name, is the part that starts with the last
     `.' in the last name component.  For example,

          (file-name-sans-extension "foo.lose.c")
               => "foo.lose"
          (file-name-sans-extension "big.hack/foo")
               => "big.hack/foo"


File: lispref.info,  Node: Directory Names,  Next: Relative File Names,  Prev: File Name Components,  Up: File Names

35.8.2 Directory Names
----------------------

A "directory name" is the name of a directory.  A directory is a kind
of file, and it has a file name, which is related to the directory name
but not identical to it.  (This is not quite the same as the usual Unix
terminology.)  These two different names for the same entity are
related by a syntactic transformation.  On Unix, this is simple: a
directory name ends in a slash, whereas the directory's name as a file
lacks that slash.

   The difference between a directory name and its name as a file is
subtle but crucial.  When an XEmacs variable or function argument is
described as being a directory name, a file name of a directory is not
acceptable.

   The following two functions convert between directory names and file
names.  They do nothing special with environment variable substitutions
such as `$HOME', and the constructs `~', and `..'.

 -- Function: file-name-as-directory filename
     This function returns a string representing FILENAME in a form
     that the operating system will interpret as the name of a
     directory.  In Unix, this means appending a slash to the string.

          (file-name-as-directory "~rms/lewis")
               => "~rms/lewis/"

 -- Function: directory-file-name dirname
     This function returns a string representing DIRNAME in a form that
     the operating system will interpret as the name of a file.  On
     Unix, this means removing a final slash from the string.

          (directory-file-name "~lewis/")
               => "~lewis"

   Directory name abbreviations are useful for directories that are
normally accessed through symbolic links.  Sometimes the users recognize
primarily the link's name as "the name" of the directory, and find it
annoying to see the directory's "real" name.  If you define the link
name as an abbreviation for the "real" name, XEmacs shows users the
abbreviation instead.

   If you wish to convert a directory name to its abbreviation, use this
function:

 -- Function: abbreviate-file-name filename &optional hack-homedir
     This function applies abbreviations from `directory-abbrev-alist'
     to its argument, and substitutes `~' for the user's home directory.

     If HACK-HOMEDIR is non-`nil', then this also substitutes `~' for
     the user's home directory.


 -- Variable: directory-abbrev-alist
     The variable `directory-abbrev-alist' contains an alist of
     abbreviations to use for file directories.  Each element has the
     form `(FROM . TO)', and says to replace FROM with TO when it
     appears in a directory name.  The FROM string is actually a
     regular expression; it should always start with `^'.  The function
     `abbreviate-file-name' performs these substitutions.

     You can set this variable in `site-init.el' to describe the
     abbreviations appropriate for your site.

     Here's an example, from a system on which file system `/home/fsf'
     and so on are normally accessed through symbolic links named `/fsf'
     and so on.

          (("^/home/fsf" . "/fsf")
           ("^/home/gp" . "/gp")
           ("^/home/gd" . "/gd"))


File: lispref.info,  Node: Relative File Names,  Next: File Name Expansion,  Prev: Directory Names,  Up: File Names

35.8.3 Absolute and Relative File Names
---------------------------------------

All the directories in the file system form a tree starting at the root
directory.  A file name can specify all the directory names starting
from the root of the tree; then it is called an "absolute" file name.
Or it can specify the position of the file in the tree relative to a
default directory; then it is called a "relative" file name.  On Unix,
an absolute file name starts with a slash or a tilde (`~'), and a
relative one does not.

 -- Function: file-name-absolute-p filename
     This function returns `t' if file FILENAME is an absolute file
     name, `nil' otherwise.

          (file-name-absolute-p "~rms/foo")
               => t
          (file-name-absolute-p "rms/foo")
               => nil
          (file-name-absolute-p "/user/rms/foo")
               => t


File: lispref.info,  Node: File Name Expansion,  Next: Unique File Names,  Prev: Relative File Names,  Up: File Names

35.8.4 Functions that Expand Filenames
--------------------------------------

"Expansion" of a file name means converting a relative file name to an
absolute one.  Since this is done relative to a default directory, you
must specify the default directory name as well as the file name to be
expanded.  Expansion also simplifies file names by eliminating
redundancies such as `./' and `NAME/../'.

 -- Function: expand-file-name filename &optional directory
     This function converts FILENAME to an absolute file name.  If
     DIRECTORY is supplied, it is the directory to start with if
     FILENAME is relative.  (The value of DIRECTORY should itself be an
     absolute directory name; it may start with `~'.)  Otherwise, the
     current buffer's value of `default-directory' is used.  For
     example:

          (expand-file-name "foo")
               => "/xcssun/users/rms/lewis/foo"
          (expand-file-name "../foo")
               => "/xcssun/users/rms/foo"
          (expand-file-name "foo" "/usr/spool/")
               => "/usr/spool/foo"
          (expand-file-name "$HOME/foo")
               => "/xcssun/users/rms/lewis/$HOME/foo"

     Filenames containing `.' or `..' are simplified to their canonical
     form:

          (expand-file-name "bar/../foo")
               => "/xcssun/users/rms/lewis/foo"

     `~/' at the beginning is expanded into the user's home directory.
     A `/' or `~' following a `/'.

     Note that `expand-file-name' does _not_ expand environment
     variables; only `substitute-in-file-name' does that.

 -- Function: file-relative-name filename &optional directory
     This function does the inverse of expansion--it tries to return a
     relative name that is equivalent to FILENAME when interpreted
     relative to DIRECTORY.

     If DIRECTORY is `nil' or omitted, the value of `default-directory'
     is used.

          (file-relative-name "/foo/bar" "/foo/")
               => "bar")
          (file-relative-name "/foo/bar" "/hack/")
               => "../foo/bar")

 -- Variable: default-directory
     The value of this buffer-local variable is the default directory
     for the current buffer.  It should be an absolute directory name;
     it may start with `~'.  This variable is local in every buffer.

     `expand-file-name' uses the default directory when its second
     argument is `nil'.

     On Unix systems, the value is always a string ending with a slash.

          default-directory
               => "/user/lewis/manual/"

 -- Function: substitute-in-file-name filename
     This function replaces environment variable references in FILENAME
     with the environment variable values.  Following standard Unix
     shell syntax, `$' is the prefix to substitute an environment
     variable value.

     The environment variable name is the series of alphanumeric
     characters (including underscores) that follow the `$'.  If the
     character following the `$' is a `{', then the variable name is
     everything up to the matching `}'.

     Here we assume that the environment variable `HOME', which holds
     the user's home directory name, has value `/xcssun/users/rms'.

          (substitute-in-file-name "$HOME/foo")
               => "/xcssun/users/rms/foo"

     After substitution, a `/' or `~' following a `/' is taken to be
     the start of an absolute file name that overrides what precedes
     it, so everything before that `/' or `~' is deleted.  For example:

          (substitute-in-file-name "bar/~/foo")
               => "~/foo"
          (substitute-in-file-name "/usr/local/$HOME/foo")
               => "/xcssun/users/rms/foo"


File: lispref.info,  Node: Unique File Names,  Next: File Name Completion,  Prev: File Name Expansion,  Up: File Names

35.8.5 Generating Unique File Names
-----------------------------------

Some programs need to write temporary files.  Here is the usual way to
construct a name for such a file:

     (make-temp-name (expand-file-name NAME-OF-APPLICATION (temp-directory)))

Here we use `(temp-directory)' to specify a directory for temporary
files--under Unix, it will normally evaluate to `"/tmp/"'.  The job of
`make-temp-name' is to prevent two different users or two different
processes from trying to use the same name.

 -- Function: temp-directory
     This function returns the name of the directory to use for
     temporary files.  Under Unix, this will be the value of `TMPDIR',
     defaulting to `/tmp'.  On Windows, this will be obtained from the
     `TEMP' or `TMP' environment variables, defaulting to `/'.

     Note that the `temp-directory' function does not exist under FSF
     Emacs.

 -- Function: make-temp-name prefix
     This function generates a temporary file name starting with
     PREFIX.  The Emacs process number forms part of the result, so
     there is no danger of generating a name being used by another
     process.

          (make-temp-name "/tmp/foo")
               => "/tmp/fooGaAQjC"

     In addition, this function makes an attempt to choose a name that
     does not specify an existing file.  To make this work, PREFIX
     should be an absolute file name.

     To avoid confusion, each Lisp application should preferably use a
     unique PREFIX to `make-temp-name'.


File: lispref.info,  Node: File Name Completion,  Next: User Name Completion,  Prev: Unique File Names,  Up: File Names

35.8.6 File Name Completion
---------------------------

This section describes low-level subroutines for completing a file
name.  For other completion functions, see *Note Completion::.

 -- Function: file-name-all-completions partial-filename directory
     This function returns a list of all possible completions for files
     whose name starts with PARTIAL-FILENAME in directory DIRECTORY.
     The order of the completions is the order of the files in the
     directory, which is unpredictable and conveys no useful
     information.

     The argument PARTIAL-FILENAME must be a file name containing no
     directory part and no slash.  The current buffer's default
     directory is prepended to DIRECTORY, if DIRECTORY is not absolute.

     File names which end with any member of
     `completion-ignored-extensions' are not considered as possible
     completions for PARTIAL-FILENAME unless there is no other possible
     completion. `completion-ignored-extensions' is not applied to the
     names of directories.

     In the following example, suppose that the current default
     directory, `~rms/lewis', has five files whose names begin with `f':
     `foo', `file~', `file.c', `file.c.~1~', and `file.c.~2~'.

          (file-name-all-completions "f" "")
               => ("foo" "file~" "file.c.~2~"
                          "file.c.~1~" "file.c")

          (file-name-all-completions "fo" "")
               => ("foo")

 -- Function: file-name-completion partial-filename directory
     This function completes the file name PARTIAL-FILENAME in directory
     DIRECTORY.  It returns the longest prefix common to all file names
     in directory DIRECTORY that start with PARTIAL-FILENAME.

     If only one match exists and PARTIAL-FILENAME matches it exactly,
     the function returns `t'.  The function returns `nil' if directory
     DIRECTORY contains no name starting with PARTIAL-FILENAME.

     File names which end with any member of
     `completion-ignored-extensions' are not considered as possible
     completions for PARTIAL-FILENAME unless there is no other possible
     completion. `completion-ignored-extensions' is not applied to the
     names of directories.

     In the following example, suppose that the current default
     directory has five files whose names begin with `f': `foo',
     `file~', `file.c', `file.c.~1~', and `file.c.~2~'.

          (file-name-completion "fi" "")
               => "file"

          (file-name-completion "file.c.~1" "")
               => "file.c.~1~"

          (file-name-completion "file.c.~1~" "")
               => t

          (file-name-completion "file.c.~3" "")
               => nil

 -- User Option: completion-ignored-extensions
     `file-name-completion' usually ignores file names that end in any
     string in this list.  It does not ignore them when all the possible
     completions end in one of these suffixes or when a buffer showing
     all possible completions is displayed.

     A typical value might look like this:

          completion-ignored-extensions
               => (".o" ".elc" "~" ".dvi")


File: lispref.info,  Node: User Name Completion,  Prev: File Name Completion,  Up: File Names

35.8.7 User Name Completion
---------------------------

This section describes low-level subroutines for completing a user
name.  For other completion functions, see *Note Completion::.

 -- Function: user-name-all-completions partial-username
     This function returns a list of all possible completions for a
     user name starting with PARTIAL-USERNAME.  The order of the
     completions is unpredictable and conveys no useful information.

     The argument PARTIAL-USERNAME must be a partial user name
     containing no tilde character and no slash.

 -- Function: user-name-completion partial-username
     This function completes a user name from PARTIAL-USERNAME.  It
     returns the longest prefix common to all user names that start with
     PARTIAL-USERNAME.

     If only one match exists and PARTIAL-USERNAME matches it exactly,
     the function returns `t'.  The function returns `nil' if no user
     name starting with PARTIAL-USERNAME exists.

 -- Function: user-name-completion-1 partial-username
     This function completes the partial user name PARTIAL-USERNAME,
     like `user-name-completion', differing only in the return value.
     This function returns the cons of the completion returned by
     `user-name-completion', and a boolean indicating whether that
     completion was unique.


File: lispref.info,  Node: Contents of Directories,  Next: Create/Delete Dirs,  Prev: File Names,  Up: Files

35.9 Contents of Directories
============================

A directory is a kind of file that contains other files entered under
various names.  Directories are a feature of the file system.

   XEmacs can list the names of the files in a directory as a Lisp list,
or display the names in a buffer using the `ls' shell command.  In the
latter case, it can optionally display information about each file,
depending on the value of switches passed to the `ls' command.

 -- Function: directory-files directory &optional full-name
          match-regexp nosort files-only
     This function returns a list of the names of the files in the
     directory DIRECTORY.  By default, the list is in alphabetical
     order.

     If FULL-NAME is non-`nil', the function returns the files'
     absolute file names.  Otherwise, it returns just the names
     relative to the specified directory.

     If MATCH-REGEXP is non-`nil', this function returns only those
     file names that contain that regular expression--the other file
     names are discarded from the list.

     If NOSORT is non-`nil', `directory-files' does not sort the list,
     so you get the file names in no particular order.  Use this if you
     want the utmost possible speed and don't care what order the files
     are processed in.  If the order of processing is visible to the
     user, then the user will probably be happier if you do sort the
     names.

     If FILES-ONLY is the symbol `t', then only the "files" in the
     directory will be returned; subdirectories will be excluded.  If
     FILES-ONLY is not `nil' and not `t', then only the subdirectories
     will be returned.  Otherwise, if FILES-ONLY is `nil' (the default)
     then both files and subdirectories will be returned.

          (directory-files "~lewis")
               => ("#foo#" "#foo.el#" "." ".."
                   "dired-mods.el" "files.texi"
                   "files.texi.~1~")

     An error is signaled if DIRECTORY is not the name of a directory
     that can be read.

 -- Function: insert-directory file switches &optional wildcard
          full-directory-p
     This function inserts (in the current buffer) a directory listing
     for directory FILE, formatted with `ls' according to SWITCHES.  It
     leaves point after the inserted text.

     The argument FILE may be either a directory name or a file
     specification including wildcard characters.  If WILDCARD is
     non-`nil', that means treat FILE as a file specification with
     wildcards.

     If FULL-DIRECTORY-P is non-`nil', that means FILE is a directory
     and switches do not contain `-d', so that the listing should show
     the full contents of the directory.  (The `-d' option to `ls' says
     to describe a directory itself rather than its contents.)

     This function works by running a directory listing program whose
     name is in the variable `insert-directory-program'.  If WILDCARD is
     non-`nil', it also runs the shell specified by `shell-file-name',
     to expand the wildcards.

 -- Variable: insert-directory-program
     This variable's value is the program to run to generate a
     directory listing for the function `insert-directory'.


File: lispref.info,  Node: Create/Delete Dirs,  Next: Magic File Names,  Prev: Contents of Directories,  Up: Files

35.10 Creating and Deleting Directories
=======================================

Most XEmacs Lisp file-manipulation functions get errors when used on
files that are directories.  For example, you cannot delete a directory
with `delete-file'.  These special functions exist to create and delete
directories.

 -- Command: make-directory dirname &optional parents
     This function creates a directory named DIRNAME.  Interactively,
     the default choice of directory to create is the current default
     directory for file names.  That is useful when you have visited a
     file in a nonexistent directory.

     Non-interactively, optional argument PARENTS says whether to
     create parent directories if they don't exist. (Interactively, this
     always happens.)

 -- Command: delete-directory dirname
     This function deletes the directory named DIRNAME.  The function
     `delete-file' does not work for files that are directories; you
     must use `delete-directory' in that case.


File: lispref.info,  Node: Magic File Names,  Next: Partial Files,  Prev: Create/Delete Dirs,  Up: Files

35.11 Making Certain File Names "Magic"
=======================================

You can implement special handling for certain file names.  This is
called making those names "magic".  You must supply a regular
expression to define the class of names (all those that match the
regular expression), plus a handler that implements all the primitive
XEmacs file operations for file names that do match.

   The variable `file-name-handler-alist' holds a list of handlers,
together with regular expressions that determine when to apply each
handler.  Each element has this form:

     (REGEXP . HANDLER)

All the XEmacs primitives for file access and file name transformation
check the given file name against `file-name-handler-alist'.  If the
file name matches REGEXP, the primitives handle that file by calling
HANDLER.

   The first argument given to HANDLER is the name of the primitive;
the remaining arguments are the arguments that were passed to that
operation.  (The first of these arguments is typically the file name
itself.)  For example, if you do this:

     (file-exists-p FILENAME)

and FILENAME has handler HANDLER, then HANDLER is called like this:

     (funcall HANDLER 'file-exists-p FILENAME)

   Here are the operations that a magic file name handler gets to
handle:

`add-name-to-file', `copy-file', `delete-directory', `delete-file',
`diff-latest-backup-file', `directory-file-name', `directory-files',
`dired-compress-file', `dired-uncache', `expand-file-name',
`file-accessible-directory-p', `file-attributes', `file-directory-p',
`file-executable-p', `file-exists-p', `file-local-copy', `file-modes',
`file-name-all-completions', `file-name-as-directory',
`file-name-completion', `file-name-directory', `file-name-nondirectory',
`file-name-sans-versions', `file-newer-than-file-p', `file-readable-p',
`file-regular-p', `file-symlink-p', `file-truename', `file-writable-p',
`get-file-buffer', `insert-directory', `insert-file-contents', `load',
`make-directory', `make-symbolic-link', `rename-file', `set-file-modes',
`set-visited-file-modtime', `unhandled-file-name-directory',
`verify-visited-file-modtime', `write-region'.

   Handlers for `insert-file-contents' typically need to clear the
buffer's modified flag, with `(set-buffer-modified-p nil)', if the
VISIT argument is non-`nil'.  This also has the effect of unlocking the
buffer if it is locked.

   The handler function must handle all of the above operations, and
possibly others to be added in the future.  It need not implement all
these operations itself--when it has nothing special to do for a
certain operation, it can reinvoke the primitive, to handle the
operation "in the usual way".  It should always reinvoke the primitive
for an operation it does not recognize.  Here's one way to do this:

     (defun my-file-handler (operation &rest args)
       ;; First check for the specific operations
       ;; that we have special handling for.
       (cond ((eq operation 'insert-file-contents) ...)
             ((eq operation 'write-region) ...)
             ...
             ;; Handle any operation we don't know about.
             (t (let ((inhibit-file-name-handlers
                      (cons 'my-file-handler
                            (and (eq inhibit-file-name-operation operation)
                                 inhibit-file-name-handlers)))
                     (inhibit-file-name-operation operation))
                  (apply operation args)))))

   When a handler function decides to call the ordinary Emacs primitive
for the operation at hand, it needs to prevent the primitive from
calling the same handler once again, thus leading to an infinite
recursion.  The example above shows how to do this, with the variables
`inhibit-file-name-handlers' and `inhibit-file-name-operation'.  Be
careful to use them exactly as shown above; the details are crucial for
proper behavior in the case of multiple handlers, and for operations
that have two file names that may each have handlers.

 -- Variable: inhibit-file-name-handlers
     This variable holds a list of handlers whose use is presently
     inhibited for a certain operation.

 -- Variable: inhibit-file-name-operation
     The operation for which certain handlers are presently inhibited.

 -- Function: find-file-name-handler filename &optional operation
     This function returns the handler function for file name FILENAME,
     or `nil' if there is none.  The argument OPERATION should be the
     operation to be performed on the file--the value you will pass to
     the handler as its first argument when you call it.  The operation
     is needed for comparison with `inhibit-file-name-operation'.

 -- Function: file-local-copy filename
     This function copies file FILENAME to an ordinary non-magic file,
     if it isn't one already.

     If FILENAME specifies a "magic" file name, which programs outside
     Emacs cannot directly read or write, this copies the contents to
     an ordinary file and returns that file's name.

     If FILENAME is an ordinary file name, not magic, then this function
     does nothing and returns `nil'.

 -- Function: unhandled-file-name-directory filename
     This function returns the name of a directory that is not magic.
     It uses the directory part of FILENAME if that is not magic.
     Otherwise, it asks the handler what to do.

     This is useful for running a subprocess; every subprocess must
     have a non-magic directory to serve as its current directory, and
     this function is a good way to come up with one.


File: lispref.info,  Node: Partial Files,  Next: Format Conversion,  Prev: Magic File Names,  Up: Files

35.12 Partial Files
===================

* Menu:

* Intro to Partial Files::
* Creating a Partial File::
* Detached Partial Files::


File: lispref.info,  Node: Intro to Partial Files,  Next: Creating a Partial File,  Up: Partial Files

35.12.1 Intro to Partial Files
------------------------------

A "partial file" is a section of a buffer (called the "master buffer")
that is placed in its own buffer and treated as its own file.  Changes
made to the partial file are not reflected in the master buffer until
the partial file is "saved" using the standard buffer save commands.
Partial files can be "reverted" (from the master buffer) just like
normal files.  When a file part is active on a master buffer, that
section of the master buffer is marked as read-only.  Two file parts on
the same master buffer are not allowed to overlap.  Partial file
buffers are indicated by the words `File Part' in the modeline.

   The master buffer knows about all the partial files that are active
on it, and thus killing or reverting the master buffer will be handled
properly.  When the master buffer is saved, if there are any unsaved
partial files active on it then the user will be given the opportunity
to first save these files.

   When a partial file buffer is first modified, the master buffer is
automatically marked as modified so that saving the master buffer will
work correctly.


File: lispref.info,  Node: Creating a Partial File,  Next: Detached Partial Files,  Prev: Intro to Partial Files,  Up: Partial Files

35.12.2 Creating a Partial File
-------------------------------

 -- Command: make-file-part &optional start end name buffer
     Make a file part on buffer BUFFER out of the region.  Call it
     NAME.  This command creates a new buffer containing the contents
     of the region and marks the buffer as referring to the specified
     buffer, called the "master buffer".  When the file-part buffer is
     saved, its changes are integrated back into the master buffer.
     When the master buffer is deleted, all file parts are deleted with
     it.

     When called from a function, expects four arguments, START, END,
     NAME, and BUFFER, all of which are optional and default to the
     beginning of BUFFER, the end of BUFFER, a name generated from
     BUFFER's name, and the current buffer, respectively.


File: lispref.info,  Node: Detached Partial Files,  Prev: Creating a Partial File,  Up: Partial Files

35.12.3 Detached Partial Files
------------------------------

Every partial file has an extent in the master buffer associated with it
(called the "master extent"), marking where in the master buffer the
partial file begins and ends.  If the text in master buffer that is
contained by the extent is deleted, then the extent becomes "detached",
meaning that it no longer refers to a specific region of the master
buffer.  This can happen either when the text is deleted directly or
when the master buffer is reverted.  Neither of these should happen in
normal usage because the master buffer should generally not be edited
directly.

   Before doing any operation that references a partial file's master
extent, XEmacs checks to make sure that the extent is not detached.  If
this is the case, XEmacs warns the user of this and the master extent is
deleted out of the master buffer, disconnecting the file part.  The file
part's filename is cleared and thus must be explicitly specified if the
detached file part is to be saved.


File: lispref.info,  Node: Format Conversion,  Next: Files and MS-DOS,  Prev: Partial Files,  Up: Files

35.13 File Format Conversion
============================

The variable `format-alist' defines a list of "file formats", which
describe textual representations used in files for the data (text,
text-properties, and possibly other information) in an Emacs buffer.
Emacs performs format conversion if appropriate when reading and writing
files.

 -- Variable: format-alist
     This list contains one format definition for each defined file
     format.

   Each format definition is a list of this form:

     (NAME DOC-STRING REGEXP FROM-FN TO-FN MODIFY MODE-FN)

   Here is what the elements in a format definition mean:

NAME
     The name of this format.

DOC-STRING
     A documentation string for the format.

REGEXP
     A regular expression which is used to recognize files represented
     in this format.

FROM-FN
     A function to call to decode data in this format (to convert file
     data into the usual Emacs data representation).

     The FROM-FN is called with two args, BEGIN and END, which specify
     the part of the buffer it should convert.  It should convert the
     text by editing it in place.  Since this can change the length of
     the text, FROM-FN should return the modified end position.

     One responsibility of FROM-FN is to make sure that the beginning
     of the file no longer matches REGEXP.  Otherwise it is likely to
     get called again.

TO-FN
     A function to call to encode data in this format (to convert the
     usual Emacs data representation into this format).

     The TO-FN is called with two args, BEGIN and END, which specify
     the part of the buffer it should convert.  There are two ways it
     can do the conversion:

        * By editing the buffer in place.  In this case, TO-FN should
          return the end-position of the range of text, as modified.

        * By returning a list of annotations.  This is a list of
          elements of the form `(POSITION . STRING)', where POSITION is
          an integer specifying the relative position in the text to be
          written, and STRING is the annotation to add there.  The list
          must be sorted in order of position when TO-FN returns it.

          When `write-region' actually writes the text from the buffer
          to the file, it intermixes the specified annotations at the
          corresponding positions.  All this takes place without
          modifying the buffer.

MODIFY
     A flag, `t' if the encoding function modifies the buffer, and
     `nil' if it works by returning a list of annotations.

MODE
     A mode function to call after visiting a file converted from this
     format.

   The function `insert-file-contents' automatically recognizes file
formats when it reads the specified file.  It checks the text of the
beginning of the file against the regular expressions of the format
definitions, and if it finds a match, it calls the decoding function for
that format.  Then it checks all the known formats over again.  It
keeps checking them until none of them is applicable.

   Visiting a file, with `find-file-noselect' or the commands that use
it, performs conversion likewise (because it calls
`insert-file-contents'); it also calls the mode function for each
format that it decodes.  It stores a list of the format names in the
buffer-local variable `buffer-file-format'.

 -- Variable: buffer-file-format
     This variable states the format of the visited file.  More
     precisely, this is a list of the file format names that were
     decoded in the course of visiting the current buffer's file.  It
     is always local in all buffers.

   When `write-region' writes data into a file, it first calls the
encoding functions for the formats listed in `buffer-file-format', in
the order of appearance in the list.

 -- Command: format-write-file file format
     This command writes the current buffer contents into the file FILE
     in format FORMAT, and makes that format the default for future
     saves of the buffer.  The argument FORMAT is a list of format
     names.

 -- Command: format-find-file file format
     This command finds the file FILE, converting it according to
     format FORMAT.  It also makes FORMAT the default if the buffer is
     saved later.

     The argument FORMAT is a list of format names.  If FORMAT is
     `nil', no conversion takes place.  Interactively, typing just
     <RET> for FORMAT specifies `nil'.

 -- Command: format-insert-file file format &optional start end
     This command inserts the contents of file FILE, converting it
     according to format FORMAT.  If START and END are non-`nil', they
     specify which part of the file to read, as in
     `insert-file-contents' (*note Reading from Files::).

     The return value is like what `insert-file-contents' returns: a
     list of the absolute file name and the length of the data inserted
     (after conversion).

     The argument FORMAT is a list of format names.  If FORMAT is
     `nil', no conversion takes place.  Interactively, typing just
     <RET> for FORMAT specifies `nil'.

 -- Variable: auto-save-file-format
     This variable specifies the format to use for auto-saving.  Its
     value is a list of format names, just like the value of
     `buffer-file-format'; but it is used instead of
     `buffer-file-format' for writing auto-save files.  This variable
     is always local in all buffers.


File: lispref.info,  Node: Files and MS-DOS,  Prev: Format Conversion,  Up: Files

35.14 Files and MS-DOS
======================

Emacs on MS-DOS makes a distinction between text files and binary
files.  This is necessary because ordinary text files on MS-DOS use a
two character sequence between lines: carriage-return and linefeed
(CRLF).  Emacs expects just a newline character (a linefeed) between
lines.  When Emacs reads or writes a text file on MS-DOS, it needs to
convert the line separators.  This means it needs to know which files
are text files and which are binary.  It makes this decision when
visiting a file, and records the decision in the variable
`buffer-file-type' for use when the file is saved.

   *Note MS-DOS Subprocesses::, for a related feature for subprocesses.

 -- Variable: buffer-file-type
     This variable, automatically local in each buffer, records the
     file type of the buffer's visited file.  The value is `nil' for
     text, `t' for binary.

 -- Function: find-buffer-file-type filename
     This function determines whether file FILENAME is a text file or a
     binary file.  It returns `nil' for text, `t' for binary.

 -- User Option: file-name-buffer-file-type-alist
     This variable holds an alist for distinguishing text files from
     binary files.  Each element has the form (REGEXP . TYPE), where
     REGEXP is matched against the file name, and TYPE may be is `nil'
     for text, `t' for binary, or a function to call to compute which.
     If it is a function, then it is called with a single argument (the
     file name) and should return `t' or `nil'.

 -- User Option: default-buffer-file-type
     This variable specifies the default file type for files whose names
     don't indicate anything in particular.  Its value should be `nil'
     for text, or `t' for binary.

 -- Command: find-file-text filename
     Like `find-file', but treat the file as text regardless of its
     name.

 -- Command: find-file-binary filename
     Like `find-file', but treat the file as binary regardless of its
     name.


File: lispref.info,  Node: Backups and Auto-Saving,  Next: Buffers,  Prev: Files,  Up: Top

36 Backups and Auto-Saving
**************************

Backup files and auto-save files are two methods by which XEmacs tries
to protect the user from the consequences of crashes or of the user's
own errors.  Auto-saving preserves the text from earlier in the current
editing session; backup files preserve file contents prior to the
current session.

* Menu:

* Backup Files::   How backup files are made; how their names are chosen.
* Auto-Saving::    How auto-save files are made; how their names are chosen.
* Reverting::      `revert-buffer', and how to customize what it does.


File: lispref.info,  Node: Backup Files,  Next: Auto-Saving,  Up: Backups and Auto-Saving

36.1 Backup Files
=================

A "backup file" is a copy of the old contents of a file you are
editing.  XEmacs makes a backup file the first time you save a buffer
into its visited file.  Normally, this means that the backup file
contains the contents of the file as it was before the current editing
session.  The contents of the backup file normally remain unchanged once
it exists.

   Backups are usually made by renaming the visited file to a new name.
Optionally, you can specify that backup files should be made by copying
the visited file.  This choice makes a difference for files with
multiple names; it also can affect whether the edited file remains owned
by the original owner or becomes owned by the user editing it.

   By default, XEmacs makes a single backup file for each file edited.
You can alternatively request numbered backups; then each new backup
file gets a new name.  You can delete old numbered backups when you
don't want them any more, or XEmacs can delete them automatically.

* Menu:

* Making Backups::     How XEmacs makes backup files, and when.
* Rename or Copy::     Two alternatives: renaming the old file or copying it.
* Numbered Backups::   Keeping multiple backups for each source file.
* Backup Names::       How backup file names are computed; customization.


File: lispref.info,  Node: Making Backups,  Next: Rename or Copy,  Up: Backup Files

36.1.1 Making Backup Files
--------------------------

 -- Function: backup-buffer
     This function makes a backup of the file visited by the current
     buffer, if appropriate.  It is called by `save-buffer' before
     saving the buffer the first time.

 -- Variable: buffer-backed-up
     This buffer-local variable indicates whether this buffer's file has
     been backed up on account of this buffer.  If it is non-`nil', then
     the backup file has been written.  Otherwise, the file should be
     backed up when it is next saved (if backups are enabled).  This is
     a permanent local; `kill-local-variables' does not alter it.

 -- User Option: make-backup-files
     This variable determines whether or not to make backup files.  If
     it is non-`nil', then XEmacs creates a backup of each file when it
     is saved for the first time--provided that `backup-inhibited' is
     `nil' (see below).

     The following example shows how to change the `make-backup-files'
     variable only in the `RMAIL' buffer and not elsewhere.  Setting it
     `nil' stops XEmacs from making backups of the `RMAIL' file, which
     may save disk space.  (You would put this code in your `.emacs'
     file.)

          (add-hook 'rmail-mode-hook
                    (function (lambda ()
                                (make-local-variable
                                 'make-backup-files)
                                (setq make-backup-files nil))))

 -- Variable: backup-enable-predicate
     This variable's value is a function to be called on certain
     occasions to decide whether a file should have backup files.  The
     function receives one argument, a file name to consider.  If the
     function returns `nil', backups are disabled for that file.
     Otherwise, the other variables in this section say whether and how
     to make backups.

     The default value is this:

          (lambda (name)
            (or (< (length name) 5)
                (not (string-equal "/tmp/"
                                   (substring name 0 5)))))

 -- Variable: backup-inhibited
     If this variable is non-`nil', backups are inhibited.  It records
     the result of testing `backup-enable-predicate' on the visited file
     name.  It can also coherently be used by other mechanisms that
     inhibit backups based on which file is visited.  For example, VC
     sets this variable non-`nil' to prevent making backups for files
     managed with a version control system.

     This is a permanent local, so that changing the major mode does
     not lose its value.  Major modes should not set this
     variable--they should set `make-backup-files' instead.


File: lispref.info,  Node: Rename or Copy,  Next: Numbered Backups,  Prev: Making Backups,  Up: Backup Files

36.1.2 Backup by Renaming or by Copying?
----------------------------------------

There are two ways that XEmacs can make a backup file:

   * 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.

   * 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.

   The first method, renaming, is the default.

   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::.

 -- Variable: backup-by-copying
     If this variable is non-`nil', XEmacs always makes backup files by
     copying.

   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.

 -- Variable: backup-by-copying-when-linked
     If this variable is non-`nil', XEmacs makes backups by copying for
     files with multiple names (hard links).

     This variable is significant only if `backup-by-copying' is `nil',
     since copying is always used when that variable is non-`nil'.

 -- 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.

     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.

     This variable is significant only if `backup-by-copying' is `nil',
     since copying is always used when that variable is non-`nil'.


File: lispref.info,  Node: Numbered Backups,  Next: Backup Names,  Prev: Rename or Copy,  Up: Backup Files

36.1.3 Making and Deleting Numbered Backup Files
------------------------------------------------

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.

 -- User Option: version-control
     This variable controls whether to make a single non-numbered backup
     file or multiple numbered backups.

    `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.


File: lispref.info,  Node: Backup Names,  Prev: Numbered Backups,  Up: Backup Files

36.1.4 Naming Backup Files
--------------------------

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.

 -- 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.

          (backup-file-name-p "foo")
               => nil
          (backup-file-name-p "foo~")
               => 3

     The standard definition of this function is as follows:

          (defun backup-file-name-p (file)
            "Return non-nil if FILE is a backup file \
          name (numeric or not)..."
            (string-match "~$" file))

     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.)

     This simple expression is placed in a separate function to make it
     easy to redefine for customization.

 -- 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.

     The standard definition of this function is as follows:

          (defun make-backup-file-name (file)
            "Create the non-numeric backup file name for FILE.
          ..."
            (concat file "~"))

     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:

          (defun make-backup-file-name (filename)
            (concat "." filename "~"))

          (make-backup-file-name "backups.texi")
               => ".backups.texi~"

 -- 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.

     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::.

     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.

          (find-backup-file-name "~rms/foo")
               => ("~rms/foo.~5~" "~rms/foo.~3~")

 -- 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.

     Some file comparison commands use this function so that they can
     automatically compare a file with its most recent backup.


File: lispref.info,  Node: Auto-Saving,  Next: Reverting,  Prev: Backup Files,  Up: Backups and Auto-Saving

36.2 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

     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.


File: lispref.info,  Node: Reverting,  Prev: Auto-Saving,  Up: Backups and Auto-Saving

36.3 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'.

     Font Lock mode uses this hook to recompute the fonts for the
     updated buffer contents.


File: lispref.info,  Node: Buffers,  Next: Windows,  Prev: Backups and Auto-Saving,  Up: Top

37 Buffers
**********

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:

* 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.


File: lispref.info,  Node: Buffer Basics,  Next: Current Buffer,  Up: Buffers

37.1 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.


File: lispref.info,  Node: Current Buffer,  Next: Buffer Names,  Prev: Buffer Basics,  Up: Buffers

37.2 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.


File: lispref.info,  Node: Buffer Names,  Next: Buffer File Name,  Prev: Current Buffer,  Up: Buffers

37.3 Buffer Names
=================

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.

   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: 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.

     If `buffer-name' returns `nil', it means that BUFFER has been
     killed.  *Note Killing Buffers::.

          (buffer-name)
               => "buffers.texi"

          (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

     See also the function `get-buffer-create' in *Note Creating
     Buffers::.

 -- 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 `<...>'.

     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.

     See the related function `generate-new-buffer' in *Note Creating
     Buffers::.


File: lispref.info,  Node: Buffer File Name,  Next: Buffer Modification,  Prev: Buffer Names,  Up: Buffers

37.4 Buffer File Name
=====================

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.


File: lispref.info,  Node: Buffer Modification,  Next: Modification Time,  Prev: Buffer File Name,  Up: Buffers

37.5 Buffer Modification
========================

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.


File: lispref.info,  Node: Modification Time,  Next: Read Only Buffers,  Prev: Buffer Modification,  Up: Buffers

37.6 Comparison of Modification Time
====================================

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::.


File: lispref.info,  Node: Read Only Buffers,  Next: The Buffer List,  Prev: Modification Time,  Up: Buffers

37.7 Read-Only Buffers
======================

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.


File: lispref.info,  Node: The Buffer List,  Next: Creating Buffers,  Prev: Read Only Buffers,  Up: Buffers

37.8 The Buffer List
====================

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.

   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.

   Note that the different buffer lists all contain the same elements.
It is only the order of those elements that is different.

 -- 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.

          (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")

     Buffers appear earlier in the list if they were current more
     recently.

     This list is a copy of a list used inside XEmacs; modifying it has
     no effect on the buffers.

 -- 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.

     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.

     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::.

     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 no suitable buffer exists, the buffer `*scratch*' is returned
     (and created, if necessary).

     Note that in FSF Emacs 19, there is no FRAME argument, and
     VISIBLE-OK is the second argument instead of the third.

 -- 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'.

 -- 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.

     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.

     If you wish to replace a buffer in all the windows that display
     it, use `replace-buffer-in-windows'.  *Note Buffers and Windows::.


File: lispref.info,  Node: Creating Buffers,  Next: Killing Buffers,  Prev: The Buffer List,  Up: Buffers

37.9 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.

   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::).

 -- 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.

     An error is signaled if NAME is not a string.

          (get-buffer-create "foo")
               => #<buffer foo>

     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: 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.

     An error is signaled if NAME is not a string.

          (generate-new-buffer "bar")
               => #<buffer bar>
          (generate-new-buffer "bar")
               => #<buffer bar<2>>
          (generate-new-buffer "bar")
               => #<buffer bar<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::.

     See the related function `generate-new-buffer-name' in *Note
     Buffer Names::.


File: lispref.info,  Node: Killing Buffers,  Next: Indirect Buffers,  Prev: Creating Buffers,  Up: Buffers

37.10 Killing Buffers
=====================

"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 object
     This function returns `t' if OBJECT is an editor buffer that has
     not been deleted, `nil' 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'.  The argument BUFFER-OR-NAME may be a buffer or
     the name of one.

     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 ----------

               => 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::.


File: lispref.info,  Node: Indirect Buffers,  Prev: Killing Buffers,  Up: Buffers

37.11 Indirect Buffers
======================

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".

   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.

   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.

   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.

   Killing an indirect buffer has no effect on its base buffer.  Killing
the base buffer kills all its indirect children.

 -- 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.

     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.

          (buffer-base-buffer (get-buffer "indirect"))
               => #<buffer "*scratch*">

 -- 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.

          (buffer-indirect-children (get-buffer "*scratch*"))
               => (#<buffer "indirect">)


File: lispref.info,  Node: Windows,  Next: Frames,  Prev: Buffers,  Up: Top

38 Windows
**********

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.

* 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.


File: lispref.info,  Node: Basic Windows,  Next: Splitting Windows,  Up: Windows

38.1 Basic Concepts of Emacs Windows
====================================

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 any 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

   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.

   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.

   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::.

   *Note Display::, for information on how the contents of the window's
buffer are displayed in the window.

 -- Function: windowp object
     This function returns `t' if OBJECT is a window.


File: lispref.info,  Node: Splitting Windows,  Next: Deleting Windows,  Prev: Basic Windows,  Up: Windows

38.2 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 nomini which-frames which-devices
     This function returns non-`nil' if there is only one window.  The
     argument NOMINI, 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 remaining arguments controls which set of windows are counted,
     as with `next-window'.

 -- 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

          ;; 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-window'.  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-window'.  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))


File: lispref.info,  Node: Deleting Windows,  Next: Selecting Windows,  Prev: Splitting Windows,  Up: Windows

38.3 Deleting Windows
=====================

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 force
     This function removes WINDOW from the display.  If WINDOW is
     omitted, then the selected window is deleted. If window is the
     only one on its frame, the frame is deleted as well.

     Normally, you cannot delete the last non-minibuffer-only frame
     (you must use `save-buffers-kill-emacs' or `kill-emacs'); an error
     is signaled instead.  However, if optional second argument FORCE is
     non-`nil', you can delete the last frame. (This will automatically
     call `save-buffers-kill-emacs'.)

     This function returns `nil'.

     When `delete-window' is called interactively, the selected window
     is deleted.

 -- 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 which-frames
          which-devices
     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 WHICH-FRAMES controls which frames to operate on:

    `nil'
          Delete all windows showing BUFFER in any frame.

    `t'
          Delete only windows showing BUFFER in the selected frame.

    `visible'
          Delete all windows showing BUFFER in any visible frame.

    `0'
          Delete all windows showing BUFFER in any visible frame.

    FRAME
          If it is a frame, delete all windows showing BUFFER in that
          frame.

     *Warning:* This is similar to, but not identical to, the meaning
     of the WHICH-FRAMES argument to `next-window'; the meanings of
     `nil' and `t' are reversed.

     The optional argument WHICH-DEVICES further clarifies on which
     devices to search for frames as specified by WHICH-FRAMES.  This
     value is only meaningful if WHICH-FRAMES is not `t'.

    `nil'
          Consider all devices on the selected console.

    DEVICE
          Consider only the one device DEVICE.

    CONSOLE
          Consider all devices on CONSOLE.

    DEVICE-TYPE
          Consider all devices with device type DEVICE-TYPE.

    `window-system'
          Consider all devices on window system consoles.

    anything else
          Consider all devices without restriction.

     This function always returns `nil'.


File: lispref.info,  Node: Selecting Windows,  Next: Cyclic Window Ordering,  Prev: Deleting Windows,  Up: Windows

38.4 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>

 -- Special Form: save-selected-window forms...
     This special form 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.

   The following functions choose one of the windows on the screen,
offering various criteria for the choice.

 -- Function: get-lru-window &optional which-frames which-devices
     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.

     By default, only the windows in the selected frame are considered.
     The optional argument WHICH-FRAMES changes this behavior.  Here
     are the possible values and their meanings:

    `nil'
          Consider all the windows in the selected windows'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.

    FRAME
          Consider all windows on frame FRAME.

    anything else
          Consider precisely the windows in the selected window's
          frame, and no others.

     The optional argument WHICH-DEVICES further clarifies on which
     devices to search for frames as specified by WHICH-FRAMES.  This
     value is only meaningful if WHICH-FRAMES is non-`nil'.

    `nil'
          Consider all devices on the selected console.

    DEVICE
          Consider only the one device DEVICE.

    CONSOLE
          Consider all devices on CONSOLE.

    DEVICE-TYPE
          Consider all devices with device type DEVICE-TYPE.

    `window-system'
          Consider all devices on window system consoles.

    anything else
          Consider all devices without restriction.


 -- Function: get-largest-window &optional which-frames which-devices
     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.

     The remaining arguments control which set of windows are
     considered.  See `next-window', above.


File: lispref.info,  Node: Cyclic Window Ordering,  Next: Buffers and Windows,  Prev: Selecting Windows,  Up: Windows

38.5 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 which-frames
          which-devices
     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.

     By default, only the windows in the selected frame are considered.
     The optional argument WHICH-FRAMES changes this behavior.  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.

    FRAME
          Consider all windows on frame FRAME.

    anything else
          Consider precisely the windows in WINDOW's frame, and no
          others.

     The optional argument WHICH-DEVICES further clarifies on which
     devices to search for frames as specified by WHICH-FRAMES.  This
     value is only meaningful if WHICH-FRAMES is non-`nil'.

    `nil'
          Consider all devices on the selected console.

    DEVICE
          Consider only the one device DEVICE.

    CONSOLE
          Consider all devices on CONSOLE.

    DEVICE-TYPE
          Consider all devices with device type DEVICE-TYPE.

    `window-system'
          Consider all devices on window system consoles.

    anything else
          Consider all devices without restriction.

     If you use consistent values for MINIBUF, WHICH-FRAMES, and
     WHICH-DEVICES, you can use `next-window' to iterate through the
     entire cycle of acceptable windows, eventually ending up back at
     the window you started with.  `previous-window' traverses the same
     cycle, in the reverse order.

     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 which-frames
          which-devices
     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 which-frames which-devices
     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 other arguments specify which windows to include in the cycle,
     as in `next-window'.

 -- Function: walk-windows function &optional minibuf which-frames
          which-devices
     This function cycles through all windows, calling `function' once
     for each window with the window as its sole argument.

     The other arguments specify which windows to cycle through, as in
     `next-window'.


File: lispref.info,  Node: Buffers and Windows,  Next: Displaying Buffers,  Prev: Cyclic Window Ordering,  Up: Windows

38.6 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.

 -- Function: set-window-buffer window buffer-or-name &optional norecord
     This function makes WINDOW display BUFFER-OR-NAME as its contents.
     BUFFER-OR-NAME can be a buffer or a buffer name.

     With non-`nil' optional argument NORECORD, do not modify the
     global or per-frame buffer ordering.

     This function returns `nil'.

          (set-window-buffer (selected-window) "foo")
               => nil

 -- 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.

          (window-buffer)
               => #<buffer windows.texi>

 -- Function: get-buffer-window buffer-or-name &optional which-frames
          which-devices
     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 remaining arguments control which windows to consider.  They
     have the same meaning as for `next-window'.


File: lispref.info,  Node: Displaying Buffers,  Next: Choosing Window,  Prev: Buffers and Windows,  Up: Windows

38.7 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 &optional which-frames
          which-devices
     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.

     The optional arguments WHICH-FRAMES and WHICH-DEVICES have the
     same meaning as with `delete-windows-on'.

     This function returns `nil'.


File: lispref.info,  Node: Choosing Window,  Next: Window Point,  Prev: Displaying Buffers,  Up: Windows

38.8 Choosing a Window for Display
==================================

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.

 -- Command: display-buffer buffer-or-name &optional not-this-window
          override-frame
     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.

     BUFFER-OR-NAME can be a buffer or the name of one.

     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 OVERRIDE-FRAME is non-`nil', display on that frame instead of
     the current frame (or the dedicated frame).

     `display-buffer' returns the window chosen to display
     BUFFER-OR-NAME.

     Precisely how `display-buffer' finds or creates a window depends on
     the variables described below.

   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.

 -- Function: window-dedicated-p window
     This function returns WINDOW's dedicated object, usually `t' or
     `nil'.

 -- 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.


File: lispref.info,  Node: Window Point,  Next: Window Start,  Prev: Choosing Window,  Up: Windows

38.9 Windows and Point
======================

Each window has its own value of point, independent of the value of
point in other windows displaying the same buffer.  This makes it useful
to have multiple windows showing one buffer.

   * The window point is established when a window is first created; it
     is initialized from the buffer's point, or from the window point
     of another window opened on the buffer if such a window exists.

   * Selecting a window sets the value of point in its buffer to the
     window's value of point.  Conversely, deselecting a window sets
     the window's value of point from that of the buffer.  Thus, when
     you switch between windows that display a given buffer, the point
     value for the selected window is in effect in the buffer, while
     the point values for the other windows are stored in those windows.

   * As long as the selected window displays the current buffer, the
     window's point and the buffer's point always move together; they
     remain equal.

   * *Note Positions::, for more details on buffer positions.

   As far as the user is concerned, point is where the cursor is, and
when the user switches to another buffer, the cursor jumps to the
position of point in that buffer.

 -- Function: window-point &optional window
     This function returns the current position of point in WINDOW.
     For a non-selected window, this is the value point would have (in
     that window's buffer) if that window were selected.

     When WINDOW is the selected window and its buffer is also the
     current buffer, the value returned is the same as the value of
     point in that buffer.

     Strictly speaking, it would be more correct to return the
     "top-level" value of point, outside of any `save-excursion' forms.
     But that value is hard to find.

 -- Function: set-window-point window position
     This function positions point in WINDOW at position POSITION in
     WINDOW's buffer.

 -- Function: current-pixel-row &optional window pos
 -- Function: current-pixel-column &optional window pos
     The function, `current-pixel-row', returns the vertical location,
     in pixels, of the point POS within the specified WINDOW;
     similarly, `current-pixel-column' returns the corresponding
     horizontal location.  The position returned is that of the
     upper-left corner of the cursor, and is relative to the upper-left
     location of the window.  If WINDOW is `nil', the function uses the
     selected window.  If POS is `nil', the value of `window-point' is
     used.

     Note that the coordinates are relative to the current XEmacs
     window, and are not relative to the XEmacs X11 window.  To obtain
     the coordinates relative to the X11 window, you must also take
     into account the spacings of any menubars, gutters, toolbars,
     margins, etc., as well as any window offsets.  The function,
     `window-pixel-edges' (*note Position of Window::), can be used to
     help calculate the location relative to the frame.

     _Important note_: in order for these functions to return a correct,
     non-nil value, two criteria _must_ be satisfied:

        * The location of `pos' must be visible within the specified
          window.  If POS is outside the visible area, `nil' is
          returned.

        * As the pixel location is determined from the redisplay
          tables, the redisplay tables must be up-to-date.  In other
          words, the XEmacs window(s), as seen by the user, must be
          correct (to improve performance, XEmacs generally defers
          display updates until control returns back to the idle loop).
          To insure that the redisplay tables are up-to-date, one of
          the following must generally be done _before_ calling
          `current-pixel-row' or `current-pixel-column':

             * If the window in question is not in a new frame, you can
               force a redisplay using `(sit-for 0)'.  See `sit-for' in
               *Note Waiting::.

             * If the window in question is in a new frame, you must
               call code like the following:

                    (while (not (frame-visible-p frame))
                      (sleep-for .5))



     If one of these is not done, the return value may be incorrect,
     even if it is non-nil.



File: lispref.info,  Node: Window Start,  Next: Vertical Scrolling,  Prev: Window Point,  Up: Windows

38.10 The Window Start Position
===============================

Each window contains a marker used to keep track of a buffer position
that specifies where in the buffer display should start.  This position
is called the "display-start" position of the window (or just the
"start").  The character after this position is the one that appears at
the upper left corner of the window.  It is usually, but not
inevitably, at the beginning of a text line.

 -- Function: window-start &optional window
     This function returns the display-start position of window WINDOW.
     If WINDOW is `nil', the selected window is used.  For example,

          (window-start)
               => 7058

     When you create a window, or display a different buffer in it, the
     display-start position is set to a display-start position recently
     used for the same buffer, or 1 if the buffer doesn't have any.

     For a realistic example, see the description of `count-lines' in
     *Note Text Lines::.

 -- Function: window-end &optional window guarantee
     This function returns the position of the end of the display in
     window WINDOW.  If WINDOW is `nil', the selected window is used.

     Simply changing the buffer text or setting `window-start' does not
     update the value that `window-end' returns.  The value is updated
     only when Emacs redisplays and redisplay actually finishes.

     If the last redisplay of WINDOW was preempted, and did not finish,
     Emacs does not know the position of the end of display in that
     window.  In that case, this function returns a value that is not
     correct.  In a future version, `window-end' will return `nil' in
     that case.

     If optional arg GUARANTEE is non-`nil', the return value is
     guaranteed to be the same as `window-end' would return at the end
     of the next full redisplay assuming nothing else changes in the
     meantime.  This function is potentially much slower with this flag
     set.


 -- Function: set-window-start window position &optional noforce
     This function sets the display-start position of WINDOW to
     POSITION in WINDOW's buffer.  It returns POSITION.

     The display routines insist that the position of point be visible
     when a buffer is displayed.  Normally, they change the
     display-start position (that is, scroll the window) whenever
     necessary to make point visible.  However, if you specify the
     start position with this function using `nil' for NOFORCE, it
     means you want display to start at POSITION even if that would put
     the location of point off the screen.  If this does place point
     off screen, the display routines move point to the left margin on
     the middle line in the window.

     For example, if point is 1 and you set the start of the window
     to 2, then point would be "above" the top of the window.  The
     display routines will automatically move point if it is still 1
     when redisplay occurs.  Here is an example:

          ;; Here is what `foo' looks like before executing
          ;;   the `set-window-start' expression.

          ---------- Buffer: foo ----------
          -!-This is the contents of buffer foo.
          2
          3
          4
          5
          6
          ---------- Buffer: foo ----------

          (set-window-start
           (selected-window)
           (1+ (window-start)))
          => 2

          ;; Here is what `foo' looks like after executing
          ;;   the `set-window-start' expression.
          ---------- Buffer: foo ----------
          his is the contents of buffer foo.
          2
          3
          -!-4
          5
          6
          ---------- Buffer: foo ----------

     If NOFORCE is non-`nil', and POSITION would place point off screen
     at the next redisplay, then redisplay computes a new window-start
     position that works well with point, and thus POSITION is not used.

 -- Function: pos-visible-in-window-p &optional position window
     This function returns `t' if POSITION is within the range of text
     currently visible on the screen in WINDOW.  It returns `nil' if
     POSITION is scrolled vertically out of view.  The argument
     POSITION defaults to the current position of point; WINDOW, to the
     selected window.  Here is an example:

          (or (pos-visible-in-window-p
               (point) (selected-window))
              (recenter 0))

     The `pos-visible-in-window-p' function considers only vertical
     scrolling.  If POSITION is out of view only because WINDOW has
     been scrolled horizontally, `pos-visible-in-window-p' returns `t'.
     *Note Horizontal Scrolling::.


File: lispref.info,  Node: Vertical Scrolling,  Next: Horizontal Scrolling,  Prev: Window Start,  Up: Windows

38.11 Vertical Scrolling
========================

Vertical scrolling means moving the text up or down in a window.  It
works by changing the value of the window's display-start location.  It
may also change the value of `window-point' to keep it on the screen.

   In the commands `scroll-up' and `scroll-down', the directions "up"
and "down" refer to the motion of the text in the buffer at which you
are looking through the window.  Imagine that the text is written on a
long roll of paper and that the scrolling commands move the paper up
and down.  Thus, if you are looking at text in the middle of a buffer
and repeatedly call `scroll-down', you will eventually see the
beginning of the buffer.

   Some people have urged that the opposite convention be used: they
imagine that the window moves over text that remains in place.  Then
"down" commands would take you to the end of the buffer.  This view is
more consistent with the actual relationship between windows and the
text in the buffer, but it is less like what the user sees.  The
position of a window on the terminal does not move, and short scrolling
commands clearly move the text up or down on the screen.  We have chosen
names that fit the user's point of view.

   The scrolling functions (aside from `scroll-other-window') have
unpredictable results if the current buffer is different from the buffer
that is displayed in the selected window.  *Note Current Buffer::.

 -- Command: scroll-up &optional lines
     This function scrolls the text in the selected window upward LINES
     lines.  If LINES is negative, scrolling is actually downward.

     If LINES is `nil' (or omitted), then the length of scroll is
     `next-screen-context-lines' lines less than the usable height of
     the window (not counting its modeline).

     `scroll-up' returns `nil'.

 -- Command: scroll-down &optional lines
     This function scrolls the text in the selected window downward
     LINES lines.  If LINES is negative, scrolling is actually upward.

     If LINES is omitted or `nil', then the length of the scroll is
     `next-screen-context-lines' lines less than the usable height of
     the window (not counting its mode line).

     `scroll-down' returns `nil'.

 -- Command: scroll-other-window &optional lines
     This function scrolls the text in another window upward LINES
     lines.  Negative values of LINES, or `nil', are handled as in
     `scroll-up'.

     You can specify a buffer to scroll with the variable
     `other-window-scroll-buffer'.  When the selected window is the
     minibuffer, the next window is normally the one at the top left
     corner.  You can specify a different window to scroll with the
     variable `minibuffer-scroll-window'.  This variable has no effect
     when any other window is selected.  *Note Minibuffer Misc::.

     When the minibuffer is active, it is the next window if the
     selected window is the one at the bottom right corner.  In this
     case, `scroll-other-window' attempts to scroll the minibuffer.  If
     the minibuffer contains just one line, it has nowhere to scroll
     to, so the line reappears after the echo area momentarily displays
     the message "Beginning of buffer".

 -- Variable: other-window-scroll-buffer
     If this variable is non-`nil', it tells `scroll-other-window'
     which buffer to scroll.

 -- User Option: scroll-step
     This variable controls how scrolling is done automatically when
     point moves off the screen.  If the value is zero, then redisplay
     scrolls the text to center point vertically in the window.  If the
     value is a positive integer N, then redisplay brings point back on
     screen by scrolling N lines in either direction, if possible;
     otherwise, it centers point.  The default value is zero.

 -- User Option: scroll-conservatively
     This variable controls how many lines Emacs tries to scroll before
     recentering.  If you set it to a small number, then when you move
     point a short distance off the screen, XEmacs will scroll the
     screen just far enough to bring point back on screen, provided
     that does not exceed `scroll-conservatively' lines.  This variable
     overrides the redisplay preemption.

 -- User Option: next-screen-context-lines
     The value of this variable is the number of lines of continuity to
     retain when scrolling by full screens.  For example, `scroll-up'
     with an argument of `nil' scrolls so that this many lines at the
     bottom of the window appear instead at the top.  The default value
     is `2'.

 -- Command: recenter &optional location window
     This function scrolls WINDOW (which defaults to the selected
     window) to put the text where point is located at a specified
     vertical position within the window.

     If LOCATION is a nonnegative number, it puts the line containing
     point LOCATION lines down from the top of the window.  If LOCATION
     is a negative number, then it counts upward from the bottom of the
     window, so that -1 stands for the last usable line in the window.
     If LOCATION is a non-`nil' list, then it stands for the line in
     the middle of the window.

     If LOCATION is `nil', `recenter' puts the line containing point in
     the middle of the window, then clears and redisplays the entire
     selected frame.

     When `recenter' is called interactively, LOCATION is the raw
     prefix argument.  Thus, typing `C-u' as the prefix sets the
     LOCATION to a non-`nil' list, while typing `C-u 4' sets LOCATION
     to 4, which positions the current line four lines from the top.

     With an argument of zero, `recenter' positions the current line at
     the top of the window.  This action is so handy that some people
     make a separate key binding to do this.  For example,

          (defun line-to-top-of-window ()
            "Scroll current line to top of window.
          Replaces three keystroke sequence C-u 0 C-l."
            (interactive)
            (recenter 0))

          (global-set-key [kp-multiply] 'line-to-top-of-window)


File: lispref.info,  Node: Horizontal Scrolling,  Next: Size of Window,  Prev: Vertical Scrolling,  Up: Windows

38.12 Horizontal Scrolling
==========================

Because we read English first from top to bottom and second from left
to right, horizontal scrolling is not like vertical scrolling.  Vertical
scrolling involves selection of a contiguous portion of text to display.
Horizontal scrolling causes part of each line to go off screen.  The
amount of horizontal scrolling is therefore specified as a number of
columns rather than as a position in the buffer.  It has nothing to do
with the display-start position returned by `window-start'.

   Usually, no horizontal scrolling is in effect; then the leftmost
column is at the left edge of the window.  In this state, scrolling to
the right is meaningless, since there is no data to the left of the
screen to be revealed by it; so this is not allowed.  Scrolling to the
left is allowed; it scrolls the first columns of text off the edge of
the window and can reveal additional columns on the right that were
truncated before.  Once a window has a nonzero amount of leftward
horizontal scrolling, you can scroll it back to the right, but only so
far as to reduce the net horizontal scroll to zero.  There is no limit
to how far left you can scroll, but eventually all the text will
disappear off the left edge.

 -- Command: scroll-left &optional count
     This function scrolls the selected window COUNT columns to the
     left (or to the right if COUNT is negative).  The return value is
     the total amount of leftward horizontal scrolling in effect after
     the change--just like the value returned by `window-hscroll'
     (below).

 -- Command: scroll-right &optional count
     This function scrolls the selected window COUNT columns to the
     right (or to the left if COUNT is negative).  The return value is
     the total amount of leftward horizontal scrolling in effect after
     the change--just like the value returned by `window-hscroll'
     (below).

     Once you scroll a window as far right as it can go, back to its
     normal position where the total leftward scrolling is zero,
     attempts to scroll any farther right have no effect.

 -- Function: window-hscroll &optional window
     This function returns the total leftward horizontal scrolling of
     WINDOW--the number of columns by which the text in WINDOW is
     scrolled left past the left margin.

     The value is never negative.  It is zero when no horizontal
     scrolling has been done in WINDOW (which is usually the case).

     If WINDOW is `nil', the selected window is used.

          (window-hscroll)
               => 0
          (scroll-left 5)
               => 5
          (window-hscroll)
               => 5

 -- Function: set-window-hscroll window columns
     This function sets the number of columns from the left margin that
     WINDOW is scrolled to the value of COLUMNS.  The argument COLUMNS
     should be zero or positive; if not, it is taken as zero.

     The value returned is COLUMNS.

          (set-window-hscroll (selected-window) 10)
               => 10

   Here is how you can determine whether a given position POSITION is
off the screen due to horizontal scrolling:

     (defun hscroll-on-screen (window position)
       (save-excursion
         (goto-char position)
         (and
          (>= (- (current-column) (window-hscroll window)) 0)
          (< (- (current-column) (window-hscroll window))
             (window-width window)))))


File: lispref.info,  Node: Size of Window,  Next: Position of Window,  Prev: Horizontal Scrolling,  Up: Windows

38.13 The Size of a Window
==========================

An Emacs window is rectangular, and its size information consists of
the height (in lines or pixels) and the width (in character positions
or pixels).  The modeline is included in the height.  The pixel width
and height values include scrollbars and margins, while the
line/character-position values do not.

   Note that the height in lines, and the width in characters, are
determined by dividing the corresponding pixel value by the height or
width of the default font in that window (if this is a variable-width
font, the average width is used).  The resulting values may or may not
represent the actual number of lines in the window, or the actual number
of character positions in any particular line, esp. if there are pixmaps
or various different fonts in the window.

   The following functions return size information about a window:

 -- Function: window-height &optional window
     This function returns the number of lines in WINDOW, including its
     modeline but not including the horizontal scrollbar, if any (this
     is different from `window-pixel-height').  If WINDOW is `nil', the
     function uses the selected window.

          (window-height)
               => 40
          (split-window-vertically)
               => #<window on "windows.texi" 0x679b>
          (window-height)
               => 20

 -- Function: window-width &optional window
     This function returns the number of columns in WINDOW, not
     including any left margin, right margin, or vertical scrollbar
     (this is different from `window-pixel-width').  If WINDOW is
     `nil', the function uses the selected window.

          (window-width)
               => 80
          (window-height)
               => 40
          (split-window-horizontally)
               => #<window on "windows.texi" 0x7538>
          (window-width)
               => 39

   Note that after splitting the window into two side-by-side windows,
the width of each window is less the half the width of the original
window because a vertical scrollbar appeared between the windows,
occupying two columns worth of space.  Also, the height shrunk by one
because horizontal scrollbars appeared that weren't there before.
(Horizontal scrollbars appear only when lines are truncated, not when
they wrap.  This is usually the case for horizontally split windows but
not for full-frame windows.  You can change this using the variables
`truncate-lines' and `truncate-partial-width-windows'.)

 -- Function: window-pixel-height &optional window
     This function returns the height of WINDOW in pixels, including
     its modeline and horizontal scrollbar, if any.  If WINDOW is
     `nil', the function uses the selected window.

          (window-pixel-height)
               => 600
          (split-window-vertically)
               => #<window on "windows.texi" 0x68a6>
          (window-pixel-height)
               => 300

 -- Function: window-pixel-width &optional window
     This function returns the width of WINDOW in pixels, including any
     left margin, right margin, or vertical scrollbar that may be
     displayed alongside it.  If WINDOW is `nil', the function uses the
     selected window.

          (window-pixel-width)
               => 735
          (window-pixel-height)
               => 600
          (split-window-horizontally)
               => #<window on "windows.texi" 0x7538>
          (window-pixel-width)
               => 367
          (window-pixel-height)
               => 600

 -- Function: window-text-area-pixel-height &optional window
     This function returns the height in pixels of the text displaying
     portion of WINDOW, which defaults to the selected window.  Unlike
     `window-pixel-height', the space occupied by the modeline and
     horizontal scrollbar, if any, is not counted.

 -- Function: window-text-area-pixel-width &optional window
     This function returns the width in pixels of the text displaying
     portion of WINDOW, which defaults to the selected window.  Unlike
     `window-pixel-width', the space occupied by the vertical scrollbar
     and divider, if any, is not counted.

 -- Function: window-displayed-text-pixel-height &optional window
          noclipped
     This function returns the height in pixels of the text displayed in
     WINDOW, which defaults to the selected window.  Unlike
     `window-text-area-pixel-height', any blank space below the end of
     the buffer is not included.  If optional argument NOCLIPPED is
     non-`nil', any space occupied by clipped lines will not be
     included.


File: lispref.info,  Node: Position of Window,  Next: Resizing Windows,  Prev: Size of Window,  Up: Windows

38.14 The Position of a Window
==============================

XEmacs provides functions to determine the absolute location of windows
within a frame, and the relative location of a window in comparison to
other windows in the same frame.

 -- Function: window-pixel-edges &optional window
     This function returns a list of the pixel edge coordinates of
     WINDOW.  If WINDOW is `nil', the selected window is used.

     The order of the list is `(LEFT TOP RIGHT BOTTOM)', all elements
     relative to 0, 0 at the top left corner of WINDOW's frame.  The
     element RIGHT of the value is one more than the rightmost pixel
     used by WINDOW (including any left margin, right margin, or
     vertical scrollbar displayed alongside it), and BOTTOM is one more
     than the bottommost pixel used by WINDOW (including any modeline
     or horizontal scrollbar displayed above or below it).  The frame
     area does not include any frame menubars, toolbars, or gutters
     that may be displayed; thus, for example, if there is only one
     window on the frame, the values for LEFT and TOP will always be 0.

     If WINDOW is at the upper left corner of its frame, RIGHT and
     BOTTOM are the same as the values returned by
     `(window-pixel-width)' and `(window-pixel-height)' respectively,
     and LEFT and TOP are zero.

   There is no longer a function `window-edges' because it does not
make sense in a world with variable-width and variable-height lines, as
are allowed in XEmacs.

 -- Function: window-highest-p window
     This function returns non-`nil' if WINDOW is along the top of its
     frame.

 -- Function: window-lowest-p window
     This function returns non-`nil' if WINDOW is along the bottom of
     its frame.

 -- Function: window-text-area-pixel-edges &optional window
     This function allows one to determine the location of the
     text-displaying portion of WINDOW, which defaults to the selected
     window, with respect to the top left corner of the window.  It
     returns a list of integer pixel positions `(left top right
     bottom)', all relative to `(0,0)' at the top left corner of the
     window.


File: lispref.info,  Node: Resizing Windows,  Next: Window Configurations,  Prev: Position of Window,  Up: Windows

38.15 Changing the Size of a Window
===================================

The window size functions fall into two classes: high-level commands
that change the size of windows and low-level functions that access
window size.  XEmacs does not permit overlapping windows or gaps between
windows, so resizing one window affects other windows.

 -- Command: enlarge-window count &optional horizontal window
     This function makes the selected window COUNT lines taller,
     stealing lines from neighboring windows.  It takes the lines from
     one window at a time until that window is used up, then takes from
     another.  If a window from which lines are stolen shrinks below
     `window-min-height' lines, that window disappears.

     If HORIZONTAL is non-`nil', this function makes WINDOW wider by
     COUNT columns, stealing columns instead of lines.  If a window
     from which columns are stolen shrinks below `window-min-width'
     columns, that window disappears.

     If the requested size would exceed that of the window's frame,
     then the function makes the window occupy the entire height (or
     width) of the frame.

     If COUNT is negative, this function shrinks the window by -COUNT
     lines or columns.  If that makes the window smaller than the
     minimum size (`window-min-height' and `window-min-width'),
     `enlarge-window' deletes the window.

     If WINDOW is non-`nil', it specifies a window to change instead of
     the selected window.

     `enlarge-window' returns `nil'.

 -- Command: enlarge-window-horizontally columns
     This function makes the selected window COLUMNS wider.  It could
     be defined as follows:

          (defun enlarge-window-horizontally (columns)
            (enlarge-window columns t))

 -- Command: enlarge-window-pixels count &optional side window
     This function makes the selected window COUNT pixels larger.  When
     called from Lisp, optional second argument SIDE non-`nil' means to
     grow sideways COUNT pixels, and optional third argument WINDOW
     specifies the window to change instead of the selected window.

 -- Command: shrink-window count &optional horizontal window
     This function is like `enlarge-window' but negates the argument
     COUNT, making the selected window smaller by giving lines (or
     columns) to the other windows.  If the window shrinks below
     `window-min-height' or `window-min-width', then it disappears.

     If COUNT is negative, the window is enlarged by -COUNT lines or
     columns.

     If WINDOW is non-`nil', it specifies a window to change instead of
     the selected window.

 -- Command: shrink-window-horizontally columns
     This function makes the selected window COLUMNS narrower.  It
     could be defined as follows:

          (defun shrink-window-horizontally (columns)
            (shrink-window columns t))

 -- Command: shrink-window-pixels count &optional side window
     This function makes the selected window COUNT pixels smaller.
     When called from Lisp, optional second argument SIDE non-`nil'
     means to shrink sideways COUNT pixels, and optional third argument
     WINDOW specifies the window to change instead of the selected
     window.

   The following two variables constrain the window-size-changing
functions to a minimum height and width.

 -- User Option: window-min-height
     The value of this variable determines how short a window may become
     before it is automatically deleted.  Making a window smaller than
     `window-min-height' automatically deletes it, and no window may be
     created shorter than this.  The absolute minimum height is two
     (allowing one line for the mode line, and one line for the buffer
     display).  Actions that change window sizes reset this variable to
     two if it is less than two.  The default value is 4.

 -- User Option: window-min-width
     The value of this variable determines how narrow a window may
     become before it automatically deleted.  Making a window smaller
     than `window-min-width' automatically deletes it, and no window
     may be created narrower than this.  The absolute minimum width is
     one; any value below that is ignored.  The default value is 10.

 -- Variable: window-size-change-functions
     This variable holds a list of functions to be called if the size
     of any window changes for any reason.  The functions are called
     just once per redisplay, and just once for each frame on which
     size changes have occurred.

     Each function receives the frame as its sole argument.  There is no
     direct way to find out which windows changed size, or precisely
     how; however, if your size-change function keeps track, after each
     change, of the windows that interest you, you can figure out what
     has changed by comparing the old size data with the new.

     Creating or deleting windows counts as a size change, and therefore
     causes these functions to be called.  Changing the frame size also
     counts, because it changes the sizes of the existing windows.

     It is not a good idea to use `save-window-excursion' in these
     functions, because that always counts as a size change, and it
     would cause these functions to be called over and over.  In most
     cases, `save-selected-window' is what you need here.


File: lispref.info,  Node: Window Configurations,  Prev: Resizing Windows,  Up: Windows

38.16 Window Configurations
===========================

A "window configuration" records the entire layout of a frame--all
windows, their sizes, which buffers they contain, what part of each
buffer is displayed, and the values of point and the mark.  You can
bring back an entire previous layout by restoring a window
configuration previously saved.

   If you want to record all frames instead of just one, use a frame
configuration instead of a window configuration.  *Note Frame
Configurations::.

 -- Function: current-window-configuration &optional frame
     This function returns a new object representing the current window
     configuration of FRAME, namely the number of windows, their sizes
     and current buffers, which window is the selected window, and for
     each window the displayed buffer, the display-start position, and
     the positions of point and the mark.  An exception is made for
     point in the current buffer, whose value is not saved.

     FRAME defaults to the selected frame.

 -- Function: set-window-configuration configuration
     This function restores the configuration of XEmacs's windows and
     buffers to the state specified by CONFIGURATION.  The argument
     CONFIGURATION must be a value that was previously returned by
     `current-window-configuration'.

     This function always counts as a window size change and triggers
     execution of the `window-size-change-functions'.  (It doesn't know
     how to tell whether the new configuration actually differs from
     the old one.)

     Here is a way of using this function to get the same effect as
     `save-window-excursion':

          (let ((config (current-window-configuration)))
            (unwind-protect
                (progn (split-window-vertically nil)
                       ...)
              (set-window-configuration config)))

 -- Special Form: save-window-excursion forms...
     This special form records the window configuration, executes FORMS
     in sequence, then restores the earlier window configuration.  The
     window configuration includes the value of point and the portion
     of the buffer that is visible.  It also includes the choice of
     selected window.  However, it does not include the value of point
     in the current buffer; use `save-excursion' if you wish to
     preserve that.

     Don't use this construct when `save-selected-window' is all you
     need.

     Exit from `save-window-excursion' always triggers execution of the
     `window-size-change-functions'.  (It doesn't know how to tell
     whether the restored configuration actually differs from the one in
     effect at the end of the FORMS.)

     The return value is the value of the final form in FORMS.  For
     example:

          (split-window)
               => #<window 25 on control.texi>
          (setq w (selected-window))
               => #<window 19 on control.texi>
          (save-window-excursion
            (delete-other-windows w)
            (switch-to-buffer "foo")
            'do-something)
               => do-something
               ;; The frame is now split again.

 -- Function: window-configuration-p object
     This function returns `t' if OBJECT is a window configuration.

   Primitives to look inside of window configurations would make sense,
but none are implemented.  It is not clear they are useful enough to be
worth implementing.


File: lispref.info,  Node: Frames,  Next: Consoles and Devices,  Prev: Windows,  Up: Top

39 Frames
*********

A FRAME is a rectangle on the screen that contains one or more XEmacs
windows (*note Windows::).  A frame initially contains a single main
window (plus perhaps an echo area), which you can subdivide vertically
or horizontally into smaller windows.  Each window is associated with a
modeline (*note Modeline Format::), and optionally two scrollbars
(*note Scrollbars::).  By default the vertical scrollbar is on, the
horizontal scrollbar is off.

   The frame may also contain menubars (*note Menubar::), toolbars
(*note Toolbar Intro::), and gutters (*note Gutter Intro::).  By default
there is one of each at the top of the frame, with menubar topmost,
toolbar next, and gutter lowest, immediately above the windows.
(Warning: the gutter is a new, experimental, and unstable feature of
XEmacs version 21.2.)

   When XEmacs runs on a text-only terminal, it starts with one "TTY
frame".  If you create additional ones, XEmacs displays one and only
one at any given time--on the terminal screen, of course.

   When XEmacs communicates directly with an X server, it does not have
a TTY frame; instead, it starts with a single "X window frame".  It can
display multiple X window frames at the same time, each in its own X
window.

 -- Function: framep object
     This predicate returns `t' if OBJECT is a frame, and `nil'
     otherwise.

* Menu:

* Creating Frames::		Creating additional frames.
* Frame Properties::		Controlling frame size, position, font, etc.
* Frame Titles::                Automatic updating of frame titles.
* Deleting Frames::		Frames last until explicitly deleted.
* Finding All Frames::		How to examine all existing frames.
* Frames and Windows::		A frame contains windows;
				  display of text always works through windows.
* Minibuffers and Frames::	How a frame finds the minibuffer to use.
* Input Focus::			Specifying the selected frame.
* Visibility of Frames::	Frames may be visible or invisible, or icons.
* Raising and Lowering::	Raising a frame makes it hide other X windows;
				  lowering it makes the others hide them.
* Frame Configurations::	Saving the state of all frames.
* Frame Hooks::                 Hooks for customizing frame behavior.

   *Note Display::, for related information.


File: lispref.info,  Node: Creating Frames,  Next: Frame Properties,  Up: Frames

39.1 Creating Frames
====================

To create a new frame, call the function `make-frame'.

 -- Command: make-frame &optional props device
     This function creates a new frame on DEVICE, if DEVICE permits
     creation of frames.  (An X server does; an ordinary terminal does
     not (yet).)  DEVICE defaults to the selected device if omitted.
     *Note Consoles and Devices::.

     The argument PROPS is a property list (a list of alternating
     keyword-value specifications) of properties for the new frame. (An
     alist is accepted for backward compatibility but should not be
     passed in.) Any properties not mentioned in PROPS default
     according to the value of the variable `default-frame-plist'.  For
     X devices, properties not specified in `default-frame-plist'
     default in turn from `default-x-frame-plist' and, if not specified
     there, from the X resources.  For TTY devices,
     `default-tty-frame-plist' is consulted as well as
     `default-frame-plist'.

     The set of possible properties depends in principle on what kind of
     window system XEmacs uses to display its frames.  *Note X Frame
     Properties::, for documentation of individual properties you can
     specify when creating an X window frame.


File: lispref.info,  Node: Frame Properties,  Next: Frame Titles,  Prev: Creating Frames,  Up: Frames

39.2 Frame Properties
=====================

A frame has many properties that control its appearance and behavior.
Just what properties a frame has depends on which display mechanism it
uses.

   Frame properties exist for the sake of window systems.  A terminal
frame has few properties, mostly for compatibility's sake; only the
height, width and `buffer-predicate' properties really do something.

* Menu:

* Property Access::	How to change a frame's properties.
* Initial Properties::	Specifying frame properties when you make a frame.
* X Frame Properties::	List of frame properties.
* Size and Position::	Changing the size and position of a frame.
* Frame Name::		The name of a frame (as opposed to its title).


File: lispref.info,  Node: Property Access,  Next: Initial Properties,  Up: Frame Properties

39.2.1 Access to Frame Properties
---------------------------------

These functions let you read and change the properties of a frame.

 -- Function: frame-properties &optional frame
     This function returns a plist listing all the properties of FRAME
     and their values.

 -- Function: frame-property frame property &optional default
     This function returns FRAME's value for the property PROPERTY, or
     DEFAULT if there is no such property.

 -- Function: set-frame-properties frame plist
     This function alters the properties of frame FRAME based on the
     elements of property list PLIST.  If you don't mention a property
     in PLIST, its value doesn't change.

 -- Function: set-frame-property frame property value
     This function sets the property PROPERTY of frame FRAME to the
     value VALUE.


File: lispref.info,  Node: Initial Properties,  Next: X Frame Properties,  Prev: Property Access,  Up: Frame Properties

39.2.2 Initial Frame Properties
-------------------------------

You can specify the properties for the initial startup frame by setting
`initial-frame-plist' in your `.emacs' file.

 -- Variable: initial-frame-plist
     This variable's value is a plist of alternating property-value
     pairs used when creating the initial X window frame.

     XEmacs creates the initial frame before it reads your `~/.emacs'
     file.  After reading that file, XEmacs checks
     `initial-frame-plist', and applies the property settings in the
     altered value to the already created initial frame.

     If these settings affect the frame geometry and appearance, you'll
     see the frame appear with the wrong ones and then change to the
     specified ones.  If that bothers you, you can specify the same
     geometry and appearance with X resources; those do take affect
     before the frame is created.  *Note X Resources: (xemacs)Resources
     X.

     X resource settings typically apply to all frames.  If you want to
     specify some X resources solely for the sake of the initial frame,
     and you don't want them to apply to subsequent frames, here's how
     to achieve this: specify properties in `default-frame-plist' to
     override the X resources for subsequent frames; then, to prevent
     these from affecting the initial frame, specify the same
     properties in `initial-frame-plist' with values that match the X
     resources.

   If these properties specify a separate minibuffer-only frame via a
`minibuffer' property of `nil', and you have not yet created one,
XEmacs creates one for you.

 -- Variable: minibuffer-frame-plist
     This variable's value is a plist of properties used when creating
     an initial minibuffer-only frame--if such a frame is needed,
     according to the properties for the main initial frame.

 -- Variable: default-frame-plist
     This is a plist specifying default values of frame properties for
     subsequent XEmacs frames (not the initial ones).

   See also `special-display-frame-plist', in *Note Choosing Window::.

   If you use options that specify window appearance when you invoke
XEmacs, they take effect by adding elements to `default-frame-plist'.
One exception is `-geometry', which adds the specified position to
`initial-frame-plist' instead.  *Note Command Arguments:
(xemacs)Command Arguments.


File: lispref.info,  Node: X Frame Properties,  Next: Size and Position,  Prev: Initial Properties,  Up: Frame Properties

39.2.3 X Window Frame Properties
--------------------------------

Just what properties a frame has depends on what display mechanism it
uses.  Here is a table of the properties of an X window frame; of these,
`name', `height', `width', and `buffer-predicate' provide meaningful
information in non-X frames.

`name'
     The name of the frame.  Most window managers display the frame's
     name in the frame's border, at the top of the frame.  If you don't
     specify a name, and you have more than one frame, XEmacs sets the
     frame name based on the buffer displayed in the frame's selected
     window.

     If you specify the frame name explicitly when you create the
     frame, the name is also used (instead of the name of the XEmacs
     executable) when looking up X resources for the frame.

`display'
     The display on which to open this frame.  It should be a string of
     the form `"HOST:DPY.SCREEN"', just like the `DISPLAY' environment
     variable.

`left'
     The screen position of the left edge, in pixels, with respect to
     the left edge of the screen.  The value may be a positive number
     POS, or a list of the form `(+ POS)' which permits specifying a
     negative POS value.

     A negative number -POS, or a list of the form `(- POS)', actually
     specifies the position of the right edge of the window with
     respect to the right edge of the screen.  A positive value of POS
     counts toward the left.  If the property is a negative integer
     -POS then POS is positive!

`top'
     The screen position of the top edge, in pixels, with respect to the
     top edge of the screen.  The value may be a positive number POS,
     or a list of the form `(+ POS)' which permits specifying a
     negative POS value.

     A negative number -POS, or a list of the form `(- POS)', actually
     specifies the position of the bottom edge of the window with
     respect to the bottom edge of the screen.  A positive value of POS
     counts toward the top.  If the property is a negative integer -POS
     then POS is positive!

`icon-left'
     The screen position of the left edge _of the frame's icon_, in
     pixels, counting from the left edge of the screen.  This takes
     effect if and when the frame is iconified.

`icon-top'
     The screen position of the top edge _of the frame's icon_, in
     pixels, counting from the top edge of the screen.  This takes
     effect if and when the frame is iconified.

`user-position'
     Non-`nil' if the screen position of the frame was explicitly
     requested by the user (for example, with the `-geometry' option).
     Nothing automatically makes this property non-`nil'; it is up to
     Lisp programs that call `make-frame' to specify this property as
     well as specifying the `left' and `top' properties.

`height'
     The height of the frame contents, in characters.  (To get the
     height in pixels, call `frame-pixel-height'; see *Note Size and
     Position::.)

`width'
     The width of the frame contents, in characters.  (To get the
     height in pixels, call `frame-pixel-width'; see *Note Size and
     Position::.)

`window-id'
     The number of the X window for the frame.

`minibuffer'
     Whether this frame has its own minibuffer.  The value `t' means
     yes, `nil' means no, `only' means this frame is just a minibuffer.
     If the value is a minibuffer window (in some other frame), the
     new frame uses that minibuffer. (Minibuffer-only and
     minibuffer-less frames are not yet implemented in XEmacs.)

`buffer-predicate'
     The buffer-predicate function for this frame.  The function
     `other-buffer' uses this predicate (from the selected frame) to
     decide which buffers it should consider, if the predicate is not
     `nil'.  It calls the predicate with one arg, a buffer, once for
     each buffer; if the predicate returns a non-`nil' value, it
     considers that buffer.

`scroll-bar-width'
     The width of the vertical scroll bar, in pixels.

`cursor-color'
     The color for the cursor that shows point.

`border-color'
     The color for the border of the frame.

`border-width'
     The width in pixels of the window border.

`internal-border-width'
     The distance in pixels between text and border.

`unsplittable'
     If non-`nil', this frame's window is never split automatically.

`inter-line-space'
     The space in pixels between adjacent lines of text. (Not currently
     implemented.)

`modeline'
     Whether the frame has a modeline.


File: lispref.info,  Node: Size and Position,  Next: Frame Name,  Prev: X Frame Properties,  Up: Frame Properties

39.2.4 Frame Size And Position
------------------------------

You can read or change the size and position of a frame using the frame
properties `left', `top', `height', and `width'.  Whatever geometry
properties you don't specify are chosen by the window manager in its
usual fashion.

   Here are some special features for working with sizes and positions:

 -- Function: set-frame-position frame left top
     This function sets the position of the top left corner of FRAME to
     LEFT and TOP.  These arguments are measured in pixels, and count
     from the top left corner of the screen.  Negative property values
     count up or rightward from the top left corner of the screen.

 -- Function: frame-height &optional frame
 -- Function: frame-width &optional frame
     These functions return the height and width of FRAME, measured in
     lines and columns.  If you don't supply FRAME, they use the
     selected frame.

 -- Function: frame-pixel-height &optional frame
 -- Function: frame-pixel-width &optional frame
     These functions return the height and width of FRAME, measured in
     pixels.  If you don't supply FRAME, they use the selected frame.

 -- Function: set-frame-size frame cols rows &optional pretend
     This function sets the size of FRAME, measured in characters; COLS
     and ROWS specify the new width and height.  (If PRETEND is
     non-`nil', it means that redisplay should act as if the frame's
     size is COLS by ROWS, but the actual size of the frame should not
     be changed.  You should not normally use this option.)

   You can also use the functions `set-frame-height' and
`set-frame-width' to set the height and width individually.  The frame
is the first argument and the size (in rows or columns) is the second.
(There is an optional third argument, PRETEND, which has the same
purpose as the corresponding argument in `set-frame-size'.)


File: lispref.info,  Node: Frame Name,  Prev: Size and Position,  Up: Frame Properties

39.2.5 The Name of a Frame (As Opposed to Its Title)
----------------------------------------------------

Under X, every frame has a name, which is not the same as the title of
the frame.  A frame's name is used to look up its resources and does
not normally change over the lifetime of a frame.  It is perfectly
allowable, and quite common, for multiple frames to have the same name.

 -- Function: frame-name &optional frame
     This function returns the name of FRAME, which defaults to the
     selected frame if not specified.  The name of a frame can also be
     obtained from the frame's properties.  *Note Frame Properties::.

 -- Variable: default-frame-name
     This variable holds the default name to assign to newly-created
     frames.  This can be overridden by arguments to `make-frame'.  This
     must be a string.


File: lispref.info,  Node: Frame Titles,  Next: Deleting Frames,  Prev: Frame Properties,  Up: Frames

39.3 Frame Titles
=================

Every frame has a title; most window managers display the frame title at
the top of the frame.  You can specify an explicit title with the
`name' frame property.  But normally you don't specify this explicitly,
and XEmacs computes the title automatically.

   XEmacs computes the frame title based on a template stored in the
variable `frame-title-format'.

 -- Variable: frame-title-format
     This variable specifies how to compute a title for a frame when
     you have not explicitly specified one.

     The variable's value is actually a modeline construct, just like
     `modeline-format'.  *Note Modeline Data::.

 -- Variable: frame-icon-title-format
     This variable specifies how to compute the title for an iconified
     frame, when you have not explicitly specified the frame title.
     This title appears in the icon itself.

 -- Function: x-set-frame-icon-pixmap frame pixmap &optional mask
     This function sets the icon of the given frame to the given image
     instance, which should be an image instance object (as returned by
     `make-image-instance'), a glyph object (as returned by
     `make-glyph'), or `nil'.  If a glyph object is given, the glyph
     will be instantiated on the frame to produce an image instance
     object.

     If the given image instance has a mask, that will be used as the
     icon mask; however, not all window managers support this.

     The window manager is also not required to support color pixmaps,
     only bitmaps (one plane deep).

     If the image instance does not have a mask, then the optional
     third argument may be the image instance to use as the mask (it
     must be one plane deep).  *Note Glyphs::.


File: lispref.info,  Node: Deleting Frames,  Next: Finding All Frames,  Prev: Frame Titles,  Up: Frames

39.4 Deleting Frames
====================

Frames remain potentially visible until you explicitly "delete" them.
A deleted frame cannot appear on the screen, but continues to exist as
a Lisp object until there are no references to it.

 -- Command: delete-frame &optional frame force
     This function deletes the frame FRAME.  By default, FRAME is the
     selected frame.

     A frame may not be deleted if its minibuffer is used by other
     frames.  Normally, you cannot delete the last non-minibuffer-only
     frame (you must use `save-buffers-kill-emacs' or `kill-emacs').
     However, if optional second argument FORCE is non-`nil', you can
     delete the last frame. (This will automatically call
     `save-buffers-kill-emacs'.)

 -- Function: frame-live-p frame
     The function `frame-live-p' returns non-`nil' if the frame FRAME
     has not been deleted.


File: lispref.info,  Node: Finding All Frames,  Next: Frames and Windows,  Prev: Deleting Frames,  Up: Frames

39.5 Finding All Frames
=======================

 -- Function: frame-list
     The function `frame-list' returns a list of all the frames that
     have not been deleted.  It is analogous to `buffer-list' for
     buffers.  The list that you get is newly created, so modifying the
     list doesn't have any effect on the internals of XEmacs.

 -- Function: device-frame-list &optional device
     This function returns a list of all frames on DEVICE.  If DEVICE
     is `nil', the selected device will be used.

 -- Function: visible-frame-list &optional device
     This function returns a list of just the currently visible frames.
     If DEVICE is specified only frames on that device will be returned.
     *Note Visibility of Frames::.  (TTY frames always count as
     "visible", even though only the selected one is actually
     displayed.)

 -- Function: next-frame &optional frame which-frames which-devices
     The function `next-frame' lets you cycle conveniently through all
     the frames from an arbitrary starting point.  It returns the "next"
     frame after FRAME in the cycle.  If FRAME defaults to the selected
     frame.

     The second argument, WHICH-FRAMES, says which frames to consider:

    `visible'
          Consider only frames that are visible.

    `iconic'
          Consider only frames that are iconic.

    `invisible'
          Consider only frames that are invisible (this is different
          from iconic).

    `visible-iconic'
          Consider frames that are visible or iconic.

    `invisible-iconic'
          Consider frames that are invisible or iconic.

    `nomini'
          Consider all frames except minibuffer-only ones.

    `visible-nomini'
          Like `visible' but omits minibuffer-only frames.

    `iconic-nomini'
          Like `iconic' but omits minibuffer-only frames.

    `invisible-nomini'
          Like `invisible' but omits minibuffer-only frames.

    `visible-iconic-nomini'
          Like `visible-iconic' but omits minibuffer-only frames.

    `invisible-iconic-nomini'
          Like `invisible-iconic' but omits minibuffer-only frames.

    `nil'
          Identical to `nomini'.

    WINDOW
          Consider only the window WINDOW's frame and any frame now
          using WINDOW as the minibuffer.

    any other value
          Consider all frames.

     The optional argument WHICH-DEVICES further clarifies on which
     devices to search for frames as specified by WHICH-FRAMES.

    `nil'
          Consider all devices on the selected console.

    DEVICE
          Consider only the one device DEVICE.

    CONSOLE
          Consider all devices on CONSOLE.

    DEVICE-TYPE
          Consider all devices with device type DEVICE-TYPE.

    `window-system'
          Consider all devices on window system consoles.

    anything else
          Consider all devices without restriction.

 -- Function: previous-frame &optional frame which-frames which-devices
     Like `next-frame', but cycles through all frames in the opposite
     direction.

   See also `next-window' and `previous-window', in *Note Cyclic Window
Ordering::.


File: lispref.info,  Node: Frames and Windows,  Next: Minibuffers and Frames,  Prev: Finding All Frames,  Up: Frames

39.6 Frames and Windows
=======================

Each window is part of one and only one frame; you can get the frame
with `window-frame'.

 -- Function: frame-root-window &optional frame
     This returns the root window of frame FRAME.  FRAME defaults to
     the selected frame if not specified.

 -- Function: window-frame &optional window
     This function returns the frame that WINDOW is on.  WINDOW
     defaults to the selected window if omitted.

   All the non-minibuffer windows in a frame are arranged in a cyclic
order.  The order runs from the frame's top window, which is at the
upper left corner, down and to the right, until it reaches the window at
the lower right corner (always the minibuffer window, if the frame has
one), and then it moves back to the top.

 -- Function: frame-highest-window &optional frame position
     This function returns the topmost, leftmost window of frame FRAME
     at position POSITION.

     If omitted, FRAME defaults to the currently selected frame.

     POSITION is used to distinguish between multiple windows that abut
     the top of the frame: 0 means the leftmost window abutting the top
     of the frame, 1 the next-leftmost, etc.  POSITION can also be less
     than zero: -1 means the rightmost window abutting the top of the
     frame, -2 the next-rightmost, etc.  If omitted, POSITION defaults
     to 0, i.e. the leftmost highest window.  If there is no window at
     the given POSITION, `nil' is returned.

   The following three functions work similarly.

 -- Function: frame-lowest-window &optional frame position
     This function returns the lowest window on FRAME which is at
     POSITION.

 -- Function: frame-leftmost-window &optional frame position
     This function returns the leftmost window on FRAME which is at
     POSITION.

 -- Function: frame-rightmost-window &optional frame position
     This function returns the rightmost window on FRAME which is at
     POSITION.

   At any time, exactly one window on any frame is "selected within the
frame".  The significance of this designation is that selecting the
frame also selects this window.  You can get the frame's current
selected window with `frame-selected-window'.

 -- Function: frame-selected-window &optional frame
     This function returns the window on FRAME that is selected within
     FRAME.  FRAME defaults to the selected frame if not specified.

   Conversely, selecting a window for XEmacs with `select-window' also
makes that window selected within its frame.  *Note Selecting Windows::.

   Another function that (usually) returns one of the windows in a
frame is `minibuffer-window'.  *Note Minibuffer Misc::.


File: lispref.info,  Node: Minibuffers and Frames,  Next: Input Focus,  Prev: Frames and Windows,  Up: Frames

39.7 Minibuffers and Frames
===========================

Normally, each frame has its own minibuffer window at the bottom, which
is used whenever that frame is selected.  If the frame has a minibuffer,
you can get it with `minibuffer-window' (*note Minibuffer Misc::).

   However, you can also create a frame with no minibuffer.  Such a
frame must use the minibuffer window of some other frame.  When you
create the frame, you can specify explicitly the minibuffer window to
use (in some other frame).  If you don't, then the minibuffer is found
in the frame which is the value of the variable
`default-minibuffer-frame'.  Its value should be a frame which does
have a minibuffer.

 -- Variable: default-minibuffer-frame
     This variable specifies the frame to use for the minibuffer
     window, by default.


File: lispref.info,  Node: Input Focus,  Next: Visibility of Frames,  Prev: Minibuffers and Frames,  Up: Frames

39.8 Input Focus
================

At any time, one frame in XEmacs is the "selected frame".  The selected
window always resides on the selected frame.  As the focus moves from
device to device, the selected frame on each device is remembered and
restored when the focus moves back to that device.

 -- Function: selected-frame &optional device
     This function returns the selected frame on DEVICE.  If DEVICE is
     not specified, the selected device will be used.  If no frames
     exist on the device, `nil' is returned.

   The X server normally directs keyboard input to the X window that the
mouse is in.  Some window managers use mouse clicks or keyboard events
to "shift the focus" to various X windows, overriding the normal
behavior of the server.

   Lisp programs can switch frames "temporarily" by calling the
function `select-frame'.  This does not override the window manager;
rather, it escapes from the window manager's control until that control
is somehow reasserted.

   When using a text-only terminal, there is no window manager;
therefore, `select-frame' is the only way to switch frames, and the
effect lasts until overridden by a subsequent call to `select-frame'.
Only the selected terminal frame is actually displayed on the terminal.
Each terminal screen except for the initial one has a number, and the
number of the selected frame appears in the mode line after the word
`XEmacs' (*note Modeline Variables::).

 -- Function: select-frame frame
     This function selects frame FRAME, temporarily disregarding the
     focus of the X server if any.  The selection of FRAME lasts until
     the next time the user does something to select a different frame,
     or until the next time this function is called.

     Note that `select-frame' does not actually cause the window-system
     focus to be set to this frame, or the `select-frame-hook' or
     `deselect-frame-hook' to be run, until the next time that XEmacs is
     waiting for an event.

     Also note that when the variable `focus-follows-mouse' is
     non-`nil', the frame selection is temporary and is reverted when
     the current command terminates, much like the buffer selected by
     `set-buffer'.  In order to effect a permanent focus change use
     `focus-frame'.

 -- Function: focus-frame frame
     This function selects FRAME and gives it the window system focus.
     The operation of `focus-frame' is not affected by the value of
     `focus-follows-mouse'.

 -- Special Form: save-selected-frame forms...
     This special form records the selected frame, executes FORMS in
     sequence, then restores the earlier selected frame.  The value
     returned is the value of the last form.

 -- Special Form: with-selected-frame frame forms...
     This special form records the selected frame, then selects FRAME
     and executes FORMS in sequence.  After the last form is finished,
     the earlier selected frame is restored.  The value returned is the
     value of the last form.


File: lispref.info,  Node: Visibility of Frames,  Next: Raising and Lowering,  Prev: Input Focus,  Up: Frames

39.9 Visibility of Frames
=========================

An frame on a window system may be "visible", "invisible", or
"iconified".  If it is visible, you can see its contents.  If it is
iconified, the frame's contents do not appear on the screen, but an icon
does.  If the frame is invisible, it doesn't show on the screen, not
even as an icon.

   Visibility is meaningless for TTY frames, since only the selected
one is actually displayed in any case.

 -- Function: make-frame-visible &optional frame
     This function makes frame FRAME visible.  If you omit FRAME, it
     makes the selected frame visible.

 -- Function: make-frame-invisible &optional frame force
     This function makes frame FRAME invisible.

 -- Command: iconify-frame &optional frame
     This function iconifies frame FRAME.

 -- Function: Command deiconify-frame &optional frame
     This function de-iconifies frame FRAME.  Under a window system,
     this is equivalent to `make-frame-visible'.

 -- Function: frame-visible-p &optional frame
     This returns whether FRAME is currently "visible" (actually in use
     for display).  A frame that is not visible is not updated, and, if
     it works through a window system, may not show at all.

 -- Function: frame-iconified-p &optional frame
     This returns whether FRAME is iconified.  Not all window managers
     use icons; some merely unmap the window, so this function is not
     the inverse of `frame-visible-p'.  It is possible for a frame to
     not be visible and not be iconified either.  However, if the frame
     is iconified, it will not be visible.  (Under FSF Emacs, the
     functionality of this function is obtained through
     `frame-visible-p'.)

 -- Function: frame-totally-visible-p &optional frame
     This returns whether FRAME is not obscured by any other X windows.
     On TTY frames, this is the same as `frame-visible-p'.


File: lispref.info,  Node: Raising and Lowering,  Next: Frame Configurations,  Prev: Visibility of Frames,  Up: Frames

39.10 Raising and Lowering Frames
=================================

The X Window System uses a desktop metaphor.  Part of this metaphor is
the idea that windows are stacked in a notional third dimension
perpendicular to the screen surface, and thus ordered from "highest" to
"lowest".  Where two windows overlap, the one higher up covers the one
underneath.  Even a window at the bottom of the stack can be seen if no
other window overlaps it.

   A window's place in this ordering is not fixed; in fact, users tend
to change the order frequently.  "Raising" a window means moving it
"up", to the top of the stack.  "Lowering" a window means moving it to
the bottom of the stack.  This motion is in the notional third
dimension only, and does not change the position of the window on the
screen.

   You can raise and lower XEmacs's X windows with these functions:

 -- Command: raise-frame &optional frame
     This function raises frame FRAME.

 -- Command: lower-frame &optional frame
     This function lowers frame FRAME.

   You can also specify auto-raise (raising automatically when a frame
is selected) or auto-lower (lowering automatically when it is
deselected).  Under X, most ICCCM-compliant window managers will have
an option to do this for you, but the following variables are provided
in case you're using a broken WM.  (Under FSF Emacs, the same
functionality is provided through the `auto-raise' and `auto-lower'
frame properties.)

 -- Variable: auto-raise-frame
     This variable's value is `t' if frames will be raised to the top
     when selected.

 -- Variable: auto-lower-frame
     This variable's value is `t' if frames will be lowered to the
     bottom when no longer selected.

   Auto-raising and auto-lowering is implemented through functions
attached to `select-frame-hook' and `deselect-frame-hook' (*note Frame
Hooks::).  Under normal circumstances, you should not call these
functions directly.

 -- Function: default-select-frame-hook
     This hook function implements the `auto-raise-frame' variable; it
     is for use as the value of `select-frame-hook'.

 -- Function: default-deselect-frame-hook
     This hook function implements the `auto-lower-frame' variable; it
     is for use as the value of `deselect-frame-hook'.


File: lispref.info,  Node: Frame Configurations,  Next: Frame Hooks,  Prev: Raising and Lowering,  Up: Frames

39.11 Frame Configurations
==========================

A "frame configuration" records the current arrangement of frames, all
their properties, and the window configuration of each one.

 -- Function: current-frame-configuration
     This function returns a frame configuration list that describes
     the current arrangement of frames and their contents.

 -- Function: set-frame-configuration configuration &optional nodelete
     This function restores the state of frames described by
     CONFIGURATION, which should be the return value from a previous
     call to `current-frame-configuration'.

     Each frame listed in CONFIGURATION has its position, size, window
     configuration, and other properties set as specified in
     CONFIGURATION.

     Ordinarily, this function deletes all existing frames not listed in
     CONFIGURATION.  But if optional second argument NODELETE is
     non-`nil', the unwanted frames are iconified instead.


File: lispref.info,  Node: Frame Hooks,  Prev: Frame Configurations,  Up: Frames

39.12 Hooks for Customizing Frame Behavior
==========================================

XEmacs provides many hooks that are called at various times during a
frame's lifetime.  *Note Hooks::.

 -- Variable: create-frame-hook
     This hook is called each time a frame is created.  The functions
     are called with one argument, the newly-created frame.

 -- Variable: delete-frame-hook
     This hook is called each time a frame is deleted.  The functions
     are called with one argument, the about-to-be-deleted frame.

 -- Variable: select-frame-hook
     This is a normal hook that is run just after a frame is selected.
     The function `default-select-frame-hook', which implements
     auto-raising (*note Raising and Lowering::), is normally attached
     to this hook.

     Note that calling `select-frame' does not necessarily set the
     focus: The actual window-system focus will not be changed until
     the next time that XEmacs is waiting for an event, and even then,
     the window manager may refuse the focus-change request.

 -- Variable: deselect-frame-hook
     This is a normal hook that is run just before a frame is deselected
     (and another frame is selected).  The function
     `default-deselect-frame-hook', which implements auto-lowering
     (*note Raising and Lowering::), is normally attached to this hook.

 -- Variable: map-frame-hook
     This hook is called each time a frame is mapped (i.e. made
     visible).  The functions are called with one argument, the newly
     mapped frame.

 -- Variable: unmap-frame-hook
     This hook is called each time a frame is unmapped (i.e. made
     invisible or iconified).  The functions are called with one
     argument, the newly unmapped frame.


File: lispref.info,  Node: Consoles and Devices,  Next: Positions,  Prev: Frames,  Up: Top

40 Consoles and Devices
***********************

A "console" is an object representing a single input connection to
XEmacs, such as an X display or a TTY connection.  It is possible for
XEmacs to have frames on multiple consoles at once (even on
heterogeneous types--you can simultaneously have a frame on an X
display and a TTY connection).  Normally, there is only one console in
existence.

   A "device" is an object representing a single output device, such as
a particular screen on an X display. (Usually there is exactly one
device per X console connection, but there may be more than one if you
have a multi-headed X display.  For TTY connections, there is always
exactly one device per console.)

   Each device has one or more "frames" in which text can be displayed.
For X displays and the like, a frame corresponds to the normal
window-system concept of a window.  Frames can overlap, be displayed at
various locations within the display, be resized, etc.  For TTY, only
one frame can be displayed at a time, and it occupies the entire TTY
display area.

   However, you can still define multiple frames and switch between
them.  Their contents are entirely separate from each other.  These
sorts of frames resemble the "virtual console" capability provided
under Linux or the multiple screens provided by the multiplexing program
`screen' under Unix.

   When you start up XEmacs, an initial console and device are created
to receive input and display frames on.  This will either be an X
display or a TTY connection, depending on what mode you started XEmacs
in (this is determined by the `DISPLAY' environment variable, the
`-nw', `-t' and `-display' command-line options, etc.).

   You can connect to other X displays and TTY connections by creating
new console objects, and to other X screens on an existing display by
creating new device objects, as described below.  Many functions (for
example the frame-creation functions) take an optional device argument
specifying which device the function pertains to.  If the argument is
omitted, it defaults to the selected device (see below).

 -- Function: consolep object
     This returns non-`nil' if OBJECT is a console.

 -- Function: devicep object
     This returns non-`nil' if OBJECT is a device.

* Menu:

* Basic Console Functions::     Functions for working with consoles.
* Basic Device Functions::      Functions for working with devices.
* Console Types and Device Classes::
                                I/O and color characteristics.
* Connecting to a Console or Device::
* The Selected Console and Device::
* Console and Device I/O::      Controlling input and output.


File: lispref.info,  Node: Basic Console Functions,  Next: Basic Device Functions,  Up: Consoles and Devices

40.1 Basic Console Functions
============================

 -- Function: console-list
     This function returns a list of all existing consoles.

 -- Function: console-device-list &optional console
     This function returns a list of all devices on CONSOLE.  If
     CONSOLE is `nil', the selected console will be used.


File: lispref.info,  Node: Basic Device Functions,  Next: Console Types and Device Classes,  Prev: Basic Console Functions,  Up: Consoles and Devices

40.2 Basic Device Functions
===========================

 -- Function: device-list
     This function returns a list of all existing devices.

 -- Function: device-or-frame-p object
     This function returns non-`nil' if OBJECT is a device or frame.
     This function is useful because devices and frames are similar in
     many respects and many functions can operate on either one.

 -- Function: device-frame-list &optional device
     This function returns a list of all frames on DEVICE.  DEVICE
     defaults to the currently selected device.

 -- Function: frame-device &optional frame
     This function returns the device that FRAME is on.  FRAME defaults
     to the currently selected frame.


File: lispref.info,  Node: Console Types and Device Classes,  Next: Connecting to a Console or Device,  Prev: Basic Device Functions,  Up: Consoles and Devices

40.3 Console Types and Device Classes
=====================================

Every device is of a particular "type", which describes how the
connection to that device is made and how the device operates, and a
particular "class", which describes other characteristics of the device
(currently, the color capabilities of the device).

   The currently-defined device types are

`x'
     A connection to an X display (such as `willow:0').

`tty'
     A connection to a tty (such as `/dev/ttyp3').

`stream'
     A stdio connection.  This describes a device for which input and
     output is only possible in a stream-like fashion, such as when
     XEmacs in running in batch mode.  The very first device created by
     XEmacs is a terminal device and is used to print out messages of
     various sorts (for example, the help message when you use the
     `-help' command-line option).

   The currently-defined device classes are
`color'
     A color device.

`grayscale'
     A grayscale device (a device that can display multiple shades of
     gray, but no color).

`mono'
     A device that can only display two colors (e.g. black and white).

 -- Function: device-type &optional device
     This function returns the type of DEVICE.  This is a symbol whose
     name is one of the device types mentioned above.  DEVICE defaults
     to the selected device.

 -- Function: device-or-frame-type device-or-frame
     This function returns the type of DEVICE-OR-FRAME.

 -- Function: device-class &optional device
     This function returns the class (color behavior) of DEVICE.  This
     is a symbol whose name is one of the device classes mentioned
     above.

 -- Function: valid-device-type-p device-type
     This function returns whether DEVICE-TYPE (which should be a
     symbol) specifies a valid device type.

 -- Function: valid-device-class-p device-class
     This function returns whether DEVICE-CLASS (which should be a
     symbol) specifies a valid device class.

 -- Variable: terminal-device
     This variable holds the initial terminal device object, which
     represents XEmacs's stdout.


File: lispref.info,  Node: Connecting to a Console or Device,  Next: The Selected Console and Device,  Prev: Console Types and Device Classes,  Up: Consoles and Devices

40.4 Connecting to a Console or Device
======================================

 -- Function: make-device type connection &optional props
     This function creates a new device.

   The following two functions create devices of specific types and are
written in terms of `make-device'.

 -- Function: make-tty-device &optional tty terminal-type
     This function creates a new tty device on TTY.  This also creates
     the tty's first frame.  TTY should be a string giving the name of
     a tty device file (e.g. `/dev/ttyp3' under SunOS et al.), as
     returned by the `tty' command issued from the Unix shell.  A value
     of `nil' means use the stdin and stdout as passed to XEmacs from
     the shell.  If TERMINAL-TYPE is non-`nil', it should be a string
     specifying the type of the terminal attached to the specified tty.
     If it is `nil', the terminal type will be inferred from the
     `TERM' environment variable.

 -- Function: make-x-device &optional display argv-list
     This function creates a new device connected to DISPLAY.  Optional
     argument ARGV-LIST is a list of strings describing command line
     options.

 -- Function: delete-device device &optional force
     This function deletes DEVICE, permanently eliminating it from use.
     This disconnects XEmacs's connection to the device.

 -- Variable: create-device-hook
     This variable, if non-`nil', should contain a list of functions,
     which are called when a device is created.

 -- Variable: delete-device-hook
     This variable, if non-`nil', should contain a list of functions,
     which are called when a device is deleted.

 -- Function: console-live-p object
     This function returns non-`nil' if OBJECT is a console that has
     not been deleted.

 -- Function: device-live-p object
     This function returns non-`nil' if OBJECT is a device that has not
     been deleted.

 -- Function: device-x-display device
     This function returns the X display which DEVICE is connected to,
     if DEVICE is an X device.


File: lispref.info,  Node: The Selected Console and Device,  Next: Console and Device I/O,  Prev: Connecting to a Console or Device,  Up: Consoles and Devices

40.5 The Selected Console and Device
====================================

 -- Function: select-console console
     This function selects the console CONSOLE.  Subsequent editing
     commands apply to its selected device, selected frame, and selected
     window.  The selection of CONSOLE lasts until the next time the
     user does something to select a different console, or until the
     next time this function is called.

 -- Function: selected-console
     This function returns the console which is currently active.

 -- Function: select-device device
     This function selects the device DEVICE.

 -- Function: selected-device &optional console
     This function returns the device which is currently active.  If
     optional CONSOLE is non-`nil', this function returns the device
     that would be currently active if CONSOLE were the selected
     console.


File: lispref.info,  Node: Console and Device I/O,  Prev: The Selected Console and Device,  Up: Consoles and Devices

40.6 Console and Device I/O
===========================

 -- Function: console-disable-input console
     This function disables input on console CONSOLE.

 -- Function: console-enable-input console
     This function enables input on console CONSOLE.

   Each device has a "baud rate" value associated with it.  On most
systems, changing this value will affect the amount of padding and
other strategic decisions made during redisplay.

 -- Function: device-baud-rate &optional device
     This function returns the output baud rate of DEVICE.

 -- Function: set-device-baud-rate device rate
     This function sets the output baud rate of DEVICE to RATE.


File: lispref.info,  Node: Positions,  Next: Markers,  Prev: Consoles and Devices,  Up: Top

41 Positions
************

A "position" is the index of a character in the text of a buffer.  More
precisely, a position identifies the place between two characters (or
before the first character, or after the last character), so we can
speak of the character before or after a given position.  However, we
often speak of the character "at" a position, meaning the character
after that position.

   Positions are usually represented as integers starting from 1, but
can also be represented as "markers"--special objects that relocate
automatically when text is inserted or deleted so they stay with the
surrounding characters.  *Note Markers::.

* Menu:

* Point::         The special position where editing takes place.
* Motion::        Changing point.
* Excursions::    Temporary motion and buffer changes.
* Narrowing::     Restricting editing to a portion of the buffer.


File: lispref.info,  Node: Point,  Next: Motion,  Up: Positions

41.1 Point
==========

"Point" is a special buffer position used by many editing commands,
including the self-inserting typed characters and text insertion
functions.  Other commands move point through the text to allow editing
and insertion at different places.

   Like other positions, point designates a place between two characters
(or before the first character, or after the last character), rather
than a particular character.  Usually terminals display the cursor over
the character that immediately follows point; point is actually before
the character on which the cursor sits.

   The value of point is a number between 1 and the buffer size plus 1.
If narrowing is in effect (*note Narrowing::), then point is constrained
to fall within the accessible portion of the buffer (possibly at one end
of it).

   Each buffer has its own value of point, which is independent of the
value of point in other buffers.  Each window also has a value of point,
which is independent of the value of point in other windows on the same
buffer.  This is why point can have different values in various windows
that display the same buffer.  When a buffer appears in only one window,
the buffer's point and the window's point normally have the same value,
so the distinction is rarely important.  *Note Window Point::, for more
details.

 -- Function: point &optional buffer
     This function returns the value of point in BUFFER, as an integer.
     BUFFER defaults to the current buffer if omitted.

          (point)
               => 175

 -- Function: point-min &optional buffer
     This function returns the minimum accessible value of point in
     BUFFER.  This is normally 1, but if narrowing is in effect, it is
     the position of the start of the region that you narrowed to.
     (*Note Narrowing::.) BUFFER defaults to the current buffer if
     omitted.

 -- Function: point-max &optional buffer
     This function returns the maximum accessible value of point in
     BUFFER.  This is `(1+ (buffer-size buffer))', unless narrowing is
     in effect, in which case it is the position of the end of the
     region that you narrowed to. (*note Narrowing::).  BUFFER defaults
     to the current buffer if omitted.

 -- Function: buffer-end flag &optional buffer
     This function returns `(point-min buffer)' if FLAG is less than 1,
     `(point-max buffer)' otherwise.  The argument FLAG must be a
     number.  BUFFER defaults to the current buffer if omitted.

 -- Function: buffer-size &optional buffer
     This function returns the total number of characters in BUFFER.
     In the absence of any narrowing (*note Narrowing::), `point-max'
     returns a value one larger than this.  BUFFER defaults to the
     current buffer if omitted.

          (buffer-size)
               => 35
          (point-max)
               => 36

 -- Variable: buffer-saved-size
     The value of this buffer-local variable is the former length of the
     current buffer, as of the last time it was read in, saved or
     auto-saved.


File: lispref.info,  Node: Motion,  Next: Excursions,  Prev: Point,  Up: Positions

41.2 Motion
===========

Motion functions change the value of point, either relative to the
current value of point, relative to the beginning or end of the buffer,
or relative to the edges of the selected window.  *Note Point::.

* Menu:

* Character Motion::       Moving in terms of characters.
* Word Motion::            Moving in terms of words.
* Buffer End Motion::      Moving to the beginning or end of the buffer.
* Text Lines::             Moving in terms of lines of text.
* Screen Lines::           Moving in terms of lines as displayed.
* List Motion::            Moving by parsing lists and sexps.
* Skipping Characters::    Skipping characters belonging to a certain set.


File: lispref.info,  Node: Character Motion,  Next: Word Motion,  Up: Motion

41.2.1 Motion by Characters
---------------------------

These functions move point based on a count of characters.  `goto-char'
is the fundamental primitive; the other functions use that.

 -- Command: goto-char position &optional buffer
     This function sets point in `buffer' to the value POSITION.  If
     POSITION is less than 1, it moves point to the beginning of the
     buffer.  If POSITION is greater than the length of the buffer, it
     moves point to the end.  BUFFER defaults to the current buffer if
     omitted.

     If narrowing is in effect, POSITION still counts from the
     beginning of the buffer, but point cannot go outside the accessible
     portion.  If POSITION is out of range, `goto-char' moves point to
     the beginning or the end of the accessible portion.

     When this function is called interactively, POSITION is the
     numeric prefix argument, if provided; otherwise it is read from the
     minibuffer.

     `goto-char' returns POSITION.

 -- Command: forward-char &optional count buffer
     This function moves point COUNT characters forward, towards the
     end of the buffer (or backward, towards the beginning of the
     buffer, if COUNT is negative).  If the function attempts to move
     point past the beginning or end of the buffer (or the limits of
     the accessible portion, when narrowing is in effect), an error is
     signaled with error code `beginning-of-buffer' or `end-of-buffer'.
     BUFFER defaults to the current buffer if omitted.

     In an interactive call, COUNT is the numeric prefix argument.

 -- Command: backward-char &optional count buffer
     This function moves point COUNT characters backward, towards the
     beginning of the buffer (or forward, towards the end of the
     buffer, if COUNT is negative).  If the function attempts to move
     point past the beginning or end of the buffer (or the limits of
     the accessible portion, when narrowing is in effect), an error is
     signaled with error code `beginning-of-buffer' or `end-of-buffer'.
     BUFFER defaults to the current buffer if omitted.

     In an interactive call, COUNT is the numeric prefix argument.


File: lispref.info,  Node: Word Motion,  Next: Buffer End Motion,  Prev: Character Motion,  Up: Motion

41.2.2 Motion by Words
----------------------

These functions for parsing words use the syntax table to decide
whether a given character is part of a word.  *Note Syntax Tables::.

 -- Command: forward-word &optional count buffer
     This function moves point forward COUNT words (or backward if
     COUNT is negative).  Normally it returns `t'.  If this motion
     encounters the beginning or end of the buffer, or the limits of the
     accessible portion when narrowing is in effect, point stops there
     and the value is `nil'.

     COUNT defaults to `1' and BUFFER defaults to the current buffer.

     In an interactive call, COUNT is set to the numeric prefix
     argument.

 -- Command: backward-word &optional count buffer
     This function is just like `forward-word', except that it moves
     backward until encountering the front of a word, rather than
     forward.  BUFFER defaults to the current buffer if omitted.

     In an interactive call, COUNT is set to the numeric prefix
     argument.

 -- Variable: words-include-escapes
     This variable affects the behavior of `forward-word' and everything
     that uses it.  If it is non-`nil', then characters in the "escape"
     and "character quote" syntax classes count as part of words.
     Otherwise, they do not.


File: lispref.info,  Node: Buffer End Motion,  Next: Text Lines,  Prev: Word Motion,  Up: Motion

41.2.3 Motion to an End of the Buffer
-------------------------------------

To move point to the beginning of the buffer, write:

     (goto-char (point-min))

Likewise, to move to the end of the buffer, use:

     (goto-char (point-max))

   Here are two commands that users use to do these things.  They are
documented here to warn you not to use them in Lisp programs, because
they set the mark and display messages in the echo area.

 -- Command: beginning-of-buffer &optional count
     This function moves point to the beginning of the buffer (or the
     limits of the accessible portion, when narrowing is in effect),
     setting the mark at the previous position.  If COUNT is non-`nil',
     then it puts point COUNT tenths of the way from the beginning of
     the buffer.

     In an interactive call, COUNT is the numeric prefix argument, if
     provided; otherwise COUNT defaults to `nil'.

     Don't use this function in Lisp programs!

 -- Command: end-of-buffer &optional count
     This function moves point to the end of the buffer (or the limits
     of the accessible portion, when narrowing is in effect), setting
     the mark at the previous position.  If COUNT is non-`nil', then it
     puts point COUNT tenths of the way from the end of the buffer.

     In an interactive call, COUNT is the numeric prefix argument, if
     provided; otherwise COUNT defaults to `nil'.

     Don't use this function in Lisp programs!


File: lispref.info,  Node: Text Lines,  Next: Screen Lines,  Prev: Buffer End Motion,  Up: Motion

41.2.4 Motion by Text Lines
---------------------------

Text lines are portions of the buffer delimited by newline characters,
which are regarded as part of the previous line.  The first text line
begins at the beginning of the buffer, and the last text line ends at
the end of the buffer whether or not the last character is a newline.
The division of the buffer into text lines is not affected by the width
of the window, by line continuation in display, or by how tabs and
control characters are displayed.

 -- Command: goto-line line
     This function moves point to the front of the LINEth line,
     counting from line 1 at beginning of the buffer.  If LINE is less
     than 1, it moves point to the beginning of the buffer.  If LINE is
     greater than the number of lines in the buffer, it moves point to
     the end of the buffer--that is, the _end of the last line_ of the
     buffer.  This is the only case in which `goto-line' does not
     necessarily move to the beginning of a line.

     If narrowing is in effect, then LINE still counts from the
     beginning of the buffer, but point cannot go outside the accessible
     portion.  So `goto-line' moves point to the beginning or end of the
     accessible portion, if the line number specifies an inaccessible
     position.

     The return value of `goto-line' is the difference between LINE and
     the line number of the line to which point actually was able to
     move (in the full buffer, before taking account of narrowing).
     Thus, the value is positive if the scan encounters the real end of
     the buffer.  The value is zero if scan encounters the end of the
     accessible portion but not the real end of the buffer.

     In an interactive call, LINE is the numeric prefix argument if one
     has been provided.  Otherwise LINE is read in the minibuffer.

 -- Command: beginning-of-line &optional count buffer
     This function moves point to the beginning of the current line.
     With an argument COUNT not `nil' or 1, it moves forward COUNT-1
     lines and then to the beginning of the line.  BUFFER defaults to
     the current buffer if omitted.

     If this function reaches the end of the buffer (or of the
     accessible portion, if narrowing is in effect), it positions point
     there.  No error is signaled.

 -- Command: end-of-line &optional count buffer
     This function moves point to the end of the current line.  With an
     argument COUNT not `nil' or 1, it moves forward COUNT-1 lines and
     then to the end of the line.  BUFFER defaults to the current
     buffer if omitted.

     If this function reaches the end of the buffer (or of the
     accessible portion, if narrowing is in effect), it positions point
     there.  No error is signaled.

 -- Command: forward-line &optional count buffer
     This function moves point forward COUNT lines, to the beginning of
     the line.  If COUNT is negative, it moves point -COUNT lines
     backward, to the beginning of a line.  If COUNT is zero, it moves
     point to the beginning of the current line.  BUFFER defaults to
     the current buffer if omitted.

     If `forward-line' encounters the beginning or end of the buffer (or
     of the accessible portion) before finding that many lines, it sets
     point there.  No error is signaled.

     `forward-line' returns the difference between COUNT and the number
     of lines actually moved.  If you attempt to move down five lines
     from the beginning of a buffer that has only three lines, point
     stops at the end of the last line, and the value will be 2.

     In an interactive call, COUNT is the numeric prefix argument.

 -- Function: count-lines start end &optional
          ignore-invisible-lines-flag
     This function returns the number of lines between the positions
     START and END in the current buffer.  If START and END are equal,
     then it returns 0.  Otherwise it returns at least 1, even if START
     and END are on the same line.  This is because the text between
     them, considered in isolation, must contain at least one line
     unless it is empty.

     With optional IGNORE-INVISIBLE-LINES-FLAG non-`nil', lines
     collapsed with selective-display are excluded from the line count.

     *N.B.* The expression to return the current line number is not
     obvious:

          (1+ (count-lines 1 (point-at-bol)))

     Here is an example of using `count-lines':

          (defun current-line ()
            "Return the vertical position of point..."
            (+ (count-lines (window-start) (point))
               (if (= (current-column) 0) 1 0)
               -1))

   Also see the functions `bolp' and `eolp' in *Note Near Point::.
These functions do not move point, but test whether it is already at the
beginning or end of a line.


File: lispref.info,  Node: Screen Lines,  Next: List Motion,  Prev: Text Lines,  Up: Motion

41.2.5 Motion by Screen Lines
-----------------------------

The line functions in the previous section count text lines, delimited
only by newline characters.  By contrast, these functions count screen
lines, which are defined by the way the text appears on the screen.  A
text line is a single screen line if it is short enough to fit the width
of the selected window, but otherwise it may occupy several screen
lines.

   In some cases, text lines are truncated on the screen rather than
continued onto additional screen lines.  In these cases,
`vertical-motion' moves point much like `forward-line'.  *Note
Truncation::.

   Because the width of a given string depends on the flags that control
the appearance of certain characters, `vertical-motion' behaves
differently, for a given piece of text, depending on the buffer it is
in, and even on the selected window (because the width, the truncation
flag, and display table may vary between windows).  *Note Usual
Display::.

   These functions scan text to determine where screen lines break, and
thus take time proportional to the distance scanned.  If you intend to
use them heavily, Emacs provides caches which may improve the
performance of your code.  *Note cache-long-line-scans: Text Lines.

 -- Function: vertical-motion count &optional window pixels
     This function moves point to the start of the frame line COUNT
     frame lines down from the frame line containing point.  If COUNT
     is negative, it moves up instead.  The optional second argument
     WINDOW may be used to specify a window other than the selected
     window in which to perform the motion.

     Normally, `vertical-motion' returns the number of lines moved.  The
     value may be less in absolute value than COUNT if the beginning or
     end of the buffer was reached.  If the optional third argument,
     PIXELS is non-`nil', the vertical pixel height of the motion which
     took place is returned instead of the actual number of lines
     moved.  A motion of zero lines returns the height of the current
     line.

     Note that `vertical-motion' sets WINDOW's buffer's point, not
     WINDOW's point. (This differs from FSF Emacs, which buggily always
     sets current buffer's point, regardless of WINDOW.)

 -- Function: vertical-motion-pixels count &optional window how
     This function moves point to the start of the frame line PIXELS
     vertical pixels down from the frame line containing point, or up if
     PIXELS is negative.  The optional second argument WINDOW is the
     window to move in, and defaults to the selected window.  The
     optional third argument HOW specifies the stopping condition.  A
     negative integer indicates that the motion should be no more than
     PIXELS.  A positive value indicates that the motion should be at
     least PIXELS.  Any other value indicates that the motion should be
     as close as possible to PIXELS.

 -- Command: move-to-window-line count &optional window
     This function moves point with respect to the text currently
     displayed in WINDOW, which defaults to the selected window.  It
     moves point to the beginning of the screen line COUNT screen lines
     from the top of the window.  If COUNT is negative, that specifies a
     position -COUNT lines from the bottom (or the last line of the
     buffer, if the buffer ends above the specified screen position).

     If COUNT is `nil', then point moves to the beginning of the line
     in the middle of the window.  If the absolute value of COUNT is
     greater than the size of the window, then point moves to the place
     that would appear on that screen line if the window were tall
     enough.  This will probably cause the next redisplay to scroll to
     bring that location onto the screen.

     In an interactive call, COUNT is the numeric prefix argument.

     The value returned is the window line number point has moved to,
     with the top line in the window numbered 0.


File: lispref.info,  Node: List Motion,  Next: Skipping Characters,  Prev: Screen Lines,  Up: Motion

41.2.6 Moving over Balanced Expressions
---------------------------------------

Here are several functions concerned with balanced-parenthesis
expressions (also called "sexps" in connection with moving across them
in XEmacs).  The syntax table controls how these functions interpret
various characters; see *Note Syntax Tables::.  *Note Parsing
Expressions::, for lower-level primitives for scanning sexps or parts of
sexps.  For user-level commands, see *Note Lists and Sexps:
(xemacs)Lists and Sexps.

 -- Command: forward-list &optional arg
     This function moves forward across ARG balanced groups of
     parentheses. (Other syntactic entities such as words or paired
     string quotes are ignored.) ARG defaults to 1 if omitted.  If ARG
     is negative, move backward across that many groups of parentheses.

 -- Command: backward-list &optional count
     This function moves backward across COUNT balanced groups of
     parentheses. (Other syntactic entities such as words or paired
     string quotes are ignored.) COUNT defaults to 1 if omitted.  If
     COUNT is negative, move forward across that many groups of
     parentheses.

 -- Command: up-list &optional count
     This function moves forward out of COUNT levels of parentheses.  A
     negative argument means move backward but still to a less deep
     spot.

 -- Command: down-list &optional count
     This function moves forward into COUNT levels of parentheses.  A
     negative argument means move backward but still go deeper in
     parentheses (-COUNT levels).

 -- Command: forward-sexp &optional count
     This function moves forward across COUNT balanced expressions.
     Balanced expressions include both those delimited by parentheses
     and other kinds, such as words and string constants.  COUNT
     defaults to 1 if omitted.  If COUNT is negative, move backward
     across that many balanced expressions.  For example,

          ---------- Buffer: foo ----------
          (concat-!- "foo " (car x) y z)
          ---------- Buffer: foo ----------

          (forward-sexp 3)
               => nil

          ---------- Buffer: foo ----------
          (concat "foo " (car x) y-!- z)
          ---------- Buffer: foo ----------

 -- Command: backward-sexp &optional count
     This function moves backward across COUNT balanced expressions.
     COUNT defaults to 1 if omitted.  If COUNT is negative, move
     forward across that many balanced expressions.

 -- Command: beginning-of-defun &optional count
     This function moves back to the COUNTth beginning of a defun.  If
     COUNT is negative, this actually moves forward, but it still moves
     to the beginning of a defun, not to the end of one.  COUNT
     defaults to 1 if omitted.

 -- Command: end-of-defun &optional count
     This function moves forward to the COUNTth end of a defun.  If
     COUNT is negative, this actually moves backward, but it still
     moves to the end of a defun, not to the beginning of one.  COUNT
     defaults to 1 if omitted.

 -- User Option: defun-prompt-regexp
     If non-`nil', this variable holds a regular expression that
     specifies what text can appear before the open-parenthesis that
     starts a defun.  That is to say, a defun begins on a line that
     starts with a match for this regular expression, followed by a
     character with open-parenthesis syntax.


File: lispref.info,  Node: Skipping Characters,  Prev: List Motion,  Up: Motion

41.2.7 Skipping Characters
--------------------------

The following two functions move point over a specified set of
characters.  For example, they are often used to skip whitespace.  For
related functions, see *Note Motion and Syntax::.

 -- Function: skip-chars-forward character-set &optional limit buffer
     This function moves point in BUFFER forward, skipping over a given
     set of characters.  It examines the character following point,
     then advances point if the character matches CHARACTER-SET.  This
     continues until it reaches a character that does not match.  The
     function returns `nil'.  BUFFER defaults to the current buffer if
     omitted.

     The argument CHARACTER-SET is like the inside of a `[...]' in a
     regular expression except that `]' is never special and `\' quotes
     `^', `-' or `\'.  Thus, `"a-zA-Z"' skips over all letters,
     stopping before the first non-letter, and `"^a-zA-Z'" skips
     non-letters stopping before the first letter.  *Note Regular
     Expressions::.

     If LIMIT is supplied (it must be a number or a marker), it
     specifies the maximum position in the buffer that point can be
     skipped to.  Point will stop at or before LIMIT.

     In the following example, point is initially located directly
     before the `T'.  After the form is evaluated, point is located at
     the end of that line (between the `t' of `hat' and the newline).
     The function skips all letters and spaces, but not newlines.

          ---------- Buffer: foo ----------
          I read "-!-The cat in the hat
          comes back" twice.
          ---------- Buffer: foo ----------

          (skip-chars-forward "a-zA-Z ")
               => nil

          ---------- Buffer: foo ----------
          I read "The cat in the hat-!-
          comes back" twice.
          ---------- Buffer: foo ----------

 -- Function: skip-chars-backward character-set &optional limit buffer
     This function moves point backward, skipping characters that match
     CHARACTER-SET, until LIMIT.  It just like `skip-chars-forward'
     except for the direction of motion.


File: lispref.info,  Node: Excursions,  Next: Narrowing,  Prev: Motion,  Up: Positions

41.3 Excursions
===============

It is often useful to move point "temporarily" within a localized
portion of the program, or to switch buffers temporarily.  This is
called an "excursion", and it is done with the `save-excursion' special
form.  This construct saves the current buffer and its values of point
and the mark so they can be restored after the completion of the
excursion.

   The forms for saving and restoring the configuration of windows are
described elsewhere (see *Note Window Configurations:: and *note Frame
Configurations::).

 -- Special Form: save-excursion forms...
     The `save-excursion' special form saves the identity of the current
     buffer and the values of point and the mark in it, evaluates
     FORMS, and finally restores the buffer and its saved values of
     point and the mark.  All three saved values are restored even in
     case of an abnormal exit via `throw' or error (*note Nonlocal
     Exits::).

     The `save-excursion' special form is the standard way to switch
     buffers or move point within one part of a program and avoid
     affecting the rest of the program.  It is used more than 500 times
     in the Lisp sources of XEmacs.

     `save-excursion' does not save the values of point and the mark for
     other buffers, so changes in other buffers remain in effect after
     `save-excursion' exits.

     Likewise, `save-excursion' does not restore window-buffer
     correspondences altered by functions such as `switch-to-buffer'.
     One way to restore these correspondences, and the selected window,
     is to use `save-window-excursion' inside `save-excursion' (*note
     Window Configurations::).

     The value returned by `save-excursion' is the result of the last of
     FORMS, or `nil' if no FORMS are given.

          (save-excursion
            FORMS)
          ==
          (let ((old-buf (current-buffer))
                (old-pnt (point-marker))
                (old-mark (copy-marker (mark-marker))))
            (unwind-protect
                (progn FORMS)
              (set-buffer old-buf)
              (goto-char old-pnt)
              (set-marker (mark-marker) old-mark)))

 -- Special Form: save-current-buffer forms...
     This special form is similar to `save-excursion' but it only saves
     and restores the current buffer.  Beginning with XEmacs 20.3,
     `save-current-buffer' is a primitive.

 -- Special Form: with-current-buffer buffer forms...
     This special form evaluates FORMS with BUFFER as the current
     buffer.  It returns the value of the last form.

 -- Special Form: with-temp-file filename forms...
     This special form creates a new buffer, evaluates FORMS there, and
     writes the buffer to FILENAME.  It returns the value of the last
     form evaluated.

 -- Special Form: save-selected-window forms...
     This special form is similar to `save-excursion' but it saves and
     restores the selected window and nothing else.


File: lispref.info,  Node: Narrowing,  Prev: Excursions,  Up: Positions

41.4 Narrowing
==============

"Narrowing" means limiting the text addressable by XEmacs editing
commands to a limited range of characters in a buffer.  The text that
remains addressable is called the "accessible portion" of the buffer.

   Narrowing is specified with two buffer positions which become the
beginning and end of the accessible portion.  For most editing commands
and most Emacs primitives, these positions replace the values of the
beginning and end of the buffer.  While narrowing is in effect, no text
outside the accessible portion is displayed, and point cannot move
outside the accessible portion.

   Values such as positions or line numbers, which usually count from
the beginning of the buffer, do so despite narrowing, but the functions
which use them refuse to operate on text that is inaccessible.

   The commands for saving buffers are unaffected by narrowing; they
save the entire buffer regardless of any narrowing.

 -- Command: narrow-to-region start end &optional buffer
     This function sets the accessible portion of BUFFER to start at
     START and end at END.  Both arguments should be character
     positions.  BUFFER defaults to the current buffer if omitted.

     In an interactive call, START and END are set to the bounds of the
     current region (point and the mark, with the smallest first).

 -- Command: narrow-to-page &optional move-count
     This function sets the accessible portion of the current buffer to
     include just the current page.  An optional first argument
     MOVE-COUNT non-`nil' means to move forward or backward by
     MOVE-COUNT pages and then narrow.  The variable `page-delimiter'
     specifies where pages start and end (*note Standard Regexps::).

     In an interactive call, MOVE-COUNT is set to the numeric prefix
     argument.

 -- Command: widen &optional buffer
     This function cancels any narrowing in BUFFER, so that the entire
     contents are accessible.  This is called "widening".  It is
     equivalent to the following expression:

          (narrow-to-region 1 (1+ (buffer-size)))

     BUFFER defaults to the current buffer if omitted.

 -- Special Form: save-restriction body...
     This special form saves the current bounds of the accessible
     portion, evaluates the BODY forms, and finally restores the saved
     bounds, thus restoring the same state of narrowing (or absence
     thereof) formerly in effect.  The state of narrowing is restored
     even in the event of an abnormal exit via `throw' or error (*note
     Nonlocal Exits::).  Therefore, this construct is a clean way to
     narrow a buffer temporarily.

     The value returned by `save-restriction' is that returned by the
     last form in BODY, or `nil' if no body forms were given.

     *Caution:* it is easy to make a mistake when using the
     `save-restriction' construct.  Read the entire description here
     before you try it.

     If BODY changes the current buffer, `save-restriction' still
     restores the restrictions on the original buffer (the buffer whose
     restrictions it saved from), but it does not restore the identity
     of the current buffer.

     `save-restriction' does _not_ restore point and the mark; use
     `save-excursion' for that.  If you use both `save-restriction' and
     `save-excursion' together, `save-excursion' should come first (on
     the outside).  Otherwise, the old point value would be restored
     with temporary narrowing still in effect.  If the old point value
     were outside the limits of the temporary narrowing, this would
     fail to restore it accurately.

     The `save-restriction' special form records the values of the
     beginning and end of the accessible portion as distances from the
     beginning and end of the buffer.  In other words, it records the
     amount of inaccessible text before and after the accessible
     portion.

     This method yields correct results if BODY does further narrowing.
     However, `save-restriction' can become confused if the body widens
     and then make changes outside the range of the saved narrowing.
     When this is what you want to do, `save-restriction' is not the
     right tool for the job.  Here is what you must use instead:

          (let ((start (point-min-marker))
                (end (point-max-marker)))
            (unwind-protect
                (progn BODY)
              (save-excursion
                (set-buffer (marker-buffer start))
                (narrow-to-region start end))))

     Here is a simple example of correct use of `save-restriction':

          ---------- Buffer: foo ----------
          This is the contents of foo
          This is the contents of foo
          This is the contents of foo-!-
          ---------- Buffer: foo ----------

          (save-excursion
            (save-restriction
              (goto-char 1)
              (forward-line 2)
              (narrow-to-region 1 (point))
              (goto-char (point-min))
              (replace-string "foo" "bar")))

          ---------- Buffer: foo ----------
          This is the contents of bar
          This is the contents of bar
          This is the contents of foo-!-
          ---------- Buffer: foo ----------


File: lispref.info,  Node: Markers,  Next: Text,  Prev: Positions,  Up: Top

42 Markers
**********

A "marker" is a Lisp object used to specify a position in a buffer
relative to the surrounding text.  A marker changes its offset from the
beginning of the buffer automatically whenever text is inserted or
deleted, so that it stays with the two characters on either side of it.

* Menu:

* Overview of Markers::      The components of a marker, and how it relocates.
* Predicates on Markers::    Testing whether an object is a marker.
* Creating Markers::         Making empty markers or markers at certain places.
* Information from Markers:: Finding the marker's buffer or character position.
* Changing Markers::         Moving the marker to a new buffer or position.
* The Mark::                 How ``the mark'' is implemented with a marker.
* The Region::               How to access ``the region''.


File: lispref.info,  Node: Overview of Markers,  Next: Predicates on Markers,  Up: Markers

42.1 Overview of Markers
========================

A marker specifies a buffer and a position in that buffer.  The marker
can be used to represent a position in the functions that require one,
just as an integer could be used.  *Note Positions::, for a complete
description of positions.

   A marker has two attributes: the marker position, and the marker
buffer.  The marker position is an integer that is equivalent (at a
given time) to the marker as a position in that buffer.  But the
marker's position value can change often during the life of the marker.
Insertion and deletion of text in the buffer relocate the marker.  The
idea is that a marker positioned between two characters remains between
those two characters despite insertion and deletion elsewhere in the
buffer.  Relocation changes the integer equivalent of the marker.

   Deleting text around a marker's position leaves the marker between
the characters immediately before and after the deleted text.  Inserting
text at the position of a marker normally leaves the marker in front of
the new text--unless it is inserted with `insert-before-markers' (*note
Insertion::).

   Insertion and deletion in a buffer must check all the markers and
relocate them if necessary.  This slows processing in a buffer with a
large number of markers.  For this reason, it is a good idea to make a
marker point nowhere if you are sure you don't need it any more.
Unreferenced markers are garbage collected eventually, but until then
will continue to use time if they do point somewhere.

   Because it is common to perform arithmetic operations on a marker
position, most of the arithmetic operations (including `+' and `-')
accept markers as arguments.  In such cases, the marker stands for its
current position.

   Note that you can use extents to achieve the same functionality, and
more, as markers. (Markers were defined before extents, which is why
they both continue to exist.) A zero-length extent with the
`detachable' property removed is almost identical to a marker.  (*Note
Extent Endpoints::, for more information on zero-length extents.)

   In particular:

   * In order to get marker-like behavior in a zero-length extent, the
     `detachable' property must be removed (otherwise, the extent will
     disappear when text near it is deleted) and exactly one endpoint
     must be closed (if both endpoints are closed, the extent will
     expand to contain text inserted where it is located).

   * If a zero-length extent has the `end-open' property but not the
     `start-open' property (this is the default), text inserted at the
     extent's location causes the extent to move forward, just like a
     marker.

   * If a zero-length extent has the `start-open' property but not the
     `end-open' property, text inserted at the extent's location causes
     the extent to remain before the text, like what happens to markers
     when `insert-before-markers' is used.

   * Markers end up after or before inserted text depending on whether
     `insert' or `insert-before-markers' was called.  These functions
     do not affect zero-length extents differently; instead, the
     presence or absence of the `start-open' and `end-open' extent
     properties determines this, as just described.

   * Markers are automatically removed from a buffer when they are no
     longer in use.  Extents remain around until explicitly removed
     from a buffer.

   * Many functions are provided for listing the extents in a buffer or
     in a region of a buffer.  No such functions exist for markers.

   Here are examples of creating markers, setting markers, and moving
point to markers:

     ;; Make a new marker that initially does not point anywhere:
     (setq m1 (make-marker))
          => #<marker in no buffer>

     ;; Set `m1' to point between the 99th and 100th characters
     ;;   in the current buffer:
     (set-marker m1 100)
          => #<marker at 100 in markers.texi>

     ;; Now insert one character at the beginning of the buffer:
     (goto-char (point-min))
          => 1
     (insert "Q")
          => nil

     ;; `m1' is updated appropriately.
     m1
          => #<marker at 101 in markers.texi>

     ;; Two markers that point to the same position
     ;;   are not `eq', but they are `equal'.
     (setq m2 (copy-marker m1))
          => #<marker at 101 in markers.texi>
     (eq m1 m2)
          => nil
     (equal m1 m2)
          => t

     ;; When you are finished using a marker, make it point nowhere.
     (set-marker m1 nil)
          => #<marker in no buffer>


File: lispref.info,  Node: Predicates on Markers,  Next: Creating Markers,  Prev: Overview of Markers,  Up: Markers

42.2 Predicates on Markers
==========================

You can test an object to see whether it is a marker, or whether it is
either an integer or a marker or either an integer, a character, or a
marker.  The latter tests are useful in connection with the arithmetic
functions that work with any of markers, integers, or characters.

 -- Function: markerp object
     This function returns `t' if OBJECT is a marker, `nil' otherwise.
     Note that integers are not markers, even though many functions
     will accept either a marker or an integer.

 -- Function: integer-or-marker-p object
     This function returns `t' if OBJECT is an integer or a marker,
     `nil' otherwise.

 -- Function: integer-char-or-marker-p object
     This function returns `t' if OBJECT is an integer, a character, or
     a marker, `nil' otherwise.

 -- Function: number-or-marker-p object
     This function returns `t' if OBJECT is a number (either kind) or a
     marker, `nil' otherwise.

 -- Function: number-char-or-marker-p object
     This function returns `t' if OBJECT is a number (either kind), a
     character, or a marker, `nil' otherwise.


File: lispref.info,  Node: Creating Markers,  Next: Information from Markers,  Prev: Predicates on Markers,  Up: Markers

42.3 Functions That Create Markers
==================================

When you create a new marker, you can make it point nowhere, or point
to the present position of point, or to the beginning or end of the
accessible portion of the buffer, or to the same place as another given
marker.

 -- Function: make-marker
     This functions returns a newly created marker that does not point
     anywhere.

          (make-marker)
               => #<marker in no buffer>

 -- Function: point-marker &optional dont-copy-p buffer
     This function returns a marker that points to the present position
     of point in BUFFER, which defaults to the current buffer.  *Note
     Point::.  For an example, see `copy-marker', below.

     Internally, a marker corresponding to point is always maintained.
     Normally the marker returned by `point-marker' is a copy; you may
     modify it with reckless abandon.  However, if optional argument
     DONT-COPY-P is non-`nil', then the real point-marker is returned;
     modifying the position of this marker will move point.  It is
     illegal to change the buffer of it, or make it point nowhere.

 -- Function: point-min-marker &optional buffer
     This function returns a new marker that points to the beginning of
     the accessible portion of BUFFER, which defaults to the current
     buffer.  This will be the beginning of the buffer unless narrowing
     is in effect.  *Note Narrowing::.

 -- Function: point-max-marker &optional buffer
     This function returns a new marker that points to the end of the
     accessible portion of BUFFER, which defaults to the current
     buffer.  This will be the end of the buffer unless narrowing is in
     effect.  *Note Narrowing::.

     Here are examples of this function and `point-min-marker', shown in
     a buffer containing a version of the source file for the text of
     this chapter.

          (point-min-marker)
               => #<marker at 1 in markers.texi>
          (point-max-marker)
               => #<marker at 15573 in markers.texi>

          (narrow-to-region 100 200)
               => nil
          (point-min-marker)
               => #<marker at 100 in markers.texi>
          (point-max-marker)
               => #<marker at 200 in markers.texi>

 -- Function: copy-marker marker-or-integer &optional marker-type
     If passed a marker as its argument, `copy-marker' returns a new
     marker that points to the same place and the same buffer as does
     MARKER-OR-INTEGER.  If passed an integer as its argument,
     `copy-marker' returns a new marker that points to position
     MARKER-OR-INTEGER in the current buffer.

     If passed an integer argument less than 1, `copy-marker' returns a
     new marker that points to the beginning of the current buffer.  If
     passed an integer argument greater than the length of the buffer,
     `copy-marker' returns a new marker that points to the end of the
     buffer.

     An error is signaled if MARKER-OR-INTEGER is neither a marker nor
     an integer.

     Optional second argument MARKER-TYPE specifies the insertion type
     of the new marker; see `marker-insertion-type'.

          (setq p (point-marker))
               => #<marker at 2139 in markers.texi>

          (setq q (copy-marker p))
               => #<marker at 2139 in markers.texi>

          (eq p q)
               => nil

          (equal p q)
               => t

          (point)
               => 2139

          (set-marker p 3000)
               => #<marker at 3000 in markers.texi>

          (point)
               => 2139

          (setq p (point-marker t))
               => #<marker at 2139 in markers.texi>

          (set-marker p 3000)
               => #<marker at 3000 in markers.texi>

          (point)
               => 3000

          (copy-marker 0)
               => #<marker at 1 in markers.texi>

          (copy-marker 20000)
               => #<marker at 7572 in markers.texi>


File: lispref.info,  Node: Information from Markers,  Next: Changing Markers,  Prev: Creating Markers,  Up: Markers

42.4 Information from Markers
=============================

This section describes the functions for accessing the components of a
marker object.

 -- Function: marker-position marker
     This function returns the position that MARKER points to, or `nil'
     if it points nowhere.

 -- Function: marker-buffer marker
     This function returns the buffer that MARKER points into, or `nil'
     if it points nowhere.

          (setq m (make-marker))
               => #<marker in no buffer>
          (marker-position m)
               => nil
          (marker-buffer m)
               => nil

          (set-marker m 3770 (current-buffer))
               => #<marker at 3770 in markers.texi>
          (marker-buffer m)
               => #<buffer markers.texi>
          (marker-position m)
               => 3770

   Two distinct markers are considered `equal' (even though not `eq')
to each other if they have the same position and buffer, or if they
both point nowhere.


File: lispref.info,  Node: Changing Markers,  Next: The Mark,  Prev: Information from Markers,  Up: Markers

42.5 Changing Marker Positions
==============================

This section describes how to change the position of an existing
marker.  When you do this, be sure you know whether the marker is used
outside of your program, and, if so, what effects will result from
moving it--otherwise, confusing things may happen in other parts of
Emacs.

 -- Function: set-marker marker position &optional buffer
     This function moves MARKER to POSITION in BUFFER.  If BUFFER is
     not provided, it defaults to the current buffer.

     POSITION can be a marker, an integer or `nil'.  If POSITION is an
     integer, `set-marker' moves MARKER to point before the POSITIONth
     character in BUFFER.  If POSITION is `nil', MARKER is made to
     point nowhere.  Then it no longer slows down editing in any
     buffer.  If POSITION is less than 1, MARKER is moved to the
     beginning of BUFFER.  If POSITION is greater than the size of
     BUFFER, MARKER is moved to the end of BUFFER.

     The value returned is MARKER.

          (setq m (point-marker))
               => #<marker at 4714 in markers.texi>
          (set-marker m 55)
               => #<marker at 55 in markers.texi>
          (setq b (get-buffer "foo"))
               => #<buffer foo>
          (set-marker m 0 b)
               => #<marker at 1 in foo>

 -- Function: move-marker marker position &optional buffer
     This is another name for `set-marker'.


File: lispref.info,  Node: The Mark,  Next: The Region,  Prev: Changing Markers,  Up: Markers

42.6 The Mark
=============

One special marker in each buffer is designated "the mark".  It records
a position for the user for the sake of commands such as `C-w' and `C-x
<TAB>'.  Lisp programs should set the mark only to values that have a
potential use to the user, and never for their own internal purposes.
For example, the `replace-regexp' command sets the mark to the value of
point before doing any replacements, because this enables the user to
move back there conveniently after the replace is finished.

   Once the mark "exists" in a buffer, it normally never ceases to
exist.  However, it may become "inactive", and usually does so after
each command (other than simple motion commands and some commands that
explicitly activate the mark).  When the mark is active, the region
between point and the mark is called the "active region" and is
highlighted specially.

   Many commands are designed so that when called interactively they
operate on the text between point and the mark.  Such commands work
only when an active region exists, i.e. when the mark is active.  (The
reason for this is to prevent you from accidentally deleting or
changing large chunks of your text.) If you are writing such a command,
don't examine the mark directly; instead, use `interactive' with the
`r' specification.  This provides the values of point and the mark as
arguments to the command in an interactive call, but permits other Lisp
programs to specify arguments explicitly, and automatically signals an
error if the command is called interactively when no active region
exists.  *Note Interactive Codes::.

   Each buffer has its own value of the mark that is independent of the
value of the mark in other buffers. (When a buffer is created, the mark
exists but does not point anywhere.  We consider this state as "the
absence of a mark in that buffer.") However, only one active region can
exist at a time.  Activating the mark in one buffer automatically
deactivates an active mark in any other buffer.  Note that the user can
explicitly activate a mark at any time by using the command
`activate-region' (normally bound to `M-C-z') or by using the command
`exchange-point-and-mark' (normally bound to `C-x C-x'), which has the
side effect of activating the mark.

   Some people do not like active regions, so they disable this behavior
by setting the variable `zmacs-regions' to `nil'.  This makes the mark
always active (except when a buffer is just created and the mark points
nowhere), and turns off the highlighting of the region between point
and the mark.  Commands that explicitly retrieve the value of the mark
should make sure that they behave correctly and consistently
irrespective of the setting of `zmacs-regions'; some primitives are
provided to ensure this behavior.

   In addition to the mark, each buffer has a "mark ring" which is a
list of markers containing previous values of the mark.  When editing
commands change the mark, they should normally save the old value of the
mark on the mark ring.  The variable `mark-ring-max' specifies the
maximum number of entries in the mark ring; once the list becomes this
long, adding a new element deletes the last element.

 -- Function: mark &optional force buffer
     This function returns BUFFER's mark position as an integer.
     BUFFER defaults to the current buffer if omitted.

     If the mark is inactive, `mark' normally returns `nil'.  However,
     if FORCE is non-`nil', then `mark' returns the mark position
     anyway--or `nil', if the mark is not yet set for the buffer.

     (Remember that if `zmacs-regions' is `nil', the mark is always
     active as long as it exists, and the FORCE argument will have no
     effect.)

     If you are using this in an editing command, you are most likely
     making a mistake; see the documentation of `set-mark' below.

 -- Function: mark-marker &optional force buffer
     This function returns BUFFER's mark.  BUFFER defaults to the
     current buffer if omitted.  This is the very marker that records
     the mark location inside XEmacs, not a copy.  Therefore, changing
     this marker's position will directly affect the position of the
     mark.  Don't do it unless that is the effect you want.

     If the mark is inactive, `mark-marker' normally returns `nil'.
     However, if FORCE is non-`nil', then `mark-marker' returns the
     mark anyway.
          (setq m (mark-marker))
               => #<marker at 3420 in markers.texi>
          (set-marker m 100)
               => #<marker at 100 in markers.texi>
          (mark-marker)
               => #<marker at 100 in markers.texi>

     Like any marker, this marker can be set to point at any buffer you
     like.  We don't recommend that you make it point at any buffer
     other than the one of which it is the mark.  If you do, it will
     yield perfectly consistent, but rather odd, results.

 -- Function: set-mark position &optional buffer
     This function sets `buffer''s mark to POSITION, and activates the
     mark.  BUFFER defaults to the current buffer if omitted.  The old
     value of the mark is _not_ pushed onto the mark ring.

     *Please note:* Use this function only if you want the user to see
     that the mark has moved, and you want the previous mark position to
     be lost.  Normally, when a new mark is set, the old one should go
     on the `mark-ring'.  For this reason, most applications should use
     `push-mark' and `pop-mark', not `set-mark'.

     Novice XEmacs Lisp programmers often try to use the mark for the
     wrong purposes.  The mark saves a location for the user's
     convenience.  An editing command should not alter the mark unless
     altering the mark is part of the user-level functionality of the
     command.  (And, in that case, this effect should be documented.)
     To remember a location for internal use in the Lisp program, store
     it in a Lisp variable.  For example:

          (let ((start (point)))
            (forward-line 1)
            (delete-region start (point))).

 -- Command: exchange-point-and-mark &optional dont-activate-region
     This function exchanges the positions of point and the mark.  It
     is intended for interactive use.  The mark is also activated
     unless DONT-ACTIVATE-REGION is non-`nil'.

 -- Function: push-mark &optional position nomsg activate buffer
     This function sets BUFFER's mark to POSITION, and pushes a copy of
     the previous mark onto `mark-ring'.  BUFFER defaults to the
     current buffer if omitted.  If POSITION is `nil', then the value
     of point is used.  `push-mark' returns `nil'.

     If the last global mark pushed was not in BUFFER, also push
     POSITION on the global mark ring (see below).

     The function `push-mark' normally _does not_ activate the mark.
     To do that, specify `t' for the argument ACTIVATE.

     A `Mark set' message is displayed unless NOMSG is non-`nil'.

 -- Function: pop-mark
     This function pops off the top element of `mark-ring' and makes
     that mark become the buffer's actual mark.  This does not move
     point in the buffer, and it does nothing if `mark-ring' is empty.
     It deactivates the mark.

     The return value is not meaningful.

 -- Variable: mark-ring
     The value of this buffer-local variable is the list of saved former
     marks of the current buffer, most recent first.

          mark-ring
          => (#<marker at 11050 in markers.texi>
              #<marker at 10832 in markers.texi>
              ...)

 -- User Option: mark-ring-max
     The value of this variable is the maximum size of `mark-ring'.  If
     more marks than this are pushed onto the `mark-ring', `push-mark'
     discards an old mark when it adds a new one.

   In additional to a per-buffer mark ring, there is a "global mark
ring".  Marks are pushed onto the global mark ring the first time you
set a mark after switching buffers.

 -- Variable: global-mark-ring
     The value of this variable is the list of saved former global
     marks, most recent first.

 -- User Option: mark-ring-max
     The value of this variable is the maximum size of
     `global-mark-ring'.  If more marks than this are pushed onto the
     `global-mark-ring', `push-mark' discards an old mark when it adds
     a new one.

 -- Command: pop-global-mark
     This function pops a mark off the global mark ring and jumps to
     that location.


File: lispref.info,  Node: The Region,  Prev: The Mark,  Up: Markers

42.7 The Region
===============

The text between point and the mark is known as "the region".  Various
functions operate on text delimited by point and the mark, but only
those functions specifically related to the region itself are described
here.

   When `zmacs-regions' is non-`nil' (this is the default), the concept
of an "active region" exists.  The region is active when the
corresponding mark is active.  Note that only one active region at a
time can exist--i.e. only one buffer's region is active at a time.
*Note The Mark::, for more information about active regions.

 -- User Option: zmacs-regions
     If non-`nil' (the default), active regions are used.  *Note The
     Mark::, for a detailed explanation of what this means.

   A number of functions are provided for explicitly determining the
bounds of the region and whether it is active.  Few programs need to use
these functions, however.  A command designed to operate on a region
should normally use `interactive' with the `r' specification to find
the beginning and end of the region.  This lets other Lisp programs
specify the bounds explicitly as arguments and automatically respects
the user's setting for `zmacs-regions'.  (*Note Interactive Codes::.)

 -- Function: region-beginning &optional buffer
     This function returns the position of the beginning of BUFFER's
     region (as an integer).  This is the position of either point or
     the mark, whichever is smaller.  BUFFER defaults to the current
     buffer if omitted.

     If the mark does not point anywhere, an error is signaled.  Note
     that this function ignores whether the region is active.

 -- Function: region-end &optional buffer
     This function returns the position of the end of BUFFER's region
     (as an integer).  This is the position of either point or the mark,
     whichever is larger.  BUFFER defaults to the current buffer if
     omitted.

     If the mark does not point anywhere, an error is signaled.  Note
     that this function ignores whether the region is active.

 -- Function: region-exists-p
     This function is non-`nil' if the region exists.  If active regions
     are in use (i.e. `zmacs-regions' is true), this means that the
     region is active.  Otherwise, this means that the user has pushed
     a mark in this buffer at some point in the past.  If this function
     returns `nil', a function that uses the `r' interactive
     specification will cause an error when called interactively.

 -- Function: region-active-p
     If `zmacs-regions' is true, this is equivalent to
     `region-exists-p'.  Otherwise, this function always returns false.
     This function is used by commands such as
     `fill-paragraph-or-region' and `capitalize-region-or-word', which
     operate either on the active region or on something else (e.g. the
     word or paragraph at point).

 -- Variable: zmacs-region-stays
     If a command sets this variable to true, the currently active
     region will remain activated when the command finishes. (Normally
     the region is deactivated when each command terminates.) If
     `zmacs-regions' is false, however, this has no effect.  Under
     normal circumstances, you do not need to set this; use the
     interactive specification `_' instead, if you want the region to
     remain active.

 -- Function: zmacs-activate-region
     This function activates the region in the current buffer (this is
     equivalent to activating the current buffer's mark).  This will
     normally also highlight the text in the active region and set
     `zmacs-region-stays' to `t'. (If `zmacs-regions' is false,
     however, this function has no effect.)

 -- Function: zmacs-deactivate-region
     This function deactivates the region in the current buffer (this is
     equivalent to deactivating the current buffer's mark).  This will
     normally also unhighlight the text in the active region and set
     `zmacs-region-stays' to `nil'. (If `zmacs-regions' is false,
     however, this function has no effect.)

 -- Function: zmacs-update-region
     This function updates the active region, if it's currently active.
     (If there is no active region, this function does nothing.) This
     has the effect of updating the highlighting on the text in the
     region; but you should never need to call this except under rather
     strange circumstances.  The command loop automatically calls it
     when appropriate.  Calling this function will call the hook
     `zmacs-update-region-hook', if the region is active.

 -- Variable: zmacs-activate-region-hook
     This normal hook is called when a region becomes active. (Usually
     this happens as a result of a command that activates the region,
     such as `set-mark-command', `activate-region', or
     `exchange-point-and-mark'.) Note that calling
     `zmacs-activate-region' will call this hook, even if the region is
     already active.  If `zmacs-regions' is false, however, this hook
     will never get called under any circumstances.

 -- Variable: zmacs-deactivate-region-hook
     This normal hook is called when an active region becomes inactive.
     (Calling `zmacs-deactivate-region' when the region is inactive will
     _not_ cause this hook to be called.)  If `zmacs-regions' is false,
     this hook will never get called.

 -- Variable: zmacs-update-region-hook
     This normal hook is called when an active region is "updated" by
     `zmacs-update-region'.  This normally gets called at the end of
     each command that sets `zmacs-region-stays' to `t', indicating
     that the region should remain activated.  The motion commands do
     this.

