new repository

1 files changed, 38 insertions, 0 deletions

diff --git a/devdocs/elisp/file-locks.html b/devdocs/elisp/file-locks.html
new file mode 100644
index 00000000..d4be8653
--- /dev/null
+++ b/devdocs/elisp/file-locks.html
@@ -0,0 +1,38 @@
+ <h3 class="section">File Locks</h3>    <p>When two users edit the same file at the same time, they are likely to interfere with each other. Emacs tries to prevent this situation from arising by recording a <em>file lock</em> when a file is being modified. Emacs can then detect the first attempt to modify a buffer visiting a file that is locked by another Emacs job, and ask the user what to do. The file lock is really a file, a symbolic link with a special name, stored in the same directory as the file you are editing. The name is constructed by prepending <samp>.#</samp> to the file name of the buffer. The target of the symbolic link will be of the form <code><var>user</var>@<var>host</var>.<var>pid</var>:<var>boot</var></code>, where <var>user</var> is replaced with the current username (from <code>user-login-name</code>), <var>host</var> with the name of the host where Emacs is running (from <code>system-name</code>), <var>pid</var> with Emacs’s process id, and <var>boot</var> with the time since the last reboot. <code>:<var>boot</var></code> is omitted if the boot time is unavailable. (On file systems that do not support symbolic links, a regular file is used instead, with contents of the form <code><var>user</var>@<var>host</var>.<var>pid</var>:<var>boot</var></code>.) </p> <p>When you access files using NFS, there may be a small probability that you and another user will both lock the same file simultaneously. If this happens, it is possible for the two users to make changes simultaneously, but Emacs will still warn the user who saves second. Also, the detection of modification of a buffer visiting a file changed on disk catches some cases of simultaneous editing; see <a href="modification-time">Modification Time</a>. </p> <dl> <dt id="file-locked-p">Function: <strong>file-locked-p</strong> <em>filename</em>
+</dt> <dd>
+<p>This function returns <code>nil</code> if the file <var>filename</var> is not locked. It returns <code>t</code> if it is locked by this Emacs process, and it returns the name of the user who has locked it if it is locked by some other job. </p> <div class="example"> <pre class="example">(file-locked-p "foo")
+     ⇒ nil
+</pre>
+</div> </dd>
+</dl> <dl> <dt id="lock-buffer">Function: <strong>lock-buffer</strong> <em>&amp;optional filename</em>
+</dt> <dd><p>This function locks the file <var>filename</var>, if the current buffer is modified. The argument <var>filename</var> defaults to the current buffer’s visited file. Nothing is done if the current buffer is not visiting a file, or is not modified, or if the option <code>create-lockfiles</code> is <code>nil</code>. </p></dd>
+</dl> <dl> <dt id="unlock-buffer">Function: <strong>unlock-buffer</strong>
+</dt> <dd><p>This function unlocks the file being visited in the current buffer, if the buffer is modified. If the buffer is not modified, then the file should not be locked, so this function does nothing. It also does nothing if the current buffer is not visiting a file, or is not locked. This function handles file system errors by calling <code>display-warning</code> and otherwise ignores the error. </p></dd>
+</dl> <dl> <dt id="create-lockfiles">User Option: <strong>create-lockfiles</strong>
+</dt> <dd><p>If this variable is <code>nil</code>, Emacs does not lock files. </p></dd>
+</dl> <dl> <dt id="lock-file-name-transforms">User Option: <strong>lock-file-name-transforms</strong>
+</dt> <dd>
+<p>By default, Emacs creates the lock files in the same directory as the files that are being locked. This can be changed by customizing this variable. Is has the same syntax as <code>auto-save-file-name-transforms</code> (see <a href="auto_002dsaving">Auto-Saving</a>). For instance, to make Emacs write all the lock files to <samp>/var/tmp/</samp>, you could say something like: </p> <div class="lisp"> <pre class="lisp">(setq lock-file-name-transforms
+      '(("\\`/.*/\\([^/]+\\)\\'" "/var/tmp/\\1" t)))
+</pre>
+</div> </dd>
+</dl> <dl> <dt id="ask-user-about-lock">Function: <strong>ask-user-about-lock</strong> <em>file other-user</em>
+</dt> <dd>
+<p>This function is called when the user tries to modify <var>file</var>, but it is locked by another user named <var>other-user</var>. The default definition of this function asks the user to say what to do. The value this function returns determines what Emacs does next: </p> <ul> <li> A value of <code>t</code> says to grab the lock on the file. Then this user may edit the file and <var>other-user</var> loses the lock. </li>
+<li> A value of <code>nil</code> says to ignore the lock and let this user edit the file anyway. </li>
+<li>  This function may instead signal a <code>file-locked</code> error, in which case the change that the user was about to make does not take place. <p>The error message for this error looks like this: </p> <div class="example"> <pre class="example">error→ File is locked: <var>file</var> <var>other-user</var>
+</pre>
+</div> <p>where <code>file</code> is the name of the file and <var>other-user</var> is the name of the user who has locked the file. </p>
+</li>
+</ul> <p>If you wish, you can replace the <code>ask-user-about-lock</code> function with your own version that makes the decision in another way. </p>
+</dd>
+</dl> <dl> <dt id="remote-file-name-inhibit-locks">User Option: <strong>remote-file-name-inhibit-locks</strong>
+</dt> <dd><p>You can prevent the creation of remote lock files by setting the variable <code>remote-file-name-inhibit-locks</code> to <code>t</code>. </p></dd>
+</dl> <dl> <dt id="lock-file-mode">Command: <strong>lock-file-mode</strong>
+</dt> <dd><p>This command, called interactively, toggles the local value of <code>create-lockfiles</code> in the current buffer. </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/File-Locks.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/File-Locks.html</a>
+  </p>
+</div>