1<html lang="en"> 2<head> 3<title>Starting - Debugging with GDB</title> 4<meta http-equiv="Content-Type" content="text/html"> 5<meta name="description" content="Debugging with GDB"> 6<meta name="generator" content="makeinfo 4.13"> 7<link title="Top" rel="start" href="index.html#Top"> 8<link rel="up" href="Running.html#Running" title="Running"> 9<link rel="prev" href="Compilation.html#Compilation" title="Compilation"> 10<link rel="next" href="Arguments.html#Arguments" title="Arguments"> 11<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage"> 12<!-- 13Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996, 141998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 15Free Software Foundation, Inc. 16 17Permission is granted to copy, distribute and/or modify this document 18under the terms of the GNU Free Documentation License, Version 1.3 or 19any later version published by the Free Software Foundation; with the 20Invariant Sections being ``Free Software'' and ``Free Software Needs 21Free Documentation'', with the Front-Cover Texts being ``A GNU Manual,'' 22and with the Back-Cover Texts as in (a) below. 23 24(a) The FSF's Back-Cover Text is: ``You are free to copy and modify 25this GNU Manual. Buying copies from GNU Press supports the FSF in 26developing GNU and promoting software freedom.''--> 27<meta http-equiv="Content-Style-Type" content="text/css"> 28<style type="text/css"><!-- 29 pre.display { font-family:inherit } 30 pre.format { font-family:inherit } 31 pre.smalldisplay { font-family:inherit; font-size:smaller } 32 pre.smallformat { font-family:inherit; font-size:smaller } 33 pre.smallexample { font-size:smaller } 34 pre.smalllisp { font-size:smaller } 35 span.sc { font-variant:small-caps } 36 span.roman { font-family:serif; font-weight:normal; } 37 span.sansserif { font-family:sans-serif; font-weight:normal; } 38--></style> 39<link rel="stylesheet" type="text/css" href="../cs.css"> 40</head> 41<body> 42<div class="node"> 43<a name="Starting"></a> 44<p> 45Next: <a rel="next" accesskey="n" href="Arguments.html#Arguments">Arguments</a>, 46Previous: <a rel="previous" accesskey="p" href="Compilation.html#Compilation">Compilation</a>, 47Up: <a rel="up" accesskey="u" href="Running.html#Running">Running</a> 48<hr> 49</div> 50 51<h3 class="section">4.2 Starting your Program</h3> 52 53<p><a name="index-starting-100"></a><a name="index-running-101"></a> 54 55<a name="index-run-102"></a> 56<a name="index-r-_0040r_007b_0028_0040code_007brun_007d_0029_007d-103"></a> 57<dl><dt><code>run</code><dt><code>r</code><dd>Use the <code>run</code> command to start your program under <span class="sc">gdb</span>. 58You must first specify the program name (except on VxWorks) with an 59argument to <span class="sc">gdb</span> (see <a href="Invocation.html#Invocation">Getting In and Out of <span class="sc">gdb</span></a>), or by using the <code>file</code> or <code>exec-file</code> command 60(see <a href="Files.html#Files">Commands to Specify Files</a>). 61 62 </dl> 63 64 <p>If you are running your program in an execution environment that 65supports processes, <code>run</code> creates an inferior process and makes 66that process run your program. In some environments without processes, 67<code>run</code> jumps to the start of your program. Other targets, 68like ‘<samp><span class="samp">remote</span></samp>’, are always running. If you get an error 69message like this one: 70 71<pre class="smallexample"> The "remote" target does not support "run". 72 Try "help target" or "continue". 73</pre> 74 <p class="noindent">then use <code>continue</code> to run your program. You may need <code>load</code> 75first (see <a href="load.html#load">load</a>). 76 77 <p>The execution of a program is affected by certain information it 78receives from its superior. <span class="sc">gdb</span> provides ways to specify this 79information, which you must do <em>before</em> starting your program. (You 80can change it after starting your program, but such changes only affect 81your program the next time you start it.) This information may be 82divided into four categories: 83 84 <dl> 85<dt>The <em>arguments.</em><dd>Specify the arguments to give your program as the arguments of the 86<code>run</code> command. If a shell is available on your target, the shell 87is used to pass the arguments, so that you may use normal conventions 88(such as wildcard expansion or variable substitution) in describing 89the arguments. 90In Unix systems, you can control which shell is used with the 91<code>SHELL</code> environment variable. 92See <a href="Arguments.html#Arguments">Your Program's Arguments</a>. 93 94 <br><dt>The <em>environment.</em><dd>Your program normally inherits its environment from <span class="sc">gdb</span>, but you can 95use the <span class="sc">gdb</span> commands <code>set environment</code> and <code>unset 96environment</code> to change parts of the environment that affect 97your program. See <a href="Environment.html#Environment">Your Program's Environment</a>. 98 99 <br><dt>The <em>working directory.</em><dd>Your program inherits its working directory from <span class="sc">gdb</span>. You can set 100the <span class="sc">gdb</span> working directory with the <code>cd</code> command in <span class="sc">gdb</span>. 101See <a href="Working-Directory.html#Working-Directory">Your Program's Working Directory</a>. 102 103 <br><dt>The <em>standard input and output.</em><dd>Your program normally uses the same device for standard input and 104standard output as <span class="sc">gdb</span> is using. You can redirect input and output 105in the <code>run</code> command line, or you can use the <code>tty</code> command to 106set a different device for your program. 107See <a href="Input_002fOutput.html#Input_002fOutput">Your Program's Input and Output</a>. 108 109 <p><a name="index-pipes-104"></a><em>Warning:</em> While input and output redirection work, you cannot use 110pipes to pass the output of the program you are debugging to another 111program; if you attempt this, <span class="sc">gdb</span> is likely to wind up debugging the 112wrong program. 113</dl> 114 115 <p>When you issue the <code>run</code> command, your program begins to execute 116immediately. See <a href="Stopping.html#Stopping">Stopping and Continuing</a>, for discussion 117of how to arrange for your program to stop. Once your program has 118stopped, you may call functions in your program, using the <code>print</code> 119or <code>call</code> commands. See <a href="Data.html#Data">Examining Data</a>. 120 121 <p>If the modification time of your symbol file has changed since the last 122time <span class="sc">gdb</span> read its symbols, <span class="sc">gdb</span> discards its symbol 123table, and reads it again. When it does this, <span class="sc">gdb</span> tries to retain 124your current breakpoints. 125 126 127<a name="index-start-105"></a> 128<dl><dt><code>start</code><dd><a name="index-run-to-main-procedure-106"></a>The name of the main procedure can vary from language to language. 129With C or C<tt>++</tt>, the main procedure name is always <code>main</code>, but 130other languages such as Ada do not require a specific name for their 131main procedure. The debugger provides a convenient way to start the 132execution of the program and to stop at the beginning of the main 133procedure, depending on the language used. 134 135 <p>The ‘<samp><span class="samp">start</span></samp>’ command does the equivalent of setting a temporary 136breakpoint at the beginning of the main procedure and then invoking 137the ‘<samp><span class="samp">run</span></samp>’ command. 138 139 <p><a name="index-elaboration-phase-107"></a>Some programs contain an <dfn>elaboration</dfn> phase where some startup code is 140executed before the main procedure is called. This depends on the 141languages used to write your program. In C<tt>++</tt>, for instance, 142constructors for static and global objects are executed before 143<code>main</code> is called. It is therefore possible that the debugger stops 144before reaching the main procedure. However, the temporary breakpoint 145will remain to halt execution. 146 147 <p>Specify the arguments to give to your program as arguments to the 148‘<samp><span class="samp">start</span></samp>’ command. These arguments will be given verbatim to the 149underlying ‘<samp><span class="samp">run</span></samp>’ command. Note that the same arguments will be 150reused if no argument is provided during subsequent calls to 151‘<samp><span class="samp">start</span></samp>’ or ‘<samp><span class="samp">run</span></samp>’. 152 153 <p>It is sometimes necessary to debug the program during elaboration. In 154these cases, using the <code>start</code> command would stop the execution of 155your program too late, as the program would have already completed the 156elaboration phase. Under these circumstances, insert breakpoints in your 157elaboration code before running your program. 158 159 <p><a name="index-set-exec_002dwrapper-108"></a><br><dt><code>set exec-wrapper </code><var>wrapper</var><dt><code>show exec-wrapper</code><dt><code>unset exec-wrapper</code><dd>When ‘<samp><span class="samp">exec-wrapper</span></samp>’ is set, the specified wrapper is used to 160launch programs for debugging. <span class="sc">gdb</span> starts your program 161with a shell command of the form <kbd>exec </kbd><var>wrapper</var> 162<var>program</var>. Quoting is added to <var>program</var> and its 163arguments, but not to <var>wrapper</var>, so you should add quotes if 164appropriate for your shell. The wrapper runs until it executes 165your program, and then <span class="sc">gdb</span> takes control. 166 167 <p>You can use any program that eventually calls <code>execve</code> with 168its arguments as a wrapper. Several standard Unix utilities do 169this, e.g. <code>env</code> and <code>nohup</code>. Any Unix shell script ending 170with <code>exec "$@"</code> will also work. 171 172 <p>For example, you can use <code>env</code> to pass an environment variable to 173the debugged program, without setting the variable in your shell's 174environment: 175 176 <pre class="smallexample"> (gdb) set exec-wrapper env 'LD_PRELOAD=libtest.so' 177 (gdb) run 178</pre> 179 <p>This command is available when debugging locally on most targets, excluding 180<span class="sc">djgpp</span>, Cygwin, MS Windows, and QNX Neutrino. 181 182 <p><a name="index-set-disable_002drandomization-109"></a><br><dt><code>set disable-randomization</code><dt><code>set disable-randomization on</code><dd>This option (enabled by default in <span class="sc">gdb</span>) will turn off the native 183randomization of the virtual address space of the started program. This option 184is useful for multiple debugging sessions to make the execution better 185reproducible and memory addresses reusable across debugging sessions. 186 187 <p>This feature is implemented only on <span class="sc">gnu</span>/Linux. You can get the same 188behavior using 189 190 <pre class="smallexample"> (gdb) set exec-wrapper setarch `uname -m` -R 191</pre> 192 <br><dt><code>set disable-randomization off</code><dd>Leave the behavior of the started executable unchanged. Some bugs rear their 193ugly heads only when the program is loaded at certain addresses. If your bug 194disappears when you run the program under <span class="sc">gdb</span>, that might be because 195<span class="sc">gdb</span> by default disables the address randomization on platforms, such 196as <span class="sc">gnu</span>/Linux, which do that for stand-alone programs. Use <kbd>set 197disable-randomization off</kbd> to try to reproduce such elusive bugs. 198 199 <p>The virtual address space randomization is implemented only on <span class="sc">gnu</span>/Linux. 200It protects the programs against some kinds of security attacks. In these 201cases the attacker needs to know the exact location of a concrete executable 202code. Randomizing its location makes it impossible to inject jumps misusing 203a code at its expected addresses. 204 205 <p>Prelinking shared libraries provides a startup performance advantage but it 206makes addresses in these libraries predictable for privileged processes by 207having just unprivileged access at the target system. Reading the shared 208library binary gives enough information for assembling the malicious code 209misusing it. Still even a prelinked shared library can get loaded at a new 210random address just requiring the regular relocation process during the 211startup. Shared libraries not already prelinked are always loaded at 212a randomly chosen address. 213 214 <p>Position independent executables (PIE) contain position independent code 215similar to the shared libraries and therefore such executables get loaded at 216a randomly chosen address upon startup. PIE executables always load even 217already prelinked shared libraries at a random address. You can build such 218executable using <samp><span class="command">gcc -fPIE -pie</span></samp>. 219 220 <p>Heap (malloc storage), stack and custom mmap areas are always placed randomly 221(as long as the randomization is enabled). 222 223 <br><dt><code>show disable-randomization</code><dd>Show the current setting of the explicit disable of the native randomization of 224the virtual address space of the started program. 225 226 </dl> 227 228 </body></html> 229 230