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.
◆ 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
◆ 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()
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
