file name and its last save file modtime. This feature is used by
@code{find-file-noselect} and you probably should not use it yourself.
-If @var{beg} and @var{end} are non-@code{nil}, they should be integers
-specifying the portion of the file to insert. In this case, @var{visit}
-must be @code{nil}. For example,
+If @var{beg} and @var{end} are non-@code{nil}, they should be numbers
+that are byte offsets specifying the portion of the file to insert.
+In this case, @var{visit} must be @code{nil}. For example,
@example
(insert-file-contents filename nil 0 500)
this case.
If @var{append} is non-@code{nil}, then the specified text is appended
-to the existing file contents (if any). If @var{append} is an
-integer, @code{write-region} seeks to that byte offset from the start
+to the existing file contents (if any). If @var{append} is a
+number, @code{write-region} seeks to that byte offset from the start
of the file and writes the data from there.
If @var{mustbenew} is non-@code{nil}, then @code{write-region} asks
using @var{string} as the error message text.
@end defun
-@defun file-ownership-preserved-p filename
+@defun file-ownership-preserved-p filename &optional group
This function returns @code{t} if deleting the file @var{filename} and
then creating it anew would keep the file's owner unchanged. It also
returns @code{t} for nonexistent files.
+If the optional argument @var{group} is non-@code{nil}, this function
+also checks that the file's group would be unchanged.
+
If @var{filename} is a symbolic link, then, unlike the other functions
discussed here, @code{file-ownership-preserved-p} does @emph{not}
replace @var{filename} with its target. However, it does recursively
@end group
@group
-% ls -l diffs
- -rw-rw-rw- 1 lewis 0 3063 Oct 30 16:00 diffs
+$ ls -l diffs
+-rw-rw-rw- 1 lewis lewis 3063 Oct 30 16:00 diffs
@end group
@end example
levels of parent directories.
@defun file-nlinks filename
-This functions returns the number of names (i.e., hard links) that
-file @var{filename} has. If the file does not exist, then this function
+This function returns the number of names (i.e., hard links) that
+file @var{filename} has. If the file does not exist, this function
returns @code{nil}. Note that symbolic links have no effect on this
-function, because they are not considered to be names of the files they
-link to.
+function, because they are not considered to be names of the files
+they link to.
@example
@group
-% 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
+$ ls -l foo*
+-rw-rw-rw- 2 rms rms 4 Aug 19 01:27 foo
+-rw-rw-rw- 2 rms rms 4 Aug 19 01:27 foo1
@end group
@group
as in @samp{ls -l}.
@item
-@code{t} if the file's @acronym{GID} would change if file were
-deleted and recreated; @code{nil} otherwise.
+An unspecified value, present for backward compatibility.
@item
The file's inode number. If possible, this is an integer. If the
(20000 23 0 0)
(20614 64555 902289 872000)
122295 "-rw-rw-rw-"
- nil (5888 2 . 43978)
+ t (5888 2 . 43978)
(15479 . 46724))
@end group
@end example
@item "-rw-rw-rw-"
has a mode of read and write access for the owner, group, and world.
-@item nil
-would retain the same @acronym{GID} if it were recreated.
+@item t
+is merely a placeholder; it carries no information.
@item (5888 2 . 43978)
has an inode number of 6473924464520138.
support, then the return value is @code{(nil nil nil nil)}.
@end defun
+@cindex access control list
+@cindex ACL entries
+ If Emacs has been compiled with @dfn{ACL} (access control list)
+support, you can use the function @code{file-acl} to retrieve a file's
+ACL entries. The interface implementation is platform-specific; on
+GNU/Linux and BSD, Emacs uses the POSIX ACL interface, while on
+MS-Windows Emacs emulates the POSIX ACL interface with native file
+security APIs.
+
+@defun file-acl filename
+This function returns the ACL entries of the file @var{filename}. The
+return value is a platform-dependent object containing some
+representation of the ACL entries. Don't use it for anything except
+passing it to the @code{set-file-acl} function (@pxref{Changing Files,
+set-file-acl}).
+
+If the file does not exist or is inaccessible, or if Emacs was unable to
+determine the ACL entries, then the return value is @code{nil}. The
+latter can happen for local files if Emacs was not compiled with ACL
+support, or for remote files if the file handler returns nil for the
+file's ACL entries.
+@end defun
+
@node Locating Files
@subsection How to Locate Files in Standard Places
@cindex locate file in path
@example
@group
-% ls -li fo*
-81908 -rw-rw-rw- 1 rms 29 Aug 18 20:32 foo
-84302 -rw-rw-rw- 1 rms 24 Aug 18 20:31 foo3
+$ ls -li fo*
+81908 -rw-rw-rw- 1 rms rms 29 Aug 18 20:32 foo
+84302 -rw-rw-rw- 1 rms rms 24 Aug 18 20:31 foo3
@end group
@end example
@end group
@group
-% ls -li fo*
-81908 -rw-rw-rw- 2 rms 29 Aug 18 20:32 foo
-81908 -rw-rw-rw- 2 rms 29 Aug 18 20:32 foo2
-84302 -rw-rw-rw- 1 rms 24 Aug 18 20:31 foo3
+$ ls -li fo*
+81908 -rw-rw-rw- 2 rms rms 29 Aug 18 20:32 foo
+81908 -rw-rw-rw- 2 rms rms 29 Aug 18 20:32 foo2
+84302 -rw-rw-rw- 1 rms rms 24 Aug 18 20:31 foo3
@end group
@end example
@end group
@group
-% ls -li fo*
-81908 -rw-rw-rw- 3 rms 29 Aug 18 20:32 foo
-81908 -rw-rw-rw- 3 rms 29 Aug 18 20:32 foo2
-81908 -rw-rw-rw- 3 rms 29 Aug 18 20:32 foo3
+$ ls -li fo*
+81908 -rw-rw-rw- 3 rms rms 29 Aug 18 20:32 foo
+81908 -rw-rw-rw- 3 rms rms 29 Aug 18 20:32 foo2
+81908 -rw-rw-rw- 3 rms rms 29 Aug 18 20:32 foo3
@end group
@end example
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}).
+If the optional argument @var{preserve-extended-attributes} is
+non-@code{nil}, and Emacs has been built with the appropriate support,
+this function attempts to copy the file's extended attributes, such as
+its SELinux context and ACL entries (@pxref{File Attributes}).
@end deffn
@deffn Command make-symbolic-link filename newname &optional ok-if-exists
@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.
+return value of @code{file-selinux-context}. The function returns
+@code{t} if it succeeds to set the SELinux security context of
+@var{filename}, @code{nil} otherwise. The function does nothing and
+returns @code{nil} if SELinux is disabled, or if Emacs was compiled
+without SELinux support.
+@end defun
+
+@defun set-file-acl filename acl-string
+This function sets the ACL entries of the file @var{filename} to
+@var{acl-string}. @xref{File Attributes}, for a brief description of
+ACLs. The @var{acl-string} argument should be a string containing the
+textual representation of the desired ACL entries as returned by
+@code{file-acl} (@pxref{File Attributes, file-acl}). The function
+returns @code{t} if it succeeds to set the ACL entries of
+@var{filename}, @code{nil} otherwise.
@end defun
@node File Names
(expand-file-name "foo" "/usr/spool/")
@result{} "/usr/spool/foo"
@end group
-@group
-(expand-file-name "$HOME/foo")
- @result{} "/xcssun/users/rms/lewis/$HOME/foo"
-@end group
@end example
If the part of the combined file name before the first slash is
@file{/../} is interpreted exactly the same as @file{/}.
Note that @code{expand-file-name} does @emph{not} expand environment
-variables; only @code{substitute-in-file-name} does that.
+variables; only @code{substitute-in-file-name} does that:
+
+@example
+@group
+(expand-file-name "$HOME/foo")
+ @result{} "/xcssun/users/rms/lewis/$HOME/foo"
+@end group
+@end example
Note also that @code{expand-file-name} does not follow symbolic links
at any level. This results in a difference between the way
@code{dired-compress-file}, @code{dired-uncache},@*
@code{expand-file-name},
@code{file-accessible-directory-p},
+@code{file-acl},
@code{file-attributes},
@code{file-directory-p},
+@code{file-equal-p},
@code{file-executable-p}, @code{file-exists-p},
+@code{file-in-directory-p},
@code{file-local-copy}, @code{file-remote-p},
@code{file-modes}, @code{file-name-all-completions},
@code{file-name-as-directory},
@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-in-directory-p},
+@code{file-readable-p}, @code{file-regular-p},
+@code{file-selinux-context},
@code{file-symlink-p}, @code{file-truename}, @code{file-writable-p},
-@code{file-equal-p}, @code{find-backup-file-name},
+@code{find-backup-file-name},
@c Not sure why it was here: @code{find-file-noselect},@*
@code{get-file-buffer},
@code{insert-directory},
@code{make-directory-internal},
@code{make-symbolic-link},@*
@code{process-file},
-@code{rename-file}, @code{set-file-modes}, @code{set-file-times},
+@code{rename-file}, @code{set-file-acl}, @code{set-file-modes},
+@code{set-file-selinux-context}, @code{set-file-times},
@code{set-visited-file-modtime}, @code{shell-command},
@code{start-file-process},
@code{substitute-in-file-name},@*
@code{dired-compress-file}, @code{dired-uncache},
@code{expand-file-name},
@code{file-accessible-direc@discretionary{}{}{}tory-p},
+@code{file-acl},
@code{file-attributes},
@code{file-direct@discretionary{}{}{}ory-p},
+@code{file-equal-p},
@code{file-executable-p}, @code{file-exists-p},
+@code{file-in-directory-p},
@code{file-local-copy}, @code{file-remote-p},
@code{file-modes}, @code{file-name-all-completions},
@code{file-name-as-directory},
@code{file-name-nondirec@discretionary{}{}{}tory},
@code{file-name-sans-versions}, @code{file-newer-than-file-p},
@code{file-ownership-pre@discretionary{}{}{}served-p},
-@code{file-readable-p}, @code{file-regular-p}, @code{file-symlink-p},
-@code{file-truename}, @code{file-writable-p},
+@code{file-readable-p}, @code{file-regular-p},
+@code{file-selinux-context},
+@code{file-symlink-p}, @code{file-truename}, @code{file-writable-p},
@code{find-backup-file-name},
@c Not sure why it was here: @code{find-file-noselect},
@code{get-file-buffer},
@code{insert-directory},
@code{insert-file-contents},
-@code{load}, @code{make-direc@discretionary{}{}{}tory},
+@code{load},
+@code{make-auto-save-file-name},
+@code{make-direc@discretionary{}{}{}tory},
@code{make-direc@discretionary{}{}{}tory-internal},
@code{make-symbolic-link},
@code{process-file},
-@code{rename-file}, @code{set-file-modes},
+@code{rename-file}, @code{set-file-acl}, @code{set-file-modes},
+@code{set-file-selinux-context}, @code{set-file-times},
@code{set-visited-file-modtime}, @code{shell-command},
@code{start-file-process},
@code{substitute-in-file-name},