path: root/devdocs/elisp/changing-files.html

 <h3 class="section">Changing File Names and Attributes</h3>     <p>The functions in this section rename, copy, delete, link, and set the modes (permissions) of files. Typically, they signal a <code>file-error</code> error if they fail to perform their function, reporting the system-dependent error message that describes the reason for the failure. If they fail because a file is missing, they signal a <code>file-missing</code> error instead. </p> <p>For performance, the operating system may cache or alias changes made by these functions instead of writing them immediately to secondary storage. See <a href="files-and-storage">Files and Storage</a>. </p> <p>In the functions that have an argument <var>newname</var>, if this argument is a directory name it is treated as if the nondirectory part of the source name were appended. Typically, a directory name is one that ends in ‘<samp>/</samp>’ (see <a href="directory-names">Directory Names</a>). For example, if the old name is <samp>a/b/c</samp>, the <var>newname</var> <samp>d/e/f/</samp> is treated as if it were <samp>d/e/f/c</samp>. This special treatment does not apply if <var>newname</var> is not a directory name but names a file that is a directory; for example, the <var>newname</var> <samp>d/e/f</samp> is left as-is even if <samp>d/e/f</samp> happens to be a directory. </p> <p>In the functions that have an argument <var>newname</var>, if a file by the name of <var>newname</var> already exists, the actions taken depend on the value of the argument <var>ok-if-already-exists</var>: </p> <ul> <li> Signal a <code>file-already-exists</code> error if <var>ok-if-already-exists</var> is <code>nil</code>. </li>
<li> Request confirmation if <var>ok-if-already-exists</var> is a number. </li>
<li> Replace the old file without confirmation if <var>ok-if-already-exists</var> is any other value. </li>
</ul> <dl> <dt id="add-name-to-file">Command: <strong>add-name-to-file</strong> <em>oldname newname &amp;optional ok-if-already-exists</em>
</dt> <dd>
  <p>This function gives the file named <var>oldname</var> the additional name <var>newname</var>. This means that <var>newname</var> becomes a new hard link to <var>oldname</var>. </p> <p>If <var>newname</var> is a symbolic link, its directory entry is replaced, not the directory entry it points to. If <var>oldname</var> is a symbolic link, this function might or might not follow the link; it does not follow the link on GNU platforms. If <var>oldname</var> is a directory, this function typically fails, although for the superuser on a few old-fashioned non-GNU platforms it can succeed and create a filesystem that is not tree-structured. </p> <p>In the first part of the following example, we list two files, <samp>foo</samp> and <samp>foo3</samp>. </p> <div class="example"> <pre class="example">$ 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
</pre>
</div> <p>Now we create a hard link, by calling <code>add-name-to-file</code>, then list the files again. This shows two names for one file, <samp>foo</samp> and <samp>foo2</samp>. </p> <div class="example"> <pre class="example">(add-name-to-file "foo" "foo2")
     ⇒ nil
</pre>

<pre class="example">$ 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
</pre>
</div> <p>Finally, we evaluate the following: </p> <div class="example"> <pre class="example">(add-name-to-file "foo" "foo3" t)
</pre>
</div> <p>and list the files again. Now there are three names for one file: <samp>foo</samp>, <samp>foo2</samp>, and <samp>foo3</samp>. The old contents of <samp>foo3</samp> are lost. </p> <div class="example"> <pre class="example">(add-name-to-file "foo1" "foo3")
     ⇒ nil
</pre>

