Debian Codegraph @

upstream/opensuse-tumbleweed/man1/gdb.1

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\"
56 .\" Required to disable full justification in groff 1.23.0.
57 .if n .ds AD l
58 .\" ========================================================================
59 .\"
60 .IX Title "GDB 1"
61 .TH GDB 1 2026-04-21 gdb-16.3 "GNU Development Tools"
62 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
63 .\" way too many mistakes in technical documents.
64 .if n .ad l
65 .nh
66 .SH NAME
67 gdb \- The GNU Debugger
68 .SH SYNOPSIS
69 .IX Header "SYNOPSIS"
70 gdb [OPTIONS] [\fIprog\fR|\fIprog\fR \fIprocID\fR|\fIprog\fR \fIcore\fR]
71 .SH DESCRIPTION
72 .IX Header "DESCRIPTION"
73 The purpose of a debugger such as GDB is to allow you to see what is
74 going on "inside" another program while it executes \-\- or what another
75 program was doing at the moment it crashed.
76 .PP
77 GDB can do four main kinds of things (plus other things in support of
78 these) to help you catch bugs in the act:
79 .IP \(bu 4
80 Start your program, specifying anything that might affect its behavior.
81 .IP \(bu 4
82 Make your program stop on specified conditions.
83 .IP \(bu 4
84 Examine what has happened, when your program has stopped.
85 .IP \(bu 4
86 Change things in your program, so you can experiment with correcting the
87 effects of one bug and go on to learn about another.
88 .PP
89 You can use GDB to debug programs written in C, C++, Fortran and
90 Modula\-2.
91 .PP
92 GDB is invoked with the shell command \f(CW\*(C`gdb\*(C'\fR. Once started, it reads
93 commands from the terminal until you tell it to exit with the GDB
94 command \f(CW\*(C`quit\*(C'\fR or \f(CW\*(C`exit\*(C'\fR. You can get online help from GDB itself
95 by using the command \f(CW\*(C`help\*(C'\fR.
96 .PP
97 You can run \f(CW\*(C`gdb\*(C'\fR with no arguments or options; but the most
98 usual way to start GDB is with one argument or two, specifying an
99 executable program as the argument:
100 .PP
101 .Vb 1
102 \& gdb program
103 .Ve
104 .PP
105 You can also start with both an executable program and a core file specified:
106 .PP
107 .Vb 1
108 \& gdb program core
109 .Ve
110 .PP
111 You can, instead, specify a process ID as a second argument or use option
112 \&\f(CW\*(C`\-p\*(C'\fR, if you want to debug a running process:
113 .PP
114 .Vb 2
115 \& gdb program 1234
116 \& gdb \-p 1234
117 .Ve
118 .PP
119 would attach GDB to process \f(CW1234\fR. With option \fB\-p\fR you
120 can omit the \fIprogram\fR filename.
121 .PP
122 Here are some of the most frequently needed GDB commands:
123 .IP "\fBbreak [\fR\fIfile\fR\fB:][\fR\fIfunction\fR\fB|\fR\fIline\fR\fB]\fR" 4
124 .IX Item "break [file:][function|line]"
125 Set a breakpoint at \fIfunction\fR or \fIline\fR (in \fIfile\fR).
126 .IP "\fBrun [\fR\fIarglist\fR\fB]\fR" 4
127 .IX Item "run [arglist]"
128 Start your program (with \fIarglist\fR, if specified).
129 .IP \fBbt\fR 4
130 .IX Item "bt"
131 Backtrace: display the program stack.
132 .IP "\fBprint\fR \fIexpr\fR" 4
133 .IX Item "print expr"
134 Display the value of an expression.
135 .IP \fBc\fR 4
136 .IX Item "c"
137 Continue running your program (after stopping, e.g. at a breakpoint).
138 .IP \fBnext\fR 4
139 .IX Item "next"
140 Execute next program line (after stopping); step \fIover\fR any
141 function calls in the line.
142 .IP "\fBedit [\fR\fIfile\fR\fB:]\fR\fIfunction\fR" 4
143 .IX Item "edit [file:]function"
144 look at the program line where it is presently stopped.
145 .IP "\fBlist [\fR\fIfile\fR\fB:]\fR\fIfunction\fR" 4
146 .IX Item "list [file:]function"
147 type the text of the program in the vicinity of where it is presently stopped.
148 .IP \fBstep\fR 4
149 .IX Item "step"
150 Execute next program line (after stopping); step \fIinto\fR any
151 function calls in the line.
152 .IP "\fBhelp [\fR\fIname\fR\fB]\fR" 4
153 .IX Item "help [name]"
154 Show information about GDB command \fIname\fR, or general information
155 about using GDB.
156 .IP \fBquit\fR 4
157 .IX Item "quit"
158 .PD 0
159 .IP \fBexit\fR 4
160 .IX Item "exit"
161 .PD
162 Exit from GDB.
163 .PP
164 For full details on GDB,
165 see \fIUsing GDB: A Guide to the GNU Source\-Level Debugger\fR,
166 by Richard M. Stallman and Roland H. Pesch. The same text is available online
167 as the \f(CW\*(C`gdb\*(C'\fR entry in the \f(CW\*(C`info\*(C'\fR program.
168 .SH OPTIONS
169 .IX Header "OPTIONS"
170 Any arguments other than options specify an executable
171 file and core file (or process ID); that is, the first argument
172 encountered with no
173 associated option flag is equivalent to a \fB\-\-se\fR option, and the second,
174 if any, is equivalent to a \fB\-c\fR option if it\*(Aqs the name of a file.
175 Many options have
176 both long and abbreviated forms; both are shown here. The long forms are also
177 recognized if you truncate them, so long as enough of the option is
178 present to be unambiguous.
179 .PP
180 The abbreviated forms are shown here with \fB\-\fR and long forms are shown
181 with \fB\-\-\fR to reflect how they are shown in \fB\-\-help\fR. However,
182 GDB recognizes all of the following conventions for most options:
183 .ie n .IP """\-\-option=\fIvalue\fR""" 4
184 .el .IP \f(CW\-\-option=\fR\f(CIvalue\fR\f(CW\fR 4
185 .IX Item "--option=value"
186 .PD 0
187 .ie n .IP """\-\-option \fIvalue\fR""" 4
188 .el .IP "\f(CW\-\-option \fR\f(CIvalue\fR\f(CW\fR" 4
189 .IX Item "--option value"
190 .ie n .IP """\-option=\fIvalue\fR""" 4
191 .el .IP \f(CW\-option=\fR\f(CIvalue\fR\f(CW\fR 4
192 .IX Item "-option=value"
193 .ie n .IP """\-option \fIvalue\fR""" 4
194 .el .IP "\f(CW\-option \fR\f(CIvalue\fR\f(CW\fR" 4
195 .IX Item "-option value"
196 .ie n .IP """\-\-o=\fIvalue\fR""" 4
197 .el .IP \f(CW\-\-o=\fR\f(CIvalue\fR\f(CW\fR 4
198 .IX Item "--o=value"
199 .ie n .IP """\-\-o \fIvalue\fR""" 4
200 .el .IP "\f(CW\-\-o \fR\f(CIvalue\fR\f(CW\fR" 4
201 .IX Item "--o value"
202 .ie n .IP """\-o=\fIvalue\fR""" 4
203 .el .IP \f(CW\-o=\fR\f(CIvalue\fR\f(CW\fR 4
204 .IX Item "-o=value"
205 .ie n .IP """\-o \fIvalue\fR""" 4
206 .el .IP "\f(CW\-o \fR\f(CIvalue\fR\f(CW\fR" 4
207 .IX Item "-o value"
208 .PD
209 .PP
210 All the options and command line arguments you give are processed
211 in sequential order. The order makes a difference when the \fB\-x\fR
212 option is used.
213 .IP \fB\-\-help\fR 4
214 .IX Item "--help"
215 .PD 0
216 .IP \fB\-h\fR 4
217 .IX Item "-h"
218 .PD
219 List all options, with brief explanations.
220 .IP \fB\-\-symbols=\fR\fIfile\fR 4
221 .IX Item "--symbols=file"
222 .PD 0
223 .IP "\fB\-s\fR \fIfile\fR" 4
224 .IX Item "-s file"
225 .PD
226 Read symbol table from \fIfile\fR.
227 .IP \fB\-\-write\fR 4
228 .IX Item "--write"
229 Enable writing into executable and core files.
230 .IP \fB\-\-exec=\fR\fIfile\fR 4
231 .IX Item "--exec=file"
232 .PD 0
233 .IP "\fB\-e\fR \fIfile\fR" 4
234 .IX Item "-e file"
235 .PD
236 Use \fIfile\fR as the executable file to execute when
237 appropriate, and for examining pure data in conjunction with a core
238 dump.
239 .IP \fB\-\-se=\fR\fIfile\fR 4
240 .IX Item "--se=file"
241 Read symbol table from \fIfile\fR and use it as the executable
242 file.
243 .IP \fB\-\-core=\fR\fIfile\fR 4
244 .IX Item "--core=file"
245 .PD 0
246 .IP "\fB\-c\fR \fIfile\fR" 4
247 .IX Item "-c file"
248 .PD
249 Use \fIfile\fR as a core dump to examine.
250 .IP \fB\-\-command=\fR\fIfile\fR 4
251 .IX Item "--command=file"
252 .PD 0
253 .IP "\fB\-x\fR \fIfile\fR" 4
254 .IX Item "-x file"
255 .PD
256 Execute GDB commands from \fIfile\fR.
257 .IP \fB\-\-eval\-command=\fR\fIcommand\fR 4
258 .IX Item "--eval-command=command"
259 .PD 0
260 .IP "\fB\-ex\fR \fIcommand\fR" 4
261 .IX Item "-ex command"
262 .PD
263 Execute given GDB \fIcommand\fR.
264 .IP \fB\-\-init\-eval\-command=\fR\fIcommand\fR 4
265 .IX Item "--init-eval-command=command"
266 .PD 0
267 .IP \fB\-iex\fR 4
268 .IX Item "-iex"
269 .PD
270 Execute GDB \fIcommand\fR before loading the inferior.
271 .IP \fB\-\-directory=\fR\fIdirectory\fR 4
272 .IX Item "--directory=directory"
273 .PD 0
274 .IP "\fB\-d\fR \fIdirectory\fR" 4
275 .IX Item "-d directory"
276 .PD
277 Add \fIdirectory\fR to the path to search for source files.
278 .IP \fB\-\-nh\fR 4
279 .IX Item "--nh"
280 Do not execute commands from \fI~/.config/gdb/gdbinit\fR,
281 \&\fI~/.gdbinit\fR, \fI~/.config/gdb/gdbearlyinit\fR, or
282 \&\fI~/.gdbearlyinit\fR
283 .IP \fB\-\-nx\fR 4
284 .IX Item "--nx"
285 .PD 0
286 .IP \fB\-n\fR 4
287 .IX Item "-n"
288 .PD
289 Do not execute commands from any \fI.gdbinit\fR or
290 \&\fI.gdbearlyinit\fR initialization files.
291 .IP \fB\-\-quiet\fR 4
292 .IX Item "--quiet"
293 .PD 0
294 .IP \fB\-\-silent\fR 4
295 .IX Item "--silent"
296 .IP \fB\-q\fR 4
297 .IX Item "-q"
298 .PD
299 "Quiet". Do not print the introductory and copyright messages. These
300 messages are also suppressed in batch mode.
301 .IP \fB\-\-batch\fR 4
302 .IX Item "--batch"
303 Run in batch mode. Exit with status \f(CW0\fR after processing all the command
304 files specified with \fB\-x\fR (and \fI.gdbinit\fR, if not inhibited).
305 Exit with nonzero status if an error occurs in executing the GDB
306 commands in the command files.
307 .Sp
308 Batch mode may be useful for running GDB as a filter, for example to
309 download and run a program on another computer; in order to make this
310 more useful, the message
311 .Sp
312 .Vb 1
313 \& Program exited normally.
314 .Ve
315 .Sp
316 (which is ordinarily issued whenever a program running under GDB control
317 terminates) is not issued when running in batch mode.
318 .IP \fB\-\-batch\-silent\fR 4
319 .IX Item "--batch-silent"
320 Run in batch mode, just like \fB\-\-batch\fR, but totally silent. All GDB
321 output is suppressed (stderr is unaffected). This is much quieter than
322 \&\fB\-\-silent\fR and would be useless for an interactive session.
323 .Sp
324 This is particularly useful when using targets that give \fBLoading section\fR
325 messages, for example.
326 .Sp
327 Note that targets that give their output via GDB, as opposed to writing
328 directly to \f(CW\*(C`stdout\*(C'\fR, will also be made silent.
329 .IP "\fB\-\-args\fR \fIprog\fR \fB[\fR\fIarglist\fR\fB]\fR" 4
330 .IX Item "--args prog [arglist]"
331 Change interpretation of command line so that arguments following this
332 option are passed as arguments to the inferior. As an example, take
333 the following command:
334 .Sp
335 .Vb 1
336 \& gdb ./a.out \-q
337 .Ve
338 .Sp
339 It would start GDB with \fB\-q\fR, not printing the introductory message. On
340 the other hand, using:
341 .Sp
342 .Vb 1
343 \& gdb \-\-args ./a.out \-q
344 .Ve
345 .Sp
346 starts GDB with the introductory message, and passes the option to the inferior.
347 .IP \fB\-\-pid=\fR\fIpid\fR 4
348 .IX Item "--pid=pid"
349 Attach GDB to an already running program, with the PID \fIpid\fR.
350 .IP \fB\-\-tui\fR 4
351 .IX Item "--tui"
352 Open the terminal user interface.
353 .IP \fB\-\-readnow\fR 4
354 .IX Item "--readnow"
355 Read all symbols from the given symfile on the first access.
356 .IP \fB\-\-readnever\fR 4
357 .IX Item "--readnever"
358 Do not read symbol files.
359 .IP \fB\-\-return\-child\-result\fR 4
360 .IX Item "--return-child-result"
361 GDB\*(Aqs exit code will be the same as the child\*(Aqs exit code.
362 .IP \fB\-\-configuration\fR 4
363 .IX Item "--configuration"
364 Print details about GDB configuration and then exit.
365 .IP \fB\-\-version\fR 4
366 .IX Item "--version"
367 Print version information and then exit.
368 .IP \fB\-\-cd=\fR\fIdirectory\fR 4
369 .IX Item "--cd=directory"
370 Run GDB using \fIdirectory\fR as its working directory,
371 instead of the current directory.
372 .IP \fB\-\-data\-directory=\fR\fIdirectory\fR 4
373 .IX Item "--data-directory=directory"
374 .PD 0
375 .IP \fB\-D\fR 4
376 .IX Item "-D"
377 .PD
378 Run GDB using \fIdirectory\fR as its data directory. The data
379 directory is where GDB searches for its auxiliary files.
380 .IP \fB\-\-fullname\fR 4
381 .IX Item "--fullname"
382 .PD 0
383 .IP \fB\-f\fR 4
384 .IX Item "-f"
385 .PD
386 Emacs sets this option when it runs GDB as a subprocess. It tells
387 GDB to output the full file name and line number in a standard,
388 recognizable fashion each time a stack frame is displayed (which
389 includes each time the program stops). This recognizable format looks
390 like two \fB\e032\fR characters, followed by the file name, line number
391 and character position separated by colons, and a newline. The
392 Emacs\-to\-GDB interface program uses the two \fB\e032\fR
393 characters as a signal to display the source code for the frame.
394 .IP "\fB\-b\fR \fIbaudrate\fR" 4
395 .IX Item "-b baudrate"
396 Set the line speed (baud rate or bits per second) of any serial
397 interface used by GDB for remote debugging.
398 .IP "\fB\-l\fR \fItimeout\fR" 4
399 .IX Item "-l timeout"
400 Set timeout, in seconds, for remote debugging.
401 .IP \fB\-\-tty=\fR\fIdevice\fR 4
402 .IX Item "--tty=device"
403 Run using \fIdevice\fR for your program\*(Aqs standard input and output.
404 .SH ENVIRONMENT
405 .IX Header "ENVIRONMENT"
406 .SH "SEE ALSO"
407 .IX Header "SEE ALSO"
408 The full documentation for GDB is maintained as a Texinfo manual.
409 If the \f(CW\*(C`info\*(C'\fR and \f(CW\*(C`gdb\*(C'\fR programs and GDB\*(Aqs Texinfo
410 documentation are properly installed at your site, the command
411 .PP
412 .Vb 1
413 \& info gdb
414 .Ve
415 .PP
416 should give you access to the complete manual.
417 .PP
418 \&\fIUsing GDB: A Guide to the GNU Source\-Level Debugger\fR,
419 Richard M. Stallman and Roland H. Pesch, July 1991.
420 .SH COPYRIGHT
421 .IX Header "COPYRIGHT"
422 Copyright (c) 1988\-2024 Free Software Foundation, Inc.
423 .PP
424 Permission is granted to copy, distribute and/or modify this document
425 under the terms of the GNU Free Documentation License, Version 1.3 or
426 any later version published by the Free Software Foundation; with the
427 Invariant Sections being "Free Software" and "Free Software Needs
428 Free Documentation", with the Front\-Cover Texts being "A GNU Manual,"
429 and with the Back\-Cover Texts as in (a) below.
430 .PP
431 (a) The FSF\*(Aqs Back\-Cover Text is: "You are free to copy and modify
432 this GNU Manual. Buying copies from GNU Press supports the FSF in
433 developing GNU and promoting software freedom."