callstack.h

In this header the general access to the library can be found.

The wrapper class declared in callstack.hpp is automatically included by this header when compiled using a C++ compiler.

struct callstack

The structure of a callstack. It consists of the translation status, the backtrace and the translated callstack frames.

enum callstack_type translationStatus

The translation status to be human-readable.

size_t frameCount

The amount of available translated callstack frames.

Note

Added in version 1.1.

struct callstack_frame * frames

An array of translated callstack frames.

Note

Added in version 1.1.

size_t backtraceSize

The amount of traced callstack frames.

void * backtrace[CALLSTACK_BACKTRACE_SIZE]

The actual backtrace. Can contain as much as CALLSTACK_BACKTRACE_SIZE frames at maximum.

struct callstack * callstack_new(void)

Creates a callstack of the calling function. The backtrace of the calling function is created. The struct is allocated and needs to be freed using the function callstack_delete(struct callstack *). In case of an error, NULL is returned.

struct callstack * callstack_newWithAddress(void *)

Creates a callstack of the calling function, ignoring all frames after the given stack address. The struct is allocated and needs to be freed using the function callstack_delete(struct callstack *). In case of an error, NULL is returned.

bool callstack_emplace(struct callstack *)

Constructs the given callstack object. Stores the backtrace of the calling function. The callstack object needs to be destructed using the function callstack_destroy(struct callstack *) after use.
Returns false if an error occurred during the initialization of the given callstack object.

bool callstack_emplaceWithAddress(struct callstack *, void *)

Constructs the given callstack object. Stores the backtrace of the calling function, ignoring all frames after the given stack address. The callstack object needs to be destructed using the function callstack_destroy(struct callstack *) upon successful construction and use.

bool callstack_emplaceWithBacktrace(struct callstack *, void *[], int)

Constructs the given callstack object. Copies the given callstack into the given object. If the trace is longer than CALLSTACK_BACKTRACE_SIZE, only the first addresses are copied. The callstack object needs to be destructed using the function callstack_destroy(struct callstack *) after use.
If the given trace's length is smaller than 0 false is returned and the given callstack object is not modified.

void callstack_copy(struct callstack *, const struct callstack *)

Copies the given callstack. The given callstack is destroyed before the contents of the other one copied.

bool callstack_relativize(struct callstack*, const char**)

Relativizes the given callstack object.
Upon successful return of the function, the addresses within the callstack object have become offsets into the runtime image they belong to. The names of these runtime images are stored within the given string array. This string array therefor should be capable to hold at least the same amount of strings as the amount of entries within the given callstack object.

Note

Added in version 2.3.

struct callstack_frame * callstack_translateRelative(struct callstack *, const char**)

Translates the given relativized callstack object using the provided array of binary file names.
The given string array must hold at least the same amount of binary file names as the amount of entries within the given callstack object.
Returns an array of the translated callstack frames.

Note

Added in version 2.3.

struct callstack_frame * callstack_toArray(struct callstack *)

Translates the given callstack and returns an array of the translated frames.

Note

Since version 1.1 a callstack frame array is returned.

Previously a string array was returned.

Returns NULL if an error happens.

struct callstack_frame * callstack_getBinaries(struct callstack *)

Translates the given callstack and returns an array of the translated frames. If the given callstack has not been translated before, only the binary file information is deducted.

Returns NULL if an error happens.

size_t callstack_getFrameCount(struct callstack *)

Returns the number of frames stored in the given callstack.

enum callstack_type callstack_getType(struct callstack *)

Returns the type of the given callstack. See callstack_type.h for more information about the possible values.

bool callstack_isTranslated(struct callstack *)

Returns whether the given callstack is already translated.

void callstack_destroy(struct callstack *)

Destroys the contents of the given callstack object.

void callstack_delete(struct callstack *)

Destroys and deallocates the given callstack object.