diff options
Diffstat (limited to 'devdocs/elisp/testing-accessibility.html')
| -rw-r--r-- | devdocs/elisp/testing-accessibility.html | 52 |
1 files changed, 52 insertions, 0 deletions
diff --git a/devdocs/elisp/testing-accessibility.html b/devdocs/elisp/testing-accessibility.html new file mode 100644 index 00000000..20086799 --- /dev/null +++ b/devdocs/elisp/testing-accessibility.html @@ -0,0 +1,52 @@ + <h4 class="subsection">Testing Accessibility</h4> <p>These functions test for permission to access a file for reading, writing, or execution. Unless explicitly stated otherwise, they follow symbolic links. See <a href="kinds-of-files">Kinds of Files</a>. </p> <p>On some operating systems, more complex sets of access permissions can be specified, via mechanisms such as Access Control Lists (ACLs). See <a href="extended-attributes">Extended Attributes</a>, for how to query and set those permissions. </p> <dl> <dt id="file-exists-p">Function: <strong>file-exists-p</strong> <em>filename</em> +</dt> <dd> +<p>This function returns <code>t</code> if a file named <var>filename</var> appears to exist. This does not mean you can necessarily read the file, only that you can probably find out its attributes. (On GNU and other POSIX-like systems, this is true if the file exists and you have execute permission on the containing directories, regardless of the permissions of the file itself.) </p> <p>If the file does not exist, or if there was trouble determining whether the file exists, this function returns <code>nil</code>. </p> <p>Directories are files, so <code>file-exists-p</code> can return <code>t</code> when given a directory. However, because <code>file-exists-p</code> follows symbolic links, it returns <code>t</code> for a symbolic link name only if the target file exists. </p> +</dd> +</dl> <dl> <dt id="file-readable-p">Function: <strong>file-readable-p</strong> <em>filename</em> +</dt> <dd><p>This function returns <code>t</code> if a file named <var>filename</var> exists and you can read it. It returns <code>nil</code> otherwise. </p></dd> +</dl> <dl> <dt id="file-executable-p">Function: <strong>file-executable-p</strong> <em>filename</em> +</dt> <dd><p>This function returns <code>t</code> if a file named <var>filename</var> exists and you can execute it. It returns <code>nil</code> otherwise. On GNU and other POSIX-like systems, if the file is a directory, execute permission means you can check the existence and attributes of files inside the directory, and open those files if their modes permit. </p></dd> +</dl> <dl> <dt id="file-writable-p">Function: <strong>file-writable-p</strong> <em>filename</em> +</dt> <dd> +<p>This function returns <code>t</code> if the file <var>filename</var> can be written or created by you, and <code>nil</code> otherwise. A file is writable if the file exists and you can write it. It is creatable if it does not exist, but its parent directory does exist and you can write in that directory. </p> <p>In the example below, <samp>foo</samp> is not writable because the parent directory does not exist, even though the user could create such a directory. </p> <div class="example"> <pre class="example">(file-writable-p "~/no-such-dir/foo") + ⇒ nil +</pre> +</div> </dd> +</dl> <dl> <dt id="file-accessible-directory-p">Function: <strong>file-accessible-directory-p</strong> <em>dirname</em> +</dt> <dd> +<p>This function returns <code>t</code> if you have permission to open existing files in the directory whose name as a file is <var>dirname</var>; otherwise (e.g., if there is no such directory), it returns <code>nil</code>. The value of <var>dirname</var> may be either a directory name (such as <samp>/foo/</samp>) or the file name of a file which is a directory (such as <samp>/foo</samp>, without the final slash). </p> <p>For example, from the following we deduce that any attempt to read a file in <samp>/foo/</samp> will give an error: </p> <div class="example"> <pre class="example">(file-accessible-directory-p "/foo") + ⇒ nil +</pre> +</div> </dd> +</dl> <dl> <dt id="with-existing-directory">Macro: <strong>with-existing-directory</strong> <em>body…</em> +</dt> <dd><p>This macro ensures that <code>default-directory</code> is bound to an existing directory before executing <var>body</var>. If <code>default-directory</code> already exists, that’s preferred, and otherwise some other directory is used. This macro can be useful, for instance, when calling an external command that requires that it’s running in a directory that exists. The chosen directory is not guaranteed to be writable. </p></dd> +</dl> <dl> <dt id="access-file">Function: <strong>access-file</strong> <em>filename string</em> +</dt> <dd><p>If you can read <var>filename</var> this function returns <code>nil</code>; otherwise it signals an error using <var>string</var> as the error message text. </p></dd> +</dl> <dl> <dt id="file-ownership-preserved-p">Function: <strong>file-ownership-preserved-p</strong> <em>filename &optional group</em> +</dt> <dd> +<p>This function returns <code>t</code> if deleting the file <var>filename</var> and then creating it anew would keep the file’s owner unchanged. It also returns <code>t</code> for nonexistent files. </p> <p>If the optional argument <var>group</var> is non-<code>nil</code>, this function also checks that the file’s group would be unchanged. </p> <p>This function does not follow symbolic links. </p> +</dd> +</dl> <dl> <dt id="file-modes">Function: <strong>file-modes</strong> <em>filename &optional flag</em> +</dt> <dd> + <p>This function returns the <em>mode bits</em> of <var>filename</var>—an integer summarizing its read, write, and execution permissions. This function follows symbolic links. If the file does not exist, the return value is <code>nil</code>. </p> <p>See <a href="https://www.gnu.org/software/coreutils/manual/html_node/File-permissions.html#File-permissions">File permissions</a> in <cite>The <small>GNU</small> <code>Coreutils</code> Manual</cite>, for a description of mode bits. For example, if the low-order bit is 1, the file is executable by all users; if the second-lowest-order bit is 1, the file is writable by all users; etc. The highest possible value is 4095 (7777 octal), meaning that everyone has read, write, and execute permission, the <acronym>SUID</acronym> bit is set for both others and group, and the sticky bit is set. </p> <p>By default this function follows symbolic links. However, if the optional argument <var>flag</var> is the symbol <code>nofollow</code>, this function does not follow <var>filename</var> if it is a symbolic link; this can help prevent inadvertently obtaining the mode bits of a file somewhere else, and is more consistent with <code>file-attributes</code> (see <a href="file-attributes">File Attributes</a>). </p> <p>See <a href="changing-files">Changing Files</a>, for the <code>set-file-modes</code> function, which can be used to set these permissions. </p> <div class="example"> <pre class="example">(file-modes "~/junk/diffs" 'nofollow) + ⇒ 492 ; <span class="roman">Decimal integer.</span> +</pre> +<pre class="example">(format "%o" 492) + ⇒ "754" ; <span class="roman">Convert to octal.</span> +</pre> + +<pre class="example">(set-file-modes "~/junk/diffs" #o666 'nofollow) + ⇒ nil +</pre> + +<pre class="example">$ ls -l diffs +-rw-rw-rw- 1 lewis lewis 3063 Oct 30 16:00 diffs +</pre> +</div> <p><strong>MS-DOS note:</strong> On MS-DOS, there is no such thing as an executable file mode bit. So <code>file-modes</code> considers a file executable if its name ends in one of the standard executable extensions, such as <samp>.com</samp>, <samp>.bat</samp>, <samp>.exe</samp>, and some others. Files that begin with the POSIX-standard ‘<samp>#!</samp>’ signature, such as shell and Perl scripts, are also considered executable. Directories are also reported as executable, for compatibility with POSIX. These conventions are also followed by <code>file-attributes</code> (see <a href="file-attributes">File Attributes</a>). </p> +</dd> +</dl><div class="_attribution"> + <p class="_attribution-p"> + Copyright © 1990-1996, 1998-2022 Free Software Foundation, Inc. <br>Licensed under the GNU GPL license.<br> + <a href="https://www.gnu.org/software/emacs/manual/html_node/elisp/Testing-Accessibility.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/Testing-Accessibility.html</a> + </p> +</div> |