| <html lang="en"> |
| <head> |
| <title>Starting - Debugging with GDB</title> |
| <meta http-equiv="Content-Type" content="text/html"> |
| <meta name="description" content="Debugging with GDB"> |
| <meta name="generator" content="makeinfo 4.13"> |
| <link title="Top" rel="start" href="index.html#Top"> |
| <link rel="up" href="Running.html#Running" title="Running"> |
| <link rel="prev" href="Compilation.html#Compilation" title="Compilation"> |
| <link rel="next" href="Arguments.html#Arguments" title="Arguments"> |
| <link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage"> |
| <!-- |
| Copyright (C) 1988-2019 Free Software Foundation, Inc. |
| |
| Permission is granted to copy, distribute and/or modify this document |
| under the terms of the GNU Free Documentation License, Version 1.3 or |
| any later version published by the Free Software Foundation; with the |
| Invariant Sections being ``Free Software'' and ``Free Software Needs |
| Free Documentation'', with the Front-Cover Texts being ``A GNU Manual,'' |
| and with the Back-Cover Texts as in (a) below. |
| |
| (a) The FSF's Back-Cover Text is: ``You are free to copy and modify |
| this GNU Manual. Buying copies from GNU Press supports the FSF in |
| developing GNU and promoting software freedom.'' |
| --> |
| <meta http-equiv="Content-Style-Type" content="text/css"> |
| <style type="text/css"><!-- |
| pre.display { font-family:inherit } |
| pre.format { font-family:inherit } |
| pre.smalldisplay { font-family:inherit; font-size:smaller } |
| pre.smallformat { font-family:inherit; font-size:smaller } |
| pre.smallexample { font-size:smaller } |
| pre.smalllisp { font-size:smaller } |
| span.sc { font-variant:small-caps } |
| span.roman { font-family:serif; font-weight:normal; } |
| span.sansserif { font-family:sans-serif; font-weight:normal; } |
| --></style> |
| </head> |
| <body> |
| <div class="node"> |
| <a name="Starting"></a> |
| <p> |
| Next: <a rel="next" accesskey="n" href="Arguments.html#Arguments">Arguments</a>, |
| Previous: <a rel="previous" accesskey="p" href="Compilation.html#Compilation">Compilation</a>, |
| Up: <a rel="up" accesskey="u" href="Running.html#Running">Running</a> |
| <hr> |
| </div> |
| |
| <h3 class="section">4.2 Starting your Program</h3> |
| |
| <p><a name="index-starting-112"></a><a name="index-running-113"></a> |
| |
| <a name="index-run-114"></a> |
| <a name="index-r-_0040r_007b_0028_0040code_007brun_007d_0029_007d-115"></a> |
| <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>. |
| You must first specify the program name with an argument 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 (see <a href="Files.html#Files">Commands to Specify Files</a>). |
| |
| </dl> |
| |
| <p>If you are running your program in an execution environment that |
| supports processes, <code>run</code> creates an inferior process and makes |
| that process run your program. In some environments without processes, |
| <code>run</code> jumps to the start of your program. Other targets, |
| like ‘<samp><span class="samp">remote</span></samp>’, are always running. If you get an error |
| message like this one: |
| |
| <pre class="smallexample"> The "remote" target does not support "run". |
| Try "help target" or "continue". |
| </pre> |
| <p class="noindent">then use <code>continue</code> to run your program. You may need <code>load</code> |
| first (see <a href="load.html#load">load</a>). |
| |
| <p>The execution of a program is affected by certain information it |
| receives from its superior. <span class="sc">gdb</span> provides ways to specify this |
| information, which you must do <em>before</em> starting your program. (You |
| can change it after starting your program, but such changes only affect |
| your program the next time you start it.) This information may be |
| divided into four categories: |
| |
| <dl> |
| <dt>The <em>arguments.</em><dd>Specify the arguments to give your program as the arguments of the |
| <code>run</code> command. If a shell is available on your target, the shell |
| is used to pass the arguments, so that you may use normal conventions |
| (such as wildcard expansion or variable substitution) in describing |
| the arguments. |
| In Unix systems, you can control which shell is used with the |
| <code>SHELL</code> environment variable. If you do not define <code>SHELL</code>, |
| <span class="sc">gdb</span> uses the default shell (<samp><span class="file">/bin/sh</span></samp>). You can disable |
| use of any shell with the <code>set startup-with-shell</code> command (see |
| below for details). |
| |
| <br><dt>The <em>environment.</em><dd>Your program normally inherits its environment from <span class="sc">gdb</span>, but you can |
| use the <span class="sc">gdb</span> commands <code>set environment</code> and <code>unset |
| environment</code> to change parts of the environment that affect |
| your program. See <a href="Environment.html#Environment">Your Program's Environment</a>. |
| |
| <br><dt>The <em>working directory.</em><dd>You can set your program's working directory with the command |
| <kbd>set cwd</kbd>. If you do not set any working directory with this |
| command, your program will inherit <span class="sc">gdb</span>'s working directory if |
| native debugging, or the remote server's working directory if remote |
| debugging. See <a href="Working-Directory.html#Working-Directory">Your Program's Working Directory</a>. |
| |
| <br><dt>The <em>standard input and output.</em><dd>Your program normally uses the same device for standard input and |
| standard output as <span class="sc">gdb</span> is using. You can redirect input and output |
| in the <code>run</code> command line, or you can use the <code>tty</code> command to |
| set a different device for your program. |
| See <a href="Input_002fOutput.html#Input_002fOutput">Your Program's Input and Output</a>. |
| |
| <p><a name="index-pipes-116"></a><em>Warning:</em> While input and output redirection work, you cannot use |
| pipes to pass the output of the program you are debugging to another |
| program; if you attempt this, <span class="sc">gdb</span> is likely to wind up debugging the |
| wrong program. |
| </dl> |
| |
| <p>When you issue the <code>run</code> command, your program begins to execute |
| immediately. See <a href="Stopping.html#Stopping">Stopping and Continuing</a>, for discussion |
| of how to arrange for your program to stop. Once your program has |
| stopped, you may call functions in your program, using the <code>print</code> |
| or <code>call</code> commands. See <a href="Data.html#Data">Examining Data</a>. |
| |
| <p>If the modification time of your symbol file has changed since the last |
| time <span class="sc">gdb</span> read its symbols, <span class="sc">gdb</span> discards its symbol |
| table, and reads it again. When it does this, <span class="sc">gdb</span> tries to retain |
| your current breakpoints. |
| |
| |
| <a name="index-start-117"></a> |
| <dl><dt><code>start</code><dd><a name="index-run-to-main-procedure-118"></a>The name of the main procedure can vary from language to language. |
| With C or C<tt>++</tt>, the main procedure name is always <code>main</code>, but |
| other languages such as Ada do not require a specific name for their |
| main procedure. The debugger provides a convenient way to start the |
| execution of the program and to stop at the beginning of the main |
| procedure, depending on the language used. |
| |
| <p>The ‘<samp><span class="samp">start</span></samp>’ command does the equivalent of setting a temporary |
| breakpoint at the beginning of the main procedure and then invoking |
| the ‘<samp><span class="samp">run</span></samp>’ command. |
| |
| <p><a name="index-elaboration-phase-119"></a>Some programs contain an <dfn>elaboration</dfn> phase where some startup code is |
| executed before the main procedure is called. This depends on the |
| languages used to write your program. In C<tt>++</tt>, for instance, |
| constructors for static and global objects are executed before |
| <code>main</code> is called. It is therefore possible that the debugger stops |
| before reaching the main procedure. However, the temporary breakpoint |
| will remain to halt execution. |
| |
| <p>Specify the arguments to give to your program as arguments to the |
| ‘<samp><span class="samp">start</span></samp>’ command. These arguments will be given verbatim to the |
| underlying ‘<samp><span class="samp">run</span></samp>’ command. Note that the same arguments will be |
| reused if no argument is provided during subsequent calls to |
| ‘<samp><span class="samp">start</span></samp>’ or ‘<samp><span class="samp">run</span></samp>’. |
| |
| <p>It is sometimes necessary to debug the program during elaboration. In |
| these cases, using the <code>start</code> command would stop the execution |
| of your program too late, as the program would have already completed |
| the elaboration phase. Under these circumstances, either insert |
| breakpoints in your elaboration code before running your program or |
| use the <code>starti</code> command. |
| |
| <p><a name="index-starti-120"></a><br><dt><code>starti</code><dd><a name="index-run-to-first-instruction-121"></a>The ‘<samp><span class="samp">starti</span></samp>’ command does the equivalent of setting a temporary |
| breakpoint at the first instruction of a program's execution and then |
| invoking the ‘<samp><span class="samp">run</span></samp>’ command. For programs containing an |
| elaboration phase, the <code>starti</code> command will stop execution at |
| the start of the elaboration phase. |
| |
| <p><a name="set-exec_002dwrapper"></a><a name="index-set-exec_002dwrapper-122"></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 |
| launch programs for debugging. <span class="sc">gdb</span> starts your program |
| with a shell command of the form <kbd>exec </kbd><var>wrapper</var> |
| <var>program</var>. Quoting is added to <var>program</var> and its |
| arguments, but not to <var>wrapper</var>, so you should add quotes if |
| appropriate for your shell. The wrapper runs until it executes |
| your program, and then <span class="sc">gdb</span> takes control. |
| |
| <p>You can use any program that eventually calls <code>execve</code> with |
| its arguments as a wrapper. Several standard Unix utilities do |
| this, e.g. <code>env</code> and <code>nohup</code>. Any Unix shell script ending |
| with <code>exec "$@"</code> will also work. |
| |
| <p>For example, you can use <code>env</code> to pass an environment variable to |
| the debugged program, without setting the variable in your shell's |
| environment: |
| |
| <pre class="smallexample"> (gdb) set exec-wrapper env 'LD_PRELOAD=libtest.so' |
| (gdb) run |
| </pre> |
| <p>This command is available when debugging locally on most targets, excluding |
| <span class="sc">djgpp</span>, Cygwin, MS Windows, and QNX Neutrino. |
| |
| <p><a name="index-set-startup_002dwith_002dshell-123"></a><a name="set-startup_002dwith_002dshell"></a><br><dt><code>set startup-with-shell</code><dt><code>set startup-with-shell on</code><dt><code>set startup-with-shell off</code><dt><code>show startup-with-shell</code><dd>On Unix systems, by default, if a shell is available on your target, |
| <span class="sc">gdb</span>) uses it to start your program. Arguments of the |
| <code>run</code> command are passed to the shell, which does variable |
| substitution, expands wildcard characters and performs redirection of |
| I/O. In some circumstances, it may be useful to disable such use of a |
| shell, for example, when debugging the shell itself or diagnosing |
| startup failures such as: |
| |
| <pre class="smallexample"> (gdb) run |
| Starting program: ./a.out |
| During startup program terminated with signal SIGSEGV, Segmentation fault. |
| </pre> |
| <p class="noindent">which indicates the shell or the wrapper specified with |
| ‘<samp><span class="samp">exec-wrapper</span></samp>’ crashed, not your program. Most often, this is |
| caused by something odd in your shell's non-interactive mode |
| initialization file—such as <samp><span class="file">.cshrc</span></samp> for C-shell, |
| $<samp><span class="file">.zshenv</span></samp> for the Z shell, or the file specified in the |
| ‘<samp><span class="samp">BASH_ENV</span></samp>’ environment variable for BASH. |
| |
| <p><a name="set-auto_002dconnect_002dnative_002dtarget"></a><a name="index-set-auto_002dconnect_002dnative_002dtarget-124"></a><br><dt><code>set auto-connect-native-target</code><dt><code>set auto-connect-native-target on</code><dt><code>set auto-connect-native-target off</code><dt><code>show auto-connect-native-target</code><dd> |
| By default, if not connected to any target yet (e.g., with |
| <code>target remote</code>), the <code>run</code> command starts your program as a |
| native process under <span class="sc">gdb</span>, on your local machine. If you're |
| sure you don't want to debug programs on your local machine, you can |
| tell <span class="sc">gdb</span> to not connect to the native target automatically |
| with the <code>set auto-connect-native-target off</code> command. |
| |
| <p>If <code>on</code>, which is the default, and if <span class="sc">gdb</span> is not |
| connected to a target already, the <code>run</code> command automaticaly |
| connects to the native target, if one is available. |
| |
| <p>If <code>off</code>, and if <span class="sc">gdb</span> is not connected to a target |
| already, the <code>run</code> command fails with an error: |
| |
| <pre class="smallexample"> (gdb) run |
| Don't know how to run. Try "help target". |
| </pre> |
| <p>If <span class="sc">gdb</span> is already connected to a target, <span class="sc">gdb</span> always |
| uses it with the <code>run</code> command. |
| |
| <p>In any case, you can explicitly connect to the native target with the |
| <code>target native</code> command. For example, |
| |
| <pre class="smallexample"> (gdb) set auto-connect-native-target off |
| (gdb) run |
| Don't know how to run. Try "help target". |
| (gdb) target native |
| (gdb) run |
| Starting program: ./a.out |
| [Inferior 1 (process 10421) exited normally] |
| </pre> |
| <p>In case you connected explicitly to the <code>native</code> target, |
| <span class="sc">gdb</span> remains connected even if all inferiors exit, ready for |
| the next <code>run</code> command. Use the <code>disconnect</code> command to |
| disconnect. |
| |
| <p>Examples of other commands that likewise respect the |
| <code>auto-connect-native-target</code> setting: <code>attach</code>, <code>info |
| proc</code>, <code>info os</code>. |
| |
| <p><a name="index-set-disable_002drandomization-125"></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 |
| randomization of the virtual address space of the started program. This option |
| is useful for multiple debugging sessions to make the execution better |
| reproducible and memory addresses reusable across debugging sessions. |
| |
| <p>This feature is implemented only on certain targets, including <span class="sc">gnu</span>/Linux. |
| On <span class="sc">gnu</span>/Linux you can get the same behavior using |
| |
| <pre class="smallexample"> (gdb) set exec-wrapper setarch `uname -m` -R |
| </pre> |
| <br><dt><code>set disable-randomization off</code><dd>Leave the behavior of the started executable unchanged. Some bugs rear their |
| ugly heads only when the program is loaded at certain addresses. If your bug |
| disappears when you run the program under <span class="sc">gdb</span>, that might be because |
| <span class="sc">gdb</span> by default disables the address randomization on platforms, such |
| as <span class="sc">gnu</span>/Linux, which do that for stand-alone programs. Use <kbd>set |
| disable-randomization off</kbd> to try to reproduce such elusive bugs. |
| |
| <p>On targets where it is available, virtual address space randomization |
| protects the programs against certain kinds of security attacks. In these |
| cases the attacker needs to know the exact location of a concrete executable |
| code. Randomizing its location makes it impossible to inject jumps misusing |
| a code at its expected addresses. |
| |
| <p>Prelinking shared libraries provides a startup performance advantage but it |
| makes addresses in these libraries predictable for privileged processes by |
| having just unprivileged access at the target system. Reading the shared |
| library binary gives enough information for assembling the malicious code |
| misusing it. Still even a prelinked shared library can get loaded at a new |
| random address just requiring the regular relocation process during the |
| startup. Shared libraries not already prelinked are always loaded at |
| a randomly chosen address. |
| |
| <p>Position independent executables (PIE) contain position independent code |
| similar to the shared libraries and therefore such executables get loaded at |
| a randomly chosen address upon startup. PIE executables always load even |
| already prelinked shared libraries at a random address. You can build such |
| executable using <samp><span class="command">gcc -fPIE -pie</span></samp>. |
| |
| <p>Heap (malloc storage), stack and custom mmap areas are always placed randomly |
| (as long as the randomization is enabled). |
| |
| <br><dt><code>show disable-randomization</code><dd>Show the current setting of the explicit disable of the native randomization of |
| the virtual address space of the started program. |
| |
| </dl> |
| |
| </body></html> |
| |