C and C++ Binaries

AST: cs_ast.h

Operations and supporting types for ASTs (cs_ast).

ASTs are available for C/C++ and binary analyses only. For C# and Java analyses, plug-ins that rely on AST properties and relationships will generally not produce useful information.

Links

Defines

#define CS_AST_H
#define cs_ast_dig(ast, out_field, ...) cs_ast_dig(ast, out_field, __VA_ARGS__, csao_null) This helps prevent bugs where the client neglects to null terminate the argument list (having two null terminators isn't harmful).
#define CS_AST_NULL (cs_ast_get_null()) The null cs_ast.
#define CS_AST_INL_H

Types

typedef cs_ast_field_type
Definition typedef enum cs_ast_field_type cs_ast_field_type
Notes Used in cs_ast_field structs to indicate the type of the value stored in the field.
typedef cs_ast_enum_value
Definition typedef struct cs_ast_enum_value cs_ast_enum_value
Notes Structure for representing an element of an AST helper enumeration.
typedef cs_ast_field
Definition typedef struct cs_ast_field cs_ast_field
Notes Structure for representing a field of an abstract syntax tree.
typedef cs_ast_binding
Definition typedef struct cs_ast_binding cs_ast_binding
Notes A binding from one pattern variable to a cs_ast_field.

A list of these is returned by the pattern-matching function cs_ast_match().

typedef cs_ast_pattern
Definition typedef struct cs_ast_pattern cs_ast_pattern
Notes A pattern for matching against ASTs and fields.

Create with cs_ast_pattern_compile().

Used by cs_ast_match()

typedef cs_ast_traverse_flags
Definition typedef csuint32 cs_ast_traverse_flags
Notes Specifies what kind of traversal a cs_ast_traverse_iter will carry out.

Used by cs_ast_iter_first().

Values for cs_ast_traverse_flags are defined in an anonymous enum, which this documentation will refer to as anonymous_cs_ast_traverse_flags_enum.

typedef cs_ast_traverse_directives
Definition typedef csuint32 cs_ast_traverse_directives
Notes Specifies behavior at a given node in a traversal with a cs_ast_traverse_iter.

Only meaningful for preorder traversals.

Used by cs_ast_iter_next().

Values for cs_ast_traverse_directives are defined in an anonymous enum, which this documentation will refer to as anonymous_cs_ast_traverse_directives_enum.

typedef cs_ast_traverse_frame
Definition typedef struct cs_ast_traverse_frame cs_ast_traverse_frame
Notes Structure for managing the nodes yet to be visited in a cs_ast traversal.
typedef cs_ast_traverse_iter
Definition typedef struct cs_ast_traverse_iter cs_ast_traverse_iter
Notes An iterator over an abstract syntax tree.
enum anonymous_csac_ast_root_enum
Definition typedef enum {
csac_ast = = 0 The abstract superclass of all AST classes. All other classes must be implemented by language modules. Because this class is abstract, you will never encounter an instance of it.
} anonymous_csac_ast_root_enum
Notes This is an anonymous enumeration containing some values for cs_ast_class - the anonymous_csac_ast_root_enum label is provided only for ease of reference within this documentation.

CSAC = CodeSonar/CodeSurfer AST Class

enum anonymous_csaf_base_families_enum
Definition typedef enum {
csaf_default = = 0 Represents the first AST family, whatever it might be. Used as a default in the API if the user does not specify a particular family.
} anonymous_csaf_base_families_enum
Notes This is an anonymous enumeration: the anonymous_csaf_base_families_enum label is provided only for ease of reference within this documentation.
enum anonymous_csao_null_enum
Definition typedef enum {
csao_null = = 0
} anonymous_csao_null_enum
Notes This is an anonymous enumeration containing some values for cs_ast_ordinal - the anonymous_csao_null_enum label is provided only for ease of reference within this documentation.

Note that zero is a special-case AST ordinal and is not used to identify an AST field.

CSAO = CodeSonar/CodeSurfer AST Ordinal

