1
.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.16)
4
.\" ========================================================================
5
.de Sp \" Vertical space (when we can't use .PP)
9
.de Vb \" Begin verbatim text
14
.de Ve \" End verbatim text
18
.\" Set up some character translations and predefined strings. \*(-- will
19
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
20
.\" double quote, and \*(R" will give a right double quote. \*(C+ will
21
.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
22
.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
23
.\" nothing in troff, for use with C<>.
25
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
29
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
30
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
43
.\" Escape single quotes in literal strings from groff's Unicode transform.
47
.\" If the F register is turned on, we'll generate index entries on stderr for
48
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
49
.\" entries marked with X<> in POD. Of course, you'll have to process the
50
.\" output yourself in some meaningful fashion.
53
. tm Index:\\$1\t\\n%\t"\\$2"
63
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
64
.\" Fear. Run. Save yourself. No user-serviceable parts.
65
. \" fudge factors for nroff and troff
74
. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
80
. \" simple accents for nroff and troff
90
. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
91
. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
92
. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
93
. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
94
. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
95
. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
97
. \" troff and (daisy-wheel) nroff accents
98
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
99
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
100
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
101
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
102
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
103
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
104
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
105
.ds ae a\h'-(\w'a'u*4/10)'e
106
.ds Ae A\h'-(\w'A'u*4/10)'E
107
. \" corrections for vroff
108
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
109
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
110
. \" for low resolution devices (crt and lpr)
111
.if \n(.H>23 .if \n(.V>19 \
124
.\" ========================================================================
126
.IX Title "GDBSERVER 1"
127
.TH GDBSERVER 1 "2014-05-05" "gdb-7.7.1" "GNU Development Tools"
128
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
129
.\" way too many mistakes in technical documents.
133
gdbserver \- Remote Server for the GNU Debugger
135
.IX Header "SYNOPSIS"
136
gdbserver \fIcomm\fR \fIprog\fR [\fIargs\fR...]
138
gdbserver \-\-attach \fIcomm\fR \fIpid\fR
140
gdbserver \-\-multi \fIcomm\fR
142
.IX Header "DESCRIPTION"
143
\&\fBgdbserver\fR is a program that allows you to run \s-1GDB\s0 on a different machine
144
than the one which is running the program being debugged.
146
Usage (server (target) side):
148
First, you need to have a copy of the program you want to debug put onto
149
the target system. The program can be stripped to save space if needed, as
150
\&\fBgdbserver\fR doesn't care about symbols. All symbol handling is taken care of by
151
the \s-1GDB\s0 running on the host system.
153
To use the server, you log on to the target system, and run the \fBgdbserver\fR
154
program. You must tell it (a) how to communicate with \s-1GDB\s0, (b) the name of
155
your program, and (c) its arguments. The general syntax is:
158
\& target> gdbserver <comm> <program> [<args> ...]
161
For example, using a serial port, you might say:
164
\& target> gdbserver /dev/com1 emacs foo.txt
167
This tells \fBgdbserver\fR to debug emacs with an argument of foo.txt, and
168
to communicate with \s-1GDB\s0 via \fI/dev/com1\fR. \fBgdbserver\fR now
169
waits patiently for the host \s-1GDB\s0 to communicate with it.
171
To use a \s-1TCP\s0 connection, you could say:
174
\& target> gdbserver host:2345 emacs foo.txt
177
This says pretty much the same thing as the last example, except that we are
178
going to communicate with the \f(CW\*(C`host\*(C'\fR \s-1GDB\s0 via \s-1TCP\s0. The \f(CW\*(C`host:2345\*(C'\fR argument means
179
that we are expecting to see a \s-1TCP\s0 connection from \f(CW\*(C`host\*(C'\fR to local \s-1TCP\s0 port
180
2345. (Currently, the \f(CW\*(C`host\*(C'\fR part is ignored.) You can choose any number you
181
want for the port number as long as it does not conflict with any existing \s-1TCP\s0
182
ports on the target system. This same port number must be used in the host
183
GDBs \f(CW\*(C`target remote\*(C'\fR command, which will be described shortly. Note that if
184
you chose a port number that conflicts with another service, \fBgdbserver\fR will
185
print an error message and exit.
187
\&\fBgdbserver\fR can also attach to running programs.
188
This is accomplished via the \fB\-\-attach\fR argument. The syntax is:
191
\& target> gdbserver \-\-attach <comm> <pid>
194
\&\fIpid\fR is the process \s-1ID\s0 of a currently running process. It isn't
195
necessary to point \fBgdbserver\fR at a binary for the running process.
197
To start \f(CW\*(C`gdbserver\*(C'\fR without supplying an initial command to run
198
or process \s-1ID\s0 to attach, use the \fB\-\-multi\fR command line option.
199
In such case you should connect using \f(CW\*(C`target extended\-remote\*(C'\fR to start
200
the program you want to debug.
203
\& target> gdbserver \-\-multi <comm>
208
You need an unstripped copy of the target program on your host system, since
209
\&\s-1GDB\s0 needs to examine it's symbol tables and such. Start up \s-1GDB\s0 as you normally
210
would, with the target program as the first argument. (You may need to use the
211
\&\fB\-\-baud\fR option if the serial line is running at anything except 9600 baud.)
212
That is \f(CW\*(C`gdb TARGET\-PROG\*(C'\fR, or \f(CW\*(C`gdb \-\-baud BAUD TARGET\-PROG\*(C'\fR. After that, the only
213
new command you need to know about is \f(CW\*(C`target remote\*(C'\fR
214
(or \f(CW\*(C`target extended\-remote\*(C'\fR). Its argument is either
215
a device name (usually a serial device, like \fI/dev/ttyb\fR), or a \f(CW\*(C`HOST:PORT\*(C'\fR
216
descriptor. For example:
219
\& (gdb) target remote /dev/ttyb
222
communicates with the server via serial line \fI/dev/ttyb\fR, and:
225
\& (gdb) target remote the\-target:2345
228
communicates via a \s-1TCP\s0 connection to port 2345 on host `the\-target', where
229
you previously started up \fBgdbserver\fR with the same port number. Note that for
230
\&\s-1TCP\s0 connections, you must start up \fBgdbserver\fR prior to using the `target remote'
231
command, otherwise you may get an error that looks something like
232
`Connection refused'.
234
\&\fBgdbserver\fR can also debug multiple inferiors at once,
236
the \s-1GDB\s0 manual in node \f(CW\*(C`Inferiors and Programs\*(C'\fR
237
\&\*(-- shell command \f(CW\*(C`info \-f gdb \-n \*(AqInferiors and Programs\*(Aq\*(C'\fR.
238
In such case use the \f(CW\*(C`extended\-remote\*(C'\fR \s-1GDB\s0 command variant:
241
\& (gdb) target extended\-remote the\-target:2345
244
The \fBgdbserver\fR option \fB\-\-multi\fR may or may not be used in such
248
There are three different modes for invoking \fBgdbserver\fR:
250
Debug a specific program specified by its program name:
253
\& gdbserver <comm> <prog> [<args>...]
256
The \fIcomm\fR parameter specifies how should the server communicate
257
with \s-1GDB\s0; it is either a device name (to use a serial line),
258
a \s-1TCP\s0 port number (\f(CW\*(C`:1234\*(C'\fR), or \f(CW\*(C`\-\*(C'\fR or \f(CW\*(C`stdio\*(C'\fR to use
259
stdin/stdout of \f(CW\*(C`gdbserver\*(C'\fR. Specify the name of the program to
260
debug in \fIprog\fR. Any remaining arguments will be passed to the
261
program verbatim. When the program exits, \s-1GDB\s0 will close the
262
connection, and \f(CW\*(C`gdbserver\*(C'\fR will exit.
264
Debug a specific program by specifying the process \s-1ID\s0 of a running
268
\& gdbserver \-\-attach <comm> <pid>
271
The \fIcomm\fR parameter is as described above. Supply the process \s-1ID\s0
272
of a running program in \fIpid\fR; \s-1GDB\s0 will do everything
273
else. Like with the previous mode, when the process \fIpid\fR exits,
274
\&\s-1GDB\s0 will close the connection, and \f(CW\*(C`gdbserver\*(C'\fR will exit.
276
Multi-process mode \*(-- debug more than one program/process:
279
\& gdbserver \-\-multi <comm>
282
In this mode, \s-1GDB\s0 can instruct \fBgdbserver\fR which
283
command(s) to run. Unlike the other 2 modes, \s-1GDB\s0 will not
284
close the connection when a process being debugged exits, so you can
285
debug several processes in the same session.
287
In each of the modes you may specify these options:
288
.IP "\fB\-\-help\fR" 4
290
List all options, with brief explanations.
291
.IP "\fB\-\-version\fR" 4
293
This option causes \fBgdbserver\fR to print its version number and exit.
294
.IP "\fB\-\-attach\fR" 4
296
\&\fBgdbserver\fR will attach to a running program. The syntax is:
299
\& target> gdbserver \-\-attach <comm> <pid>
302
\&\fIpid\fR is the process \s-1ID\s0 of a currently running process. It isn't
303
necessary to point \fBgdbserver\fR at a binary for the running process.
304
.IP "\fB\-\-multi\fR" 4
306
To start \f(CW\*(C`gdbserver\*(C'\fR without supplying an initial command to run
307
or process \s-1ID\s0 to attach, use this command line option.
308
Then you can connect using \f(CW\*(C`target extended\-remote\*(C'\fR and start
309
the program you want to debug. The syntax is:
312
\& target> gdbserver \-\-multi <comm>
314
.IP "\fB\-\-debug\fR" 4
316
Instruct \f(CW\*(C`gdbserver\*(C'\fR to display extra status information about the debugging
318
This option is intended for \f(CW\*(C`gdbserver\*(C'\fR development and for bug reports to
320
.IP "\fB\-\-remote\-debug\fR" 4
321
.IX Item "--remote-debug"
322
Instruct \f(CW\*(C`gdbserver\*(C'\fR to display remote protocol debug output.
323
This option is intended for \f(CW\*(C`gdbserver\*(C'\fR development and for bug reports to
325
.IP "\fB\-\-wrapper\fR" 4
327
Specify a wrapper to launch programs
328
for debugging. The option should be followed by the name of the
329
wrapper, then any command-line arguments to pass to the wrapper, then
330
\&\f(CW\*(C`\-\-\*(C'\fR indicating the end of the wrapper arguments.
331
.IP "\fB\-\-once\fR" 4
333
By default, \fBgdbserver\fR keeps the listening \s-1TCP\s0 port open, so that
334
additional connections are possible. However, if you start \f(CW\*(C`gdbserver\*(C'\fR
335
with the \fB\-\-once\fR option, it will stop listening for any further
336
connection attempts after connecting to the first \s-1GDB\s0 session.
338
.IX Header "SEE ALSO"
339
The full documentation for \s-1GDB\s0 is maintained as a Texinfo manual.
340
If the \f(CW\*(C`info\*(C'\fR and \f(CW\*(C`gdb\*(C'\fR programs and \s-1GDB\s0's Texinfo
341
documentation are properly installed at your site, the command
347
should give you access to the complete manual.
349
\&\fIUsing \s-1GDB:\s0 A Guide to the \s-1GNU\s0 Source-Level Debugger\fR,
350
Richard M. Stallman and Roland H. Pesch, July 1991.
352
.IX Header "COPYRIGHT"
353
Copyright (c) 1988\-2014 Free Software Foundation, Inc.
355
Permission is granted to copy, distribute and/or modify this document
356
under the terms of the \s-1GNU\s0 Free Documentation License, Version 1.3 or
357
any later version published by the Free Software Foundation; with the
358
Invariant Sections being \*(L"Free Software\*(R" and \*(L"Free Software Needs
359
Free Documentation\*(R", with the Front-Cover Texts being \*(L"A \s-1GNU\s0 Manual,\*(R"
360
and with the Back-Cover Texts as in (a) below.
362
(a) The \s-1FSF\s0's Back-Cover Text is: \*(L"You are free to copy and modify
363
this \s-1GNU\s0 Manual. Buying copies from \s-1GNU\s0 Press supports the \s-1FSF\s0 in
364
developing \s-1GNU\s0 and promoting software freedom.\*(R"
added
removed
gdb/doc/gdbserver.1
