1GDBSERVER(1)                 GNU Development Tools                GDBSERVER(1)
2
3
4

NAME

6       gdbserver - Remote Server for the GNU Debugger
7

SYNOPSIS

9       gdbserver comm prog [args...]
10
11       gdbserver --attach comm pid
12
13       gdbserver --multi comm
14

DESCRIPTION

16       gdbserver is a program that allows you to run GDB on a different
17       machine than the one which is running the program being debugged.
18
19       Usage (server (target) side):
20
21       First, you need to have a copy of the program you want to debug put
22       onto the target system.  The program can be stripped to save space if
23       needed, as gdbserver doesn't care about symbols.  All symbol handling
24       is taken care of by the GDB running on the host system.
25
26       To use the server, you log on to the target system, and run the
27       gdbserver program.  You must tell it (a) how to communicate with GDB,
28       (b) the name of your program, and (c) its arguments.  The general
29       syntax is:
30
31               target> gdbserver <comm> <program> [<args> ...]
32
33       For example, using a serial port, you might say:
34
35               target> gdbserver /dev/com1 emacs foo.txt
36
37       This tells gdbserver to debug emacs with an argument of foo.txt, and to
38       communicate with GDB via /dev/com1.  gdbserver now waits patiently for
39       the host GDB to communicate with it.
40
41       To use a TCP connection, you could say:
42
43               target> gdbserver host:2345 emacs foo.txt
44
45       This says pretty much the same thing as the last example, except that
46       we are going to communicate with the "host" GDB via TCP.  The
47       "host:2345" argument means that we are expecting to see a TCP
48       connection from "host" to local TCP port 2345.  (Currently, the "host"
49       part is ignored.)  You can choose any number you want for the port
50       number as long as it does not conflict with any existing TCP ports on
51       the target system.  This same port number must be used in the host GDBs
52       "target remote" command, which will be described shortly.  Note that if
53       you chose a port number that conflicts with another service, gdbserver
54       will print an error message and exit.
55
56       gdbserver can also attach to running programs.  This is accomplished
57       via the --attach argument.  The syntax is:
58
59               target> gdbserver --attach <comm> <pid>
60
61       pid is the process ID of a currently running process.  It isn't
62       necessary to point gdbserver at a binary for the running process.
63
64       To start "gdbserver" without supplying an initial command to run or
65       process ID to attach, use the --multi command line option.  In such
66       case you should connect using "target extended-remote" to start the
67       program you want to debug.
68
69               target> gdbserver --multi <comm>
70
71       Usage (host side):
72
73       You need an unstripped copy of the target program on your host system,
74       since GDB needs to examine it's symbol tables and such.  Start up GDB
75       as you normally would, with the target program as the first argument.
76       (You may need to use the --baud option if the serial line is running at
77       anything except 9600 baud.)  That is "gdb TARGET-PROG", or "gdb --baud
78       BAUD TARGET-PROG".  After that, the only new command you need to know
79       about is "target remote" (or "target extended-remote").  Its argument
80       is either a device name (usually a serial device, like /dev/ttyb), or a
81       "HOST:PORT" descriptor.  For example:
82
83               (gdb) target remote /dev/ttyb
84
85       communicates with the server via serial line /dev/ttyb, and:
86
87               (gdb) target remote the-target:2345
88
89       communicates via a TCP connection to port 2345 on host `the-target',
90       where you previously started up gdbserver with the same port number.
91       Note that for TCP connections, you must start up gdbserver prior to
92       using the `target remote' command, otherwise you may get an error that
93       looks something like `Connection refused'.
94
95       gdbserver can also debug multiple inferiors at once, described in the
96       GDB manual in node "Inferiors and Programs" -- shell command "info -f
97       gdb -n 'Inferiors and Programs'".  In such case use the
98       "extended-remote" GDB command variant:
99
100               (gdb) target extended-remote the-target:2345
101
102       The gdbserver option --multi may or may not be used in such case.
103

OPTIONS

105       There are three different modes for invoking gdbserver:
106
107       ·   Debug a specific program specified by its program name:
108
109                   gdbserver <comm> <prog> [<args>...]
110
111           The comm parameter specifies how should the server communicate with
112           GDB; it is either a device name (to use a serial line), a TCP port
113           number (":1234"), or "-" or "stdio" to use stdin/stdout of
114           "gdbserver".  Specify the name of the program to debug in prog.
115           Any remaining arguments will be passed to the program verbatim.
116           When the program exits, GDB will close the connection, and
117           "gdbserver" will exit.
118
119       ·   Debug a specific program by specifying the process ID of a running
120           program:
121
122                   gdbserver --attach <comm> <pid>
123
124           The comm parameter is as described above.  Supply the process ID of
125           a running program in pid; GDB will do everything else.  Like with
126           the previous mode, when the process pid exits, GDB will close the
127           connection, and "gdbserver" will exit.
128
129       ·   Multi-process mode -- debug more than one program/process:
130
131                   gdbserver --multi <comm>
132
133           In this mode, GDB can instruct gdbserver which command(s) to run.
134           Unlike the other 2 modes, GDB will not close the connection when a
135           process being debugged exits, so you can debug several processes in
136           the same session.
137
138       In each of the modes you may specify these options:
139
140       --help
141           List all options, with brief explanations.
142
143       --version
144           This option causes gdbserver to print its version number and exit.
145
146       --attach
147           gdbserver will attach to a running program.  The syntax is:
148
149                   target> gdbserver --attach <comm> <pid>
150
151           pid is the process ID of a currently running process.  It isn't
152           necessary to point gdbserver at a binary for the running process.
153
154       --multi
155           To start "gdbserver" without supplying an initial command to run or
156           process ID to attach, use this command line option.  Then you can
157           connect using "target extended-remote" and start the program you
158           want to debug.  The syntax is:
159
160                   target> gdbserver --multi <comm>
161
162       --debug
163           Instruct "gdbserver" to display extra status information about the
164           debugging process.  This option is intended for "gdbserver"
165           development and for bug reports to the developers.
166
167       --remote-debug
168           Instruct "gdbserver" to display remote protocol debug output.  This
169           option is intended for "gdbserver" development and for bug reports
170           to the developers.
171
172       --debug-format=option1[,option2,...]
173           Instruct "gdbserver" to include extra information in each line of
174           debugging output.
175
176       --wrapper
177           Specify a wrapper to launch programs for debugging.  The option
178           should be followed by the name of the wrapper, then any command-
179           line arguments to pass to the wrapper, then "--" indicating the end
180           of the wrapper arguments.
181
182       --once
183           By default, gdbserver keeps the listening TCP port open, so that
184           additional connections are possible.  However, if you start
185           "gdbserver" with the --once option, it will stop listening for any
186           further connection attempts after connecting to the first GDB
187           session.
188

SEE ALSO

190       The full documentation for GDB is maintained as a Texinfo manual.  If
191       the "info" and "gdb" programs and GDB's Texinfo documentation are
192       properly installed at your site, the command
193
194               info gdb
195
196       should give you access to the complete manual.
197
198       Using GDB: A Guide to the GNU Source-Level Debugger, Richard M.
199       Stallman and Roland H. Pesch, July 1991.
200
202       Copyright (c) 1988-2015 Free Software Foundation, Inc.
203
204       Permission is granted to copy, distribute and/or modify this document
205       under the terms of the GNU Free Documentation License, Version 1.3 or
206       any later version published by the Free Software Foundation; with the
207       Invariant Sections being "Free Software" and "Free Software Needs Free
208       Documentation", with the Front-Cover Texts being "A GNU Manual," and
209       with the Back-Cover Texts as in (a) below.
210
211       (a) The FSF's Back-Cover Text is: "You are free to copy and modify this
212       GNU Manual.  Buying copies from GNU Press supports the FSF in
213       developing GNU and promoting software freedom."
214
215
216
217gdb-7.10.50.20160125-cvs          2019-07-25                      GDBSERVER(1)
Impressum