PT_INSN_GET_IMAGE(3)

💖 PT_INSN_GET_IMAGE — bestie edition 💖

okay so this is a section 3 manual page from the intel-pt library, and it's all about the traced memory image descriptor that your instruction flow decoder and your block decoder use to read instruction memory. four functions, one vibe, let's go ✨

---

✨ NAME ✨

pt_insn_get_image, pt_insn_set_image, pt_blk_get_image, pt_blk_set_image — get/set an Intel(R) Processor Trace instruction flow or block decoder's traced memory image descriptor 🎀

---

🦋 SYNOPSIS 🦋

#include <intel-pt.h>
struct pt_image *pt_insn_get_image(struct pt_insn_decoder *decoder);
struct pt_image *pt_blk_get_image(struct pt_block_decoder *decoder);
int pt_insn_set_image(struct pt_insn_decoder *decoder,
                      struct pt_image *image);
int pt_blk_set_image(struct pt_block_decoder *decoder,
                     struct pt_image *image);

and when you link, bestie, you link with -lipt. periodt 💅

---

🌸 DESCRIPTION 🌸

So pt_insn_get_image() and pt_blk_get_image() hand you back the traced memory image descriptor that decoder uses for reading instruction memory. go peep pt_image_alloc(3) if you wanna know more about that whole situation 👀

every single decoder comes with its own default pt_image* object. it's initially empty, and it gets automatically destroyed when the decoder is freed. so like, you don't have to worry about it, it's giving self-care 🧖♀️

then pt_insn_set_image() and pt_blk_set_image() set the traced memory image descriptor that decoder uses for reading instruction memory. and here's the lil twist: if the image argument is NULL, it sets decoder's image to be its default image 🎀

⚠️ okay but listen: the user is responsible for freeing the pt_image object that image points to when it is no longer needed. that's on you, not the library. no cap.

---

🌈 RETURN VALUE 🌈

pt_insn_get_image() and pt_blk_get_image() return a pointer to decoder's pt_image object 💖

the returned pointer is NULL if the decoder argument is NULL. (iconic of them honestly)

pt_insn_set_image() and pt_blk_set_image() return zero on success or a negative pt_error_code enumeration constant in case of an error 😭

---

💀 ERRORS 💀

• pte_invalid — the decoder argument is NULL. that's it, that's the whole error list, we love a short list 🙈

---

👑 NOTES 👑

🚨 One pt_image object must not be shared between multiple decoders. do NOT do it. i'm serious.

if you want a common image, use pt_image_copy(3) to copy it instead. sharing is not caring in this specific case, iykyk 💅

---

🌟 SEE ALSO 🌟

• pt_insn_alloc_decoder(3)
• pt_insn_free_decoder(3)
• pt_insn_next(3)
• pt_blk_alloc_decoder(3)
• pt_blk_free_decoder(3)
• pt_blk_next(3)

---

and that's the whole page bestie!! 🫶 this was the PT_INSN_GET_IMAGE page from the intel-pt man pages, section 3 of the manual, brought to you by the same iconic crew behind the rest of the intel-pt docs — mwah, go read the SEE ALSOs, ily, bye ✨💖🎀