C and C++ Binaries

Cross-Referencing: cs_xref.h

Defines operations for cross-referencing.

Links

Defines

#define CS_XREF_H

Types

typedef cs_xref_occ_iter_flags
Definition typedef csuint32 cs_xref_occ_iter_flags
Notes Flags for setting up a cs_xref_occ_iter iterator.

Used by cs_xref_occ_iter_first().

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

typedef cs_xref_def_iter_flags
Definition typedef csuint32 cs_xref_def_iter_flags
Notes Flags for setting up a cs_xref_def_iter iterator.

Used by cs_xref_def_iter_first()

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

typedef cs_xref_def_iter
Definition typedef struct __cs_xref_def_iter cs_xref_def_iter
Notes An iterator over the definitions of a token.

Used by:

API clients should never directly access the fields of this type. This is only exported so that clients may stack allocate these things. Future versions of the API reserve the right to change the definition of this iterator type.

typedef cs_xref_occ_iter
Definition typedef struct __cs_xref_occ_iter cs_xref_occ_iter
Notes An iterator over the occurrences of a token.

Used by:

API clients should never directly access the fields of this type. This is only exported so that clients may stack allocate these things. Future versions of the API reserve the right to change the definition of this iterator type.

typedef cs_xref_intra_def_iter
Definition typedef struct __cs_xref_intra_def_iter cs_xref_intra_def_iter
Notes An iterator over the definitions of a token in a single compilation unit.

Used by:

API clients should never directly access the fields of this type. This is only exported so that clients may stack allocate these things. Future versions of the API reserve the right to change the definition of this iterator type.

typedef cs_xref_file_query
Definition typedef struct __cs_xref_file_query cs_xref_file_query
Notes Included in a cs_xref_query to specify which files to consider.

When constructing a cs_xref_file_query, memset it to 0 initially before setting the individual fields.

typedef cs_xref_query_iterator_fn_t
Definition typedef cs_result(* cs_xref_query_iterator_fn_t)(const cs_xref_tuple *t, void *ctx)
Notes Will be invoked on every tuple that matches the query.

Parameters:

Returns a cs_result

  • On success, return CS_SUCCESS.
  • On failure, return an appropriate cs_result (in particular, not CS_SUCCESS) to help you diagnose any problems that occur.
typedef cs_xref_query_cmp_fn_t
Definition typedef int(* cs_xref_query_cmp_fn_t)(const cs_xref_tuple *a, const cs_xref_tuple *b, void *ctx)
Notes Comparison function to be used for sorting the results from executing a cs_xref_query.

Parameters:

  • a The first argument to the comparison.
  • b The second argument to the comparison.
  • ctx The contextual information associated with the query (cs_xref_query.ctx), if any.

Returns an integer x, such that:

  • x<0 if a should appear before b in the results,
  • x==0 if a and b can appear in either order,
  • x>0 if b should appear before a.
typedef cs_xref_query_flags
Definition typedef csuint32 cs_xref_query_flags
Notes Flags for specifying properties of a cs_xref_query.

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

typedef cs_xref_query
Definition typedef struct __cs_xref_query cs_xref_query
Notes Fully specifies a query over the tokens in an analyzed project.
typedef cs_xref_query_iter
Definition typedef struct __cs_xref_query_iter cs_xref_query_iter
Notes A iterator over the results of a cs_xref_query.

Used by:

API clients should never directly access the fields of this type. This is only exported so that clients may stack allocate these things. Future versions of the API reserve the right to change the definition of this iterator type.

