|
Call back function when pin initialization is finished.
|
|
Call back function when Pin attaches to application in Probe mode
|
|
Call-back function when application changes context.
|
|
Call back function when Pin detaches from application in JIT mode
|
|
Call back function when Pin detaches from application in Probe mode
|
|
Call back function that Pin will use to fetch code bytes to be jitted.
|
|
Call back function when application exits. It is called after all the per thread fini functions were called (registered via PIN_AddThreadFiniFunction). This function may be called on any application thread or internal thread spawned by the tool.
|
|
Call-back function when the application forks.
|
|
Call-back function in probe mode for fork notification.
|
|
Call back function when the tool intercepts a signal with PIN_InterceptSignal().
|
|
Handler (call-back) function when pin/tool generates internal exception. This function can be registered via PIN_AddInternalExceptionHandler() or PIN_TryStart(). This function becomes active only after APPLICATION_START_CALLBACK notification is delivered. Any internal exception prior to this event can't be handled. If the exception occurred while analysis routine is executed, it is legal to modify the execution control path using functions such as PIN_RaiseException() or PIN_ExecuteAt(). In this case, any per-thread INTERNAL_EXCEPTION_CALLBACK function registered via PIN_TryStart() will be unregistered automatically (similar semantics to PIN_TryEnd() for all registered notifications)
|
|
Call back function for pin/tool to modify memory address arguments in analysis routines. This feature allows users to register for a callback immediately prior to an analysis routine which gets one of the four IARG_MEMORY*_PTR as a parameter. The callback enables the user to manipulate the memory address pointed to by the aforementioned parameter. This function can be registered via PIN_AddMemoryAddressTransFunction(). This function is called from the jitted code, so calls to this function are not serialized.
|
|
Call back function when pin/tool is out of memory. This function can be registered via PIN_AddOutOfMemoryFunction().
|
|
Callback function when probe insertion is complete.
|
|
Call back function when Pin removes all old instrumented code from its cache
|
|
Call-back function when an attached thread starts to run under Pin in probe mode. The tool receives the signal mask at the attach point and can modify it. The changes to this value will be applied when the thread continues to run. Pin does not validate the new signal mask so tools must take extra care when modifying this value.
|
|
Call-back function before an application thread is being detached from Pin in probe mode. The callback is received in the thread native context before probes removal.
|
|
Call-back function when thread ends.
|
|
Call-back function when thread begins.
|
|
|
Possible return values of the INTERNAL_EXCEPTION_CALLBACK exception filter function
|
|
time of callback notification |
|
List of supported modes of symbolic information delivery. Used in PIN_InitSymbolsAlt().
|
|
Register a notification function that is called after pin initialization is finished. This notification function is available when pin launches the application and when pin attaches to a running process. When pin launches the application, this notification function is called on the application's main thread.
When pin attaches to a running process, this notification function is called on a dedicated thread which is not part of the application's threads.
When Pin starts running a program, it calls into the tool several times in the following order:
|
|
Register a notification function that is called immediately before the application changes context due to receipt of an asynchronous event such as Unix signal or Windows APC.
|
|
Call func immediately before Pin relinquishes control of the application through PIN_Detach(). At this stage no more instrumentation/analysis callbacks will be called This function is called one time for the process. It may be called by any thread. Pin memory is not freed at this moment.
|
|
Register a notification function that is called immediately after Pin relinquishes control of the application through PIN_DetachProbed(). There can be more than one Detach callback function.
|
|
Called to register a function That will become the function that Pin calls to fetch application instructions. Pin sometimes attempt to fetch instructions from an invalid address, and the call-back needs to handle this correctly. If multiple functions are registered using this API, only the last one registered is used Pin cannot automatically detect self-modifying code (SMC) when a tool uses this API. Therefore, such tools take over responsibility for detecting SMC and must invalidate the code cache with CODECACHE_InvalidateRange() if self-modifying code is detected.
|
|
Call func immediately before the application exits. The function is not an instrumentation function--it cannot insert instrumentation. There can be more than one Fini function.
|
|
Register a function to be called when the application is about to exit. The registered function will be executed in a thread that does not hold any thread synchronization lock in Pin. It means that this callback function can be executed concurrently with other Pin callbacks and APIs.
|
|
Register a notification function that is called before a child/exec-ed process is starting to execute NOTE: Only one callback can be registered
|
|
Register a notification handler that is called when the application forks a new process. The function can only be used on Linux.
|
|
Register a notification handler that is called when the application forks a new process. If vfork() is called in application, Pin replaces it with fork(). This replacement is needed to keep Pin/Tool state consistent and prevent memory overlap in callbacks following the fork/vfork. The function can only be used on Linux.
|
|
Register a global (not per-thread) notification handler function that is called upon receipt of any unhandled internal exception in Pin or the tool. This handler does not catch exceptions that are generated by the application, nor does it catch exceptions that are handled by PIN_TryStart() / PIN_TryEnd(). The handler is active for all the application's threads, it should be called in tool's main() before PIN_StartProgram(). If it is called after PIN_StartProgram() is called, it will be ignored. The user can register up to MAX_IEH_CALLBACKS global notification functions.
|
|
Register a callback for modifying memory address arguments that are passed to analysis routines. See MEMORY_ADDR_TRANS_CALLBACK for usage details.
Only one such callback may be registered.
|
|
Register a notification function that is called when pin/tool is out of memory.
A tool can register only one notification function.
|
|
Register a notification function that is called when Pin has inserted all probes.
|
|
This API is useful when Pin is run in probe mode and attaches to a running process. Tools may use this API to register a notification that is called by each application thread. After Pin attaches to the process, Pin first notifies the tool of any images that are loaded (see IMG_AddInstrumentFunction()) and then notifies the tool that initialization is complete (see PIN_AddApplicationStartFunction()). After that, each thread in the application calls the notification set up by PIN_AddThreadAttachProbedFunction(). After each thread returns from this notification, it resumes execution in the application code. Note, this notification happens only for threads that exist in the process at the time that Pin attaches. It does not happen for threads that are created in the process after Pin is already attached.
|
|
This API is useful when Pin runs in probe mode and detaches from a running process. Tools may use this API to register a notification that is called by each application thread before any probes removal. This notification is given in the thread native context. Note, this notification happens only for threads that exist in the process at the time that Pin detaches. It does not happen for threads that are created in the process after Pin is already detached.
|
|
Register a notification function that is called when an application thread terminates. The call-back happens even for the application's root (initial) thread. The notification call-back will often happen on the physical thread that is exiting, but under some circumstances it will be called on a different physical thread.
|
|
Register a notification function that is called when a thread starts executing in the application. The call-back happens even for the application's root (initial) thread.
|
|
Initiate Pin attach request in probe mode. If Pin was not detached (using PIN_DetachProbed()) this function will be ignored.
|
|
This API allows a tool to call a function inside the application. The function is executed under control of Pin's JIT compiler, and the application code is instrumented normally. Tools should not make direct calls to application functions when Pin is in JIT mode. PIN_CallApplicationFunction() can be called from a replacement routine or an analysis routine, but not from a call-back. Note that this API can result in recursive execution in the tool since the called application function is also instrumented. One usage model for this API is to "wrap" an application function, executing analysis code before the function is called and after it returns. To do this, use RTN_ReplaceSignature() to replace the application function, use IARG_ORIG_FUNCPTR to pass the original function pointer to the replacement routine, and use IARG_CONST_CONTEXT to pass the register state. You can then call back on the original function from your replacement routine with PIN_CallApplicationFunction(). Note, however, that the overhead of PIN_CallApplicationFunction() can be high, so it is more efficient to use *_InsertCall() instead if possible.
|
|
Given an address, this API checks whether the memory page which contains this address has a read access protection.
|
|
Given an address, this API checks whether the memory page which contains this address has a write access protection.
|
|
Pin relinquishes control of the application and the original un-instrumented code is executed. On Linux, the function may be invoked from analysis, instrumentation or callback routines. It may be executed by any thread, including threads spawned by the Pintool which are invisible to the Pin VM. On Windows and OS X*, the function must be invoked from an analysis routine. Invoking the function from instrumentation routines could cause Pin to misbehave. See Tests/detach.C for an example of its use. The request for detach is considered by Pin as asynchronous. This means that Pin will perform the detach procedure at a point which it considers convenient to do so. From the user's perspective, instrumentation, analysis or callback routines might still be executed after calling PIN_Detach(). In practice, PIN_Detach() simply registers the request to the Pin VM and exits immediately i.e. the function does not wait for detach to complete. Once Pin starts the detach procedure, it can't be blocked, and will not run forever. It is not possible to detach one thread. All threads will run natively after PIN_Detach(). During detach, Pin doesn't free memory used for Pin objects. This memory will be used during re-attach. During the detach procedure Pin runs an auxiliary process, which communicates with the running application process via debug interface. The auxiliary process is temporary and will exit immediately when the detach procedure is completed. For the user, this means that a debugger cannot be attached to the application process during detach.
Use PIN_AddDetachFunction() to receive a notification just prior to detach. The callback will be received after all the threads are stopped inside the VM and no more instrumentation functions, analysis routines or callbacks will be called.
|
|
Initiate Pin detach request in probe mode. In the scope of this operation, Pin removes all probes set by Pin & tool, The user can get a notification when the detach operation has been completed (via callback registration using PIN_AddDetachFunctionProbed()). On Linux, the user can get additional per-thread callbacks just prior to probes removal. (via callback registration using PIN_AddThreadDetachProbedFunction()).These callbacks will be given for each thread in its native context. If Pin has already detached (using PIN_DetachProbed()), or if Pin has not fully started yet (the notification function registered by PIN_AddApplicationStartFunction() was not yet delivered to the tool), this function will be ignored.
|
|
A function to fetch the code raw bytes. This function should be used when the tool needs the raw bytes of instructions and the tool is using a code fetcher function that translates the original code address to an actual code address.
|
|
This function is useful when the tool that use attach is doing some initial work that needs the number of threads at the time of the attach.
|
|
Get the Registered notification function that is called when tool needs to modify memory address in PIN.
|
|
Initialize Pin system. Must be called before PIN_StartProgram
|
|
Initialize symbol table code. Pin does not read symbols unless this is called. Must be called before PIN_StartProgram
|
|
Initialize symbol table code with an explicitly specified mode of symbol support.
|
|
Insert a call to an analysis routine relative to a location. In this location we expect to find a safe instruction, i.e. an instruction which is large enough to be replaced entirely with a jump instruction (i.e. 5/7 bytes long), it is not a control flow instruction, and it doesn't have memory operand.
Some restrictions apply when using IARG_CONTEXT. See Instrumentation arguments for more information. IARG_THREAD_ID is not supported.
|
|
Establish an interceptor function for signals delivered to the application. Tools should never call sigaction() directly to handle signals. The interceptor function is called whenever the application receives the requested signal, regardless of whether the application has a handler for that signal. The tool's handler can then decide whether the signal should be forwarded to the application. There are two intended usage models for this API, which are both advanced features. If your tool merely needs to be notified of signals that are sent to the application, use PIN_AddContextChangeFunction() instead. In one usage model, a tool can take over ownership of a signal in order to use the signal as an asynchronous communication mechanism to the outside world. For example, if a tool intercepts SIGUSR1, a user of the tool could send this signal and tell the tool to do something. In this usage model, the tool may want to call PIN_UnblockSignal() so that it will receive the signal even if the application attempts to block it. In the second usage model, the tool may need to "squash" certain signals that the application generates. For example, a tool that forces speculative execution in the application may want to intercept and squash exceptions generated in the speculative code. A tool can set only one "intercept" handler for a particular signal, so a new handler overwrites any previous handler for the same signal. To disable a handler, pass a NULL function pointer.
|
|
This function is useful when an analysis routine might block for an indefinite period of time. In such cases, the analysis code can periodically call PIN_IsActionPending() to see if the thread has some pending action that needs to be handled in the Pin VM. If so, the analysis routine should return back to the VM, either by returning or by calling PIN_ExecuteAt().
|
|
|
|
|
|
Check if the given location is safe for probe insertion. This means that the location contains an instruction which is large enough to be replaced entirely with a jump instruction (i.e. 5/7 bytes long), it is not a control flow instruction, and it doesn't have memory operand.
|
|
Some Pin API functions may only be called when the thread is holding this lock. See also PIN_UnlockClient. The client lock is recursive, so can be claimed again by a thread if it already holds it. PIN_LockClient and PIN_UnlockClient calls must be matched, since the lock implementation maintains a depth count.
|
|
Invalidates all the Fini callback functions registered via PIN_AddFiniFunction; Fini callbacks will no longer be called before the application exits. Must be called prior to invoking PIN_Detach if the tool has previously registered Fini callbacks and libc.so is not yet loaded into memory yet for a dynamically linked binary.
|
|
All instrumentation is removed. When application code is executed the instrumentation routines will be called to reinstrument all code. Similarly, any ahead-of-time instrumentation will be reapplied if the relevant code is re-executed.
|
|
Copy the specified number of bytes from a source memory region to a destination memory region. The function guarantees safe return to the caller even if the source or destination regions are inaccessible (entirely or partially). Tools should use this function to ensure safe access to the original content of the application's memory. For example, on Windows, Pin replaces certain TEB fields when running analysis routines in the tool. If the tool accesses these fields directly, it would see the values assigned by Pin rather than the original ones. On the contrary, PIN_SafeCopy() always reads and modifies the original application's values of these fields. This function can be used in any thread, including any internal thread spawned by the tool.
|
|
Copy the specified number of bytes from a source memory region to a destination memory region. The function guarantees safe return to the caller even if the source or destination regions are inaccessible (entirely or partially). In addition to the PIN_SafeCopy functionality, this function allows the tool to obtain detailed exception information in case of failure. This function can be used in any thread, including any internal thread spawned by the tool.
structure.
|
|
Starts executing the application, when Pin is in JIT mode, which is the default. Note that PIN_Init() must be called before PIN_StartProgram(). The PIN_StartProgram() function never returns. It also unwinds the tool's stack, so any local (stack based) variables are lost.
|
|
Starts executing the application, when Pin is in Probe mode. Note that PIN_Init() must be called before PIN_StartProgramProbed(). The PIN_StartProgramProbed() function never returns. It also unwinds the tool's stack, so any local (stack based) variables are lost.
|
|
Returns full path of main Pin tool binary image, encoded in UTF8 (superset of ASCII), this is supported for Windows (only for locales encoded in UTF8)
|
|
Unregister the last registered notification function (registered via PIN_TryStart()) from the context of the calling thread. This function should be called in the same function scope as the previously registered PIN_TryStart().
|
|
Register a per-thread notification handler function that is called upon receipt of an internal exception in pin or the tool in the context of the calling thread. Use PIN_TryEnd() in order to remove the registered handler from the context of the calling thread (do it in the same function scope). The user can register up to MAX_IEH_CALLBACKS per-thread notification functions.
|
|
This API is normally used in conjunction with PIN_InterceptSignal() to prevent the application from blocking a signal that the tool intercepts. This is useful if the tool wants to ensure that the application will not prevent the tool from receiving the intercepted signal. When this API is called before PIN_StartProgram(), it affects all threads in the application. However, if it is called after PIN_StartProgram(), it only affects the calling thread. If the application spawns a thread, the child thread inherits the signal blocking state from its parent. Tools should take care when using this API because it can adversely affect the application if it also uses the signal sig.
|
|
Some Pin API functions may be called only when the thread is holding this lock. See also PIN_LockClient.
|
|
Returns full path of Pin binary invoked, encoded in UTF8 (superset of ASCII), this is supported for Linux (only for locales encoded in UTF8)
|