Controlling and Initializing

Typedefs
typedef INT32	LEVEL_PINCLIENT::THREADID
typedef VOID(*	LEVEL_PINCLIENT::REMOVE_INSTRUMENTATION_CALLBACK )(VOID *v)
typedef VOID(*	LEVEL_PINCLIENT::DETACH_CALLBACK )(VOID *v)
typedef VOID(*	LEVEL_PINCLIENT::FINI_CALLBACK )(INT32 code, VOID *v)
typedef VOID(*	LEVEL_PINCLIENT::FORK_CALLBACK )(INT32 threadid, const CONTEXT *ctxt, VOID *v)
typedef VOID(*	LEVEL_PINCLIENT::THREAD_BEGIN_CALLBACK )(UINT32 threadIndex, VOID *sp, int flags, VOID *v)
typedef VOID(*	LEVEL_PINCLIENT::THREAD_END_CALLBACK )(UINT32 threadIndex, INT32 code, VOID *v)
typedef VOID(*	LEVEL_PINCLIENT::SIGNAL_BEFORE_CALLBACK )(INT32 threadIndex, INT32 sig, const CONTEXT *ctxtFrom, const CONTEXT *ctxtTo, VOID *v)
typedef VOID(*	LEVEL_PINCLIENT::SIGNAL_AFTER_CALLBACK )(INT32 threadIndex, const CONTEXT *ctxtFrom, const CONTEXT *ctxtTo, VOID *v)
typedef BOOL(*	LEVEL_PINCLIENT::SIGNAL_INTERCEPT_CALLBACK )(INT32 threadIndex, INT32 sig, CONTEXT *ctxt, BOOL hasHndlr, VOID *v)
Enumerations
enum	LEVEL_PINCLIENT::FPOINT {   LEVEL_PINCLIENT::FPOINT_BEFORE,   LEVEL_PINCLIENT::FPOINT_AFTER_IN_PARENT,   LEVEL_PINCLIENT::FPOINT_AFTER_IN_CHILD }
Functions
VOID	LEVEL_PINCLIENT::PIN_InitSymbols ()
VOID	LEVEL_PINCLIENT::PIN_RemoveAllProbes ()
VOID	LEVEL_PINCLIENT::PIN_InsertProbe (ADDRINT src_addr, ADDRINT dst_addr)
VOID	LEVEL_PINCLIENT::PIN_RemoveProbe (ADDRINT address)
THREADID	LEVEL_PINCLIENT::PIN_ThreadId ()
VOID	LEVEL_PINCLIENT::PIN_LockClient ()
VOID	LEVEL_PINCLIENT::PIN_UnlockClient ()
VOID	LEVEL_PINCLIENT::PIN_AddFiniFunction (FINI_CALLBACK fun, VOID *val)
VOID	LEVEL_PINCLIENT::PIN_AddDetachFunction (DETACH_CALLBACK fun, VOID *val)
VOID	LEVEL_PINCLIENT::PIN_AddThreadBeginFunction (THREAD_BEGIN_CALLBACK fun, VOID *val)
VOID	LEVEL_PINCLIENT::PIN_AddThreadEndFunction (THREAD_END_CALLBACK fun, VOID *val)
VOID	LEVEL_PINCLIENT::PIN_AddSignalBeforeFunction (SIGNAL_BEFORE_CALLBACK fun, VOID *val)
VOID	LEVEL_PINCLIENT::PIN_AddSignalAfterFunction (SIGNAL_AFTER_CALLBACK fun, VOID *val)
VOID	LEVEL_PINCLIENT::PIN_AddSignalInterceptFunction (INT32 sig, SIGNAL_INTERCEPT_CALLBACK fun, VOID *val)
VOID	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_StartProbedProgram ()
VOID	LEVEL_PINCLIENT::PIN_StartProgramProbed ()
BOOL	LEVEL_PINCLIENT::PIN_Init (INT32 argc, CHAR **argv)
VOID	LEVEL_PINCLIENT::GetVmLock ()
VOID	LEVEL_PINCLIENT::ReleaseVmLock ()

---

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

Call back function when Pin detaches from application

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

Call back function when application exits

typedef VOID(* LEVEL_PINCLIENT::FORK_CALLBACK)(INT32 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::REMOVE_INSTRUMENTATION_CALLBACK)(VOID *v)

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

typedef VOID(* LEVEL_PINCLIENT::SIGNAL_AFTER_CALLBACK)(INT32 threadIndex, const CONTEXT *ctxtFrom, const CONTEXT *ctxtTo, VOID *v)

Call back function when application signal handler returns. Parameters: threadIndex  The Pin thread ID of the thread that handled the signal. ctxtFrom  Application's register state at end of handler. ctxtTo  Application's register state to which the handler is returning. v  The tool's call-back value.

