API Reference

The Intel® Trace Collector library provides the user with a number of functions that control the profiling library and record user-defined activities, define groups of processes, define performance counters and record their values. Header files with the necessary parameter, macro and function declarations are provided in the include directory: VT.h for ANSI C and C++ and VT.inc for Fortran 77 and Fortran 90. It is strongly recommended to include these header files if any Intel Trace Collector API functions are to be called.

You can also find the description of all available API functions in comments for VT.h and in the man pages on Linux* OS (man VT).

The Intel Trace Collector library is thread-safe in the sense that all of its API functions can be called by several threads at the same time. Some API functions can really be executed concurrently, others protect global data with POSIX* mutexes.

Concepts

This section uses the following concepts, essential for understanding the Intel Trace Collector API:

For detailed description and examples of these concepts within the framework of the configuration functionality, see Filtering Trace Data.

General Macros and Errors

#define VT_VERSION

API version constant. It is incremented each time the API changes, even if the change does not break compatibility with the existing API. It can be used to determine at compile time how to call the API, like this:

#if VT_VERSION > 4000
   do something
#else
   do something different
#endif

VT_version() provides the same information at runtime.

To check whether the current revision of the API is still compatible with the revision of the API that the application was written against, compare against both VT_VERSION and VT_VERSION_COMPATIBILITY, as shown below.

#define VT_VERSION_COMPATIBILITY

Oldest API definition, which is still compatible with the current one.

It is set to the current version each time an API change can break programs written for the previous API. For example, a program written for VT_VERSION2090 will work with API 3000 if VT_VERSION_COMPATIBILITY remained at 2090. It may even work without modifications when VT_VERSION_COMPATIBILITY was increased to 3000, but this cannot be determined automatically and will require a source code review.

Here is a usage example:

#define APP_VT_VERSION 1000 // API version used by APP
#ifdef VT_VERSION_COMPATIBILITY > APP_EXPECTED_VT_VERSION
# error "VT.h is no longer compatible with APP's usage of the API"
#endif
#ifdef VT_VERSION < APP_EXPECTED_VT_VERSION
# error "VT.h is not recent enough for APP"
#endif

Suppose you instrumented your C source code for the API with VT_VERSION equal to 3100. Then you could add the following code fragment to detect incompatible changes in the API:

#include <VT.h>
#if VT_VERSION_COMPATIBILITY > 3100
# error ITC API is no longer compatible with our calls
#endif

Make sure to compare against a fixed number but not VT_VERSION, because VT_VERSION will always be greater or equal VT_VERSION_COMPATIBILITY.

To make the instrumentation work again after such a change, you can either just update the instrumentation to accommodate for the change or even provide different instrumentation that is chosen by the C preprocessor based on the value of VT_VERSION.

enum _VT_ErrorCode

Error codes returned by Intel Trace Collector API.

Enumerator Description
VT_OK OK
VT_ERR_NOLICENSE No valid license found
VT_ERR_NOTIMPLEMENTED Not implemented
VT_ERR_NOTINITIALIZED Not initialized
VT_ERR_BADREQUEST Invalid request type
VT_ERR_BADSYMBOLID Wrong symbol ID
VT_ERR_BADSCLID Wrong SCL ID
VT_ERR_BADSCL Wrong SCL
VT_ERR_BADFORMAT Wrong format
VT_ERR_BADKIND Wrong kind found
VT_ERR_NOMEMORY Could not get memory
VT_ERR_BADFILE Error while handling file
VT_ERR_FLUSH Error while flushing
VT_ERR_BADARG Wrong argument
VT_ERR_NOTHREADS No worker threads
VT_ERR_BADINDEX Wrong thread index
VT_ERR_COMM Communication error
VT_ERR_INVT Intel® Trace Collector API called while inside an Intel® Trace Collector function
VT_ERR_IGNORE Non-fatal error code