enum cs_ast_field_type
Definition typedef enum {
csft_null , (This should never be observed.)
csft_ast , a cs_ast
csft_ast_class , No field in a cs_ast will have this type, but it may be used in patterns and bound by matching such patterns.
csft_boolean , a cs_boolean
csft_enumeration , an element of an AST helper enumeration, as a cs_ast_enum_value
csft_int8 , an 8-bit integer
csft_uint8 , an unsigned 8-bit integer
csft_int16 , a 16-bit integer
csft_uint16 , an unsigned 16-bit integer
csft_int32 , a 32-bit integer
csft_uint32 , an unsigned 32-bit integer
csft_int64 , a 64-bit integer
csft_uint64 , an unsigned 64-bit integer
csft_int128 , a 128-bit integer
csft_uint128 , an unsigned 128-bit integer
csft_flt32 , a 32-bit float
csft_flt64 , a 64-bit float
csft_flt96 , a 96-bit float (NOT CURRENTLY USED)
csft_flt128 , a 128-bit float (NOT CURRENTLY USED)
csft_const_str64 , a utf-8 encoded cs_const_string64
csft_const_str , a utf-8 encoded cs_const_string
csft_bytes , a cs_const_string64 representing unencoded data
csft_abs_loc , a cs_abs_loc
csft_sfid , a cs_sfid
csft_reserved , for internal use
csft_count (This should never be observed.)
} cs_ast_field_type
Notes Used in cs_ast_field structs to indicate the type of the value stored in the field.
enum anonymous_cs_ast_traverse_flags_enum
Definition typedef enum {
csatf_normal = = 0x0, Preorder, left-to-right traversal.
csatf_right_to_left = = 0x1, Right-to-left traversal.
csatf_postorder = = 0x2, Postorder traversal.
csatf_all = = 0x3
} anonymous_cs_ast_traverse_flags_enum
Notes This is an anonymous enumeration containing values for cs_ast_traverse_flags - the anonymous_cs_ast_traverse_flags_enum label is provided only for ease of reference within this documentation.
enum anonymous_cs_ast_traverse_directives_enum
Definition typedef enum {
csatd_normal = = 0x0, Continue traversal as specified.
csatd_skip_children = = 0x1, Skip the children of the current node, but continue with remainder of traversal.
csatd_all = = 0x1
} anonymous_cs_ast_traverse_directives_enum
Notes This is an anonymous enumeration containing values for cs_ast_traverse_directives - the anonymous_cs_ast_traverse_directives_enum label is provided only for ease of reference within this documentation.

On Separate Pages

struct cs_ast_enum_value
struct cs_ast_field
union cs_ast_field::cs_ast_field_variant
struct cs_ast_binding
struct cs_ast_traverse_iter

Functions

