Comparison: C++ API vs C API

Table of Contents

• Comparison Factors
• Code Examples
• Links

This section compares and contrasts the C and C++ Plug-In APIs for CodeSonar.

Its main expected audience is users who have previously used the C API and are considering switching to the C++ API.

Users who plan to use the C++ API and have not previously used the C API do not need to read this page.

Comparison Factors

There are several primary factors that make the C++ API more convenient and safer than the C API.

• Easy debugging. Nearly every C++ type implements operator<< in order to make "printf" style debugging convenient.
• No pointers. The C++ API does not take or return pointers. Plugins that do not use operator new or operator delete will be free from many classes of errors. There is an exception for functors such as visitors, where CodeSonar must take ownership of a virtual class instance the user has constructed.
• Exceptions. The C++ API raises exceptions when things go wrong. In C, pretty much every function returns a status code (cs_result) indicating whether or not it succeeded, and the logical return value is usually returned by reference. Since C++ has exceptions, the logical return value is never returned by reference, but is actually the return value. In C, the onus to constantly check and digest the status code is on the user, and it very easy to do the wrong thing.
• No side effects. Because of exceptions, the C++ API can be virtually free of side effects (which were usually output parameters). There are a few exceptions. For instance, the "add" method of mutable_set modifies the set. But in general, function outputs are always through the return value.
• Memory management. In C++, std::string and std::vector free the user from needing to supply user-allocated buffers. The user also does not need to worry about leaking the buffers, not allocating enough space, reading past the end of initialized data, etc.
• More obvious behavior. The behavior of many C APIs is difficult to discern because of the mix of input parameters, output parameters, memory capacities, status codes, etc. A function with a fairly simple purpose ends up taking quite a few parameters. Simply having methods in C++ as opposed to top-level functions makes explicit what was previously a rough convention in the C API. Many methods take zero parameters, making them extremely easy to use. Default parameters and overloading help here too.
• Type safety. The C API involves tagged unions, anonymous enums, pointers, and a number of other risky constructs. Many of these risks are eliminated in the C++ API.
• Resource Acquisition is Initialization. Many of the C++ types do not offer default constructors, making it impossible to have an uninitialized variable. There is no longer such a thing as a "null" program point or AST, in the absence of type casts.
• Templated container types. Makes for a very consistent interface. Mixins are used to add special methods (such as forward_slice) that are particular to certain template instantiations.
• Friendly type names. Many of the C API types have archaic historical names. For instance, procedures are called "Procedure Dependence Graphs", or PDGs. The entire codebase is called the SDG. Variables are ABS_LOCs. A program point is a PDG_VERTEX. Compilation units are called UIDs. Include tree nodes are SFIDs. None of these names are intuitive for new users. New type names are cs::project, cs::compunit, cs::procedure, cs::symbol, cs::point, cs::sfileinst
• Standard libraries. Having STL is very convenient. The API generally obeys STL conventions and rules.

If you avoid the following, it should be difficult to cause crashes in a C++ plug-in.

• type casts
• operator new and operator delete
• unions
• pointers
• libraries other than STL

It is possible to cause uncaught exceptions, stack overflow, OOM, division by zero, and problems stemming from STL.

Code Examples

Task	C++	C equivalent
Get the procedure containing a program point.
	procedure container = pnt.get_procedure();	cs_result r; cs_pdg container; r = cs_pdg_vertex_pdg( pnt, &container ); if( r != CS_SUCCESS ) abort();
Invoke any function that returns a string
	cout << "ast pretty prints as " << node.pretty_print() << endl;	// Common usage mistakes: // null pointer derefs, buffer overruns, forgetting to check return // codes for errors, leaking the buffer, uninitialized variable, // use after free, double free, other memory management issues size_t bn; cs_result r; char *buf = NULL; r = cs_ast_pretty_print(node, NULL, 0, &bn); if( r == CS_TRUNCATED ) { buf = malloc( bn ); if( !buf ) abort(); } else if( r != CS_SUCCESS ) abort(); r = cs_ast_pretty_print(node, buf, bn, &bn); if( r != CS_SUCCESS ) abort(); printf( "ast pretty prints as %s\n", buf ); free(buf);
Invoke any function that returns a vector
	std::vector<ast_field> vec = node.children();	size_t bn; cs_result r; cs_ast_field *buf = NULL; r = cs_ast_children(node, NULL, 0, &bn); if( r == CS_TRUNCATED ) { buf = malloc( bn ); if( !buf ) abort(); } else if( r != CS_SUCCESS ) abort(); r = cs_ast_children(node, buf, bn, &bn); if( r != CS_SUCCESS ) abort(); free(buf);
Create and use an AST pattern that matches "x + K" for any integer literal K. Print K.
	// Make it static so we only compile it once. Could be in top-level scope. static ast_pattern pat("(c:+ :2 (c:integer-value :value ?K))"); ast_bindings bs = pat.match_with_bindings(node); if( !bs ) cout << "No match!" << endl; else cout << "Matched; K=" << bs["K"].as_int32() << endl;	cs_ast_pattern *pat; cs_result r; const char *err, *err_location; cs_ast_binding bindings[1]; r = cs_ast_pattern_compile( "(c:+ :2 (c:integer-value :value ?K))", &pat, &err, &err_location ); if( r != CS_SUCCESS ) { fprintf( stderr, "oops: %s near `%s'\n", err, err_location ); fflush(NULL); abort(); } r = cs_ast_match( node, pat, bindings, sizeof(bindings), &bn ); switch( r ) { case CS_SUCCESS: if( bn == sizeof(bindings) && bindings[0].f.type == csft_int32 ) printf( "Matched; K=%d\n", bindings[0].f._.int32 ); else printf( "Type not int32?\n" ); break; case CS_ELEMENT_NOT_PRESENT: printf( "No match!\n" ); break; default: abort(); }
Use an iterator
	for( ast_iterator it = root_node.begin(); !it.at_end(); ++it ) { ast node = *it; // do stuff with node }	cs_result r; cs_ast_traverse_iter it; for( r = cs_ast_iter_first( root_node, csatf_normal, &node, &it ); r == CS_SUCCESS; r = cs_ast_iter_next( csatd_normal, &node, &it ) ) { // do stuff with node } if( r != CS_OUT_OF_ELEMENTS ) abort(); r = cs_ast_iter_close( &it ); if( r != CS_SUCCESS ) abort();
Forward slice from main
	cout << "Size is " << project::current().find_procedure("foo").points().forward_slice().size() << endl;	cs_pdg proc; cs_result r; cs_pdg_vertex_set vs, rs; r = cs_pdg_find( "foo", &proc ); if( r != CS_SUCCESS ) abort(); r = cs_pdg_vertices( proc, &vs ); if( r != CS_SUCCESS ) abort(); r = cs_s_forward_slice( vs, cs_pdg_edge_kind_datacontrol, &rs ); if( r != CS_SUCCESS ) abort(); printf( "Size is %d\n", (int)cs_pdg_vertex_set_cardinality(rs) );

Links

• cs Namespace Reference: index of C++ API classes and typedefs.
• Writing C++ Plug-Ins For CodeSonar: information about writing and building a C++ plug-in.
• Plug-In API Tutorial: annotated example plug-ins in C++ and the other supported API languages, including step-by-step instructions for building and testing.