PT_IMAGE_SET_CALLBACK(3)

✨ PT_IMAGE_SET_CALLBACK ✨

okay bestie, we're in pt_image_set_callback(3) territory and honestly? it's giving "plumbing but make it glam". let's get into it 💅

---

🌸 NAME 🌸

pt_image_set_callback — set a traced memory image read memory callback

like, you're telling your traced memory image who to call when it needs to read memory it doesn't already have. iconic behavior tbh 🫶

---

🎀 SYNOPSIS 🎀

#include <intel-pt.h>
typedef int (read_memory_callback_t)(uint8_t *buffer, size_t size,
                                     const struct pt_asid *asid,
                                     uint64_t ip, void *context);
int pt_image_set_callback(struct pt_image *image,
                          read_memory_callback_t *callback,
                          void *context);

Link with -lipt.

no cap: that -lipt is not optional, bestie. link it or weep 😭

---

💖 DESCRIPTION 💖

pt_image_set_callback() sets the function pointed to by callback as the read-memory callback function in the pt_image object pointed to by image. any previous read-memory callback function is replaced — it's not stacking, it's a glow-up swap, one at a time periodt.

and you can remove the read-memory callback function entirely by passing NULL as the callback argument. poof. gone. 🦋

here's the tea though: when the Intel(R) Processor Trace (Intel PT) instruction flow decoder that is using image tries to read memory from a location that is not contained in any of the file sections in image, it calls the read-memory callback function with the following arguments:

• buffer — a pre-allocated memory buffer to hold the to-be-read memory. the callback function shall provide the read memory in that buffer. it's literally an empty cup and you gotta fill it 🍓
• size — the size of the memory buffer pointed to by the buffer argument.
• asid — the address-space identifier specifying the process, guest, or hypervisor, in which context the ip argument is to be interpreted. see pt_image_add_file(3). iykyk 💜
• ip — the virtual address from which size bytes of memory shall be read.
• context — the context argument passed to pt_image_set_callback().

the callback function shall return the number of bytes read on success (no more than size) or a negative pt_error_code enumeration constant in case of an error.

⚠️ real talk: return no more than size. over-reporting bytes you didn't actually write is not the vibe and it's not allowed. and on failure, negative pt_error_code — not zero, not a shrug emoji 🙈

---

👑 RETURN VALUE 👑

pt_image_set_callback() returns zero on success or a negative pt_error_code enumeration constant in case of an error.

zero = slay. negative = something's wrong, check the errors section below bestie ⭐

---

🔥 ERRORS 🔥

• pte_invalid — if the image argument is NULL. like, you cannot set a callback on nothing, that's not main character energy, that's a crash. 💀

---

🌈 SEE ALSO 🌈

• pt_image_alloc(3)
• pt_image_free(3)
• 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_insn_set_image(3)
• pt_insn_get_image**(3)

---

and that's the whole page, bestie 🧚 this one came to you from the PT_IMAGE_SET_CALLBACK(3) manual page — that's the footer line, the source/version-and-date situation, sitting right there at the bottom of the page. go forth and read some memory 💖✨🎀