clang 8.0.0

Typedefs | Enumerations | Functions
Diagnostic reporting
libclang: C Interface to Clang
Collaboration diagram for Diagnostic reporting:

## Typedefs
typedef void * | CXDiagnostic
| A single diagnostic, containing the diagnostic's severity, location, text, source ranges, and fix-it hints. More...
typedef void * | CXDiagnosticSet
| A group of CXDiagnostics. More...

## Enumerations
enum | CXDiagnosticSeverity { CXDiagnostic_Ignored = 0, CXDiagnostic_Note = 1, CXDiagnostic_Warning = 2, CXDiagnostic_Error = 3, CXDiagnostic_Fatal = 4 }
| Describes the severity of a particular diagnostic. More...
enum | CXLoadDiag_Error { CXLoadDiag_None = 0, CXLoadDiag_Unknown = 1, CXLoadDiag_CannotLoad = 2, CXLoadDiag_InvalidFile = 3 }
| Describes the kind of error that occurred (if any) in a call to `clang_loadDiagnostics`. More...
enum | CXDiagnosticDisplayOptions { CXDiagnostic_DisplaySourceLocation = 0x01, CXDiagnostic_DisplayColumn = 0x02, CXDiagnostic_DisplaySourceRanges = 0x04, CXDiagnostic_DisplayOption = 0x08, CXDiagnostic_DisplayCategoryId = 0x10, CXDiagnostic_DisplayCategoryName = 0x20 }
| Options to control the display of diagnostics. More...

## Functions
CINDEX_LINKAGE unsigned | clang_getNumDiagnosticsInSet (CXDiagnosticSet Diags)
| Determine the number of diagnostics in a CXDiagnosticSet. More...
CINDEX_LINKAGE CXDiagnostic | clang_getDiagnosticInSet (CXDiagnosticSet Diags, unsigned Index)
| Retrieve a diagnostic associated with the given CXDiagnosticSet. More...
CINDEX_LINKAGE CXDiagnosticSet | clang_loadDiagnostics (const char *file, enum CXLoadDiag_Error *error, CXString *errorString)
| Deserialize a set of diagnostics from a Clang diagnostics bitcode file. More...
CINDEX_LINKAGE void | clang_disposeDiagnosticSet (CXDiagnosticSet Diags)
| Release a CXDiagnosticSet and all of its contained diagnostics. More...
CINDEX_LINKAGE CXDiagnosticSet | clang_getChildDiagnostics (CXDiagnostic D)
| Retrieve the child diagnostics of a CXDiagnostic. More...
CINDEX_LINKAGE unsigned | clang_getNumDiagnostics (CXTranslationUnit Unit)
| Determine the number of diagnostics produced for the given translation unit. More...
CINDEX_LINKAGE CXDiagnostic | clang_getDiagnostic (CXTranslationUnit Unit, unsigned Index)
| Retrieve a diagnostic associated with the given translation unit. More...
CINDEX_LINKAGE CXDiagnosticSet | clang_getDiagnosticSetFromTU (CXTranslationUnit Unit)
| Retrieve the complete set of diagnostics associated with a translation unit. More...
CINDEX_LINKAGE void | clang_disposeDiagnostic (CXDiagnostic Diagnostic)
| Destroy a diagnostic. More...
CINDEX_LINKAGE CXString | clang_formatDiagnostic (CXDiagnostic Diagnostic, unsigned Options)
| Format the given diagnostic in a manner that is suitable for display. More...
CINDEX_LINKAGE unsigned | clang_defaultDiagnosticDisplayOptions (void)
| Retrieve the set of display options most similar to the default behavior of the clang compiler. More...
CINDEX_LINKAGE enum CXDiagnosticSeverity | clang_getDiagnosticSeverity (CXDiagnostic)
| Determine the severity of the given diagnostic. More...
CINDEX_LINKAGE CXSourceLocation | clang_getDiagnosticLocation (CXDiagnostic)
| Retrieve the source location of the given diagnostic. More...
CINDEX_LINKAGE CXString | clang_getDiagnosticSpelling (CXDiagnostic)
| Retrieve the text of the given diagnostic. More...
CINDEX_LINKAGE CXString | clang_getDiagnosticOption (CXDiagnostic Diag, CXString *Disable)
| Retrieve the name of the command-line option that enabled this diagnostic. More...
CINDEX_LINKAGE unsigned | clang_getDiagnosticCategory (CXDiagnostic)
| Retrieve the category number for this diagnostic. More...
CINDEX_DEPRECATED CINDEX_LINKAGE CXString | clang_getDiagnosticCategoryName (unsigned Category)
| Retrieve the name of a particular diagnostic category. More...
CINDEX_LINKAGE CXString | clang_getDiagnosticCategoryText (CXDiagnostic)
| Retrieve the diagnostic category text for a given diagnostic. More...
CINDEX_LINKAGE unsigned | clang_getDiagnosticNumRanges (CXDiagnostic)
| Determine the number of source ranges associated with the given diagnostic. More...
CINDEX_LINKAGE CXSourceRange | clang_getDiagnosticRange (CXDiagnostic Diagnostic, unsigned Range)
| Retrieve a source range associated with the diagnostic. More...
CINDEX_LINKAGE unsigned | clang_getDiagnosticNumFixIts (CXDiagnostic Diagnostic)
| Determine the number of fix-it hints associated with the given diagnostic. More...
CINDEX_LINKAGE CXString | clang_getDiagnosticFixIt (CXDiagnostic Diagnostic, unsigned FixIt, CXSourceRange *ReplacementRange)
| Retrieve the replacement information for a given fix-it. More...