<pre class="example">$ 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
</pre>
</div> <p>This function is meaningless on operating systems where multiple names for one file are not allowed. Some systems implement multiple names by copying the file instead. </p> <p>See also <code>file-nlinks</code> in <a href="file-attributes">File Attributes</a>. </p>
</dd>
</dl> <dl> <dt id="rename-file">Command: <strong>rename-file</strong> <em>filename newname &amp;optional ok-if-already-exists</em>
</dt> <dd>
<p>This command renames the file <var>filename</var> as <var>newname</var>. </p> <p>If <var>filename</var> has additional names aside from <var>filename</var>, it continues to have those names. In fact, adding the name <var>newname</var> with <code>add-name-to-file</code> and then deleting <var>filename</var> has the same effect as renaming, aside from momentary intermediate states and treatment of errors, directories and symbolic links. </p> <p>This command does not follow symbolic links. If <var>filename</var> is a symbolic link, this command renames the symbolic link, not the file it points to. If <var>newname</var> is a symbolic link, its directory entry is replaced, not the directory entry it points to. </p> <p>This command does nothing if <var>filename</var> and <var>newname</var> are the same directory entry, i.e., if they refer to the same parent directory and give the same name within that directory. Otherwise, if <var>filename</var> and <var>newname</var> name the same file, this command does nothing on POSIX-conforming systems, and removes <var>filename</var> on some non-POSIX systems. </p> <p>If <var>newname</var> exists, then it must be an empty directory if <var>oldname</var> is a directory and a non-directory otherwise. </p>
</dd>
</dl> <dl> <dt id="copy-file">Command: <strong>copy-file</strong> <em>oldname newname &amp;optional ok-if-already-exists time preserve-uid-gid preserve-extended-attributes</em>
</dt> <dd>
<p>This command copies the file <var>oldname</var> to <var>newname</var>. An error is signaled if <var>oldname</var> is not a regular file. If <var>newname</var> names a directory, it copies <var>oldname</var> into that directory, preserving its final name component. </p> <p>This function follows symbolic links, except that it does not follow a dangling symbolic link to create <var>newname</var>. </p> <p>If <var>time</var> is non-<code>nil</code>, then this function gives the new file the same last-modified time that the old one has. (This works on only some operating systems.) If setting the time gets an error, <code>copy-file</code> signals a <code>file-date-error</code> error. In an interactive call, a prefix argument specifies a non-<code>nil</code> value for <var>time</var>. </p> <p>If argument <var>preserve-uid-gid</var> is <code>nil</code>, we let the operating system decide the user and group ownership of the new file (this is usually set to the user running Emacs). If <var>preserve-uid-gid</var> is non-<code>nil</code>, we attempt to copy the user and group ownership of the file. This works only on some operating systems, and only if you have the correct permissions to do so. </p> <p>If the optional argument <var>preserve-permissions</var> is non-<code>nil</code>, this function copies the file modes (or “permissions”) of <var>oldname</var> to <var>newname</var>, as well as the Access Control List and SELinux context (if any). See <a href="information-about-files">Information about Files</a>. </p> <p>Otherwise, the file modes of <var>newname</var> are left unchanged if it is an existing file, and set to those of <var>oldname</var>, masked by the default file permissions (see <code>set-default-file-modes</code> below), if <var>newname</var> is to be newly created. The Access Control List or SELinux context are not copied over in either case. </p>
</dd>
</dl> <dl> <dt id="make-symbolic-link">Command: <strong>make-symbolic-link</strong> <em>target linkname &amp;optional ok-if-already-exists</em>
</dt> <dd>
  <p>This command makes a symbolic link to <var>target</var>, named <var>linkname</var>. This is like the shell command ‘<samp>ln -s <var>target</var> <var>linkname</var></samp>’. The <var>target</var> argument is treated only as a string; it need not name an existing file. If <var>ok-if-already-exists</var> is an integer, indicating interactive use, then leading ‘<samp>~</samp>’ is expanded and leading ‘<samp>/:</samp>’ is stripped in the <var>target</var> string. </p> <p>If <var>target</var> is a relative file name, the resulting symbolic link is interpreted relative to the directory containing the symbolic link. See <a href="relative-file-names">Relative File Names</a>. </p> <p>If both <var>target</var> and <var>linkname</var> have remote file name syntax, and if both remote identifications are equal, the symbolic link points to the local file name part of <var>target</var>. </p> <p>This function is not available on systems that don’t support symbolic links. </p>
