Debian Codegraph @

gcc/doc/libgdiagnostics/tutorial/07-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 Tutorial part 7: execution paths
21 ================================
22
23 A :type:`diagnostic` can optionally have a :type:`diagnostic_execution_path`
24 describing a path of execution through code.
25
26 For example, let's pretend we're writing a static analyis tool for finding
27 bugs in `CPython extension code <https://docs.python.org/3/c-api/index.html>`_.
28
29 Let's say we're analyzing this code:
30
31 .. literalinclude:: ../../../testsuite/libgdiagnostics.dg/test-warning-with-path.c
32 :language: c
33 :start-after: begin fake source
34 :end-before: end fake source
35
36 This code attempts to take an Python integer parameter and then build a
37 list of that length, containing random integers. However, there are
38 **numerous bugs** in this code: a type mismatch, mistakes in
39 reference-counting, and an almost total lack of error-handling.
40
41 For example, ``PyList_Append`` requires a non-NULL first parameter (``list``),
42 but ``PyList_New`` can fail, returning NULL, and this isn't checked for,
43 which would lead to a segfault if ``PyList_New`` fails.
44
45 We can add a :type:`diagnostic_execution_path` to the :type:`diagnostic`
46 via :func:`diagnostic_add_execution_path`, and then add events to it
47 using :func:`diagnostic_execution_path_add_event`.
48
49 For example, with::
50
51 diagnostic_event_id alloc_event_id
52 = diagnostic_execution_path_add_event (path,
53 loc_call_to_PyList_New,
54 logical_loc, 0,
55 "when %qs fails, returning NULL",
56 "PyList_New");
57
58 we create an event that will be worded as::
59
60 (1) when `PyList_New' fails, returning NULL
61
62 Note that :func:`diagnostic_execution_path_add_event` returns a
63 :type:`diagnostic_event_id`. We can use this to refer to this event
64 in another event using the ``%@`` format code in its message, which
65 takes the address of a :type:`diagnostic_event_id`::
66
67 diagnostic_execution_path_add_event (path,
68 loc_call_to_PyList_Append,
69 logical_loc, 0,
70 "when calling %qs, passing NULL from %@ as argument %i",
71 "PyList_Append", &alloc_event_id, 1);
72
73 where the latter event will be worded as::
74
75 (2) when calling `PyList_Append', passing NULL from (1) as argument 1
76
77 where the ``%@`` reference to the other event has been printed as ``(1)``.
78 In SARIF output the text "(1)" will have a embedded link referring within the sarif
79 log to the ``threadFlowLocation`` object for the other event, via JSON
80 pointer (see `§3.10.3 "URIs that use the sarif scheme" <https://docs.oasis-open.org/sarif/sarif/v2.1.0/errata01/os/sarif-v2.1.0-errata01-os-complete.html#_Toc141790707>`_).
81
82 Let's add an event between these describing control flow, creating three
83 events in all:
84
85 .. literalinclude:: ../../../testsuite/libgdiagnostics.dg/test-warning-with-path.c
86 :language: c
87 :start-after: begin path creation
88 :end-before: end path creation
89
90 Assuming we also gave it :type:`diagnostic_logical_location` with:
91
92 .. literalinclude:: ../../../testsuite/libgdiagnostics.dg/test-warning-with-path.c
93 :language: c
94 :start-after: begin create logical locs
95 :end-before: end create logical locs
96
97 and finish the :type:`diagnostic` with :func:`diagnostic_finish` like this::
98
99 diagnostic_finish (d,
100 "passing NULL as argument %i to %qs"
101 " which requires a non-NULL parameter",
102 1, "PyList_Append");
103
104 then we should get output to text sinks similar to the following::
105
106 In function 'make_a_list_of_random_ints_badly':
107 test-warning-with-path.c:30:5: warning: passing NULL as argument 1 to 'PyList_Append' which requires a non-NULL parameter"
108 30 | PyList_Append(list, item);
109 | ^~~~~~~~~~~~~~~~~~~~~~~~~
110 make_a_list_of_random_ints_badly': events 1-3
111 26 | list = PyList_New(0);
112 | ^~~~~~~~~~~~~
113 | |
114 | (1) when 'PyList_New' fails, returning NULL
115 27 |
116 28 | for (i = 0; i < count; i++) {
117 | ~~~~~~~~~
118 | |
119 | (2) when 'i < count'
120 29 | item = PyLong_FromLong(random());
121 30 | PyList_Append(list, item);
122 | ~~~~~~~~~~~~~~~~~~~~~~~~~
123 | |
124 | (3) when calling 'PyList_Append', passing NULL from (1) as argument 1
125
126 and for SARIF sinks the path will be added as a ``codeFlow`` object
127 (see SARIF 2.1.0 `§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>`_).
128
129 Here's the above example in full:
130
131 .. literalinclude:: ../../../testsuite/libgdiagnostics.dg/test-warning-with-path.c
132 :language: c
133 :start-after: begin full example
134 :end-before: end full example
135
136
137 Moving on
138 *********
139
140 That's the end of the tutorial. For more information on libgdiagnostics, see
141 the :doc:`topic guide <../topics/index>`.