which are sometimes useful in user Lisp code: @code{create-file-buffer}
and @code{after-find-file}. This section explains how to use them.
+@c FIXME This does not describe the default behavior, because
+@c uniquify is enabled by default and advises this function.
+@c This is confusing. uniquify should be folded into the function proper.
@defun create-file-buffer filename
This function creates a suitably named buffer for visiting
@var{filename}, and returns it. It uses @var{filename} (sans directory)
as the name if that name is free; otherwise, it appends a string such as
@samp{<2>} to get an unused name. See also @ref{Creating Buffers}.
+Note that the @file{uniquify} library affects the result of this
+function. @xref{Uniquify,,, emacs, The GNU Emacs Manual}.
@strong{Please note:} @code{create-file-buffer} does @emph{not}
associate the new buffer with a file and does not select the buffer.
When two users edit the same file at the same time, they are likely
to interfere with each other. Emacs tries to prevent this situation
from arising by recording a @dfn{file lock} when a file is being
-modified. (File locks are not implemented on Microsoft systems.)
+modified.
Emacs can then detect the first attempt to modify a buffer visiting a
file that is locked by another Emacs job, and ask the user what to do.
The file lock is really a file, a symbolic link with a special name,
-stored in the same directory as the file you are editing.
+stored in the same directory as the file you are editing. (On file
+systems that do not support symbolic links, a regular file is used.)
When you access files using NFS, there may be a small probability that
you and another user will both lock the same file ``simultaneously''.
This function locks the file @var{filename}, if the current buffer is
modified. The argument @var{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, or if the system does not support locking.
+file, or is not modified, or if the option @code{create-lockfiles} is
+@code{nil}.
@end defun
@defun 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, or if the
-system does not support locking.
+does nothing if the current buffer is not visiting a file, or is not locked.
@end defun
- 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}. 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
@end itemize
If you wish, you can replace the @code{ask-user-about-lock} function
-with your own version that makes the decision in another way. The code
-for its usual definition is in @file{userlock.el}.
+with your own version that makes the decision in another way.
@end defun
@node Information about Files
@defun file-symlink-p filename
@cindex file symbolic links
If the file @var{filename} is a symbolic link, the
-@code{file-symlink-p} function returns the (non-recursive) link target
-as a string. (Determining the file name that the link points to from
-the target is nontrivial.) First, this function recursively follows
-symbolic links at all levels of parent directories.
-
-If the file @var{filename} is not a symbolic link (or there is no such file),
+@code{file-symlink-p} function returns its (non-recursive) link target
+as a string. (The link target string is not necessarily the full
+absolute file name of the target; determining the full file name that
+the link points to is nontrivial, see below.) If the leading
+directories of @var{filename} include symbolic links, this function
+recursively follows them.
+
+If the file @var{filename} is not a symbolic link, or does not exist,
@code{file-symlink-p} returns @code{nil}.
+Here are a few examples of using this function:
+
@example
@group
-(file-symlink-p "foo")
+(file-symlink-p "not-a-symlink")
@result{} nil
@end group
@group
(file-symlink-p "sym-link")
- @result{} "foo"
+ @result{} "not-a-symlink"
@end group
@group
(file-symlink-p "sym-link2")
@result{} "/pub/bin"
@end group
@end example
+
+Note that in the third example, the function returned @file{sym-link},
+but did not proceed to resolve it, although that file is itself a
+symbolic link. This is what we meant by ``non-recursive'' above---the
+process of following the symbolic links does not recurse if the link
+target is itself a link.
+
+The string that this function returns is what is recorded in the
+symbolic link; it may or may not include any leading directories.
+This function does @emph{not} expand the link target to produce a
+fully-qualified file name, and in particular does not use the leading
+directories, if any, of the @var{filename} argument if the link target
+is not an absolute file name. Here's an example:
+
+@example
+@group
+(file-symlink-p "/foo/bar/baz")
+ @result{} "some-file"
+@end group
+@end example
+
+@noindent
+Here, although @file{/foo/bar/baz} was given as a fully-qualified file
+name, the result is not, and in fact does not have any leading
+directories at all. And since @file{some-file} might itself be a
+symbolic link, you cannot simply prepend leading directories to it,
+nor even naively use @code{expand-file-name} (@pxref{File Name
+Expansion}) to produce its absolute file name.
+
+For this reason, this function is seldom useful if you need to
+determine more than just the fact that a file is or isn't a symbolic
+link. If you actually need the file name of the link target, use
+@code{file-chase-links} or @code{file-truename}, described in
+@ref{Truenames}.
@end defun
The next two functions recursively follow symbolic links at
@item
The file's @acronym{UID}, normally as a string. However, if it does
-not correspond to a named user, the value is an integer or a floating
-point number.
+not correspond to a named user, the value is a number.
@item
The file's @acronym{GID}, likewise.
for the file, beyond the file's contents.
@item
-The size of the file in bytes. If the size is too large to fit in a
-Lisp integer, this is a floating point number.
+The size of the file in bytes. This is floating point if the size is
+too large to fit in a Lisp integer.
@item
The file's modes, as a string of ten letters or dashes,
@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 dividing it by @math{2^16} yields a representable integer,
+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 number is too wide for even that, the value is of the form
the correct permissions to do so.
If the optional argument @var{preserve-permissions} is non-@code{nil},
-this function copies the file modes (or ``permissions''), as well as
-its Access Control List and SELinux context (if any).
-@xref{Information about Files}. Otherwise, if the destination is
-created its file permission bits are those of the source, masked by
-the default file permissions.
+this function copies the file modes (or ``permissions'') of
+@var{oldname} to @var{newname}, as well as the Access Control List and
+SELinux context (if any). @xref{Information about Files}.
+
+Otherwise, the file modes of @var{newname} are left unchanged if it is
+an existing file, and set to those of @var{oldname}, masked by the
+default file permissions (see @code{set-default-file-modes} below), if
+@var{newname} is to be newly created. The Access Control List or
+SELinux context are not copied over in either case.
@end deffn
@deffn Command make-symbolic-link filename newname &optional ok-if-exists
@defun set-default-file-modes mode
@cindex umask
-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.
+This function sets the default 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
permissions.
@end defun
+@defmac with-file-modes mode body@dots{}
+This macro evaluates the @var{body} forms with the default
+permissions for new files temporarily set to @var{modes} (whose value
+is as for @code{set-file-modes} above). When finished, it restores
+the original default file permissions, and returns the value of the
+last form in @var{body}.
+
+This is useful for creating private files, for example.
+@end defmac
+
@defun default-file-modes
This function returns the default file permissions, as an integer.
@end defun
@defun file-modes-symbolic-to-number modes &optional base-modes
This function converts a symbolic file mode specification in
-@var{modes} into the equivalent integer value. If the symbolic
+@var{modes} into the equivalent integer. 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 0, i.e., no access rights at