Controlling and Initializing

Typedefs
typedef VOID(*	LEVEL_PINCLIENT::REMOVE_INSTRUMENTATION_CALLBACK )(VOID *v)
typedef VOID(*	LEVEL_PINCLIENT::DETACH_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_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)
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_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_AddThreadStartFunction (THREAD_START_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)
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_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)

---

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::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 a 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

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 recieves 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

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::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::REMOVE_INSTRUMENTATION_CALLBACK)(VOID *v)

Call back function when Pin removes all old instrumented code from its cache

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_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 thread 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_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_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

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_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_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 properly switched. 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 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

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 (   )

Return TRUE if -probe on command line. Tool can run in Probe mode without specifying -probe on the command line. This switch is provided as a convenience. Returns: TRUE if -probe is present on the copmmand line; FALSE otherwise. 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). Use of this function also guarantees that the tool reads or writes the values used by the application. For example, on Windows, Pin replaces certain TEB fields when running a tool's analysis code. If the tool accessed these fields directly, it would see the modified values rather than the original ones. Using PIN_SafeCopy() allows the tool to read or write the application's values for these fields. We recommend using this API any time a tool reads or writes application memory. 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

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

---