Controlling and Initializing

Typedefs
typedef VOID(*	LEVEL_PINCLIENT::FORK_PROBE_MODE_CALLBACK )(UINT32 childPid, VOID *v)
typedef VOID(*	LEVEL_PINCLIENT::REMOVE_INSTRUMENTATION_CALLBACK )(VOID *v)
typedef VOID(*	LEVEL_PINCLIENT::DETACH_CALLBACK )(VOID *v)
typedef VOID(*	LEVEL_PINCLIENT::DETACH_PROBED_CALLBACK )(VOID *v)
typedef VOID(*	LEVEL_PINCLIENT::ATTACH_PROBED_CALLBACK )(VOID *v)
typedef VOID(*	LEVEL_PINCLIENT::APPLICATION_START_CALLBACK )(VOID *v)
typedef VOID(*	LEVEL_PINCLIENT::FINI_CALLBACK )(INT32 code, VOID *v)
typedef size_t(*	LEVEL_PINCLIENT::FETCH_CALLBACK )(void *buf, ADDRINT addr, size_t size, VOID *v)
typedef VOID(*	LEVEL_PINCLIENT::OUT_OF_MEMORY_CALLBACK )(size_t size, VOID *v)
typedef VOID(*	LEVEL_PINCLIENT::FORK_CALLBACK )(THREADID threadid, const CONTEXT *ctxt, VOID *v)
typedef VOID(*	LEVEL_PINCLIENT::THREAD_START_CALLBACK )(THREADID threadIndex, CONTEXT *ctxt, INT32 flags, VOID *v)
typedef VOID(*	LEVEL_PINCLIENT::THREAD_ATTACH_PROBED_CALLBACK )(VOID *v)
typedef VOID(*	LEVEL_PINCLIENT::THREAD_FINI_CALLBACK )(THREADID threadIndex, const CONTEXT *ctxt, INT32 code, VOID *v)
typedef VOID(*	LEVEL_PINCLIENT::CONTEXT_CHANGE_CALLBACK )(THREADID threadIndex, CONTEXT_CHANGE_REASON reason, const CONTEXT *from, CONTEXT *to, INT32 info, VOID *v)
typedef VOID(*	LEVEL_PINCLIENT::SYSCALL_ENTRY_CALLBACK )(THREADID threadIndex, CONTEXT *ctxt, SYSCALL_STANDARD std, VOID *v)
typedef VOID(*	LEVEL_PINCLIENT::SYSCALL_EXIT_CALLBACK )(THREADID threadIndex, CONTEXT *ctxt, SYSCALL_STANDARD std, VOID *v)
typedef BOOL(*	LEVEL_PINCLIENT::SIGNAL_INTERCEPT_CALLBACK )(THREADID threadIndex, INT32 sig, CONTEXT *ctxt, BOOL hasHndlr, VOID *v)
typedef VOID(*	LEVEL_PINCLIENT::PROBES_INSERTED_CALLBACK )(IMG img, VOID *v)
Enumerations
enum	LEVEL_PINCLIENT::SYMBOL_INFO_MODE {   LEVEL_PINCLIENT::EXPORT_SYMBOLS,   LEVEL_PINCLIENT::DEBUG_OR_EXPORT_SYMBOLS }
enum	LEVEL_PINCLIENT::FPOINT {   LEVEL_PINCLIENT::FPOINT_BEFORE,   LEVEL_PINCLIENT::FPOINT_AFTER_IN_PARENT,   LEVEL_PINCLIENT::FPOINT_AFTER_IN_CHILD }
enum	CONTEXT_CHANGE_REASON {   CONTEXT_CHANGE_REASON_FATALSIGNAL,   CONTEXT_CHANGE_REASON_SIGNAL,   CONTEXT_CHANGE_REASON_SIGRETURN,   CONTEXT_CHANGE_REASON_APC,   CONTEXT_CHANGE_REASON_EXCEPTION,   CONTEXT_CHANGE_REASON_CALLBACK }
Functions
VOID	LEVEL_PINCLIENT::PIN_AddForkFunctionProbed (FPOINT point, FORK_PROBE_MODE_CALLBACK fun, VOID *val)
VOID	LEVEL_PINCLIENT::PIN_InitSymbols ()
BOOL	LEVEL_PINCLIENT::PIN_InitSymbolsAlt (SYMBOL_INFO_MODE mode)
VOID	LEVEL_PINCLIENT::PIN_AddFollowChildProcessFunction (FOLLOW_CHILD_PROCESS_CALLBACK fun, VOID *val)
BOOL	LEVEL_PINCLIENT::PIN_IsProbeMode ()
VOID	LEVEL_PINCLIENT::PIN_LockClient ()
VOID	LEVEL_PINCLIENT::PIN_UnlockClient ()
VOID	LEVEL_PINCLIENT::PIN_CallApplicationFunction (CONTEXT *ctxt, THREADID threadId, CALLINGSTD_TYPE cstype, AFUNPTR origFunPtr,...)
VOID	LEVEL_PINCLIENT::PIN_AddFiniFunction (FINI_CALLBACK fun, VOID *val)
VOID	LEVEL_PINCLIENT::PIN_AddFetchFunction (FETCH_CALLBACK fun, VOID *val)
VOID	LEVEL_PINCLIENT::PIN_AddOutOfMemoryFunction (OUT_OF_MEMORY_CALLBACK fun, VOID *val)
VOID	LEVEL_PINCLIENT::PIN_AddDetachFunction (DETACH_CALLBACK fun, VOID *val)
VOID	LEVEL_PINCLIENT::PIN_AddDetachFunctionProbed (DETACH_PROBED_CALLBACK fun, VOID *val)
VOID	LEVEL_PINCLIENT::PIN_AddThreadStartFunction (THREAD_START_CALLBACK fun, VOID *val)
VOID	LEVEL_PINCLIENT::PIN_AddThreadAttachProbedFunction (THREAD_ATTACH_PROBED_CALLBACK fun, VOID *val)
VOID	LEVEL_PINCLIENT::PIN_AddApplicationStartFunction (APPLICATION_START_CALLBACK fun, VOID *val)
VOID	LEVEL_PINCLIENT::PIN_AddThreadFiniFunction (THREAD_FINI_CALLBACK fun, VOID *val)
VOID	LEVEL_PINCLIENT::PIN_AddContextChangeFunction (CONTEXT_CHANGE_CALLBACK fun, VOID *val)
VOID	LEVEL_PINCLIENT::PIN_AddSyscallEntryFunction (SYSCALL_ENTRY_CALLBACK fun, VOID *val)
VOID	LEVEL_PINCLIENT::PIN_AddSyscallExitFunction (SYSCALL_EXIT_CALLBACK fun, VOID *val)
BOOL	LEVEL_PINCLIENT::PIN_AddSignalInterceptFunction (INT32 sig, SIGNAL_INTERCEPT_CALLBACK fun, VOID *val)
VOID	LEVEL_PINCLIENT::PIN_AddProbesInsertedFunction (PROBES_INSERTED_CALLBACK fun, VOID *val)
BOOL	LEVEL_PINCLIENT::PIN_AddForkFunction (FPOINT point, FORK_CALLBACK fun, VOID *val)
VOID	LEVEL_PINCLIENT::PIN_RemoveInstrumentation ()
VOID	LEVEL_PINCLIENT::PIN_RemoveFiniFunctions ()
VOID	LEVEL_PINCLIENT::PIN_Detach ()
VOID	LEVEL_PINCLIENT::PIN_DetachProbed ()
VOID	LEVEL_PINCLIENT::PIN_AttachProbed (ATTACH_PROBED_CALLBACK fun, VOID *val)
VOID	LEVEL_PINCLIENT::PIN_StartProgram ()
VOID	LEVEL_PINCLIENT::PIN_StartProgramProbed ()
BOOL	LEVEL_PINCLIENT::PIN_Init (INT32 argc, CHAR **argv)
CHAR *	LEVEL_PINCLIENT::PIN_VmFullPath ()
size_t	LEVEL_PINCLIENT::PIN_SafeCopy (VOID *dst, const VOID *src, size_t size)
size_t	LEVEL_PINCLIENT::PIN_SafeCopyEx (VOID *dst, const VOID *src, size_t size, EXCEPTION_INFO *pExceptInfo)