enum anonymous_cs_xref_occ_iter_flags_enum
Definition typedef enum {
csxroif_none = = 0x0, Null flag.
csxroif_drop_libmodel_defs = = 0x1, If an occurrence's associated definition is in a library model, don't include the occurrence in the iteration.
csxroif_drop_libmodel_occs = = 0x2, If an occurrence is in a library model, don't include it in the iteration.
csxroif_dontcare_complete = = 0x4, If two tuples differ only in completeness, only one of the two will be returned.
csxroif_dontcare_def_or_complete = = 0x8|csxroif_dontcare_complete, If two tuples differ only in def_sf, def_line, or completeness, only one of the two will be returned.
csxroif_populate_counters = = 0x10, Ignored by the C API. Reserved for use by the C++ API.
csxroif_all = = 0x1f
} anonymous_cs_xref_occ_iter_flags_enum
Notes This is an anonymous enumeration containing values for cs_xref_occ_iter_flags - the anonymous_cs_xref_occ_iter_flags_enum label is provided only for ease of reference within this documentation.
enum anonymous_cs_xref_def_iter_flags_enum
Definition typedef enum {
csxrdif_none = = 0x0, Null flag.
csxrdif_drop_libmodel_defs = = 0x1, If a definition is in a library model, don't include it in the iteration.
csxrdif_all = = 0x1
} anonymous_cs_xref_def_iter_flags_enum
Notes This is an anonymous enumeration containing values for cs_xref_def_iter_flags - the anonymous_cs_xref_def_iter_flags_enum label is provided only for ease of reference within this documentation.
enum anonymous_cs_xref_query_flags_enum
Definition typedef enum {
csxrqf_none = = 0x0, Null flag.
csxrqf_uniquify = = 0x1, Specifies whether and how the query will perform 'uniquification' on its result set.

Behavior depends on whether or not the cs_xref_query Q includes a non-null cmp field.

  • If Q.cmp is NULL:
    • If csxrqf_uniquify is specified, the query will return only unique tuples. (That is, if the raw result set contains a subset of tuples that are identical across all values, all but one of those tuples will be removed before returning the set.)
    • If csxrqf_uniquify is not specified, no uniquification is performed.
  • If Q.cmp is non-NULL:
    • If csxrqf_uniquify is specified, the query will perform uniquification with respect to Q.cmp: if the raw result set contains a subset of tuples that all compare equal according to Q.cmp, all but one of those tuples will be removed before returning the set.)
    • If csxrqf_uniquify is not specified, the query will perform uniquification with respect to complete tuple uniqueness (that is, the same unquification strategy as used when Q.cmp is NULL and csxrqf_uniquify is specified).
csxrqf_populate_counters = = 0x2, Populate the .scanned and .unscanned fields of the "counters" argument when the query is executed with cs_xref_query_execute (the .matched field is always populated).

Do not set this flag (or csxrqf_all) if you are specifying a NULL "counters" argument.

csxrqf_all = = 0x3
} anonymous_cs_xref_query_flags_enum
Notes This is an anonymous enumeration containing values for cs_xref_query_flags - the anonymous_cs_xref_query_flags_enum label is provided only for ease of reference within this documentation.

On Separate Pages

struct __cs_xref_def_iter
struct __cs_xref_occ_iter
struct __cs_xref_intra_def_iter
struct __cs_xref_file_query
struct __cs_xref_query
struct __cs_xref_query_iter

Functions

cs_xr_kind cs_xr_kind_lookup ( cs_const_string kname )
Get the cs_xr_kind object with the specified name.
cs_xr_role cs_xr_role_lookup ( cs_const_string rname )
Get the cs_xr_role object with the specified name.
cs_xr_kind_role cs_xr_kind_role_lookup ( cs_const_string krname )
Get the cs_xr_role object with the specified name.
cs_result cs_xref_def_iter_first ( cs_sf sf, cs_line fline, csuint64 namehash, cs_xref_def_iter_flags flags, cs_xref_tuple * t, cs_xref_def_iter * iter )
Given an occurrence of a token, set up an iterator over definitions of that entity and retrieve the first item from the iterator.
cs_result cs_xref_def_iter_next ( cs_xref_tuple * t, cs_xref_def_iter * iter )
Retrieve the next definition from a cs_xref_def_iter iterator.
cs_result cs_xref_def_iter_close ( cs_xref_def_iter * iter )
Close a cs_xref_def_iter object.
cs_result cs_xref_occ_iter_first ( cs_sf occ_sf, cs_line occ_line, csuint64 namehash, cs_xr_kind_role kr_filter, cs_size_t limit_per_kind_role, cs_xref_occ_iter_flags iter_flags, cs_xref_tuple * t, cs_xref_occ_iter * iter, cs_xref_result_counters * iter_counters, cs_xref_occ_iter * homonym_iter, cs_xref_result_counters * homonym_iter_counters )
Given a token occurrence: set up an iterator over all occurrences of the corresponding source entity, or over all occurrences of the entity in a specific kind/role, and retrieve the first item from the iterator.
cs_result cs_xref_occ_iter_next ( cs_xref_tuple * t, cs_xref_occ_iter * iter )
Retrieve the next occurrence from a cs_xref_occ_iter iterator.
cs_result cs_xref_occ_iter_close ( cs_xref_occ_iter * iter )
Close a cs_xref_occ_iter object.
cs_result cs_xref_intra_def_iter_first ( cs_sf sf, cs_line line_lb, cs_line line_ub, cs_xref_tuple * t, cs_xref_intra_def_iter * iter )
Given a code region, set up an iterator over the definitions - in the same compilation unit - of all source entities with occurrences in that region, and retrieve the first definition from the iterator.
cs_result cs_xref_intra_def_iter_next ( cs_xref_tuple * t, cs_xref_intra_def_iter * iter )
Retrieve the next definition from a cs_xref_intra_def_iter iterator.
cs_result cs_xref_intra_def_iter_close ( cs_xref_intra_def_iter * iter )
Close a cs_xref_intra_def_iter object.
cs_result cs_xref_query_execute ( const cs_xref_query * csq, cs_xref_result_counters * counters )
Execute a cs_xref_query.
cs_result cs_xref_query_iter_first ( const cs_xref_query * csq, cs_xref_tuple * t, cs_xref_query_iter * iter )
Set up an iterator over the results of a cs_xref_query, and retrieve the first cs_xref_tuple in the result set.
cs_result cs_xref_query_iter_next ( cs_xref_tuple * t, cs_xref_query_iter * iter )
Retrieve the next cs_xref_tuple from a cs_xref_query_iter.
cs_result cs_xref_query_iter_close ( cs_xref_query_iter * iter )
Close a cs_xref_query_iter iterator.
cs_result cs_xref_tuple_token ( const cs_xref_tuple * t, cs_string out_string, cs_size_t capacity_bytes, cs_size_t * bytes_needed )
Get the source token corresponding to the specified cs_xref_tuple.

