2 _dnl__ Copyright (c) 1988 1989 1990 1991 Free Software Foundation, Inc.
3 _dnl__ This file is part of the source for the GDB manual.
5 @node Targets, Controlling _GDBN__, _GDBN__ Files, Top
6 @chapter Specifying a Debugging Target
7 @cindex debugging target
9 A @dfn{target} is an interface between the debugger and a particular
10 kind of file or process.
12 Often, you will be able to run _GDBN__ in the same host environment as the
13 program you are debugging; in that case, the debugging target can just be
14 specified as a side effect of the @code{file} or @code{core} commands.
15 When you need more flexibility---for example, running _GDBN__ on a
16 physically separate host, controlling standalone systems over a
17 serial port, or realtime systems over a TCP/IP connection---you can use
18 the @code{target} command.
21 * Active Targets:: Active Targets
22 * Target Commands:: Commands for Managing Targets
23 * Remote:: Remote Debugging
26 @node Active Targets, Target Commands, Targets, Targets
27 @section Active Targets
28 @cindex stacking targets
29 @cindex active targets
30 @cindex multiple targets
32 Targets are managed in three @dfn{strata} that correspond to different
33 classes of target: processes, core files, and executable files. This
34 allows you to (for example) start a process and inspect its activity
35 without abandoning your work on a core file.
37 More than one target can potentially respond to a request. In
38 particular, when you access memory _GDBN__ will examine the three strata of
39 targets until it finds a target that can handle that particular address.
40 Strata are always examined in a fixed order: first a process if there is
41 one, then a core file if there is one, and finally an executable file if
42 there is one of those.
44 When you specify a new target in a given stratum, it replaces any target
45 previously in that stratum.
47 To get rid of a target without replacing it, use the @code{detach}
48 command. The related command @code{attach} provides you with a way of
49 choosing a particular running process as a new target. @xref{Attach}.
51 @node Target Commands, Remote, Active Targets, Targets
52 @section Commands for Managing Targets
55 @item target @var{type} @var{parameters}
56 Connects the _GDBN__ host environment to a target machine or process. A
57 target is typically a protocol for talking to debugging facilities. You
58 use the argument @var{type} to specify the type or protocol of the
61 Further @var{parameters} are interpreted by the target protocol, but
62 typically include things like device names or host names to connect
63 with, process numbers, and baud rates.
65 The @code{target} command will not repeat if you press @key{RET} again
66 after executing the command.
70 Displays the names of all targets available. To display targets
71 currently selected, use either @code{info target} or @code{info files}
74 @item help target @var{name}
75 Describe a particular target, including any parameters necessary to
79 Here are some common targets (available, or not, depending on the _GDBN__
83 @item target exec @var{prog}
85 An executable file. @samp{target exec @var{prog}} is the same as
86 @samp{exec-file @var{prog}}.
88 @item target core @var{filename}
90 A core dump file. @samp{target core @var{filename}} is the same as
91 @samp{core-file @var{filename}}.
93 @item target remote @var{dev}
95 Remote serial target in _GDBN__-specific protocol. The argument @var{dev}
96 specifies what serial device to use for the connection (e.g.
97 @file{/dev/ttya}). @xref{Remote}.
100 @item target amd-eb @var{dev} @var{speed} @var{PROG}
101 @kindex target amd-eb
103 Remote PC-resident AMD EB29K board, attached over serial lines.
104 @var{dev} is the serial device, as for @code{target remote};
105 @var{speed} allows you to specify the linespeed; and @var{PROG} is the
106 name of the program to be debugged, as it appears to DOS on the PC.
111 @item target nindy @var{devicename}
113 An Intel 960 board controlled by a Nindy Monitor. @var{devicename} is
114 the name of the serial device to use for the connection, e.g.
115 @file{/dev/ttya}. @xref{i960-Nindy Remote}.
119 @item target vxworks @var{machinename}
120 @kindex target vxworks
121 A VxWorks system, attached via TCP/IP. The argument @var{machinename}
122 is the target system's machine name or IP address.
123 @xref{VxWorks Remote}.
128 Different targets are available on different configurations of _GDBN__; your
129 configuration may have more or fewer targets.
132 @node Remote, , Target Commands, Targets
133 @section Remote Debugging
134 @cindex remote debugging
138 _include__(gdb.inv.m-m4)<>_dnl__
142 If you are trying to debug a program running on a machine that can't run
143 _GDBN__ in the usual way, it is often useful to use remote debugging. For
144 example, you might use remote debugging on an operating system kernel, or on
145 a small system which does not have a general purpose operating system
146 powerful enough to run a full-featured debugger.
148 Some configurations of _GDBN__ have special serial or TCP/IP interfaces
149 to make this work with particular debugging targets. In addition,
150 _GDBN__ comes with a generic serial protocol (specific to _GDBN__, but
151 not specific to any particular target system) which you can use if you
152 write the remote stubs---the code that will run on the remote system to
153 communicate with _GDBN__.
155 To use the _GDBN__ remote serial protocol, the program to be debugged on
156 the remote machine needs to contain a debugging stub which talks to
157 _GDBN__ over the serial line. Several working remote stubs are
158 distributed with _GDBN__; see the @file{README} file in the _GDBN__
159 distribution for more information.
161 For details of this communication protocol, see the comments in the
162 _GDBN__ source file @file{remote.c}.
164 To start remote debugging, first run _GDBN__ and specify as an executable file
165 the program that is running in the remote machine. This tells _GDBN__ how
166 to find the program's symbols and the contents of its pure text. Then
167 establish communication using the @code{target remote} command with a device
168 name as an argument. For example:
171 target remote /dev/ttyb
175 if the serial line is connected to the device named @file{/dev/ttyb}. This
176 will stop the remote machine if it is not already stopped.
178 Now you can use all the usual commands to examine and change data and to
179 step and continue the remote program.
181 To resume the remote program and stop debugging it, use the @code{detach}
184 Other remote targets may be available in your
185 configuration of _GDBN__; use @code{help targets} to list them.
188 _include__(gdb.inv.s-m4)
189 @c Text on starting up GDB in various specific cases; it goes up front
190 @c in manuals configured for any of those particular situations, here