</dd>
</dl>   <dl> <dt id="delete-file">Command: <strong>delete-file</strong> <em>filename &amp;optional trash</em>
</dt> <dd>
 <p>This command deletes the file <var>filename</var>. If the file has multiple names, it continues to exist under the other names. If <var>filename</var> is a symbolic link, <code>delete-file</code> deletes only the symbolic link and not its target. </p> <p>A suitable kind of <code>file-error</code> error is signaled if the file does not exist, or is not deletable. (On GNU and other POSIX-like systems, a file is deletable if its directory is writable.) </p> <p>If the optional argument <var>trash</var> is non-<code>nil</code> and the variable <code>delete-by-moving-to-trash</code> is non-<code>nil</code>, this command moves the file into the system Trash instead of deleting it. See <a href="https://www.gnu.org/software/emacs/manual/html_node/emacs/Misc-File-Ops.html#Misc-File-Ops">Miscellaneous File Operations</a> in <cite>The GNU Emacs Manual</cite>. When called interactively, <var>trash</var> is <code>t</code> if no prefix argument is given, and <code>nil</code> otherwise. </p> <p>See also <code>delete-directory</code> in <a href="create_002fdelete-dirs">Create/Delete Dirs</a>. </p>
</dd>
</dl>    <dl> <dt id="set-file-modes">Command: <strong>set-file-modes</strong> <em>filename mode &amp;optional flag</em>
</dt> <dd>
<p>This function sets the <em>file mode</em> (or <em>permissions</em>) of <var>filename</var> to <var>mode</var>. </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 changing the mode bits of a file somewhere else. On platforms that do not support changing mode bits on a symbolic link, this function signals an error when <var>filename</var> is a symbolic link and <var>flag</var> is <code>nofollow</code>. </p> <p>If called non-interactively, <var>mode</var> must be an integer. Only the lowest 12 bits of the integer are used; on most systems, only the lowest 9 bits are meaningful. You can use the Lisp construct for octal numbers to enter <var>mode</var>. For example, </p> <div class="example"> <pre class="example">(set-file-modes "myfile" #o644 'nofollow)
</pre>
</div> <p>specifies that the file should be readable and writable for its owner, readable for group members, and readable for all other users. 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 bit specifications. </p> <p>Interactively, <var>mode</var> is read from the minibuffer using <code>read-file-modes</code> (see below), which lets the user type in either an integer or a string representing the permissions symbolically. </p> <p>See <a href="testing-accessibility">Testing Accessibility</a>, for the function <code>file-modes</code>, which returns the permissions of a file. </p>
</dd>
</dl> <dl> <dt id="set-default-file-modes">Function: <strong>set-default-file-modes</strong> <em>mode</em>
</dt> <dd>
 <p>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</code> will not grant execute permissions even if the default file permissions allow execution). On GNU and other POSIX-like systems, the default permissions are given by the bitwise complement of the ‘<samp>umask</samp>’ value, i.e. each bit that is set in the argument <var>mode</var> will be <em>reset</em> in the default permissions with which Emacs creates files. </p> <p>The argument <var>mode</var> should be an integer which specifies the permissions, similar to <code>set-file-modes</code> above. Only the lowest 9 bits are meaningful. </p> <p>The default file permissions have no effect when you save a modified version of an existing file; saving a file preserves its existing permissions. </p>
