PT_IMAGE_ALLOC(3)

💖 PT_IMAGE_ALLOC(3) — the intel-pt image allocation girlies 💖

okay bestie, so this is a section 3 manual page (that's library functions, iykyk ✨) for three lil functions that live together in the intel-pt house: pt_image_alloc, pt_image_free, and pt_image_name. they handle the whole allocate / free a traced memory image descriptor situation. let's get into it 🫶

---

🌸 NAME 🌸

pt_image_alloc</p>, pt_image_free</p>, pt_image_name</p> — allocate/free a traced memory image descriptor ✨

---

🎀 SYNOPSIS 🎀

like, literally just:

#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);

and don't forget: Link with -lipt. 👑

---

💅 DESCRIPTION 💅

pt_image_alloc()

pt_image_alloc()</p> allocates a brand new pt_image and hands you back a pointer to it. main character energy fr fr 💖

and what is a pt_image object, you ask? it's the memory image that was traced, defined as a collection of file sections plus the virtual addresses at which those sections were loaded. iconic. 🌈

okay so the name argument points to an optional zero-terminated name string. two paths here, bestie:

• if name is NULL — it gets ignored, no drama, and the returned pt_image object simply will not have a name.
• otherwise — the returned pt_image object gets a copy of the string that name points to, as its name. a whole copy, not just a pointer. slay. 💅

pt_image_name()

pt_image_name()</p> returns the name of the pt_image object that the image argument points to. that's it, that's the function. ✨

pt_image_free()

pt_image_free()</p> frees the pt_image object pointed to by image.

⚠️ bestie listen — the image argument must be NULL or point to an image that has been allocated by a call to pt_image_alloc(). those are the only two options. no improvising. 🙈

---

⭐ RETURN VALUE ⭐

• pt_image_alloc() returns a pointer to a pt_image object on success, or NULL in case of an error. that's the vibe check 💀
• pt_image_name() returns a pointer to a zero-terminated string of NULL if the image does not have a name.

---

🦋 EXAMPLE 🦋

here's the whole thing in action, look at her go:

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 👑

go read these next, bestie, they're all part of the same friend group:

• 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)

---

and that's the page!! 🎀 this one literally signs off as PT_IMAGE_ALLOC(3) — that's the footer, that's the whole footer, she said what she said 💖 no cap, go allocate something. mwah. 🫶✨