Debian Codegraph @

gcc/doc/libgdiagnostics/topics/execution-paths.rst

raw
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>`_).