another round of sgj_* function renaming; sg_inq+sg_vpd: add new Block Limits VPD page code

git-svn-id: https://svn.bingwo.ca/repos/sg3_utils/trunk@961 6180dd3e-e324-4e3e-922d-17de1ae2f315

1 files changed, 102 insertions, 75 deletions

diff --git a/include/sg_pr2serr.h b/include/sg_pr2serr.h
index 23295a50..ad3cec94 100644
--- a/include/sg_pr2serr.h
+++ b/include/sg_pr2serr.h
@@ -37,12 +37,13 @@ int pr2serr(const char * fmt, ...) __printf(1, 2);
 int pr2ws(const char * fmt, ...) __printf(1, 2);
 
 /* Want safe, 'n += snprintf(b + n, blen - n, ...)' style sequence of
- * functions. Returns number of chars placed in cp excluding the
- * trailing null char. So for cp_max_len > 0 the return value is always
- * < cp_max_len; for cp_max_len <= 1 the return value is 0 and no chars are
- * written to cp. Note this means that when cp_max_len = 1, this function
- * assumes that cp[0] is the null character and does nothing (and returns
- * 0). Linux kernel has a similar function called  scnprintf().  */
+ * functions that can be called mulriple times. Returns number of chars
+ * placed in cp excluding the trailing null char. So for cp_max_len > 0 the
+ * return value is always < cp_max_len; for cp_max_len <= 1 the return value
+ * is 0 and no chars are written to cp. Note this means that when
+ * cp_max_len = 1, this function assumes that cp[0] is the null character
+ * and does nothing (and returns 0). Linux kernel has a similar function
+ * called  scnprintf().  */
 int sg_scnpr(char * cp, int cp_max_len, const char * fmt, ...) __printf(3, 4);
 
 /* JSON support functions and structures follow. The prefix "sgj_" is used
@@ -72,7 +73,7 @@ typedef struct sgj_state_t {
     bool pr_exit_status;        /* 'e' (def: true) */
     bool pr_hex;                /* 'h' (def: false) */
     bool pr_leadin;             /* 'l' (def: true) */
-    bool pr_name_ex;        /* 'n' name extra (information) (def: false) */
+    bool pr_name_ex;        /* 'n' name_extra (information) (def: false) */
     bool pr_out_hr;             /* 'o' (def: false) */
     bool pr_packed;             /* 'k' (def: false) only when !pr_pretty */
     bool pr_pretty;             /* 'p' (def: true) */