---

Detailed Description

This group of functions is used to initialize Pin, start the application, and a call backs for events like application exit.

---

Typedef Documentation

typedef VOID(* LEVEL_PINCLIENT::APPLICATION_START_CALLBACK)(VOID *v)

Call back function when pin initialization is finished. Parameters: [in]  v  The tool's call-back value.

typedef VOID(* LEVEL_PINCLIENT::ATTACH_PROBED_CALLBACK)(VOID *v)

Call back function when Pin attaches to application in Probe mode Parameters: [in]  v  The tool's call-back value.

typedef VOID(* LEVEL_PINCLIENT::CONTEXT_CHANGE_CALLBACK)(THREADID threadIndex, CONTEXT_CHANGE_REASON reason, const CONTEXT *from, CONTEXT *to, INT32 info, VOID *v)

Call-back function when application changes context. Parameters: [in]  threadIndex  The Pin thread ID of the thread that changes contexts. [in]  reason  Cause of the context change. [in]  from  Application's register state prior to the context change (NULL if reason is CONTEXT_CHANGE_REASON_CALLBACK). [in]  to  Application's register state after context change (NULL if reason is CONTEXT_CHANGE_REASON_FATALSIGNAL). The tool may change this and affect the new register state. [in]  info  Additional information (depends on reason): CONTEXT_CHANGE_REASON_FATALSIGNAL: The Unix signal number. CONTEXT_CHANGE_REASON_SIGNAL: The Unix signal number. CONTEXT_CHANGE_REASON_EXCEPTION: The Windows exception code. [in]  v  The tool's call-back value.

