sg_rem_rest_elem: new utility for removing or restoring elements; bug fixes

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

2 files changed, 111 insertions, 50 deletions

diff --git a/include/sg_lib.h b/include/sg_lib.h
index 383e9072..0fa4693a 100644
--- a/include/sg_lib.h
+++ b/include/sg_lib.h
@@ -230,9 +230,16 @@ int sg_get_sense_key(const uint8_t * sensep, int sense_len);
 /* Yield string associated with sense_key value. Returns 'buff'. */
 char * sg_get_sense_key_str(int sense_key, int buff_len, char * buff);
 
-/* Yield string associated with ASC/ASCQ values. Returns 'buff'. */
+/* Yield string associated with ASC/ASCQ values. Returns 'buff'. Prefixes
+ * any valid additional sense found with "Additional sense: ". */
 char * sg_get_asc_ascq_str(int asc, int ascq, int buff_len, char * buff);
 
+/* Same as sg_get_asc_ascq_str() when add_sense_leadin is true. When it is
+ * false this function does _not_ prefix any valid additional sense found
+ * with "Additional sense: ". */
+char * sg_get_additional_sense_str(int asc, int ascq, bool add_sense_leadin,
+                                   int buff_len, char * buff);
+
 /* Returns true if valid bit set, false if valid bit clear. Irrespective the
  * information field is written out via 'info_outp' (except when it is
  * NULL). Handles both fixed and descriptor sense formats. */
