cs_sysutil.h

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.

If you access the manual through the hub's Web GUI, the functionality will not be suppressed because the hub is a web server.
Alternatively, your browser may allow you to explicitly disable the security setting that suppresses functionality. See the CodeSonar FAQ for more information.

CodeSonar^® 9.0p0 Hot Tips

CONFIDENTIAL

CodeSecure Inc

cs_sysutil.h

Defines a set of system utility operations for CodeSonar.

Links
Defines
Functions
Function Descriptions

Defines

#define CS_SYSUTIL_H
#define CSRC(c)	do{ \ cs_result __csrc_res = (c); \ if( cs_unlikely( __csrc_res != CS_SUCCESS ) ) \ { \ cs_fatal( __FILE__ ":%d: " #c " exited with %s\n", \ __LINE__, cs_resolve_error( __csrc_res ) ); \ } \ }while(0)	General-purpose convenience macro for verifying the well-behavedness of API calls. Use around calls to functions that return cs_result where you are not explicitly expecting, detecting, and handling modes of failure: all return values other than CS_SUCCESS will cause the program to fail with a diagnostic message.
#define CSLC(c)	do{ \ cs_result __csrc_res = (c); \ if( cs_unlikely( __csrc_res != CS_SUCCESS && \ __csrc_res != CS_OUT_OF_ELEMENTS ) ) \ { \ cs_fatal( __FILE__ ":%d: " #c " is %s\n", \ __LINE__, cs_resolve_error( __csrc_res ) ); \ } \ }while(0)	Iteration-specific convenience macro for verifying the well-behavedness of API calls: all return values other than CS_SUCCESS and CS_OUT_OF_ELEMENTS will cause the program to fail with a diagnostic message. For example: for( r = cs_abs_loc_for_each_first(...); r == CS_SUCCESS; r = cs_abs_loc_for_each_next(...) ) ...; CSLC(r);
#define CSRCA(c)	do{ \ cs_result __csrc_res = (c); \ if( cs_unlikely( __csrc_res != CS_SUCCESS && \ __csrc_res != CS_ELEMENT_ALREADY_PRESENT ) ) \ { \ cs_fatal( __FILE__ ":%d: " #c " exited with %s\n", \ __LINE__, cs_resolve_error( __csrc_res ) ); \ } \ }while(0)	Reporting/insertion-specific convenience macro for verifying the well-behavedness of API calls. Use around calls to functions that return cs_result if you are not explicitly expecting, detecting, and handling modes of failure: all return values other than CS_SUCCESS and CS_ELEMENT_ALREADY_PRESENT will cause the program to fail with a diagnostic message.
#define CSRCD(c)	do{ \ cs_result __csrc_res = (c); \ if( cs_unlikely( __csrc_res != CS_SUCCESS && \ __csrc_res != CS_ELEMENT_NOT_PRESENT ) ) \ { \ cs_fatal( __FILE__ ":%d: " #c " exited with %s\n", \ __LINE__, cs_resolve_error( __csrc_res ) ); \ } \ }while(0)	Retrieval/lookup-specific convenience macro for verifying the well-behavedness of API calls. Use around calls to functions that return cs_result if you are not explicitly expecting, detecting, and handling modes of failure: all return values other than CS_SUCCESS and CS_ELEMENT_NOT_PRESENT will cause the program to fail with a diagnostic message.
#define CSRCR(c)	do{ \ cs_result __csrc_res = (c); \ if( cs_unlikely( __csrc_res != CS_SUCCESS && \ __csrc_res != CS_REPLACED ) ) \ { \ cs_fatal( __FILE__ ":%d: " #c " exited with %s\n", \ __LINE__, cs_resolve_error( __csrc_res ) ); \ } \ }while(0)	Convenience macro for verifying the well-behavedness of API calls. Use around calls to functions that return cs_result if you are not explicitly expecting, detecting, and handling modes of failure : all return values other than CS_SUCCESS and CS_REPLACED will cause the program to fail with a diagnostic message.
#define CSRF(name, c)	do{ \ cs_fatal( __FILE__ ":%d: " name " exited with %s\n", \ __LINE__, cs_resolve_error( c ) ); \ }while(0)	Convenience macro: causes the program to fail with a diagnostic message.

Functions

