path: root/devdocs/elisp/buffer-file-name.html

 <h3 class="section">Buffer File Name</h3>    <p>The <em>buffer file name</em> is the name of the file that is visited in that buffer. When a buffer is not visiting a file, its buffer file name is <code>nil</code>. Most of the time, the buffer name is the same as the nondirectory part of the buffer file name, but the buffer file name and the buffer name are distinct and can be set independently. See <a href="visiting-files">Visiting Files</a>. </p> <dl> <dt id="buffer-file-name">Function: <strong>buffer-file-name</strong> <em>&amp;optional buffer</em>
</dt> <dd>
<p>This function returns the absolute file name of the file that <var>buffer</var> is visiting. If <var>buffer</var> is not visiting any file, <code>buffer-file-name</code> returns <code>nil</code>. If <var>buffer</var> is not supplied, it defaults to the current buffer. </p> <div class="example"> <pre class="example">(buffer-file-name (other-buffer))
     ⇒ "/usr/user/lewis/manual/files.texi"
</pre>
</div> </dd>
</dl> <dl> <dt id="buffer-file-name">Variable: <strong>buffer-file-name</strong>
</dt> <dd>
<p>This buffer-local variable contains the name of the file being visited in the current buffer, or <code>nil</code> if it is not visiting a file. It is a permanent local variable, unaffected by <code>kill-all-local-variables</code>. </p> <div class="example"> <pre class="example">buffer-file-name
     ⇒ "/usr/user/lewis/manual/buffers.texi"
</pre>
</div> <p>It is risky to change this variable’s value without doing various other things. Normally it is better to use <code>set-visited-file-name</code> (see below); some of the things done there, such as changing the buffer name, are not strictly necessary, but others are essential to avoid confusing Emacs. </p>
</dd>
</dl> <dl> <dt id="buffer-file-truename">Variable: <strong>buffer-file-truename</strong>
</dt> <dd><p>This buffer-local variable holds the abbreviated truename of the file visited in the current buffer, or <code>nil</code> if no file is visited. It is a permanent local, unaffected by <code>kill-all-local-variables</code>. See <a href="truenames">Truenames</a>, and <a href="directory-names#abbreviate_002dfile_002dname">abbreviate-file-name</a>. </p></dd>
</dl> <dl> <dt id="buffer-file-number">Variable: <strong>buffer-file-number</strong>
</dt> <dd>
<p>This buffer-local variable holds the file number and directory device number of the file visited in the current buffer, or <code>nil</code> if no file or a nonexistent file is visited. It is a permanent local, unaffected by <code>kill-all-local-variables</code>. </p> <p>The value is normally a list of the form <code>(<var>filenum</var>
<var>devnum</var>)</code>. This pair of numbers uniquely identifies the file among all files accessible on the system. See the function <code>file-attributes</code>, in <a href="file-attributes">File Attributes</a>, for more information about them. </p> <p>If <code>buffer-file-name</code> is the name of a symbolic link, then both numbers refer to the recursive target. </p>
</dd>
</dl> <dl> <dt id="get-file-buffer">Function: <strong>get-file-buffer</strong> <em>filename</em>
</dt> <dd>
<p>This function returns the buffer visiting file <var>filename</var>. If there is no such buffer, it returns <code>nil</code>. The argument <var>filename</var>, which must be a string, is expanded (see <a href="file-name-expansion">File Name Expansion</a>), then compared against the visited file names of all live buffers. Note that the buffer’s <code>buffer-file-name</code> must match the expansion of <var>filename</var> exactly. This function will not recognize other names for the same file. </p> <div class="example"> <pre class="example">(get-file-buffer "buffers.texi")
    ⇒ #&lt;buffer buffers.texi&gt;
</pre>
</div> <p>In unusual circumstances, there can be more than one buffer visiting the same file name. In such cases, this function returns the first such buffer in the buffer list. </p>
</dd>
</dl> <dl> <dt id="find-buffer-visiting">Function: <strong>find-buffer-visiting</strong> <em>filename &amp;optional predicate</em>
</dt> <dd><p>This is like <code>get-file-buffer</code>, except that it can return any buffer visiting the file <em>possibly under a different name</em>. That is, the buffer’s <code>buffer-file-name</code> does not need to match the expansion of <var>filename</var> exactly, it only needs to refer to the same file. If <var>predicate</var> is non-<code>nil</code>, it should be a function of one argument, a buffer visiting <var>filename</var>. The buffer is only considered a suitable return value if <var>predicate</var> returns non-<code>nil</code>. If it can not find a suitable buffer to return, <code>find-buffer-visiting</code> returns <code>nil</code>. </p></dd>
</dl> <dl> <dt id="set-visited-file-name">Command: <strong>set-visited-file-name</strong> <em>filename &amp;optional no-query along-with-file</em>
</dt> <dd>
<p>If <var>filename</var> is a non-empty string, this function changes the name of the file visited in the current buffer to <var>filename</var>. (If the buffer had no visited file, this gives it one.) The <em>next time</em> the buffer is saved it will go in the newly-specified file. </p> <p>This command marks the buffer as modified, since it does not (as far as Emacs knows) match the contents of <var>filename</var>, even if it matched the former visited file. It also renames the buffer to correspond to the new file name, unless the new name is already in use. </p> <p>If <var>filename</var> is <code>nil</code> or the empty string, that stands for “no visited file”. In this case, <code>set-visited-file-name</code> marks the buffer as having no visited file, without changing the buffer’s modified flag. </p> <p>Normally, this function asks the user for confirmation if there already is a buffer visiting <var>filename</var>. If <var>no-query</var> is non-<code>nil</code>, that prevents asking this question. If there already is a buffer visiting <var>filename</var>, and the user confirms or <var>no-query</var> is non-<code>nil</code>, this function makes the new buffer name unique by appending a number inside of ‘<samp>&lt;…&gt;</samp>’ to <var>filename</var>. </p> <p>If <var>along-with-file</var> is non-<code>nil</code>, that means to assume that the former visited file has been renamed to <var>filename</var>. In this case, the command does not change the buffer’s modified flag, nor the buffer’s recorded last file modification time as reported by <code>visited-file-modtime</code> (see <a href="modification-time">Modification Time</a>). If <var>along-with-file</var> is <code>nil</code>, this function clears the recorded last file modification time, after which <code>visited-file-modtime</code> returns zero. </p> <p>When the function <code>set-visited-file-name</code> is called interactively, it prompts for <var>filename</var> in the minibuffer. </p>
</dd>
</dl> <dl> <dt id="list-buffers-directory">Variable: <strong>list-buffers-directory</strong>
</dt> <dd><p>This buffer-local variable specifies a string to display in a buffer listing where the visited file name would go, for buffers that don’t have a visited file name. Dired buffers use this variable. </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/Buffer-File-Name.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/Buffer-File-Name.html</a>
  </p>
</div>