JavaScript is not currently enabled, but is required for full CodeSonar manual search and browse functionality.
If you are viewing this file in your hub's Web GUI, enable JavaScript in your browser: you will also need it for GUI functionality.
If you opened this file directly from disk, your browser may be directly suppressing JavaScript functionality: certain browsers perform this suppression on local files (but not files delivered by web servers) for security reasons.
| CodeSonar® 9.0p0 Hot Tips | CONFIDENTIAL | CodeSecure Inc |
Defines a set of utility operations for CodeSonar.
| #define CS_UTILITY_H | ||
| #define cs_uid_equal(a, b) | ((a)==(b)) | a and b are equal |
| #define cs_uid_hash(uid) | ((cs_detcheck_nondet_event( "cs_uid_hash" ), (cs_hash_t)(uid))) | Convert uid to a cs_hash_t. |
| #define cs_uid_hash_seed(uid, seed) | ((cs_hash_t)(uid)+(cs_hash_t)(seed)) | |
| #define cs_uid_is_null(uid) | ((uid)?cs_false:cs_true) | Check if uid is null. |
| #define cs_uid_to_integer(uid) | ((csuint32)(uid)) | Convert uid to a csuint32. |
| #define CS_SFID_NULL | (cs_sfid_get_null()) | The null cs_sfid. |
| #define CS_SF_NULL | (cs_sf_get_null()) | The null cs_sf. |
| #define CS_UTILITY_INL_H |
| cs_const_string | cs_version ( )
Get the CodeSurfer version number for the current installation.
|
| int | cs_major_version ( )
Get the major part of the CodeSurfer version number for the current installation.
|
| int | cs_minor_version ( )
Get the minor part of the CodeSurfer version number for the current installation.
|
| int | cs_patch_version ( )
Get the patch number for the current CodeSurfer installation.
|
| csuint64 | cs_bytes_hash ( const void * data, cs_size_t len )
Hash a block of memory.
|
| cs_boolean | cs_uid_equal ( cs_uid uid1, cs_uid uid2 )
Check: are two cs_uid objects equal?
|
| cs_hash_t | cs_uid_hash ( cs_uid uid )
Hash function for cs_uid.
|
| cs_hash_t | cs_uid_stable_hash ( cs_uid uid )
Get a hash value for a cs_uid, with stable results across sufficiently-similar analyses.
|
| int | cs_uid_stable_compare ( cs_uid uid_a, cs_uid uid_b )
Compare two cs_uid objects, with stable results across sufficiently-similar analyses.
|
| cs_boolean | cs_uid_is_null ( cs_uid uid )
Check: is the specified cs_uid null?
|
| csuint32 | cs_uid_to_integer ( cs_uid uid )
Convert a cs_uid to a csuint32.
|
| cs_result | cs_sfid_to_string ( cs_sfid sfid, cs_string out_string, cs_size_t capacity_bytes, cs_size_t * bytes_needed ) |
| cs_result | cs_string_to_sfid ( cs_const_string str, cs_sfid * out_sfid )
Convert a hexadecimal number (as a cs_const_string) to a cs_sfid.
|
| cs_result | cs_xmlencode ( cs_const_string str, cs_size_t str_len, cs_boolean use_private_use_area, cs_string buf, cs_size_t buf_bytes, cs_size_t * bytes_needed )
XML-encode a cs_const_string.
|
| cs_const_string | cs_xmlencode_string ( cs_const_string str, cs_size_t str_len, cs_boolean use_private_use_area )
XML-encode a cs_const_string, with buffer management included.
|
| cs_result | cs_xmldecode ( cs_const_string str, cs_string buf, cs_size_t buf_bytes, cs_size_t * bytes_needed )
XML-decode a cs_const_string.
|
| cs_const_string | cs_xmldecode_string ( cs_const_string str )
XML-decode a cs_const_string, with buffer management included.
|
| cs_boolean | cs_file_path_equal ( cs_const_file_path file_path1, cs_const_file_path file_path2 )
Check: are two cs_file_path objects equal?
|
| cs_hash_t | cs_file_path_hash ( cs_const_file_path file_path )
Get a hash value for a cs_file_path.
|
| csuint64 | cs_file_path_hash64 ( cs_const_file_path file_path, csuint64 hash_seed )
Get a 64-bit hash value for a cs_file_path with respect to a 64-bit seed.
|
| cs_result | cs_set_kind_name ( cs_set_kind kind, cs_const_string * out_string )
Get the name of a cs_set_kind.
|
| cs_result | cs_get_user_name ( cs_string buf, cs_size_t capacity_bytes, cs_size_t * bytes_needed )
Get the user name of the current user.
|
| cs_result | cs_get_machine_name ( cs_string buf, cs_size_t capacity_bytes, cs_size_t * bytes_needed )
Get the name of the current machine.
|
| cs_const_string const * | cs_get_startup_argv ( )
Get the argv array used to start the process hosting the plugin.
|
| void | cs_flush_managed_objects ( )
Flush managed objects to disk.
|
| void | cs_set_resident_capacity ( cs_size_t capacity_bytes )
Alter the number of bytes of managed objects that can be kept in memory.
|
| cs_size_t | cs_get_resident_capacity ( )
Get the number of bytes of managed objects that can be kept in memory.
|
| void | cs_set_io_buffer_capacity ( cs_size_t buffering_bytes )
Set the number of bytes to allocate for IO buffering.
|
| cs_size_t | cs_get_io_buffer_capacity_pending ( )
Get the IO buffer capacity specified in the last cs_set_io_buffer_capacity() call.
|
| cs_result | cs_get_io_buffer_capacity_current ( cs_size_t * buffering_bytes )
Get the number of bytes currently allocated for IO buffering.
|
| void | cs_exit ( int code )
Cleanly call "exit(int)".
|
| cs_const_string | cs_install_prefix ( )
Retrieve the file system path for the CodeSurfer installation.
|
| cs_const_string | cs_codesecure_home_directory ( )
Retrieve the file system path for the CodeSecure installation.
|
| cs_result | cs_load_project ( cs_const_string prj )
Loads the given project file.
|
| cs_boolean | cs_sf_equal ( cs_sf sf1, cs_sf sf2 )
Check: are two cs_sf objects equal?
|
| int | cs_sf_compare ( cs_sf sf_a, cs_sf sf_b )
Compare two cs_sf objects.
|
| cs_hash_t | cs_sf_hash ( cs_sf sf )
Hash function for cs_sf.
|
| csuint64 | cs_sf_hash64 ( cs_sf sf )
64-bit hash function for cs_sf.
|
| cs_boolean | cs_sf_is_null ( cs_sf sf )
Check: is the specified cs_sf null?
|
| cs_sf | cs_sf_get_null ( )
Get a null cs_sf.
|
| cs_boolean | cs_sfid_equal ( cs_sfid sfid1, cs_sfid sfid2 )
Check: are two cs_sfid objects equal?
|
| int | cs_sfid_compare ( cs_sfid sfid_a, cs_sfid sfid_b )
Compare two cs_sfid objects.
|
| cs_hash_t | cs_sfid_hash ( cs_sfid sfid )
Hash function for cs_sfid.
|
| cs_hash_t | cs_sfid_hash_seed ( cs_sfid sfid, cs_hash_t hash_seed )
Seeded hash function for cs_sfid.
|
| cs_boolean | cs_sfid_is_null ( cs_sfid sfid )
Check: is the specified cs_sfid null?
|
| cs_sfid | cs_sfid_get_null ( )
Get a null cs_sfid.
|
| int | cs_uid_compare ( cs_uid uid_a, cs_uid uid_b )
Compare two cs_uid objects.
|
| cs_boolean | cs_const_string64_is_null ( cs_const_string64 s )
Check: is the specified cs_const_string64 null?
|
| cs_const_string64 | cs_const_string64_get_null ( )
Get a null cs_const_string64.
|
| cs_sf | cs_sf_from_hash64 ( csuint64 h )
Recover a cs_sf from its 64-bit hash.
|
| Returns | A cs_string representation of the CodeSurfer version number for the current installation, in format "major#.minor#". |
|---|
| Returns | The major part of the CodeSurfer version number for the current installation (that is, the number before the "."), as an int. |
|---|
| Returns | The minor part of the CodeSurfer version number (that is, the number after the "."), as an int. |
|---|
| Returns | The patch number for the current CodeSurfer installation, as an int. |
|---|
| Parameters |
|
||||||
|---|---|---|---|---|---|---|---|
| Returns | A hash of the data |
| Parameters |
|
||||||
|---|---|---|---|---|---|---|---|
| Returns |
A cs_boolean:
|
| Parameters |
|
|||
|---|---|---|---|---|
| Returns | The hash for uid. | |||
| Notes | For a fixed cs_uid u in a single analysis, cs_uid_hash(u) will always return the same value. However, cs_uid_hash() will not necessarily return this same value when called on the corresponding cs_uid u' in a different analysis. Function cs_uid_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_uid_hash(): it has better performance. |
| Parameters |
|
|||
|---|---|---|---|---|
| Returns | A hash derived from uid. | |||
| 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 u1 be a cs_uid in A1, and u2 be the cs_uid in A2 that corresponds to u1. Then cs_uid_stable_hash(u1)==cs_uid_stable_hash(u2).
If you do not need hash values to be stable across analyses, use cs_uid_hash(): it has better performance. |
| Parameters |
|
||||||
|---|---|---|---|---|---|---|---|
| Returns |
An integer N, such that:
|
||||||
| Notes | This function is provided so cs_uid objects 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_uid values in A1, and a2 and b2 be the cs_uid values in A2 that correspond to a1 and b1 respectively. Then cs_uid_stable_compare(a1,b1)==cs_uid_stable_compare(a2,b2). If you do not need comparison results to be stable across different analyses, use cs_uid_compare(): it has better performance. |
| Parameters |
|
|||
|---|---|---|---|---|
| Returns |
A cs_boolean:
|
| Parameters |
|
||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Returns |
A cs_result:
|
||||||||||||
| Notes | The inverse function is cs_string_to_sfid().
Call this function with out_string NULL and capacity_bytes 0 (zero) to determine the memory needed to hold the entire representation. |
| Parameters |
|
||||||
|---|---|---|---|---|---|---|---|
| Returns |
A cs_result:
|
||||||
| Notes | The inverse function is cs_sfid_to_string(). |
| Parameters |
|
|||||||||
|---|---|---|---|---|---|---|---|---|---|---|
| Returns |
A cs_result:
|
|||||||||
| Notes | When parsing source code, CodeSonar may encounter code using an unspecified encoding. In general, CodeSonar's strategy for dealing with this ambiguity is to forward the bit stream as-is all the way to the UI (typically a web browser).
When use_private_use_area is cs_true, bytes 128 or higher will be escaped as code point 0xe000 + byte. They will appear in the XML as ... The CodeSonar hub expects XML to be encoded in this fashion. If use_private_use_area is cs_false, the bytes will appear as-is in the XML. XML parsers will reject this XML if they do not use a character encoding matching the data.
|
| Parameters |
|
|||||||||
|---|---|---|---|---|---|---|---|---|---|---|
| Returns | The encoded string. | |||||||||
| Notes | When parsing source code, CodeSonar may encounter code using an unspecified encoding. In general, CodeSonar's strategy for dealing with this ambiguity is to forward the bit stream as-is all the way to the UI (typically a web browser).
When use_private_use_area is cs_true, bytes 128 or higher will be escaped as code point 0xe000 + byte. They will appear in the XML as ... The CodeSonar hub expects XML to be encoded in this fashion. If use_private_use_area is cs_false, the bytes will appear as-is in the XML. XML parsers will reject this XML if they do not use a character encoding matching the data. |
| Parameters |
|
||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Returns |
A cs_result:
|
| Parameters |
|
|||
|---|---|---|---|---|
| Returns | The decoded string. |
| Parameters |
|
||||||
|---|---|---|---|---|---|---|---|
| Returns |
A cs_boolean:
|
||||||
| Notes | If file names on the host platform are case insensitive, so is this check. |
| Parameters |
|
|||
|---|---|---|---|---|
| Returns | A hash of file_path. | |||
| Notes | If two file paths p1 and p2 are equal according to cs_file_path_equal(), then cs_file_path_hash(p1) will be equal to cs_file_hash(p2). |
| Parameters |
|
||||||
|---|---|---|---|---|---|---|---|
| Returns | A 64-bit hash of file_path, as a csuint64. |
| Parameters |
|
||||||
|---|---|---|---|---|---|---|---|
| Returns |
A cs_result:
|
||||||
| Time-Complexity | O(1) |
| Parameters |
|
|||||||||
|---|---|---|---|---|---|---|---|---|---|---|
| Returns |
A cs_result:
|
|||||||||
| Notes | Call this function with buf NULL and capacity_bytes 0 (zero) to determine the memory needed to hold the entire user name. |
| Parameters |
|
|||||||||
|---|---|---|---|---|---|---|---|---|---|---|
| Returns |
A cs_result:
|
|||||||||
| Notes | Call this function with buf NULL and capacity_bytes 0 (zero) to determine the memory needed to hold the entire machine name. |
| Returns | An array of cs_const_string, with the last element holding NULL. The format corresponds to the argument to a main function traditionally called 'argv'. ('argc' is implicit in the number of elements before reaching NULL.) |
|---|---|
| Notes | CodeSurfer and CodeSonar ignore command-line arguments provided after a '--'; this can be used to pass arguments to the plugin. For example, 'csurf -l my-plugin.so -- --do-something-cool'. However, the full argument list will be provided as the return from this function; for the example, it would be {"csurf", "-l", "my-plugin.so", "--", "--do-something-cool"}. |
| Returns | void |
|---|---|
| Notes | Calling this function will free all managed objects from memory and write them to disk. It is illegal to call this function with certain types of outstanding iterators. An assertion of very limited usefulness will fire if you do so. |
| Parameters |
|
|||
|---|---|---|---|---|
| Returns | void | |||
| Notes | A reasonable setting might be 1024*1024*256. This should probably not exceed 0.75 * min(RAM_SIZE,2GB). Setting this value too low can cause thrashing, but might be desirable if your algorithm has good access patterns or needs to use the memory for other purposes.
If called with a value less than the current number of bytes in use by resident objects, then objects will be paged out immediately. |
| Returns | The number of bytes of managed objects that can be kept in memory at any time. |
|---|
| Parameters |
|
|||
|---|---|---|---|---|
| Returns | void | |||
| Notes | A reasonable setting might be 1024*1024*128:
The new value does not take effect until the next time cs_s_read_sdg() is called. |
| Returns | The number of bytes allocated for IO buffering. |
|---|
| Parameters |
|
|||
|---|---|---|---|---|
| Returns |
A cs_result:
|
| Parameters |
|
|||
|---|---|---|---|---|
| Returns | void | |||
| Notes | Use this mechanism to cleanly call "exit(int)". Calling libc exit() directly can leave the intermediate files on the disk in an inconsistent state |
| Returns | The installation directory path for CodeSurfer. Note that this is always a subdirectory of cs_codesecure_home_directory(), called 'csurf'. |
|---|
| Returns | The CodeSecure installation directory path. |
|---|
| Returns |
A cs_result:
|
|---|
| Parameters |
|
||||||
|---|---|---|---|---|---|---|---|
| Returns |
A cs_boolean:
|
| Parameters |
|
||||||
|---|---|---|---|---|---|---|---|
| Returns |
An integer N, such that:
|
||||||
| Notes | This function is provided so cs_sf objects can be stored in ordered containers. It is not based on any user-perceivable order of cs_sf objects.
For fixed cs_sf values a and b in a single analysis, cs_sf_compare(a,b) will always return the same value. However, cs_sf_compare() will not necessarily return this same value when called on the corresponding cs_sf values a' and b' in a different analysis. Function cs_sf_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_sf_compare(): it has better performance. |
| Parameters |
|
|||
|---|---|---|---|---|
| Returns | A hash of sf. | |||
| Notes | For a fixed cs_sf s in a single analysis, cs_sf_hash(s) will always return the same value. However, cs_sf_hash() will not necessarily return this same value when called on the corresponding cs_sf s' in a different analysis. Function cs_sf_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_sf_hash(): it has better performance. |
| Parameters |
|
|||
|---|---|---|---|---|
| Returns | A 64-bit hash of sfid, as a csuint64. | |||
| Notes | The inverse function is cs_sf_from_hash64(). |
| Parameters |
|
|||
|---|---|---|---|---|
| Returns |
A cs_boolean:
|
| Parameters |
|
||||||
|---|---|---|---|---|---|---|---|
| Returns |
A cs_boolean:
|
| Parameters |
|
||||||
|---|---|---|---|---|---|---|---|
| Returns |
An integer N, such that:
|
||||||
| Notes | This function is provided so cs_sfid objects can be stored in ordered containers. It is not based on any user-perceivable order of cs_sfid objects.
For fixed cs_sfid values a and b in a single analysis, cs_sfid_compare(a,b) will always return the same value. However, cs_sfid_compare() will not necessarily return this same value when called on the corresponding cs_sfid values a' and b' in a different analysis. Function cs_sfid_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_sfid_compare(): it has better performance. |
| Parameters |
|
|||
|---|---|---|---|---|
| Returns | A hash of sfid. | |||
| Notes | For a fixed cs_sfid s in a single analysis, cs_sfid_hash(s) will always return the same value. However, cs_sfid_hash() will not necessarily return this same value when called on the corresponding cs_sfid s' in a different analysis. Function cs_sfid_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_sfid_hash(): it has better performance. |
| Parameters |
|
|||
|---|---|---|---|---|
| Returns |
A cs_boolean:
|
|||
| Notes | No CodeSonar API function should ever return a null cs_sfid, with the exception of cs_sfid_get_null(). |
| Parameters |
|
||||||
|---|---|---|---|---|---|---|---|
| Returns |
An integer N, such that:
|
||||||
| Notes | This function is provided so cs_uid objects can be stored in ordered containers. It is not based on any user-perceivable order of cs_uid objects.
For fixed cs_uid values a and b in a single analysis, cs_uid_compare(a,b) will always return the same value. However, cs_uid_compare() will not necessarily return this same value when called on the corresponding cs_uid values a' and b' in a different analysis. Function cs_uid_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_uid_compare(): it has better performance. |
| Parameters |
|
|||
|---|---|---|---|---|
| Returns |
A cs_boolean:
|
| Returns | A null cs_const_string64. |
|---|
| Parameters |
|
|||
|---|---|---|---|---|
| Returns | The cs_sf corresponding to h. | |||
| Notes | The inverse function is cs_sf_hash64(). |