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