Pin
|
API Reference | |
Command Line Switches | This section describes the command line switches that are currently supported by Pin |
IMG: Image Object | An IMG represents all the data structures corresponding to a binary (executable). Can be accessed at instrumentation time and analysis time. Note: Shared libraries are also represented by the IMG abstraction. Moreover, the IMG objects are created in a lazy fashion. Only if a shared library is loaded and IMG is created. Over the lifetime of a process the number IMG objects created may hence increase. APIs from this group are available in any thread, including any internal thread spawned by the tool |
▼INS: Instruction Object | An INS represents an instruction. Can only be accessed at instrumentation time |
Instrumentation API | |
Generic inspection API | |
Inspection API for IA-32 and Intel(R) 64 instructions | |
Generic modification API | |
SEC: Section Object | A SEC is modeled after the sections found inside elf images. Can be accessed at instrumentation time and analysis time |
RTN: Routine Object | A RTN represents the functions/routines/procedures typically produced by a compiler for a procedural programming language such as C. Pin finds routines by using the symbol table information. You must call PIN_InitSymbols() so that symbol table information will be available. Can be accessed at instrumentation time and analysis time. APIs from this group are available in any thread, including any internal thread spawned by the tool |
▼REG: Register Object | Can be accessed at instrumentation time and analysis time |
REG (generic) | |
REG (specific to the IA-32 and Intel(R) 64 architectures) | |
TRACE: Single entrance, multiple exit sequence of instructions | Sequence of instructions that is always entered at the top and may have multiple exits. If Pin detects a jump to an instruction in the middle of a trace, it will create a new trace beginning at the target. See Instrumentation Granularity |
BBL: Single entrance, single exit sequence of instructions | Sequence of instructions that is always entered at the top and exited at the bottom by a fall through and/or taken branch. If Pin detects a jump to an instruction in the middle of a bbl, it will create a new bbl beginning at the target. See Instrumentation Granularity |
SYM: Symbol Object | Symbol objects provide information about function symbols in the application. See Symbols for more information |
Utilities for formatting strings | |
Utilities for tokenizing strings | |
▼KNOB: Commandline Option Handling | Knobs automate the parsing and management of command line switches. A command line contains switches for Pin, the tool, and the application. The knobs parsing code understands how to separate them |
KNOB: Basics | |
KNOB: Printing | |
LOCK: Locking Primitives | Primitives for locking. APIs from this group are available in any thread, including any internal thread spawned by the tool |
Controlling and Initializing | This group of functions is used to initialize Pin, start the application, and a call backs for events like application exit |
Trace version APIs | APIs to implement multiple types of instrumentation on traces and switch between them. Trace versioning allows the same code to be instrumented multiple times. For example, a trace can have both heavyweight and lightweight instrumentation and Pin can switch between the two while the application is running. See tests in the tools/InstrumentationOrderAndVersion directory for examples that use the versioning API's |
Fast Buffering APIs | APIs to perform low-overhead buffering of data for analysis. Use PIN_DefineTraceBuffer() to create space for storing data, and INS_InsertFillBuffer() to fill the buffers. When a buffer overflows, or the thread exits, the defined callback will be used to process the data |
PROTO API | This API describes an application routine |
Pin Process API | These APIs provide information about the instrumented process. They are available in any thread, including any internal thread spawned by the tool |
Pin Thread API | A group of Pin threading primitives. These APIs are available in any thread, including any internal thread spawned by the tool |
Pin System Call API | These APIs provide Pin support for extracting information about, or modifying, system calls made by the pinned program |
DBG: Debugging using Pin | Access the debug information contained in an elf binary |
Pin Error Reporting Support | Pin errors are normally printed to the screen. Some tools prefer to take the Pin errors and create their own error message. This is important if your tool has a particular look and feel. Pin provides the -error_file option, which generates a machine-parsable error code, and supresses error being emitted to the screen |
Basic types | |
Instrumentation for Common Instrumentation Tasks | Instlib provides instrumentation for some common tasks. It is implemented as classes that automatically insert the instrumentation so it can be used with tools without having to knows the details of the implementation |
ALARM | Call a function when the specified event has occured. Triggers can be base on instruction counts or executing a specific address |
Follow Child Process API | These APIs allow the user to be notified before child(Windows*)/exec-ed(Linux*) process is starting to execute. The user can use the CHILD_PROCESS handle to get information about the process that is going to be executed. The user can decide whether to inject Pin (and PinTool) into the child/exec-ed process. On Linux, if the user has decided to inject Pin into the child process and the injection has failed, the child process would run uninstrumeted. This is only supported for parent injection. In case of child injection, the behavior is the same as on Windows. On Windows, if the injection has failed, the child process would be terminated. However, the parent will continue to run. NOTE: |
Architecture-specific utilities | |
Miscellaneous functions | |
Context manipulation API | This API allows the user to read and modify the architectural register state of the processor, as seen in the application that runs under Pin |
Physical context manipulation API | This API allows the user to read and modify the Pin/tool architectural register state of the processor. The registers physical context range (enumerated in REG) is up to REG_PHYSICAL_CONTEXT_END registers and floating point state |
PIN callbacks manipulation API | This API allows the user to retrieve and modify properties of the registered callback functions that were registered in Pin |
Exception API | This API allows the user to raise exceptions on behalf of the application and also analyze information associated with exceptions |
Application Level Debugging API | This API allows the user to debug the application that is running on top of Pin. It also allows a tool to interact with the debugger and provide extended commands to the debugger. Also see the tutorial section on this topic: The Pin Advanced Debugging Extensions |
Stop, examine and resume application threads API | This API allows the user to stop all application threads, examine and modify their state and then resume them. It is available in analysis routines and internal threads |
Prototypes | A PROTO is a data structure that describes a function prototype |
Instrumentation arguments | See INS_InsertCall |
Pin Deprecated API | APIs from older versions of Pin that have been replaced by more powerful, or simpler, interfaces in the current version of Pin. The newer APIs should be used instead of these interfaces |