X-Git-Url: http://git.chise.org/gitweb/?a=blobdiff_plain;f=info%2Flispref.info-24;h=a7775715feac6ff206e687bc493a7daab07db9f5;hb=21f468e67f1166bb9473becadd5d304a45a844b0;hp=1233bf9b5ba5a14423a1da815d6a597fc4457f2e;hpb=430e0db85cc37821320fe27da9feeacc7961003f;p=chise%2Fxemacs-chise.git diff --git a/info/lispref.info-24 b/info/lispref.info-24 index 1233bf9..a777571 100644 --- a/info/lispref.info-24 +++ b/info/lispref.info-24 @@ -1,5 +1,5 @@ -This is Info file ../../info/lispref.info, produced by Makeinfo version -1.68 from the input file lispref.texi. +This is ../info/lispref.info, produced by makeinfo version 4.0 from +lispref/lispref.texi. INFO-DIR-SECTION XEmacs Editor START-INFO-DIR-ENTRY @@ -50,6 +50,1023 @@ may be included in a translation approved by the Free Software Foundation instead of in the original English.  +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'. + + +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. + + +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" + + +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")) + + +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 + + +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" + + +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'. + + +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") + + +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. + + +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'. + + +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. + + +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. + + +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:: + + +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. + + +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. + + +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. + + +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 + 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 + 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 Files and MS-DOS @@ -72,7 +1089,7 @@ visiting a file, and records the decision in the variable 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. @@ -89,11 +1106,11 @@ visiting a file, and records the decision in the variable 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. @@ -209,978 +1226,3 @@ Making Backup Files 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 - -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 - -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. - - -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. - - -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. - - -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. - - -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. - - -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. - - -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) - => # - - - 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. - - -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")) - => # - (kill-buffer foo) - => nil - (buffer-name foo) - => nil - foo - => # - - - 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")) - => # - (get-buffer b) - => # - (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 - -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") - => # - - 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 - -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. - - -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::. - - -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. -