299 lines
17 KiB
HTML
299 lines
17 KiB
HTML
|
<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>
|
||
|
|
|