From 0d8588c8e206030d96dce2f59e155e8f699f39f6 Mon Sep 17 00:00:00 2001
From: _ov4 <ov4@ov4.org>
Date: Fri, 9 Oct 2026 07:56:08 +0000
Subject: add some documentation

---
 src/history.cc | 14 ++++++++++++++
 1 file changed, 14 insertions(+)

diff --git a/src/history.cc b/src/history.cc
index 1fb18ed..5ba33ea 100644
--- a/src/history.cc
+++ b/src/history.cc
@@ -36,6 +36,9 @@ string get_default_history_path()
     return get_home_dir() + '/' + ".ccshell_history";
 }
 
+/*
+ * load history from file
+ */
 void load_history(const string &path)
 {
     history_vec.clear();
@@ -53,8 +56,19 @@ void load_history(const string &path)
     return;
 }
 
+
+/*
+ * atomically save history to file
+ */
 void save_history(const string &path)
 {
+    /*
+     * C++ and C standard lib do not guarantee that write is atomic
+     * So if the program crashes, or computer shutdowns, it will leave a bad file
+     * Then reading it may lead to problems if we launch the shell again
+     * But unix guarantees rename(2) is atomic
+     * So we just write to a temp file, and rename it to replace the "real" history file
+     */
     string tmp_path = path + ".tmp";
     int fd = open(tmp_path.c_str(), (O_WRONLY | O_CREAT | O_TRUNC), (S_IRUSR | S_IWUSR));
     if (fd == -1) 
-- 
cgit v1.3.1-4-g156e