## Detailed Description

## Typedef Documentation

## ◆ CXDiagnostic

typedef void* CXDiagnostic

A single diagnostic, containing the diagnostic's severity, location, text, source ranges, and fix-it hints.

Definition at line 782 of file Index.h.

## ◆ CXDiagnosticSet

typedef void* CXDiagnosticSet

A group of CXDiagnostics.

Definition at line 787 of file Index.h.

## Enumeration Type Documentation

## ◆ CXDiagnosticDisplayOptions

enum CXDiagnosticDisplayOptions

Options to control the display of diagnostics.

The values in this enum are meant to be combined to customize the behavior of `clang_formatDiagnostic()`.

Enumerator
CXDiagnostic_DisplaySourceLocation | Display the source-location information where the diagnostic was located. When set, diagnostics will be prefixed by the file, line, and (optionally) column to which the diagnostic refers. For example, test.c:28: warning: extra tokens at end of #endif directive This option corresponds to the clang flag `-fshow-source-location`.
CXDiagnostic_DisplayColumn | If displaying the source-location information of the diagnostic, also include the column number. This option corresponds to the clang flag `-fshow-column`.
CXDiagnostic_DisplaySourceRanges | If displaying the source-location information of the diagnostic, also include information about source ranges in a machine-parsable format. This option corresponds to the clang flag `-fdiagnostics-print-source-range-info`.
CXDiagnostic_DisplayOption | Display the option name associated with this diagnostic, if any. The option name displayed (e.g., -Wconversion) will be placed in brackets after the diagnostic text. This option corresponds to the clang flag `-fdiagnostics-show-option`.
CXDiagnostic_DisplayCategoryId | Display the category number associated with this diagnostic, if any. The category number is displayed within brackets after the diagnostic text. This option corresponds to the clang flag `-fdiagnostics-show-category=id`.
CXDiagnostic_DisplayCategoryName | Display the category name associated with this diagnostic, if any. The category name is displayed within brackets after the diagnostic text. This option corresponds to the clang flag `-fdiagnostics-show-category=name`.

Definition at line 903 of file Index.h.

## ◆ CXDiagnosticSeverity

enum CXDiagnosticSeverity

Describes the severity of a particular diagnostic.

Enumerator
CXDiagnostic_Ignored | A diagnostic that has been suppressed, e.g., by a command-line option.
CXDiagnostic_Note | This diagnostic is a note that should be attached to the previous (non-note) diagnostic.
CXDiagnostic_Warning | This diagnostic indicates suspicious code that may not be wrong.
CXDiagnostic_Error | This diagnostic indicates that the code is ill-formed.
CXDiagnostic_Fatal | This diagnostic indicates that the code is ill-formed such that future parser recovery is unlikely to produce useful results.

Definition at line 746 of file Index.h.

## ◆ CXLoadDiag_Error

enum CXLoadDiag_Error

Describes the kind of error that occurred (if any) in a call to `clang_loadDiagnostics`.

Enumerator
CXLoadDiag_None | Indicates that no error occurred.
CXLoadDiag_Unknown | Indicates that an unknown error occurred while attempting to deserialize diagnostics.
CXLoadDiag_CannotLoad | Indicates that the file containing the serialized diagnostics could not be opened.
CXLoadDiag_InvalidFile | Indicates that the serialized diagnostics file is invalid or corrupt.

