| 1 |
.. Copyright (C) 2024-2025 Free Software Foundation, Inc. |
| 2 |
Originally contributed by David Malcolm <[email protected]> |
| 3 |
|
| 4 |
This is free software: you can redistribute it and/or modify it |
| 5 |
under the terms of the GNU General Public License as published by |
| 6 |
the Free Software Foundation, either version 3 of the License, or |
| 7 |
(at your option) any later version. |
| 8 |
|
| 9 |
This program is distributed in the hope that it will be useful, but |
| 10 |
WITHOUT ANY WARRANTY; without even the implied warranty of |
| 11 |
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU |
| 12 |
General Public License for more details. |
| 13 |
|
| 14 |
You should have received a copy of the GNU General Public License |
| 15 |
along with this program. If not, see |
| 16 |
<https://www.gnu.org/licenses/>. |
| 17 |
|
| 18 |
.. default-domain:: c |
| 19 |
|
| 20 |
Execution paths |
| 21 |
=============== |
| 22 |
|
| 23 |
.. type:: diagnostic_execution_path |
| 24 |
|
| 25 |
A :type:`diagnostic` can optionally contain a :type:`diagnostic_execution_path` |
| 26 |
describing a path of execution through code. |
| 27 |
|
| 28 |
.. function:: diagnostic_execution_path * diagnostic_add_execution_path (diagnostic *diag) |
| 29 |
|
| 30 |
Create and borrow a pointer to an execution path for ``diag``. |
| 31 |
|
| 32 |
The path is automatically cleaned up when ``diag`` is finished. |
| 33 |
|
| 34 |
``diag`` must be non-NULL. |
| 35 |
|
| 36 |
.. function:: diagnostic_execution_path * diagnostic_manager_new_execution_path (diagnostic_manager *diag_mgr) |
| 37 |
|
| 38 |
Create a new execution path. This is owned by the caller and must have either |
| 39 |
:func:`diagnostic_take_execution_path` or |
| 40 |
:func:`diagnostic_execution_path_release` called on it. |
| 41 |
|
| 42 |
``diag_mgr`` must be non-NULL. |
| 43 |
|
| 44 |
.. function:: void diagnostic_take_execution_path (diagnostic *diag, diagnostic_execution_path *path) |
| 45 |
|
| 46 |
Set ``diag`` to use ``path`` as its execution path, taking ownership of ``path``. |
| 47 |
|
| 48 |
Both parameters must be non-NULL. |
| 49 |
|
| 50 |
.. function:: void diagnostic_execution_path_release (diagnostic_execution_path *path) |
| 51 |
|
| 52 |
Release ownership of ``path``, which must not have been taken by a diagnostic. |
| 53 |
|
| 54 |
.. type:: diagnostic_event_id |
| 55 |
|
| 56 |
A :type:`diagnostic_event_id` identifies a particular event within a |
| 57 |
:type:`diagnostic_execution_path` and can be used for expressing |
| 58 |
cross-references between events. In particular FIXME |
| 59 |
|
| 60 |
.. function:: diagnostic_event_id diagnostic_execution_path_add_event (diagnostic_execution_path *path, \ |
| 61 |
const diagnostic_physical_location *physical_loc, \ |
| 62 |
const diagnostic_logical_location *logical_loc, \ |
| 63 |
unsigned stack_depth, \ |
| 64 |
const char *fmt, ...) |
| 65 |
|
| 66 |
Append an event to the end of ``path``, which must be non-NULL. |
| 67 |
|
| 68 |
``physical_loc`` can be NULL, or non-NULL to associate the event |
| 69 |
with a :type:`diagnostic_physical_location`. |
| 70 |
|
| 71 |
``logical_loc`` can be NULL, or non-NULL to associate the event |
| 72 |
with a :type:`diagnostic_logical_location`. |
| 73 |
|
| 74 |
``stack_depth`` is for use in interprocedural paths and identifies the |
| 75 |
depth of the stack at the event. Purely intraprocedural paths should |
| 76 |
use a stack depth of 1 for their events |
| 77 |
|
| 78 |
``fmt`` must be non-NULL. See :doc:`message-formatting` for details of |
| 79 |
how to use it. |
| 80 |
|
| 81 |
.. function:: diagnostic_event_id diagnostic_execution_path_add_event_va (diagnostic_execution_path *path, \ |
| 82 |
const diagnostic_physical_location *physical_loc, \ |
| 83 |
const diagnostic_logical_location *logical_loc, \ |
| 84 |
unsigned stack_depth, \ |
| 85 |
const char *fmt, \ |
| 86 |
va_list *args) |
| 87 |
|
| 88 |
Equivalent to :func:`diagnostic_execution_path_add_event`, but using a |
| 89 |
:type:`va_list` rather than directly taking variadic arguments. |
| 90 |
|
| 91 |
Paths are printed to text sinks, and for SARIF sinks each path is added as |
| 92 |
a ``codeFlow`` object (see SARIF 2.1.0 |
| 93 |
`ยง3.36 codeFlow object <https://docs.oasis-open.org/sarif/sarif/v2.1.0/errata01/os/sarif-v2.1.0-errata01-os-complete.html#_Toc141790990>`_). |