|
DataMuseum.dkPresents historical artifacts from the history of: DKUUG/EUUG Conference tapes |
This is an automatic "excavation" of a thematic subset of
See our Wiki for more about DKUUG/EUUG Conference tapes Excavated with: AutoArchaeologist - Free & Open Source Software. |
top - metrics - downloadIndex: T l
Length: 54618 (0xd55a)
Types: TextFile
Names: »lispref-12«
└─⟦a05ed705a⟧ Bits:30007078 DKUUG GNU 2/12/89
└─⟦c06c473ab⟧ »./UNRELEASED/lispref.tar.Z«
└─⟦1b57a2ffe⟧
└─⟦this⟧ »lispref-12«
Info file: lispref, -*-Text-*-
produced by texinfo-format-buffer
from file: lispref.texinfo
This file documents GNU Emacs Lisp.
This is Edition 0.1 Beta of the GNU Emacs Lisp Reference Manual, for
Emacs Version 18, with some references to Emacs Version 19.
Please read this document for review purposes.
Published by the Free Software Foundation, 675 Massachusetts Avenue,
Cambridge, MA 02139 USA
Copyright (C) 1989 Free Software Foundation, Inc.
Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.
Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided that the
entire resulting derived work is distributed under the terms of a
permission notice identical to this one.
Permission is granted to copy and distribute translations of this manual
into another language, under the above conditions for modified versions,
except that this permission notice may be stated in a translation
approved by the Foundation.
▶1f◀
File: lispref Node: Changing File Names and Attributes, Prev: Contents of Directories, Up: Files, Next: File Names
Changing File Names and Attributes
==================================
You can use the functions in this section to rename, copy, delete,
link, and set the modes of files.
* Function: add-name-to-file OLDNAME NEWNAME &optional OK-IF-ALREADY-EXISTS
This function gives the file named OLDNAME the additional name
NEWNAME. This means that NEWNAME will be a new ``hard link'' to
OLDNAME.
This function is meaningless on VMS, where multiple names for one
file are not allowed.
If a file by the name of NEWNAME already exists:
* It is an error if OK-IF-ALREADY-EXISTS is `nil'.
* Confirmation is requested if OK-IF-ALREADY-EXISTS is a number.
* No confirmation is requested if OK-IF-ALREADY-EXISTS is any
other value, in which case the old file is removed.
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 links
to `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 `(add-name-to-file "~/lewis/foo"
"~/lewis/foo3" t)', and again list the files. Now there are three
links to `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
* Command: rename-file FILENAME NEWNAME &optional OK-IF-ALREADY-EXISTS
This function renames FILENAME as NEWNAME.
If FILENAME has names (i.e., hard links) other than filename, it
continues to have those names.
If a file by the name of NEWNAME already exists:
* The function signals a `file-already-exists' error, unless
OK-IF-ALREADY-EXISTS is non-`nil'.
* Emacs requests confirmation if NEWNAME already exists if
OK-IF-ALREADY-EXISTS is numeric.
When called interactively, Emacs prompts for FILENAME and NEWNAME
in the minibuffer. In interactive use, Emacs requests confirmation
if NEWNAME already exists.
* Function: copy-file OLDNAME NEWNAME &optional OK-IF-EXISTS TIME
This function copies the file OLDNAME to NEWNAME. It is an error
if OLDNAME does not exist.
If a file by the name of NEWNAME already exists:
* It is an error if OK-IF-EXISTS is either `nil' or not
supplied.
* Emacs requests confirmation if OK-IF-EXISTS is a number.
* Emacs does *not* request confirmation if OK-IF-EXISTS is any
other value, in which case the old file is removed.
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.)
* Function: delete-file FILENAME
This function deletes the file FILENAME. This function is
essentially the same as the shell command `rm FILENAME'.
If FILENAME has multiple names, it continues to exist with the
other names.
It is an error if the file does not exist, or is not deletable.
(In Unix, a file is deletable if it is writable or its directory is
writable.)
* Command: make-symbolic-link FILENAME NEWNAME &optional OK-IF-EXISTS
This function makes a symbolic link to FILENAME, named NEWNAME.
It signals a `file-already-exists' error if NEWNAME already exists
unless OK-IF-EXISTS is non-`nil'. If OK-IF-EXISTS is numeric, then
Emacs requests confirmation if NEWNAME already exists. If it is
`t', then the old file is simply deleted.
When called interactively, FILENAME and NEWNAME are prompted for
in the minibuffer. OK-IF-EXISTS is set to the processed prefix
argument.
* Function: set-file-modes FILE-NAME MODE
This function sets mode bits of FILE-NAME to MODE (which must be
a integer). Only the 12 low bits of MODE are used.
▶1f◀
File: lispref Node: File Names, Prev: Changing File Names and Attributes, Up: Files
File Names
==========
Files are generally referred to by their names; Emacs is no exception
to this. File names in Emacs are represented as strings. The functions
which read, write or move files all expect a file name argument.
In addition to operating on files themselves, Emacs Lisp programs
often need to operate on the names: to take them apart, and use the
pieces to construct related file names. This section describes how to
manipulate file names.
The functions in this section do not actually operate on files, so
they can operate on file names which do not refer to an existing file or
directory.
On VMS, all these functions understand both VMS file name syntax and
Unix syntax. This is so that all the standard Lisp libraries can
specify file names in Unix syntax and then work properly on either
system without change.
▶1f◀
File: lispref Node: File Name Components, Up: File Names, Next: Directory 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 in that
directory.
Therefore, a file name in Emacs is considered to have two main parts:
the directory name, and "nondirectory" part or file name within the
directory. Concatenating these two parts reproduces the original file
name. Either part may be empty. On Unix, the directory part is
everything up to and including the last slash; the nondirectory part is
the rest. The rules in VMS syntax are complicated.
For some purposes, the nondirectory part is further subdivided into
the name and the version number. On Unix, only backup files have
version numbers in their names; on VMS, every file has a version number,
but most of the time the file name actually used in Emacs omits the
version number. Version numbers are found mostly in directory lists.
* Function: file-name-directory FILENAME
This function returns the directory component in FILENAME. It
returns `nil' if FILENAME does not include a directory. On Unix,
the function returns a string ending in a slash. On VMS, it
returns a string ending in one of the three characters `:', `]', or
`>'.
(file-name-directory "lewis/foo") ; Unix example
=> "lewis/"
(file-name-directory "foo") ; Unix example
=> nil
(file-name-directory "[X]FOO.TMP") ; VMS example
=> [X]
* Function: file-name-nondirectory FILENAME
This function returns the file name from FILENAME without its
directory component (if any).
(file-name-nondirectory "lewis/foo")
=> "foo"
(file-name-nondirectory "foo")
=> "foo"
(file-name-nondirectory "[X]FOO.TMP")
=> "FOO.TMP"
* Function: file-name-sans-versions FILENAME
This function returns FILENAME without any file version numbers,
backup version numbers, or trailing tildes.
(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"
;; The following example applies to VMS only.
(file-name-sans-versions "foo;23")
=> "foo"
▶1f◀
File: lispref Node: Directory Names, Prev: File Name Components, Up: File Names, Next: Relative File Names
Directory Names
---------------
A directory name is the name of a directory, which is a special kind
of file. This file also has a file name, which is its name when
considered as a file in its own right. 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. (This is not quite
identical to the conventions of Unix terminology.) On VMS, the
relationship is more complicated.
Though the difference between a directory name and its name as a file
may be small, it is crucial. When an Emacs variable or function
argument is described as being a directory name, a file name of a
directory is not acceptable.
All of these functions take a single argument, FILENAME, which must be
a string. Environment variables such as `$HOME', and the symbols `~',
and `..', are *not* expanded. Use `expand-file-name' or
`substitute-in-file-name' for that (*Note Relative File Names::).
* 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 that the string has a slash
appended to it. In VMS, the function converts a string of the form
`[X]Y.DIR.1' to the form `[X.Y]'.
(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 that the string has a final slash removed. On
VMS, the function converts a string of the form `[X.Y]' to
`[X]Y.DIR.1'.
(directory-file-name "~lewis/")
=> "~lewis"
▶1f◀
File: lispref Node: Relative File Names, Prev: Directory Names, Up: File Names, Next: File Name Expansion
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 an "relative" file name. On
Unix, an absolute file name starts with a slash or a tilde (`~'), and a
relative one does not. The rules on VMS are complicated.
* Function: file-name-absolute-p FILENAME
This function returns `t' if file FILENAME specifies an absolute
file name, `nil' otherwise. On VMS, this function understands both
Unix syntax and VMS syntax.
(file-name-absolute-p "~rms/foo")
=> t
(file-name-absolute-p "rms/foo")
=> nil
(file-name-absolute-p "$HOME")
=> nil
(file-name-absolute-p "/user/rms/foo")
=> t
▶1f◀
File: lispref Node: File Name Expansion, Prev: Relative File Names, Up: File Names, Next: Unique File Names
Functions that Expand Filenames
-------------------------------
"Expanding" a file name means converting a relative file name to an
absolute one. Since this is done relative to a directory, you must
specify the directory name as well as the file name to be expanded.
Expansion also canonicalizes file names by simplifying 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, then it is the directory to start with if
FILENAME is relative. Otherwise, the current buffer's value of
`default-directory' is used.
Filenames containing `.' or `..' are expanded to their canonical
form. Adjacent `/'s condensed into a single `/'. `~' as a file is
expanded into the user's home directory. See
`substitute-in-file-name' below for the details.
But note that `expand-file-name' does *not* expand environment
variables. (`substitute-in-file-name' does that.)
(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"
* Function: substitute-in-file-name FILENAME
This function replaces environment variables names in FILENAME
with the values to which they are set by the operating system.
Following standard Unix shell syntax, `$' begins an environment
variable.
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 `}'.
If a `~' or a `/' appears following a `/', everything through the
first `/' is discarded.
Here we assume that the environment variable `HOME', which is the
user's home directory name, is `/xcssun/users/rms'.
(substitute-in-file-name "bar/~/foo")
=> "~/foo"
(substitute-in-file-name "$HOME/foo")
=> "/xcssun/users/rms/foo"
(substitute-in-file-name "/usr/local/$HOME/foo")
=> "/xcssun/users/rms/foo"
On VMS, `$' substitution is not done; this function does little on
VMS.
▶1f◀
File: lispref Node: Unique File Names, Prev: File Name Expansion, Up: File Names, Next: Filename Completion
Generating Unique File Names
----------------------------
Some programs need to construct temporary files. Here is the usual
way to construct a name for such a file:
(concat "/tmp/" (make-temp-name NAME-OF-APPLICATION))
The directory `/tmp/' is chosen because that is the standard place on
Unix for temporary files. The task of `make-temp-name' is to prevent
two different users or two different jobs from trying to use the same
name.
* Function: make-temp-name STRING
This function generates string that can be used as a unique name.
The name will start with the prefix STRING, and finish with a
number which is different in each Emacs job.
(make-temp-name "foo")
=> "foo021304"
(make-temp-name "foo")
=> "foo021304"
To prevent conflicts among different application libraries run in
the same Emacs, each application should have its own STRING. The
number added to the end of the name distinguishes between the same
application running in different Emacses.
▶1f◀
File: lispref Node: Filename Completion, Prev: Unique File Names, Up: File Names
Filename Completion
-------------------
This section describes low-level subroutines for completing a
filename.
For other completion functions, *Note Completion::, and *Note Lisp
Symbol Completion::.
* Function: file-name-all-completions PARTIAL-FILENAME DIRECTORY
This function returns a list of all possible completions for a
file whose name starts with PARTIAL-FILENAME in directory
DIRECTORY. The order of the completions is the order of the files
in DIRECTORY, which is not normally sorted.
PARTIAL-FILENAME must contain no directory and no slash. The
current buffer's default directory is prepended to DIRECTORY, if
DIRECTORY is not an absolute file name.
In the following example, suppose that the current default
directory, `~rms/lewis', has five files whose names begin with `f':
`foo', `file~', `file.texinfo', `file.texinfo.~1~', and
`file.texinfo.~2~'.
(file-name-all-completions "f" "~rms/lewis")
=> ("foo" "file~" "file.texinfo.~2~"
"file.texinfo.~1~" "file.texinfo")
(file-name-all-completions "fo" "")
=> ("foo")
* Function: file-name-completion FILENAME DIRECTORY
This function completes the file name FILENAME in directory
DIRECTORY. It returns the longest prefix common to all filenames
in DIRECTORY that start with FILENAME.
If only one match exists, and FILENAME matches exactly, the
function returns `t'. The function returns `nil' if DIRECTORY
contains no name starting with FILENAME.
In the following example, suppose that the current default
direction, `~rms/lewis', has five files whose names begin with `f':
`foo', `file~', `file.texinfo', `file.texinfo.~1~', and
`file.texinfo.~2~'.
(file-name-completion "fi" "")
=> "file"
(file-name-completion "file.texinfo.~1" "")
=> "file.texinfo.~1~"
(file-name-completion "file.texinfo.~1~" "")
=> t
(file-name-completion "file.texinfo.~3" "")
=> nil
* User Option: completion-ignored-extensions
The filename completion functions usually ignore all filenames
that end in any string in this list.
The variable looks somewhat like this:
completion-ignored-extensions
=> (".o" ".elc" "~" ".dvi")
▶1f◀
File: lispref Node: Backups and Auto Saving, Prev: Files, Up: Top, Next: Buffers
Backups and Auto Saving
***********************
Backup files and auto-save files are two methods by which Emacs tries
to protect the user from the consequences of crashes or of the user's
own errors. Auto-saving preserves the text from earlier in the current
editing session. Backup files preserve file contents prior to the
current session.
* Menu:
* Backup Files::
* Auto Saving::
* Reverting::
▶1f◀
File: lispref Node: Backup Files, Prev: Backups and Auto Saving, Up: Backups and Auto Saving, Next: Auto Saving
Backup Files
============
A "backup file" is a copy of the old contents of a file you are
editing. Emacs makes a backup file the first time you save a buffer
into the visited file. This means that the backup file contains the
contents of the file as it was before editing started in the current
editing session. The contents of the backup file are not normally
changed during the current editing session.
By default, Emacs makes a single backup file for each file you edit.
You can alternatively request numbered backups; then each new backup
file gets a new name. It is up to you to delete old numbered backups
when you don't want them any more.
Backups are usually made by renaming the visited file to a new name.
Optionally, you can specify that backup files should be made by copying
the visited file. This choice makes a difference for files with
multiple hard links; it also can affect the owner of the file.
* Menu:
* Making Backups::
* Rename or Copy::
* Backup Names::
▶1f◀
File: lispref Node: Making Backups, Prev: Backup Files, Up: Backup Files, Next: Rename or Copy
Making Backup Files
-------------------
* Function: backup-buffer
This function makes a backup of the file visited by the current
buffer, if appropriate. It is called by `save-buffer' before
saving the buffer the first time.
* Variable: buffer-backed-up
This buffer-local variable indicates whether this buffer's file
has been backed up on account of this buffer. If it is non-`nil',
then the backup file has been written. The file is backed up just
before the file is saved for the first time.
* Variable: make-backup-files
This global variable determines whether or not backup files will
be created. If it is non-`nil', then Emacs will create a backup of
each file when it is saved for the first time.
The following example shows how to change the `make-backup-files'
variable only in your `RMAIL' buffer and not elsewhere. Setting it
`nil' stops Emacs from making backups of your `RMAIL' file, which
may save disk space. (You would put this code in your `.emacs'
file.)
(setq rmail-mode-hook
(function (lambda ()
(make-local-variable 'make-backup-files)
(setq make-backup-files nil)))
▶1f◀
File: lispref Node: Rename or Copy, Prev: Making Backups, Up: Backup Files, Next: Backup Names
Backup by Renaming or by Copying?
---------------------------------
There are two ways that Emacs can make a backup:
* Emacs can rename the original file into a backup file, and then
write the buffer being saved into a new file. In this case, any
other names (e.g., hard links) that the old file had will now refer
to the backup file. The new file will be owned by the user and its
group will be the user's default group.
* Emacs can copy the original file into a backup file, and then
overwrite the original file with new contents. In this case, any
other names (e.g., hard links) that the original file had will
still refer to the most current version of the file. The file's
owner and group will be unchanged.
The first method, of renaming, is the default.
The variable `backup-by-copying', if non-`nil', says to use the second
method, which is to copy the file and then write the buffer on top of
the original.
The variable `file-precious-flag', if non-`nil', also has this effect,
as a sideline of its other significance. *Note Saving Buffers::.
The variables `backup-by-copying-when-linked' and
`backup-by-copying-when-mismatch', if 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
This global variable determines whether backup files will be made
by copying. If it is non-`nil', then Emacs will always copy the
current contents of the file into the backup file before writing
the buffer to be saved to the file. (In many circumstances, this
has the same effect as `file-precious-flag'.)
* Variable: backup-by-copying-when-linked
This global variable determines whether backups for files with
multiple names (hard links) will be made by copying. If it is
non-`nil', then Emacs will use copying to create backups for those
files.
This variable is relevant only if `backup-by-copying' is `nil',
since copying is always used when that variable is non-`nil'.
* Variable: backup-by-copying-when-mismatch
This global variable determines whether Emacs will make backups
by copying when renaming would cause either the owner or the group
of the file to change. If it is non-`nil' then Emacs will create
backups for those file by copying.
Renaming may still be used (subject to control of other
variables) when it would not result in changing 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 relevant only if `backup-by-copying' is `nil',
since copying is always used when that variable is non-`nil'.
▶1f◀
File: lispref Node: Backup Names, Prev: Rename or Copy, Up: Backup Files
Naming Backup Files
-------------------
* 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
In the standard release, the body of this function consists of
the following line:
(string-match "~$" file)
In other words, the function returns a non-`nil' value if the
filename ends with a `~'
This simple expression is given its own name as a function so
that you can redefine it for customization.
* Function: make-backup-file-name FILENAME
This function creates a non-numeric backup file name to be used
when FILENAME is backed up. On Unix, the value is just FILENAME
with a tilde appended.
In the standard release, the body of this function consists of
the following line:
(concat file "~")
You can change the backup file names for all backup files by
redefining this function. In the following example,
`make-backup-file-name' is redefined to prepend a `.' as well as to
append a tilde.
(defun make-backup-file-name (filename)
(concat "." filename "~"))
(make-backup-file-name "backups.texinfo")
=> ".backups.texinfo~"
* Function: find-backup-file-name FILENAME
This function computes the file name for a new backup file for
FILENAME. If numerous backup files for FILENAME exist (which
implies that the backups must be numeric backups), then this
function also makes a list of old backup files that are ripe for
deletion.
The global variables `kept-old-versions' and `kept-new-versions'
determine which old backup versions Emacs will keep (by not
including them in the list of backup files ripe 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 old versions.
In the example, `~rms/lewis/foo.~5~' is the name for the new
backup file and `~rms/lewis/foo.~3~' is the ``excess'' version that
you should consider deleting now.
(find-backup-file-name "~rms/lewis/foo")
=> ("~rms/lewis/foo.~5~" "~rms/lewis/foo.~3~")
* 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. If there are backups
numbered 1, 2, 3, 5, and 6, and the value of `kept-old-versions' is
2, then the ``oldest'' backups 1 and 2 will be kept, and 3 will be
flagged for deletion, unless (in this example) the value of
`kept-new-versions' is greater than 2.
* User Option: kept-new-versions
The value of this variable is the number of a file's most recent
versions to keep when a new numbered backup is made. It includes
the new backup. It must be greater than 0. Thus, if the value of
`kept-new-versions' is 2, then the two most recent backups of a
file will be kept.
▶1f◀
File: lispref Node: Auto Saving, Prev: Backup Files, Up: Backups and Auto Saving, Next: Reverting
Auto Saving
===========
Emacs saves all files that you are visiting from time to time without
being asked. This is called ``auto saving''. (Emacs counts your
keystrokes; by default, your work is saved after 300 keystrokes.) Auto
saving prevents you from losing more than a limited amount of work if
the system crashes. *Note Auto Saving: Protection Against Disasters:
(emacs)Auto Save.
* 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/#file.texinfo#"
* Command: auto-save-mode ARG
When used interactively without being passed an argument this
command is a toggle switch. It turns on auto saving of the
contents of the current buffer if it is off and vice-versa. When
passed ARG, the command turns auto saving on if the value of ARG is
positive, 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 possibly be returned by `make-auto-save-file-name'.
According to the usual naming convention, any name that begins
and ends with hash marks (`#') is a possible auto-save file name,
and any other name isn't.
(make-auto-save-file-name)
=> "/xcssun/users/rms/lewis/#file.texinfo#"
(auto-save-file-name-p "#file.texinfo#")
=> 0
(auto-save-file-name-p "file.texinfo")
=> nil
In the standard release, the body of this function consists of
the following line:
(string-match "^#.*#$" filename)
This function exists so that you can customize it if you wish to
change the naming convention for auto-save files.
* Variable: auto-save-visited-file-name
If this global variable is non-`nil', then Emacs will auto save
buffers in the files they are visiting. That is, the same name is
used as the file currently has. Normally, auto-save files have
other names that created by `make-auto-save-file-name'.
* 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'; that should be checked before this
function is called.
(make-auto-save-file-name)
=> "/xcssun/users/rms/lewis/#file-backup.texinfo#"
The body of `make-auto-save-file-name' consists of the following
lines:
(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.
* 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 changes. It returns
`nil'.
* User Option: auto-save-interval
The value of this variable is the number of characters that Emacs
may read from the keyboard between auto-saves. When this number is
reached, then Emacs will auto-save each file again.
* Command: do-auto-save &optional NO-MESSAGE
This function auto-saves all buffers that need to be auto-saved.
This is all buffers that have auto-saving enabled and that have
been changed since the last time they were auto-saved.
If NO-MESSAGE is non-`nil', then Emacs will not print out its
standard message: `Auto-saving...'.
* Function: delete-auto-save-file-if-necessary
This function deletes the auto-save files for the current buffer
if variable `delete-auto-save-files' is non-`nil'. This function
is called every time you save the buffer.
* Variable: delete-auto-save-files
This global variable is used by the function
`delete-auto-save-file-if-necessary'. If it is non-`nil', then
auto-save files for the buffers will be deleted when you save the
buffer.
In other words, if the value of `delete-auto-save-files' is
non-`nil', Emacs will delete auto-save files when a true save is
done (in the visited file). This saves on disk space and
unclutters your directory.
* Function: rename-auto-save-file
This function adjusts the current buffer's auto-save file name
for current conditions. Assuming that the visited file has been
renamed, this function renames the auto-save file, too. If the
visited file name has not changed, this function does nothing.
▶1f◀
File: lispref 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 NO-AUTOSAVE-OFFER-P 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 latest auto-save file is more
recent than the visited file, Emacs asks the user whether to use
that instead.
When the value of the `no-autosave-offer-p' argument is
non-`nil', Emacs does not offer to use the auto-save file. This
argument is the prefix argument when the function is called
interactively.
When the value of the `noconfirm' argument is non-`nil', Emacs
does not ask for confirmation for the reversion action. This means
that the buffer is deleted and replaced by the text from the file
on the disk, without asking the user if he or she really wants
that.
If the value of the `revert-buffer-function' variable is
non-`nil', it is called as a function to do the work.
* Variable: revert-buffer-function
The value of this variable is the function to use to revert this
buffer; but if the value of this variable is `nil', then the
`revert-buffer' function carries out its default action.
Modes such as Dired mode, in which the text being edited does not
consist of a file's contents but can be regenerated, set this
variable locally.
* Command: recover-file FILENAME
This function visits FILENAME, but gets the contents from its
last auto-save file.
The `after-find-file' function displays a message suggesting the
use of `recover-file' if the auto-save file is newer than the file
just visited. This situation may be the result of a crash. By
using `recover-file', you may recover a great deal of work.
It is an error if there is no auto-save file for FILENAME, or if
FILENAME is newer than its auto-save file. If FILENAME does not
exist, but its auto-save file does, that is ok. This last
situation may occur if you visited a nonexistent file and never
actually saved it.
This function is for interactive use.
▶1f◀
File: lispref Node: Buffers, Prev: Backups and Auto Saving, Up: Top, Next: Windows
Buffers
*******
A "buffer" is a Lisp object containing characters. Buffers are used
to hold the contents of files when they are visited, but buffers need
not have an associated file. While several buffers may exist at one
time, exactly one buffer is designated the "current buffer". Most
editing commands act on the contents of the current buffer. Each
buffer, including the current buffer, may or may not be displayed in a
window.
* Menu:
* Buffer Basics::
* Buffer Names::
* Buffer File Name::
* Buffer Contents::
* Buffer Modification::
* Modification Time::
* Read Only Buffers::
* The Buffer List::
* Creating Buffers::
* Killing Buffers::
* Changing Buffers::
▶1f◀
File: lispref Node: Buffer Basics, Prev: Buffers, Up: Buffers, Next: Buffer Names
Buffer Basics
=============
The contents of a buffer may be viewed as an extendable string;
insertions and deletions may occur in any part of the buffer.
A Lisp buffer object has information about one specific buffer. Some
of this information is directly accessible to the programmer through
variables; other information is only accessible through functions that
modify it or return it. (For example, the width of a tab character 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" variables. These buffer-local bindings exactly parallel
the global value cell of a symbol, if any, but they are ``seen'' by the
evaluator before the actual global value cell. This means you can set
buffer-local variables, such as `fill-column' or `comment-column', to
different values for each buffer. For more information about
buffer-local variables and functions that relate to them, *Note Buffer
Local Variables::.
For functions and variables that relate to saving the contents of
buffers to files, *Note Writing to Files::. For functions and variables
that relate to the display of buffers in windows, *Note Windows::.
* Function: bufferp OBJECT
This function returns `t' if OBJECT is a buffer, `nil' otherwise.
* Function: current-buffer
This function returns the current buffer. There is always one
and only one buffer designated the current buffer. Many editing
commands act on the current buffer. It need not be displayed in a
window.
(current-buffer)
=> #<buffer buffers.texinfo>
▶1f◀
File: lispref Node: Buffer Names, Prev: Buffer Basics, Up: Buffers, Next: Buffer File Name
Buffer Names
============
Each buffer has a unique name. The buffer name may be used in place
of the buffer object in many functions that operate on buffers. Buffers
that are generally ephemeral and uninteresting to the user have names
starting with a space; this prevents the buffer from being listed by the
`list-buffers' or `buffer-menu' command.
Many of the following functions accept either a buffer or a buffer
name (a string) as an argument. Any argument called BUFFER-OR-NAME is
assumed to be one or the other, and it is an error if it is not. Any
argument called BUFFER must be an actual buffer, not a string.
* 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 the result
of `buffer-name' is `nil', then BUFFER has been killed.
(buffer-name)
=> "buffers.texinfo"
(setq foo (get-buffer "temp"))
=> #<buffer temp>
(kill-buffer foo)
=> nil
(buffer-name foo)
=> nil
foo
=> #<killed buffer>
* Command: rename-buffer NEWNAME
This function renames the current buffer to NEWNAME. It is an
error if NEWNAME is not a string, or if there is already a buffer
with that name. It returns `nil'.
You can use this command to rename the `*shell*' buffer to some
other name, which makes it possible for you to create a second
shell buffer inside of Emacs.
* Function: get-buffer BUFFER-OR-NAME
This function returns the buffer BUFFER-OR-NAME. If
BUFFER-OR-NAME is a string and there is no buffer of that name,
`nil' is returned.
The argument passed to `get-buffer' is almost always the name of
a buffer. Although BUFFER-OR-NAME may be a buffer, this would not
be very useful.
(setq b (get-buffer "lewis"))
=> #<buffer lewis>
(get-buffer b)
=> #<buffer lewis>
(get-buffer "Frazzle-nots")
=> nil
▶1f◀
File: lispref Node: Buffer File Name, Prev: Buffer Names, Up: Buffers, Next: Buffer Contents
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'.
For functions and variables that relate to saving the contents of
buffers to files, *Note Writing to Files::.
* Function: buffer-file-name &optional BUFFER
This function returns the absolute file name of the file that the
buffer is visiting. If BUFFER is not supplied, it defaults to the
current buffer. If the buffer is not visiting any file, this
returns `nil'.
(buffer-file-name (other-buffer))
=> "/usr/user/lewis/manual/files.texinfo"
* 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.
buffer-file-name
=> "/usr/user/lewis/manual/buffers.texinfo"
* Function: get-file-buffer FILENAME
This function returns the buffer visiting file FILENAME. If
there is no such buffer, it returns NIL. FILENAME must be a
string.
(get-file-buffer "buffers.texinfo")
=> #<buffer buffers.texinfo>
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
This function changes the name of the file visited in current
buffer to FILENAME. The *next time* the buffer is saved it will go
in the newly specified file. If the buffer had no visited file,
this can give it one.
If FILENAME is `nil' or is the empty string, that stands for ``no
visited file''. In this case, the buffer will not have a visited
file when this function returns, whether or not it had one
previously. Also see `clear-visited-file-modtime' and
`verify-visited-file-modtime' in *Note Buffer Modification::.
When `set-visited-file-name' is called interactively, Emacs
prompts for FILENAME in the minibuffer.
▶1f◀
File: lispref Node: Buffer Contents, Prev: Buffer File Name, Up: Buffers, Next: Buffer Modification
Buffer Contents
===============
The following functions return information about the buffer contents,
including their limits. *Note Text::, for functions that modify the
contents, and *Note Searching and Matching::, for functions that search
the contents.
* Function: buffer-substring START END
This function returns a string containing a copy of the text of
the region defined by positions START and END in the current
buffer. If the arguments are not between the values returned by
`(point-min)' and `(point-max)', Emacs signals an
`args-out-of-range' error
---------- Buffer: foo ----------
This is the contents of buffer foo
---------- Buffer: foo ----------
(buffer-substring 1 10)
=> "This is t"
(buffer-substring (point-max) 10)
=> "he contents of buffer foo
"
* Function: buffer-size
This function returns the total number of characters in the
current buffer. This number is one less than the number
`point-max' returns in the absence of a clipping restriction (*Note
Clipping Restrictions::).
(buffer-size)
=> 35
(point-max)
=> 36
* Variable: buffer-saved-size
The value of this buffer-local variable is the length of the
current buffer when it was last read in, saved or auto-saved.
* Function: buffer-end FLAG
This function returns `(point-min)' if FLAG is less than `1',
`(point-max)' otherwise.
* Function: point-min
This function returns the minimum accessible value of the point
in the current buffer. This is `1', unless a clipping restriction
is in effect, in which case it is the position of the start of the
clipping restriction. (*Note Clipping Restrictions::.)
* Function: point-max
This function returns the maximum accessible value of the point
in the current buffer. This is `(1+ (buffer-size))', unless a
clipping restriction is in effect, in which case it is the position
of the end of the clipping restriction. (*Note Clipping
Restrictions::).
* Function: buffer-string
This function returns the contents of the current buffer as a
string.
(buffer-string)
=> "This is the contents of buffer foo
"
▶1f◀
File: lispref Node: Buffer Modification, Prev: Buffer Contents, Up: Buffers, Next: Modification Time
Buffer Modification
===================
Emacs 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, and cleared to `nil' when
you save the buffer. Thus, the flag indicates whether there are unsaved
changes. The flag value is normally indicated in the mode line (*Note
Major Line Information::), and controls saving (*Note Saving Buffers::)
and auto-saving (*Note Auto Saving::).
Lisp programs also set the flag explicitly. The Lisp function
`set-visited-file-name' sets the flag to `t'; even if the text is
unchanged since some other file was visited in the buffer, the text does
not match the new visited file.
* Function: buffer-modified-p &optional BUFFER
This function returns `t' if the buffer has been modified since
it was last read in from a file or saved, `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 `t'
(or any non-`nil' value). It marks the buffer as unmodified if the
flag is `nil'.
Another effect of calling this function is to cause redisplay of
the mode line for the current buffer, unconditionally.
* Command: not-modified
Mark current buffer as unmodified, not needing to be saved.
Don't use this function in programs!
For functions that modify buffers, *Note Text::.
▶1f◀
File: lispref Node: Modification Time, Prev: Buffer Modification, Up: Buffers, Next: Read Only Buffers
Comparison of Modification Time
===============================
If you visit a file and make changes in the buffer, and meanwhile the
file itself is changed on disk, saving the buffer would overwrite the
changes in the file. Occasionally, if the file was changed
inadvertently, this may be what you want. Most of the time, it would
lose valuable information. Emacs 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 Emacs's record of the modification time
for the file that the buffer is visiting and compares it to the
actual modification time of the file as recorded by the operating
system. The two will be the same unless some other process has
written the file since Emacs visited or saved it.
The function returns `t' if the last actual modification time and
Emacs'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. This means that
the next attempt to save this buffer will certainly not complain of
a discrepancy among file modification times.
This is used in `set-visited-file-name' and other exceptional
places where the usual test to avoid overwriting a changed file is
undesirable.
* Function: ask-user-about-supersession-threat FN
Ask a user who is about to modify an obsolete buffer what to do.
An "obsolete buffer" is one for which the associated file on disk
is newer than the last save-time of the buffer. This means some
other program probably altered the file.
This function is called automatically by Emacs on the proper
occasions. You can redefine this function to do what you prefer.
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 `(FN)'), in which
case the proposed buffer modification is not allowed.
▶1f◀
File: lispref Node: Read Only Buffers, Prev: Modification Time, Up: Buffers, Next: The Buffer List
Read Only Buffers
=================
A buffer may be designated as "read-only". This means that the
buffer's contents may not be modified, although you may change your view
of the contents by scrolling, narrowing, or widening.
* Variable: buffer-read-only
This buffer-local variable specifies whether the buffer is
read-only. If it is `nil', then the buffer is not read-only,
otherwise it is.
* Command: toggle-read-only
This command changes whether the current buffer is read-only,
regardless of whether it is visiting a file. Don't use this
command in programs!
* 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.
Read-only buffers are used in two kinds of situations.
* A buffer visiting a file is made read-only if the file is
write-protected.
Here, the purpose is to show the user that editing the buffer is
probably futile. If the user wants to make changes anyway, he or
she can use `toggle-read-only'.
* 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 the mode in question bind
`buffer-read-only' to `nil' (with `let') around the places where
they change the text.
▶1f◀
File: lispref Node: The Buffer List, Prev: Read Only Buffers, Up: Buffers, Next: Creating Buffers
The Buffer List
===============
The "buffer list" is a list of all buffers that have not been killed.
The order of the buffers in the list is based primarily on how recently
each buffer has been displayed in the selected window. Several
functions, including `other-buffer', depend on this order.
* Function: buffer-list
This function returns a list of all buffers, including those
whose names begin with a space.
(buffer-list)
=> (#<buffer buffers.texinfo> #<buffer *Minibuf-1*>
#<buffer buffer.c> #<buffer *Help*> #<buffer TAGS>)
;; Notice the name of the minibuffer begins with a space!
(mapcar (function buffer-name) (buffer-list))
=> ("buffers.texinfo" " *Minibuf-1*" "buffer.c" "*Help*" "TAGS")
* Command: list-buffers &optional FILES-ONLY
This function displays a listing of the names of existing
buffers. It clears the buffer `*Buffer List*', then inserts the
listing into that buffer and displays it in a window.
All buffers that have names starting with spaces are omitted from
the display.
If FILES-ONLY is non-`nil', then the list shows only buffers that
are visiting files.
In the listing, the current buffer has a dot in the first column.
If the column labeled `M' contains a `*', then that buffer has been
modified. If the column labeled `R' contains a `%', then that
buffer is `read-only'.
`list-buffers' returns `nil'.
The buffers are listed in the order which they appear in the
buffer list. This is the order in which they are chosen as the
default buffer by such functions as `other-buffer'.
(list-buffers)
=> nil
---------- Buffer: *Buffer List* ----------
MR Buffer Size Mode File
-- ------ ---- ---- ----
.* buffers.texinfo 17870 Texinfo /lewis/buffers.texinfo
buffer.c 43204 C /lewis/buffer.c
* *Help* 131 Fundamental
TAGS 190930 Fundamental /lewis/TAGS
*% *Buffer List* 0 Buffer Menu
---------- Buffer: *Buffer List* ----------
(list-buffers t)
=> nil
---------- Buffer: *Buffer List* ----------
MR Buffer Size Mode File
-- ------ ---- ---- ----
.* buffers.texinfo 17870 Texinfo /lewis/buffers.texinfo
buffer.c 43204 C /lewis/buffer.c
% TAGS 190930 Fundamental /lewis/TAGS
---------- Buffer: *Buffer List* ----------
* Command: bury-buffer &optional BUFFER-OR-NAME
This function puts BUFFER-OR-NAME at the end of the buffer list
without changing the order of any of the other buffers on the list.
There it is the least desirable candidate for `other-buffer' to
return, and appears last in the list displayed by `list-buffers'.
If BUFFER-OR-NAME is not supplied, it defaults to the current
buffer.
If BUFFER-OR-NAME is the current buffer, then the current buffer
is replaced in the selected window by the buffer selected by
`other-buffer'. If the current buffer is displayed in a window
other than the selected one, it remains there.
When called interactively, this function buries the current
buffer.
* Function: other-buffer &optional BUFFER-OR-NAME
This function returns the most recently current buffer other than
BUFFER-OR-NAME. If BUFFER-OR-NAME is not supplied (or if it is not
a buffer), then `other-buffer' returns the first buffer on the
buffer list that is not visible in any window. If no other buffer
exists, the buffer `*scratch*' is returned.
▶1f◀