PT_IMAGE_REMOVE_BY_FILENAME(3)

💖 PT_IMAGE_REMOVE_BY_FILENAME(3) 💖

okay so bestie, we're in section 3 of the manual (the library-call girlies section, iykyk) and today's main character is pt_image_remove_by_filename, with pt_image_remove_by_asid riding shotgun. both of them do one thing and they do it well: they yeet sections out of a traced memory image descriptor. so real. so necessary. let's get into it. 🎀

---

✨ NAME ✨

pt_image_remove_by_filename, pt_image_remove_by_asid — remove sections from a traced memory image descriptor 🧹💅

---

🦋 SYNOPSIS 🦋

#include <intel-pt.h>
int pt_image_remove_by_filename(struct pt_image *image,
                                const char *filename,
                                const struct pt_asid *asid);
int pt_image_remove_by_asid(struct pt_image *image,
                            const struct pt_asid *asid);

Link with -lipt.

---

🌸 DESCRIPTION 🌸

so pt_image_remove_by_filename() removes all sections from image that were added by a call to pt_image_add_file(3) with an identical filename argument, or by a call to pt_image_copy(3) from such a section. and listen — sections that are based on the same underlying file but that were added using a different filename argument are not removed. they stay. they're thriving. periodt. 🙈

if the asid argument is not NULL, it removes only sections that were added with a matching address-space identifier. See pt_image_add_file(3).

and then pt_image_remove_by_asid(3) removes all sections from image that were added by a call to pt_image_add_file(3) with a matching asid argument, or by a call to pt_image_copy(3) from such a section. See pt_image_add_file(3). 💜

now, the matchmaking rules, because this is the part everyone gets wrong and I need you to lock in:

two pt_asid objects match in their cr3 or vmcs field if one of them does not provide the field (i.e. sets it to pt_asid_no_cr3 or pt_asid_no_vmcs respectively) or if the provided values are identical.

two pt_asid objects match if they match in all fields.

that's it. that's the whole vibe check. ✨

---

🔥 RETURN VALUE 🔥

Both functions return the number of sections removed on success, or a negative pt_error_code enumeration constant in case of an error. no cap. 😭

---

💀 ERRORS 💀

• pte_invalid — the image argument is NULL, or the filename argument is NULL (pt_image_remove_by_filename() only). like, asid-only girlies don't even have a filename to be mad about. 🤷

---

👑 EXAMPLE 👑

this one is a whole novel and I love her for it. read every comment, they're the plot:

int foo(struct pt_image *image, uint64_t cr3) {
    struct pt_asid asid1, asid2;
    int errcode;

    pt_asid_init(&asid1);
    asid1.cr3 = cr3;

    pt_asid_init(&asid2);
    asid2.cr3 = ~cr3;

    errcode = pt_image_add_file(image, "/path/to/libfoo.so",
                                0xa000, 0x100, &asid1, 0xb000);
    if (errcode < 0)
        return errcode;

    errcode = pt_image_add_file(image, "rel/path/to/libfoo.so",
                                0xa000, 0x100, &asid1, 0xc000);
    if (errcode < 0)
        return errcode;

    /* This call would only remove the section added first:
     *
     * - filename matches only the first section's filename
     * - NULL matches every asid
     */
    (void) pt_image_remove_by_filename(image,
                                       "/path/to/libfoo.so",
                                       NULL);

    /* This call would not remove any of the above sections:
     *
     * - filename matches the first section's filename
     * - asid2 does not match asid1
     */
    (void) pt_image_remove_by_filename(image,
                                       "/path/to/libfoo.so",
                                       &asid2);

    /* This call would not remove any of the above sections:
     *
     * - asid2 does not match asid1
     */
    (void) pt_image_remove_by_asid(image, &asid2);

    /* This call would remove both sections:
     *
     * - asid1 matches itself
     */
    (void) pt_image_remove_by_asid(image, &asid1);

    /* This call would remove both sections:
     *
     * - NULL matches every asid
     */
    (void) pt_image_remove_by_asid(image, NULL);
}

---

🌈 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_insn_set_image(3)
• pt_insn_get_image(3)

---

bestie this whole thing is giving "go read pt_image_add_file(3) before you text me back" energy and honestly? correct.

---

and that's the page!! 💖 the footer down at the bottom is just the title echoing itself one more time — PT_IMAGE_REMOVE_BY_FILENAME(3) — no version, no date, just the name, like a signature at the end of a love letter. iconic behaviour honestly. go remove some sections, you've got this 🫶✨🎀