<HTML>
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<!-- Created on March, 27 2008 by texi2html 1.64 -->
<!--
Written by: Lionel Cons <Lionel.Cons@cern.ch> (original author)
Karl Berry <karl@freefriends.org>
Olaf Bachmann <obachman@mathematik.uni-kl.de>
and many others.
Maintained by: Olaf Bachmann <obachman@mathematik.uni-kl.de>
Send bugs and suggestions to <texi2html@mathematik.uni-kl.de>
-->
<HEAD>
<TITLE>Debugging with GDB: Targets</TITLE>
<META NAME="description" CONTENT="Debugging with GDB: Targets">
<META NAME="keywords" CONTENT="Debugging with GDB: Targets">
<META NAME="resource-type" CONTENT="document">
<META NAME="distribution" CONTENT="global">
<META NAME="Generator" CONTENT="texi2html 1.64">
</HEAD>
<BODY LANG="" BGCOLOR="#FFFFFF" TEXT="#000000" LINK="#0000FF" VLINK="#800080" ALINK="#FF0000">
<A NAME="SEC158"></A>
<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_16.html#SEC157"> < </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_17.html#SEC159"> > </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_3.html#SEC6"> << </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb.html#SEC_Top"> Up </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_18.html#SEC162"> >> </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb.html#SEC_Top">Top</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_toc.html#SEC_Contents">Contents</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_38.html#SEC764">Index</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_abt.html#SEC_About"> ? </A>]</TD>
</TR></TABLE>
<H1> 16. Specifying a Debugging Target </H1>
<!--docid::SEC158::-->
<P>
<A NAME="IDX763"></A>
A <EM>target</EM> is the execution environment occupied by your program.
</P><P>
Often, GDB runs in the same host environment as your program;
in that case, the debugging target is specified as a side effect when
you use the <CODE>file</CODE> or <CODE>core</CODE> commands. When you need more
flexibility--for example, running GDB on a physically separate
host, or controlling a standalone system over a serial port or a
realtime system over a TCP/IP connection--you can use the <CODE>target</CODE>
command to specify one of the target types configured for GDB
(see section <A HREF="gdb_17.html#SEC160">Commands for Managing Targets</A>).
</P><P>
<A NAME="IDX764"></A>
It is possible to build GDB for several different <EM>target
architectures</EM>. When GDB is built like that, you can choose
one of the available architectures with the <KBD>set architecture</KBD>
command.
</P><P>
<DL COMPACT>
<A NAME="IDX765"></A>
<A NAME="IDX766"></A>
<DT><CODE>set architecture <VAR>arch</VAR></CODE>
<DD>This command sets the current target architecture to <VAR>arch</VAR>. The
value of <VAR>arch</VAR> can be <CODE>"auto"</CODE>, in addition to one of the
supported architectures.
<P>
<DT><CODE>show architecture</CODE>
<DD>Show the current target architecture.
<P>
<DT><CODE>set processor</CODE>
<DD><DT><CODE>processor</CODE>
<DD><A NAME="IDX767"></A>
<A NAME="IDX768"></A>
These are alias commands for, respectively, <CODE>set architecture</CODE>
and <CODE>show architecture</CODE>.
</DL>
<P>
<BLOCKQUOTE><TABLE BORDER=0 CELLSPACING=0>
<TR><TD ALIGN="left" VALIGN="TOP"><A HREF="gdb_17.html#SEC159">16.1 Active Targets</A></TD><TD> </TD><TD ALIGN="left" VALIGN="TOP">Active targets</TD></TR>
<TR><TD ALIGN="left" VALIGN="TOP"><A HREF="gdb_17.html#SEC160">16.2 Commands for Managing Targets</A></TD><TD> </TD><TD ALIGN="left" VALIGN="TOP">Commands for managing targets</TD></TR>
<TR><TD ALIGN="left" VALIGN="TOP"><A HREF="gdb_17.html#SEC161">16.3 Choosing Target Byte Order</A></TD><TD> </TD><TD ALIGN="left" VALIGN="TOP">Choosing target byte order</TD></TR>
</TABLE></BLOCKQUOTE>
<P>
<A NAME="Active Targets"></A>
<HR SIZE="6">
<A NAME="SEC159"></A>
<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_17.html#SEC158"> < </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_17.html#SEC160"> > </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_17.html#SEC158"> << </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_17.html#SEC158"> Up </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_18.html#SEC162"> >> </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb.html#SEC_Top">Top</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_toc.html#SEC_Contents">Contents</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_38.html#SEC764">Index</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_abt.html#SEC_About"> ? </A>]</TD>
</TR></TABLE>
<H2> 16.1 Active Targets </H2>
<!--docid::SEC159::-->
<P>
<A NAME="IDX769"></A>
<A NAME="IDX770"></A>
<A NAME="IDX771"></A>
</P><P>
There are three classes of targets: processes, core files, and
executable files. GDB can work concurrently on up to three
active targets, one in each class. This allows you to (for example)
start a process and inspect its activity without abandoning your work on
a core file.
</P><P>
For example, if you execute <SAMP>`gdb a.out'</SAMP>, then the executable file
<CODE>a.out</CODE> is the only active target. If you designate a core file as
well--presumably from a prior run that crashed and coredumped--then
GDB has two active targets and uses them in tandem, looking
first in the corefile target, then in the executable file, to satisfy
requests for memory addresses. (Typically, these two classes of target
are complementary, since core files contain only a program's
read-write memory--variables and so on--plus machine status, while
executable files contain only the program text and initialized data.)
</P><P>
When you type <CODE>run</CODE>, your executable file becomes an active process
target as well. When a process target is active, all GDB
commands requesting memory addresses refer to that target; addresses in
an active core file or executable file target are obscured while the
process target is active.
</P><P>
Use the <CODE>core-file</CODE> and <CODE>exec-file</CODE> commands to select a new
core file or executable target (see section <A HREF="gdb_16.html#SEC155">Commands to Specify Files</A>). To specify as a target a process that is already running, use
the <CODE>attach</CODE> command (see section <A HREF="gdb_5.html#SEC25">Debugging an Already-running Process</A>).
</P><P>
<A NAME="Target Commands"></A>
<HR SIZE="6">
<A NAME="SEC160"></A>
<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_17.html#SEC159"> < </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_17.html#SEC161"> > </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_17.html#SEC161"> << </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_17.html#SEC158"> Up </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_18.html#SEC162"> >> </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb.html#SEC_Top">Top</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_toc.html#SEC_Contents">Contents</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_38.html#SEC764">Index</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_abt.html#SEC_About"> ? </A>]</TD>
</TR></TABLE>
<H2> 16.2 Commands for Managing Targets </H2>
<!--docid::SEC160::-->
<P>
<DL COMPACT>
<DT><CODE>target <VAR>type</VAR> <VAR>parameters</VAR></CODE>
<DD>Connects the GDB host environment to a target machine or
process. A target is typically a protocol for talking to debugging
facilities. You use the argument <VAR>type</VAR> to specify the type or
protocol of the target machine.
<P>
Further <VAR>parameters</VAR> are interpreted by the target protocol, but
typically include things like device names or host names to connect
with, process numbers, and baud rates.
</P><P>
The <CODE>target</CODE> command does not repeat if you press <KBD>RET</KBD> again
after executing the command.
</P><P>
<A NAME="IDX772"></A>
<DT><CODE>help target</CODE>
<DD>Displays the names of all targets available. To display targets
currently selected, use either <CODE>info target</CODE> or <CODE>info files</CODE>
(see section <A HREF="gdb_16.html#SEC155">Commands to Specify Files</A>).
<P>
<DT><CODE>help target <VAR>name</VAR></CODE>
<DD>Describe a particular target, including any parameters necessary to
select it.
<P>
<A NAME="IDX773"></A>
<DT><CODE>set gnutarget <VAR>args</VAR></CODE>
<DD>GDB uses its own library BFD to read your files. GDB
knows whether it is reading an <EM>executable</EM>,
a <EM>core</EM>, or a <EM>.o</EM> file; however, you can specify the file format
with the <CODE>set gnutarget</CODE> command. Unlike most <CODE>target</CODE> commands,
with <CODE>gnutarget</CODE> the <CODE>target</CODE> refers to a program, not a machine.
<P>
<BLOCKQUOTE>
<EM>Warning:</EM> To specify a file format with <CODE>set gnutarget</CODE>,
you must know the actual BFD name.
</BLOCKQUOTE>
<P>
See section <A HREF="gdb_16.html#SEC155">Commands to Specify Files</A>.
</P><P>
<A NAME="IDX774"></A>
<DT><CODE>show gnutarget</CODE>
<DD>Use the <CODE>show gnutarget</CODE> command to display what file format
<CODE>gnutarget</CODE> is set to read. If you have not set <CODE>gnutarget</CODE>,
GDB will determine the file format for each file automatically,
and <CODE>show gnutarget</CODE> displays <SAMP>`The current BDF target is "auto"'</SAMP>.
</DL>
<P>
<A NAME="IDX775"></A>
Here are some common targets (available, or not, depending on the GDB
configuration):
</P><P>
<DL COMPACT>
<A NAME="IDX776"></A>
<DT><CODE>target exec <VAR>program</VAR></CODE>
<DD><A NAME="IDX777"></A>
An executable file. <SAMP>`target exec <VAR>program</VAR>'</SAMP> is the same as
<SAMP>`exec-file <VAR>program</VAR>'</SAMP>.
<P>
<DT><CODE>target core <VAR>filename</VAR></CODE>
<DD><A NAME="IDX778"></A>
A core dump file. <SAMP>`target core <VAR>filename</VAR>'</SAMP> is the same as
<SAMP>`core-file <VAR>filename</VAR>'</SAMP>.
<P>
<DT><CODE>target remote <VAR>medium</VAR></CODE>
<DD><A NAME="IDX779"></A>
A remote system connected to GDB via a serial line or network
connection. This command tells GDB to use its own remote
protocol over <VAR>medium</VAR> for debugging. See section <A HREF="gdb_18.html#SEC162">17. Debugging Remote Programs</A>.
<P>
For example, if you have a board connected to <TT>`/dev/ttya'</TT> on the
machine running GDB, you could say:
</P><P>
<TABLE><tr><td> </td><td class=smallexample><FONT SIZE=-1><pre>target remote /dev/ttya
</FONT></pre></td></tr></table></P><P>
<CODE>target remote</CODE> supports the <CODE>load</CODE> command. This is only
useful if you have some other way of getting the stub to the target
system, and you can put it somewhere in memory where it won't get
clobbered by the download.
</P><P>
<DT><CODE>target sim</CODE>
<DD><A NAME="IDX780"></A>
Builtin CPU simulator. GDB includes simulators for most architectures.
In general,
<TABLE><tr><td> </td><td class=smallexample><FONT SIZE=-1><pre> target sim
load
run
</FONT></pre></td></tr></table>works; however, you cannot assume that a specific memory map, device
drivers, or even basic I/O is available, although some simulators do
provide these. For info about any processor-specific simulator details,
see the appropriate section in <A HREF="gdb_19.html#SEC194">Embedded Processors</A>.
<P>
</DL>
<P>
Some configurations may include these targets as well:
</P><P>
<DL COMPACT>
<DT><CODE>target nrom <VAR>dev</VAR></CODE>
<DD><A NAME="IDX781"></A>
NetROM ROM emulator. This target only supports downloading.
<P>
</DL>
<P>
Different targets are available on different configurations of GDB;
your configuration may have more or fewer targets.
</P><P>
Many remote targets require you to download the executable's code once
you've successfully established a connection. You may wish to control
various aspects of this process.
</P><P>
<DL COMPACT>
<DT><CODE>set hash</CODE>
<DD><A NAME="IDX782"></A>
<A NAME="IDX783"></A>
This command controls whether a hash mark <SAMP>`#'</SAMP> is displayed while
downloading a file to the remote monitor. If on, a hash mark is
displayed after each S-record is successfully downloaded to the
monitor.
<P>
<DT><CODE>show hash</CODE>
<DD><A NAME="IDX784"></A>
Show the current status of displaying the hash mark.
<P>
<DT><CODE>set debug monitor</CODE>
<DD><A NAME="IDX785"></A>
<A NAME="IDX786"></A>
Enable or disable display of communications messages between
GDB and the remote monitor.
<P>
<DT><CODE>show debug monitor</CODE>
<DD><A NAME="IDX787"></A>
Show the current status of displaying communications between
GDB and the remote monitor.
</DL>
<P>
<DL COMPACT>
<A NAME="IDX788"></A>
<DT><CODE>load <VAR>filename</VAR></CODE>
<DD>Depending on what remote debugging facilities are configured into
GDB, the <CODE>load</CODE> command may be available. Where it exists, it
is meant to make <VAR>filename</VAR> (an executable) available for debugging
on the remote system--by downloading, or dynamic linking, for example.
<CODE>load</CODE> also records the <VAR>filename</VAR> symbol table in GDB, like
the <CODE>add-symbol-file</CODE> command.
<P>
If your GDB does not have a <CODE>load</CODE> command, attempting to
execute it gets the error message "<CODE>You can't do that when your
target is <small>...</small></CODE>"
</P><P>
The file is loaded at whatever address is specified in the executable.
For some object file formats, you can specify the load address when you
link the program; for other formats, like a.out, the object file format
specifies a fixed address.
</P><P>
Depending on the remote side capabilities, GDB may be able to
load programs into flash memory.
</P><P>
<CODE>load</CODE> does not repeat if you press <KBD>RET</KBD> again after using it.
</DL>
<P>
<A NAME="Byte Order"></A>
<HR SIZE="6">
<A NAME="SEC161"></A>
<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_17.html#SEC160"> < </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_18.html#SEC162"> > </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_17.html#SEC158"> << </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_17.html#SEC158"> Up </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_18.html#SEC162"> >> </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb.html#SEC_Top">Top</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_toc.html#SEC_Contents">Contents</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_38.html#SEC764">Index</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_abt.html#SEC_About"> ? </A>]</TD>
</TR></TABLE>
<H2> 16.3 Choosing Target Byte Order </H2>
<!--docid::SEC161::-->
<P>
<A NAME="IDX789"></A>
<A NAME="IDX790"></A>
</P><P>
Some types of processors, such as the MIPS, PowerPC, and Renesas SH,
offer the ability to run either big-endian or little-endian byte
orders. Usually the executable or symbol will include a bit to
designate the endian-ness, and you will not need to worry about
which to use. However, you may still find it useful to adjust
GDB's idea of processor endian-ness manually.
</P><P>
<DL COMPACT>
<A NAME="IDX791"></A>
<DT><CODE>set endian big</CODE>
<DD>Instruct GDB to assume the target is big-endian.
<P>
<DT><CODE>set endian little</CODE>
<DD>Instruct GDB to assume the target is little-endian.
<P>
<DT><CODE>set endian auto</CODE>
<DD>Instruct GDB to use the byte order associated with the
executable.
<P>
<DT><CODE>show endian</CODE>
<DD>Display GDB's current idea of the target byte order.
<P>
</DL>
<P>
Note that these commands merely adjust interpretation of symbolic
data on the host, and that they have absolutely no effect on the
target system.
</P><P>
<A NAME="Remote Debugging"></A>
<HR SIZE="6">
<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_17.html#SEC158"> << </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_18.html#SEC162"> >> </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb.html#SEC_Top">Top</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_toc.html#SEC_Contents">Contents</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_38.html#SEC764">Index</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_abt.html#SEC_About"> ? </A>]</TD>
</TR></TABLE>
<BR>
<FONT SIZE="-1">
<address>
<p>Please send FSF & GNU inquiries & questions to <a
href="mailto:gnu@gnu.org">gnu@gnu.org</a>. There are also <a
href="http://www.gnu.org/home.html#ContactInfo">other ways to
contact</a> the FSF.</p>
<p>These pages are maintained by <a
href="http://www.gnu.org/software/gdb/">the GDB developers</a>.</p>
<p>Copyright Free Software Foundation, Inc., 59 Temple Place - Suite
330, Boston, MA 02111, USA.</p>
<p>Verbatim copying and distribution of this entire article is
permitted in any medium, provided this notice is preserved.</p>
</address>
This document was generated
by <I>GDB Administrator</I> on <I>March, 27 2008</I>
using <A HREF="http://www.mathematik.uni-kl.de/~obachman/Texi2html
"><I>texi2html</I></A>
</BODY>
</HTML>