PT_ISCACHE_READ(3)

💖 PT_ISCACHE_READ(3) 💖

okay bestie, gather round, because we're reading memory out of a cached file section and it's actually so much fun, no cap. this is pt_iscache_read, section 3 of the manual (the library-calls girlies), from the intel-pt headers. let's get into it 🦋

---

✨ NAME ✨

pt_iscache_read — read memory from a cached file section 📖

---

🌸 SYNOPSIS 🌸

#include <intel-pt.h>
int pt_iscache_read(struct pt_image_section_cache *iscache,
                    uint8_t *buffer, uint64_t size, int isid,
                    uint64_t vaddr);

Link with -lipt.

---

💅 DESCRIPTION 💅

so pt_iscache_read() reads memory from a cached file section. and like, the file section has to have been added beforehand by a call to pt_iscache_add(3) — you can't just roll up and read a section that isn't in the cache, that's not the vibe. 🚫

here's the cast of characters, lowkey iconic each one:

• the iscache argument points to the pt_image_section_cache object. it has to be the same one that was used in the corresponding pt_iscache_add(3) call. same cache, same energy, periodt.
• the buffer argument must point to a memory buffer of at least size bytes. big enough or don't bother bestie.
• the isid argument identifies the file section we're reading memory from. it must be the same identifier that was returned from the corresponding pt_iscache_add(3) call that added the file section to the cache. matching IDs only, it's giving loyalty. 🔑
• the vaddr argument gives the virtual address from which size bytes of memory shall be read.

on success, pt_iscache_read() copies at most size bytes of memory from the cached file section identified by isid in iscache, starting at virtual address vaddr, into buffer — and then it returns the number of bytes that were actually copied. at most, bestie. remember that word, it comes back around. 😌

and heads up: multiple calls to pt_iscache_read() may be necessary if size is bigger than 4Kbyte or if the read crosses a section boundary. so if your size is giving huge, you're gonna need to loop it. one call is not gonna eat the whole thing, iykyk. 🍓

---

👑 RETURN VALUE 👑

pt_iscache_read() returns the number of bytes that were read on success 🌈, or a negative pt_error_code enumeration constant in case of an error 💀.

---

🔥 ERRORS 🔥

• pte_invalid — the iscache or buffer argument is NULL, or the size argument is zero. basically: null pointers and zero-size reads are not invited to the function. 🙈
• pte_bad_image — the iscache does not contain a section identified by isid. that ID? not in this cache. ghosted fr fr.
• pte_nomap — the vaddr argument lies outside of the virtual address range of the cached section. you asked for an address that section doesn't cover, bestie, it's simply not there. 😭

---

🎀 SEE ALSO 🎀

• pt_iscache_alloc(3)
• pt_iscache_free(3)
• pt_iscache_add(3)

---

and that's the whole page, mwah 💋 — this was PT_ISCACHE_READ(3) from the intel-pt library docs, section 3, and yes she's iconic for a reason. go forth and read your cached sections, you absolute main character 🫶✨