update exit codes and docs

bin/ch-completion.bash

@@ -392,13 +392,7 @@ _ch_image_complete () {
             fi
             ;;
         modify)
-            case "$prev" in
-            -o|--out)
-                # Can’t complete for this option
-                COMPREPLY=()
-                return 0
-                ;;
-            esac
+            # FIXME: Implement
             extras="$extras $_image_modify_opts"
             ;;
         esac

bin/ch_fuse.c

@@ -188,7 +188,7 @@ int sq_loop(void)
 
    // Clean up zombie child if exit signal was SIGCHLD.
    if (!sigchld_received)
-      exit_code = 59;
+      exit_code = ERR_SQUASH;
    else {
       Tf (wait(&child_status) >= 0, "can't wait for child");
       if (WIFEXITED(child_status)) {

bin/ch_misc.h

@@ -24,10 +24,10 @@
    don’t need to worry about running out of room. */
 #define WARNINGS_SIZE (4*1024)
 
-/* Exit codes */
-#define ERR_CHRUN 57
-#define ERR_CMD 58
-#define ERR_SQUASH 59
+/* Exit codes (see also: test/common.bash). */
+#define ERR_CHRUN 31
+#define ERR_CMD 49
+#define ERR_SQUASH 84
 
 /* Test some value, and if it's not what we expect, exit with a fatal error.
    These are macros so we have access to the file and line number.
@@ -67,7 +67,6 @@
 #define T_(x)      if (!(x)) msg_fatal(__FILE__, __LINE__, errno, NULL)
 #define Tf(x, ...) if (!(x)) msg_fatal(__FILE__, __LINE__, errno, __VA_ARGS__)
 #define Te(x, ...) if (!(x)) msg_fatal(__FILE__, __LINE__, 0, __VA_ARGS__)
-#define Terror(x, ...) if (!(x)) msg_error(__FILE__, __LINE__, errno, __VA_ARGS__)
 #define Z_(x)      if (x)    msg_fatal(__FILE__, __LINE__, errno, NULL)
 #define Zf(x, ...) if (x)    msg_fatal(__FILE__, __LINE__, errno, __VA_ARGS__)
 #define Ze(x, ...) if (x)    msg_fatal(__FILE__, __LINE__, 0, __VA_ARGS__)

doc/ch-image.rst

@@ -1905,16 +1905,16 @@ Synopsis
 
 ::
 
-   $ ch-image [...] modify [...] TARGET DEST
+   $ ch-image [...] modify [...] SOURCE DEST
 
 Description
 -----------
 
-This subcommand makes a copy of image :code:`TARGET` named :code:`DEST` and
+This subcommand makes a copy of image :code:`SOURCE` named :code:`DEST` and
 starts a shell on :code:`DEST` in order to edit the image interactively. It is
 similar to a :code:`RUN` instruction that starts an interactive shell. If there
 is already an image named :code:`DEST`, it will be overwritten. :code:`DEST` must
-be different than :code:`TARGET`.
+be different than :code:`SOURCE`.
 
   :code:`-c CMD`
     Run :code:`CMD` inside the container, as though specified by the :code:`RUN`
@@ -1925,6 +1925,56 @@ be different than :code:`TARGET`.
    Use shell :code:`SHELL` for interactive session, rather than the default
    :code:`/bin/sh`.
 
+Build cache implications
+------------------------
+
+Images produced by a :code:`modify` operation (:code:`DEST`) are adopted into
+the  build cache, with the parent being the specified source image
+(:code:`SOURCE`). The nature of :code:`modify` makes it impossible to perform
+the usual computation of state ID (SID) for the resulting cache entry without
+intercepting the input of the interactive session, which is unnecessarily
+complicated. Instead, we assign the adopted image a “fake” SID in the
+form of a version 4 UUID.
+
+SIDs are used to retrieve image states from the cache. Since the :code:`modify`
+operation is at odds with the notion of container provenance, image states
+resulting from :code:`modify` will never be used by the cache, so using UUIDs in
+place of SIDs does not undermine cache functionality. Adoption of modified
+images is done soley for cache consistency rather than actual utility.
+
+Below is an example of cache adoption of a modified image, starting with a
+non-empty cache::
+
+  $ ch-image build-cache --tree
+   *  (bar) IMPORT bar
+   | *  (foo) IMPORT foo
+   |/
+   *  (root) ROOT
+
+   named images:       3
+   state IDs:          3
+   large files:        0
+   commits:            3
+   internal files:     7 K
+   disk used:        227 MiB
+   $ ch-image modify foo baz
+   copying image from cache ...
+   [...]
+   > exit
+   $ ch-image build-cache --tree
+   *  (baz) MODIFY interactive
+   *  (foo) IMPORT foo
+   | *  (bar) IMPORT bar
+   |/
+   *  (root) ROOT
+
+   named images:       4
+   state IDs:          4
+   large files:        0
+   commits:            4
+   internal files:     7 K
+   disk used:        227 MiB
+
 .. warning::
 
    This subcommand is rarely needed. Non-interactive build using a Dockerfile

doc/ch-run.rst

@@ -755,15 +755,17 @@ filesystem and the user command is killed by a signal, the exit status is 1
 regardless of the signal value. Alternatively, :code:`ch-run` can exit with the
 following statuses:
 
-57
+31
   Error during containerization (:code:`ch-run` failure)
 
-58
+49
   Unable to start user command
 
-59
+84
   SquashFUSE loop exited on signal before user command was complete
 
+128+N
+  Child process failed to exit normally, with exit code N
 
 .. include:: ./bugs.rst
 .. include:: ./see_also.rst

test/common.bash

@@ -329,10 +329,10 @@ chmod 700 "$btnew"
 export BATS_TMPDIR=$btnew
 [[ $(stat -c %a "$BATS_TMPDIR") = '700' ]]
 
-# ch-run exit codes (see also: ch_misc.h)
-CH_ERR_RUN=57
-CH_ERR_CMD=58
-CH_ERR_SQUASH=59 # Currently not used, here just in case
+# ch-run exit codes. (see also: ch_misc.h)
+CH_ERR_RUN=31
+CH_ERR_CMD=49
+CH_ERR_SQUASH=84 # Currently not used, here just in case
 
 ch_runfile=$(command -v ch-run)