1 #ifndef SG_PR2SERR_H 2 #define SG_PR2SERR_H 3 4 /* 5 * Copyright (c) 2004-2022 Douglas Gilbert. 6 * All rights reserved. 7 * Use of this source code is governed by a BSD-style 8 * license that can be found in the BSD_LICENSE file. 9 * 10 * SPDX-License-Identifier: BSD-2-Clause 11 */ 12 13 #include <inttypes.h> 14 #include <stdio.h> 15 #include <stdbool.h> 16 17 #ifdef __cplusplus 18 extern "C" { 19 #endif 20 21 /* pr2serr and pr2ws are convenience functions that replace the somewhat 22 * long-winded fprintf(stderr, ....). The second form (i.e. pr2ws() ) is for 23 * internal library use and may place its output somewhere other than stderr; 24 * it depends on the external variable sg_warnings_strm which can be set 25 * with sg_set_warnings_strm(). By default it uses stderr. */ 26 27 #if __USE_MINGW_ANSI_STDIO -0 == 1 28 #define __printf(a, b) __attribute__((__format__(gnu_printf, a, b))) 29 #elif defined(__GNUC__) || defined(__clang__) 30 #define __printf(a, b) __attribute__((__format__(printf, a, b))) 31 #else 32 #define __printf(a, b) 33 #endif 34 35 int pr2serr(const char * fmt, ...) __printf(1, 2); 36 37 int pr2ws(const char * fmt, ...) __printf(1, 2); 38 39 /* Want safe, 'n += snprintf(b + n, blen - n, ...)' style sequence of 40 * functions that can be called multiple times. Returns number of chars 41 * placed in cp excluding the trailing null char. So for cp_max_len > 0 the 42 * return value is always < cp_max_len; for cp_max_len <= 1 the return value 43 * is 0 and no chars are written to cp. Note this means that when 44 * cp_max_len = 1, this function assumes that cp[0] is the null character 45 * and does nothing (and returns 0). Linux kernel has a similar function 46 * called scnprintf(). */ 47 int sg_scnpr(char * cp, int cp_max_len, const char * fmt, ...) __printf(3, 4); 48 49 /* JSON support functions and structures follow. The prefix "sgj_" is used 50 * for sg3_utils JSON functions, types and values. */ 51 52 enum sgj_separator_t { 53 SGJ_SEP_NONE = 0, 54 SGJ_SEP_SPACE_1, 55 SGJ_SEP_SPACE_2, 56 SGJ_SEP_SPACE_3, 57 SGJ_SEP_SPACE_4, 58 SGJ_SEP_EQUAL_NO_SPACE, 59 SGJ_SEP_EQUAL_1_SPACE, 60 SGJ_SEP_COLON_NO_SPACE, 61 SGJ_SEP_COLON_1_SPACE, 62 }; 63 64 typedef void * sgj_opaque_p; 65 66 /* Apart from the state information at the end of this structure, the earlier 67 * fields are initialized from the command line argument given to the 68 * --json= option. If there is no argument then they initialized as shown. */ 69 typedef struct sgj_state_t { 70 /* the following set by default, the SG3_UTILS_JSON_OPTS environment 71 * variable or command line argument to --json option, in that order. */ 72 bool pr_as_json; /* = false (def: is human readable output) */ 73 bool pr_exit_status; /* 'e' (def: true) */ 74 bool pr_hex; /* 'h' (def: false) */ 75 bool pr_leadin; /* 'l' (def: true) */ 76 bool pr_name_ex; /* 'n' name_extra (information) (def: false) */ 77 bool pr_out_hr; /* 'o' (def: false) */ 78 bool pr_packed; /* 'k' (def: false) only when !pr_pretty */ 79 bool pr_pretty; /* 'p' (def: true) */ 80 bool pr_string; /* 's' (def: true) */ 81 char pr_format; /* (def: '\0') */ 82 int pr_indent_size; /* digit (def: 4) */ 83 int verbose; /* 'v' (def: 0) incremented each appearance */ 84 85 /* the following hold state information */ 86 int first_bad_char; /* = '\0' */ 87 sgj_opaque_p basep; /* base JSON object pointer */ 88 sgj_opaque_p out_hrp; /* JSON array pointer when pr_out_hr set */ 89 sgj_opaque_p userp; /* for temporary usage */ 90 } sgj_state; 91 92 /* This function tries to convert the in_name C string to the "snake_case" 93 * convention so the output sname only contains lower case ASCII letters, 94 * numerals and "_" as a separator. Any leading or trailing underscores 95 * are removed as are repeated underscores (e.g. "_Snake __ case" becomes 96 * "snake_case"). Parentheses and the characters between them are removed. 97 * Returns sname (i.e. the pointer to the output buffer). 98 * Note: strlen(in_name) should be <= max_sname_len . */ 99 char * sgj_convert_to_snake_name(const char * in_name, char * sname, 100 int max_sname_len); 101 bool sgj_is_snake_name(const char * in_name); 102 103 /* There are many variants of JSON supporting functions below and some 104 * abbreviations are used to shorten their function names: 105 * sgj_ - prefix of all the functions related to (non-)JSON output 106 * hr - human readable form (as it was before JSON) 107 * js - JSON only output 108 * haj - human readable and JSON output, hr goes in 'output' array 109 * pr - has printf() like variadic arguments 110 * _r - suffix indicating the return value should/must be used 111 * nv - adds a name-value JSON field (or several) 112 * o - value is the provided JSON object (or array) 113 * i - value is a JSON integer object (int64_t or uint64_t) 114 * b - value is a JSON boolean object 115 * s - value is a JSON string object 116 * str - same as s 117 * hex - value is hexadecimal in a JSON string object 118 * _nex - extra 'name_extra' JSON string object about name 119 * new - object that needs sgj_free_unattached() if not attached 120 * 121 * */ 122 123 /* If jsp in non-NULL and jsp->pr_as_json is true then this call is ignored 124 * unless jsp->pr_out_hrp is true. Otherwise this function prints to stdout 125 * like printf(fmt, ...); note that no LF is added. In the jsp->pr_out_hrp is 126 * true case, nothing is printed to stdout but instead is placed into a JSON 127 * array (jsp->out_hrp) after some preprocessing. That preprocessing involves 128 * removing a leading LF from 'fmt' (if present) and up to two trailing LF 129 * characters. */ 130 void sgj_pr_hr(sgj_state * jsp, const char * fmt, ...) __printf(2, 3); 131 132 /* Initializes the state object pointed to by jsp based on the argument 133 * given to the right of --json= pointed to by j_optarg. If it is NULL 134 * then state object gets its default values. Returns true if argument 135 * to --json= is decoded properly, else returns false and places the 136 * first "bad" character in jsp->first_bad_char . Note that no JSON 137 * in-core tree needs to exist when this function is called. */ 138 bool sgj_init_state(sgj_state * jsp, const char * j_optarg); 139 140 /* sgj_start() creates a JSON in-core tree and returns a pointer to it (or 141 * NULL if the associated heap allocation fails). It should be paired with 142 * sgj_finish() to clean up (i.e. remove all heap allocations) all the 143 * elements (i.e. JSON objects and arrays) that have been placed in that 144 * in-core tree. If jsp is NULL nothing further happens. Otherwise the pointer 145 * to be returned is placed in jsp->basep. If jsp->pr_leadin is true and 146 * util_name is non-NULL then a "utility_invoked" JSON object is made with 147 * "name", and "version_date" object fields. If the jsp->pr_out_hr field is 148 * true a named array called "output" is added to the "utility_invoked" object 149 * (creating it in the case when jsp->pr_leadin is false) and a pointer to 150 * that array object is placed in jsp->objectp . The returned pointer is not 151 * usually needed but if it is NULL then a heap allocation has failed. */ 152 sgj_opaque_p sgj_start_r(const char * util_name, const char * ver_str, 153 int argc, char *argv[], sgj_state * jsp); 154 155 /* These are low level functions returning a pointer to a newly created JSON 156 * object or array. If jsp is NULL or jsp->pr_as_json is false nothing happens 157 * and NULL is returned. Note that this JSON object is _not_ placed in the 158 * in-core tree controlled by jsp (jsp->basep); it may be added later as the 159 * fourth argument to sgj_js_nv_o(), for example. */ 160 sgj_opaque_p sgj_new_unattached_object_r(sgj_state * jsp); 161 sgj_opaque_p sgj_new_unattached_array_r(sgj_state * jsp); 162 163 /* If jsp is NULL or jsp->pr_as_json is false nothing happens and NULL is 164 * returned. Otherwise it creates a new named object (whose name is what 165 * 'name' points to) at 'jop' with an empty object as its value; a pointer 166 * to that empty object is returned. If 'jop' is NULL then jsp->basep is 167 * used instead. The returned value should always be checked (for NULL) 168 * and if not, used. */ 169 sgj_opaque_p sgj_named_subobject_r(sgj_state * jsp, sgj_opaque_p jop, 170 const char * name); 171 sgj_opaque_p sgj_snake_named_subobject_r(sgj_state * jsp, sgj_opaque_p jop, 172 const char * conv2sname); 173 174 /* If jsp is NULL or jsp->pr_as_json is false nothing happens and NULL is 175 * returned. Otherwise it creates a new named object (whose name is what 176 * 'name' points to) at 'jop' with an empty array as its value; a pointer 177 * to that empty array is returned. If 'jop' is NULL then jsp->basep is 178 * used instead. The returned value should always * be checked (for NULL) 179 * and if not, used. */ 180 sgj_opaque_p sgj_named_subarray_r(sgj_state * jsp, sgj_opaque_p jop, 181 const char * name); 182 sgj_opaque_p sgj_snake_named_subarray_r(sgj_state * jsp, sgj_opaque_p jop, 183 const char * conv2sname); 184 185 /* If either jsp or value is NULL or jsp->pr_as_json is false then nothing 186 * happens and NULL is returned. The insertion point is at jop but if it is 187 * NULL jsp->basep is used. If 'name' is non-NULL a new named JSON object is 188 * added using 'name' and the associated value is a JSON string formed from 189 * 'value'. If 'name' is NULL then 'jop' is assumed to be a JSON array and 190 * a JSON string formed from 'value' is added. Note that the jsp->pr_string 191 * setting is ignored by this function. If successful returns a * a pointer 192 * newly formed JSON string. */ 193 sgj_opaque_p sgj_js_nv_s(sgj_state * jsp, sgj_opaque_p jop, 194 const char * name, const char * value); 195 sgj_opaque_p sgj_js_nv_s_len(sgj_state * jsp, sgj_opaque_p jop, 196 const char * name, 197 const char * value, int slen); 198 199 /* If either jsp is NULL or jsp->pr_as_json is false then nothing happens and 200 * NULL is returned. The insertion point is at jop but if it is NULL 201 * jsp->basep is used. If 'name' is non-NULL a new named JSON object is 202 * added using 'name' and the associated value is a JSON integer formed from 203 * 'value'. If 'name' is NULL then 'jop' is assumed to be a JSON array and 204 * a JSON integer formed from 'value' is added. If successful returns a 205 * a pointer newly formed JSON integer. */ 206 sgj_opaque_p sgj_js_nv_i(sgj_state * jsp, sgj_opaque_p jop, 207 const char * name, int64_t value); 208 209 /* If either jsp is NULL or jsp->pr_as_json is false then nothing happens and 210 * NULL is returned. The insertion point is at jop but if it is NULL 211 * jsp->basep is used. If 'name' is non-NULL a new named JSON object is 212 * added using 'name' and the associated value is a JSON boolean formed from 213 * 'value'. If 'name' is NULL then 'jop' is assumed to be a JSON array and 214 * a JSON boolean formed from 'value' is added. If successful returns a 215 * a pointer newly formed JSON boolean. */ 216 sgj_opaque_p sgj_js_nv_b(sgj_state * jsp, sgj_opaque_p jop, 217 const char * name, bool value); 218 219 /* If jsp is NULL, jsp->pr_as_json is false or ua_jop is NULL nothing then 220 * happens and NULL is returned. 'jop' is the insertion point but if it is 221 * NULL jsp->basep is used instead. If 'name' is non-NULL a new named JSON 222 * object is added using 'name' and the associated value is ua_jop. If 'name' 223 * is NULL then 'jop' is assumed to be a JSON array and ua_jop is added to 224 * it. If successful returns ua_jop . The "ua_" prefix stands for unattached. 225 * That should be the case before invocation and it will be attached to jop 226 * after a successful invocation. This means that ua_jop must have been 227 * created by sgj_new_unattached_object_r() or similar. */ 228 sgj_opaque_p sgj_js_nv_o(sgj_state * jsp, sgj_opaque_p jop, 229 const char * name, sgj_opaque_p ua_jop); 230 231 /* This function only produces JSON output if jsp is non-NULL and 232 * jsp->pr_as_json is true. It adds a named object at 'jop' (or jop->basep 233 * if jop is NULL) along with a value. If jsp->pr_hex is true then that 234 * value is two sub-objects, one named 'i' with a 'value' as a JSON integer, 235 * the other one named 'hex' with 'value' rendered as hex in a JSON string. 236 * If jsp->pr_hex is false then there are no sub-objects and the 'value' is 237 * rendered as JSON integer. */ 238 void sgj_js_nv_ihex(sgj_state * jsp, sgj_opaque_p jop, 239 const char * name, uint64_t value); 240 241 /* This function only produces JSON output if jsp is non-NULL and 242 * jsp->pr_as_json is true. It adds a named object at 'jop' (or jop->basep 243 * if jop is NULL) along with a value. If jsp->pr_string is true then that 244 * value is two sub-objects, one named 'i' with a 'val_i' as a JSON integer, 245 * the other one named str_name with val_s rendered as a JSON string. If 246 * str_name is NULL then "meaning" will be used. If jsp->pr_string is false 247 * then there are no sub-objects and the 'val_i' is rendered as a JSON 248 * integer. */ 249 void sgj_js_nv_istr(sgj_state * jsp, sgj_opaque_p jop, 250 const char * name, int64_t val_i, 251 const char * str_name, const char * val_s); 252 253 /* Similar to sgj_js_nv_istr(). The hex output is conditional jsp->pr_hex . */ 254 void sgj_js_nv_ihexstr(sgj_state * jsp, sgj_opaque_p jop, 255 const char * name, int64_t val_i, 256 const char * str_name, const char * val_s); 257 258 /* This function only produces JSON output if jsp is non-NULL and 259 * jsp->pr_as_json is true. It adds a named object at 'jop' (or jop->basep 260 * if jop is NULL) along with a value. If jsp->pr_name_ex is true then that 261 * value is two sub-objects, one named 'i' with a 'val_i' as a JSON integer, 262 * the other one named "abbreviated_name_expansion" with value nex_s rendered 263 * as a JSON string. If jsp->pr_hex and 'hex_as_well' are true, then a 264 * sub-object named 'hex' with a value rendered as a hex string equal to 265 * val_i. If jsp->pr_name_ex is false and either jsp->pr_hex or hex_as_well are 266 * false then there are no sub-objects and the 'val_i' is rendered as a JSON 267 * integer. */ 268 void sgj_js_nv_ihex_nex(sgj_state * jsp, sgj_opaque_p jop, const char * name, 269 int64_t val_i, bool hex_as_well, const char * nex_s); 270 271 void sgj_js_nv_ihexstr_nex(sgj_state * jsp, sgj_opaque_p jop, 272 const char * name, int64_t val_i, bool hex_as_well, 273 const char * str_name, const char * val_s, 274 const char * nex_s); 275 276 /* Add named field whose value is a (large) JSON string made up of num_bytes 277 * ASCII hexadecimal bytes (each two hex digits separated by a space) starting 278 * at byte_arr. The heap is used for intermediate storage so num_bytes can 279 * be arbitrarily large. */ 280 void sgj_js_nv_hex_bytes(sgj_state * jsp, sgj_opaque_p jop, const char * name, 281 const uint8_t * byte_arr, int num_bytes); 282 283 /* The '_haj_' refers to generating output both for human readable and/or 284 * JSON with a single invocation. If jsp is non-NULL and jsp->pr_out_hr is 285 * true then both JSON and human readable output is formed (and the latter is 286 * placed in the jsp->out_hrp JSON array). The human readable form will have 287 * leadin_sp spaces followed by 'name' then a separator, then 'value' with a 288 * trailing LF. If 'name' is NULL then it and the separator are ignored. If 289 * there is JSON output, then leadin_sp and sep are ignored. If 'jop' is NULL 290 * then basep->basep is used. If 'name' is NULL then a JSON string object, 291 * made from 'value' is added to the JSON array pointed to by 'jop'. 292 * Otherwise a 'name'-d JSON object whose value is a JSON string object made 293 * from 'value' is added at 'jop'. */ 294 void sgj_haj_vs(sgj_state * jsp, sgj_opaque_p jop, int leadin_sp, 295 const char * name, enum sgj_separator_t sep, 296 const char * value); 297 298 /* Similar to sgj_haj_vs()'s description with 'JSON string object' 299 * replaced by 'JSON integer object'. */ 300 void sgj_haj_vi(sgj_state * jsp, sgj_opaque_p jop, int leadin_sp, 301 const char * name, enum sgj_separator_t sep, 302 int64_t value, bool hex_as_well); 303 void sgj_haj_vistr(sgj_state * jsp, sgj_opaque_p jop, int leadin_sp, 304 const char * name, enum sgj_separator_t sep, 305 int64_t value, bool hex_as_well, const char * val_s); 306 307 /* The '_nex' refers to a "name_extra" (information) sub-object (a JSON 308 * string) which explains a bit more about the 'name' entry. This is useful 309 * when T10 specifies the name as an abbreviation (e.g. SYSV). Whether this 310 * sub-object is shown in the JSON output is controlled by the 'n' control 311 * character. */ 312 void sgj_haj_vi_nex(sgj_state * jsp, sgj_opaque_p jop, int leadin_sp, 313 const char * name, enum sgj_separator_t sep, 314 int64_t value, bool hex_as_well, const char * nex_s); 315 void sgj_haj_vistr_nex(sgj_state * jsp, sgj_opaque_p jop, int leadin_sp, 316 const char * name, enum sgj_separator_t sep, 317 int64_t value, bool hex_as_well, 318 const char * val_s, const char * nex_s); 319 320 /* Similar to above '_haj_' calls but a named sub-object is always formed 321 * containing a JSON integer object named "i" whose value is 'value'. The 322 * returned pointer is to that sub-object. */ 323 sgj_opaque_p sgj_haj_subo_r(sgj_state * jsp, sgj_opaque_p jop, int leadin_sp, 324 const char * name, enum sgj_separator_t sep, 325 int64_t value, bool hex_as_well); 326 327 /* Similar to sgj_haj_vs()'s description with 'JSON string object' replaced 328 * by 'JSON boolean object'. */ 329 void sgj_haj_vb(sgj_state * jsp, sgj_opaque_p jop, int leadin_sp, 330 const char * name, enum sgj_separator_t sep, bool value); 331 332 /* Breaks up the string pointed to by 'sp' into lines and adds them to the 333 * jsp->out_hrp array. Treat '\n' in sp as line breaks. Consumes characters 334 * from sp until either a '\0' is found or slen is exhausted. Add each line 335 * to jsp->out_hrp JSON array (if conditions met). */ 336 void sgj_js_str_out(sgj_state * jsp, const char * sp, int slen); 337 338 /* This function only produces JSON output if jsp is non-NULL and 339 * jsp->pr_as_json is true. 'sbp' is assumed to point to sense data as 340 * defined by T10 with a length of 'sb_len' bytes. Returns false if an 341 * issue is detected, else it returns true. */ 342 bool sgj_js_sense(sgj_state * jsp, sgj_opaque_p jop, const uint8_t * sbp, 343 int sb_len); 344 345 bool sgj_js_designation_descriptor(sgj_state * jsp, sgj_opaque_p jop, 346 const uint8_t * ddp, int dd_len); 347 348 /* Nothing in the in-core JSON tree is actually printed to 'fp' (typically 349 * stdout) until this call is made. If jsp is NULL, jsp->pr_as_json is false 350 * or jsp->basep is NULL then this function does nothing. If jsp->exit_status 351 * is true then a new JSON object named "exit_status" and the 'exit_status' 352 * value rendered as a JSON integer is appended to jsp->basep. The in-core 353 * JSON tree with jsp->basep as its root is streamed to 'fp'. */ 354 void sgj_js2file(sgj_state * jsp, sgj_opaque_p jop, int exit_status, 355 FILE * fp); 356 357 /* This function is only needed if the pointer returned from either 358 * sgj_new_unattached_object_r() or sgj_new_unattached_array_r() has not 359 * been attached into the in-core JSON tree whose root is jsp->basep . */ 360 void sgj_free_unattached(sgj_opaque_p jop); 361 362 /* If jsp is NULL or jsp->basep is NULL then this function does nothing. 363 * This function does bottom up, heap freeing of all the in-core JSON 364 * objects and arrays attached to the root JSON object assumed to be 365 * found at jsp->basep . After this call jsp->basep, jsp->out_hrp and 366 * jsp->userp will all be set to NULL. */ 367 void sgj_finish(sgj_state * jsp); 368 369 char * sg_json_usage(int char_if_not_j, char * b, int blen); 370 371 372 #ifdef __cplusplus 373 } 374 #endif 375 376 #endif 377