PT_ISCACHE_ADD_FILE(3)

💖 NAME 💖

pt_iscache_add_file — bestie, this is the one that adds file sections to a traced memory image section cache ✨

---

🌸 SYNOPSIS 🌸

#include <intel-pt.h>
int pt_iscache_add_file(struct pt_image_section_cache *iscache,
                        const char *filename, uint64_t offset,
                        uint64_t size, uint64_t vaddr);

Link with -lipt.

---

🦋 DESCRIPTION 🦋

okay so pt_iscache_add_file() takes a brand new section — literally size bytes, starting at offset inside filename, loaded at vaddr — and drops it into iscache. slay 💅

When it works? it hands you back a positive integer identifier that uniquely IDs the section you just added, inside that cache. no cap, that identifier is your new bestie because you can use it to:

• add sections from an image section cache to one or more traced memory images — go check pt_image_add_cached(3) 🫶 and heads up, sections added from an image section cache get shared across images 👑
• read memory from the cached section — see pt_iscache_read(3) 📖

and the way this thing is lowkey smart: if the cache already contains a suitable section, it doesn't add anything, it just returns the identifier for the existing one. periodt. and if the cache already has a section that only differs in the load address, then a new section gets added that shares the underlying file section 🧚 shared file section, shared vibes.

---

⭐ RETURN VALUE ⭐

pt_iscache_add_file() returns a positive image section identifier when it's thriving, or a negative pt_error_code enumeration constant if it's giving error 😭

---

💀 ERRORS 💀

• pte_invalid — the iscache or filename argument is NULL, or the offset argument is too big such that the section would start past the end of the file 🙈 (like, you can't start reading past the end of the file, babe, that's not a thing)

---

🔥 EXAMPLE 🔥

int add_file(struct pt_image_section_cache *iscache, struct pt_image *image,
             const char *filename, uint64_t offset, uint64_t size,
             uint64_t vaddr, const struct pt_asid *asid) {
    int isid;

    isid = pt_iscache_add_file(iscache, filename, offset, size, vaddr);
    if (isid < 0)
       return isid;

    return pt_image_add_cached(image, iscache, isid, asid);
}

---

🌈 SEE ALSO 🌈

pt_iscache_alloc(3), pt_iscache_free(3), pt_iscache_read(3), pt_image_add_cached(3)

---

ok that's the whole thing, you're so welcome 💖 this was PT_ISCACHE_ADD_FILE(3) from the intel-pt (libipt) section 3 manual pages — mwah, kisses, go add some file sections bestie 🎀✨🌸