Pin
Typedefs | Functions
Pin Process API

Typedefs

typedef void * CHILD_PROCESS
 
typedef BOOL(* FOLLOW_CHILD_PROCESS_CALLBACK) (CHILD_PROCESS cProcess, VOID *val)
 

Functions

OS_PROCESS_ID CHILD_PROCESS_GetId (CHILD_PROCESS cProcess)
 
VOID CHILD_PROCESS_GetCommandLine (CHILD_PROCESS cProcess, INT *pArgc, const CHAR *const **pArgv)
 
VOID CHILD_PROCESS_SetPinCommandLine (CHILD_PROCESS cProcess, INT argc, const CHAR *const *argv)
 
NORETURN VOID PIN_ExitProcess (INT32 exitCode)
 
INT PIN_GetPid ()
 
NORETURN VOID PIN_ExitApplication (INT32 status)
 

Detailed Description

These APIs provide information about the instrumented process. They are available in any thread, including any internal thread spawned by the tool.

Typedef Documentation

◆ CHILD_PROCESS

typedef void* CHILD_PROCESS

Pin client functions for the follow child process mechanism

CHILD_PROCESS - Handle for child process APIs

◆ FOLLOW_CHILD_PROCESS_CALLBACK

typedef BOOL(* FOLLOW_CHILD_PROCESS_CALLBACK) (CHILD_PROCESS cProcess, VOID *val)

Call back function before child(Windows*)/exec-ed(Linux*) process is starting to execute. The function can be registered by PIN_AddFollowChildProcessFunction().

Parameters
[in]childProcessChild process handle, it's lifetime is in the scope of the callback
[in]valThe tool's call-back value
Returns
TRUE If user is interested to inject Pin (and tool) into child/exec-ed process
FALSE If user is not interested to inject Pin (and tool) into child/exec-ed process

Function Documentation

◆ CHILD_PROCESS_GetCommandLine()

VOID CHILD_PROCESS_GetCommandLine ( CHILD_PROCESS  cProcess,
INT *  pArgc,
const CHAR *const **  pArgv 
)

Get application's original command line (without Pin's command line)

Parameters
[in]childProcesschild process handle
[out]pArgcpointer to application's argc
[out]pArgvpointer to application's argv this data is allocated by Pin and can't be modified by tool, it's lifetime is in the scope of the callback
Availability:
Mode: JIT & Probe
O/S: Windows
CPU: All

◆ CHILD_PROCESS_GetId()

OS_PROCESS_ID CHILD_PROCESS_GetId ( CHILD_PROCESS  cProcess)

Get process id of child process (meaningful only for Windows*)

Parameters
[in]childProcesschild process handle
Returns
process id of child process
Availability:
Mode: JIT & Probe
O/S: Windows
CPU: All

◆ CHILD_PROCESS_SetPinCommandLine()

VOID CHILD_PROCESS_SetPinCommandLine ( CHILD_PROCESS  cProcess,
INT  argc,
const CHAR *const *  argv 
)

Set Pin's (and tool's) command line for the child process (e.g. "c:\\pin_path\\pin -probe -follow_execv -t c:\\pintool_path\\tool --")

If this API is not called, Pin will be injected into child/exec-ed process with the same command line as of current process.

NOTE:

  • Providing full path for Pin and tool is the safest way to ensure they will be found (e.g. changing execution directory by application)
  • Use same Pin version for all process tree
Parameters
[in]childProcesshandle to child process
[in]argcPin's (and tool's) argc
[in]argvPin's (and tool's) argv, this data is allocated by tool and can't be modified by Pin, it's lifetime is in the scope of this function
Availability:
Mode: JIT & Probe
O/S: Windows
CPU: All

◆ PIN_ExitApplication()

NORETURN VOID PIN_ExitApplication ( INT32  status)

Terminate the current process after calling the relevant thread and process exit callbacks. This call behaves "as if" the application process itself had executed a process termination system call. It therefore does perform all the finalization actions Pin normally takes on application process exit, including calling registered thread and process fini-functions, unlike PIN_ExitProcess, which exits immediately.

This API may be called from an instrumentation callback function or an analysis routine. However, it should not be called from any FINI_CALLBACK or THREAD_FINI_CALLBACK routines. It may be called by an application thread or a tool internal thread (that was created via PIN_SpawnInternalThread).

Be aware, that when called from an internal thread, the calling thread will not exit until after the tool's fini callbacks return. Therefore, to avoid deadlock, your fini callbacks should not wait for that internal thread to exit.

Parameters
[in]statusThe result argument to exit
Returns
This function does not return.
Note
The vm and pin client locks are obtained during the call of this API.
Availability:
Mode: JIT
O/S: Linux,Windows,BSD
CPU: All

◆ PIN_ExitProcess()

NORETURN VOID PIN_ExitProcess ( INT32  exitCode)

Terminate the current process immediately, without calling any thread or process fini callbacks that may be registered. (See PIN_ExitApplication, if you want fini callbacks to be called).

This function should be used only for abnormal termination of the instrumented process. Normally, the process is terminated when Pin executes a process termination system call on behalf of the application.

Parameters
[in]exitCodeexit code of the process to be reported to the operating system.
Returns
the function never returns.
Availability:
Mode: JIT & Probe
O/S: Linux, Windows & macOS*
CPU: All

◆ PIN_GetPid()

INT PIN_GetPid ( )

Returns current process id

Availability:
Mode: JIT & Probe
O/S: Linux, Windows & macOS*
CPU: All