path: root/devdocs/elisp/unique-file-names.html

 <h4 class="subsection">Generating Unique File Names</h4>   <p>Some programs need to write temporary files. Here is the usual way to construct a name for such a file: </p> <div class="example"> <pre class="example">(make-temp-file <var>name-of-application</var>)
</pre>
</div> <p>The job of <code>make-temp-file</code> is to prevent two different users or two different jobs from trying to use the exact same file name. </p> <dl> <dt id="make-temp-file">Function: <strong>make-temp-file</strong> <em>prefix &amp;optional dir-flag suffix text</em>
</dt> <dd>
<p>This function creates a temporary file and returns its name. Emacs creates the temporary file’s name by adding to <var>prefix</var> some random characters that are different in each Emacs job. The result is guaranteed to be a newly created file, containing <var>text</var> if that’s given as a string and empty otherwise. On MS-DOS, this function can truncate <var>prefix</var> to fit into the 8+3 file-name limits. If <var>prefix</var> is a relative file name, it is expanded against <code>temporary-file-directory</code>. </p> <div class="example"> <pre class="example">(make-temp-file "foo")
     ⇒ "/tmp/foo232J6v"
</pre>
</div> <p>When <code>make-temp-file</code> returns, the file has been created and is empty. At that point, you should write the intended contents into the file. </p> <p>If <var>dir-flag</var> is non-<code>nil</code>, <code>make-temp-file</code> creates an empty directory instead of an empty file. It returns the file name, not the directory name, of that directory. See <a href="directory-names">Directory Names</a>. </p> <p>If <var>suffix</var> is non-<code>nil</code>, <code>make-temp-file</code> adds it at the end of the file name. </p> <p>If <var>text</var> is a string, <code>make-temp-file</code> inserts it in the file. </p> <p>To prevent conflicts among different libraries running in the same Emacs, each Lisp program that uses <code>make-temp-file</code> should have its own <var>prefix</var>. The number added to the end of <var>prefix</var> distinguishes between the same application running in different Emacs jobs. Additional added characters permit a large number of distinct names even in one Emacs job. </p>
</dd>
</dl> <p>The default directory for temporary files is controlled by the variable <code>temporary-file-directory</code>. This variable gives the user a uniform way to specify the directory for all temporary files. Some programs use <code>small-temporary-file-directory</code> instead, if that is non-<code>nil</code>. To use it, you should expand the prefix against the proper directory before calling <code>make-temp-file</code>. </p> <dl> <dt id="temporary-file-directory">User Option: <strong>temporary-file-directory</strong>
</dt> <dd>
   <p>This variable specifies the directory name for creating temporary files. Its value should be a directory name (see <a href="directory-names">Directory Names</a>), but it is good for Lisp programs to cope if the value is a directory’s file name instead. Using the value as the second argument to <code>expand-file-name</code> is a good way to achieve that. </p> <p>The default value is determined in a reasonable way for your operating system; it is based on the <code>TMPDIR</code>, <code>TMP</code> and <code>TEMP</code> environment variables, with a fall-back to a system-dependent name if none of these variables is defined. </p> <p>Even if you do not use <code>make-temp-file</code> to create the temporary file, you should still use this variable to decide which directory to put the file in. However, if you expect the file to be small, you should use <code>small-temporary-file-directory</code> first if that is non-<code>nil</code>. </p>
</dd>
</dl> <dl> <dt id="small-temporary-file-directory">User Option: <strong>small-temporary-file-directory</strong>
</dt> <dd>
<p>This variable specifies the directory name for creating certain temporary files, which are likely to be small. </p> <p>If you want to write a temporary file which is likely to be small, you should compute the directory like this: </p> <div class="example"> <pre class="example">(make-temp-file
  (expand-file-name <var>prefix</var>
                    (or small-temporary-file-directory
                        temporary-file-directory)))
</pre>
</div> </dd>
</dl> <dl> <dt id="make-temp-name">Function: <strong>make-temp-name</strong> <em>base-name</em>
</dt> <dd>
<p>This function generates a string that might be a unique file name. The name starts with <var>base-name</var>, and has several random characters appended to it, which are different in each Emacs job. It is like <code>make-temp-file</code> except that (i) it just constructs a name and does not create a file, (ii) <var>base-name</var> should be an absolute file name that is not magic, and (iii) if the returned file name is magic, it might name an existing file. See <a href="magic-file-names">Magic File Names</a>. </p> <p><strong>Warning:</strong> In most cases, you should not use this function; use <code>make-temp-file</code> instead! This function is susceptible to a race condition, between the <code>make-temp-name</code> call and the creation of the file, which in some cases may cause a security hole. </p>
</dd>
</dl> <p>Sometimes, it is necessary to create a temporary file on a remote host or a mounted directory. The following two functions support this. </p>  <dl> <dt id="make-nearby-temp-file">Function: <strong>make-nearby-temp-file</strong> <em>prefix &amp;optional dir-flag suffix</em>
</dt> <dd>
<p>This function is similar to <code>make-temp-file</code>, but it creates a temporary file as close as possible to <code>default-directory</code>. If <var>prefix</var> is a relative file name, and <code>default-directory</code> is a remote file name or located on a mounted file systems, the temporary file is created in the directory returned by the function <code>temporary-file-directory</code>. Otherwise, the function <code>make-temp-file</code> is used. <var>prefix</var>, <var>dir-flag</var> and <var>suffix</var> have the same meaning as in <code>make-temp-file</code>. </p> <div class="example"> <pre class="example">(let ((default-directory "/ssh:remotehost:"))
  (make-nearby-temp-file "foo"))
     ⇒ "/ssh:remotehost:/tmp/foo232J6v"
</pre>
</div> </dd>
</dl> <dl> <dt id="temporary-file-directory">Function: <strong>temporary-file-directory</strong>
</dt> <dd><p>The directory for writing temporary files via <code>make-nearby-temp-file</code>. In case of a remote <code>default-directory</code>, this is a directory for temporary files on that remote host. If such a directory does not exist, or <code>default-directory</code> ought to be located on a mounted file system (see <code>mounted-file-systems</code>), the function returns <code>default-directory</code>. For a non-remote and non-mounted <code>default-directory</code>, the value of the variable <code>temporary-file-directory</code> is returned. </p></dd>
</dl> <p>In order to extract the local part of the file’s name of a temporary file, use <code>file-local-name</code> (see <a href="magic-file-names">Magic File Names</a>). </p><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/Unique-File-Names.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/Unique-File-Names.html</a>
  </p>
</div>