typedef VOID(* LEVEL_PINCLIENT::DETACH_CALLBACK)(VOID *v)

Call back function when Pin detaches from application in JIT mode Parameters: [in]  v  The tool's call-back value.

typedef VOID(* LEVEL_PINCLIENT::DETACH_PROBED_CALLBACK)(VOID *v)

Call back function when Pin detaches from application in Probe mode Parameters: [in]  v  The tool's call-back value.

typedef size_t(* LEVEL_PINCLIENT::FETCH_CALLBACK)(void *buf, ADDRINT addr, size_t size, VOID *v)

Call back function that PIN will use to fetch code bytes to be jitted. Parameters: [out]  buf  A buffer which receives the fetched instruction bytes. This buffer is at least size bytes long. [in]  addr  Starting address from which instruction bytes should be fetched. [in]  size  The number of bytes that should be fetched. [in]  v  The tool's call-back value. Returns: The number of bytes sucessfully fetched into buf. This may be less than size (or even zero) if Pin attempts to fetch instructions from an invalid address.

typedef VOID(* LEVEL_PINCLIENT::FINI_CALLBACK)(INT32 code, VOID *v)

Call back function when application exits Parameters: [in]  code  O/S specific termination code for the application. [in]  v  The tool's call-back value.

typedef VOID(* LEVEL_PINCLIENT::FORK_CALLBACK)(THREADID threadid, const CONTEXT *ctxt, VOID *v)

Call-back function when the application forks. Parameters: [in]  threadId  Thread index [in]  ctxt  Register state immediately before/after the fork. [in]  v  The tool's call-back value.

typedef VOID(* LEVEL_PINCLIENT::FORK_PROBE_MODE_CALLBACK)(UINT32 childPid, VOID *v)

Call-back function in probe mode for fork notification. Parameters: [in]  childPid  Process id of the child process, available after fork in parent [in]  v  The tool's call-back value.

typedef VOID(* LEVEL_PINCLIENT::OUT_OF_MEMORY_CALLBACK)(size_t size, VOID *v)

Call back function when pin /pin tool is out of memory Parameters: [in]  size  Size of the failed allocation [in]  v  The tool's call-back value

typedef VOID(* LEVEL_PINCLIENT::PROBES_INSERTED_CALLBACK)(IMG img, VOID *v)

Callback function when probe insertion is complete. Parameters: [in]  img  Image. [in]  v  The tool's call-back value.

typedef VOID(* LEVEL_PINCLIENT::REMOVE_INSTRUMENTATION_CALLBACK)(VOID *v)

