Adding metadata

Tool metadata

It’s possible to set up various metadata on the diagnostic_manager as a whole, describing the program creating the diagnostics.

Note

It’s not required to set up any of this up on a diagnostic_manager. However, if you are doing SARIF output, then you need to at least call diagnostic_manager_set_tool_name() or the generated .sarif file will not validate against the schema.

void diagnostic_manager_set_tool_name(diagnostic_manager *diag_mgr, const char *value)

Set a string for the name of the tool emitting the diagnostics.

Both parameters must be non-NULL.

If set, this string will be used

  • by text output sinks as a prefix for output when no physical location is available, replacing progname in the following:

    $ ./tut01-hello-world
    progname: error: I'm sorry Dave, I'm afraid I can't do that
    
  • by SARIF output sinks as the value for the name property of the driver (SARIF v2.1.0 §3.19.8).

void diagnostic_manager_set_full_name(diagnostic_manager *diag_mgr, const char *value)

Set a string giving the name of the tool along with the its version and other useful information:

diagnostic_manager_set_full_name (diag_mgr, "FooChecker 0.1 (en_US)");

If set, this string will be used by SARIF output sinks as the value for the fullName property of the driver (SARIF v2.1.0 §3.19.9).

Both parameters must be non-NULL.

void diagnostic_manager_set_version_string(diagnostic_manager *diag_mgr, const char *value)

Set a string suitable for use as the value of the SARIF version property of the driver. (SARIF v2.1.0 §3.19.13):

diagnostic_manager_set_version_string (diag_mgr, "0.1");

Both parameters must be non-NULL.

void diagnostic_manager_set_version_url(diagnostic_manager *diag_mgr, const char *value)

Set a string suitable for use as the value of the SARIF informationUri property of the driver. (SARIF v2.1.0 §3.19.17):

diagnostic_manager_set_version_url (diag_mgr,
                                    "https://www.example.com/foo-checker/releases/0.1/");

Both parameters must be non-NULL.

Adding metadata to a diagnostic

void diagnostic_set_cwe(diagnostic *diag, unsigned cwe_id)

Associate diag with the given ID within the Common Weakness Enumeration:

/* CWE-242: Use of Inherently Dangerous Function.  */
diagnostic_set_cwe (d, 242);

diag must be non-NULL.

The CWE value will be printed by text sinks after the message:

test-metadata.c:21:3: warning: never use 'gets' [CWE-242]

and in a sufficiently-capable terminal will be a link to documentation about the CWE.

void diagnostic_add_rule(diagnostic *diag, const char *title, const char *url)

Associate this diagnostic with a particular rule that has been violated (such as in a coding standard, or within a specification).

A diagnostic can be associated with zero or more rules.

diag must be non-NULL. The rule must have at least one of a title and a URL, but these can be NULL.

For example, given:

diagnostic_add_rule (d,
                     "MSC24-C",
                     "https://wiki.sei.cmu.edu/confluence/display/c/MSC24-C.+Do+not+use+deprecated+or+obsolescent+functions");

the rule name will be printed by text sinks after the message:

test-metadata.c:21:3: warning: never use 'gets' [MSC24-C]
 21 |   gets (buf);
    |   ^~~~~~~~~~

and if so, the URL will be available in a sufficiently capable terminal.

This can be used in conjunction with diagnostic_set_cwe(), giving output like this:

test-metadata.c:21:3: warning: never use 'gets' [CWE-242] [MSC24-C]
 21 |   gets (buf);
    |   ^~~~~~~~~~