|
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: 51361 (0xc8a1)
Types: TextFile
Names: »lispref-11«
└─⟦a05ed705a⟧ Bits:30007078 DKUUG GNU 2/12/89
└─⟦c06c473ab⟧ »./UNRELEASED/lispref.tar.Z«
└─⟦1b57a2ffe⟧
└─⟦this⟧ »lispref-11«
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: Documentation, Prev: Major and Minor Modes, Up: Top, Next: Files
Documentation
*************
GNU Emacs Lisp has a simple to use facility for displaying the
documentation strings that are associated with functions and variables.
In addition, Emacs has powerful on-line help.
Documentation strings should be distinguished from manuals such as
this one, which can be examined inside Emacs using Info. A manual is
defined by its own source file; documentation strings are specified in
the source of the functions and variables documented.
* Menu:
* Documentation Basics::
* Documentation Strings::
* Help Functions::
▶1f◀
File: lispref Node: Documentation Basics, Prev: Documentation, Up: Documentation, Next: Documentation Strings
Documentation Basics
====================
A documentation string is written between double quotes, `"like
this"'.
In a function definition, the documentation string follows the
argument list in a variable definition, the documentation string follows
the initial value of the variable.
When you write a documentation string, you should make the first line
a complete sentence (or two compelte sentences) since some commands,
such as `apropos', print only the first line of a multi-line
documentation string. Also, you should not indent the second line of a
documentation string, if you have one, because that looks odd when you
use `C-h f' (`describe-function') or `C-h v' (`describe-variable').
In Emacs Lisp, the underlying principle is that adocumentation string
is kept with the function or variable which it describes:
* The documentation for a function is stored in the function
definition itself (*Note Lambda Expressions::). The function
`documentation' knows how to extract it.
* The documentation for a variable is stored on the variable's
property list under the property name `variable-documentation'.
The function `documentation-property' knows how to extract it.
However, to save space, the documentation for preloaded functions and
variables (including primitive functions and autoloaded functions)
stored in the `emacs/etc/DOC-VERSION' file. Both the `documentation'
and the `documentation-property' functions know how to access the
`emacs/etc/DOC-VERSION' file, and the process is transparent to the
user. In this case, the `variable-documentation' property of the symbol
is an integer offset into the `emacs/etc/DOC-VERSION' file. Keeping the
documentation strings out of the Emacs core image saves a significant
amount of space.
See `where-is-internal' and `describe-bindings' in *Note Global and
Local Keymaps::. Also, *Note Help: (emacs)Help..
The `emacs/etc' directory contains two utilities for printing the
`emacs/etc/DOC-VERSION' file in hardcopy. These are `sorted-doc.c' and
`digest-doc.c'.
In addition, documentation strings may contain several special
substrings. These substrings allow the functions which retrieve them to
substitute the actual (current) key bindings into the strings, using the
`substitute-command-keys' function. (*Note Documentation Strings::.)
▶1f◀
File: lispref Node: Documentation Strings, Prev: Documentation Basics, Up: Documentation, Next: Help Functions
Access to Documentation Strings
===============================
* Function: documentation-property SYMBOL PROPERTY
This function returns the documentation string that is SYMBOL's
PROPERTY. Use of this function differs from using `get', since
`documentation-property' is also able to access documentation
strings that are stored in the `emacs/etc/DOC-VERSION' file. In
addition, `documentation-property' runs `substitute-command-keys'
on the resulting string, so Emacs will display the actual (current)
keybindings.
(documentation-property 'command-line-processed
'variable-documentation)
=> "t once command line has been processed"
(symbol-plist 'command-line-processed)
=> (variable-documentation 188902)
* Function: documentation FUNCTION
This function returns the documentation string of FUNCTION. If
the documentation string is stored in the `emacs/etc/DOC-VERSION'
file, this function will access it there.
In addition, `documentation' runs `substitute-command-keys' on
the resulting string, so the value contains the actual (current)
keybindings.
Emacs signals a `void-function' error unless FUNCTION has a
function definition. However, FUNCTION does not need to have a
documentation string. If there is no documentation string, the
function returns `nil'.
Here is a function which uses `documentation' and
`documentation-property' to display the documentation strings for
several symbols in a `*Help*' buffer.
(defun describe-symbols (pattern)
"Describe the currently active Emacs Lisp symbols matching PATTERN.
All symbols that have PATTERN in their name are described
in the *Help* buffer."
(interactive "sDescribe symbols matching: ")
(let ((describe-func
(function
(lambda (s)
;; Print description of symbol.
(if (fboundp s) ; It is a function.
(princ
(format "%s\t%s\n%s\n\n" s
(if (commandp s)
(concat "Command: "
(or (mapconcat
'key-description
(where-is-internal s)
" ")))
"Function")
(or (documentation s)
"not documented"))))
(if (boundp s) ; It is a variable.
(princ
(format "%s\t%s\n%s\n\n" s
(if (user-variable-p s)
"Option "
"Variable")
(or
(documentation-property
s
'variable-documentation)
"not documented"))))))
sym-list)
;; Build a list of symbols that match pattern.
(mapatoms (function
(lambda (sym)
(if (string-match pattern
(symbol-name sym))
(setq sym-list (cons sym sym-list))
))))
;; Display the data.
(with-output-to-temp-buffer "*Help*"
(mapcar describe-func (sort sym-list 'string<))
(print-help-return-message))))
The `describe-symbols' function works like `apropos', but
provides more information.
(describe-symbols "goal")
---------- Buffer: *Help* ----------
goal-column Option
*Semipermanent goal column for vertical motion,
as set by C-x C-n, or nil.
set-goal-column Command: C-x C-n
Set the current horizontal position as a goal for C-n and C-p.
Those commands will move to this position in the line moved to
rather than trying to keep the same horizontal position.
With a non-nil argument, clears out the goal column
so that C-n and C-p resume vertical motion.
temporary-goal-column Variable
Current goal column for vertical motion.
It is the column where point was at the start of current run
of vertical motion commands.
---------- Buffer: *Help* ----------
* Function: Snarf-documentation FILENAME
This function is used only during Emacs initialization. It is
executed before the system dumps a runnable Emacs.
`Snarf-documentation' finds the file-offsets of the documentation
strings stored in the file FILENAME, and records them in the
in-core function definitions in place of the documentation strings.
FILENAME is found in the `emacs/etc' directory (usually FILENAME
is `"DOC-VERSION"'). When the dumped Emacs is later executed, the
file is found in the `exec-directory'.
* Function: substitute-command-keys STRING
This function returns STRING with modifications made to specially
formatted substrings such that the actual (current) keybindings are
listed. This permists the documentation to provide information
that is updated to contain information about the current key
bindings. (The key bindings may change between the time Emacs is
built and the time that the documentation is asked for.)
The following table lists the forms of the special substrings
that are recognized by `substitute-command-keys' and the forms with
which the special substrings are replaced.
`\[COMMAND]'
replaced by either a keystroke sequence that will invoke
COMMAND or `M-x COMMAND' if COMMAND is not bound to a key
sequence.
`\{MAPVAR} '
replaced by a summary (made by `describe-bindings') of the
value of MAPVAR, taken as a keymap.
`\<MAPVAR> '
make `substitute-command-keys' use the value of MAPVAR as the
keymap for future `\[COMMAND]' substrings. This special
string does not produce any replacement text itself; it only
affects the replacements done later.
Note: Each `\' must be doubled when written in a string in
Emacs Lisp.
Here are examples of each special substring:
(substitute-command-keys
"To abort recursive edit, type: \\[abort-recursive-edit]")
=> "To abort recursive edit, type: C-]"
(substitute-command-keys
"The keys which are defined for the minibuffer here are:
\\{minibuffer-local-must-match-map}")
=> "The keys which are defined for the minibuffer here are:
? minibuffer-completion-help
SPC minibuffer-complete-word
TAB minibuffer-complete
LFD minibuffer-complete-and-exit
RET minibuffer-complete-and-exit
C-g abort-recursive-edit
"
(substitute-command-keys
"To abort a recursive edit from the minibuffer, type
\\<minibuffer-local-must-match-map>\\[abort-recursive-edit]")
=> "To abort a recursive edit from the minibuffer, type C-g"
* Function: key-description STRING
This function returns a string for printing the Emacs standard
notation of the characters in STRING. See the examples for
`single-key-description'.
* Function: single-key-description CHARACTER
This function returns a string for printing CHARACTER in the
standard Emacs notation. Normal printing characters don't change,
control characters turn into a string starting with `C-', meta
characters turn into a string starting with `M-', and space,
linefeed, etc. are transformed to SPC, LFD, etc.
(single-key-description ?\C-x)
=> "C-x"
(key-description "\C-x \M-y \n \t \r \f123")
=> "C-x SPC M-y SPC LFD SPC TAB SPC RET SPC C-l 1 2 3"
* Function: text-char-description CHARACTER
This function returns a string for printing CHARACTER. This is
like `single-key-description', except that that control characters
are represented with a leading caret (uparrow).
(text-char-description ?\C-c)
=> "^C"
(text-char-description ?\M-m)
=> "M-m"
(text-char-description ?\C-\M-m)
=> "M-^M"
▶1f◀
File: lispref Node: Help Functions, Prev: Documentation Strings, Up: Documentation
Help Functions
==============
Emacs provides a variety of on-line help functions. You can get to
all of them by typing `C-h' and then a key. Here we describe some
program-level interfaces. For more information about the interactive
help commands, *Note Help: (emacs)Help..
In addition, `M-.' (`find-tag') is often helpful, as it brings you to
the source of a function or variable.
Emacs loads the default help commands from the `emacs/lisp/help.el'
library. In addition, Emacs has a `emacs/lisp/helper.el' library of
utilities. This latter library is for modes that want to provide help
without relinquishing control, such as the `electric' modes. (To
distinguish them from the regular help functions, all the functions in
the `emacs/lisp/helper.el' library have names beginning with `Helper'.)
* Command: apropos REGEXP &optional PREDICATE NOPRINT
This function finds all symbols whose names contain a match for
the regular expression REGEXP, and returns a list of them.
Normally it will also pop up a window with the `*Help*' buffer in
it, displaying the symbols and a one line description. (Since only
the first lines of documentation strings are displayed, try to make
the first lines of your documentation strings whole sentences.) If
NOPRINT is non-`nil', it does not display them, but just returns
the list.
If PREDICATE is non-`nil', then that predicate is called on each
symbol that has matched REGEXP and only symbols for which that
predicate returns a non-`nil' value are listed (and displayed).
When you call `apropos' interactively, Emacs prompts for REGEXP
in the minibuffer.
In the first of the following examples, Emacs finds all the
matches to `exec'. They are returned but not displayed. In the
second example, Emacs finds and returns only those symbols that are
also commands; in addition, they are then displayed in the `*Help*'
buffer.
(apropos "exec" nil t)
=> (Buffer-menu-execute command-execute exec-directory
exec-path execute-extended-command execute-kbd-macro
executing-kbd-macro executing-macro)
(apropos "exec" 'commandp)
=> (Buffer-menu-execute execute-extended-command)
---------- Buffer: *Help* ----------
Buffer-menu-execute
Function: Save and/or delete buffers marked with
M-x Buffer-menu-save or M-x Buffer-menu-delete commands.
execute-extended-command ESC x
Function: Read function name, then read its arguments and call it.
---------- Buffer: *Help* ----------
Typing `C-h a' (`command-apropos') calls `apropos', but the
command only displays information about symbols that are commands.
In the body of the `command-apropos' function, the call to
`apropos' looks like this:
(apropos string 'commandp)
* User Option: completion-auto-help
If this variable is non-`nil', Emacs automatically displays a
list of possible completions, whenever the user asks for completion
but nothing can be completed because the next character is not
unique.
* Function: help-command
This function is a keymap equivalent to `help-map'. It is
defined in `emacs/lisp/help.el' like this:
(define-key global-map "\C-h" 'help-command)
(fset 'help-command help-map)
* Variable: help-map
The value of this variable is a local keymap for characters
following the Help key.
* Function: print-help-return-message &optional FUNCTION
This function builds a message explaining how to restore the
previous state of the windows after a help command. After building
the message, it applies FUNCTION to it if FUNCTION is non-`nil'.
Otherwise it applies `message' to it, thus printing it in the echo
area.
This function expects to be called inside of a
`with-output-to-temp-buffer' special form, and expects the value of
`standard-output' to be the temporary buffer used by that special
form, which is what it will be if you do not change it.
See the example in the section describing the `documentation'
function (*Note Documentation Strings::).
The constructed message will be one of the forms shown below.
(print-help-return-message)
---------- Echo Area ----------
Type C-x 1 to remove help window.
---------- Echo Area ----------
---------- Echo Area ----------
Type C-x 4 b RET to restore old contents of help window.
---------- Echo Area ----------
Also, see the description of `where-is-internal'; this function
returns list of key sequences (of any length) that are bound to
COMMAND in the local keymap and the global keymap. *Note Global
and Local Keymaps::.
The following two functions are found in the library `helper'. You
must load that library with `(require 'helper)' in order to use them.
* Command: Helper-describe-bindings
This command pops up a window displaying the help buffer
containing a listing of all of the key bindings from both the local
and global keymaps. It works by calling `describe-bindings'.
* Command: Helper-help
This command provides help for the current mode. It prompts the
user in the minibuffer with a message: `Help (Type ? for further
options)', and then provides assistance for finding out what the
key bindings are, and what the mode is intended for. It returns
`nil'.
This can be customized by changing the map `Helper-help-map'.
* Variable: help-char
The value of this variable is the character that Emacs recognizes
as meaning Help. When Emacs reads this character (which is usually
8, the value of `C-h'), Emacs evaluates `(eval help-form)', and
displays the result if it is a string. If `help-form''s value is
`nil', this character is read normally.
* Variable: help-form
The value of this variable is a form to execute when the
character `help-char' is read. If the form returns a string, that
string is displayed. If `help-form' is `nil', then the help
character is not recognized.
▶1f◀
File: lispref Node: Files, Prev: Documentation, Up: Top, Next: Backups and Auto Saving
Files
*****
In Emacs, you can find, create, view, save, and otherwise work with
files and directories. Not all of the file-related functions are
described in this chapter; some are described in *Note Buffers::; and,
functions related to backups and auto saving are described in *Note
Backups and Auto Saving::.
* Menu:
* Visiting Files::
* Saving Buffers::
* Reading from Files::
* Writing to Files::
* File Locks::
* Information about Files::
* Contents of Directories::
* Changing File Names and Attributes::
* File Names::
▶1f◀
File: lispref Node: Visiting Files, Prev: Files, Up: Files, Next: Saving Buffers
Visiting Files
==============
Visiting a file means reading a file into a buffer. Once this is
done, we say that the buffer is "visiting" that file, and call the file
``the visited file'' of the buffer.
A file and a buffer are two different entities. A file is information
recorded permanently in the computer (unless you delete it). A buffer,
on the other hand, is information inside of Emacs that will vanish at
the end of the editing session (or when you kill the buffer). Usually,
a buffer contains information that you have copied from a file; thus, we
say the buffer is visiting that file. This copy is what you work on and
modify. Changes to the buffer do not change the file, until you save
the file. When you save the file, the buffer is copied to the file and
is thus saved permanently.
In spite of the distinction between files and buffers, people often
refer to a file when they mean a buffer and vice-versa. Indeed, most
people say, ``I am editing a file,'' rather than saying, ``I am editing
a buffer which I will soon save as a file of the same name.'' It is
almost always clear from context what people mean. When dealing with a
computer program, however, it is well to keep the distinction in mind,
since the computer is not as smart as a person.
For historical reasons, these functions are called `find-...', rather
than `visit-...'.
*Note Buffer File Name::, for functions and variables that relate to
the visited file name of a buffer.
* Command: find-file FILENAME
This function reads FILENAME into a buffer and displays that
buffer in the selected window, in which the user may edit it.
The body of the `find-file' function is very simple and looks like
this:
(switch-to-buffer (find-file-noselect filename))
(See `switch-to-buffer' in *Note Changing Buffers::.)
When `find-file' is called interactively, Emacs prompts for
FILENAME in the minibuffer.
* Function: find-file-noselect FILENAME
This function is the guts of all the file-visting functions. It
reads a file into a buffer and returns the buffer. You may then
display the buffer in a window if you wish, but this function does
not do so. The buffer is not made the current buffer. (If you
wish to edit the file, you have to switch to it.)
If no buffer is currently visiting FILENAME, then one is created
and the file is visited. If FILENAME does not exist, it is created
as empty, and Emacs displays a message `New file' in the echo area.
If a buffer is already visiting FILENAME, then
`find-file-noselect' verifies that the file has not changed since
it was last visited or saved, and returns that buffer. If the file
has changed, then this function offers to re-read the changed file.
If the user says `yes', any changes previously made in the buffer
will be lost.
The `find-file-noselect' function calls `after-find-file' after
the file is found. The `after-find-file' function sets the buffer
major mode, parses local variables, warns the user if there exists
an auto-save file more recent than the file just visited, and
finishes by running the hooks in `find-file-hooks'.
The `find-file-noselect' function returns the buffer visiting the
file.
(find-file-noselect "foo")
=> #<buffer foo>
Note that the `find-file-noselect' function checks whether a
buffer is already visiting FILENAME; if it is, the function
verifies that the file has not changed since it was last visited or
saved, and returns that buffer. If the file has changed, Emacs
offers to read in the changed file. If the user says `yes', any
changes made to the buffer will be lost.
* Command: find-alternate-file FILENAME
This function reads in the file FILENAME, and selects its buffer,
killing the previous buffer. If your current buffer contains an
empty file that you just visited by mistake, use this command to
visit the file you really want.
When this function is called interactively, Emacs prompts you for
FILENAME.
* Command: find-file-other-window FILENAME
This function visits the file FILENAME, and displays its buffer
in a window other than the selected window. If there are two or
more windows on the screen, then the non-selected window will be
used. If there is only one window, it will be split. The function
returns `nil'.
When this function is called interactively, Emacs prompts for
FILENAME.
* Command: find-file-read-only FILENAME
This function visits the file named FILENAME and selects its
buffer, just like `find-file', but it marks the buffer as
read-only. *Note Read Only Buffers::, for related functions and
variables.
When this function is called interactively, Emacs prompts for
FILENAME.
* Command: view-file FILENAME
This function views FILENAME in "View mode", returning to the
previous buffer when done. View mode is a mode that allows you to
skim rapidly through the file but does not let you modify it.
After loading the file, `view-file' calls the value of
`view-hook' if that is non-`nil'.
When this function is called interactively, Emacs prompts for
FILENAME in the minibuffer.
* Variable: find-file-hooks
The value of this variable is a list of functions to be called
after a file is visited. The file's local-variables specification
(if any) will have been processed before the hooks are run. The
buffer visiting the file is current when the hooks are fun.
* Variable: find-file-not-found-hooks
The value of this variable is a list of functions to be called
when `find-file' or `find-file-noselect' is passed a nonexistent
FILENAME. These functions are called as soon as the error is
detected. `buffer-file-name' is already set up. The functions are
called in the order given, until one of them returns non-`nil'.
* Menu:
* Subroutines of Visiting::
▶1f◀
File: lispref Node: Subroutines of Visiting, Prev: Visiting Files, Up: Visiting Files
Subroutines of Visiting
-----------------------
The `find-file-noselect' function uses the `after-find-file' and
`create-file-buffer' functions.
* Function: after-find-file &optional ERROR WARN
This function is called by `find-file-noselect' and by the
default revert function (*Note Reverting::). It sets the buffer
major mode, and parses local variables.
If there was an error in opening the file, the calling function
should pass ERROR a non-`nil' value. In that case,
`after-find-file' issues a warning: `(New File)'. Note that, for
serious errors, you would not even call `after-find-file'. Only
``file not found'' errors get here with a non-`nil' ERROR.
If WARN is non-`nil', then Emacs will issue a warning if there
exists an auto-save file more recent than the visited file.
The last thing `after-find-file' does is call all the functions
in `find-file-hooks'.
* Function: create-file-buffer FILENAME
This function creates a suitably named buffer for visiting
FILENAME, and returns it. The string FILENAME (sans directory) is
used unchanged if that name is free; otherwise a string such as
`<2>' is appended to get an unused name. Also *Note Creating
Buffers::.
Note: `create-file-buffer' does *not* associate the new buffer
with any file and does not make it the current buffer.
(create-file-buffer "foo")
=> #<buffer foo>
(create-file-buffer "foo")
=> #<buffer foo<2>>
(create-file-buffer "foo")
=> #<buffer foo<3>>
This function is used by `find-file-noselect'.
▶1f◀
File: lispref Node: Saving Buffers, Prev: Visiting Files, Up: Files, Next: Reading from Files
Saving Buffers
==============
When you work on a file in Emacs, you are actually working on a buffer
that is visiting that file---that is, the contents of the file are
copied into the buffer and the copy is what you work on and modify.
Changes to the buffer do not change the file, until you save the buffer
as a newly written file. The save buffer commands do this.
* Command: save-buffer &optional BACKUP-OPTION
This function saves the contents of the current buffer in its
visited file if the buffer has been modified. Otherwise, it does
nothing.
If BACKUP-OPTION is `nil', the `save-buffer' function make a
backup file only if this is the first save or if the buffer was
previously modified.
The `save-buffer' function is designed for interactive use; and
the value of BACKUP-OPTION then depends of the number of `C-u'
keystrokes prefixing the `save-buffer' command.
* With 1 or 3 `C-u''s, the `save-buffer' function marks this
version of the buffer to be backed up.
* With 2 or 3 `C-u''s, the `save-buffer' function
unconditionally backs up previous version.
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. A
non-numbered backup file is called `foo~'.
Numeric backups (rather than `foo~') will be made if the value of
`version-control' is not the symbol `never', and either there are
already numeric versions of the file being backed up or else
`version-control' is non-`nil'. (Thus, numeric backups will be
kept if the value of `version-control' is `t'.)
`dired-kept-versions' controls `dired''s `dired-clean-directory'
(`.') command. No one wants to save too many versions of a file,
since that takes up too much disk space. The variable
`kept-old-versions' tells the system how many of the oldest
versions to keep; and the variable `kept-new-versions' tells the
system how many new versions to keep. The defaults values are two
old versions and two new. Thus, if you had made a total of 77
versions of `foo', your directory would contain `foo.~1~',
`foo.~2~', `foo.~75~', `foo.~76~', and `foo', the current version.
If the value of the `trim-versions-without-asking' variable is
`nil', the system queries the user before deleting excess versions.
Otherwise it does it silently.
* Command: save-buffers-kill-emacs &optional KILL-SILENTLY-P
This function offers to save each buffer that needs to be saved,
and then kills this Emacs session. Called with a non-`nil' value
of the optional KILL-SILENTLY-P argument, this function saves all
the file-visiting buffers without querying the user or displaying
any message about saving, and then kills the session.
The body of the `save-buffers-kill-emacs' function consists of the
two following lines:
(save-some-buffers arg t)
(kill-emacs)
* Command: save-some-buffers &optional SAVE-SILENTLY-P EXITING
This command saves some modified file-visiting buffers.
Normally, Emacs asks the user about each buffer. If the function
is called with a non-`nil' value of the optional SAVE-SILENTLY-P
argument, this function saves all the file-visiting buffers without
querying the user.
The optional EXITING argument is for non-interactive use only; it
is set by the `save-buffers-kill-emacs' function and causes Emacs
to offer to save even certain buffers that are not visiting files,
as well. These are buffers that have a non-`nil' local value of
`buffer-offer-save'.
* Variable: buffer-offer-save
When this variable is non-`nil' in a buffer, Emacs offers to save
the buffer on exit even if the buffer is not visiting a file. The
variable is automatically local in all buffers. Normally, Mail
mode (used for editing outgoing mail) sets this to `t'.
* Command: write-file FILENAME
This function writes the current buffer into file FILENAME, makes
the buffer visit that file, and marks it not modified.
* Variable: write-file-hooks
The value of this variable is a list of functions to be called
before writing out a buffer to its visited file. If one of them
returns non-`nil', the file is considered already written and the
rest are not called, nor is the usual code for writing the file
executed.
If the `file-precious-flag' variable is `nil', the file is moved
to the backup file before any of the hooks are called, so if none
of the hooks save the file, but one returns non-`nil', the file
will not exist, although the backup will.
Here is an example of how to add a hook to the `write-file-hooks'
just once.
(or (memq 'my-write-file-hook write-file-hooks)
(setq write-file-hooks
(cons 'my-write-file-hook write-file-hooks)))
* Variable: file-precious-flag
If this global variable is non-`nil', then `save-buffer' protects
against I/O errors while saving files, by renaming the original
file to a temporary name before writing the new contents of the
file. If the new contents are successfully written, the renamed
original file is deleted. Otherwise, it is renamed back to the
original name. This procedure prevents problems such as a lack of
disk space from resulting in an invalid file.
Some modes set this non-`nil' locally in particular buffers.
* User Option: require-final-newline
This global variable determines whether files may be written out
that do *not* end with a newline. If the value of the variable is
`t', then Emacs silently puts a newline at the end of the file
whenever the file being saved does not already end in one. If the
value of the variable is non-`nil', but not `t', then Emacs asks
the user whether to add a newline in each such case.
If the value of the variable is `nil', then Emacs doesn't add
newlines at all. `nil' is the default value, but a few major modes
change it to `t'.
▶1f◀
File: lispref Node: Reading from Files, Prev: Saving Buffers, Up: Files, Next: Writing to Files
Reading from Files
==================
You can copy a file directly from the disk and insert it into a buffer
using the `insert-file-contents' function, or its interactive envelope,
`insert-file'.
* Command: insert-file FILENAME
This function inserts the contents of file FILENAME into the
current buffer after the point. It is an error if FILENAME is not
a readable file. This is for interactive use and does little more
than call `insert-file-contents'.
* Function: insert-file-contents FILENAME VISIT
This function inserts the contents of file FILENAME into the
current buffer after the point. If VISIT is non-`nil', the
buffer's visited filename and last save file modtime are set, and
it is marked unmodified, so that it is now visiting the file
FILENAME.
It is an error if FILENAME is not a readable file.
This function returns a list of the absolute file name and the
length of the data inserted.
▶1f◀
File: lispref Node: Writing to Files, Prev: Reading from Files, Up: Files, Next: File Locks
Writing to Files
================
You can write the contents of a buffer, or part of a buffer, directly
to a file on disk using the `append-to-file' and `write-region'
functions. Normally, this is done for files not visited by the buffer
in question.
* Command: append-to-file START END FILENAME
This function appends the contents of the region delimited by
START and END in the current buffer to the end of file FILENAME.
If that file does not exist, it is created.
This function returns `nil'.
It is an error if FILENAME does not specify a (possibly
non-existent) file which is writable in an existing directory.
* Command: write-region START END FILENAME &optional APPEND VISIT
This function writes the region (of the current buffer) delimited
by START and END into the file specified by FILENAME.
If APPEND is non-`nil', then the region will be appended to the
existing file contents (if any).
If VISIT is `t', then Emacs establishes an association between the
buffer and the file: the buffer is then visiting that file. It
also sets the last file modification time for the current buffer to
FILENAME's modtime, and marks the buffer as not modified.
Normally, this function prints a message `Wrote file FILENAME' in
the echo area. If VISIT is neither `t' nor `nil', then this
message is inhibited. This feature is useful for programs which
use files for internal purposes, files which the user does not need
to know about.
▶1f◀
File: lispref Node: File Locks, Prev: Writing to Files, Up: Files, Next: Information about Files
File Locks
==========
When two different people attempt to modify and save the same file at
the same time, the changes made by one person are lost as the changes
made by the other overwrite them. File locks are used to help avoid
such an unfortunate occurrence. Instead of destroying on person's work,
Emacs, aided by locks, will ask you what to do.
* Function: file-locked-p FILENAME
This function returns `nil' if the FILENAME is not locked by this
Emacs process. It returns `t' if it is locked by this Emacs, and
it returns the name of the user who has locked it if it is locked
by someone else.
(file-locked-p "foo")
=> nil
* Function: lock-buffer &optional FILENAME
This function locks FILENAME, if the current buffer is modified.
FILENAME defaults to the current buffer's visited file. Nothing is
done if the current buffer is not visiting a file, or is not
modified.
* Function: unlock-buffer
This function unlocks the file being visited in the current buffer,
if the buffer is modified. If the buffer is not modified, then the
file should not be locked, so this function does nothing. It also
does nothing if the current buffer is not visiting a file.
* Function: ask-user-about-lock FILE OTHER-USER
This function asks the user what to do when he or she has asked
to edit FILE but it is locked by OTHER-USER.
Depending on the user's answer, the `ask-user-about-lock'
function will do one of the following:
* The function may return `t', which grabs the lock on the file;
in this case the user may edit the file; and it becomes locked
to OTHER-USER.
* The function may return `nil', which allows the user to edit
the file even though it is locked.
* The function may signal a `file-locked' error, in which case
the user is refraining from editing the file. In this case,
Emacs displays the following error message:
error--> "File is locked" FILE OTHER-USER
where `file' is the name of the file and OTHER-USER is the
name of the user who has locked the file.
If you wish, you can replace the `ask-user-about-lock' function
with your own version that does what you prefer. The code for its
usual definition is in `userlock.el'.
▶1f◀
File: lispref Node: Information about Files, Prev: File Locks, Up: Files, Next: Contents of Directories
Information about Files
=======================
The functions described in this section are similar in as much as they
all operate on strings which are interpreted as file names. All have
names that begin with the word `file'. These functions all return
information about actual files or directories, so their arguments must
all exist as actual files or directories unless otherwise noted.
Most of the file-oriented functions take a single argument, FILENAME,
which must be a string. The file name is expanded using
`expand-file-name', so `~' is handled correctly, as are relative file
names (including `../'). Environment variables in filenames, such as
`$HOME', etc., are not substituted by these functions.
* Menu:
* Testing Accessibility::
* Distinguishing Kinds of Files::
* File Attributes::
▶1f◀
File: lispref Node: Testing Accessibility, Prev: Information about Files, Up: Information about Files, Next: Distinguishing Kinds of Files
Testing Accessibility
---------------------
* Function: file-exists-p FILENAME
This function returns `t' if a file named FILENAME exists. This
does not mean you can necessarily read the file, only that you can
do a directory listing on the directory which it is in.
If you do not have permission to do a directory listing on the
directory containing FILENAME, then the result will be `nil'.
* Function: file-readable-p FILENAME
This function returns `t' if a file named FILENAME exists and you
can read it. It returns `nil' otherwise.
(file-readable-p "file.texinfo")
=> t
(file-exists-p "/usr/spool/mqueue")
=> t
(file-readable-p "/usr/spool/mqueue")
=> nil
* Function: file-writable-p FILENAME
This functions returns `t' if FILENAME can be written or created
by you. It is writable if the file exists and you can write it.
It is creatable if the file does not exist, but the directory it
would be in does exist and you can write in that directory.
`file-writable-p' returns `nil' otherwise.
In the third example below, `foo' is not writable because the
parent directory does not exist, even though the user could create
it.
(file-writable-p "~rms/foo")
=> t
(file-writable-p "/foo")
=> nil
(file-writable-p "~rms/no-such-dir/foo")
=> nil
* Function: file-newer-than-file-p FILENAME1 FILENAME2
This functions returns `t' if the file FILENAME1 is newer than
file FILENAME2. If FILENAME1 does not exist, it returns `nil'. If
FILENAME2 does not exist, it returns `t'.
In the example, assume that the file `aug-19' was written on the
19th, and `aug-20' was written on the 20th. The file `no-file'
doesn't exist at all.
(file-newer-than-file-p "aug-19" "aug-20")
=> nil
(file-newer-than-file-p "aug-20" "aug-19")
=> t
(file-newer-than-file-p "aug-19" "no-file")
=> t
(file-newer-than-file-p "no-file" "aug-19")
=> nil
▶1f◀
File: lispref Node: Distinguishing Kinds of Files, Prev: Testing Accessibility, Up: Information about Files, Next: File Attributes
Distinguishing Kinds of Files
-----------------------------
* Function: file-symlink-p FILENAME
If FILENAME is a symbolic link, the `file-symlink-p' function
returns the file name to which it is linked. This may be the name
of a text file, a directory, or even another symbolic link, or of
no file at all.
If FILENAME is not a symbolic link (or there is no such file),
`file-symlink-p' returns `nil'.
(file-symlink-p "foo")
=> nil
(file-symlink-p "sym-link")
=> "foo"
(file-symlink-p "sym-link2")
=> "sym-link"
(file-symlink-p "/bin")
=> "/pub/bin"
* Function: file-directory-p FILENAME
This function returns `t' if FILENAME is the name of an existing
directory, `nil' otherwise.
(file-directory-p "~rms")
=> t
(file-directory-p "~rms/lewis/file.texinfo")
=> nil
(file-directory-p "~rms/lewis/no-such-file")
=> nil
(file-directory-p "$HOME")
=> nil
(file-directory-p (substitute-in-file-name "$HOME"))
=> t
▶1f◀
File: lispref Node: File Attributes, Prev: Distinguishing Kinds of Files, Up: Information about Files
Other Information about Files
-----------------------------
* Function: file-attributes FILENAME
This function returns a list of attributes of file FILENAME. If
the specified file cannot be opened, it returns `nil'.
The elements of the list, in order, are:
1. `t' for a directory, a string for a symbolic link (the name
linked to), or `nil' for a text file.
2. The number of links to the file.
3. The file's UID.
4. The file's GID.
5. The time of last access, as a list of two integers. The first
integer has the high-order 16 bits of time, the second has the
low 16 bits.
6. The time of last modification as a list of two integers (see
above).
7. The time of last status change as a list of two integers (see
above).
8. The size of the file in bytes.
9. The file's modes, as a string of ten letters or dashes as in
`ls -l'.
10. `t' if the file's GID would change if file were deleted and
recreated.
11. The file's inode number.
For example, here are the file attributes for `file.texinfo':
(file-attributes "file.texinfo")
=> (nil
1
2235
75
(8489 20284)
(8489 20284)
(8489 20285)
14906
"-rw-rw-rw-"
nil
20920)
and here is how the result is interpreted:
`nil'
is neither a directory nor a symbolic link.
`1'
has only one link to it, the name `file.texinfo'.
`2235'
is owned by the user with UID 2235.
`75'
is in the group with GID 75
`(8489 20284)'
was last accessed on Aug 19 00:09. Unfortunately, you cannot
convert this number into a time string in Emacs.
`(8489 20284)'
was last accessed on Aug 19 00:09. Unfortunately, you cannot
convert this number into a time string in Emacs.
`(8489 20285'
last had its inode changed on Aug 19 00:09. Unfortunately,
you cannot convert this number into a time string in Emacs.
`14906'
has 14906 characters in it.
`-rw-rw-rw-'
has a mode of read and write access for the owner, group, and
world.
`nil'
would retain the same `gid' if it were recreated.
`20920'
has an inode number of 20920
* Function: file-modes FILE-NAME
This function returns the mode bits of FILE-NAME, as a decimal
integer. The mode bits are the usual Unix mode bits. If the
low-order bit is 1, then the file is executable by others, if the
second lowest-order bit is 1, then the file is writable by others,
etc.
The highest value returnable is 4095 (7777 octal), meaning that
everyone has read, write, and execute permission, that the file has
the SUID bit set for both others and group, and that the file has
the sticky bit set.
(file-modes "~/junk/diffs")
=> 492 ; decimal integer
(format "%o" 492)
-| 754 ; convert to octal
(set-file-modes "~/junk/diffs" 4095)
=> nil
% ls -l diffs
=> -rwxr-xr-- 1 lewis 0 3063 Oct 30 16:00 diffs
* Function: file-nlinks FILENAME
This functions returns the number of names (i.e., hard links)
that file FILENAME has. If the file does not exist, then this
function returns `nil'.
% ls -l foo*
-rw-rw-rw- 2 rms 4 Aug 19 01:27 foo
-rw-rw-rw- 2 rms 4 Aug 19 01:27 foo1
(file-nlinks "foo")
=> 2
(file-nlinks "doesnt-exist")
=> nil
▶1f◀
File: lispref Node: Contents of Directories, Prev: Information about Files, Up: Files, Next: Changing File Names and Attributes
Contents of Directories
=======================
A directory is a kind of file which contains other files entered under
various names. Directories belong to Unix, not to Emacs.
Emacs 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, Emacs will 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
This function returns a list of the names of the files in the
directory DIRECTORY.
If FULL-NAME is non-`nil', the function returns the files' absolute
file names. Otherwise, if MATCH-REGEXP is non-`nil', function
returns only those file names that contain that regular
expression---the other file names are discarded from the list.
(directory-files "~lewis")
=> ("#foo#" "#foo.el#" "." ".."
"dired-mods.el" "file.texinfo" "file.texinfo.~1~")
It is an error if DIRECTORY is not the name of a readable
directory.
* Function: file-name-all-versions FILE DIRNAME
This function returns a list of all versions of the file named
FILE in directory DIRNAME.
* Command: list-directory DIRNAME &optional VERBOSE
This command displays a list of files in or matching DIRNAME. It
calls the shell command `ls', optionally passing it an appropriate
switch.
Wildcards in DIRNAME are processed by the shell.
A prefix argument (the function's second argument if it is called
noninteractively) causes the function to pass the value of
`list-directory-verbose-switches' to `ls' as a switch. Otherwise,
the function passes `list-directory-brief-switches' to `ls'.
* Variable: list-directory-brief-switches
This variable contains switches for `list-directory' to pass to
`ls' for a short or `brief' listing. The default value is `"-CF"'.
* Variable: list-directory-verbose-switches
This variable contains switches for `list-directory' to pass to
`ls' for a verbose or `long' listing. The default value is `"-l"'.
* Variable: default-directory
The value of this buffer-local variable is the default directory
for the current buffer. This is always a string ending with a
slash on Unix systems.
default-directory
=> "/user/lewis/manual/"
▶1f◀