visited in the current buffer, or @code{nil} if no file is visited.
It is a permanent local, unaffected by
@code{kill-all-local-variables}. @xref{Truenames}, and
-@ref{Definition of abbreviate-file-name}.
+@ref{abbreviate-file-name}.
@end defvar
@defvar buffer-file-number
last file modification time, after which @code{visited-file-modtime}
returns zero.
-@c Wordy to avoid overfull hbox. --rjc 16mar92
-When the function @code{set-visited-file-name} is called interactively, it
-prompts for @var{filename} in the minibuffer.
+When the function @code{set-visited-file-name} is called
+interactively, it prompts for @var{filename} in the minibuffer.
@end deffn
@defvar list-buffers-directory
This command switches to the last buffer in the local buffer list of
the selected frame. More precisely, it calls the function
@code{switch-to-buffer} (@pxref{Switching Buffers}), to display the
-buffer returned by @code{last-buffer}, see above, in the selected
+buffer returned by @code{last-buffer} (see above), in the selected
window.
@end deffn
@defun generate-new-buffer name
This function returns a newly created, empty buffer, but does not make
-it current. If there is no buffer named @var{name}, then that is the
-name of the new buffer. If that name is in use, this function adds
-suffixes of the form @samp{<@var{n}>} to @var{name}, where @var{n} is an
-integer. It tries successive integers starting with 2 until it finds an
-available name.
+it current. The name of the buffer is generated by passing @var{name}
+to the function @code{generate-new-buffer-name} (@pxref{Buffer
+Names}). Thus, if there is no buffer named @var{name}, then that is
+the name of the new buffer; if that name is in use, a suffix of the
+form @samp{<@var{n}>}, where @var{n} is an integer, is appended to
+@var{name}.
An error is signaled if @var{name} is not a string.
The major mode for the new buffer is set to Fundamental mode. The default
value of the variable @code{major-mode} is handled at a higher level.
@xref{Auto Major Mode}.
-
-See the related function @code{generate-new-buffer-name} in @ref{Buffer
-Names}.
@end defun
@node Killing Buffers
distinct according to @code{eq} although both are dead.
If you kill a buffer that is current or displayed in a window, Emacs
-automatically selects or displays some other buffer instead. This means
-that killing a buffer can in general change the current buffer.
-Therefore, when you kill a buffer, you should also take the precautions
+automatically selects or displays some other buffer instead. This
+means that killing a buffer can change the current buffer. Therefore,
+when you kill a buffer, you should also take the precautions
associated with changing the current buffer (unless you happen to know
that the buffer being killed isn't current). @xref{Current Buffer}.
If you kill a buffer that is the base buffer of one or more indirect
-buffers, the indirect buffers are automatically killed as well.
-
- The @code{buffer-name} of a killed buffer is @code{nil}. You can use
-this feature to test whether a buffer has been killed:
+@iftex
+buffers,
+@end iftex
+@ifnottex
+buffers (@pxref{Indirect Buffers}),
+@end ifnottex
+the indirect buffers are automatically killed as well.
-@example
-@group
-(defun buffer-killed-p (buffer)
- "Return t if BUFFER is killed."
- (not (buffer-name buffer)))
-@end group
-@end example
+@cindex live buffer
+ The @code{buffer-name} of a buffer is @code{nil} if, and only if,
+the buffer is killed. A buffer that has not been killed is called a
+@dfn{live} buffer. To test whether a buffer is live or killed, use
+the function @code{buffer-live-p} (see below).
@deffn Command kill-buffer &optional buffer-or-name
This function kills the buffer @var{buffer-or-name}, freeing all its
buffer.
Any processes that have this buffer as the @code{process-buffer} are
-sent the @code{SIGHUP} signal, which normally causes them to terminate.
-(The basic meaning of @code{SIGHUP} is that a dialup line has been
-disconnected.) @xref{Signals to Processes}.
+sent the @code{SIGHUP} (``hangup'') signal, which normally causes them
+to terminate. @xref{Signals to Processes}.
If the buffer is visiting a file and contains unsaved changes,
@code{kill-buffer} asks the user to confirm before the buffer is killed.
@end defvar
@defun buffer-live-p object
-This function returns @code{t} if @var{object} is a buffer which has
-not been killed, @code{nil} otherwise.
+This function returns @code{t} if @var{object} is a live buffer (a
+buffer which has not been killed), @code{nil} otherwise.
@end defun
@node Indirect Buffers
This section explains how to search for a file in a list of
directories (a @dfn{path}), or for an executable file in the standard
-list of executable file directories, or for an Emacs-specific user
-configuration file.
+list of executable file directories.
+
+ To search for a user-specific configuration file, @xref{Standard
+File Names}, for the @code{locate-user-emacs-file} function.
@defun locate-file filename path &optional suffixes predicate
This function searches for a file whose name is @var{filename} in a
@code{exec-suffixes} (@pxref{Subprocess Creation}).
@end defun
-@defun locate-user-emacs-file base-name &optional old-name
-This function returns an absolute file name for an Emacs-specific
-configuration or data file. The argument @file{base-name} should be a
-relative file name. The return value is the absolute name of a file
-in the directory specified by @code{user-emacs-directory}; if that
-directory does not exist, this function creates it.
-
-If the optional argument @var{old-name} is non-@code{nil}, it
-specifies a file in the user's home directory,
-@file{~/@var{old-name}}. If such a file exists, the return value is
-the absolute name of that file, instead of the file specified by
-@var{base-name}. This argument is intended to be used by Emacs
-packages to provide backward compatibility. For instance, prior to
-the introduction of @code{user-emacs-directory}, the abbrev file was
-located in @file{~/.abbrev_defs}, so the definition of
-@code{abbrev-file-name} is
-
-@example
-(defcustom abbrev-file-name
- (locate-user-emacs-file "abbrev_defs" ".abbrev_defs")
- "Default name of file from which to read abbrevs."
- @dots{}
- :type 'file)
-@end example
-@end defun
-
@node Changing Files
@section Changing File Names and Attributes
@c @cindex renaming files Duplicates rename-file
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 @dfn{absolute}
-file name. Or it can specify the position of the file in the tree
-relative to a default directory; then it is called a @dfn{relative} file
-name. On Unix and GNU/Linux, an absolute file name starts with a slash
-or a tilde (@samp{~}), and a relative one does not. On MS-DOS and
-MS-Windows, an absolute file name starts with a slash or a backslash, or
-with a drive specification @samp{@var{x}:/}, where @var{x} is the
-@dfn{drive letter}.
+starting from the root of the tree; then it is called an
+@dfn{absolute} file name. Or it can specify the position of the file
+in the tree relative to a default directory; then it is called a
+@dfn{relative} file name. On Unix and GNU/Linux, an absolute file
+name starts with a @samp{/} or a @samp{~}
+(@pxref{abbreviate-file-name}), and a relative one does not. On
+MS-DOS and MS-Windows, an absolute file name starts with a slash or a
+backslash, or with a drive specification @samp{@var{x}:/}, where
+@var{x} is the @dfn{drive letter}.
@defun file-name-absolute-p filename
This function returns @code{t} if file @var{filename} is an absolute
To convert a directory name to its abbreviation, use this
function:
+@cindex file name abbreviations
+@cindex abbreviated file names
@defun abbreviate-file-name filename
-@anchor{Definition of abbreviate-file-name}
+@anchor{abbreviate-file-name}
This function returns an abbreviated form of @var{filename}. It
applies the abbreviations specified in @code{directory-abbrev-alist}
(@pxref{File Aliases,,File Aliases, emacs, The GNU Emacs Manual}),
@subsection Functions that Expand Filenames
@cindex expansion of file names
- @dfn{Expansion} of a file name means converting a relative file name
-to an absolute one. Since this is done relative to a default directory,
-you must specify the default directory name as well as the file name to
-be expanded. Expansion also simplifies file names by eliminating
-redundancies such as @file{./} and @file{@var{name}/../}.
+ @dfn{Expanding} a file name means converting a relative file name to
+an absolute one. Since this is done relative to a default directory,
+you must specify the default directory name as well as the file name
+to be expanded. It also involves expanding abbreviations like
+@file{~/}
+@ifnottex
+(@pxref{abbreviate-file-name}),
+@end ifnottex
+and eliminating redundancies like @file{./} and @file{@var{name}/../}.
@defun expand-file-name filename &optional directory
This function converts @var{filename} to an absolute file name. If
@node Standard File Names
@subsection Standard File Names
- Most of the file names used in Lisp programs are entered by the user.
-But occasionally a Lisp program needs to specify a standard file name
-for a particular use---typically, to hold customization information
-about each user. For example, abbrev definitions are stored (by
-default) in the file @file{~/.abbrev_defs}; the @code{completion}
-package stores completions in the file @file{~/.completions}. These are
-two of the many standard file names used by parts of Emacs for certain
-purposes.
-
- Various operating systems have their own conventions for valid file
-names and for which file names to use for user profile data. A Lisp
-program which reads a file using a standard file name ought to use, on
-each type of system, a file name suitable for that system. The function
-@code{convert-standard-filename} makes this easy to do.
+ Sometimes, an Emacs Lisp program needs to specify a standard file
+name for a particular use---typically, to hold configuration data
+specified by the current user. Usually, such files should be located
+in the directory specified by @code{user-emacs-directory}, which is
+@file{~/.emacs.d} by default (@pxref{Init File}). For example, abbrev
+definitions are stored by default in @file{~/.emacs.d/abbrev_defs}.
+The easiest way to specify such a file name is to use the function
+@code{locate-user-emacs-file}.
-@defun convert-standard-filename filename
-This function alters the file name @var{filename} to fit the conventions
-of the operating system in use, and returns the result as a new string.
-@end defun
+@defun locate-user-emacs-file base-name &optional old-name
+This function returns an absolute file name for an Emacs-specific
+configuration or data file. The argument @file{base-name} should be a
+relative file name. The return value is the absolute name of a file
+in the directory specified by @code{user-emacs-directory}; if that
+directory does not exist, this function creates it.
- The recommended way to specify a standard file name in a Lisp program
-is to choose a name which fits the conventions of GNU and Unix systems,
-usually with a nondirectory part that starts with a period, and pass it
-to @code{convert-standard-filename} instead of using it directly. Here
-is an example from the @code{completion} package:
+If the optional argument @var{old-name} is non-@code{nil}, it
+specifies a file in the user's home directory,
+@file{~/@var{old-name}}. If such a file exists, the return value is
+the absolute name of that file, instead of the file specified by
+@var{base-name}. This argument is intended to be used by Emacs
+packages to provide backward compatibility. For instance, prior to
+the introduction of @code{user-emacs-directory}, the abbrev file was
+located in @file{~/.abbrev_defs}. Here is the definition of
+@code{abbrev-file-name}:
@example
-(defvar save-completions-file-name
- (convert-standard-filename "~/.completions")
- "*The file name to save completions to.")
+(defcustom abbrev-file-name
+ (locate-user-emacs-file "abbrev_defs" ".abbrev_defs")
+ "Default name of file from which to read abbrevs."
+ @dots{}
+ :type 'file)
@end example
+@end defun
- On GNU and Unix systems, and on some other systems as well,
-@code{convert-standard-filename} returns its argument unchanged. On
-some other systems, it alters the name to fit the system's conventions.
-
- For example, on MS-DOS the alterations made by this function include
-converting a leading @samp{.} to @samp{_}, converting a @samp{_} in the
-middle of the name to @samp{.} if there is no other @samp{.}, inserting
-a @samp{.} after eight characters if there is none, and truncating to
-three characters after the @samp{.}. (It makes other changes as well.)
-Thus, @file{.abbrev_defs} becomes @file{_abbrev.def}, and
-@file{.completions} becomes @file{_complet.ion}.
+ A lower-level function for standardizing file names, which
+@code{locate-user-emacs-file} uses as a subroutine, is
+@code{convert-standard-filename}.
+
+@defun convert-standard-filename filename
+This function returns a file name based on @var{filename}, which fits
+the conventions of the current operating system.
+
+On GNU and Unix systems, this simply returns @var{filename}. On other
+operating systems, it may enforce system-specific file name
+conventions; for example, on MS-DOS this function performs a variety
+of changes to enforce MS-DOS file name limitations, including
+converting any leading @samp{.} to @samp{_} and truncating to three
+characters after the @samp{.}.
+
+The recommended way to use this function is to specify a name which
+fits the conventions of GNU and Unix systems, and pass it to
+@code{convert-standard-filename}.
+@end defun
@node Contents of Directories
@section Contents of Directories
projects / emacs.git / commitdiff