Pin
Typedefs | Functions
Follow Child Process API

Typedefs

typedef LEVEL_BASE::CHILD_PROCESS_CLASS * LEVEL_PINCLIENT::CHILD_PROCESS
 
typedef BOOL(* LEVEL_PINCLIENT::FOLLOW_CHILD_PROCESS_CALLBACK) (CHILD_PROCESS childProcess, VOID *val)
 

Functions

OS_PROCESS_ID LEVEL_PINCLIENT::CHILD_PROCESS_GetId (CHILD_PROCESS childProcess)
 
VOID LEVEL_PINCLIENT::CHILD_PROCESS_GetCommandLine (CHILD_PROCESS childProcess, INT *pArgc, const CHAR *const **pArgv)
 
VOID LEVEL_PINCLIENT::CHILD_PROCESS_SetPinCommandLine (CHILD_PROCESS childProcess, INT argc, const CHAR *const *argv)
 

Detailed Description

These APIs allow the user to be notified before child(Windows*)/exec-ed(Linux*) process is starting to execute. The user can use the CHILD_PROCESS handle to get information about the process that is going to be executed. The user can decide whether to inject Pin (and PinTool) into the child/exec-ed process.
On Linux, if the user has decided to inject Pin into the child process and the injection has failed, the child process would run uninstrumeted. This is only supported for parent injection. In case of child injection, the behavior is the same as on Windows.
On Windows, if the injection has failed, the child process would be terminated. However, the parent will continue to run.
NOTE:

Typedef Documentation

◆ CHILD_PROCESS

typedef LEVEL_BASE::CHILD_PROCESS_CLASS* LEVEL_PINCLIENT::CHILD_PROCESS

CHILD_PROCESS - Handle for child process APIs

◆ FOLLOW_CHILD_PROCESS_CALLBACK

typedef BOOL(* LEVEL_PINCLIENT::FOLLOW_CHILD_PROCESS_CALLBACK) (CHILD_PROCESS childProcess, 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 LEVEL_PINCLIENT::CHILD_PROCESS_GetCommandLine ( CHILD_PROCESS  childProcess,
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 LEVEL_PINCLIENT::CHILD_PROCESS_GetId ( CHILD_PROCESS  childProcess)

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 LEVEL_PINCLIENT::CHILD_PROCESS_SetPinCommandLine ( CHILD_PROCESS  childProcess,
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