Call back function when Pin removes all old instrumented code from its cache Parameters: [in]  v  The tool's call-back value.

typedef BOOL(* LEVEL_PINCLIENT::SIGNAL_INTERCEPT_CALLBACK)(THREADID threadIndex, INT32 sig, CONTEXT *ctxt, BOOL hasHndlr, VOID *v)

Call back function when tool creates its own signal handler. Parameters: threadIndex  The Pin thread ID of the thread that handled the signal. sig  The signal number. ctxt  Application's register state when it was interrupted by the signal. The tool may change this context if desired. If so, the application continues at the modified context. Or, if the application's signal handler is envoked, that handler returns to the modified context. hndlr  Boolean indicating if the application has a registered signal handler. v  The tool's call-back value. Returns: Returning TRUE tells Pin to pass the signal on to the application's handler (if any). If the tool returns FALSE or if the application has no handler, execution continues at ctxt.

typedef VOID(* LEVEL_PINCLIENT::SYSCALL_ENTRY_CALLBACK)(THREADID threadIndex, CONTEXT *ctxt, SYSCALL_STANDARD std, VOID *v)

Call-back function before execution of a system call. Parameters: [in]  threadIndex  The Pin thread ID of the thread that executes the system call. [in,out]  ctxt  Application's register state immediately before execution of the system call. The tool may change this and affect the new register state. [in]  std  The system calling standard. [in]  v  The tool's call-back value.

typedef VOID(* LEVEL_PINCLIENT::SYSCALL_EXIT_CALLBACK)(THREADID threadIndex, CONTEXT *ctxt, SYSCALL_STANDARD std, VOID *v)

Call-back function after execution of a system call. Parameters: [in]  threadIndex  The Pin thread ID of the thread that executed the system call. [in,out]  ctxt  Application's register state immediately after execution of the system call.The tool may change this and affect the new register state. [in]  std  The system calling standard. [in]  v  The tool's call-back value.

typedef VOID(* LEVEL_PINCLIENT::THREAD_ATTACH_PROBED_CALLBACK)(VOID *v)

Call-back function when an attached thread starts to run under Pin in probe mode. Parameters: [in]  v  The tool's call-back value.

typedef VOID(* LEVEL_PINCLIENT::THREAD_FINI_CALLBACK)(THREADID threadIndex, const CONTEXT *ctxt, INT32 code, VOID *v)

Call-back function when thread ends. Parameters: [in]  threadIndex  The Pin thread ID of the terminating thread. [in]  ctxt  Register state of the thread immediately before it terminates. [in]  code  O/S specific termination code for the thread. [in]  v  The tool's call-back value.

typedef VOID(* LEVEL_PINCLIENT::THREAD_START_CALLBACK)(THREADID threadIndex, CONTEXT *ctxt, INT32 flags, VOID *v)

Call-back function when thread begins. Parameters: [in]  threadIndex  The Pin thread ID of the new thread. [in]  ctxt  Initial register state for the new thread. The tool may change this. [in]  flags  O/S specific flags for the new thread. [in]  v  The tool's call-back value.

---

Enumeration Type Documentation

enum CONTEXT_CHANGE_REASON

Possible reasons for an application context change. Enumerator: CONTEXT_CHANGE_REASON_FATALSIGNAL  Receipt of fatal Unix signal. CONTEXT_CHANGE_REASON_SIGNAL  Receipt of handled Unix signal. CONTEXT_CHANGE_REASON_SIGRETURN  Return from Unix signal handler. CONTEXT_CHANGE_REASON_APC  Receipt of Windows APC. CONTEXT_CHANGE_REASON_EXCEPTION  Receipt of Windows exception. CONTEXT_CHANGE_REASON_CALLBACK  Receipt of Windows call-back.

enum LEVEL_PINCLIENT::FPOINT

time of callback notification Enumerator: FPOINT_BEFORE  Call-back in parent, just before fork. FPOINT_AFTER_IN_PARENT  Call-back in parent, immediately after fork. FPOINT_AFTER_IN_CHILD  Call-back in child, immediately after fork.

enum LEVEL_PINCLIENT::SYMBOL_INFO_MODE

