Document the contents of the shm_path fields of the ust session registry

Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>

diff --git a/src/bin/lttng-sessiond/ust-registry.h b/src/bin/lttng-sessiond/ust-registry.h
index 414975cafc4b1f3b209e49ce5900c7373e18f2dd..2940ab7accea9534b3fe63696f4b5ea6a60a55e6 100644 (file)
--- a/src/bin/lttng-sessiond/ust-registry.h
+++ b/src/bin/lttng-sessiond/ust-registry.h
@@ -71,6 +71,32 @@ struct ust_registry_session {
        /* Current version of the metadata. */
        uint64_t metadata_version;
 
+       /*
+        * Those fields are only used when a session is created with
+        * the --shm-path option. In this case, the metadata is output
+        * twice: once to the consumer, as ususal, but a second time
+        * also in the shm path directly. This is done so that a copy
+        * of the metadata that is as fresh as possible is available
+        * on the event of a crash.
+        *
+        * root_shm_path contains the shm-path provided by the user, along with
+        * the session's name and timestamp:
+        *   e.g. /tmp/my_shm/my_session-20180612-135822
+        *
+        * shm_path contains the full path of the memory buffers:
+        *   e.g. /tmp/my_shm/my_session-20180612-135822/ust/uid/1000/64-bit
+        *
+        * metadata_path contains the full path to the metadata file that
+        * is kept for the "crash buffer" extraction:
+        *  e.g. /tmp/my_shm/my_session-20180612-135822/ust/uid/1000/64-bit/metadata
+        *
+        * Note that this is not the trace's final metadata file. It is
+        * only meant to be used to read the contents of the ring buffers
+        * in the event of a crash.
+        *
+        * metadata_fd is a file descriptor that points to the file at
+        * 'metadata_path'.
+        */
        char root_shm_path[PATH_MAX];
        char shm_path[PATH_MAX];
        char metadata_path[PATH_MAX];