PT_ISCACHE_ALLOC(3)

💖 PT_ISCACHE_ALLOC 💖

okay bestie, we're in section 3 of the intel-pt manual, and today's episode is the traced memory image section cache — allocation, naming, and freeing. it's giving malloc but make it ✨sections✨. let's go 🦋

---

✨ NAME ✨

pt_iscache_alloc, pt_iscache_free, pt_iscache_name — allocate / free a traced memory image section cache. that's the whole gig, no cap 💅

---

🌸 SYNOPSIS 🌸

#include <intel-pt.h>

struct pt_image_section_cache *pt_iscache_alloc(const char *name);

const char *pt_iscache_name(const struct pt_image_section_cache *iscache);

void pt_iscache_free(struct pt_image_section_cache *iscache);

and like, link with -lipt obviously. don't forget it or the linker will be SO dramatic about it 😭

---

🎀 DESCRIPTION 🎀

so pt_iscache_alloc() allocates a brand new pt_image_section_cache and hands you back a pointer to it. a pt_image_section_cache object is basically a little collection — it holds a bunch of file sections plus the virtual addresses where those sections got loaded. it's the group chat and the pinned locations, together 🫶

here's the slay part: those image sections can be added to one or more pt_image objects. the underlying file sections get mapped once, and their content is shared across images. no duplicating, no wasting memory, we love an efficient queen 👑

now, the name argument points to an optional zero-terminated name string. quick rules:

• if name is NULL — it's ignored, and the returned pt_image_section_cache object just won't have a name. no name, no problem 🙈
• otherwise — the returned pt_image_section_object object gets a copy of the string that name points to, as its name. a copy, bestie, not a reference. she keeps her own 💖

pt_iscache_name() returns the name of the pt_image_section_cache object that the iscache argument points to.

pt_iscache_free() frees the pt_image_section_cache object pointed to by iscache. but listen, there's a rule and it is NOT optional:

the iscache argument must be NULL, or it must point to an image section cache that was allocated by a call to pt_iscache_alloc(). anything else and you're in undefined-behaviour territory, which is not the vibe 😭💀

---

⭐ RETURN VALUE ⭐

• pt_iscache_alloc() — returns a pointer to a pt_image_section_cache object on success, or NULL if something went wrong. NULL is the "we don't talk about it" signal 💔
• pt_iscache_name() — returns a pointer to a zero-terminated string, or NULL if the image section cache doesn't have a name.

---

🌈 EXAMPLE 🌈

here's the whole flow, copy-paste ready, literally:

       int foo(const char *name) {
           struct pt_image_section_cache *iscache;
           errcode;

           image = pt_iscache_alloc(name);
           if (!iscache)
               return pte_nomem;

           errcode = bar(iscache);

           pt_iscache_free(iscache);
           return errcode;
       }

alloc, do the thing, free. the sacred trilogy 🙏✨

---

👑 SEE ALSO 👑

• pt_iscache_add_file(3)
• pt_image_add_cached(3)

---

and that's the page, bestie 💜 this was PT_ISCACHE_ALLOC(3) from the intel-pt manual — section 3, in all her glory. go forth and cache responsibly, mwah 🎀💖🦋