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:

• CHILD_PROCESS handle lifetime is in the scope of the callback
  
• These set of APIs are active only if -follow_execv is enabled
  
• If -follow_execv is enabled and the user has not registered to get a notification, Pin will be injected into child/exec-ed process with the same command line as of current process.
  

---

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

---