1<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> 2<html> 3<!-- Copyright (C) 1988-2021 Free Software Foundation, Inc. 4 5Permission is granted to copy, distribute and/or modify this document 6under the terms of the GNU Free Documentation License, Version 1.3 or 7any later version published by the Free Software Foundation; with the 8Invariant Sections being "Free Software" and "Free Software Needs 9Free Documentation", with the Front-Cover Texts being "A GNU Manual," 10and with the Back-Cover Texts as in (a) below. 11 12(a) The FSF's Back-Cover Text is: "You are free to copy and modify 13this GNU Manual. Buying copies from GNU Press supports the FSF in 14developing GNU and promoting software freedom." --> 15<!-- Created by GNU Texinfo 5.1, http://www.gnu.org/software/texinfo/ --> 16<head> 17<title>Debugging with GDB: Compiling and Injecting Code</title> 18 19<meta name="description" content="Debugging with GDB: Compiling and Injecting Code"> 20<meta name="keywords" content="Debugging with GDB: Compiling and Injecting Code"> 21<meta name="resource-type" content="document"> 22<meta name="distribution" content="global"> 23<meta name="Generator" content="makeinfo"> 24<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> 25<link href="index.html#Top" rel="start" title="Top"> 26<link href="Concept-Index.html#Concept-Index" rel="index" title="Concept Index"> 27<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents"> 28<link href="Altering.html#Altering" rel="up" title="Altering"> 29<link href="GDB-Files.html#GDB-Files" rel="next" title="GDB Files"> 30<link href="Patching.html#Patching" rel="previous" title="Patching"> 31<style type="text/css"> 32<!-- 33a.summary-letter {text-decoration: none} 34blockquote.smallquotation {font-size: smaller} 35div.display {margin-left: 3.2em} 36div.example {margin-left: 3.2em} 37div.indentedblock {margin-left: 3.2em} 38div.lisp {margin-left: 3.2em} 39div.smalldisplay {margin-left: 3.2em} 40div.smallexample {margin-left: 3.2em} 41div.smallindentedblock {margin-left: 3.2em; font-size: smaller} 42div.smalllisp {margin-left: 3.2em} 43kbd {font-style:oblique} 44pre.display {font-family: inherit} 45pre.format {font-family: inherit} 46pre.menu-comment {font-family: serif} 47pre.menu-preformatted {font-family: serif} 48pre.smalldisplay {font-family: inherit; font-size: smaller} 49pre.smallexample {font-size: smaller} 50pre.smallformat {font-family: inherit; font-size: smaller} 51pre.smalllisp {font-size: smaller} 52span.nocodebreak {white-space:nowrap} 53span.nolinebreak {white-space:nowrap} 54span.roman {font-family:serif; font-weight:normal} 55span.sansserif {font-family:sans-serif; font-weight:normal} 56ul.no-bullet {list-style: none} 57--> 58</style> 59 60 61</head> 62 63<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000"> 64<a name="Compiling-and-Injecting-Code"></a> 65<div class="header"> 66<p> 67Previous: <a href="Patching.html#Patching" accesskey="p" rel="previous">Patching</a>, Up: <a href="Altering.html#Altering" accesskey="u" rel="up">Altering</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Concept-Index.html#Concept-Index" title="Index" rel="index">Index</a>]</p> 68</div> 69<hr> 70<a name="Compiling-and-Injecting-Code-in-GDB"></a> 71<h3 class="section">17.7 Compiling and Injecting Code in <small>GDB</small></h3> 72<a name="index-injecting-code"></a> 73<a name="index-writing-into-executables-1"></a> 74<a name="index-compiling-code"></a> 75 76<p><small>GDB</small> supports on-demand compilation and code injection into 77programs running under <small>GDB</small>. GCC 5.0 or higher built with 78<samp>libcc1.so</samp> must be installed for this functionality to be enabled. 79This functionality is implemented with the following commands. 80</p> 81<dl compact="compact"> 82<dd><a name="index-compile-code"></a> 83</dd> 84<dt><code>compile code <var>source-code</var></code></dt> 85<dt><code>compile code -raw <var>--</var> <var>source-code</var></code></dt> 86<dd><p>Compile <var>source-code</var> with the compiler language found as the current 87language in <small>GDB</small> (see <a href="Languages.html#Languages">Languages</a>). If compilation and 88injection is not supported with the current language specified in 89<small>GDB</small>, or the compiler does not support this feature, an error 90message will be printed. If <var>source-code</var> compiles and links 91successfully, <small>GDB</small> will load the object-code emitted, 92and execute it within the context of the currently selected inferior. 93It is important to note that the compiled code is executed immediately. 94After execution, the compiled code is removed from <small>GDB</small> and any 95new types or variables you have defined will be deleted. 96</p> 97<p>The command allows you to specify <var>source-code</var> in two ways. 98The simplest method is to provide a single line of code to the command. 99E.g.: 100</p> 101<div class="smallexample"> 102<pre class="smallexample">compile code printf ("hello world\n"); 103</pre></div> 104 105<p>If you specify options on the command line as well as source code, they 106may conflict. The ‘<samp>--</samp>’ delimiter can be used to separate options 107from actual source code. E.g.: 108</p> 109<div class="smallexample"> 110<pre class="smallexample">compile code -r -- printf ("hello world\n"); 111</pre></div> 112 113<p>Alternatively you can enter source code as multiple lines of text. To 114enter this mode, invoke the ‘<samp>compile code</samp>’ command without any text 115following the command. This will start the multiple-line editor and 116allow you to type as many lines of source code as required. When you 117have completed typing, enter ‘<samp>end</samp>’ on its own line to exit the 118editor. 119</p> 120<div class="smallexample"> 121<pre class="smallexample">compile code 122>printf ("hello\n"); 123>printf ("world\n"); 124>end 125</pre></div> 126 127<p>Specifying ‘<samp>-raw</samp>’, prohibits <small>GDB</small> from wrapping the 128provided <var>source-code</var> in a callable scope. In this case, you must 129specify the entry point of the code by defining a function named 130<code>_gdb_expr_</code>. The ‘<samp>-raw</samp>’ code cannot access variables of the 131inferior. Using ‘<samp>-raw</samp>’ option may be needed for example when 132<var>source-code</var> requires ‘<samp>#include</samp>’ lines which may conflict with 133inferior symbols otherwise. 134</p> 135<a name="index-compile-file"></a> 136</dd> 137<dt><code>compile file <var>filename</var></code></dt> 138<dt><code>compile file -raw <var>filename</var></code></dt> 139<dd><p>Like <code>compile code</code>, but take the source code from <var>filename</var>. 140</p> 141<div class="smallexample"> 142<pre class="smallexample">compile file /home/user/example.c 143</pre></div> 144</dd> 145</dl> 146 147<dl compact="compact"> 148<dt><code>compile print [[<var>options</var>] --] <var>expr</var></code></dt> 149<dt><code>compile print [[<var>options</var>] --] /<var>f</var> <var>expr</var></code></dt> 150<dd><p>Compile and execute <var>expr</var> with the compiler language found as the 151current language in <small>GDB</small> (see <a href="Languages.html#Languages">Languages</a>). By default the 152value of <var>expr</var> is printed in a format appropriate to its data type; 153you can choose a different format by specifying ‘<samp>/<var>f</var></samp>’, where 154<var>f</var> is a letter specifying the format; see <a href="Output-Formats.html#Output-Formats">Output 155Formats</a>. The <code>compile print</code> command accepts the same options 156as the <code>print</code> command; see <a href="Data.html#print-options">print options</a>. 157</p> 158</dd> 159<dt><code>compile print [[<var>options</var>] --]</code></dt> 160<dt><code>compile print [[<var>options</var>] --] /<var>f</var></code></dt> 161<dd><a name="index-reprint-the-last-value-1"></a> 162<p>Alternatively you can enter the expression (source code producing it) as 163multiple lines of text. To enter this mode, invoke the ‘<samp>compile print</samp>’ 164command without any text following the command. This will start the 165multiple-line editor. 166</p></dd> 167</dl> 168 169<p>The process of compiling and injecting the code can be inspected using: 170</p> 171<dl compact="compact"> 172<dd><a name="set-debug-compile"></a></dd> 173<dt><code>set debug compile</code></dt> 174<dd><a name="index-compile-command-debugging-info"></a> 175<p>Turns on or off display of <small>GDB</small> process of compiling and 176injecting the code. The default is off. 177</p> 178</dd> 179<dt><code>show debug compile</code></dt> 180<dd><p>Displays the current state of displaying <small>GDB</small> process of 181compiling and injecting the code. 182</p> 183<a name="set-debug-compile_002dcplus_002dtypes"></a></dd> 184<dt><code>set debug compile-cplus-types</code></dt> 185<dd><a name="index-compile-C_002b_002b-type-conversion"></a> 186<p>Turns on or off the display of C<tt>++</tt> type conversion debugging information. 187The default is off. 188</p> 189</dd> 190<dt><code>show debug compile-cplus-types</code></dt> 191<dd><p>Displays the current state of displaying debugging information for 192C<tt>++</tt> type conversion. 193</p></dd> 194</dl> 195 196<a name="Compilation-Options-for-the-compile-Command"></a> 197<h4 class="subsection">17.7.1 Compilation Options for the <code>compile</code> Command</h4> 198 199<p><small>GDB</small> needs to specify the right compilation options for the code 200to be injected, in part to make its ABI compatible with the inferior 201and in part to make the injected code compatible with <small>GDB</small>’s 202injecting process. 203</p> 204<p>The options used, in increasing precedence: 205</p> 206<dl compact="compact"> 207<dt>target architecture and OS options (<code>gdbarch</code>)</dt> 208<dd><p>These options depend on target processor type and target operating 209system, usually they specify at least 32-bit (<code>-m32</code>) or 64-bit 210(<code>-m64</code>) compilation option. 211</p> 212</dd> 213<dt>compilation options recorded in the target</dt> 214<dd><p><small>GCC</small> (since version 4.7) stores the options used for compilation 215into <code>DW_AT_producer</code> part of DWARF debugging information according 216to the <small>GCC</small> option <code>-grecord-gcc-switches</code>. One has to 217explicitly specify <code>-g</code> during inferior compilation otherwise 218<small>GCC</small> produces no DWARF. This feature is only relevant for 219platforms where <code>-g</code> produces DWARF by default, otherwise one may 220try to enforce DWARF by using <code>-gdwarf-4</code>. 221</p> 222</dd> 223<dt>compilation options set by <code>set compile-args</code></dt> 224</dl> 225 226<p>You can override compilation options using the following command: 227</p> 228<dl compact="compact"> 229<dt><code>set compile-args</code></dt> 230<dd><a name="index-compile-command-options-override"></a> 231<p>Set compilation options used for compiling and injecting code with the 232<code>compile</code> commands. These options override any conflicting ones 233from the target architecture and/or options stored during inferior 234compilation. 235</p> 236</dd> 237<dt><code>show compile-args</code></dt> 238<dd><p>Displays the current state of compilation options override. 239This does not show all the options actually used during compilation, 240use <a href="#set-debug-compile">set debug compile</a> for that. 241</p></dd> 242</dl> 243 244<a name="Caveats-When-Using-the-compile-Command"></a> 245<h4 class="subsection">17.7.2 Caveats When Using the <code>compile</code> Command</h4> 246 247<p>There are a few caveats to keep in mind when using the <code>compile</code> 248command. As the caveats are different per language, the table below 249highlights specific issues on a per language basis. 250</p> 251<dl compact="compact"> 252<dt>C code examples and caveats</dt> 253<dd><p>When the language in <small>GDB</small> is set to ‘<samp>C</samp>’, the compiler will 254attempt to compile the source code with a ‘<samp>C</samp>’ compiler. The source 255code provided to the <code>compile</code> command will have much the same 256access to variables and types as it normally would if it were part of 257the program currently being debugged in <small>GDB</small>. 258</p> 259<p>Below is a sample program that forms the basis of the examples that 260follow. This program has been compiled and loaded into <small>GDB</small>, 261much like any other normal debugging session. 262</p> 263<div class="smallexample"> 264<pre class="smallexample">void function1 (void) 265{ 266 int i = 42; 267 printf ("function 1\n"); 268} 269 270void function2 (void) 271{ 272 int j = 12; 273 function1 (); 274} 275 276int main(void) 277{ 278 int k = 6; 279 int *p; 280 function2 (); 281 return 0; 282} 283</pre></div> 284 285<p>For the purposes of the examples in this section, the program above has 286been compiled, loaded into <small>GDB</small>, stopped at the function 287<code>main</code>, and <small>GDB</small> is awaiting input from the user. 288</p> 289<p>To access variables and types for any program in <small>GDB</small>, the 290program must be compiled and packaged with debug information. The 291<code>compile</code> command is not an exception to this rule. Without debug 292information, you can still use the <code>compile</code> command, but you will 293be very limited in what variables and types you can access. 294</p> 295<p>So with that in mind, the example above has been compiled with debug 296information enabled. The <code>compile</code> command will have access to 297all variables and types (except those that may have been optimized 298out). Currently, as <small>GDB</small> has stopped the program in the 299<code>main</code> function, the <code>compile</code> command would have access to 300the variable <code>k</code>. You could invoke the <code>compile</code> command 301and type some source code to set the value of <code>k</code>. You can also 302read it, or do anything with that variable you would normally do in 303<code>C</code>. Be aware that changes to inferior variables in the 304<code>compile</code> command are persistent. In the following example: 305</p> 306<div class="smallexample"> 307<pre class="smallexample">compile code k = 3; 308</pre></div> 309 310<p>the variable <code>k</code> is now 3. It will retain that value until 311something else in the example program changes it, or another 312<code>compile</code> command changes it. 313</p> 314<p>Normal scope and access rules apply to source code compiled and 315injected by the <code>compile</code> command. In the example, the variables 316<code>j</code> and <code>k</code> are not accessible yet, because the program is 317currently stopped in the <code>main</code> function, where these variables 318are not in scope. Therefore, the following command 319</p> 320<div class="smallexample"> 321<pre class="smallexample">compile code j = 3; 322</pre></div> 323 324<p>will result in a compilation error message. 325</p> 326<p>Once the program is continued, execution will bring these variables in 327scope, and they will become accessible; then the code you specify via 328the <code>compile</code> command will be able to access them. 329</p> 330<p>You can create variables and types with the <code>compile</code> command as 331part of your source code. Variables and types that are created as part 332of the <code>compile</code> command are not visible to the rest of the program for 333the duration of its run. This example is valid: 334</p> 335<div class="smallexample"> 336<pre class="smallexample">compile code int ff = 5; printf ("ff is %d\n", ff); 337</pre></div> 338 339<p>However, if you were to type the following into <small>GDB</small> after that 340command has completed: 341</p> 342<div class="smallexample"> 343<pre class="smallexample">compile code printf ("ff is %d\n'', ff); 344</pre></div> 345 346<p>a compiler error would be raised as the variable <code>ff</code> no longer 347exists. Object code generated and injected by the <code>compile</code> 348command is removed when its execution ends. Caution is advised 349when assigning to program variables values of variables created by the 350code submitted to the <code>compile</code> command. This example is valid: 351</p> 352<div class="smallexample"> 353<pre class="smallexample">compile code int ff = 5; k = ff; 354</pre></div> 355 356<p>The value of the variable <code>ff</code> is assigned to <code>k</code>. The variable 357<code>k</code> does not require the existence of <code>ff</code> to maintain the value 358it has been assigned. However, pointers require particular care in 359assignment. If the source code compiled with the <code>compile</code> command 360changed the address of a pointer in the example program, perhaps to a 361variable created in the <code>compile</code> command, that pointer would point 362to an invalid location when the command exits. The following example 363would likely cause issues with your debugged program: 364</p> 365<div class="smallexample"> 366<pre class="smallexample">compile code int ff = 5; p = &ff; 367</pre></div> 368 369<p>In this example, <code>p</code> would point to <code>ff</code> when the 370<code>compile</code> command is executing the source code provided to it. 371However, as variables in the (example) program persist with their 372assigned values, the variable <code>p</code> would point to an invalid 373location when the command exists. A general rule should be followed 374in that you should either assign <code>NULL</code> to any assigned pointers, 375or restore a valid location to the pointer before the command exits. 376</p> 377<p>Similar caution must be exercised with any structs, unions, and typedefs 378defined in <code>compile</code> command. Types defined in the <code>compile</code> 379command will no longer be available in the next <code>compile</code> command. 380Therefore, if you cast a variable to a type defined in the 381<code>compile</code> command, care must be taken to ensure that any future 382need to resolve the type can be achieved. 383</p> 384<div class="smallexample"> 385<pre class="smallexample">(gdb) compile code static struct a { int a; } v = { 42 }; argv = &v; 386(gdb) compile code printf ("%d\n", ((struct a *) argv)->a); 387gdb command line:1:36: error: dereferencing pointer to incomplete type ‘struct a’ 388Compilation failed. 389(gdb) compile code struct a { int a; }; printf ("%d\n", ((struct a *) argv)->a); 39042 391</pre></div> 392 393<p>Variables that have been optimized away by the compiler are not 394accessible to the code submitted to the <code>compile</code> command. 395Access to those variables will generate a compiler error which <small>GDB</small> 396will print to the console. 397</p></dd> 398</dl> 399 400<a name="Compiler-Search-for-the-compile-Command"></a> 401<h4 class="subsection">17.7.3 Compiler Search for the <code>compile</code> Command</h4> 402 403<p><small>GDB</small> needs to find <small>GCC</small> for the inferior being debugged 404which may not be obvious for remote targets of different architecture 405than where <small>GDB</small> is running. Environment variable <code>PATH</code> on 406<small>GDB</small> host is searched for <small>GCC</small> binary matching the 407target architecture and operating system. This search can be overriden 408by <code>set compile-gcc</code> <small>GDB</small> command below. <code>PATH</code> is 409taken from shell that executed <small>GDB</small>, it is not the value set by 410<small>GDB</small> command <code>set environment</code>). See <a href="Environment.html#Environment">Environment</a>. 411</p> 412 413<p>Specifically <code>PATH</code> is searched for binaries matching regular expression 414<code><var>arch</var>(-[^-]*)?-<var>os</var>-gcc</code> according to the inferior target being 415debugged. <var>arch</var> is processor name — multiarch is supported, so for 416example both <code>i386</code> and <code>x86_64</code> targets look for pattern 417<code>(x86_64|i.86)</code> and both <code>s390</code> and <code>s390x</code> targets look 418for pattern <code>s390x?</code>. <var>os</var> is currently supported only for 419pattern <code>linux(-gnu)?</code>. 420</p> 421<p>On Posix hosts the compiler driver <small>GDB</small> needs to find also 422shared library <samp>libcc1.so</samp> from the compiler. It is searched in 423default shared library search path (overridable with usual environment 424variable <code>LD_LIBRARY_PATH</code>), unrelated to <code>PATH</code> or <code>set 425compile-gcc</code> settings. Contrary to it <samp>libcc1plugin.so</samp> is found 426according to the installation of the found compiler — as possibly 427specified by the <code>set compile-gcc</code> command. 428</p> 429<dl compact="compact"> 430<dt><code>set compile-gcc</code></dt> 431<dd><a name="index-compile-command-driver-filename-override"></a> 432<p>Set compilation command used for compiling and injecting code with the 433<code>compile</code> commands. If this option is not set (it is set to 434an empty string), the search described above will occur — that is the 435default. 436</p> 437</dd> 438<dt><code>show compile-gcc</code></dt> 439<dd><p>Displays the current compile command <small>GCC</small> driver filename. 440If set, it is the main command <code>gcc</code>, found usually for example 441under name <samp>x86_64-linux-gnu-gcc</samp>. 442</p></dd> 443</dl> 444 445<hr> 446<div class="header"> 447<p> 448Previous: <a href="Patching.html#Patching" accesskey="p" rel="previous">Patching</a>, Up: <a href="Altering.html#Altering" accesskey="u" rel="up">Altering</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Concept-Index.html#Concept-Index" title="Index" rel="index">Index</a>]</p> 449</div> 450 451 452 453</body> 454</html> 455