-This is Info file ../info/lispref.info, produced by Makeinfo version
-1.68 from the input file lispref/lispref.texi.
+This is ../info/lispref.info, produced by makeinfo version 4.0b from
+lispref/lispref.texi.
INFO-DIR-SECTION XEmacs Editor
START-INFO-DIR-ENTRY
Foundation instead of in the original English.
\1f
+File: lispref.info, Node: Changing File Attributes, Next: File Names, Prev: Information about Files, Up: Files
+
+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'.
+
+\1f
+File: lispref.info, Node: File Names, Next: Contents of Directories, Prev: Changing File Attributes, Up: Files
+
+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.
+
+\1f
+File: lispref.info, Node: File Name Components, Next: Directory Names, Up: File Names
+
+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"
+
+\1f
+File: lispref.info, Node: Directory Names, Next: Relative File Names, Prev: File Name Components, Up: File Names
+
+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"))
+
+\1f
+File: lispref.info, Node: Relative File Names, Next: File Name Expansion, Prev: Directory Names, Up: File Names
+
+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
+
+\1f
+File: lispref.info, Node: File Name Expansion, Next: Unique File Names, Prev: Relative File Names, Up: File Names
+
+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"
+
+\1f
+File: lispref.info, Node: Unique File Names, Next: File Name Completion, Prev: File Name Expansion, Up: File Names
+
+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'.
+
+\1f
+File: lispref.info, Node: File Name Completion, Next: User Name Completion, Prev: Unique File Names, Up: File Names
+
+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")
+
+\1f
+File: lispref.info, Node: User Name Completion, Prev: File Name Completion, Up: File Names
+
+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.
+
+\1f
+File: lispref.info, Node: Contents of Directories, Next: Create/Delete Dirs, Prev: File Names, Up: Files
+
+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'.
+
+\1f
+File: lispref.info, Node: Create/Delete Dirs, Next: Magic File Names, Prev: Contents of Directories, Up: Files
+
+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.
+
+\1f
+File: lispref.info, Node: Magic File Names, Next: Partial Files, Prev: Create/Delete Dirs, Up: Files
+
+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.
+
+\1f
+File: lispref.info, Node: Partial Files, Next: Format Conversion, Prev: Magic File Names, Up: Files
+
+Partial Files
+=============
+
+* Menu:
+
+* Intro to Partial Files::
+* Creating a Partial File::
+* Detached Partial Files::
+
+\1f
+File: lispref.info, Node: Intro to Partial Files, Next: Creating a Partial File, Up: Partial Files
+
+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.
+
+\1f
+File: lispref.info, Node: Creating a Partial File, Next: Detached Partial Files, Prev: Intro to Partial Files, Up: Partial Files
+
+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.
+
+\1f
+File: lispref.info, Node: Detached Partial Files, Prev: Creating a Partial File, Up: Partial Files
+
+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.
+
+\1f
+File: lispref.info, Node: Format Conversion, Next: Files and MS-DOS, Prev: Partial Files, Up: Files
+
+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.
+
+\1f
File: lispref.info, Node: Files and MS-DOS, Prev: Format Conversion, Up: Files
Files and MS-DOS
file type of the buffer's visited file. The value is `nil' for
text, `t' for binary.
- - Function: find-buffer-file-type FILENAME
+ - 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.
don't indicate anything in particular. Its value should be `nil'
for text, or `t' for binary.
- - Command: find-file-text FILENAME
+ - Command: find-file-text filename
Like `find-file', but treat the file as text regardless of its
name.
- - Command: find-file-binary FILENAME
+ - Command: find-file-binary filename
Like `find-file', but treat the file as binary regardless of its
name.
not lose its value. Major modes should not set this
variable--they should set `make-backup-files' instead.
-\1f
-File: lispref.info, Node: Rename or Copy, Next: Numbered Backups, Prev: Making Backups, Up: Backup Files
-
-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'.
-
-\1f
-File: lispref.info, Node: Numbered Backups, Next: Backup Names, Prev: Rename or Copy, Up: Backup Files
-
-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: trim-versions-without-asking
- If this variable is non-`nil', then saving a file deletes excess
- backup versions silently. Otherwise, it asks the user whether to
- delete them.
-
- - User Option: dired-kept-versions
- This variable specifies how many of the newest backup versions to
- keep in the Dired command `.' (`dired-clean-directory'). That's
- the same thing `kept-new-versions' specifies when you make a new
- backup file. The default value is 2.
-
-\1f
-File: lispref.info, Node: Backup Names, Prev: Numbered Backups, Up: Backup Files
-
-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.
-
-\1f
-File: lispref.info, Node: Auto-Saving, Next: Reverting, Prev: Backup Files, Up: Backups and Auto-Saving
-
-Auto-Saving
-===========
-
- XEmacs periodically saves all files that you are visiting; this is
-called "auto-saving". Auto-saving prevents you from losing more than a
-limited amount of work if the system crashes. By default, auto-saves
-happen every 300 keystrokes, or after around 30 seconds of idle time.
-*Note Auto-Save: (emacs)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
- 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.
-
-\1f
-File: lispref.info, Node: Reverting, Prev: Auto-Saving, Up: Backups and Auto-Saving
-
-Reverting
-=========
-
- If you have made extensive changes to a file and then change your
-mind about them, you can get rid of them by reading in the previous
-version of the file with the `revert-buffer' command. *Note Reverting
-a Buffer: (emacs)Reverting.
-
- - Command: revert-buffer &optional CHECK-AUTO-SAVE NOCONFIRM
- 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.
-
- 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.
-
-\1f
-File: lispref.info, Node: Buffers, Next: Windows, Prev: Backups and Auto-Saving, Up: Top
-
-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 windows.
-
-* 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.
-
-\1f
-File: lispref.info, Node: Buffer Basics, Next: Current Buffer, Up: Buffers
-
-Buffer Basics
-=============
-
- A "buffer" is a Lisp object containing text to be edited. Buffers
-are used to hold the contents of files that are being visited; there may
-also be buffers that are not visiting files. While several buffers may
-exist at one time, exactly one buffer is designated the "current
-buffer" at any time. Most editing commands act on the contents of the
-current buffer. Each buffer, including the current buffer, may or may
-not be displayed in any windows.
-
- Buffers in Emacs editing are objects that have distinct names and
-hold text that can be edited. Buffers appear to Lisp programs as a
-special data type. You can think of the contents of a buffer as an
-extendable 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.
-
-\1f
-File: lispref.info, Node: Current Buffer, Next: Buffer Names, Prev: Buffer Basics, Up: Buffers
-
-The Current Buffer
-==================
-
- There are, in general, many buffers in an Emacs session. At any
-time, one of them is designated as the "current buffer". This is the
-buffer in which most editing takes place, because most of the primitives
-for examining or changing text in a buffer operate implicitly on the
-current buffer (*note Text::.). Normally the buffer that is displayed
-on the screen in the selected window is the current buffer, but this is
-not always so: a Lisp program can designate any buffer as current
-temporarily in order to operate on its contents, without changing what
-is displayed on the screen.
-
- The way to designate a current buffer in a Lisp program is by calling
-`set-buffer'. The specified buffer remains current until a new one is
-designated.
-
- When an editing command returns to the editor command loop, the
-command loop designates the buffer displayed in the selected window as
-current, to prevent confusion: the buffer that the cursor is in when
-Emacs reads a command is the buffer that the command will apply to.
-(*Note Command Loop::.) Therefore, `set-buffer' is not the way to
-switch visibly to a different buffer so that the user can edit it. For
-this, you must use the functions described in *Note Displaying
-Buffers::.
-
- However, Lisp functions that change to a different current buffer
-should not depend on the command loop to set it back afterwards.
-Editing commands written in XEmacs Lisp can be called from other
-programs as well as from the command loop. It is convenient for the
-caller if the subroutine does not change which buffer is current
-(unless, of course, that is the subroutine's purpose). Therefore, you
-should normally use `set-buffer' within a `save-excursion' that will
-restore the current buffer when your function is done (*note
-Excursions::.). Here is an example, the code for the command
-`append-to-buffer' (with the documentation string abridged):
-
- (defun append-to-buffer (buffer start end)
- "Append to specified buffer the text of the region.
- ..."
- (interactive "BAppend to buffer: \nr")
- (let ((oldbuf (current-buffer)))
- (save-excursion
- (set-buffer (get-buffer-create buffer))
- (insert-buffer-substring oldbuf start end))))
-
-This function binds a local variable to the current buffer, and then
-`save-excursion' records the values of point, the mark, and the
-original buffer. Next, `set-buffer' makes another buffer current.
-Finally, `insert-buffer-substring' copies the string from the original
-current buffer to the new current buffer.
-
- If the buffer appended to happens to be displayed in some window,
-the next redisplay will show how its text has changed. Otherwise, you
-will not see the change immediately on the screen. The buffer becomes
-current temporarily during the execution of the command, but this does
-not cause it to be displayed.
-
- If you make local bindings (with `let' or function arguments) for a
-variable that may also have buffer-local bindings, make sure that the
-same buffer is current at the beginning and at the end of the local
-binding's scope. Otherwise you might bind it in one buffer and unbind
-it in another! There are two ways to do this. In simple cases, you may
-see that nothing ever changes the current buffer within the scope of the
-binding. Otherwise, use `save-excursion' to make sure that the buffer
-current at the beginning is current again whenever the variable is
-unbound.
-
- It is not reliable to change the current buffer back with
-`set-buffer', because that won't do the job if a quit happens while the
-wrong buffer is current. Here is what *not* to do:
-
- (let (buffer-read-only
- (obuf (current-buffer)))
- (set-buffer ...)
- ...
- (set-buffer obuf))
-
-Using `save-excursion', as shown below, handles quitting, errors, and
-`throw', as well as ordinary evaluation.
-
- (let (buffer-read-only)
- (save-excursion
- (set-buffer ...)
- ...))
-
- - Function: current-buffer
- This function returns the current buffer.
-
- (current-buffer)
- => #<buffer buffers.texi>
-
- - Function: set-buffer BUFFER-OR-NAME
- This function makes BUFFER-OR-NAME the current buffer. It does
- not display the buffer in the currently selected window or in any
- other window, so the user cannot necessarily see the buffer. But
- Lisp programs can in any case work on it.
-
- This function returns the buffer identified by BUFFER-OR-NAME. An
- error is signaled if BUFFER-OR-NAME does not identify an existing
- buffer.
-
-\1f
-File: lispref.info, Node: Buffer Names, Next: Buffer File Name, Prev: Current Buffer, Up: Buffers
-
-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 specified by 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 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::.
-
-\1f
-File: lispref.info, Node: Buffer File Name, Next: Buffer Modification, Prev: Buffer Names, Up: Buffers
-
-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.
-
-\1f
-File: lispref.info, Node: Buffer Modification, Next: Modification Time, Prev: Buffer File Name, Up: Buffers
-
-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
- This function marks the current buffer as modified if FLAG is
- non-`nil', or as unmodified if the flag is `nil'.
-
- Another effect of calling this function is to cause unconditional
- redisplay of the modeline for the current buffer. In fact, the
- function `redraw-modeline' works by doing this:
-
- (set-buffer-modified-p (buffer-modified-p))
-
- - Command: not-modified &optional ARG
- This command marks the current buffer as unmodified, and not
- needing to be saved. (If ARG is non-`nil', the buffer is instead
- marked as modified.) Don't use this function in programs, since it
- prints a message in the echo area; use `set-buffer-modified-p'
- (above) instead.
-
- - Function: buffer-modified-tick &optional BUFFER
- This function returns BUFFER`s modification-count. This is a
- counter that increments every time the buffer is modified. If
- BUFFER is `nil' (or omitted), the current buffer is used.
-
-\1f
-File: lispref.info, Node: Modification Time, Next: Read Only Buffers, Prev: Buffer Modification, Up: Buffers
-
-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::.
-
-\1f
-File: lispref.info, Node: Read Only Buffers, Next: The Buffer List, Prev: Modification Time, Up: Buffers
-
-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
- This command changes whether the current buffer is read-only. It
- is intended for interactive use; 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
- This function signals a `buffer-read-only' error if the current
- buffer is read-only. *Note Interactive Call::, for another way to
- signal an error if the current buffer is read-only.
-
projects / chise / xemacs-chise.git / blobdiff