cs_result cs_ast_class_lookup ( cs_const_string class_name, cs_ast_class * out_ast_class )
Get the cs_ast_class with a specified name.
cs_result cs_ast_ordinal_lookup ( cs_const_string class_name, cs_ast_ordinal * out_ast_ordinal )
Get the cs_ast_ordinal with a specified name.
cs_result cs_ast_family_lookup ( cs_const_string family_name, cs_ast_family * out_ast_family )
Get the cs_ast_family with a specified name.
cs_result cs_ast_get_all_classes ( cs_ast_class * out_classes, cs_size_t capacity_bytes, cs_size_t * bytes_needed )
Get a list of all AST classes (cs_ast_class).
cs_result cs_ast_get_all_ordinals ( cs_ast_ordinal * out_ordinals, cs_size_t capacity_bytes, cs_size_t * bytes_needed )
Get a list of all AST ordinals (cs_ast_ordinal).
cs_result cs_ast_get_all_family_names ( cs_const_string * out_families, cs_size_t capacity_bytes, cs_size_t * bytes_needed )
Get a list of all names of AST families (cs_ast_family).
cs_ast_class cs_ast_class_superclass ( cs_ast_class sub )
Get the immediate superclass of a cs_ast_class.
cs_result cs_ast_get_field ( cs_ast ast, cs_ast_ordinal ord, cs_ast_field * out_field )
Get a specified field of a cs_ast.
cs_result cs_ast_children ( cs_ast ast, cs_ast_field * out_children, cs_size_t capacity_bytes, cs_size_t * bytes_needed )
Get all children of a cs_ast.
cs_result cs_ast_attributes ( cs_ast ast, cs_ast_field * out_attributes, cs_size_t capacity_bytes, cs_size_t * bytes_needed )
Get all attributes of a cs_ast.
cs_result cs_ast_fields ( cs_ast ast, cs_ast_field * out_fields, cs_size_t capacity_bytes, cs_size_t * bytes_needed )
Get all fields (that is, all children and all attributes) of a cs_ast.
cs_result cs_ast_fields_split ( cs_ast ast, cs_ast_field * out_fields, cs_size_t capacity_bytes, cs_size_t * bytes_needed, cs_size_t * children_bytes_needed )
Like cs_ast_fields(), but with an additional output parameter that allows the caller to distinguish children from attributes.
cs_result cs_ast_pretty_print ( cs_ast ast, cs_string out_string, cs_size_t capacity_bytes, cs_size_t * bytes_needed )
Get a pretty-printed version of a cs_ast.
cs_const_string cs_ast_dump ( cs_ast ast, cs_size_t attribute_depth )
Get an ASCII art tree rendering of a cs_ast.
cs_result cs_ast_create ( cs_ast * out_ast, cs_ast_class ast_class, cs_size_t num_fields, const cs_ast_field * ast_fields )
Create a new cs_ast with the specified fields.
cs_result cs_ast_close ( cs_ast ast )
Dispose of a cs_ast (but don't free any of its fields).
cs_const_string cs_ast_class_name ( cs_ast_class c )
Get a string representation of a cs_ast_class name.
cs_const_string cs_ast_ordinal_name ( cs_ast_ordinal ord )
Get a string representation of a cs_ast_ordinal.
cs_const_string cs_ast_field_type_name ( cs_ast_field_type ft )
Get a string representation of a cs_ast_field_type.
int cs_ast_compare ( cs_ast ast_a, cs_ast ast_b )
Compare two cs_ast objects, with consistent results across all analysis processes for a single analysis.
cs_hash_t cs_ast_hash ( cs_ast ast )
Get a hash value for a cs_ast.
int cs_ast_field_fast_compare ( cs_ast_field a, cs_ast_field b )
If the ast field is ast-typed, uses cs_ast_fast_compare.
int cs_ast_field_compare ( cs_ast_field a, cs_ast_field b )
Compare two cs_ast_field objects, with consistent results across all analysis processes for a single analysis.
cs_hash_t cs_ast_field_hash ( cs_ast_field f )
Get a hash value for a cs_ast_field.
cs_hash_t cs_ast_field_fast_hash ( cs_ast_field f )
If the ast field is ast-typed, uses cs_ast_fast_hash(), otherwise behaves just like cs_ast_field_hash().
int cs_ast_stable_compare ( cs_ast ast_a, cs_ast ast_b )
Compare two cs_ast values, with stable results across sufficiently-similar analyses.
int cs_ast_field_stable_compare ( cs_ast_field field_a, cs_ast_field field_b )
Compare two cs_ast_field values, with stable results across sufficiently-similar analyses.
cs_result cs_ast_pattern_compile ( cs_const_string pat_spec, cs_ast_pattern ** out_pat, cs_const_string * err, cs_const_string * err_location, ... )
Compile a cs_const_string representation into a cs_ast_pattern.
void cs_ast_pattern_incr ( cs_ast_pattern * pat )
Increment reference count of pat.
cs_result cs_ast_match ( cs_ast v, cs_ast_pattern * p, cs_ast_binding * out_bindings, cs_size_t capacity_bytes, cs_size_t * bytes_needed )
Check whether a cs_ast matches a specified cs_ast_pattern.
cs_result cs_ast_pattern_close ( cs_ast_pattern * p )
Dispose of a cs_ast_pattern.
cs_result cs_ast_iter_first ( cs_ast root_ast, cs_ast_traverse_flags trav_flags, cs_ast * ast, cs_ast_traverse_iter * iter )
Set up a cs_ast for traversal, retrieving the first cs_ast according to the traversal specified and opening a cs_ast_traverse_iter for the rest of the tree.
cs_result cs_ast_iter_next ( cs_ast_traverse_directives directives, cs_ast * ast, cs_ast_traverse_iter * iter )
Retrieve the next cs_ast from a cs_ast_traverse_iter.
cs_result cs_ast_iter_close ( cs_ast_traverse_iter * iter )
Close a cs_ast_traverse_iter iterator.
cs_result cs_ast_dig ( cs_ast ast, cs_ast_field * out_field, ... )
Quickly dig deep into an abstract syntax tree to recover a field.
const char * cs_ast_string ( cs_ast ast )
Get a pretty-printed version of a cs_ast.
cs_boolean cs_ast_class_is_subclass ( cs_ast_class sub, cs_ast_class sup )
Check: is one cs_ast_class a subclass of another?
cs_ast_class cs_ast_get_class ( cs_ast ast )
Get the cs_ast_class to which a cs_ast belongs.
cs_boolean cs_ast_is_a ( cs_ast ast, cs_ast_class cls )
Check: is a cs_ast an instance of the specified cs_ast_class?
int cs_ast_fast_compare ( cs_ast ast1, cs_ast ast2 )
Get the relative ordering of two cs_ast objects within the "fast AST compare" ordering.
cs_boolean cs_ast_equal ( cs_ast ast1, cs_ast ast2 )
Check: do two cs_ast objects refer to the very same node?
cs_hash_t cs_ast_fast_hash ( cs_ast ast )
Get a "fast hash" value for a cs_ast.
cs_boolean cs_ast_is_null ( cs_ast ast )
Check: is a cs_ast null?
cs_boolean cs_ast_field_equal ( cs_ast_field a, cs_ast_field b )
Check: do two cs_ast_field objects have the same type and value?
cs_boolean cs_ast_field_is_null ( cs_ast_field fld )
Check whether the type of a cs_ast_field is csft_null.

Function Descriptions

Function cs_ast_class_lookup
cs_result cs_ast_class_lookup (
Get the cs_ast_class with a specified name.
Parameters
class_name [in] The name of the cs_ast_class to retrieve.
out_ast_class [out] A user-allocated buffer to be populated with the retrieved cs_ast_class.
Returns A cs_result:
Function cs_ast_ordinal_lookup
cs_result cs_ast_ordinal_lookup (
Get the cs_ast_ordinal with a specified name.
Parameters
class_name [in] The name of the cs_ast_ordinal to retrieve.
out_ast_ordinal [out] A user-allocated buffer to be populated with the retrieved cs_ast_ordinal.
Returns A cs_result:
Function cs_ast_family_lookup
cs_result cs_ast_family_lookup (
Get the cs_ast_family with a specified name.
Parameters
family_name [in] The name of the cs_ast_family to retrieve (for example, 'normalized').
out_ast_family [out] A user-allocated buffer to be populated with the retrieved cs_ast_family.
Returns A cs_result:
Function cs_ast_get_all_classes
cs_result cs_ast_get_all_classes (
Get a list of all AST classes (cs_ast_class).
Parameters
out_classes [out] A user-allocated buffer to be populated with the retrieved AST classes (cs_ast_class).
capacity_bytes [in] The size of out_classes, in bytes.
bytes_needed [out] The number of bytes required to store all AST classes.
Returns A cs_result:
  • CS_SUCCESS if the full list of AST classes was successfully written to out_classes.
  • CS_TRUNCATED if out_classes was not large enough to hold the entire list (and so the list was truncated).
Notes This retrieves every class possible, even abstract ones.

Call this function with out_classes NULL and capacity_bytes 0 (zero) to determine the memory needed to hold all cs_ast_class values.

Function cs_ast_get_all_ordinals
cs_result cs_ast_get_all_ordinals (
Get a list of all AST ordinals (cs_ast_ordinal).
Parameters
out_ordinals [out] A user-allocated buffer to be populated with the retrieved AST ordinals (cs_ast_ordinal).
capacity_bytes [in] The size of out_ordinals, in bytes.
bytes_needed [out] The number of bytes required to store all AST ordinals.
Returns A cs_result:
  • CS_SUCCESS if the full list of AST ordinals was successfully written to out_ordinals.
  • CS_TRUNCATED if out_ordinals was not large enough to hold the entire list (and so the list was truncated).
Notes This retrieves every ordinal possible.

Call this function with out_ordinals NULL and capacity_bytes 0 (zero) to determine the memory needed to hold all cs_ast_ordinal values.

Function cs_ast_get_all_family_names
cs_result cs_ast_get_all_family_names (
Get a list of all names of AST families (cs_ast_family).
Parameters
out_families [out] A user-allocated buffer to be populated with the retrieved family names.
capacity_bytes [in] The size of out_families, in bytes.
bytes_needed [out] The number of bytes required to store all family names.
Returns A cs_result:
  • CS_SUCCESS if the full list of family names was successfully written to out_families.
  • CS_TRUNCATED if out_families was not large enough to hold the entire list (and so the list was truncated).
Notes This retrieves every family name possible.

Call this function with out_families NULL and capacity_bytes 0 (zero) to determine the memory needed to hold all cs_ast_family values.

Function cs_ast_class_superclass
cs_ast_class cs_ast_class_superclass (
Get the immediate superclass of a cs_ast_class.
Parameters
sub [in] The cs_ast_class whose immediate superclass is required.
Returns The cs_ast_class that is the immediate superclass of sub. If sub is at the top of the class inheritance tree, return sub.
Function cs_ast_get_field
cs_result cs_ast_get_field (
Get a specified field of a cs_ast.
Parameters
ast [in] The cs_ast from which to retrieve a field.
ord [in] A cs_ast_ordinal indicating the field to retrieve from ast.
out_field [out] A user-allocated buffer to be populated with the ord field of ast. On success, out_field->ordinal will match ord.
Returns A cs_result:
Function cs_ast_children
cs_result cs_ast_children (
Get all children of a cs_ast.
Parameters
ast [in] The cs_ast whose children are required.
out_children [out] A user-allocated buffer to be populated with the retrieved children. The order of the list is fixed (but arbitrary): two ASTs with the same set of child ordinals will have the same ordering.
capacity_bytes [in] The size of out_children, in bytes.
bytes_needed [out] The number of bytes required to store all children of ast.
Returns A cs_result:
  • CS_SUCCESS if the full list of children was successfully written to out_children.
  • CS_TRUNCATED if out_children was not large enough to hold the entire list (and so the list was truncated).
Notes Call this function with out_children NULL and capacity_bytes 0 (zero) to determine the memory needed to hold all children of ast.
Function cs_ast_attributes
cs_result cs_ast_attributes (
Get all attributes of a cs_ast.
Parameters
ast [in] The cs_ast whose attributes are required.
out_attributes [out] A user-allocated buffer to be populated with the retrieved attributes. The order of the list is fixed (but arbitrary): two ASTs with the same set of attribute ordinals will have the same ordering.
capacity_bytes [in] The size of out_attributes, in bytes.
bytes_needed [out] The number of bytes required to store all attributes of ast.
Returns A cs_result:
  • CS_SUCCESS if the full list of attributes was successfully written to out_attributes.
  • CS_TRUNCATED if out_attributes was not large enough to hold the entire list (and so the list was truncated).
Notes Call this function with out_attributes NULL and capacity_bytes 0 (zero) to determine the memory needed to hold all attributes of ast.
Function cs_ast_fields
cs_result cs_ast_fields (
Get all fields (that is, all children and all attributes) of a cs_ast.
Parameters
ast [in] The cs_ast whose children and attributes are required.
out_fields [out] A user-allocated buffer to be populated with the retrieved fields: all children, followed by all attributes. The order of the list is fixed (but arbitrary): two ASTs with the same set of field ordinals will have the same ordering.
capacity_bytes [in] The size of out_fields, in bytes.
bytes_needed [out] The number of bytes required to store all children and attributes of ast.
Returns A cs_result:
  • CS_SUCCESS if the full list of children and the full list of attributes were successfully written to out_fields.
  • CS_TRUNCATED if out_fields was not large enough to hold all the fields of ast (and so the list was truncated).
Notes Call this function with out_fields NULL and capacity_bytes 0 (zero) to determine the memory needed to hold all fields of ast.
Function cs_ast_fields_split
cs_result cs_ast_fields_split (
Like cs_ast_fields(), but with an additional output parameter that allows the caller to distinguish children from attributes.
Parameters
ast [in] The cs_ast whose children and attributes are required.
out_fields [out] A user-allocated buffer to be populated with the retrieved fields: all children, followed by all attributes. The order of the list is fixed (but arbitrary): two ASTs with the same set of field ordinals will have the same ordering.
capacity_bytes [in] The size of out_fields, in bytes.
bytes_needed [out] The number of bytes required to store all children and attributes of ast.
children_bytes_needed [out] The number of bytes required to store the children of ast. The caller can therefore assume that the first children_bytes_needed bytes of out_fields will be populated by children (as opposed to attributes).
Returns A cs_result, as for cs_ast_fields().
Notes Call this function with out_fields NULL and capacity_bytes 0 (zero) to determine the memory needed to hold all fields of ast.
Function cs_ast_pretty_print
cs_result cs_ast_pretty_print (
Get a pretty-printed version of a cs_ast.
Parameters
ast [in] The cs_ast of interest.
out_string [out] A user-allocated buffer to be populated with the pretty-printed version of ast.
capacity_bytes [in] The size of out_string, in bytes.
bytes_needed [inout] The number of bytes required to store the entire pretty-printed version of ast. If the user sets this to NULL, the function will write the pretty-printed version of ast to out_string (truncating it if necessary) but will not compute the bytes needed for the full string.
Returns A cs_result:
Notes Call this function with out_string NULL and capacity_bytes 0 (zero) to determine the memory needed to hold the pretty-printed version of ast.
Function cs_ast_dump
cs_const_string cs_ast_dump (
Get an ASCII art tree rendering of a cs_ast.
Parameters
ast [in] The cs_ast of interest.
attribute_depth [in] The maximum depth of attribute subtrees that will be displayed in the tree. Attributes can give rise to cycles, so attribute subtrees must have a bounded height in order to bound the size of the dump.
Returns A pointer to an internal buffer, which will remain valid until the next call to this function.
Function cs_ast_create
cs_result cs_ast_create (
Create a new cs_ast with the specified fields.
Parameters
out_ast [out] A user-allocated buffer to be populated with the newly-created cs_ast.
ast_class [in] The class for the new cs_ast.
num_fields [in] The number of fields the new cs_ast will have.
ast_fields [in] A list of fields for the new cs_ast. There should be num_fields entries in this list.
Returns A cs_result:
Function cs_ast_close
cs_result cs_ast_close (
Dispose of a cs_ast (but don't free any of its fields).
Parameters
ast [in] The cs_ast to dispose.
Returns A cs_result:
Function cs_ast_class_name
cs_const_string cs_ast_class_name (
Get a string representation of a cs_ast_class name.
Parameters
c [in] The cs_ast_class whose name is required.
Returns The name associated with c, as a cs_const_string.
Function cs_ast_ordinal_name
cs_const_string cs_ast_ordinal_name (
Get a string representation of a cs_ast_ordinal.
Parameters
ord [in] The cs_ast_ordinal whose name is required.
Returns if ord<0, (ie, corresponds to an enum symbol) the name associated with ord; otherwise NULL.
Function cs_ast_field_type_name
cs_const_string cs_ast_field_type_name (
Get a string representation of a cs_ast_field_type.
Parameters
ft [in] The cs_ast_field_type whose name is required.
Returns if ft corresponds to a valid field type, the name associated with ft; otherwise NULL.
Function cs_ast_compare
int cs_ast_compare (
Compare two cs_ast objects, with consistent results across all analysis processes for a single analysis.
Parameters
ast_a [in] First argument to comparison.
ast_b [in] Second argument to comparison.
Returns An integer N, such that:
  • N<0 if ast_a < ast_b
  • N==0 if ast_a and ast_b are the same cs_ast
  • N>0 if ast_a > ast_b
Notes This function is provided so cs_ast objects can be stored in ordered containers. It is not based on any user-perceivable ordering.

For fixed cs_ast values a and b in a single analysis, cs_ast_compare(a,b) will always return the same value. However, cs_ast_compare() will not necessarily return this same value when called on the corresponding cs_ast values a' and b' in a different analysis. Function cs_ast_stable_compare() provides some degree of stability across analyses, although restrictions still apply. If you do not need comparison results to be stable across different analyses, use cs_ast_compare() or cs_ast_fast_compare(): they have better performance.

  • cs_ast_compare() if you need comparison results to be consistent across all processes for a single analysis.
  • cs_ast_fast_compare() if you only need comparison results to be consistent within a single analysis process.
Function cs_ast_hash
cs_hash_t cs_ast_hash (
Get a hash value for a cs_ast.
Parameters
ast [in] The cs_ast for which to get the hash value.
Returns The hash value for ast, as a cs_hash_t.
Notes For fixed cs_ast a in a single analysis, cs_ast_hash(a) will always return the same value. However, cs_ast_hash() will not necessarily return this same value when called on the corresponding cs_ast value a' in a different analysis.

If you only need hash values to be consistent within a single analysis process (not across different processes in the same analysis), you can use cs_ast_fast_hash().

Function cs_ast_field_fast_compare
int cs_ast_field_fast_compare (
If the ast field is ast-typed, uses cs_ast_fast_compare.
Notes Otherwise behaves just like cs_ast_field_compare.
Function cs_ast_field_compare
int cs_ast_field_compare (
Compare two cs_ast_field objects, with consistent results across all analysis processes for a single analysis.
Notes The ordinals, types, and payloads get compared.
Function cs_ast_field_hash
cs_hash_t cs_ast_field_hash (
Get a hash value for a cs_ast_field.
Function cs_ast_field_fast_hash
cs_hash_t cs_ast_field_fast_hash (
If the ast field is ast-typed, uses cs_ast_fast_hash(), otherwise behaves just like cs_ast_field_hash().
Function cs_ast_stable_compare
int cs_ast_stable_compare (
Compare two cs_ast values, with stable results across sufficiently-similar analyses.
Parameters
ast_a [in] First argument to comparison.
ast_b [in] Second argument to comparison.
Returns An integer N, such that:
  • N<0 if ast_a considered less than ast_b
  • N==0 if ast_a and ast_b are the same cs_ast
  • N>0 if ast_a considered greater than ast_b
Time-Complexity O(s) where s is the sum of the number of transitive children and attributes in ast_a and ast_b and the sum of the lengths of strings that are transitively children or attributes of either ast. It can be the total number of nodes in the two compilations in the worst case.
Notes The comparison is stable in the following sense. Suppose there are two analyses A1 and A2 generated with exactly the same inputs (including identical analyzed code, underlying build commands and ordering, command line and configuration settings, increment order and contents). Let a1 and b1 be two cs_ast values in A1, and a2 and b2 be the cs_ast values in A2 that correspond to a1 and b1 respectively. Then cs_ast_stable_compare(a1,b1)==cs_ast_stable_compare(a2,b2).

If you do not need comparison results to be stable across different analyses, use one of the following: they have better performance.

  • cs_ast_compare() if you need comparison results to be consistent across all processes for a single analysis.
  • cs_ast_fast_compare() if you only need comparison results to be consistent within a single analysis process.
Function cs_ast_field_stable_compare
int cs_ast_field_stable_compare (
Compare two cs_ast_field values, with stable results across sufficiently-similar analyses.
Parameters
field_a [in] First argument to comparison.
field_b [in] Second argument to comparison.
Returns An integer N, such that:
  • N<0 if field_a considered less than field_b
  • N==0 if field_a considered equal to field_b
  • N>0 if field_a considered greater than field_b
Time-Complexity O(s) where s is the sum of the number of transitive children and attributes in field_a and field_b and the sum of the lengths of strings that are transitively children or attributes of either AST.
Notes The comparison is stable in the following sense. Suppose there are two analyses A1 and A2 generated with exactly the same inputs (including identical analyzed code, underlying build commands and ordering, command line and configuration settings, increment order and contents). Let a1 and b1 be two cs_ast_field values in A1, and a2 and b2 be the cs_ast_field values in A2 that correspond to a1 and b1 respectively. Then cs_ast_field_stable_compare(a1,b1)==cs_ast_field_stable_compare(a2,b2).
Function cs_ast_pattern_compile
cs_result cs_ast_pattern_compile (
Compile a cs_const_string representation into a cs_ast_pattern.
Parameters
pat_spec [in] A cs_const_string specification of the desired pattern.
out_pat [out] On success, will be populated with the newly created cs_ast_pattern.
err [out] On failure, will be populated with an error message about a problem encountered in creating the pattern.
err_location [out] On failure, will be populated with a pointer into pat_spec indicating the location of the problem described by err.
... [in] fp0, ctx0, fp1, ctx1, ... ( used when the pattern includes one or more closures)
  • fp is a function pointer of type cs_boolean *(const cs_ast_field *, void *)
  • ctx is a void*
Returns A cs_result:
Notes For more information, see AST Patterns.
Function cs_ast_pattern_incr
void cs_ast_pattern_incr (
Increment reference count of pat.
Parameters
pat [inout] Pattern whose reference count should be incremented.
Notes cs_ast_pattern_close() will only free the pattern when the reference count reaches 0. Freshly compiled patterns have a reference count of 1.
Function cs_ast_match
cs_result cs_ast_match (
Check whether a cs_ast matches a specified cs_ast_pattern.
Parameters
v [in] The cs_ast to be checked.
p [in] The cs_ast_pattern to be compared with v.
out_bindings [out] A user-allocated buffer to be populated with the bindings generated in matching v against p. Bindings are in order of first occurrence, even if unbound (in which case the .f.type field of the binding will be set to csft_null).
capacity_bytes [in] The size of out_bindings, in bytes.
bytes_needed [out] The number of bytes required to store all the bindings (cs_ast_binding) associated with the matching of p and v.
Returns A cs_result:
Notes Call this function with out_bindings NULL and capacity_bytes 0 (zero) to determine
  • whether p is valid and matches v, and
  • if so, the memory needed to hold the full set of bindings associated with the matching.
Function cs_ast_pattern_close
cs_result cs_ast_pattern_close (
Dispose of a cs_ast_pattern.
Parameters
p [inout] The cs_ast_pattern to be disposed.
Returns CS_SUCCESS on success.
Function cs_ast_iter_first
cs_result cs_ast_iter_first (
Set up a cs_ast for traversal, retrieving the first cs_ast according to the traversal specified and opening a cs_ast_traverse_iter for the rest of the tree.
Parameters
root_ast [in] The root cs_ast of the tree that is to be traversed.
trav_flags [in] Specifies the order in which iter will traverse the tree.
ast [out] The first (according to the order specified by trav_flags) cs_ast in the traversal from root_ast.
iter [out] An iterator for the tree.
Returns A cs_result:
Notes Retrieve the first cs_ast from the tree rooted at root_ast. This function opens iter, which is required by cs_ast_iter_next(). Use cs_ast_iter_close() to close iter.
Function cs_ast_iter_next
cs_result cs_ast_iter_next (
Retrieve the next cs_ast from a cs_ast_traverse_iter.
Parameters
directives [in] Specifies whether or not the children of the most-recently-returned cs_ast should be included in the traversal.
ast [out] The next cs_ast.
iter [inout] The cs_ast_traverse_iter from which to retrieve ast.
Returns A cs_result:
Notes Retrieve the next cs_ast from a cs_ast_traverse_iter. If iter is at the end of its iteration, it is closed.
Function cs_ast_iter_close
cs_result cs_ast_iter_close (
Close a cs_ast_traverse_iter iterator.
Parameters
iter [out] The cs_ast_traverse_iter to be closed.
Returns CS_SUCCESS on success.
Function cs_ast_dig
cs_result cs_ast_dig (
Quickly dig deep into an abstract syntax tree to recover a field.
Parameters
ast [in] The cs_ast.
out_field [out] The recovered cs_ast_field.
... [in] Zero or more AST ordinals (cs_ast_ordinal), terminated by csao_null.
Returns A cs_result:
Notes On success, out_field is set as follows:
  • If there are no cs_ast_ordinal arguments, out_field will be a wrapper around ast.
  • If there is one cs_ast_ordinal argument, out_field will be the field of ast specified by that ordinal.
  • If there are multiple cs_ast_ordinal arguments, each ordinal is applied to the cs_ast obtained by applying the previous ordinals: cs_ast_dig(a,&f,x,y,...) is equivalent to cs_ast_dig(a,&f,x); cs_ast_dig(f._.ast,&f,y,...) (assuming both succeed).

For example, suppose ast1 is a c:= AST representing the statement a = b + c. Then to retrieve the AST for c (by wrapping it in c_field), you could call: 

cs_ast_dig(ast1, &c_field, 2, 2, csao_null)
Function cs_ast_string
const char * cs_ast_string (
Get a pretty-printed version of a cs_ast.
Parameters
ast [in] The cs_ast of interest.
Returns A pointer to a buffer containing a pretty-printed version of ast (as a char*). The buffer is only valid until another API function is invoked.
Notes Do not modify or free the returned buffer.

This function entails less user overhead than cs_ast_pretty_print(), and so can be more convenient to use; the tradeoff is that the returned value is not under user control and has a constrained lifetime.

Function cs_ast_class_is_subclass
cs_boolean cs_ast_class_is_subclass (
Check: is one cs_ast_class a subclass of another?
Parameters
sub [in] The proposed subclass.
sup [in] The proposed superclass.
Returns cs_true if sub is a subclass of sup, cs_false otherwise. The subclass relationship is transitive and reflexive
Function cs_ast_get_class
cs_ast_class cs_ast_get_class (
Get the cs_ast_class to which a cs_ast belongs.
Parameters
ast [in] The cs_ast whose class is required.
Returns The most specific cs_ast_class to which ast belongs.
Function cs_ast_is_a
cs_boolean cs_ast_is_a (
Check: is a cs_ast an instance of the specified cs_ast_class?
Parameters
ast [in] The cs_ast whose class membership is being checked.
cls [in] The cs_ast_class.
Returns cs_true if ast is an instance of cls, or of a subclass of cls, cs_false otherwise.
Function cs_ast_fast_compare
int cs_ast_fast_compare (
Get the relative ordering of two cs_ast objects within the "fast AST compare" ordering.
Parameters
ast1 [in] The left-hand cs_ast in the comparison.
ast2 [in] The right-hand cs_ast in the comparison.
Returns An integer N, such that:
  • N<0 if ast1 < ast2
  • N==0 if ast1 and ast2 are the same cs_ast
  • N>0 if ast1 > ast2
Notes The "fast AST compare" ordering is a total ordering over cs_ast objects that is provided for performance only. It is not stable from process to process, even on the same (ie, not rebuilt) project.
Function cs_ast_equal
cs_boolean cs_ast_equal (
Check: do two cs_ast objects refer to the very same node?
Parameters
ast1 [in] The first cs_ast.
ast2 [in] The second cs_ast.
Returns cs_true if ast1 and ast2 refer to the very same node, cs_false otherwise.
Function cs_ast_fast_hash
cs_hash_t cs_ast_fast_hash (
Get a "fast hash" value for a cs_ast.
Parameters
ast [in] The cs_ast for which to get the hash value.
Returns The hash value for ast, as a cs_hash_t.
Notes The "fast-hash" function on cs_ast is provided for performance only. It is not stable from process to process, even on the same (ie, not rebuilt) project. For consistent results across all processes for a single analysis, use cs_ast_hash().
Function cs_ast_is_null
cs_boolean cs_ast_is_null (
Check: is a cs_ast null?
Parameters
ast [in] The cs_ast to check.
Returns cs_true if ast is null, cs_false otherwise.
Function cs_ast_field_equal
cs_boolean cs_ast_field_equal (
Check: do two cs_ast_field objects have the same type and value?
Parameters
a [in] The first cs_ast_field.
b [in] The second cs_ast_field.
Returns cs_true if a and b have the same type and value, cs_false otherwise.
Notes If both arguments are csft_ast typed, then returns the same value as cs_ast_equal().
Function cs_ast_field_is_null
cs_boolean cs_ast_field_is_null (
Check whether the type of a cs_ast_field is csft_null.