gdb/doc/gdbserver.1

   1 .\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28)
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sp \" Vertical space (when we can't use .PP)
   6 .if t .sp .5v
   7 .if n .sp
   8 ..
   9 .de Vb \" Begin verbatim text
  10 .ft CW
  11 .nf
  12 .ne \\$1
  13 ..
  14 .de Ve \" End verbatim text
  15 .ft R
  16 .fi
  17 ..
  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<>.
  24 .tr \(*W-
  25 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  26 .ie n \{\
  27 .    ds -- \(*W-
  28 .    ds PI pi
  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
  31 .    ds L" ""
  32 .    ds R" ""
  33 .    ds C` ""
  34 .    ds C' ""
  35 'br\}
  36 .el\{\
  37 .    ds -- \|\(em\|
  38 .    ds PI \(*p
  39 .    ds L" ``
  40 .    ds R" ''
  41 .    ds C`
  42 .    ds C'
  43 'br\}
  44 .\"
  45 .\" Escape single quotes in literal strings from groff's Unicode transform.
  46 .ie \n(.g .ds Aq \(aq
  47 .el       .ds Aq '
  48 .\"
  49 .\" If the F register is turned on, we'll generate index entries on stderr for
  50 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
  51 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  52 .\" output yourself in some meaningful fashion.
  53 .\"
  54 .\" Avoid warning from groff about undefined register 'F'.
  55 .de IX
  56 ..
  57 .nr rF 0
  58 .if \n(.g .if rF .nr rF 1
  59 .if (\n(rF:(\n(.g==0)) \{
  60 .    if \nF \{
  61 .        de IX
  62 .        tm Index:\\$1\t\\n%\t"\\$2"
  63 ..
  64 .        if !\nF==2 \{
  65 .            nr % 0
  66 .            nr F 2
  67 .        \}
  68 .    \}
  69 .\}
  70 .rr rF
  71 .\"
  72 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  73 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  74 .    \" fudge factors for nroff and troff
  75 .if n \{\
  76 .    ds #H 0
  77 .    ds #V .8m
  78 .    ds #F .3m
  79 .    ds #[ \f1
  80 .    ds #] \fP
  81 .\}
  82 .if t \{\
  83 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  84 .    ds #V .6m
  85 .    ds #F 0
  86 .    ds #[ \&
  87 .    ds #] \&
  88 .\}
  89 .    \" simple accents for nroff and troff
  90 .if n \{\
  91 .    ds ' \&
  92 .    ds ` \&
  93 .    ds ^ \&
  94 .    ds , \&
  95 .    ds ~ ~
  96 .    ds /
  97 .\}
  98 .if t \{\
  99 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
 100 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
 101 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
 102 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
 103 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 104 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 105 .\}
 106 .    \" troff and (daisy-wheel) nroff accents
 107 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 108 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 109 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 110 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 111 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 112 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 113 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 114 .ds ae a\h'-(\w'a'u*4/10)'e
 115 .ds Ae A\h'-(\w'A'u*4/10)'E
 116 .    \" corrections for vroff
 117 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 118 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 119 .    \" for low resolution devices (crt and lpr)
 120 .if \n(.H>23 .if \n(.V>19 \
 121 \{\
 122 .    ds : e
 123 .    ds 8 ss
 124 .    ds o a
 125 .    ds d- d\h'-1'\(ga
 126 .    ds D- D\h'-1'\(hy
 127 .    ds th \o'bp'
 128 .    ds Th \o'LP'
 129 .    ds ae ae
 130 .    ds Ae AE
 131 .\}
 132 .rm #[ #] #H #V #F C
 133 .\" ========================================================================
 134 .\"
 135 .IX Title "GDBSERVER 1"
 136 .TH GDBSERVER 1 "2015-02-20" "gdb-7.9" "GNU Development Tools"
 137 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 138 .\" way too many mistakes in technical documents.
 139 .if n .ad l
 140 .nh
 141 .SH "NAME"
 142 gdbserver \- Remote Server for the GNU Debugger
 143 .SH "SYNOPSIS"
 144 .IX Header "SYNOPSIS"
 145 gdbserver \fIcomm\fR \fIprog\fR [\fIargs\fR...]
 146 .PP
 147 gdbserver \-\-attach \fIcomm\fR \fIpid\fR
 148 .PP
 149 gdbserver \-\-multi \fIcomm\fR
 150 .SH "DESCRIPTION"
 151 .IX Header "DESCRIPTION"
 152 \&\fBgdbserver\fR is a program that allows you to run \s-1GDB\s0 on a different machine
 153 than the one which is running the program being debugged.
 154 .PP
 155 Usage (server (target) side):
 156 .PP
 157 First, you need to have a copy of the program you want to debug put onto
 158 the target system.  The program can be stripped to save space if needed, as
 159 \&\fBgdbserver\fR doesn't care about symbols.  All symbol handling is taken care of by
 160 the \s-1GDB\s0 running on the host system.
 161 .PP
 162 To use the server, you log on to the target system, and run the \fBgdbserver\fR
 163 program.  You must tell it (a) how to communicate with \s-1GDB, \s0(b) the name of
 164 your program, and (c) its arguments.  The general syntax is:
 165 .PP
 166 .Vb 1
 167 \&        target> gdbserver <comm> <program> [<args> ...]
 168 .Ve
 169 .PP
 170 For example, using a serial port, you might say:
 171 .PP
 172 .Vb 1
 173 \&        target> gdbserver /dev/com1 emacs foo.txt
 174 .Ve
 175 .PP
 176 This tells \fBgdbserver\fR to debug emacs with an argument of foo.txt, and
 177 to communicate with \s-1GDB\s0 via \fI/dev/com1\fR.  \fBgdbserver\fR now
 178 waits patiently for the host \s-1GDB\s0 to communicate with it.
 179 .PP
 180 To use a \s-1TCP\s0 connection, you could say:
 181 .PP
 182 .Vb 1
 183 \&        target> gdbserver host:2345 emacs foo.txt
 184 .Ve
 185 .PP
 186 This says pretty much the same thing as the last example, except that we are
 187 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
 188 that we are expecting to see a \s-1TCP\s0 connection from \f(CW\*(C`host\*(C'\fR to local \s-1TCP\s0 port
 189 2345.  (Currently, the \f(CW\*(C`host\*(C'\fR part is ignored.)  You can choose any number you
 190 want for the port number as long as it does not conflict with any existing \s-1TCP\s0
 191 ports on the target system.  This same port number must be used in the host
 192 GDBs \f(CW\*(C`target remote\*(C'\fR command, which will be described shortly.  Note that if
 193 you chose a port number that conflicts with another service, \fBgdbserver\fR will
 194 print an error message and exit.
 195 .PP
 196 \&\fBgdbserver\fR can also attach to running programs.
 197 This is accomplished via the \fB\-\-attach\fR argument.  The syntax is:
 198 .PP
 199 .Vb 1
 200 \&        target> gdbserver \-\-attach <comm> <pid>
 201 .Ve
 202 .PP
 203 \&\fIpid\fR is the process \s-1ID\s0 of a currently running process.  It isn't
 204 necessary to point \fBgdbserver\fR at a binary for the running process.
 205 .PP
 206 To start \f(CW\*(C`gdbserver\*(C'\fR without supplying an initial command to run
 207 or process \s-1ID\s0 to attach, use the \fB\-\-multi\fR command line option.
 208 In such case you should connect using \f(CW\*(C`target extended\-remote\*(C'\fR to start
 209 the program you want to debug.
 210 .PP
 211 .Vb 1
 212 \&        target> gdbserver \-\-multi <comm>
 213 .Ve
 214 .PP
 215 Usage (host side):
 216 .PP
 217 You need an unstripped copy of the target program on your host system, since
 218 \&\s-1GDB\s0 needs to examine it's symbol tables and such.  Start up \s-1GDB\s0 as you normally
 219 would, with the target program as the first argument.  (You may need to use the
 220 \&\fB\-\-baud\fR option if the serial line is running at anything except 9600 baud.)
 221 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
 222 new command you need to know about is \f(CW\*(C`target remote\*(C'\fR
 223 (or \f(CW\*(C`target extended\-remote\*(C'\fR).  Its argument is either
 224 a device name (usually a serial device, like \fI/dev/ttyb\fR), or a \f(CW\*(C`HOST:PORT\*(C'\fR
 225 descriptor.  For example:
 226 .PP
 227 .Vb 1
 228 \&        (gdb) target remote /dev/ttyb
 229 .Ve
 230 .PP
 231 communicates with the server via serial line \fI/dev/ttyb\fR, and:
 232 .PP
 233 .Vb 1
 234 \&        (gdb) target remote the\-target:2345
 235 .Ve
 236 .PP
 237 communicates via a \s-1TCP\s0 connection to port 2345 on host `the\-target', where
 238 you previously started up \fBgdbserver\fR with the same port number.  Note that for
 239 \&\s-1TCP\s0 connections, you must start up \fBgdbserver\fR prior to using the `target remote'
 240 command, otherwise you may get an error that looks something like
 241 `Connection refused'.
 242 .PP
 243 \&\fBgdbserver\fR can also debug multiple inferiors at once,
 244 described in
 245 the \s-1GDB\s0 manual in node \f(CW\*(C`Inferiors and Programs\*(C'\fR
 246 \&\*(-- shell command \f(CW\*(C`info \-f gdb \-n \*(AqInferiors and Programs\*(Aq\*(C'\fR.
 247 In such case use the \f(CW\*(C`extended\-remote\*(C'\fR \s-1GDB\s0 command variant:
 248 .PP
 249 .Vb 1
 250 \&        (gdb) target extended\-remote the\-target:2345
 251 .Ve
 252 .PP
 253 The \fBgdbserver\fR option \fB\-\-multi\fR may or may not be used in such
 254 case.
 255 .SH "OPTIONS"
 256 .IX Header "OPTIONS"
 257 There are three different modes for invoking \fBgdbserver\fR:
 258 .IP "\(bu" 4
 259 Debug a specific program specified by its program name:
 260 .Sp
 261 .Vb 1
 262 \&        gdbserver <comm> <prog> [<args>...]
 263 .Ve
 264 .Sp
 265 The \fIcomm\fR parameter specifies how should the server communicate
 266 with \s-1GDB\s0; it is either a device name (to use a serial line),
 267 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
 268 stdin/stdout of \f(CW\*(C`gdbserver\*(C'\fR.  Specify the name of the program to
 269 debug in \fIprog\fR.  Any remaining arguments will be passed to the
 270 program verbatim.  When the program exits, \s-1GDB\s0 will close the
 271 connection, and \f(CW\*(C`gdbserver\*(C'\fR will exit.
 272 .IP "\(bu" 4
 273 Debug a specific program by specifying the process \s-1ID\s0 of a running
 274 program:
 275 .Sp
 276 .Vb 1
 277 \&        gdbserver \-\-attach <comm> <pid>
 278 .Ve
 279 .Sp
 280 The \fIcomm\fR parameter is as described above.  Supply the process \s-1ID\s0
 281 of a running program in \fIpid\fR; \s-1GDB\s0 will do everything
 282 else.  Like with the previous mode, when the process \fIpid\fR exits,
 283 \&\s-1GDB\s0 will close the connection, and \f(CW\*(C`gdbserver\*(C'\fR will exit.
 284 .IP "\(bu" 4
 285 Multi-process mode \*(-- debug more than one program/process:
 286 .Sp
 287 .Vb 1
 288 \&        gdbserver \-\-multi <comm>
 289 .Ve
 290 .Sp
 291 In this mode, \s-1GDB\s0 can instruct \fBgdbserver\fR which
 292 command(s) to run.  Unlike the other 2 modes, \s-1GDB\s0 will not
 293 close the connection when a process being debugged exits, so you can
 294 debug several processes in the same session.
 295 .PP
 296 In each of the modes you may specify these options:
 297 .IP "\fB\-\-help\fR" 4
 298 .IX Item "--help"
 299 List all options, with brief explanations.
 300 .IP "\fB\-\-version\fR" 4
 301 .IX Item "--version"
 302 This option causes \fBgdbserver\fR to print its version number and exit.
 303 .IP "\fB\-\-attach\fR" 4
 304 .IX Item "--attach"
 305 \&\fBgdbserver\fR will attach to a running program.  The syntax is:
 306 .Sp
 307 .Vb 1
 308 \&        target> gdbserver \-\-attach <comm> <pid>
 309 .Ve
 310 .Sp
 311 \&\fIpid\fR is the process \s-1ID\s0 of a currently running process.  It isn't
 312 necessary to point \fBgdbserver\fR at a binary for the running process.
 313 .IP "\fB\-\-multi\fR" 4
 314 .IX Item "--multi"
 315 To start \f(CW\*(C`gdbserver\*(C'\fR without supplying an initial command to run
 316 or process \s-1ID\s0 to attach, use this command line option.
 317 Then you can connect using \f(CW\*(C`target extended\-remote\*(C'\fR and start
 318 the program you want to debug.  The syntax is:
 319 .Sp
 320 .Vb 1
 321 \&        target> gdbserver \-\-multi <comm>
 322 .Ve
 323 .IP "\fB\-\-debug\fR" 4
 324 .IX Item "--debug"
 325 Instruct \f(CW\*(C`gdbserver\*(C'\fR to display extra status information about the debugging
 326 process.
 327 This option is intended for \f(CW\*(C`gdbserver\*(C'\fR development and for bug reports to
 328 the developers.
 329 .IP "\fB\-\-remote\-debug\fR" 4
 330 .IX Item "--remote-debug"
 331 Instruct \f(CW\*(C`gdbserver\*(C'\fR to display remote protocol debug output.
 332 This option is intended for \f(CW\*(C`gdbserver\*(C'\fR development and for bug reports to
 333 the developers.
 334 .IP "\fB\-\-debug\-format=option1\fR[\fB,option2,...\fR]" 4
 335 .IX Item "--debug-format=option1[,option2,...]"
 336 Instruct \f(CW\*(C`gdbserver\*(C'\fR to include extra information in each line
 337 of debugging output.
 338 .IP "\fB\-\-wrapper\fR" 4
 339 .IX Item "--wrapper"
 340 Specify a wrapper to launch programs
 341 for debugging.  The option should be followed by the name of the
 342 wrapper, then any command-line arguments to pass to the wrapper, then
 343 \&\f(CW\*(C`\-\-\*(C'\fR indicating the end of the wrapper arguments.
 344 .IP "\fB\-\-once\fR" 4
 345 .IX Item "--once"
 346 By default, \fBgdbserver\fR keeps the listening \s-1TCP\s0 port open, so that
 347 additional connections are possible.  However, if you start \f(CW\*(C`gdbserver\*(C'\fR
 348 with the \fB\-\-once\fR option, it will stop listening for any further
 349 connection attempts after connecting to the first \s-1GDB\s0 session.
 350 .SH "SEE ALSO"
 351 .IX Header "SEE ALSO"
 352 The full documentation for \s-1GDB\s0 is maintained as a Texinfo manual.
 353 If the \f(CW\*(C`info\*(C'\fR and \f(CW\*(C`gdb\*(C'\fR programs and \s-1GDB\s0's Texinfo
 354 documentation are properly installed at your site, the command
 355 .PP
 356 .Vb 1
 357 \&        info gdb
 358 .Ve
 359 .PP
 360 should give you access to the complete manual.
 361 .PP
 362 \&\fIUsing \s-1GDB: A\s0 Guide to the \s-1GNU\s0 Source-Level Debugger\fR,
 363 Richard M. Stallman and Roland H. Pesch, July 1991.
 364 .SH "COPYRIGHT"
 365 .IX Header "COPYRIGHT"
 366 Copyright (c) 1988\-2015 Free Software Foundation, Inc.
 367 .PP
 368 Permission is granted to copy, distribute and/or modify this document
 369 under the terms of the \s-1GNU\s0 Free Documentation License, Version 1.3 or
 370 any later version published by the Free Software Foundation; with the
 371 Invariant Sections being \*(L"Free Software\*(R" and \*(L"Free Software Needs
 372 Free Documentation\*(R", with the Front-Cover Texts being \*(L"A \s-1GNU\s0 Manual,\*(R"
 373 and with the Back-Cover Texts as in (a) below.
 374 .PP
 375 (a) The \s-1FSF\s0's Back-Cover Text is: \*(L"You are free to copy and modify
 376 this \s-1GNU\s0 Manual.  Buying copies from \s-1GNU\s0 Press supports the \s-1FSF\s0 in
 377 developing \s-1GNU\s0 and promoting software freedom.\*(R"