- Main Page
- Modules
- Classes

- Search for |

# 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