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

typedef LEVEL_BASE::CHILD_PROCESS_CLASS* LEVEL_PINCLIENT::CHILD_PROCESS
 

CHILD_PROCESS - Handle for child process APIs

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] childProcess Child process handle, it's lifetime is in the scope of the callback
[in] val The 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

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] childProcess child process handle
[out] pArgc pointer to application's argc
[out] pArgv pointer 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

OS_PROCESS_ID LEVEL_PINCLIENT::CHILD_PROCESS_GetId CHILD_PROCESS  childProcess  ) 
 

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

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

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] childProcess handle to child process
[in] argc Pin's (and tool's) argc
[in] argv Pin'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


Generated on Sun Jan 28 23:35:39 2018 for Pin by  doxygen 1.4.6