1PT_IMAGE_ALLOC(3)                                            PT_IMAGE_ALLOC(3)
2
3
4

NAME

6       pt_image_alloc,  pt_image_free,  pt_image_name - allocate/free a traced
7       memory image descriptor
8

SYNOPSIS

10       #include <intel-pt.h>
11       struct pt_image *pt_image_alloc(const char *name);
12       const char *pt_image_name(const struct pt_image *image);
13       void pt_image_free(struct pt_image *image);
14
15       Link with -lipt.
16

DESCRIPTION

18       pt_image_alloc() allocates a new pt_image and returns a pointer to  it.
19       A pt_image object defines the memory image that was traced as a collec‐
20       tion of file sections and the virtual addresses at which those sections
21       were loaded.
22
23       The  name  argument  points to an optional zero-terminated name string.
24       If the name argument is NULL, it  will  be  ignored  and  the  returned
25       pt_image object will not have a name.  Otherwise, the returned pt_image
26       object will have a copy of the string pointed to by the  name  argument
27       as name.
28
29       pt_image_name() returns the name of the pt_image object the image argu‐
30       ment points to.
31
32       pt_image_free() frees the pt_image object pointed to by image.  The im‐
33       age  argument must be NULL or point to an image that has been allocated
34       by a call to pt_image_alloc().
35

RETURN VALUE

37       pt_image_alloc() returns a pointer to a pt_image object on  success  or
38       NULL in case of an error.
39
40       pt_image_name()  returns  a pointer to a zero-terminated string of NULL
41       if the image does not have a name.
42

EXAMPLE

44              int foo(const char *name) {
45                  struct pt_image *image;
46                  errcode;
47
48                  image = pt_image_alloc(name);
49                  if (!image)
50                      return pte_nomem;
51
52                  errcode = bar(image);
53
54                  pt_image_free(image);
55                  return errcode;
56              }
57

SEE ALSO

59       pt_image_add_file(3), pt_image_add_cached(3), pt_image_copy(3),  pt_im‐
60       age_remove_by_filename(3),      pt_image_remove_by_asid(3),      pt_im‐
61       age_set_callback(3), pt_insn_set_image(3), pt_insn_get_image(3)
62
63
64
65                                                             PT_IMAGE_ALLOC(3)
Impressum