Documentation updates

include/vapi/vsc.h

@@ -60,30 +60,12 @@ int VSC_Arg(struct VSM_data *vd, int arg, const char *opt);
 	 */
 
 struct VSC_C_mgt *VSC_Mgt(struct VSM_data *vd, struct VSM_fantom *fantom);
-	/*
-	 * Looks up and returns the management stats structure. If fantom
-	 * is non-NULL, it can if successful later be used with
-	 * VSM_StillValid. Returns NULL until the management process has
-	 * finished initialization.
-	 *
-	 * The returned structure is valid for at most 60 seconds after
-	 * VSM_StillValid(,fantom) starts returning VSM_invalid. Using the
-	 * pointer after this event gives undefined behavior.
-	 *
-	 * Arguments:
-	 *	    vd: The VSM_data context
-	 *	fantom: Pointer to a fantom. Can be NULL.
-	 *
-	 * Return values:
-	 *      NULL: Failure
-	 *  non-NULL: Success
-	 */
-
 struct VSC_C_main *VSC_Main(struct VSM_data *vd, struct VSM_fantom *fantom);
 	/*
-	 * Looks up and returns the main stats structure. If fantom is
-	 * non-NULL, it can if successful later be used with
-	 * VSM_StillValid. Returns NULL until child has been started.
+	 * Looks up and returns the management stats and the child main
+	 * stats structure. If fantom is non-NULL, it can later be used
+	 * with VSM_StillValid. Returns NULL until the management process
+	 * has finished initialization or the child has been started.
 	 *
 	 * The returned structure is valid for at most 60 seconds after
 	 * VSM_StillValid(,fantom) starts returning VSM_invalid. Using the

include/vapi/vsm.h

@@ -151,9 +151,28 @@ enum VSM_valid_e {
 enum VSM_valid_e VSM_StillValid(const struct VSM_data *vd,
     struct VSM_fantom *vf);
 	/*
-	 * This is a cheap syscall-less check to see if the fantom is still
-	 * valid.  Further checking with VSM_Abandoned() may be a good
-	 * idea.
+	 * Check the validity of a previously looked up VSM_fantom.
+	 *
+	 * VSM_invalid means that the SHM chunk this fantom points to does
+	 * not exist in the log file any longer. Using the fantom's
+	 * pointer gives undefined results. Further checking with
+	 * VSM_Abandoned() may be a good idea.
+	 *
+	 * VSM_valid means that the SHM structure has not changed since
+	 * the fantom was looked up or since the last call to
+	 * VSM_StillValid().
+	 *
+	 * VSM_similar means that the SHM structure has changed, but there
+	 * is still a valid chunk present with the same the same type and
+	 * identifier. The fantom's pointers and dimensions haven't
+	 * changed. The next call to VSM_StillValid() on this fantom will
+	 * return VSM_valid.
+	 *
+	 * Applications using the fantom to monitor a single chunk can
+	 * treat VSM_similar as equal to VSM_valid.  Applications using a
+	 * fantom to monitor the SHM file for new or removed chunks,
+	 * should reiterate over the chunks on VSM_similar as the
+	 * structure has changed.
 	 *
 	 * Return:
 	 *   VSM_invalid: fantom is not valid any more.