|
Packit |
b1f7ae |
% PT_IMAGE_REMOVE_BY_FILENAME(3)
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
! Copyright (c) 2015-2017, Intel Corporation
|
|
Packit |
b1f7ae |
!
|
|
Packit |
b1f7ae |
! Redistribution and use in source and binary forms, with or without
|
|
Packit |
b1f7ae |
! modification, are permitted provided that the following conditions are met:
|
|
Packit |
b1f7ae |
!
|
|
Packit |
b1f7ae |
! * Redistributions of source code must retain the above copyright notice,
|
|
Packit |
b1f7ae |
! this list of conditions and the following disclaimer.
|
|
Packit |
b1f7ae |
! * Redistributions in binary form must reproduce the above copyright notice,
|
|
Packit |
b1f7ae |
! this list of conditions and the following disclaimer in the documentation
|
|
Packit |
b1f7ae |
! and/or other materials provided with the distribution.
|
|
Packit |
b1f7ae |
! * Neither the name of Intel Corporation nor the names of its contributors
|
|
Packit |
b1f7ae |
! may be used to endorse or promote products derived from this software
|
|
Packit |
b1f7ae |
! without specific prior written permission.
|
|
Packit |
b1f7ae |
!
|
|
Packit |
b1f7ae |
! THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
|
|
Packit |
b1f7ae |
! AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
|
Packit |
b1f7ae |
! IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
|
Packit |
b1f7ae |
! ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
|
|
Packit |
b1f7ae |
! LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
|
|
Packit |
b1f7ae |
! CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
|
|
Packit |
b1f7ae |
! SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
|
|
Packit |
b1f7ae |
! INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
|
|
Packit |
b1f7ae |
! CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
|
|
Packit |
b1f7ae |
! ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
|
|
Packit |
b1f7ae |
! POSSIBILITY OF SUCH DAMAGE.
|
|
Packit |
b1f7ae |
!-->
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
# NAME
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
pt_image_remove_by_filename, pt_image_remove_by_asid - remove sections from a
|
|
Packit |
b1f7ae |
traced memory image descriptor
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
# SYNOPSIS
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
| **\#include `<intel-pt.h>`**
|
|
Packit |
b1f7ae |
|
|
|
Packit |
b1f7ae |
| **int pt_image_remove_by_filename(struct pt_image \**image*,**
|
|
Packit |
b1f7ae |
| **const char \**filename*,**
|
|
Packit |
b1f7ae |
| **const struct pt_asid \**asid*);**
|
|
Packit |
b1f7ae |
| **int pt_image_remove_by_asid(struct pt_image \**image*,**
|
|
Packit |
b1f7ae |
| **const struct pt_asid \**asid*);**
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
Link with *-lipt*.
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
# DESCRIPTION
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
**pt_image_remove_by_filename**() removes all sections from *image* that were
|
|
Packit |
b1f7ae |
added by a call to **pt_image_add_file**(3) with an identical *filename*
|
|
Packit |
b1f7ae |
argument or by a call to **pt_image_copy**(3) from such a section. Sections
|
|
Packit |
b1f7ae |
that are based on the same underlying file but that were added using a different
|
|
Packit |
b1f7ae |
*filename* argument are not removed.
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
If the *asid* argument is not NULL, it removes only sections that were added
|
|
Packit |
b1f7ae |
with a matching address-space identifier. See **pt_image_add_file**(3).
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
**pt_image_remove_by_asid**(3) removes all sections from *image* that were added
|
|
Packit |
b1f7ae |
by a call to **pt_image_add_file**(3) with a matching *asid* argument or by a
|
|
Packit |
b1f7ae |
call to **pt_image_copy**(3) from such a section. See **pt_image_add_file**(3).
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
Two *pt_asid* objects match in their "cr3* or *vmcs* field if one of them does
|
|
Packit |
b1f7ae |
not provide the field (i.e. sets it to *pt_asid_no_cr3* or *pt_asid_no_vmcs*
|
|
Packit |
b1f7ae |
respectively) or if the provided values are identical. Two *pt_asid* objects
|
|
Packit |
b1f7ae |
match if they match in all fields.
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
# RETURN VALUE
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
Both functions return the number of sections removed on success or a negative
|
|
Packit |
b1f7ae |
*pt_error_code* enumeration constant in case of an error.
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
# ERRORS
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
pte_invalid
|
|
Packit |
b1f7ae |
: The *image* argument is NULL or the *filename* argument is NULL
|
|
Packit |
b1f7ae |
(**pt_image_remove_by_filename**() only).
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
# EXAMPLE
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
~~~{.c}
|
|
Packit |
b1f7ae |
int foo(struct pt_image *image, uint64_t cr3) {
|
|
Packit |
b1f7ae |
struct pt_asid asid1, asid2;
|
|
Packit |
b1f7ae |
int errcode;
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
pt_asid_init(&asid1);
|
|
Packit |
b1f7ae |
asid1.cr3 = cr3;
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
pt_asid_init(&asid2);
|
|
Packit |
b1f7ae |
asid2.cr3 = ~cr3;
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
errcode = pt_image_add_file(image, "/path/to/libfoo.so",
|
|
Packit |
b1f7ae |
0xa000, 0x100, &asid1, 0xb000);
|
|
Packit |
b1f7ae |
if (errcode < 0)
|
|
Packit |
b1f7ae |
return errcode;
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
errcode = pt_image_add_file(image, "rel/path/to/libfoo.so",
|
|
Packit |
b1f7ae |
0xa000, 0x100, &asid1, 0xc000);
|
|
Packit |
b1f7ae |
if (errcode < 0)
|
|
Packit |
b1f7ae |
return errcode;
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
/* This call would only remove the section added first:
|
|
Packit |
b1f7ae |
*
|
|
Packit |
b1f7ae |
* - filename matches only the first section's filename
|
|
Packit |
b1f7ae |
* - NULL matches every asid
|
|
Packit |
b1f7ae |
*/
|
|
Packit |
b1f7ae |
(void) pt_image_remove_by_filename(image,
|
|
Packit |
b1f7ae |
"/path/to/libfoo.so",
|
|
Packit |
b1f7ae |
NULL);
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
/* This call would not remove any of the above sections:
|
|
Packit |
b1f7ae |
*
|
|
Packit |
b1f7ae |
* - filename matches the first section's filename
|
|
Packit |
b1f7ae |
* - asid2 does not match asid1
|
|
Packit |
b1f7ae |
*/
|
|
Packit |
b1f7ae |
(void) pt_image_remove_by_filename(image,
|
|
Packit |
b1f7ae |
"/path/to/libfoo.so",
|
|
Packit |
b1f7ae |
&asid2);
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
/* This call would not remove any of the above sections:
|
|
Packit |
b1f7ae |
*
|
|
Packit |
b1f7ae |
* - asid2 does not match asid1
|
|
Packit |
b1f7ae |
*/
|
|
Packit |
b1f7ae |
(void) pt_image_remove_by_asid(image, &asid2);
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
/* This call would remove both sections:
|
|
Packit |
b1f7ae |
*
|
|
Packit |
b1f7ae |
* - asid1 matches itself
|
|
Packit |
b1f7ae |
*/
|
|
Packit |
b1f7ae |
(void) pt_image_remove_by_asid(image, &asid1);
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
/* This call would remove both sections:
|
|
Packit |
b1f7ae |
*
|
|
Packit |
b1f7ae |
* - NULL matches every asid
|
|
Packit |
b1f7ae |
*/
|
|
Packit |
b1f7ae |
(void) pt_image_remove_by_asid(image, NULL);
|
|
Packit |
b1f7ae |
}
|
|
Packit |
b1f7ae |
~~~
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
# SEE ALSO
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
**pt_image_alloc**(3), **pt_image_free**(3), **pt_image_add_file**(3),
|
|
Packit |
b1f7ae |
**pt_image_add_cached**(3), **pt_image_copy**(3), **pt_insn_set_image**(3),
|
|
Packit |
b1f7ae |
**pt_insn_get_image**(3)
|