pt_image_alloc man page

pt_image_alloc, pt_image_free, pt_image_name ā€” allocate/free a traced memory image descriptor

Synopsis

#include <intel-pt.h>

struct pt_image *pt_image_alloc(const char *name);

const char *pt_image_name(const struct pt_image *image);

void pt_image_free(struct pt_image *image);

Link with -lipt.

Description

pt_image_alloc() allocates a new pt_image and returns a pointer to it. A pt_image object defines the memory image that was traced as a collection of file sections and the virtual addresses at which those sections were loaded.

The name argument points to an optional zero-terminated name string. If the name argument is NULL, it will be ignored and the returned pt_image object will not have a name. Otherwise, the returned pt_image object will have a copy of the string pointed to by the name argument as name.

pt_image_name() returns the name of the pt_image object the image argument points to.

pt_image_free() frees the pt_image object pointed to by image. The image argument must be NULL or point to an image that has been allocated by a call to pt_image_alloc().

Return Value

pt_image_alloc() returns a pointer to a pt_image object on success or NULL in case of an error.

pt_image_name() returns a pointer to a zero-terminated string of NULL if the image does not have a name.

Example

int foo(const char *name) {
    struct pt_image *image;
    errcode;

    image = pt_image_alloc(name);
    if (!image)
        return pte_nomem;

    errcode = bar(image);

    pt_image_free(image);
    return errcode;
}

See Also

pt_image_add_file(3), pt_image_add_cached(3), pt_image_copy(3), pt_image_remove_by_filename(3), pt_image_remove_by_asid(3), pt_image_set_callback(3), pt_insn_set_image(3), pt_insn_get_image(3)

Referenced By

pt_image_add_file(3), pt_image_remove_by_filename(3), pt_image_set_callback(3).

The man pages pt_image_free(3) and pt_image_name(3) are aliases of pt_image_alloc(3).