GCC Middle and Back End API Reference
libgdiagnostics.h
Go to the documentation of this file.
1/* A pure C API for emitting diagnostics.
2 Copyright (C) 2023-2025 Free Software Foundation, Inc.
3
4This file is part of GCC.
5
6GCC is free software; you can redistribute it and/or modify it
7under the terms of the GNU General Public License as published by
8the Free Software Foundation; either version 3, or (at your option)
9any later version.
10
11GCC is distributed in the hope that it will be useful, but
12WITHOUT ANY WARRANTY; without even the implied warranty of
13MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14General Public License for more details.
15
16You should have received a copy of the GNU General Public License
17along with GCC; see the file COPYING3. If not see
18<http://www.gnu.org/licenses/>. */
19
20#ifndef LIBGDIAGNOSTICS_H
21#define LIBGDIAGNOSTICS_H
22
23#include <stdarg.h>
24#include <stdio.h>
25
26#ifdef __cplusplus
27extern "C" {
28#endif /* __cplusplus */
29
30/**********************************************************************
31 Compatibility macros.
32 **********************************************************************/
33
34/* This macro simplifies testing whether we are using gcc, and if it
35 is of a particular minimum version. (Both major & minor numbers are
36 significant.) This macro will evaluate to 0 if we are not using
37 gcc at all. */
38#define LIBGDIAGNOSTICS_GCC_VERSION (__GNUC__ * 1000 + __GNUC_MINOR__)
39
40/**********************************************************************
41 Macros for attributes.
42 **********************************************************************/
43
44# if (LIBGDIAGNOSTICS_GCC_VERSION >= 3003)
45# define LIBGDIAGNOSTICS_PARAM_MUST_BE_NON_NULL(ARG_NUM) __attribute__ ((__nonnull__ (ARG_NUM)))
46# else
47# define LIBGDIAGNOSTICS_PARAM_MUST_BE_NON_NULL(ARG_NUM)
48# endif /* GNUC >= 3.3 */
49
50#define LIBGDIAGNOSTICS_PARAM_CAN_BE_NULL(ARG_NUM)
51 /* empty; for the human reader */
52
53# if (LIBGDIAGNOSTICS_GCC_VERSION >= 4001)
54# define LIBGDIAGNOSTICS_PARAM_FORMAT_STRING(FMT_KIND, FMT_ARG_NUM, ARGS_ARG_NUM) \
55 __attribute__ ((__format__ (FMT_KIND, FMT_ARG_NUM, ARGS_ARG_NUM)))
56# else
57# define LIBGDIAGNOSTICS_PARAM_FORMAT_STRING(FMT_KIND, FMT_ARG_NUM, ARGS_ARG_NUM)
58# endif /* GNUC >= 4.1 */
59
60#define LIBGDIAGNOSTICS_PARAM_GCC_FORMAT_STRING(FMT_ARG_NUM, ARGS_ARG_NUM) \
61 LIBGDIAGNOSTICS_PARAM_MUST_BE_NON_NULL (FMT_ARG_NUM)
62 /* In theory we'd also add
63 __attribute__ ((__format__ (__gcc_diag__, FMT_ARG_NUM, ARGS_ARG_NUM)))
64 if LIBGDIAGNOSTICS_GCC_VERSION >= 4001
65 However, doing so leads to warnings from -Wformat-diag, which is part
66 of -Wall but undocumented, and much fussier than I'd want to inflict
67 on users of libgdiagnostics. */
68
69#define LIBGDIAGNOSTICS_PARAM_PRINTF_FORMAT_STRING(FMT_ARG_NUM, ARGS_ARG_NUM) \
70 LIBGDIAGNOSTICS_PARAM_MUST_BE_NON_NULL (FMT_ARG_NUM) \
71 LIBGDIAGNOSTICS_PARAM_FORMAT_STRING(gnu_printf, FMT_ARG_NUM, ARGS_ARG_NUM)
72
73/**********************************************************************
74 Data structures and types.
75 All structs within the API are opaque.
76 **********************************************************************/
77
78/* An opaque bundle of state for a client of the library.
79 Has zero of more "sinks" to which diagnostics are emitted.
80 Responsibilities:
81 - location-management
82 - caching of source file content
83 - patch generation. */
85
86/* Types relating to diagnostic output sinks. */
87
89
90/* An enum for determining if we should colorize a text output sink. */
97
98/* An enum for choosing the SARIF version for a SARIF output sink. */
99
105
106/* Types relating to "physical" source locations i.e. locations within
107 specific files expressed via line/column. */
108
109/* Opaque type describing a particular input file. */
111
112/* Opaque type representing a key into a database of source locations within
113 a diagnostic_manager. Locations are created by various API calls into
114 the diagnostic_manager expressing source code points and ranges. They
115 persist until the diagnostic_manager is released, which cleans them
116 up.
117
118 NULL means "UNKNOWN", and can be returned by the manager as a
119 fallback when a problem occurs (e.g. too many locations).
120
121 A diagnostic_location can be a single point within the source code,
122 such as here (at the the '"' at the start of the string literal):
123
124 | int i = "foo";
125 | ^
126
127 or be a range with a start and finish, and a "caret" location.
128
129 | a = (foo && bar)
130 | ~~~~~^~~~~~~
131
132 where the caret here is at the first "&", and the start and finish
133 are at the parentheses. */
134
136
137/* Types for storing line and column information in text files.
138
139 Both libgdiagnostics and emacs number source *lines* starting at 1, but
140 they have differing conventions for *columns*.
141
142 libgdiagnostics uses a 1-based convention for source columns,
143 whereas Emacs's M-x column-number-mode uses a 0-based convention.
144
145 For example, an error in the initial, left-hand
146 column of source line 3 is reported by libgdiagnostics as:
147
148 some-file.c:3:1: error: ...etc...
149
150 On navigating to the location of that error in Emacs
151 (e.g. via "next-error"),
152 the locus is reported in the Mode Line
153 (assuming M-x column-number-mode) as:
154
155 some-file.c 10% (3, 0)
156
157 i.e. "3:1:" in libgdiagnostics corresponds to "(3, 0)" in Emacs. */
158
159typedef unsigned int diagnostic_line_num_t;
160typedef unsigned int diagnostic_column_num_t;
161
162/* An opaque type describing a "logical" source location
163 e.g. "within function 'foo'". */
164
166
167/* An enum for discriminating between different kinds of logical location
168 for a diagnostic.
169
170 Roughly corresponds to logicalLocation's "kind" property in SARIF v2.1.0
171 (section 3.33.7). */
172
200
201/* A "diagnostic" is an opaque bundle of state for a particular
202 diagnostic that is being constructed in memory.
203
204 A diagnostic has a primary location and zero or more secondary
205 locations. For example:
206
207 | a = (foo && bar)
208 | ~~~~~^~~~~~~
209
210 This diagnostic has a single diagnostic_location, with the caret
211 at the first "&", and the start/finish at the parentheses.
212
213 Contrast with:
214
215 | a = (foo && bar)
216 | ~~~ ^~ ~~~
217
218 This diagnostic has three locations
219 - The primary location (at "&&") has its caret and start location at
220 the first "&" and end at the second "&.
221 - The secondary location for "foo" has its start and finish at the "f"
222 and "o" of "foo"; the caret is not flagged for display, but is perhaps at
223 the "f" of "foo".
224 - Similarly, the other secondary location (for "bar") has its start and
225 finish at the "b" and "r" of "bar"; the caret is not flagged for
226 display, but is perhaps at the"b" of "bar". */
227typedef struct diagnostic diagnostic;
228
230{
234
235 /* A problem where the input is valid, but the tool isn't
236 able to handle it. */
238};
239
240/* Types for working with execution paths. */
243
245
246/**********************************************************************
247 API entrypoints.
248 **********************************************************************/
249
250/* Create a new diagnostic_manager.
251 The client needs to call diagnostic_release_manager on it at some
252 point.
253 Note that no output sinks are created by default. */
254
255extern diagnostic_manager *
257
258/* Release a diagnostic_manager.
259 This will flush output to all of the output sinks, and clean up. */
260
261extern void
264
265/* Optional metadata about the manager. */
266
267/* Set a string suitable for use as the value of the SARIF "name" property
268 (SARIF v2.1.0 section 3.19.8). */
269
270extern void
272 const char *value)
275
276/* Set a string suitable for use as the value of the SARIF "fullName" property
277 (SARIF v2.1.0 section 3.19.9). */
278
279extern void
281 const char *value)
284
285/* Set a string suitable for use as the value of the SARIF "version" property
286 (SARIF v2.1.0 section 3.19.13). */
287
288extern void
290 const char *value)
293
294/* Set a string suitable for use as the value of the SARIF "informationUri"
295 property (SARIF v2.1.0 section 3.19.17). */
296
297extern void
299 const char *value)
302
303/* Destinations for diagnostics. */
304
305/* Add a new output sink to DIAG_MGR, which writes GCC-style diagnostics
306 to DST_STREAM.
307 Return a borrowed pointer to the sink, which is cleaned up when DIAG_MGR
308 is released.
309 DST_STREAM is borrowed, and must outlive DIAG_MGR.
310 The output for each diagnostic is written and flushed as each
311 diagnostic is finished. */
312
315 FILE *dst_stream,
316 enum diagnostic_colorize colorize)
319
320/* Functions to manipulate text sinks. */
321
322/* Enable/disable printing of source text in the text sink.
323 Default: enabled. */
324
325extern void
327 int value)
329
330/* Update colorization of text sink. */
331
332extern void
334 enum diagnostic_colorize colorize)
336
337/* Enable/disable colorization of the characters of source text
338 that are underlined.
339 This should be true for clients that generate range information
340 (so that the ranges of code are colorized),
341 and false for clients that merely specify points within the
342 source code (to avoid e.g. colorizing just the first character in
343 a token, which would look strange).
344 Default: enabled. */
345
346extern void
348 int value)
350
351/* Add a new output sink to DIAG_MGR, which writes SARIF of the given
352 version to DST_STREAM.
353
354 The output is not written until DIAG_MGR is released.
355
356 DST_STREAM is borrowed, and must outlive DIAG_MGR.
357
358 For the result to be a valid SARIF file according to the schema,
359 DIAG_MGR must have had diagnostic_manager_set_tool_name called on it. */
360
361extern void
363 FILE *dst_stream,
364 const diagnostic_file *main_input_file,
365 enum diagnostic_sarif_version version)
369
370/* Write a patch to DST_STREAM consisting of all fix-it hints
371 on all diagnostics that have been finished on DIAG_MGR. */
372
373extern void
375 FILE *dst_stream)
378
379/* Location management. */
380
381/* Create a new diagnostic_file * for file NAME.
382
383 Repeated calls with matching NAMEs will return the
384 same object.
385
386 If SARIF_SOURCE_LANGUAGE is non-NULL, it specifies a "sourceLanguage"
387 value for the file when use when writing SARIF.
388 See SARIF v2.1.0 Appendix J for suggested values for various
389 programmming languages. */
390
391extern diagnostic_file *
393 const char *name,
394 const char *sarif_source_language)
398
399/* Populate the source-quoting cache for FILE, specifying the
400 given buffer as the content of the file (rather than
401 attempting to read the content from the filesystem). */
402
403extern void
405 const char *buf,
406 size_t sz)
409
410/* Write a representation of FILE to OUT, for debugging. */
411
412extern void
414 const diagnostic_file *file,
415 FILE *out)
419
420/* Attempt to create a diagnostic_location representing
421 FILENAME:LINE_NUM, with no column information
422 (thus "the whole line"). */
423
424extern const diagnostic_physical_location *
426 const diagnostic_file *file,
427 diagnostic_line_num_t line_num)
430
431/* Attempt to create a diagnostic_physical_location representing
432 FILENAME:LINE_NUM:COLUMN_NUM. */
433
434extern const diagnostic_physical_location *
436 const diagnostic_file *file,
437 diagnostic_line_num_t line_num,
438 diagnostic_column_num_t column_num)
441
442/* Attempt to create a diagnostic_physical_location representing a
443 range within a source file, with a highlighted "caret" location.
444
445 All must be within the same file, but they can be on different lines.
446
447 For example, consider the location of the binary expression below:
448
449 ...|__________1111111112222222
450 ...|12345678901234567890123456
451 ...|
452 521|int sum (int foo, int bar)
453 522|{
454 523| return foo + bar;
455 ...| ~~~~^~~~~
456 524|}
457
458 The location's caret is at the "+", line 523 column 15, but starts
459 earlier, at the "f" of "foo" at column 11. The finish is at the "r"
460 of "bar" at column 19. */
461
462extern const diagnostic_physical_location *
464 const diagnostic_physical_location *loc_caret,
465 const diagnostic_physical_location *loc_start,
466 const diagnostic_physical_location *loc_end)
471
472/* Write a representation of LOC to OUT, for debugging. */
473
474extern void
477 FILE *out)
481
482/* A bundle of state describing a logical location in the user's source,
483 such as "in function 'foo'".
484
485 SHORT_NAME can be NULL, or else a string suitable for use by
486 the SARIF logicalLocation "name" property (SARIF v2.1.0 section 3.33.4).
487
488 FULLY_QUALIFIED_NAME can be NULL or else a string suitable for use by
489 the SARIF logicalLocation "fullyQualifiedName" property
490 (SARIF v2.1.0 section 3.33.5).
491
492 DECORATED_NAME can be NULL or else a string suitable for use by
493 the SARIF logicalLocation "decoratedName" property
494 (SARIF v2.1.0 section 3.33.6). */
495
496extern const diagnostic_logical_location *
499 const diagnostic_logical_location *parent,
500 const char *short_name,
501 const char *fully_qualified_name,
502 const char *decorated_name)
508
509/* Write a representation of LOC to OUT, for debugging. */
510
511extern void
514 FILE *out)
518
519/* Accessors for logical locations (added in LIBGDIAGNOSTICS_ABI_1;
520 you can test for their presence using
521 #ifdef LIBDIAGNOSTICS_HAVE_LOGICAL_LOCATION_ACCESSORS
522*/
523#define LIBDIAGNOSTICS_HAVE_LOGICAL_LOCATION_ACCESSORS
524
528
529extern const diagnostic_logical_location *
532
533extern const char *
536
537extern const char *
540
541extern const char *
544
545/* Diagnostic groups. */
546
547/* Begin a diagnostic group. All diagnostics emitted within
548 DIAG_MGR after the first one will be treated as notes about
549 the initial diagnostic. */
550
551extern void
554
555/* Finish a diagnostic group. */
556
557extern void
560
561/* Step-by-step creation of a diagnostic. */
562
563extern diagnostic *
565 enum diagnostic_level level)
567
568/* Associate this diagnostic with the given ID within
569 the Common Weakness Enumeration. */
570
571extern void
573 unsigned cwe_id)
575
576/* Associate this diagnostic with a particular rule that has been violated
577 (such as in a coding standard, or within a specification).
578 The rule must have at least one of a title and a URL, but these
579 can be NULL.
580 A diagnostic can be associated with zero or more rules. */
581
582extern void
584 const char *title,
585 const char *url)
589
590/* Set the primary location of DIAG. */
591
592extern void
597
598/* Set the primary location of DIAG, with a label. */
599
600extern void
603 const char *fmt, ...)
607
608/* Add a secondary location to DIAG. */
609
610extern void
614
615/* Add a secondary location to DIAG, with a label. */
616
617extern void
620 const char *text)
624
625/* Set the logical location of DIAG. */
626
627extern void
629 const diagnostic_logical_location *logical_loc)
632
633/* Fix-it hints. */
634
635extern void
638 const char *addition)
642
643extern void
646 const char *addition)
650
651extern void
654 const char *replacement)
658
659extern void
664
665/* Create and borrow a pointer to an execution path for DIAG.
666 The path is automatically cleaned up when DIAG is finished. */
667
671
672/* Create a new execution path.
673 This is owned by the called and must have either
674 diagnostic_take_execution_path or diagnostic_execution_path_release
675 called on it. */
676
680
681/* Set DIAG to use PATH as its execution path, taking ownership of PATH. */
682
683extern void
688
689/* Release ownership of PATH, which must not have been taken
690 by a diagnostic. */
691
692extern void
695
696/* Append an event to the end of PATH. */
697
700 const diagnostic_physical_location *physical_loc,
701 const diagnostic_logical_location *logical_loc,
702 unsigned stack_depth,
703 const char *fmt, ...)
709
710/* Append an event to the end of PATH. */
711
714 const diagnostic_physical_location *physical_loc,
715 const diagnostic_logical_location *logical_loc,
716 unsigned stack_depth,
717 const char *fmt,
718 va_list *args)
724
725/* Emit DIAG to all sinks of its manager, and release DIAG.
726 Use FMT for the message.
727 Note that this uses gcc's pretty-print format, which is *not* printf.
728 TODO: who is responsible for putting FMT through gettext? */
729
730extern void
731diagnostic_finish (diagnostic *diag, const char *fmt, ...)
735
736/* As diagnostic_finish, but with a va_list. */
737
738extern void
739diagnostic_finish_va (diagnostic *diag, const char *fmt, va_list *args)
743
744/* Get the diagnostic_file associated with PHYSICAL_LOC. */
745
746extern diagnostic_file *
749
750/* Attempt to parse SPEC as if an argument to GCC's
751 -fdiagnostics-add-output=OUTPUT-SPEC.
752 If successful, add an output sink to AFFECTED_MGR and return zero.
753 Otherwise, emit a diagnostic to CONTROL_MGR and return non-zero.
754 Added in LIBGDIAGNOSTICS_ABI_2. */
755#define LIBDIAGNOSTICS_HAVE_diagnostic_manager_add_sink_from_spec
756
757extern int
759 const char *option_name,
760 const char *spec,
761 diagnostic_manager *control_mgr)
766
767
768/* Set the main input file of MGR to be FILE.
769 This affects the <title> of generated HTML and
770 the "role" of the artifact in SARIF output (SARIF v2.1.0
771 section 3.24.6).
772 Added in LIBGDIAGNOSTICS_ABI_2. */
773#define LIBDIAGNOSTICS_HAVE_diagnostic_manager_set_analysis_target
774
775extern void
777 const diagnostic_file *file)
780
781/* Directed graphs. */
782
786
787/* Create a new graph.
788 This is owned by the caller and must have one of
789 diagnostic_manager_take_global_graph, diagnostic_take_graph,
790 or diagnostic_graph_release called on it.
791 Added in LIBGDIAGNOSTICS_ABI_3. */
792
793extern diagnostic_graph *
796
797/* Report this graph "globally", taking ownership of it.
798 Added in LIBGDIAGNOSTICS_ABI_3. */
799
800extern void
805
806/* Add this graph to DIAG, transferring ownership to it.
807 Added in LIBGDIAGNOSTICS_ABI_3. */
808
809extern void
814
815/* Release this graph. Added in LIBGDIAGNOSTICS_ABI_3. */
816
817extern void
820
821/* Set the description of GRAPH for use
822 in the value of the SARIF "description" property
823 (SARIF v2.1.0 section 3.39.2).
824 Added in LIBGDIAGNOSTICS_ABI_3. */
825
826extern void
828 const char *description)
831
832/* Create and add a new node within GRAPH.
833 NODE_ID must be unique within nodes in GRAPH.
834 The new node is owned by GRAPH.
835 PARENT_NODE can be NULL (for a top-level node in the graph),
836 or non-null for a child node.
837 Added in LIBGDIAGNOSTICS_ABI_3. */
838
839extern diagnostic_node *
841 const char *node_id,
842 diagnostic_node *parent_node)
846
847/* Create and add a new edge within GRAPH.
848
849 If non-null, then EDGE_ID must be unique within edges in GRAPH;
850 if EDGE_ID is null then a unique id of the form "edge0", "edge1", etc
851 will be used automatically.
852
853 The new edge is owned by GRAPH.
854 Added in LIBGDIAGNOSTICS_ABI_3. */
855
856extern diagnostic_edge *
858 const char *edge_id,
859 diagnostic_node *src_node,
860 diagnostic_node *dst_node,
861 const char *label)
867
868/* Get the node in GRAPH with the given id, or null.
869 Added in LIBGDIAGNOSTICS_ABI_3. */
870
871extern diagnostic_node *
873 const char *node_id)
876
877/* Get the edge in GRAPH with the given id, or null.
878 Added in LIBGDIAGNOSTICS_ABI_3. */
879
880extern diagnostic_edge *
882 const char *edge_id)
885
886/* Set the label of NODE for use
887 in the value of the SARIF "label" property
888 (SARIF v2.1.0 section 3.40.3).
889 Added in LIBGDIAGNOSTICS_ABI_3. */
890
891extern void
893 const char *label)
896
897/* Set the physical location of NODE.
898 Added in LIBGDIAGNOSTICS_ABI_3. */
899
900extern void
905
906/* Set the logical location of NODE.
907 Added in LIBGDIAGNOSTICS_ABI_3. */
908
909extern void
911 const diagnostic_logical_location *logical_loc)
914
915/* Message buffers. */
916
917#define LIBDIAGNOSTICS_HAVE_diagnostic_message_buffer
918
919/* Create a new diagnostic_message_buffer.
920 Added in LIBGDIAGNOSTICS_ABI_4. */
921
924
925/* Release a diagnostic_message_buffer that hasn't been used.
926 Added in LIBGDIAGNOSTICS_ABI_4. */
927
928extern void
931
932/* Append a UTF-8 encoded null-terminated string to the buffer.
933 Added in LIBGDIAGNOSTICS_ABI_4. */
934
935extern void
937 const char *p)
940
941/* Append a UTF-8 encoded run of bytes to the buffer.
942 Added in LIBGDIAGNOSTICS_ABI_4. */
943
944extern void
946 const char *p,
947 size_t len)
950
951/* Append a byte to to the buffer. This should be either
952 ASCII, or part of UTF-8 encoded text.
953 Added in LIBGDIAGNOSTICS_ABI_4. */
954
955extern void
957 char ch)
959
960/* Append a formatted string to the buffer, using the formatting rules
961 for "printf".
962 The string is assumed to be UTF-8 encoded.
963 Added in LIBGDIAGNOSTICS_ABI_4. */
964
965extern void
967 const char *fmt, ...)
970
971/* Append a diagnostic_event_id to the buffer in the form "(1)".
972 Added in LIBGDIAGNOSTICS_ABI_4. */
973
974extern void
976 diagnostic_event_id event_id)
978
979/* Begin a run of text associated with the given URL.
980 Added in LIBGDIAGNOSTICS_ABI_4. */
981
982extern void
984 const char *url)
987
988/* End a run of text started with diagnostic_message_buffer_begin_url.
989 Added in LIBGDIAGNOSTICS_ABI_4. */
990
991extern void
994
995/* Begin a run of text to be printed in quotes.
996 Added in LIBGDIAGNOSTICS_ABI_4. */
997
998extern void
1001
1002/* End a run of text started with diagnostic_message_buffer_begin_quote.
1003 Added in LIBGDIAGNOSTICS_ABI_4. */
1004
1005extern void
1008
1009/* Begin a run of text to be printed with color.
1010 Added in LIBGDIAGNOSTICS_ABI_4. */
1011
1012extern void
1014 const char *color)
1017
1018/* End a run of text started with diagnostic_message_buffer_begin_color.
1019 Added in LIBGDIAGNOSTICS_ABI_4. */
1020
1021extern void
1024
1025/* Write a debugging representation of MSG_BUG to OUTF.
1026 Added in LIBGDIAGNOSTICS_ABI_4. */
1027
1028extern void
1030 FILE *outf)
1032
1033/* As diagnostic_finish, but takes ownership of MSG_BUF.
1034 Added in LIBGDIAGNOSTICS_ABI_4. */
1035
1036extern void
1041
1042/* As diagnostic_add_location_with_label but takes ownership of MSG_BUF.
1043 Added in LIBGDIAGNOSTICS_ABI_4. */
1044
1045extern void
1052
1053/* As diagnostic_execution_path_add_event but takes ownership of MSG_BUF.
1054 Added in LIBGDIAGNOSTICS_ABI_4. */
1055
1058 const diagnostic_physical_location *physical_loc,
1059 const diagnostic_logical_location *logical_loc,
1060 unsigned stack_depth,
1066
1067/* Set the description of GRAPH for use
1068 in the value of the SARIF "description" property
1069 (SARIF v2.1.0 section 3.39.2).
1070
1071 Takes ownership of DESC, if non-null.
1072
1073 Added in LIBGDIAGNOSTICS_ABI_4. */
1074
1075extern void
1080
1081/* Create and add a new edge within GRAPH.
1082
1083 If non-null, then EDGE_ID must be unique within edges in GRAPH;
1084 if EDGE_ID is null then a unique id of the form "edge0", "edge1", etc
1085 will be used automatically.
1086
1087 Takes ownership of LABEL, if non-null.
1088
1089 The new edge is owned by GRAPH.
1090 Added in LIBGDIAGNOSTICS_ABI_4. */
1091
1092extern diagnostic_edge *
1094 const char *edge_id,
1095 diagnostic_node *src_node,
1096 diagnostic_node *dst_node,
1103
1104/* Set the label of NODE for use
1105 in the value of the SARIF "label" property
1106 (SARIF v2.1.0 section 3.40.3).
1107
1108 Takes ownership of LABEL, if non-null.
1109
1110 Added in LIBGDIAGNOSTICS_ABI_4. */
1111
1112extern void
1117
1118/* DEFERRED:
1119 - thread-safety
1120 - plural forms
1121 - enum about what a "column number" means (bytes, unichars, etc)
1122 - locations within binary files
1123 - options and URLs for warnings
1124 - enable/disable of warnings by kind
1125 - command-line arguments
1126 - plugin metadata. */
1127
1128#ifdef __cplusplus
1129}
1130#endif /* __cplusplus */
1131
1132#endif /* LIBGDIAGNOSTICS_H */
static struct path_prefix cpath path
Definition collect2.cc:514
void diagnostic_finish(diagnostic_context *context)
Definition diagnostic.h:1201
static void color(void)
Definition ira-color.cc:5258
void diagnostic_graph_set_description(diagnostic_graph *graph, const char *desc)
Definition libgdiagnostics.cc:2551
void diagnostic_graph_release(diagnostic_graph *graph)
Definition libgdiagnostics.cc:2543
void diagnostic_manager_set_full_name(diagnostic_manager *diag_mgr, const char *value)
Definition libgdiagnostics.cc:1716
diagnostic_text_sink * diagnostic_manager_add_text_sink(diagnostic_manager *diag_mgr, FILE *dst_stream, enum diagnostic_colorize colorize)
Definition libgdiagnostics.cc:1752
const diagnostic_logical_location * diagnostic_manager_new_logical_location(diagnostic_manager *diag_mgr, enum diagnostic_logical_location_kind_t kind, const diagnostic_logical_location *parent, const char *short_name, const char *fully_qualified_name, const char *decorated_name)
Definition libgdiagnostics.cc:1969
void diagnostic_add_location(diagnostic *diag, const diagnostic_physical_location *loc)
Definition libgdiagnostics.cc:2147
diagnostic_edge * diagnostic_graph_add_edge_via_msg_buf(diagnostic_graph *graph, const char *edge_id, diagnostic_node *src_node, diagnostic_node *dst_node, diagnostic_message_buffer *label)
Definition libgdiagnostics.cc:2896
void diagnostic_add_fix_it_hint_delete(diagnostic *diag, const diagnostic_physical_location *loc)
Definition libgdiagnostics.cc:2232
void diagnostic_manager_write_patch(diagnostic_manager *diag_mgr, FILE *dst_stream)
Definition libgdiagnostics.cc:1835
void diagnostic_message_buffer_append_text(diagnostic_message_buffer *msg_buf, const char *p, size_t len)
Definition libgdiagnostics.cc:2702
void diagnostic_take_graph(diagnostic *diag, diagnostic_graph *graph)
Definition libgdiagnostics.cc:2531
diagnostic_event_id diagnostic_execution_path_add_event(diagnostic_execution_path *path, const diagnostic_physical_location *physical_loc, const diagnostic_logical_location *logical_loc, unsigned stack_depth, const char *gmsgid,...)
Definition libgdiagnostics.cc:2285
void diagnostic_manager_add_sarif_sink(diagnostic_manager *diag_mgr, FILE *dst_stream, const diagnostic_file *main_input_file, enum diagnostic_sarif_version version)
Definition libgdiagnostics.cc:1802
diagnostic_event_id diagnostic_execution_path_add_event_via_msg_buf(diagnostic_execution_path *path, const diagnostic_physical_location *physical_loc, const diagnostic_logical_location *logical_loc, unsigned stack_depth, diagnostic_message_buffer *msg_buf)
Definition libgdiagnostics.cc:2860
void diagnostic_add_location_with_label_via_msg_buf(diagnostic *diag, const diagnostic_physical_location *loc, diagnostic_message_buffer *msg_buf)
Definition libgdiagnostics.cc:2845
void diagnostic_message_buffer_begin_quote(diagnostic_message_buffer *msg_buf)
Definition libgdiagnostics.cc:2774
void diagnostic_text_sink_set_labelled_source_colorization_enabled(diagnostic_text_sink *text_sink, int value)
Definition libgdiagnostics.cc:1790
const diagnostic_physical_location * diagnostic_manager_new_location_from_range(diagnostic_manager *diag_mgr, const diagnostic_physical_location *loc_caret, const diagnostic_physical_location *loc_start, const diagnostic_physical_location *loc_end)
Definition libgdiagnostics.cc:1924
void diagnostic_message_buffer_dump(const diagnostic_message_buffer *msg_buf, FILE *outf)
Definition libgdiagnostics.cc:2813
void diagnostic_node_set_label(diagnostic_node *node, const char *label)
Definition libgdiagnostics.cc:2626
void diagnostic_graph_set_description_via_msg_buf(diagnostic_graph *graph, diagnostic_message_buffer *desc)
Definition libgdiagnostics.cc:2882
void diagnostic_message_buffer_append_printf(diagnostic_message_buffer *msg_buf, const char *fmt,...)
Definition libgdiagnostics.cc:2724
void diagnostic_text_sink_set_colorize(diagnostic_text_sink *text_sink, enum diagnostic_colorize colorize)
Definition libgdiagnostics.cc:1779
diagnostic_execution_path * diagnostic_add_execution_path(diagnostic *diag)
Definition libgdiagnostics.cc:2245
void diagnostic_node_set_location(diagnostic_node *node, const diagnostic_physical_location *loc)
Definition libgdiagnostics.cc:2615
diagnostic_node * diagnostic_graph_get_node_by_id(diagnostic_graph *graph, const char *node_id)
Definition libgdiagnostics.cc:2591
void diagnostic_set_location(diagnostic *diag, const diagnostic_physical_location *loc)
Definition libgdiagnostics.cc:2135
diagnostic_node * diagnostic_graph_add_node(diagnostic_graph *graph, const char *node_id, diagnostic_node *parent_node)
Definition libgdiagnostics.cc:2562
void diagnostic_add_fix_it_hint_insert_before(diagnostic *diag, const diagnostic_physical_location *loc, const char *addition)
Definition libgdiagnostics.cc:2184
void diagnostic_node_set_label_via_msg_buf(diagnostic_node *node, diagnostic_message_buffer *label)
Definition libgdiagnostics.cc:2920
void diagnostic_message_buffer_begin_color(diagnostic_message_buffer *msg_buf, const char *color)
Definition libgdiagnostics.cc:2792
void diagnostic_manager_debug_dump_logical_location(const diagnostic_manager *diag_mgr, const diagnostic_logical_location *loc, FILE *out)
Definition libgdiagnostics.cc:1986
void diagnostic_message_buffer_append_event_id(diagnostic_message_buffer *msg_buf, diagnostic_event_id event_id)
Definition libgdiagnostics.cc:2743
diagnostic_event_id diagnostic_execution_path_add_event_va(diagnostic_execution_path *path, const diagnostic_physical_location *physical_loc, const diagnostic_logical_location *logical_loc, unsigned stack_depth, const char *gmsgid, va_list *args)
Definition libgdiagnostics.cc:2309
void diagnostic_message_buffer_append_byte(diagnostic_message_buffer *msg_buf, char ch)
Definition libgdiagnostics.cc:2714
diagnostic_file * diagnostic_physical_location_get_file(const diagnostic_physical_location *physical_loc)
Definition libgdiagnostics.cc:2360
const diagnostic_physical_location * diagnostic_manager_new_location_from_file_line_column(diagnostic_manager *diag_mgr, const diagnostic_file *file, diagnostic_line_num_t line_num, diagnostic_column_num_t column_num)
Definition libgdiagnostics.cc:1908
void diagnostic_manager_set_version_url(diagnostic_manager *diag_mgr, const char *value)
Definition libgdiagnostics.cc:1740
void diagnostic_message_buffer_end_url(diagnostic_message_buffer *msg_buf)
Definition libgdiagnostics.cc:2765
void diagnostic_message_buffer_end_quote(diagnostic_message_buffer *msg_buf)
Definition libgdiagnostics.cc:2783
void diagnostic_file_set_buffered_content(diagnostic_file *file, const char *buf, size_t sz)
Definition libgdiagnostics.cc:1860
void diagnostic_set_logical_location(diagnostic *diag, const diagnostic_logical_location *logical_loc)
Definition libgdiagnostics.cc:2173
void diagnostic_message_buffer_end_color(diagnostic_message_buffer *msg_buf)
Definition libgdiagnostics.cc:2804
diagnostic_edge * diagnostic_graph_add_edge(diagnostic_graph *graph, const char *edge_id, diagnostic_node *src_node, diagnostic_node *dst_node, const char *label)
Definition libgdiagnostics.cc:2575
void diagnostic_add_fix_it_hint_replace(diagnostic *diag, const diagnostic_physical_location *loc, const char *replacement)
Definition libgdiagnostics.cc:2216
void diagnostic_manager_debug_dump_location(const diagnostic_manager *diag_mgr, const diagnostic_physical_location *loc, FILE *out)
Definition libgdiagnostics.cc:1939
void diagnostic_manager_set_version_string(diagnostic_manager *diag_mgr, const char *value)
Definition libgdiagnostics.cc:1728
void diagnostic_add_location_with_label(diagnostic *diag, const diagnostic_physical_location *loc, const char *text)
Definition libgdiagnostics.cc:2159
diagnostic_file * diagnostic_manager_new_file(diagnostic_manager *diag_mgr, const char *name, const char *sarif_source_language)
Definition libgdiagnostics.cc:1847
void diagnostic_manager_take_global_graph(diagnostic_manager *manager, diagnostic_graph *graph)
Definition libgdiagnostics.cc:2521
void diagnostic_finish_va(diagnostic *diag, const char *gmsgid, va_list *args)
Definition libgdiagnostics.cc:2343
void diagnostic_execution_path_release(diagnostic_execution_path *path)
Definition libgdiagnostics.cc:2277
void diagnostic_add_fix_it_hint_insert_after(diagnostic *diag, const diagnostic_physical_location *loc, const char *addition)
Definition libgdiagnostics.cc:2200
void diagnostic_message_buffer_begin_url(diagnostic_message_buffer *msg_buf, const char *url)
Definition libgdiagnostics.cc:2753
void diagnostic_manager_debug_dump_file(diagnostic_manager *, const diagnostic_file *file, FILE *out)
Definition libgdiagnostics.cc:1871
void diagnostic_finish_via_msg_buf(diagnostic *diag, diagnostic_message_buffer *msg_buf)
Definition libgdiagnostics.cc:2825
void diagnostic_node_set_logical_location(diagnostic_node *node, const diagnostic_logical_location *logical_loc)
Definition libgdiagnostics.cc:2637
void diagnostic_text_sink_set_source_printing_enabled(diagnostic_text_sink *text_sink, int value)
Definition libgdiagnostics.cc:1768
const diagnostic_physical_location * diagnostic_manager_new_location_from_file_and_line(diagnostic_manager *diag_mgr, const diagnostic_file *file, diagnostic_line_num_t linenum)
Definition libgdiagnostics.cc:1895
diagnostic_edge * diagnostic_graph_get_edge_by_id(diagnostic_graph *graph, const char *edge_id)
Definition libgdiagnostics.cc:2603
diagnostic_execution_path * diagnostic_manager_new_execution_path(diagnostic_manager *manager)
Definition libgdiagnostics.cc:2255
void diagnostic_take_execution_path(diagnostic *diag, diagnostic_execution_path *path)
Definition libgdiagnostics.cc:2265
diagnostic_graph * diagnostic_manager_new_graph(diagnostic_manager *manager)
Definition libgdiagnostics.cc:2511
void diagnostic_set_location_with_label(diagnostic *diag, const diagnostic_physical_location *loc, const char *fmt,...) LIBGDIAGNOSTICS_PARAM_MUST_BE_NON_NULL(3)
#define LIBGDIAGNOSTICS_PARAM_CAN_BE_NULL(ARG_NUM)
Definition libgdiagnostics.h:50
void diagnostic_add_rule(diagnostic *diag, const char *title, const char *url) LIBGDIAGNOSTICS_PARAM_CAN_BE_NULL(3)
Definition libgdiagnostics.cc:2123
diagnostic * diagnostic_begin(diagnostic_manager *diag_mgr, enum diagnostic_level level) LIBGDIAGNOSTICS_PARAM_MUST_BE_NON_NULL(1)
Definition libgdiagnostics.cc:2101
int diagnostic_event_id
Definition libgdiagnostics.h:242
#define LIBGDIAGNOSTICS_PARAM_GCC_FORMAT_STRING(FMT_ARG_NUM, ARGS_ARG_NUM)
Definition libgdiagnostics.h:60
void diagnostic_manager_end_group(diagnostic_manager *diag_mgr) LIBGDIAGNOSTICS_PARAM_MUST_BE_NON_NULL(1)
Definition libgdiagnostics.cc:2092
#define LIBGDIAGNOSTICS_PARAM_MUST_BE_NON_NULL(ARG_NUM)
Definition libgdiagnostics.h:47
diagnostic_logical_location_kind_t
Definition libgdiagnostics.h:174
@ DIAGNOSTIC_LOGICAL_LOCATION_KIND_FUNCTION
Definition libgdiagnostics.h:176
@ DIAGNOSTIC_LOGICAL_LOCATION_KIND_DECLARATION
Definition libgdiagnostics.h:192
@ DIAGNOSTIC_LOGICAL_LOCATION_KIND_NAMESPACE
Definition libgdiagnostics.h:179
@ DIAGNOSTIC_LOGICAL_LOCATION_KIND_ATTRIBUTE
Definition libgdiagnostics.h:187
@ DIAGNOSTIC_LOGICAL_LOCATION_KIND_ARRAY
Definition libgdiagnostics.h:196
@ DIAGNOSTIC_LOGICAL_LOCATION_KIND_VALUE
Definition libgdiagnostics.h:198
@ DIAGNOSTIC_LOGICAL_LOCATION_KIND_MEMBER
Definition libgdiagnostics.h:177
@ DIAGNOSTIC_LOGICAL_LOCATION_KIND_PROCESSING_INSTRUCTION
Definition libgdiagnostics.h:190
@ DIAGNOSTIC_LOGICAL_LOCATION_KIND_OBJECT
Definition libgdiagnostics.h:195
@ DIAGNOSTIC_LOGICAL_LOCATION_KIND_RETURN_TYPE
Definition libgdiagnostics.h:181
@ DIAGNOSTIC_LOGICAL_LOCATION_KIND_TEXT
Definition libgdiagnostics.h:188
@ DIAGNOSTIC_LOGICAL_LOCATION_KIND_VARIABLE
Definition libgdiagnostics.h:183
@ DIAGNOSTIC_LOGICAL_LOCATION_KIND_TYPE
Definition libgdiagnostics.h:180
@ DIAGNOSTIC_LOGICAL_LOCATION_KIND_ELEMENT
Definition libgdiagnostics.h:186
@ DIAGNOSTIC_LOGICAL_LOCATION_KIND_PARAMETER
Definition libgdiagnostics.h:182
@ DIAGNOSTIC_LOGICAL_LOCATION_KIND_MODULE
Definition libgdiagnostics.h:178
@ DIAGNOSTIC_LOGICAL_LOCATION_KIND_PROPERTY
Definition libgdiagnostics.h:197
@ DIAGNOSTIC_LOGICAL_LOCATION_KIND_COMMENT
Definition libgdiagnostics.h:189
@ DIAGNOSTIC_LOGICAL_LOCATION_KIND_DTD
Definition libgdiagnostics.h:191
unsigned int diagnostic_line_num_t
Definition libgdiagnostics.h:159
void diagnostic_message_buffer_append_str(diagnostic_message_buffer *msg_buf, const char *p) LIBGDIAGNOSTICS_PARAM_MUST_BE_NON_NULL(2)
Definition libgdiagnostics.cc:2691
void diagnostic_set_cwe(diagnostic *diag, unsigned cwe_id) LIBGDIAGNOSTICS_PARAM_MUST_BE_NON_NULL(1)
Definition libgdiagnostics.cc:2112
void diagnostic_manager_set_tool_name(diagnostic_manager *diag_mgr, const char *value) LIBGDIAGNOSTICS_PARAM_MUST_BE_NON_NULL(2)
Definition libgdiagnostics.cc:1704
diagnostic_message_buffer * diagnostic_message_buffer_new(void)
Definition libgdiagnostics.cc:2676
void diagnostic_manager_set_analysis_target(diagnostic_manager *mgr, const diagnostic_file *file) LIBGDIAGNOSTICS_PARAM_MUST_BE_NON_NULL(2)
Definition libgdiagnostics.cc:2465
diagnostic_manager * diagnostic_manager_new(void)
Definition libgdiagnostics.cc:1688
diagnostic_sarif_version
Definition libgdiagnostics.h:101
@ DIAGNOSTIC_SARIF_VERSION_2_1_0
Definition libgdiagnostics.h:102
@ DIAGNOSTIC_SARIF_VERSION_2_2_PRERELEASE
Definition libgdiagnostics.h:103
diagnostic_colorize
Definition libgdiagnostics.h:92
@ DIAGNOSTIC_COLORIZE_YES
Definition libgdiagnostics.h:95
@ DIAGNOSTIC_COLORIZE_IF_TTY
Definition libgdiagnostics.h:93
@ DIAGNOSTIC_COLORIZE_NO
Definition libgdiagnostics.h:94
const char * diagnostic_logical_location_get_short_name(const diagnostic_logical_location *loc) LIBGDIAGNOSTICS_PARAM_MUST_BE_NON_NULL(1)
Definition libgdiagnostics.cc:2387
void diagnostic_message_buffer_release(diagnostic_message_buffer *msg_buf) LIBGDIAGNOSTICS_PARAM_MUST_BE_NON_NULL(1)
Definition libgdiagnostics.cc:2684
#define LIBGDIAGNOSTICS_PARAM_PRINTF_FORMAT_STRING(FMT_ARG_NUM, ARGS_ARG_NUM)
Definition libgdiagnostics.h:69
unsigned int diagnostic_column_num_t
Definition libgdiagnostics.h:160
diagnostic_level
Definition libgdiagnostics.h:230
@ DIAGNOSTIC_LEVEL_ERROR
Definition libgdiagnostics.h:231
@ DIAGNOSTIC_LEVEL_SORRY
Definition libgdiagnostics.h:237
@ DIAGNOSTIC_LEVEL_WARNING
Definition libgdiagnostics.h:232
@ DIAGNOSTIC_LEVEL_NOTE
Definition libgdiagnostics.h:233
void diagnostic_manager_begin_group(diagnostic_manager *diag_mgr) LIBGDIAGNOSTICS_PARAM_MUST_BE_NON_NULL(1)
Definition libgdiagnostics.cc:2083
enum diagnostic_logical_location_kind_t diagnostic_logical_location_get_kind(const diagnostic_logical_location *loc) LIBGDIAGNOSTICS_PARAM_MUST_BE_NON_NULL(1)
Definition libgdiagnostics.cc:2371
void diagnostic_manager_release(diagnostic_manager *) LIBGDIAGNOSTICS_PARAM_MUST_BE_NON_NULL(1)
Definition libgdiagnostics.cc:1696
const char * diagnostic_logical_location_get_fully_qualified_name(const diagnostic_logical_location *loc) LIBGDIAGNOSTICS_PARAM_MUST_BE_NON_NULL(1)
Definition libgdiagnostics.cc:2395
const diagnostic_logical_location * diagnostic_logical_location_get_parent(const diagnostic_logical_location *loc) LIBGDIAGNOSTICS_PARAM_MUST_BE_NON_NULL(1)
Definition libgdiagnostics.cc:2379
int diagnostic_manager_add_sink_from_spec(diagnostic_manager *affected_mgr, const char *option_name, const char *spec, diagnostic_manager *control_mgr) LIBGDIAGNOSTICS_PARAM_MUST_BE_NON_NULL(4)
Definition libgdiagnostics.cc:2444
const char * diagnostic_logical_location_get_decorated_name(const diagnostic_logical_location *loc) LIBGDIAGNOSTICS_PARAM_MUST_BE_NON_NULL(1)
Definition libgdiagnostics.cc:2403
@ text
Definition logical-location.h:49
@ value
Definition logical-location.h:59
Definition genautomata.cc:601
Definition libgdiagnostics.cc:978
Definition libgdiagnostics.cc:1100
Definition libgdiagnostics.cc:117
Definition libgdiagnostics.cc:955
Definition libgdiagnostics.cc:174
Definition libgdiagnostics.cc:630
Definition libgdiagnostics.cc:353
Definition libgdiagnostics.cc:969
Definition libgdiagnostics.cc:150
Definition libgdiagnostics.cc:229
Definition libgdiagnostics.cc:1201
Definition graphds.h:48
Definition gengtype.h:377
Definition reload.cc:154