gcc/libgdiagnostics.h

   1 /* A pure C API for emitting diagnostics.
   2    Copyright (C) 2023-2025 Free Software Foundation, Inc.
   3
   4 This file is part of GCC.
   5
   6 GCC is free software; you can redistribute it and/or modify it
   7 under the terms of the GNU General Public License as published by
   8 the Free Software Foundation; either version 3, or (at your option)
   9 any later version.
  10
  11 GCC is distributed in the hope that it will be useful, but
  12 WITHOUT ANY WARRANTY; without even the implied warranty of
  13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14 General Public License for more details.
  15
  16 You should have received a copy of the GNU General Public License
  17 along 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
  27 extern "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 #define LIBGDIAGNOSTICS_PARAM_GCC_FORMAT_STRING(FMT_ARG_NUM, ARGS_ARG_NUM) \
  54   LIBGDIAGNOSTICS_PARAM_MUST_BE_NON_NULL (FMT_ARG_NUM)
  55   /* In theory we'd also add
  56        __attribute__ ((__format__ (__gcc_diag__, FMT_ARG_NUM, ARGS_ARG_NUM)))
  57      if LIBGDIAGNOSTICS_GCC_VERSION >= 4001
  58      However, doing so leads to warnings from -Wformat-diag, which is part
  59      of -Wall but undocumented, and much fussier than I'd want to inflict
  60      on users of libgdiagnostics.  */
  61
  62 /**********************************************************************
  63  Data structures and types.
  64  All structs within the API are opaque.
  65  **********************************************************************/
  66
  67 /* An opaque bundle of state for a client of the library.
  68    Has zero of more "sinks" to which diagnostics are emitted.
  69    Responsibilities:
  70    - location-management
  71    - caching of source file content
  72    - patch generation.  */
  73 typedef struct diagnostic_manager diagnostic_manager;
  74
  75 /* Types relating to diagnostic output sinks.  */
  76
  77 typedef struct diagnostic_text_sink diagnostic_text_sink;
  78
  79 /* An enum for determining if we should colorize a text output sink.  */
  80 enum diagnostic_colorize
  81 {
  82   DIAGNOSTIC_COLORIZE_IF_TTY,
  83   DIAGNOSTIC_COLORIZE_NO,
  84   DIAGNOSTIC_COLORIZE_YES
  85 };
  86
  87 /* An enum for choosing the SARIF version for a SARIF output sink.  */
  88
  89 enum diagnostic_sarif_version
  90 {
  91   DIAGNOSTIC_SARIF_VERSION_2_1_0,
  92   DIAGNOSTIC_SARIF_VERSION_2_2_PRERELEASE
  93 };
  94
  95 /* Types relating to "physical" source locations i.e. locations within
  96    specific files expressed via line/column.  */
  97
  98 /* Opaque type describing a particular input file.  */
  99 typedef struct diagnostic_file diagnostic_file;
 100
 101 /* Opaque type representing a key into a database of source locations within
 102    a diagnostic_manager.  Locations are created by various API calls into
 103    the diagnostic_manager expressing source code points and ranges.  They
 104    persist until the diagnostic_manager is released, which cleans them
 105    up.
 106
 107    NULL means "UNKNOWN", and can be returned by the manager as a
 108    fallback when a problem occurs (e.g. too many locations).
 109
 110    A diagnostic_location can be a single point within the source code,
 111    such as here (at the the '"' at the start of the string literal):
 112
 113    |  int i = "foo";
 114    |          ^
 115
 116    or be a range with a start and finish, and a "caret" location.
 117
 118    |   a = (foo && bar)
 119    |       ~~~~~^~~~~~~
 120
 121    where the caret here is at the first "&", and the start and finish
 122    are at the parentheses.  */
 123
 124 typedef struct diagnostic_physical_location diagnostic_physical_location;
 125
 126 /* Types for storing line and column information in text files.
 127
 128    Both libgdiagnostics and emacs number source *lines* starting at 1, but
 129    they have differing conventions for *columns*.
 130
 131    libgdiagnostics uses a 1-based convention for source columns,
 132    whereas Emacs's M-x column-number-mode uses a 0-based convention.
 133
 134    For example, an error in the initial, left-hand
 135    column of source line 3 is reported by libgdiagnostics as:
 136
 137       some-file.c:3:1: error: ...etc...
 138
 139    On navigating to the location of that error in Emacs
 140    (e.g. via "next-error"),
 141    the locus is reported in the Mode Line
 142    (assuming M-x column-number-mode) as:
 143
 144      some-file.c   10%   (3, 0)
 145
 146    i.e. "3:1:" in libgdiagnostics corresponds to "(3, 0)" in Emacs.  */
 147
 148 typedef unsigned int diagnostic_line_num_t;
 149 typedef unsigned int diagnostic_column_num_t;
 150
 151 /* An opaque type describing a "logical" source location
 152    e.g. "within function 'foo'".  */
 153
 154 typedef struct diagnostic_logical_location diagnostic_logical_location;
 155
 156 /* An enum for discriminating between different kinds of logical location
 157    for a diagnostic.
 158
 159    Roughly corresponds to logicalLocation's "kind" property in SARIF v2.1.0
 160    (section 3.33.7).  */
 161
 162 enum diagnostic_logical_location_kind_t
 163 {
 164   DIAGNOSTIC_LOGICAL_LOCATION_KIND_FUNCTION,
 165   DIAGNOSTIC_LOGICAL_LOCATION_KIND_MEMBER,
 166   DIAGNOSTIC_LOGICAL_LOCATION_KIND_MODULE,
 167   DIAGNOSTIC_LOGICAL_LOCATION_KIND_NAMESPACE,
 168   DIAGNOSTIC_LOGICAL_LOCATION_KIND_TYPE,
 169   DIAGNOSTIC_LOGICAL_LOCATION_KIND_RETURN_TYPE,
 170   DIAGNOSTIC_LOGICAL_LOCATION_KIND_PARAMETER,
 171   DIAGNOSTIC_LOGICAL_LOCATION_KIND_VARIABLE
 172 };
 173
 174 /* A "diagnostic" is an opaque bundle of state for a particular
 175    diagnostic that is being constructed in memory.
 176
 177    A diagnostic has a primary location and zero or more secondary
 178    locations.  For example:
 179
 180    |   a = (foo && bar)
 181    |       ~~~~~^~~~~~~
 182
 183    This diagnostic has a single diagnostic_location, with the caret
 184    at the first "&", and the start/finish at the parentheses.
 185
 186    Contrast with:
 187
 188    |   a = (foo && bar)
 189    |        ~~~ ^~ ~~~
 190
 191    This diagnostic has three locations
 192    - The primary location (at "&&") has its caret and start location at
 193    the first "&" and end at the second "&.
 194    - The secondary location for "foo" has its start and finish at the "f"
 195    and "o" of "foo"; the caret is not flagged for display, but is perhaps at
 196    the "f" of "foo".
 197    - Similarly, the other secondary location (for "bar") has its start and
 198    finish at the "b" and "r" of "bar"; the caret is not flagged for
 199    display, but is perhaps at the"b" of "bar".  */
 200 typedef struct diagnostic diagnostic;
 201
 202 enum diagnostic_level
 203 {
 204   DIAGNOSTIC_LEVEL_ERROR,
 205   DIAGNOSTIC_LEVEL_WARNING,
 206   DIAGNOSTIC_LEVEL_NOTE,
 207
 208   /* A problem where the input is valid, but the tool isn't
 209      able to handle it.  */
 210   DIAGNOSTIC_LEVEL_SORRY
 211 };
 212
 213 /* Types for working with execution paths.  */
 214 typedef struct diagnostic_execution_path diagnostic_execution_path;
 215 typedef int diagnostic_event_id;
 216
 217 /**********************************************************************
 218  API entrypoints.
 219  **********************************************************************/
 220
 221 /* Create a new diagnostic_manager.
 222    The client needs to call diagnostic_release_manager on it at some
 223    point.
 224    Note that no output sinks are created by default.  */
 225
 226 extern diagnostic_manager *
 227 diagnostic_manager_new (void);
 228
 229 /* Release a diagnostic_manager.
 230    This will flush output to all of the output sinks, and clean up. */
 231
 232 extern void
 233 diagnostic_manager_release (diagnostic_manager *)
 234   LIBGDIAGNOSTICS_PARAM_MUST_BE_NON_NULL (1);
 235
 236 /* Optional metadata about the manager.  */
 237
 238 /* Set a string suitable for use as the value of the SARIF "name" property
 239    (SARIF v2.1.0 section 3.19.8).  */
 240
 241 extern void
 242 diagnostic_manager_set_tool_name (diagnostic_manager *diag_mgr,
 243                                   const char *value)
 244   LIBGDIAGNOSTICS_PARAM_MUST_BE_NON_NULL (1)
 245   LIBGDIAGNOSTICS_PARAM_MUST_BE_NON_NULL (2);
 246
 247 /* Set a string suitable for use as the value of the SARIF "fullName" property
 248    (SARIF v2.1.0 section 3.19.9).  */
 249
 250 extern void
 251 diagnostic_manager_set_full_name (diagnostic_manager *diag_mgr,
 252                                   const char *value)
 253   LIBGDIAGNOSTICS_PARAM_MUST_BE_NON_NULL (1)
 254   LIBGDIAGNOSTICS_PARAM_MUST_BE_NON_NULL (2);
 255
 256 /* Set a string suitable for use as the value of the SARIF "version" property
 257    (SARIF v2.1.0 section 3.19.13).  */
 258
 259 extern void
 260 diagnostic_manager_set_version_string (diagnostic_manager *diag_mgr,
 261                                        const char *value)
 262   LIBGDIAGNOSTICS_PARAM_MUST_BE_NON_NULL (1)
 263   LIBGDIAGNOSTICS_PARAM_MUST_BE_NON_NULL (2);
 264
 265 /* Set a string suitable for use as the value of the SARIF "informationUri"
 266    property (SARIF v2.1.0 section 3.19.17).  */
 267
 268 extern void
 269 diagnostic_manager_set_version_url (diagnostic_manager *diag_mgr,
 270                                     const char *value)
 271   LIBGDIAGNOSTICS_PARAM_MUST_BE_NON_NULL (1)
 272   LIBGDIAGNOSTICS_PARAM_MUST_BE_NON_NULL (2);
 273
 274 /* Destinations for diagnostics.  */
 275
 276 /* Add a new output sink to DIAG_MGR, which writes GCC-style diagnostics
 277    to DST_STREAM.
 278    Return a borrowed pointer to the sink, which is cleaned up when DIAG_MGR
 279    is released.
 280    DST_STREAM is borrowed, and must outlive DIAG_MGR.
 281    The output for each diagnostic is written and flushed as each
 282    diagnostic is finished.  */
 283
 284 extern diagnostic_text_sink *
 285 diagnostic_manager_add_text_sink (diagnostic_manager *diag_mgr,
 286                                   FILE *dst_stream,
 287                                   enum diagnostic_colorize colorize)
 288   LIBGDIAGNOSTICS_PARAM_MUST_BE_NON_NULL (1)
 289   LIBGDIAGNOSTICS_PARAM_MUST_BE_NON_NULL (2);
 290
 291 /* Functions to manipulate text sinks.  */
 292
 293 /* Enable/disable printing of source text in the text sink.
 294    Default: enabled.  */
 295
 296 extern void
 297 diagnostic_text_sink_set_source_printing_enabled (diagnostic_text_sink *text_sink,
 298                                                   int value)
 299   LIBGDIAGNOSTICS_PARAM_MUST_BE_NON_NULL (1);
 300
 301 /* Update colorization of text sink.  */
 302
 303 extern void
 304 diagnostic_text_sink_set_colorize (diagnostic_text_sink *text_sink,
 305                                    enum diagnostic_colorize colorize)
 306   LIBGDIAGNOSTICS_PARAM_MUST_BE_NON_NULL (1);
 307
 308 /* Enable/disable colorization of the characters of source text
 309    that are underlined.
 310    This should be true for clients that generate range information
 311    (so that the ranges of code are colorized),
 312    and false for clients that merely specify points within the
 313    source code (to avoid e.g. colorizing just the first character in
 314    a token, which would look strange).
 315    Default: enabled.  */
 316
 317 extern void
 318 diagnostic_text_sink_set_labelled_source_colorization_enabled (diagnostic_text_sink *text_sink,
 319                                                                int value)
 320   LIBGDIAGNOSTICS_PARAM_MUST_BE_NON_NULL (1);
 321
 322 /* Add a new output sink to DIAG_MGR, which writes SARIF of the given
 323    version to DST_STREAM.
 324
 325    The output is not written until DIAG_MGR is released.
 326
 327    DST_STREAM is borrowed, and must outlive DIAG_MGR.
 328
 329    For the result to be a valid SARIF file according to the schema,
 330    DIAG_MGR must have had diagnostic_manager_set_tool_name called on it.  */
 331
 332 extern void
 333 diagnostic_manager_add_sarif_sink (diagnostic_manager *diag_mgr,
 334                                    FILE *dst_stream,
 335                                    const diagnostic_file *main_input_file,
 336                                    enum diagnostic_sarif_version version)
 337   LIBGDIAGNOSTICS_PARAM_MUST_BE_NON_NULL (1)
 338   LIBGDIAGNOSTICS_PARAM_MUST_BE_NON_NULL (2)
 339   LIBGDIAGNOSTICS_PARAM_MUST_BE_NON_NULL (3);
 340
 341 /* Write a patch to DST_STREAM consisting of all fix-it hints
 342    on all diagnostics that have been finished on DIAG_MGR.  */
 343
 344 extern void
 345 diagnostic_manager_write_patch (diagnostic_manager *diag_mgr,
 346                                 FILE *dst_stream)
 347   LIBGDIAGNOSTICS_PARAM_MUST_BE_NON_NULL (1)
 348   LIBGDIAGNOSTICS_PARAM_MUST_BE_NON_NULL (2);
 349
 350 /* Location management.  */
 351
 352 /* Create a new diagnostic_file * for file NAME.
 353
 354    Repeated calls with matching NAMEs will return the
 355    same object.
 356
 357    If SARIF_SOURCE_LANGUAGE is non-NULL, it specifies a "sourceLanguage"
 358    value for the file when use when writing SARIF.
 359    See SARIF v2.1.0 Appendix J for suggested values for various
 360    programmming languages.  */
 361
 362 extern diagnostic_file *
 363 diagnostic_manager_new_file (diagnostic_manager *diag_mgr,
 364                              const char *name,
 365                              const char *sarif_source_language)
 366   LIBGDIAGNOSTICS_PARAM_MUST_BE_NON_NULL (1)
 367   LIBGDIAGNOSTICS_PARAM_MUST_BE_NON_NULL (2)
 368   LIBGDIAGNOSTICS_PARAM_CAN_BE_NULL (3);
 369
 370 /* Populate the source-quoting cache for FILE, specifying the
 371    given buffer as the content of the file (rather than
 372    attempting to read the content from the filesystem).  */
 373
 374 extern void
 375 diagnostic_file_set_buffered_content (diagnostic_file *file,
 376                                       const char *buf,
 377                                       size_t sz)
 378   LIBGDIAGNOSTICS_PARAM_MUST_BE_NON_NULL (1)
 379   LIBGDIAGNOSTICS_PARAM_MUST_BE_NON_NULL (2);
 380
 381 /* Write a representation of FILE to OUT, for debugging.  */
 382
 383 extern void
 384 diagnostic_manager_debug_dump_file (diagnostic_manager *diag_mgr,
 385                                     const diagnostic_file *file,
 386                                     FILE *out)
 387   LIBGDIAGNOSTICS_PARAM_MUST_BE_NON_NULL (1)
 388   LIBGDIAGNOSTICS_PARAM_CAN_BE_NULL (2)
 389   LIBGDIAGNOSTICS_PARAM_MUST_BE_NON_NULL (3);
 390
 391 /* Attempt to create a diagnostic_location representing
 392    FILENAME:LINE_NUM, with no column information
 393    (thus "the whole line").  */
 394
 395 extern const diagnostic_physical_location *
 396 diagnostic_manager_new_location_from_file_and_line (diagnostic_manager *diag_mgr,
 397                                                     const diagnostic_file *file,
 398                                                     diagnostic_line_num_t line_num)
 399   LIBGDIAGNOSTICS_PARAM_MUST_BE_NON_NULL (1)
 400   LIBGDIAGNOSTICS_PARAM_MUST_BE_NON_NULL (2);
 401
 402 /* Attempt to create a diagnostic_physical_location representing
 403    FILENAME:LINE_NUM:COLUMN_NUM.  */
 404
 405 extern const diagnostic_physical_location *
 406 diagnostic_manager_new_location_from_file_line_column (diagnostic_manager *diag_mgr,
 407                                                        const diagnostic_file *file,
 408                                                        diagnostic_line_num_t line_num,
 409                                                        diagnostic_column_num_t column_num)
 410   LIBGDIAGNOSTICS_PARAM_MUST_BE_NON_NULL (1)
 411   LIBGDIAGNOSTICS_PARAM_MUST_BE_NON_NULL (2);
 412
 413 /* Attempt to create a diagnostic_physical_location representing a
 414    range within a source file, with a highlighted "caret" location.
 415
 416    All must be within the same file, but they can be on different lines.
 417
 418    For example, consider the location of the binary expression below:
 419
 420      ...|__________1111111112222222
 421      ...|12345678901234567890123456
 422      ...|
 423      521|int sum (int foo, int bar)
 424      522|{
 425      523|   return foo + bar;
 426      ...|          ~~~~^~~~~
 427      524|}
 428
 429    The location's caret is at the "+", line 523 column 15, but starts
 430    earlier, at the "f" of "foo" at column 11.  The finish is at the "r"
 431    of "bar" at column 19.  */
 432
 433 extern const diagnostic_physical_location *
 434 diagnostic_manager_new_location_from_range (diagnostic_manager *diag_mgr,
 435                                             const diagnostic_physical_location *loc_caret,
 436                                             const diagnostic_physical_location *loc_start,
 437                                             const diagnostic_physical_location *loc_end)
 438   LIBGDIAGNOSTICS_PARAM_MUST_BE_NON_NULL (1)
 439   LIBGDIAGNOSTICS_PARAM_CAN_BE_NULL (2)
 440   LIBGDIAGNOSTICS_PARAM_CAN_BE_NULL (3)
 441   LIBGDIAGNOSTICS_PARAM_CAN_BE_NULL (4);
 442
 443 /* Write a representation of LOC to OUT, for debugging.  */
 444
 445 extern void
 446 diagnostic_manager_debug_dump_location (const diagnostic_manager *diag_mgr,
 447                                         const diagnostic_physical_location *loc,
 448                                         FILE *out)
 449   LIBGDIAGNOSTICS_PARAM_MUST_BE_NON_NULL (1)
 450   LIBGDIAGNOSTICS_PARAM_CAN_BE_NULL (2)
 451   LIBGDIAGNOSTICS_PARAM_MUST_BE_NON_NULL (3);
 452
 453 /* A bundle of state describing a logical location in the user's source,
 454    such as "in function 'foo'".
 455
 456    SHORT_NAME can be NULL, or else a string suitable for use by
 457    the SARIF logicalLocation "name" property (SARIF v2.1.0 section 3.33.4).
 458
 459    FULLY_QUALIFIED_NAME can be NULL or else a string  suitable for use by
 460    the SARIF logicalLocation "fullyQualifiedName" property
 461    (SARIF v2.1.0 section 3.33.5).
 462
 463    DECORATED_NAME can be NULL or else a string  suitable for use by
 464    the SARIF logicalLocation "decoratedName" property
 465    (SARIF v2.1.0 section 3.33.6).  */
 466
 467 extern const diagnostic_logical_location *
 468 diagnostic_manager_new_logical_location (diagnostic_manager *diag_mgr,
 469                                          enum diagnostic_logical_location_kind_t kind,
 470                                          const diagnostic_logical_location *parent,
 471                                          const char *short_name,
 472                                          const char *fully_qualified_name,
 473                                          const char *decorated_name)
 474   LIBGDIAGNOSTICS_PARAM_MUST_BE_NON_NULL (1)
 475   LIBGDIAGNOSTICS_PARAM_CAN_BE_NULL (3)
 476   LIBGDIAGNOSTICS_PARAM_CAN_BE_NULL (4)
 477   LIBGDIAGNOSTICS_PARAM_CAN_BE_NULL (5)
 478   LIBGDIAGNOSTICS_PARAM_CAN_BE_NULL (6);
 479
 480 /* Write a representation of LOC to OUT, for debugging.  */
 481
 482 extern void
 483 diagnostic_manager_debug_dump_logical_location (const diagnostic_manager *diag_mgr,
 484                                                 const diagnostic_logical_location *loc,
 485                                                 FILE *out)
 486   LIBGDIAGNOSTICS_PARAM_MUST_BE_NON_NULL (1)
 487   LIBGDIAGNOSTICS_PARAM_CAN_BE_NULL (2)
 488   LIBGDIAGNOSTICS_PARAM_MUST_BE_NON_NULL (3);
 489
 490 /* Diagnostic groups.  */
 491
 492 /* Begin a diagnostic group.  All diagnostics emitted within
 493    DIAG_MGR after the first one will be treated as notes about
 494    the initial diagnostic.  */
 495
 496 extern void
 497 diagnostic_manager_begin_group (diagnostic_manager *diag_mgr)
 498   LIBGDIAGNOSTICS_PARAM_MUST_BE_NON_NULL (1);
 499
 500 /* Finish a diagnostic group.  */
 501
 502 extern void
 503 diagnostic_manager_end_group (diagnostic_manager *diag_mgr)
 504   LIBGDIAGNOSTICS_PARAM_MUST_BE_NON_NULL (1);
 505
 506 /* Step-by-step creation of a diagnostic.  */
 507
 508 extern diagnostic *
 509 diagnostic_begin (diagnostic_manager *diag_mgr,
 510                   enum diagnostic_level level)
 511   LIBGDIAGNOSTICS_PARAM_MUST_BE_NON_NULL (1);
 512
 513 /* Associate this diagnostic with the given ID within
 514    the Common Weakness Enumeration.  */
 515
 516 extern void
 517 diagnostic_set_cwe (diagnostic *diag,
 518                     unsigned cwe_id)
 519   LIBGDIAGNOSTICS_PARAM_MUST_BE_NON_NULL (1);
 520
 521 /* Associate this diagnostic with a particular rule that has been violated
 522    (such as in a coding standard, or within a specification).
 523    The rule must have at least one of a title and a URL, but these
 524    can be NULL.
 525    A diagnostic can be associated with zero or more rules.  */
 526
 527 extern void
 528 diagnostic_add_rule (diagnostic *diag,
 529                      const char *title,
 530                      const char *url)
 531   LIBGDIAGNOSTICS_PARAM_MUST_BE_NON_NULL (1)
 532   LIBGDIAGNOSTICS_PARAM_CAN_BE_NULL (2)
 533   LIBGDIAGNOSTICS_PARAM_CAN_BE_NULL (3);
 534
 535 /* Set the primary location of DIAG.  */
 536
 537 extern void
 538 diagnostic_set_location (diagnostic *diag,
 539                          const diagnostic_physical_location * loc)
 540   LIBGDIAGNOSTICS_PARAM_MUST_BE_NON_NULL (1)
 541   LIBGDIAGNOSTICS_PARAM_CAN_BE_NULL (2);
 542
 543 /* Set the primary location of DIAG, with a label.  */
 544
 545 extern void
 546 diagnostic_set_location_with_label (diagnostic *diag,
 547                                     const diagnostic_physical_location *loc,
 548                                     const char *fmt, ...)
 549   LIBGDIAGNOSTICS_PARAM_MUST_BE_NON_NULL (1)
 550   LIBGDIAGNOSTICS_PARAM_CAN_BE_NULL (2)
 551   LIBGDIAGNOSTICS_PARAM_MUST_BE_NON_NULL (3);
 552
 553 /* Add a secondary location to DIAG.  */
 554
 555 extern void
 556 diagnostic_add_location (diagnostic *diag,
 557                          const diagnostic_physical_location * loc)
 558   LIBGDIAGNOSTICS_PARAM_MUST_BE_NON_NULL (1);
 559
 560 /* Add a secondary location to DIAG, with a label.  */
 561
 562 extern void
 563 diagnostic_add_location_with_label (diagnostic *diag,
 564                                     const diagnostic_physical_location *loc,
 565                                     const char *text)
 566   LIBGDIAGNOSTICS_PARAM_MUST_BE_NON_NULL (1)
 567   LIBGDIAGNOSTICS_PARAM_CAN_BE_NULL (2)
 568   LIBGDIAGNOSTICS_PARAM_MUST_BE_NON_NULL (3);
 569
 570 /* Set the logical location of DIAG.  */
 571
 572 extern void
 573 diagnostic_set_logical_location (diagnostic *diag,
 574                                  const diagnostic_logical_location *logical_loc)
 575   LIBGDIAGNOSTICS_PARAM_MUST_BE_NON_NULL (1)
 576   LIBGDIAGNOSTICS_PARAM_CAN_BE_NULL (2);
 577
 578 /* Fix-it hints.  */
 579
 580 extern void
 581 diagnostic_add_fix_it_hint_insert_before (diagnostic *diag,
 582                                           const diagnostic_physical_location *loc,
 583                                           const char *addition)
 584   LIBGDIAGNOSTICS_PARAM_MUST_BE_NON_NULL (1)
 585   LIBGDIAGNOSTICS_PARAM_CAN_BE_NULL (2)
 586   LIBGDIAGNOSTICS_PARAM_MUST_BE_NON_NULL (3);
 587
 588 extern void
 589 diagnostic_add_fix_it_hint_insert_after (diagnostic *diag,
 590                                          const diagnostic_physical_location *loc,
 591                                          const char *addition)
 592   LIBGDIAGNOSTICS_PARAM_MUST_BE_NON_NULL (1)
 593   LIBGDIAGNOSTICS_PARAM_CAN_BE_NULL (2)
 594   LIBGDIAGNOSTICS_PARAM_MUST_BE_NON_NULL (3);
 595
 596 extern void
 597 diagnostic_add_fix_it_hint_replace (diagnostic *diag,
 598                                     const diagnostic_physical_location *loc,
 599                                     const char *replacement)
 600   LIBGDIAGNOSTICS_PARAM_MUST_BE_NON_NULL (1)
 601   LIBGDIAGNOSTICS_PARAM_CAN_BE_NULL (2)
 602   LIBGDIAGNOSTICS_PARAM_MUST_BE_NON_NULL (3);
 603
 604 extern void
 605 diagnostic_add_fix_it_hint_delete (diagnostic *diag,
 606                                    const diagnostic_physical_location *loc)
 607   LIBGDIAGNOSTICS_PARAM_MUST_BE_NON_NULL (1)
 608   LIBGDIAGNOSTICS_PARAM_CAN_BE_NULL (2);
 609
 610 /* Create and borrow a pointer to an execution path for DIAG.
 611    The path is automatically cleaned up when DIAG is finished.  */
 612
 613 extern diagnostic_execution_path *
 614 diagnostic_add_execution_path (diagnostic *diag)
 615   LIBGDIAGNOSTICS_PARAM_MUST_BE_NON_NULL (1);
 616
 617 /* Create a new execution path.
 618    This is owned by the called and must have either
 619    diagnostic_take_execution_path or diagnostic_execution_path_release
 620    called on it.  */
 621
 622 extern diagnostic_execution_path *
 623 diagnostic_manager_new_execution_path (diagnostic_manager *manager)
 624   LIBGDIAGNOSTICS_PARAM_MUST_BE_NON_NULL (1);
 625
 626 /* Set DIAG to use PATH as its execution path, taking ownership of PATH.  */
 627
 628 extern void
 629 diagnostic_take_execution_path (diagnostic *diag,
 630                                 diagnostic_execution_path *path)
 631   LIBGDIAGNOSTICS_PARAM_MUST_BE_NON_NULL (1)
 632   LIBGDIAGNOSTICS_PARAM_MUST_BE_NON_NULL (2);
 633
 634 /* Release ownership of PATH, which must not have been taken
 635    by a diagnostic.  */
 636
 637 extern void
 638 diagnostic_execution_path_release (diagnostic_execution_path *path)
 639   LIBGDIAGNOSTICS_PARAM_CAN_BE_NULL (1);
 640
 641 /* Append an event to the end of PATH.  */
 642
 643 extern diagnostic_event_id
 644 diagnostic_execution_path_add_event (diagnostic_execution_path *path,
 645                                      const diagnostic_physical_location *physical_loc,
 646                                      const diagnostic_logical_location *logical_loc,
 647                                      unsigned stack_depth,
 648                                      const char *fmt, ...)
 649   LIBGDIAGNOSTICS_PARAM_MUST_BE_NON_NULL (1)
 650   LIBGDIAGNOSTICS_PARAM_CAN_BE_NULL (2)
 651   LIBGDIAGNOSTICS_PARAM_CAN_BE_NULL (3)
 652   LIBGDIAGNOSTICS_PARAM_MUST_BE_NON_NULL (5)
 653   LIBGDIAGNOSTICS_PARAM_GCC_FORMAT_STRING (5, 6);
 654
 655 /* Append an event to the end of PATH.  */
 656
 657 extern diagnostic_event_id
 658 diagnostic_execution_path_add_event_va (diagnostic_execution_path *path,
 659                                         const diagnostic_physical_location *physical_loc,
 660                                         const diagnostic_logical_location *logical_loc,
 661                                         unsigned stack_depth,
 662                                         const char *fmt,
 663                                         va_list *args)
 664   LIBGDIAGNOSTICS_PARAM_MUST_BE_NON_NULL (1)
 665   LIBGDIAGNOSTICS_PARAM_CAN_BE_NULL (2)
 666   LIBGDIAGNOSTICS_PARAM_CAN_BE_NULL (3)
 667   LIBGDIAGNOSTICS_PARAM_MUST_BE_NON_NULL (5)
 668   LIBGDIAGNOSTICS_PARAM_GCC_FORMAT_STRING (5, 0);
 669
 670 /* Emit DIAG to all sinks of its manager, and release DIAG.
 671    Use FMT for the message.
 672    Note that this uses gcc's pretty-print format, which is *not* printf.
 673    TODO: who is responsible for putting FMT through gettext?  */
 674
 675 extern void
 676 diagnostic_finish (diagnostic *diag, const char *fmt, ...)
 677   LIBGDIAGNOSTICS_PARAM_MUST_BE_NON_NULL (1)
 678   LIBGDIAGNOSTICS_PARAM_MUST_BE_NON_NULL (2)
 679   LIBGDIAGNOSTICS_PARAM_GCC_FORMAT_STRING (2, 3);
 680
 681 /* As diagnostic_finish, but with a va_list.  */
 682
 683 extern void
 684 diagnostic_finish_va (diagnostic *diag, const char *fmt, va_list *args)
 685   LIBGDIAGNOSTICS_PARAM_MUST_BE_NON_NULL (1)
 686   LIBGDIAGNOSTICS_PARAM_MUST_BE_NON_NULL (2)
 687   LIBGDIAGNOSTICS_PARAM_GCC_FORMAT_STRING (2, 0);
 688
 689 /* DEFERRED:
 690    - thread-safety
 691    - plural forms
 692    - enum about what a "column number" means (bytes, unichars, etc)
 693    - locations within binary files
 694    - options and URLs for warnings
 695    - enable/disable of warnings by kind
 696    - plugin metadata.  */
 697
 698 #ifdef __cplusplus
 699 }
 700 #endif /* __cplusplus */
 701
 702 #endif  /* LIBGDIAGNOSTICS_H  */