# HG changeset patch
# User Matthew Wild <mwild1@gmail.com>
# Date 1738852938 0
# Node ID 2b3d499365183cb7b421fc63280932353b94ad05
# Parent  4e7ac0e8dfc4b93936f6fe58a41a4a8feeb26ae6
util.prosodyctl: Add comments to explain logic and expected behaviour (#1688)

diff -r 4e7ac0e8dfc4 -r 2b3d49936518 util/prosodyctl.lua
--- a/util/prosodyctl.lua	Thu Feb 06 14:35:29 2025 +0000
+++ b/util/prosodyctl.lua	Thu Feb 06 14:42:18 2025 +0000
@@ -40,6 +40,7 @@
 		["unable-to-save-data"] = "Unable to store, perhaps you don't have permission?";
 		["no-pidfile"] = "There is no 'pidfile' option in the configuration file, see https://prosody.im/doc/prosodyctl#pidfile for help";
 		["invalid-pidfile"] = "The 'pidfile' option in the configuration file is not a string, see https://prosody.im/doc/prosodyctl#pidfile for help";
+		["pidfile-not-locked"] = "Stale pidfile found. Prosody is probably not running.";
 		["no-posix"] = "The mod_posix module is not enabled in the Prosody config file, see https://prosody.im/doc/prosodyctl for more info";
 		["no-such-method"] = "This module has no commands";
 		["not-running"] = "Prosody is not running";
@@ -143,8 +144,14 @@
 		return false, "pidfile-read-failed", err;
 	end
 
+	-- Check for a lock on the file
 	local locked, err = lfs.lock(file, "w"); -- luacheck: ignore 211/err
 	if locked then
+		-- Prosody keeps the pidfile locked while it is running.
+		-- We successfully locked the file, which means Prosody is not
+		-- running and the pidfile is stale (somehow it was not
+		-- cleaned up). We'll abort here, to avoid sending signals to
+		-- a non-Prosody PID.
 		file:close();
 		return false, "pidfile-not-locked";
 	end