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
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 string containing the textual
+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
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
@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},