@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990-1995, 1998-1999, 2001-2011
+@c Copyright (C) 1990-1995, 1998-1999, 2001-2012
@c Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
-@setfilename ../../info/files
@node Files, Backups and Auto-Saving, Documentation, Top
@comment node-name, next, previous, up
@chapter Files
- In Emacs, you can find, create, view, save, and otherwise work with
-files and file directories. This chapter describes most of the
-file-related functions of Emacs Lisp, but a few others are described in
+ This chapter describes the Emacs Lisp functions and variables to
+find, create, view, save, and otherwise work with files and file
+directories. A few other file-related functions are described in
@ref{Buffers}, and those related to backups and auto-saving are
described in @ref{Backups and Auto-Saving}.
names. A file name is actually a string. Most of these functions
expand file name arguments by calling @code{expand-file-name}, so that
@file{~} is handled correctly, as are relative file names (including
-@samp{../}). These functions don't recognize environment variable
-substitutions such as @samp{$HOME}. @xref{File Name Expansion}.
+@samp{../}). @xref{File Name Expansion}.
+
+ In addition, certain @dfn{magic} file names are handled specially.
+For example, when a remote file name is specified, Emacs accesses the
+file over the network via an appropriate protocol (@pxref{Remote
+Files,, Remote Files, emacs, The GNU Emacs Manual}). This handling is
+done at a very low level, so you may assume that all the functions
+described in this chapter accept magic file names as file name
+arguments, except where noted. @xref{Magic File Names}, for details.
When file I/O functions signal Lisp errors, they usually use the
condition @code{file-error} (@pxref{Handling Errors}). The error
* File Locks:: Locking and unlocking files, to prevent
simultaneous editing by two people.
* Information about Files:: Testing existence, accessibility, size of files.
-* Changing Files:: Renaming files, changing protection, etc.
+* Changing Files:: Renaming files, changing permissions, etc.
* File Names:: Decomposing and expanding file names.
* Contents of Directories:: Getting a list of the files in a directory.
* Create/Delete Dirs:: Creating and Deleting Directories.
-* Magic File Names:: Defining "magic" special handling
- for certain file names.
+* Magic File Names:: Special handling for certain file names.
* Format Conversion:: Conversion to and from various file formats.
@end menu
In spite of the distinction between files and buffers, people often
refer to a file when they mean a buffer and vice-versa. Indeed, we say,
-``I am editing a file,'' rather than, ``I am editing a buffer that I
-will soon save as a file of the same name.'' Humans do not usually need
+``I am editing a file'', rather than, ``I am editing a buffer that I
+will soon save as a file of the same name''. Humans do not usually need
to make the distinction explicit. When dealing with a computer program,
however, it is good to keep the distinction in mind.
@end smallexample
@noindent
-(See @code{switch-to-buffer} in @ref{Displaying Buffers}.)
+(See @code{switch-to-buffer} in @ref{Switching Buffers}.)
If @var{wildcards} is non-@code{nil}, which is always true in an
interactive call, then @code{find-file} expands wildcard characters in
@deffn Command find-file-other-window filename &optional wildcards
This command selects a buffer visiting the file @var{filename}, but
-does so in a window other than the selected window. It may use another
-existing window or split a window; see @ref{Displaying Buffers}.
+does so in a window other than the selected window. It may use
+another existing window or split a window; see @ref{Switching
+Buffers}.
When this command is called interactively, it prompts for
@var{filename}.
@var{filename}.
@end deffn
-@deffn Command view-file filename
-This command visits @var{filename} using View mode, returning to the
-previous buffer when you exit View mode. View mode is a minor mode that
-provides commands to skim rapidly through the file, but does not let you
-modify the text. Entering View mode runs the normal hook
-@code{view-mode-hook}. @xref{Hooks}.
-
-When @code{view-file} is called interactively, it prompts for
-@var{filename}.
-@end deffn
-
@defopt find-file-wildcards
If this variable is non-@code{nil}, then the various @code{find-file}
commands check for wildcard characters and visit all the files that
@defopt require-final-newline
This variable determines whether files may be written out that do
@emph{not} end with a newline. If the value of the variable is
-@code{t}, then @code{save-buffer} silently adds a newline at the end of
-the file whenever the buffer being saved does not already end in one.
-If the value of the variable is non-@code{nil}, but not @code{t}, then
-@code{save-buffer} asks the user whether to add a newline each time the
-case arises.
+@code{t}, then @code{save-buffer} silently adds a newline at the end
+of the buffer whenever it does not already end in one. If the value
+is @code{visit}, Emacs adds a missing newline just after it visits the
+file. If the value is @code{visit-save}, Emacs adds a missing newline
+both on visiting and on saving. For any other non-@code{nil} value,
+@code{save-buffer} asks the user whether to add a newline each time
+the case arises.
If the value of the variable is @code{nil}, then @code{save-buffer}
doesn't add newlines at all. @code{nil} is the default value, but a few
and the length of the data inserted. An error is signaled if
@var{filename} is not the name of a file that can be read.
-The function @code{insert-file-contents} checks the file contents
-against the defined file formats, and converts the file contents if
-appropriate and also calls the functions in
-the list @code{after-insert-file-functions}. @xref{Format Conversion}.
-Normally, one of the functions in the
+This function checks the file contents against the defined file
+formats, and converts the file contents if appropriate and also calls
+the functions in the list @code{after-insert-file-functions}.
+@xref{Format Conversion}. Normally, one of the functions in the
@code{after-insert-file-functions} list determines the coding system
(@pxref{Coding Systems}) used for decoding the file's contents,
including end-of-line conversion. However, if the file contains null
-bytes, it is by default visited without any code conversions; see
-@ref{Lisp and Coding Systems, inhibit-null-byte-detection}, for how to
-control this behavior.
+bytes, it is by default visited without any code conversions.
+@xref{Lisp and Coding Systems, inhibit-null-byte-detection}.
If @var{visit} is non-@code{nil}, this function additionally marks the
buffer as unmodified and sets up various fields in the buffer so that it
@end defun
@defun insert-file-contents-literally filename &optional visit beg end replace
-This function works like @code{insert-file-contents} except that it does
-not do format decoding (@pxref{Format Conversion}), does not do
-character code conversion (@pxref{Coding Systems}), does not run
-@code{find-file-hook}, does not perform automatic uncompression, and so
-on.
+This function works like @code{insert-file-contents} except that it
+does not run @code{find-file-hook}, and does not do format decoding,
+character code conversion, automatic uncompression, and so on.
@end defun
If you want to pass a file name to another process so that another
stored in the same directory as the file you are editing.
When you access files using NFS, there may be a small probability that
-you and another user will both lock the same file ``simultaneously.''
+you and another user will both lock the same file ``simultaneously''.
If this happens, it is possible for the two users to make changes
simultaneously, but Emacs will still warn the user who saves second.
Also, the detection of modification of a buffer visiting a file changed
File locking is not supported on some systems. On systems that do not
support it, the functions @code{lock-buffer}, @code{unlock-buffer} and
-@code{file-locked-p} do nothing and return @code{nil}.
+@code{file-locked-p} do nothing and return @code{nil}. It is also
+possible to disable locking, by setting the variable @code{create-lockfiles}.
+
+@defopt create-lockfiles
+If this variable is @code{nil}, Emacs does not lock files.
+@end defopt
@defun ask-user-about-lock file other-user
This function is called when the user tries to modify @var{file}, but it
to exist. This does not mean you can necessarily read the file, only
that you can find out its attributes. (On Unix and GNU/Linux, this is
true if the file exists and you have execute permission on the
-containing directories, regardless of the protection of the file
+containing directories, regardless of the permissions of the file
itself.)
If the file does not exist, or if fascist access control policies
other I/O device).
@end defun
+@defun file-equal-p file1 file2
+This function returns @code{t} if the files @var{file1} and
+@var{file2} name the same file. If @var{file1} or @var{file2} does
+not exist, the return value is unspecified.
+@end defun
+
+@defun file-in-directory-p file dir
+This function returns @code{t} if @var{file} is a file in directory
+@var{dir}, or in a subdirectory of @var{dir}. It also returns
+@code{t} if @var{file} and @var{dir} are the same directory. It
+compares the @code{file-truename} values of the two directories
+(@pxref{Truenames}). If @var{dir} does not name an existing
+directory, the return value is @code{nil}.
+@end defun
+
@node Truenames
@subsection Truenames
@cindex truename (of file)
-@c Emacs 19 features
The @dfn{truename} of a file is the name that you get by following
symbolic links at all levels until none remain, then simplifying away
@samp{.}@: and @samp{..}@: appearing as name components. This results
because they eliminate symbolic links as a cause of name variation.
@defun file-truename filename
-The function @code{file-truename} returns the truename of the file
-@var{filename}. If the argument is not an absolute file name,
-this function first expands it against @code{default-directory}.
+This function returns the truename of the file @var{filename}. If the
+argument is not an absolute file name, this function first expands it
+against @code{default-directory}.
This function does not expand environment variables. Only
@code{substitute-in-file-name} does that. @xref{Definition of
@comment node-name, next, previous, up
@subsection Other Information about Files
- This section describes the functions for getting detailed information
-about a file, other than its contents. This information includes the
-mode bits that control access permission, the owner and group numbers,
-the number of names, the inode number, the size, and the times of access
-and modification.
+ This section describes the functions for getting detailed
+information about a file, other than its contents. This information
+includes the mode bits that control access permissions, the owner and
+group numbers, the number of names, the inode number, the size, and
+the times of access and modification.
@defun file-modes filename
-@cindex permission
+@cindex file permissions
+@cindex permissions, file
@cindex file attributes
-This function returns the mode bits of @var{filename}, as an integer.
-The mode bits are also called the file permissions, and they specify
-access control in the usual Unix fashion. If the low-order bit is 1,
-then the file is executable by all users, if the second-lowest-order bit
-is 1, then the file is writable by all users, etc.
-
-The highest value returnable is 4095 (7777 octal), meaning that
-everyone has read, write, and execute permission, that the @acronym{SUID} bit
-is set for both others and group, and that the sticky bit is set.
-
-If @var{filename} does not exist, @code{file-modes} returns @code{nil}.
-
-This function recursively follows symbolic links at all levels.
+@cindex file modes
+This function returns the @dfn{mode bits} describing the @dfn{file
+permissions} of @var{filename}, as an integer. It recursively follows
+symbolic links in @var{filename} at all levels. If @var{filename}
+does not exist, the return value is @code{nil}.
+
+@xref{File Permissions,,, coreutils, The @sc{gnu} @code{Coreutils}
+Manual}, for a description of mode bits. If the low-order bit is 1,
+then the file is executable by all users, if the second-lowest-order
+bit is 1, then the file is writable by all users, etc. The highest
+value returnable is 4095 (7777 octal), meaning that everyone has read,
+write, and execute permission, that the @acronym{SUID} bit is set for
+both others and group, and that the sticky bit is set.
@example
@group
@end group
@group
-(set-file-modes "~/junk/diffs" 438)
+(set-file-modes "~/junk/diffs" #o666)
@result{} nil
@end group
-@group
-(format "%o" 438)
- @result{} "666" ; @r{Convert to octal.}
-@end group
-
@group
% ls -l diffs
-rw-rw-rw- 1 lewis 0 3063 Oct 30 16:00 diffs
@end group
@end example
+
+@xref{Changing Files}, for functions that change file permissions,
+such as @code{set-file-modes}.
+
+@cindex MS-DOS and file modes
+@cindex file modes and MS-DOS
+@strong{MS-DOS note:} On MS-DOS, there is no such thing as an
+``executable'' file mode bit. So @code{file-modes} considers a file
+executable if its name ends in one of the standard executable
+extensions, such as @file{.com}, @file{.bat}, @file{.exe}, and some
+others. Files that begin with the Unix-standard @samp{#!} signature,
+such as shell and Perl scripts, are also considered executable.
+Directories are also reported as executable, for compatibility with
+Unix. These conventions are also followed by @code{file-attributes},
+below.
@end defun
-If the @var{filename} argument to the next two functions is a symbolic
-link, then these function do @emph{not} replace it with its target.
-However, they both recursively follow symbolic links at all levels of
-parent directories.
+ If the @var{filename} argument to the next two functions is a
+symbolic link, then these function do @emph{not} replace it with its
+target. However, they both recursively follow symbolic links at all
+levels of parent directories.
@defun file-nlinks filename
This functions returns the number of names (i.e., hard links) that
@item
The file's inode number. If possible, this is an integer. If the
inode number is too large to be represented as an integer in Emacs
-Lisp, but still fits into a 32-bit integer, then the value has the
+Lisp but dividing it by @math{2^16} yields a representable integer,
+then the value has the
form @code{(@var{high} . @var{low})}, where @var{low} holds the low 16
-bits. If the inode is wider than 32 bits, the value is of the form
+bits. If the inode number is too wide for even that, the value is of the form
@code{(@var{high} @var{middle} . @var{low})}, where @code{high} holds
-the high 24 bits, @var{middle} the next 24 bits, and @var{low} the low
+the high bits, @var{middle} the middle 24 bits, and @var{low} the low
16 bits.
@item
@end table
@end defun
-@cindex MS-DOS and file modes
-@cindex file modes and MS-DOS
- On MS-DOS, there is no such thing as an ``executable'' file mode bit.
-So Emacs considers a file executable if its name ends in one of the
-standard executable extensions, such as @file{.com}, @file{.bat},
-@file{.exe}, and some others. Files that begin with the Unix-standard
-@samp{#!} signature, such as shell and Perl scripts, are also considered
-as executable files. This is reflected in the values returned by
-@code{file-modes} and @code{file-attributes}. Directories are also
-reported with executable bit set, for compatibility with Unix.
+@cindex SELinux context
+ SELinux is a Linux kernel feature which provides more sophisticated
+file access controls than ordinary ``Unix-style'' file permissions.
+If Emacs has been compiled with SELinux support on a system with
+SELinux enabled, you can use the function @code{file-selinux-context}
+to retrieve a file's SELinux security context. For the function
+@code{set-file-selinux-context}, see @ref{Changing Files}.
+
+@defun file-selinux-context filename
+This function returns the SELinux security context of the file
+@var{filename}. This return value is a list of the form
+@code{(@var{user} @var{role} @var{type} @var{range})}, whose elements
+are the context's user, role, type, and range respectively, as Lisp
+strings. See the SELinux documentation for details about what these
+actually mean.
+
+If the file does not exist or is inaccessible, or if the system does
+not support SELinux, or if Emacs was not compiled with SELinux
+support, then the return value is @code{(nil nil nil nil)}.
+@end defun
@node Locating Files
@subsection How to Locate Files in Standard Places
@cindex find file in path
This section explains how to search for a file in a list of
-directories (a @dfn{path}). One example is when you need to look for
-a program's executable file, e.g., to find out whether a given program
-is installed on the user's system. Another example is the search for
-Lisp libraries (@pxref{Library Search}). Such searches generally need
-to try various possible file name extensions, in addition to various
-possible directories. Emacs provides a function for such a
-generalized search for a file.
+directories (a @dfn{path}), or for an executable file in the standard
+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
list of directories given by @var{path}, trying the suffixes in
-@var{suffixes}. If it finds such a file, it returns the full
-@dfn{absolute file name} of the file (@pxref{Relative File Names});
-otherwise it returns @code{nil}.
+@var{suffixes}. If it finds such a file, it returns the file's
+absolute file name (@pxref{Relative File Names}); otherwise it returns
+@code{nil}.
The optional argument @var{suffixes} gives the list of file-name
suffixes to append to @var{filename} when searching.
suffixes. If @var{suffixes} is @code{nil}, or @code{("")}, then there
are no suffixes, and @var{filename} is used only as-is. Typical
values of @var{suffixes} are @code{exec-suffixes} (@pxref{Subprocess
-Creation, exec-suffixes}), @code{load-suffixes},
-@code{load-file-rep-suffixes} and the return value of the function
-@code{get-load-suffixes} (@pxref{Load Suffixes}).
+Creation}), @code{load-suffixes}, @code{load-file-rep-suffixes} and
+the return value of the function @code{get-load-suffixes} (@pxref{Load
+Suffixes}).
Typical values for @var{path} are @code{exec-path} (@pxref{Subprocess
-Creation, exec-path}) when looking for executable programs or
-@code{load-path} (@pxref{Library Search, load-path}) when looking for
-Lisp files. If @var{filename} is absolute, @var{path} has no effect,
-but the suffixes in @var{suffixes} are still tried.
-
-The optional argument @var{predicate}, if non-@code{nil}, specifies
-the predicate function to use for testing whether a candidate file is
-suitable. The predicate function is passed the candidate file name as
-its single argument. If @var{predicate} is @code{nil} or unspecified,
-@code{locate-file} uses @code{file-readable-p} as the default
-predicate. Useful non-default predicates include
-@code{file-executable-p}, @code{file-directory-p}, and other
-predicates described in @ref{Kinds of Files}.
+Creation}) when looking for executable programs, or @code{load-path}
+(@pxref{Library Search}) when looking for Lisp files. If
+@var{filename} is absolute, @var{path} has no effect, but the suffixes
+in @var{suffixes} are still tried.
+
+The optional argument @var{predicate}, if non-@code{nil}, specifies a
+predicate function for testing whether a candidate file is suitable.
+The predicate is passed the candidate file name as its single
+argument. If @var{predicate} is @code{nil} or omitted,
+@code{locate-file} uses @code{file-readable-p} as the predicate.
+@xref{Kinds of Files}, for other useful predicates, e.g.@:
+@code{file-executable-p} and @code{file-directory-p}.
For compatibility, @var{predicate} can also be one of the symbols
@code{executable}, @code{readable}, @code{writable}, @code{exists}, or
@defun executable-find program
This function searches for the executable file of the named
-@var{program} and returns the full absolute name of the executable,
+@var{program} and returns the absolute file name of the executable,
including its file-name extensions, if any. It returns @code{nil} if
the file is not found. The functions searches in all the directories
-in @code{exec-path} and tries all the file-name extensions in
-@code{exec-suffixes}.
+in @code{exec-path}, and tries all the file-name extensions in
+@code{exec-suffixes} (@pxref{Subprocess Creation}).
@end defun
@node Changing Files
@cindex linking files
@cindex setting modes of files
- The functions in this section rename, copy, delete, link, and set the
-modes of files.
+ The functions in this section rename, copy, delete, link, and set
+the modes (permissions) of files.
In the functions that have an argument @var{newname}, if a file by the
name of @var{newname} already exists, the actions taken depend on the
same effect as renaming, aside from momentary intermediate states.
@end deffn
-@deffn Command copy-file oldname newname &optional ok-if-exists time preserve-uid-gid
+@deffn Command copy-file oldname newname &optional ok-if-exists time preserve-uid-gid preserve-selinux
This command copies the file @var{oldname} to @var{newname}. An
error is signaled if @var{oldname} does not exist. If @var{newname}
names a directory, it copies @var{oldname} into that directory,
non-@code{nil}, we attempt to copy the user and group ownership of the
file. This works only on some operating systems, and only if you have
the correct permissions to do so.
+
+If the optional argument @var{preserve-selinux} is non-@code{nil}, and
+Emacs has been compiled with SELinux support, this function attempts
+to copy the file's SELinux context (@pxref{File Attributes}).
@end deffn
@deffn Command make-symbolic-link filename newname &optional ok-if-exists
links.
@end deffn
-@deffn Command delete-file filename
+@cindex trash
+@vindex delete-by-moving-to-trash
+@deffn Command delete-file filename &optional trash
@pindex rm
-This command deletes the file @var{filename}, like the shell command
-@samp{rm @var{filename}}. If the file has multiple names, it continues
-to exist under the other names.
-
-A suitable kind of @code{file-error} error is signaled if the file does
-not exist, or is not deletable. (On Unix and GNU/Linux, a file is
-deletable if its directory is writable.)
-
-If @var{filename} is a symbolic link, @code{delete-file} does not
-replace it with its target, but it does follow symbolic links at all
-levels of parent directories.
+This command deletes the file @var{filename}. If the file has
+multiple names, it continues to exist under the other names. If
+@var{filename} is a symbolic link, @code{delete-file} deletes only the
+symbolic link and not its target (though it does follow symbolic links
+at all levels of parent directories).
+
+A suitable kind of @code{file-error} error is signaled if the file
+does not exist, or is not deletable. (On Unix and GNU/Linux, a file
+is deletable if its directory is writable.)
+
+If the optional argument @var{trash} is non-@code{nil} and the
+variable @code{delete-by-moving-to-trash} is non-@code{nil}, this
+command moves the file into the system Trash instead of deleting it.
+@xref{Misc File Ops,,Miscellaneous File Operations, emacs, The GNU
+Emacs Manual}. When called interactively, @var{trash} is @code{t} if
+no prefix argument is given, and @code{nil} otherwise.
See also @code{delete-directory} in @ref{Create/Delete Dirs}.
@end deffn
+@cindex file permissions, setting
+@cindex permissions, file
+@cindex file modes, setting
@deffn Command set-file-modes filename mode
-This function sets mode bits of @var{filename} to @var{mode} (which
-must be an integer when the function is called non-interactively).
-Only the low 12 bits of @var{mode} are used.
+This function sets the @dfn{file mode} (or @dfn{file permissions}) of
+@var{filename} to @var{mode}. It recursively follows symbolic links
+at all levels for @var{filename}.
+
+If called non-interactively, @var{mode} must be an integer. Only the
+lowest 12 bits of the integer are used; on most systems, only the
+lowest 9 bits are meaningful. You can use the Lisp construct for
+octal numbers to enter @var{mode}. For example,
+
+@example
+(set-file-modes #o644)
+@end example
+
+@noindent
+specifies that the file should be readable and writable for its owner,
+readable for group members, and readable for all other users.
+@xref{File Permissions,,, coreutils, The @sc{gnu} @code{Coreutils}
+Manual}, for a description of mode bit specifications.
Interactively, @var{mode} is read from the minibuffer using
-@code{read-file-modes}, which accepts mode bits either as a number or
-as a character string representing the mode bits symbolically. See
-the description of @code{read-file-modes} below for the supported
-forms of symbolic notation for mode bits.
+@code{read-file-modes} (see below), which lets the user type in either
+an integer or a string representing the permissions symbolically.
-This function recursively follows symbolic links at all levels for
-@var{filename}.
+@xref{File Attributes}, for the function @code{file-modes}, which
+returns the permissions of a file.
@end deffn
-@c Emacs 19 feature
@defun set-default-file-modes mode
@cindex umask
-This function sets the default file protection for new files created by
-Emacs and its subprocesses. Every file created with Emacs initially has
-this protection, or a subset of it (@code{write-region} will not give a
-file execute permission even if the default file protection allows
-execute permission). On Unix and GNU/Linux, the default protection is
-the bitwise complement of the ``umask'' value.
-
-The argument @var{mode} must be an integer. On most systems, only the
-low 9 bits of @var{mode} are meaningful. You can use the Lisp construct
-for octal character codes to enter @var{mode}; for example,
-
-@example
-(set-default-file-modes ?\644)
-@end example
-
-Saving a modified version of an existing file does not count as creating
-the file; it preserves the existing file's mode, whatever that is. So
-the default file protection has no effect.
+This function sets the default file permissions for new files created
+by Emacs and its subprocesses. Every file created with Emacs
+initially has these permissions, or a subset of them
+(@code{write-region} will not grant execute permissions even if the
+default file permissions allow execution). On Unix and GNU/Linux, the
+default permissions are given by the bitwise complement of the
+``umask'' value.
+
+The argument @var{mode} should be an integer which specifies the
+permissions, similar to @code{set-file-modes} above. Only the lowest
+9 bits are meaningful.
+
+The default file permissions have no effect when you save a modified
+version of an existing file; saving a file preserves its existing
+permissions.
@end defun
@defun default-file-modes
-This function returns the current default protection value.
+This function returns the default file permissions, as an integer.
@end defun
@defun read-file-modes &optional prompt base-file
-This function reads file mode bits from the minibuffer. The optional
-argument @var{prompt} specifies a non-default prompt. Second optional
-argument @var{base-file} is the name of a file on whose permissions to
-base the mode bits that this function returns, if what the user types
-specifies mode bits relative to permissions of an existing file.
+This function reads a set of file mode bits from the minibuffer. The
+first optional argument @var{prompt} specifies a non-default prompt.
+Second second optional argument @var{base-file} is the name of a file
+on whose permissions to base the mode bits that this function returns,
+if what the user types specifies mode bits relative to permissions of
+an existing file.
If user input represents an octal number, this function returns that
number. If it is a complete symbolic specification of mode bits, as
@code{nil}, the function uses @code{0} as the base mode bits. The
complete and relative specifications can be combined, as in
@code{"u+r,g+rx,o+r,g-w"}. @xref{File Permissions,,, coreutils, The
-@sc{gnu} @code{Coreutils} Manual}, for detailed description of
-symbolic mode bits specifications.
+@sc{gnu} @code{Coreutils} Manual}, for a description of file mode
+specifications.
@end defun
@defun file-modes-symbolic-to-number modes &optional base-modes
-This subroutine converts a symbolic specification of file mode bits in
-@var{modes} into the equivalent numeric value. If the symbolic
+This function converts a symbolic file mode specification in
+@var{modes} into the equivalent integer value. If the symbolic
specification is based on an existing file, that file's mode bits are
taken from the optional argument @var{base-modes}; if that argument is
-omitted or @code{nil}, it defaults to zero, i.e.@: no access rights at
+omitted or @code{nil}, it defaults to 0, i.e.@: no access rights at
all.
@end defun
(@pxref{Time of Day}).
@end defun
+@defun set-file-selinux-context filename context
+This function sets the SELinux security context of the file
+@var{filename} to @var{context}. @xref{File Attributes}, for a brief
+description of SELinux contexts. The @var{context} argument should be
+a list @code{(@var{user} @var{role} @var{type} @var{range})}, like the
+return value of @code{file-selinux-context}. The function does
+nothing if SELinux is disabled, or if Emacs was compiled without
+SELinux support.
+@end defun
+
@node File Names
@section File Names
@cindex file names
@end defun
@defun file-name-extension filename &optional period
-This function returns @var{filename}'s final ``extension,'' if any,
+This function returns @var{filename}'s final ``extension'', if any,
after applying @code{file-name-sans-versions} to remove any
version/backup part. The extension, in a file name, is the part that
follows the last @samp{.} in the last name component (minus any
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
results.
@c Wordy to avoid overfull hbox. --rjc 15mar92
-Here we assume that the environment variable @code{HOME}, which holds
+Here we assume that the environment variable @env{HOME}, which holds
the user's home directory name, has value @samp{/xcssun/users/rms}.
@example
non-@code{nil}. To use it, you should expand the prefix against
the proper directory before calling @code{make-temp-file}.
- In older Emacs versions where @code{make-temp-file} does not exist,
-you should use @code{make-temp-name} instead:
-
-@example
-(make-temp-name
- (expand-file-name @var{name-of-application}
- temporary-file-directory))
-@end example
-
-@defun make-temp-name string
-This function generates a string that can be used as a unique file
-name. The name starts with @var{string}, and has several random
-characters appended to it, which are different in each Emacs job. It
-is like @code{make-temp-file} except that it just constructs a name,
-and does not create a file. Another difference is that @var{string}
-should be an absolute file name. On MS-DOS, this function can
-truncate the @var{string} prefix to fit into the 8+3 file-name limits.
-@end defun
-
@defopt temporary-file-directory
-@cindex @code{TMPDIR} environment variable
-@cindex @code{TMP} environment variable
-@cindex @code{TEMP} environment variable
+@cindex @env{TMPDIR} environment variable
+@cindex @env{TMP} environment variable
+@cindex @env{TEMP} environment variable
This variable specifies the directory name for creating temporary files.
Its value should be a directory name (@pxref{Directory Names}), but it
is good for Lisp programs to cope if the value is a directory's file
@code{expand-file-name} is a good way to achieve that.
The default value is determined in a reasonable way for your operating
-system; it is based on the @code{TMPDIR}, @code{TMP} and @code{TEMP}
+system; it is based on the @env{TMPDIR}, @env{TMP} and @env{TEMP}
environment variables, with a fall-back to a system-dependent name if
none of these variables is defined.
@end example
@end defopt
+@defun make-temp-name base-name
+This function generates a string that can be used as a unique file
+name. The name starts with @var{base-name}, and has several random
+characters appended to it, which are different in each Emacs job. It
+is like @code{make-temp-file} except that (i) it just constructs a
+name, and does not create a file, and (ii) @var{base-name} should be
+an absolute file name (on MS-DOS, this function can truncate
+@var{base-name} to fit into the 8+3 file-name limits).
+
+@strong{Warning:} In most cases, you should not use this function; use
+@code{make-temp-file} instead! This function is susceptible to a race
+condition, between the @code{make-temp-name} call and the creation of
+the file, which in some cases may cause a security hole.
+@end defun
+
@node File Name Completion
@subsection File Name Completion
@cindex file name completion subroutines
@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.
-
-@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
-
- 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:
+ 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 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}. 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.
+ A lower-level function for standardizing file names, which
+@code{locate-user-emacs-file} uses as a subroutine, is
+@code{convert-standard-filename}.
- 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}.
+@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
@code{mkdir} is an alias for this.
@end deffn
-@deffn Command copy-directory dirname newname &optional keep-time parents
+@deffn Command copy-directory dirname newname &optional keep-time parents copy-contents
This command copies the directory named @var{dirname} to
@var{newname}. If @var{newname} names an existing directory,
@var{dirname} will be copied to a subdirectory there.
It always sets the file modes of the copied files to match the
corresponding original file.
-The third arg @var{keep-time} non-@code{nil} means to preserve the
+The third argument @var{keep-time} non-@code{nil} means to preserve the
modification time of the copied files. A prefix arg makes
@var{keep-time} non-@code{nil}.
-Noninteractively, the last argument @var{parents} says whether to
+The fourth argument @var{parents} says whether to
create parent directories if they don't exist. Interactively,
this happens by default.
+
+The fifth argument @var{copy-contents}, if non-@code{nil}, means to
+copy the contents of @var{dirname} directly into @var{newname} if the
+latter is an existing directory, instead of copying @var{dirname} into
+it as a subdirectory.
@end deffn
-@deffn Command delete-directory dirname &optional recursive
+@cindex trash
+@vindex delete-by-moving-to-trash
+@deffn Command delete-directory dirname &optional recursive trash
This command deletes the directory named @var{dirname}. The function
@code{delete-file} does not work for files that are directories; you
must use @code{delete-directory} for them. If @var{recursive} is
@code{delete-directory} only follows symbolic links at the level of
parent directories.
+
+If the optional argument @var{trash} is non-@code{nil} and the
+variable @code{delete-by-moving-to-trash} is non-@code{nil}, this
+command moves the file into the system Trash instead of deleting it.
+@xref{Misc File Ops,,Miscellaneous File Operations, emacs, The GNU
+Emacs Manual}. When called interactively, @var{trash} is @code{t} if
+no prefix argument is given, and @code{nil} otherwise.
@end deffn
@node Magic File Names
@section Making Certain File Names ``Magic''
@cindex magic file names
-@c Emacs 19 feature
You can implement special handling for certain file names. This is
called making those names @dfn{magic}. The principal use for this
feature is in implementing remote file names (@pxref{Remote Files,,
To define a kind of magic file name, you must supply a regular
expression to define the class of names (all those that match the
regular expression), plus a handler that implements all the primitive
-Emacs file operations for file names that do match.
+Emacs file operations for file names that match.
@vindex file-name-handler-alist
The variable @code{file-name-handler-alist} holds a list of handlers,
@code{file-name-nondirectory},
@code{file-name-sans-versions}, @code{file-newer-than-file-p},
@code{file-ownership-preserved-p},
-@code{file-readable-p}, @code{file-regular-p}, @code{file-symlink-p},
-@code{file-truename}, @code{file-writable-p},
-@code{find-backup-file-name},
+@code{file-readable-p}, @code{file-regular-p}, @code{file-in-directory-p},
+@code{file-symlink-p}, @code{file-truename}, @code{file-writable-p},
+@code{file-equal-p}, @code{find-backup-file-name},
@c Not sure why it was here: @code{find-file-noselect},@*
@code{get-file-buffer},
@code{insert-directory},
possibly others to be added in the future. It need not implement all
these operations itself---when it has nothing special to do for a
certain operation, it can reinvoke the primitive, to handle the
-operation ``in the usual way.'' It should always reinvoke the primitive
+operation ``in the usual way''. It should always reinvoke the primitive
for an operation it does not recognize. Here's one way to do this:
@smallexample
filenames, that means they are stored on the same file system and can
be accessed locally with respect to each other. This means, for
example, that it is possible to start a remote process accessing both
-files at the same time. Implementors of file handlers need to ensure
+files at the same time. Implementers of file handlers need to ensure
this principle is valid.
@var{identification} specifies which part of the identifier shall be
@end defun
@defopt remote-file-name-inhibit-cache
-Whether to use the remote file-name cache for read access.
-
-File attributes of remote files are cached for better performance. If
-they are changed out of Emacs' control, the cached values become
+The attributes of remote files can be cached for better performance. If
+they are changed outside of Emacs's control, the cached values become
invalid, and must be reread.
-When set to @code{nil}, cached values are always used. This shall be
-set with care. When set to @code{t}, cached values are never used.
-ALthough this is the safest value, it could result in performance
-degradation.
+When this variable is set to @code{nil}, cached values are never
+expired. Use this setting with caution, only if you are sure nothing
+other than Emacs ever changes the remote files. If it is set to
+@code{t}, cached values are never used. This is the safest value, but
+could result in performance degradation.
A compromise is to set it to a positive number. This means that
cached values are used for that amount of seconds since they were
-cached.
-
-In case a remote file is checked regularly, it might be reasonable to
-let-bind this variable to a value less then the time period between
-two checks. Example:
+cached. If a remote file is checked regularly, it might be a good
+idea to let-bind this variable to a value less than the time period
+between consecutive checks. For example:
@example
(defun display-time-file-nonempty-p (file)
- (let ((remote-file-name-inhibit-cache (- display-time-interval 5)))
+ (let ((remote-file-name-inhibit-cache
+ (- display-time-interval 5)))
(and (file-exists-p file)
(< 0 (nth 7 (file-attributes (file-chase-links file)))))))
@end example
This command writes the current buffer contents into the file @var{file}
in a format based on @var{format}, which is a list of format names. It
constructs the actual format starting from @var{format}, then appending
-any elements from the value of @code{buffer-file-format} with a non-nil
-@var{preserve} flag (see above), if they are not already present in
-@var{format}. It then updates @code{buffer-file-format} with this
-format, making it the default for future saves. Except for the
+any elements from the value of @code{buffer-file-format} with a
+non-@code{nil} @var{preserve} flag (see above), if they are not already
+present in @var{format}. It then updates @code{buffer-file-format} with
+this format, making it the default for future saves. Except for the
@var{format} argument, this command is similar to @code{write-file}. In
particular, @var{confirm} has the same meaning and interactive treatment
as the corresponding argument to @code{write-file}. @xref{Definition of
HCoop / bpt / emacs.git / blobdiff