Definition at line 810 of file Index.h.

## Function Documentation

## ◆ clang_defaultDiagnosticDisplayOptions()

CINDEX_LINKAGE unsigned clang_defaultDiagnosticDisplayOptions | ( | void |  | ) |

Retrieve the set of display options most similar to the default behavior of the clang compiler.

Returns
  A set of display options suitable for use with `clang_formatDiagnostic()`.

## ◆ clang_disposeDiagnostic()

CINDEX_LINKAGE void clang_disposeDiagnostic | ( | CXDiagnostic | Diagnostic | ) |

Destroy a diagnostic.

## ◆ clang_disposeDiagnosticSet()

CINDEX_LINKAGE void clang_disposeDiagnosticSet | ( | CXDiagnosticSet | Diags | ) |

Release a CXDiagnosticSet and all of its contained diagnostics.

## ◆ clang_formatDiagnostic()

CINDEX_LINKAGE CXString clang_formatDiagnostic | ( | CXDiagnostic | Diagnostic,
|  | unsigned | Options
| ) |  |

Format the given diagnostic in a manner that is suitable for display.

This routine will format the given diagnostic to a string, rendering the diagnostic according to the various options given. The `clang_defaultDiagnosticDisplayOptions()` function returns the set of options that most closely mimics the behavior of the clang compiler.

Parameters

  Diagnostic | The diagnostic to print.
  Options | A set of options that control the diagnostic display, created by combining `CXDiagnosticDisplayOptions` values.

Returns
  A new string containing for formatted diagnostic.

## ◆ clang_getChildDiagnostics()

CINDEX_LINKAGE CXDiagnosticSet clang_getChildDiagnostics | ( | CXDiagnostic | D | ) |

Retrieve the child diagnostics of a CXDiagnostic.

This CXDiagnosticSet does not need to be released by clang_disposeDiagnosticSet.

## ◆ clang_getDiagnostic()

CINDEX_LINKAGE CXDiagnostic clang_getDiagnostic | ( | CXTranslationUnit | Unit,
|  | unsigned | Index
| ) |  |

Retrieve a diagnostic associated with the given translation unit.

Parameters

  Unit | the translation unit to query.
  Index | the zero-based diagnostic number to retrieve.

Returns
  the requested diagnostic. This diagnostic must be freed via a call to `clang_disposeDiagnostic()`.

## ◆ clang_getDiagnosticCategory()

CINDEX_LINKAGE unsigned clang_getDiagnosticCategory | ( | CXDiagnostic |  | ) |

Retrieve the category number for this diagnostic.

Diagnostics can be categorized into groups along with other, related diagnostics (e.g., diagnostics under the same warning flag). This routine retrieves the category number for the given diagnostic.

Returns
  The number of the category that contains this diagnostic, or zero if this diagnostic is uncategorized.

## ◆ clang_getDiagnosticCategoryName()

CINDEX_DEPRECATED CINDEX_LINKAGE CXString clang_getDiagnosticCategoryName | ( | unsigned | Category | ) |

Retrieve the name of a particular diagnostic category.

This is now deprecated. Use clang_getDiagnosticCategoryText() instead.

Parameters

  Category | A diagnostic category number, as returned by `clang_getDiagnosticCategory()`.

Returns
  The name of the given diagnostic category.

## ◆ clang_getDiagnosticCategoryText()

CINDEX_LINKAGE CXString clang_getDiagnosticCategoryText | ( | CXDiagnostic |  | ) |

Retrieve the diagnostic category text for a given diagnostic.

Returns
  The text of the given diagnostic category.

## ◆ clang_getDiagnosticFixIt()

CINDEX_LINKAGE CXString clang_getDiagnosticFixIt | ( | CXDiagnostic | Diagnostic,
|  | unsigned | FixIt,
|  | CXSourceRange * | ReplacementRange
| ) |  |

Retrieve the replacement information for a given fix-it.

Fix-its are described in terms of a source range whose contents should be replaced by a string. This approach generalizes over three kinds of operations: removal of source code (the range covers the code to be removed and the replacement string is empty), replacement of source code (the range covers the code to be replaced and the replacement string provides the new code), and insertion (both the start and end of the range point at the insertion location, and the replacement string provides the text to insert).

Parameters

  Diagnostic | The diagnostic whose fix-its are being queried.
  FixIt | The zero-based index of the fix-it.
  ReplacementRange | The source range whose contents will be replaced with the returned replacement string. Note that source ranges are half-open ranges [a, b), so the source code should be replaced from a and up to (but not including) b.

