43BSDReno/contrib/emacs-18.55/info/gdb-1 - annotate

Return to gdb-1 CVS log

Up to [CSRG BSD Unix] / 43BSDReno / contrib / emacs-18.55 / info

Annotation of 43BSDReno/contrib/emacs-18.55/info/gdb-1, revision 1.1.1.1

1.1 root 1: Info file gdb, produced by texinfo-format-buffer -*-Text-*-
2: from file gdb.texinfo
3:
4: This file documents the GNU debugger GDB.
5:
6: Copyright (C) 1988 Free Software Foundation, Inc.
7:
8: Permission is granted to make and distribute verbatim copies of
9: this manual provided the copyright notice and this permission notice
10: are preserved on all copies.
11:
12: Permission is granted to copy and distribute modified versions of this
13: manual under the conditions for verbatim copying, provided also that the
14: sections entitled "Distribution" and "GDB General Public License" are
15: included exactly as in the original, and provided that the entire resulting
16: derived work is distributed under the terms of a permission notice
17: identical to this one.
18:
19: Permission is granted to copy and distribute translations of this manual
20: into another language, under the above conditions for modified versions,
21: except that the sections entitled "Distribution" and "GDB General Public
22: License" may be included in a translation approved by the author instead
23: of in the original English.
24:
25:
26:
27: File: gdb Node: Top, Up: (DIR), Next: Commands
28:
29: Summary of GDB
30: **************
31:
32: The purpose of a debugger such as GDB is to allow you to execute another
33: program while examining what is going on inside it. We call the other
34: program "your program" or "the program being debugged".
35:
36: GDB can do four kinds of things (plus other things in support of these):
37:
38: 1. Start the program, specifying anything that might affect its behavior.
39:
40: 2. Make the program stop on specified conditions.
41:
42: 3. Examine what has happened, when the program has stopped, so that you
43: can see bugs happen.
44:
45: 4. Change things in the program, so you can correct the effects of one bug
46: and go on to learn about another without having to recompile first.
47:
48: * Menu:
49:
50: * License:: The GDB General Public License gives you permission
51: to redistribute GDB on certain terms; and also
52: explains that there is no warranty.
53: * Input:: GDB command syntax and input conventions.
54: * Files:: Specifying files for GDB to operate on.
55: * Options:: GDB arguments and options.
56: * Compilation::Compiling your program so you can debug it.
57: * Running:: Running your program under GDB.
58: * Stopping:: Making your program stop. Why it may stop. What to do then.
59: * Stack:: Examining your program's stack.
60: * Source:: Examining your program's source files.
61: * Data:: Examining data in your program.
62: * Symbols:: Examining the debugger's symbol table.
63: * Altering:: Altering things in your program.
64: * Sequences:: Canned command sequences for repeated use.
65: * Emacs:: Using GDB through GNU Emacs.
66: * Remote:: Remote kernel debugging across a serial line.
67: * Commands:: Index of GDB commands.
68: * Concepts:: Index of GDB concepts.
69:
70:
71: File: gdb Node: License, Prev: Top, Up: Top, Next: Input
72:
73: GDB General Public License
74: **************************
75: (Clarified 11 Feb 1988)
76:
77: The license agreements of most software companies keep you at the mercy
78: of those companies. By contrast, our general public license is intended to
79: give everyone the right to share GDB. To make sure that you get the rights
80: we want you to have, we need to make restrictions that forbid anyone to
81: deny you these rights or to ask you to surrender the rights. Hence this
82: license agreement.
83:
84: Specifically, we want to make sure that you have the right to give away
85: copies of GDB, that you receive source code or else can get it if you want
86: it, that you can change GDB or use pieces of it in new free programs, and
87: that you know you can do these things.
88:
89: To make sure that everyone has such rights, we have to forbid you to
90: deprive anyone else of these rights. For example, if you distribute copies
91: of GDB, you must give the recipients all the rights that you have. You
92: must make sure that they, too, receive or can get the source code. And you
93: must tell them their rights.
94:
95: Also, for our own protection, we must make certain that everyone finds
96: out that there is no warranty for GDB. If GDB is modified by someone else
97: and passed on, we want its recipients to know that what they have is not
98: what we distributed, so that any problems introduced by others will not
99: reflect on our reputation.
100:
101: Therefore we (Richard Stallman and the Free Software Foundation,
102: Inc.) make the following terms which say what you must do to be
103: allowed to distribute or change GDB.
104:
105:
106: Copying Policies
107: ================
108:
109: 1. You may copy and distribute verbatim copies of GDB source code as you
110: receive it, in any medium, provided that you conspicuously and
111: appropriately publish on each file a valid copyright notice "Copyright
112: (C) 1988 Free Software Foundation, Inc." (or with whatever year
113: is appropriate); keep intact the notices on all files that
114: refer to this License Agreement and to the absence of any warranty; and
115: give any other recipients of the GDB program a copy of this License
116: Agreement along with the program. You may charge a distribution fee
117: for the physical act of transferring a copy.
118:
119: 2. You may modify your copy or copies of GDB source code or any portion
120: of it, and copy and distribute such modifications under the terms of
121: Paragraph 1 above, provided that you also do the following:
122:
123: * cause the modified files to carry prominent notices stating
124: that you changed the files and the date of any change; and
125:
126: * cause the whole of any work that you distribute or publish, that
127: in whole or in part contains or is a derivative of GDB or any
128: part thereof, to be licensed at no charge to all third parties on
129: terms identical to those contained in this License Agreement
130: (except that you may choose to grant more extensive warranty
131: protection to some or all third parties, at your option).
132:
133: * if the modified program serves as a debugger, cause it, when
134: started running in the simplest and usual way, to print an
135: announcement including a valid copyright notice "Copyright
136: (C) 1988 Free Software Foundation, Inc." (or with the
137: year that is appropriate), saying that there is no warranty (or
138: else, saying that you provide a warranty) and that users may
139: redistribute the program under these conditions, and telling the
140: user how to view a copy of this License Agreement.
141:
142: * You may charge a distribution fee for the physical act of
143: transferring a copy, and you may at your option offer warranty
144: protection in exchange for a fee.
145:
146: Mere aggregation of another unrelated program with this program (or its
147: derivative) on a volume of a storage or distribution medium does not bring
148: the other program under the scope of these terms.
149:
150: 3. You may copy and distribute GDB (or a portion or derivative of it,
151: under Paragraph 2) in object code or executable form under the terms
152: of Paragraphs 1 and 2 above provided that you also do one of the
153: following:
154:
155: * accompany it with the complete corresponding machine-readable
156: source code, which must be distributed under the terms of
157: Paragraphs 1 and 2 above; or,
158:
159: * accompany it with a written offer, valid for at least three
160: years, to give any third party free (except for a nominal
161: shipping charge) a complete machine-readable copy of the
162: corresponding source code, to be distributed under the terms of
163: Paragraphs 1 and 2 above; or,
164:
165: * accompany it with the information you received as to where the
166: corresponding source code may be obtained. (This alternative is
167: allowed only for noncommercial distribution and only if you
168: received the program in object code or executable form alone.)
169:
170: For an executable file, complete source code means all the source code
171: for all modules it contains; but, as a special exception, it need not
172: include source code for modules which are standard libraries that
173: accompany the operating system on which the executable file runs.
174:
175: 4. You may not copy, sublicense, distribute or transfer GDB except as
176: expressly provided under this License Agreement. Any attempt
177: otherwise to copy, sublicense, distribute or transfer GDB is void and
178: your rights to use GDB under this License agreement shall be
179: automatically terminated. However, parties who have received computer
180: software programs from you with this License Agreement will not have
181: their licenses terminated so long as such parties remain in full
182: compliance.
183:
184: 5. If you wish to incorporate parts of GDB into other free programs whose
185: distribution conditions are different, write to the Free Software
186: Foundation. We have not yet worked out a simple rule that can be
187: stated here, but we will often permit this. We will be guided by the
188: two goals of preserving the free status of all derivatives our free
189: software and of promoting the sharing and reuse of software.
190:
191:
192: NO WARRANTY
193: ===========
194:
195: BECAUSE GDB IS LICENSED FREE OF CHARGE, WE PROVIDE ABSOLUTELY
196: NO WARRANTY, TO THE EXTENT PERMITTED BY APPLICABLE STATE LAW. EXCEPT
197: WHEN OTHERWISE STATED IN WRITING, THE FREE SOFTWARE FOUNDATION, INC,
198: RICHARD M. STALLMAN AND/OR OTHER PARTIES PROVIDE GDB "AS IS"
199: WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING,
200: BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
201: FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY
202: AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE GDB
203: PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY
204: SERVICING, REPAIR OR CORRECTION.
205:
206: IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW WILL FREE SOFTWARE
207: FOUNDATION, INC., RICHARD M. STALLMAN, AND/OR ANY OTHER PARTY WHO MAY
208: MODIFY AND REDISTRIBUTE GDB AS PERMITTED ABOVE, BE LIABLE TO YOU
209: FOR DAMAGES, INCLUDING ANY LOST PROFITS, LOST MONIES, OR OTHER
210: SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR
211: INABILITY TO USE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA
212: BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY THIRD PARTIES OR A
213: FAILURE OF THE PROGRAM TO OPERATE WITH PROGRAMS NOT DISTRIBUTED BY
214: FREE SOFTWARE FOUNDATION, INC.) THE PROGRAM, EVEN IF YOU HAVE BEEN
215: ADVISED OF THE POSSIBILITY OF SUCH DAMAGES, OR FOR ANY CLAIM BY ANY
216: OTHER PARTY.
217:
218:
219: File: gdb Node: Input, Prev: License, Up: Top, Next: Files
220:
221: GDB Input Conventions
222: *********************
223:
224: GDB is invoked with the shell command `gdb'. Once started, it reads
225: commands from the terminal until you tell it to exit.
226:
227: A GDB command is a single line of input. There is no limit on how long
228: it can be. It starts with a command name, which is followed by arguments
229: whose meaning depends on the command name. Some command names do not
230: allow arguments.
231:
232: GDB command names may always be abbreviated if the abbreviation is
233: unambiguous. Sometimes even ambiguous abbreviations are allowed; for
234: example, `s' is specially defined as equivalent to `step'
235: even though there are other commands whose names start with `s'.
236: Possible command abbreviations are often stated in the documentation
237: of the individual commands.
238:
239: A blank line as input to GDB means to repeat the previous command verbatim.
240: Certain commands do not allow themselves to be repeated this way; these are
241: commands for which unintentional repetition might cause trouble and which
242: you are unlikely to want to repeat. Certain others (`list' and
243: `x') act differently when repeated because that is more useful.
244:
245: A line of input starting with `#' is a comment; it does nothing.
246: This is useful mainly in command files (*Note Command Files::).
247:
248: GDB "prompts" for commands with a string that is normally `(gdb)'.
249: When debugging GDB with GDB, it is useful to change the prompt in one of
250: the GDBs so that you can distinguish them. This can be done with the
251: `set-prompt' command.
252:
253: `set-prompt NEWPROMPT'
254: Directs GDB to use NEWPROMPT as its prompt string henceforth.
255:
256: To exit GDB, use the `quit' command (abbreviated `q').
257: `Ctrl-c' will not exit from GDB, but rather will terminate the action
258: of any GDB command that is in progress and return to GDB command level.
259: It is safe to type `Ctrl-c' at any time because GDB does not allow
260: it to take effect until a time when it is safe.
261:
262:
263: File: gdb Node: Files, Prev: Input, Up: Top, Next: Options
264:
265: Specifying GDB's Files
266: **********************
267:
268: GDB needs to know the filename of the program to be debugged. To debug a
269: core dump of a previous run, GDB must be told the filename of the core
270: dump.
271:
272: * Menu:
273:
274: * Arguments: File Arguments. Specifying files with arguments
275: (when you start GDB).
276: * Commands: File Commands. Specifying files with GDB commands.
277:
278:
279: File: gdb Node: File Arguments, Prev: Files, Up: Files, Next: File Commands
280:
281: Specifying Files with Arguments
282: ===============================
283:
284: The usual way to specify the executable and core dump file names is with
285: two command arguments given when you start GDB. The first argument is used
286: as the file for execution and symbols, and the second argument (if any) is
287: used as the core dump file name. Thus,
288:
289: gdb progm core
290:
291: specifies `progm' as the executable program and `core' as a core
292: dump file to examine. (You do not need to have a core dump file if what
293: you plan to do is debug the program interactively.)
294:
295: *Note Options::, for full information on command options and arguments for
296: GDB.
297:
298:
299: File: gdb Node: File Commands, Prev: File Arguments, Up: Files
300:
301: Specifying Files with Commands
302: ==============================
303:
304: Usually you specify the files for GDB to work with by giving arguments when
305: you invoke GDB. But occasionally it is necessary to change to a different
306: file during a GDB session. Or you may run GDB and forget to specify the
307: files you want to use. In these situations the GDB commands to specify new
308: files are useful.
309:
310: `exec-file FILENAME'
311: Specify that the program to be run is found in FILENAME. If you
312: do not specify a directory and the file is not found in GDB's working
313: directory, GDB will use the environment variable `PATH' as a list
314: of directories to search, just as the shell does when looking for a
315: program to run.
316:
317: `symbol-file FILENAME'
318: Read symbol table information from file FILENAME. `PATH'
319: is searched when necessary. Most of the time you will use both the
320: `exec-file' and `symbol-file' commands on the same file.
321:
322: `symbol-file' with no argument clears out GDB's symbol table.
323:
324: `core-file FILENAME'
325: Specify the whereabouts of a core dump file to be used as the
326: "contents of memory". Note that the core dump contains only the
327: writable parts of memory; the read-only parts must come from the
328: executable file.
329:
330: `core-file' with no argument specifies that no core file is
331: to be used.
332:
333: `kill'
334: Cancel running the program under GDB. This could be used if you wish
335: to debug a core dump instead. GDB ignores any core dump file if it is
336: actually running the program, so the `kill' command is the only
337: sure way to go back to using the core dump file.
338:
339: `info files'
340: Print the names of the executable and core dump files currently in
341: use by GDB, and the file from which symbols were loaded.
342:
343: While all three file-specifying commands allow both absolute and relative
344: file names as arguments, GDB always converts the file name to an absolute
345: one and remembers it that way.
346:
347: The `symbol-file' command causes GDB to forget the contents of its
348: convenience variables, the value history, and all breakpoints and
349: auto-display expressions. This is because they may contain pointers to the
350: internal data recording symbols and data types, which are part of the old
351: symbol table data being discarded inside GDB.
352:
353:
354: File: gdb Node: Options, Prev: Files, Up: Top, Next: Compilation
355:
356: Options and Arguments for GDB
357: *****************************
358:
359: When you invoke GDB, you can pass commands telling it what files to
360: operate on and what other things to do.
361:
362: * Menu:
363:
364: * Mode Options:: Options controlling modes of operation.
365: * File Options:: Options to specify files (executable, coredump, commands)
366: * Other Arguments:: Any other arguments without options
367: also specify files.
368:
369:
370: File: gdb Node: Mode Options, Prev: Options, Up: Options, Next: File Options
371:
372: Mode Options
373: ============
374:
375: `-nx'
376: Do not execute commands from the init files `.gdbinit'.
377: Normally, the commands in these files are executed after all the
378: command options and arguments have been processed. *Note Command Files::.
379:
380: `-q'
381: "Quiet". Do not print the usual introductory messages.
382:
383: `-batch'
384: Run in batch mode. Exit with code 1 after processing all the command
385: files specified with `-x' (and `.gdbinit', if not
386: inhibited). Exit also if, due to an error, GDB would otherwise
387: attempt to read a command from the terminal.
388:
389: `-fullname'
390: This option is used when Emacs runs GDB as a subprocess. It tells GDB
391: to output the full file name and line number in a standard,
392: recognizable fashion each time a stack frame is displayed (which
393: includes each time the program stops). This recognizable format looks
394: like two `\032' characters, followed by the filename, line number
395: and character position separated by colons, and a newline. The
396: Emacs-to-GDB interface program uses the two `\032' characters as
397: a signal to display the source code for the frame.
398:
399:
400: File: gdb Node: File Options, Prev: Mode Options, Up: Options, Next: Other Arguments
401:
402: File-specifying Options
403: =======================
404:
405: All the options and command line arguments given are processed
406: in sequential order. The order makes a difference when the
407: `-x' command is used.
408:
409: `-s FILE'
410: Read symbol table from file FILE.
411:
412: `-e FILE'
413: Use file FILE as the executable file to execute when
414: appropriate, and for examining pure data in conjunction with a core
415: dump.
416:
417: `-se FILE'
418: Read symbol table from file FILE and use it as the executable
419: file.
420:
421: `-c FILE'
422: Use file FILE as a core dump to examine.
423:
424: `-x FILE'
425: Execute GDB commands from file FILE.
426:
427: `-d DIRECTORY'
428: Add DIRECTORY to the path to search for source files.
429:
430:
431: File: gdb Node: Other Arguments, Prev: File Options, Up: Options
432:
433: Other Arguments
434: ===============
435:
436: If there are arguments to GDB that are not options or associated with
437: options, the first one specifies the symbol table and executable file name
438: (as if it were preceded by `-se') and the second one specifies a core
439: dump file name (as if it were preceded by `-c').
440:
441:
442: File: gdb Node: Compilation, Prev: Options, Up: Top, Next: Running
443:
444: Compiling Your Program for Debugging
445: ************************************
446:
447: In order to debug a program effectively, you need to ask for debugging
448: information when you compile it. This information in the object file
449: describes the data type of each variable or function and the correspondence
450: between source line numbers and addresses in the executable code.
451:
452: To request debugging information, specify the `-g' option when you run
453: the compiler.
454:
455: The Unix C compiler is unable to handle the `-g' and `-O' options
456: together. This means that you cannot ask for optimization if you ask for
457: debugger information.
458:
459: The GNU C compiler supports `-g' with or without `-O', making it
460: possible to debug optimized code. We recommend that you *always* use
461: `-g' whenever you compile a program. You may think the program is
462: correct, but there's no sense in pushing your luck.
463:
464: If you are using the GNU C compiler, the GNU assembler and the GNU linker,
465: you can choose between two formats of debugging information: the standard
466: Unix format, which is what you get with `-g', and GDB's own format,
467: which you request by using `-gg' instead of `-g'. This stores
468: debugging information in the executable file in a format much like that
469: which is used inside GDB. This has these advantages and disadvantages:
470:
471: * GDB can read `-gg' format more than twice as fast as Unix
472: `-g' format.
473:
474: * The `-gg' format uses much more disk space than Unix format.
475:
476: * The Unix debuggers can understand only Unix format, so you cannot use
477: Unix source-level debuggers if you compile with `-gg'. (The
478: `adb' debugger works with either format; it does not use this
479: information in any case.)
480:
481:
482: File: gdb Node: Running, Prev: Compilation, Up: Top, Next: Stopping
483:
484: Running Your Program Under GDB
485: ******************************
486:
487: To start your program under GDB, use the `run' command. The program
488: must already have been specified using the `exec-file' command or with
489: an argument to GDB (*Note Files::); what `run' does is create an
490: inferior process, load the program into it, and set it in motion.
491:
492: The execution of a program is affected by certain information it receives
493: from its superior. GDB provides ways to specify them, which you must do
494: before starting the program. (You can change them after starting the
495: program, but such changes do not affect the program unless you start it
496: over again.)
497:
498: The arguments.
499: You specify the arguments to give the program as the arguments of the
500: `run' command.
501:
502: The environment.
503: The program normally inherits its environment from GDB, but you can
504: use the GDB commands `set-environment' and `unset-environment' to
505: change parts of the environment that will be given to the program.
506:
507: The working directory.
508: The program inherits its working directory from GDB. You can set GDB's
509: working directory with the `cd' command in GDB.
510:
511: After the `run' command, the debugger does nothing but wait for your
512: program to stop. *Note Stopping::.
513:
514: * Menu:
515:
516: * Arguments:: Specifying the arguments for your program.
517: * Environment:: Specifying the environment for your program.
518: * Working Directory:: Specifying the working directory for giving
519: to your program when it is run.
520: * Input/Output:: Specifying the program's standard input and output.
521: * Attach:: Debugging a process started outside GDB.
522:
523:
524: File: gdb Node: Arguments, Prev: Running, Up: Running, Next: Environment
525:
526: Your Program's Arguments
527: ========================
528:
529: You specify the arguments to give the program as the arguments of the
530: `run' command. They are passed to a shell, which expands wildcard
531: characters and performs redirection of I/O, and thence to the program.
532:
533: `run' with no arguments uses the same arguments used by the previous
534: `run'.
535:
536: The command `set-args' can be used to specify the arguments to be used
537: the next time the program is run. If `set-args' has no arguments, it
538: means to use no arguments the next time the program is run. If you have
539: run your program with arguments and want to run it again with no arguments,
540: this is the only way to do so.
541:
542:
543: File: gdb Node: Environment, Prev: Arguments, Up: Running, Next: Working Directory
544:
545: Your Program's Environment
546: ==========================
547:
548: The "environment" consists of a set of "environment variables" and
549: their values. Environment variables conventionally record such things as
550: your user name, your home directory, your terminal type, and your search
551: path for programs to run. Usually you set up environment variables with
552: the shell and they are inherited by all the other programs you run. When
553: debugging, it can be useful to try running the program with different
554: environments without having to start the debugger over again.
555:
556: `info environment VARNAME'
557: Print the value of environment variable VARNAME to be given to
558: your program when it is started. This command can be abbreviated
559: `i env VARNAME'.
560:
561: `info environment'
562: Print the names and values of all environment variables to be given to
563: your program when it is started. This command can be abbreviated
564: `i env'.
565:
566: `set-environment VARNAME VALUE'
567: Sets environment variable VARNAME to VALUE, for your
568: program only, not for GDB itself. VALUE may be any string; the
569: values of environment variables are just strings, and any
570: interpretation is supplied by your program itself. This command
571: can be abbreviated as short as `set-e'.
572:
573: `unset-environment VARNAME'
574: Remove variable VARNAME from the environment to be passed to
575: your program. This is different from `set-env VARNAME ='
576: because `unset-environment' makes a variable not be defined at
577: all, which is distinguishable from an empty value. This command can
578: be abbreviated `unset'.
579:
580:
581: File: gdb Node: Working Directory, Prev: Environment, Up: Running, Next: Input/Output
582:
583: Your Program's Working Directory
584: ================================
585:
586: Each time you start your program with `run', it inherits its working
587: directory from the current working directory of GDB. GDB's working
588: directory is initially whatever it inherited from its superior, but you can
589: specify the working directory for GDB with the `cd' command.
590:
591: The GDB working directory also serves as a default for the commands
592: that specify files for GDB to operate on. *Note Files::.
593:
594: `cd DIRECTORY'
595: Set GDB's working directory to DIRECTORY.
596:
597: `pwd'
598: Print GDB's working directory.
599:
600:
601: File: gdb Node: Input/Output, Prev: Working Directory, Up: Running, Next: Attach
602:
603: Your Program's Input and Output
604: ===============================
605:
606: By default, the program you run under GDB does input and output to the same
607: terminal that GDB uses.
608:
609: You can redirect the program's input and/or output using `sh'-style
610: redirection commands in the `run' command. For example,
611:
612: run > outfile
613:
614: starts the program, diverting its output to the file `outfile'.
615:
616: Another way to specify where the program should do input and output is with
617: the `tty' command. This command accepts a file name as argument, and
618: causes this file to be the default for future `run' commands. For
619: example,
620:
621: tty /dev/ttyb
622:
623: directs that processes started with subsequent `run' commands default
624: to do input and output on the terminal `/dev/ttyb'. An explicit
625: redirection in `run' overrides the `tty' command.
626:
627: When you use the `tty' command or redirect input in the `run'
628: command, the *input for your program* comes from the specified file,
629: but the input for GDB still comes from your terminal. The program's
630: controlling terminal is your (GDB's) terminal, not the terminal that the
631: program is reading from; so if you want to type `C-c' to stop the
632: program, you must type it on your (GDB's) terminal. A `C-c' typed on
633: the program's terminal is available to the program as ordinary input.
634:
635:
636: File: gdb Node: Attach, Prev: Input/Output, Up: Running
637:
638: Debugging an Already-Running Process
639: ====================================
640:
641: Some operating systems (in particular, Sun) allow GDB to begin debugging an
642: already-running process that was started outside of GDB. To do this you
643: must use the `attach' command instead of the `run' command.
644:
645: The `attach' command requires one argument, which is the process-id of
646: the process you want to debug. (The usual way to find out the process-id
647: of the process is with the `ps' utility.)
648:
649: The first thing GDB after arranging to debug the process is to stop it.
650: You can examine and modify an attached process with all the GDB commands
651: that ordinarily available when you start processes with `run'. You
652: can insert breakpoints; you can step and continue; you can modify storage.
653: If you would rather the process continue running, use the `continue'
654: command after attaching.
655:
656: When you are finished debugging the attached process, you can use the
657: `detach' command to release it from GDB's control. Detaching
658: the process continues its execution. After the `detach' command,
659: that process and GDB become completely independent once more, and you
660: are ready to `attach' another process or start one with `run'.
661:
662: If you exit GDB or use the `run' command while you have an attached
663: process, you kill that process. You will be asked for confirmation if you
664: try to do either of these things.
665:
666:
667: File: gdb Node: Stopping, Prev: Running, Up: Top, Next: Stack
668:
669: Stopping and Continuing
670: ***********************
671:
672: When you run a program normally, it runs until exiting. The purpose
673: of using a debugger is so that you can stop it before that point;
674: or so that if the program runs into trouble you can find out why.
675:
676: * Menu:
677:
678: * Signals:: Fatal signals in your program just stop it;
679: then you can use GDB to see what is going on.
680: * Breakpoints:: Breakpoints let you stop your program when it
681: reaches a specified point in the code.
682: * Continuing:: Resuming execution until the next signal or breakpoint.
683: * Stepping:: Stepping runs the program a short distance and
684: then stops it wherever it has come to.
685:
686:
687: File: gdb Node: Signals, Prev: Stopping, Up: Stopping, Next: Breakpoints
688:
689: Signals
690: =======
691:
692: A signal is an asynchronous event that can happen in a program. The
693: operating system defines the possible kinds of signals, and gives each kind
694: a name and a number. For example, `SIGINT' is the signal a program
695: gets when you type `Ctrl-c'; `SIGSEGV' is the signal a program
696: gets from referencing a place in memory far away from all the areas in use;
697: `SIGALRM' occurs when the alarm clock timer goes off (which happens
698: only if the program has requested an alarm).
699:
700: Some signals, including `SIGALRM', are a normal part of the
701: functioning of the program. Others, such as `SIGSEGV', indicate
702: errors; these signals are "fatal" (kill the program immediately) if the
703: program has not specified in advance some other way to handle the signal.
704: `SIGINT' does not indicate an error in the program, but it is normally
705: fatal so it can carry out the purpose of `Ctrl-c': to kill the program.
706:
707: GDB has the ability to detect any occurrence of a signal in the program
708: running under GDB's control. You can tell GDB in advance what to do for
709: each kind of signal.
710:
711: Normally, GDB is set up to ignore non-erroneous signals like `SIGALRM'
712: (so as not to interfere with their role in the functioning of the program)
713: but to stop the program immediately whenever an error signal happens.
714: You can change these settings with the `handle' command. You must
715: specify which signal you are talking about with its number.
716:
717: `info signal'
718: Print a table of all the kinds of signals and how GDB has been told to
719: handle each one. You can use this to see the signal numbers of all
720: the defined types of signals.
721:
722: `handle SIGNALNUM KEYWORDS...'
723: Change the way GDB handles signal SIGNALNUM. The KEYWORDS
724: say what change to make.
725:
726: To use the `handle' command you must know the code number of the
727: signal you are concerned with. To find the code number, type `info
728: signal' which prints a table of signal names and numbers.
729:
730: The keywords allowed by the handle command can be abbreviated. Their full
731: names are
732:
733: `stop'
734: GDB should stop the program when this signal happens. This implies
735: the `print' keyword as well.
736:
737: `print'
738: GDB should print a message when this signal happens.
739:
740: `nostop'
741: GDB should not stop the program when this signal happens. It may
742: still print a message telling you that the signal has come in.
743:
744: `noprint'
745: GDB should not mention the occurrence of the signal at all. This
746: implies the `nostop' keyword as well.
747:
748: `pass'
749: GDB should allow the program to see this signal; the program will be
750: able to handle the signal, or may be terminated if the signal is fatal
751: and not handled.
752:
753: `nopass'
754: GDB should not allow the program to see this signal.
755:
756: When a signal has been set to stop the program, the program cannot see the
757: signal until you continue. It will see the signal then, if `pass' is
758: in effect for the signal in question at that time. In other words,
759: after GDB reports a signal, you can use the `handle' command with
760: `pass' or `nopass' to control whether that signal will be seen by
761: the program when you later continue it.
762:
763: You can also use the `signal' command to prevent the program from
764: seeing a signal, or cause it to see a signal it normally would not see,
765: or to give it any signal at any time. *Note Signaling::.
766:
767:
768: File: gdb Node: Breakpoints, Prev: Signals, Up: Stopping, Next: Continuing
769:
770: Breakpoints
771: ===========
772:
773: A "breakpoint" makes your program stop whenever a certain point in the
774: program is reached. You set breakpoints explicitly with GDB commands,
775: specifying the place where the program should stop by line number, function
776: name or exact address in the program. You can add various other conditions
777: to control whether the program will stop.
778:
779: Each breakpoint is assigned a number when it is created; these numbers are
780: successive integers starting with 1. In many of the commands for controlling
781: various features of breakpoints you use the breakpoint number to say which
782: breakpoint you want to change. Each breakpoint may be "enabled" or
783: "disabled"; if disabled, it has no effect on the program until you
784: enable it again.
785:
786: The command `info break' prints a list of all breakpoints set and not
787: cleared, showing their numbers, where in the program they are, and any
788: special features in use for them. Disabled breakpoints are included in the
789: list, but marked as disabled. `info break' with a breakpoint number
790: as argument lists only that breakpoint. The convenience variable `$_'
791: and the default examining-address for the `x' command are set to the
792: address of the last breakpoint listed (*Note Memory::).
793:
794: * Menu:
795:
796: * Set Breaks:: How to establish breakpoints.
797: * Clear Breaks:: How to remove breakpoints no longer needed.
798: * Disabling:: How to disable breakpoints (turn them off temporarily).
799: * Conditions:: Making extra conditions on whether to stop.
800: * Break Commands:: Commands to be executed at a breakpoint.
801: * Error in Breakpoints:: "Cannot insert breakpoints" error--why, what to do.
802:
803:
804: File: gdb Node: Set Breaks, Prev: Breakpoints, Up: Breakpoints, Next: Clear Breaks
805:
806: Setting Breakpoints
807: -------------------
808:
809: Breakpoints are set with the `break' command (abbreviated `b').
810: You have several ways to say where the breakpoint should go.
811:
812: `break FUNCTION'
813: Set a breakpoint at entry to function FUNCTION.
814:
815: `break LINENUM'
816: Set a breakpoint at line LINENUM in the current source file.
817: That file is the last file whose source text was printed. This
818: breakpoint will stop the program just before it executes any of the
819: code on that line.
820:
821: `break FILENAME:LINENUM'
822: Set a breakpoint at line LINENUM in source file FILENAME.
823:
824: `break FILENAME:FUNCTION'
825: Set a breakpoint at entry to function FUNCTION found in file
826: FILENAME. Specifying a filename as well as a function name is
827: superfluous except when multiple files contain similarly named
828: functions.
829:
830: `break *ADDRESS'
831: Set a breakpoint at address ADDRESS. You can use this to set
832: breakpoints in parts of the program which do not have debugging
833: information or source files.
834:
835: `break'
836: Set a breakpoint at the next instruction to be executed in the
837: selected stack frame (*Note Stack::). This is a silly thing to do in
838: the innermost stack frame because the program would stop immediately
839: after being started, but it is very useful with another stack frame,
840: because it will cause the program to stop as soon as control returns
841: to that frame.
842:
843: `break ... if COND'
844: Set a breakpoint with condition COND; evaluate the expression
845: COND each time the breakpoint is reached, and stop only if the
846: value is nonzero. `...' stands for one of the possible
847: arguments described above (or no argument) specifying where to break.
848: *Note Conditions::, for more information on breakpoint conditions.
849:
850: `tbreak ARGS'
851: Set a breakpoint enabled only for one stop. ARGS are the
852: same as in the `break' command, and the breakpoint is set in the same
853: way, but the breakpoint is automatically "disabled" the first time it
854: is hit.
855:
856: GDB allows you to set any number of breakpoints at the same place in the
857: program. There is nothing silly or meaningless about this. When the
858: breakpoints are conditional, this is even useful (*Note Conditions::).
859:
860:
861: File: gdb Node: Clear Breaks, Prev: Set Breaks, Up: Breakpoints, Next: Disabling
862:
863: Clearing Breakpoints
864: --------------------
865:
866: It is often necessary to eliminate a breakpoint once it has done its job
867: and you no longer want the program to stop there. This is called
868: "clearing" or `deleting' the breakpoint. A breakpoint that
869: has been cleared no longer exists in any sense.
870:
871: With the `clear' command you can clear breakpoints according to where
872: they are in the program. With the `delete' command you can clear
873: individual breakpoints by specifying their breakpoint numbers.
874:
875: It is not necessary to clear a breakpoint to proceed past it. GDB
876: automatically ignores breakpoints in the first instruction to be executed
877: when you continue execution at the same address where the program stopped.
878:
879: `clear'
880: Clear any breakpoints at the next instruction to be executed in the
881: selected stack frame (*Note Selection::). When the innermost frame
882: is selected, this is a good way to clear a breakpoint that the program
883: just stopped at.
884:
885: `clear FUNCTION'
886: `clear FILENAME:FUNCTION'
887: Clear any breakpoints set at entry to the function FUNCTION.
888:
889: `clear LINENUM'
890: `clear FILENAME:LINENUM'
891: Clear any breakpoints set at or within the code of the specified line.
892:
893: `delete BNUMS...'
894: Delete the breakpoints of the numbers specified as arguments.
895: A breakpoint deleted is forgotten completely.
896:
897:
898: File: gdb Node: Disabling, Prev: Clear Breaks, Up: Breakpoints, Next: Conditions
899:
900: Disabling Breakpoints
901: ---------------------
902:
903: Rather than clearing a breakpoint, you might prefer to "disable" it.
904: This makes the breakpoint inoperative as if it had been cleared, but
905: remembers the information on the breakpoint so that you can "enable"
906: it again later.
907:
908: You disable and enable breakpoints with the `enable' and
909: `disable' commands, specifying one or more breakpoint numbers as
910: arguments. Use `info break' to print a list of breakpoints if you
911: don't know which breakpoint numbers to use.
912:
913: A breakpoint can have any of four different states of enablement:
914:
915: * Enabled. The breakpoint will stop the program. A breakpoint made
916: with the `break' command starts out in this state.
917: * Disabled. The breakpoint has no effect on the program.
918: * Enabled once. The breakpoint will stop the program, but
919: when it does so it will become disabled. A breakpoint made
920: with the `tbreak' command starts out in this state.
921: * Enabled for deletion. The breakpoint will stop the program, but
922: immediately after it does so it will be deleted permanently.
923:
924: You change the state of enablement of a breakpoint with the following
925: commands:
926:
927: `disable BNUMS...'
928: Disable the specified breakpoints. A disabled breakpoint has no
929: effect but is not forgotten. All options such as ignore-counts,
930: conditions and commands are remembered in case the breakpoint is
931: enabled again later.
932:
933: `enable BNUMS...'
934: Enable the specified breakpoints. They become effective once again in
935: stopping the program, until you specify otherwise.
936:
937: `enable once BNUMS...'
938: Enable the specified breakpoints temporarily. Each will be disabled
939: again the next time it stops the program (unless you have used one of
940: these commands to specify a different state before that time comes).
941:
942: `enable delete BNUMS...'
943: Enable the specified breakpoints to work once and then die. Each of
944: the breakpoints will be deleted the next time it stops the program
945: (unless you have used one of these commands to specify a different
946: state before that time comes).
947:
948: Aside from the automatic disablement or deletion of a breakpoint when it
949: stops the program, which happens only in certain states, the state of
950: enablement of a breakpoint changes only when one of the commands above
951: is used.
952:
953:
954: File: gdb Node: Conditions, Prev: Disabling, Up: Breakpoints, Next: Break Commands
955:
956: Break Conditions
957: ----------------
958:
959: The simplest sort of breakpoint breaks every time the program reaches a
960: specified place. You can also specify a "condition" for a breakpoint.
961: A condition is just a boolean expression in your programming language.
962: A breakpoint with a condition evaluates the expression each time the
963: program reaches it, and the program stops only if the condition is true.
964:
965: Break conditions may have side effects, and may even call functions in your
966: program. These may sound like strange things to do, but their effects are
967: completely predictable unless there is another enabled breakpoint at the
968: same address. (In that case, GDB might see the other breakpoint first and
969: stop the program without checking the condition of this one.) Note that
970: breakpoint commands are usually more convenient and flexible for the
971: purpose of performing side effects when a breakpoint is reached
972: (*Note Break Commands::).
973:
974: Break conditions can be specified when a breakpoint is set, by using
975: `if' in the arguments to the `break' command. *Note Set Breaks::.
976: They can also be changed at any time with the `condition' command:
977:
978: `condition BNUM EXPRESSION'
979: Specify EXPRESSION as the break condition for breakpoint number
980: BNUM. From now on, this breakpoint will stop the program only if
981: the value of EXPRESSION is true (nonzero, in C). EXPRESSION
982: is not evaluated at the time the `condition' command is given.
983:
984: `condition BNUM'
985: Remove the condition from breakpoint number BNUM. It becomes
986: an ordinary unconditional breakpoint.
987:
988: A special feature is provided for one kind of condition: to prevent the
989: breakpoint from doing anything until it has been reached a certain number
990: of times. This is done with the "ignore count" of the breakpoint.
991: When the program reaches a breakpoint whose ignore count is positive, then
992: instead of stopping, it just decrements the ignore count by one and
993: continues.
994:
995: `ignore BNUM COUNT'
996: Set the ignore count of breakpoint number BNUM to COUNT.
997: The next COUNT times the breakpoint is reached, it will not stop.
998:
999: To make the breakpoint stop the next time it is reached, specify
1000: a count of zero.
1001:
1002: `cont COUNT'
1003: Continue execution of the program, setting the ignore count of the
1004: breakpoint that the program stopped at to COUNT minus one.
1005: Continuing through the breakpoint does not itself count as one of
1006: COUNT. Thus, the program will not stop at this breakpoint until the
1007: COUNT'th time it is hit.
1008:
1009: This command is allowed only when the program stopped due to a
1010: breakpoint. At other times, the argument to `cont' is ignored.
1011:
1012: If a breakpoint has a positive ignore count and a condition, the condition
1013: is not checked. Once the ignore count reaches zero, the condition will
1014: start to be checked.
1015:
1016: Note that you could achieve the effect of the ignore count with a condition
1017: such as `$foo-- <= 0' using a debugger convenience variable that is
1018: decremented each time. That is why the ignore count is considered a
1019: special case of a condition. *Note Convenience Vars::.
1020:
1021:
1022: File: gdb Node: Break Commands, Prev: Conditions, Up: Breakpoints, Next: Error in Breakpoints
1023:
1024: Commands Executed on Breaking
1025: -----------------------------
1026:
1027: You can give any breakpoint a series of commands to execute when the
1028: program stops due to that breakpoint. For example, you might want to
1029: print the values of certain expressions, or enable other breakpoints.
1030:
1031: `commands BNUM'
1032: Specify commands for breakpoint number BNUM. The commands
1033: themselves appear on the following lines. Type a line containing just
1034: `end' to terminate the commands.
1035:
1036: To remove all commands from a breakpoint, use the command
1037: `commands' and follow it immediately by `end'; that is, give
1038: no commands.
1039:
1040: It is possible for breakpoint commands to start the program up again.
1041: Simply use the `cont' command, or `step', or any other command
1042: to resume execution. However, any remaining breakpoint commands are
1043: ignored. When the program stops again, GDB will act according to why
1044: that stop took place.
1045:
1046: If the first command specified is `silent', the usual message about
1047: stopping at a breakpoint is not printed. This may be desirable for
1048: breakpoints that are to print a specific message and then continue.
1049: If the remaining commands too print nothing, you will see no sign that
1050: the breakpoint was reached at all. `silent' is not really a command;
1051: it is meaningful only at the beginning of the commands for a breakpoint.
1052:
1053: The commands `echo' and `output' that allow you to print precisely
1054: controlled output are often useful in silent breakpoints. *Note Output::.
1055:
1056: For example, here is how you could use breakpoint commands to print the
1057: value of `x' at entry to `foo' whenever it is positive. We
1058: assume that the newly created breakpoint is number 4; `break' will
1059: print the number that is assigned.
1060:
1061: break foo if x>0
1062: commands 4
1063: silent
1064: echo x is\040
1065: output x
1066: echo \n
1067: cont
1068: end
1069:
1070: One application for breakpoint commands is to correct one bug so you can
1071: test another. Put a breakpoint just after the erroneous line of code, give
1072: it a condition to detect the case in which something erroneous has been
1073: done, and give it commands to assign correct values to any variables that
1074: need them. End with the `cont' command so that the program does not
1075: stop, and start with the `silent' command so that no output is
1076: produced. Here is an example:
1077:
1078: break 403
1079: commands 5
1080: silent
1081: set x = y + 4
1082: cont
1083: end
1084:
1085: One deficiency in the operation of automatically continuing breakpoints
1086: under Unix appears when your program uses raw mode for the terminal.
1087: GDB options back to its own terminal modes (not raw) before executing
1088: commands, and then must switch back to raw mode when your program is
1089: continued. This causes any pending terminal input to be lost.
1090:
1091: In the GNU system, this will be fixed by changing the behavior of
1092: terminal modes.
1093:
1094: Under Unix, when you have this problem, you might be able to get around
1095: it by putting your actions into the breakpoint condition instead of
1096: commands. For example
1097:
1098: condition 5 (x = y + 4), 0
1099:
1100: is a condition expression that will change `x' as needed, then always
1101: have the value 0 so the program will not stop. Loss of input is avoided
1102: here because break conditions are evaluated without changing the terminal
1103: modes. When you want to have nontrivial conditions for performing the side
1104: effects, the operators `&&', `||' and `? ... :' may be useful.
1105:
1106:
1107: File: gdb Node: Error in Breakpoints, Prev: Break Commands, Up: Breakpoints
1108:
1109: "Cannot Insert Breakpoints" Error
1110: ---------------------------------
1111:
1112: Under Unix, breakpoints cannot be used in a program if any other process
1113: is running that program. Attempting to run or continue the program with
1114: a breakpoint in this case will cause GDB to stop it.
1115:
1116: When this happens, you have two ways to proceed:
1117:
1118: 1. Remove or disable the breakpoints, then continue.
1119:
1120: 2. Suspend GDB, and copy the file containing the program to a new name.
1121: Resume GDB and use the `exec-file' command to specify that GDB
1122: should run the program under that name. Then start the program again.
1123:
1124:
1125: File: gdb Node: Continuing, Prev: Breakpoints, Up: Stopping, Next: Stepping
1126:
1127: Continuing
1128: ==========
1129:
1130: After your program stops, most likely you will want it to run some more if
1131: the bug you are looking for has not happened yet.
1132:
1133: `cont'
1134: Continue running the program at the place where it stopped.
1135:
1136: If the program stopped at a breakpoint, the place to continue running
1137: is the address of the breakpoint. You might expect that continuing would
1138: just stop at the same breakpoint immediately. In fact, `cont'
1139: takes special care to prevent that from happening. You do not need
1140: to clear the breakpoint to proceed through it after stopping at it.
1141:
1142: You can, however, specify an ignore-count for the breakpoint that the
1143: program stopped at, by means of an argument to the `cont' command.
1144: *Note Conditions::.
1145:
1146: If the program stopped because of a signal other than `SIGINT' or
1147: `SIGTRAP', continuing will cause the program to see that signal.
1148: You may not want this to happen. For example, if the program stopped
1149: due to some sort of memory reference error, you might store correct
1150: values into the erroneous variables and continue, hoping to see more
1151: execution; but the program would probably terminate immediately as
1152: a result of the fatal signal once it sees the signal. To prevent this,
1153: you can continue with `signal 0'. *Note Signaling::. You can
1154: also act in advance to prevent the program from seeing certain kinds
1155: of signals, using the `handle' command (*Note Signals::).
1156:
1157:
1158: File: gdb Node: Stepping, Prev: Continuing, Up: Stopping
1159:
1160: Stepping
1161: ========
1162:
1163: "Stepping" means setting your program in motion for a limited time, so
1164: that control will return automatically to the debugger after one line of
1165: code or one machine instruction. Breakpoints are active during stepping
1166: and the program will stop for them even if it has not gone as far as the
1167: stepping command specifies.
1168:
1169: `step'
1170: Proceed the program until control reaches a different line, then stop
1171: it and return to the debugger. This command is abbreviated `s'.
1172:
1173: `step COUNT'
1174: Proceed as in `step', but do so COUNT times. If a breakpoint
1175: or a signal not related to stepping is reached before COUNT steps,
1176: stepping stops right away.
1177:
1178: `next'
1179: Similar to `step', but any function calls appearing within the line of
1180: code are executed without stopping. Execution stops when control reaches a
1181: different line of code at the stack level which was executing when the
1182: `next' command was given. This command is abbreviated `n'.
1183:
1184: An argument is a repeat count, as in `step'.
1185:
1186: `finish'
1187: Continue running until just after the selected stack frame returns
1188: (or until there is some other reason to stop, such as a fatal signal
1189: or a breakpoint).
1190:
1191: Contrast this with the `return' command (*Note Returning::).
1192:
1193: `stepi'
1194: `si'
1195: Proceed one machine instruction, then stop and return to the debugger.
1196:
1197: It is often useful to do `display/i $pc' when stepping by machine
1198: instructions. This will cause the next instruction to be executed to
1199: be displayed automatically at each stop. *Note Auto Display::.
1200:
1201: An argument is a repeat count, as in `step'.
1202:
1203: `nexti'
1204: `ni'
1205: Proceed one machine instruction, but if it is a subroutine call,
1206: proceed until the subroutine returns.
1207:
1208: An argument is a repeat count, as in `next'.
1209:
1210: A typical technique for using stepping is to put a breakpoint
1211: (*Note Breakpoints::) at the beginning of the function or the section of
1212: the program in which a problem is believed to lie, and then step through
1213: the suspect area, examining the variables that are interesting, until the
1214: problem happens.
1215:
1216: The `cont' command can be used after stepping to resume execution
1217: until the next breakpoint or signal.
1218:
1219:

unix.superglobalmegacorp.com

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.