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 thedriver
(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 thedriver
(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 thedriver
. (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 thedriver
. (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); | ^~~~~~~~~~