@@ -584,6 +591,25 @@ int sg_vpd_dev_id_iter(const uint8_t * initial_desig_desc, int page_len,
  * If errnum is negative, flip its sign. */
 char * safe_strerror(int errnum);
 
+/* Not all platforms support the Unix sleep(seconds) function. */
+void sg_sleep_secs(int num_secs);
+
+/* There are several SCSI commands that are very destructive for the user
+ * data stored on a device. The FORMAT UNIT command is the prime example
+ * but there are an increasing number of newer SCSI commands that remove or
+ * destroy some or all of the user's data. This function takes 15 seconds,
+ * divided into three parts, saying that 'cmd_name' will be executed on
+ * 'dev_name' and then waits for 5 seconds inviting the user to press
+ * control-C to abort the operation. After three such prompts the function
+ * returns and the utility start to execute the "dangerous" SCSI command,
+ * Utilities that use this function usually have a --quick option to bypass
+ * this call. That may be appropriate if the utility in question is called
+ * from a script or in background processing. If 'stress_all' is true then
+ * state "ALL data" will be lost, if false drop the "ALL". */
+void
+sg_warn_and_wait(const char * cmd_name, const char * dev_name,
+                 bool stress_all);
+
 
 /* Print (to stdout) 'str' of bytes in hex, 16 bytes per line optionally
  * followed at the right hand side of the line with an ASCII interpretation.
@@ -607,24 +633,24 @@ void dStrHexErr(const char * str, int len, int no_ascii);
  * 'no_ascii' selects one of 3 output format types as shown in dStrHex() . */
 void dStrHexFp(const char* str, int len, int no_ascii, FILE * fp);
 
-/* Read 'len' bytes from 'str' and output as ASCII-Hex bytes (space
- * separated) to 'b' not to exceed 'b_len' characters. Each line
- * starts with 'leadin' (NULL for no leadin) and there are 16 bytes
- * per line with an extra space between the 8th and 9th bytes. 'format'
- * is 0 for repeat in printable ASCII ('.' for non printable chars) to
- * right of each line; 1 don't (so just output ASCII hex). Note that
- * an address is not printed on each line preceding the hex data. Returns
- * number of bytes written to 'b' excluding the trailing '\0'.
- * The only difference between dStrHexStr() and hex2str() is the type of
- * the first argument. */
-int dStrHexStr(const char * str, int len, const char * leadin, int format,
+/* Read 'len' bytes from 'str' and output as ASCII-Hex bytes (space separated)
+ * to 'b' not to exceed 'b_len' characters. Each line starts with 'leadin'
+ * (NULL for no leadin) and there are 16 bytes per line with an extra space
+ * between the 8th and 9th bytes. 'oformat' is 0 for repeat in printable ASCII
+ * ('.' for non printable chars) to right of each line; 1 don't (so just
+ * output ASCII hex). If 'oformat' is 2 output same as 1 but any LFs are
+ * replaced by space (and trailing spaces are trimmed). Note that an address
+ * is not printed on each line preceding the hex data. Returns number of bytes
+ * written to 'b' excluding the trailing '\0'. The only difference between
+ * dStrHexStr() and hex2str() is the type of the first argument. */
+int dStrHexStr(const char * str, int len, const char * leadin, int oformat,
                int cb_len, char * cbp);
-int hex2str(const uint8_t * b_str, int len, const char * leadin, int format,
+int hex2str(const uint8_t * b_str, int len, const char * leadin, int oformat,
             int cb_len, char * cbp);
 
 /* Similar to hex2str() but outputs to file pointed to be fp */
-void hex2fp(const uint8_t * b_str, int len, const char * leadin, int format,
-	    FILE * fp);
+void hex2fp(const uint8_t * b_str, int len, const char * leadin, int oformat,
+            FILE * fp);
 
 /* The following 2 functions are equivalent to dStrHex() and dStrHexErr()
  * respectively. The difference is only the type of the first of argument:
@@ -635,11 +661,12 @@ void hex2stderr(const uint8_t * b_str, int len, int no_ascii);
 
 /* Read ASCII hex bytes or binary from fname (a file named '-' taken as
  * stdin). If reading ASCII hex then there should be either one entry per
- * line or a comma, space or tab separated list of bytes. If no_space is
- * set then a string of ACSII hex digits is expected, 2 per byte. Everything
- * from and including a '#' on a line is ignored. Returns 0 if ok, or an
- * error code. If the error code is SG_LIB_LBA_OUT_OF_RANGE then mp_arr
- * would be exceeded and both mp_arr and mp_arr_len are written to. */
+ * line or a comma, space, hyphen or tab separated list of bytes. If
+ * no_space is * set then a string of ACSII hex digits is expected, 2 per
+ * byte. Everything from and including a '#' on a line is ignored. Returns
+ * 0 if ok, or an error code. If the error code is
+ * SG_LIB_LBA_OUT_OF_RANGE then mp_arr would be exceeded and both mp_arr
+ * and mp_arr_len are written to. */
 int sg_f2hex_arr(const char * fname, bool as_binary, bool no_space,
                  uint8_t * mp_arr, int * mp_arr_len, int max_arr_len);
 
diff --git a/include/sg_pr2serr.h b/include/sg_pr2serr.h
index a7a09f86..9a1fd273 100644
--- a/include/sg_pr2serr.h
+++ b/include/sg_pr2serr.h
@@ -69,6 +69,7 @@ typedef struct sgj_state_t {
     /* the following set by default, the SG3_UTILS_JSON_OPTS envirinment
      * variable or command line argument to --json option, in that order. */
     bool pr_as_json;            /* = false */
+    bool pr_ane;        /* 'a' abbreviated name expansion (def: false) */
     bool pr_exit_status;        /* 'e' (def: true) */
     bool pr_hex;                /* 'h' (def: false) */
     bool pr_leadin;             /* 'l' (def: true) */
@@ -121,7 +122,7 @@ sgj_opaque_p sgj_start(const char * util_name, const char * ver_str,
  * 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
- * third argument to sgj_add_array_element(), for example. */
+ * 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);
 
@@ -150,8 +151,8 @@ sgj_opaque_p sgj_new_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_val_s(sgj_state * jsp, sgj_opaque_p jop,
-                           const char * name, const char * value);
+sgj_opaque_p sgj_add_nv_s(sgj_state * jsp, sgj_opaque_p jop,
+                          const char * name, const char * 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
@@ -160,8 +161,8 @@ sgj_opaque_p sgj_add_val_s(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_val_i(sgj_state * jsp, sgj_opaque_p jop,
-                           const char * name, int64_t value);
+sgj_opaque_p sgj_add_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
@@ -170,8 +171,8 @@ sgj_opaque_p sgj_add_val_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_val_b(sgj_state * jsp, sgj_opaque_p jop,
-                           const char * name, bool value);
+sgj_opaque_p sgj_add_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
@@ -179,13 +180,13 @@ sgj_opaque_p sgj_add_val_b(sgj_state * jsp, sgj_opaque_p jop,
  * object is added using 'name' and the associated value is ua_jop. If 'name'
  * is NULL then 'jop' is assumed to be a JSON array and ua_jop is added to
  * it. If successful returns ua_jop . The "ua_" prefix stands for unattached.
- * Tha should be the case before invocation and it will be attached to jop
+ * 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_val_o(sgj_state * jsp, sgj_opaque_p jop,
-                           const char * name, sgj_opaque_p ua_jop);
+sgj_opaque_p sgj_add_nv_o(sgj_state * jsp, sgj_opaque_p jop,
+                          const char * name, sgj_opaque_p ua_jop);
 
-/* The '_twin_' refers to generating output both for human readable and/or
+/* 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_output is
  * true then both JSON and human readable output is formed (and the latter is
  * placed in the jsp->outputp JSON array). The human readable form will have
@@ -196,41 +197,74 @@ sgj_opaque_p sgj_add_val_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_twin_vs(sgj_state * jsp, sgj_opaque_p jop, int leadin_sp,
-                    const char * name, enum sgj_separator_t sep,
-                    const char * value);
+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);
 
-/* Similar to sgj_pr_twin_vs()'s description with 'JSON string object'
+/* Similar to sgj_pr_hr_js_vs()'s description with 'JSON string object'
  * replaced by 'JSON integer object'. */
-void sgj_pr_twin_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(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_twin_vs()'s description with 'JSON string object'
+/* Similar to sgj_pr_hr_js_vs()'s description with 'JSON string object'
  * replaced by 'JSON boolean object'. */
-void sgj_pr_twin_vb(sgj_state * jsp, sgj_opaque_p jop, int leadin_sp,
-                    const char * name, enum sgj_separator_t sep, bool value);
+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);
 
 /* 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
  * if jop is NULL) along with a value. If jsp->pr_hex is true then that
  * value is two sub-objects, one named 'i' with a 'value' as a JSON integer,
  * the other one named 'hex' with 'value' rendered as hex in a JSON string.
- * If jsp->pr_hex is false the there are no sub-objects and the 'value' is
+ * If jsp->pr_hex is false then there are no sub-objects and the 'value' is
  * rendered as JSON integer. */
-void sgj_add_name_pair_ihex(sgj_state * jsp, sgj_opaque_p jop,
-                            const char * name, uint64_t value);
+void sgj_add_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
  * if jop is NULL) along with a value. If jsp->pr_string is true then that
  * value is two sub-objects, one named 'i' with a 'val_i' as a JSON integer,
- * the other one named str_name with val_s rendered as a JSON string.
- * If jsp->pr_string is false the there are no sub-objects and the 'val_i' is
- * rendered as JSON integer. */
-void sgj_add_name_pair_istr(sgj_state * jsp, sgj_opaque_p jop,
-                            const char * name, int64_t val_i,
-                            const char * str_name, const char * val_s);
+ * the other one named str_name with val_s rendered as a JSON string. If
+ * 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_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);
+
+/* 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
+ * if jop is NULL) along with a value. If jsp->pr_ane is true then that
+ * value is two sub-objects, one named 'i' with a 'val_i' as a JSON integer,
+ * the other one named "abbreviated_name_expansion" with value ane_s rendered
+ * as a JSON string. If jsp->pr_hex and 'want_hex' are true, then a
+ * sub-object named 'hex' with a value rendered as a hex string equal to
+ * val_i. If jsp->pr_ane 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_ane(sgj_state * jsp, sgj_opaque_p jop, const char * name,
+                         int64_t val_i, bool want_hex, const char * ane_s);
+
+void sgj_add_nv_ihexstr_ane(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 * ane_s);
+
+/* 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_get_sense(sgj_state * jsp, sgj_opaque_p jop, const uint8_t * sbp,
+                   int sb_len);
+
+bool sgj_get_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