cs_size_t	cs_snprintf ( cs_string buffer, cs_size_t print_bytes, cs_const_string format_str, ... ) C99 compliant snprintf implementation.
cs_size_t	cs_vsnprintf ( cs_string buffer, cs_size_t print_bytes, cs_const_string format_str, va_list args ) C99 compliant vsnprintf implementation.
void	cs_fatal ( const char * format, ... ) Print an error message to stderr and then call abort.
cs_const_string	cs_resolve_error ( cs_result err ) Resolve a descriptive string from a return code.
void *	cs_scratchpad_data ( ) Get a link to the scratchpad.
void	cs_scratchpad_resize ( cs_size_t s ) Set the size of the scratchpad.
cs_size_t	cs_scratchpad_bytes ( ) Get the current size of the scratchpad.

Function Descriptions

Function cs_snprintf

cs_size_t cs_snprintf (

cs_string buffer,
cs_size_t print_bytes,
cs_const_string format_str,
... )

C99 compliant snprintf implementation.

Parameters

buffer	[in]	The string to print.
print_bytes	[in]	The (maximum) number of bytes to print from buffer.
format_str	[in]	The format string.

Returns

The number of bytes printed.

Function cs_vsnprintf

cs_size_t cs_vsnprintf (

cs_string buffer,
cs_size_t print_bytes,
cs_const_string format_str,
va_list args )

C99 compliant vsnprintf implementation.

Parameters

buffer	[in]	The string to print.
print_bytes	[in]	The (maximum) number of bytes to print from buffer.
format_str	[in]	The format string.
args	[in]	A list containing all the remaining print arguments.

Returns

The number of bytes printed.

Function cs_fatal

void cs_fatal (

const char * format,
... )

Print an error message to stderr and then call abort.

Notes	This function might be changed to show a message box on windows when CodeSurfer is not hooked up to a console.

Function cs_resolve_error

cs_const_string cs_resolve_error (

cs_result err )

Resolve a descriptive string from a return code.

Parameters

err

[in]

A cs_result for which to find the description.

Returns

A string representation of the cs_result specified, or "Invalid cs_result" if err is not a valid cs_result.

Function cs_scratchpad_data

void * cs_scratchpad_data ( )

Get a link to the scratchpad.

Returns	A link to the scratchpad, as a void*.
Notes	The scratchpad is a buffer provided by the API. Users can read and write this buffer, and can also change its size using cs_scratchpad_resize() and retrieve its current size using cs_scratchpad_bytes(). Note that the location of the scratchpad may change if the scratchpad is resized. A typical use for the scratchpad is storing the results of API functions that can return CS_TRUNCATED, as in the following example. for(;;){ switch( r = cs_pdg_vertex_characters( v, (cs_string)cs_scratchpad_data(), cs_scratchpad_bytes(), &bytes_needed ) ){ case CS_TRUNCATED: if( limit > cssp_bytes() ){ cs_scratchpad_resize(limit < bytes_needed ? limit : bytes_needed ); continue; } else { perform_desired_operation(cs_scratchpad_data(); } case CS_SUCCESS: perform_desired_operation(cs_scratchpad_data(); default: cs_resolve_error(r); } }

Returns

A link to the scratchpad, as a void*.

Notes

The scratchpad is a buffer provided by the API. Users can read and write this buffer, and can also change its size using cs_scratchpad_resize() and retrieve its current size using cs_scratchpad_bytes(). Note that the location of the scratchpad may change if the scratchpad is resized.

A typical use for the scratchpad is storing the results of API functions that can return CS_TRUNCATED, as in the following example.

for(;;){
  switch( r = cs_pdg_vertex_characters( 
           v, 
           (cs_string)cs_scratchpad_data(),
           cs_scratchpad_bytes(),
           &bytes_needed ) ){
    case CS_TRUNCATED:
       if( limit > cssp_bytes() ){
          cs_scratchpad_resize(limit < bytes_needed ? limit : bytes_needed );
          continue;
       }
       else {
          perform_desired_operation(cs_scratchpad_data();
       }
     case CS_SUCCESS:
       perform_desired_operation(cs_scratchpad_data();
     default:
       cs_resolve_error(r);
  }  
}

Function cs_scratchpad_resize

void cs_scratchpad_resize (

cs_size_t s )

Set the size of the scratchpad.

Parameters

[in]

The new size for the scratchpad, in bytes.

Returns

void.

Notes

Note that resizing the scratchpad can cause it to be relocated, so always retrieve a new scratchpad pointer with cs_scratchpad_data() after using cs_scratchpad_resize().

See the cs_scratchpad_data() documentation for further information and a code example.

Function cs_scratchpad_bytes

cs_size_t cs_scratchpad_bytes ( )

Get the current size of the scratchpad.

Returns	The current size of the scratchpad, in bytes.
Notes	See the cs_scratchpad_data() documentation for further information and a code example.

cs_sysutil.h

Links

Defines

Functions

Function Descriptions