diff options
Diffstat (limited to 'devdocs/elisp/file-attributes.html')
| -rw-r--r-- | devdocs/elisp/file-attributes.html | 70 |
1 files changed, 70 insertions, 0 deletions
diff --git a/devdocs/elisp/file-attributes.html b/devdocs/elisp/file-attributes.html new file mode 100644 index 00000000..dddb3c62 --- /dev/null +++ b/devdocs/elisp/file-attributes.html @@ -0,0 +1,70 @@ + <h4 class="subsection">File Attributes</h4> <p>This section describes the functions for getting detailed information about a file, including the owner and group numbers, the number of names, the inode number, the size, and the times of access and modification. </p> <dl> <dt id="file-newer-than-file-p">Function: <strong>file-newer-than-file-p</strong> <em>filename1 filename2</em> +</dt> <dd> + <p>This function returns <code>t</code> if the file <var>filename1</var> is newer than file <var>filename2</var>. If <var>filename1</var> does not exist, it returns <code>nil</code>. If <var>filename1</var> does exist, but <var>filename2</var> does not, it returns <code>t</code>. </p> <p>In the following example, assume that the file <samp>aug-19</samp> was written on the 19th, <samp>aug-20</samp> was written on the 20th, and the file <samp>no-file</samp> doesn’t exist at all. </p> <div class="example"> <pre class="example">(file-newer-than-file-p "aug-19" "aug-20") + ⇒ nil +</pre> +<pre class="example">(file-newer-than-file-p "aug-20" "aug-19") + ⇒ t +</pre> +<pre class="example">(file-newer-than-file-p "aug-19" "no-file") + ⇒ t +</pre> +<pre class="example">(file-newer-than-file-p "no-file" "aug-19") + ⇒ nil +</pre> +</div> </dd> +</dl> <dl> <dt id="file-attributes">Function: <strong>file-attributes</strong> <em>filename &optional id-format</em> +</dt> <dd> +<p>This function returns a list of attributes of file <var>filename</var>. If the specified file does not exist, it returns <code>nil</code>. This function does not follow symbolic links. The optional parameter <var>id-format</var> specifies the preferred format of attributes <acronym>UID</acronym> and <acronym>GID</acronym> (see below)—the valid values are <code>'string</code> and <code>'integer</code>. The latter is the default, but we plan to change that, so you should specify a non-<code>nil</code> value for <var>id-format</var> if you use the returned <acronym>UID</acronym> or <acronym>GID</acronym>. </p> <p>On GNU platforms when operating on a local file, this function is atomic: if the filesystem is simultaneously being changed by some other process, this function returns the file’s attributes either before or after the change. Otherwise this function is not atomic, and might return <code>nil</code> if it detects the race condition, or might return a hodgepodge of the previous and current file attributes. </p> <p>Accessor functions are provided to access the elements in this list. The accessors are mentioned along with the descriptions of the elements below. </p> <p>The elements of the list, in order, are: </p> <ol start="0"> <li> <code>t</code> for a directory, a string for a symbolic link (the name linked to), or <code>nil</code> for a text file (<code>file-attribute-type</code>). </li> +<li> The number of names the file has (<code>file-attribute-link-number</code>). Alternate names, also known as hard links, can be created by using the <code>add-name-to-file</code> function (see <a href="changing-files">Changing Files</a>). </li> +<li> The file’s <acronym>UID</acronym>, normally as a string (<code>file-attribute-user-id</code>). However, if it does not correspond to a named user, the value is an integer. </li> +<li> The file’s <acronym>GID</acronym>, likewise (<code>file-attribute-group-id</code>). </li> +<li> The time of last access as a Lisp timestamp (<code>file-attribute-access-time</code>). The timestamp is in the style of <code>current-time</code> (see <a href="time-of-day">Time of Day</a>) and is truncated to that of the filesystem’s timestamp resolution; for example, on some FAT-based filesystems, only the date of last access is recorded, so this time will always hold the midnight of the day of the last access. </li> +<li> The time of last modification as a Lisp timestamp (<code>file-attribute-modification-time</code>). This is the last time when the file’s contents were modified. </li> +<li> The time of last status change as a Lisp timestamp (<code>file-attribute-status-change-time</code>). This is the time of the last change to the file’s access mode bits, its owner and group, and other information recorded in the filesystem for the file, beyond the file’s contents. </li> +<li> The size of the file in bytes (<code>file-attribute-size</code>). </li> +<li> The file’s modes, as a string of ten letters or dashes, as in ‘<samp>ls -l</samp>’ (<code>file-attribute-modes</code>). </li> +<li> An unspecified value, present for backward compatibility. </li> +<li> The file’s inode number (<code>file-attribute-inode-number</code>), a nonnegative integer. </li> +<li> The filesystem number of the device that the file is on <code>file-attribute-device-number</code>), an integer. This element and the file’s inode number together give enough information to distinguish any two files on the system—no two files can have the same values for both of these numbers. </li> +</ol> <p>For example, here are the file attributes for <samp>files.texi</samp>: </p> <div class="example"> <pre class="example">(file-attributes "files.texi" 'string) + ⇒ (nil 1 "lh" "users" + (20614 64019 50040 152000) + (20000 23 0 0) + (20614 64555 902289 872000) + 122295 "-rw-rw-rw-" + t 6473924464520138 + 1014478468) +</pre> +</div> <p>and here is how the result is interpreted: </p> <dl compact> <dt><code>nil</code></dt> <dd> +<p>is neither a directory nor a symbolic link. </p> </dd> <dt><code>1</code></dt> <dd> +<p>has only one name (the name <samp>files.texi</samp> in the current default directory). </p> </dd> <dt><code>"lh"</code></dt> <dd> +<p>is owned by the user with name ‘<samp>lh</samp>’. </p> </dd> <dt><code>"users"</code></dt> <dd> +<p>is in the group with name ‘<samp>users</samp>’. </p> </dd> <dt><code>(20614 64019 50040 152000)</code></dt> <dd> +<p>was last accessed on October 23, 2012, at 20:12:03.050040152 UTC. </p> </dd> <dt><code>(20000 23 0 0)</code></dt> <dd> +<p>was last modified on July 15, 2001, at 08:53:43 UTC. </p> </dd> <dt><code>(20614 64555 902289 872000)</code></dt> <dd> +<p>last had its status changed on October 23, 2012, at 20:20:59.902289872 UTC. </p> </dd> <dt><code>122295</code></dt> <dd> +<p>is 122295 bytes long. (It may not contain 122295 characters, though, if some of the bytes belong to multibyte sequences, and also if the end-of-line format is CR-LF.) </p> </dd> <dt><code>"-rw-rw-rw-"</code></dt> <dd> +<p>has a mode of read and write access for the owner, group, and world. </p> </dd> <dt><code>t</code></dt> <dd> +<p>is merely a placeholder; it carries no information. </p> </dd> <dt><code>6473924464520138</code></dt> <dd> +<p>has an inode number of 6473924464520138. </p> </dd> <dt><code>1014478468</code></dt> <dd><p>is on the file-system device whose number is 1014478468. </p></dd> </dl> </dd> +</dl> <dl> <dt id="file-nlinks">Function: <strong>file-nlinks</strong> <em>filename</em> +</dt> <dd> +<p>This function returns the number of names (i.e., hard links) that file <var>filename</var> has. If the file does not exist, this function returns <code>nil</code>. Note that symbolic links have no effect on this function, because they are not considered to be names of the files they link to. This function does not follow symbolic links. </p> <div class="example"> <pre class="example">$ 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 +</pre> + +<pre class="example">(file-nlinks "foo") + ⇒ 2 +</pre> +<pre class="example">(file-nlinks "doesnt-exist") + ⇒ nil +</pre> +</div> </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/File-Attributes.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/File-Attributes.html</a> + </p> +</div> |