clang 20.0.0git
Typedefs | Enumerations | Functions
Diagnostic reporting

Typedefs

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

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.
 
CINDEX_LINKAGE CXDiagnostic clang_getDiagnosticInSet (CXDiagnosticSet Diags, unsigned Index)
 Retrieve a diagnostic associated with the given CXDiagnosticSet.
 
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.
 
CINDEX_LINKAGE void clang_disposeDiagnosticSet (CXDiagnosticSet Diags)
 Release a CXDiagnosticSet and all of its contained diagnostics.
 
CINDEX_LINKAGE CXDiagnosticSet clang_getChildDiagnostics (CXDiagnostic D)
 Retrieve the child diagnostics of a CXDiagnostic.
 
CINDEX_LINKAGE void clang_disposeDiagnostic (CXDiagnostic Diagnostic)
 Destroy a diagnostic.
 
CINDEX_LINKAGE CXString clang_formatDiagnostic (CXDiagnostic Diagnostic, unsigned Options)
 Format the given diagnostic in a manner that is suitable for display.
 
CINDEX_LINKAGE unsigned clang_defaultDiagnosticDisplayOptions (void)
 Retrieve the set of display options most similar to the default behavior of the clang compiler.
 
CINDEX_LINKAGE enum CXDiagnosticSeverity clang_getDiagnosticSeverity (CXDiagnostic)
 Determine the severity of the given diagnostic.
 
CINDEX_LINKAGE CXSourceLocation clang_getDiagnosticLocation (CXDiagnostic)
 Retrieve the source location of the given diagnostic.
 
CINDEX_LINKAGE CXString clang_getDiagnosticSpelling (CXDiagnostic)
 Retrieve the text of the given diagnostic.
 
CINDEX_LINKAGE CXString clang_getDiagnosticOption (CXDiagnostic Diag, CXString *Disable)
 Retrieve the name of the command-line option that enabled this diagnostic.
 
CINDEX_LINKAGE unsigned clang_getDiagnosticCategory (CXDiagnostic)
 Retrieve the category number for this diagnostic.
 
CINDEX_DEPRECATED CINDEX_LINKAGE CXString clang_getDiagnosticCategoryName (unsigned Category)
 Retrieve the name of a particular diagnostic category.
 
CINDEX_LINKAGE CXString clang_getDiagnosticCategoryText (CXDiagnostic)
 Retrieve the diagnostic category text for a given diagnostic.
 
CINDEX_LINKAGE unsigned clang_getDiagnosticNumRanges (CXDiagnostic)
 Determine the number of source ranges associated with the given diagnostic.
 
CINDEX_LINKAGE CXSourceRange clang_getDiagnosticRange (CXDiagnostic Diagnostic, unsigned Range)
 Retrieve a source range associated with the diagnostic.
 
CINDEX_LINKAGE unsigned clang_getDiagnosticNumFixIts (CXDiagnostic Diagnostic)
 Determine the number of fix-it hints associated with the given diagnostic.
 
CINDEX_LINKAGE CXString clang_getDiagnosticFixIt (CXDiagnostic Diagnostic, unsigned FixIt, CXSourceRange *ReplacementRange)
 Retrieve the replacement information for a given fix-it.
 

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 69 of file CXDiagnostic.h.

◆ CXDiagnosticSet

typedef void* CXDiagnosticSet

A group of CXDiagnostics.

Definition at line 74 of file CXDiagnostic.h.

Enumeration Type Documentation

◆ 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 162 of file CXDiagnostic.h.

◆ 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 33 of file CXDiagnostic.h.

◆ 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 97 of file CXDiagnostic.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
DiagnosticThe diagnostic to print.
OptionsA 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_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
CategoryA 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
DiagnosticThe diagnostic whose fix-its are being queried.
FixItThe zero-based index of the fix-it.
ReplacementRangeThe 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
Diagsthe CXDiagnosticSet to query.
Indexthe 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
DiagThe diagnostic to be queried.
DisableIf 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
Diagnosticthe diagnostic whose range is being extracted.
Rangethe zero-based index specifying which range to
Returns
the requested source range.

◆ 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_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
fileThe name of the file to deserialize.
errorA pointer to a enum value recording if there was a problem deserializing the diagnostics.
errorStringA 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().