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

• 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

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]	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

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]	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

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]

childProcess

child 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]	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