</dd>
</dl> <dl> <dt id="with-file-modes">Macro: <strong>with-file-modes</strong> <em>mode body…</em>
</dt> <dd>
<p>This macro evaluates the <var>body</var> forms with the default permissions for new files temporarily set to <var>modes</var> (whose value is as for <code>set-file-modes</code> above). When finished, it restores the original default file permissions, and returns the value of the last form in <var>body</var>. </p> <p>This is useful for creating private files, for example. </p>
</dd>
</dl> <dl> <dt id="default-file-modes">Function: <strong>default-file-modes</strong>
</dt> <dd><p>This function returns the default file permissions, as an integer. </p></dd>
</dl> <dl> <dt id="read-file-modes">Function: <strong>read-file-modes</strong> <em>&amp;optional prompt base-file</em>
</dt> <dd>
<p>This function reads a set of file mode bits from the minibuffer. The first optional argument <var>prompt</var> specifies a non-default prompt. Second second optional argument <var>base-file</var> is the name of a file on whose permissions to base the mode bits that this function returns, if what the user types specifies mode bits relative to permissions of an existing file. </p> <p>If user input represents an octal number, this function returns that number. If it is a complete symbolic specification of mode bits, as in <code>"u=rwx"</code>, the function converts it to the equivalent numeric value using <code>file-modes-symbolic-to-number</code> and returns the result. If the specification is relative, as in <code>"o+g"</code>, then the permissions on which the specification is based are taken from the mode bits of <var>base-file</var>. If <var>base-file</var> is omitted or <code>nil</code>, the function uses <code>0</code> as the base mode bits. The complete and relative specifications can be combined, as in <code>"u+r,g+rx,o+r,g-w"</code>. 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 file mode specifications. </p>
</dd>
</dl> <dl> <dt id="file-modes-symbolic-to-number">Function: <strong>file-modes-symbolic-to-number</strong> <em>modes &amp;optional base-modes</em>
</dt> <dd><p>This function converts a symbolic file mode specification in <var>modes</var> 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</var>; if that argument is omitted or <code>nil</code>, it defaults to 0, i.e., no access rights at all. </p></dd>
</dl> <dl> <dt id="file-modes-number-to-symbolic">Function: <strong>file-modes-number-to-symbolic</strong> <em>modes</em>
</dt> <dd><p>This function converts a numeric file mode specification in <var>modes</var> into the equivalent symbolic form. </p></dd>
</dl> <dl> <dt id="set-file-times">Function: <strong>set-file-times</strong> <em>filename &amp;optional time flag</em>
</dt> <dd>
<p>This function sets the access and modification times of <var>filename</var> to <var>time</var>. The return value is <code>t</code> if the times are successfully set, otherwise it is <code>nil</code>. <var>time</var> defaults to the current time and must be a time value (see <a href="time-of-day">Time of Day</a>). </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 changing the times of a file somewhere else. On platforms that do not support changing times on a symbolic link, this function signals an error when <var>filename</var> is a symbolic link and <var>flag</var> is <code>nofollow</code>. </p>
</dd>
</dl> <dl> <dt id="set-file-extended-attributes">Function: <strong>set-file-extended-attributes</strong> <em>filename attribute-alist</em>
</dt> <dd><p>This function sets the Emacs-recognized extended file attributes for <var>filename</var>. The second argument <var>attribute-alist</var> should be an alist of the same form returned by <code>file-extended-attributes</code>. The return value is <code>t</code> if the attributes are successfully set, otherwise it is <code>nil</code>. See <a href="extended-attributes">Extended Attributes</a>. </p></dd>
</dl> <dl> <dt id="set-file-selinux-context">Function: <strong>set-file-selinux-context</strong> <em>filename context</em>
</dt> <dd>
<p>This function sets the SELinux security context for <var>filename</var> to <var>context</var>. The <var>context</var> argument should be a list <code>(<var>user</var> <var>role</var> <var>type</var> <var>range</var>)</code>, where each element is a string. See <a href="extended-attributes">Extended Attributes</a>. </p> <p>The function returns <code>t</code> if it succeeds in setting the SELinux context of <var>filename</var>. It returns <code>nil</code> if the context was not set (e.g., if SELinux is disabled, or if Emacs was compiled without SELinux support). </p>
</dd>
</dl> <dl> <dt id="set-file-acl">Function: <strong>set-file-acl</strong> <em>filename acl</em>
</dt> <dd>
<p>This function sets the Access Control List for <var>filename</var> to <var>acl</var>. The <var>acl</var> argument should have the same form returned by the function <code>file-acl</code>. See <a href="extended-attributes">Extended Attributes</a>. </p> <p>The function returns <code>t</code> if it successfully sets the ACL of <var>filename</var>, <code>nil</code> otherwise. </p>
</dd>
</dl><div class="_attribution">
  <p class="_attribution-p">
    Copyright &copy; 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/Changing-Files.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/Changing-Files.html</a>
  </p>
</div>