List of supported modes of symbolic information delivery. Used in PIN_InitSymbolsAlt() Enumerator: EXPORT_SYMBOLS  Only symbols taken from export table are provided. DEBUG_OR_EXPORT_SYMBOLS  First debug symbols if available, otherwise export symbols.

---

Function Documentation

VOID LEVEL_PINCLIENT::PIN_AddApplicationStartFunction (  APPLICATION_START_CALLBACK  fun, VOID *  val )

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 it is called, all the application's threads are running. When Pin starts running a program in Probe mode, it calls into the tool several times in the following order: 1. Calls the tool's main() function. 2. If the tool set up a notification with IMG_AddInstrumentFunction(), Pin calls this call-back for each image that is already loaded in the application's address space at the point when Pin attaches to it. 3. Calls any notification call-backs set up with PIN_AddApplicationStartFunction(). Parameters: [in]  fun  Function to be called at application start. [in]  val  Value to pass to the function. Availability: Mode: Probe O/S: Windows CPU: IA32, Intel64

VOID LEVEL_PINCLIENT::PIN_AddContextChangeFunction (  CONTEXT_CHANGE_CALLBACK  fun, VOID *  val )

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. Parameters: [in]  fun  Call-back function to execute immediately before the application changes context. [in]  val  Value to pass to the function. Availability: Mode: JIT O/S: Linux, Windows CPU: All

VOID LEVEL_PINCLIENT::PIN_AddDetachFunction (  DETACH_CALLBACK  fun, VOID *  val )

Call func immediately before Pin relinquishes control of the application through PIN_Detach(). The function is not an instrumentation function. There can be more than one Detach function. Parameters: fun  Call back function to execute before detaching val  Value to be passed to fun when it is called Availability: Mode: JIT O/S: Linux CPU: All

VOID LEVEL_PINCLIENT::PIN_AddDetachFunctionProbed (  DETACH_PROBED_CALLBACK  fun, VOID *  val )

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. When this callback function is called, it is guarnteed that Pin removed all probes from the application code and that no other callbcak function will be called afterwards (except from additional Detach callback functions). Parameters: fun  Call back function to execute before detaching val  Value to be passed to fun when it is called Availability: Mode: Probe O/S: Windows CPU: All

VOID LEVEL_PINCLIENT::PIN_AddFetchFunction (  FETCH_CALLBACK  fun, VOID *  val )

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. Parameters: [in]  fun  The tool's call-back function. [in]  val  The tool's call-back value. Availability: Mode: JIT O/S: Linux, Windows & MacOS CPU: All

VOID LEVEL_PINCLIENT::PIN_AddFiniFunction (  FINI_CALLBACK  fun, VOID *  val )

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. Parameters: fun  Call back function is passed exit code and val val  Value to be passed to fun when it is called Availability: Mode: JIT O/S: Linux, Windows & MacOS CPU: All

VOID LEVEL_PINCLIENT::PIN_AddFollowChildProcessFunction (  FOLLOW_CHILD_PROCESS_CALLBACK  fun, VOID *  val )

Register a notification function that is called before a child/exec-ed process is starting to execute NOTE: Only one callback can be registered Parameters: [in]  fun  Call-back function [in]  val  Value to pass to the function Availability: Mode: JIT & Probe O/S: Windows, Linux CPU: All

BOOL LEVEL_PINCLIENT::PIN_AddForkFunction (  FPOINT  point, FORK_CALLBACK  fun, VOID *  val )

Register a notification handler that is called when the application forks a new process. Parameters: [in]  where  Tells when to make the call-back and tells whether the parent or child makes the call-back. [in]  fun  Call-back function to execute. [in]  v  Value passed as final parameter to call-back. Returns: TRUE if succeeds, FALSE otherwise Note: Function always return FALSE on Windows Availability: Mode: JIT O/S: Linux CPU: All

VOID LEVEL_PINCLIENT::PIN_AddForkFunctionProbed (  FPOINT  point, FORK_PROBE_MODE_CALLBACK  fun, VOID *  val )

