C and C++ Binaries

Directory Operations: cs_directory.h

Defines a set of cs_directory operations for CodeSonar.

Links

Defines

#define CS_DIRECTORY_H
#define CS_DIRECTORY_NULL (cs_directory_get_null()) The null cs_directory.
#define CS_DIRECTORY_INL_H

Functions

cs_result cs_directory_root_directory_iter_first ( cs_directory * dir, cs_directory_root_directory_iter * itr )
Open a cs_directory_root_directory_iter for traversing the set of root directories deduced by inspecting all source file paths in the project, and retrieve the first root cs_directory.
cs_result cs_directory_root_directory_iter_next ( cs_directory * dir, cs_directory_root_directory_iter * itr )
Advance the provided cs_directory_root_directory_iter and retrieve the next root directory.
cs_result cs_directory_root_directory_iter_close ( cs_directory_root_directory_iter * itr )
Close a cs_directory_root_directory_iter iterator.
cs_result cs_directory_child_directory_iter_first ( const cs_directory parent_dir, cs_directory * child_dir, cs_directory_child_directory_iter * itr )
Open a cs_directory_child_directory_iter for traversing the immediate subdirectories of the specified parent, and retrieve the first child directory.
cs_result cs_directory_child_directory_count ( cs_directory dir, cs_size_t * count )
Get the number of subdirectories in a directory.
cs_result cs_directory_root_directory_count ( cs_size_t * count )
Get the number of root directories in the project.
cs_result cs_directory_file_count ( const cs_directory dir, cs_size_t * count )
Get the number of files in a directory.
cs_result cs_directory_child_directory_iter_next ( cs_directory * dir, cs_directory_child_directory_iter * itr )
Advance the provided cs_directory_child_directory_iter and retrieve the next child directory.
cs_result cs_directory_child_directory_iter_close ( cs_directory_child_directory_iter * itr )
Close a cs_directory_child_directory_iter iterator.
cs_result cs_directory_file_iter_first ( const cs_directory dir, cs_sf * sf, cs_directory_file_iter * itr )
Open a cs_directory_file_iter for traversing the source files immediately contained in a directory, and retrieve the first file.
cs_result cs_directory_file_iter_next ( cs_sf * sf, cs_directory_file_iter * itr )
Advance the provided cs_directory_file_iter and retrieve the next file.
cs_result cs_directory_file_iter_close ( cs_directory_file_iter * itr )
Close a cs_directory_file_iter iterator.
cs_result cs_directory_parent ( cs_directory dir, cs_directory * parent_dir )
Retrive the parent cs_directory of a cs_directory.
cs_result cs_directory_depth ( cs_directory dir, csuint32 * depth_out )
Get the depth or distance from root of a cs_directory.
cs_result cs_directory_normalized_path ( cs_directory dir, cs_file_path dirpath, cs_size_t capacity_bytes, cs_size_t * bytes_needed )
Retrieve the normalized version of the full path for the specified cs_directory.
cs_result cs_directory_path ( cs_directory dir, cs_file_path dirpath, cs_size_t capacity_bytes, cs_size_t * bytes_needed )
Retrieve the full path for the cs_directory.
const char * cs_directory_normalized_string ( cs_directory dir )
Get the normalized directory path associated with a cs_directory.
const char * cs_directory_string ( cs_directory dir )
Get the directory path associated with a cs_directory.
cs_hash_t cs_directory_stable_hash ( cs_directory dir )
Get a hash value for a cs_directory, with stable results across sufficiently-similar analyses.
int cs_directory_stable_compare ( cs_directory dir_a, cs_directory dir_b )
Compare two cs_directory objects, with stable results across sufficiently-similar analyses.
cs_boolean cs_directory_equal ( cs_directory dir1, cs_directory dir2 )
Check: are two cs_directory values equal?
int cs_directory_compare ( cs_directory dir_a, cs_directory dir_b )
Compare two cs_directory objects.
cs_hash_t cs_directory_hash ( cs_directory dir )
Hash function for cs_directory.
cs_boolean cs_directory_is_null ( cs_directory dir )
Determine whether a cs_directory is null.
cs_directory cs_directory_get_null ( )
Return a null cs_directory.

Function Descriptions

