|
|
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
|
|
|
Call-back function when the application forks.
|
|
|
Call-back function in probe mode for fork notification.
|
|
|
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 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 tool creates its own signal handler.
|
|
|
Call-back function before execution of a system call.
|
|
|
Call-back function after execution of a system call.
|
|
|
Call-back function when an attached thread starts to run under Pin in probe mode.
|
|
|
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 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 global (not per-thread) notification handler function that is called upon receipt of internal exception of pin/tool. This function 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 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.
|
|
||||||||||||||||
|
Takes over ownership of a signal for the tool and establishes a tool handler for the signal. Tools should never call sigaction() directly to handle signals. Use this function to take over "ownership" of a signal. If you want to be notified when the application receives a signal, use PIN_AddContextChangeFunction() instead. Tools should take care when intercepting signals, because this can adversely affect the application if it also uses the signal. The application is still allowed to set up its own handler for an intercepted signal. However, the application is prevented from attempts to block the signal. When an intercepted signal is received, the tool's handler is called first. The tool's handler then decides whether the signal should be forwarded to the application's handler (if any). 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.
|
|
||||||||||||
|
Register a notification function that is called immediately before execution of a system call.
|
|
||||||||||||
|
Register a notification function that is called immediately after execution of a system call.
|
|
||||||||||||
|
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.
|
|
||||||||||||
|
Register a notification function that is called when an application thread terminates. The call-back happens even for the application's root (initial) 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. PIN_CallApplicationFunction() can be called from a replacement routine or an analysis routine. Pin restores the application context before calling the application function and then restores the tool context before returning to the replacement/analysis function. Tools should not call application functions directly because the context will not be switched properly. Note that if the tool changes the application register context using PIN_SetContextReg(), and pass this context to PIN_CallApplicationFunction(), the updated context will be used by the application function. RTN_ReplaceSignature() should be used to replace the application routine, passing the application context and the original function pointer as additional arguments to the replacement function. RTN_InsertCall() should be used to access the analysis routine, passing the application context and the original function pointer as arguments.
|
|
|
Pin relinquishes control of the application and the original uninstrumented code is executed. On Linux: This routine may be invoked in JIT mode from analysis or instrumentation routine. It also can be invoked from a callback or from any special thread, dedicated by Pin tool and invisible for Pin VM. The request for detach is considered in Pin as asynchronous. PIN_Detach() sets the request inside Pin and exits immediately. Note, the PIN_Detach() procedure does not wait for detach completion. From user's perspective, calling to PIN_Detach() doesn't mean that instrumentation function, analysis routines or callbacks will not be called any more. Since PIN_Detach() is called, Pin performs detach at a point convenient for this procedure. Detach process, started by Pin can't be blocked, and will not run forever. User can't detach one thread; all threads are running natively after PIN_Detach(). PIN_AddDetachFunction() lets user to receive notification when detach is completed. At this momment Pin notifyes that all threads are stopped inside VM and no more instrumentation function, analysis routines or callbacks will be called. Actually, Pin doesn't free memory used for Pin objects. But in the future, when re-attach will be possible, this memory will be reused. Pin runs an auxiliary process, which communicates with the running application process via debug interface. The auxiliary process is temporary and exits immediately when detach is completed. But for user it means that debugger can not be attached to application process at this time. On Windows amd Mac Os the function must be invoked through an analysis routine. Invoking via instrumentation routines could cause Pin to misbehave See Tests/detach.C for an example of its use.
|
|
|
Initiate Pin detach request in probe mode. The user can get a notification when the detach operation has been completed (via callback registration using PIN_AddDetachFunctionProbed()). In the scope of this operation, Pin removes all probes set by Pin & tool, in addition, it guarantees that no callback function registered previously by the tool will be called.
|
|
||||||||||||
|
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 explicitly specified mode of symbol support.
|
|
|
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().
|
|
|
|
|
|
Some Pin API functions must be called when the thread is holding this lock. See also PIN_UnlockClient.
|
|
|
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.
|
|
||||||||||||||||
|
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.
|
|
||||||||||||||||||||
|
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.
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.
|
|
|
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 per-thread notification handler function that is called upon receipt of internal exception of pin/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.
|
|
|
Some Pin API functions must be called 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)
|
1.4.6