Returns
  A string containing text that should be replace the source code indicated by the `ReplacementRange`.

## ◆ clang_getDiagnosticInSet()

CINDEX_LINKAGE CXDiagnostic clang_getDiagnosticInSet | ( | CXDiagnosticSet | Diags,
|  | unsigned | Index
| ) |  |

Retrieve a diagnostic associated with the given CXDiagnosticSet.

Parameters

  Diags | the CXDiagnosticSet to query.
  Index | the zero-based diagnostic number to retrieve.

Returns
  the requested diagnostic. This diagnostic must be freed via a call to `clang_disposeDiagnostic()`.

## ◆ clang_getDiagnosticLocation()

CINDEX_LINKAGE CXSourceLocation clang_getDiagnosticLocation | ( | CXDiagnostic |  | ) |

Retrieve the source location of the given diagnostic.

This location is where Clang would print the caret ('^') when displaying the diagnostic on the command line.

## ◆ clang_getDiagnosticNumFixIts()

CINDEX_LINKAGE unsigned clang_getDiagnosticNumFixIts | ( | CXDiagnostic | Diagnostic | ) |

Determine the number of fix-it hints associated with the given diagnostic.

## ◆ clang_getDiagnosticNumRanges()

CINDEX_LINKAGE unsigned clang_getDiagnosticNumRanges | ( | CXDiagnostic |  | ) |

Determine the number of source ranges associated with the given diagnostic.

## ◆ clang_getDiagnosticOption()

CINDEX_LINKAGE CXString clang_getDiagnosticOption | ( | CXDiagnostic | Diag,
|  | CXString * | Disable
| ) |  |

Retrieve the name of the command-line option that enabled this diagnostic.

Parameters

  Diag | The diagnostic to be queried.
  Disable | If non-NULL, will be set to the option that disables this diagnostic (if any).

Returns
  A string that contains the command-line option used to enable this warning, such as "-Wconversion" or "-pedantic".

## ◆ clang_getDiagnosticRange()

CINDEX_LINKAGE CXSourceRange clang_getDiagnosticRange | ( | CXDiagnostic | Diagnostic,
|  | unsigned | Range
| ) |  |

Retrieve a source range associated with the diagnostic.

A diagnostic's source ranges highlight important elements in the source code. On the command line, Clang displays source ranges by underlining them with '~' characters.

Parameters

  Diagnostic | the diagnostic whose range is being extracted.
  Range | the zero-based index specifying which range to

Returns
  the requested source range.

## ◆ clang_getDiagnosticSetFromTU()

CINDEX_LINKAGE CXDiagnosticSet clang_getDiagnosticSetFromTU | ( | CXTranslationUnit | Unit | ) |

Retrieve the complete set of diagnostics associated with a translation unit.

Parameters

  Unit | the translation unit to query.

## ◆ clang_getDiagnosticSeverity()

CINDEX_LINKAGE enum CXDiagnosticSeverity clang_getDiagnosticSeverity | ( | CXDiagnostic |  | ) |

Determine the severity of the given diagnostic.

## ◆ clang_getDiagnosticSpelling()

CINDEX_LINKAGE CXString clang_getDiagnosticSpelling | ( | CXDiagnostic |  | ) |

Retrieve the text of the given diagnostic.

## ◆ clang_getNumDiagnostics()

CINDEX_LINKAGE unsigned clang_getNumDiagnostics | ( | CXTranslationUnit | Unit | ) |

Determine the number of diagnostics produced for the given translation unit.

## ◆ clang_getNumDiagnosticsInSet()

CINDEX_LINKAGE unsigned clang_getNumDiagnosticsInSet | ( | CXDiagnosticSet | Diags | ) |

Determine the number of diagnostics in a CXDiagnosticSet.

## ◆ clang_loadDiagnostics()

CINDEX_LINKAGE CXDiagnosticSet clang_loadDiagnostics | ( | const char * | file,
|  | enum CXLoadDiag_Error * | error,
|  | CXString * | errorString
| ) |  |

Deserialize a set of diagnostics from a Clang diagnostics bitcode file.

Parameters

  file | The name of the file to deserialize.
  error | A pointer to a enum value recording if there was a problem deserializing the diagnostics.
  errorString | A pointer to a CXString for recording the error string if the file was not successfully loaded.

Returns
  A loaded CXDiagnosticSet if successful, and NULL otherwise. These diagnostics should be released using clang_disposeDiagnosticSet().