sar: Add further comments in code

Signed-off-by: Sebastien GODARD <sysstat@users.noreply.github.com>

diff --git a/sa.h b/sa.h
index 0e2e6ab288fad00b79f73e2f8f17ba87b6eb0ac4..fdb564b4a739fe0f3a7fb0d426c13b859124060d 100644 (file)
--- a/sa.h
+++ b/sa.h
@@ -317,6 +317,12 @@ struct svg_hdr_parm {
  ***************************************************************************
  * Definitions of header structures.
  *
+ * The rule is: "strict writing, broad reading", meaning that sar/sadc can
+ * only append data to a datafile whose format is strictly the same as that
+ * of current version (checking FORMAT_MAGIC is not enough), but sar/sadf
+ * can read data from different versions, providing that FORMAT_MAGIC value
+ * has not changed.
+ *
  * Format of system activity data files:
  *      __
  *     |
@@ -398,6 +404,9 @@ struct file_magic {
        unsigned int upgraded;
        /*
         * Padding. Reserved for future use while avoiding a format change.
+        * sysstat always reads a number of bytes which is that expected for
+        * current sysstat version (FILE_MAGIC_SIZE). We cannot guess if we
+        * are going to read a file from current, an older or a newer version.
         */
        unsigned char pad[FILE_MAGIC_PADDING];
 };

diff --git a/sa_common.c b/sa_common.c
index 1f931728213e168a8c071fba029bc64d8c828dd7..5a7493a41553313e3a94e640c95c562306e07f37 100644 (file)
--- a/sa_common.c
+++ b/sa_common.c
@@ -1375,7 +1375,7 @@ int sa_open_read_magic(int *fd, char *dfile, struct file_magic *file_magic,
                }
        }
        if (file_magic->format_magic != FORMAT_MAGIC)
-               /* This is an old sa datafile format */
+               /* This is an old (or new) sa datafile format */
                return -1;
 
        return 0;
@@ -1384,12 +1384,14 @@ int sa_open_read_magic(int *fd, char *dfile, struct file_magic *file_magic,
 /*
  ***************************************************************************
  * Open a data file, and perform various checks before reading.
+ * NB: This is called only when reading a datafile (sar and sadf), never
+ * when writing or appending data to a datafile.
  *
  * IN:
  * @dfile      Name of system activity data file.
  * @act                Array of activities.
  * @ignore     Set to 1 if a true sysstat activity file but with a bad
- *             format should not yield an error message. Useful with
+ *             format should not yield an error message. Used with
  *             sadf -H and sadf -c.
  *
  * OUT:
@@ -1419,6 +1421,9 @@ void check_file_actlst(int *ifd, char *dfile, struct activity *act[],
        if (sa_open_read_magic(ifd, dfile, file_magic, ignore, endian_mismatch) < 0)
                return;
 
+       /* We know now that we have a *compatible* sysstat datafile format */
+
+       /* Allocate buffer for file_header structure */
        SREALLOC(buffer, char, file_magic->header_size);
 
        /* Read sa data file standard header and allocate activity list */