@@ -96,6 +97,24 @@ typedef struct sgj_state_t {
  * Note: strlen(in_name) should be <= max_sname_len . */
 char * sgj_convert_to_snake_name(const char * in_name, char * sname,
                                  int max_sname_len);
+/* There are many variants of JSON supporting functions below and some
+ * abbreaviations are used to shorten their function names:
+ *    sgj_  - prefix of all the functions related to (non-)JSON output
+ *    hr    - human readable form (as it was before JSON)
+ *    js    - JSON only output (unless 'hr_js' given)
+ *    pr    - has printf() like variadic arguments
+ *    _r    - suffix indicating the return value should/must be used
+ *    nv    - adds a name-value JSON field (or several)
+ *    o     - value is the provided JSON object (or array)
+ *    i     - value is a JSON integer object (int64_t or uint64_t)
+ *    b     - value is a JSON boolean object
+ *    s     - value is a JSON string object
+ *    str   - same as s
+ *    hex   - value is hexadecimal in a JSON string object
+ *    _nex  - extra 'name_extra' JSON string object about name
+ *    new   - object that needs sgj_free_unattached() it not attached
+ *
+ *    */
 
 /* If jsp in non-NULL and jsp->pr_as_json is true then this call is ignored
  * unless jsp->pr_out_hrp is true. Otherwise this function prints to stdout
@@ -126,16 +145,16 @@ bool sgj_init_state(sgj_state * jsp, const char * j_optarg);
  * (creating it in the case when jsp->pr_leadin is false) and a pointer to
  * that array object is placed in jsp->objectp . The returned pointer is not
  * usually needed but if it is NULL then a heap allocation has failed. */
-sgj_opaque_p sgj_start(const char * util_name, const char * ver_str,
-                       int argc, char *argv[], sgj_state * jsp);
+sgj_opaque_p sgj_start_r(const char * util_name, const char * ver_str,
+                         int argc, char *argv[], sgj_state * jsp);
 
 /* These are low level functions returning a pointer to a newly created JSON
  * object or array. If jsp is NULL or jsp->pr_as_json is false nothing happens
  * and NULL is returned. Note that this JSON object is _not_ placed in the
  * in-core tree controlled by jsp (jsp->basep); it may be added later as the
- * fourth argument to sgj_add_nv_o(), for example. */
-sgj_opaque_p sgj_new_unattached_object(sgj_state * jsp);
-sgj_opaque_p sgj_new_unattached_array(sgj_state * jsp);
+ * fourth argument to sgj_js_nv_o(), for example. */
+sgj_opaque_p sgj_new_unattached_object_r(sgj_state * jsp);
+sgj_opaque_p sgj_new_unattached_array_r(sgj_state * jsp);
 
 /* If jsp is NULL or jsp->pr_as_json is false nothing happens and NULL is
  * returned. Otherwise it creates a new named object (whose name is what
@@ -143,10 +162,10 @@ sgj_opaque_p sgj_new_unattached_array(sgj_state * jsp);
  * to that empty object is returned. If 'jop' is NULL then jsp->basep is
  * used instead. The returned value should always be checked (for NULL)
  * and if not, used. */
-sgj_opaque_p sgj_new_named_object(sgj_state * jsp, sgj_opaque_p jop,
-                                  const char * name);
-sgj_opaque_p sgj_new_snake_named_object(sgj_state * jsp, sgj_opaque_p jop,
-                                        const char * conv2sname);
+sgj_opaque_p sgj_named_subobject_r(sgj_state * jsp, sgj_opaque_p jop,
+                                   const char * name);
+sgj_opaque_p sgj_snake_named_subobject_r(sgj_state * jsp, sgj_opaque_p jop,
+                                         const char * conv2sname);
 
 /* If jsp is NULL or jsp->pr_as_json is false nothing happens and NULL is
  * returned. Otherwise it creates a new named object (whose name is what
@@ -154,10 +173,10 @@ sgj_opaque_p sgj_new_snake_named_object(sgj_state * jsp, sgj_opaque_p jop,
  * to that empty array is returned.  If 'jop' is NULL then jsp->basep is
  * used instead. The returned value should always * be checked (for NULL)
  * and if not, used. */
-sgj_opaque_p sgj_new_named_array(sgj_state * jsp, sgj_opaque_p jop,
-                                 const char * name);
-sgj_opaque_p sgj_new_snake_named_array(sgj_state * jsp, sgj_opaque_p jop,
-                                       const char * conv2sname);
+sgj_opaque_p sgj_named_subarray_r(sgj_state * jsp, sgj_opaque_p jop,
+                                  const char * name);
+sgj_opaque_p sgj_snake_named_subarray_r(sgj_state * jsp, sgj_opaque_p jop,
+                                        const char * conv2sname);
 
 /* If either jsp or value is NULL or jsp->pr_as_json is false then nothing
  * happens and NULL is returned. The insertion point is at jop but if it is
@@ -166,11 +185,11 @@ sgj_opaque_p sgj_new_snake_named_array(sgj_state * jsp, sgj_opaque_p jop,
  * 'value'. If 'name' is NULL then 'jop' is assumed to be a JSON array and
  * a JSON string formed from 'value' is added. If successful returns a
  * a pointer newly formed JSON string. */
-sgj_opaque_p sgj_add_nv_s(sgj_state * jsp, sgj_opaque_p jop,
-                          const char * name, const char * value);
-sgj_opaque_p sgj_add_nv_s_len(sgj_state * jsp, sgj_opaque_p jop,
-                              const char * name,
-                              const char * value, int slen);
+sgj_opaque_p sgj_js_nv_s(sgj_state * jsp, sgj_opaque_p jop,
+                         const char * name, const char * value);
+sgj_opaque_p sgj_js_nv_s_len(sgj_state * jsp, sgj_opaque_p jop,
+                             const char * name,
+                             const char * value, int slen);
 
 /* If either jsp is NULL or jsp->pr_as_json is false then nothing happens and
  * NULL is returned. The insertion point is at jop but if it is NULL
@@ -179,8 +198,8 @@ sgj_opaque_p sgj_add_nv_s_len(sgj_state * jsp, sgj_opaque_p jop,
  * 'value'. If 'name' is NULL then 'jop' is assumed to be a JSON array and
  * a JSON integer formed from 'value' is added. If successful returns a
  * a pointer newly formed JSON integer. */
-sgj_opaque_p sgj_add_nv_i(sgj_state * jsp, sgj_opaque_p jop,
-                          const char * name, int64_t value);
+sgj_opaque_p sgj_js_nv_i(sgj_state * jsp, sgj_opaque_p jop,
+                         const char * name, int64_t value);
 
 /* If either jsp is NULL or jsp->pr_as_json is false then nothing happens and
  * NULL is returned. The insertion point is at jop but if it is NULL
@@ -189,8 +208,8 @@ sgj_opaque_p sgj_add_nv_i(sgj_state * jsp, sgj_opaque_p jop,
  * 'value'. If 'name' is NULL then 'jop' is assumed to be a JSON array and
  * a JSON boolean formed from 'value' is added. If successful returns a
  * a pointer newly formed JSON boolean. */
-sgj_opaque_p sgj_add_nv_b(sgj_state * jsp, sgj_opaque_p jop,
-                          const char * name, bool value);
+sgj_opaque_p sgj_js_nv_b(sgj_state * jsp, sgj_opaque_p jop,
+                         const char * name, bool value);
 
 /* If jsp is NULL, jsp->pr_as_json is false or ua_jop is NULL nothing then
  * happens and NULL is returned. 'jop' is the insertion point but if it is
@@ -200,12 +219,12 @@ sgj_opaque_p sgj_add_nv_b(sgj_state * jsp, sgj_opaque_p jop,
  * it. If successful returns ua_jop . The "ua_" prefix stands for unattached.
  * That should be the case before invocation and it will be attached to jop
  * after a successful invocation. This means that ua_jop must have been
- * created by sgj_new_unattached_object() or similar. */
-sgj_opaque_p sgj_add_nv_o(sgj_state * jsp, sgj_opaque_p jop,
-                          const char * name, sgj_opaque_p ua_jop);
+ * created by sgj_new_unattached_object_r() or similar. */
+sgj_opaque_p sgj_js_nv_o(sgj_state * jsp, sgj_opaque_p jop,
+                         const char * name, sgj_opaque_p ua_jop);
 
 /* The '_hr_js_' refers to generating output both for human readable and/or
- * JSON with a single invocation. If jsp is non_NULL and jsp->pr_out_hr is
+ * JSON with a single invocation. If jsp is non-NULL and jsp->pr_out_hr is
  * true then both JSON and human readable output is formed (and the latter is
  * placed in the jsp->out_hrp JSON array). The human readable form will have
  * leadin_sp spaces followed by 'name' then a separator, then 'value' with a
@@ -215,26 +234,35 @@ sgj_opaque_p sgj_add_nv_o(sgj_state * jsp, sgj_opaque_p jop,
  * made from 'value' is added to the JSON array pointed to by 'jop'.
  * Otherwise a 'name'-d JSON object whose value is a JSON string object made
  * from 'value' is added at 'jop'. */
-void sgj_pr_hr_js_vs(sgj_state * jsp, sgj_opaque_p jop, int leadin_sp,
-                     const char * name, enum sgj_separator_t sep,
-                     const char * value);
+void sgj_hr_js_vs(sgj_state * jsp, sgj_opaque_p jop, int leadin_sp,
+                  const char * name, enum sgj_separator_t sep,
+                  const char * value);
 
-/* Similar to sgj_pr_hr_js_vs()'s description with 'JSON string object'
+/* Similar to sgj_hr_js_vs()'s description with 'JSON string object'
  * replaced by 'JSON integer object'. */
-void sgj_pr_hr_js_vi(sgj_state * jsp, sgj_opaque_p jop, int leadin_sp,
-                     const char * name, enum sgj_separator_t sep,
-                     int64_t value);
-void sgj_pr_hr_js_vi_nex(sgj_state * jsp, sgj_opaque_p jop, int leadin_sp,
-                         const char * name, enum sgj_separator_t sep,
-                         int64_t value, const char * nex_s);
-sgj_opaque_p sgj_pr_hr_js_subo(sgj_state * jsp, sgj_opaque_p jop,
-                               int leadin_sp, const char * name,
-                               enum sgj_separator_t sep, int64_t value);
-
-/* Similar to sgj_pr_hr_js_vs()'s description with 'JSON string object'
+void sgj_hr_js_vi(sgj_state * jsp, sgj_opaque_p jop, int leadin_sp,
+                  const char * name, enum sgj_separator_t sep,
+                  int64_t value, bool hex_as_well);
+/* The '_nex' refers to a "name_extra" (information) sub-object (a JSON
+ * string) which explains a bit more about the 'name' entry. This is useful
+ * when T10 specifies the name as an abbreviation (e.g. SYSV). Whether this
+ * sub-object is shown in the JSON output is controlled by the 'n' control
+ * character. */
+void sgj_hr_js_vi_nex(sgj_state * jsp, sgj_opaque_p jop, int leadin_sp,
+                      const char * name, enum sgj_separator_t sep,
+                      int64_t value, bool hex_as_well, const char * nex_s);
+
+/* Similar to above '_hr_js_' calls but a named sub-object is always formed
+ * containing a JSON integer object named "i" whose value is 'value'. The
+ * returned pointer is to that sub-object. */
+sgj_opaque_p sgj_hr_js_subo_r(sgj_state * jsp, sgj_opaque_p jop,
+                              int leadin_sp, const char * name,
+                              enum sgj_separator_t sep, int64_t value);
+
+/* Similar to sgj_hr_js_vs()'s description with 'JSON string object'
  * replaced by 'JSON boolean object'. */
-void sgj_pr_hr_js_vb(sgj_state * jsp, sgj_opaque_p jop, int leadin_sp,
-                     const char * name, enum sgj_separator_t sep, bool value);
+void sgj_hr_js_vb(sgj_state * jsp, sgj_opaque_p jop, int leadin_sp,
+                  const char * name, enum sgj_separator_t sep, bool value);
 
 /* This function only produces JSON output if jsp is non-NULL and
  * jsp->pr_as_json is true. It adds a named object at 'jop' (or jop->basep
@@ -243,8 +271,8 @@ void sgj_pr_hr_js_vb(sgj_state * jsp, sgj_opaque_p jop, int leadin_sp,
  * the other one named 'hex' with 'value' rendered as hex in a JSON string.
  * If jsp->pr_hex is false then there are no sub-objects and the 'value' is
  * rendered as JSON integer. */
-void sgj_add_nv_ihex(sgj_state * jsp, sgj_opaque_p jop,
-                     const char * name, uint64_t value);
+void sgj_js_nv_ihex(sgj_state * jsp, sgj_opaque_p jop,
+                    const char * name, uint64_t value);
 
 /* This function only produces JSON output if jsp is non-NULL and
  * jsp->pr_as_json is true. It adds a named object at 'jop' (or jop->basep
@@ -254,13 +282,13 @@ void sgj_add_nv_ihex(sgj_state * jsp, sgj_opaque_p jop,
  * str_name is NULL then "meaning" will be used. If jsp->pr_string is false
  * then there are no sub-objects and the 'val_i' is rendered as a JSON
  * integer. */
-void sgj_add_nv_istr(sgj_state * jsp, sgj_opaque_p jop,
-                     const char * name, int64_t val_i,
-                     const char * str_name, const char * val_s);
+void sgj_js_nv_istr(sgj_state * jsp, sgj_opaque_p jop,
+                    const char * name, int64_t val_i,
+                    const char * str_name, const char * val_s);
 
-void sgj_add_nv_ihexstr(sgj_state * jsp, sgj_opaque_p jop,
-                        const char * name, int64_t val_i,
-                        const char * str_name, const char * val_s);
+void sgj_js_nv_ihexstr(sgj_state * jsp, sgj_opaque_p jop,
+                       const char * name, int64_t val_i,
+                       const char * str_name, const char * val_s);
 
 /* This function only produces JSON output if jsp is non-NULL and
  * jsp->pr_as_json is true. It adds a named object at 'jop' (or jop->basep
@@ -272,34 +300,33 @@ void sgj_add_nv_ihexstr(sgj_state * jsp, sgj_opaque_p jop,
  * val_i. If jsp->pr_name_ex is false and either jsp->pr_hex or want_hex are
  * false then there are no sub-objects and the 'val_i' is rendered as a JSON
  * integer. */
-void sgj_add_nv_ihex_nex(sgj_state * jsp, sgj_opaque_p jop, const char * name,
-                         int64_t val_i, bool want_hex, const char * nex_s);
+void sgj_js_nv_ihex_nex(sgj_state * jsp, sgj_opaque_p jop, const char * name,
+                        int64_t val_i, bool want_hex, const char * nex_s);
 
-void sgj_add_nv_ihexstr_nex(sgj_state * jsp, sgj_opaque_p jop,
-                            const char * name, int64_t val_i, bool want_hex,
-                            const char * str_name, const char * val_s,
-                            const char * nex_s);
+void sgj_js_nv_ihexstr_nex(sgj_state * jsp, sgj_opaque_p jop,
+                           const char * name, int64_t val_i, bool want_hex,
+                           const char * str_name, const char * val_s,
+                           const char * nex_s);
 
 /* Add hex byte strings irrespective of jsp->pr_hex setting. */
-void
-sgj_add_nv_hex_bytes(sgj_state * jsp, sgj_opaque_p jop, const char * name,
-                     const uint8_t * byte_arr, int num_bytes);
+void sgj_js_nv_hex_bytes(sgj_state * jsp, sgj_opaque_p jop, const char * name,
+                         const uint8_t * byte_arr, int num_bytes);
 
 /* Breaks up the string pointed to by 'sp' into lines and adds them to the
  * jsp->out_hrp array. Treat '\n' in sp as line breaks. Consumes characters
  * from sp until either a '\0' is found or slen is exhausted. Add each line
  * to jsp->out_hrp JSON array (if conditions met). */
-void sgj_pr_str_out_hr(sgj_state * jsp, const char * sp, int slen);
+void sgj_js_str_out(sgj_state * jsp, const char * sp, int slen);
 
 /* This function only produces JSON output if jsp is non-NULL and
  * jsp->pr_as_json is true. 'sbp' is assumed to point to sense data as
  * defined by T10 with a length of 'sb_len' bytes. Returns false if an
  * issue is detetected, else it returns true. */
-bool sgj_pr_js_sense(sgj_state * jsp, sgj_opaque_p jop, const uint8_t * sbp,
-                     int sb_len);
+bool sgj_js_sense(sgj_state * jsp, sgj_opaque_p jop, const uint8_t * sbp,
+                  int sb_len);
 
-bool sgj_pr_js_designation_descriptor(sgj_state * jsp, sgj_opaque_p jop,
-                                      const uint8_t * ddp, int dd_len);
+bool sgj_js_designation_descriptor(sgj_state * jsp, sgj_opaque_p jop,
+                                   const uint8_t * ddp, int dd_len);
 
 /* Nothing in the in-core JSON tree is actually printed to 'fp' (typically
  * stdout) until this call is made. If jsp is NULL, jsp->pr_as_json is false
@@ -307,12 +334,12 @@ bool sgj_pr_js_designation_descriptor(sgj_state * jsp, sgj_opaque_p jop,
  * is true then a new JSON object named "exit_status" and the 'exit_status'
  * value rendered as a JSON integer is appended to jsp->basep. The in-core
  * JSON tree with jsp->basep as its root is streamed to 'fp'. */
-void sgj_pr2file(sgj_state * jsp, sgj_opaque_p jop, int exit_status,
+void sgj_js2file(sgj_state * jsp, sgj_opaque_p jop, int exit_status,
                  FILE * fp);
 
 /* This function is only needed if the pointer returned from either
- * sgj_new_unattached_object() or sgj_new_unattached_array() has not been
- * attached into the in-core JSON tree whose root is jsp->basep . */
+ * sgj_new_unattached_object_r() or sgj_new_unattached_array_r() has not
+ * been attached into the in-core JSON tree whose root is jsp->basep . */
 void sgj_free_unattached(sgj_opaque_p jop);
 
 /* If jsp is NULL or jsp->basep is NULL then this function does nothing.