typedef VOID(* LEVEL_PINCLIENT::SIGNAL_BEFORE_CALLBACK)(INT32 threadIndex, INT32 sig, const CONTEXT *ctxtFrom, const CONTEXT *ctxtTo, VOID *v)

Call back function when application handles a signal. Parameters: threadIndex  The Pin thread ID of the thread that handles the signal. sig  The signal number. ctxtFrom  Application's register state when it was interrupted by the signal. ctxtTo  Application's register state at start of handler. v  The tool's call-back value.

typedef BOOL(* LEVEL_PINCLIENT::SIGNAL_INTERCEPT_CALLBACK)(INT32 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::THREAD_BEGIN_CALLBACK)(UINT32 threadIndex, VOID *sp, int flags, VOID *v)

Call back function when thread begins

typedef VOID(* LEVEL_PINCLIENT::THREAD_END_CALLBACK)(UINT32 threadIndex, INT32 code, VOID *v)

Call back function when thread ends

typedef INT32 LEVEL_PINCLIENT::THREADID

Not implemented yet.

---

Enumeration Type Documentation

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.

---

Function Documentation

VOID LEVEL_PINCLIENT::GetVmLock (   )

For experts only!

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

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

VOID 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.

VOID LEVEL_PINCLIENT::PIN_AddSignalAfterFunction (  SIGNAL_AFTER_CALLBACK  fun, VOID *  val )

Register a notification function that is called immediately after the application returns from a signal handler. This notification only occurs if the application returns "normally" from the signal handler. If the application jumps out of its handler early (e.g. via longjmp), the notification does not occur. Parameters: fun  Call back function to execute immediately after the application's signal handler. val  Value to pass to the function.

VOID LEVEL_PINCLIENT::PIN_AddSignalBeforeFunction (  SIGNAL_BEFORE_CALLBACK  fun, VOID *  val )

Register a notification function that is called immediately before the application jumps to a signal handler. The tool is only notified of a signal that the application actually handles. Unhandled signals do not trigger a notification. Parameters: fun  Call back function to execute immediately before the application's signal handler. val  Value to pass to the function.

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

VOID LEVEL_PINCLIENT::PIN_AddThreadBeginFunction (  THREAD_BEGIN_CALLBACK  fun, VOID *  val )

Call func immediately after a new thread has been created Parameters: fun  Call back function to execute after new thread has been created val  Value to be passed to fun when it is called

VOID LEVEL_PINCLIENT::PIN_AddThreadEndFunction (  THREAD_END_CALLBACK  fun, VOID *  val )

Call func immediately before a thread ends Parameters: fun  Call back function to execute before new thread ends val  Value to be passed to fun when it is called

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.

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 Returns: true if an error was detected parsing the command line

VOID LEVEL_PINCLIENT::PIN_InitSymbols (   )

Initialize symbol table code. Pin does not read symbols unless this is called. Must be called before PIN_StartProgram

VOID LEVEL_PINCLIENT::PIN_InsertProbe (  ADDRINT  src_addr, ADDRINT  dst_addr )

Insert a probe at an address Parameters: src_addr  Address to insert the probe at dst_addr  Target to where the probe should point to

VOID LEVEL_PINCLIENT::PIN_LockClient (   )

Some Pin API functions must be called when the thread is holding this lock. See also PIN_UnlockClient.

VOID LEVEL_PINCLIENT::PIN_RemoveAllProbes (   )

Remove all previously inserted probes

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.

VOID LEVEL_PINCLIENT::PIN_RemoveInstrumentation (   )

All instrumentation is removed. When application code is executed the instrumentation routines will be called to reinstrument all code.

VOID LEVEL_PINCLIENT::PIN_RemoveProbe (  ADDRINT  address  )

Remove a probe that was previously inserted at address Parameters: src_addr  Address at which a probe was previously inserted

VOID LEVEL_PINCLIENT::PIN_StartProbedProgram (   )

DEPRECATED. Please use PIN_StartProgramProbed().

VOID LEVEL_PINCLIENT::PIN_StartProgram (   )

Starts program executing, never returns. PIN_Init must be called first

VOID LEVEL_PINCLIENT::PIN_StartProgramProbed (   )

Starts program executing, never returns. PIN_Init must be called first. The command line option -probe must be invoked when using PIN_StartProgramProbed(). A probed program only invokes instrumentation at explicitly inserted probe points.

THREADID LEVEL_PINCLIENT::PIN_ThreadId (   )

Returns: thread id of caller. Cannot be called from a replacement function.

VOID LEVEL_PINCLIENT::PIN_UnlockClient (   )

Some Pin API functions must be called when the thread is holding this lock. See also PIN_LockClient

VOID LEVEL_PINCLIENT::ReleaseVmLock (   )

For experts only!

---