Register a notification handler that is called when the application forks a new process. Parameters: [in]  where  Tells when to make the call-back and tells whether the parent or child makes the call-back. [in]  fun  Call-back function to execute. [in]  v  Value passed as final parameter to call-back. Returns: TRUE if succeeds, FALSE otherwise Availability: Mode: Probe O/S: Linux CPU: All

VOID LEVEL_PINCLIENT::PIN_AddOutOfMemoryFunction (  OUT_OF_MEMORY_CALLBACK  fun, VOID *  val )

Register a notification function that is called when pin / pin tool is out of memory. Try to reduce memory consumption when this notification function is called. Any implicit or explicit usage of malloc()/realloc() etc. in this notification function might cause an infinite recursion. The call to the notification function is NOT serialized by pin. A tool can register only one callback function. A new callback registration overwrites any previous registration. To disable the callback, pass a NULL function pointer. Parameters: fun  Call back function is passed the size of the failing allocation val  Value to be passed to fun when it is called Availability: Mode: JIT & PROBE O/S: Linux, Windows & MacOS CPU: All

VOID LEVEL_PINCLIENT::PIN_AddProbesInsertedFunction (  PROBES_INSERTED_CALLBACK  fun, VOID *  val )

Register a notification function that is called when Pin has inserted all probes. Parameters: [in]  img  Image. [in]  fun  Callback function to execute when probe insertion is complete. [in]  val  Value to pass to the function. Availability: Mode: Probe O/S: Linux, Windows CPU: All

BOOL LEVEL_PINCLIENT::PIN_AddSignalInterceptFunction (  INT32  sig, SIGNAL_INTERCEPT_CALLBACK  fun, VOID *  val )

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. Parameters: sig  The signal number to handle. fun  The tool's handler function, or NULL to return ownership of the signal back to the application. val  Value to pass to the handler function. Returns: TRUE if succeeds, FALSE otherwise Note: Intercepting a signal immediately forces the current thread to unblock that signal. This ensures that the application cannot prevent the tool from receiving the signal. Any future threads that the application creates will also be prevented from blocking the signal. However, if there are existing threads in the application when the tool intercepts a signal, those threads will not be prevented from blocking the intercepted signal until some future time. There is no guarantee on when the other threads will unblock the intercepted signal, and they may never do so if they are permanently blocked in a system call. To avoid this problem, it is safest to call PIN_AddSignalInterceptFunction() before starting the application with PIN_StartProgram(). Function always return FALSE on Windows Availability: Mode: JIT O/S: Linux CPU: All

VOID LEVEL_PINCLIENT::PIN_AddSyscallEntryFunction (  SYSCALL_ENTRY_CALLBACK  fun, VOID *  val )

Register a notification function that is called immediately before execution of a system call. Parameters: [in]  fun  Function to be called immediately before execution of a system call. [in]  val  Value to pass to the function. Availability: Mode: JIT O/S: Linux, Windows CPU: All

VOID LEVEL_PINCLIENT::PIN_AddSyscallExitFunction (  SYSCALL_EXIT_CALLBACK  fun, VOID *  val )

Register a notification function that is called immediately after execution of a system call. The notification is called for each system call when it returns to the application, even if the system call changes control flow and does not fall through to the next instruction. Parameters: [in]  fun  Function to be called immediately after execution of a system call. [in]  val  Value to pass to the function. Note: In order to monitor all possible control transfers from the operating system to the user mode application, the tool has to register both a SYSCALL_EXIT_CALLBACK and a CONTEXT_CHANGE_CALLBACK callback functions. This can be done using the corresponding registration functions: PIN_AddSyscallExitFunction() and PIN_AddContextChangeFunction(). When a system call returns to the application, the tool receives the SYSCALL_EXIT_CALLBACK notification. Usually, this callback immediately follows the corresponding SYSCALL_ENTRY_CALLBACK notification and there is no application code executed between these two events. However, some (Windows) system calls can be interrupted by a system event (APC, Windows callback, exception) before they return to the application. If this happens, the tool receives the corresponding CONTEXT_CHANGE_CALLBACK notification just before the (user mode) handler of the system event gets executed. Eventually, when the event handler and the interrupted system call are completed, the SYSCALL_EXIT_CALLBACK notification is delivered to the tool. Availability: Mode: JIT O/S: Linux, Windows CPU: All