Function cs_directory_root_directory_iter_first
cs_result cs_directory_root_directory_iter_first (
Open a cs_directory_root_directory_iter for traversing the set of root directories deduced by inspecting all source file paths in the project, and retrieve the first root cs_directory.
Parameters
dir [out] The cs_directory for the first root directory.
itr [out] A cs_directory_root_directory_iter iterator opened to traverse the root directories.
Returns A cs_result:
Function cs_directory_root_directory_iter_next
cs_result cs_directory_root_directory_iter_next (
Advance the provided cs_directory_root_directory_iter and retrieve the next root directory.
Parameters
dir [out] The cs_directory for the next root directory.
itr [out] The cs_directory_root_directory_iter iterator from which to retrieve the next root/child directory.
Returns A cs_result:
Function cs_directory_root_directory_iter_close
cs_result cs_directory_root_directory_iter_close (
Close a cs_directory_root_directory_iter iterator.
Parameters
itr [in] The cs_directory_root_directory_iter iterator to close.
Returns CS_SUCCESS on successful close.
Function cs_directory_child_directory_iter_first
cs_result cs_directory_child_directory_iter_first (
Open a cs_directory_child_directory_iter for traversing the immediate subdirectories of the specified parent, and retrieve the first child directory.
Parameters
parent_dir [in] The cs_directory whose children are to be retrieved by this iterator.
child_dir [out] The cs_directory for the first child of parent_dir.
itr [out] A cs_directory_root_directory_iter iterator opened to traverse the children of parent_dir.
Returns A cs_result:
Function cs_directory_child_directory_count
cs_result cs_directory_child_directory_count (
Get the number of subdirectories in a directory.
Parameters
dir [in] The cs_directory whose subdirectories are to be counted.
count [out] The number of subdirectories.
Returns A cs_result:
Function cs_directory_root_directory_count
cs_result cs_directory_root_directory_count (
Get the number of root directories in the project.
Parameters
count [out] The number of root directories.
Returns A cs_result:
Function cs_directory_file_count
cs_result cs_directory_file_count (
Get the number of files in a directory.
Parameters
dir [in] The cs_directory whose files are to be counted.
count [out] The number of files.
Returns A cs_result:
Function cs_directory_child_directory_iter_next
cs_result cs_directory_child_directory_iter_next (
Advance the provided cs_directory_child_directory_iter and retrieve the next child directory.
Parameters
dir [out] The cs_directory for the next child directory.
itr [out] The cs_directory_child_directory_iter iterator from which to retrieve the next child directory.
Returns A cs_result:
Function cs_directory_child_directory_iter_close
cs_result cs_directory_child_directory_iter_close (
Close a cs_directory_child_directory_iter iterator.
Parameters
itr [in] The cs_directory_child_directory_iter iterator to close.
Returns CS_SUCCESS on successful close.
Function cs_directory_file_iter_first
cs_result cs_directory_file_iter_first (
Open a cs_directory_file_iter for traversing the source files immediately contained in a directory, and retrieve the first file.
Parameters
dir [in] The cs_directory whose files are to be retrieved by this iterator.
sf [out] The cs_sf for the first file in dir.
itr [out] A cs_directory_file_iter iterator opened to traverse the files in dir.
Returns A cs_result:
Function cs_directory_file_iter_next
cs_result cs_directory_file_iter_next (
Advance the provided cs_directory_file_iter and retrieve the next file.
Parameters
sf [out] The cs_sf for the next file.
itr [out] The cs_directory_file_iter iterator from which to retrieve the next file.
Returns A cs_result:
Function cs_directory_file_iter_close
cs_result cs_directory_file_iter_close (
Close a cs_directory_file_iter iterator.
Parameters
itr [in] The cs_directory_file_iter iterator to close.
Returns CS_SUCCESS on successful close.
Function cs_directory_parent
cs_result cs_directory_parent (
Retrive the parent cs_directory of a cs_directory.
Parameters
dir [in] The cs_directory whose parent is to be obtained.
parent_dir [out] Receives the parent cs_directory.
Returns A cs_result:
Function cs_directory_depth
cs_result cs_directory_depth (
Get the depth or distance from root of a cs_directory.
Parameters
dir [in] The cs_directory whose depth is to be obtained.
depth_out [out] The depth of dir.
Returns A cs_result:
Function cs_directory_normalized_path
cs_result cs_directory_normalized_path (
Retrieve the normalized version of the full path for the specified cs_directory.
Parameters
dir [in] The cs_directory whose path is to be obtained.
dirpath [out] A user-allocated buffer to be populated with the path of the directory.
  • Windows: this path is the downcased version of the one output by cs_directory_path(), with backslash directory separators replaced by forward slashes.
  • Mac: this path is the downcased version of the one output by cs_directory_path().
  • Otherwise: this path is the same as the one output by cs_directory_path().
capacity_bytes [in] The capacity of dirpath, measured in bytes.
bytes_needed [out] The number of bytes required to store the entire path of the directory.
Returns A cs_result:
  • CS_TRUNCATED if dirpath is not large enough to hold the entire path (and so the path is truncated),
  • CS_SUCCESS otherwise.
Notes Retrieves the normalized path of the directory associated with a cs_directory and writes it to dirpath. If path is not large enough to hold the entire name, the name is truncated to fit into dirpath.

Call this function with dirpath NULL and capacity_bytes 0 to obtain the required capacity of dirpath.

Function cs_directory_path
cs_result cs_directory_path (
Retrieve the full path for the cs_directory.
Parameters
dir [in] The cs_directory whose path is to be obtained.
dirpath [out] A user-allocated buffer to be populated with the path of the directory.
capacity_bytes [in] The capacity of dirpath, measured in bytes.
bytes_needed [out] The number of bytes required to store the entire path of the directory.
Returns A cs_result:
  • CS_TRUNCATED if dirpath is not large enough to hold the entire path (and so the path is truncated),
  • CS_SUCCESS otherwise.
Notes Retrieves the path of the directory associated with a cs_directory and writes it to path. If dirpath is not large enough to hold the entire name, the name is truncated to fit into dirpath.

Call this function with dirpath NULL and capacity_bytes 0 to obtain the required capacity of path.

Function cs_directory_normalized_string
const char * cs_directory_normalized_string (
Get the normalized directory path associated with a cs_directory.
Parameters
dir [in] The cs_directory the path to which is to be obtained.
Returns A pointer to a buffer containing the path of the directory associated with dir (as a char*). The buffer is only valid until another API function is invoked.
  • Windows: this string is the downcased version of the one returned by cs_directory_string(), with backslash directory separators replaced by forward slashes.
  • Mac: this string is the downcased version of the one returned by cs_directory_string().
  • Otherwise: this string is the same as the one returned by cs_directory_string().
Notes Do not modify or free the returned buffer.

This function entails less user overhead than cs_directory_normalized_path(), 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_directory_string
const char * cs_directory_string (
Get the directory path associated with a cs_directory.
Parameters
dir [in] The cs_directory whose path is to be obtained.
Returns A pointer to a buffer containing the path of the directory associated with dir (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_directory_path(), 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_directory_stable_hash
cs_hash_t cs_directory_stable_hash (
Get a hash value for a cs_directory, with stable results across sufficiently-similar analyses.
Parameters
dir [in] The cs_directory value to hash.
Returns A hash derived from the contents of dir.
Notes This hash value 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 d1 be a cs_directory in A1, and d2 be the cs_directory in A2 that corresponds to d1. Then cs_directory_stable_hash(d1)==cs_directory_stable_hash(d2).

If you do not need hash values to be stable across analyses, use cs_directory_hash(): it has better performance.

Function cs_directory_stable_compare
int cs_directory_stable_compare (
Compare two cs_directory objects, with stable results across sufficiently-similar analyses.
Parameters
dir_a [in] First cs_directory to compare.
dir_b [in] Second cs_directory to compare.
Returns An integer N, such that:
  • N<0 if dir_a considered less than dir_b
  • N==0 if dir_a and dir_b have the same normalized directory path as determined by cs_directory_normalized_string().
  • N>0 if dir_a considered greater than dir_b
Notes This function is provided so cs_directory values can be stored in ordered containers that provide stable iteration order.

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_directory values in A1, and a2 and b2 be the cs_directory values in A2 that correspond to a1 and b1 respectively. Then cs_directory_stable_compare(a1,b1)==cs_directory_stable_compare(a2,b2).

If you do not need comparison results to be stable across different analyses, use cs_directory_compare(): it has better performance.

Function cs_directory_equal
cs_boolean cs_directory_equal (
Check: are two cs_directory values equal?
Parameters
dir1 [in] First argument to equality test.
dir2 [in] Second argument to equality test.
Returns cs_true if dir1 and dir2 are equal; cs_false if not.
Function cs_directory_compare
int cs_directory_compare (
Compare two cs_directory objects.
Parameters
dir_a [in] First argument to comparison.
dir_b [in] Second argument to comparison.
Returns An integer N, such that:
  • N<0 if dir_a is considered less than dir_b
  • N==0 if dir_a and dir_b are the same cs_directory
  • N>0 if dir_a is considered greater than dir_b
Notes This function is provided so cs_directory objects can be stored in ordered containers. It is not based on any user-perceivable ordering.

For fixed cs_directory values a and b in a single analysis, cs_directory_compare(a,b) will always return the same value. However, cs_directory_compare() will not necessarily return this same value when called on the corresponding cs_directory values a' and b' in a different analysis. Function cs_directory_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_directory_compare(): it has better performance.

Function cs_directory_hash
cs_hash_t cs_directory_hash (
Hash function for cs_directory.
Parameters
dir [in] A cs_directory to hash.
Returns A hash of dir.
Notes For a fixed cs_directory d in a single analysis, cs_directory_hash(d) will always return the same value. However, cs_directory_hash() will not necessarily return this same value when called on the corresponding cs_directory d' in a different analysis. Function cs_directory_stable_hash() provides some degree of stability across analyses, although restrictions still apply. If you do not need hash values to be stable across different analyses, use cs_directory_hash(): it has better performance.
Function cs_directory_is_null
cs_boolean cs_directory_is_null (
Determine whether a cs_directory is null.
Parameters
dir [in] The cs_directory to check for nullity.
Returns cs_true if dir is null, cs_false otherwise.
Function cs_directory_get_null
cs_directory cs_directory_get_null ( )
Return a null cs_directory.
Returns A null cs_directory.