Function Descriptions

Function cs_xr_kind_lookup
cs_xr_kind cs_xr_kind_lookup (
Get the cs_xr_kind object with the specified name.
Parameters
kname [in] The name of a token kind, as a cs_const_string.
Returns The cs_xr_kind whose name is kname. Returns csxrk_count if kname does not correspond to a valid cs_xr_kind.
Function cs_xr_role_lookup
cs_xr_role cs_xr_role_lookup (
Get the cs_xr_role object with the specified name.
Parameters
rname [in] The name of a token role, as a cs_const_string.
Returns The cs_xr_role whose name is rname. Returns csxrr_count if rname does not correspond to a valid cs_xr_role.
Function cs_xr_kind_role_lookup
cs_xr_kind_role cs_xr_kind_role_lookup (
Get the cs_xr_role object with the specified name.
Parameters
krname [in] The name of a token kind-role pair, as a cs_const_string.
Returns The cs_xr_kind_role whose name is krname. Returns csxrkr_count if krname does not correspond to a valid cs_xr_kind_role.
Function cs_xref_def_iter_first
cs_result cs_xref_def_iter_first (
Given an occurrence of a token, set up an iterator over definitions of that entity and retrieve the first item from the iterator.
Parameters
sf [in] The source file containing the occurrence.
fline [in] The line containing the occurrence.
namehash [in] The token name hash, as given by cs_xref_namehash(). Note that when this is compared against hashed procedure names, the procedure basename as retrieved by cs_procedure_basename() is used.
flags [in] Specify desired properties for the iterator.
t [out] The first token definition retrieved by the iterator, as a cs_xref_tuple.
iter [out] An iterator to traverse the definitions of the token.
Returns A cs_result:
Function cs_xref_def_iter_next
cs_result cs_xref_def_iter_next (
Retrieve the next definition from a cs_xref_def_iter iterator.
Parameters
t [out] The next definition, as a cs_xref_tuple.
iter [inout] The iterator from which to retrieve t.
Returns A cs_result:
Function cs_xref_def_iter_close
cs_result cs_xref_def_iter_close (
Close a cs_xref_def_iter object.
Parameters
iter [in] The iterator to be closed.
Returns CS_SUCCESS on success.
Function cs_xref_occ_iter_first
cs_result cs_xref_occ_iter_first (
Given a token occurrence: set up an iterator over all occurrences of the corresponding source entity, or over all occurrences of the entity in a specific kind/role, and retrieve the first item from the iterator.
Parameters
occ_sf [in] The source file containing the token occurrence.
occ_line [in] The line in occ_sf containing the token occurrence.
namehash [in] Hash of the token name - see cs_xref_namehash() for details. Note that when this is compared against hashed procedure names, the procedure basename as retrieved by cs_procedure_basename() is used.
kr_filter [in] The iteration will be restricted to occurrences in this kind/role. Set to csxrkr_count to cover all kind/roles.
limit_per_kind_role [in] The iteration will cover at most this many occurrences for each kind/role specified by kr_filter (that is, either one kind/role or all the kind/roles the entity occurs in). Set to 0 if no limit is wanted.
iter_flags [in] Flags for setting up the iterator.
t [out] The first occurrence retrieved from iter.
iter [out] An iterator over the source entity occurrences, subject to the restrictions imposed by kr_filter, limit_per_kind_role, and iter_flags.
iter_counters [out] Tuple counts from retrieving the set of tuples to be iterated over by iter. Note that this set is retrieved as part of the initialization of iter: the counts do not depend on the operations subsequently carried out on iter. Can be NULL if you are not interested in the counts.
homonym_iter [out] If non-NULL, then homonym_iter can be used to iterate over occurrences of other source entities with the same name. The homonym_iter iterator is also set up using limit_per_kind_role and iter_flags, but will cover all kind/roles regardless of the setting of kr_filter. Set to NULL if no other iterator is required.
homonym_iter_counters [out] Tuple counts from retrieving the set of tuples to be iterated over by homonym_iter. Note that this set is retrieved as part of the initialization of homonym_iter: the counts do not depend on the operations subsequently carried out on homonym_iter. Can be NULL if you are not interested in the counts. Even if non-NULL, will not be populated if homonym_iter is NULL.
Returns A cs_result:
Function cs_xref_occ_iter_next
cs_result cs_xref_occ_iter_next (
Retrieve the next occurrence from a cs_xref_occ_iter iterator.
Parameters
t [out] The next occurrence, as a cs_xref_tuple.
iter [inout] The iterator from which to retrieve t.
Returns A cs_result:
Function cs_xref_occ_iter_close
cs_result cs_xref_occ_iter_close (
Close a cs_xref_occ_iter object.
Parameters
iter [in] The iterator to be closed.
Returns CS_SUCCESS on success.
Function cs_xref_intra_def_iter_first
cs_result cs_xref_intra_def_iter_first (
Given a code region, set up an iterator over the definitions - in the same compilation unit - of all source entities with occurrences in that region, and retrieve the first definition from the iterator.
Parameters
sf [in] The source file containing the code region.
line_lb [in] The lowest-numbered line in sf that is contained in the code region.
line_ub [in] The highest-numbered line in sf that is contained in the code region.
t [out] The first definition retrieved from iter.
iter [out] An iterator over definitions that:
  • are located in the same compilation unit as sf, and
  • define one of the source entities occurring in the specified code region.
Returns A cs_result:
Function cs_xref_intra_def_iter_next
cs_result cs_xref_intra_def_iter_next (
Retrieve the next definition from a cs_xref_intra_def_iter iterator.
Parameters
t [out] The next occurrence, as a cs_xref_tuple.
iter [inout] The iterator from which to retrieve t.
Returns A cs_result:
Function cs_xref_intra_def_iter_close
cs_result cs_xref_intra_def_iter_close (
Close a cs_xref_intra_def_iter object.
Parameters
iter [in] The iterator to be closed.
Returns CS_SUCCESS on success.
Function cs_xref_query_execute
cs_result cs_xref_query_execute (
Execute a cs_xref_query.
Parameters
csq [in] The cs_xref_query to be executed.
counters [out] Tuple counts from executing csq. Can be NULL if you are not interested in these counts: do not set csq.flags to csxrqf_populate_counters or csxrqf_all in this case.
Returns A cs_result:
  • if csq.iterate returns some R != CS_SUCCESS on a tuple in the query result set, this function also returns R.
  • Otherwise, returns CS_SUCCESS on successful completion.
Notes The query specified by csq is executed, and counters is populated accordingly.

Once the set of query results has been obtained, callback function csq.iterate is applied to each tuple in the result set, in the order specified by csq.cmp. If it returns a non-CS_SUCCESS result R on any tuple, the iteration halts and this function returns R.

Function cs_xref_query_iter_first
cs_result cs_xref_query_iter_first (
Set up an iterator over the results of a cs_xref_query, and retrieve the first cs_xref_tuple in the result set.
Parameters
csq [in] The cs_xref_query whose results are to be iterated over.
t [out] The first cs_xref_tuple in the result set for csq.
iter [out] An iterator over the result set for csq.
Returns A cs_result:
Notes Note that csq.iterate is is not used when iterating over the csq result set with these cs_xref_query_iter iteration functions.
Function cs_xref_query_iter_next
cs_result cs_xref_query_iter_next (
Retrieve the next cs_xref_tuple from a cs_xref_query_iter.
Parameters
t [out] The next cs_xref_tuple in the result set.
iter [inout] The iterator from which to retrieve t.
Returns A cs_result:
Function cs_xref_query_iter_close
cs_result cs_xref_query_iter_close (
Close a cs_xref_query_iter iterator.
Parameters
iter [out] The iterator to be closed.
Returns CS_SUCCESS on success.
Function cs_xref_tuple_token
cs_result cs_xref_tuple_token (
Get the source token corresponding to the specified cs_xref_tuple.
Parameters
t [in] The tuple of interest.
out_string [out] A user-allocated buffer to be populated with the retrieved token.
capacity_bytes [in] The size of out_string, in bytes.
bytes_needed [out] The number of bytes required to store the entire token, including null terminator.
Returns A cs_result:
  • CS_SUCCESS if the full token was written to out_string.
  • CS_TRUNCATED if out_string was not large enough to hold the entire token (and so the token was truncated).
  • CS_ELEMENT_NOT_PRESENT if no source token corresponding to t could be found.
Notes A procedure name token is the procedure basename as returned by cs_pdg_basename().

Call this function with out_string NULL and capacity_bytes 0 (zero) to determine the memory needed to hold the retrieved token.