pt_iscache_add_file man page

pt_iscache_add_file — add 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

pt_iscache_add_file() adds a new section consisting of size bytes starting at offset in filename loaded at vaddr to iscache.

On success, pt_iscache_add_file() returns a positive integer identifier that uniquely identifies the added section in that cache. This identifier can be used to add sections from an image section cache to one or more traced memory images. See pt_image_add_cached(3). Sections added from an image section cache will be shared across images. It can also be used to read memory from the cached section. See pt_iscache_read(3).

If the cache already contains a suitable section, no section is added and the identifier for the existing section is returned. If the cache already contains a section that only differs in the load address, a new section is added that shares the underlying file section.

Return Value

pt_iscache_add_file() returns a positive image section identifier on success or a negative pt_error_code enumeration constant in case of an 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.

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)

Referenced By

pt_image_add_file(3), pt_iscache_alloc(3).