From c06c68253b90670ca66f22be40ffbd198f22145f Mon Sep 17 00:00:00 2001
From: Laurent Bercot <ska-skaware@skarnet.org>
Date: Sat, 30 Sep 2017 13:14:20 +0000
Subject:  Add doc precisions about live compiled dbs

---
 doc/s6-rc-compile.html | 17 +++++++++++++++++
 doc/s6-rc-init.html    |  4 ++++
 doc/s6-rc-update.html  |  5 +++++
 3 files changed, 26 insertions(+)

(limited to 'doc')

diff --git a/doc/s6-rc-compile.html b/doc/s6-rc-compile.html
index d78e7ad..d23f071 100644
--- a/doc/s6-rc-compile.html
+++ b/doc/s6-rc-compile.html
@@ -374,6 +374,23 @@ instance managed by an automatically generated longrun service named
 <tt>s6rc-fdholder</tt>.
 </p>
 
+<h2> Compiled database usage </h2>
+
+<ul>
+ <li> Once it has been built with s6-rc-compile, a compiled database cannot be
+modified. It (i.e. the directory containing the <em>n</em>, <em>db</em> and
+<em>resolve.cdb</em> files as well as the <em>servicedirs</em< subdirectory)
+can be moved around in the filesystem, provided the insides remain
+untouched. </li>
+ <li> Once a compiled database is live (i.e. it has services running on it,
+following an invocation of <a href="s6-rc-init.html">s6-rc-init</a> or
+<a href="s6-rc-update.html">s6-rc-update</a>, it <em>must not move anymore</em>,
+and it must not be deleted. The only way to "free" such a compiled database
+for displacement or deletion is to replace it as the live one via another
+call to <a href="s6-rc-update.html">s6-rc-update</a>. </li>
+</ul>
+
+
 <h2> A complete example </h2>
 
 <p>
diff --git a/doc/s6-rc-init.html b/doc/s6-rc-init.html
index 54692bf..f3a7bb1 100644
--- a/doc/s6-rc-init.html
+++ b/doc/s6-rc-init.html
@@ -129,6 +129,10 @@ compiled service databases into some versioned directory, and that
 use. This will make it easier to create new compiled databases and
 switch them with <a href="s6-rc-update.html">s6-rc-update</a>
 without having to change the s6-rc-init invocation in boot scripts. </li>
+ <li> After s6-rc-init runs, <em>compiled</em> has become the
+"live compiled database", and must not be tampered with or deleted.
+The only way to free it for deletion is to replace it with another
+database, via a call to <a href="s6-rc-update.html">s6-rc-update</a>. </li>
 </ul>
 
 </body>
diff --git a/doc/s6-rc-update.html b/doc/s6-rc-update.html
index 6c23975..178d299 100644
--- a/doc/s6-rc-update.html
+++ b/doc/s6-rc-update.html
@@ -272,6 +272,11 @@ old compiled unless more work is performed. It is recommended to keep a
 <a href="s6-rc-init.html">s6-rc-init</a> on <tt>current</tt>, and to
 make <tt>current</tt> a link to the new compiled right after a s6-rc-update
 invocation. </li>
+ <li> s6-rc-update is the only way to "free" the old compiled database
+for displacement or deletion. A live compiled database must not be
+tampered with. After a s6-rc-update invocation, the old database isn't
+live anymore and can be moved or deleted; instead, <em>newdb</em> is
+live. </li>
 </ul>
 
 </body>
-- 
cgit v1.2.3