Graphs

type diagnostic_graph

SARIF has support for capturing directed graphs (such as callgraphs and control flow graphs), both at the level of the run as a whole, and at the level of individual results.

libgdiagnostics supports this with the following entrypoints, allowing directed graphs to be

diagnostic_graph *diagnostic_manager_new_graph(diagnostic_manager *manager)

Create a new directed graph.

The resulting graph is owned by the caller and must have one of diagnostic_manager_take_global_graph(), diagnostic_take_graph(), or diagnostic_graph_release() called on it to avoid leaks.

The parameter manager must be non-null.

This function was added in LIBGDIAGNOSTICS_ABI_3.

void diagnostic_manager_take_global_graph(diagnostic_manager *manager, diagnostic_graph *graph)

Report this graph “globally”, taking ownership of it. This won’t appear in text sinks, but in SARIF sinks the graph will be added to theRun.graphs (SARIF v2.1.0 3.14.20).

Parameters manager and graph must both be non-null.

This function was added in LIBGDIAGNOSTICS_ABI_3.

void diagnostic_take_graph(diagnostic *diag, diagnostic_graph *graph)

Add this graph to diag, transferring ownership of it to diag. This won’t appear in text sinks, but in SARIF sinks the graph will be added to theResult.graphs (SARIF v2.1.0 3.27.19).

Parameters diag and graph must both be non-null.

This function was added in LIBGDIAGNOSTICS_ABI_3.

void diagnostic_graph_release(diagnostic_graph *graph)

Release graph which must still be owned by the caller i.e. it must not have had diagnostic_manager_take_global_graph() or diagnostic_take_graph() called on it.

Parameters graph can be null.

This function was added in LIBGDIAGNOSTICS_ABI_3.

void diagnostic_graph_set_description(diagnostic_graph *graph, const char *description)

Set the description of graph for use in the value of the SARIF description property (SARIF v2.1.0 section 3.39.2).

The parameter graph must be non-null. The parameter description can be null, for clearing any existing description.

This function was added in LIBGDIAGNOSTICS_ABI_3.

diagnostic_node *diagnostic_graph_add_node(diagnostic_graph *graph, const char *node_id, diagnostic_node *parent_node)

Create and add a new node within graph with the given id`. The id must be unique within nodes in graph.

The parameters graph and id must be non-null.

parent_node can be NULL (for a top-level node in the graph), or non-null for a child node, allowing for arbitrary nesting of nodes.

The new node is owned by graph.

This function was added in LIBGDIAGNOSTICS_ABI_3.

diagnostic_edge *diagnostic_graph_add_edge(diagnostic_graph *graph, const char *edge_id, diagnostic_node *src_node, diagnostic_node *dst_node, const char *label)

Create and add a new edge within graph.

The parameters graph, src_node and dest_node must be non-null.

If non-null, then edge_id must be unique within graph; if edge_id is null then a unique id of the form “edge0”, “edge1”, etc will be used automatically.

If non-null, then label will be used for the value of the SARIF label property (SARIF v2.1.0 section 3.41.3).

The new edge is owned by graph.

This function was added in LIBGDIAGNOSTICS_ABI_3.

diagnostic_node *diagnostic_graph_get_node_by_id(diagnostic_graph *graph, const char *node_id)

Get the node in graph with the given id, or null.

The parameters graph and node_id must be non-null.

This function was added in LIBGDIAGNOSTICS_ABI_3.

diagnostic_edge *diagnostic_graph_get_edge_by_id(diagnostic_graph *graph, const char *edge_id)

Get the edge in graph with the given id, or null.

The parameters graph and edge_id must be non-null.

This function was added in LIBGDIAGNOSTICS_ABI_3.

type diagnostic_node
void diagnostic_node_set_label(diagnostic_node *node, const char *label)

Set the label of node for use in the value of the SARIF label property (SARIF v2.1.0 section 3.40.3).

The parameter node must be non-null. The parameter label can be null, for clearing any existing label.

This function was added in LIBGDIAGNOSTICS_ABI_3.

void diagnostic_node_set_location(diagnostic_node *node, const diagnostic_physical_location *loc)

Set the physical location of node, if any.

The parameter node must be non-null. The parameter loc can be null, for clearing any existing location.

If set, the value will be used by SARIF sinks within the location property (SARIF v2.1.0 section 3.40.4).

This function was added in LIBGDIAGNOSTICS_ABI_3.

void diagnostic_node_set_logical_location(diagnostic_node *node, const diagnostic_logical_location *logical_loc)

Set the logical location of node, if any.

The parameter node must be non-null. The parameter logical_loc _can be null, for clearing any existing location.

If set, the value will be used by SARIF sinks within the location property (SARIF v2.1.0 section 3.40.4).

This function was added in LIBGDIAGNOSTICS_ABI_3.