VOID LEVEL_PINCLIENT::PIN_AddThreadAttachProbedFunction (  THREAD_ATTACH_PROBED_CALLBACK  fun, VOID *  val )

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. Parameters: [in]  fun  Call-back function to execute for the attached thread. [in]  val  Value to pass to the function. Availability: Mode: Probe O/S: Linux CPU: All

VOID LEVEL_PINCLIENT::PIN_AddThreadFiniFunction (  THREAD_FINI_CALLBACK  fun, VOID *  val )

Register a notification function that is called when an application thread terminates. The call-back happens even for the application's root (initial) thread. Parameters: [in]  fun  Call-back function to execute for the terminating thread. [in]  val  Value to pass to the function. Availability: Mode: JIT O/S: Linux, Windows & MacOS CPU: All

VOID LEVEL_PINCLIENT::PIN_AddThreadStartFunction (  THREAD_START_CALLBACK  fun, VOID *  val )

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. Parameters: [in]  fun  Call-back function to execute for the new thread. [in]  val  Value to pass to the function. Availability: Mode: JIT O/S: Linux, Windows & MacOS CPU: All

VOID LEVEL_PINCLIENT::PIN_AttachProbed (  ATTACH_PROBED_CALLBACK  fun, VOID *  val )

Initiate Pin attach request in probe mode. If Pin was not detached (using PIN_DetachProbed()) this function will be ignored. The given notification function will be called immediately after Pin regain control of the application. It is expected that in the scope of this callback, the tool will register callbacks (e.g. IMG_AddInstrumentFunction()) and will reconfigure itself (if needed). In order to change tool's KNOB value, use KNOB: Basics Note: Pin's state can't be reconfigured in the scope of the callback function (don't use PIN_Init(), PIN_InitSymbols(), PIN_StartProgramProbed() etc.) Parameters: fun  Call back function to execute when starting to attach val  Value to be passed to fun when it is called Availability: Mode: Probe O/S: Windows CPU: All

VOID LEVEL_PINCLIENT::PIN_CallApplicationFunction (  CONTEXT *  ctxt, THREADID  threadId, CALLINGSTD_TYPE  cstype, AFUNPTR  origFunPtr,   ... )

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. Parameters: ctxt  The application register context of the call site. threadId  The Pin id of the current thread (see PIN_ThreadId()) cstype  The calling standard used for compiling this function (CALLINGSTD_DEFAULT recommended). origFunPtr  The entry point of the application function to be called. ...  List of function argument type and size. See PIN_PARG for the recommended method of passing function arguments. PIN_PARG_END() must end the argument list, even if the function has no arguments. If the application function has a return value, it must appear first in the argument list. Availability: Mode: JIT only O/S: Linux and Windows CPU: IA-32 and Intel(R) 64 architectures

VOID LEVEL_PINCLIENT::PIN_Detach (   )

Pin relinquishes control of the application and the original uninstrumented code is executed. To ensure proper behavior 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. Availability: Mode: JIT O/S: Linux, Windows, & MacOS CPU: All

VOID LEVEL_PINCLIENT::PIN_DetachProbed (   )

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. If Pin was already detached (using PIN_DetachProbed()), or if Pin was not started yet (using PIN_StartProgramProbed()), this function will be ignored. Note: Eventhough Pin removes all probes, replacement functions can still be active (for example, if the replacement function is still located on the call stack of one of the threads). It is the tool responsibility to handle these scenarios. Availability: Mode: Probe O/S: Windows CPU: All

BOOL LEVEL_PINCLIENT::PIN_Init (  INT32  argc, CHAR **  argv )

Initialize Pin system. Must be called before PIN_StartProgram Parameters: argc  argc value passed to main argv  argv value passed to main, encoded in UTF8 (a superset of ASCII) Returns: true if an error was detected parsing the command line Availability: Mode: JIT & Probe O/S: Linux, Windows & MacOS CPU: All

VOID LEVEL_PINCLIENT::PIN_InitSymbols (   )

Initialize symbol table code. Pin does not read symbols unless this is called. Must be called before PIN_StartProgram Availability: Mode: JIT & Probe O/S: Linux, Windows & MacOS CPU: All

