path: root/devdocs/elisp/writing-to-files.html

 <h3 class="section">Writing to Files</h3>  <p>You can write the contents of a buffer, or part of a buffer, directly to a file on disk using the <code>append-to-file</code> and <code>write-region</code> functions. Don’t use these functions to write to files that are being visited; that could cause confusion in the mechanisms for visiting. </p> <dl> <dt id="append-to-file">Command: <strong>append-to-file</strong> <em>start end filename</em>
</dt> <dd>
<p>This function appends the contents of the region delimited by <var>start</var> and <var>end</var> in the current buffer to the end of file <var>filename</var>. If that file does not exist, it is created. This function returns <code>nil</code>. </p> <p>An error is signaled if you cannot write or create <var>filename</var>. </p> <p>When called from Lisp, this function is completely equivalent to: </p> <div class="example"> <pre class="example">(write-region start end filename t)
</pre>
</div> </dd>
</dl> <dl> <dt id="write-region">Command: <strong>write-region</strong> <em>start end filename &amp;optional append visit lockname mustbenew</em>
</dt> <dd>
<p>This function writes the region delimited by <var>start</var> and <var>end</var> in the current buffer into the file specified by <var>filename</var>. </p> <p>If <var>start</var> is <code>nil</code>, then the command writes the entire buffer contents (<em>not</em> just the accessible portion) to the file and ignores <var>end</var>. </p> <p>If <var>start</var> is a string, then <code>write-region</code> writes or appends that string, rather than text from the buffer. <var>end</var> is ignored in this case. </p> <p>If <var>append</var> is non-<code>nil</code>, then the specified text is appended to the existing file contents (if any). If <var>append</var> is a number, <code>write-region</code> seeks to that byte offset from the start of the file and writes the data from there. </p> <p>If <var>mustbenew</var> is non-<code>nil</code>, then <code>write-region</code> asks for confirmation if <var>filename</var> names an existing file. If <var>mustbenew</var> is the symbol <code>excl</code>, then <code>write-region</code> does not ask for confirmation, but instead it signals an error <code>file-already-exists</code> if the file already exists. Although <code>write-region</code> normally follows a symbolic link and creates the pointed-to file if the symbolic link is dangling, it does not follow symbolic links if <var>mustbenew</var> is <code>excl</code>. </p> <p>The test for an existing file, when <var>mustbenew</var> is <code>excl</code>, uses a special system feature. At least for files on a local disk, there is no chance that some other program could create a file of the same name before Emacs does, without Emacs’s noticing. </p> <p>If <var>visit</var> is <code>t</code>, then Emacs establishes an association between the buffer and the file: the buffer is then visiting that file. It also sets the last file modification time for the current buffer to <var>filename</var>’s modtime, and marks the buffer as not modified. This feature is used by <code>save-buffer</code>, but you probably should not use it yourself. </p> <p>If <var>visit</var> is a string, it specifies the file name to visit. This way, you can write the data to one file (<var>filename</var>) while recording the buffer as visiting another file (<var>visit</var>). The argument <var>visit</var> is used in the echo area message and also for file locking; <var>visit</var> is stored in <code>buffer-file-name</code>. This feature is used to implement <code>file-precious-flag</code>; don’t use it yourself unless you really know what you’re doing. </p> <p>The optional argument <var>lockname</var>, if non-<code>nil</code>, specifies the file name to use for purposes of locking and unlocking, overriding <var>filename</var> and <var>visit</var> for that purpose. </p> <p>The function <code>write-region</code> converts the data which it writes to the appropriate file formats specified by <code>buffer-file-format</code> and also calls the functions in the list <code>write-region-annotate-functions</code>. See <a href="format-conversion">Format Conversion</a>. </p> <p>Normally, <code>write-region</code> displays the message ‘<samp>Wrote <var>filename</var></samp>’ in the echo area. This message is inhibited if <var>visit</var> is neither <code>t</code> nor <code>nil</code> nor a string, or if Emacs is operating in batch mode (see <a href="batch-mode">Batch Mode</a>). This feature is useful for programs that use files for internal purposes, files that the user does not need to know about. </p>
</dd>
</dl> <dl> <dt id="write-region-inhibit-fsync">Variable: <strong>write-region-inhibit-fsync</strong>
</dt> <dd><p>If this variable’s value is <code>nil</code>, <code>write-region</code> uses the <code>fsync</code> system call after writing a file. Although this slows Emacs down, it lessens the risk of data loss after power failure. If the value is <code>t</code>, Emacs does not use <code>fsync</code>. The default value is <code>nil</code> when Emacs is interactive, and <code>t</code> when Emacs runs in batch mode. See <a href="files-and-storage">Files and Storage</a>. </p></dd>
</dl> <dl> <dt id="with-temp-file">Macro: <strong>with-temp-file</strong> <em>file body…</em>
</dt> <dd>
<p>The <code>with-temp-file</code> macro evaluates the <var>body</var> forms with a temporary buffer as the current buffer; then, at the end, it writes the buffer contents into file <var>file</var>. It kills the temporary buffer when finished, restoring the buffer that was current before the <code>with-temp-file</code> form. Then it returns the value of the last form in <var>body</var>. </p> <p>The current buffer is restored even in case of an abnormal exit via <code>throw</code> or error (see <a href="nonlocal-exits">Nonlocal Exits</a>). </p> <p>Like <code>with-temp-buffer</code> (see <a href="current-buffer#Definition-of-with_002dtemp_002dbuffer">Current Buffer</a>), the temporary buffer used by this macro does not run the hooks <code>kill-buffer-hook</code>, <code>kill-buffer-query-functions</code> (see <a href="killing-buffers">Killing Buffers</a>), and <code>buffer-list-update-hook</code> (see <a href="buffer-list">Buffer List</a>). </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/Writing-to-Files.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/Writing-to-Files.html</a>
  </p>
</div>