You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
277 lines
14 KiB
277 lines
14 KiB
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
|
<html xmlns="http://www.w3.org/1999/xhtml">
|
|
<head>
|
|
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
|
|
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
|
|
<meta name="generator" content="Doxygen 1.8.13"/>
|
|
<meta name="viewport" content="width=device-width, initial-scale=1"/>
|
|
<title>Pin: Follow Child Process API</title>
|
|
<link href="tabs.css" rel="stylesheet" type="text/css"/>
|
|
<script type="text/javascript" src="jquery.js"></script>
|
|
<script type="text/javascript" src="dynsections.js"></script>
|
|
<link href="search/search.css" rel="stylesheet" type="text/css"/>
|
|
<script type="text/javascript" src="search/searchdata.js"></script>
|
|
<script type="text/javascript" src="search/search.js"></script>
|
|
<link href="doxygen.css" rel="stylesheet" type="text/css" />
|
|
</head>
|
|
<body>
|
|
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
|
|
<div id="titlearea">
|
|
<table cellspacing="0" cellpadding="0">
|
|
<tbody>
|
|
<tr style="height: 56px;">
|
|
<td id="projectalign" style="padding-left: 0.5em;">
|
|
<div id="projectname">Pin
|
|
</div>
|
|
</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</div>
|
|
<!-- end header part -->
|
|
<!-- Generated by Doxygen 1.8.13 -->
|
|
<script type="text/javascript">
|
|
var searchBox = new SearchBox("searchBox", "search",false,'Search');
|
|
</script>
|
|
<script type="text/javascript" src="menudata.js"></script>
|
|
<script type="text/javascript" src="menu.js"></script>
|
|
<script type="text/javascript">
|
|
$(function() {
|
|
initMenu('',true,false,'search.php','Search');
|
|
$(document).ready(function() { init_search(); });
|
|
});
|
|
</script>
|
|
<div id="main-nav"></div>
|
|
</div><!-- top -->
|
|
<!-- window showing the filter options -->
|
|
<div id="MSearchSelectWindow"
|
|
onmouseover="return searchBox.OnSearchSelectShow()"
|
|
onmouseout="return searchBox.OnSearchSelectHide()"
|
|
onkeydown="return searchBox.OnSearchSelectKey(event)">
|
|
</div>
|
|
|
|
<!-- iframe showing the search results (closed by default) -->
|
|
<div id="MSearchResultsWindow">
|
|
<iframe src="javascript:void(0)" frameborder="0"
|
|
name="MSearchResults" id="MSearchResults">
|
|
</iframe>
|
|
</div>
|
|
|
|
<div class="header">
|
|
<div class="summary">
|
|
<a href="#typedef-members">Typedefs</a> |
|
|
<a href="#func-members">Functions</a> </div>
|
|
<div class="headertitle">
|
|
<div class="title">Follow Child Process API</div> </div>
|
|
</div><!--header-->
|
|
<div class="contents">
|
|
<table class="memberdecls">
|
|
<tr class="heading"><td colspan="2"><h2 class="groupheader"><a name="typedef-members"></a>
|
|
Typedefs</h2></td></tr>
|
|
<tr class="memitem:ga17aa0357dbaaec79a971207a6d4ec281"><td class="memItemLeft" align="right" valign="top">typedef LEVEL_BASE::CHILD_PROCESS_CLASS * </td><td class="memItemRight" valign="bottom"><a class="el" href="group__CHILD__PROCESS__API.html#ga17aa0357dbaaec79a971207a6d4ec281">LEVEL_PINCLIENT::CHILD_PROCESS</a></td></tr>
|
|
<tr class="separator:ga17aa0357dbaaec79a971207a6d4ec281"><td class="memSeparator" colspan="2"> </td></tr>
|
|
<tr class="memitem:gaf1def25be0eafe4f4249392e7c67e72e"><td class="memItemLeft" align="right" valign="top">typedef BOOL(* </td><td class="memItemRight" valign="bottom"><a class="el" href="group__CHILD__PROCESS__API.html#gaf1def25be0eafe4f4249392e7c67e72e">LEVEL_PINCLIENT::FOLLOW_CHILD_PROCESS_CALLBACK</a>) (<a class="el" href="group__CHILD__PROCESS__API.html#ga17aa0357dbaaec79a971207a6d4ec281">CHILD_PROCESS</a> childProcess, VOID *val)</td></tr>
|
|
<tr class="separator:gaf1def25be0eafe4f4249392e7c67e72e"><td class="memSeparator" colspan="2"> </td></tr>
|
|
</table><table class="memberdecls">
|
|
<tr class="heading"><td colspan="2"><h2 class="groupheader"><a name="func-members"></a>
|
|
Functions</h2></td></tr>
|
|
<tr class="memitem:ga0b2e319de5e952095201a6d15f257c39"><td class="memItemLeft" align="right" valign="top"><a class="el" href="group__PIN__THREAD__API.html#ga2bf6029042d57fb825536c795c94d1ed">OS_PROCESS_ID</a> </td><td class="memItemRight" valign="bottom"><a class="el" href="group__CHILD__PROCESS__API.html#ga0b2e319de5e952095201a6d15f257c39">LEVEL_PINCLIENT::CHILD_PROCESS_GetId</a> (<a class="el" href="group__CHILD__PROCESS__API.html#ga17aa0357dbaaec79a971207a6d4ec281">CHILD_PROCESS</a> childProcess)</td></tr>
|
|
<tr class="separator:ga0b2e319de5e952095201a6d15f257c39"><td class="memSeparator" colspan="2"> </td></tr>
|
|
<tr class="memitem:ga49de6a716351cd4cc809a76685ebf74b"><td class="memItemLeft" align="right" valign="top">VOID </td><td class="memItemRight" valign="bottom"><a class="el" href="group__CHILD__PROCESS__API.html#ga49de6a716351cd4cc809a76685ebf74b">LEVEL_PINCLIENT::CHILD_PROCESS_GetCommandLine</a> (<a class="el" href="group__CHILD__PROCESS__API.html#ga17aa0357dbaaec79a971207a6d4ec281">CHILD_PROCESS</a> childProcess, INT *pArgc, const CHAR *const **pArgv)</td></tr>
|
|
<tr class="separator:ga49de6a716351cd4cc809a76685ebf74b"><td class="memSeparator" colspan="2"> </td></tr>
|
|
<tr class="memitem:ga40356c5b1a2fdaf98b6b7c9cedc9a860"><td class="memItemLeft" align="right" valign="top">VOID </td><td class="memItemRight" valign="bottom"><a class="el" href="group__CHILD__PROCESS__API.html#ga40356c5b1a2fdaf98b6b7c9cedc9a860">LEVEL_PINCLIENT::CHILD_PROCESS_SetPinCommandLine</a> (<a class="el" href="group__CHILD__PROCESS__API.html#ga17aa0357dbaaec79a971207a6d4ec281">CHILD_PROCESS</a> childProcess, INT argc, const CHAR *const *argv)</td></tr>
|
|
<tr class="separator:ga40356c5b1a2fdaf98b6b7c9cedc9a860"><td class="memSeparator" colspan="2"> </td></tr>
|
|
</table>
|
|
<a name="details" id="details"></a><h2 class="groupheader">Detailed Description</h2>
|
|
<p>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.<br />
|
|
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.<br />
|
|
On Windows, if the injection has failed, the child process would be terminated. However, the parent will continue to run.<br />
|
|
NOTE:</p><ul>
|
|
<li>CHILD_PROCESS handle lifetime is in the scope of the callback<br />
|
|
</li>
|
|
<li>These set of APIs are active only if -follow_execv is enabled<br />
|
|
</li>
|
|
<li>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.<br />
|
|
</li>
|
|
</ul>
|
|
<h2 class="groupheader">Typedef Documentation</h2>
|
|
<a id="ga17aa0357dbaaec79a971207a6d4ec281"></a>
|
|
<h2 class="memtitle"><span class="permalink"><a href="#ga17aa0357dbaaec79a971207a6d4ec281">◆ </a></span>CHILD_PROCESS</h2>
|
|
|
|
<div class="memitem">
|
|
<div class="memproto">
|
|
<table class="memname">
|
|
<tr>
|
|
<td class="memname">typedef LEVEL_BASE::CHILD_PROCESS_CLASS* <a class="el" href="group__CHILD__PROCESS__API.html#ga17aa0357dbaaec79a971207a6d4ec281">LEVEL_PINCLIENT::CHILD_PROCESS</a></td>
|
|
</tr>
|
|
</table>
|
|
</div><div class="memdoc">
|
|
<p>CHILD_PROCESS - Handle for child process APIs </p>
|
|
|
|
</div>
|
|
</div>
|
|
<a id="gaf1def25be0eafe4f4249392e7c67e72e"></a>
|
|
<h2 class="memtitle"><span class="permalink"><a href="#gaf1def25be0eafe4f4249392e7c67e72e">◆ </a></span>FOLLOW_CHILD_PROCESS_CALLBACK</h2>
|
|
|
|
<div class="memitem">
|
|
<div class="memproto">
|
|
<table class="memname">
|
|
<tr>
|
|
<td class="memname">typedef BOOL(* LEVEL_PINCLIENT::FOLLOW_CHILD_PROCESS_CALLBACK) (<a class="el" href="group__CHILD__PROCESS__API.html#ga17aa0357dbaaec79a971207a6d4ec281">CHILD_PROCESS</a> childProcess, VOID *val)</td>
|
|
</tr>
|
|
</table>
|
|
</div><div class="memdoc">
|
|
<p>Call back function before child(Windows*)/exec-ed(Linux*) process is starting to execute. The function can be registered by <a class="el" href="group__PIN__CONTROL.html#ga5f4e19c43f3de21d382c3c4e2442d961">PIN_AddFollowChildProcessFunction()</a>.</p>
|
|
<dl class="params"><dt>Parameters</dt><dd>
|
|
<table class="params">
|
|
<tr><td class="paramdir">[in]</td><td class="paramname">childProcess</td><td>Child process handle, it's lifetime is in the scope of the callback </td></tr>
|
|
<tr><td class="paramdir">[in]</td><td class="paramname">val</td><td>The tool's call-back value</td></tr>
|
|
</table>
|
|
</dd>
|
|
</dl>
|
|
<dl class="section return"><dt>Returns</dt><dd>TRUE If user is interested to inject Pin (and tool) into child/exec-ed process<br />
|
|
FALSE If user is not interested to inject Pin (and tool) into child/exec-ed process<br />
|
|
</dd></dl>
|
|
|
|
</div>
|
|
</div>
|
|
<h2 class="groupheader">Function Documentation</h2>
|
|
<a id="ga49de6a716351cd4cc809a76685ebf74b"></a>
|
|
<h2 class="memtitle"><span class="permalink"><a href="#ga49de6a716351cd4cc809a76685ebf74b">◆ </a></span>CHILD_PROCESS_GetCommandLine()</h2>
|
|
|
|
<div class="memitem">
|
|
<div class="memproto">
|
|
<table class="memname">
|
|
<tr>
|
|
<td class="memname">VOID LEVEL_PINCLIENT::CHILD_PROCESS_GetCommandLine </td>
|
|
<td>(</td>
|
|
<td class="paramtype"><a class="el" href="group__CHILD__PROCESS__API.html#ga17aa0357dbaaec79a971207a6d4ec281">CHILD_PROCESS</a> </td>
|
|
<td class="paramname"><em>childProcess</em>, </td>
|
|
</tr>
|
|
<tr>
|
|
<td class="paramkey"></td>
|
|
<td></td>
|
|
<td class="paramtype">INT * </td>
|
|
<td class="paramname"><em>pArgc</em>, </td>
|
|
</tr>
|
|
<tr>
|
|
<td class="paramkey"></td>
|
|
<td></td>
|
|
<td class="paramtype">const CHAR *const ** </td>
|
|
<td class="paramname"><em>pArgv</em> </td>
|
|
</tr>
|
|
<tr>
|
|
<td></td>
|
|
<td>)</td>
|
|
<td></td><td></td>
|
|
</tr>
|
|
</table>
|
|
</div><div class="memdoc">
|
|
<p>Get application's original command line (without Pin's command line)</p>
|
|
<dl class="params"><dt>Parameters</dt><dd>
|
|
<table class="params">
|
|
<tr><td class="paramdir">[in]</td><td class="paramname">childProcess</td><td>child process handle </td></tr>
|
|
<tr><td class="paramdir">[out]</td><td class="paramname">pArgc</td><td>pointer to application's argc </td></tr>
|
|
<tr><td class="paramdir">[out]</td><td class="paramname">pArgv</td><td>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</td></tr>
|
|
</table>
|
|
</dd>
|
|
</dl>
|
|
<dl class="section user"><dt>Availability:</dt><dd><b>Mode:</b> JIT & Probe<br />
|
|
<b>O/S</b>: Windows<br />
|
|
<b>CPU:</b> All<br />
|
|
</dd></dl>
|
|
|
|
</div>
|
|
</div>
|
|
<a id="ga0b2e319de5e952095201a6d15f257c39"></a>
|
|
<h2 class="memtitle"><span class="permalink"><a href="#ga0b2e319de5e952095201a6d15f257c39">◆ </a></span>CHILD_PROCESS_GetId()</h2>
|
|
|
|
<div class="memitem">
|
|
<div class="memproto">
|
|
<table class="memname">
|
|
<tr>
|
|
<td class="memname"><a class="el" href="group__PIN__THREAD__API.html#ga2bf6029042d57fb825536c795c94d1ed">OS_PROCESS_ID</a> LEVEL_PINCLIENT::CHILD_PROCESS_GetId </td>
|
|
<td>(</td>
|
|
<td class="paramtype"><a class="el" href="group__CHILD__PROCESS__API.html#ga17aa0357dbaaec79a971207a6d4ec281">CHILD_PROCESS</a> </td>
|
|
<td class="paramname"><em>childProcess</em></td><td>)</td>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
</div><div class="memdoc">
|
|
<p>Get process id of child process (meaningful only for Windows*)</p>
|
|
<dl class="params"><dt>Parameters</dt><dd>
|
|
<table class="params">
|
|
<tr><td class="paramdir">[in]</td><td class="paramname">childProcess</td><td>child process handle</td></tr>
|
|
</table>
|
|
</dd>
|
|
</dl>
|
|
<dl class="section return"><dt>Returns</dt><dd>process id of child process</dd></dl>
|
|
<dl class="section user"><dt>Availability:</dt><dd><b>Mode:</b> JIT & Probe<br />
|
|
<b>O/S</b>: Windows<br />
|
|
<b>CPU:</b> All<br />
|
|
</dd></dl>
|
|
|
|
</div>
|
|
</div>
|
|
<a id="ga40356c5b1a2fdaf98b6b7c9cedc9a860"></a>
|
|
<h2 class="memtitle"><span class="permalink"><a href="#ga40356c5b1a2fdaf98b6b7c9cedc9a860">◆ </a></span>CHILD_PROCESS_SetPinCommandLine()</h2>
|
|
|
|
<div class="memitem">
|
|
<div class="memproto">
|
|
<table class="memname">
|
|
<tr>
|
|
<td class="memname">VOID LEVEL_PINCLIENT::CHILD_PROCESS_SetPinCommandLine </td>
|
|
<td>(</td>
|
|
<td class="paramtype"><a class="el" href="group__CHILD__PROCESS__API.html#ga17aa0357dbaaec79a971207a6d4ec281">CHILD_PROCESS</a> </td>
|
|
<td class="paramname"><em>childProcess</em>, </td>
|
|
</tr>
|
|
<tr>
|
|
<td class="paramkey"></td>
|
|
<td></td>
|
|
<td class="paramtype">INT </td>
|
|
<td class="paramname"><em>argc</em>, </td>
|
|
</tr>
|
|
<tr>
|
|
<td class="paramkey"></td>
|
|
<td></td>
|
|
<td class="paramtype">const CHAR *const * </td>
|
|
<td class="paramname"><em>argv</em> </td>
|
|
</tr>
|
|
<tr>
|
|
<td></td>
|
|
<td>)</td>
|
|
<td></td><td></td>
|
|
</tr>
|
|
</table>
|
|
</div><div class="memdoc">
|
|
<p>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 --")</p>
|
|
<p>If this API is not called, Pin will be injected into child/exec-ed process with the same command line as of current process.</p>
|
|
<p>NOTE:</p><ul>
|
|
<li>Providing full path for Pin and tool is the safest way to ensure they will be found (e.g. changing execution directory by application)</li>
|
|
<li>Use same Pin version for all process tree</li>
|
|
</ul>
|
|
<dl class="params"><dt>Parameters</dt><dd>
|
|
<table class="params">
|
|
<tr><td class="paramdir">[in]</td><td class="paramname">childProcess</td><td>handle to child process </td></tr>
|
|
<tr><td class="paramdir">[in]</td><td class="paramname">argc</td><td>Pin's (and tool's) argc </td></tr>
|
|
<tr><td class="paramdir">[in]</td><td class="paramname">argv</td><td>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</td></tr>
|
|
</table>
|
|
</dd>
|
|
</dl>
|
|
<dl class="section user"><dt>Availability:</dt><dd><b>Mode:</b> JIT & Probe<br />
|
|
<b>O/S</b>: Windows<br />
|
|
<b>CPU:</b> All<br />
|
|
</dd></dl>
|
|
|
|
</div>
|
|
</div>
|
|
</div><!-- contents -->
|
|
<!-- start footer part -->
|
|
<hr class="footer"/><address class="footer"><small>
|
|
Generated by  <a href="http://www.doxygen.org/index.html">
|
|
<img class="footer" src="doxygen.png" alt="doxygen"/>
|
|
</a> 1.8.13
|
|
</small></address>
|
|
</body>
|
|
</html>
|