BOOL LEVEL_PINCLIENT::PIN_InitSymbolsAlt (  SYMBOL_INFO_MODE  mode  )

Initialize symbol table code with explicitly specified mode of symbol support. Pin does not read symbols unless this is called. Must be called before PIN_StartProgram. Alternative to PIN_InitSymbols() on Windows. On Linux & MacOS it is implemented as PIN_InitSymbols() Parameters: [in]  mode  Explicit mode of symbol support. Valid values: EXPORT_SYMBOLS Only symbols taken from export table are provided. Line information is not available. DEBUG_OR_EXPORT_SYMBOLS First debug symbols if available, otherwise export symbols. This mode is set by PIN_InitSymbols() This parameter is ignored on Linux & MacOS. Returns: TRUE if the operation succeeded Availability: Mode: JIT & Probe O/S: Windows, Linux & MacOS CPU: All

BOOL LEVEL_PINCLIENT::PIN_IsProbeMode (   )

Returns: Return TRUE if -probe on command line or if Tool started application calling PIN_StartProgramProbed(). Note: Tool can run in Probe mode without specifying -probe on the command line. This switch is provided as a convenience. In that case, PIN_IsProbeMode() will return FALSE before PIN_StartProgramProbed() was called (Since the default running mode is JIT). Availability: Mode: JIT & Probe O/S: Linux, Windows & MacOS CPU: All

VOID LEVEL_PINCLIENT::PIN_LockClient (   )

Some Pin API functions must be called when the thread is holding this lock. See also PIN_UnlockClient. Availability: Mode: JIT & Probe O/S: Linux, Windows & MacOS CPU: All

VOID LEVEL_PINCLIENT::PIN_RemoveFiniFunctions (   )

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. Availability: Mode: JIT O/S: Linux, Windows & MacOS CPU: All

VOID LEVEL_PINCLIENT::PIN_RemoveInstrumentation (   )

All instrumentation is removed. When application code is executed the instrumentation routines will be called to reinstrument all code. Availability: Mode: JIT O/S: Linux, Windows & MacOS CPU: All

size_t LEVEL_PINCLIENT::PIN_SafeCopy (  VOID *  dst, const VOID *  src, size_t  size )

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. Parameters: [out]  dst  destination region [in]  src  region to copy from [in]  size  number of bytes to copy Returns: Number of bytes successfully copied from the source to the destination region. Availability: Mode: JIT O/S: Linux, Windows CPU: All

size_t LEVEL_PINCLIENT::PIN_SafeCopyEx (  VOID *  dst, const VOID *  src, size_t  size, EXCEPTION_INFO *  pExceptInfo )

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. Parameters: [out]  dst  destination region [in]  src  region to copy from [in]  size  number of bytes to copy [out]  pExceptInfo  pointer to the structure that receives the exception information in case of failure. Returns: Number of bytes successfully copied from the source to the destination region. If the function fails to copy all bytes, it provides detailed description of the failure in the structure. Note: The exception address in the returned exception information always has zero value. If the tool wants to raise this exception on behalf of the application, it should use PIN_SetExceptionAddress function to set an appropriate exception address before passing the exception information to the PIN_RaiseException function. Availability: Mode: JIT O/S: Linux, Windows CPU: All

VOID LEVEL_PINCLIENT::PIN_StartProgram (   )

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. Availability: Mode: JIT O/S: Linux, Windows & MacOS CPU: All

VOID LEVEL_PINCLIENT::PIN_StartProgramProbed (   )

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. Availability: Mode: Probe O/S: Linux, Windows & MacOS CPU: All

VOID LEVEL_PINCLIENT::PIN_UnlockClient (   )

Some Pin API functions must be called when the thread is holding this lock. See also PIN_LockClient. Availability: Mode: JIT & Probe O/S: Linux, Windows & MacOS CPU: All

CHAR* LEVEL_PINCLIENT::PIN_VmFullPath (   )

Returns full path of Pin binary invoked, encoded in UTF8 (superset of ASCII), this is supported for Linux (only for locales encoded in UTF8) Availability: Mode: JIT O/S: Linux & MacOS CPU: All

---