| gdb.texinfo (46289) | gdb.texinfo (98948) |
|---|---|
| 1\input texinfo @c -*-texinfo-*- | 1\input texinfo @c -*-texinfo-*- |
| 2@c Copyright 1988-1999 | 2@c Copyright 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996, 1998, 3@c 1999, 2000, 2001, 2002 |
| 3@c Free Software Foundation, Inc. 4@c | 4@c Free Software Foundation, Inc. 5@c |
| 5@c %**start of header | 6@c %**start of header |
| 6@c makeinfo ignores cmds prev to setfilename, so its arg cannot make use 7@c of @set vars. However, you can override filename with makeinfo -o. 8@setfilename gdb.info 9@c 10@include gdb-cfg.texi 11@c | 7@c makeinfo ignores cmds prev to setfilename, so its arg cannot make use 8@c of @set vars. However, you can override filename with makeinfo -o. 9@setfilename gdb.info 10@c 11@include gdb-cfg.texi 12@c |
| 12@ifset GENERIC | |
| 13@settitle Debugging with @value{GDBN} | 13@settitle Debugging with @value{GDBN} |
| 14@end ifset 15@ifclear GENERIC 16@settitle Debugging with @value{GDBN} (@value{TARGET}) 17@end ifclear | |
| 18@setchapternewpage odd 19@c %**end of header 20 21@iftex 22@c @smallbook 23@c @cropmarks 24@end iftex 25 26@finalout 27@syncodeindex ky cp 28 | 14@setchapternewpage odd 15@c %**end of header 16 17@iftex 18@c @smallbook 19@c @cropmarks 20@end iftex 21 22@finalout 23@syncodeindex ky cp 24 |
| 29@c readline appendices use @vindex | 25@c readline appendices use @vindex, @findex and @ftable, 26@c annotate.texi and gdbmi use @findex. |
| 30@syncodeindex vr cp | 27@syncodeindex vr cp |
| 28@syncodeindex fn cp |
|
| 31 32@c !!set GDB manual's edition---not the same as GDB version! | 29 30@c !!set GDB manual's edition---not the same as GDB version! |
| 33@set EDITION Seventh | 31@set EDITION Ninth |
| 34 35@c !!set GDB manual's revision date | 32 33@c !!set GDB manual's revision date |
| 36@set DATE February 1999 | 34@set DATE December 2001 |
| 37 | 35 |
| 38@c THIS MANUAL REQUIRES TEXINFO-2 macros and info-makers to format properly. | 36@c THIS MANUAL REQUIRES TEXINFO 4.0 OR LATER. |
| 39 | 37 |
| 40@ifinfo | |
| 41@c This is a dir.info fragment to support semi-automated addition of | 38@c This is a dir.info fragment to support semi-automated addition of |
| 42@c manuals to an info tree. zoo@cygnus.com is developing this facility. 43@format 44START-INFO-DIR-ENTRY 45* Gdb: (gdb). The @sc{gnu} debugger. 46END-INFO-DIR-ENTRY 47@end format 48@end ifinfo 49@c 50@c | 39@c manuals to an info tree. 40@dircategory Programming & development tools. 41@direntry 42* Gdb: (gdb). The @sc{gnu} debugger. 43@end direntry 44 |
| 51@ifinfo 52This file documents the @sc{gnu} debugger @value{GDBN}. 53 54 | 45@ifinfo 46This file documents the @sc{gnu} debugger @value{GDBN}. 47 48 |
| 55This is the @value{EDITION} Edition, @value{DATE}, | 49This is the @value{EDITION} Edition, @value{DATE}, |
| 56of @cite{Debugging with @value{GDBN}: the @sc{gnu} Source-Level Debugger} 57for @value{GDBN} Version @value{GDBVN}. 58 | 50of @cite{Debugging with @value{GDBN}: the @sc{gnu} Source-Level Debugger} 51for @value{GDBN} Version @value{GDBVN}. 52 |
| 59Copyright (C) 1988-1999 Free Software Foundation, Inc. | 53Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996, 1998,@* 54 1999, 2000, 2001, 2002 Free Software Foundation, Inc. |
| 60 | 55 |
| 61Permission is granted to make and distribute verbatim copies of 62this manual provided the copyright notice and this permission notice 63are preserved on all copies. | 56Permission is granted to copy, distribute and/or modify this document 57under the terms of the GNU Free Documentation License, Version 1.1 or 58any later version published by the Free Software Foundation; with the 59Invariant Sections being ``Free Software'' and ``Free Software Needs 60Free Documentation'', with the Front-Cover Texts being ``A GNU Manual,'' 61and with the Back-Cover Texts as in (a) below. |
| 64 | 62 |
| 65@ignore 66Permission is granted to process this file through TeX and print the 67results, provided the printed document carries copying permission 68notice identical to this one except for the removal of this paragraph 69(this paragraph not being relevant to the printed manual). 70 71@end ignore 72Permission is granted to copy and distribute modified versions of this 73manual under the conditions for verbatim copying, provided also that the 74entire resulting derived work is distributed under the terms of a 75permission notice identical to this one. 76 77Permission is granted to copy and distribute translations of this manual 78into another language, under the above conditions for modified versions. | 63(a) The Free Software Foundation's Back-Cover Text is: ``You have 64freedom to copy and modify this GNU Manual, like GNU software. Copies 65published by the Free Software Foundation raise funds for GNU 66development.'' |
| 79@end ifinfo 80 81@titlepage 82@title Debugging with @value{GDBN} 83@subtitle The @sc{gnu} Source-Level Debugger | 67@end ifinfo 68 69@titlepage 70@title Debugging with @value{GDBN} 71@subtitle The @sc{gnu} Source-Level Debugger |
| 84@ifclear GENERIC 85@subtitle (@value{TARGET}) 86@end ifclear | |
| 87@sp 1 | 72@sp 1 |
| 88@ifclear HPPA | |
| 89@subtitle @value{EDITION} Edition, for @value{GDBN} version @value{GDBVN} 90@subtitle @value{DATE} | 73@subtitle @value{EDITION} Edition, for @value{GDBN} version @value{GDBVN} 74@subtitle @value{DATE} |
| 91@author Richard M. Stallman and Roland H. Pesch 92@end ifclear 93@ifset HPPA 94@subtitle Edition @value{EDITION}, for @value{HPVER} (based on @value{GDBN} @value{GDBVN}) 95@subtitle @value{DATE} 96@author Richard M. Stallman and Roland H. Pesch (modified by HP) 97@end ifset | 75@author Richard Stallman, Roland Pesch, Stan Shebs, et al. |
| 98@page | 76@page |
| 99@ifclear HPPA | |
| 100@tex 101{\parskip=0pt | 77@tex 78{\parskip=0pt |
| 102\hfill (Send bugs and comments on @value{GDBN} to bug-gdb\@prep.ai.mit.edu.)\par | 79\hfill (Send bugs and comments on @value{GDBN} to bug-gdb\@gnu.org.)\par |
| 103\hfill {\it Debugging with @value{GDBN}}\par 104\hfill \TeX{}info \texinfoversion\par 105} 106@end tex | 80\hfill {\it Debugging with @value{GDBN}}\par 81\hfill \TeX{}info \texinfoversion\par 82} 83@end tex |
| 107@end ifclear 108@ifset HPPA 109@tex 110{\parskip=0pt 111\hfill {\it Debugging with @value{GDBN}}\par 112\hfill \TeX{}info \texinfoversion\par 113} 114@end tex 115@end ifset | |
| 116 117@vskip 0pt plus 1filll | 84 85@vskip 0pt plus 1filll |
| 118Copyright @copyright{} 1988-1999 Free Software Foundation, Inc. | 86Copyright @copyright{} 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 871996, 1998, 1999, 2000, 2001, 2002 Free Software Foundation, Inc. |
| 119@sp 2 | 88@sp 2 |
| 120@ifclear HPPA | |
| 121Published by the Free Software Foundation @* 12259 Temple Place - Suite 330, @* 123Boston, MA 02111-1307 USA @* | 89Published by the Free Software Foundation @* 9059 Temple Place - Suite 330, @* 91Boston, MA 02111-1307 USA @* |
| 124Printed copies are available for $20 each. @* 125ISBN 1-882114-11-6 @* 126@end ifclear 127 128Permission is granted to make and distribute verbatim copies of 129this manual provided the copyright notice and this permission notice 130are preserved on all copies. | 92ISBN 1-882114-77-9 @* |
| 131 | 93 |
| 132Permission is granted to copy and distribute modified versions of this 133manual under the conditions for verbatim copying, provided also that the 134entire resulting derived work is distributed under the terms of a 135permission notice identical to this one. | 94Permission is granted to copy, distribute and/or modify this document 95under the terms of the GNU Free Documentation License, Version 1.1 or 96any later version published by the Free Software Foundation; with the 97Invariant Sections being ``Free Software'' and ``Free Software Needs 98Free Documentation'', with the Front-Cover Texts being ``A GNU Manual,'' 99and with the Back-Cover Texts as in (a) below. |
| 136 | 100 |
| 137Permission is granted to copy and distribute translations of this manual 138into another language, under the above conditions for modified versions. | 101(a) The Free Software Foundation's Back-Cover Text is: ``You have 102freedom to copy and modify this GNU Manual, like GNU software. Copies 103published by the Free Software Foundation raise funds for GNU 104development.'' |
| 139@end titlepage 140@page 141 | 105@end titlepage 106@page 107 |
| 142@ifinfo | 108@ifnottex |
| 143@node Top, Summary, (dir), (dir) | 109@node Top, Summary, (dir), (dir) |
| 110 |
|
| 144@top Debugging with @value{GDBN} 145 146This file describes @value{GDBN}, the @sc{gnu} symbolic debugger. 147 | 111@top Debugging with @value{GDBN} 112 113This file describes @value{GDBN}, the @sc{gnu} symbolic debugger. 114 |
| 148This is the @value{EDITION} Edition, @value{DATE}, for @value{GDBN} Version | 115This is the @value{EDITION} Edition, @value{DATE}, for @value{GDBN} Version |
| 149@value{GDBVN}. 150 | 116@value{GDBVN}. 117 |
| 151Copyright (C) 1988-1999 Free Software Foundation, Inc. | 118Copyright (C) 1988-2002 Free Software Foundation, Inc. 119 |
| 152@menu 153* Summary:: Summary of @value{GDBN} | 120@menu 121* Summary:: Summary of @value{GDBN} |
| 154@ifclear BARETARGET | |
| 155* Sample Session:: A sample @value{GDBN} session | 122* Sample Session:: A sample @value{GDBN} session |
| 156@end ifclear | |
| 157 158* Invocation:: Getting in and out of @value{GDBN} 159* Commands:: @value{GDBN} commands 160* Running:: Running programs under @value{GDBN} 161* Stopping:: Stopping and continuing 162* Stack:: Examining the stack 163* Source:: Examining source files 164* Data:: Examining data | 123 124* Invocation:: Getting in and out of @value{GDBN} 125* Commands:: @value{GDBN} commands 126* Running:: Running programs under @value{GDBN} 127* Stopping:: Stopping and continuing 128* Stack:: Examining the stack 129* Source:: Examining source files 130* Data:: Examining data |
| 165@ifclear CONLY | 131* Tracepoints:: Debugging remote targets non-intrusively 132* Overlays:: Debugging programs that use overlays 133 |
| 166* Languages:: Using @value{GDBN} with different languages | 134* Languages:: Using @value{GDBN} with different languages |
| 167@end ifclear | |
| 168 | 135 |
| 169@ifset CONLY 170* C:: C language support 171@end ifset 172 | |
| 173* Symbols:: Examining the symbol table 174* Altering:: Altering execution 175* GDB Files:: @value{GDBN} files 176* Targets:: Specifying a debugging target | 136* Symbols:: Examining the symbol table 137* Altering:: Altering execution 138* GDB Files:: @value{GDBN} files 139* Targets:: Specifying a debugging target |
| 140* Remote Debugging:: Debugging remote programs 141* Configurations:: Configuration-specific information |
|
| 177* Controlling GDB:: Controlling @value{GDBN} 178* Sequences:: Canned sequences of commands | 142* Controlling GDB:: Controlling @value{GDBN} 143* Sequences:: Canned sequences of commands |
| 179@ifclear DOSHOST | 144* TUI:: @value{GDBN} Text User Interface |
| 180* Emacs:: Using @value{GDBN} under @sc{gnu} Emacs | 145* Emacs:: Using @value{GDBN} under @sc{gnu} Emacs |
| 181@end ifclear | 146* Annotations:: @value{GDBN}'s annotation interface. 147* GDB/MI:: @value{GDBN}'s Machine Interface. |
| 182 183* GDB Bugs:: Reporting bugs in @value{GDBN} | 148 149* GDB Bugs:: Reporting bugs in @value{GDBN} |
| 184 185@ifclear PRECONFIGURED 186@ifclear HPPA | |
| 187* Formatting Documentation:: How to format and print @value{GDBN} documentation | 150* Formatting Documentation:: How to format and print @value{GDBN} documentation |
| 188@end ifclear | |
| 189 | 151 |
| 190@end ifclear 191 | |
| 192* Command Line Editing:: Command Line Editing 193* Using History Interactively:: Using History Interactively 194* Installing GDB:: Installing GDB | 152* Command Line Editing:: Command Line Editing 153* Using History Interactively:: Using History Interactively 154* Installing GDB:: Installing GDB |
| 155* Maintenance Commands:: Maintenance Commands 156* Remote Protocol:: GDB Remote Serial Protocol 157* Copying:: GNU General Public License says 158 how you can copy and share GDB 159* GNU Free Documentation License:: The license for this documentation |
|
| 195* Index:: Index | 160* Index:: Index |
| 196 197 --- The Detailed Node Listing --- 198 199Summary of @value{GDBN} 200 201* Free Software:: Freely redistributable software 202* Contributors:: Contributors to GDB 203 204Getting In and Out of @value{GDBN} 205 206* Invoking GDB:: How to start @value{GDBN} 207* Quitting GDB:: How to quit @value{GDBN} 208* Shell Commands:: How to use shell commands inside @value{GDBN} 209 210Invoking @value{GDBN} 211 212* File Options:: Choosing files 213* Mode Options:: Choosing modes 214 215@value{GDBN} Commands 216 217* Command Syntax:: How to give commands to @value{GDBN} 218* Completion:: Command completion 219* Help:: How to ask @value{GDBN} for help 220 221Running Programs Under @value{GDBN} 222 223* Compilation:: Compiling for debugging 224* Starting:: Starting your program 225@ifclear BARETARGET 226* Arguments:: Your program's arguments 227* Environment:: Your program's environment 228@end ifclear 229 230* Working Directory:: Your program's working directory 231* Input/Output:: Your program's input and output 232* Attach:: Debugging an already-running process 233* Kill Process:: Killing the child process 234@ifclear HPPA 235* Process Information:: Additional process information 236@end ifclear 237 238* Threads:: Debugging programs with multiple threads 239* Processes:: Debugging programs with multiple processes 240 241Stopping and Continuing 242 243* Breakpoints:: Breakpoints, watchpoints, and catchpoints 244* Continuing and Stepping:: Resuming execution 245@ifset POSIX 246* Signals:: Signals 247@end ifset 248@ifclear BARETARGET 249* Thread Stops:: Stopping and starting multi-thread programs 250@end ifclear 251 252Breakpoints and watchpoints 253 254* Set Breaks:: Setting breakpoints 255* Set Watchpoints:: Setting watchpoints 256* Set Catchpoints:: Setting catchpoints 257* Delete Breaks:: Deleting breakpoints 258* Disabling:: Disabling breakpoints 259* Conditions:: Break conditions 260* Break Commands:: Breakpoint command lists 261@ifclear CONLY 262* Breakpoint Menus:: Breakpoint menus 263@end ifclear 264 265Examining the Stack 266 267* Frames:: Stack frames 268* Backtrace:: Backtraces 269* Selection:: Selecting a frame 270* Frame Info:: Information on a frame 271* Alpha/MIPS Stack:: Alpha and MIPS machines and the function stack 272 273Examining Source Files 274 275* List:: Printing source lines 276@ifclear DOSHOST 277* Search:: Searching source files 278@end ifclear 279* Source Path:: Specifying source directories 280* Machine Code:: Source and machine code 281 282Examining Data 283 284* Expressions:: Expressions 285* Variables:: Program variables 286* Arrays:: Artificial arrays 287* Output Formats:: Output formats 288* Memory:: Examining memory 289* Auto Display:: Automatic display 290* Print Settings:: Print settings 291* Value History:: Value history 292* Convenience Vars:: Convenience variables 293* Registers:: Registers 294@ifclear HAVE-FLOAT 295* Floating Point Hardware:: Floating point hardware 296@end ifclear 297 298Using @value{GDBN} with Different Languages 299 300* Setting:: Switching between source languages 301* Show:: Displaying the language 302@ifset MOD2 303* Checks:: Type and range checks 304@end ifset 305 306* Support:: Supported languages 307 308Switching between source languages 309 310* Filenames:: Filename extensions and languages. 311* Manually:: Setting the working language manually 312* Automatically:: Having @value{GDBN} infer the source language 313 314@ifset MOD2 315Type and range checking 316 317* Type Checking:: An overview of type checking 318* Range Checking:: An overview of range checking 319@end ifset 320 321Supported languages 322 323@ifset MOD2 324* C:: C and C++ 325 326C Language Support 327 328* C Operators:: C operators 329 330C Language Support 331@end ifset 332 333* C Operators:: C and C++ operators 334* C Constants:: C and C++ constants 335* Cplus expressions:: C++ expressions 336* C Defaults:: Default settings for C and C++ 337@ifset MOD2 338* C Checks:: C and C++ type and range checks 339@end ifset 340* Debugging C:: @value{GDBN} and C 341* Debugging C plus plus:: @value{GDBN} features for C++ 342 343@ifset MOD2 344Modula-2 345 346* M2 Operators:: Built-in operators 347* Built-In Func/Proc:: Built-in functions and procedures 348* M2 Constants:: Modula-2 constants 349* M2 Defaults:: Default settings for Modula-2 350* Deviations:: Deviations from standard Modula-2 351* M2 Checks:: Modula-2 type and range checks 352* M2 Scope:: The scope operators @code{::} and @code{.} 353* GDB/M2:: @value{GDBN} and Modula-2 354@end ifset 355 356Altering Execution 357 358* Assignment:: Assignment to variables 359* Jumping:: Continuing at a different address 360@ifclear BARETARGET 361* Signaling:: Giving your program a signal 362@end ifclear 363* Returning:: Returning from a function 364* Calling:: Calling your program's functions 365* Patching:: Patching your program 366 367@value{GDBN} Files 368 369* Files:: Commands to specify files 370* Symbol Errors:: Errors reading symbol files 371 372Specifying a Debugging Target 373 374* Active Targets:: Active targets 375* Target Commands:: Commands for managing targets 376@ifclear HPPA 377* Byte Order:: Choosing target byte order 378* Remote:: Remote debugging 379 380Remote debugging 381@end ifclear 382 383@ifset REMOTESTUB 384* Remote Serial:: @value{GDBN} remote serial protocol 385@end ifset 386 387@ifset I960 388* i960-Nindy Remote:: @value{GDBN} with a remote i960 (Nindy) 389@end ifset 390 391@ifset AMD29K 392* UDI29K Remote:: The UDI protocol for AMD29K 393* EB29K Remote:: The EBMON protocol for AMD29K 394@end ifset 395 396@ifset VXWORKS 397* VxWorks Remote:: @value{GDBN} and VxWorks 398@end ifset 399 400@ifset ST2000 401* ST2000 Remote:: @value{GDBN} with a Tandem ST2000 402@end ifset 403 404@ifset H8 405* Hitachi Remote:: @value{GDBN} and Hitachi Microprocessors 406@end ifset 407 408@ifset MIPS 409* MIPS Remote:: @value{GDBN} and MIPS boards 410@end ifset 411 412@ifset SIMS 413* Simulator:: Simulated CPU target 414@end ifset 415 416Controlling @value{GDBN} 417 418* Prompt:: Prompt 419* Editing:: Command editing 420* History:: Command history 421* Screen Size:: Screen size 422* Numbers:: Numbers 423* Messages/Warnings:: Optional warnings and messages 424 425Canned Sequences of Commands 426 427* Define:: User-defined commands 428* Hooks:: User-defined command hooks 429* Command Files:: Command files 430* Output:: Commands for controlled output 431 432Reporting Bugs in @value{GDBN} 433 434* Bug Criteria:: Have you found a bug? 435* Bug Reporting:: How to report bugs 436 437Installing @value{GDBN} 438 439* Separate Objdir:: Compiling @value{GDBN} in another directory 440* Config Names:: Specifying names for hosts and targets 441* Configure Options:: Summary of options for configure | |
| 442@end menu 443 | 161@end menu 162 |
| 444@end ifinfo | 163@end ifnottex |
| 445 | 164 |
| 446@node Summary, Sample Session, Top, Top | 165@contents 166 167@node Summary |
| 447@unnumbered Summary of @value{GDBN} 448 449The purpose of a debugger such as @value{GDBN} is to allow you to see what is 450going on ``inside'' another program while it executes---or what another 451program was doing at the moment it crashed. 452 453@value{GDBN} can do four main kinds of things (plus other things in support of 454these) to help you catch bugs in the act: --- 8 unchanged lines hidden (view full) --- 463@item 464Examine what has happened, when your program has stopped. 465 466@item 467Change things in your program, so you can experiment with correcting the 468effects of one bug and go on to learn about another. 469@end itemize 470 | 168@unnumbered Summary of @value{GDBN} 169 170The purpose of a debugger such as @value{GDBN} is to allow you to see what is 171going on ``inside'' another program while it executes---or what another 172program was doing at the moment it crashed. 173 174@value{GDBN} can do four main kinds of things (plus other things in support of 175these) to help you catch bugs in the act: --- 8 unchanged lines hidden (view full) --- 184@item 185Examine what has happened, when your program has stopped. 186 187@item 188Change things in your program, so you can experiment with correcting the 189effects of one bug and go on to learn about another. 190@end itemize 191 |
| 471@ifclear CONLY 472You can use @value{GDBN} to debug programs written in C or C++. 473@c "MOD2" used as a "miscellaneous languages" flag here. 474@c This is acceptable while there is no real doc for Chill and Pascal. 475@ifclear MOD2 | 192You can use @value{GDBN} to debug programs written in C and C++. |
| 476For more information, see @ref{Support,,Supported languages}. | 193For more information, see @ref{Support,,Supported languages}. |
| 477@end ifclear 478@ifset MOD2 | |
| 479For more information, see @ref{C,,C and C++}. 480 | 194For more information, see @ref{C,,C and C++}. 195 |
| 196@cindex Chill 197@cindex Modula-2 |
|
| 481Support for Modula-2 and Chill is partial. For information on Modula-2, | 198Support for Modula-2 and Chill is partial. For information on Modula-2, |
| 482see @ref{Modula-2,,Modula-2}. There is no further documentation on Chill yet. | 199see @ref{Modula-2,,Modula-2}. For information on Chill, see @ref{Chill}. |
| 483 | 200 |
| 484Debugging Pascal programs which use sets, subranges, file variables, or nested 485functions does not currently work. @value{GDBN} does not support 486entering expressions, printing values, or similar features using Pascal syntax. 487@end ifset | 201@cindex Pascal 202Debugging Pascal programs which use sets, subranges, file variables, or 203nested functions does not currently work. @value{GDBN} does not support 204entering expressions, printing values, or similar features using Pascal 205syntax. |
| 488 | 206 |
| 489@ifset FORTRAN | |
| 490@cindex Fortran 491@value{GDBN} can be used to debug programs written in Fortran, although | 207@cindex Fortran 208@value{GDBN} can be used to debug programs written in Fortran, although |
| 492it does not yet support entering expressions, printing values, or 493similar features using Fortran syntax. It may be necessary to refer to 494some variables with a trailing underscore. 495@end ifset 496@end ifclear | 209it may be necessary to refer to some variables with a trailing 210underscore. |
| 497 | 211 |
| 498@ifset HPPA 499This version of the manual documents HP Wildebeest (WDB) Version 0.75, 500implemented on HP 9000 systems running Release 10.20, 10.30, or 11.0 of 501the HP-UX operating system. HP WDB 0.75 can be used to debug code 502generated by the HP ANSI C and HP ANSI C++ compilers as well as the 503@sc{gnu} C and C++ compilers. It does not support the debugging of 504Fortran, Modula-2, or Chill programs. 505@end ifset 506 | |
| 507@menu 508* Free Software:: Freely redistributable software 509* Contributors:: Contributors to GDB 510@end menu 511 | 212@menu 213* Free Software:: Freely redistributable software 214* Contributors:: Contributors to GDB 215@end menu 216 |
| 512@node Free Software, Contributors, Summary, Summary | 217@node Free Software |
| 513@unnumberedsec Free software 514 | 218@unnumberedsec Free software 219 |
| 515@value{GDBN} is @dfn{free software}, protected by the @sc{gnu} | 220@value{GDBN} is @dfn{free software}, protected by the @sc{gnu} |
| 516General Public License 517(GPL). The GPL gives you the freedom to copy or adapt a licensed 518program---but every person getting a copy also gets with it the 519freedom to modify that copy (which means that they must get access to 520the source code), and the freedom to distribute further copies. 521Typical software companies use copyrights to limit your freedoms; the 522Free Software Foundation uses the GPL to preserve these freedoms. 523 524Fundamentally, the General Public License is a license which says that 525you have these freedoms and that you cannot take these freedoms away 526from anyone else. 527 | 221General Public License 222(GPL). The GPL gives you the freedom to copy or adapt a licensed 223program---but every person getting a copy also gets with it the 224freedom to modify that copy (which means that they must get access to 225the source code), and the freedom to distribute further copies. 226Typical software companies use copyrights to limit your freedoms; the 227Free Software Foundation uses the GPL to preserve these freedoms. 228 229Fundamentally, the General Public License is a license which says that 230you have these freedoms and that you cannot take these freedoms away 231from anyone else. 232 |
| 528@node Contributors, , Free Software, Summary 529@unnumberedsec Contributors to GDB | 233@unnumberedsec Free Software Needs Free Documentation |
| 530 | 234 |
| 531Richard Stallman was the original author of GDB, and of many other 532@sc{gnu} programs. Many others have contributed to its development. 533This section attempts to credit major contributors. One of the virtues 534of free software is that everyone is free to contribute to it; with 535regret, we cannot actually acknowledge everyone here. The file 536@file{ChangeLog} in the @value{GDBN} distribution approximates a | 235The biggest deficiency in the free software community today is not in 236the software---it is the lack of good free documentation that we can 237include with the free software. Many of our most important 238programs do not come with free reference manuals and free introductory 239texts. Documentation is an essential part of any software package; 240when an important free software package does not come with a free 241manual and a free tutorial, that is a major gap. We have many such 242gaps today. 243 244Consider Perl, for instance. The tutorial manuals that people 245normally use are non-free. How did this come about? Because the 246authors of those manuals published them with restrictive terms---no 247copying, no modification, source files not available---which exclude 248them from the free software world. 249 250That wasn't the first time this sort of thing happened, and it was far 251from the last. Many times we have heard a GNU user eagerly describe a 252manual that he is writing, his intended contribution to the community, 253only to learn that he had ruined everything by signing a publication 254contract to make it non-free. 255 256Free documentation, like free software, is a matter of freedom, not 257price. The problem with the non-free manual is not that publishers 258charge a price for printed copies---that in itself is fine. (The Free 259Software Foundation sells printed copies of manuals, too.) The 260problem is the restrictions on the use of the manual. Free manuals 261are available in source code form, and give you permission to copy and 262modify. Non-free manuals do not allow this. 263 264The criteria of freedom for a free manual are roughly the same as for 265free software. Redistribution (including the normal kinds of 266commercial redistribution) must be permitted, so that the manual can 267accompany every copy of the program, both on-line and on paper. 268 269Permission for modification of the technical content is crucial too. 270When people modify the software, adding or changing features, if they 271are conscientious they will change the manual too---so they can 272provide accurate and clear documentation for the modified program. A 273manual that leaves you no choice but to write a new manual to document 274a changed version of the program is not really available to our 275community. 276 277Some kinds of limits on the way modification is handled are 278acceptable. For example, requirements to preserve the original 279author's copyright notice, the distribution terms, or the list of 280authors, are ok. It is also no problem to require modified versions 281to include notice that they were modified. Even entire sections that 282may not be deleted or changed are acceptable, as long as they deal 283with nontechnical topics (like this one). These kinds of restrictions 284are acceptable because they don't obstruct the community's normal use 285of the manual. 286 287However, it must be possible to modify all the @emph{technical} 288content of the manual, and then distribute the result in all the usual 289media, through all the usual channels. Otherwise, the restrictions 290obstruct the use of the manual, it is not free, and we need another 291manual to replace it. 292 293Please spread the word about this issue. Our community continues to 294lose manuals to proprietary publishing. If we spread the word that 295free software needs free reference manuals and free tutorials, perhaps 296the next person who wants to contribute by writing documentation will 297realize, before it is too late, that only free manuals contribute to 298the free software community. 299 300If you are writing documentation, please insist on publishing it under 301the GNU Free Documentation License or another free documentation 302license. Remember that this decision requires your approval---you 303don't have to let the publisher decide. Some commercial publishers 304will use a free license if you insist, but they will not propose the 305option; it is up to you to raise the issue and say firmly that this is 306what you want. If the publisher you are dealing with refuses, please 307try other publishers. If you're not sure whether a proposed license 308is free, write to @email{licensing@@gnu.org}. 309 310You can encourage commercial publishers to sell more free, copylefted 311manuals and tutorials by buying them, and particularly by buying 312copies from the publishers that paid for their writing or for major 313improvements. Meanwhile, try to avoid buying non-free documentation 314at all. Check the distribution terms of a manual before you buy it, 315and insist that whoever seeks your business must respect your freedom. 316Check the history of the book, and try to reward the publishers that 317have paid or pay the authors to work on it. 318 319The Free Software Foundation maintains a list of free documentation 320published by other publishers, at 321@url{http://www.fsf.org/doc/other-free-books.html}. 322 323@node Contributors 324@unnumberedsec Contributors to @value{GDBN} 325 326Richard Stallman was the original author of @value{GDBN}, and of many 327other @sc{gnu} programs. Many others have contributed to its 328development. This section attempts to credit major contributors. One 329of the virtues of free software is that everyone is free to contribute 330to it; with regret, we cannot actually acknowledge everyone here. The 331file @file{ChangeLog} in the @value{GDBN} distribution approximates a |
| 537blow-by-blow account. 538 539Changes much prior to version 2.0 are lost in the mists of time. 540 541@quotation 542@emph{Plea:} Additions to this section are particularly welcome. If you 543or your friends (or enemies, to be evenhanded) have been unfairly 544omitted from this list, we would like to add your names! 545@end quotation 546 547So that they may not regard their many labors as thankless, we 548particularly thank those who shepherded @value{GDBN} through major 549releases: | 332blow-by-blow account. 333 334Changes much prior to version 2.0 are lost in the mists of time. 335 336@quotation 337@emph{Plea:} Additions to this section are particularly welcome. If you 338or your friends (or enemies, to be evenhanded) have been unfairly 339omitted from this list, we would like to add your names! 340@end quotation 341 342So that they may not regard their many labors as thankless, we 343particularly thank those who shepherded @value{GDBN} through major 344releases: |
| 345Andrew Cagney (releases 5.0 and 5.1); |
|
| 550Jim Blandy (release 4.18); 551Jason Molenda (release 4.17); 552Stan Shebs (release 4.14); 553Fred Fish (releases 4.16, 4.15, 4.13, 4.12, 4.11, 4.10, and 4.9); 554Stu Grossman and John Gilmore (releases 4.8, 4.7, 4.6, 4.5, and 4.4); 555John Gilmore (releases 4.3, 4.2, 4.1, 4.0, and 3.9); 556Jim Kingdon (releases 3.5, 3.4, and 3.3); 557and Randy Smith (releases 3.2, 3.1, and 3.0). 558 559Richard Stallman, assisted at various times by Peter TerMaat, Chris 560Hanson, and Richard Mlynarik, handled releases through 2.8. 561 | 346Jim Blandy (release 4.18); 347Jason Molenda (release 4.17); 348Stan Shebs (release 4.14); 349Fred Fish (releases 4.16, 4.15, 4.13, 4.12, 4.11, 4.10, and 4.9); 350Stu Grossman and John Gilmore (releases 4.8, 4.7, 4.6, 4.5, and 4.4); 351John Gilmore (releases 4.3, 4.2, 4.1, 4.0, and 3.9); 352Jim Kingdon (releases 3.5, 3.4, and 3.3); 353and Randy Smith (releases 3.2, 3.1, and 3.0). 354 355Richard Stallman, assisted at various times by Peter TerMaat, Chris 356Hanson, and Richard Mlynarik, handled releases through 2.8. 357 |
| 562@ifclear CONLY 563Michael Tiemann is the author of most of the @sc{gnu} C++ support in GDB, 564with significant additional contributions from Per Bothner. James 565Clark wrote the @sc{gnu} C++ demangler. Early work on C++ was by Peter 566TerMaat (who also did much general update work leading to release 3.0). 567@end ifclear | 358Michael Tiemann is the author of most of the @sc{gnu} C@t{++} support 359in @value{GDBN}, with significant additional contributions from Per 360Bothner and Daniel Berlin. James Clark wrote the @sc{gnu} C@t{++} 361demangler. Early work on C@t{++} was by Peter TerMaat (who also did 362much general update work leading to release 3.0). |
| 568 | 363 |
| 569@value{GDBN} 4 uses the BFD subroutine library to examine multiple | 364@value{GDBN} uses the BFD subroutine library to examine multiple |
| 570object-file formats; BFD was a joint project of David V. 571Henkel-Wallace, Rich Pixley, Steve Chamberlain, and John Gilmore. 572 573David Johnson wrote the original COFF support; Pace Willison did 574the original support for encapsulated COFF. 575 | 365object-file formats; BFD was a joint project of David V. 366Henkel-Wallace, Rich Pixley, Steve Chamberlain, and John Gilmore. 367 368David Johnson wrote the original COFF support; Pace Willison did 369the original support for encapsulated COFF. 370 |
| 576Brent Benson of Harris Computer Systems contributed DWARF 2 support. | 371Brent Benson of Harris Computer Systems contributed DWARF2 support. |
| 577 578Adam de Boor and Bradley Davis contributed the ISI Optimum V support. 579Per Bothner, Noboyuki Hikichi, and Alessandro Forin contributed MIPS 580support. 581Jean-Daniel Fekete contributed Sun 386i support. 582Chris Hanson improved the HP9000 support. 583Noboyuki Hikichi and Tomoyuki Hasei contributed Sony/News OS 3 support. 584David Johnson contributed Encore Umax support. --- 20 unchanged lines hidden (view full) --- 605Patrick Duval, Ted Goldstein, Vikram Koka and Glenn Engel helped develop 606remote debugging. Intel Corporation, Wind River Systems, AMD, and ARM 607contributed remote debugging modules for the i960, VxWorks, A29K UDI, 608and RDI targets, respectively. 609 610Brian Fox is the author of the readline libraries providing 611command-line editing and command history. 612 | 372 373Adam de Boor and Bradley Davis contributed the ISI Optimum V support. 374Per Bothner, Noboyuki Hikichi, and Alessandro Forin contributed MIPS 375support. 376Jean-Daniel Fekete contributed Sun 386i support. 377Chris Hanson improved the HP9000 support. 378Noboyuki Hikichi and Tomoyuki Hasei contributed Sony/News OS 3 support. 379David Johnson contributed Encore Umax support. --- 20 unchanged lines hidden (view full) --- 400Patrick Duval, Ted Goldstein, Vikram Koka and Glenn Engel helped develop 401remote debugging. Intel Corporation, Wind River Systems, AMD, and ARM 402contributed remote debugging modules for the i960, VxWorks, A29K UDI, 403and RDI targets, respectively. 404 405Brian Fox is the author of the readline libraries providing 406command-line editing and command history. 407 |
| 613Andrew Beers of SUNY Buffalo wrote the language-switching code, 614@ifset MOD2 615the Modula-2 support, 616@end ifset 617and contributed the Languages chapter of this manual. | 408Andrew Beers of SUNY Buffalo wrote the language-switching code, the 409Modula-2 support, and contributed the Languages chapter of this manual. |
| 618 | 410 |
| 619Fred Fish wrote most of the support for Unix System Vr4. 620@ifclear CONLY 621He also enhanced the command-completion support to cover C++ overloaded | 411Fred Fish wrote most of the support for Unix System Vr4. 412He also enhanced the command-completion support to cover C@t{++} overloaded |
| 622symbols. | 413symbols. |
| 623@end ifclear | |
| 624 625Hitachi America, Ltd. sponsored the support for H8/300, H8/500, and 626Super-H processors. 627 628NEC sponsored the support for the v850, Vr4xxx, and Vr5xxx processors. 629 630Mitsubishi sponsored the support for D10V, D30V, and M32R/D processors. 631 632Toshiba sponsored the support for the TX39 Mips processor. 633 634Matsushita sponsored the support for the MN10200 and MN10300 processors. 635 | 414 415Hitachi America, Ltd. sponsored the support for H8/300, H8/500, and 416Super-H processors. 417 418NEC sponsored the support for the v850, Vr4xxx, and Vr5xxx processors. 419 420Mitsubishi sponsored the support for D10V, D30V, and M32R/D processors. 421 422Toshiba sponsored the support for the TX39 Mips processor. 423 424Matsushita sponsored the support for the MN10200 and MN10300 processors. 425 |
| 636Fujitsu sponsored the support for SPARClite and FR30 processors | 426Fujitsu sponsored the support for SPARClite and FR30 processors. |
| 637 638Kung Hsu, Jeff Law, and Rick Sladkey added support for hardware 639watchpoints. 640 641Michael Snyder added support for tracepoints. 642 643Stu Grossman wrote gdbserver. 644 645Jim Kingdon, Peter Schauer, Ian Taylor, and Stu Grossman made | 427 428Kung Hsu, Jeff Law, and Rick Sladkey added support for hardware 429watchpoints. 430 431Michael Snyder added support for tracepoints. 432 433Stu Grossman wrote gdbserver. 434 435Jim Kingdon, Peter Schauer, Ian Taylor, and Stu Grossman made |
| 646nearly innumerable bug fixes and cleanups throughout GDB. | 436nearly innumerable bug fixes and cleanups throughout @value{GDBN}. |
| 647 648The following people at the Hewlett-Packard Company contributed 649support for the PA-RISC 2.0 architecture, HP-UX 10.20, 10.30, and 11.0 | 437 438The following people at the Hewlett-Packard Company contributed 439support for the PA-RISC 2.0 architecture, HP-UX 10.20, 10.30, and 11.0 |
| 650(narrow mode), HP's implementation of kernel threads, HP's aC++ | 440(narrow mode), HP's implementation of kernel threads, HP's aC@t{++} |
| 651compiler, and the terminal user interface: Ben Krepp, Richard Title, 652John Bishop, Susan Macchia, Kathy Mann, Satish Pai, India Paul, Steve 653Rehrauer, and Elena Zannoni. Kim Haase provided HP-specific 654information in this manual. 655 | 441compiler, and the terminal user interface: Ben Krepp, Richard Title, 442John Bishop, Susan Macchia, Kathy Mann, Satish Pai, India Paul, Steve 443Rehrauer, and Elena Zannoni. Kim Haase provided HP-specific 444information in this manual. 445 |
| 656Cygnus Solutions has sponsored GDB maintenance and much of its 657development since 1991. Cygnus engineers who have worked on GDB 658fulltime include Mark Alexander, Jim Blandy, Per Bothner, Edith Epstein, 659Chris Faylor, Fred Fish, Martin Hunt, Jim Ingham, John Gilmore, Stu 660Grossman, Kung Hsu, Jim Kingdon, John Metzler, Fernando Nasser, Geoffrey 661Noer, Dawn Perchik, Rich Pixley, Zdenek Radouch, Keith Seitz, Stan 662Shebs, David Taylor, and Elena Zannoni. In addition, Dave Brolley, Ian 663Carmichael, Steve Chamberlain, Nick Clifton, JT Conklin, Stan Cox, DJ 664Delorie, Ulrich Drepper, Frank Eigler, Doug Evans, Sean Fagan, David 665Henkel-Wallace, Richard Henderson, Jeff Holcomb, Jeff Law, Jim Lemke, 666Tom Lord, Bob Manson, Michael Meissner, Jason Merrill, Catherine Moore, 667Drew Moseley, Ken Raeburn, Gavin Romig-Koch, Rob Savoye, Jamie Smith, 668Mike Stump, Ian Taylor, Angela Thomas, Michael Tiemann, Tom Tromey, Ron 669Unrau, Jim Wilson, and David Zuhn have made contributions both large 670and small. | 446DJ Delorie ported @value{GDBN} to MS-DOS, for the DJGPP project. 447Robert Hoehne made significant contributions to the DJGPP port. |
| 671 | 448 |
| 449Cygnus Solutions has sponsored @value{GDBN} maintenance and much of its 450development since 1991. Cygnus engineers who have worked on @value{GDBN} 451fulltime include Mark Alexander, Jim Blandy, Per Bothner, Kevin 452Buettner, Edith Epstein, Chris Faylor, Fred Fish, Martin Hunt, Jim 453Ingham, John Gilmore, Stu Grossman, Kung Hsu, Jim Kingdon, John Metzler, 454Fernando Nasser, Geoffrey Noer, Dawn Perchik, Rich Pixley, Zdenek 455Radouch, Keith Seitz, Stan Shebs, David Taylor, and Elena Zannoni. In 456addition, Dave Brolley, Ian Carmichael, Steve Chamberlain, Nick Clifton, 457JT Conklin, Stan Cox, DJ Delorie, Ulrich Drepper, Frank Eigler, Doug 458Evans, Sean Fagan, David Henkel-Wallace, Richard Henderson, Jeff 459Holcomb, Jeff Law, Jim Lemke, Tom Lord, Bob Manson, Michael Meissner, 460Jason Merrill, Catherine Moore, Drew Moseley, Ken Raeburn, Gavin 461Romig-Koch, Rob Savoye, Jamie Smith, Mike Stump, Ian Taylor, Angela 462Thomas, Michael Tiemann, Tom Tromey, Ron Unrau, Jim Wilson, and David 463Zuhn have made contributions both large and small. |
|
| 672 | 464 |
| 673@ifclear BARETARGET 674@node Sample Session, Invocation, Summary, Top | 465 466@node Sample Session |
| 675@chapter A Sample @value{GDBN} Session 676 677You can use this manual at your leisure to read all about @value{GDBN}. 678However, a handful of commands are enough to get started using the 679debugger. This chapter illustrates those commands. 680 681@iftex 682In this sample session, we emphasize user input like this: @b{input}, --- 30 unchanged lines hidden (view full) --- 713@b{baz} 714@b{C-d} 715m4: End of input: 0: fatal error: EOF in string 716@end smallexample 717 718@noindent 719Let us use @value{GDBN} to try to see what is going on. 720 | 467@chapter A Sample @value{GDBN} Session 468 469You can use this manual at your leisure to read all about @value{GDBN}. 470However, a handful of commands are enough to get started using the 471debugger. This chapter illustrates those commands. 472 473@iftex 474In this sample session, we emphasize user input like this: @b{input}, --- 30 unchanged lines hidden (view full) --- 505@b{baz} 506@b{C-d} 507m4: End of input: 0: fatal error: EOF in string 508@end smallexample 509 510@noindent 511Let us use @value{GDBN} to try to see what is going on. 512 |
| 721@ifclear HPPA | |
| 722@smallexample 723$ @b{@value{GDBP} m4} 724@c FIXME: this falsifies the exact text played out, to permit smallbook 725@c FIXME... format to come out better. 726@value{GDBN} is free software and you are welcome to distribute copies | 513@smallexample 514$ @b{@value{GDBP} m4} 515@c FIXME: this falsifies the exact text played out, to permit smallbook 516@c FIXME... format to come out better. 517@value{GDBN} is free software and you are welcome to distribute copies |
| 727 of it under certain conditions; type "show copying" to see | 518 of it under certain conditions; type "show copying" to see |
| 728 the conditions. | 519 the conditions. |
| 729There is absolutely no warranty for @value{GDBN}; type "show warranty" | 520There is absolutely no warranty for @value{GDBN}; type "show warranty" |
| 730 for details. 731 732@value{GDBN} @value{GDBVN}, Copyright 1999 Free Software Foundation, Inc... 733(@value{GDBP}) 734@end smallexample | 521 for details. 522 523@value{GDBN} @value{GDBVN}, Copyright 1999 Free Software Foundation, Inc... 524(@value{GDBP}) 525@end smallexample |
| 735@end ifclear 736@ifset HPPA 737@smallexample 738$ @b{@value{GDBP} m4} 739Wildebeest is free software and you are welcome to distribute copies of 740it under certain conditions; type "show copying" to see the conditions. 741There is absolutely no warranty for Wildebeest; type "show warranty" 742for details. | |
| 743 | 526 |
| 744Hewlett-Packard Wildebeest 0.75 (based on GDB 4.16) 745(built for PA-RISC 1.1 or 2.0, HP-UX 10.20) 746Copyright 1996, 1997 Free Software Foundation, Inc. 747(@value{GDBP}) 748@end smallexample 749@end ifset 750 | |
| 751@noindent 752@value{GDBN} reads only enough symbol data to know where to find the 753rest when needed; as a result, the first prompt comes up very quickly. 754We now tell @value{GDBN} to use a narrower display width than usual, so 755that examples fit in this manual. 756 757@smallexample 758(@value{GDBP}) @b{set width 70} --- 27 unchanged lines hidden (view full) --- 786@noindent 787To trigger the breakpoint, we call @code{changequote}. @value{GDBN} 788suspends execution of @code{m4}, displaying information about the 789context where it stops. 790 791@smallexample 792@b{changequote(<QUOTE>,<UNQUOTE>)} 793 | 527@noindent 528@value{GDBN} reads only enough symbol data to know where to find the 529rest when needed; as a result, the first prompt comes up very quickly. 530We now tell @value{GDBN} to use a narrower display width than usual, so 531that examples fit in this manual. 532 533@smallexample 534(@value{GDBP}) @b{set width 70} --- 27 unchanged lines hidden (view full) --- 562@noindent 563To trigger the breakpoint, we call @code{changequote}. @value{GDBN} 564suspends execution of @code{m4}, displaying information about the 565context where it stops. 566 567@smallexample 568@b{changequote(<QUOTE>,<UNQUOTE>)} 569 |
| 794Breakpoint 1, m4_changequote (argc=3, argv=0x33c70) | 570Breakpoint 1, m4_changequote (argc=3, argv=0x33c70) |
| 795 at builtin.c:879 796879 if (bad_argc(TOKEN_DATA_TEXT(argv[0]),argc,1,3)) 797@end smallexample 798 799@noindent 800Now we use the command @code{n} (@code{next}) to advance execution to 801the next line of the current function. 802 --- 23 unchanged lines hidden (view full) --- 826command (which can also be spelled @code{bt}), to see where we are 827in the stack as a whole: the @code{backtrace} command displays a 828stack frame for each active subroutine. 829 830@smallexample 831(@value{GDBP}) @b{bt} 832#0 set_quotes (lq=0x34c78 "<QUOTE>", rq=0x34c88 "<UNQUOTE>") 833 at input.c:530 | 571 at builtin.c:879 572879 if (bad_argc(TOKEN_DATA_TEXT(argv[0]),argc,1,3)) 573@end smallexample 574 575@noindent 576Now we use the command @code{n} (@code{next}) to advance execution to 577the next line of the current function. 578 --- 23 unchanged lines hidden (view full) --- 602command (which can also be spelled @code{bt}), to see where we are 603in the stack as a whole: the @code{backtrace} command displays a 604stack frame for each active subroutine. 605 606@smallexample 607(@value{GDBP}) @b{bt} 608#0 set_quotes (lq=0x34c78 "<QUOTE>", rq=0x34c88 "<UNQUOTE>") 609 at input.c:530 |
| 834#1 0x6344 in m4_changequote (argc=3, argv=0x33c70) | 610#1 0x6344 in m4_changequote (argc=3, argv=0x33c70) |
| 835 at builtin.c:882 836#2 0x8174 in expand_macro (sym=0x33320) at macro.c:242 837#3 0x7a88 in expand_token (obs=0x0, t=209696, td=0xf7fffa30) 838 at macro.c:71 839#4 0x79dc in expand_input () at macro.c:40 840#5 0x2930 in main (argc=0, argv=0xf7fffb20) at m4.c:195 841@end smallexample 842 --- 108 unchanged lines hidden (view full) --- 951@noindent 952The message @samp{Program exited normally.} is from @value{GDBN}; it 953indicates @code{m4} has finished executing. We can end our @value{GDBN} 954session with the @value{GDBN} @code{quit} command. 955 956@smallexample 957(@value{GDBP}) @b{quit} 958@end smallexample | 611 at builtin.c:882 612#2 0x8174 in expand_macro (sym=0x33320) at macro.c:242 613#3 0x7a88 in expand_token (obs=0x0, t=209696, td=0xf7fffa30) 614 at macro.c:71 615#4 0x79dc in expand_input () at macro.c:40 616#5 0x2930 in main (argc=0, argv=0xf7fffb20) at m4.c:195 617@end smallexample 618 --- 108 unchanged lines hidden (view full) --- 727@noindent 728The message @samp{Program exited normally.} is from @value{GDBN}; it 729indicates @code{m4} has finished executing. We can end our @value{GDBN} 730session with the @value{GDBN} @code{quit} command. 731 732@smallexample 733(@value{GDBP}) @b{quit} 734@end smallexample |
| 959@end ifclear | |
| 960 | 735 |
| 961@node Invocation, Commands, Sample Session, Top | 736@node Invocation |
| 962@chapter Getting In and Out of @value{GDBN} 963 964This chapter discusses how to start @value{GDBN}, and how to get out of it. | 737@chapter Getting In and Out of @value{GDBN} 738 739This chapter discusses how to start @value{GDBN}, and how to get out of it. |
| 965The essentials are: | 740The essentials are: |
| 966@itemize @bullet | 741@itemize @bullet |
| 967@item 968type @samp{@value{GDBP}} to start GDB. 969@item | 742@item 743type @samp{@value{GDBP}} to start @value{GDBN}. 744@item |
| 970type @kbd{quit} or @kbd{C-d} to exit. 971@end itemize 972 973@menu 974* Invoking GDB:: How to start @value{GDBN} 975* Quitting GDB:: How to quit @value{GDBN} 976* Shell Commands:: How to use shell commands inside @value{GDBN} 977@end menu 978 | 745type @kbd{quit} or @kbd{C-d} to exit. 746@end itemize 747 748@menu 749* Invoking GDB:: How to start @value{GDBN} 750* Quitting GDB:: How to quit @value{GDBN} 751* Shell Commands:: How to use shell commands inside @value{GDBN} 752@end menu 753 |
| 979@node Invoking GDB, Quitting GDB, Invocation, Invocation | 754@node Invoking GDB |
| 980@section Invoking @value{GDBN} 981 | 755@section Invoking @value{GDBN} 756 |
| 982@ifset H8EXCLUSIVE 983For details on starting up @value{GDBP} as a 984remote debugger attached to a Hitachi microprocessor, see @ref{Hitachi 985Remote,,@value{GDBN} and Hitachi Microprocessors}. 986@end ifset 987 | |
| 988Invoke @value{GDBN} by running the program @code{@value{GDBP}}. Once started, 989@value{GDBN} reads commands from the terminal until you tell it to exit. 990 991You can also run @code{@value{GDBP}} with a variety of arguments and options, 992to specify more of your debugging environment at the outset. 993 | 757Invoke @value{GDBN} by running the program @code{@value{GDBP}}. Once started, 758@value{GDBN} reads commands from the terminal until you tell it to exit. 759 760You can also run @code{@value{GDBP}} with a variety of arguments and options, 761to specify more of your debugging environment at the outset. 762 |
| 994@ifset GENERIC | |
| 995The command-line options described here are designed 996to cover a variety of situations; in some environments, some of these | 763The command-line options described here are designed 764to cover a variety of situations; in some environments, some of these |
| 997options may effectively be unavailable. 998@end ifset | 765options may effectively be unavailable. |
| 999 1000The most usual way to start @value{GDBN} is with one argument, 1001specifying an executable program: 1002 1003@example 1004@value{GDBP} @var{program} 1005@end example 1006 | 766 767The most usual way to start @value{GDBN} is with one argument, 768specifying an executable program: 769 770@example 771@value{GDBP} @var{program} 772@end example 773 |
| 1007@ifclear BARETARGET | |
| 1008@noindent 1009You can also start with both an executable program and a core file 1010specified: 1011 1012@example 1013@value{GDBP} @var{program} @var{core} 1014@end example 1015 1016You can, instead, specify a process ID as a second argument, if you want 1017to debug a running process: 1018 1019@example 1020@value{GDBP} @var{program} 1234 1021@end example 1022 1023@noindent 1024would attach @value{GDBN} to process @code{1234} (unless you also have a file 1025named @file{1234}; @value{GDBN} does check for a core file first). 1026 | 774@noindent 775You can also start with both an executable program and a core file 776specified: 777 778@example 779@value{GDBP} @var{program} @var{core} 780@end example 781 782You can, instead, specify a process ID as a second argument, if you want 783to debug a running process: 784 785@example 786@value{GDBP} @var{program} 1234 787@end example 788 789@noindent 790would attach @value{GDBN} to process @code{1234} (unless you also have a file 791named @file{1234}; @value{GDBN} does check for a core file first). 792 |
| 1027@ifclear HPPA | |
| 1028Taking advantage of the second command-line argument requires a fairly | 793Taking advantage of the second command-line argument requires a fairly |
| 1029complete operating system; when you use @value{GDBN} as a remote debugger 1030attached to a bare board, there may not be any notion of ``process'', 1031and there is often no way to get a core dump. 1032@end ifclear 1033@end ifclear | 794complete operating system; when you use @value{GDBN} as a remote 795debugger attached to a bare board, there may not be any notion of 796``process'', and there is often no way to get a core dump. @value{GDBN} 797will warn you if it is unable to attach or to read core dumps. |
| 1034 | 798 |
| 1035You can run @code{gdb} without printing the front material, which describes | 799You can optionally have @code{@value{GDBP}} pass any arguments after the 800executable file to the inferior using @code{--args}. This option stops 801option processing. 802@example 803gdb --args gcc -O2 -c foo.c 804@end example 805This will cause @code{@value{GDBP}} to debug @code{gcc}, and to set 806@code{gcc}'s command-line arguments (@pxref{Arguments}) to @samp{-O2 -c foo.c}. 807 808You can run @code{@value{GDBP}} without printing the front material, which describes |
| 1036@value{GDBN}'s non-warranty, by specifying @code{-silent}: 1037 1038@smallexample 1039@value{GDBP} -silent 1040@end smallexample 1041 1042@noindent 1043You can further control how @value{GDBN} starts up by using command-line --- 11 unchanged lines hidden (view full) --- 1055(@samp{@value{GDBP} -h} is a shorter equivalent). 1056 1057All options and command line arguments you give are processed 1058in sequential order. The order makes a difference when the 1059@samp{-x} option is used. 1060 1061 1062@menu | 809@value{GDBN}'s non-warranty, by specifying @code{-silent}: 810 811@smallexample 812@value{GDBP} -silent 813@end smallexample 814 815@noindent 816You can further control how @value{GDBN} starts up by using command-line --- 11 unchanged lines hidden (view full) --- 828(@samp{@value{GDBP} -h} is a shorter equivalent). 829 830All options and command line arguments you give are processed 831in sequential order. The order makes a difference when the 832@samp{-x} option is used. 833 834 835@menu |
| 1063@ifclear GENERIC 1064@ifset REMOTESTUB 1065* Remote Serial:: @value{GDBN} remote serial protocol 1066@end ifset 1067@ifset I960 1068* i960-Nindy Remote:: @value{GDBN} with a remote i960 (Nindy) 1069@end ifset 1070@ifset AMD29K 1071* UDI29K Remote:: The UDI protocol for AMD29K 1072* EB29K Remote:: The EBMON protocol for AMD29K 1073@end ifset 1074@ifset VXWORKS 1075* VxWorks Remote:: @value{GDBN} and VxWorks 1076@end ifset 1077@ifset ST2000 1078* ST2000 Remote:: @value{GDBN} with a Tandem ST2000 1079@end ifset 1080@ifset H8 1081* Hitachi Remote:: @value{GDBN} and Hitachi Microprocessors 1082@end ifset 1083@ifset MIPS 1084* MIPS Remote:: @value{GDBN} and MIPS boards 1085@end ifset 1086@ifset SPARCLET 1087* Sparclet Remote:: @value{GDBN} and Sparclet boards 1088@end ifset 1089@ifset SIMS 1090* Simulator:: Simulated CPU target 1091@end ifset 1092@end ifclear 1093@c remnant makeinfo bug requires this blank line after *two* end-ifblahs: 1094 | |
| 1095* File Options:: Choosing files 1096* Mode Options:: Choosing modes 1097@end menu 1098 | 836* File Options:: Choosing files 837* Mode Options:: Choosing modes 838@end menu 839 |
| 1099@ifclear GENERIC 1100@ifclear HPPA 1101@include remote.texi 1102@end ifclear 1103@end ifclear 1104 | |
| 1105@node File Options 1106@subsection Choosing files 1107 | 840@node File Options 841@subsection Choosing files 842 |
| 1108@ifclear BARETARGET | |
| 1109When @value{GDBN} starts, it reads any arguments other than options as 1110specifying an executable file and core file (or process ID). This is 1111the same as if the arguments were specified by the @samp{-se} and | 843When @value{GDBN} starts, it reads any arguments other than options as 844specifying an executable file and core file (or process ID). This is 845the same as if the arguments were specified by the @samp{-se} and |
| 1112@samp{-c} options respectively. (@value{GDBN} reads the first argument 1113that does not have an associated option flag as equivalent to the 1114@samp{-se} option followed by that argument; and the second argument 1115that does not have an associated option flag, if any, as equivalent to 1116the @samp{-c} option followed by that argument.) 1117@end ifclear 1118@ifset BARETARGET 1119When @value{GDBN} starts, it reads any argument other than options as 1120specifying an executable file. This is the same as if the argument was 1121specified by the @samp{-se} option. 1122@end ifset | 846@samp{-c} (or @samp{-p} options respectively. (@value{GDBN} reads the 847first argument that does not have an associated option flag as 848equivalent to the @samp{-se} option followed by that argument; and the 849second argument that does not have an associated option flag, if any, as 850equivalent to the @samp{-c}/@samp{-p} option followed by that argument.) 851If the second argument begins with a decimal digit, @value{GDBN} will 852first attempt to attach to it as a process, and if that fails, attempt 853to open it as a corefile. If you have a corefile whose name begins with 854a digit, you can prevent @value{GDBN} from treating it as a pid by 855prefixing it with @file{./}, eg. @file{./12345}. |
| 1123 | 856 |
| 857If @value{GDBN} has not been configured to included core file support, 858such as for most embedded targets, then it will complain about a second 859argument and ignore it. 860 |
|
| 1124Many options have both long and short forms; both are shown in the 1125following list. @value{GDBN} also recognizes the long forms if you truncate 1126them, so long as enough of the option is present to be unambiguous. 1127(If you prefer, you can flag option arguments with @samp{--} rather 1128than @samp{-}, though we illustrate the more usual convention.) 1129 | 861Many options have both long and short forms; both are shown in the 862following list. @value{GDBN} also recognizes the long forms if you truncate 863them, so long as enough of the option is present to be unambiguous. 864(If you prefer, you can flag option arguments with @samp{--} rather 865than @samp{-}, though we illustrate the more usual convention.) 866 |
| 867@c NOTE: the @cindex entries here use double dashes ON PURPOSE. This 868@c way, both those who look for -foo and --foo in the index, will find 869@c it. 870 |
|
| 1130@table @code 1131@item -symbols @var{file} 1132@itemx -s @var{file} | 871@table @code 872@item -symbols @var{file} 873@itemx -s @var{file} |
| 874@cindex @code{--symbols} 875@cindex @code{-s} |
|
| 1133Read symbol table from file @var{file}. 1134 1135@item -exec @var{file} 1136@itemx -e @var{file} | 876Read symbol table from file @var{file}. 877 878@item -exec @var{file} 879@itemx -e @var{file} |
| 1137Use file @var{file} as the executable file to execute when 1138@ifset BARETARGET 1139appropriate. 1140@end ifset 1141@ifclear BARETARGET 1142appropriate, and for examining pure data in conjunction with a core 1143dump. 1144@end ifclear | 880@cindex @code{--exec} 881@cindex @code{-e} 882Use file @var{file} as the executable file to execute when appropriate, 883and for examining pure data in conjunction with a core dump. |
| 1145 1146@item -se @var{file} | 884 885@item -se @var{file} |
| 886@cindex @code{--se} |
|
| 1147Read symbol table from file @var{file} and use it as the executable 1148file. 1149 | 887Read symbol table from file @var{file} and use it as the executable 888file. 889 |
| 1150@ifclear BARETARGET | |
| 1151@item -core @var{file} 1152@itemx -c @var{file} | 890@item -core @var{file} 891@itemx -c @var{file} |
| 1153Use file @var{file} as a core dump to examine. | 892@cindex @code{--core} 893@cindex @code{-c} 894Use file @var{file} as a core dump to examine. |
| 1154 1155@item -c @var{number} | 895 896@item -c @var{number} |
| 1156Connect to process ID @var{number}, as with the @code{attach} command 1157(unless there is a file in core-dump format named @var{number}, in which 1158case @samp{-c} specifies that file as a core dump to read). 1159@end ifclear | 897@item -pid @var{number} 898@itemx -p @var{number} 899@cindex @code{--pid} 900@cindex @code{-p} 901Connect to process ID @var{number}, as with the @code{attach} command. 902If there is no such process, @value{GDBN} will attempt to open a core 903file named @var{number}. |
| 1160 1161@item -command @var{file} 1162@itemx -x @var{file} | 904 905@item -command @var{file} 906@itemx -x @var{file} |
| 907@cindex @code{--command} 908@cindex @code{-x} |
|
| 1163Execute @value{GDBN} commands from file @var{file}. @xref{Command 1164Files,, Command files}. 1165 1166@item -directory @var{directory} 1167@itemx -d @var{directory} | 909Execute @value{GDBN} commands from file @var{file}. @xref{Command 910Files,, Command files}. 911 912@item -directory @var{directory} 913@itemx -d @var{directory} |
| 914@cindex @code{--directory} 915@cindex @code{-d} |
|
| 1168Add @var{directory} to the path to search for source files. 1169 | 916Add @var{directory} to the path to search for source files. 917 |
| 1170@ifclear BARETARGET 1171@ifclear HPPA | |
| 1172@item -m 1173@itemx -mapped | 918@item -m 919@itemx -mapped |
| 920@cindex @code{--mapped} 921@cindex @code{-m} |
|
| 1174@emph{Warning: this option depends on operating system facilities that are not 1175supported on all systems.}@* 1176If memory-mapped files are available on your system through the @code{mmap} | 922@emph{Warning: this option depends on operating system facilities that are not 923supported on all systems.}@* 924If memory-mapped files are available on your system through the @code{mmap} |
| 1177system call, you can use this option | 925system call, you can use this option |
| 1178to have @value{GDBN} write the symbols from your 1179program into a reusable file in the current directory. If the program you are debugging is | 926to have @value{GDBN} write the symbols from your 927program into a reusable file in the current directory. If the program you are debugging is |
| 1180called @file{/tmp/fred}, the mapped symbol file is @file{./fred.syms}. | 928called @file{/tmp/fred}, the mapped symbol file is @file{/tmp/fred.syms}. |
| 1181Future @value{GDBN} debugging sessions notice the presence of this file, 1182and can quickly map in symbol information from it, rather than reading 1183the symbol table from the executable program. 1184 1185The @file{.syms} file is specific to the host machine where @value{GDBN} 1186is run. It holds an exact image of the internal @value{GDBN} symbol 1187table. It cannot be shared across multiple host platforms. | 929Future @value{GDBN} debugging sessions notice the presence of this file, 930and can quickly map in symbol information from it, rather than reading 931the symbol table from the executable program. 932 933The @file{.syms} file is specific to the host machine where @value{GDBN} 934is run. It holds an exact image of the internal @value{GDBN} symbol 935table. It cannot be shared across multiple host platforms. |
| 1188@end ifclear 1189@end ifclear | |
| 1190 | 936 |
| 1191@ifclear HPPA | |
| 1192@item -r 1193@itemx -readnow | 937@item -r 938@itemx -readnow |
| 939@cindex @code{--readnow} 940@cindex @code{-r} |
|
| 1194Read each symbol file's entire symbol table immediately, rather than 1195the default, which is to read it incrementally as it is needed. 1196This makes startup slower, but makes future operations faster. | 941Read each symbol file's entire symbol table immediately, rather than 942the default, which is to read it incrementally as it is needed. 943This makes startup slower, but makes future operations faster. |
| 1197@end ifclear | 944 |
| 1198@end table 1199 | 945@end table 946 |
| 1200@ifclear BARETARGET 1201@ifclear HPPA 1202The @code{-mapped} and @code{-readnow} options are typically combined in | 947You typically combine the @code{-mapped} and @code{-readnow} options in |
| 1203order to build a @file{.syms} file that contains complete symbol | 948order to build a @file{.syms} file that contains complete symbol |
| 1204information. (@xref{Files,,Commands to specify files}, for 1205information on @file{.syms} files.) A simple GDB invocation to do 1206nothing but build a @file{.syms} file for future use is: | 949information. (@xref{Files,,Commands to specify files}, for information 950on @file{.syms} files.) A simple @value{GDBN} invocation to do nothing 951but build a @file{.syms} file for future use is: |
| 1207 1208@example | 952 953@example |
| 1209 gdb -batch -nx -mapped -readnow programname | 954gdb -batch -nx -mapped -readnow programname |
| 1210@end example | 955@end example |
| 1211@end ifclear 1212@end ifclear | |
| 1213 | 956 |
| 1214@node Mode Options, , File Options, Invoking GDB | 957@node Mode Options |
| 1215@subsection Choosing modes 1216 1217You can run @value{GDBN} in various alternative modes---for example, in 1218batch mode or quiet mode. 1219 1220@table @code 1221@item -nx 1222@itemx -n | 958@subsection Choosing modes 959 960You can run @value{GDBN} in various alternative modes---for example, in 961batch mode or quiet mode. 962 963@table @code 964@item -nx 965@itemx -n |
| 1223Do not execute commands from any initialization files (normally called 1224@file{.gdbinit}, or @file{gdb.ini} on PCs). Normally, the commands in 1225these files are executed after all the command options and arguments 1226have been processed. @xref{Command Files,,Command files}. | 966@cindex @code{--nx} 967@cindex @code{-n} 968Do not execute commands found in any initialization files. Normally, 969@value{GDBN} executes the commands in these files after all the command 970options and arguments have been processed. @xref{Command Files,,Command 971files}. |
| 1227 1228@item -quiet | 972 973@item -quiet |
| 974@itemx -silent |
|
| 1229@itemx -q | 975@itemx -q |
| 976@cindex @code{--quiet} 977@cindex @code{--silent} 978@cindex @code{-q} |
|
| 1230``Quiet''. Do not print the introductory and copyright messages. These 1231messages are also suppressed in batch mode. 1232 1233@item -batch | 979``Quiet''. Do not print the introductory and copyright messages. These 980messages are also suppressed in batch mode. 981 982@item -batch |
| 983@cindex @code{--batch} |
|
| 1234Run in batch mode. Exit with status @code{0} after processing all the 1235command files specified with @samp{-x} (and all commands from 1236initialization files, if not inhibited with @samp{-n}). Exit with 1237nonzero status if an error occurs in executing the @value{GDBN} commands 1238in the command files. 1239 | 984Run in batch mode. Exit with status @code{0} after processing all the 985command files specified with @samp{-x} (and all commands from 986initialization files, if not inhibited with @samp{-n}). Exit with 987nonzero status if an error occurs in executing the @value{GDBN} commands 988in the command files. 989 |
| 1240Batch mode may be useful for running @value{GDBN} as a filter, for example to 1241download and run a program on another computer; in order to make this 1242more useful, the message | 990Batch mode may be useful for running @value{GDBN} as a filter, for 991example to download and run a program on another computer; in order to 992make this more useful, the message |
| 1243 1244@example 1245Program exited normally. 1246@end example 1247 1248@noindent | 993 994@example 995Program exited normally. 996@end example 997 998@noindent |
| 1249(which is ordinarily issued whenever a program running under @value{GDBN} control 1250terminates) is not issued when running in batch mode. | 999(which is ordinarily issued whenever a program running under 1000@value{GDBN} control terminates) is not issued when running in batch 1001mode. |
| 1251 | 1002 |
| 1003@item -nowindows 1004@itemx -nw 1005@cindex @code{--nowindows} 1006@cindex @code{-nw} 1007``No windows''. If @value{GDBN} comes with a graphical user interface 1008(GUI) built in, then this option tells @value{GDBN} to only use the command-line 1009interface. If no GUI is available, this option has no effect. 1010 1011@item -windows 1012@itemx -w 1013@cindex @code{--windows} 1014@cindex @code{-w} 1015If @value{GDBN} includes a GUI, then this option requires it to be 1016used if possible. 1017 |
|
| 1252@item -cd @var{directory} | 1018@item -cd @var{directory} |
| 1019@cindex @code{--cd} |
|
| 1253Run @value{GDBN} using @var{directory} as its working directory, 1254instead of the current directory. 1255 | 1020Run @value{GDBN} using @var{directory} as its working directory, 1021instead of the current directory. 1022 |
| 1256@ifclear DOSHOST | |
| 1257@item -fullname 1258@itemx -f | 1023@item -fullname 1024@itemx -f |
| 1259@sc{gnu} Emacs sets this option when it runs @value{GDBN} as a subprocess. It tells @value{GDBN} 1260to output the full file name and line number in a standard, 1261recognizable fashion each time a stack frame is displayed (which 1262includes each time your program stops). This recognizable format looks 1263like two @samp{\032} characters, followed by the file name, line number 1264and character position separated by colons, and a newline. The 1265Emacs-to-@value{GDBN} interface program uses the two @samp{\032} characters as 1266a signal to display the source code for the frame. 1267@end ifclear | 1025@cindex @code{--fullname} 1026@cindex @code{-f} 1027@sc{gnu} Emacs sets this option when it runs @value{GDBN} as a 1028subprocess. It tells @value{GDBN} to output the full file name and line 1029number in a standard, recognizable fashion each time a stack frame is 1030displayed (which includes each time your program stops). This 1031recognizable format looks like two @samp{\032} characters, followed by 1032the file name, line number and character position separated by colons, 1033and a newline. The Emacs-to-@value{GDBN} interface program uses the two 1034@samp{\032} characters as a signal to display the source code for the 1035frame. |
| 1268 | 1036 |
| 1269@ifset SERIAL 1270@ifclear HPPA 1271@item -b @var{bps} | 1037@item -epoch 1038@cindex @code{--epoch} 1039The Epoch Emacs-@value{GDBN} interface sets this option when it runs 1040@value{GDBN} as a subprocess. It tells @value{GDBN} to modify its print 1041routines so as to allow Epoch to display values of expressions in a 1042separate window. 1043 1044@item -annotate @var{level} 1045@cindex @code{--annotate} 1046This option sets the @dfn{annotation level} inside @value{GDBN}. Its 1047effect is identical to using @samp{set annotate @var{level}} 1048(@pxref{Annotations}). 1049Annotation level controls how much information does @value{GDBN} print 1050together with its prompt, values of expressions, source lines, and other 1051types of output. Level 0 is the normal, level 1 is for use when 1052@value{GDBN} is run as a subprocess of @sc{gnu} Emacs, level 2 is the 1053maximum annotation suitable for programs that control @value{GDBN}. 1054 1055@item -async 1056@cindex @code{--async} 1057Use the asynchronous event loop for the command-line interface. 1058@value{GDBN} processes all events, such as user keyboard input, via a 1059special event loop. This allows @value{GDBN} to accept and process user 1060commands in parallel with the debugged process being 1061run@footnote{@value{GDBN} built with @sc{djgpp} tools for 1062MS-DOS/MS-Windows supports this mode of operation, but the event loop is 1063suspended when the debuggee runs.}, so you don't need to wait for 1064control to return to @value{GDBN} before you type the next command. 1065(@emph{Note:} as of version 5.1, the target side of the asynchronous 1066operation is not yet in place, so @samp{-async} does not work fully 1067yet.) 1068@c FIXME: when the target side of the event loop is done, the above NOTE 1069@c should be removed. 1070 1071When the standard input is connected to a terminal device, @value{GDBN} 1072uses the asynchronous event loop by default, unless disabled by the 1073@samp{-noasync} option. 1074 1075@item -noasync 1076@cindex @code{--noasync} 1077Disable the asynchronous event loop for the command-line interface. 1078 1079@item --args 1080@cindex @code{--args} 1081Change interpretation of command line so that arguments following the 1082executable file are passed as command line arguments to the inferior. 1083This option stops option processing. 1084 1085@item -baud @var{bps} 1086@itemx -b @var{bps} 1087@cindex @code{--baud} 1088@cindex @code{-b} |
| 1272Set the line speed (baud rate or bits per second) of any serial 1273interface used by @value{GDBN} for remote debugging. | 1089Set the line speed (baud rate or bits per second) of any serial 1090interface used by @value{GDBN} for remote debugging. |
| 1274@end ifclear | |
| 1275 1276@item -tty @var{device} | 1091 1092@item -tty @var{device} |
| 1093@itemx -t @var{device} 1094@cindex @code{--tty} 1095@cindex @code{-t} |
|
| 1277Run using @var{device} for your program's standard input and output. 1278@c FIXME: kingdon thinks there is more to -tty. Investigate. | 1096Run using @var{device} for your program's standard input and output. 1097@c FIXME: kingdon thinks there is more to -tty. Investigate. |
| 1279@end ifset | |
| 1280 | 1098 |
| 1281@ifset HPPA | 1099@c resolve the situation of these eventually |
| 1282@item -tui | 1100@item -tui |
| 1283Use a Terminal User Interface. For information, use your Web browser to 1284read the file @file{TUI.html}, which is usually installed in the 1285directory @code{/opt/langtools/wdb/doc} on HP-UX systems. Do not use 1286this option if you run @value{GDBN} from Emacs (see @pxref{Emacs, ,Using 1287@value{GDBN} under @sc{gnu} Emacs}). | 1101@cindex @code{--tui} 1102Activate the Terminal User Interface when starting. 1103The Terminal User Interface manages several text windows on the terminal, 1104showing source, assembly, registers and @value{GDBN} command outputs 1105(@pxref{TUI, ,@value{GDBN} Text User Interface}). 1106Do not use this option if you run @value{GDBN} from Emacs 1107(@pxref{Emacs, ,Using @value{GDBN} under @sc{gnu} Emacs}). |
| 1288 | 1108 |
| 1289@item -xdb 1290Run in XDB compatibility mode, allowing the use of certain XDB commands. 1291For information, see the file @file{xdb_trans.html}, which is usually 1292installed in the directory @code{/opt/langtools/wdb/doc} on HP-UX 1293systems. 1294@end ifset | 1109@c @item -xdb 1110@c @cindex @code{--xdb} 1111@c Run in XDB compatibility mode, allowing the use of certain XDB commands. 1112@c For information, see the file @file{xdb_trans.html}, which is usually 1113@c installed in the directory @code{/opt/langtools/wdb/doc} on HP-UX 1114@c systems. 1115 1116@item -interpreter @var{interp} 1117@cindex @code{--interpreter} 1118Use the interpreter @var{interp} for interface with the controlling 1119program or device. This option is meant to be set by programs which 1120communicate with @value{GDBN} using it as a back end. 1121 1122@samp{--interpreter=mi} (or @samp{--interpreter=mi1}) causes 1123@value{GDBN} to use the @dfn{gdb/mi interface} (@pxref{GDB/MI, , The 1124@sc{gdb/mi} Interface}). The older @sc{gdb/mi} interface, included in 1125@value{GDBN} version 5.0 can be selected with @samp{--interpreter=mi0}. 1126 1127@item -write 1128@cindex @code{--write} 1129Open the executable and core files for both reading and writing. This 1130is equivalent to the @samp{set write on} command inside @value{GDBN} 1131(@pxref{Patching}). 1132 1133@item -statistics 1134@cindex @code{--statistics} 1135This option causes @value{GDBN} to print statistics about time and 1136memory usage after it completes each command and returns to the prompt. 1137 1138@item -version 1139@cindex @code{--version} 1140This option causes @value{GDBN} to print its version number and 1141no-warranty blurb, and exit. 1142 |
| 1295@end table 1296 | 1143@end table 1144 |
| 1297@node Quitting GDB, Shell Commands, Invoking GDB, Invocation | 1145@node Quitting GDB |
| 1298@section Quitting @value{GDBN} 1299@cindex exiting @value{GDBN} 1300@cindex leaving @value{GDBN} 1301 1302@table @code 1303@kindex quit @r{[}@var{expression}@r{]} | 1146@section Quitting @value{GDBN} 1147@cindex exiting @value{GDBN} 1148@cindex leaving @value{GDBN} 1149 1150@table @code 1151@kindex quit @r{[}@var{expression}@r{]} |
| 1304@kindex q 1305@item quit 1306To exit @value{GDBN}, use the @code{quit} command (abbreviated @code{q}), or 1307type an end-of-file character (usually @kbd{C-d}). If you do not supply 1308@var{expression}, @value{GDBN} will terminate normally; otherwise it will 1309terminate using the result of @var{expression} as the error code. | 1152@kindex q @r{(@code{quit})} 1153@item quit @r{[}@var{expression}@r{]} 1154@itemx q 1155To exit @value{GDBN}, use the @code{quit} command (abbreviated 1156@code{q}), or type an end-of-file character (usually @kbd{C-d}). If you 1157do not supply @var{expression}, @value{GDBN} will terminate normally; 1158otherwise it will terminate using the result of @var{expression} as the 1159error code. |
| 1310@end table 1311 1312@cindex interrupt 1313An interrupt (often @kbd{C-c}) does not exit from @value{GDBN}, but rather 1314terminates the action of any @value{GDBN} command that is in progress and 1315returns to @value{GDBN} command level. It is safe to type the interrupt 1316character at any time because @value{GDBN} does not allow it to take effect 1317until a time when it is safe. 1318 | 1160@end table 1161 1162@cindex interrupt 1163An interrupt (often @kbd{C-c}) does not exit from @value{GDBN}, but rather 1164terminates the action of any @value{GDBN} command that is in progress and 1165returns to @value{GDBN} command level. It is safe to type the interrupt 1166character at any time because @value{GDBN} does not allow it to take effect 1167until a time when it is safe. 1168 |
| 1319@ifclear BARETARGET | |
| 1320If you have been using @value{GDBN} to control an attached process or 1321device, you can release it with the @code{detach} command 1322(@pxref{Attach, ,Debugging an already-running process}). | 1169If you have been using @value{GDBN} to control an attached process or 1170device, you can release it with the @code{detach} command 1171(@pxref{Attach, ,Debugging an already-running process}). |
| 1323@end ifclear | |
| 1324 | 1172 |
| 1325@node Shell Commands, , Quitting GDB, Invocation | 1173@node Shell Commands |
| 1326@section Shell commands 1327 1328If you need to execute occasional shell commands during your 1329debugging session, there is no need to leave or suspend @value{GDBN}; you can 1330just use the @code{shell} command. 1331 1332@table @code 1333@kindex shell 1334@cindex shell escape 1335@item shell @var{command string} 1336Invoke a standard shell to execute @var{command string}. | 1174@section Shell commands 1175 1176If you need to execute occasional shell commands during your 1177debugging session, there is no need to leave or suspend @value{GDBN}; you can 1178just use the @code{shell} command. 1179 1180@table @code 1181@kindex shell 1182@cindex shell escape 1183@item shell @var{command string} 1184Invoke a standard shell to execute @var{command string}. |
| 1337@ifclear DOSHOST | |
| 1338If it exists, the environment variable @code{SHELL} determines which | 1185If it exists, the environment variable @code{SHELL} determines which |
| 1339shell to run. Otherwise @value{GDBN} uses @code{/bin/sh}. 1340@end ifclear | 1186shell to run. Otherwise @value{GDBN} uses the default shell 1187(@file{/bin/sh} on Unix systems, @file{COMMAND.COM} on MS-DOS, etc.). |
| 1341@end table 1342 1343The utility @code{make} is often needed in development environments. 1344You do not have to use the @code{shell} command for this purpose in 1345@value{GDBN}: 1346 1347@table @code 1348@kindex make 1349@cindex calling make 1350@item make @var{make-args} 1351Execute the @code{make} program with the specified 1352arguments. This is equivalent to @samp{shell make @var{make-args}}. 1353@end table 1354 | 1188@end table 1189 1190The utility @code{make} is often needed in development environments. 1191You do not have to use the @code{shell} command for this purpose in 1192@value{GDBN}: 1193 1194@table @code 1195@kindex make 1196@cindex calling make 1197@item make @var{make-args} 1198Execute the @code{make} program with the specified 1199arguments. This is equivalent to @samp{shell make @var{make-args}}. 1200@end table 1201 |
| 1355@node Commands, Running, Invocation, Top | 1202@node Commands |
| 1356@chapter @value{GDBN} Commands 1357 1358You can abbreviate a @value{GDBN} command to the first few letters of the command 1359name, if that abbreviation is unambiguous; and you can repeat certain 1360@value{GDBN} commands by typing just @key{RET}. You can also use the @key{TAB} 1361key to get @value{GDBN} to fill out the rest of a word in a command (or to 1362show you the alternatives available, if there is more than one possibility). 1363 1364@menu 1365* Command Syntax:: How to give commands to @value{GDBN} 1366* Completion:: Command completion 1367* Help:: How to ask @value{GDBN} for help 1368@end menu 1369 | 1203@chapter @value{GDBN} Commands 1204 1205You can abbreviate a @value{GDBN} command to the first few letters of the command 1206name, if that abbreviation is unambiguous; and you can repeat certain 1207@value{GDBN} commands by typing just @key{RET}. You can also use the @key{TAB} 1208key to get @value{GDBN} to fill out the rest of a word in a command (or to 1209show you the alternatives available, if there is more than one possibility). 1210 1211@menu 1212* Command Syntax:: How to give commands to @value{GDBN} 1213* Completion:: Command completion 1214* Help:: How to ask @value{GDBN} for help 1215@end menu 1216 |
| 1370@node Command Syntax, Completion, Commands, Commands | 1217@node Command Syntax |
| 1371@section Command syntax 1372 1373A @value{GDBN} command is a single line of input. There is no limit on 1374how long it can be. It starts with a command name, which is followed by 1375arguments whose meaning depends on the command name. For example, the 1376command @code{step} accepts an argument which is the number of times to 1377step, as in @samp{step 5}. You can also use the @code{step} command | 1218@section Command syntax 1219 1220A @value{GDBN} command is a single line of input. There is no limit on 1221how long it can be. It starts with a command name, which is followed by 1222arguments whose meaning depends on the command name. For example, the 1223command @code{step} accepts an argument which is the number of times to 1224step, as in @samp{step 5}. You can also use the @code{step} command |
| 1378with no arguments. Some command names do not allow any arguments. | 1225with no arguments. Some commands do not allow any arguments. |
| 1379 1380@cindex abbreviation 1381@value{GDBN} command names may always be truncated if that abbreviation is 1382unambiguous. Other possible command abbreviations are listed in the 1383documentation for individual commands. In some cases, even ambiguous 1384abbreviations are allowed; for example, @code{s} is specially defined as 1385equivalent to @code{step} even though there are other commands whose 1386names start with @code{s}. You can test abbreviations by using them as 1387arguments to the @code{help} command. 1388 1389@cindex repeating commands | 1226 1227@cindex abbreviation 1228@value{GDBN} command names may always be truncated if that abbreviation is 1229unambiguous. Other possible command abbreviations are listed in the 1230documentation for individual commands. In some cases, even ambiguous 1231abbreviations are allowed; for example, @code{s} is specially defined as 1232equivalent to @code{step} even though there are other commands whose 1233names start with @code{s}. You can test abbreviations by using them as 1234arguments to the @code{help} command. 1235 1236@cindex repeating commands |
| 1390@kindex RET | 1237@kindex RET @r{(repeat last command)} |
| 1391A blank line as input to @value{GDBN} (typing just @key{RET}) means to | 1238A blank line as input to @value{GDBN} (typing just @key{RET}) means to |
| 1392repeat the previous command. Certain commands (for example, @code{run}) | 1239repeat the previous command. Certain commands (for example, @code{run}) |
| 1393will not repeat this way; these are commands whose unintentional 1394repetition might cause trouble and which you are unlikely to want to 1395repeat. 1396 1397The @code{list} and @code{x} commands, when you repeat them with 1398@key{RET}, construct new arguments rather than repeating 1399exactly as typed. This permits easy scanning of source or memory. 1400 1401@value{GDBN} can also use @key{RET} in another way: to partition lengthy 1402output, in a way similar to the common utility @code{more} 1403(@pxref{Screen Size,,Screen size}). Since it is easy to press one 1404@key{RET} too many in this situation, @value{GDBN} disables command 1405repetition after any command that generates this sort of display. 1406 | 1240will not repeat this way; these are commands whose unintentional 1241repetition might cause trouble and which you are unlikely to want to 1242repeat. 1243 1244The @code{list} and @code{x} commands, when you repeat them with 1245@key{RET}, construct new arguments rather than repeating 1246exactly as typed. This permits easy scanning of source or memory. 1247 1248@value{GDBN} can also use @key{RET} in another way: to partition lengthy 1249output, in a way similar to the common utility @code{more} 1250(@pxref{Screen Size,,Screen size}). Since it is easy to press one 1251@key{RET} too many in this situation, @value{GDBN} disables command 1252repetition after any command that generates this sort of display. 1253 |
| 1407@kindex # | 1254@kindex # @r{(a comment)} |
| 1408@cindex comment 1409Any text from a @kbd{#} to the end of the line is a comment; it does 1410nothing. This is useful mainly in command files (@pxref{Command 1411Files,,Command files}). 1412 | 1255@cindex comment 1256Any text from a @kbd{#} to the end of the line is a comment; it does 1257nothing. This is useful mainly in command files (@pxref{Command 1258Files,,Command files}). 1259 |
| 1413@node Completion, Help, Command Syntax, Commands | 1260@cindex repeating command sequences 1261@kindex C-o @r{(operate-and-get-next)} 1262The @kbd{C-o} binding is useful for repeating a complex sequence of 1263commands. This command accepts the current line, like @kbd{RET}, and 1264then fetches the next line relative to the current line from the history 1265for editing. 1266 1267@node Completion |
| 1414@section Command completion 1415 1416@cindex completion 1417@cindex word completion 1418@value{GDBN} can fill in the rest of a word in a command for you, if there is 1419only one possibility; it can also show you what the valid possibilities 1420are for the next word in a command, at any time. This works for @value{GDBN} 1421commands, @value{GDBN} subcommands, and the names of symbols in your program. --- 35 unchanged lines hidden (view full) --- 1457begins with @samp{make_}, but when you type @kbd{b make_@key{TAB}} @value{GDBN} 1458just sounds the bell. Typing @key{TAB} again displays all the 1459function names in your program that begin with those characters, for 1460example: 1461 1462@example 1463(@value{GDBP}) b make_ @key{TAB} 1464@exdent @value{GDBN} sounds bell; press @key{TAB} again, to see: | 1268@section Command completion 1269 1270@cindex completion 1271@cindex word completion 1272@value{GDBN} can fill in the rest of a word in a command for you, if there is 1273only one possibility; it can also show you what the valid possibilities 1274are for the next word in a command, at any time. This works for @value{GDBN} 1275commands, @value{GDBN} subcommands, and the names of symbols in your program. --- 35 unchanged lines hidden (view full) --- 1311begins with @samp{make_}, but when you type @kbd{b make_@key{TAB}} @value{GDBN} 1312just sounds the bell. Typing @key{TAB} again displays all the 1313function names in your program that begin with those characters, for 1314example: 1315 1316@example 1317(@value{GDBP}) b make_ @key{TAB} 1318@exdent @value{GDBN} sounds bell; press @key{TAB} again, to see: |
| 1465make_a_section_from_file make_environ 1466make_abs_section make_function_type 1467make_blockvector make_pointer_type 1468make_cleanup make_reference_type | 1319make_a_section_from_file make_environ 1320make_abs_section make_function_type 1321make_blockvector make_pointer_type 1322make_cleanup make_reference_type |
| 1469make_command make_symbol_completion_list 1470(@value{GDBP}) b make_ 1471@end example 1472 1473@noindent 1474After displaying the available possibilities, @value{GDBN} copies your 1475partial input (@samp{b make_} in the example) so you can finish the 1476command. 1477 1478If you just want to see the list of alternatives in the first place, you | 1323make_command make_symbol_completion_list 1324(@value{GDBP}) b make_ 1325@end example 1326 1327@noindent 1328After displaying the available possibilities, @value{GDBN} copies your 1329partial input (@samp{b make_} in the example) so you can finish the 1330command. 1331 1332If you just want to see the list of alternatives in the first place, you |
| 1479can press @kbd{M-?} rather than pressing @key{TAB} twice. @kbd{M-?} 1480means @kbd{@key{META} ?}. You can type this 1481@ifclear DOSHOST 1482either by holding down a | 1333can press @kbd{M-?} rather than pressing @key{TAB} twice. @kbd{M-?} 1334means @kbd{@key{META} ?}. You can type this either by holding down a |
| 1483key designated as the @key{META} shift on your keyboard (if there is | 1335key designated as the @key{META} shift on your keyboard (if there is |
| 1484one) while typing @kbd{?}, or 1485@end ifclear 1486as @key{ESC} followed by @kbd{?}. | 1336one) while typing @kbd{?}, or as @key{ESC} followed by @kbd{?}. |
| 1487 1488@cindex quotes in commands 1489@cindex completion of quoted strings 1490Sometimes the string you need, while logically a ``word'', may contain | 1337 1338@cindex quotes in commands 1339@cindex completion of quoted strings 1340Sometimes the string you need, while logically a ``word'', may contain |
| 1491parentheses or other characters that @value{GDBN} normally excludes from its 1492notion of a word. To permit word completion to work in this situation, 1493you may enclose words in @code{'} (single quote marks) in @value{GDBN} commands. | 1341parentheses or other characters that @value{GDBN} normally excludes from 1342its notion of a word. To permit word completion to work in this 1343situation, you may enclose words in @code{'} (single quote marks) in 1344@value{GDBN} commands. |
| 1494 | 1345 |
| 1495@ifclear CONLY | |
| 1496The most likely situation where you might need this is in typing the | 1346The most likely situation where you might need this is in typing the |
| 1497name of a C++ function. This is because C++ allows function overloading 1498(multiple definitions of the same function, distinguished by argument 1499type). For example, when you want to set a breakpoint you may need to 1500distinguish whether you mean the version of @code{name} that takes an 1501@code{int} parameter, @code{name(int)}, or the version that takes a 1502@code{float} parameter, @code{name(float)}. To use the word-completion 1503facilities in this situation, type a single quote @code{'} at the 1504beginning of the function name. This alerts @value{GDBN} that it may need to 1505consider more information than usual when you press @key{TAB} or 1506@kbd{M-?} to request word completion: | 1347name of a C@t{++} function. This is because C@t{++} allows function 1348overloading (multiple definitions of the same function, distinguished 1349by argument type). For example, when you want to set a breakpoint you 1350may need to distinguish whether you mean the version of @code{name} 1351that takes an @code{int} parameter, @code{name(int)}, or the version 1352that takes a @code{float} parameter, @code{name(float)}. To use the 1353word-completion facilities in this situation, type a single quote 1354@code{'} at the beginning of the function name. This alerts 1355@value{GDBN} that it may need to consider more information than usual 1356when you press @key{TAB} or @kbd{M-?} to request word completion: |
| 1507 1508@example | 1357 1358@example |
| 1509(@value{GDBP}) b 'bubble( @key{M-?} | 1359(@value{GDBP}) b 'bubble( @kbd{M-?} |
| 1510bubble(double,double) bubble(int,int) 1511(@value{GDBP}) b 'bubble( 1512@end example 1513 1514In some cases, @value{GDBN} can tell that completing a name requires using 1515quotes. When this happens, @value{GDBN} inserts the quote for you (while 1516completing as much as it can) if you do not type the quote in the first 1517place: --- 4 unchanged lines hidden (view full) --- 1522(@value{GDBP}) b 'bubble( 1523@end example 1524 1525@noindent 1526In general, @value{GDBN} can tell that a quote is needed (and inserts it) if 1527you have not yet started typing the argument list when you ask for 1528completion on an overloaded symbol. 1529 | 1360bubble(double,double) bubble(int,int) 1361(@value{GDBP}) b 'bubble( 1362@end example 1363 1364In some cases, @value{GDBN} can tell that completing a name requires using 1365quotes. When this happens, @value{GDBN} inserts the quote for you (while 1366completing as much as it can) if you do not type the quote in the first 1367place: --- 4 unchanged lines hidden (view full) --- 1372(@value{GDBP}) b 'bubble( 1373@end example 1374 1375@noindent 1376In general, @value{GDBN} can tell that a quote is needed (and inserts it) if 1377you have not yet started typing the argument list when you ask for 1378completion on an overloaded symbol. 1379 |
| 1530For more information about overloaded functions, @pxref{Cplus 1531expressions, ,C++ expressions}. You can use the command @code{set | 1380For more information about overloaded functions, see @ref{C plus plus 1381expressions, ,C@t{++} expressions}. You can use the command @code{set |
| 1532overload-resolution off} to disable overload resolution; | 1382overload-resolution off} to disable overload resolution; |
| 1533@pxref{Debugging C plus plus, ,@value{GDBN} features for C++}. 1534@end ifclear | 1383see @ref{Debugging C plus plus, ,@value{GDBN} features for C@t{++}}. |
| 1535 1536 | 1384 1385 |
| 1537@node Help, , Completion, Commands | 1386@node Help |
| 1538@section Getting help 1539@cindex online documentation 1540@kindex help 1541 | 1387@section Getting help 1388@cindex online documentation 1389@kindex help 1390 |
| 1542You can always ask @value{GDBN} itself for information on its commands, | 1391You can always ask @value{GDBN} itself for information on its commands, |
| 1543using the command @code{help}. 1544 1545@table @code | 1392using the command @code{help}. 1393 1394@table @code |
| 1546@kindex h | 1395@kindex h @r{(@code{help})} |
| 1547@item help 1548@itemx h 1549You can use @code{help} (abbreviated @code{h}) with no arguments to 1550display a short list of named classes of commands: 1551 1552@smallexample 1553(@value{GDBP}) help 1554List of classes of commands: 1555 | 1396@item help 1397@itemx h 1398You can use @code{help} (abbreviated @code{h}) with no arguments to 1399display a short list of named classes of commands: 1400 1401@smallexample 1402(@value{GDBP}) help 1403List of classes of commands: 1404 |
| 1556running -- Running the program 1557stack -- Examining the stack 1558data -- Examining data | 1405aliases -- Aliases of other commands |
| 1559breakpoints -- Making program stop at certain points | 1406breakpoints -- Making program stop at certain points |
| 1407data -- Examining data |
|
| 1560files -- Specifying and examining files | 1408files -- Specifying and examining files |
| 1409internals -- Maintenance commands 1410obscure -- Obscure features 1411running -- Running the program 1412stack -- Examining the stack |
|
| 1561status -- Status inquiries 1562support -- Support facilities | 1413status -- Status inquiries 1414support -- Support facilities |
| 1415tracepoints -- Tracing of program execution without@* 1416 stopping the program |
|
| 1563user-defined -- User-defined commands | 1417user-defined -- User-defined commands |
| 1564aliases -- Aliases of other commands 1565obscure -- Obscure features | |
| 1566 | 1418 |
| 1567Type "help" followed by a class name for a list of | 1419Type "help" followed by a class name for a list of |
| 1568commands in that class. | 1420commands in that class. |
| 1569Type "help" followed by command name for full | 1421Type "help" followed by command name for full |
| 1570documentation. 1571Command name abbreviations are allowed if unambiguous. 1572(@value{GDBP}) 1573@end smallexample | 1422documentation. 1423Command name abbreviations are allowed if unambiguous. 1424(@value{GDBP}) 1425@end smallexample |
| 1426@c the above line break eliminates huge line overfull... |
|
| 1574 1575@item help @var{class} 1576Using one of the general help classes as an argument, you can get a 1577list of the individual commands in that class. For example, here is the 1578help display for the class @code{status}: 1579 1580@smallexample 1581(@value{GDBP}) help status 1582Status inquiries. 1583 1584List of commands: 1585 1586@c Line break in "show" line falsifies real output, but needed 1587@c to fit in smallbook page size. | 1427 1428@item help @var{class} 1429Using one of the general help classes as an argument, you can get a 1430list of the individual commands in that class. For example, here is the 1431help display for the class @code{status}: 1432 1433@smallexample 1434(@value{GDBP}) help status 1435Status inquiries. 1436 1437List of commands: 1438 1439@c Line break in "show" line falsifies real output, but needed 1440@c to fit in smallbook page size. |
| 1588show -- Generic command for showing things set 1589 with "set" 1590info -- Generic command for printing status | 1441info -- Generic command for showing things 1442 about the program being debugged 1443show -- Generic command for showing things 1444 about the debugger |
| 1591 | 1445 |
| 1592Type "help" followed by command name for full | 1446Type "help" followed by command name for full |
| 1593documentation. 1594Command name abbreviations are allowed if unambiguous. 1595(@value{GDBP}) 1596@end smallexample 1597 1598@item help @var{command} 1599With a command name as @code{help} argument, @value{GDBN} displays a 1600short paragraph on how to use that command. 1601 | 1447documentation. 1448Command name abbreviations are allowed if unambiguous. 1449(@value{GDBP}) 1450@end smallexample 1451 1452@item help @var{command} 1453With a command name as @code{help} argument, @value{GDBN} displays a 1454short paragraph on how to use that command. 1455 |
| 1456@kindex apropos 1457@item apropos @var{args} 1458The @code{apropos @var{args}} command searches through all of the @value{GDBN} 1459commands, and their documentation, for the regular expression specified in 1460@var{args}. It prints out all matches found. For example: 1461 1462@smallexample 1463apropos reload 1464@end smallexample 1465 1466@noindent 1467results in: 1468 1469@smallexample 1470@c @group 1471set symbol-reloading -- Set dynamic symbol table reloading 1472 multiple times in one run 1473show symbol-reloading -- Show dynamic symbol table reloading 1474 multiple times in one run 1475@c @end group 1476@end smallexample 1477 |
|
| 1602@kindex complete 1603@item complete @var{args} 1604The @code{complete @var{args}} command lists all the possible completions 1605for the beginning of a command. Use @var{args} to specify the beginning of the 1606command you want completed. For example: 1607 1608@smallexample 1609complete i 1610@end smallexample 1611 1612@noindent results in: 1613 1614@smallexample 1615@group | 1478@kindex complete 1479@item complete @var{args} 1480The @code{complete @var{args}} command lists all the possible completions 1481for the beginning of a command. Use @var{args} to specify the beginning of the 1482command you want completed. For example: 1483 1484@smallexample 1485complete i 1486@end smallexample 1487 1488@noindent results in: 1489 1490@smallexample 1491@group |
| 1492if 1493ignore |
|
| 1616info 1617inspect | 1494info 1495inspect |
| 1618ignore | |
| 1619@end group 1620@end smallexample 1621 1622@noindent This is intended for use by @sc{gnu} Emacs. 1623@end table 1624 1625In addition to @code{help}, you can use the @value{GDBN} commands @code{info} 1626and @code{show} to inquire about the state of your program, or the state 1627of @value{GDBN} itself. Each command supports many topics of inquiry; this 1628manual introduces each of them in the appropriate context. The listings 1629under @code{info} and under @code{show} in the Index point to 1630all the sub-commands. @xref{Index}. 1631 1632@c @group 1633@table @code 1634@kindex info | 1496@end group 1497@end smallexample 1498 1499@noindent This is intended for use by @sc{gnu} Emacs. 1500@end table 1501 1502In addition to @code{help}, you can use the @value{GDBN} commands @code{info} 1503and @code{show} to inquire about the state of your program, or the state 1504of @value{GDBN} itself. Each command supports many topics of inquiry; this 1505manual introduces each of them in the appropriate context. The listings 1506under @code{info} and under @code{show} in the Index point to 1507all the sub-commands. @xref{Index}. 1508 1509@c @group 1510@table @code 1511@kindex info |
| 1635@kindex i | 1512@kindex i @r{(@code{info})} |
| 1636@item info 1637This command (abbreviated @code{i}) is for describing the state of your 1638program. For example, you can list the arguments given to your program 1639with @code{info args}, list the registers currently in use with @code{info 1640registers}, or list the breakpoints you have set with @code{info breakpoints}. 1641You can get a complete list of the @code{info} sub-commands with 1642@w{@code{help info}}. 1643 1644@kindex set 1645@item set | 1513@item info 1514This command (abbreviated @code{i}) is for describing the state of your 1515program. For example, you can list the arguments given to your program 1516with @code{info args}, list the registers currently in use with @code{info 1517registers}, or list the breakpoints you have set with @code{info breakpoints}. 1518You can get a complete list of the @code{info} sub-commands with 1519@w{@code{help info}}. 1520 1521@kindex set 1522@item set |
| 1646You can assign the result of an expression to an environment variable with | 1523You can assign the result of an expression to an environment variable with |
| 1647@code{set}. For example, you can set the @value{GDBN} prompt to a $-sign with 1648@code{set prompt $}. 1649 1650@kindex show 1651@item show | 1524@code{set}. For example, you can set the @value{GDBN} prompt to a $-sign with 1525@code{set prompt $}. 1526 1527@kindex show 1528@item show |
| 1652In contrast to @code{info}, @code{show} is for describing the state of | 1529In contrast to @code{info}, @code{show} is for describing the state of |
| 1653@value{GDBN} itself. 1654You can change most of the things you can @code{show}, by using the 1655related command @code{set}; for example, you can control what number 1656system is used for displays with @code{set radix}, or simply inquire 1657which is currently in use with @code{show radix}. 1658 1659@kindex info set 1660To display all the settable parameters and their current --- 8 unchanged lines hidden (view full) --- 1669Here are three miscellaneous @code{show} subcommands, all of which are 1670exceptional in lacking corresponding @code{set} commands: 1671 1672@table @code 1673@kindex show version 1674@cindex version number 1675@item show version 1676Show what version of @value{GDBN} is running. You should include this | 1530@value{GDBN} itself. 1531You can change most of the things you can @code{show}, by using the 1532related command @code{set}; for example, you can control what number 1533system is used for displays with @code{set radix}, or simply inquire 1534which is currently in use with @code{show radix}. 1535 1536@kindex info set 1537To display all the settable parameters and their current --- 8 unchanged lines hidden (view full) --- 1546Here are three miscellaneous @code{show} subcommands, all of which are 1547exceptional in lacking corresponding @code{set} commands: 1548 1549@table @code 1550@kindex show version 1551@cindex version number 1552@item show version 1553Show what version of @value{GDBN} is running. You should include this |
| 1677information in @value{GDBN} bug-reports. If multiple versions of @value{GDBN} are in 1678use at your site, you may occasionally want to determine which version 1679of @value{GDBN} you are running; as @value{GDBN} evolves, new commands are introduced, 1680and old ones may wither away. The version number is also announced 1681when you start @value{GDBN}. | 1554information in @value{GDBN} bug-reports. If multiple versions of 1555@value{GDBN} are in use at your site, you may need to determine which 1556version of @value{GDBN} you are running; as @value{GDBN} evolves, new 1557commands are introduced, and old ones may wither away. Also, many 1558system vendors ship variant versions of @value{GDBN}, and there are 1559variant versions of @value{GDBN} in @sc{gnu}/Linux distributions as well. 1560The version number is the same as the one announced when you start 1561@value{GDBN}. |
| 1682 1683@kindex show copying 1684@item show copying 1685Display information about permission for copying @value{GDBN}. 1686 1687@kindex show warranty 1688@item show warranty | 1562 1563@kindex show copying 1564@item show copying 1565Display information about permission for copying @value{GDBN}. 1566 1567@kindex show warranty 1568@item show warranty |
| 1689Display the @sc{gnu} ``NO WARRANTY'' statement. | 1569Display the @sc{gnu} ``NO WARRANTY'' statement, or a warranty, 1570if your version of @value{GDBN} comes with one. 1571 |
| 1690@end table 1691 | 1572@end table 1573 |
| 1692@node Running, Stopping, Commands, Top | 1574@node Running |
| 1693@chapter Running Programs Under @value{GDBN} 1694 1695When you run a program under @value{GDBN}, you must first generate 1696debugging information when you compile it. | 1575@chapter Running Programs Under @value{GDBN} 1576 1577When you run a program under @value{GDBN}, you must first generate 1578debugging information when you compile it. |
| 1697@ifclear BARETARGET 1698You may start @value{GDBN} with its arguments, if any, in an environment 1699of your choice. You may redirect your program's input and output, debug an 1700already running process, or kill a child process. 1701@end ifclear | |
| 1702 | 1579 |
| 1580You may start @value{GDBN} with its arguments, if any, in an environment 1581of your choice. If you are doing native debugging, you may redirect 1582your program's input and output, debug an already running process, or 1583kill a child process. 1584 |
|
| 1703@menu 1704* Compilation:: Compiling for debugging 1705* Starting:: Starting your program | 1585@menu 1586* Compilation:: Compiling for debugging 1587* Starting:: Starting your program |
| 1706@ifclear BARETARGET | |
| 1707* Arguments:: Your program's arguments 1708* Environment:: Your program's environment | 1588* Arguments:: Your program's arguments 1589* Environment:: Your program's environment |
| 1709@end ifclear | |
| 1710 1711* Working Directory:: Your program's working directory 1712* Input/Output:: Your program's input and output 1713* Attach:: Debugging an already-running process 1714* Kill Process:: Killing the child process | 1590 1591* Working Directory:: Your program's working directory 1592* Input/Output:: Your program's input and output 1593* Attach:: Debugging an already-running process 1594* Kill Process:: Killing the child process |
| 1715@ifclear HPPA 1716* Process Information:: Additional process information 1717@end ifclear | |
| 1718 1719* Threads:: Debugging programs with multiple threads 1720* Processes:: Debugging programs with multiple processes 1721@end menu 1722 | 1595 1596* Threads:: Debugging programs with multiple threads 1597* Processes:: Debugging programs with multiple processes 1598@end menu 1599 |
| 1723@node Compilation, Starting, Running, Running | 1600@node Compilation |
| 1724@section Compiling for debugging 1725 1726In order to debug a program effectively, you need to generate 1727debugging information when you compile it. This debugging information 1728is stored in the object file; it describes the data type of each 1729variable or function and the correspondence between source line numbers 1730and addresses in the executable code. 1731 1732To request debugging information, specify the @samp{-g} option when you run 1733the compiler. 1734 1735Many C compilers are unable to handle the @samp{-g} and @samp{-O} 1736options together. Using those compilers, you cannot generate optimized 1737executables containing debugging information. 1738 | 1601@section Compiling for debugging 1602 1603In order to debug a program effectively, you need to generate 1604debugging information when you compile it. This debugging information 1605is stored in the object file; it describes the data type of each 1606variable or function and the correspondence between source line numbers 1607and addresses in the executable code. 1608 1609To request debugging information, specify the @samp{-g} option when you run 1610the compiler. 1611 1612Many C compilers are unable to handle the @samp{-g} and @samp{-O} 1613options together. Using those compilers, you cannot generate optimized 1614executables containing debugging information. 1615 |
| 1739@ifclear HPPA 1740@value{NGCC}, the @sc{gnu} C compiler, supports @samp{-g} with or without 1741@end ifclear 1742@ifset HPPA 1743The HP ANSI C and C++ compilers, as well as @value{NGCC}, the @sc{gnu} C 1744compiler, support @samp{-g} with or without 1745@end ifset 1746@samp{-O}, making it possible to debug optimized code. We recommend 1747that you @emph{always} use @samp{-g} whenever you compile a program. 1748You may think your program is correct, but there is no sense in pushing 1749your luck. | 1616@value{NGCC}, the @sc{gnu} C compiler, supports @samp{-g} with or 1617without @samp{-O}, making it possible to debug optimized code. We 1618recommend that you @emph{always} use @samp{-g} whenever you compile a 1619program. You may think your program is correct, but there is no sense 1620in pushing your luck. |
| 1750 1751@cindex optimized code, debugging 1752@cindex debugging optimized code 1753When you debug a program compiled with @samp{-g -O}, remember that the 1754optimizer is rearranging your code; the debugger shows you what is 1755really there. Do not be too surprised when the execution path does not 1756exactly match your source file! An extreme example: if you define a 1757variable, but never use it, @value{GDBN} never sees that --- 4 unchanged lines hidden (view full) --- 1762doubt, recompile with @samp{-g} alone, and if this fixes the problem, 1763please report it to us as a bug (including a test case!). 1764 1765Older versions of the @sc{gnu} C compiler permitted a variant option 1766@w{@samp{-gg}} for debugging information. @value{GDBN} no longer supports this 1767format; if your @sc{gnu} C compiler has this option, do not use it. 1768 1769@need 2000 | 1621 1622@cindex optimized code, debugging 1623@cindex debugging optimized code 1624When you debug a program compiled with @samp{-g -O}, remember that the 1625optimizer is rearranging your code; the debugger shows you what is 1626really there. Do not be too surprised when the execution path does not 1627exactly match your source file! An extreme example: if you define a 1628variable, but never use it, @value{GDBN} never sees that --- 4 unchanged lines hidden (view full) --- 1633doubt, recompile with @samp{-g} alone, and if this fixes the problem, 1634please report it to us as a bug (including a test case!). 1635 1636Older versions of the @sc{gnu} C compiler permitted a variant option 1637@w{@samp{-gg}} for debugging information. @value{GDBN} no longer supports this 1638format; if your @sc{gnu} C compiler has this option, do not use it. 1639 1640@need 2000 |
| 1770@node Starting, Arguments, Compilation, Running | 1641@node Starting |
| 1771@section Starting your program 1772@cindex starting 1773@cindex running 1774 1775@table @code 1776@kindex run | 1642@section Starting your program 1643@cindex starting 1644@cindex running 1645 1646@table @code 1647@kindex run |
| 1648@kindex r @r{(@code{run})} |
|
| 1777@item run 1778@itemx r | 1649@item run 1650@itemx r |
| 1779Use the @code{run} command to start your program under @value{GDBN}. You must 1780first specify the program name 1781@ifset VXWORKS 1782(except on VxWorks) 1783@end ifset 1784with an argument to @value{GDBN} (@pxref{Invocation, ,Getting In and 1785Out of @value{GDBN}}), or by using the @code{file} or @code{exec-file} 1786command (@pxref{Files, ,Commands to specify files}). | 1651Use the @code{run} command to start your program under @value{GDBN}. 1652You must first specify the program name (except on VxWorks) with an 1653argument to @value{GDBN} (@pxref{Invocation, ,Getting In and Out of 1654@value{GDBN}}), or by using the @code{file} or @code{exec-file} command 1655(@pxref{Files, ,Commands to specify files}). |
| 1787 1788@end table 1789 | 1656 1657@end table 1658 |
| 1790@ifclear BARETARGET | |
| 1791If you are running your program in an execution environment that 1792supports processes, @code{run} creates an inferior process and makes 1793that process run your program. (In environments without processes, 1794@code{run} jumps to the start of your program.) 1795 1796The execution of a program is affected by certain information it 1797receives from its superior. @value{GDBN} provides ways to specify this 1798information, which you must do @emph{before} starting your program. (You --- 31 unchanged lines hidden (view full) --- 1830@xref{Input/Output, ,Your program's input and output}. 1831 1832@cindex pipes 1833@emph{Warning:} While input and output redirection work, you cannot use 1834pipes to pass the output of the program you are debugging to another 1835program; if you attempt this, @value{GDBN} is likely to wind up debugging the 1836wrong program. 1837@end table | 1659If you are running your program in an execution environment that 1660supports processes, @code{run} creates an inferior process and makes 1661that process run your program. (In environments without processes, 1662@code{run} jumps to the start of your program.) 1663 1664The execution of a program is affected by certain information it 1665receives from its superior. @value{GDBN} provides ways to specify this 1666information, which you must do @emph{before} starting your program. (You --- 31 unchanged lines hidden (view full) --- 1698@xref{Input/Output, ,Your program's input and output}. 1699 1700@cindex pipes 1701@emph{Warning:} While input and output redirection work, you cannot use 1702pipes to pass the output of the program you are debugging to another 1703program; if you attempt this, @value{GDBN} is likely to wind up debugging the 1704wrong program. 1705@end table |
| 1838@end ifclear | |
| 1839 1840When you issue the @code{run} command, your program begins to execute 1841immediately. @xref{Stopping, ,Stopping and continuing}, for discussion 1842of how to arrange for your program to stop. Once your program has 1843stopped, you may call functions in your program, using the @code{print} 1844or @code{call} commands. @xref{Data, ,Examining Data}. 1845 1846If the modification time of your symbol file has changed since the last 1847time @value{GDBN} read its symbols, @value{GDBN} discards its symbol 1848table, and reads it again. When it does this, @value{GDBN} tries to retain 1849your current breakpoints. 1850 | 1706 1707When you issue the @code{run} command, your program begins to execute 1708immediately. @xref{Stopping, ,Stopping and continuing}, for discussion 1709of how to arrange for your program to stop. Once your program has 1710stopped, you may call functions in your program, using the @code{print} 1711or @code{call} commands. @xref{Data, ,Examining Data}. 1712 1713If the modification time of your symbol file has changed since the last 1714time @value{GDBN} read its symbols, @value{GDBN} discards its symbol 1715table, and reads it again. When it does this, @value{GDBN} tries to retain 1716your current breakpoints. 1717 |
| 1851@ifclear BARETARGET 1852@node Arguments, Environment, Starting, Running | 1718@node Arguments |
| 1853@section Your program's arguments 1854 1855@cindex arguments (to your program) 1856The arguments to your program can be specified by the arguments of the | 1719@section Your program's arguments 1720 1721@cindex arguments (to your program) 1722The arguments to your program can be specified by the arguments of the |
| 1857@code{run} command. | 1723@code{run} command. |
| 1858They are passed to a shell, which expands wildcard characters and 1859performs redirection of I/O, and thence to your program. Your 1860@code{SHELL} environment variable (if it exists) specifies what shell 1861@value{GDBN} uses. If you do not define @code{SHELL}, @value{GDBN} uses | 1724They are passed to a shell, which expands wildcard characters and 1725performs redirection of I/O, and thence to your program. Your 1726@code{SHELL} environment variable (if it exists) specifies what shell 1727@value{GDBN} uses. If you do not define @code{SHELL}, @value{GDBN} uses |
| 1862@code{/bin/sh}. | 1728the default shell (@file{/bin/sh} on Unix). |
| 1863 | 1729 |
| 1730On non-Unix systems, the program is usually invoked directly by 1731@value{GDBN}, which emulates I/O redirection via the appropriate system 1732calls, and the wildcard characters are expanded by the startup code of 1733the program, not by the shell. 1734 |
|
| 1864@code{run} with no arguments uses the same arguments used by the previous 1865@code{run}, or those set by the @code{set args} command. 1866 | 1735@code{run} with no arguments uses the same arguments used by the previous 1736@code{run}, or those set by the @code{set args} command. 1737 |
| 1867@kindex set args | |
| 1868@table @code | 1738@table @code |
| 1739@kindex set args |
|
| 1869@item set args 1870Specify the arguments to be used the next time your program is run. If 1871@code{set args} has no arguments, @code{run} executes your program 1872with no arguments. Once you have run your program with arguments, 1873using @code{set args} before the next @code{run} is the only way to run 1874it again without arguments. 1875 1876@kindex show args 1877@item show args 1878Show the arguments to give your program when it is started. 1879@end table 1880 | 1740@item set args 1741Specify the arguments to be used the next time your program is run. If 1742@code{set args} has no arguments, @code{run} executes your program 1743with no arguments. Once you have run your program with arguments, 1744using @code{set args} before the next @code{run} is the only way to run 1745it again without arguments. 1746 1747@kindex show args 1748@item show args 1749Show the arguments to give your program when it is started. 1750@end table 1751 |
| 1881@node Environment, Working Directory, Arguments, Running | 1752@node Environment |
| 1882@section Your program's environment 1883 1884@cindex environment (of your program) 1885The @dfn{environment} consists of a set of environment variables and 1886their values. Environment variables conventionally record such things as 1887your user name, your home directory, your terminal type, and your search 1888path for programs to run. Usually you set up environment variables with 1889the shell and they are inherited by all the other programs you run. When 1890debugging, it can be useful to try running your program with a modified 1891environment without having to start @value{GDBN} over again. 1892 1893@table @code 1894@kindex path 1895@item path @var{directory} 1896Add @var{directory} to the front of the @code{PATH} environment variable | 1753@section Your program's environment 1754 1755@cindex environment (of your program) 1756The @dfn{environment} consists of a set of environment variables and 1757their values. Environment variables conventionally record such things as 1758your user name, your home directory, your terminal type, and your search 1759path for programs to run. Usually you set up environment variables with 1760the shell and they are inherited by all the other programs you run. When 1761debugging, it can be useful to try running your program with a modified 1762environment without having to start @value{GDBN} over again. 1763 1764@table @code 1765@kindex path 1766@item path @var{directory} 1767Add @var{directory} to the front of the @code{PATH} environment variable |
| 1897(the search path for executables), for both @value{GDBN} and your program. 1898You may specify several directory names, separated by @samp{:} or 1899whitespace. If @var{directory} is already in the path, it is moved to 1900the front, so it is searched sooner. | 1768(the search path for executables) that will be passed to your program. 1769The value of @code{PATH} used by @value{GDBN} does not change. 1770You may specify several directory names, separated by whitespace or by a 1771system-dependent separator character (@samp{:} on Unix, @samp{;} on 1772MS-DOS and MS-Windows). If @var{directory} is already in the path, it 1773is moved to the front, so it is searched sooner. |
| 1901 1902You can use the string @samp{$cwd} to refer to whatever is the current 1903working directory at the time @value{GDBN} searches the path. If you 1904use @samp{.} instead, it refers to the directory where you executed the 1905@code{path} command. @value{GDBN} replaces @samp{.} in the 1906@var{directory} argument (with the current path) before adding 1907@var{directory} to the search path. 1908@c 'path' is explicitly nonrepeatable, but RMS points out it is silly to --- 7 unchanged lines hidden (view full) --- 1916@kindex show environment 1917@item show environment @r{[}@var{varname}@r{]} 1918Print the value of environment variable @var{varname} to be given to 1919your program when it starts. If you do not supply @var{varname}, 1920print the names and values of all environment variables to be given to 1921your program. You can abbreviate @code{environment} as @code{env}. 1922 1923@kindex set environment | 1774 1775You can use the string @samp{$cwd} to refer to whatever is the current 1776working directory at the time @value{GDBN} searches the path. If you 1777use @samp{.} instead, it refers to the directory where you executed the 1778@code{path} command. @value{GDBN} replaces @samp{.} in the 1779@var{directory} argument (with the current path) before adding 1780@var{directory} to the search path. 1781@c 'path' is explicitly nonrepeatable, but RMS points out it is silly to --- 7 unchanged lines hidden (view full) --- 1789@kindex show environment 1790@item show environment @r{[}@var{varname}@r{]} 1791Print the value of environment variable @var{varname} to be given to 1792your program when it starts. If you do not supply @var{varname}, 1793print the names and values of all environment variables to be given to 1794your program. You can abbreviate @code{environment} as @code{env}. 1795 1796@kindex set environment |
| 1924@item set environment @var{varname} @r{[}=@r{]} @var{value} | 1797@item set environment @var{varname} @r{[}=@var{value}@r{]} |
| 1925Set environment variable @var{varname} to @var{value}. The value 1926changes for your program only, not for @value{GDBN} itself. @var{value} may 1927be any string; the values of environment variables are just strings, and 1928any interpretation is supplied by your program itself. The @var{value} 1929parameter is optional; if it is eliminated, the variable is set to a 1930null value. 1931@c "any string" here does not include leading, trailing 1932@c blanks. Gnu asks: does anyone care? 1933 1934For example, this command: 1935 1936@example 1937set env USER = foo 1938@end example 1939 1940@noindent | 1798Set environment variable @var{varname} to @var{value}. The value 1799changes for your program only, not for @value{GDBN} itself. @var{value} may 1800be any string; the values of environment variables are just strings, and 1801any interpretation is supplied by your program itself. The @var{value} 1802parameter is optional; if it is eliminated, the variable is set to a 1803null value. 1804@c "any string" here does not include leading, trailing 1805@c blanks. Gnu asks: does anyone care? 1806 1807For example, this command: 1808 1809@example 1810set env USER = foo 1811@end example 1812 1813@noindent |
| 1941tells a Unix program, when subsequently run, that its user is named | 1814tells the debugged program, when subsequently run, that its user is named |
| 1942@samp{foo}. (The spaces around @samp{=} are used for clarity here; they 1943are not actually required.) 1944 1945@kindex unset environment 1946@item unset environment @var{varname} 1947Remove variable @var{varname} from the environment to be passed to your 1948program. This is different from @samp{set env @var{varname} =}; 1949@code{unset environment} removes the variable from the environment, 1950rather than assigning it an empty value. 1951@end table 1952 | 1815@samp{foo}. (The spaces around @samp{=} are used for clarity here; they 1816are not actually required.) 1817 1818@kindex unset environment 1819@item unset environment @var{varname} 1820Remove variable @var{varname} from the environment to be passed to your 1821program. This is different from @samp{set env @var{varname} =}; 1822@code{unset environment} removes the variable from the environment, 1823rather than assigning it an empty value. 1824@end table 1825 |
| 1953@emph{Warning:} @value{GDBN} runs your program using the shell indicated | 1826@emph{Warning:} On Unix systems, @value{GDBN} runs your program using 1827the shell indicated |
| 1954by your @code{SHELL} environment variable if it exists (or 1955@code{/bin/sh} if not). If your @code{SHELL} variable names a shell 1956that runs an initialization file---such as @file{.cshrc} for C-shell, or 1957@file{.bashrc} for BASH---any variables you set in that file affect 1958your program. You may wish to move setting of environment variables to 1959files that are only run when you sign on, such as @file{.login} or 1960@file{.profile}. 1961 | 1828by your @code{SHELL} environment variable if it exists (or 1829@code{/bin/sh} if not). If your @code{SHELL} variable names a shell 1830that runs an initialization file---such as @file{.cshrc} for C-shell, or 1831@file{.bashrc} for BASH---any variables you set in that file affect 1832your program. You may wish to move setting of environment variables to 1833files that are only run when you sign on, such as @file{.login} or 1834@file{.profile}. 1835 |
| 1962@node Working Directory, Input/Output, Environment, Running | 1836@node Working Directory |
| 1963@section Your program's working directory 1964 1965@cindex working directory (of your program) 1966Each time you start your program with @code{run}, it inherits its 1967working directory from the current working directory of @value{GDBN}. 1968The @value{GDBN} working directory is initially whatever it inherited 1969from its parent process (typically the shell), but you can specify a new 1970working directory in @value{GDBN} with the @code{cd} command. --- 7 unchanged lines hidden (view full) --- 1978@item cd @var{directory} 1979Set the @value{GDBN} working directory to @var{directory}. 1980 1981@kindex pwd 1982@item pwd 1983Print the @value{GDBN} working directory. 1984@end table 1985 | 1837@section Your program's working directory 1838 1839@cindex working directory (of your program) 1840Each time you start your program with @code{run}, it inherits its 1841working directory from the current working directory of @value{GDBN}. 1842The @value{GDBN} working directory is initially whatever it inherited 1843from its parent process (typically the shell), but you can specify a new 1844working directory in @value{GDBN} with the @code{cd} command. --- 7 unchanged lines hidden (view full) --- 1852@item cd @var{directory} 1853Set the @value{GDBN} working directory to @var{directory}. 1854 1855@kindex pwd 1856@item pwd 1857Print the @value{GDBN} working directory. 1858@end table 1859 |
| 1986@node Input/Output, Attach, Working Directory, Running | 1860@node Input/Output |
| 1987@section Your program's input and output 1988 1989@cindex redirection 1990@cindex i/o 1991@cindex terminal 1992By default, the program you run under @value{GDBN} does input and output to | 1861@section Your program's input and output 1862 1863@cindex redirection 1864@cindex i/o 1865@cindex terminal 1866By default, the program you run under @value{GDBN} does input and output to |
| 1993the same terminal that @value{GDBN} uses. @value{GDBN} switches the terminal | 1867the same terminal that @value{GDBN} uses. @value{GDBN} switches the terminal |
| 1994to its own terminal modes to interact with you, but it records the terminal 1995modes your program was using and switches back to them when you continue 1996running your program. 1997 1998@table @code 1999@kindex info terminal 2000@item info terminal 2001Displays information recorded by @value{GDBN} about the terminal modes your --- 30 unchanged lines hidden (view full) --- 2032An explicit redirection in @code{run} overrides the @code{tty} command's 2033effect on the input/output device, but not its effect on the controlling 2034terminal. 2035 2036When you use the @code{tty} command or redirect input in the @code{run} 2037command, only the input @emph{for your program} is affected. The input 2038for @value{GDBN} still comes from your terminal. 2039 | 1868to its own terminal modes to interact with you, but it records the terminal 1869modes your program was using and switches back to them when you continue 1870running your program. 1871 1872@table @code 1873@kindex info terminal 1874@item info terminal 1875Displays information recorded by @value{GDBN} about the terminal modes your --- 30 unchanged lines hidden (view full) --- 1906An explicit redirection in @code{run} overrides the @code{tty} command's 1907effect on the input/output device, but not its effect on the controlling 1908terminal. 1909 1910When you use the @code{tty} command or redirect input in the @code{run} 1911command, only the input @emph{for your program} is affected. The input 1912for @value{GDBN} still comes from your terminal. 1913 |
| 2040@node Attach, Kill Process, Input/Output, Running | 1914@node Attach |
| 2041@section Debugging an already-running process 2042@kindex attach 2043@cindex attach 2044 2045@table @code 2046@item attach @var{process-id} 2047This command attaches to a running process---one that was started 2048outside @value{GDBN}. (@code{info files} shows your active --- 14 unchanged lines hidden (view full) --- 2063the process first by looking in the current working directory, then (if 2064the program is not found) by using the source file search path 2065(@pxref{Source Path, ,Specifying source directories}). You can also use 2066the @code{file} command to load the program. @xref{Files, ,Commands to 2067Specify Files}. 2068 2069The first thing @value{GDBN} does after arranging to debug the specified 2070process is to stop it. You can examine and modify an attached process | 1915@section Debugging an already-running process 1916@kindex attach 1917@cindex attach 1918 1919@table @code 1920@item attach @var{process-id} 1921This command attaches to a running process---one that was started 1922outside @value{GDBN}. (@code{info files} shows your active --- 14 unchanged lines hidden (view full) --- 1937the process first by looking in the current working directory, then (if 1938the program is not found) by using the source file search path 1939(@pxref{Source Path, ,Specifying source directories}). You can also use 1940the @code{file} command to load the program. @xref{Files, ,Commands to 1941Specify Files}. 1942 1943The first thing @value{GDBN} does after arranging to debug the specified 1944process is to stop it. You can examine and modify an attached process |
| 2071with all the @value{GDBN} commands that are ordinarily available when you start 2072@ifclear HPPA 2073processes with @code{run}. You can insert breakpoints; you can step and 2074@end ifclear 2075@ifset HPPA 2076processes with @code{run}. You can insert breakpoints (except in shared 2077libraries); you can step and 2078@end ifset 2079continue; you can modify storage. If you would rather the process 2080continue running, you may use the @code{continue} command after | 1945with all the @value{GDBN} commands that are ordinarily available when 1946you start processes with @code{run}. You can insert breakpoints; you 1947can step and continue; you can modify storage. If you would rather the 1948process continue running, you may use the @code{continue} command after |
| 2081attaching @value{GDBN} to the process. 2082 2083@table @code 2084@kindex detach 2085@item detach 2086When you have finished debugging the attached process, you can use the 2087@code{detach} command to release it from @value{GDBN} control. Detaching 2088the process continues its execution. After the @code{detach} command, --- 5 unchanged lines hidden (view full) --- 2094 2095If you exit @value{GDBN} or use the @code{run} command while you have an 2096attached process, you kill that process. By default, @value{GDBN} asks 2097for confirmation if you try to do either of these things; you can 2098control whether or not you need to confirm by using the @code{set 2099confirm} command (@pxref{Messages/Warnings, ,Optional warnings and 2100messages}). 2101 | 1949attaching @value{GDBN} to the process. 1950 1951@table @code 1952@kindex detach 1953@item detach 1954When you have finished debugging the attached process, you can use the 1955@code{detach} command to release it from @value{GDBN} control. Detaching 1956the process continues its execution. After the @code{detach} command, --- 5 unchanged lines hidden (view full) --- 1962 1963If you exit @value{GDBN} or use the @code{run} command while you have an 1964attached process, you kill that process. By default, @value{GDBN} asks 1965for confirmation if you try to do either of these things; you can 1966control whether or not you need to confirm by using the @code{set 1967confirm} command (@pxref{Messages/Warnings, ,Optional warnings and 1968messages}). 1969 |
| 2102@ifset HPPA 2103@node Kill Process, Threads, Attach, Running | 1970@node Kill Process |
| 2104@section Killing the child process | 1971@section Killing the child process |
| 2105@end ifset 2106@ifclear HPPA 2107@node Kill Process, Process Information, Attach, Running 2108@section Killing the child process 2109@end ifclear | |
| 2110 2111@table @code 2112@kindex kill 2113@item kill 2114Kill the child process in which your program is running under @value{GDBN}. 2115@end table 2116 2117This command is useful if you wish to debug a core dump instead of a --- 7 unchanged lines hidden (view full) --- 2125 2126The @code{kill} command is also useful if you wish to recompile and 2127relink your program, since on many systems it is impossible to modify an 2128executable file while it is running in a process. In this case, when you 2129next type @code{run}, @value{GDBN} notices that the file has changed, and 2130reads the symbol table again (while trying to preserve your current 2131breakpoint settings). 2132 | 1972 1973@table @code 1974@kindex kill 1975@item kill 1976Kill the child process in which your program is running under @value{GDBN}. 1977@end table 1978 1979This command is useful if you wish to debug a core dump instead of a --- 7 unchanged lines hidden (view full) --- 1987 1988The @code{kill} command is also useful if you wish to recompile and 1989relink your program, since on many systems it is impossible to modify an 1990executable file while it is running in a process. In this case, when you 1991next type @code{run}, @value{GDBN} notices that the file has changed, and 1992reads the symbol table again (while trying to preserve your current 1993breakpoint settings). 1994 |
| 2133@ifclear HPPA 2134@node Process Information, Threads, Kill Process, Running 2135@section Additional process information 2136 2137@kindex /proc 2138@cindex process image 2139Some operating systems provide a facility called @samp{/proc} that can 2140be used to examine the image of a running process using file-system 2141subroutines. If @value{GDBN} is configured for an operating system with this 2142facility, the command @code{info proc} is available to report on several 2143kinds of information about the process running your program. 2144@code{info proc} works only on SVR4 systems that support @code{procfs}. 2145 2146@table @code 2147@kindex info proc 2148@item info proc 2149Summarize available information about the process. 2150 2151@kindex info proc mappings 2152@item info proc mappings 2153Report on the address ranges accessible in the program, with information 2154on whether your program may read, write, or execute each range. 2155 2156@kindex info proc times 2157@item info proc times 2158Starting time, user CPU time, and system CPU time for your program and 2159its children. 2160 2161@kindex info proc id 2162@item info proc id 2163Report on the process IDs related to your program: its own process ID, 2164the ID of its parent, the process group ID, and the session ID. 2165 2166@kindex info proc status 2167@item info proc status 2168General information on the state of the process. If the process is 2169stopped, this report includes the reason for stopping, and any signal 2170received. 2171 2172@item info proc all 2173Show all the above information about the process. 2174@end table 2175@end ifclear 2176 2177@ifset HPPA 2178@node Threads, Processes, Kill Process, Running | 1995@node Threads |
| 2179@section Debugging programs with multiple threads | 1996@section Debugging programs with multiple threads |
| 2180@end ifset 2181@ifclear HPPA 2182@node Threads, Processes, Process Information, Running 2183@section Debugging programs with multiple threads 2184@end ifclear | |
| 2185 2186@cindex threads of execution 2187@cindex multiple threads 2188@cindex switching threads 2189In some operating systems, such as HP-UX and Solaris, a single program 2190may have more than one @dfn{thread} of execution. The precise semantics 2191of threads differ from one operating system to another, but in general 2192the threads of a single program are akin to multiple processes---except 2193that they share one address space (that is, they can all examine and 2194modify the same variables). On the other hand, each thread has its own 2195registers and execution stack, and perhaps private memory. 2196 2197@value{GDBN} provides these facilities for debugging multi-thread 2198programs: 2199 2200@itemize @bullet 2201@item automatic notification of new threads 2202@item @samp{thread @var{threadno}}, a command to switch among threads 2203@item @samp{info threads}, a command to inquire about existing threads | 1997 1998@cindex threads of execution 1999@cindex multiple threads 2000@cindex switching threads 2001In some operating systems, such as HP-UX and Solaris, a single program 2002may have more than one @dfn{thread} of execution. The precise semantics 2003of threads differ from one operating system to another, but in general 2004the threads of a single program are akin to multiple processes---except 2005that they share one address space (that is, they can all examine and 2006modify the same variables). On the other hand, each thread has its own 2007registers and execution stack, and perhaps private memory. 2008 2009@value{GDBN} provides these facilities for debugging multi-thread 2010programs: 2011 2012@itemize @bullet 2013@item automatic notification of new threads 2014@item @samp{thread @var{threadno}}, a command to switch among threads 2015@item @samp{info threads}, a command to inquire about existing threads |
| 2204@item @samp{thread apply [@var{threadno}] [@var{all}] @var{args}}, | 2016@item @samp{thread apply [@var{threadno}] [@var{all}] @var{args}}, |
| 2205a command to apply a command to a list of threads 2206@item thread-specific breakpoints 2207@end itemize 2208 | 2017a command to apply a command to a list of threads 2018@item thread-specific breakpoints 2019@end itemize 2020 |
| 2209@ifclear HPPA | |
| 2210@quotation 2211@emph{Warning:} These facilities are not yet available on every 2212@value{GDBN} configuration where the operating system supports threads. 2213If your @value{GDBN} does not support threads, these commands have no 2214effect. For example, a system without thread support shows no output 2215from @samp{info threads}, and always rejects the @code{thread} command, 2216like this: 2217 2218@smallexample 2219(@value{GDBP}) info threads 2220(@value{GDBP}) thread 1 2221Thread ID 1 not known. Use the "info threads" command to 2222see the IDs of currently known threads. 2223@end smallexample 2224@c FIXME to implementors: how hard would it be to say "sorry, this GDB 2225@c doesn't support threads"? 2226@end quotation | 2021@quotation 2022@emph{Warning:} These facilities are not yet available on every 2023@value{GDBN} configuration where the operating system supports threads. 2024If your @value{GDBN} does not support threads, these commands have no 2025effect. For example, a system without thread support shows no output 2026from @samp{info threads}, and always rejects the @code{thread} command, 2027like this: 2028 2029@smallexample 2030(@value{GDBP}) info threads 2031(@value{GDBP}) thread 1 2032Thread ID 1 not known. Use the "info threads" command to 2033see the IDs of currently known threads. 2034@end smallexample 2035@c FIXME to implementors: how hard would it be to say "sorry, this GDB 2036@c doesn't support threads"? 2037@end quotation |
| 2227@end ifclear | |
| 2228 2229@cindex focus of debugging 2230@cindex current thread 2231The @value{GDBN} thread debugging facility allows you to observe all 2232threads while your program runs---but whenever @value{GDBN} takes 2233control, one thread in particular is always the focus of debugging. 2234This thread is called the @dfn{current thread}. Debugging commands show 2235program information from the perspective of the current thread. 2236 | 2038 2039@cindex focus of debugging 2040@cindex current thread 2041The @value{GDBN} thread debugging facility allows you to observe all 2042threads while your program runs---but whenever @value{GDBN} takes 2043control, one thread in particular is always the focus of debugging. 2044This thread is called the @dfn{current thread}. Debugging commands show 2045program information from the perspective of the current thread. 2046 |
| 2237@ifclear HPPA 2238@kindex New @var{systag} | 2047@cindex @code{New} @var{systag} message |
| 2239@cindex thread identifier (system) 2240@c FIXME-implementors!! It would be more helpful if the [New...] message 2241@c included GDB's numeric thread handle, so you could just go to that 2242@c thread without first checking `info threads'. 2243Whenever @value{GDBN} detects a new thread in your program, it displays 2244the target system's identification for the thread with a message in the 2245form @samp{[New @var{systag}]}. @var{systag} is a thread identifier 2246whose form varies depending on the particular system. For example, on --- 5 unchanged lines hidden (view full) --- 2252 2253@noindent 2254when @value{GDBN} notices a new thread. In contrast, on an SGI system, 2255the @var{systag} is simply something like @samp{process 368}, with no 2256further qualifier. 2257 2258@c FIXME!! (1) Does the [New...] message appear even for the very first 2259@c thread of a program, or does it only appear for the | 2048@cindex thread identifier (system) 2049@c FIXME-implementors!! It would be more helpful if the [New...] message 2050@c included GDB's numeric thread handle, so you could just go to that 2051@c thread without first checking `info threads'. 2052Whenever @value{GDBN} detects a new thread in your program, it displays 2053the target system's identification for the thread with a message in the 2054form @samp{[New @var{systag}]}. @var{systag} is a thread identifier 2055whose form varies depending on the particular system. For example, on --- 5 unchanged lines hidden (view full) --- 2061 2062@noindent 2063when @value{GDBN} notices a new thread. In contrast, on an SGI system, 2064the @var{systag} is simply something like @samp{process 368}, with no 2065further qualifier. 2066 2067@c FIXME!! (1) Does the [New...] message appear even for the very first 2068@c thread of a program, or does it only appear for the |
| 2260@c second---i.e., when it becomes obvious we have a multithread | 2069@c second---i.e.@: when it becomes obvious we have a multithread |
| 2261@c program? 2262@c (2) *Is* there necessarily a first thread always? Or do some 2263@c multithread systems permit starting a program with multiple | 2070@c program? 2071@c (2) *Is* there necessarily a first thread always? Or do some 2072@c multithread systems permit starting a program with multiple |
| 2264@c threads ab initio? | 2073@c threads ab initio? |
| 2265 2266@cindex thread number 2267@cindex thread identifier (GDB) 2268For debugging purposes, @value{GDBN} associates its own thread 2269number---always a single integer---with each thread in your program. 2270 2271@table @code 2272@kindex info threads --- 8 unchanged lines hidden (view full) --- 2281 2282@item the current stack frame summary for that thread 2283@end enumerate 2284 2285@noindent 2286An asterisk @samp{*} to the left of the @value{GDBN} thread number 2287indicates the current thread. 2288 | 2074 2075@cindex thread number 2076@cindex thread identifier (GDB) 2077For debugging purposes, @value{GDBN} associates its own thread 2078number---always a single integer---with each thread in your program. 2079 2080@table @code 2081@kindex info threads --- 8 unchanged lines hidden (view full) --- 2090 2091@item the current stack frame summary for that thread 2092@end enumerate 2093 2094@noindent 2095An asterisk @samp{*} to the left of the @value{GDBN} thread number 2096indicates the current thread. 2097 |
| 2289For example, | 2098For example, |
| 2290@end table 2291@c end table here to get a little more width for example 2292 2293@smallexample 2294(@value{GDBP}) info threads 2295 3 process 35 thread 27 0x34e5 in sigpause () 2296 2 process 35 thread 23 0x34e5 in sigpause () 2297* 1 process 35 thread 13 main (argc=1, argv=0x7ffffff8) 2298 at threadtest.c:68 2299@end smallexample | 2099@end table 2100@c end table here to get a little more width for example 2101 2102@smallexample 2103(@value{GDBP}) info threads 2104 3 process 35 thread 27 0x34e5 in sigpause () 2105 2 process 35 thread 23 0x34e5 in sigpause () 2106* 1 process 35 thread 13 main (argc=1, argv=0x7ffffff8) 2107 at threadtest.c:68 2108@end smallexample |
| 2300@end ifclear 2301@ifset HPPA | |
| 2302 | 2109 |
| 2110On HP-UX systems: 2111 |
|
| 2303@cindex thread number 2304@cindex thread identifier (GDB) 2305For debugging purposes, @value{GDBN} associates its own thread 2306number---a small integer assigned in thread-creation order---with each 2307thread in your program. 2308 | 2112@cindex thread number 2113@cindex thread identifier (GDB) 2114For debugging purposes, @value{GDBN} associates its own thread 2115number---a small integer assigned in thread-creation order---with each 2116thread in your program. 2117 |
| 2309@kindex New @var{systag} 2310@cindex thread identifier (system) | 2118@cindex @code{New} @var{systag} message, on HP-UX 2119@cindex thread identifier (system), on HP-UX |
| 2311@c FIXME-implementors!! It would be more helpful if the [New...] message 2312@c included GDB's numeric thread handle, so you could just go to that 2313@c thread without first checking `info threads'. 2314Whenever @value{GDBN} detects a new thread in your program, it displays 2315both @value{GDBN}'s thread number and the target system's identification for the thread with a message in the 2316form @samp{[New @var{systag}]}. @var{systag} is a thread identifier 2317whose form varies depending on the particular system. For example, on 2318HP-UX, you see 2319 2320@example 2321[New thread 2 (system thread 26594)] 2322@end example 2323 2324@noindent | 2120@c FIXME-implementors!! It would be more helpful if the [New...] message 2121@c included GDB's numeric thread handle, so you could just go to that 2122@c thread without first checking `info threads'. 2123Whenever @value{GDBN} detects a new thread in your program, it displays 2124both @value{GDBN}'s thread number and the target system's identification for the thread with a message in the 2125form @samp{[New @var{systag}]}. @var{systag} is a thread identifier 2126whose form varies depending on the particular system. For example, on 2127HP-UX, you see 2128 2129@example 2130[New thread 2 (system thread 26594)] 2131@end example 2132 2133@noindent |
| 2325when @value{GDBN} notices a new thread. | 2134when @value{GDBN} notices a new thread. |
| 2326 2327@table @code 2328@kindex info threads 2329@item info threads 2330Display a summary of all threads currently in your 2331program. @value{GDBN} displays for each thread (in this order): 2332 2333@enumerate 2334@item the thread number assigned by @value{GDBN} 2335 2336@item the target system's thread identifier (@var{systag}) 2337 2338@item the current stack frame summary for that thread 2339@end enumerate 2340 2341@noindent 2342An asterisk @samp{*} to the left of the @value{GDBN} thread number 2343indicates the current thread. 2344 | 2135 2136@table @code 2137@kindex info threads 2138@item info threads 2139Display a summary of all threads currently in your 2140program. @value{GDBN} displays for each thread (in this order): 2141 2142@enumerate 2143@item the thread number assigned by @value{GDBN} 2144 2145@item the target system's thread identifier (@var{systag}) 2146 2147@item the current stack frame summary for that thread 2148@end enumerate 2149 2150@noindent 2151An asterisk @samp{*} to the left of the @value{GDBN} thread number 2152indicates the current thread. 2153 |
| 2345For example, | 2154For example, |
| 2346@end table 2347@c end table here to get a little more width for example 2348 2349@example 2350(@value{GDBP}) info threads | 2155@end table 2156@c end table here to get a little more width for example 2157 2158@example 2159(@value{GDBP}) info threads |
| 2351 * 3 system thread 26607 worker (wptr=0x7b09c318 "@@") at quicksort.c:137 2352 2 system thread 26606 0x7b0030d8 in __ksleep () from /usr/lib/libc.2 2353 1 system thread 27905 0x7b003498 in _brk () from /usr/lib/libc.2 | 2160 * 3 system thread 26607 worker (wptr=0x7b09c318 "@@") \@* 2161 at quicksort.c:137 2162 2 system thread 26606 0x7b0030d8 in __ksleep () \@* 2163 from /usr/lib/libc.2 2164 1 system thread 27905 0x7b003498 in _brk () \@* 2165 from /usr/lib/libc.2 |
| 2354@end example | 2166@end example |
| 2355@end ifset | |
| 2356 2357@table @code 2358@kindex thread @var{threadno} 2359@item thread @var{threadno} 2360Make thread number @var{threadno} the current thread. The command 2361argument @var{threadno} is the internal @value{GDBN} thread number, as 2362shown in the first field of the @samp{info threads} display. 2363@value{GDBN} responds by displaying the system identifier of the thread 2364you selected, and its current stack frame summary: 2365 2366@smallexample 2367@c FIXME!! This example made up; find a @value{GDBN} w/threads and get real one 2368(@value{GDBP}) thread 2 | 2167 2168@table @code 2169@kindex thread @var{threadno} 2170@item thread @var{threadno} 2171Make thread number @var{threadno} the current thread. The command 2172argument @var{threadno} is the internal @value{GDBN} thread number, as 2173shown in the first field of the @samp{info threads} display. 2174@value{GDBN} responds by displaying the system identifier of the thread 2175you selected, and its current stack frame summary: 2176 2177@smallexample 2178@c FIXME!! This example made up; find a @value{GDBN} w/threads and get real one 2179(@value{GDBP}) thread 2 |
| 2369@ifclear HPPA | |
| 2370[Switching to process 35 thread 23] | 2180[Switching to process 35 thread 23] |
| 2371@end ifclear 2372@ifset HPPA 2373[Switching to thread 2 (system thread 26594)] 2374@end ifset | |
| 23750x34e5 in sigpause () 2376@end smallexample 2377 2378@noindent 2379As with the @samp{[New @dots{}]} message, the form of the text after 2380@samp{Switching to} depends on your system's conventions for identifying | 21810x34e5 in sigpause () 2182@end smallexample 2183 2184@noindent 2185As with the @samp{[New @dots{}]} message, the form of the text after 2186@samp{Switching to} depends on your system's conventions for identifying |
| 2381threads. | 2187threads. |
| 2382 2383@kindex thread apply 2384@item thread apply [@var{threadno}] [@var{all}] @var{args} 2385The @code{thread apply} command allows you to apply a command to one or 2386more threads. Specify the numbers of the threads that you want affected 2387with the command argument @var{threadno}. @var{threadno} is the internal 2388@value{GDBN} thread number, as shown in the first field of the @samp{info | 2188 2189@kindex thread apply 2190@item thread apply [@var{threadno}] [@var{all}] @var{args} 2191The @code{thread apply} command allows you to apply a command to one or 2192more threads. Specify the numbers of the threads that you want affected 2193with the command argument @var{threadno}. @var{threadno} is the internal 2194@value{GDBN} thread number, as shown in the first field of the @samp{info |
| 2389threads} display. To apply a command to all threads, use 2390@code{thread apply all} @var{args}. | 2195threads} display. To apply a command to all threads, use 2196@code{thread apply all} @var{args}. |
| 2391@end table 2392 2393@cindex automatic thread selection 2394@cindex switching threads automatically 2395@cindex threads, automatic switching 2396Whenever @value{GDBN} stops your program, due to a breakpoint or a 2397signal, it automatically selects the thread where that breakpoint or 2398signal happened. @value{GDBN} alerts you to the context switch with a 2399message of the form @samp{[Switching to @var{systag}]} to identify the 2400thread. 2401 2402@xref{Thread Stops,,Stopping and starting multi-thread programs}, for 2403more information about how @value{GDBN} behaves when you stop and start 2404programs with multiple threads. 2405 2406@xref{Set Watchpoints,,Setting watchpoints}, for information about 2407watchpoints in programs with multiple threads. | 2197@end table 2198 2199@cindex automatic thread selection 2200@cindex switching threads automatically 2201@cindex threads, automatic switching 2202Whenever @value{GDBN} stops your program, due to a breakpoint or a 2203signal, it automatically selects the thread where that breakpoint or 2204signal happened. @value{GDBN} alerts you to the context switch with a 2205message of the form @samp{[Switching to @var{systag}]} to identify the 2206thread. 2207 2208@xref{Thread Stops,,Stopping and starting multi-thread programs}, for 2209more information about how @value{GDBN} behaves when you stop and start 2210programs with multiple threads. 2211 2212@xref{Set Watchpoints,,Setting watchpoints}, for information about 2213watchpoints in programs with multiple threads. |
| 2408@end ifclear | |
| 2409 | 2214 |
| 2410@ifclear HPPA 2411@node Processes, , Threads, Running | 2215@node Processes |
| 2412@section Debugging programs with multiple processes 2413 2414@cindex fork, debugging programs which call 2415@cindex multiple processes 2416@cindex processes, multiple | 2216@section Debugging programs with multiple processes 2217 2218@cindex fork, debugging programs which call 2219@cindex multiple processes 2220@cindex processes, multiple |
| 2417@value{GDBN} has no special support for debugging programs which create 2418additional processes using the @code{fork} function. When a program 2419forks, @value{GDBN} will continue to debug the parent process and the 2420child process will run unimpeded. If you have set a breakpoint in any 2421code which the child then executes, the child will get a @code{SIGTRAP} 2422signal which (unless it catches the signal) will cause it to terminate. | 2221On most systems, @value{GDBN} has no special support for debugging 2222programs which create additional processes using the @code{fork} 2223function. When a program forks, @value{GDBN} will continue to debug the 2224parent process and the child process will run unimpeded. If you have 2225set a breakpoint in any code which the child then executes, the child 2226will get a @code{SIGTRAP} signal which (unless it catches the signal) 2227will cause it to terminate. |
| 2423 2424However, if you want to debug the child process there is a workaround 2425which isn't too painful. Put a call to @code{sleep} in the code which 2426the child process executes after the fork. It may be useful to sleep 2427only if a certain environment variable is set, or a certain file exists, 2428so that the delay need not occur when you don't want to run @value{GDBN} 2429on the child. While the child is sleeping, use the @code{ps} program to 2430get its process ID. Then tell @value{GDBN} (a new invocation of 2431@value{GDBN} if you are also debugging the parent process) to attach to | 2228 2229However, if you want to debug the child process there is a workaround 2230which isn't too painful. Put a call to @code{sleep} in the code which 2231the child process executes after the fork. It may be useful to sleep 2232only if a certain environment variable is set, or a certain file exists, 2233so that the delay need not occur when you don't want to run @value{GDBN} 2234on the child. While the child is sleeping, use the @code{ps} program to 2235get its process ID. Then tell @value{GDBN} (a new invocation of 2236@value{GDBN} if you are also debugging the parent process) to attach to |
| 2432the child process (see @ref{Attach}). From that point on you can debug | 2237the child process (@pxref{Attach}). From that point on you can debug |
| 2433the child process just like any other process which you attached to. | 2238the child process just like any other process which you attached to. |
| 2434@end ifclear 2435@ifset HPPA 2436@node Processes, , Threads, Running 2437@section Debugging programs with multiple processes | |
| 2438 | 2239 |
| 2439@cindex fork, debugging programs which call 2440@cindex multiple processes 2441@cindex processes, multiple | 2240On HP-UX (11.x and later only?), @value{GDBN} provides support for 2241debugging programs that create additional processes using the 2242@code{fork} or @code{vfork} function. |
| 2442 | 2243 |
| 2443@value{GDBN} provides support for debugging programs that create 2444additional processes using the @code{fork} or @code{vfork} function. 2445 | |
| 2446By default, when a program forks, @value{GDBN} will continue to debug 2447the parent process and the child process will run unimpeded. 2448 2449If you want to follow the child process instead of the parent process, 2450use the command @w{@code{set follow-fork-mode}}. 2451 2452@table @code 2453@kindex set follow-fork-mode 2454@item set follow-fork-mode @var{mode} 2455Set the debugger response to a program call of @code{fork} or 2456@code{vfork}. A call to @code{fork} or @code{vfork} creates a new 2457process. The @var{mode} can be: 2458 2459@table @code 2460@item parent 2461The original process is debugged after a fork. The child process runs | 2244By default, when a program forks, @value{GDBN} will continue to debug 2245the parent process and the child process will run unimpeded. 2246 2247If you want to follow the child process instead of the parent process, 2248use the command @w{@code{set follow-fork-mode}}. 2249 2250@table @code 2251@kindex set follow-fork-mode 2252@item set follow-fork-mode @var{mode} 2253Set the debugger response to a program call of @code{fork} or 2254@code{vfork}. A call to @code{fork} or @code{vfork} creates a new 2255process. The @var{mode} can be: 2256 2257@table @code 2258@item parent 2259The original process is debugged after a fork. The child process runs |
| 2462unimpeded. | 2260unimpeded. This is the default. |
| 2463 2464@item child 2465The new process is debugged after a fork. The parent process runs 2466unimpeded. 2467 2468@item ask 2469The debugger will ask for one of the above choices. 2470@end table 2471 2472@item show follow-fork-mode | 2261 2262@item child 2263The new process is debugged after a fork. The parent process runs 2264unimpeded. 2265 2266@item ask 2267The debugger will ask for one of the above choices. 2268@end table 2269 2270@item show follow-fork-mode |
| 2473Display the current debugger response to a fork or vfork call. | 2271Display the current debugger response to a @code{fork} or @code{vfork} call. |
| 2474@end table 2475 2476If you ask to debug a child process and a @code{vfork} is followed by an 2477@code{exec}, @value{GDBN} executes the new target up to the first 2478breakpoint in the new target. If you have a breakpoint set on 2479@code{main} in your original program, the breakpoint will also be set on 2480the child process's @code{main}. 2481 2482When a child process is spawned by @code{vfork}, you cannot debug the 2483child or parent until an @code{exec} call completes. 2484 2485If you issue a @code{run} command to @value{GDBN} after an @code{exec} 2486call executes, the new target restarts. To restart the parent process, 2487use the @code{file} command with the parent executable name as its 2488argument. 2489 2490You can use the @code{catch} command to make @value{GDBN} stop whenever 2491a @code{fork}, @code{vfork}, or @code{exec} call is made. @xref{Set 2492Catchpoints, ,Setting catchpoints}. | 2272@end table 2273 2274If you ask to debug a child process and a @code{vfork} is followed by an 2275@code{exec}, @value{GDBN} executes the new target up to the first 2276breakpoint in the new target. If you have a breakpoint set on 2277@code{main} in your original program, the breakpoint will also be set on 2278the child process's @code{main}. 2279 2280When a child process is spawned by @code{vfork}, you cannot debug the 2281child or parent until an @code{exec} call completes. 2282 2283If you issue a @code{run} command to @value{GDBN} after an @code{exec} 2284call executes, the new target restarts. To restart the parent process, 2285use the @code{file} command with the parent executable name as its 2286argument. 2287 2288You can use the @code{catch} command to make @value{GDBN} stop whenever 2289a @code{fork}, @code{vfork}, or @code{exec} call is made. @xref{Set 2290Catchpoints, ,Setting catchpoints}. |
| 2493@end ifset | |
| 2494 | 2291 |
| 2495@node Stopping, Stack, Running, Top | 2292@node Stopping |
| 2496@chapter Stopping and Continuing 2497 2498The principal purposes of using a debugger are so that you can stop your 2499program before it terminates; or so that, if your program runs into 2500trouble, you can investigate and find out why. 2501 | 2293@chapter Stopping and Continuing 2294 2295The principal purposes of using a debugger are so that you can stop your 2296program before it terminates; or so that, if your program runs into 2297trouble, you can investigate and find out why. 2298 |
| 2502Inside @value{GDBN}, your program may stop for any of several reasons, such 2503as 2504@ifclear BARETARGET 2505a signal, 2506@end ifclear 2507a breakpoint, or reaching a new line after a @value{GDBN} 2508command such as @code{step}. You may then examine and change 2509variables, set new breakpoints or remove old ones, and then continue 2510execution. Usually, the messages shown by @value{GDBN} provide ample 2511explanation of the status of your program---but you can also explicitly 2512request this information at any time. | 2299Inside @value{GDBN}, your program may stop for any of several reasons, 2300such as a signal, a breakpoint, or reaching a new line after a 2301@value{GDBN} command such as @code{step}. You may then examine and 2302change variables, set new breakpoints or remove old ones, and then 2303continue execution. Usually, the messages shown by @value{GDBN} provide 2304ample explanation of the status of your program---but you can also 2305explicitly request this information at any time. |
| 2513 2514@table @code 2515@kindex info program 2516@item info program 2517Display information about the status of your program: whether it is | 2306 2307@table @code 2308@kindex info program 2309@item info program 2310Display information about the status of your program: whether it is |
| 2518running or not, 2519@ifclear BARETARGET 2520what process it is, 2521@end ifclear 2522and why it stopped. | 2311running or not, what process it is, and why it stopped. |
| 2523@end table 2524 2525@menu 2526* Breakpoints:: Breakpoints, watchpoints, and catchpoints 2527* Continuing and Stepping:: Resuming execution | 2312@end table 2313 2314@menu 2315* Breakpoints:: Breakpoints, watchpoints, and catchpoints 2316* Continuing and Stepping:: Resuming execution |
| 2528@ifset POSIX | |
| 2529* Signals:: Signals | 2317* Signals:: Signals |
| 2530@end ifset 2531 2532@ifclear BARETARGET | |
| 2533* Thread Stops:: Stopping and starting multi-thread programs | 2318* Thread Stops:: Stopping and starting multi-thread programs |
| 2534@end ifclear 2535 | |
| 2536@end menu 2537 | 2319@end menu 2320 |
| 2538@node Breakpoints, Continuing and Stepping, Stopping, Stopping | 2321@node Breakpoints |
| 2539@section Breakpoints, watchpoints, and catchpoints 2540 2541@cindex breakpoints 2542A @dfn{breakpoint} makes your program stop whenever a certain point in 2543the program is reached. For each breakpoint, you can add conditions to 2544control in finer detail whether your program stops. You can set 2545breakpoints with the @code{break} command and its variants (@pxref{Set 2546Breaks, ,Setting breakpoints}), to specify the place where your program --- 20 unchanged lines hidden (view full) --- 2567 2568You can arrange to have values from your program displayed automatically 2569whenever @value{GDBN} stops at a breakpoint. @xref{Auto Display,, 2570Automatic display}. 2571 2572@cindex catchpoints 2573@cindex breakpoint on events 2574A @dfn{catchpoint} is another special breakpoint that stops your program | 2322@section Breakpoints, watchpoints, and catchpoints 2323 2324@cindex breakpoints 2325A @dfn{breakpoint} makes your program stop whenever a certain point in 2326the program is reached. For each breakpoint, you can add conditions to 2327control in finer detail whether your program stops. You can set 2328breakpoints with the @code{break} command and its variants (@pxref{Set 2329Breaks, ,Setting breakpoints}), to specify the place where your program --- 20 unchanged lines hidden (view full) --- 2350 2351You can arrange to have values from your program displayed automatically 2352whenever @value{GDBN} stops at a breakpoint. @xref{Auto Display,, 2353Automatic display}. 2354 2355@cindex catchpoints 2356@cindex breakpoint on events 2357A @dfn{catchpoint} is another special breakpoint that stops your program |
| 2575when a certain kind of event occurs, such as the throwing of a C++ | 2358when a certain kind of event occurs, such as the throwing of a C@t{++} |
| 2576exception or the loading of a library. As with watchpoints, you use a 2577different command to set a catchpoint (@pxref{Set Catchpoints, ,Setting 2578catchpoints}), but aside from that, you can manage a catchpoint like any 2579other breakpoint. (To stop when your program receives a signal, use the | 2359exception or the loading of a library. As with watchpoints, you use a 2360different command to set a catchpoint (@pxref{Set Catchpoints, ,Setting 2361catchpoints}), but aside from that, you can manage a catchpoint like any 2362other breakpoint. (To stop when your program receives a signal, use the |
| 2580@code{handle} command; @pxref{Signals, ,Signals}.) | 2363@code{handle} command; see @ref{Signals, ,Signals}.) |
| 2581 2582@cindex breakpoint numbers 2583@cindex numbers for breakpoints 2584@value{GDBN} assigns a number to each breakpoint, watchpoint, or 2585catchpoint when you create it; these numbers are successive integers 2586starting with one. In many of the commands for controlling various 2587features of breakpoints you use the breakpoint number to say which 2588breakpoint you want to change. Each breakpoint may be @dfn{enabled} or 2589@dfn{disabled}; if disabled, it has no effect on your program until you 2590enable it again. 2591 | 2364 2365@cindex breakpoint numbers 2366@cindex numbers for breakpoints 2367@value{GDBN} assigns a number to each breakpoint, watchpoint, or 2368catchpoint when you create it; these numbers are successive integers 2369starting with one. In many of the commands for controlling various 2370features of breakpoints you use the breakpoint number to say which 2371breakpoint you want to change. Each breakpoint may be @dfn{enabled} or 2372@dfn{disabled}; if disabled, it has no effect on your program until you 2373enable it again. 2374 |
| 2375@cindex breakpoint ranges 2376@cindex ranges of breakpoints 2377Some @value{GDBN} commands accept a range of breakpoints on which to 2378operate. A breakpoint range is either a single breakpoint number, like 2379@samp{5}, or two such numbers, in increasing order, separated by a 2380hyphen, like @samp{5-7}. When a breakpoint range is given to a command, 2381all breakpoint in that range are operated on. 2382 |
|
| 2592@menu 2593* Set Breaks:: Setting breakpoints 2594* Set Watchpoints:: Setting watchpoints 2595* Set Catchpoints:: Setting catchpoints 2596* Delete Breaks:: Deleting breakpoints 2597* Disabling:: Disabling breakpoints 2598* Conditions:: Break conditions 2599* Break Commands:: Breakpoint command lists | 2383@menu 2384* Set Breaks:: Setting breakpoints 2385* Set Watchpoints:: Setting watchpoints 2386* Set Catchpoints:: Setting catchpoints 2387* Delete Breaks:: Deleting breakpoints 2388* Disabling:: Disabling breakpoints 2389* Conditions:: Break conditions 2390* Break Commands:: Breakpoint command lists |
| 2600@ifclear CONLY | |
| 2601* Breakpoint Menus:: Breakpoint menus | 2391* Breakpoint Menus:: Breakpoint menus |
| 2602@end ifclear 2603 2604@c @ifclear BARETARGET 2605@c * Error in Breakpoints:: ``Cannot insert breakpoints'' 2606@c @end ifclear | 2392* Error in Breakpoints:: ``Cannot insert breakpoints'' |
| 2607@end menu 2608 | 2393@end menu 2394 |
| 2609@node Set Breaks, Set Watchpoints, Breakpoints, Breakpoints | 2395@node Set Breaks |
| 2610@subsection Setting breakpoints 2611 | 2396@subsection Setting breakpoints 2397 |
| 2612@c FIXME LMB what does GDB do if no code on line of breakpt? | 2398@c FIXME LMB what does GDB do if no code on line of breakpt? |
| 2613@c consider in particular declaration with/without initialization. 2614@c 2615@c FIXME 2 is there stuff on this already? break at fun start, already init? 2616 2617@kindex break | 2399@c consider in particular declaration with/without initialization. 2400@c 2401@c FIXME 2 is there stuff on this already? break at fun start, already init? 2402 2403@kindex break |
| 2618@kindex b 2619@kindex $bpnum | 2404@kindex b @r{(@code{break})} 2405@vindex $bpnum@r{, convenience variable} |
| 2620@cindex latest breakpoint 2621Breakpoints are set with the @code{break} command (abbreviated | 2406@cindex latest breakpoint 2407Breakpoints are set with the @code{break} command (abbreviated |
| 2622@code{b}). The debugger convenience variable @samp{$bpnum} records the 2623number of the breakpoints you've set most recently; see @ref{Convenience | 2408@code{b}). The debugger convenience variable @samp{$bpnum} records the 2409number of the breakpoint you've set most recently; see @ref{Convenience |
| 2624Vars,, Convenience variables}, for a discussion of what you can do with 2625convenience variables. 2626 2627You have several ways to say where the breakpoint should go. 2628 2629@table @code 2630@item break @var{function} | 2410Vars,, Convenience variables}, for a discussion of what you can do with 2411convenience variables. 2412 2413You have several ways to say where the breakpoint should go. 2414 2415@table @code 2416@item break @var{function} |
| 2631Set a breakpoint at entry to function @var{function}. 2632@ifclear CONLY | 2417Set a breakpoint at entry to function @var{function}. |
| 2633When using source languages that permit overloading of symbols, such as | 2418When using source languages that permit overloading of symbols, such as |
| 2634C++, @var{function} may refer to more than one possible place to break. | 2419C@t{++}, @var{function} may refer to more than one possible place to break. |
| 2635@xref{Breakpoint Menus,,Breakpoint menus}, for a discussion of that situation. | 2420@xref{Breakpoint Menus,,Breakpoint menus}, for a discussion of that situation. |
| 2636@end ifclear | |
| 2637 2638@item break +@var{offset} 2639@itemx break -@var{offset} 2640Set a breakpoint some number of lines forward or back from the position | 2421 2422@item break +@var{offset} 2423@itemx break -@var{offset} 2424Set a breakpoint some number of lines forward or back from the position |
| 2641at which execution stopped in the currently selected frame. | 2425at which execution stopped in the currently selected @dfn{stack frame}. 2426(@xref{Frames, ,Frames}, for a description of stack frames.) |
| 2642 2643@item break @var{linenum} 2644Set a breakpoint at line @var{linenum} in the current source file. | 2427 2428@item break @var{linenum} 2429Set a breakpoint at line @var{linenum} in the current source file. |
| 2645That file is the last file whose source text was printed. This 2646breakpoint stops your program just before it executes any of the | 2430The current source file is the last file whose source text was printed. 2431The breakpoint will stop your program just before it executes any of the |
| 2647code on that line. 2648 2649@item break @var{filename}:@var{linenum} 2650Set a breakpoint at line @var{linenum} in source file @var{filename}. 2651 2652@item break @var{filename}:@var{function} 2653Set a breakpoint at entry to function @var{function} found in file 2654@var{filename}. Specifying a file name as well as a function name is --- 33 unchanged lines hidden (view full) --- 2688 2689@kindex tbreak 2690@item tbreak @var{args} 2691Set a breakpoint enabled only for one stop. @var{args} are the 2692same as for the @code{break} command, and the breakpoint is set in the same 2693way, but the breakpoint is automatically deleted after the first time your 2694program stops there. @xref{Disabling, ,Disabling breakpoints}. 2695 | 2432code on that line. 2433 2434@item break @var{filename}:@var{linenum} 2435Set a breakpoint at line @var{linenum} in source file @var{filename}. 2436 2437@item break @var{filename}:@var{function} 2438Set a breakpoint at entry to function @var{function} found in file 2439@var{filename}. Specifying a file name as well as a function name is --- 33 unchanged lines hidden (view full) --- 2473 2474@kindex tbreak 2475@item tbreak @var{args} 2476Set a breakpoint enabled only for one stop. @var{args} are the 2477same as for the @code{break} command, and the breakpoint is set in the same 2478way, but the breakpoint is automatically deleted after the first time your 2479program stops there. @xref{Disabling, ,Disabling breakpoints}. 2480 |
| 2696@ifclear HPPA | |
| 2697@kindex hbreak 2698@item hbreak @var{args} | 2481@kindex hbreak 2482@item hbreak @var{args} |
| 2699Set a hardware-assisted breakpoint. @var{args} are the same as for the 2700@code{break} command and the breakpoint is set in the same way, but the | 2483Set a hardware-assisted breakpoint. @var{args} are the same as for the 2484@code{break} command and the breakpoint is set in the same way, but the |
| 2701breakpoint requires hardware support and some target hardware may not 2702have this support. The main purpose of this is EPROM/ROM code | 2485breakpoint requires hardware support and some target hardware may not 2486have this support. The main purpose of this is EPROM/ROM code |
| 2703debugging, so you can set a breakpoint at an instruction without 2704changing the instruction. This can be used with the new trap-generation 2705provided by SPARClite DSU. DSU will generate traps when a program accesses 2706some data or instruction address that is assigned to the debug registers. 2707However the hardware breakpoint registers can only take two data breakpoints, 2708and @value{GDBN} will reject this command if more than two are used. 2709Delete or disable unused hardware breakpoints before setting 2710new ones. @xref{Conditions, ,Break conditions}. | 2487debugging, so you can set a breakpoint at an instruction without 2488changing the instruction. This can be used with the new trap-generation 2489provided by SPARClite DSU and some x86-based targets. These targets 2490will generate traps when a program accesses some data or instruction 2491address that is assigned to the debug registers. However the hardware 2492breakpoint registers can take a limited number of breakpoints. For 2493example, on the DSU, only two data breakpoints can be set at a time, and 2494@value{GDBN} will reject this command if more than two are used. Delete 2495or disable unused hardware breakpoints before setting new ones 2496(@pxref{Disabling, ,Disabling}). @xref{Conditions, ,Break conditions}. |
| 2711 2712@kindex thbreak 2713@item thbreak @var{args} 2714Set a hardware-assisted breakpoint enabled only for one stop. @var{args} 2715are the same as for the @code{hbreak} command and the breakpoint is set in | 2497 2498@kindex thbreak 2499@item thbreak @var{args} 2500Set a hardware-assisted breakpoint enabled only for one stop. @var{args} 2501are the same as for the @code{hbreak} command and the breakpoint is set in |
| 2716the same way. However, like the @code{tbreak} command, | 2502the same way. However, like the @code{tbreak} command, |
| 2717the breakpoint is automatically deleted after the 2718first time your program stops there. Also, like the @code{hbreak} | 2503the breakpoint is automatically deleted after the 2504first time your program stops there. Also, like the @code{hbreak} |
| 2719command, the breakpoint requires hardware support and some target hardware 2720may not have this support. @xref{Disabling, ,Disabling breakpoints}. 2721Also @xref{Conditions, ,Break conditions}. 2722@end ifclear | 2505command, the breakpoint requires hardware support and some target hardware 2506may not have this support. @xref{Disabling, ,Disabling breakpoints}. 2507See also @ref{Conditions, ,Break conditions}. |
| 2723 2724@kindex rbreak 2725@cindex regular expression 2726@item rbreak @var{regex} | 2508 2509@kindex rbreak 2510@cindex regular expression 2511@item rbreak @var{regex} |
| 2727@c FIXME what kind of regexp? | |
| 2728Set breakpoints on all functions matching the regular expression | 2512Set breakpoints on all functions matching the regular expression |
| 2729@var{regex}. This command 2730sets an unconditional breakpoint on all matches, printing a list of all 2731breakpoints it set. Once these breakpoints are set, they are treated 2732just like the breakpoints set with the @code{break} command. You can 2733delete them, disable them, or make them conditional the same way as any 2734other breakpoint. | 2513@var{regex}. This command sets an unconditional breakpoint on all 2514matches, printing a list of all breakpoints it set. Once these 2515breakpoints are set, they are treated just like the breakpoints set with 2516the @code{break} command. You can delete them, disable them, or make 2517them conditional the same way as any other breakpoint. |
| 2735 | 2518 |
| 2736@ifclear CONLY 2737When debugging C++ programs, @code{rbreak} is useful for setting | 2519The syntax of the regular expression is the standard one used with tools 2520like @file{grep}. Note that this is different from the syntax used by 2521shells, so for instance @code{foo*} matches all functions that include 2522an @code{fo} followed by zero or more @code{o}s. There is an implicit 2523@code{.*} leading and trailing the regular expression you supply, so to 2524match only functions that begin with @code{foo}, use @code{^foo}. 2525 2526When debugging C@t{++} programs, @code{rbreak} is useful for setting |
| 2738breakpoints on overloaded functions that are not members of any special 2739classes. | 2527breakpoints on overloaded functions that are not members of any special 2528classes. |
| 2740@end ifclear | |
| 2741 2742@kindex info breakpoints 2743@cindex @code{$_} and @code{info breakpoints} 2744@item info breakpoints @r{[}@var{n}@r{]} 2745@itemx info break @r{[}@var{n}@r{]} 2746@itemx info watchpoints @r{[}@var{n}@r{]} 2747Print a table of all breakpoints, watchpoints, and catchpoints set and 2748not deleted, with the following columns for each breakpoint: 2749 2750@table @emph 2751@item Breakpoint Numbers 2752@item Type 2753Breakpoint, watchpoint, or catchpoint. 2754@item Disposition 2755Whether the breakpoint is marked to be disabled or deleted when hit. 2756@item Enabled or Disabled 2757Enabled breakpoints are marked with @samp{y}. @samp{n} marks breakpoints 2758that are not enabled. 2759@item Address | 2529 2530@kindex info breakpoints 2531@cindex @code{$_} and @code{info breakpoints} 2532@item info breakpoints @r{[}@var{n}@r{]} 2533@itemx info break @r{[}@var{n}@r{]} 2534@itemx info watchpoints @r{[}@var{n}@r{]} 2535Print a table of all breakpoints, watchpoints, and catchpoints set and 2536not deleted, with the following columns for each breakpoint: 2537 2538@table @emph 2539@item Breakpoint Numbers 2540@item Type 2541Breakpoint, watchpoint, or catchpoint. 2542@item Disposition 2543Whether the breakpoint is marked to be disabled or deleted when hit. 2544@item Enabled or Disabled 2545Enabled breakpoints are marked with @samp{y}. @samp{n} marks breakpoints 2546that are not enabled. 2547@item Address |
| 2760Where the breakpoint is in your program, as a memory address | 2548Where the breakpoint is in your program, as a memory address. |
| 2761@item What 2762Where the breakpoint is in the source for your program, as a file and 2763line number. 2764@end table 2765 2766@noindent 2767If a breakpoint is conditional, @code{info break} shows the condition on 2768the line following the affected breakpoint; breakpoint commands, if any, 2769are listed after that. 2770 2771@noindent 2772@code{info break} with a breakpoint 2773number @var{n} as argument lists only that breakpoint. The 2774convenience variable @code{$_} and the default examining-address for 2775the @code{x} command are set to the address of the last breakpoint | 2549@item What 2550Where the breakpoint is in the source for your program, as a file and 2551line number. 2552@end table 2553 2554@noindent 2555If a breakpoint is conditional, @code{info break} shows the condition on 2556the line following the affected breakpoint; breakpoint commands, if any, 2557are listed after that. 2558 2559@noindent 2560@code{info break} with a breakpoint 2561number @var{n} as argument lists only that breakpoint. The 2562convenience variable @code{$_} and the default examining-address for 2563the @code{x} command are set to the address of the last breakpoint |
| 2776listed (@pxref{Memory, ,Examining memory}). | 2564listed (@pxref{Memory, ,Examining memory}). |
| 2777 2778@noindent 2779@code{info break} displays a count of the number of times the breakpoint 2780has been hit. This is especially useful in conjunction with the 2781@code{ignore} command. You can ignore a large number of breakpoint 2782hits, look at the breakpoint info to see how many times the breakpoint 2783was hit, and then run again, ignoring one less than that number. This 2784will get you quickly to the last hit of that breakpoint. 2785@end table 2786 2787@value{GDBN} allows you to set any number of breakpoints at the same place in 2788your program. There is nothing silly or meaningless about this. When 2789the breakpoints are conditional, this is even useful 2790(@pxref{Conditions, ,Break conditions}). 2791 2792@cindex negative breakpoint numbers 2793@cindex internal @value{GDBN} breakpoints | 2565 2566@noindent 2567@code{info break} displays a count of the number of times the breakpoint 2568has been hit. This is especially useful in conjunction with the 2569@code{ignore} command. You can ignore a large number of breakpoint 2570hits, look at the breakpoint info to see how many times the breakpoint 2571was hit, and then run again, ignoring one less than that number. This 2572will get you quickly to the last hit of that breakpoint. 2573@end table 2574 2575@value{GDBN} allows you to set any number of breakpoints at the same place in 2576your program. There is nothing silly or meaningless about this. When 2577the breakpoints are conditional, this is even useful 2578(@pxref{Conditions, ,Break conditions}). 2579 2580@cindex negative breakpoint numbers 2581@cindex internal @value{GDBN} breakpoints |
| 2794@value{GDBN} itself sometimes sets breakpoints in your program for special 2795purposes, such as proper handling of @code{longjmp} (in C programs). 2796These internal breakpoints are assigned negative numbers, starting with 2797@code{-1}; @samp{info breakpoints} does not display them. 2798 | 2582@value{GDBN} itself sometimes sets breakpoints in your program for 2583special purposes, such as proper handling of @code{longjmp} (in C 2584programs). These internal breakpoints are assigned negative numbers, 2585starting with @code{-1}; @samp{info breakpoints} does not display them. |
| 2799You can see these breakpoints with the @value{GDBN} maintenance command | 2586You can see these breakpoints with the @value{GDBN} maintenance command |
| 2800@samp{maint info breakpoints}. | 2587@samp{maint info breakpoints} (@pxref{maint info breakpoints}). |
| 2801 | 2588 |
| 2802@table @code 2803@kindex maint info breakpoints 2804@item maint info breakpoints 2805Using the same format as @samp{info breakpoints}, display both the 2806breakpoints you've set explicitly, and those @value{GDBN} is using for 2807internal purposes. Internal breakpoints are shown with negative 2808breakpoint numbers. The type column identifies what kind of breakpoint 2809is shown: | |
| 2810 | 2589 |
| 2811@table @code 2812@item breakpoint 2813Normal, explicitly set breakpoint. 2814 2815@item watchpoint 2816Normal, explicitly set watchpoint. 2817 2818@item longjmp 2819Internal breakpoint, used to handle correctly stepping through 2820@code{longjmp} calls. 2821 2822@item longjmp resume 2823Internal breakpoint at the target of a @code{longjmp}. 2824 2825@item until 2826Temporary internal breakpoint used by the @value{GDBN} @code{until} command. 2827 2828@item finish 2829Temporary internal breakpoint used by the @value{GDBN} @code{finish} command. 2830 2831@ifset HPPA 2832@item shlib events 2833Shared library events. 2834@end ifset 2835@end table 2836@end table 2837 2838 2839@node Set Watchpoints, Set Catchpoints, Set Breaks, Breakpoints | 2590@node Set Watchpoints |
| 2840@subsection Setting watchpoints 2841 2842@cindex setting watchpoints 2843@cindex software watchpoints 2844@cindex hardware watchpoints 2845You can use a watchpoint to stop execution whenever the value of an 2846expression changes, without having to predict a particular place where 2847this may happen. 2848 2849Depending on your system, watchpoints may be implemented in software or | 2591@subsection Setting watchpoints 2592 2593@cindex setting watchpoints 2594@cindex software watchpoints 2595@cindex hardware watchpoints 2596You can use a watchpoint to stop execution whenever the value of an 2597expression changes, without having to predict a particular place where 2598this may happen. 2599 2600Depending on your system, watchpoints may be implemented in software or |
| 2850hardware. GDB does software watchpointing by single-stepping your | 2601hardware. @value{GDBN} does software watchpointing by single-stepping your |
| 2851program and testing the variable's value each time, which is hundreds of 2852times slower than normal execution. (But this may still be worth it, to 2853catch errors where you have no clue what part of your program is the 2854culprit.) 2855 | 2602program and testing the variable's value each time, which is hundreds of 2603times slower than normal execution. (But this may still be worth it, to 2604catch errors where you have no clue what part of your program is the 2605culprit.) 2606 |
| 2856On some systems, such as HP-UX and Linux, GDB includes support for | 2607On some systems, such as HP-UX, Linux and some other x86-based targets, 2608@value{GDBN} includes support for |
| 2857hardware watchpoints, which do not slow down the running of your 2858program. 2859 2860@table @code 2861@kindex watch 2862@item watch @var{expr} 2863Set a watchpoint for an expression. @value{GDBN} will break when @var{expr} 2864is written into by the program and its value changes. 2865 2866@kindex rwatch 2867@item rwatch @var{expr} 2868Set a watchpoint that will break when watch @var{expr} is read by the program. | 2609hardware watchpoints, which do not slow down the running of your 2610program. 2611 2612@table @code 2613@kindex watch 2614@item watch @var{expr} 2615Set a watchpoint for an expression. @value{GDBN} will break when @var{expr} 2616is written into by the program and its value changes. 2617 2618@kindex rwatch 2619@item rwatch @var{expr} 2620Set a watchpoint that will break when watch @var{expr} is read by the program. |
| 2869If you use both watchpoints, both must be set with the @code{rwatch} 2870command. | |
| 2871 2872@kindex awatch 2873@item awatch @var{expr} | 2621 2622@kindex awatch 2623@item awatch @var{expr} |
| 2874Set a watchpoint that will break when @var{args} is read and written into 2875by the program. If you use both watchpoints, both must be set with the 2876@code{awatch} command. | 2624Set a watchpoint that will break when @var{expr} is either read or written into 2625by the program. |
| 2877 2878@kindex info watchpoints 2879@item info watchpoints 2880This command prints a list of watchpoints, breakpoints, and catchpoints; 2881it is the same as @code{info break}. 2882@end table 2883 2884@value{GDBN} sets a @dfn{hardware watchpoint} if possible. Hardware --- 7 unchanged lines hidden (view full) --- 2892 2893@example 2894Hardware watchpoint @var{num}: @var{expr} 2895@end example 2896 2897@noindent 2898if it was able to set a hardware watchpoint. 2899 | 2626 2627@kindex info watchpoints 2628@item info watchpoints 2629This command prints a list of watchpoints, breakpoints, and catchpoints; 2630it is the same as @code{info break}. 2631@end table 2632 2633@value{GDBN} sets a @dfn{hardware watchpoint} if possible. Hardware --- 7 unchanged lines hidden (view full) --- 2641 2642@example 2643Hardware watchpoint @var{num}: @var{expr} 2644@end example 2645 2646@noindent 2647if it was able to set a hardware watchpoint. 2648 |
| 2900The SPARClite DSU will generate traps when a program accesses 2901some data or instruction address that is assigned to the debug registers. 2902For the data addresses, DSU facilitates the @code{watch} command. 2903However the hardware breakpoint registers can only take two data watchpoints, 2904and both watchpoints must be the same kind. For example, you can set two 2905watchpoints with @code{watch} commands, two with @code{rwatch} 2906commands, @strong{or} two with @code{awatch} commands, but you cannot set one 2907watchpoint with one command and the other with a different command. | 2649Currently, the @code{awatch} and @code{rwatch} commands can only set 2650hardware watchpoints, because accesses to data that don't change the 2651value of the watched expression cannot be detected without examining 2652every instruction as it is being executed, and @value{GDBN} does not do 2653that currently. If @value{GDBN} finds that it is unable to set a 2654hardware breakpoint with the @code{awatch} or @code{rwatch} command, it 2655will print a message like this: 2656 2657@smallexample 2658Expression cannot be implemented with read/access watchpoint. 2659@end smallexample 2660 2661Sometimes, @value{GDBN} cannot set a hardware watchpoint because the 2662data type of the watched expression is wider than what a hardware 2663watchpoint on the target machine can handle. For example, some systems 2664can only watch regions that are up to 4 bytes wide; on such systems you 2665cannot set hardware watchpoints for an expression that yields a 2666double-precision floating-point number (which is typically 8 bytes 2667wide). As a work-around, it might be possible to break the large region 2668into a series of smaller ones and watch them with separate watchpoints. 2669 2670If you set too many hardware watchpoints, @value{GDBN} might be unable 2671to insert all of them when you resume the execution of your program. 2672Since the precise number of active watchpoints is unknown until such 2673time as the program is about to be resumed, @value{GDBN} might not be 2674able to warn you about this when you set the watchpoints, and the 2675warning will be printed only when the program is resumed: 2676 2677@smallexample 2678Hardware watchpoint @var{num}: Could not insert watchpoint 2679@end smallexample 2680 2681@noindent 2682If this happens, delete or disable some of the watchpoints. 2683 2684The SPARClite DSU will generate traps when a program accesses some data 2685or instruction address that is assigned to the debug registers. For the 2686data addresses, DSU facilitates the @code{watch} command. However the 2687hardware breakpoint registers can only take two data watchpoints, and 2688both watchpoints must be the same kind. For example, you can set two 2689watchpoints with @code{watch} commands, two with @code{rwatch} commands, 2690@strong{or} two with @code{awatch} commands, but you cannot set one 2691watchpoint with one command and the other with a different command. |
| 2908@value{GDBN} will reject the command if you try to mix watchpoints. 2909Delete or disable unused watchpoint commands before setting new ones. 2910 2911If you call a function interactively using @code{print} or @code{call}, | 2692@value{GDBN} will reject the command if you try to mix watchpoints. 2693Delete or disable unused watchpoint commands before setting new ones. 2694 2695If you call a function interactively using @code{print} or @code{call}, |
| 2912any watchpoints you have set will be inactive until GDB reaches another | 2696any watchpoints you have set will be inactive until @value{GDBN} reaches another |
| 2913kind of breakpoint or the call completes. 2914 | 2697kind of breakpoint or the call completes. 2698 |
| 2915@ifclear BARETARGET | 2699@value{GDBN} automatically deletes watchpoints that watch local 2700(automatic) variables, or expressions that involve such variables, when 2701they go out of scope, that is, when the execution leaves the block in 2702which these variables were defined. In particular, when the program 2703being debugged terminates, @emph{all} local variables go out of scope, 2704and so only watchpoints that watch global variables remain set. If you 2705rerun the program, you will need to set all such watchpoints again. One 2706way of doing that would be to set a code breakpoint at the entry to the 2707@code{main} function and when it breaks, set all the watchpoints. 2708 |
| 2916@quotation 2917@cindex watchpoints and threads 2918@cindex threads and watchpoints | 2709@quotation 2710@cindex watchpoints and threads 2711@cindex threads and watchpoints |
| 2919@ifclear HPPA | |
| 2920@emph{Warning:} In multi-thread programs, watchpoints have only limited 2921usefulness. With the current watchpoint implementation, @value{GDBN} 2922can only watch the value of an expression @emph{in a single thread}. If 2923you are confident that the expression can only change due to the current 2924thread's activity (and if you are also confident that no other thread 2925can become current), then you can use watchpoints as usual. However, 2926@value{GDBN} may not notice when a non-current thread's activity changes 2927the expression. | 2712@emph{Warning:} In multi-thread programs, watchpoints have only limited 2713usefulness. With the current watchpoint implementation, @value{GDBN} 2714can only watch the value of an expression @emph{in a single thread}. If 2715you are confident that the expression can only change due to the current 2716thread's activity (and if you are also confident that no other thread 2717can become current), then you can use watchpoints as usual. However, 2718@value{GDBN} may not notice when a non-current thread's activity changes 2719the expression. |
| 2928@end ifclear 2929@ifset HPPA 2930@emph{Warning:} In multi-thread programs, software watchpoints have only 2931limited usefulness. If @value{GDBN} creates a software watchpoint, it 2932can only watch the value of an expression @emph{in a single thread}. If 2933you are confident that the expression can only change due to the current 2934thread's activity (and if you are also confident that no other thread 2935can become current), then you can use software watchpoints as usual. 2936However, @value{GDBN} may not notice when a non-current thread's 2937activity changes the expression. (Hardware watchpoints, in contrast, 2938watch an expression in all threads.) 2939@end ifset | 2720 2721@c FIXME: this is almost identical to the previous paragraph. 2722@emph{HP-UX Warning:} In multi-thread programs, software watchpoints 2723have only limited usefulness. If @value{GDBN} creates a software 2724watchpoint, it can only watch the value of an expression @emph{in a 2725single thread}. If you are confident that the expression can only 2726change due to the current thread's activity (and if you are also 2727confident that no other thread can become current), then you can use 2728software watchpoints as usual. However, @value{GDBN} may not notice 2729when a non-current thread's activity changes the expression. (Hardware 2730watchpoints, in contrast, watch an expression in all threads.) |
| 2940@end quotation | 2731@end quotation |
| 2941@end ifclear | |
| 2942 | 2732 |
| 2943@node Set Catchpoints, Delete Breaks, Set Watchpoints, Breakpoints | 2733@node Set Catchpoints |
| 2944@subsection Setting catchpoints | 2734@subsection Setting catchpoints |
| 2945@cindex catchpoints | 2735@cindex catchpoints, setting |
| 2946@cindex exception handlers 2947@cindex event handling 2948 2949You can use @dfn{catchpoints} to cause the debugger to stop for certain | 2736@cindex exception handlers 2737@cindex event handling 2738 2739You can use @dfn{catchpoints} to cause the debugger to stop for certain |
| 2950kinds of program events, such as C++ exceptions or the loading of a | 2740kinds of program events, such as C@t{++} exceptions or the loading of a |
| 2951shared library. Use the @code{catch} command to set a catchpoint. 2952 2953@table @code 2954@kindex catch 2955@item catch @var{event} 2956Stop when @var{event} occurs. @var{event} can be any of the following: 2957@table @code 2958@item throw 2959@kindex catch throw | 2741shared library. Use the @code{catch} command to set a catchpoint. 2742 2743@table @code 2744@kindex catch 2745@item catch @var{event} 2746Stop when @var{event} occurs. @var{event} can be any of the following: 2747@table @code 2748@item throw 2749@kindex catch throw |
| 2960The throwing of a C++ exception. | 2750The throwing of a C@t{++} exception. |
| 2961 2962@item catch 2963@kindex catch catch | 2751 2752@item catch 2753@kindex catch catch |
| 2964The catching of a C++ exception. | 2754The catching of a C@t{++} exception. |
| 2965 2966@item exec 2967@kindex catch exec 2968A call to @code{exec}. This is currently only available for HP-UX. 2969 2970@item fork 2971@kindex catch fork 2972A call to @code{fork}. This is currently only available for HP-UX. --- 18 unchanged lines hidden (view full) --- 2991@item tcatch @var{event} 2992Set a catchpoint that is enabled only for one stop. The catchpoint is 2993automatically deleted after the first time the event is caught. 2994 2995@end table 2996 2997Use the @code{info break} command to list the current catchpoints. 2998 | 2755 2756@item exec 2757@kindex catch exec 2758A call to @code{exec}. This is currently only available for HP-UX. 2759 2760@item fork 2761@kindex catch fork 2762A call to @code{fork}. This is currently only available for HP-UX. --- 18 unchanged lines hidden (view full) --- 2781@item tcatch @var{event} 2782Set a catchpoint that is enabled only for one stop. The catchpoint is 2783automatically deleted after the first time the event is caught. 2784 2785@end table 2786 2787Use the @code{info break} command to list the current catchpoints. 2788 |
| 2999There are currently some limitations to C++ exception handling | 2789There are currently some limitations to C@t{++} exception handling |
| 3000(@code{catch throw} and @code{catch catch}) in @value{GDBN}: 3001 3002@itemize @bullet 3003@item 3004If you call a function interactively, @value{GDBN} normally returns 3005control to you when the function has finished executing. If the call 3006raises an exception, however, the call may bypass the mechanism that 3007returns control to you and cause your program either to abort or to --- 13 unchanged lines hidden (view full) --- 3021Sometimes @code{catch} is not the best way to debug exception handling: 3022if you need to know exactly where an exception is raised, it is better to 3023stop @emph{before} the exception handler is called, since that way you 3024can see the stack before any unwinding takes place. If you set a 3025breakpoint in an exception handler instead, it may not be easy to find 3026out where the exception was raised. 3027 3028To stop just before an exception handler is called, you need some | 2790(@code{catch throw} and @code{catch catch}) in @value{GDBN}: 2791 2792@itemize @bullet 2793@item 2794If you call a function interactively, @value{GDBN} normally returns 2795control to you when the function has finished executing. If the call 2796raises an exception, however, the call may bypass the mechanism that 2797returns control to you and cause your program either to abort or to --- 13 unchanged lines hidden (view full) --- 2811Sometimes @code{catch} is not the best way to debug exception handling: 2812if you need to know exactly where an exception is raised, it is better to 2813stop @emph{before} the exception handler is called, since that way you 2814can see the stack before any unwinding takes place. If you set a 2815breakpoint in an exception handler instead, it may not be easy to find 2816out where the exception was raised. 2817 2818To stop just before an exception handler is called, you need some |
| 3029knowledge of the implementation. In the case of @sc{gnu} C++, exceptions are | 2819knowledge of the implementation. In the case of @sc{gnu} C@t{++}, exceptions are |
| 3030raised by calling a library function named @code{__raise_exception} 3031which has the following ANSI C interface: 3032 3033@example 3034 /* @var{addr} is where the exception identifier is stored. | 2820raised by calling a library function named @code{__raise_exception} 2821which has the following ANSI C interface: 2822 2823@example 2824 /* @var{addr} is where the exception identifier is stored. |
| 3035 ID is the exception identifier. */ 3036 void __raise_exception (void **@var{addr}, void *@var{id}); | 2825 @var{id} is the exception identifier. */ 2826 void __raise_exception (void **addr, void *id); |
| 3037@end example 3038 3039@noindent 3040To make the debugger catch all exceptions before any stack 3041unwinding takes place, set a breakpoint on @code{__raise_exception} 3042(@pxref{Breakpoints, ,Breakpoints; watchpoints; and exceptions}). 3043 3044With a conditional breakpoint (@pxref{Conditions, ,Break conditions}) 3045that depends on the value of @var{id}, you can stop your program when 3046a specific exception is raised. You can use multiple conditional 3047breakpoints to stop your program when any of a number of exceptions are 3048raised. 3049 3050 | 2827@end example 2828 2829@noindent 2830To make the debugger catch all exceptions before any stack 2831unwinding takes place, set a breakpoint on @code{__raise_exception} 2832(@pxref{Breakpoints, ,Breakpoints; watchpoints; and exceptions}). 2833 2834With a conditional breakpoint (@pxref{Conditions, ,Break conditions}) 2835that depends on the value of @var{id}, you can stop your program when 2836a specific exception is raised. You can use multiple conditional 2837breakpoints to stop your program when any of a number of exceptions are 2838raised. 2839 2840 |
| 3051@node Delete Breaks, Disabling, Set Catchpoints, Breakpoints | 2841@node Delete Breaks |
| 3052@subsection Deleting breakpoints 3053 3054@cindex clearing breakpoints, watchpoints, catchpoints 3055@cindex deleting breakpoints, watchpoints, catchpoints 3056It is often necessary to eliminate a breakpoint, watchpoint, or 3057catchpoint once it has done its job and you no longer want your program 3058to stop there. This is called @dfn{deleting} the breakpoint. A 3059breakpoint that has been deleted no longer exists; it is forgotten. --- 20 unchanged lines hidden (view full) --- 3080Delete any breakpoints set at entry to the function @var{function}. 3081 3082@item clear @var{linenum} 3083@itemx clear @var{filename}:@var{linenum} 3084Delete any breakpoints set at or within the code of the specified line. 3085 3086@cindex delete breakpoints 3087@kindex delete | 2842@subsection Deleting breakpoints 2843 2844@cindex clearing breakpoints, watchpoints, catchpoints 2845@cindex deleting breakpoints, watchpoints, catchpoints 2846It is often necessary to eliminate a breakpoint, watchpoint, or 2847catchpoint once it has done its job and you no longer want your program 2848to stop there. This is called @dfn{deleting} the breakpoint. A 2849breakpoint that has been deleted no longer exists; it is forgotten. --- 20 unchanged lines hidden (view full) --- 2870Delete any breakpoints set at entry to the function @var{function}. 2871 2872@item clear @var{linenum} 2873@itemx clear @var{filename}:@var{linenum} 2874Delete any breakpoints set at or within the code of the specified line. 2875 2876@cindex delete breakpoints 2877@kindex delete |
| 3088@kindex d 3089@item delete @r{[}breakpoints@r{]} @r{[}@var{bnums}@dots{}@r{]} 3090Delete the breakpoints, watchpoints, or catchpoints of the numbers 3091specified as arguments. If no argument is specified, delete all | 2878@kindex d @r{(@code{delete})} 2879@item delete @r{[}breakpoints@r{]} @r{[}@var{range}@dots{}@r{]} 2880Delete the breakpoints, watchpoints, or catchpoints of the breakpoint 2881ranges specified as arguments. If no argument is specified, delete all |
| 3092breakpoints (@value{GDBN} asks confirmation, unless you have @code{set 3093confirm off}). You can abbreviate this command as @code{d}. 3094@end table 3095 | 2882breakpoints (@value{GDBN} asks confirmation, unless you have @code{set 2883confirm off}). You can abbreviate this command as @code{d}. 2884@end table 2885 |
| 3096@node Disabling, Conditions, Delete Breaks, Breakpoints | 2886@node Disabling |
| 3097@subsection Disabling breakpoints 3098 3099@kindex disable breakpoints 3100@kindex enable breakpoints 3101Rather than deleting a breakpoint, watchpoint, or catchpoint, you might 3102prefer to @dfn{disable} it. This makes the breakpoint inoperative as if 3103it had been deleted, but remembers the information on the breakpoint so 3104that you can @dfn{enable} it again later. --- 10 unchanged lines hidden (view full) --- 3115@itemize @bullet 3116@item 3117Enabled. The breakpoint stops your program. A breakpoint set 3118with the @code{break} command starts out in this state. 3119@item 3120Disabled. The breakpoint has no effect on your program. 3121@item 3122Enabled once. The breakpoint stops your program, but then becomes | 2887@subsection Disabling breakpoints 2888 2889@kindex disable breakpoints 2890@kindex enable breakpoints 2891Rather than deleting a breakpoint, watchpoint, or catchpoint, you might 2892prefer to @dfn{disable} it. This makes the breakpoint inoperative as if 2893it had been deleted, but remembers the information on the breakpoint so 2894that you can @dfn{enable} it again later. --- 10 unchanged lines hidden (view full) --- 2905@itemize @bullet 2906@item 2907Enabled. The breakpoint stops your program. A breakpoint set 2908with the @code{break} command starts out in this state. 2909@item 2910Disabled. The breakpoint has no effect on your program. 2911@item 2912Enabled once. The breakpoint stops your program, but then becomes |
| 3123disabled. A breakpoint set with the @code{tbreak} command starts out in 3124this state. | 2913disabled. |
| 3125@item 3126Enabled for deletion. The breakpoint stops your program, but | 2914@item 2915Enabled for deletion. The breakpoint stops your program, but |
| 3127immediately after it does so it is deleted permanently. | 2916immediately after it does so it is deleted permanently. A breakpoint 2917set with the @code{tbreak} command starts out in this state. |
| 3128@end itemize 3129 3130You can use the following commands to enable or disable breakpoints, 3131watchpoints, and catchpoints: 3132 3133@table @code 3134@kindex disable breakpoints 3135@kindex disable | 2918@end itemize 2919 2920You can use the following commands to enable or disable breakpoints, 2921watchpoints, and catchpoints: 2922 2923@table @code 2924@kindex disable breakpoints 2925@kindex disable |
| 3136@kindex dis 3137@item disable @r{[}breakpoints@r{]} @r{[}@var{bnums}@dots{}@r{]} | 2926@kindex dis @r{(@code{disable})} 2927@item disable @r{[}breakpoints@r{]} @r{[}@var{range}@dots{}@r{]} |
| 3138Disable the specified breakpoints---or all breakpoints, if none are 3139listed. A disabled breakpoint has no effect but is not forgotten. All 3140options such as ignore-counts, conditions and commands are remembered in 3141case the breakpoint is enabled again later. You may abbreviate 3142@code{disable} as @code{dis}. 3143 3144@kindex enable breakpoints 3145@kindex enable | 2928Disable the specified breakpoints---or all breakpoints, if none are 2929listed. A disabled breakpoint has no effect but is not forgotten. All 2930options such as ignore-counts, conditions and commands are remembered in 2931case the breakpoint is enabled again later. You may abbreviate 2932@code{disable} as @code{dis}. 2933 2934@kindex enable breakpoints 2935@kindex enable |
| 3146@item enable @r{[}breakpoints@r{]} @r{[}@var{bnums}@dots{}@r{]} | 2936@item enable @r{[}breakpoints@r{]} @r{[}@var{range}@dots{}@r{]} |
| 3147Enable the specified breakpoints (or all defined breakpoints). They 3148become effective once again in stopping your program. 3149 | 2937Enable the specified breakpoints (or all defined breakpoints). They 2938become effective once again in stopping your program. 2939 |
| 3150@item enable @r{[}breakpoints@r{]} once @var{bnums}@dots{} | 2940@item enable @r{[}breakpoints@r{]} once @var{range}@dots{} |
| 3151Enable the specified breakpoints temporarily. @value{GDBN} disables any 3152of these breakpoints immediately after stopping your program. 3153 | 2941Enable the specified breakpoints temporarily. @value{GDBN} disables any 2942of these breakpoints immediately after stopping your program. 2943 |
| 3154@item enable @r{[}breakpoints@r{]} delete @var{bnums}@dots{} | 2944@item enable @r{[}breakpoints@r{]} delete @var{range}@dots{} |
| 3155Enable the specified breakpoints to work once, then die. @value{GDBN} 3156deletes any of these breakpoints as soon as your program stops there. 3157@end table 3158 | 2945Enable the specified breakpoints to work once, then die. @value{GDBN} 2946deletes any of these breakpoints as soon as your program stops there. 2947@end table 2948 |
| 2949@c FIXME: I think the following ``Except for [...] @code{tbreak}'' is 2950@c confusing: tbreak is also initially enabled. |
|
| 3159Except for a breakpoint set with @code{tbreak} (@pxref{Set Breaks, 3160,Setting breakpoints}), breakpoints that you set are initially enabled; 3161subsequently, they become disabled or enabled only when you use one of 3162the commands above. (The command @code{until} can set and delete a 3163breakpoint of its own, but it does not change the state of your other 3164breakpoints; see @ref{Continuing and Stepping, ,Continuing and 3165stepping}.) 3166 | 2951Except for a breakpoint set with @code{tbreak} (@pxref{Set Breaks, 2952,Setting breakpoints}), breakpoints that you set are initially enabled; 2953subsequently, they become disabled or enabled only when you use one of 2954the commands above. (The command @code{until} can set and delete a 2955breakpoint of its own, but it does not change the state of your other 2956breakpoints; see @ref{Continuing and Stepping, ,Continuing and 2957stepping}.) 2958 |
| 3167@node Conditions, Break Commands, Disabling, Breakpoints | 2959@node Conditions |
| 3168@subsection Break conditions 3169@cindex conditional breakpoints 3170@cindex breakpoint conditions 3171 3172@c FIXME what is scope of break condition expr? Context where wanted? | 2960@subsection Break conditions 2961@cindex conditional breakpoints 2962@cindex breakpoint conditions 2963 2964@c FIXME what is scope of break condition expr? Context where wanted? |
| 3173@c in particular for a watchpoint? | 2965@c in particular for a watchpoint? |
| 3174The simplest sort of breakpoint breaks every time your program reaches a 3175specified place. You can also specify a @dfn{condition} for a 3176breakpoint. A condition is just a Boolean expression in your 3177programming language (@pxref{Expressions, ,Expressions}). A breakpoint with 3178a condition evaluates the expression each time your program reaches it, 3179and your program stops only if the condition is @emph{true}. 3180 3181This is the converse of using assertions for program validation; in that --- 10 unchanged lines hidden (view full) --- 3192 3193Break conditions can have side effects, and may even call functions in 3194your program. This can be useful, for example, to activate functions 3195that log program progress, or to use your own print functions to 3196format special data structures. The effects are completely predictable 3197unless there is another enabled breakpoint at the same address. (In 3198that case, @value{GDBN} might see the other breakpoint first and stop your 3199program without checking the condition of this one.) Note that | 2966The simplest sort of breakpoint breaks every time your program reaches a 2967specified place. You can also specify a @dfn{condition} for a 2968breakpoint. A condition is just a Boolean expression in your 2969programming language (@pxref{Expressions, ,Expressions}). A breakpoint with 2970a condition evaluates the expression each time your program reaches it, 2971and your program stops only if the condition is @emph{true}. 2972 2973This is the converse of using assertions for program validation; in that --- 10 unchanged lines hidden (view full) --- 2984 2985Break conditions can have side effects, and may even call functions in 2986your program. This can be useful, for example, to activate functions 2987that log program progress, or to use your own print functions to 2988format special data structures. The effects are completely predictable 2989unless there is another enabled breakpoint at the same address. (In 2990that case, @value{GDBN} might see the other breakpoint first and stop your 2991program without checking the condition of this one.) Note that |
| 3200breakpoint commands are usually more convenient and flexible for the | 2992breakpoint commands are usually more convenient and flexible than break 2993conditions for the |
| 3201purpose of performing side effects when a breakpoint is reached 3202(@pxref{Break Commands, ,Breakpoint command lists}). 3203 3204Break conditions can be specified when a breakpoint is set, by using 3205@samp{if} in the arguments to the @code{break} command. @xref{Set 3206Breaks, ,Setting breakpoints}. They can also be changed at any time 3207with the @code{condition} command. | 2994purpose of performing side effects when a breakpoint is reached 2995(@pxref{Break Commands, ,Breakpoint command lists}). 2996 2997Break conditions can be specified when a breakpoint is set, by using 2998@samp{if} in the arguments to the @code{break} command. @xref{Set 2999Breaks, ,Setting breakpoints}. They can also be changed at any time 3000with the @code{condition} command. |
| 3208@ifclear HPPA 3209@c The watch command now seems to recognize the if keyword. 3210@c catch doesn't, though. 3211The @code{watch} command does not recognize the @code{if} keyword; 3212@code{condition} is the only way to impose a further condition on a 3213watchpoint. 3214@end ifclear 3215@ifset HPPA | 3001 |
| 3216You can also use the @code{if} keyword with the @code{watch} command. 3217The @code{catch} command does not recognize the @code{if} keyword; 3218@code{condition} is the only way to impose a further condition on a 3219catchpoint. | 3002You can also use the @code{if} keyword with the @code{watch} command. 3003The @code{catch} command does not recognize the @code{if} keyword; 3004@code{condition} is the only way to impose a further condition on a 3005catchpoint. |
| 3220@end ifset | |
| 3221 3222@table @code 3223@kindex condition 3224@item condition @var{bnum} @var{expression} 3225Specify @var{expression} as the break condition for breakpoint, 3226watchpoint, or catchpoint number @var{bnum}. After you set a condition, 3227breakpoint @var{bnum} stops your program only if the value of 3228@var{expression} is true (nonzero, in C). When you use 3229@code{condition}, @value{GDBN} checks @var{expression} immediately for 3230syntactic correctness, and to determine whether symbols in it have | 3006 3007@table @code 3008@kindex condition 3009@item condition @var{bnum} @var{expression} 3010Specify @var{expression} as the break condition for breakpoint, 3011watchpoint, or catchpoint number @var{bnum}. After you set a condition, 3012breakpoint @var{bnum} stops your program only if the value of 3013@var{expression} is true (nonzero, in C). When you use 3014@code{condition}, @value{GDBN} checks @var{expression} immediately for 3015syntactic correctness, and to determine whether symbols in it have |
| 3231referents in the context of your breakpoint. 3232@c FIXME so what does GDB do if there is no referent? Moreover, what 3233@c about watchpoints? | 3016referents in the context of your breakpoint. If @var{expression} uses 3017symbols not referenced in the context of the breakpoint, @value{GDBN} 3018prints an error message: 3019 3020@example 3021No symbol "foo" in current context. 3022@end example 3023 3024@noindent |
| 3234@value{GDBN} does 3235not actually evaluate @var{expression} at the time the @code{condition} | 3025@value{GDBN} does 3026not actually evaluate @var{expression} at the time the @code{condition} |
| 3236command is given, however. @xref{Expressions, ,Expressions}. | 3027command (or a command that sets a breakpoint with a condition, like 3028@code{break if @dots{}}) is given, however. @xref{Expressions, ,Expressions}. |
| 3237 3238@item condition @var{bnum} 3239Remove the condition from breakpoint number @var{bnum}. It becomes 3240an ordinary unconditional breakpoint. 3241@end table 3242 3243@cindex ignore count (of breakpoint) 3244A special case of a breakpoint condition is to stop only when the --- 31 unchanged lines hidden (view full) --- 3276as @w{@samp{$foo-- <= 0}} using a debugger convenience variable that 3277is decremented each time. @xref{Convenience Vars, ,Convenience 3278variables}. 3279@end table 3280 3281Ignore counts apply to breakpoints, watchpoints, and catchpoints. 3282 3283 | 3029 3030@item condition @var{bnum} 3031Remove the condition from breakpoint number @var{bnum}. It becomes 3032an ordinary unconditional breakpoint. 3033@end table 3034 3035@cindex ignore count (of breakpoint) 3036A special case of a breakpoint condition is to stop only when the --- 31 unchanged lines hidden (view full) --- 3068as @w{@samp{$foo-- <= 0}} using a debugger convenience variable that 3069is decremented each time. @xref{Convenience Vars, ,Convenience 3070variables}. 3071@end table 3072 3073Ignore counts apply to breakpoints, watchpoints, and catchpoints. 3074 3075 |
| 3284@node Break Commands, Breakpoint Menus, Conditions, Breakpoints | 3076@node Break Commands |
| 3285@subsection Breakpoint command lists 3286 3287@cindex breakpoint commands 3288You can give any breakpoint (or watchpoint or catchpoint) a series of 3289commands to execute when your program stops due to that breakpoint. For 3290example, you might want to print the values of certain expressions, or 3291enable other breakpoints. 3292 --- 64 unchanged lines hidden (view full) --- 3357break 403 3358commands 3359silent 3360set x = y + 4 3361cont 3362end 3363@end example 3364 | 3077@subsection Breakpoint command lists 3078 3079@cindex breakpoint commands 3080You can give any breakpoint (or watchpoint or catchpoint) a series of 3081commands to execute when your program stops due to that breakpoint. For 3082example, you might want to print the values of certain expressions, or 3083enable other breakpoints. 3084 --- 64 unchanged lines hidden (view full) --- 3149break 403 3150commands 3151silent 3152set x = y + 4 3153cont 3154end 3155@end example 3156 |
| 3365@ifclear CONLY 3366@node Breakpoint Menus, , Break Commands, Breakpoints | 3157@node Breakpoint Menus |
| 3367@subsection Breakpoint menus 3368@cindex overloading 3369@cindex symbol overloading 3370 | 3158@subsection Breakpoint menus 3159@cindex overloading 3160@cindex symbol overloading 3161 |
| 3371Some programming languages (notably C++) permit a single function name | 3162Some programming languages (notably C@t{++}) permit a single function name |
| 3372to be defined several times, for application in different contexts. 3373This is called @dfn{overloading}. When a function name is overloaded, 3374@samp{break @var{function}} is not enough to tell @value{GDBN} where you want 3375a breakpoint. If you realize this is a problem, you can use 3376something like @samp{break @var{function}(@var{types})} to specify which 3377particular version of the function you want. Otherwise, @value{GDBN} offers 3378you a menu of numbered choices for different possible breakpoints, and 3379waits for your selection with the prompt @samp{>}. The first two --- 23 unchanged lines hidden (view full) --- 3403Breakpoint 2 at 0xb344: file String.cc, line 875. 3404Breakpoint 3 at 0xafcc: file String.cc, line 846. 3405Multiple breakpoints were set. 3406Use the "delete" command to delete unwanted 3407 breakpoints. 3408(@value{GDBP}) 3409@end group 3410@end smallexample | 3163to be defined several times, for application in different contexts. 3164This is called @dfn{overloading}. When a function name is overloaded, 3165@samp{break @var{function}} is not enough to tell @value{GDBN} where you want 3166a breakpoint. If you realize this is a problem, you can use 3167something like @samp{break @var{function}(@var{types})} to specify which 3168particular version of the function you want. Otherwise, @value{GDBN} offers 3169you a menu of numbered choices for different possible breakpoints, and 3170waits for your selection with the prompt @samp{>}. The first two --- 23 unchanged lines hidden (view full) --- 3194Breakpoint 2 at 0xb344: file String.cc, line 875. 3195Breakpoint 3 at 0xafcc: file String.cc, line 846. 3196Multiple breakpoints were set. 3197Use the "delete" command to delete unwanted 3198 breakpoints. 3199(@value{GDBP}) 3200@end group 3201@end smallexample |
| 3411@end ifclear | |
| 3412 3413@c @ifclear BARETARGET | 3202 3203@c @ifclear BARETARGET |
| 3414@c @node Error in Breakpoints 3415@c @subsection ``Cannot insert breakpoints'' | 3204@node Error in Breakpoints 3205@subsection ``Cannot insert breakpoints'' |
| 3416@c 3417@c FIXME!! 14/6/95 Is there a real example of this? Let's use it. 3418@c | 3206@c 3207@c FIXME!! 14/6/95 Is there a real example of this? Let's use it. 3208@c |
| 3419@c Under some operating systems, breakpoints cannot be used in a program if 3420@c any other process is running that program. In this situation, 3421@c attempting to run or continue a program with a breakpoint causes 3422@c @value{GDBN} to stop the other process. 3423@c 3424@c When this happens, you have three ways to proceed: 3425@c 3426@c @enumerate 3427@c @item 3428@c Remove or disable the breakpoints, then continue. 3429@c 3430@c @item 3431@c Suspend @value{GDBN}, and copy the file containing your program to a new 3432@c name. Resume @value{GDBN} and use the @code{exec-file} command to specify 3433@c that @value{GDBN} should run your program under that name. 3434@c Then start your program again. 3435@c 3436@c @item 3437@c Relink your program so that the text segment is nonsharable, using the 3438@c linker option @samp{-N}. The operating system limitation may not apply 3439@c to nonsharable executables. 3440@c @end enumerate | 3209Under some operating systems, breakpoints cannot be used in a program if 3210any other process is running that program. In this situation, 3211attempting to run or continue a program with a breakpoint causes 3212@value{GDBN} to print an error message: 3213 3214@example 3215Cannot insert breakpoints. 3216The same program may be running in another process. 3217@end example 3218 3219When this happens, you have three ways to proceed: 3220 3221@enumerate 3222@item 3223Remove or disable the breakpoints, then continue. 3224 3225@item 3226Suspend @value{GDBN}, and copy the file containing your program to a new 3227name. Resume @value{GDBN} and use the @code{exec-file} command to specify 3228that @value{GDBN} should run your program under that name. 3229Then start your program again. 3230 3231@item 3232Relink your program so that the text segment is nonsharable, using the 3233linker option @samp{-N}. The operating system limitation may not apply 3234to nonsharable executables. 3235@end enumerate |
| 3441@c @end ifclear 3442 | 3236@c @end ifclear 3237 |
| 3443@node Continuing and Stepping, Signals, Breakpoints, Stopping | 3238A similar message can be printed if you request too many active 3239hardware-assisted breakpoints and watchpoints: 3240 3241@c FIXME: the precise wording of this message may change; the relevant 3242@c source change is not committed yet (Sep 3, 1999). 3243@smallexample 3244Stopped; cannot insert breakpoints. 3245You may have requested too many hardware breakpoints and watchpoints. 3246@end smallexample 3247 3248@noindent 3249This message is printed when you attempt to resume the program, since 3250only then @value{GDBN} knows exactly how many hardware breakpoints and 3251watchpoints it needs to insert. 3252 3253When this message is printed, you need to disable or remove some of the 3254hardware-assisted breakpoints and watchpoints, and then continue. 3255 3256 3257@node Continuing and Stepping |
| 3444@section Continuing and stepping 3445 3446@cindex stepping 3447@cindex continuing 3448@cindex resuming execution 3449@dfn{Continuing} means resuming program execution until your program 3450completes normally. In contrast, @dfn{stepping} means executing just 3451one more ``step'' of your program, where ``step'' may mean either one 3452line of source code, or one machine instruction (depending on what | 3258@section Continuing and stepping 3259 3260@cindex stepping 3261@cindex continuing 3262@cindex resuming execution 3263@dfn{Continuing} means resuming program execution until your program 3264completes normally. In contrast, @dfn{stepping} means executing just 3265one more ``step'' of your program, where ``step'' may mean either one 3266line of source code, or one machine instruction (depending on what |
| 3453particular command you use). Either when continuing 3454or when stepping, your program may stop even sooner, due to 3455@ifset BARETARGET 3456a breakpoint. 3457@end ifset 3458@ifclear BARETARGET 3459a breakpoint or a signal. (If due to a signal, you may want to use 3460@code{handle}, or use @samp{signal 0} to resume execution. 3461@xref{Signals, ,Signals}.) 3462@end ifclear | 3267particular command you use). Either when continuing or when stepping, 3268your program may stop even sooner, due to a breakpoint or a signal. (If 3269it stops due to a signal, you may want to use @code{handle}, or use 3270@samp{signal 0} to resume execution. @xref{Signals, ,Signals}.) |
| 3463 3464@table @code 3465@kindex continue | 3271 3272@table @code 3273@kindex continue |
| 3466@kindex c 3467@kindex fg | 3274@kindex c @r{(@code{continue})} 3275@kindex fg @r{(resume foreground execution)} |
| 3468@item continue @r{[}@var{ignore-count}@r{]} 3469@itemx c @r{[}@var{ignore-count}@r{]} 3470@itemx fg @r{[}@var{ignore-count}@r{]} 3471Resume program execution, at the address where your program last stopped; 3472any breakpoints set at that address are bypassed. The optional argument 3473@var{ignore-count} allows you to specify a further number of times to 3474ignore a breakpoint at this location; its effect is like that of 3475@code{ignore} (@pxref{Conditions, ,Break conditions}). 3476 3477The argument @var{ignore-count} is meaningful only when your program 3478stopped due to a breakpoint. At other times, the argument to 3479@code{continue} is ignored. 3480 | 3276@item continue @r{[}@var{ignore-count}@r{]} 3277@itemx c @r{[}@var{ignore-count}@r{]} 3278@itemx fg @r{[}@var{ignore-count}@r{]} 3279Resume program execution, at the address where your program last stopped; 3280any breakpoints set at that address are bypassed. The optional argument 3281@var{ignore-count} allows you to specify a further number of times to 3282ignore a breakpoint at this location; its effect is like that of 3283@code{ignore} (@pxref{Conditions, ,Break conditions}). 3284 3285The argument @var{ignore-count} is meaningful only when your program 3286stopped due to a breakpoint. At other times, the argument to 3287@code{continue} is ignored. 3288 |
| 3481The synonyms @code{c} and @code{fg} are provided purely for convenience, 3482and have exactly the same behavior as @code{continue}. | 3289The synonyms @code{c} and @code{fg} (for @dfn{foreground}, as the 3290debugged program is deemed to be the foreground program) are provided 3291purely for convenience, and have exactly the same behavior as 3292@code{continue}. |
| 3483@end table 3484 3485To resume execution at a different place, you can use @code{return} 3486(@pxref{Returning, ,Returning from a function}) to go back to the 3487calling function; or @code{jump} (@pxref{Jumping, ,Continuing at a 3488different address}) to go to an arbitrary location in your program. 3489 3490A typical technique for using stepping is to set a breakpoint 3491(@pxref{Breakpoints, ,Breakpoints; watchpoints; and catchpoints}) at the 3492beginning of the function or the section of your program where a problem 3493is believed to lie, run your program until it stops at that breakpoint, 3494and then step through the suspect area, examining the variables that are 3495interesting, until you see the problem happen. 3496 3497@table @code 3498@kindex step | 3293@end table 3294 3295To resume execution at a different place, you can use @code{return} 3296(@pxref{Returning, ,Returning from a function}) to go back to the 3297calling function; or @code{jump} (@pxref{Jumping, ,Continuing at a 3298different address}) to go to an arbitrary location in your program. 3299 3300A typical technique for using stepping is to set a breakpoint 3301(@pxref{Breakpoints, ,Breakpoints; watchpoints; and catchpoints}) at the 3302beginning of the function or the section of your program where a problem 3303is believed to lie, run your program until it stops at that breakpoint, 3304and then step through the suspect area, examining the variables that are 3305interesting, until you see the problem happen. 3306 3307@table @code 3308@kindex step |
| 3499@kindex s | 3309@kindex s @r{(@code{step})} |
| 3500@item step 3501Continue running your program until control reaches a different source 3502line, then stop it and return control to @value{GDBN}. This command is 3503abbreviated @code{s}. 3504 3505@quotation 3506@c "without debugging information" is imprecise; actually "without line 3507@c numbers in the debugging information". (gcc -g1 has debugging info but 3508@c not line numbers). But it seems complex to try to make that 3509@c distinction here. 3510@emph{Warning:} If you use the @code{step} command while control is 3511within a function that was compiled without debugging information, 3512execution proceeds until control reaches a function that does have 3513debugging information. Likewise, it will not step into a function which 3514is compiled without debugging information. To step through functions 3515without debugging information, use the @code{stepi} command, described 3516below. 3517@end quotation 3518 | 3310@item step 3311Continue running your program until control reaches a different source 3312line, then stop it and return control to @value{GDBN}. This command is 3313abbreviated @code{s}. 3314 3315@quotation 3316@c "without debugging information" is imprecise; actually "without line 3317@c numbers in the debugging information". (gcc -g1 has debugging info but 3318@c not line numbers). But it seems complex to try to make that 3319@c distinction here. 3320@emph{Warning:} If you use the @code{step} command while control is 3321within a function that was compiled without debugging information, 3322execution proceeds until control reaches a function that does have 3323debugging information. Likewise, it will not step into a function which 3324is compiled without debugging information. To step through functions 3325without debugging information, use the @code{stepi} command, described 3326below. 3327@end quotation 3328 |
| 3519The @code{step} command now only stops at the first instruction of a 3520source line. This prevents the multiple stops that used to occur in 3521switch statements, for loops, etc. @code{step} continues to stop if a 3522function that has debugging information is called within the line. | 3329The @code{step} command only stops at the first instruction of a source 3330line. This prevents the multiple stops that could otherwise occur in 3331@code{switch} statements, @code{for} loops, etc. @code{step} continues 3332to stop if a function that has debugging information is called within 3333the line. In other words, @code{step} @emph{steps inside} any functions 3334called within the line. |
| 3523 | 3335 |
| 3524Also, the @code{step} command now only enters a subroutine if there is line 3525number information for the subroutine. Otherwise it acts like the 3526@code{next} command. This avoids problems when using @code{cc -gl} | 3336Also, the @code{step} command only enters a function if there is line 3337number information for the function. Otherwise it acts like the 3338@code{next} command. This avoids problems when using @code{cc -gl} |
| 3527on MIPS machines. Previously, @code{step} entered subroutines if there | 3339on MIPS machines. Previously, @code{step} entered subroutines if there |
| 3528was any debugging information about the routine. | 3340was any debugging information about the routine. |
| 3529 3530@item step @var{count} 3531Continue running as in @code{step}, but do so @var{count} times. If a | 3341 3342@item step @var{count} 3343Continue running as in @code{step}, but do so @var{count} times. If a |
| 3532breakpoint is reached, 3533@ifclear BARETARGET 3534or a signal not related to stepping occurs before @var{count} steps, 3535@end ifclear 3536stepping stops right away. | 3344breakpoint is reached, or a signal not related to stepping occurs before 3345@var{count} steps, stepping stops right away. |
| 3537 3538@kindex next | 3346 3347@kindex next |
| 3539@kindex n | 3348@kindex n @r{(@code{next})} |
| 3540@item next @r{[}@var{count}@r{]} 3541Continue to the next source line in the current (innermost) stack frame. | 3349@item next @r{[}@var{count}@r{]} 3350Continue to the next source line in the current (innermost) stack frame. |
| 3542This is similar to @code{step}, but function calls that appear within the line 3543of code are executed without stopping. Execution stops when control 3544reaches a different line of code at the original stack level that was 3545executing when you gave the @code{next} command. This command is abbreviated 3546@code{n}. | 3351This is similar to @code{step}, but function calls that appear within 3352the line of code are executed without stopping. Execution stops when 3353control reaches a different line of code at the original stack level 3354that was executing when you gave the @code{next} command. This command 3355is abbreviated @code{n}. |
| 3547 3548An argument @var{count} is a repeat count, as for @code{step}. 3549 3550 3551@c FIX ME!! Do we delete this, or is there a way it fits in with 3552@c the following paragraph? --- Vctoria 3553@c 3554@c @code{next} within a function that lacks debugging information acts like 3555@c @code{step}, but any function calls appearing within the code of the 3556@c function are executed without stopping. 3557 | 3356 3357An argument @var{count} is a repeat count, as for @code{step}. 3358 3359 3360@c FIX ME!! Do we delete this, or is there a way it fits in with 3361@c the following paragraph? --- Vctoria 3362@c 3363@c @code{next} within a function that lacks debugging information acts like 3364@c @code{step}, but any function calls appearing within the code of the 3365@c function are executed without stopping. 3366 |
| 3558The @code{next} command now only stops at the first instruction of a 3559source line. This prevents the multiple stops that used to occur in 3560switch statements, for loops, etc. | 3367The @code{next} command only stops at the first instruction of a 3368source line. This prevents multiple stops that could otherwise occur in 3369@code{switch} statements, @code{for} loops, etc. |
| 3561 | 3370 |
| 3371@kindex set step-mode 3372@item set step-mode 3373@cindex functions without line info, and stepping 3374@cindex stepping into functions with no line info 3375@itemx set step-mode on 3376The @code{set step-mode on} command causes the @code{step} command to 3377stop at the first instruction of a function which contains no debug line 3378information rather than stepping over it. 3379 3380This is useful in cases where you may be interested in inspecting the 3381machine instructions of a function which has no symbolic info and do not 3382want @value{GDBN} to automatically skip over this function. 3383 3384@item set step-mode off 3385Causes the @code{step} command to step over any functions which contains no 3386debug information. This is the default. 3387 |
|
| 3562@kindex finish 3563@item finish 3564Continue running until just after function in the selected stack frame 3565returns. Print the returned value (if any). 3566 3567Contrast this with the @code{return} command (@pxref{Returning, 3568,Returning from a function}). 3569 3570@kindex until | 3388@kindex finish 3389@item finish 3390Continue running until just after function in the selected stack frame 3391returns. Print the returned value (if any). 3392 3393Contrast this with the @code{return} command (@pxref{Returning, 3394,Returning from a function}). 3395 3396@kindex until |
| 3571@kindex u | 3397@kindex u @r{(@code{until})} |
| 3572@item until 3573@itemx u 3574Continue running until a source line past the current line, in the 3575current stack frame, is reached. This command is used to avoid single 3576stepping through a loop more than once. It is like the @code{next} 3577command, except that when @code{until} encounters a jump, it 3578automatically continues execution until the program counter is greater 3579than the address of the jump. --- 37 unchanged lines hidden (view full) --- 3617@itemx u @var{location} 3618Continue running your program until either the specified location is 3619reached, or the current stack frame returns. @var{location} is any of 3620the forms of argument acceptable to @code{break} (@pxref{Set Breaks, 3621,Setting breakpoints}). This form of the command uses breakpoints, 3622and hence is quicker than @code{until} without an argument. 3623 3624@kindex stepi | 3398@item until 3399@itemx u 3400Continue running until a source line past the current line, in the 3401current stack frame, is reached. This command is used to avoid single 3402stepping through a loop more than once. It is like the @code{next} 3403command, except that when @code{until} encounters a jump, it 3404automatically continues execution until the program counter is greater 3405than the address of the jump. --- 37 unchanged lines hidden (view full) --- 3443@itemx u @var{location} 3444Continue running your program until either the specified location is 3445reached, or the current stack frame returns. @var{location} is any of 3446the forms of argument acceptable to @code{break} (@pxref{Set Breaks, 3447,Setting breakpoints}). This form of the command uses breakpoints, 3448and hence is quicker than @code{until} without an argument. 3449 3450@kindex stepi |
| 3625@kindex si | 3451@kindex si @r{(@code{stepi})} |
| 3626@item stepi | 3452@item stepi |
| 3453@itemx stepi @var{arg} |
|
| 3627@itemx si 3628Execute one machine instruction, then stop and return to the debugger. 3629 3630It is often useful to do @samp{display/i $pc} when stepping by machine 3631instructions. This makes @value{GDBN} automatically display the next 3632instruction to be executed, each time your program stops. @xref{Auto 3633Display,, Automatic display}. 3634 3635An argument is a repeat count, as in @code{step}. 3636 3637@need 750 3638@kindex nexti | 3454@itemx si 3455Execute one machine instruction, then stop and return to the debugger. 3456 3457It is often useful to do @samp{display/i $pc} when stepping by machine 3458instructions. This makes @value{GDBN} automatically display the next 3459instruction to be executed, each time your program stops. @xref{Auto 3460Display,, Automatic display}. 3461 3462An argument is a repeat count, as in @code{step}. 3463 3464@need 750 3465@kindex nexti |
| 3639@kindex ni | 3466@kindex ni @r{(@code{nexti})} |
| 3640@item nexti | 3467@item nexti |
| 3468@itemx nexti @var{arg} |
|
| 3641@itemx ni 3642Execute one machine instruction, but if it is a function call, 3643proceed until the function returns. 3644 3645An argument is a repeat count, as in @code{next}. 3646@end table 3647 | 3469@itemx ni 3470Execute one machine instruction, but if it is a function call, 3471proceed until the function returns. 3472 3473An argument is a repeat count, as in @code{next}. 3474@end table 3475 |
| 3648@ifset POSIX 3649@node Signals, Thread Stops, Continuing and Stepping, Stopping | 3476@node Signals |
| 3650@section Signals 3651@cindex signals 3652 3653A signal is an asynchronous event that can happen in a program. The 3654operating system defines the possible kinds of signals, and gives each 3655kind a name and a number. For example, in Unix @code{SIGINT} is the | 3477@section Signals 3478@cindex signals 3479 3480A signal is an asynchronous event that can happen in a program. The 3481operating system defines the possible kinds of signals, and gives each 3482kind a name and a number. For example, in Unix @code{SIGINT} is the |
| 3656signal a program gets when you type an interrupt (often @kbd{C-c}); | 3483signal a program gets when you type an interrupt character (often @kbd{C-c}); |
| 3657@code{SIGSEGV} is the signal a program gets from referencing a place in 3658memory far away from all the areas in use; @code{SIGALRM} occurs when 3659the alarm clock timer goes off (which happens only if your program has 3660requested an alarm). 3661 3662@cindex fatal signals 3663Some signals, including @code{SIGALRM}, are a normal part of the 3664functioning of your program. Others, such as @code{SIGSEGV}, indicate | 3484@code{SIGSEGV} is the signal a program gets from referencing a place in 3485memory far away from all the areas in use; @code{SIGALRM} occurs when 3486the alarm clock timer goes off (which happens only if your program has 3487requested an alarm). 3488 3489@cindex fatal signals 3490Some signals, including @code{SIGALRM}, are a normal part of the 3491functioning of your program. Others, such as @code{SIGSEGV}, indicate |
| 3665errors; these signals are @dfn{fatal} (kill your program immediately) if the | 3492errors; these signals are @dfn{fatal} (they kill your program immediately) if the |
| 3666program has not specified in advance some other way to handle the signal. 3667@code{SIGINT} does not indicate an error in your program, but it is normally 3668fatal so it can carry out the purpose of the interrupt: to kill the program. 3669 3670@value{GDBN} has the ability to detect any occurrence of a signal in your 3671program. You can tell @value{GDBN} in advance what to do for each kind of 3672signal. 3673 3674@cindex handling signals | 3493program has not specified in advance some other way to handle the signal. 3494@code{SIGINT} does not indicate an error in your program, but it is normally 3495fatal so it can carry out the purpose of the interrupt: to kill the program. 3496 3497@value{GDBN} has the ability to detect any occurrence of a signal in your 3498program. You can tell @value{GDBN} in advance what to do for each kind of 3499signal. 3500 3501@cindex handling signals |
| 3675Normally, @value{GDBN} is set up to ignore non-erroneous signals like @code{SIGALRM} 3676(so as not to interfere with their role in the functioning of your program) | 3502Normally, @value{GDBN} is set up to let the non-erroneous signals like 3503@code{SIGALRM} be silently passed to your program 3504(so as not to interfere with their role in the program's functioning) |
| 3677but to stop your program immediately whenever an error signal happens. 3678You can change these settings with the @code{handle} command. 3679 3680@table @code 3681@kindex info signals 3682@item info signals | 3505but to stop your program immediately whenever an error signal happens. 3506You can change these settings with the @code{handle} command. 3507 3508@table @code 3509@kindex info signals 3510@item info signals |
| 3511@itemx info handle |
|
| 3683Print a table of all the kinds of signals and how @value{GDBN} has been told to 3684handle each one. You can use this to see the signal numbers of all 3685the defined types of signals. 3686 | 3512Print a table of all the kinds of signals and how @value{GDBN} has been told to 3513handle each one. You can use this to see the signal numbers of all 3514the defined types of signals. 3515 |
| 3687@code{info handle} is the new alias for @code{info signals}. | 3516@code{info handle} is an alias for @code{info signals}. |
| 3688 3689@kindex handle 3690@item handle @var{signal} @var{keywords}@dots{} | 3517 3518@kindex handle 3519@item handle @var{signal} @var{keywords}@dots{} |
| 3691Change the way @value{GDBN} handles signal @var{signal}. @var{signal} can 3692be the number of a signal or its name (with or without the @samp{SIG} at the 3693beginning). The @var{keywords} say what change to make. | 3520Change the way @value{GDBN} handles signal @var{signal}. @var{signal} 3521can be the number of a signal or its name (with or without the 3522@samp{SIG} at the beginning); a list of signal numbers of the form 3523@samp{@var{low}-@var{high}}; or the word @samp{all}, meaning all the 3524known signals. The @var{keywords} say what change to make. |
| 3694@end table 3695 3696@c @group 3697The keywords allowed by the @code{handle} command can be abbreviated. 3698Their full names are: 3699 3700@table @code 3701@item nostop --- 7 unchanged lines hidden (view full) --- 3709@item print 3710@value{GDBN} should print a message when this signal happens. 3711 3712@item noprint 3713@value{GDBN} should not mention the occurrence of the signal at all. This 3714implies the @code{nostop} keyword as well. 3715 3716@item pass | 3525@end table 3526 3527@c @group 3528The keywords allowed by the @code{handle} command can be abbreviated. 3529Their full names are: 3530 3531@table @code 3532@item nostop --- 7 unchanged lines hidden (view full) --- 3540@item print 3541@value{GDBN} should print a message when this signal happens. 3542 3543@item noprint 3544@value{GDBN} should not mention the occurrence of the signal at all. This 3545implies the @code{nostop} keyword as well. 3546 3547@item pass |
| 3548@itemx noignore |
|
| 3717@value{GDBN} should allow your program to see this signal; your program 3718can handle the signal, or else it may terminate if the signal is fatal | 3549@value{GDBN} should allow your program to see this signal; your program 3550can handle the signal, or else it may terminate if the signal is fatal |
| 3719and not handled. | 3551and not handled. @code{pass} and @code{noignore} are synonyms. |
| 3720 3721@item nopass | 3552 3553@item nopass |
| 3554@itemx ignore |
|
| 3722@value{GDBN} should not allow your program to see this signal. | 3555@value{GDBN} should not allow your program to see this signal. |
| 3556@code{nopass} and @code{ignore} are synonyms. |
|
| 3723@end table 3724@c @end group 3725 | 3557@end table 3558@c @end group 3559 |
| 3726When a signal stops your program, the signal is not visible until you | 3560When a signal stops your program, the signal is not visible to the 3561program until you |
| 3727continue. Your program sees the signal then, if @code{pass} is in 3728effect for the signal in question @emph{at that time}. In other words, 3729after @value{GDBN} reports a signal, you can use the @code{handle} 3730command with @code{pass} or @code{nopass} to control whether your 3731program sees that signal when you continue. 3732 | 3562continue. Your program sees the signal then, if @code{pass} is in 3563effect for the signal in question @emph{at that time}. In other words, 3564after @value{GDBN} reports a signal, you can use the @code{handle} 3565command with @code{pass} or @code{nopass} to control whether your 3566program sees that signal when you continue. 3567 |
| 3568The default is set to @code{nostop}, @code{noprint}, @code{pass} for 3569non-erroneous signals such as @code{SIGALRM}, @code{SIGWINCH} and 3570@code{SIGCHLD}, and to @code{stop}, @code{print}, @code{pass} for the 3571erroneous signals. 3572 |
|
| 3733You can also use the @code{signal} command to prevent your program from 3734seeing a signal, or cause it to see a signal it normally would not see, 3735or to give it any signal at any time. For example, if your program stopped 3736due to some sort of memory reference error, you might store correct 3737values into the erroneous variables and continue, hoping to see more 3738execution; but your program would probably terminate immediately as 3739a result of the fatal signal once it saw the signal. To prevent this, 3740you can continue with @samp{signal 0}. @xref{Signaling, ,Giving your | 3573You can also use the @code{signal} command to prevent your program from 3574seeing a signal, or cause it to see a signal it normally would not see, 3575or to give it any signal at any time. For example, if your program stopped 3576due to some sort of memory reference error, you might store correct 3577values into the erroneous variables and continue, hoping to see more 3578execution; but your program would probably terminate immediately as 3579a result of the fatal signal once it saw the signal. To prevent this, 3580you can continue with @samp{signal 0}. @xref{Signaling, ,Giving your |
| 3741program a signal}. 3742@end ifset | 3581program a signal}. |
| 3743 | 3582 |
| 3744@ifclear BARETARGET 3745@node Thread Stops, , Signals, Stopping | 3583@node Thread Stops |
| 3746@section Stopping and starting multi-thread programs 3747 3748When your program has multiple threads (@pxref{Threads,, Debugging 3749programs with multiple threads}), you can choose whether to set 3750breakpoints on all threads, or on a particular thread. 3751 3752@table @code 3753@cindex breakpoints and threads --- 14 unchanged lines hidden (view full) --- 3768breakpoint, the breakpoint applies to @emph{all} threads of your 3769program. 3770 3771You can use the @code{thread} qualifier on conditional breakpoints as 3772well; in this case, place @samp{thread @var{threadno}} before the 3773breakpoint condition, like this: 3774 3775@smallexample | 3584@section Stopping and starting multi-thread programs 3585 3586When your program has multiple threads (@pxref{Threads,, Debugging 3587programs with multiple threads}), you can choose whether to set 3588breakpoints on all threads, or on a particular thread. 3589 3590@table @code 3591@cindex breakpoints and threads --- 14 unchanged lines hidden (view full) --- 3606breakpoint, the breakpoint applies to @emph{all} threads of your 3607program. 3608 3609You can use the @code{thread} qualifier on conditional breakpoints as 3610well; in this case, place @samp{thread @var{threadno}} before the 3611breakpoint condition, like this: 3612 3613@smallexample |
| 3776(gdb) break frik.c:13 thread 28 if bartab > lim | 3614(@value{GDBP}) break frik.c:13 thread 28 if bartab > lim |
| 3777@end smallexample 3778 3779@end table 3780 3781@cindex stopped threads 3782@cindex threads, stopped 3783Whenever your program stops under @value{GDBN} for any reason, 3784@emph{all} threads of execution stop, not just the current thread. This 3785allows you to examine the overall state of the program, including 3786switching between threads, without worrying that things may change 3787underfoot. 3788 3789@cindex continuing threads 3790@cindex threads, continuing 3791Conversely, whenever you restart the program, @emph{all} threads start 3792executing. @emph{This is true even when single-stepping} with commands | 3615@end smallexample 3616 3617@end table 3618 3619@cindex stopped threads 3620@cindex threads, stopped 3621Whenever your program stops under @value{GDBN} for any reason, 3622@emph{all} threads of execution stop, not just the current thread. This 3623allows you to examine the overall state of the program, including 3624switching between threads, without worrying that things may change 3625underfoot. 3626 3627@cindex continuing threads 3628@cindex threads, continuing 3629Conversely, whenever you restart the program, @emph{all} threads start 3630executing. @emph{This is true even when single-stepping} with commands |
| 3793like @code{step} or @code{next}. | 3631like @code{step} or @code{next}. |
| 3794 3795In particular, @value{GDBN} cannot single-step all threads in lockstep. 3796Since thread scheduling is up to your debugging target's operating 3797system (not controlled by @value{GDBN}), other threads may 3798execute more than one statement while the current thread completes a 3799single step. Moreover, in general other threads stop in the middle of a 3800statement, rather than at a clean statement boundary, when the program 3801stops. --- 9 unchanged lines hidden (view full) --- 3811@table @code 3812@item set scheduler-locking @var{mode} 3813Set the scheduler locking mode. If it is @code{off}, then there is no 3814locking and any thread may run at any time. If @code{on}, then only the 3815current thread may run when the inferior is resumed. The @code{step} 3816mode optimizes for single-stepping. It stops other threads from 3817``seizing the prompt'' by preempting the current thread while you are 3818stepping. Other threads will only rarely (or never) get a chance to run | 3632 3633In particular, @value{GDBN} cannot single-step all threads in lockstep. 3634Since thread scheduling is up to your debugging target's operating 3635system (not controlled by @value{GDBN}), other threads may 3636execute more than one statement while the current thread completes a 3637single step. Moreover, in general other threads stop in the middle of a 3638statement, rather than at a clean statement boundary, when the program 3639stops. --- 9 unchanged lines hidden (view full) --- 3649@table @code 3650@item set scheduler-locking @var{mode} 3651Set the scheduler locking mode. If it is @code{off}, then there is no 3652locking and any thread may run at any time. If @code{on}, then only the 3653current thread may run when the inferior is resumed. The @code{step} 3654mode optimizes for single-stepping. It stops other threads from 3655``seizing the prompt'' by preempting the current thread while you are 3656stepping. Other threads will only rarely (or never) get a chance to run |
| 3819when you step. They are more likely to run when you ``next'' over a | 3657when you step. They are more likely to run when you @samp{next} over a |
| 3820function call, and they are completely free to run when you use commands | 3658function call, and they are completely free to run when you use commands |
| 3821like ``continue'', ``until'', or ``finish''. However, unless another | 3659like @samp{continue}, @samp{until}, or @samp{finish}. However, unless another |
| 3822thread hits a breakpoint during its timeslice, they will never steal the | 3660thread hits a breakpoint during its timeslice, they will never steal the |
| 3823GDB prompt away from the thread that you are debugging. | 3661@value{GDBN} prompt away from the thread that you are debugging. |
| 3824 3825@item show scheduler-locking 3826Display the current scheduler locking mode. 3827@end table 3828 | 3662 3663@item show scheduler-locking 3664Display the current scheduler locking mode. 3665@end table 3666 |
| 3829@end ifclear | |
| 3830 | 3667 |
| 3831 3832@node Stack, Source, Stopping, Top | 3668@node Stack |
| 3833@chapter Examining the Stack 3834 3835When your program has stopped, the first thing you need to know is where it 3836stopped and how it got there. 3837 3838@cindex call stack | 3669@chapter Examining the Stack 3670 3671When your program has stopped, the first thing you need to know is where it 3672stopped and how it got there. 3673 3674@cindex call stack |
| 3839Each time your program performs a function call, information about the call 3840is generated. 3841That information includes the location of the call in your program, 3842the arguments of the call, | 3675Each time your program performs a function call, information about the call 3676is generated. 3677That information includes the location of the call in your program, 3678the arguments of the call, |
| 3843and the local variables of the function being called. | 3679and the local variables of the function being called. |
| 3844The information is saved in a block of data called a @dfn{stack frame}. | 3680The information is saved in a block of data called a @dfn{stack frame}. |
| 3845The stack frames are allocated in a region of memory called the @dfn{call 3846stack}. 3847 3848When your program stops, the @value{GDBN} commands for examining the 3849stack allow you to see all of this information. 3850 3851@cindex selected frame 3852One of the stack frames is @dfn{selected} by @value{GDBN} and many 3853@value{GDBN} commands refer implicitly to the selected frame. In 3854particular, whenever you ask @value{GDBN} for the value of a variable in 3855your program, the value is found in the selected frame. There are 3856special @value{GDBN} commands to select whichever frame you are 3857interested in. @xref{Selection, ,Selecting a frame}. 3858 3859When your program stops, @value{GDBN} automatically selects the | 3681The stack frames are allocated in a region of memory called the @dfn{call 3682stack}. 3683 3684When your program stops, the @value{GDBN} commands for examining the 3685stack allow you to see all of this information. 3686 3687@cindex selected frame 3688One of the stack frames is @dfn{selected} by @value{GDBN} and many 3689@value{GDBN} commands refer implicitly to the selected frame. In 3690particular, whenever you ask @value{GDBN} for the value of a variable in 3691your program, the value is found in the selected frame. There are 3692special @value{GDBN} commands to select whichever frame you are 3693interested in. @xref{Selection, ,Selecting a frame}. 3694 3695When your program stops, @value{GDBN} automatically selects the |
| 3860currently executing frame and describes it briefly, similar to the | 3696currently executing frame and describes it briefly, similar to the |
| 3861@code{frame} command (@pxref{Frame Info, ,Information about a frame}). 3862 3863@menu 3864* Frames:: Stack frames 3865* Backtrace:: Backtraces 3866* Selection:: Selecting a frame 3867* Frame Info:: Information on a frame | 3697@code{frame} command (@pxref{Frame Info, ,Information about a frame}). 3698 3699@menu 3700* Frames:: Stack frames 3701* Backtrace:: Backtraces 3702* Selection:: Selecting a frame 3703* Frame Info:: Information on a frame |
| 3868* Alpha/MIPS Stack:: Alpha and MIPS machines and the function stack | |
| 3869 3870@end menu 3871 | 3704 3705@end menu 3706 |
| 3872@node Frames, Backtrace, Stack, Stack | 3707@node Frames |
| 3873@section Stack frames 3874 | 3708@section Stack frames 3709 |
| 3875@cindex frame | 3710@cindex frame, definition |
| 3876@cindex stack frame 3877The call stack is divided up into contiguous pieces called @dfn{stack 3878frames}, or @dfn{frames} for short; each frame is the data associated 3879with one call to one function. The frame contains the arguments given 3880to the function, the function's local variables, and the address at 3881which the function is executing. 3882 3883@cindex initial frame --- 18 unchanged lines hidden (view full) --- 3902 3903@cindex frame number 3904@value{GDBN} assigns numbers to all existing stack frames, starting with 3905zero for the innermost frame, one for the frame that called it, 3906and so on upward. These numbers do not really exist in your program; 3907they are assigned by @value{GDBN} to give you a way of designating stack 3908frames in @value{GDBN} commands. 3909 | 3711@cindex stack frame 3712The call stack is divided up into contiguous pieces called @dfn{stack 3713frames}, or @dfn{frames} for short; each frame is the data associated 3714with one call to one function. The frame contains the arguments given 3715to the function, the function's local variables, and the address at 3716which the function is executing. 3717 3718@cindex initial frame --- 18 unchanged lines hidden (view full) --- 3737 3738@cindex frame number 3739@value{GDBN} assigns numbers to all existing stack frames, starting with 3740zero for the innermost frame, one for the frame that called it, 3741and so on upward. These numbers do not really exist in your program; 3742they are assigned by @value{GDBN} to give you a way of designating stack 3743frames in @value{GDBN} commands. 3744 |
| 3910@c below produces an acceptable overful hbox. --mew 13aug1993 | 3745@c The -fomit-frame-pointer below perennially causes hbox overflow 3746@c underflow problems. |
| 3911@cindex frameless execution 3912Some compilers provide a way to compile functions so that they operate | 3747@cindex frameless execution 3748Some compilers provide a way to compile functions so that they operate |
| 3913without stack frames. (For example, the @code{@value{GCC}} option 3914@samp{-fomit-frame-pointer} generates functions without a frame.) | 3749without stack frames. (For example, the @value{GCC} option 3750@example 3751@samp{-fomit-frame-pointer} 3752@end example 3753generates functions without a frame.) |
| 3915This is occasionally done with heavily used library functions to save 3916the frame setup time. @value{GDBN} has limited facilities for dealing 3917with these function invocations. If the innermost function invocation 3918has no stack frame, @value{GDBN} nevertheless regards it as though 3919it had a separate frame, which is numbered zero as usual, allowing 3920correct tracing of the function call chain. However, @value{GDBN} has 3921no provision for frameless functions elsewhere in the stack. 3922 3923@table @code | 3754This is occasionally done with heavily used library functions to save 3755the frame setup time. @value{GDBN} has limited facilities for dealing 3756with these function invocations. If the innermost function invocation 3757has no stack frame, @value{GDBN} nevertheless regards it as though 3758it had a separate frame, which is numbered zero as usual, allowing 3759correct tracing of the function call chain. However, @value{GDBN} has 3760no provision for frameless functions elsewhere in the stack. 3761 3762@table @code |
| 3924@kindex frame | 3763@kindex frame@r{, command} 3764@cindex current stack frame |
| 3925@item frame @var{args} | 3765@item frame @var{args} |
| 3926The @code{frame} command allows you to move from one stack frame to another, | 3766The @code{frame} command allows you to move from one stack frame to another, |
| 3927and to print the stack frame you select. @var{args} may be either the | 3767and to print the stack frame you select. @var{args} may be either the |
| 3928address of the frame or the stack frame number. Without an argument, 3929@code{frame} prints the current stack frame. | 3768address of the frame or the stack frame number. Without an argument, 3769@code{frame} prints the current stack frame. |
| 3930 3931@kindex select-frame | 3770 3771@kindex select-frame |
| 3772@cindex selecting frame silently |
|
| 3932@item select-frame 3933The @code{select-frame} command allows you to move from one stack frame 3934to another without printing the frame. This is the silent version of 3935@code{frame}. 3936@end table 3937 | 3773@item select-frame 3774The @code{select-frame} command allows you to move from one stack frame 3775to another without printing the frame. This is the silent version of 3776@code{frame}. 3777@end table 3778 |
| 3938@node Backtrace, Selection, Frames, Stack | 3779@node Backtrace |
| 3939@section Backtraces 3940 3941@cindex backtraces 3942@cindex tracebacks 3943@cindex stack traces 3944A backtrace is a summary of how your program got where it is. It shows one 3945line per frame, for many frames, starting with the currently executing 3946frame (frame zero), followed by its caller (frame one), and on up the 3947stack. 3948 3949@table @code 3950@kindex backtrace | 3780@section Backtraces 3781 3782@cindex backtraces 3783@cindex tracebacks 3784@cindex stack traces 3785A backtrace is a summary of how your program got where it is. It shows one 3786line per frame, for many frames, starting with the currently executing 3787frame (frame zero), followed by its caller (frame one), and on up the 3788stack. 3789 3790@table @code 3791@kindex backtrace |
| 3951@kindex bt | 3792@kindex bt @r{(@code{backtrace})} |
| 3952@item backtrace 3953@itemx bt 3954Print a backtrace of the entire stack: one line per frame for all 3955frames in the stack. 3956 3957You can stop the backtrace at any time by typing the system interrupt 3958character, normally @kbd{C-c}. 3959 3960@item backtrace @var{n} 3961@itemx bt @var{n} 3962Similar, but print only the innermost @var{n} frames. 3963 3964@item backtrace -@var{n} 3965@itemx bt -@var{n} 3966Similar, but print only the outermost @var{n} frames. 3967@end table 3968 3969@kindex where 3970@kindex info stack | 3793@item backtrace 3794@itemx bt 3795Print a backtrace of the entire stack: one line per frame for all 3796frames in the stack. 3797 3798You can stop the backtrace at any time by typing the system interrupt 3799character, normally @kbd{C-c}. 3800 3801@item backtrace @var{n} 3802@itemx bt @var{n} 3803Similar, but print only the innermost @var{n} frames. 3804 3805@item backtrace -@var{n} 3806@itemx bt -@var{n} 3807Similar, but print only the outermost @var{n} frames. 3808@end table 3809 3810@kindex where 3811@kindex info stack |
| 3971@kindex info s | 3812@kindex info s @r{(@code{info stack})} |
| 3972The names @code{where} and @code{info stack} (abbreviated @code{info s}) 3973are additional aliases for @code{backtrace}. 3974 3975Each line in the backtrace shows the frame number and the function name. 3976The program counter value is also shown---unless you use @code{set 3977print address off}. The backtrace also shows the source file name and 3978line number, as well as the arguments to the function. The program 3979counter value is omitted if it is at the beginning of the code for that 3980line number. 3981 3982Here is an example of a backtrace. It was made with the command 3983@samp{bt 3}, so it shows the innermost three frames. 3984 3985@smallexample 3986@group | 3813The names @code{where} and @code{info stack} (abbreviated @code{info s}) 3814are additional aliases for @code{backtrace}. 3815 3816Each line in the backtrace shows the frame number and the function name. 3817The program counter value is also shown---unless you use @code{set 3818print address off}. The backtrace also shows the source file name and 3819line number, as well as the arguments to the function. The program 3820counter value is omitted if it is at the beginning of the code for that 3821line number. 3822 3823Here is an example of a backtrace. It was made with the command 3824@samp{bt 3}, so it shows the innermost three frames. 3825 3826@smallexample 3827@group |
| 3987#0 m4_traceon (obs=0x24eb0, argc=1, argv=0x2b8c8) | 3828#0 m4_traceon (obs=0x24eb0, argc=1, argv=0x2b8c8) |
| 3988 at builtin.c:993 3989#1 0x6e38 in expand_macro (sym=0x2b600) at macro.c:242 3990#2 0x6840 in expand_token (obs=0x0, t=177664, td=0xf7fffb08) 3991 at macro.c:71 3992(More stack frames follow...) 3993@end group 3994@end smallexample 3995 3996@noindent 3997The display for frame zero does not begin with a program counter 3998value, indicating that your program has stopped at the beginning of the 3999code for line @code{993} of @code{builtin.c}. 4000 | 3829 at builtin.c:993 3830#1 0x6e38 in expand_macro (sym=0x2b600) at macro.c:242 3831#2 0x6840 in expand_token (obs=0x0, t=177664, td=0xf7fffb08) 3832 at macro.c:71 3833(More stack frames follow...) 3834@end group 3835@end smallexample 3836 3837@noindent 3838The display for frame zero does not begin with a program counter 3839value, indicating that your program has stopped at the beginning of the 3840code for line @code{993} of @code{builtin.c}. 3841 |
| 4001@node Selection, Frame Info, Backtrace, Stack | 3842@node Selection |
| 4002@section Selecting a frame 4003 4004Most commands for examining the stack and other data in your program work on 4005whichever stack frame is selected at the moment. Here are the commands for 4006selecting a stack frame; all of them finish by printing a brief description 4007of the stack frame just selected. 4008 4009@table @code | 3843@section Selecting a frame 3844 3845Most commands for examining the stack and other data in your program work on 3846whichever stack frame is selected at the moment. Here are the commands for 3847selecting a stack frame; all of them finish by printing a brief description 3848of the stack frame just selected. 3849 3850@table @code |
| 4010@kindex frame 4011@kindex f | 3851@kindex frame@r{, selecting} 3852@kindex f @r{(@code{frame})} |
| 4012@item frame @var{n} 4013@itemx f @var{n} 4014Select frame number @var{n}. Recall that frame zero is the innermost 4015(currently executing) frame, frame one is the frame that called the 4016innermost one, and so on. The highest-numbered frame is the one for 4017@code{main}. 4018 4019@item frame @var{addr} 4020@itemx f @var{addr} 4021Select the frame at address @var{addr}. This is useful mainly if the 4022chaining of stack frames has been damaged by a bug, making it 4023impossible for @value{GDBN} to assign numbers properly to all frames. In 4024addition, this can be useful when your program has multiple stacks and 4025switches between them. 4026 | 3853@item frame @var{n} 3854@itemx f @var{n} 3855Select frame number @var{n}. Recall that frame zero is the innermost 3856(currently executing) frame, frame one is the frame that called the 3857innermost one, and so on. The highest-numbered frame is the one for 3858@code{main}. 3859 3860@item frame @var{addr} 3861@itemx f @var{addr} 3862Select the frame at address @var{addr}. This is useful mainly if the 3863chaining of stack frames has been damaged by a bug, making it 3864impossible for @value{GDBN} to assign numbers properly to all frames. In 3865addition, this can be useful when your program has multiple stacks and 3866switches between them. 3867 |
| 4027@ifclear H8EXCLUSIVE 4028@ifclear HPPA | |
| 4029On the SPARC architecture, @code{frame} needs two addresses to 4030select an arbitrary frame: a frame pointer and a stack pointer. 4031 4032On the MIPS and Alpha architecture, it needs two addresses: a stack 4033pointer and a program counter. 4034 4035On the 29k architecture, it needs three addresses: a register stack 4036pointer, a program counter, and a memory stack pointer. 4037@c note to future updaters: this is conditioned on a flag 4038@c SETUP_ARBITRARY_FRAME in the tm-*.h files. The above is up to date 4039@c as of 27 Jan 1994. | 3868On the SPARC architecture, @code{frame} needs two addresses to 3869select an arbitrary frame: a frame pointer and a stack pointer. 3870 3871On the MIPS and Alpha architecture, it needs two addresses: a stack 3872pointer and a program counter. 3873 3874On the 29k architecture, it needs three addresses: a register stack 3875pointer, a program counter, and a memory stack pointer. 3876@c note to future updaters: this is conditioned on a flag 3877@c SETUP_ARBITRARY_FRAME in the tm-*.h files. The above is up to date 3878@c as of 27 Jan 1994. |
| 4040@end ifclear 4041@end ifclear | |
| 4042 4043@kindex up 4044@item up @var{n} 4045Move @var{n} frames up the stack. For positive numbers @var{n}, this 4046advances toward the outermost frame, to higher frame numbers, to frames 4047that have existed longer. @var{n} defaults to one. 4048 4049@kindex down | 3879 3880@kindex up 3881@item up @var{n} 3882Move @var{n} frames up the stack. For positive numbers @var{n}, this 3883advances toward the outermost frame, to higher frame numbers, to frames 3884that have existed longer. @var{n} defaults to one. 3885 3886@kindex down |
| 4050@kindex do | 3887@kindex do @r{(@code{down})} |
| 4051@item down @var{n} 4052Move @var{n} frames down the stack. For positive numbers @var{n}, this 4053advances toward the innermost frame, to lower frame numbers, to frames 4054that were created more recently. @var{n} defaults to one. You may 4055abbreviate @code{down} as @code{do}. 4056@end table 4057 4058All of these commands end by printing two lines of output describing the 4059frame. The first line shows the frame number, the function name, the 4060arguments, and the source file and line number of execution in that | 3888@item down @var{n} 3889Move @var{n} frames down the stack. For positive numbers @var{n}, this 3890advances toward the innermost frame, to lower frame numbers, to frames 3891that were created more recently. @var{n} defaults to one. You may 3892abbreviate @code{down} as @code{do}. 3893@end table 3894 3895All of these commands end by printing two lines of output describing the 3896frame. The first line shows the frame number, the function name, the 3897arguments, and the source file and line number of execution in that |
| 4061frame. The second line shows the text of that source line. | 3898frame. The second line shows the text of that source line. |
| 4062 4063@need 1000 4064For example: 4065 4066@smallexample 4067@group 4068(@value{GDBP}) up 4069#1 0x22f0 in main (argc=1, argv=0xf7fffbf4, env=0xf7fffbfc) --- 13 unchanged lines hidden (view full) --- 4083@itemx down-silently @var{n} 4084These two commands are variants of @code{up} and @code{down}, 4085respectively; they differ in that they do their work silently, without 4086causing display of the new frame. They are intended primarily for use 4087in @value{GDBN} command scripts, where the output might be unnecessary and 4088distracting. 4089@end table 4090 | 3899 3900@need 1000 3901For example: 3902 3903@smallexample 3904@group 3905(@value{GDBP}) up 3906#1 0x22f0 in main (argc=1, argv=0xf7fffbf4, env=0xf7fffbfc) --- 13 unchanged lines hidden (view full) --- 3920@itemx down-silently @var{n} 3921These two commands are variants of @code{up} and @code{down}, 3922respectively; they differ in that they do their work silently, without 3923causing display of the new frame. They are intended primarily for use 3924in @value{GDBN} command scripts, where the output might be unnecessary and 3925distracting. 3926@end table 3927 |
| 4091@node Frame Info, Alpha/MIPS Stack, Selection, Stack | 3928@node Frame Info |
| 4092@section Information about a frame 4093 4094There are several other commands to print information about the selected 4095stack frame. 4096 4097@table @code 4098@item frame 4099@itemx f 4100When used without any argument, this command does not change which 4101frame is selected, but prints a brief description of the currently 4102selected stack frame. It can be abbreviated @code{f}. With an 4103argument, this command is used to select a stack frame. 4104@xref{Selection, ,Selecting a frame}. 4105 4106@kindex info frame | 3929@section Information about a frame 3930 3931There are several other commands to print information about the selected 3932stack frame. 3933 3934@table @code 3935@item frame 3936@itemx f 3937When used without any argument, this command does not change which 3938frame is selected, but prints a brief description of the currently 3939selected stack frame. It can be abbreviated @code{f}. With an 3940argument, this command is used to select a stack frame. 3941@xref{Selection, ,Selecting a frame}. 3942 3943@kindex info frame |
| 4107@kindex info f | 3944@kindex info f @r{(@code{info frame})} |
| 4108@item info frame 4109@itemx info f 4110This command prints a verbose description of the selected stack frame, 4111including: 4112 4113@itemize @bullet | 3945@item info frame 3946@itemx info f 3947This command prints a verbose description of the selected stack frame, 3948including: 3949 3950@itemize @bullet |
| 4114@item 4115the address of the frame | |
| 4116@item | 3951@item |
| 3952the address of the frame 3953@item |
|
| 4117the address of the next frame down (called by this frame) 4118@item 4119the address of the next frame up (caller of this frame) 4120@item 4121the language in which the source code corresponding to this frame is written 4122@item 4123the address of the frame's arguments 4124@item | 3954the address of the next frame down (called by this frame) 3955@item 3956the address of the next frame up (caller of this frame) 3957@item 3958the language in which the source code corresponding to this frame is written 3959@item 3960the address of the frame's arguments 3961@item |
| 3962the address of the frame's local variables 3963@item |
|
| 4125the program counter saved in it (the address of execution in the caller frame) 4126@item 4127which registers were saved in the frame 4128@end itemize 4129 4130@noindent The verbose description is useful when 4131something has gone wrong that has made the stack format fail to fit 4132the usual conventions. --- 11 unchanged lines hidden (view full) --- 4144Print the arguments of the selected frame, each on a separate line. 4145 4146@item info locals 4147@kindex info locals 4148Print the local variables of the selected frame, each on a separate 4149line. These are all variables (declared either static or automatic) 4150accessible at the point of execution of the selected frame. 4151 | 3964the program counter saved in it (the address of execution in the caller frame) 3965@item 3966which registers were saved in the frame 3967@end itemize 3968 3969@noindent The verbose description is useful when 3970something has gone wrong that has made the stack format fail to fit 3971the usual conventions. --- 11 unchanged lines hidden (view full) --- 3983Print the arguments of the selected frame, each on a separate line. 3984 3985@item info locals 3986@kindex info locals 3987Print the local variables of the selected frame, each on a separate 3988line. These are all variables (declared either static or automatic) 3989accessible at the point of execution of the selected frame. 3990 |
| 4152@ifclear CONLY 4153@ifclear HPPA | |
| 4154@kindex info catch | 3991@kindex info catch |
| 4155@cindex catch exceptions 4156@cindex exception handlers | 3992@cindex catch exceptions, list active handlers 3993@cindex exception handlers, how to list |
| 4157@item info catch 4158Print a list of all the exception handlers that are active in the 4159current stack frame at the current point of execution. To see other 4160exception handlers, visit the associated frame (using the @code{up}, 4161@code{down}, or @code{frame} commands); then type @code{info catch}. 4162@xref{Set Catchpoints, , Setting catchpoints}. | 3994@item info catch 3995Print a list of all the exception handlers that are active in the 3996current stack frame at the current point of execution. To see other 3997exception handlers, visit the associated frame (using the @code{up}, 3998@code{down}, or @code{frame} commands); then type @code{info catch}. 3999@xref{Set Catchpoints, , Setting catchpoints}. |
| 4163@end ifclear 4164@end ifclear 4165@end table | |
| 4166 | 4000 |
| 4167@node Alpha/MIPS Stack, , Frame Info, Stack 4168@section MIPS/Alpha machines and the function stack 4169 4170@cindex stack on Alpha 4171@cindex stack on MIPS 4172@cindex Alpha stack 4173@cindex MIPS stack 4174Alpha- and MIPS-based computers use an unusual stack frame, which 4175sometimes requires @value{GDBN} to search backward in the object code to 4176find the beginning of a function. 4177 4178@cindex response time, MIPS debugging 4179To improve response time (especially for embedded applications, where 4180@value{GDBN} may be restricted to a slow serial line for this search) 4181you may want to limit the size of this search, using one of these 4182commands: 4183 4184@table @code 4185@cindex @code{heuristic-fence-post} (Alpha,MIPS) 4186@item set heuristic-fence-post @var{limit} 4187Restrict @value{GDBN} to examining at most @var{limit} bytes in its search 4188for the beginning of a function. A value of @var{0} (the default) 4189means there is no limit. However, except for @var{0}, the larger the 4190limit the more bytes @code{heuristic-fence-post} must search and 4191therefore the longer it takes to run. 4192 4193@item show heuristic-fence-post 4194Display the current limit. | |
| 4195@end table 4196 | 4001@end table 4002 |
| 4197@noindent 4198These commands are available @emph{only} when @value{GDBN} is configured 4199for debugging programs on Alpha or MIPS processors. | |
| 4200 | 4003 |
| 4201 4202@node Source, Data, Stack, Top | 4004@node Source |
| 4203@chapter Examining Source Files 4204 4205@value{GDBN} can print parts of your program's source, since the debugging 4206information recorded in the program tells @value{GDBN} what source files were 4207used to build it. When your program stops, @value{GDBN} spontaneously prints 4208the line where it stopped. Likewise, when you select a stack frame 4209(@pxref{Selection, ,Selecting a frame}), @value{GDBN} prints the line where 4210execution in that frame has stopped. You can print other portions of 4211source files by explicit command. 4212 | 4005@chapter Examining Source Files 4006 4007@value{GDBN} can print parts of your program's source, since the debugging 4008information recorded in the program tells @value{GDBN} what source files were 4009used to build it. When your program stops, @value{GDBN} spontaneously prints 4010the line where it stopped. Likewise, when you select a stack frame 4011(@pxref{Selection, ,Selecting a frame}), @value{GDBN} prints the line where 4012execution in that frame has stopped. You can print other portions of 4013source files by explicit command. 4014 |
| 4213@ifclear DOSHOST 4214If you use @value{GDBN} through its @sc{gnu} Emacs interface, you may prefer 4215to use 4216Emacs facilities to view source; @pxref{Emacs, ,Using @value{GDBN} under @sc{gnu} Emacs}. 4217@end ifclear | 4015If you use @value{GDBN} through its @sc{gnu} Emacs interface, you may 4016prefer to use Emacs facilities to view source; see @ref{Emacs, ,Using 4017@value{GDBN} under @sc{gnu} Emacs}. |
| 4218 4219@menu 4220* List:: Printing source lines | 4018 4019@menu 4020* List:: Printing source lines |
| 4221@ifclear DOSHOST | |
| 4222* Search:: Searching source files | 4021* Search:: Searching source files |
| 4223@end ifclear 4224 | |
| 4225* Source Path:: Specifying source directories 4226* Machine Code:: Source and machine code 4227@end menu 4228 | 4022* Source Path:: Specifying source directories 4023* Machine Code:: Source and machine code 4024@end menu 4025 |
| 4229@node List, Search, Source, Source | 4026@node List |
| 4230@section Printing source lines 4231 4232@kindex list | 4027@section Printing source lines 4028 4029@kindex list |
| 4233@kindex l | 4030@kindex l @r{(@code{list})} |
| 4234To print lines from a source file, use the @code{list} command | 4031To print lines from a source file, use the @code{list} command |
| 4235(abbreviated @code{l}). By default, ten lines are printed. | 4032(abbreviated @code{l}). By default, ten lines are printed. |
| 4236There are several ways to specify what part of the file you want to print. 4237 4238Here are the forms of the @code{list} command most commonly used: 4239 4240@table @code 4241@item list @var{linenum} 4242Print lines centered around line number @var{linenum} in the 4243current source file. --- 31 unchanged lines hidden (view full) --- 4275so it is equivalent to typing just @code{list}. This is more useful 4276than listing the same lines again. An exception is made for an 4277argument of @samp{-}; that argument is preserved in repetition so that 4278each repetition moves up in the source file. 4279 4280@cindex linespec 4281In general, the @code{list} command expects you to supply zero, one or two 4282@dfn{linespecs}. Linespecs specify source lines; there are several ways | 4033There are several ways to specify what part of the file you want to print. 4034 4035Here are the forms of the @code{list} command most commonly used: 4036 4037@table @code 4038@item list @var{linenum} 4039Print lines centered around line number @var{linenum} in the 4040current source file. --- 31 unchanged lines hidden (view full) --- 4072so it is equivalent to typing just @code{list}. This is more useful 4073than listing the same lines again. An exception is made for an 4074argument of @samp{-}; that argument is preserved in repetition so that 4075each repetition moves up in the source file. 4076 4077@cindex linespec 4078In general, the @code{list} command expects you to supply zero, one or two 4079@dfn{linespecs}. Linespecs specify source lines; there are several ways |
| 4283of writing them but the effect is always to specify some source line. | 4080of writing them, but the effect is always to specify some source line. |
| 4284Here is a complete description of the possible arguments for @code{list}: 4285 4286@table @code 4287@item list @var{linespec} 4288Print lines centered around the line specified by @var{linespec}. 4289 4290@item list @var{first},@var{last} 4291Print lines from @var{first} to @var{last}. Both arguments are --- 46 unchanged lines hidden (view full) --- 4338file name with a function name to avoid ambiguity when there are 4339identically named functions in different source files. 4340 4341@item *@var{address} 4342Specifies the line containing the program address @var{address}. 4343@var{address} may be any expression. 4344@end table 4345 | 4081Here is a complete description of the possible arguments for @code{list}: 4082 4083@table @code 4084@item list @var{linespec} 4085Print lines centered around the line specified by @var{linespec}. 4086 4087@item list @var{first},@var{last} 4088Print lines from @var{first} to @var{last}. Both arguments are --- 46 unchanged lines hidden (view full) --- 4135file name with a function name to avoid ambiguity when there are 4136identically named functions in different source files. 4137 4138@item *@var{address} 4139Specifies the line containing the program address @var{address}. 4140@var{address} may be any expression. 4141@end table 4142 |
| 4346@ifclear DOSHOST 4347@node Search, Source Path, List, Source | 4143@node Search |
| 4348@section Searching source files 4349@cindex searching 4350@kindex reverse-search 4351 4352There are two commands for searching through the current source file for a 4353regular expression. 4354 4355@table @code 4356@kindex search 4357@kindex forward-search 4358@item forward-search @var{regexp} 4359@itemx search @var{regexp} 4360The command @samp{forward-search @var{regexp}} checks each line, 4361starting with the one following the last line listed, for a match for | 4144@section Searching source files 4145@cindex searching 4146@kindex reverse-search 4147 4148There are two commands for searching through the current source file for a 4149regular expression. 4150 4151@table @code 4152@kindex search 4153@kindex forward-search 4154@item forward-search @var{regexp} 4155@itemx search @var{regexp} 4156The command @samp{forward-search @var{regexp}} checks each line, 4157starting with the one following the last line listed, for a match for |
| 4362@var{regexp}. It lists the line that is found. You can use the | 4158@var{regexp}. It lists the line that is found. You can use the |
| 4363synonym @samp{search @var{regexp}} or abbreviate the command name as 4364@code{fo}. 4365 4366@item reverse-search @var{regexp} 4367The command @samp{reverse-search @var{regexp}} checks each line, starting 4368with the one before the last line listed and going backward, for a match 4369for @var{regexp}. It lists the line that is found. You can abbreviate 4370this command as @code{rev}. 4371@end table | 4159synonym @samp{search @var{regexp}} or abbreviate the command name as 4160@code{fo}. 4161 4162@item reverse-search @var{regexp} 4163The command @samp{reverse-search @var{regexp}} checks each line, starting 4164with the one before the last line listed and going backward, for a match 4165for @var{regexp}. It lists the line that is found. You can abbreviate 4166this command as @code{rev}. 4167@end table |
| 4372@end ifclear | |
| 4373 | 4168 |
| 4374@node Source Path, Machine Code, Search, Source | 4169@node Source Path |
| 4375@section Specifying source directories 4376 4377@cindex source path 4378@cindex directories for source files 4379Executable programs sometimes do not record the directories of the source 4380files from which they were compiled, just the names. Even when they do, 4381the directories could be moved between the compilation and your debugging 4382session. @value{GDBN} has a list of directories to search for source files; --- 11 unchanged lines hidden (view full) --- 4394last resort. 4395 4396Whenever you reset or rearrange the source path, @value{GDBN} clears out 4397any information it has cached about where source files are found and where 4398each line is in the file. 4399 4400@kindex directory 4401@kindex dir | 4170@section Specifying source directories 4171 4172@cindex source path 4173@cindex directories for source files 4174Executable programs sometimes do not record the directories of the source 4175files from which they were compiled, just the names. Even when they do, 4176the directories could be moved between the compilation and your debugging 4177session. @value{GDBN} has a list of directories to search for source files; --- 11 unchanged lines hidden (view full) --- 4189last resort. 4190 4191Whenever you reset or rearrange the source path, @value{GDBN} clears out 4192any information it has cached about where source files are found and where 4193each line is in the file. 4194 4195@kindex directory 4196@kindex dir |
| 4402When you start @value{GDBN}, its source path is empty. | 4197When you start @value{GDBN}, its source path includes only @samp{cdir} 4198and @samp{cwd}, in that order. |
| 4403To add other directories, use the @code{directory} command. 4404 4405@table @code 4406@item directory @var{dirname} @dots{} 4407@item dir @var{dirname} @dots{} 4408Add directory @var{dirname} to the front of the source path. Several | 4199To add other directories, use the @code{directory} command. 4200 4201@table @code 4202@item directory @var{dirname} @dots{} 4203@item dir @var{dirname} @dots{} 4204Add directory @var{dirname} to the front of the source path. Several |
| 4409directory names may be given to this command, separated by @samp{:} or | 4205directory names may be given to this command, separated by @samp{:} 4206(@samp{;} on MS-DOS and MS-Windows, where @samp{:} usually appears as 4207part of absolute file names) or |
| 4410whitespace. You may specify a directory that is already in the source 4411path; this moves it forward, so @value{GDBN} searches it sooner. 4412 4413@kindex cdir 4414@kindex cwd | 4208whitespace. You may specify a directory that is already in the source 4209path; this moves it forward, so @value{GDBN} searches it sooner. 4210 4211@kindex cdir 4212@kindex cwd |
| 4415@kindex $cdir 4416@kindex $cwd | 4213@vindex $cdir@r{, convenience variable} 4214@vindex $cwdr@r{, convenience variable} |
| 4417@cindex compilation directory 4418@cindex current directory 4419@cindex working directory 4420@cindex directory, current 4421@cindex directory, compilation 4422You can use the string @samp{$cdir} to refer to the compilation 4423directory (if one is recorded), and @samp{$cwd} to refer to the current 4424working directory. @samp{$cwd} is not the same as @samp{.}---the former --- 21 unchanged lines hidden (view full) --- 4446Use @code{directory} with no argument to reset the source path to empty. 4447 4448@item 4449Use @code{directory} with suitable arguments to reinstall the 4450directories you want in the source path. You can add all the 4451directories in one command. 4452@end enumerate 4453 | 4215@cindex compilation directory 4216@cindex current directory 4217@cindex working directory 4218@cindex directory, current 4219@cindex directory, compilation 4220You can use the string @samp{$cdir} to refer to the compilation 4221directory (if one is recorded), and @samp{$cwd} to refer to the current 4222working directory. @samp{$cwd} is not the same as @samp{.}---the former --- 21 unchanged lines hidden (view full) --- 4244Use @code{directory} with no argument to reset the source path to empty. 4245 4246@item 4247Use @code{directory} with suitable arguments to reinstall the 4248directories you want in the source path. You can add all the 4249directories in one command. 4250@end enumerate 4251 |
| 4454@node Machine Code, , Source Path, Source | 4252@node Machine Code |
| 4455@section Source and machine code 4456 4457You can use the command @code{info line} to map source lines to program 4458addresses (and vice versa), and the command @code{disassemble} to display 4459a range of addresses as machine instructions. When run under @sc{gnu} Emacs | 4253@section Source and machine code 4254 4255You can use the command @code{info line} to map source lines to program 4256addresses (and vice versa), and the command @code{disassemble} to display 4257a range of addresses as machine instructions. When run under @sc{gnu} Emacs |
| 4460mode, the @code{info line} command now causes the arrow to point to the 4461line specified. Also, @code{info line} prints addresses in symbolic form as | 4258mode, the @code{info line} command causes the arrow to point to the 4259line specified. Also, @code{info line} prints addresses in symbolic form as |
| 4462well as hex. 4463 4464@table @code 4465@kindex info line 4466@item info line @var{linespec} 4467Print the starting and ending addresses of the compiled code for 4468source line @var{linespec}. You can specify source lines in any of 4469the ways understood by the @code{list} command (@pxref{List, ,Printing 4470source lines}). 4471@end table 4472 4473For example, we can use @code{info line} to discover the location of 4474the object code for the first line of function 4475@code{m4_changequote}: 4476 | 4260well as hex. 4261 4262@table @code 4263@kindex info line 4264@item info line @var{linespec} 4265Print the starting and ending addresses of the compiled code for 4266source line @var{linespec}. You can specify source lines in any of 4267the ways understood by the @code{list} command (@pxref{List, ,Printing 4268source lines}). 4269@end table 4270 4271For example, we can use @code{info line} to discover the location of 4272the object code for the first line of function 4273@code{m4_changequote}: 4274 |
| 4275@c FIXME: I think this example should also show the addresses in 4276@c symbolic form, as they usually would be displayed. |
|
| 4477@smallexample | 4277@smallexample |
| 4478(@value{GDBP}) info line m4_changecom | 4278(@value{GDBP}) info line m4_changequote |
| 4479Line 895 of "builtin.c" starts at pc 0x634c and ends at 0x6350. 4480@end smallexample 4481 4482@noindent 4483We can also inquire (using @code{*@var{addr}} as the form for 4484@var{linespec}) what source line covers a particular address: 4485@smallexample 4486(@value{GDBP}) info line *0x63ff 4487Line 926 of "builtin.c" starts at pc 0x63e4 and ends at 0x6404. 4488@end smallexample 4489 4490@cindex @code{$_} and @code{info line} | 4279Line 895 of "builtin.c" starts at pc 0x634c and ends at 0x6350. 4280@end smallexample 4281 4282@noindent 4283We can also inquire (using @code{*@var{addr}} as the form for 4284@var{linespec}) what source line covers a particular address: 4285@smallexample 4286(@value{GDBP}) info line *0x63ff 4287Line 926 of "builtin.c" starts at pc 0x63e4 and ends at 0x6404. 4288@end smallexample 4289 4290@cindex @code{$_} and @code{info line} |
| 4291@kindex x@r{(examine), and} info line |
|
| 4491After @code{info line}, the default address for the @code{x} command 4492is changed to the starting address of the line, so that @samp{x/i} is 4493sufficient to begin examining the machine code (@pxref{Memory, 4494,Examining memory}). Also, this address is saved as the value of the 4495convenience variable @code{$_} (@pxref{Convenience Vars, ,Convenience 4496variables}). 4497 4498@table @code --- 6 unchanged lines hidden (view full) --- 4505This specialized command dumps a range of memory as machine 4506instructions. The default memory range is the function surrounding the 4507program counter of the selected frame. A single argument to this 4508command is a program counter value; @value{GDBN} dumps the function 4509surrounding this value. Two arguments specify a range of addresses 4510(first inclusive, second exclusive) to dump. 4511@end table 4512 | 4292After @code{info line}, the default address for the @code{x} command 4293is changed to the starting address of the line, so that @samp{x/i} is 4294sufficient to begin examining the machine code (@pxref{Memory, 4295,Examining memory}). Also, this address is saved as the value of the 4296convenience variable @code{$_} (@pxref{Convenience Vars, ,Convenience 4297variables}). 4298 4299@table @code --- 6 unchanged lines hidden (view full) --- 4306This specialized command dumps a range of memory as machine 4307instructions. The default memory range is the function surrounding the 4308program counter of the selected frame. A single argument to this 4309command is a program counter value; @value{GDBN} dumps the function 4310surrounding this value. Two arguments specify a range of addresses 4311(first inclusive, second exclusive) to dump. 4312@end table 4313 |
| 4513@ifclear H8EXCLUSIVE | |
| 4514The following example shows the disassembly of a range of addresses of 4515HP PA-RISC 2.0 code: 4516 4517@smallexample 4518(@value{GDBP}) disas 0x32c4 0x32e4 4519Dump of assembler code from 0x32c4 to 0x32e4: 45200x32c4 <main+204>: addil 0,dp 45210x32c8 <main+208>: ldw 0x22c(sr0,r1),r26 45220x32cc <main+212>: ldil 0x3000,r31 45230x32d0 <main+216>: ble 0x3f8(sr4,r31) 45240x32d4 <main+220>: ldo 0(r31),rp 45250x32d8 <main+224>: addil -0x800,dp 45260x32dc <main+228>: ldo 0x588(r1),r26 45270x32e0 <main+232>: ldil 0x3000,r31 4528End of assembler dump. 4529@end smallexample | 4314The following example shows the disassembly of a range of addresses of 4315HP PA-RISC 2.0 code: 4316 4317@smallexample 4318(@value{GDBP}) disas 0x32c4 0x32e4 4319Dump of assembler code from 0x32c4 to 0x32e4: 43200x32c4 <main+204>: addil 0,dp 43210x32c8 <main+208>: ldw 0x22c(sr0,r1),r26 43220x32cc <main+212>: ldil 0x3000,r31 43230x32d0 <main+216>: ble 0x3f8(sr4,r31) 43240x32d4 <main+220>: ldo 0(r31),rp 43250x32d8 <main+224>: addil -0x800,dp 43260x32dc <main+228>: ldo 0x588(r1),r26 43270x32e0 <main+232>: ldil 0x3000,r31 4328End of assembler dump. 4329@end smallexample |
| 4530@end ifclear | |
| 4531 | 4330 |
| 4532@ifset H8EXCLUSIVE 4533For example, here is the beginning of the output for the 4534disassembly of a function @code{fact}: 4535 4536 4537@smallexample 4538(@value{GDBP}) disas fact 4539Dump of assembler code for function fact: 4540to 0x808c: 45410x802c <fact>: 6d f2 mov.w r2,@@-r7 45420x802e <fact+2>: 6d f3 mov.w r3,@@-r7 45430x8030 <fact+4>: 6d f6 mov.w r6,@@-r7 45440x8032 <fact+6>: 0d 76 mov.w r7,r6 45450x8034 <fact+8>: 6f 70 00 08 mov.w @@(0x8,r7),r0 45460x8038 <fact+12> 19 11 sub.w r1,r1 4547 . 4548 . 4549 . 4550@end smallexample 4551@end ifset 4552 | |
| 4553Some architectures have more than one commonly-used set of instruction 4554mnemonics or other syntax. 4555 4556@table @code | 4331Some architectures have more than one commonly-used set of instruction 4332mnemonics or other syntax. 4333 4334@table @code |
| 4557@kindex set assembly-language | 4335@kindex set disassembly-flavor |
| 4558@cindex assembly instructions 4559@cindex instructions, assembly 4560@cindex machine instructions 4561@cindex listing machine instructions | 4336@cindex assembly instructions 4337@cindex instructions, assembly 4338@cindex machine instructions 4339@cindex listing machine instructions |
| 4562@item set assembly-language @var{instruction-set} | 4340@cindex Intel disassembly flavor 4341@cindex AT&T disassembly flavor 4342@item set disassembly-flavor @var{instruction-set} |
| 4563Select the instruction set to use when disassembling the 4564program via the @code{disassemble} or @code{x/i} commands. 4565 4566Currently this command is only defined for the Intel x86 family. You | 4343Select the instruction set to use when disassembling the 4344program via the @code{disassemble} or @code{x/i} commands. 4345 4346Currently this command is only defined for the Intel x86 family. You |
| 4567can set @var{instruction-set} to either @code{i386} or @code{i8086}. 4568The default is @code{i386}. | 4347can set @var{instruction-set} to either @code{intel} or @code{att}. 4348The default is @code{att}, the AT&T flavor used by default by Unix 4349assemblers for x86-based targets. |
| 4569@end table 4570 4571 | 4350@end table 4351 4352 |
| 4572@node Data, Languages, Source, Top | 4353@node Data |
| 4573@chapter Examining Data 4574 4575@cindex printing data 4576@cindex examining data 4577@kindex print 4578@kindex inspect 4579@c "inspect" is not quite a synonym if you are using Epoch, which we do not 4580@c document because it is nonstandard... Under Epoch it displays in a 4581@c different window or something like that. 4582The usual way to examine data in your program is with the @code{print} | 4354@chapter Examining Data 4355 4356@cindex printing data 4357@cindex examining data 4358@kindex print 4359@kindex inspect 4360@c "inspect" is not quite a synonym if you are using Epoch, which we do not 4361@c document because it is nonstandard... Under Epoch it displays in a 4362@c different window or something like that. 4363The usual way to examine data in your program is with the @code{print} |
| 4583command (abbreviated @code{p}), or its synonym @code{inspect}. 4584@ifclear CONLY 4585It evaluates and prints the value of an expression of the language your 4586program is written in (@pxref{Languages, ,Using @value{GDBN} with Different 4587Languages}). 4588@end ifclear | 4364command (abbreviated @code{p}), or its synonym @code{inspect}. It 4365evaluates and prints the value of an expression of the language your 4366program is written in (@pxref{Languages, ,Using @value{GDBN} with 4367Different Languages}). |
| 4589 4590@table @code | 4368 4369@table @code |
| 4591@item print @var{exp} 4592@itemx print /@var{f} @var{exp} 4593@var{exp} is an expression (in the source language). By default the 4594value of @var{exp} is printed in a format appropriate to its data type; | 4370@item print @var{expr} 4371@itemx print /@var{f} @var{expr} 4372@var{expr} is an expression (in the source language). By default the 4373value of @var{expr} is printed in a format appropriate to its data type; |
| 4595you can choose a different format by specifying @samp{/@var{f}}, where | 4374you can choose a different format by specifying @samp{/@var{f}}, where |
| 4596@var{f} is a letter specifying the format; @pxref{Output Formats,,Output | 4375@var{f} is a letter specifying the format; see @ref{Output Formats,,Output |
| 4597formats}. 4598 4599@item print 4600@itemx print /@var{f} | 4376formats}. 4377 4378@item print 4379@itemx print /@var{f} |
| 4601If you omit @var{exp}, @value{GDBN} displays the last value again (from the | 4380If you omit @var{expr}, @value{GDBN} displays the last value again (from the |
| 4602@dfn{value history}; @pxref{Value History, ,Value history}). This allows you to 4603conveniently inspect the same value in an alternative format. 4604@end table 4605 4606A more low-level way of examining data is with the @code{x} command. 4607It examines data in memory at a specified address and prints it in a 4608specified format. @xref{Memory, ,Examining memory}. 4609 | 4381@dfn{value history}; @pxref{Value History, ,Value history}). This allows you to 4382conveniently inspect the same value in an alternative format. 4383@end table 4384 4385A more low-level way of examining data is with the @code{x} command. 4386It examines data in memory at a specified address and prints it in a 4387specified format. @xref{Memory, ,Examining memory}. 4388 |
| 4610If you are interested in information about types, or about how the fields 4611of a struct 4612@ifclear CONLY 4613or class 4614@end ifclear 4615are declared, use the @code{ptype @var{exp}} 4616command rather than @code{print}. @xref{Symbols, ,Examining the Symbol Table}. | 4389If you are interested in information about types, or about how the 4390fields of a struct or a class are declared, use the @code{ptype @var{exp}} 4391command rather than @code{print}. @xref{Symbols, ,Examining the Symbol 4392Table}. |
| 4617 4618@menu 4619* Expressions:: Expressions 4620* Variables:: Program variables 4621* Arrays:: Artificial arrays 4622* Output Formats:: Output formats 4623* Memory:: Examining memory 4624* Auto Display:: Automatic display 4625* Print Settings:: Print settings 4626* Value History:: Value history 4627* Convenience Vars:: Convenience variables 4628* Registers:: Registers | 4393 4394@menu 4395* Expressions:: Expressions 4396* Variables:: Program variables 4397* Arrays:: Artificial arrays 4398* Output Formats:: Output formats 4399* Memory:: Examining memory 4400* Auto Display:: Automatic display 4401* Print Settings:: Print settings 4402* Value History:: Value history 4403* Convenience Vars:: Convenience variables 4404* Registers:: Registers |
| 4629@ifclear HAVE-FLOAT | |
| 4630* Floating Point Hardware:: Floating point hardware | 4405* Floating Point Hardware:: Floating point hardware |
| 4631@end ifclear 4632 | 4406* Memory Region Attributes:: Memory region attributes |
| 4633@end menu 4634 | 4407@end menu 4408 |
| 4635@node Expressions, Variables, Data, Data | 4409@node Expressions |
| 4636@section Expressions 4637 4638@cindex expressions 4639@code{print} and many other @value{GDBN} commands accept an expression and 4640compute its value. Any kind of constant, variable or operator defined 4641by the programming language you are using is valid in an expression in 4642@value{GDBN}. This includes conditional expressions, function calls, casts 4643and string constants. It unfortunately does not include symbols defined 4644by preprocessor @code{#define} commands. 4645 | 4410@section Expressions 4411 4412@cindex expressions 4413@code{print} and many other @value{GDBN} commands accept an expression and 4414compute its value. Any kind of constant, variable or operator defined 4415by the programming language you are using is valid in an expression in 4416@value{GDBN}. This includes conditional expressions, function calls, casts 4417and string constants. It unfortunately does not include symbols defined 4418by preprocessor @code{#define} commands. 4419 |
| 4646@value{GDBN} now supports array constants in expressions input by 4647the user. The syntax is @var{@{element, element@dots{}@}}. For example, 4648you can now use the command @code{print @{1, 2, 3@}} to build up an array in 4649memory that is malloc'd in the target program. | 4420@value{GDBN} supports array constants in expressions input by 4421the user. The syntax is @{@var{element}, @var{element}@dots{}@}. For example, 4422you can use the command @code{print @{1, 2, 3@}} to build up an array in 4423memory that is @code{malloc}ed in the target program. |
| 4650 | 4424 |
| 4651@ifclear CONLY | |
| 4652Because C is so widespread, most of the expressions shown in examples in 4653this manual are in C. @xref{Languages, , Using @value{GDBN} with Different 4654Languages}, for information on how to use expressions in other 4655languages. 4656 4657In this section, we discuss operators that you can use in @value{GDBN} 4658expressions regardless of your programming language. 4659 4660Casts are supported in all languages, not just in C, because it is so 4661useful to cast a number into a pointer in order to examine a structure 4662at that address in memory. 4663@c FIXME: casts supported---Mod2 true? | 4425Because C is so widespread, most of the expressions shown in examples in 4426this manual are in C. @xref{Languages, , Using @value{GDBN} with Different 4427Languages}, for information on how to use expressions in other 4428languages. 4429 4430In this section, we discuss operators that you can use in @value{GDBN} 4431expressions regardless of your programming language. 4432 4433Casts are supported in all languages, not just in C, because it is so 4434useful to cast a number into a pointer in order to examine a structure 4435at that address in memory. 4436@c FIXME: casts supported---Mod2 true? |
| 4664@end ifclear | |
| 4665 4666@value{GDBN} supports these operators, in addition to those common 4667to programming languages: 4668 4669@table @code 4670@item @@ 4671@samp{@@} is a binary operator for treating parts of memory as arrays. 4672@xref{Arrays, ,Artificial arrays}, for more information. --- 9 unchanged lines hidden (view full) --- 4682@item @{@var{type}@} @var{addr} 4683Refers to an object of type @var{type} stored at address @var{addr} in 4684memory. @var{addr} may be any expression whose value is an integer or 4685pointer (but parentheses are required around binary operators, just as in 4686a cast). This construct is allowed regardless of what kind of data is 4687normally supposed to reside at @var{addr}. 4688@end table 4689 | 4437 4438@value{GDBN} supports these operators, in addition to those common 4439to programming languages: 4440 4441@table @code 4442@item @@ 4443@samp{@@} is a binary operator for treating parts of memory as arrays. 4444@xref{Arrays, ,Artificial arrays}, for more information. --- 9 unchanged lines hidden (view full) --- 4454@item @{@var{type}@} @var{addr} 4455Refers to an object of type @var{type} stored at address @var{addr} in 4456memory. @var{addr} may be any expression whose value is an integer or 4457pointer (but parentheses are required around binary operators, just as in 4458a cast). This construct is allowed regardless of what kind of data is 4459normally supposed to reside at @var{addr}. 4460@end table 4461 |
| 4690@node Variables, Arrays, Expressions, Data | 4462@node Variables |
| 4691@section Program variables 4692 4693The most common kind of expression to use is the name of a variable 4694in your program. 4695 4696Variables in expressions are understood in the selected stack frame 4697(@pxref{Selection, ,Selecting a frame}); they must be either: 4698 4699@itemize @bullet 4700@item 4701global (or file-static) 4702@end itemize 4703 | 4463@section Program variables 4464 4465The most common kind of expression to use is the name of a variable 4466in your program. 4467 4468Variables in expressions are understood in the selected stack frame 4469(@pxref{Selection, ,Selecting a frame}); they must be either: 4470 4471@itemize @bullet 4472@item 4473global (or file-static) 4474@end itemize 4475 |
| 4704@noindent or | 4476@noindent or |
| 4705 4706@itemize @bullet 4707@item 4708visible according to the scope rules of the 4709programming language from the point of execution in that frame | 4477 4478@itemize @bullet 4479@item 4480visible according to the scope rules of the 4481programming language from the point of execution in that frame |
| 4710@end itemize | 4482@end itemize |
| 4711 4712@noindent This means that in the function 4713 4714@example 4715foo (a) 4716 int a; 4717@{ 4718 bar (a); --- 14 unchanged lines hidden (view full) --- 4733There is an exception: you can refer to a variable or function whose 4734scope is a single source file even if the current execution point is not 4735in this file. But it is possible to have more than one such variable or 4736function with the same name (in different source files). If that 4737happens, referring to that name has unpredictable effects. If you wish, 4738you can specify a static variable in a particular function or file, 4739using the colon-colon notation: 4740 | 4483 4484@noindent This means that in the function 4485 4486@example 4487foo (a) 4488 int a; 4489@{ 4490 bar (a); --- 14 unchanged lines hidden (view full) --- 4505There is an exception: you can refer to a variable or function whose 4506scope is a single source file even if the current execution point is not 4507in this file. But it is possible to have more than one such variable or 4508function with the same name (in different source files). If that 4509happens, referring to that name has unpredictable effects. If you wish, 4510you can specify a static variable in a particular function or file, 4511using the colon-colon notation: 4512 |
| 4741@cindex colon-colon | 4513@cindex colon-colon, context for variables/functions |
| 4742@iftex 4743@c info cannot cope with a :: index entry, but why deprive hard copy readers? | 4514@iftex 4515@c info cannot cope with a :: index entry, but why deprive hard copy readers? |
| 4744@kindex :: | 4516@cindex @code{::}, context for variables/functions |
| 4745@end iftex 4746@example 4747@var{file}::@var{variable} 4748@var{function}::@var{variable} 4749@end example 4750 4751@noindent 4752Here @var{file} or @var{function} is the name of the context for the 4753static @var{variable}. In the case of file names, you can use quotes to 4754make sure @value{GDBN} parses the file name as a single word---for example, 4755to print a global value of @code{x} defined in @file{f2.c}: 4756 4757@example 4758(@value{GDBP}) p 'f2.c'::x 4759@end example 4760 | 4517@end iftex 4518@example 4519@var{file}::@var{variable} 4520@var{function}::@var{variable} 4521@end example 4522 4523@noindent 4524Here @var{file} or @var{function} is the name of the context for the 4525static @var{variable}. In the case of file names, you can use quotes to 4526make sure @value{GDBN} parses the file name as a single word---for example, 4527to print a global value of @code{x} defined in @file{f2.c}: 4528 4529@example 4530(@value{GDBP}) p 'f2.c'::x 4531@end example 4532 |
| 4761@ifclear CONLY 4762@cindex C++ scope resolution | 4533@cindex C@t{++} scope resolution |
| 4763This use of @samp{::} is very rarely in conflict with the very similar | 4534This use of @samp{::} is very rarely in conflict with the very similar |
| 4764use of the same notation in C++. @value{GDBN} also supports use of the C++ | 4535use of the same notation in C@t{++}. @value{GDBN} also supports use of the C@t{++} |
| 4765scope resolution operator in @value{GDBN} expressions. 4766@c FIXME: Um, so what happens in one of those rare cases where it's in 4767@c conflict?? --mew | 4536scope resolution operator in @value{GDBN} expressions. 4537@c FIXME: Um, so what happens in one of those rare cases where it's in 4538@c conflict?? --mew |
| 4768@end ifclear | |
| 4769 4770@cindex wrong values 4771@cindex variable values, wrong 4772@quotation 4773@emph{Warning:} Occasionally, a local variable may appear to have the 4774wrong value at certain points in a function---just after entry to a new 4775scope, and just before exit. 4776@end quotation --- 5 unchanged lines hidden (view full) --- 4782also takes more than one machine instruction to destroy a stack frame; 4783after you begin stepping through that group of instructions, local 4784variable definitions may be gone. 4785 4786This may also happen when the compiler does significant optimizations. 4787To be sure of always seeing accurate values, turn off all optimization 4788when compiling. 4789 | 4539 4540@cindex wrong values 4541@cindex variable values, wrong 4542@quotation 4543@emph{Warning:} Occasionally, a local variable may appear to have the 4544wrong value at certain points in a function---just after entry to a new 4545scope, and just before exit. 4546@end quotation --- 5 unchanged lines hidden (view full) --- 4552also takes more than one machine instruction to destroy a stack frame; 4553after you begin stepping through that group of instructions, local 4554variable definitions may be gone. 4555 4556This may also happen when the compiler does significant optimizations. 4557To be sure of always seeing accurate values, turn off all optimization 4558when compiling. 4559 |
| 4790@node Arrays, Output Formats, Variables, Data | 4560@cindex ``No symbol "foo" in current context'' 4561Another possible effect of compiler optimizations is to optimize 4562unused variables out of existence, or assign variables to registers (as 4563opposed to memory addresses). Depending on the support for such cases 4564offered by the debug info format used by the compiler, @value{GDBN} 4565might not be able to display values for such local variables. If that 4566happens, @value{GDBN} will print a message like this: 4567 4568@example 4569No symbol "foo" in current context. 4570@end example 4571 4572To solve such problems, either recompile without optimizations, or use a 4573different debug info format, if the compiler supports several such 4574formats. For example, @value{NGCC}, the @sc{gnu} C/C@t{++} compiler usually 4575supports the @samp{-gstabs} option. @samp{-gstabs} produces debug info 4576in a format that is superior to formats such as COFF. You may be able 4577to use DWARF2 (@samp{-gdwarf-2}), which is also an effective form for 4578debug info. See @ref{Debugging Options,,Options for Debugging Your 4579Program or @sc{gnu} CC, gcc.info, Using @sc{gnu} CC}, for more 4580information. 4581 4582 4583@node Arrays |
| 4791@section Artificial arrays 4792 4793@cindex artificial array | 4584@section Artificial arrays 4585 4586@cindex artificial array |
| 4794@kindex @@ | 4587@kindex @@@r{, referencing memory as an array} |
| 4795It is often useful to print out several successive objects of the 4796same type in memory; a section of an array, or an array of 4797dynamically determined size for which only a pointer exists in the 4798program. 4799 4800You can do this by referring to a contiguous span of memory as an 4801@dfn{artificial array}, using the binary operator @samp{@@}. The left 4802operand of @samp{@@} should be the first element of the desired array --- 25 unchanged lines hidden (view full) --- 4828This re-interprets a value as if it were an array. 4829The value need not be in memory: 4830@example 4831(@value{GDBP}) p/x (short[2])0x12345678 4832$1 = @{0x1234, 0x5678@} 4833@end example 4834 4835As a convenience, if you leave the array length out (as in | 4588It is often useful to print out several successive objects of the 4589same type in memory; a section of an array, or an array of 4590dynamically determined size for which only a pointer exists in the 4591program. 4592 4593You can do this by referring to a contiguous span of memory as an 4594@dfn{artificial array}, using the binary operator @samp{@@}. The left 4595operand of @samp{@@} should be the first element of the desired array --- 25 unchanged lines hidden (view full) --- 4621This re-interprets a value as if it were an array. 4622The value need not be in memory: 4623@example 4624(@value{GDBP}) p/x (short[2])0x12345678 4625$1 = @{0x1234, 0x5678@} 4626@end example 4627 4628As a convenience, if you leave the array length out (as in |
| 4836@samp{(@var{type})[])@var{value}}) gdb calculates the size to fill | 4629@samp{(@var{type}[])@var{value}}) @value{GDBN} calculates the size to fill |
| 4837the value (as @samp{sizeof(@var{value})/sizeof(@var{type})}: 4838@example 4839(@value{GDBP}) p/x (short[])0x12345678 4840$2 = @{0x1234, 0x5678@} 4841@end example 4842 4843Sometimes the artificial array mechanism is not quite enough; in 4844moderately complex data structures, the elements of interest may not --- 9 unchanged lines hidden (view full) --- 4854@example 4855set $i = 0 4856p dtab[$i++]->fv 4857@key{RET} 4858@key{RET} 4859@dots{} 4860@end example 4861 | 4630the value (as @samp{sizeof(@var{value})/sizeof(@var{type})}: 4631@example 4632(@value{GDBP}) p/x (short[])0x12345678 4633$2 = @{0x1234, 0x5678@} 4634@end example 4635 4636Sometimes the artificial array mechanism is not quite enough; in 4637moderately complex data structures, the elements of interest may not --- 9 unchanged lines hidden (view full) --- 4647@example 4648set $i = 0 4649p dtab[$i++]->fv 4650@key{RET} 4651@key{RET} 4652@dots{} 4653@end example 4654 |
| 4862@node Output Formats, Memory, Arrays, Data | 4655@node Output Formats |
| 4863@section Output formats 4864 4865@cindex formatted output 4866@cindex output formats 4867By default, @value{GDBN} prints a value according to its data type. Sometimes 4868this is not what you want. For example, you might want to print a number 4869in hex, or a pointer in decimal. Or you might want to view data in memory 4870at a certain address as a character string or as an instruction. To do --- 17 unchanged lines hidden (view full) --- 4888 4889@item o 4890Print as integer in octal. 4891 4892@item t 4893Print as integer in binary. The letter @samp{t} stands for ``two''. 4894@footnote{@samp{b} cannot be used because these format letters are also 4895used with the @code{x} command, where @samp{b} stands for ``byte''; | 4656@section Output formats 4657 4658@cindex formatted output 4659@cindex output formats 4660By default, @value{GDBN} prints a value according to its data type. Sometimes 4661this is not what you want. For example, you might want to print a number 4662in hex, or a pointer in decimal. Or you might want to view data in memory 4663at a certain address as a character string or as an instruction. To do --- 17 unchanged lines hidden (view full) --- 4681 4682@item o 4683Print as integer in octal. 4684 4685@item t 4686Print as integer in binary. The letter @samp{t} stands for ``two''. 4687@footnote{@samp{b} cannot be used because these format letters are also 4688used with the @code{x} command, where @samp{b} stands for ``byte''; |
| 4896@pxref{Memory,,Examining memory}.} | 4689see @ref{Memory,,Examining memory}.} |
| 4897 4898@item a 4899@cindex unknown address, locating | 4690 4691@item a 4692@cindex unknown address, locating |
| 4693@cindex locate address |
|
| 4900Print as an address, both absolute in hexadecimal and as an offset from 4901the nearest preceding symbol. You can use this format used to discover 4902where (in what function) an unknown address is located: 4903 4904@example 4905(@value{GDBP}) p/a 0x54320 4906$3 = 0x54320 <_initialize_vx+396> 4907@end example 4908 | 4694Print as an address, both absolute in hexadecimal and as an offset from 4695the nearest preceding symbol. You can use this format used to discover 4696where (in what function) an unknown address is located: 4697 4698@example 4699(@value{GDBP}) p/a 0x54320 4700$3 = 0x54320 <_initialize_vx+396> 4701@end example 4702 |
| 4703@noindent 4704The command @code{info symbol 0x54320} yields similar results. 4705@xref{Symbols, info symbol}. 4706 |
|
| 4909@item c 4910Regard as an integer and print it as a character constant. 4911 4912@item f 4913Regard the bits of the value as a floating point number and print 4914using typical floating point syntax. 4915@end table 4916 --- 6 unchanged lines hidden (view full) --- 4923@noindent 4924Note that no space is required before the slash; this is because command 4925names in @value{GDBN} cannot contain a slash. 4926 4927To reprint the last value in the value history with a different format, 4928you can use the @code{print} command with just a format and no 4929expression. For example, @samp{p/x} reprints the last value in hex. 4930 | 4707@item c 4708Regard as an integer and print it as a character constant. 4709 4710@item f 4711Regard the bits of the value as a floating point number and print 4712using typical floating point syntax. 4713@end table 4714 --- 6 unchanged lines hidden (view full) --- 4721@noindent 4722Note that no space is required before the slash; this is because command 4723names in @value{GDBN} cannot contain a slash. 4724 4725To reprint the last value in the value history with a different format, 4726you can use the @code{print} command with just a format and no 4727expression. For example, @samp{p/x} reprints the last value in hex. 4728 |
| 4931@node Memory, Auto Display, Output Formats, Data | 4729@node Memory |
| 4932@section Examining memory 4933 4934You can use the command @code{x} (for ``examine'') to examine memory in 4935any of several formats, independently of your program's data types. 4936 4937@cindex examining memory 4938@table @code | 4730@section Examining memory 4731 4732You can use the command @code{x} (for ``examine'') to examine memory in 4733any of several formats, independently of your program's data types. 4734 4735@cindex examining memory 4736@table @code |
| 4939@kindex x | 4737@kindex x @r{(examine memory)} |
| 4940@item x/@var{nfu} @var{addr} 4941@itemx x @var{addr} 4942@itemx x 4943Use the @code{x} command to examine memory. 4944@end table 4945 4946@var{n}, @var{f}, and @var{u} are all optional parameters that specify how 4947much memory to display and how to format it; @var{addr} is an --- 43 unchanged lines hidden (view full) --- 4991starting address of a line), and @code{print} (if you use it to display 4992a value from memory). 4993@end table 4994 4995For example, @samp{x/3uh 0x54320} is a request to display three halfwords 4996(@code{h}) of memory, formatted as unsigned decimal integers (@samp{u}), 4997starting at address @code{0x54320}. @samp{x/4xw $sp} prints the four 4998words (@samp{w}) of memory above the stack pointer (here, @samp{$sp}; | 4738@item x/@var{nfu} @var{addr} 4739@itemx x @var{addr} 4740@itemx x 4741Use the @code{x} command to examine memory. 4742@end table 4743 4744@var{n}, @var{f}, and @var{u} are all optional parameters that specify how 4745much memory to display and how to format it; @var{addr} is an --- 43 unchanged lines hidden (view full) --- 4789starting address of a line), and @code{print} (if you use it to display 4790a value from memory). 4791@end table 4792 4793For example, @samp{x/3uh 0x54320} is a request to display three halfwords 4794(@code{h}) of memory, formatted as unsigned decimal integers (@samp{u}), 4795starting at address @code{0x54320}. @samp{x/4xw $sp} prints the four 4796words (@samp{w}) of memory above the stack pointer (here, @samp{$sp}; |
| 4999@pxref{Registers}) in hexadecimal (@samp{x}). | 4797@pxref{Registers, ,Registers}) in hexadecimal (@samp{x}). |
| 5000 5001Since the letters indicating unit sizes are all distinct from the 5002letters specifying output formats, you do not have to remember whether 5003unit size or format comes first; either order works. The output 5004specifications @samp{4xw} and @samp{4wx} mean exactly the same thing. 5005(However, the count @var{n} must come first; @samp{wx4} does not work.) 5006 5007Even though the unit size @var{u} is ignored for the formats @samp{s} 5008and @samp{i}, you might still want to use a count @var{n}; for example, 5009@samp{3i} specifies that you want to see three machine instructions, 5010including any operands. The command @code{disassemble} gives an | 4798 4799Since the letters indicating unit sizes are all distinct from the 4800letters specifying output formats, you do not have to remember whether 4801unit size or format comes first; either order works. The output 4802specifications @samp{4xw} and @samp{4wx} mean exactly the same thing. 4803(However, the count @var{n} must come first; @samp{wx4} does not work.) 4804 4805Even though the unit size @var{u} is ignored for the formats @samp{s} 4806and @samp{i}, you might still want to use a count @var{n}; for example, 4807@samp{3i} specifies that you want to see three machine instructions, 4808including any operands. The command @code{disassemble} gives an |
| 5011alternative way of inspecting machine instructions; @pxref{Machine | 4809alternative way of inspecting machine instructions; see @ref{Machine |
| 5012Code,,Source and machine code}. 5013 5014All the defaults for the arguments to @code{x} are designed to make it 5015easy to continue scanning memory with minimal specifications each time 5016you use @code{x}. For example, after you have inspected three machine 5017instructions with @samp{x/3i @var{addr}}, you can inspect the next seven 5018with just @samp{x/7}. If you use @key{RET} to repeat the @code{x} command, 5019the repeat count @var{n} is used again; the other arguments default as --- 8 unchanged lines hidden (view full) --- 5028examined is available for use in expressions in the convenience variable 5029@code{$_}. The contents of that address, as examined, are available in 5030the convenience variable @code{$__}. 5031 5032If the @code{x} command has a repeat count, the address and contents saved 5033are from the last memory unit printed; this is not the same as the last 5034address printed if several units were printed on the last line of output. 5035 | 4810Code,,Source and machine code}. 4811 4812All the defaults for the arguments to @code{x} are designed to make it 4813easy to continue scanning memory with minimal specifications each time 4814you use @code{x}. For example, after you have inspected three machine 4815instructions with @samp{x/3i @var{addr}}, you can inspect the next seven 4816with just @samp{x/7}. If you use @key{RET} to repeat the @code{x} command, 4817the repeat count @var{n} is used again; the other arguments default as --- 8 unchanged lines hidden (view full) --- 4826examined is available for use in expressions in the convenience variable 4827@code{$_}. The contents of that address, as examined, are available in 4828the convenience variable @code{$__}. 4829 4830If the @code{x} command has a repeat count, the address and contents saved 4831are from the last memory unit printed; this is not the same as the last 4832address printed if several units were printed on the last line of output. 4833 |
| 5036@node Auto Display, Print Settings, Memory, Data | 4834@node Auto Display |
| 5037@section Automatic display 5038@cindex automatic display 5039@cindex display of expressions 5040 5041If you find that you want to print the value of an expression frequently 5042(to see how it changes), you might want to add it to the @dfn{automatic 5043display list} so that @value{GDBN} prints its value each time your program stops. 5044Each expression added to the list is given a number to identify it; --- 11 unchanged lines hidden (view full) --- 5056specify the output format you prefer; in fact, @code{display} decides 5057whether to use @code{print} or @code{x} depending on how elaborate your 5058format specification is---it uses @code{x} if you specify a unit size, 5059or one of the two formats (@samp{i} and @samp{s}) that are only 5060supported by @code{x}; otherwise it uses @code{print}. 5061 5062@table @code 5063@kindex display | 4835@section Automatic display 4836@cindex automatic display 4837@cindex display of expressions 4838 4839If you find that you want to print the value of an expression frequently 4840(to see how it changes), you might want to add it to the @dfn{automatic 4841display list} so that @value{GDBN} prints its value each time your program stops. 4842Each expression added to the list is given a number to identify it; --- 11 unchanged lines hidden (view full) --- 4854specify the output format you prefer; in fact, @code{display} decides 4855whether to use @code{print} or @code{x} depending on how elaborate your 4856format specification is---it uses @code{x} if you specify a unit size, 4857or one of the two formats (@samp{i} and @samp{s}) that are only 4858supported by @code{x}; otherwise it uses @code{print}. 4859 4860@table @code 4861@kindex display |
| 5064@item display @var{exp} 5065Add the expression @var{exp} to the list of expressions to display | 4862@item display @var{expr} 4863Add the expression @var{expr} to the list of expressions to display |
| 5066each time your program stops. @xref{Expressions, ,Expressions}. 5067 5068@code{display} does not repeat if you press @key{RET} again after using it. 5069 | 4864each time your program stops. @xref{Expressions, ,Expressions}. 4865 4866@code{display} does not repeat if you press @key{RET} again after using it. 4867 |
| 5070@item display/@var{fmt} @var{exp} | 4868@item display/@var{fmt} @var{expr} |
| 5071For @var{fmt} specifying only a display format and not a size or | 4869For @var{fmt} specifying only a display format and not a size or |
| 5072count, add the expression @var{exp} to the auto-display list but | 4870count, add the expression @var{expr} to the auto-display list but |
| 5073arrange to display it each time in the specified format @var{fmt}. 5074@xref{Output Formats,,Output formats}. 5075 5076@item display/@var{fmt} @var{addr} 5077For @var{fmt} @samp{i} or @samp{s}, or including a unit-size or a 5078number of units, add the expression @var{addr} as a memory address to 5079be examined each time your program stops. Examining means in effect 5080doing @samp{x/@var{fmt} @var{addr}}. @xref{Memory, ,Examining memory}. 5081@end table 5082 5083For example, @samp{display/i $pc} can be helpful, to see the machine 5084instruction about to be executed each time execution stops (@samp{$pc} | 4871arrange to display it each time in the specified format @var{fmt}. 4872@xref{Output Formats,,Output formats}. 4873 4874@item display/@var{fmt} @var{addr} 4875For @var{fmt} @samp{i} or @samp{s}, or including a unit-size or a 4876number of units, add the expression @var{addr} as a memory address to 4877be examined each time your program stops. Examining means in effect 4878doing @samp{x/@var{fmt} @var{addr}}. @xref{Memory, ,Examining memory}. 4879@end table 4880 4881For example, @samp{display/i $pc} can be helpful, to see the machine 4882instruction about to be executed each time execution stops (@samp{$pc} |
| 5085is a common name for the program counter; @pxref{Registers}). | 4883is a common name for the program counter; @pxref{Registers, ,Registers}). |
| 5086 5087@table @code 5088@kindex delete display 5089@kindex undisplay 5090@item undisplay @var{dnums}@dots{} 5091@itemx delete display @var{dnums}@dots{} 5092Remove item numbers @var{dnums} from the list of expressions to display. 5093 --- 30 unchanged lines hidden (view full) --- 5124variables is not defined. For example, if you give the command 5125@code{display last_char} while inside a function with an argument 5126@code{last_char}, @value{GDBN} displays this argument while your program 5127continues to stop inside that function. When it stops elsewhere---where 5128there is no variable @code{last_char}---the display is disabled 5129automatically. The next time your program stops where @code{last_char} 5130is meaningful, you can enable the display expression once again. 5131 | 4884 4885@table @code 4886@kindex delete display 4887@kindex undisplay 4888@item undisplay @var{dnums}@dots{} 4889@itemx delete display @var{dnums}@dots{} 4890Remove item numbers @var{dnums} from the list of expressions to display. 4891 --- 30 unchanged lines hidden (view full) --- 4922variables is not defined. For example, if you give the command 4923@code{display last_char} while inside a function with an argument 4924@code{last_char}, @value{GDBN} displays this argument while your program 4925continues to stop inside that function. When it stops elsewhere---where 4926there is no variable @code{last_char}---the display is disabled 4927automatically. The next time your program stops where @code{last_char} 4928is meaningful, you can enable the display expression once again. 4929 |
| 5132@node Print Settings, Value History, Auto Display, Data | 4930@node Print Settings |
| 5133@section Print settings 5134 5135@cindex format options 5136@cindex print settings 5137@value{GDBN} provides the following ways to control how arrays, structures, 5138and symbols are printed. 5139 5140@noindent --- 72 unchanged lines hidden (view full) --- 5213Also, you may wish to see the symbolic form only if the address being 5214printed is reasonably close to the closest earlier symbol: 5215 5216@table @code 5217@kindex set print max-symbolic-offset 5218@item set print max-symbolic-offset @var{max-offset} 5219Tell @value{GDBN} to only display the symbolic form of an address if the 5220offset between the closest earlier symbol and the address is less than | 4931@section Print settings 4932 4933@cindex format options 4934@cindex print settings 4935@value{GDBN} provides the following ways to control how arrays, structures, 4936and symbols are printed. 4937 4938@noindent --- 72 unchanged lines hidden (view full) --- 5011Also, you may wish to see the symbolic form only if the address being 5012printed is reasonably close to the closest earlier symbol: 5013 5014@table @code 5015@kindex set print max-symbolic-offset 5016@item set print max-symbolic-offset @var{max-offset} 5017Tell @value{GDBN} to only display the symbolic form of an address if the 5018offset between the closest earlier symbol and the address is less than |
| 5221@var{max-offset}. The default is 0, which tells @value{GDBN} | 5019@var{max-offset}. The default is 0, which tells @value{GDBN} |
| 5222to always print the symbolic form of an address if any symbol precedes it. 5223 5224@kindex show print max-symbolic-offset 5225@item show print max-symbolic-offset 5226Ask how large the maximum offset is that @value{GDBN} prints in a 5227symbolic address. 5228@end table 5229 --- 36 unchanged lines hidden (view full) --- 5266arrays. 5267 5268@kindex set print elements 5269@item set print elements @var{number-of-elements} 5270Set a limit on how many elements of an array @value{GDBN} will print. 5271If @value{GDBN} is printing a large array, it stops printing after it has 5272printed the number of elements set by the @code{set print elements} command. 5273This limit also applies to the display of strings. | 5020to always print the symbolic form of an address if any symbol precedes it. 5021 5022@kindex show print max-symbolic-offset 5023@item show print max-symbolic-offset 5024Ask how large the maximum offset is that @value{GDBN} prints in a 5025symbolic address. 5026@end table 5027 --- 36 unchanged lines hidden (view full) --- 5064arrays. 5065 5066@kindex set print elements 5067@item set print elements @var{number-of-elements} 5068Set a limit on how many elements of an array @value{GDBN} will print. 5069If @value{GDBN} is printing a large array, it stops printing after it has 5070printed the number of elements set by the @code{set print elements} command. 5071This limit also applies to the display of strings. |
| 5072When @value{GDBN} starts, this limit is set to 200. |
|
| 5274Setting @var{number-of-elements} to zero means that the printing is unlimited. 5275 5276@kindex show print elements 5277@item show print elements 5278Display the number of elements of a large array that @value{GDBN} will print. 5279If the number is 0, then the printing is unlimited. 5280 5281@kindex set print null-stop 5282@item set print null-stop 5283Cause @value{GDBN} to stop printing the characters of an array when the first | 5073Setting @var{number-of-elements} to zero means that the printing is unlimited. 5074 5075@kindex show print elements 5076@item show print elements 5077Display the number of elements of a large array that @value{GDBN} will print. 5078If the number is 0, then the printing is unlimited. 5079 5080@kindex set print null-stop 5081@item set print null-stop 5082Cause @value{GDBN} to stop printing the characters of an array when the first |
| 5284@sc{NULL} is encountered. This is useful when large arrays actually | 5083@sc{null} is encountered. This is useful when large arrays actually |
| 5285contain only short strings. | 5084contain only short strings. |
| 5085The default is off. |
|
| 5286 5287@kindex set print pretty 5288@item set print pretty on | 5086 5087@kindex set print pretty 5088@item set print pretty on |
| 5289Cause @value{GDBN} to print structures in an indented format with one member | 5089Cause @value{GDBN} to print structures in an indented format with one member |
| 5290per line, like this: 5291 5292@smallexample 5293@group 5294$1 = @{ 5295 next = 0x0, 5296 flags = @{ 5297 sweet = 1, --- 34 unchanged lines hidden (view full) --- 5332international character sets, and is the default. 5333 5334@kindex show print sevenbit-strings 5335@item show print sevenbit-strings 5336Show whether or not @value{GDBN} is printing only seven-bit characters. 5337 5338@kindex set print union 5339@item set print union on | 5090per line, like this: 5091 5092@smallexample 5093@group 5094$1 = @{ 5095 next = 0x0, 5096 flags = @{ 5097 sweet = 1, --- 34 unchanged lines hidden (view full) --- 5132international character sets, and is the default. 5133 5134@kindex show print sevenbit-strings 5135@item show print sevenbit-strings 5136Show whether or not @value{GDBN} is printing only seven-bit characters. 5137 5138@kindex set print union 5139@item set print union on |
| 5340Tell @value{GDBN} to print unions which are contained in structures. This | 5140Tell @value{GDBN} to print unions which are contained in structures. This |
| 5341is the default setting. 5342 5343@item set print union off 5344Tell @value{GDBN} not to print unions which are contained in structures. 5345 5346@kindex show print union 5347@item show print union 5348Ask @value{GDBN} whether or not it will print unions which are contained in 5349structures. 5350 5351For example, given the declarations 5352 5353@smallexample 5354typedef enum @{Tree, Bug@} Species; 5355typedef enum @{Big_tree, Acorn, Seedling@} Tree_forms; | 5141is the default setting. 5142 5143@item set print union off 5144Tell @value{GDBN} not to print unions which are contained in structures. 5145 5146@kindex show print union 5147@item show print union 5148Ask @value{GDBN} whether or not it will print unions which are contained in 5149structures. 5150 5151For example, given the declarations 5152 5153@smallexample 5154typedef enum @{Tree, Bug@} Species; 5155typedef enum @{Big_tree, Acorn, Seedling@} Tree_forms; |
| 5356typedef enum @{Caterpillar, Cocoon, Butterfly@} | 5156typedef enum @{Caterpillar, Cocoon, Butterfly@} |
| 5357 Bug_forms; 5358 5359struct thing @{ 5360 Species it; 5361 union @{ 5362 Tree_forms tree; 5363 Bug_forms bug; 5364 @} form; --- 12 unchanged lines hidden (view full) --- 5377@noindent 5378and with @code{set print union off} in effect it would print 5379 5380@smallexample 5381$1 = @{it = Tree, form = @{...@}@} 5382@end smallexample 5383@end table 5384 | 5157 Bug_forms; 5158 5159struct thing @{ 5160 Species it; 5161 union @{ 5162 Tree_forms tree; 5163 Bug_forms bug; 5164 @} form; --- 12 unchanged lines hidden (view full) --- 5177@noindent 5178and with @code{set print union off} in effect it would print 5179 5180@smallexample 5181$1 = @{it = Tree, form = @{...@}@} 5182@end smallexample 5183@end table 5184 |
| 5385@ifclear CONLY | |
| 5386@need 1000 5387@noindent | 5185@need 1000 5186@noindent |
| 5388These settings are of interest when debugging C++ programs: | 5187These settings are of interest when debugging C@t{++} programs: |
| 5389 5390@table @code 5391@cindex demangling 5392@kindex set print demangle 5393@item set print demangle 5394@itemx set print demangle on | 5188 5189@table @code 5190@cindex demangling 5191@kindex set print demangle 5192@item set print demangle 5193@itemx set print demangle on |
| 5395Print C++ names in their source form rather than in the encoded | 5194Print C@t{++} names in their source form rather than in the encoded |
| 5396(``mangled'') form passed to the assembler and linker for type-safe | 5195(``mangled'') form passed to the assembler and linker for type-safe |
| 5397linkage. The default is @samp{on}. | 5196linkage. The default is on. |
| 5398 5399@kindex show print demangle 5400@item show print demangle | 5197 5198@kindex show print demangle 5199@item show print demangle |
| 5401Show whether C++ names are printed in mangled or demangled form. | 5200Show whether C@t{++} names are printed in mangled or demangled form. |
| 5402 5403@kindex set print asm-demangle 5404@item set print asm-demangle 5405@itemx set print asm-demangle on | 5201 5202@kindex set print asm-demangle 5203@item set print asm-demangle 5204@itemx set print asm-demangle on |
| 5406Print C++ names in their source form rather than their mangled form, even | 5205Print C@t{++} names in their source form rather than their mangled form, even |
| 5407in assembler code printouts such as instruction disassemblies. 5408The default is off. 5409 5410@kindex show print asm-demangle 5411@item show print asm-demangle | 5206in assembler code printouts such as instruction disassemblies. 5207The default is off. 5208 5209@kindex show print asm-demangle 5210@item show print asm-demangle |
| 5412Show whether C++ names in assembly listings are printed in mangled | 5211Show whether C@t{++} names in assembly listings are printed in mangled |
| 5413or demangled form. 5414 5415@kindex set demangle-style | 5212or demangled form. 5213 5214@kindex set demangle-style |
| 5416@cindex C++ symbol decoding style 5417@cindex symbol decoding style, C++ | 5215@cindex C@t{++} symbol decoding style 5216@cindex symbol decoding style, C@t{++} |
| 5418@item set demangle-style @var{style} 5419Choose among several encoding schemes used by different compilers to | 5217@item set demangle-style @var{style} 5218Choose among several encoding schemes used by different compilers to |
| 5420represent C++ names. The choices for @var{style} are currently: | 5219represent C@t{++} names. The choices for @var{style} are currently: |
| 5421 5422@table @code 5423@item auto 5424Allow @value{GDBN} to choose a decoding style by inspecting your program. 5425 5426@item gnu | 5220 5221@table @code 5222@item auto 5223Allow @value{GDBN} to choose a decoding style by inspecting your program. 5224 5225@item gnu |
| 5427Decode based on the @sc{gnu} C++ compiler (@code{g++}) encoding algorithm. 5428@ifclear HPPA | 5226Decode based on the @sc{gnu} C@t{++} compiler (@code{g++}) encoding algorithm. |
| 5429This is the default. | 5227This is the default. |
| 5430@end ifclear | |
| 5431 5432@item hp | 5228 5229@item hp |
| 5433Decode based on the HP ANSI C++ (@code{aCC}) encoding algorithm. | 5230Decode based on the HP ANSI C@t{++} (@code{aCC}) encoding algorithm. |
| 5434 5435@item lucid | 5231 5232@item lucid |
| 5436Decode based on the Lucid C++ compiler (@code{lcc}) encoding algorithm. | 5233Decode based on the Lucid C@t{++} compiler (@code{lcc}) encoding algorithm. |
| 5437 5438@item arm | 5234 5235@item arm |
| 5439Decode using the algorithm in the @cite{C++ Annotated Reference Manual}. | 5236Decode using the algorithm in the @cite{C@t{++} Annotated Reference Manual}. |
| 5440@strong{Warning:} this setting alone is not sufficient to allow 5441debugging @code{cfront}-generated executables. @value{GDBN} would 5442require further enhancement to permit that. 5443 5444@end table 5445If you omit @var{style}, you will see a list of possible formats. 5446 5447@kindex show demangle-style 5448@item show demangle-style | 5237@strong{Warning:} this setting alone is not sufficient to allow 5238debugging @code{cfront}-generated executables. @value{GDBN} would 5239require further enhancement to permit that. 5240 5241@end table 5242If you omit @var{style}, you will see a list of possible formats. 5243 5244@kindex show demangle-style 5245@item show demangle-style |
| 5449Display the encoding style currently in use for decoding C++ symbols. | 5246Display the encoding style currently in use for decoding C@t{++} symbols. |
| 5450 5451@kindex set print object 5452@item set print object 5453@itemx set print object on 5454When displaying a pointer to an object, identify the @emph{actual} 5455(derived) type of the object rather than the @emph{declared} type, using 5456the virtual function table. 5457 5458@item set print object off 5459Display only the declared type of objects, without reference to the 5460virtual function table. This is the default setting. 5461 5462@kindex show print object 5463@item show print object 5464Show whether actual, or declared, object types are displayed. 5465 5466@kindex set print static-members 5467@item set print static-members 5468@itemx set print static-members on | 5247 5248@kindex set print object 5249@item set print object 5250@itemx set print object on 5251When displaying a pointer to an object, identify the @emph{actual} 5252(derived) type of the object rather than the @emph{declared} type, using 5253the virtual function table. 5254 5255@item set print object off 5256Display only the declared type of objects, without reference to the 5257virtual function table. This is the default setting. 5258 5259@kindex show print object 5260@item show print object 5261Show whether actual, or declared, object types are displayed. 5262 5263@kindex set print static-members 5264@item set print static-members 5265@itemx set print static-members on |
| 5469Print static members when displaying a C++ object. The default is on. | 5266Print static members when displaying a C@t{++} object. The default is on. |
| 5470 5471@item set print static-members off | 5267 5268@item set print static-members off |
| 5472Do not print static members when displaying a C++ object. | 5269Do not print static members when displaying a C@t{++} object. |
| 5473 5474@kindex show print static-members 5475@item show print static-members | 5270 5271@kindex show print static-members 5272@item show print static-members |
| 5476Show whether C++ static members are printed, or not. | 5273Show whether C@t{++} static members are printed, or not. |
| 5477 5478@c These don't work with HP ANSI C++ yet. 5479@kindex set print vtbl 5480@item set print vtbl 5481@itemx set print vtbl on | 5274 5275@c These don't work with HP ANSI C++ yet. 5276@kindex set print vtbl 5277@item set print vtbl 5278@itemx set print vtbl on |
| 5482Pretty print C++ virtual function tables. The default is off. 5483@ifset HPPA | 5279Pretty print C@t{++} virtual function tables. The default is off. |
| 5484(The @code{vtbl} commands do not work on programs compiled with the HP | 5280(The @code{vtbl} commands do not work on programs compiled with the HP |
| 5485ANSI C++ compiler (@code{aCC}).) 5486@end ifset | 5281ANSI C@t{++} compiler (@code{aCC}).) |
| 5487 5488@item set print vtbl off | 5282 5283@item set print vtbl off |
| 5489Do not pretty print C++ virtual function tables. | 5284Do not pretty print C@t{++} virtual function tables. |
| 5490 5491@kindex show print vtbl 5492@item show print vtbl | 5285 5286@kindex show print vtbl 5287@item show print vtbl |
| 5493Show whether C++ virtual function tables are pretty printed, or not. | 5288Show whether C@t{++} virtual function tables are pretty printed, or not. |
| 5494@end table | 5289@end table |
| 5495@end ifclear | |
| 5496 | 5290 |
| 5497@node Value History, Convenience Vars, Print Settings, Data | 5291@node Value History |
| 5498@section Value history 5499 5500@cindex value history | 5292@section Value history 5293 5294@cindex value history |
| 5501Values printed by the @code{print} command are saved in the @value{GDBN} 5502@dfn{value history}. This allows you to refer to them in other expressions. 5503Values are kept until the symbol table is re-read or discarded 5504(for example with the @code{file} or @code{symbol-file} commands). 5505When the symbol table changes, the value history is discarded, 5506since the values may contain pointers back to the types defined in the | 5295Values printed by the @code{print} command are saved in the @value{GDBN} 5296@dfn{value history}. This allows you to refer to them in other expressions. 5297Values are kept until the symbol table is re-read or discarded 5298(for example with the @code{file} or @code{symbol-file} commands). 5299When the symbol table changes, the value history is discarded, 5300since the values may contain pointers back to the types defined in the |
| 5507symbol table. 5508 5509@cindex @code{$} 5510@cindex @code{$$} 5511@cindex history number 5512The values printed are given @dfn{history numbers} by which you can 5513refer to them. These are successive integers starting with one. 5514@code{print} shows you the history number assigned to a value by --- 51 unchanged lines hidden (view full) --- 5566@item show values + 5567Print ten history values just after the values last printed. If no more 5568values are available, @code{show values +} produces no display. 5569@end table 5570 5571Pressing @key{RET} to repeat @code{show values @var{n}} has exactly the 5572same effect as @samp{show values +}. 5573 | 5301symbol table. 5302 5303@cindex @code{$} 5304@cindex @code{$$} 5305@cindex history number 5306The values printed are given @dfn{history numbers} by which you can 5307refer to them. These are successive integers starting with one. 5308@code{print} shows you the history number assigned to a value by --- 51 unchanged lines hidden (view full) --- 5360@item show values + 5361Print ten history values just after the values last printed. If no more 5362values are available, @code{show values +} produces no display. 5363@end table 5364 5365Pressing @key{RET} to repeat @code{show values @var{n}} has exactly the 5366same effect as @samp{show values +}. 5367 |
| 5574@node Convenience Vars, Registers, Value History, Data | 5368@node Convenience Vars |
| 5575@section Convenience variables 5576 5577@cindex convenience variables 5578@value{GDBN} provides @dfn{convenience variables} that you can use within 5579@value{GDBN} to hold on to a value and refer to it later. These variables 5580exist entirely within @value{GDBN}; they are not part of your program, and 5581setting a convenience variable has no direct effect on further execution 5582of your program. That is why you can use them freely. 5583 5584Convenience variables are prefixed with @samp{$}. Any name preceded by 5585@samp{$} can be used for a convenience variable, unless it is one of | 5369@section Convenience variables 5370 5371@cindex convenience variables 5372@value{GDBN} provides @dfn{convenience variables} that you can use within 5373@value{GDBN} to hold on to a value and refer to it later. These variables 5374exist entirely within @value{GDBN}; they are not part of your program, and 5375setting a convenience variable has no direct effect on further execution 5376of your program. That is why you can use them freely. 5377 5378Convenience variables are prefixed with @samp{$}. Any name preceded by 5379@samp{$} can be used for a convenience variable, unless it is one of |
| 5586the predefined machine-specific register names (@pxref{Registers}). | 5380the predefined machine-specific register names (@pxref{Registers, ,Registers}). |
| 5587(Value history references, in contrast, are @emph{numbers} preceded 5588by @samp{$}. @xref{Value History, ,Value history}.) 5589 5590You can save a value in a convenience variable with an assignment 5591expression, just as you would set a variable in your program. 5592For example: 5593 5594@example --- 12 unchanged lines hidden (view full) --- 5607variable any type of value, including structures and arrays, even if 5608that variable already has a value of a different type. The convenience 5609variable, when used as an expression, has the type of its current value. 5610 5611@table @code 5612@kindex show convenience 5613@item show convenience 5614Print a list of convenience variables used so far, and their values. | 5381(Value history references, in contrast, are @emph{numbers} preceded 5382by @samp{$}. @xref{Value History, ,Value history}.) 5383 5384You can save a value in a convenience variable with an assignment 5385expression, just as you would set a variable in your program. 5386For example: 5387 5388@example --- 12 unchanged lines hidden (view full) --- 5401variable any type of value, including structures and arrays, even if 5402that variable already has a value of a different type. The convenience 5403variable, when used as an expression, has the type of its current value. 5404 5405@table @code 5406@kindex show convenience 5407@item show convenience 5408Print a list of convenience variables used so far, and their values. |
| 5615Abbreviated @code{show con}. | 5409Abbreviated @code{show conv}. |
| 5616@end table 5617 5618One of the ways to use a convenience variable is as a counter to be 5619incremented or a pointer to be advanced. For example, to print 5620a field from successive elements of an array of structures: 5621 5622@example 5623set $i = 0 5624print bar[$i++]->contents 5625@end example 5626 | 5410@end table 5411 5412One of the ways to use a convenience variable is as a counter to be 5413incremented or a pointer to be advanced. For example, to print 5414a field from successive elements of an array of structures: 5415 5416@example 5417set $i = 0 5418print bar[$i++]->contents 5419@end example 5420 |
| 5627@noindent Repeat that command by typing @key{RET}. | 5421@noindent 5422Repeat that command by typing @key{RET}. |
| 5628 5629Some convenience variables are created automatically by @value{GDBN} and given 5630values likely to be useful. 5631 5632@table @code | 5423 5424Some convenience variables are created automatically by @value{GDBN} and given 5425values likely to be useful. 5426 5427@table @code |
| 5633@kindex $_ | 5428@vindex $_@r{, convenience variable} |
| 5634@item $_ 5635The variable @code{$_} is automatically set by the @code{x} command to 5636the last address examined (@pxref{Memory, ,Examining memory}). Other 5637commands which provide a default address for @code{x} to examine also 5638set @code{$_} to that address; these commands include @code{info line} 5639and @code{info breakpoint}. The type of @code{$_} is @code{void *} 5640except when set by the @code{x} command, in which case it is a pointer 5641to the type of @code{$__}. 5642 | 5429@item $_ 5430The variable @code{$_} is automatically set by the @code{x} command to 5431the last address examined (@pxref{Memory, ,Examining memory}). Other 5432commands which provide a default address for @code{x} to examine also 5433set @code{$_} to that address; these commands include @code{info line} 5434and @code{info breakpoint}. The type of @code{$_} is @code{void *} 5435except when set by the @code{x} command, in which case it is a pointer 5436to the type of @code{$__}. 5437 |
| 5643@kindex $__ | 5438@vindex $__@r{, convenience variable} |
| 5644@item $__ 5645The variable @code{$__} is automatically set by the @code{x} command 5646to the value found in the last address examined. Its type is chosen 5647to match the format in which the data was printed. 5648 5649@item $_exitcode | 5439@item $__ 5440The variable @code{$__} is automatically set by the @code{x} command 5441to the value found in the last address examined. Its type is chosen 5442to match the format in which the data was printed. 5443 5444@item $_exitcode |
| 5650@kindex $_exitcode | 5445@vindex $_exitcode@r{, convenience variable} |
| 5651The variable @code{$_exitcode} is automatically set to the exit code when 5652the program being debugged terminates. 5653@end table 5654 | 5446The variable @code{$_exitcode} is automatically set to the exit code when 5447the program being debugged terminates. 5448@end table 5449 |
| 5655@ifset HPPA 5656If you refer to a function or variable name that begins with a dollar 5657sign, @value{GDBN} searches for a user or system name first, before it 5658searches for a convenience variable. 5659@end ifset | 5450On HP-UX systems, if you refer to a function or variable name that 5451begins with a dollar sign, @value{GDBN} searches for a user or system 5452name first, before it searches for a convenience variable. |
| 5660 | 5453 |
| 5661@node Registers, Floating Point Hardware, Convenience Vars, Data | 5454@node Registers |
| 5662@section Registers 5663 5664@cindex registers 5665You can refer to machine register contents, in expressions, as variables 5666with names starting with @samp{$}. The names of registers are different 5667for each machine; use @code{info registers} to see the names used on 5668your machine. 5669 --- 6 unchanged lines hidden (view full) --- 5676@kindex info all-registers 5677@cindex floating point registers 5678@item info all-registers 5679Print the names and values of all registers, including floating-point 5680registers. 5681 5682@item info registers @var{regname} @dots{} 5683Print the @dfn{relativized} value of each specified register @var{regname}. | 5455@section Registers 5456 5457@cindex registers 5458You can refer to machine register contents, in expressions, as variables 5459with names starting with @samp{$}. The names of registers are different 5460for each machine; use @code{info registers} to see the names used on 5461your machine. 5462 --- 6 unchanged lines hidden (view full) --- 5469@kindex info all-registers 5470@cindex floating point registers 5471@item info all-registers 5472Print the names and values of all registers, including floating-point 5473registers. 5474 5475@item info registers @var{regname} @dots{} 5476Print the @dfn{relativized} value of each specified register @var{regname}. |
| 5684As discussed in detail below, register values are normally relative to 5685the selected stack frame. @var{regname} may be any register name valid on | 5477As discussed in detail below, register values are normally relative to 5478the selected stack frame. @var{regname} may be any register name valid on |
| 5686the machine you are using, with or without the initial @samp{$}. 5687@end table 5688 5689@value{GDBN} has four ``standard'' register names that are available (in 5690expressions) on most machines---whenever they do not conflict with an 5691architecture's canonical mnemonics for registers. The register names 5692@code{$pc} and @code{$sp} are used for the program counter register and 5693the stack pointer. @code{$fp} is used for a register that contains a --- 14 unchanged lines hidden (view full) --- 5708 5709@noindent 5710or add four to the stack pointer@footnote{This is a way of removing 5711one word from the stack, on machines where stacks grow downward in 5712memory (most machines, nowadays). This assumes that the innermost 5713stack frame is selected; setting @code{$sp} is not allowed when other 5714stack frames are selected. To pop entire frames off the stack, 5715regardless of machine architecture, use @code{return}; | 5479the machine you are using, with or without the initial @samp{$}. 5480@end table 5481 5482@value{GDBN} has four ``standard'' register names that are available (in 5483expressions) on most machines---whenever they do not conflict with an 5484architecture's canonical mnemonics for registers. The register names 5485@code{$pc} and @code{$sp} are used for the program counter register and 5486the stack pointer. @code{$fp} is used for a register that contains a --- 14 unchanged lines hidden (view full) --- 5501 5502@noindent 5503or add four to the stack pointer@footnote{This is a way of removing 5504one word from the stack, on machines where stacks grow downward in 5505memory (most machines, nowadays). This assumes that the innermost 5506stack frame is selected; setting @code{$sp} is not allowed when other 5507stack frames are selected. To pop entire frames off the stack, 5508regardless of machine architecture, use @code{return}; |
| 5716@pxref{Returning, ,Returning from a function}.} with | 5509see @ref{Returning, ,Returning from a function}.} with |
| 5717 5718@example 5719set $sp += 4 5720@end example 5721 5722Whenever possible, these four standard register names are available on 5723your machine even though the machine has different canonical mnemonics, 5724so long as there is no conflict. The @code{info registers} command 5725shows the canonical names. For example, on the SPARC, @code{info 5726registers} displays the processor status register as @code{$psr} but you | 5510 5511@example 5512set $sp += 4 5513@end example 5514 5515Whenever possible, these four standard register names are available on 5516your machine even though the machine has different canonical mnemonics, 5517so long as there is no conflict. The @code{info registers} command 5518shows the canonical names. For example, on the SPARC, @code{info 5519registers} displays the processor status register as @code{$psr} but you |
| 5727can also refer to it as @code{$ps}. | 5520can also refer to it as @code{$ps}; and on x86-based machines @code{$ps} 5521is an alias for the @sc{eflags} register. |
| 5728 5729@value{GDBN} always considers the contents of an ordinary register as an 5730integer when the register is examined in this way. Some machines have 5731special registers which can hold nothing but floating point; these 5732registers are considered to have floating point values. There is no way 5733to refer to the contents of an ordinary register as floating point value 5734(although you can @emph{print} it as a floating point value with 5735@samp{print/f $@var{regname}}). 5736 5737Some registers have distinct ``raw'' and ``virtual'' data formats. This 5738means that the data format in which the register contents are saved by 5739the operating system is not the same one that your program normally 5740sees. For example, the registers of the 68881 floating point 5741coprocessor are always saved in ``extended'' (raw) format, but all C 5742programs expect to work with ``double'' (virtual) format. In such | 5522 5523@value{GDBN} always considers the contents of an ordinary register as an 5524integer when the register is examined in this way. Some machines have 5525special registers which can hold nothing but floating point; these 5526registers are considered to have floating point values. There is no way 5527to refer to the contents of an ordinary register as floating point value 5528(although you can @emph{print} it as a floating point value with 5529@samp{print/f $@var{regname}}). 5530 5531Some registers have distinct ``raw'' and ``virtual'' data formats. This 5532means that the data format in which the register contents are saved by 5533the operating system is not the same one that your program normally 5534sees. For example, the registers of the 68881 floating point 5535coprocessor are always saved in ``extended'' (raw) format, but all C 5536programs expect to work with ``double'' (virtual) format. In such |
| 5743cases, @value{GDBN} normally works with the virtual format only (the format | 5537cases, @value{GDBN} normally works with the virtual format only (the format |
| 5744that makes sense for your program), but the @code{info registers} command 5745prints the data in both formats. 5746 5747Normally, register values are relative to the selected stack frame 5748(@pxref{Selection, ,Selecting a frame}). This means that you get the 5749value that the register would contain if all stack frames farther in 5750were exited and their saved registers restored. In order to see the 5751true contents of hardware registers, you must select the innermost 5752frame (with @samp{frame 0}). 5753 5754However, @value{GDBN} must deduce where registers are saved, from the machine 5755code generated by your compiler. If some registers are not saved, or if 5756@value{GDBN} is unable to locate the saved registers, the selected stack 5757frame makes no difference. 5758 | 5538that makes sense for your program), but the @code{info registers} command 5539prints the data in both formats. 5540 5541Normally, register values are relative to the selected stack frame 5542(@pxref{Selection, ,Selecting a frame}). This means that you get the 5543value that the register would contain if all stack frames farther in 5544were exited and their saved registers restored. In order to see the 5545true contents of hardware registers, you must select the innermost 5546frame (with @samp{frame 0}). 5547 5548However, @value{GDBN} must deduce where registers are saved, from the machine 5549code generated by your compiler. If some registers are not saved, or if 5550@value{GDBN} is unable to locate the saved registers, the selected stack 5551frame makes no difference. 5552 |
| 5759@ifset AMD29K 5760@table @code 5761@kindex set rstack_high_address 5762@cindex AMD 29K register stack 5763@cindex register stack, AMD29K 5764@item set rstack_high_address @var{address} 5765On AMD 29000 family processors, registers are saved in a separate 5766``register stack''. There is no way for @value{GDBN} to determine the extent 5767of this stack. Normally, @value{GDBN} just assumes that the stack is ``large 5768enough''. This may result in @value{GDBN} referencing memory locations that 5769do not exist. If necessary, you can get around this problem by 5770specifying the ending address of the register stack with the @code{set 5771rstack_high_address} command. The argument should be an address, which 5772you probably want to precede with @samp{0x} to specify in 5773hexadecimal. 5774 5775@kindex show rstack_high_address 5776@item show rstack_high_address 5777Display the current limit of the register stack, on AMD 29000 family 5778processors. 5779@end table 5780@end ifset 5781 5782@ifclear HAVE-FLOAT 5783@node Floating Point Hardware, , Registers, Data | 5553@node Floating Point Hardware |
| 5784@section Floating point hardware 5785@cindex floating point 5786 5787Depending on the configuration, @value{GDBN} may be able to give 5788you more information about the status of the floating point hardware. 5789 5790@table @code 5791@kindex info float 5792@item info float 5793Display hardware-dependent information about the floating 5794point unit. The exact contents and layout vary depending on the 5795floating point chip. Currently, @samp{info float} is supported on 5796the ARM and x86 machines. 5797@end table | 5554@section Floating point hardware 5555@cindex floating point 5556 5557Depending on the configuration, @value{GDBN} may be able to give 5558you more information about the status of the floating point hardware. 5559 5560@table @code 5561@kindex info float 5562@item info float 5563Display hardware-dependent information about the floating 5564point unit. The exact contents and layout vary depending on the 5565floating point chip. Currently, @samp{info float} is supported on 5566the ARM and x86 machines. 5567@end table |
| 5798@end ifclear | |
| 5799 | 5568 |
| 5800@ifclear CONLY 5801@node Languages, Symbols, Data, Top | 5569@node Memory Region Attributes 5570@section Memory Region Attributes 5571@cindex memory region attributes 5572 5573@dfn{Memory region attributes} allow you to describe special handling 5574required by regions of your target's memory. @value{GDBN} uses attributes 5575to determine whether to allow certain types of memory accesses; whether to 5576use specific width accesses; and whether to cache target memory. 5577 5578Defined memory regions can be individually enabled and disabled. When a 5579memory region is disabled, @value{GDBN} uses the default attributes when 5580accessing memory in that region. Similarly, if no memory regions have 5581been defined, @value{GDBN} uses the default attributes when accessing 5582all memory. 5583 5584When a memory region is defined, it is given a number to identify it; 5585to enable, disable, or remove a memory region, you specify that number. 5586 5587@table @code 5588@kindex mem 5589@item mem @var{address1} @var{address2} @var{attributes}@dots{} 5590Define memory region bounded by @var{address1} and @var{address2} 5591with attributes @var{attributes}@dots{}. 5592 5593@kindex delete mem 5594@item delete mem @var{nums}@dots{} 5595Remove memory regions @var{nums}@dots{}. 5596 5597@kindex disable mem 5598@item disable mem @var{nums}@dots{} 5599Disable memory regions @var{nums}@dots{}. 5600A disabled memory region is not forgotten. 5601It may be enabled again later. 5602 5603@kindex enable mem 5604@item enable mem @var{nums}@dots{} 5605Enable memory regions @var{nums}@dots{}. 5606 5607@kindex info mem 5608@item info mem 5609Print a table of all defined memory regions, with the following columns 5610for each region. 5611 5612@table @emph 5613@item Memory Region Number 5614@item Enabled or Disabled. 5615Enabled memory regions are marked with @samp{y}. 5616Disabled memory regions are marked with @samp{n}. 5617 5618@item Lo Address 5619The address defining the inclusive lower bound of the memory region. 5620 5621@item Hi Address 5622The address defining the exclusive upper bound of the memory region. 5623 5624@item Attributes 5625The list of attributes set for this memory region. 5626@end table 5627@end table 5628 5629 5630@subsection Attributes 5631 5632@subsubsection Memory Access Mode 5633The access mode attributes set whether @value{GDBN} may make read or 5634write accesses to a memory region. 5635 5636While these attributes prevent @value{GDBN} from performing invalid 5637memory accesses, they do nothing to prevent the target system, I/O DMA, 5638etc. from accessing memory. 5639 5640@table @code 5641@item ro 5642Memory is read only. 5643@item wo 5644Memory is write only. 5645@item rw 5646Memory is read/write. This is the default. 5647@end table 5648 5649@subsubsection Memory Access Size 5650The acccess size attributes tells @value{GDBN} to use specific sized 5651accesses in the memory region. Often memory mapped device registers 5652require specific sized accesses. If no access size attribute is 5653specified, @value{GDBN} may use accesses of any size. 5654 5655@table @code 5656@item 8 5657Use 8 bit memory accesses. 5658@item 16 5659Use 16 bit memory accesses. 5660@item 32 5661Use 32 bit memory accesses. 5662@item 64 5663Use 64 bit memory accesses. 5664@end table 5665 5666@c @subsubsection Hardware/Software Breakpoints 5667@c The hardware/software breakpoint attributes set whether @value{GDBN} 5668@c will use hardware or software breakpoints for the internal breakpoints 5669@c used by the step, next, finish, until, etc. commands. 5670@c 5671@c @table @code 5672@c @item hwbreak 5673@c Always use hardware breakpoints 5674@c @item swbreak (default) 5675@c @end table 5676 5677@subsubsection Data Cache 5678The data cache attributes set whether @value{GDBN} will cache target 5679memory. While this generally improves performance by reducing debug 5680protocol overhead, it can lead to incorrect results because @value{GDBN} 5681does not know about volatile variables or memory mapped device 5682registers. 5683 5684@table @code 5685@item cache 5686Enable @value{GDBN} to cache target memory. 5687@item nocache 5688Disable @value{GDBN} from caching target memory. This is the default. 5689@end table 5690 5691@c @subsubsection Memory Write Verification 5692@c The memory write verification attributes set whether @value{GDBN} 5693@c will re-reads data after each write to verify the write was successful. 5694@c 5695@c @table @code 5696@c @item verify 5697@c @item noverify (default) 5698@c @end table 5699 5700@node Tracepoints 5701@chapter Tracepoints 5702@c This chapter is based on the documentation written by Michael 5703@c Snyder, David Taylor, Jim Blandy, and Elena Zannoni. 5704 5705@cindex tracepoints 5706In some applications, it is not feasible for the debugger to interrupt 5707the program's execution long enough for the developer to learn 5708anything helpful about its behavior. If the program's correctness 5709depends on its real-time behavior, delays introduced by a debugger 5710might cause the program to change its behavior drastically, or perhaps 5711fail, even when the code itself is correct. It is useful to be able 5712to observe the program's behavior without interrupting it. 5713 5714Using @value{GDBN}'s @code{trace} and @code{collect} commands, you can 5715specify locations in the program, called @dfn{tracepoints}, and 5716arbitrary expressions to evaluate when those tracepoints are reached. 5717Later, using the @code{tfind} command, you can examine the values 5718those expressions had when the program hit the tracepoints. The 5719expressions may also denote objects in memory---structures or arrays, 5720for example---whose values @value{GDBN} should record; while visiting 5721a particular tracepoint, you may inspect those objects as if they were 5722in memory at that moment. However, because @value{GDBN} records these 5723values without interacting with you, it can do so quickly and 5724unobtrusively, hopefully not disturbing the program's behavior. 5725 5726The tracepoint facility is currently available only for remote 5727targets. @xref{Targets}. In addition, your remote target must know how 5728to collect trace data. This functionality is implemented in the remote 5729stub; however, none of the stubs distributed with @value{GDBN} support 5730tracepoints as of this writing. 5731 5732This chapter describes the tracepoint commands and features. 5733 5734@menu 5735* Set Tracepoints:: 5736* Analyze Collected Data:: 5737* Tracepoint Variables:: 5738@end menu 5739 5740@node Set Tracepoints 5741@section Commands to Set Tracepoints 5742 5743Before running such a @dfn{trace experiment}, an arbitrary number of 5744tracepoints can be set. Like a breakpoint (@pxref{Set Breaks}), a 5745tracepoint has a number assigned to it by @value{GDBN}. Like with 5746breakpoints, tracepoint numbers are successive integers starting from 5747one. Many of the commands associated with tracepoints take the 5748tracepoint number as their argument, to identify which tracepoint to 5749work on. 5750 5751For each tracepoint, you can specify, in advance, some arbitrary set 5752of data that you want the target to collect in the trace buffer when 5753it hits that tracepoint. The collected data can include registers, 5754local variables, or global data. Later, you can use @value{GDBN} 5755commands to examine the values these data had at the time the 5756tracepoint was hit. 5757 5758This section describes commands to set tracepoints and associated 5759conditions and actions. 5760 5761@menu 5762* Create and Delete Tracepoints:: 5763* Enable and Disable Tracepoints:: 5764* Tracepoint Passcounts:: 5765* Tracepoint Actions:: 5766* Listing Tracepoints:: 5767* Starting and Stopping Trace Experiment:: 5768@end menu 5769 5770@node Create and Delete Tracepoints 5771@subsection Create and Delete Tracepoints 5772 5773@table @code 5774@cindex set tracepoint 5775@kindex trace 5776@item trace 5777The @code{trace} command is very similar to the @code{break} command. 5778Its argument can be a source line, a function name, or an address in 5779the target program. @xref{Set Breaks}. The @code{trace} command 5780defines a tracepoint, which is a point in the target program where the 5781debugger will briefly stop, collect some data, and then allow the 5782program to continue. Setting a tracepoint or changing its commands 5783doesn't take effect until the next @code{tstart} command; thus, you 5784cannot change the tracepoint attributes once a trace experiment is 5785running. 5786 5787Here are some examples of using the @code{trace} command: 5788 5789@smallexample 5790(@value{GDBP}) @b{trace foo.c:121} // a source file and line number 5791 5792(@value{GDBP}) @b{trace +2} // 2 lines forward 5793 5794(@value{GDBP}) @b{trace my_function} // first source line of function 5795 5796(@value{GDBP}) @b{trace *my_function} // EXACT start address of function 5797 5798(@value{GDBP}) @b{trace *0x2117c4} // an address 5799@end smallexample 5800 5801@noindent 5802You can abbreviate @code{trace} as @code{tr}. 5803 5804@vindex $tpnum 5805@cindex last tracepoint number 5806@cindex recent tracepoint number 5807@cindex tracepoint number 5808The convenience variable @code{$tpnum} records the tracepoint number 5809of the most recently set tracepoint. 5810 5811@kindex delete tracepoint 5812@cindex tracepoint deletion 5813@item delete tracepoint @r{[}@var{num}@r{]} 5814Permanently delete one or more tracepoints. With no argument, the 5815default is to delete all tracepoints. 5816 5817Examples: 5818 5819@smallexample 5820(@value{GDBP}) @b{delete trace 1 2 3} // remove three tracepoints 5821 5822(@value{GDBP}) @b{delete trace} // remove all tracepoints 5823@end smallexample 5824 5825@noindent 5826You can abbreviate this command as @code{del tr}. 5827@end table 5828 5829@node Enable and Disable Tracepoints 5830@subsection Enable and Disable Tracepoints 5831 5832@table @code 5833@kindex disable tracepoint 5834@item disable tracepoint @r{[}@var{num}@r{]} 5835Disable tracepoint @var{num}, or all tracepoints if no argument 5836@var{num} is given. A disabled tracepoint will have no effect during 5837the next trace experiment, but it is not forgotten. You can re-enable 5838a disabled tracepoint using the @code{enable tracepoint} command. 5839 5840@kindex enable tracepoint 5841@item enable tracepoint @r{[}@var{num}@r{]} 5842Enable tracepoint @var{num}, or all tracepoints. The enabled 5843tracepoints will become effective the next time a trace experiment is 5844run. 5845@end table 5846 5847@node Tracepoint Passcounts 5848@subsection Tracepoint Passcounts 5849 5850@table @code 5851@kindex passcount 5852@cindex tracepoint pass count 5853@item passcount @r{[}@var{n} @r{[}@var{num}@r{]]} 5854Set the @dfn{passcount} of a tracepoint. The passcount is a way to 5855automatically stop a trace experiment. If a tracepoint's passcount is 5856@var{n}, then the trace experiment will be automatically stopped on 5857the @var{n}'th time that tracepoint is hit. If the tracepoint number 5858@var{num} is not specified, the @code{passcount} command sets the 5859passcount of the most recently defined tracepoint. If no passcount is 5860given, the trace experiment will run until stopped explicitly by the 5861user. 5862 5863Examples: 5864 5865@smallexample 5866(@value{GDBP}) @b{passcount 5 2} // Stop on the 5th execution of 5867@exdent @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @code{// tracepoint 2} 5868 5869(@value{GDBP}) @b{passcount 12} // Stop on the 12th execution of the 5870@exdent @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @code{// most recently defined tracepoint.} 5871(@value{GDBP}) @b{trace foo} 5872(@value{GDBP}) @b{pass 3} 5873(@value{GDBP}) @b{trace bar} 5874(@value{GDBP}) @b{pass 2} 5875(@value{GDBP}) @b{trace baz} 5876(@value{GDBP}) @b{pass 1} // Stop tracing when foo has been 5877@exdent @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @code{// executed 3 times OR when bar has} 5878@exdent @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @code{// been executed 2 times} 5879@exdent @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @code{// OR when baz has been executed 1 time.} 5880@end smallexample 5881@end table 5882 5883@node Tracepoint Actions 5884@subsection Tracepoint Action Lists 5885 5886@table @code 5887@kindex actions 5888@cindex tracepoint actions 5889@item actions @r{[}@var{num}@r{]} 5890This command will prompt for a list of actions to be taken when the 5891tracepoint is hit. If the tracepoint number @var{num} is not 5892specified, this command sets the actions for the one that was most 5893recently defined (so that you can define a tracepoint and then say 5894@code{actions} without bothering about its number). You specify the 5895actions themselves on the following lines, one action at a time, and 5896terminate the actions list with a line containing just @code{end}. So 5897far, the only defined actions are @code{collect} and 5898@code{while-stepping}. 5899 5900@cindex remove actions from a tracepoint 5901To remove all actions from a tracepoint, type @samp{actions @var{num}} 5902and follow it immediately with @samp{end}. 5903 5904@smallexample 5905(@value{GDBP}) @b{collect @var{data}} // collect some data 5906 5907(@value{GDBP}) @b{while-stepping 5} // single-step 5 times, collect data 5908 5909(@value{GDBP}) @b{end} // signals the end of actions. 5910@end smallexample 5911 5912In the following example, the action list begins with @code{collect} 5913commands indicating the things to be collected when the tracepoint is 5914hit. Then, in order to single-step and collect additional data 5915following the tracepoint, a @code{while-stepping} command is used, 5916followed by the list of things to be collected while stepping. The 5917@code{while-stepping} command is terminated by its own separate 5918@code{end} command. Lastly, the action list is terminated by an 5919@code{end} command. 5920 5921@smallexample 5922(@value{GDBP}) @b{trace foo} 5923(@value{GDBP}) @b{actions} 5924Enter actions for tracepoint 1, one per line: 5925> collect bar,baz 5926> collect $regs 5927> while-stepping 12 5928 > collect $fp, $sp 5929 > end 5930end 5931@end smallexample 5932 5933@kindex collect @r{(tracepoints)} 5934@item collect @var{expr1}, @var{expr2}, @dots{} 5935Collect values of the given expressions when the tracepoint is hit. 5936This command accepts a comma-separated list of any valid expressions. 5937In addition to global, static, or local variables, the following 5938special arguments are supported: 5939 5940@table @code 5941@item $regs 5942collect all registers 5943 5944@item $args 5945collect all function arguments 5946 5947@item $locals 5948collect all local variables. 5949@end table 5950 5951You can give several consecutive @code{collect} commands, each one 5952with a single argument, or one @code{collect} command with several 5953arguments separated by commas: the effect is the same. 5954 5955The command @code{info scope} (@pxref{Symbols, info scope}) is 5956particularly useful for figuring out what data to collect. 5957 5958@kindex while-stepping @r{(tracepoints)} 5959@item while-stepping @var{n} 5960Perform @var{n} single-step traces after the tracepoint, collecting 5961new data at each step. The @code{while-stepping} command is 5962followed by the list of what to collect while stepping (followed by 5963its own @code{end} command): 5964 5965@smallexample 5966> while-stepping 12 5967 > collect $regs, myglobal 5968 > end 5969> 5970@end smallexample 5971 5972@noindent 5973You may abbreviate @code{while-stepping} as @code{ws} or 5974@code{stepping}. 5975@end table 5976 5977@node Listing Tracepoints 5978@subsection Listing Tracepoints 5979 5980@table @code 5981@kindex info tracepoints 5982@cindex information about tracepoints 5983@item info tracepoints @r{[}@var{num}@r{]} 5984Display information about the tracepoint @var{num}. If you don't specify 5985a tracepoint number, displays information about all the tracepoints 5986defined so far. For each tracepoint, the following information is 5987shown: 5988 5989@itemize @bullet 5990@item 5991its number 5992@item 5993whether it is enabled or disabled 5994@item 5995its address 5996@item 5997its passcount as given by the @code{passcount @var{n}} command 5998@item 5999its step count as given by the @code{while-stepping @var{n}} command 6000@item 6001where in the source files is the tracepoint set 6002@item 6003its action list as given by the @code{actions} command 6004@end itemize 6005 6006@smallexample 6007(@value{GDBP}) @b{info trace} 6008Num Enb Address PassC StepC What 60091 y 0x002117c4 0 0 <gdb_asm> 60102 y 0x0020dc64 0 0 in g_test at g_test.c:1375 60113 y 0x0020b1f4 0 0 in get_data at ../foo.c:41 6012(@value{GDBP}) 6013@end smallexample 6014 6015@noindent 6016This command can be abbreviated @code{info tp}. 6017@end table 6018 6019@node Starting and Stopping Trace Experiment 6020@subsection Starting and Stopping Trace Experiment 6021 6022@table @code 6023@kindex tstart 6024@cindex start a new trace experiment 6025@cindex collected data discarded 6026@item tstart 6027This command takes no arguments. It starts the trace experiment, and 6028begins collecting data. This has the side effect of discarding all 6029the data collected in the trace buffer during the previous trace 6030experiment. 6031 6032@kindex tstop 6033@cindex stop a running trace experiment 6034@item tstop 6035This command takes no arguments. It ends the trace experiment, and 6036stops collecting data. 6037 6038@strong{Note:} a trace experiment and data collection may stop 6039automatically if any tracepoint's passcount is reached 6040(@pxref{Tracepoint Passcounts}), or if the trace buffer becomes full. 6041 6042@kindex tstatus 6043@cindex status of trace data collection 6044@cindex trace experiment, status of 6045@item tstatus 6046This command displays the status of the current trace data 6047collection. 6048@end table 6049 6050Here is an example of the commands we described so far: 6051 6052@smallexample 6053(@value{GDBP}) @b{trace gdb_c_test} 6054(@value{GDBP}) @b{actions} 6055Enter actions for tracepoint #1, one per line. 6056> collect $regs,$locals,$args 6057> while-stepping 11 6058 > collect $regs 6059 > end 6060> end 6061(@value{GDBP}) @b{tstart} 6062 [time passes @dots{}] 6063(@value{GDBP}) @b{tstop} 6064@end smallexample 6065 6066 6067@node Analyze Collected Data 6068@section Using the collected data 6069 6070After the tracepoint experiment ends, you use @value{GDBN} commands 6071for examining the trace data. The basic idea is that each tracepoint 6072collects a trace @dfn{snapshot} every time it is hit and another 6073snapshot every time it single-steps. All these snapshots are 6074consecutively numbered from zero and go into a buffer, and you can 6075examine them later. The way you examine them is to @dfn{focus} on a 6076specific trace snapshot. When the remote stub is focused on a trace 6077snapshot, it will respond to all @value{GDBN} requests for memory and 6078registers by reading from the buffer which belongs to that snapshot, 6079rather than from @emph{real} memory or registers of the program being 6080debugged. This means that @strong{all} @value{GDBN} commands 6081(@code{print}, @code{info registers}, @code{backtrace}, etc.) will 6082behave as if we were currently debugging the program state as it was 6083when the tracepoint occurred. Any requests for data that are not in 6084the buffer will fail. 6085 6086@menu 6087* tfind:: How to select a trace snapshot 6088* tdump:: How to display all data for a snapshot 6089* save-tracepoints:: How to save tracepoints for a future run 6090@end menu 6091 6092@node tfind 6093@subsection @code{tfind @var{n}} 6094 6095@kindex tfind 6096@cindex select trace snapshot 6097@cindex find trace snapshot 6098The basic command for selecting a trace snapshot from the buffer is 6099@code{tfind @var{n}}, which finds trace snapshot number @var{n}, 6100counting from zero. If no argument @var{n} is given, the next 6101snapshot is selected. 6102 6103Here are the various forms of using the @code{tfind} command. 6104 6105@table @code 6106@item tfind start 6107Find the first snapshot in the buffer. This is a synonym for 6108@code{tfind 0} (since 0 is the number of the first snapshot). 6109 6110@item tfind none 6111Stop debugging trace snapshots, resume @emph{live} debugging. 6112 6113@item tfind end 6114Same as @samp{tfind none}. 6115 6116@item tfind 6117No argument means find the next trace snapshot. 6118 6119@item tfind - 6120Find the previous trace snapshot before the current one. This permits 6121retracing earlier steps. 6122 6123@item tfind tracepoint @var{num} 6124Find the next snapshot associated with tracepoint @var{num}. Search 6125proceeds forward from the last examined trace snapshot. If no 6126argument @var{num} is given, it means find the next snapshot collected 6127for the same tracepoint as the current snapshot. 6128 6129@item tfind pc @var{addr} 6130Find the next snapshot associated with the value @var{addr} of the 6131program counter. Search proceeds forward from the last examined trace 6132snapshot. If no argument @var{addr} is given, it means find the next 6133snapshot with the same value of PC as the current snapshot. 6134 6135@item tfind outside @var{addr1}, @var{addr2} 6136Find the next snapshot whose PC is outside the given range of 6137addresses. 6138 6139@item tfind range @var{addr1}, @var{addr2} 6140Find the next snapshot whose PC is between @var{addr1} and 6141@var{addr2}. @c FIXME: Is the range inclusive or exclusive? 6142 6143@item tfind line @r{[}@var{file}:@r{]}@var{n} 6144Find the next snapshot associated with the source line @var{n}. If 6145the optional argument @var{file} is given, refer to line @var{n} in 6146that source file. Search proceeds forward from the last examined 6147trace snapshot. If no argument @var{n} is given, it means find the 6148next line other than the one currently being examined; thus saying 6149@code{tfind line} repeatedly can appear to have the same effect as 6150stepping from line to line in a @emph{live} debugging session. 6151@end table 6152 6153The default arguments for the @code{tfind} commands are specifically 6154designed to make it easy to scan through the trace buffer. For 6155instance, @code{tfind} with no argument selects the next trace 6156snapshot, and @code{tfind -} with no argument selects the previous 6157trace snapshot. So, by giving one @code{tfind} command, and then 6158simply hitting @key{RET} repeatedly you can examine all the trace 6159snapshots in order. Or, by saying @code{tfind -} and then hitting 6160@key{RET} repeatedly you can examine the snapshots in reverse order. 6161The @code{tfind line} command with no argument selects the snapshot 6162for the next source line executed. The @code{tfind pc} command with 6163no argument selects the next snapshot with the same program counter 6164(PC) as the current frame. The @code{tfind tracepoint} command with 6165no argument selects the next trace snapshot collected by the same 6166tracepoint as the current one. 6167 6168In addition to letting you scan through the trace buffer manually, 6169these commands make it easy to construct @value{GDBN} scripts that 6170scan through the trace buffer and print out whatever collected data 6171you are interested in. Thus, if we want to examine the PC, FP, and SP 6172registers from each trace frame in the buffer, we can say this: 6173 6174@smallexample 6175(@value{GDBP}) @b{tfind start} 6176(@value{GDBP}) @b{while ($trace_frame != -1)} 6177> printf "Frame %d, PC = %08X, SP = %08X, FP = %08X\n", \ 6178 $trace_frame, $pc, $sp, $fp 6179> tfind 6180> end 6181 6182Frame 0, PC = 0020DC64, SP = 0030BF3C, FP = 0030BF44 6183Frame 1, PC = 0020DC6C, SP = 0030BF38, FP = 0030BF44 6184Frame 2, PC = 0020DC70, SP = 0030BF34, FP = 0030BF44 6185Frame 3, PC = 0020DC74, SP = 0030BF30, FP = 0030BF44 6186Frame 4, PC = 0020DC78, SP = 0030BF2C, FP = 0030BF44 6187Frame 5, PC = 0020DC7C, SP = 0030BF28, FP = 0030BF44 6188Frame 6, PC = 0020DC80, SP = 0030BF24, FP = 0030BF44 6189Frame 7, PC = 0020DC84, SP = 0030BF20, FP = 0030BF44 6190Frame 8, PC = 0020DC88, SP = 0030BF1C, FP = 0030BF44 6191Frame 9, PC = 0020DC8E, SP = 0030BF18, FP = 0030BF44 6192Frame 10, PC = 00203F6C, SP = 0030BE3C, FP = 0030BF14 6193@end smallexample 6194 6195Or, if we want to examine the variable @code{X} at each source line in 6196the buffer: 6197 6198@smallexample 6199(@value{GDBP}) @b{tfind start} 6200(@value{GDBP}) @b{while ($trace_frame != -1)} 6201> printf "Frame %d, X == %d\n", $trace_frame, X 6202> tfind line 6203> end 6204 6205Frame 0, X = 1 6206Frame 7, X = 2 6207Frame 13, X = 255 6208@end smallexample 6209 6210@node tdump 6211@subsection @code{tdump} 6212@kindex tdump 6213@cindex dump all data collected at tracepoint 6214@cindex tracepoint data, display 6215 6216This command takes no arguments. It prints all the data collected at 6217the current trace snapshot. 6218 6219@smallexample 6220(@value{GDBP}) @b{trace 444} 6221(@value{GDBP}) @b{actions} 6222Enter actions for tracepoint #2, one per line: 6223> collect $regs, $locals, $args, gdb_long_test 6224> end 6225 6226(@value{GDBP}) @b{tstart} 6227 6228(@value{GDBP}) @b{tfind line 444} 6229#0 gdb_test (p1=0x11, p2=0x22, p3=0x33, p4=0x44, p5=0x55, p6=0x66) 6230at gdb_test.c:444 6231444 printp( "%s: arguments = 0x%X 0x%X 0x%X 0x%X 0x%X 0x%X\n", ) 6232 6233(@value{GDBP}) @b{tdump} 6234Data collected at tracepoint 2, trace frame 1: 6235d0 0xc4aa0085 -995491707 6236d1 0x18 24 6237d2 0x80 128 6238d3 0x33 51 6239d4 0x71aea3d 119204413 6240d5 0x22 34 6241d6 0xe0 224 6242d7 0x380035 3670069 6243a0 0x19e24a 1696330 6244a1 0x3000668 50333288 6245a2 0x100 256 6246a3 0x322000 3284992 6247a4 0x3000698 50333336 6248a5 0x1ad3cc 1758156 6249fp 0x30bf3c 0x30bf3c 6250sp 0x30bf34 0x30bf34 6251ps 0x0 0 6252pc 0x20b2c8 0x20b2c8 6253fpcontrol 0x0 0 6254fpstatus 0x0 0 6255fpiaddr 0x0 0 6256p = 0x20e5b4 "gdb-test" 6257p1 = (void *) 0x11 6258p2 = (void *) 0x22 6259p3 = (void *) 0x33 6260p4 = (void *) 0x44 6261p5 = (void *) 0x55 6262p6 = (void *) 0x66 6263gdb_long_test = 17 '\021' 6264 6265(@value{GDBP}) 6266@end smallexample 6267 6268@node save-tracepoints 6269@subsection @code{save-tracepoints @var{filename}} 6270@kindex save-tracepoints 6271@cindex save tracepoints for future sessions 6272 6273This command saves all current tracepoint definitions together with 6274their actions and passcounts, into a file @file{@var{filename}} 6275suitable for use in a later debugging session. To read the saved 6276tracepoint definitions, use the @code{source} command (@pxref{Command 6277Files}). 6278 6279@node Tracepoint Variables 6280@section Convenience Variables for Tracepoints 6281@cindex tracepoint variables 6282@cindex convenience variables for tracepoints 6283 6284@table @code 6285@vindex $trace_frame 6286@item (int) $trace_frame 6287The current trace snapshot (a.k.a.@: @dfn{frame}) number, or -1 if no 6288snapshot is selected. 6289 6290@vindex $tracepoint 6291@item (int) $tracepoint 6292The tracepoint for the current trace snapshot. 6293 6294@vindex $trace_line 6295@item (int) $trace_line 6296The line number for the current trace snapshot. 6297 6298@vindex $trace_file 6299@item (char []) $trace_file 6300The source file for the current trace snapshot. 6301 6302@vindex $trace_func 6303@item (char []) $trace_func 6304The name of the function containing @code{$tracepoint}. 6305@end table 6306 6307Note: @code{$trace_file} is not suitable for use in @code{printf}, 6308use @code{output} instead. 6309 6310Here's a simple example of using these convenience variables for 6311stepping through all the trace snapshots and printing some of their 6312data. 6313 6314@smallexample 6315(@value{GDBP}) @b{tfind start} 6316 6317(@value{GDBP}) @b{while $trace_frame != -1} 6318> output $trace_file 6319> printf ", line %d (tracepoint #%d)\n", $trace_line, $tracepoint 6320> tfind 6321> end 6322@end smallexample 6323 6324@node Overlays 6325@chapter Debugging Programs That Use Overlays 6326@cindex overlays 6327 6328If your program is too large to fit completely in your target system's 6329memory, you can sometimes use @dfn{overlays} to work around this 6330problem. @value{GDBN} provides some support for debugging programs that 6331use overlays. 6332 6333@menu 6334* How Overlays Work:: A general explanation of overlays. 6335* Overlay Commands:: Managing overlays in @value{GDBN}. 6336* Automatic Overlay Debugging:: @value{GDBN} can find out which overlays are 6337 mapped by asking the inferior. 6338* Overlay Sample Program:: A sample program using overlays. 6339@end menu 6340 6341@node How Overlays Work 6342@section How Overlays Work 6343@cindex mapped overlays 6344@cindex unmapped overlays 6345@cindex load address, overlay's 6346@cindex mapped address 6347@cindex overlay area 6348 6349Suppose you have a computer whose instruction address space is only 64 6350kilobytes long, but which has much more memory which can be accessed by 6351other means: special instructions, segment registers, or memory 6352management hardware, for example. Suppose further that you want to 6353adapt a program which is larger than 64 kilobytes to run on this system. 6354 6355One solution is to identify modules of your program which are relatively 6356independent, and need not call each other directly; call these modules 6357@dfn{overlays}. Separate the overlays from the main program, and place 6358their machine code in the larger memory. Place your main program in 6359instruction memory, but leave at least enough space there to hold the 6360largest overlay as well. 6361 6362Now, to call a function located in an overlay, you must first copy that 6363overlay's machine code from the large memory into the space set aside 6364for it in the instruction memory, and then jump to its entry point 6365there. 6366 6367@c NB: In the below the mapped area's size is greater or equal to the 6368@c size of all overlays. This is intentional to remind the developer 6369@c that overlays don't necessarily need to be the same size. 6370 6371@example 6372@group 6373 Data Instruction Larger 6374Address Space Address Space Address Space 6375+-----------+ +-----------+ +-----------+ 6376| | | | | | 6377+-----------+ +-----------+ +-----------+<-- overlay 1 6378| program | | main | .----| overlay 1 | load address 6379| variables | | program | | +-----------+ 6380| and heap | | | | | | 6381+-----------+ | | | +-----------+<-- overlay 2 6382| | +-----------+ | | | load address 6383+-----------+ | | | .-| overlay 2 | 6384 | | | | | | 6385 mapped --->+-----------+ | | +-----------+ 6386 address | | | | | | 6387 | overlay | <-' | | | 6388 | area | <---' +-----------+<-- overlay 3 6389 | | <---. | | load address 6390 +-----------+ `--| overlay 3 | 6391 | | | | 6392 +-----------+ | | 6393 +-----------+ 6394 | | 6395 +-----------+ 6396 6397 @anchor{A code overlay}A code overlay 6398@end group 6399@end example 6400 6401The diagram (@pxref{A code overlay}) shows a system with separate data 6402and instruction address spaces. To map an overlay, the program copies 6403its code from the larger address space to the instruction address space. 6404Since the overlays shown here all use the same mapped address, only one 6405may be mapped at a time. For a system with a single address space for 6406data and instructions, the diagram would be similar, except that the 6407program variables and heap would share an address space with the main 6408program and the overlay area. 6409 6410An overlay loaded into instruction memory and ready for use is called a 6411@dfn{mapped} overlay; its @dfn{mapped address} is its address in the 6412instruction memory. An overlay not present (or only partially present) 6413in instruction memory is called @dfn{unmapped}; its @dfn{load address} 6414is its address in the larger memory. The mapped address is also called 6415the @dfn{virtual memory address}, or @dfn{VMA}; the load address is also 6416called the @dfn{load memory address}, or @dfn{LMA}. 6417 6418Unfortunately, overlays are not a completely transparent way to adapt a 6419program to limited instruction memory. They introduce a new set of 6420global constraints you must keep in mind as you design your program: 6421 6422@itemize @bullet 6423 6424@item 6425Before calling or returning to a function in an overlay, your program 6426must make sure that overlay is actually mapped. Otherwise, the call or 6427return will transfer control to the right address, but in the wrong 6428overlay, and your program will probably crash. 6429 6430@item 6431If the process of mapping an overlay is expensive on your system, you 6432will need to choose your overlays carefully to minimize their effect on 6433your program's performance. 6434 6435@item 6436The executable file you load onto your system must contain each 6437overlay's instructions, appearing at the overlay's load address, not its 6438mapped address. However, each overlay's instructions must be relocated 6439and its symbols defined as if the overlay were at its mapped address. 6440You can use GNU linker scripts to specify different load and relocation 6441addresses for pieces of your program; see @ref{Overlay Description,,, 6442ld.info, Using ld: the GNU linker}. 6443 6444@item 6445The procedure for loading executable files onto your system must be able 6446to load their contents into the larger address space as well as the 6447instruction and data spaces. 6448 6449@end itemize 6450 6451The overlay system described above is rather simple, and could be 6452improved in many ways: 6453 6454@itemize @bullet 6455 6456@item 6457If your system has suitable bank switch registers or memory management 6458hardware, you could use those facilities to make an overlay's load area 6459contents simply appear at their mapped address in instruction space. 6460This would probably be faster than copying the overlay to its mapped 6461area in the usual way. 6462 6463@item 6464If your overlays are small enough, you could set aside more than one 6465overlay area, and have more than one overlay mapped at a time. 6466 6467@item 6468You can use overlays to manage data, as well as instructions. In 6469general, data overlays are even less transparent to your design than 6470code overlays: whereas code overlays only require care when you call or 6471return to functions, data overlays require care every time you access 6472the data. Also, if you change the contents of a data overlay, you 6473must copy its contents back out to its load address before you can copy a 6474different data overlay into the same mapped area. 6475 6476@end itemize 6477 6478 6479@node Overlay Commands 6480@section Overlay Commands 6481 6482To use @value{GDBN}'s overlay support, each overlay in your program must 6483correspond to a separate section of the executable file. The section's 6484virtual memory address and load memory address must be the overlay's 6485mapped and load addresses. Identifying overlays with sections allows 6486@value{GDBN} to determine the appropriate address of a function or 6487variable, depending on whether the overlay is mapped or not. 6488 6489@value{GDBN}'s overlay commands all start with the word @code{overlay}; 6490you can abbreviate this as @code{ov} or @code{ovly}. The commands are: 6491 6492@table @code 6493@item overlay off 6494@kindex overlay off 6495Disable @value{GDBN}'s overlay support. When overlay support is 6496disabled, @value{GDBN} assumes that all functions and variables are 6497always present at their mapped addresses. By default, @value{GDBN}'s 6498overlay support is disabled. 6499 6500@item overlay manual 6501@kindex overlay manual 6502@cindex manual overlay debugging 6503Enable @dfn{manual} overlay debugging. In this mode, @value{GDBN} 6504relies on you to tell it which overlays are mapped, and which are not, 6505using the @code{overlay map-overlay} and @code{overlay unmap-overlay} 6506commands described below. 6507 6508@item overlay map-overlay @var{overlay} 6509@itemx overlay map @var{overlay} 6510@kindex overlay map-overlay 6511@cindex map an overlay 6512Tell @value{GDBN} that @var{overlay} is now mapped; @var{overlay} must 6513be the name of the object file section containing the overlay. When an 6514overlay is mapped, @value{GDBN} assumes it can find the overlay's 6515functions and variables at their mapped addresses. @value{GDBN} assumes 6516that any other overlays whose mapped ranges overlap that of 6517@var{overlay} are now unmapped. 6518 6519@item overlay unmap-overlay @var{overlay} 6520@itemx overlay unmap @var{overlay} 6521@kindex overlay unmap-overlay 6522@cindex unmap an overlay 6523Tell @value{GDBN} that @var{overlay} is no longer mapped; @var{overlay} 6524must be the name of the object file section containing the overlay. 6525When an overlay is unmapped, @value{GDBN} assumes it can find the 6526overlay's functions and variables at their load addresses. 6527 6528@item overlay auto 6529@kindex overlay auto 6530Enable @dfn{automatic} overlay debugging. In this mode, @value{GDBN} 6531consults a data structure the overlay manager maintains in the inferior 6532to see which overlays are mapped. For details, see @ref{Automatic 6533Overlay Debugging}. 6534 6535@item overlay load-target 6536@itemx overlay load 6537@kindex overlay load-target 6538@cindex reloading the overlay table 6539Re-read the overlay table from the inferior. Normally, @value{GDBN} 6540re-reads the table @value{GDBN} automatically each time the inferior 6541stops, so this command should only be necessary if you have changed the 6542overlay mapping yourself using @value{GDBN}. This command is only 6543useful when using automatic overlay debugging. 6544 6545@item overlay list-overlays 6546@itemx overlay list 6547@cindex listing mapped overlays 6548Display a list of the overlays currently mapped, along with their mapped 6549addresses, load addresses, and sizes. 6550 6551@end table 6552 6553Normally, when @value{GDBN} prints a code address, it includes the name 6554of the function the address falls in: 6555 6556@example 6557(gdb) print main 6558$3 = @{int ()@} 0x11a0 <main> 6559@end example 6560@noindent 6561When overlay debugging is enabled, @value{GDBN} recognizes code in 6562unmapped overlays, and prints the names of unmapped functions with 6563asterisks around them. For example, if @code{foo} is a function in an 6564unmapped overlay, @value{GDBN} prints it this way: 6565 6566@example 6567(gdb) overlay list 6568No sections are mapped. 6569(gdb) print foo 6570$5 = @{int (int)@} 0x100000 <*foo*> 6571@end example 6572@noindent 6573When @code{foo}'s overlay is mapped, @value{GDBN} prints the function's 6574name normally: 6575 6576@example 6577(gdb) overlay list 6578Section .ov.foo.text, loaded at 0x100000 - 0x100034, 6579 mapped at 0x1016 - 0x104a 6580(gdb) print foo 6581$6 = @{int (int)@} 0x1016 <foo> 6582@end example 6583 6584When overlay debugging is enabled, @value{GDBN} can find the correct 6585address for functions and variables in an overlay, whether or not the 6586overlay is mapped. This allows most @value{GDBN} commands, like 6587@code{break} and @code{disassemble}, to work normally, even on unmapped 6588code. However, @value{GDBN}'s breakpoint support has some limitations: 6589 6590@itemize @bullet 6591@item 6592@cindex breakpoints in overlays 6593@cindex overlays, setting breakpoints in 6594You can set breakpoints in functions in unmapped overlays, as long as 6595@value{GDBN} can write to the overlay at its load address. 6596@item 6597@value{GDBN} can not set hardware or simulator-based breakpoints in 6598unmapped overlays. However, if you set a breakpoint at the end of your 6599overlay manager (and tell @value{GDBN} which overlays are now mapped, if 6600you are using manual overlay management), @value{GDBN} will re-set its 6601breakpoints properly. 6602@end itemize 6603 6604 6605@node Automatic Overlay Debugging 6606@section Automatic Overlay Debugging 6607@cindex automatic overlay debugging 6608 6609@value{GDBN} can automatically track which overlays are mapped and which 6610are not, given some simple co-operation from the overlay manager in the 6611inferior. If you enable automatic overlay debugging with the 6612@code{overlay auto} command (@pxref{Overlay Commands}), @value{GDBN} 6613looks in the inferior's memory for certain variables describing the 6614current state of the overlays. 6615 6616Here are the variables your overlay manager must define to support 6617@value{GDBN}'s automatic overlay debugging: 6618 6619@table @asis 6620 6621@item @code{_ovly_table}: 6622This variable must be an array of the following structures: 6623 6624@example 6625struct 6626@{ 6627 /* The overlay's mapped address. */ 6628 unsigned long vma; 6629 6630 /* The size of the overlay, in bytes. */ 6631 unsigned long size; 6632 6633 /* The overlay's load address. */ 6634 unsigned long lma; 6635 6636 /* Non-zero if the overlay is currently mapped; 6637 zero otherwise. */ 6638 unsigned long mapped; 6639@} 6640@end example 6641 6642@item @code{_novlys}: 6643This variable must be a four-byte signed integer, holding the total 6644number of elements in @code{_ovly_table}. 6645 6646@end table 6647 6648To decide whether a particular overlay is mapped or not, @value{GDBN} 6649looks for an entry in @w{@code{_ovly_table}} whose @code{vma} and 6650@code{lma} members equal the VMA and LMA of the overlay's section in the 6651executable file. When @value{GDBN} finds a matching entry, it consults 6652the entry's @code{mapped} member to determine whether the overlay is 6653currently mapped. 6654 6655In addition, your overlay manager may define a function called 6656@code{_ovly_debug_event}. If this function is defined, @value{GDBN} 6657will silently set a breakpoint there. If the overlay manager then 6658calls this function whenever it has changed the overlay table, this 6659will enable @value{GDBN} to accurately keep track of which overlays 6660are in program memory, and update any breakpoints that may be set 6661in overlays. This will allow breakpoints to work even if the 6662overlays are kept in ROM or other non-writable memory while they 6663are not being executed. 6664 6665@node Overlay Sample Program 6666@section Overlay Sample Program 6667@cindex overlay example program 6668 6669When linking a program which uses overlays, you must place the overlays 6670at their load addresses, while relocating them to run at their mapped 6671addresses. To do this, you must write a linker script (@pxref{Overlay 6672Description,,, ld.info, Using ld: the GNU linker}). Unfortunately, 6673since linker scripts are specific to a particular host system, target 6674architecture, and target memory layout, this manual cannot provide 6675portable sample code demonstrating @value{GDBN}'s overlay support. 6676 6677However, the @value{GDBN} source distribution does contain an overlaid 6678program, with linker scripts for a few systems, as part of its test 6679suite. The program consists of the following files from 6680@file{gdb/testsuite/gdb.base}: 6681 6682@table @file 6683@item overlays.c 6684The main program file. 6685@item ovlymgr.c 6686A simple overlay manager, used by @file{overlays.c}. 6687@item foo.c 6688@itemx bar.c 6689@itemx baz.c 6690@itemx grbx.c 6691Overlay modules, loaded and used by @file{overlays.c}. 6692@item d10v.ld 6693@itemx m32r.ld 6694Linker scripts for linking the test program on the @code{d10v-elf} 6695and @code{m32r-elf} targets. 6696@end table 6697 6698You can build the test program using the @code{d10v-elf} GCC 6699cross-compiler like this: 6700 6701@example 6702$ d10v-elf-gcc -g -c overlays.c 6703$ d10v-elf-gcc -g -c ovlymgr.c 6704$ d10v-elf-gcc -g -c foo.c 6705$ d10v-elf-gcc -g -c bar.c 6706$ d10v-elf-gcc -g -c baz.c 6707$ d10v-elf-gcc -g -c grbx.c 6708$ d10v-elf-gcc -g overlays.o ovlymgr.o foo.o bar.o \ 6709 baz.o grbx.o -Wl,-Td10v.ld -o overlays 6710@end example 6711 6712The build process is identical for any other architecture, except that 6713you must substitute the appropriate compiler and linker script for the 6714target system for @code{d10v-elf-gcc} and @code{d10v.ld}. 6715 6716 6717@node Languages |
| 5802@chapter Using @value{GDBN} with Different Languages 5803@cindex languages 5804 | 6718@chapter Using @value{GDBN} with Different Languages 6719@cindex languages 6720 |
| 5805@ifset MOD2 | |
| 5806Although programming languages generally have common aspects, they are 5807rarely expressed in the same manner. For instance, in ANSI C, 5808dereferencing a pointer @code{p} is accomplished by @code{*p}, but in 5809Modula-2, it is accomplished by @code{p^}. Values can also be | 6721Although programming languages generally have common aspects, they are 6722rarely expressed in the same manner. For instance, in ANSI C, 6723dereferencing a pointer @code{p} is accomplished by @code{*p}, but in 6724Modula-2, it is accomplished by @code{p^}. Values can also be |
| 5810represented (and displayed) differently. Hex numbers in C appear as | 6725represented (and displayed) differently. Hex numbers in C appear as |
| 5811@samp{0x1ae}, while in Modula-2 they appear as @samp{1AEH}. | 6726@samp{0x1ae}, while in Modula-2 they appear as @samp{1AEH}. |
| 5812@end ifset | |
| 5813 5814@cindex working language 5815Language-specific information is built into @value{GDBN} for some languages, 5816allowing you to express operations like the above in your program's 5817native language, and allowing @value{GDBN} to output values in a manner 5818consistent with the syntax of your program's native language. The 5819language you use to build expressions is called the @dfn{working 5820language}. 5821 5822@menu 5823* Setting:: Switching between source languages 5824* Show:: Displaying the language | 6727 6728@cindex working language 6729Language-specific information is built into @value{GDBN} for some languages, 6730allowing you to express operations like the above in your program's 6731native language, and allowing @value{GDBN} to output values in a manner 6732consistent with the syntax of your program's native language. The 6733language you use to build expressions is called the @dfn{working 6734language}. 6735 6736@menu 6737* Setting:: Switching between source languages 6738* Show:: Displaying the language |
| 5825@ifset MOD2 | |
| 5826* Checks:: Type and range checks | 6739* Checks:: Type and range checks |
| 5827@end ifset 5828 | |
| 5829* Support:: Supported languages 5830@end menu 5831 | 6740* Support:: Supported languages 6741@end menu 6742 |
| 5832@node Setting, Show, Languages, Languages | 6743@node Setting |
| 5833@section Switching between source languages 5834 5835There are two ways to control the working language---either have @value{GDBN} 5836set it automatically, or select it manually yourself. You can use the 5837@code{set language} command for either purpose. On startup, @value{GDBN} 5838defaults to setting the language automatically. The working language is 5839used to determine how expressions you type are interpreted, how values 5840are printed, etc. 5841 5842In addition to the working language, every source file that 5843@value{GDBN} knows about has its own working language. For some object 5844file formats, the compiler might indicate which language a particular 5845source file is in. However, most of the time @value{GDBN} infers the 5846language from the name of the file. The language of a source file | 6744@section Switching between source languages 6745 6746There are two ways to control the working language---either have @value{GDBN} 6747set it automatically, or select it manually yourself. You can use the 6748@code{set language} command for either purpose. On startup, @value{GDBN} 6749defaults to setting the language automatically. The working language is 6750used to determine how expressions you type are interpreted, how values 6751are printed, etc. 6752 6753In addition to the working language, every source file that 6754@value{GDBN} knows about has its own working language. For some object 6755file formats, the compiler might indicate which language a particular 6756source file is in. However, most of the time @value{GDBN} infers the 6757language from the name of the file. The language of a source file |
| 5847controls whether C++ names are demangled---this way @code{backtrace} can | 6758controls whether C@t{++} names are demangled---this way @code{backtrace} can |
| 5848show each frame appropriately for its own language. There is no way to | 6759show each frame appropriately for its own language. There is no way to |
| 5849set the language of a source file from within @value{GDBN}. | 6760set the language of a source file from within @value{GDBN}, but you can 6761set the language associated with a filename extension. @xref{Show, , 6762Displaying the language}. |
| 5850 5851This is most commonly a problem when you use a program, such | 6763 6764This is most commonly a problem when you use a program, such |
| 5852as @code{cfront} or @code{f2c}, that generates C but is written in | 6765as @code{cfront} or @code{f2c}, that generates C but is written in |
| 5853another language. In that case, make the 5854program use @code{#line} directives in its C output; that way 5855@value{GDBN} will know the correct language of the source code of the original 5856program, and will display that source code, not the generated C code. 5857 5858@menu 5859* Filenames:: Filename extensions and languages. 5860* Manually:: Setting the working language manually 5861* Automatically:: Having @value{GDBN} infer the source language 5862@end menu 5863 | 6766another language. In that case, make the 6767program use @code{#line} directives in its C output; that way 6768@value{GDBN} will know the correct language of the source code of the original 6769program, and will display that source code, not the generated C code. 6770 6771@menu 6772* Filenames:: Filename extensions and languages. 6773* Manually:: Setting the working language manually 6774* Automatically:: Having @value{GDBN} infer the source language 6775@end menu 6776 |
| 5864@node Filenames, Manually, Setting, Setting | 6777@node Filenames |
| 5865@subsection List of filename extensions and languages 5866 5867If a source file name ends in one of the following extensions, then 5868@value{GDBN} infers that its language is the one indicated. 5869 5870@table @file 5871 5872@item .c 5873C source file 5874 5875@item .C 5876@itemx .cc 5877@itemx .cp 5878@itemx .cpp 5879@itemx .cxx 5880@itemx .c++ | 6778@subsection List of filename extensions and languages 6779 6780If a source file name ends in one of the following extensions, then 6781@value{GDBN} infers that its language is the one indicated. 6782 6783@table @file 6784 6785@item .c 6786C source file 6787 6788@item .C 6789@itemx .cc 6790@itemx .cp 6791@itemx .cpp 6792@itemx .cxx 6793@itemx .c++ |
| 5881C++ source file | 6794C@t{++} source file |
| 5882 5883@item .f 5884@itemx .F 5885Fortran source file 5886 | 6795 6796@item .f 6797@itemx .F 6798Fortran source file 6799 |
| 5887@ifclear HPPA | |
| 5888@item .ch 5889@itemx .c186 5890@itemx .c286 | 6800@item .ch 6801@itemx .c186 6802@itemx .c286 |
| 5891CHILL source file. 5892@end ifclear | 6803CHILL source file |
| 5893 | 6804 |
| 5894@ifset MOD2 | |
| 5895@item .mod 5896Modula-2 source file | 6805@item .mod 6806Modula-2 source file |
| 5897@end ifset | |
| 5898 5899@item .s 5900@itemx .S 5901Assembler source file. This actually behaves almost like C, but 5902@value{GDBN} does not skip over function prologues when stepping. 5903@end table 5904 5905In addition, you may set the language associated with a filename 5906extension. @xref{Show, , Displaying the language}. 5907 | 6807 6808@item .s 6809@itemx .S 6810Assembler source file. This actually behaves almost like C, but 6811@value{GDBN} does not skip over function prologues when stepping. 6812@end table 6813 6814In addition, you may set the language associated with a filename 6815extension. @xref{Show, , Displaying the language}. 6816 |
| 5908@node Manually, Automatically, Filenames, Setting | 6817@node Manually |
| 5909@subsection Setting the working language 5910 5911If you allow @value{GDBN} to set the language automatically, 5912expressions are interpreted the same way in your debugging session and 5913your program. 5914 5915@kindex set language 5916If you wish, you may set the language manually. To do this, issue the 5917command @samp{set language @var{lang}}, where @var{lang} is the name of | 6818@subsection Setting the working language 6819 6820If you allow @value{GDBN} to set the language automatically, 6821expressions are interpreted the same way in your debugging session and 6822your program. 6823 6824@kindex set language 6825If you wish, you may set the language manually. To do this, issue the 6826command @samp{set language @var{lang}}, where @var{lang} is the name of |
| 5918a language, such as 5919@ifclear MOD2 5920@code{c}. 5921@end ifclear 5922@ifset MOD2 | 6827a language, such as |
| 5923@code{c} or @code{modula-2}. | 6828@code{c} or @code{modula-2}. |
| 5924@end ifset | |
| 5925For a list of the supported languages, type @samp{set language}. 5926 | 6829For a list of the supported languages, type @samp{set language}. 6830 |
| 5927@ifclear MOD2 5928Setting the language manually prevents @value{GDBN} from updating the 5929working language automatically. For example, if you used the @code{c} 5930setting to debug a C++ program, names might not be demangled properly, 5931overload resolution would not work, user-defined operators might not be 5932interpreted correctly, and so on. 5933@end ifclear 5934@ifset MOD2 | |
| 5935Setting the language manually prevents @value{GDBN} from updating the working 5936language automatically. This can lead to confusion if you try 5937to debug a program when the working language is not the same as the 5938source language, when an expression is acceptable to both 5939languages---but means different things. For instance, if the current 5940source file were written in C, and @value{GDBN} was parsing Modula-2, a 5941command such as: 5942 5943@example 5944print a = b + c 5945@end example 5946 5947@noindent 5948might not have the effect you intended. In C, this means to add 5949@code{b} and @code{c} and place the result in @code{a}. The result 5950printed would be the value of @code{a}. In Modula-2, this means to compare 5951@code{a} to the result of @code{b+c}, yielding a @code{BOOLEAN} value. | 6831Setting the language manually prevents @value{GDBN} from updating the working 6832language automatically. This can lead to confusion if you try 6833to debug a program when the working language is not the same as the 6834source language, when an expression is acceptable to both 6835languages---but means different things. For instance, if the current 6836source file were written in C, and @value{GDBN} was parsing Modula-2, a 6837command such as: 6838 6839@example 6840print a = b + c 6841@end example 6842 6843@noindent 6844might not have the effect you intended. In C, this means to add 6845@code{b} and @code{c} and place the result in @code{a}. The result 6846printed would be the value of @code{a}. In Modula-2, this means to compare 6847@code{a} to the result of @code{b+c}, yielding a @code{BOOLEAN} value. |
| 5952@end ifset | |
| 5953 | 6848 |
| 5954@node Automatically, , Manually, Setting | 6849@node Automatically |
| 5955@subsection Having @value{GDBN} infer the source language 5956 5957To have @value{GDBN} set the working language automatically, use 5958@samp{set language local} or @samp{set language auto}. @value{GDBN} 5959then infers the working language. That is, when your program stops in a 5960frame (usually by encountering a breakpoint), @value{GDBN} sets the 5961working language to the language recorded for the function in that 5962frame. If the language for a frame is unknown (that is, if the function 5963or block corresponding to the frame was defined in a source file that 5964does not have a recognized extension), the current working language is 5965not changed, and @value{GDBN} issues a warning. 5966 5967This may not seem necessary for most programs, which are written 5968entirely in one source language. However, program modules and libraries 5969written in one source language can be used by a main program written in 5970a different source language. Using @samp{set language auto} in this 5971case frees you from having to set the working language manually. 5972 | 6850@subsection Having @value{GDBN} infer the source language 6851 6852To have @value{GDBN} set the working language automatically, use 6853@samp{set language local} or @samp{set language auto}. @value{GDBN} 6854then infers the working language. That is, when your program stops in a 6855frame (usually by encountering a breakpoint), @value{GDBN} sets the 6856working language to the language recorded for the function in that 6857frame. If the language for a frame is unknown (that is, if the function 6858or block corresponding to the frame was defined in a source file that 6859does not have a recognized extension), the current working language is 6860not changed, and @value{GDBN} issues a warning. 6861 6862This may not seem necessary for most programs, which are written 6863entirely in one source language. However, program modules and libraries 6864written in one source language can be used by a main program written in 6865a different source language. Using @samp{set language auto} in this 6866case frees you from having to set the working language manually. 6867 |
| 5973@ifset MOD2 5974@node Show, Checks, Setting, Languages | 6868@node Show |
| 5975@section Displaying the language | 6869@section Displaying the language |
| 5976@end ifset 5977@ifclear MOD2 5978@node Show, Support, Setting, Languages 5979@section Displaying the language 5980@end ifclear | |
| 5981 5982The following commands help you find out which language is the 5983working language, and also what language source files were written in. 5984 5985@kindex show language | 6870 6871The following commands help you find out which language is the 6872working language, and also what language source files were written in. 6873 6874@kindex show language |
| 5986@kindex info frame 5987@kindex info source | 6875@kindex info frame@r{, show the source language} 6876@kindex info source@r{, show the source language} |
| 5988@table @code 5989@item show language 5990Display the current working language. This is the 5991language you can use with commands such as @code{print} to 5992build and compute expressions that may involve variables in your program. 5993 5994@item info frame | 6877@table @code 6878@item show language 6879Display the current working language. This is the 6880language you can use with commands such as @code{print} to 6881build and compute expressions that may involve variables in your program. 6882 6883@item info frame |
| 5995Display the source language for this frame. This language becomes the | 6884Display the source language for this frame. This language becomes the |
| 5996working language if you use an identifier from this frame. | 6885working language if you use an identifier from this frame. |
| 5997@xref{Frame Info, ,Information about a frame}, to identify the other | 6886@xref{Frame Info, ,Information about a frame}, to identify the other |
| 5998information listed here. 5999 6000@item info source 6001Display the source language of this source file. | 6887information listed here. 6888 6889@item info source 6890Display the source language of this source file. |
| 6002@xref{Symbols, ,Examining the Symbol Table}, to identify the other | 6891@xref{Symbols, ,Examining the Symbol Table}, to identify the other |
| 6003information listed here. 6004@end table 6005 6006In unusual circumstances, you may have source files with extensions 6007not in the standard list. You can then set the extension associated 6008with a language explicitly: 6009 6010@kindex set extension-language 6011@kindex info extensions 6012@table @code 6013@item set extension-language @var{.ext} @var{language} 6014Set source files with extension @var{.ext} to be assumed to be in 6015the source language @var{language}. 6016 6017@item info extensions 6018List all the filename extensions and the associated languages. 6019@end table 6020 | 6892information listed here. 6893@end table 6894 6895In unusual circumstances, you may have source files with extensions 6896not in the standard list. You can then set the extension associated 6897with a language explicitly: 6898 6899@kindex set extension-language 6900@kindex info extensions 6901@table @code 6902@item set extension-language @var{.ext} @var{language} 6903Set source files with extension @var{.ext} to be assumed to be in 6904the source language @var{language}. 6905 6906@item info extensions 6907List all the filename extensions and the associated languages. 6908@end table 6909 |
| 6021@ifset MOD2 6022@node Checks, Support, Show, Languages | 6910@node Checks |
| 6023@section Type and range checking 6024 6025@quotation 6026@emph{Warning:} In this release, the @value{GDBN} commands for type and range 6027checking are included, but they do not yet have any effect. This 6028section documents the intended facilities. 6029@end quotation 6030@c FIXME remove warning when type/range code added --- 16 unchanged lines hidden (view full) --- 6047 6048@menu 6049* Type Checking:: An overview of type checking 6050* Range Checking:: An overview of range checking 6051@end menu 6052 6053@cindex type checking 6054@cindex checks, type | 6911@section Type and range checking 6912 6913@quotation 6914@emph{Warning:} In this release, the @value{GDBN} commands for type and range 6915checking are included, but they do not yet have any effect. This 6916section documents the intended facilities. 6917@end quotation 6918@c FIXME remove warning when type/range code added --- 16 unchanged lines hidden (view full) --- 6935 6936@menu 6937* Type Checking:: An overview of type checking 6938* Range Checking:: An overview of range checking 6939@end menu 6940 6941@cindex type checking 6942@cindex checks, type |
| 6055@node Type Checking, Range Checking, Checks, Checks | 6943@node Type Checking |
| 6056@subsection An overview of type checking 6057 6058Some languages, such as Modula-2, are strongly typed, meaning that the 6059arguments to operators and functions have to be of the correct type, 6060otherwise an error occurs. These checks prevent type mismatch 6061errors from ever causing any run-time problems. For example, 6062 6063@smallexample 60641 + 2 @result{} 3 6065@exdent but 6066@error{} 1 + 2.3 6067@end smallexample 6068 6069The second example fails because the @code{CARDINAL} 1 is not 6070type-compatible with the @code{REAL} 2.3. 6071 | 6944@subsection An overview of type checking 6945 6946Some languages, such as Modula-2, are strongly typed, meaning that the 6947arguments to operators and functions have to be of the correct type, 6948otherwise an error occurs. These checks prevent type mismatch 6949errors from ever causing any run-time problems. For example, 6950 6951@smallexample 69521 + 2 @result{} 3 6953@exdent but 6954@error{} 1 + 2.3 6955@end smallexample 6956 6957The second example fails because the @code{CARDINAL} 1 is not 6958type-compatible with the @code{REAL} 2.3. 6959 |
| 6072For the expressions you use in @value{GDBN} commands, you can tell the 6073@value{GDBN} type checker to skip checking; 6074to treat any mismatches as errors and abandon the expression; 6075or to only issue warnings when type mismatches occur, | 6960For the expressions you use in @value{GDBN} commands, you can tell the 6961@value{GDBN} type checker to skip checking; 6962to treat any mismatches as errors and abandon the expression; 6963or to only issue warnings when type mismatches occur, |
| 6076but evaluate the expression anyway. When you choose the last of 6077these, @value{GDBN} evaluates expressions like the second example above, but 6078also issues a warning. 6079 | 6964but evaluate the expression anyway. When you choose the last of 6965these, @value{GDBN} evaluates expressions like the second example above, but 6966also issues a warning. 6967 |
| 6080Even if you turn type checking off, there may be other reasons 6081related to type that prevent @value{GDBN} from evaluating an expression. 6082For instance, @value{GDBN} does not know how to add an @code{int} and 6083a @code{struct foo}. These particular type errors have nothing to do 6084with the language in use, and usually arise from expressions, such as | 6968Even if you turn type checking off, there may be other reasons 6969related to type that prevent @value{GDBN} from evaluating an expression. 6970For instance, @value{GDBN} does not know how to add an @code{int} and 6971a @code{struct foo}. These particular type errors have nothing to do 6972with the language in use, and usually arise from expressions, such as |
| 6085the one described above, which make little sense to evaluate anyway. 6086 6087Each language defines to what degree it is strict about type. For 6088instance, both Modula-2 and C require the arguments to arithmetical 6089operators to be numbers. In C, enumerated types and pointers can be 6090represented as numbers, so that they are valid arguments to mathematical 6091operators. @xref{Support, ,Supported languages}, for further 6092details on specific languages. 6093 6094@value{GDBN} provides some additional commands for controlling the type checker: 6095 | 6973the one described above, which make little sense to evaluate anyway. 6974 6975Each language defines to what degree it is strict about type. For 6976instance, both Modula-2 and C require the arguments to arithmetical 6977operators to be numbers. In C, enumerated types and pointers can be 6978represented as numbers, so that they are valid arguments to mathematical 6979operators. @xref{Support, ,Supported languages}, for further 6980details on specific languages. 6981 6982@value{GDBN} provides some additional commands for controlling the type checker: 6983 |
| 6096@kindex set check | 6984@kindex set check@r{, type} |
| 6097@kindex set check type 6098@kindex show check type 6099@table @code 6100@item set check type auto 6101Set type checking on or off based on the current working language. 6102@xref{Support, ,Supported languages}, for the default settings for 6103each language. 6104 6105@item set check type on 6106@itemx set check type off 6107Set type checking on or off, overriding the default setting for the 6108current working language. Issue a warning if the setting does not 6109match the language default. If any type mismatches occur in | 6985@kindex set check type 6986@kindex show check type 6987@table @code 6988@item set check type auto 6989Set type checking on or off based on the current working language. 6990@xref{Support, ,Supported languages}, for the default settings for 6991each language. 6992 6993@item set check type on 6994@itemx set check type off 6995Set type checking on or off, overriding the default setting for the 6996current working language. Issue a warning if the setting does not 6997match the language default. If any type mismatches occur in |
| 6110evaluating an expression while typechecking is on, @value{GDBN} prints a | 6998evaluating an expression while type checking is on, @value{GDBN} prints a |
| 6111message and aborts evaluation of the expression. 6112 6113@item set check type warn 6114Cause the type checker to issue warnings, but to always attempt to 6115evaluate the expression. Evaluating the expression may still 6116be impossible for other reasons. For example, @value{GDBN} cannot add 6117numbers and structures. 6118 6119@item show type | 6999message and aborts evaluation of the expression. 7000 7001@item set check type warn 7002Cause the type checker to issue warnings, but to always attempt to 7003evaluate the expression. Evaluating the expression may still 7004be impossible for other reasons. For example, @value{GDBN} cannot add 7005numbers and structures. 7006 7007@item show type |
| 6120Show the current setting of the type checker, and whether or not @value{GDBN} | 7008Show the current setting of the type checker, and whether or not @value{GDBN} |
| 6121is setting it automatically. 6122@end table 6123 6124@cindex range checking 6125@cindex checks, range | 7009is setting it automatically. 7010@end table 7011 7012@cindex range checking 7013@cindex checks, range |
| 6126@node Range Checking, , Type Checking, Checks | 7014@node Range Checking |
| 6127@subsection An overview of range checking 6128 6129In some languages (such as Modula-2), it is an error to exceed the 6130bounds of a type; this is enforced with run-time checks. Such range 6131checking is meant to ensure program correctness by making sure 6132computations do not overflow, or indices on an array element access do 6133not exceed the bounds of the array. 6134 --- 14 unchanged lines hidden (view full) --- 6149@end example 6150 6151This, too, is specific to individual languages, and in some cases 6152specific to individual compilers or machines. @xref{Support, , 6153Supported languages}, for further details on specific languages. 6154 6155@value{GDBN} provides some additional commands for controlling the range checker: 6156 | 7015@subsection An overview of range checking 7016 7017In some languages (such as Modula-2), it is an error to exceed the 7018bounds of a type; this is enforced with run-time checks. Such range 7019checking is meant to ensure program correctness by making sure 7020computations do not overflow, or indices on an array element access do 7021not exceed the bounds of the array. 7022 --- 14 unchanged lines hidden (view full) --- 7037@end example 7038 7039This, too, is specific to individual languages, and in some cases 7040specific to individual compilers or machines. @xref{Support, , 7041Supported languages}, for further details on specific languages. 7042 7043@value{GDBN} provides some additional commands for controlling the range checker: 7044 |
| 6157@kindex set check | 7045@kindex set check@r{, range} |
| 6158@kindex set check range 6159@kindex show check range 6160@table @code 6161@item set check range auto 6162Set range checking on or off based on the current working language. 6163@xref{Support, ,Supported languages}, for the default settings for 6164each language. 6165 6166@item set check range on 6167@itemx set check range off 6168Set range checking on or off, overriding the default setting for the 6169current working language. A warning is issued if the setting does not | 7046@kindex set check range 7047@kindex show check range 7048@table @code 7049@item set check range auto 7050Set range checking on or off based on the current working language. 7051@xref{Support, ,Supported languages}, for the default settings for 7052each language. 7053 7054@item set check range on 7055@itemx set check range off 7056Set range checking on or off, overriding the default setting for the 7057current working language. A warning is issued if the setting does not |
| 6170match the language default. If a range error occurs, then a message 6171is printed and evaluation of the expression is aborted. | 7058match the language default. If a range error occurs and range checking is on, 7059then a message is printed and evaluation of the expression is aborted. |
| 6172 6173@item set check range warn 6174Output messages when the @value{GDBN} range checker detects a range error, 6175but attempt to evaluate the expression anyway. Evaluating the 6176expression may still be impossible for other reasons, such as accessing 6177memory that the process does not own (a typical example from many Unix 6178systems). 6179 6180@item show range 6181Show the current setting of the range checker, and whether or not it is 6182being set automatically by @value{GDBN}. 6183@end table | 7060 7061@item set check range warn 7062Output messages when the @value{GDBN} range checker detects a range error, 7063but attempt to evaluate the expression anyway. Evaluating the 7064expression may still be impossible for other reasons, such as accessing 7065memory that the process does not own (a typical example from many Unix 7066systems). 7067 7068@item show range 7069Show the current setting of the range checker, and whether or not it is 7070being set automatically by @value{GDBN}. 7071@end table |
| 6184@end ifset | |
| 6185 | 7072 |
| 6186@ifset MOD2 6187@node Support, , Checks, Languages | 7073@node Support |
| 6188@section Supported languages | 7074@section Supported languages |
| 6189@end ifset 6190@ifclear MOD2 6191@node Support, , Show, Languages 6192@section Supported languages 6193@end ifclear | |
| 6194 | 7075 |
| 6195@ifset MOD2 6196@value{GDBN} supports C, C++, Fortran, Chill, assembly, and Modula-2. 6197@end ifset 6198@ifclear MOD2 6199@value{GDBN} supports C, C++, Fortran, Chill, and assembly. 6200@end ifclear | 7076@value{GDBN} supports C, C@t{++}, Fortran, Java, Chill, assembly, and Modula-2. 7077@c This is false ... |
| 6201Some @value{GDBN} features may be used in expressions regardless of the 6202language you use: the @value{GDBN} @code{@@} and @code{::} operators, 6203and the @samp{@{type@}addr} construct (@pxref{Expressions, 6204,Expressions}) can be used with the constructs of any supported 6205language. 6206 6207The following sections detail to what degree each source language is 6208supported by @value{GDBN}. These sections are not meant to be language 6209tutorials or references, but serve only as a reference guide to what the 6210@value{GDBN} expression parser accepts, and what input and output 6211formats should look like for different languages. There are many good 6212books written on each of these languages; please look to these for a 6213language reference or tutorial. 6214 | 7078Some @value{GDBN} features may be used in expressions regardless of the 7079language you use: the @value{GDBN} @code{@@} and @code{::} operators, 7080and the @samp{@{type@}addr} construct (@pxref{Expressions, 7081,Expressions}) can be used with the constructs of any supported 7082language. 7083 7084The following sections detail to what degree each source language is 7085supported by @value{GDBN}. These sections are not meant to be language 7086tutorials or references, but serve only as a reference guide to what the 7087@value{GDBN} expression parser accepts, and what input and output 7088formats should look like for different languages. There are many good 7089books written on each of these languages; please look to these for a 7090language reference or tutorial. 7091 |
| 6215@ifset MOD2 | |
| 6216@menu | 7092@menu |
| 6217* C:: C and C++ 6218* Modula-2:: Modula-2 | 7093* C:: C and C@t{++} 7094* Modula-2:: Modula-2 7095* Chill:: Chill |
| 6219@end menu 6220 | 7096@end menu 7097 |
| 6221@node C, Modula-2, , Support 6222@subsection C and C++ 6223@cindex C and C++ 6224@cindex expressions in C or C++ 6225@end ifset | 7098@node C 7099@subsection C and C@t{++} |
| 6226 | 7100 |
| 6227Since C and C++ are so closely related, many features of @value{GDBN} apply | 7101@cindex C and C@t{++} 7102@cindex expressions in C or C@t{++} 7103 7104Since C and C@t{++} are so closely related, many features of @value{GDBN} apply |
| 6228to both languages. Whenever this is the case, we discuss those languages 6229together. 6230 | 7105to both languages. Whenever this is the case, we discuss those languages 7106together. 7107 |
| 6231@ifclear MOD2 6232@c Cancel this below, under same condition, at end of this chapter! 6233@raisesections 6234@end ifclear 6235 6236@ifclear HPPA 6237@cindex C++ 6238@kindex g++ 6239@cindex @sc{gnu} C++ 6240The C++ debugging facilities are jointly implemented by the C++ 6241compiler and @value{GDBN}. Therefore, to debug your C++ code 6242effectively, you must compile your C++ programs with a supported 6243C++ compiler, such as @sc{gnu} @code{g++}, or the HP ANSI C++ | 7108@cindex C@t{++} 7109@cindex @code{g++}, @sc{gnu} C@t{++} compiler 7110@cindex @sc{gnu} C@t{++} 7111The C@t{++} debugging facilities are jointly implemented by the C@t{++} 7112compiler and @value{GDBN}. Therefore, to debug your C@t{++} code 7113effectively, you must compile your C@t{++} programs with a supported 7114C@t{++} compiler, such as @sc{gnu} @code{g++}, or the HP ANSI C@t{++} |
| 6244compiler (@code{aCC}). 6245 | 7115compiler (@code{aCC}). 7116 |
| 6246For best results when using @sc{gnu} C++, use the stabs debugging | 7117For best results when using @sc{gnu} C@t{++}, use the stabs debugging |
| 6247format. You can select that format explicitly with the @code{g++} 6248command-line options @samp{-gstabs} or @samp{-gstabs+}. See 6249@ref{Debugging Options,,Options for Debugging Your Program or @sc{gnu} 6250CC, gcc.info, Using @sc{gnu} CC}, for more information. | 7118format. You can select that format explicitly with the @code{g++} 7119command-line options @samp{-gstabs} or @samp{-gstabs+}. See 7120@ref{Debugging Options,,Options for Debugging Your Program or @sc{gnu} 7121CC, gcc.info, Using @sc{gnu} CC}, for more information. |
| 6251@end ifclear 6252@ifset HPPA 6253@cindex C++ 6254@kindex g++ 6255@cindex @sc{gnu} C++ 6256You can use @value{GDBN} to debug C programs compiled with either the HP 6257C compiler (@code{cc}) or the GNU C compiler (@code{gcc}), and to debug 6258programs compiled with either the HP ANSI C++ compiler (@code{aCC}) or 6259the @sc{gnu} C++ compiler (@code{g++}). | |
| 6260 | 7122 |
| 6261If you compile with the @sc{gnu} C++ compiler, use the stabs debugging 6262format for best results when debugging. You can select that format 6263explicitly with the @code{g++} command-line options @samp{-gstabs} or 6264@samp{-gstabs+}. See @ref{Debugging Options,,Options for Debugging Your 6265Program or @sc{gnu} CC, gcc.info, Using @sc{gnu} CC}, for more 6266information. 6267@end ifset 6268@end ifclear 6269 6270@ifset CONLY 6271@node C, Symbols, Data, Top 6272@chapter C Language Support 6273@cindex C language 6274@cindex expressions in C 6275 6276Information specific to the C language is built into @value{GDBN} so that you 6277can use C expressions while debugging. This also permits @value{GDBN} to 6278output values in a manner consistent with C conventions. 6279 | |
| 6280@menu | 7123@menu |
| 6281* C Operators:: C operators 6282@end menu 6283@end ifset 6284 6285@ifclear CONLY 6286@menu 6287* C Operators:: C and C++ operators 6288* C Constants:: C and C++ constants 6289* Cplus expressions:: C++ expressions 6290* C Defaults:: Default settings for C and C++ 6291@ifset MOD2 6292* C Checks:: C and C++ type and range checks 6293@end ifset 6294 | 7124* C Operators:: C and C@t{++} operators 7125* C Constants:: C and C@t{++} constants 7126* C plus plus expressions:: C@t{++} expressions 7127* C Defaults:: Default settings for C and C@t{++} 7128* C Checks:: C and C@t{++} type and range checks |
| 6295* Debugging C:: @value{GDBN} and C | 7129* Debugging C:: @value{GDBN} and C |
| 6296* Debugging C plus plus:: @value{GDBN} features for C++ | 7130* Debugging C plus plus:: @value{GDBN} features for C@t{++} |
| 6297@end menu | 7131@end menu |
| 6298@end ifclear | |
| 6299 | 7132 |
| 6300@ifclear CONLY 6301@cindex C and C++ operators 6302@node C Operators, C Constants, , C 6303@subsubsection C and C++ operators 6304@end ifclear 6305@ifset CONLY 6306@cindex C operators 6307@node C Operators, C Constants, C, C 6308@section C operators 6309@end ifset | 7133@node C Operators 7134@subsubsection C and C@t{++} operators |
| 6310 | 7135 |
| 7136@cindex C and C@t{++} operators 7137 |
|
| 6311Operators must be defined on values of specific types. For instance, 6312@code{+} is defined on numbers, but not on structures. Operators are | 7138Operators must be defined on values of specific types. For instance, 7139@code{+} is defined on numbers, but not on structures. Operators are |
| 6313often defined on groups of types. | 7140often defined on groups of types. |
| 6314 | 7141 |
| 6315@ifclear CONLY 6316For the purposes of C and C++, the following definitions hold: 6317@end ifclear | 7142For the purposes of C and C@t{++}, the following definitions hold: |
| 6318 6319@itemize @bullet | 7143 7144@itemize @bullet |
| 7145 |
|
| 6320@item | 7146@item |
| 6321@ifclear HPPA | |
| 6322@emph{Integral types} include @code{int} with any of its storage-class | 7147@emph{Integral types} include @code{int} with any of its storage-class |
| 6323specifiers; @code{char}; and @code{enum}. 6324@end ifclear 6325@ifset HPPA 6326@emph{Integral types} include @code{int} with any of its storage-class 6327specifiers; @code{char}; @code{enum}; and, for C++, @code{bool}. 6328@end ifset | 7148specifiers; @code{char}; @code{enum}; and, for C@t{++}, @code{bool}. |
| 6329 6330@item | 7149 7150@item |
| 6331@emph{Floating-point types} include @code{float} and @code{double}. | 7151@emph{Floating-point types} include @code{float}, @code{double}, and 7152@code{long double} (if supported by the target platform). |
| 6332 6333@item | 7153 7154@item |
| 6334@emph{Pointer types} include all types defined as @code{(@var{type} 6335*)}. | 7155@emph{Pointer types} include all types defined as @code{(@var{type} *)}. |
| 6336 6337@item 6338@emph{Scalar types} include all of the above. | 7156 7157@item 7158@emph{Scalar types} include all of the above. |
| 7159 |
|
| 6339@end itemize 6340 6341@noindent 6342The following operators are supported. They are listed here 6343in order of increasing precedence: 6344 6345@table @code 6346@item , 6347The comma or sequencing operator. Expressions in a comma-separated list 6348are evaluated from left to right, with the result of the entire 6349expression being the last expression evaluated. 6350 6351@item = 6352Assignment. The value of an assignment expression is the value 6353assigned. Defined on scalar types. 6354 6355@item @var{op}= 6356Used in an expression of the form @w{@code{@var{a} @var{op}= @var{b}}}, 6357and translated to @w{@code{@var{a} = @var{a op b}}}. | 7160@end itemize 7161 7162@noindent 7163The following operators are supported. They are listed here 7164in order of increasing precedence: 7165 7166@table @code 7167@item , 7168The comma or sequencing operator. Expressions in a comma-separated list 7169are evaluated from left to right, with the result of the entire 7170expression being the last expression evaluated. 7171 7172@item = 7173Assignment. The value of an assignment expression is the value 7174assigned. Defined on scalar types. 7175 7176@item @var{op}= 7177Used in an expression of the form @w{@code{@var{a} @var{op}= @var{b}}}, 7178and translated to @w{@code{@var{a} = @var{a op b}}}. |
| 6358@w{@code{@var{op}=}} and @code{=} have the same precendence. | 7179@w{@code{@var{op}=}} and @code{=} have the same precedence. |
| 6359@var{op} is any one of the operators @code{|}, @code{^}, @code{&}, 6360@code{<<}, @code{>>}, @code{+}, @code{-}, @code{*}, @code{/}, @code{%}. 6361 6362@item ?: 6363The ternary operator. @code{@var{a} ? @var{b} : @var{c}} can be thought 6364of as: if @var{a} then @var{b} else @var{c}. @var{a} should be of an 6365integral type. 6366 --- 44 unchanged lines hidden (view full) --- 6411 6412@item * 6413Pointer dereferencing. Defined on pointer types. Same precedence as 6414@code{++}. 6415 6416@item & 6417Address operator. Defined on variables. Same precedence as @code{++}. 6418 | 7180@var{op} is any one of the operators @code{|}, @code{^}, @code{&}, 7181@code{<<}, @code{>>}, @code{+}, @code{-}, @code{*}, @code{/}, @code{%}. 7182 7183@item ?: 7184The ternary operator. @code{@var{a} ? @var{b} : @var{c}} can be thought 7185of as: if @var{a} then @var{b} else @var{c}. @var{a} should be of an 7186integral type. 7187 --- 44 unchanged lines hidden (view full) --- 7232 7233@item * 7234Pointer dereferencing. Defined on pointer types. Same precedence as 7235@code{++}. 7236 7237@item & 7238Address operator. Defined on variables. Same precedence as @code{++}. 7239 |
| 6419@ifclear CONLY 6420For debugging C++, @value{GDBN} implements a use of @samp{&} beyond what is 6421allowed in the C++ language itself: you can use @samp{&(&@var{ref})} | 7240For debugging C@t{++}, @value{GDBN} implements a use of @samp{&} beyond what is 7241allowed in the C@t{++} language itself: you can use @samp{&(&@var{ref})} |
| 6422(or, if you prefer, simply @samp{&&@var{ref}}) to examine the address | 7242(or, if you prefer, simply @samp{&&@var{ref}}) to examine the address |
| 6423where a C++ reference variable (declared with @samp{&@var{ref}}) is | 7243where a C@t{++} reference variable (declared with @samp{&@var{ref}}) is |
| 6424stored. | 7244stored. |
| 6425@end ifclear | |
| 6426 6427@item - 6428Negative. Defined on integral and floating-point types. Same 6429precedence as @code{++}. 6430 6431@item ! 6432Logical negation. Defined on integral types. Same precedence as 6433@code{++}. --- 4 unchanged lines hidden (view full) --- 6438 6439 6440@item .@r{, }-> 6441Structure member, and pointer-to-structure member. For convenience, 6442@value{GDBN} regards the two as equivalent, choosing whether to dereference a 6443pointer based on the stored type information. 6444Defined on @code{struct} and @code{union} data. 6445 | 7245 7246@item - 7247Negative. Defined on integral and floating-point types. Same 7248precedence as @code{++}. 7249 7250@item ! 7251Logical negation. Defined on integral types. Same precedence as 7252@code{++}. --- 4 unchanged lines hidden (view full) --- 7257 7258 7259@item .@r{, }-> 7260Structure member, and pointer-to-structure member. For convenience, 7261@value{GDBN} regards the two as equivalent, choosing whether to dereference a 7262pointer based on the stored type information. 7263Defined on @code{struct} and @code{union} data. 7264 |
| 6446@ifset HPPA | |
| 6447@item .*@r{, }->* 6448Dereferences of pointers to members. | 7265@item .*@r{, }->* 7266Dereferences of pointers to members. |
| 6449@end ifset | |
| 6450 6451@item [] 6452Array indexing. @code{@var{a}[@var{i}]} is defined as 6453@code{*(@var{a}+@var{i})}. Same precedence as @code{->}. 6454 6455@item () 6456Function parameter list. Same precedence as @code{->}. 6457 | 7267 7268@item [] 7269Array indexing. @code{@var{a}[@var{i}]} is defined as 7270@code{*(@var{a}+@var{i})}. Same precedence as @code{->}. 7271 7272@item () 7273Function parameter list. Same precedence as @code{->}. 7274 |
| 6458@ifclear CONLY | |
| 6459@item :: | 7275@item :: |
| 6460C++ scope resolution operator. Defined on 6461@code{struct}, @code{union}, and @code{class} types. 6462@end ifclear | 7276C@t{++} scope resolution operator. Defined on @code{struct}, @code{union}, 7277and @code{class} types. |
| 6463 6464@item :: | 7278 7279@item :: |
| 6465Doubled colons 6466@ifclear CONLY 6467also 6468@end ifclear 6469represent the @value{GDBN} scope operator (@pxref{Expressions, 6470,Expressions}). 6471@ifclear CONLY 6472Same precedence as @code{::}, above. 6473@end ifclear | 7280Doubled colons also represent the @value{GDBN} scope operator 7281(@pxref{Expressions, ,Expressions}). Same precedence as @code{::}, 7282above. |
| 6474@end table 6475 | 7283@end table 7284 |
| 6476@ifset HPPA | |
| 6477If an operator is redefined in the user code, @value{GDBN} usually 6478attempts to invoke the redefined version instead of using the operator's 6479predefined meaning. | 7285If an operator is redefined in the user code, @value{GDBN} usually 7286attempts to invoke the redefined version instead of using the operator's 7287predefined meaning. |
| 6480@end ifset | |
| 6481 | 7288 |
| 6482@ifclear CONLY | |
| 6483@menu | 7289@menu |
| 6484* C Constants:: | 7290* C Constants:: |
| 6485@end menu 6486 | 7291@end menu 7292 |
| 6487@ifset MOD2 6488@node C Constants, Cplus expressions, C Operators, C 6489@subsubsection C and C++ constants 6490@end ifset 6491@ifclear MOD2 6492@node C Constants, Cplus expressions, C Operators, Support 6493@subsubsection C and C++ constants 6494@end ifclear | 7293@node C Constants 7294@subsubsection C and C@t{++} constants |
| 6495 | 7295 |
| 6496@cindex C and C++ constants 6497@value{GDBN} allows you to express the constants of C and C++ in the 6498following ways: 6499@end ifclear 6500@ifset CONLY 6501@cindex C constants 6502@node C Constants, Debugging C, C Operators, C 6503@section C constants | 7296@cindex C and C@t{++} constants |
| 6504 | 7297 |
| 6505@value{GDBN} allows you to express the constants of C in the | 7298@value{GDBN} allows you to express the constants of C and C@t{++} in the |
| 6506following ways: | 7299following ways: |
| 6507@end ifset | |
| 6508 6509@itemize @bullet 6510@item 6511Integer constants are a sequence of digits. Octal constants are | 7300 7301@itemize @bullet 7302@item 7303Integer constants are a sequence of digits. Octal constants are |
| 6512specified by a leading @samp{0} (i.e. zero), and hexadecimal constants by 6513a leading @samp{0x} or @samp{0X}. Constants may also end with a letter | 7304specified by a leading @samp{0} (i.e.@: zero), and hexadecimal constants 7305by a leading @samp{0x} or @samp{0X}. Constants may also end with a letter |
| 6514@samp{l}, specifying that the constant should be treated as a 6515@code{long} value. 6516 6517@item 6518Floating point constants are a sequence of digits, followed by a decimal 6519point, followed by a sequence of digits, and optionally followed by an 6520exponent. An exponent is of the form: 6521@samp{@w{e@r{[[}+@r{]|}-@r{]}@var{nnn}}}, where @var{nnn} is another 6522sequence of digits. The @samp{+} is optional for positive exponents. | 7306@samp{l}, specifying that the constant should be treated as a 7307@code{long} value. 7308 7309@item 7310Floating point constants are a sequence of digits, followed by a decimal 7311point, followed by a sequence of digits, and optionally followed by an 7312exponent. An exponent is of the form: 7313@samp{@w{e@r{[[}+@r{]|}-@r{]}@var{nnn}}}, where @var{nnn} is another 7314sequence of digits. The @samp{+} is optional for positive exponents. |
| 7315A floating-point constant may also end with a letter @samp{f} or 7316@samp{F}, specifying that the constant should be treated as being of 7317the @code{float} (as opposed to the default @code{double}) type; or with 7318a letter @samp{l} or @samp{L}, which specifies a @code{long double} 7319constant. |
|
| 6523 6524@item 6525Enumerated constants consist of enumerated identifiers, or their 6526integral equivalents. 6527 6528@item 6529Character constants are a single character surrounded by single quotes 6530(@code{'}), or a number---the ordinal value of the corresponding character | 7320 7321@item 7322Enumerated constants consist of enumerated identifiers, or their 7323integral equivalents. 7324 7325@item 7326Character constants are a single character surrounded by single quotes 7327(@code{'}), or a number---the ordinal value of the corresponding character |
| 6531(usually its @sc{ASCII} value). Within quotes, the single character may | 7328(usually its @sc{ascii} value). Within quotes, the single character may |
| 6532be represented by a letter or by @dfn{escape sequences}, which are of 6533the form @samp{\@var{nnn}}, where @var{nnn} is the octal representation 6534of the character's ordinal value; or of the form @samp{\@var{x}}, where 6535@samp{@var{x}} is a predefined special character---for example, 6536@samp{\n} for newline. 6537 6538@item | 7329be represented by a letter or by @dfn{escape sequences}, which are of 7330the form @samp{\@var{nnn}}, where @var{nnn} is the octal representation 7331of the character's ordinal value; or of the form @samp{\@var{x}}, where 7332@samp{@var{x}} is a predefined special character---for example, 7333@samp{\n} for newline. 7334 7335@item |
| 6539String constants are a sequence of character constants surrounded 6540by double quotes (@code{"}). | 7336String constants are a sequence of character constants surrounded by 7337double quotes (@code{"}). Any valid character constant (as described 7338above) may appear. Double quotes within the string must be preceded by 7339a backslash, so for instance @samp{"a\"b'c"} is a string of five 7340characters. |
| 6541 6542@item 6543Pointer constants are an integral value. You can also write pointers 6544to constants using the C operator @samp{&}. 6545 6546@item 6547Array constants are comma-separated lists surrounded by braces @samp{@{} 6548and @samp{@}}; for example, @samp{@{1,2,3@}} is a three-element array of 6549integers, @samp{@{@{1,2@}, @{3,4@}, @{5,6@}@}} is a three-by-two array, 6550and @samp{@{&"hi", &"there", &"fred"@}} is a three-element array of pointers. 6551@end itemize 6552 | 7341 7342@item 7343Pointer constants are an integral value. You can also write pointers 7344to constants using the C operator @samp{&}. 7345 7346@item 7347Array constants are comma-separated lists surrounded by braces @samp{@{} 7348and @samp{@}}; for example, @samp{@{1,2,3@}} is a three-element array of 7349integers, @samp{@{@{1,2@}, @{3,4@}, @{5,6@}@}} is a three-by-two array, 7350and @samp{@{&"hi", &"there", &"fred"@}} is a three-element array of pointers. 7351@end itemize 7352 |
| 6553@ifclear CONLY | |
| 6554@menu | 7353@menu |
| 6555* Cplus expressions:: 6556* C Defaults:: 6557@ifset MOD2 6558* C Checks:: 6559@end ifset | 7354* C plus plus expressions:: 7355* C Defaults:: 7356* C Checks:: |
| 6560 | 7357 |
| 6561* Debugging C:: | 7358* Debugging C:: |
| 6562@end menu 6563 | 7359@end menu 7360 |
| 6564@ifset MOD2 6565@node Cplus expressions, C Defaults, C Constants, C 6566@subsubsection C++ expressions 6567@end ifset 6568@ifclear MOD2 6569@node Cplus expressions, C Defaults, C Constants, Support 6570@subsubsection C++ expressions 6571@end ifclear | 7361@node C plus plus expressions 7362@subsubsection C@t{++} expressions |
| 6572 | 7363 |
| 6573@cindex expressions in C++ 6574@value{GDBN} expression handling can interpret most C++ expressions. | 7364@cindex expressions in C@t{++} 7365@value{GDBN} expression handling can interpret most C@t{++} expressions. |
| 6575 | 7366 |
| 6576@ifclear HPPA 6577@cindex C++ support, not in @sc{coff} 6578@cindex @sc{coff} versus C++ 6579@cindex C++ and object formats 6580@cindex object formats and C++ 6581@cindex a.out and C++ 6582@cindex @sc{ecoff} and C++ 6583@cindex @sc{xcoff} and C++ 6584@cindex @sc{elf}/stabs and C++ 6585@cindex @sc{elf}/@sc{dwarf} and C++ | 7367@cindex C@t{++} support, not in @sc{coff} 7368@cindex @sc{coff} versus C@t{++} 7369@cindex C@t{++} and object formats 7370@cindex object formats and C@t{++} 7371@cindex a.out and C@t{++} 7372@cindex @sc{ecoff} and C@t{++} 7373@cindex @sc{xcoff} and C@t{++} 7374@cindex @sc{elf}/stabs and C@t{++} 7375@cindex @sc{elf}/@sc{dwarf} and C@t{++} |
| 6586@c FIXME!! GDB may eventually be able to debug C++ using DWARF; check 6587@c periodically whether this has happened... 6588@quotation | 7376@c FIXME!! GDB may eventually be able to debug C++ using DWARF; check 7377@c periodically whether this has happened... 7378@quotation |
| 6589@emph{Warning:} @value{GDBN} can only debug C++ code if you use the 6590proper compiler. Typically, C++ debugging depends on the use of | 7379@emph{Warning:} @value{GDBN} can only debug C@t{++} code if you use the 7380proper compiler. Typically, C@t{++} debugging depends on the use of |
| 6591additional debugging information in the symbol table, and thus requires 6592special support. In particular, if your compiler generates a.out, MIPS 6593@sc{ecoff}, RS/6000 @sc{xcoff}, or @sc{elf} with stabs extensions to the 6594symbol table, these facilities are all available. (With @sc{gnu} CC, 6595you can use the @samp{-gstabs} option to request stabs debugging 6596extensions explicitly.) Where the object code format is standard | 7381additional debugging information in the symbol table, and thus requires 7382special support. In particular, if your compiler generates a.out, MIPS 7383@sc{ecoff}, RS/6000 @sc{xcoff}, or @sc{elf} with stabs extensions to the 7384symbol table, these facilities are all available. (With @sc{gnu} CC, 7385you can use the @samp{-gstabs} option to request stabs debugging 7386extensions explicitly.) Where the object code format is standard |
| 6597@sc{coff} or @sc{dwarf} in @sc{elf}, on the other hand, most of the C++ | 7387@sc{coff} or @sc{dwarf} in @sc{elf}, on the other hand, most of the C@t{++} |
| 6598support in @value{GDBN} does @emph{not} work. 6599@end quotation | 7388support in @value{GDBN} does @emph{not} work. 7389@end quotation |
| 6600@end ifclear | |
| 6601 6602@enumerate 6603 6604@cindex member functions 6605@item 6606Member function calls are allowed; you can use expressions like 6607 6608@example 6609count = aml->GetOriginal(x, y) 6610@end example 6611 | 7390 7391@enumerate 7392 7393@cindex member functions 7394@item 7395Member function calls are allowed; you can use expressions like 7396 7397@example 7398count = aml->GetOriginal(x, y) 7399@end example 7400 |
| 6612@kindex this 6613@cindex namespace in C++ | 7401@vindex this@r{, inside C@t{++} member functions} 7402@cindex namespace in C@t{++} |
| 6614@item 6615While a member function is active (in the selected stack frame), your 6616expressions have the same namespace available as the member function; 6617that is, @value{GDBN} allows implicit references to the class instance | 7403@item 7404While a member function is active (in the selected stack frame), your 7405expressions have the same namespace available as the member function; 7406that is, @value{GDBN} allows implicit references to the class instance |
| 6618pointer @code{this} following the same rules as C++. | 7407pointer @code{this} following the same rules as C@t{++}. |
| 6619 | 7408 |
| 6620@ifclear HPPA | |
| 6621@cindex call overloaded functions | 7409@cindex call overloaded functions |
| 6622@cindex type conversions in C++ | 7410@cindex overloaded functions, calling 7411@cindex type conversions in C@t{++} |
| 6623@item 6624You can call overloaded functions; @value{GDBN} resolves the function | 7412@item 7413You can call overloaded functions; @value{GDBN} resolves the function |
| 6625call to the right definition, with one restriction---you must use 6626arguments of the type required by the function that you want to call. 6627@value{GDBN} does not perform conversions requiring constructors or 6628user-defined type operators. 6629@end ifclear 6630@ifset HPPA 6631@cindex call overloaded functions 6632@cindex overloaded functions 6633@cindex type conversions in C++ 6634@item 6635You can call overloaded functions; @value{GDBN} resolves the function 6636call to the right definition, with some restrictions. GDB does not | 7414call to the right definition, with some restrictions. @value{GDBN} does not |
| 6637perform overload resolution involving user-defined type conversions, 6638calls to constructors, or instantiations of templates that do not exist 6639in the program. It also cannot handle ellipsis argument lists or 6640default arguments. 6641 6642It does perform integral conversions and promotions, floating-point 6643promotions, arithmetic conversions, pointer conversions, conversions of 6644class objects to base classes, and standard conversions such as those of 6645functions or arrays to pointers; it requires an exact match on the 6646number of function arguments. 6647 6648Overload resolution is always performed, unless you have specified 6649@code{set overload-resolution off}. @xref{Debugging C plus plus, | 7415perform overload resolution involving user-defined type conversions, 7416calls to constructors, or instantiations of templates that do not exist 7417in the program. It also cannot handle ellipsis argument lists or 7418default arguments. 7419 7420It does perform integral conversions and promotions, floating-point 7421promotions, arithmetic conversions, pointer conversions, conversions of 7422class objects to base classes, and standard conversions such as those of 7423functions or arrays to pointers; it requires an exact match on the 7424number of function arguments. 7425 7426Overload resolution is always performed, unless you have specified 7427@code{set overload-resolution off}. @xref{Debugging C plus plus, |
| 6650,@value{GDBN} features for C++}. | 7428,@value{GDBN} features for C@t{++}}. |
| 6651 | 7429 |
| 6652You must specify@code{set overload-resolution off} in order to use an | 7430You must specify @code{set overload-resolution off} in order to use an |
| 6653explicit function signature to call an overloaded function, as in 6654@smallexample 6655p 'foo(char,int)'('x', 13) 6656@end smallexample | 7431explicit function signature to call an overloaded function, as in 7432@smallexample 7433p 'foo(char,int)'('x', 13) 7434@end smallexample |
| 7435 |
|
| 6657The @value{GDBN} command-completion facility can simplify this; | 7436The @value{GDBN} command-completion facility can simplify this; |
| 6658@pxref{Completion, ,Command completion}. | 7437see @ref{Completion, ,Command completion}. |
| 6659 | 7438 |
| 6660@end ifset 6661 | |
| 6662@cindex reference declarations 6663@item | 7439@cindex reference declarations 7440@item |
| 6664@value{GDBN} understands variables declared as C++ references; you can use 6665them in expressions just as you do in C++ source---they are automatically | 7441@value{GDBN} understands variables declared as C@t{++} references; you can use 7442them in expressions just as you do in C@t{++} source---they are automatically |
| 6666dereferenced. 6667 6668In the parameter list shown when @value{GDBN} displays a frame, the values of 6669reference variables are not displayed (unlike other variables); this 6670avoids clutter, since references are often used for large structures. 6671The @emph{address} of a reference variable is always shown, unless 6672you have specified @samp{set print address off}. 6673 6674@item | 7443dereferenced. 7444 7445In the parameter list shown when @value{GDBN} displays a frame, the values of 7446reference variables are not displayed (unlike other variables); this 7447avoids clutter, since references are often used for large structures. 7448The @emph{address} of a reference variable is always shown, unless 7449you have specified @samp{set print address off}. 7450 7451@item |
| 6675@value{GDBN} supports the C++ name resolution operator @code{::}---your | 7452@value{GDBN} supports the C@t{++} name resolution operator @code{::}---your |
| 6676expressions can use it just as expressions in your program do. Since 6677one scope may be defined in another, you can use @code{::} repeatedly if 6678necessary, for example in an expression like 6679@samp{@var{scope1}::@var{scope2}::@var{name}}. @value{GDBN} also allows | 7453expressions can use it just as expressions in your program do. Since 7454one scope may be defined in another, you can use @code{::} repeatedly if 7455necessary, for example in an expression like 7456@samp{@var{scope1}::@var{scope2}::@var{name}}. @value{GDBN} also allows |
| 6680resolving name scope by reference to source files, in both C and C++ | 7457resolving name scope by reference to source files, in both C and C@t{++} |
| 6681debugging (@pxref{Variables, ,Program variables}). 6682@end enumerate 6683 | 7458debugging (@pxref{Variables, ,Program variables}). 7459@end enumerate 7460 |
| 6684@ifset HPPA 6685In addition, @value{GDBN} supports calling virtual functions correctly, 6686printing out virtual bases of objects, calling functions in a base 6687subobject, casting objects, and invoking user-defined operators. 6688@end ifset | 7461In addition, when used with HP's C@t{++} compiler, @value{GDBN} supports 7462calling virtual functions correctly, printing out virtual bases of 7463objects, calling functions in a base subobject, casting objects, and 7464invoking user-defined operators. |
| 6689 | 7465 |
| 6690@ifset MOD2 6691@node C Defaults, C Checks, Cplus expressions, C 6692@subsubsection C and C++ defaults 6693@end ifset 6694@ifclear MOD2 6695@node C Defaults, Debugging C, Cplus expressions, Support 6696@subsubsection C and C++ defaults 6697@end ifclear 6698@cindex C and C++ defaults | 7466@node C Defaults 7467@subsubsection C and C@t{++} defaults |
| 6699 | 7468 |
| 6700@ifclear HPPA | 7469@cindex C and C@t{++} defaults 7470 |
| 6701If you allow @value{GDBN} to set type and range checking automatically, they 6702both default to @code{off} whenever the working language changes to | 7471If you allow @value{GDBN} to set type and range checking automatically, they 7472both default to @code{off} whenever the working language changes to |
| 6703C or C++. This happens regardless of whether you or @value{GDBN} | 7473C or C@t{++}. This happens regardless of whether you or @value{GDBN} |
| 6704selects the working language. | 7474selects the working language. |
| 6705@end ifclear | |
| 6706 6707If you allow @value{GDBN} to set the language automatically, it 6708recognizes source files whose names end with @file{.c}, @file{.C}, or 6709@file{.cc}, etc, and when @value{GDBN} enters code compiled from one of | 7475 7476If you allow @value{GDBN} to set the language automatically, it 7477recognizes source files whose names end with @file{.c}, @file{.C}, or 7478@file{.cc}, etc, and when @value{GDBN} enters code compiled from one of |
| 6710these files, it sets the working language to C or C++. | 7479these files, it sets the working language to C or C@t{++}. |
| 6711@xref{Automatically, ,Having @value{GDBN} infer the source language}, 6712for further details. 6713 | 7480@xref{Automatically, ,Having @value{GDBN} infer the source language}, 7481for further details. 7482 |
| 6714@ifset MOD2 | |
| 6715@c Type checking is (a) primarily motivated by Modula-2, and (b) 6716@c unimplemented. If (b) changes, it might make sense to let this node 6717@c appear even if Mod-2 does not, but meanwhile ignore it. roland 16jul93. | 7483@c Type checking is (a) primarily motivated by Modula-2, and (b) 7484@c unimplemented. If (b) changes, it might make sense to let this node 7485@c appear even if Mod-2 does not, but meanwhile ignore it. roland 16jul93. |
| 6718@node C Checks, Debugging C, C Defaults, C Constants 6719@subsubsection C and C++ type and range checks 6720@cindex C and C++ checks | |
| 6721 | 7486 |
| 6722By default, when @value{GDBN} parses C or C++ expressions, type checking | 7487@node C Checks 7488@subsubsection C and C@t{++} type and range checks 7489 7490@cindex C and C@t{++} checks 7491 7492By default, when @value{GDBN} parses C or C@t{++} expressions, type checking |
| 6723is not used. However, if you turn type checking on, @value{GDBN} 6724considers two variables type equivalent if: 6725 6726@itemize @bullet 6727@item 6728The two variables are structured and have the same structure, union, or 6729enumerated tag. 6730 --- 9 unchanged lines hidden (view full) --- 6740declared in the same declaration. (Note: this may not be true for all C 6741compilers.) 6742@end ignore 6743@end itemize 6744 6745Range checking, if turned on, is done on mathematical operations. Array 6746indices are not checked, since they are often used to index a pointer 6747that is not itself an array. | 7493is not used. However, if you turn type checking on, @value{GDBN} 7494considers two variables type equivalent if: 7495 7496@itemize @bullet 7497@item 7498The two variables are structured and have the same structure, union, or 7499enumerated tag. 7500 --- 9 unchanged lines hidden (view full) --- 7510declared in the same declaration. (Note: this may not be true for all C 7511compilers.) 7512@end ignore 7513@end itemize 7514 7515Range checking, if turned on, is done on mathematical operations. Array 7516indices are not checked, since they are often used to index a pointer 7517that is not itself an array. |
| 6748@end ifset 6749@end ifclear | |
| 6750 | 7518 |
| 6751@ifclear CONLY 6752@ifset MOD2 6753@node Debugging C, Debugging C plus plus, C Checks, C | 7519@node Debugging C |
| 6754@subsubsection @value{GDBN} and C | 7520@subsubsection @value{GDBN} and C |
| 6755@end ifset 6756@ifclear MOD2 6757@node Debugging C, Debugging C plus plus, C Defaults, Support 6758@subsubsection @value{GDBN} and C 6759@end ifclear 6760@end ifclear 6761@ifset CONLY 6762@node Debugging C, , C Constants, C 6763@section @value{GDBN} and C 6764@end ifset | |
| 6765 6766The @code{set print union} and @code{show print union} commands apply to 6767the @code{union} type. When set to @samp{on}, any @code{union} that is | 7521 7522The @code{set print union} and @code{show print union} commands apply to 7523the @code{union} type. When set to @samp{on}, any @code{union} that is |
| 6768inside a @code{struct} 6769@ifclear CONLY 6770or @code{class} 6771@end ifclear 6772is also printed. 6773Otherwise, it appears as @samp{@{...@}}. | 7524inside a @code{struct} or @code{class} is also printed. Otherwise, it 7525appears as @samp{@{...@}}. |
| 6774 6775The @code{@@} operator aids in the debugging of dynamic arrays, formed 6776with pointers and a memory allocation function. @xref{Expressions, 6777,Expressions}. 6778 | 7526 7527The @code{@@} operator aids in the debugging of dynamic arrays, formed 7528with pointers and a memory allocation function. @xref{Expressions, 7529,Expressions}. 7530 |
| 6779@ifclear CONLY | |
| 6780@menu | 7531@menu |
| 6781* Debugging C plus plus:: | 7532* Debugging C plus plus:: |
| 6782@end menu 6783 | 7533@end menu 7534 |
| 6784@ifset MOD2 6785@node Debugging C plus plus, , Debugging C, C 6786@subsubsection @value{GDBN} features for C++ 6787@end ifset 6788@ifclear MOD2 6789@node Debugging C plus plus, , Debugging C, Support 6790@subsubsection @value{GDBN} features for C++ 6791@end ifclear | 7535@node Debugging C plus plus 7536@subsubsection @value{GDBN} features for C@t{++} |
| 6792 | 7537 |
| 6793@cindex commands for C++ 6794Some @value{GDBN} commands are particularly useful with C++, and some are 6795designed specifically for use with C++. Here is a summary: | 7538@cindex commands for C@t{++} |
| 6796 | 7539 |
| 7540Some @value{GDBN} commands are particularly useful with C@t{++}, and some are 7541designed specifically for use with C@t{++}. Here is a summary: 7542 |
|
| 6797@table @code 6798@cindex break in overloaded functions 6799@item @r{breakpoint menus} 6800When you want a breakpoint in a function whose name is overloaded, 6801@value{GDBN} breakpoint menus help you specify which function definition 6802you want. @xref{Breakpoint Menus,,Breakpoint menus}. 6803 | 7543@table @code 7544@cindex break in overloaded functions 7545@item @r{breakpoint menus} 7546When you want a breakpoint in a function whose name is overloaded, 7547@value{GDBN} breakpoint menus help you specify which function definition 7548you want. @xref{Breakpoint Menus,,Breakpoint menus}. 7549 |
| 6804@cindex overloading in C++ | 7550@cindex overloading in C@t{++} |
| 6805@item rbreak @var{regex} 6806Setting breakpoints using regular expressions is helpful for setting 6807breakpoints on overloaded functions that are not members of any special 6808classes. 6809@xref{Set Breaks, ,Setting breakpoints}. 6810 | 7551@item rbreak @var{regex} 7552Setting breakpoints using regular expressions is helpful for setting 7553breakpoints on overloaded functions that are not members of any special 7554classes. 7555@xref{Set Breaks, ,Setting breakpoints}. 7556 |
| 6811@cindex C++ exception handling | 7557@cindex C@t{++} exception handling |
| 6812@item catch throw 6813@itemx catch catch | 7558@item catch throw 7559@itemx catch catch |
| 6814Debug C++ exception handling using these commands. @xref{Set | 7560Debug C@t{++} exception handling using these commands. @xref{Set |
| 6815Catchpoints, , Setting catchpoints}. 6816 6817@cindex inheritance 6818@item ptype @var{typename} 6819Print inheritance relationships as well as other information for type 6820@var{typename}. 6821@xref{Symbols, ,Examining the Symbol Table}. 6822 | 7561Catchpoints, , Setting catchpoints}. 7562 7563@cindex inheritance 7564@item ptype @var{typename} 7565Print inheritance relationships as well as other information for type 7566@var{typename}. 7567@xref{Symbols, ,Examining the Symbol Table}. 7568 |
| 6823@cindex C++ symbol display | 7569@cindex C@t{++} symbol display |
| 6824@item set print demangle 6825@itemx show print demangle 6826@itemx set print asm-demangle 6827@itemx show print asm-demangle | 7570@item set print demangle 7571@itemx show print demangle 7572@itemx set print asm-demangle 7573@itemx show print asm-demangle |
| 6828Control whether C++ symbols display in their source form, both when 6829displaying code as C++ source and when displaying disassemblies. | 7574Control whether C@t{++} symbols display in their source form, both when 7575displaying code as C@t{++} source and when displaying disassemblies. |
| 6830@xref{Print Settings, ,Print settings}. 6831 6832@item set print object 6833@itemx show print object 6834Choose whether to print derived (actual) or declared types of objects. 6835@xref{Print Settings, ,Print settings}. 6836 6837@item set print vtbl 6838@itemx show print vtbl 6839Control the format for printing virtual function tables. 6840@xref{Print Settings, ,Print settings}. | 7576@xref{Print Settings, ,Print settings}. 7577 7578@item set print object 7579@itemx show print object 7580Choose whether to print derived (actual) or declared types of objects. 7581@xref{Print Settings, ,Print settings}. 7582 7583@item set print vtbl 7584@itemx show print vtbl 7585Control the format for printing virtual function tables. 7586@xref{Print Settings, ,Print settings}. |
| 6841@ifset HPPA | |
| 6842(The @code{vtbl} commands do not work on programs compiled with the HP | 7587(The @code{vtbl} commands do not work on programs compiled with the HP |
| 6843ANSI C++ compiler (@code{aCC}).) | 7588ANSI C@t{++} compiler (@code{aCC}).) |
| 6844 6845@kindex set overload-resolution | 7589 7590@kindex set overload-resolution |
| 6846@cindex overloaded functions | 7591@cindex overloaded functions, overload resolution |
| 6847@item set overload-resolution on | 7592@item set overload-resolution on |
| 6848Enable overload resolution for C++ expression evaluation. The default | 7593Enable overload resolution for C@t{++} expression evaluation. The default |
| 6849is on. For overloaded functions, @value{GDBN} evaluates the arguments 6850and searches for a function whose signature matches the argument types, | 7594is on. For overloaded functions, @value{GDBN} evaluates the arguments 7595and searches for a function whose signature matches the argument types, |
| 6851using the standard C++ conversion rules (@pxref{Cplus expressions, ,C++ 6852expressions} for details). If it cannot find a match, it emits a | 7596using the standard C@t{++} conversion rules (see @ref{C plus plus expressions, ,C@t{++} 7597expressions}, for details). If it cannot find a match, it emits a |
| 6853message. 6854 6855@item set overload-resolution off | 7598message. 7599 7600@item set overload-resolution off |
| 6856Disable overload resolution for C++ expression evaluation. For | 7601Disable overload resolution for C@t{++} expression evaluation. For |
| 6857overloaded functions that are not class member functions, @value{GDBN} 6858chooses the first function of the specified name that it finds in the 6859symbol table, whether or not its arguments are of the correct type. For 6860overloaded functions that are class member functions, @value{GDBN} 6861searches for a function whose signature @emph{exactly} matches the 6862argument types. | 7602overloaded functions that are not class member functions, @value{GDBN} 7603chooses the first function of the specified name that it finds in the 7604symbol table, whether or not its arguments are of the correct type. For 7605overloaded functions that are class member functions, @value{GDBN} 7606searches for a function whose signature @emph{exactly} matches the 7607argument types. |
| 6863@end ifset | |
| 6864 6865@item @r{Overloaded symbol names} 6866You can specify a particular definition of an overloaded symbol, using | 7608 7609@item @r{Overloaded symbol names} 7610You can specify a particular definition of an overloaded symbol, using |
| 6867the same notation that is used to declare such symbols in C++: type | 7611the same notation that is used to declare such symbols in C@t{++}: type |
| 6868@code{@var{symbol}(@var{types})} rather than just @var{symbol}. You can 6869also use the @value{GDBN} command-line word completion facilities to list the 6870available choices, or to finish the type list for you. 6871@xref{Completion,, Command completion}, for details on how to do this. 6872@end table | 7612@code{@var{symbol}(@var{types})} rather than just @var{symbol}. You can 7613also use the @value{GDBN} command-line word completion facilities to list the 7614available choices, or to finish the type list for you. 7615@xref{Completion,, Command completion}, for details on how to do this. 7616@end table |
| 6873@ifclear MOD2 6874@c cancels "raisesections" under same conditions near bgn of chapter 6875@lowersections 6876@end ifclear | |
| 6877 | 7617 |
| 6878@ifset MOD2 6879@node Modula-2, ,C , Support | 7618@node Modula-2 |
| 6880@subsection Modula-2 | 7619@subsection Modula-2 |
| 6881@cindex Modula-2 | |
| 6882 | 7620 |
| 7621@cindex Modula-2, @value{GDBN} support 7622 |
|
| 6883The extensions made to @value{GDBN} to support Modula-2 only support 6884output from the @sc{gnu} Modula-2 compiler (which is currently being 6885developed). Other Modula-2 compilers are not currently supported, and 6886attempting to debug executables produced by them is most likely 6887to give an error as @value{GDBN} reads in the executable's symbol 6888table. 6889 6890@cindex expressions in Modula-2 6891@menu 6892* M2 Operators:: Built-in operators 6893* Built-In Func/Proc:: Built-in functions and procedures 6894* M2 Constants:: Modula-2 constants 6895* M2 Defaults:: Default settings for Modula-2 6896* Deviations:: Deviations from standard Modula-2 6897* M2 Checks:: Modula-2 type and range checks 6898* M2 Scope:: The scope operators @code{::} and @code{.} 6899* GDB/M2:: @value{GDBN} and Modula-2 6900@end menu 6901 | 7623The extensions made to @value{GDBN} to support Modula-2 only support 7624output from the @sc{gnu} Modula-2 compiler (which is currently being 7625developed). Other Modula-2 compilers are not currently supported, and 7626attempting to debug executables produced by them is most likely 7627to give an error as @value{GDBN} reads in the executable's symbol 7628table. 7629 7630@cindex expressions in Modula-2 7631@menu 7632* M2 Operators:: Built-in operators 7633* Built-In Func/Proc:: Built-in functions and procedures 7634* M2 Constants:: Modula-2 constants 7635* M2 Defaults:: Default settings for Modula-2 7636* Deviations:: Deviations from standard Modula-2 7637* M2 Checks:: Modula-2 type and range checks 7638* M2 Scope:: The scope operators @code{::} and @code{.} 7639* GDB/M2:: @value{GDBN} and Modula-2 7640@end menu 7641 |
| 6902@node M2 Operators, Built-In Func/Proc, Modula-2, Modula-2 | 7642@node M2 Operators |
| 6903@subsubsection Operators 6904@cindex Modula-2 operators 6905 6906Operators must be defined on values of specific types. For instance, 6907@code{+} is defined on numbers, but not on structures. Operators are 6908often defined on groups of types. For the purposes of Modula-2, the 6909following definitions hold: 6910 --- 35 unchanged lines hidden (view full) --- 6946Assignment. The value of @var{var} @code{:=} @var{value} is 6947@var{value}. 6948 6949@item <@r{, }> 6950Less than, greater than on integral, floating-point, or enumerated 6951types. 6952 6953@item <=@r{, }>= | 7643@subsubsection Operators 7644@cindex Modula-2 operators 7645 7646Operators must be defined on values of specific types. For instance, 7647@code{+} is defined on numbers, but not on structures. Operators are 7648often defined on groups of types. For the purposes of Modula-2, the 7649following definitions hold: 7650 --- 35 unchanged lines hidden (view full) --- 7686Assignment. The value of @var{var} @code{:=} @var{value} is 7687@var{value}. 7688 7689@item <@r{, }> 7690Less than, greater than on integral, floating-point, or enumerated 7691types. 7692 7693@item <=@r{, }>= |
| 6954Less than, greater than, less than or equal to, greater than or equal to | 7694Less than or equal to, greater than or equal to |
| 6955on integral, floating-point and enumerated types, or set inclusion on 6956set types. Same precedence as @code{<}. 6957 6958@item =@r{, }<>@r{, }# 6959Equality and two ways of expressing inequality, valid on scalar types. 6960Same precedence as @code{<}. In @value{GDBN} scripts, only @code{<>} is 6961available for inequality, since @code{#} conflicts with the script 6962comment character. 6963 6964@item IN 6965Set membership. Defined on set types and the types of their members. 6966Same precedence as @code{<}. 6967 6968@item OR 6969Boolean disjunction. Defined on boolean types. 6970 6971@item AND@r{, }& | 7695on integral, floating-point and enumerated types, or set inclusion on 7696set types. Same precedence as @code{<}. 7697 7698@item =@r{, }<>@r{, }# 7699Equality and two ways of expressing inequality, valid on scalar types. 7700Same precedence as @code{<}. In @value{GDBN} scripts, only @code{<>} is 7701available for inequality, since @code{#} conflicts with the script 7702comment character. 7703 7704@item IN 7705Set membership. Defined on set types and the types of their members. 7706Same precedence as @code{<}. 7707 7708@item OR 7709Boolean disjunction. Defined on boolean types. 7710 7711@item AND@r{, }& |
| 6972Boolean conjuction. Defined on boolean types. | 7712Boolean conjunction. Defined on boolean types. |
| 6973 6974@item @@ 6975The @value{GDBN} ``artificial array'' operator (@pxref{Expressions, ,Expressions}). 6976 6977@item +@r{, }- 6978Addition and subtraction on integral and floating-point types, or union 6979and difference on set types. 6980 --- 36 unchanged lines hidden (view full) --- 7017 7018@quotation 7019@emph{Warning:} Sets and their operations are not yet supported, so @value{GDBN} 7020treats the use of the operator @code{IN}, or the use of operators 7021@code{+}, @code{-}, @code{*}, @code{/}, @code{=}, , @code{<>}, @code{#}, 7022@code{<=}, and @code{>=} on sets as an error. 7023@end quotation 7024 | 7713 7714@item @@ 7715The @value{GDBN} ``artificial array'' operator (@pxref{Expressions, ,Expressions}). 7716 7717@item +@r{, }- 7718Addition and subtraction on integral and floating-point types, or union 7719and difference on set types. 7720 --- 36 unchanged lines hidden (view full) --- 7757 7758@quotation 7759@emph{Warning:} Sets and their operations are not yet supported, so @value{GDBN} 7760treats the use of the operator @code{IN}, or the use of operators 7761@code{+}, @code{-}, @code{*}, @code{/}, @code{=}, , @code{<>}, @code{#}, 7762@code{<=}, and @code{>=} on sets as an error. 7763@end quotation 7764 |
| 7025@cindex Modula-2 built-ins 7026@node Built-In Func/Proc, M2 Constants, M2 Operators, Modula-2 | 7765 7766@node Built-In Func/Proc |
| 7027@subsubsection Built-in functions and procedures | 7767@subsubsection Built-in functions and procedures |
| 7768@cindex Modula-2 built-ins |
|
| 7028 7029Modula-2 also makes available several built-in procedures and functions. 7030In describing these, the following metavariables are used: 7031 7032@table @var 7033 7034@item a 7035represents an @code{ARRAY} variable. --- 29 unchanged lines hidden (view full) --- 7065All Modula-2 built-in procedures also return a result, described below. 7066 7067@table @code 7068@item ABS(@var{n}) 7069Returns the absolute value of @var{n}. 7070 7071@item CAP(@var{c}) 7072If @var{c} is a lower case letter, it returns its upper case | 7769 7770Modula-2 also makes available several built-in procedures and functions. 7771In describing these, the following metavariables are used: 7772 7773@table @var 7774 7775@item a 7776represents an @code{ARRAY} variable. --- 29 unchanged lines hidden (view full) --- 7806All Modula-2 built-in procedures also return a result, described below. 7807 7808@table @code 7809@item ABS(@var{n}) 7810Returns the absolute value of @var{n}. 7811 7812@item CAP(@var{c}) 7813If @var{c} is a lower case letter, it returns its upper case |
| 7073equivalent, otherwise it returns its argument | 7814equivalent, otherwise it returns its argument. |
| 7074 7075@item CHR(@var{i}) 7076Returns the character whose ordinal value is @var{i}. 7077 7078@item DEC(@var{v}) | 7815 7816@item CHR(@var{i}) 7817Returns the character whose ordinal value is @var{i}. 7818 7819@item DEC(@var{v}) |
| 7079Decrements the value in the variable @var{v}. Returns the new value. | 7820Decrements the value in the variable @var{v} by one. Returns the new value. |
| 7080 7081@item DEC(@var{v},@var{i}) 7082Decrements the value in the variable @var{v} by @var{i}. Returns the 7083new value. 7084 7085@item EXCL(@var{m},@var{s}) 7086Removes the element @var{m} from the set @var{s}. Returns the new 7087set. 7088 7089@item FLOAT(@var{i}) 7090Returns the floating point equivalent of the integer @var{i}. 7091 7092@item HIGH(@var{a}) 7093Returns the index of the last member of @var{a}. 7094 7095@item INC(@var{v}) | 7821 7822@item DEC(@var{v},@var{i}) 7823Decrements the value in the variable @var{v} by @var{i}. Returns the 7824new value. 7825 7826@item EXCL(@var{m},@var{s}) 7827Removes the element @var{m} from the set @var{s}. Returns the new 7828set. 7829 7830@item FLOAT(@var{i}) 7831Returns the floating point equivalent of the integer @var{i}. 7832 7833@item HIGH(@var{a}) 7834Returns the index of the last member of @var{a}. 7835 7836@item INC(@var{v}) |
| 7096Increments the value in the variable @var{v}. Returns the new value. | 7837Increments the value in the variable @var{v} by one. Returns the new value. |
| 7097 7098@item INC(@var{v},@var{i}) 7099Increments the value in the variable @var{v} by @var{i}. Returns the 7100new value. 7101 7102@item INCL(@var{m},@var{s}) 7103Adds the element @var{m} to the set @var{s} if it is not already 7104there. Returns the new set. --- 4 unchanged lines hidden (view full) --- 7109@item MIN(@var{t}) 7110Returns the minimum value of the type @var{t}. 7111 7112@item ODD(@var{i}) 7113Returns boolean TRUE if @var{i} is an odd number. 7114 7115@item ORD(@var{x}) 7116Returns the ordinal value of its argument. For example, the ordinal | 7838 7839@item INC(@var{v},@var{i}) 7840Increments the value in the variable @var{v} by @var{i}. Returns the 7841new value. 7842 7843@item INCL(@var{m},@var{s}) 7844Adds the element @var{m} to the set @var{s} if it is not already 7845there. Returns the new set. --- 4 unchanged lines hidden (view full) --- 7850@item MIN(@var{t}) 7851Returns the minimum value of the type @var{t}. 7852 7853@item ODD(@var{i}) 7854Returns boolean TRUE if @var{i} is an odd number. 7855 7856@item ORD(@var{x}) 7857Returns the ordinal value of its argument. For example, the ordinal |
| 7117value of a character is its ASCII value (on machines supporting the 7118ASCII character set). @var{x} must be of an ordered type, which include | 7858value of a character is its @sc{ascii} value (on machines supporting the 7859@sc{ascii} character set). @var{x} must be of an ordered type, which include |
| 7119integral, character and enumerated types. 7120 7121@item SIZE(@var{x}) 7122Returns the size of its argument. @var{x} can be a variable or a type. 7123 7124@item TRUNC(@var{r}) 7125Returns the integral part of @var{r}. 7126 7127@item VAL(@var{t},@var{i}) 7128Returns the member of the type @var{t} whose ordinal value is @var{i}. 7129@end table 7130 7131@quotation 7132@emph{Warning:} Sets and their operations are not yet supported, so 7133@value{GDBN} treats the use of procedures @code{INCL} and @code{EXCL} as 7134an error. 7135@end quotation 7136 7137@cindex Modula-2 constants | 7860integral, character and enumerated types. 7861 7862@item SIZE(@var{x}) 7863Returns the size of its argument. @var{x} can be a variable or a type. 7864 7865@item TRUNC(@var{r}) 7866Returns the integral part of @var{r}. 7867 7868@item VAL(@var{t},@var{i}) 7869Returns the member of the type @var{t} whose ordinal value is @var{i}. 7870@end table 7871 7872@quotation 7873@emph{Warning:} Sets and their operations are not yet supported, so 7874@value{GDBN} treats the use of procedures @code{INCL} and @code{EXCL} as 7875an error. 7876@end quotation 7877 7878@cindex Modula-2 constants |
| 7138@node M2 Constants, M2 Defaults, Built-In Func/Proc, Modula-2 | 7879@node M2 Constants |
| 7139@subsubsection Constants 7140 7141@value{GDBN} allows you to express the constants of Modula-2 in the following 7142ways: 7143 7144@itemize @bullet 7145 7146@item --- 8 unchanged lines hidden (view full) --- 7155then be specified, in the form @samp{E@r{[}+@r{|}-@r{]}@var{nnn}}, where 7156@samp{@r{[}+@r{|}-@r{]}@var{nnn}} is the desired exponent. All of the 7157digits of the floating point constant must be valid decimal (base 10) 7158digits. 7159 7160@item 7161Character constants consist of a single character enclosed by a pair of 7162like quotes, either single (@code{'}) or double (@code{"}). They may | 7880@subsubsection Constants 7881 7882@value{GDBN} allows you to express the constants of Modula-2 in the following 7883ways: 7884 7885@itemize @bullet 7886 7887@item --- 8 unchanged lines hidden (view full) --- 7896then be specified, in the form @samp{E@r{[}+@r{|}-@r{]}@var{nnn}}, where 7897@samp{@r{[}+@r{|}-@r{]}@var{nnn}} is the desired exponent. All of the 7898digits of the floating point constant must be valid decimal (base 10) 7899digits. 7900 7901@item 7902Character constants consist of a single character enclosed by a pair of 7903like quotes, either single (@code{'}) or double (@code{"}). They may |
| 7163also be expressed by their ordinal value (their ASCII value, usually) | 7904also be expressed by their ordinal value (their @sc{ascii} value, usually) |
| 7164followed by a @samp{C}. 7165 7166@item 7167String constants consist of a sequence of characters enclosed by a 7168pair of like quotes, either single (@code{'}) or double (@code{"}). 7169Escape sequences in the style of C are also allowed. @xref{C | 7905followed by a @samp{C}. 7906 7907@item 7908String constants consist of a sequence of characters enclosed by a 7909pair of like quotes, either single (@code{'}) or double (@code{"}). 7910Escape sequences in the style of C are also allowed. @xref{C |
| 7170Constants, ,C and C++ constants}, for a brief explanation of escape | 7911Constants, ,C and C@t{++} constants}, for a brief explanation of escape |
| 7171sequences. 7172 7173@item 7174Enumerated constants consist of an enumerated identifier. 7175 7176@item 7177Boolean constants consist of the identifiers @code{TRUE} and 7178@code{FALSE}. 7179 7180@item 7181Pointer constants consist of integral values only. 7182 7183@item 7184Set constants are not yet supported. 7185@end itemize 7186 | 7912sequences. 7913 7914@item 7915Enumerated constants consist of an enumerated identifier. 7916 7917@item 7918Boolean constants consist of the identifiers @code{TRUE} and 7919@code{FALSE}. 7920 7921@item 7922Pointer constants consist of integral values only. 7923 7924@item 7925Set constants are not yet supported. 7926@end itemize 7927 |
| 7187@node M2 Defaults, Deviations, M2 Constants, Modula-2 | 7928@node M2 Defaults |
| 7188@subsubsection Modula-2 defaults 7189@cindex Modula-2 defaults 7190 7191If type and range checking are set automatically by @value{GDBN}, they 7192both default to @code{on} whenever the working language changes to | 7929@subsubsection Modula-2 defaults 7930@cindex Modula-2 defaults 7931 7932If type and range checking are set automatically by @value{GDBN}, they 7933both default to @code{on} whenever the working language changes to |
| 7193Modula-2. This happens regardless of whether you, or @value{GDBN}, | 7934Modula-2. This happens regardless of whether you or @value{GDBN} |
| 7194selected the working language. 7195 7196If you allow @value{GDBN} to set the language automatically, then entering 7197code compiled from a file whose name ends with @file{.mod} sets the | 7935selected the working language. 7936 7937If you allow @value{GDBN} to set the language automatically, then entering 7938code compiled from a file whose name ends with @file{.mod} sets the |
| 7198working language to Modula-2. @xref{Automatically, ,Having @value{GDBN} set | 7939working language to Modula-2. @xref{Automatically, ,Having @value{GDBN} set |
| 7199the language automatically}, for further details. 7200 | 7940the language automatically}, for further details. 7941 |
| 7201@node Deviations, M2 Checks, M2 Defaults, Modula-2 | 7942@node Deviations |
| 7202@subsubsection Deviations from standard Modula-2 7203@cindex Modula-2, deviations from 7204 7205A few changes have been made to make Modula-2 programs easier to debug. 7206This is done primarily via loosening its type strictness: 7207 7208@itemize @bullet 7209@item --- 13 unchanged lines hidden (view full) --- 7223@item 7224The assignment operator (@code{:=}) returns the value of its right-hand 7225argument. 7226 7227@item 7228All built-in procedures both modify @emph{and} return their argument. 7229@end itemize 7230 | 7943@subsubsection Deviations from standard Modula-2 7944@cindex Modula-2, deviations from 7945 7946A few changes have been made to make Modula-2 programs easier to debug. 7947This is done primarily via loosening its type strictness: 7948 7949@itemize @bullet 7950@item --- 13 unchanged lines hidden (view full) --- 7964@item 7965The assignment operator (@code{:=}) returns the value of its right-hand 7966argument. 7967 7968@item 7969All built-in procedures both modify @emph{and} return their argument. 7970@end itemize 7971 |
| 7231@node M2 Checks, M2 Scope, Deviations, Modula-2 | 7972@node M2 Checks |
| 7232@subsubsection Modula-2 type and range checks 7233@cindex Modula-2 checks 7234 7235@quotation 7236@emph{Warning:} in this release, @value{GDBN} does not yet perform type or 7237range checking. 7238@end quotation 7239@c FIXME remove warning when type/range checks added --- 11 unchanged lines hidden (view full) --- 7251@end itemize 7252 7253As long as type checking is enabled, any attempt to combine variables 7254whose types are not equivalent is an error. 7255 7256Range checking is done on all mathematical operations, assignment, array 7257index bounds, and all built-in functions and procedures. 7258 | 7973@subsubsection Modula-2 type and range checks 7974@cindex Modula-2 checks 7975 7976@quotation 7977@emph{Warning:} in this release, @value{GDBN} does not yet perform type or 7978range checking. 7979@end quotation 7980@c FIXME remove warning when type/range checks added --- 11 unchanged lines hidden (view full) --- 7992@end itemize 7993 7994As long as type checking is enabled, any attempt to combine variables 7995whose types are not equivalent is an error. 7996 7997Range checking is done on all mathematical operations, assignment, array 7998index bounds, and all built-in functions and procedures. 7999 |
| 7259@node M2 Scope, GDB/M2, M2 Checks, Modula-2 | 8000@node M2 Scope |
| 7260@subsubsection The scope operators @code{::} and @code{.} 7261@cindex scope | 8001@subsubsection The scope operators @code{::} and @code{.} 8002@cindex scope |
| 7262@kindex . | 8003@cindex @code{.}, Modula-2 scope operator |
| 7263@cindex colon, doubled as scope operator 7264@ifinfo | 8004@cindex colon, doubled as scope operator 8005@ifinfo |
| 7265@kindex colon-colon | 8006@vindex colon-colon@r{, in Modula-2} |
| 7266@c Info cannot handle :: but TeX can. 7267@end ifinfo 7268@iftex | 8007@c Info cannot handle :: but TeX can. 8008@end ifinfo 8009@iftex |
| 7269@kindex :: | 8010@vindex ::@r{, in Modula-2} |
| 7270@end iftex 7271 7272There are a few subtle differences between the Modula-2 scope operator 7273(@code{.}) and the @value{GDBN} scope operator (@code{::}). The two have 7274similar syntax: 7275 7276@example 7277 --- 13 unchanged lines hidden (view full) --- 7291 7292Using the @code{.} operator makes @value{GDBN} search the current scope for 7293the identifier specified by @var{id} that was imported from the 7294definition module specified by @var{module}. With this operator, it is 7295an error if the identifier @var{id} was not imported from definition 7296module @var{module}, or if @var{id} is not an identifier in 7297@var{module}. 7298 | 8011@end iftex 8012 8013There are a few subtle differences between the Modula-2 scope operator 8014(@code{.}) and the @value{GDBN} scope operator (@code{::}). The two have 8015similar syntax: 8016 8017@example 8018 --- 13 unchanged lines hidden (view full) --- 8032 8033Using the @code{.} operator makes @value{GDBN} search the current scope for 8034the identifier specified by @var{id} that was imported from the 8035definition module specified by @var{module}. With this operator, it is 8036an error if the identifier @var{id} was not imported from definition 8037module @var{module}, or if @var{id} is not an identifier in 8038@var{module}. 8039 |
| 7299@node GDB/M2, , M2 Scope, Modula-2 | 8040@node GDB/M2 |
| 7300@subsubsection @value{GDBN} and Modula-2 7301 7302Some @value{GDBN} commands have little use when debugging Modula-2 programs. 7303Five subcommands of @code{set print} and @code{show print} apply | 8041@subsubsection @value{GDBN} and Modula-2 8042 8043Some @value{GDBN} commands have little use when debugging Modula-2 programs. 8044Five subcommands of @code{set print} and @code{show print} apply |
| 7304specifically to C and C++: @samp{vtbl}, @samp{demangle}, | 8045specifically to C and C@t{++}: @samp{vtbl}, @samp{demangle}, |
| 7305@samp{asm-demangle}, @samp{object}, and @samp{union}. The first four | 8046@samp{asm-demangle}, @samp{object}, and @samp{union}. The first four |
| 7306apply to C++, and the last to the C @code{union} type, which has no direct | 8047apply to C@t{++}, and the last to the C @code{union} type, which has no direct |
| 7307analogue in Modula-2. 7308 7309The @code{@@} operator (@pxref{Expressions, ,Expressions}), while available | 8048analogue in Modula-2. 8049 8050The @code{@@} operator (@pxref{Expressions, ,Expressions}), while available |
| 7310while using any language, is not useful with Modula-2. Its | 8051with any language, is not useful with Modula-2. Its |
| 7311intent is to aid the debugging of @dfn{dynamic arrays}, which cannot be | 8052intent is to aid the debugging of @dfn{dynamic arrays}, which cannot be |
| 7312created in Modula-2 as they can in C or C++. However, because an | 8053created in Modula-2 as they can in C or C@t{++}. However, because an |
| 7313address can be specified by an integral constant, the construct | 8054address can be specified by an integral constant, the construct |
| 7314@samp{@{@var{type}@}@var{adrexp}} is still useful. (@pxref{Expressions, ,Expressions}) | 8055@samp{@{@var{type}@}@var{adrexp}} is still useful. |
| 7315 7316@cindex @code{#} in Modula-2 7317In @value{GDBN} scripts, the Modula-2 inequality operator @code{#} is 7318interpreted as the beginning of a comment. Use @code{<>} instead. | 8056 8057@cindex @code{#} in Modula-2 8058In @value{GDBN} scripts, the Modula-2 inequality operator @code{#} is 8059interpreted as the beginning of a comment. Use @code{<>} instead. |
| 7319@end ifset 7320@end ifclear | |
| 7321 | 8060 |
| 7322@node Symbols, Altering, Languages, Top | 8061@node Chill 8062@subsection Chill 8063 8064The extensions made to @value{GDBN} to support Chill only support output 8065from the @sc{gnu} Chill compiler. Other Chill compilers are not currently 8066supported, and attempting to debug executables produced by them is most 8067likely to give an error as @value{GDBN} reads in the executable's symbol 8068table. 8069 8070@c This used to say "... following Chill related topics ...", but since 8071@c menus are not shown in the printed manual, it would look awkward. 8072This section covers the Chill related topics and the features 8073of @value{GDBN} which support these topics. 8074 8075@menu 8076* How modes are displayed:: How modes are displayed 8077* Locations:: Locations and their accesses 8078* Values and their Operations:: Values and their Operations 8079* Chill type and range checks:: 8080* Chill defaults:: 8081@end menu 8082 8083@node How modes are displayed 8084@subsubsection How modes are displayed 8085 8086The Chill Datatype- (Mode) support of @value{GDBN} is directly related 8087with the functionality of the @sc{gnu} Chill compiler, and therefore deviates 8088slightly from the standard specification of the Chill language. The 8089provided modes are: 8090 8091@c FIXME: this @table's contents effectively disable @code by using @r 8092@c on every @item. So why does it need @code? 8093@table @code 8094@item @r{@emph{Discrete modes:}} 8095@itemize @bullet 8096@item 8097@emph{Integer Modes} which are predefined by @code{BYTE, UBYTE, INT, 8098UINT, LONG, ULONG}, 8099@item 8100@emph{Boolean Mode} which is predefined by @code{BOOL}, 8101@item 8102@emph{Character Mode} which is predefined by @code{CHAR}, 8103@item 8104@emph{Set Mode} which is displayed by the keyword @code{SET}. 8105@smallexample 8106(@value{GDBP}) ptype x 8107type = SET (karli = 10, susi = 20, fritzi = 100) 8108@end smallexample 8109If the type is an unnumbered set the set element values are omitted. 8110@item 8111@emph{Range Mode} which is displayed by 8112@smallexample 8113@code{type = <basemode>(<lower bound> : <upper bound>)} 8114@end smallexample 8115where @code{<lower bound>, <upper bound>} can be of any discrete literal 8116expression (e.g. set element names). 8117@end itemize 8118 8119@item @r{@emph{Powerset Mode:}} 8120A Powerset Mode is displayed by the keyword @code{POWERSET} followed by 8121the member mode of the powerset. The member mode can be any discrete mode. 8122@smallexample 8123(@value{GDBP}) ptype x 8124type = POWERSET SET (egon, hugo, otto) 8125@end smallexample 8126 8127@item @r{@emph{Reference Modes:}} 8128@itemize @bullet 8129@item 8130@emph{Bound Reference Mode} which is displayed by the keyword @code{REF} 8131followed by the mode name to which the reference is bound. 8132@item 8133@emph{Free Reference Mode} which is displayed by the keyword @code{PTR}. 8134@end itemize 8135 8136@item @r{@emph{Procedure mode}} 8137The procedure mode is displayed by @code{type = PROC(<parameter list>) 8138<return mode> EXCEPTIONS (<exception list>)}. The @code{<parameter 8139list>} is a list of the parameter modes. @code{<return mode>} indicates 8140the mode of the result of the procedure if any. The exceptionlist lists 8141all possible exceptions which can be raised by the procedure. 8142 8143@ignore 8144@item @r{@emph{Instance mode}} 8145The instance mode is represented by a structure, which has a static 8146type, and is therefore not really of interest. 8147@end ignore 8148 8149@item @r{@emph{Synchronization Modes:}} 8150@itemize @bullet 8151@item 8152@emph{Event Mode} which is displayed by 8153@smallexample 8154@code{EVENT (<event length>)} 8155@end smallexample 8156where @code{(<event length>)} is optional. 8157@item 8158@emph{Buffer Mode} which is displayed by 8159@smallexample 8160@code{BUFFER (<buffer length>)<buffer element mode>} 8161@end smallexample 8162where @code{(<buffer length>)} is optional. 8163@end itemize 8164 8165@item @r{@emph{Timing Modes:}} 8166@itemize @bullet 8167@item 8168@emph{Duration Mode} which is predefined by @code{DURATION} 8169@item 8170@emph{Absolute Time Mode} which is predefined by @code{TIME} 8171@end itemize 8172 8173@item @r{@emph{Real Modes:}} 8174Real Modes are predefined with @code{REAL} and @code{LONG_REAL}. 8175 8176@item @r{@emph{String Modes:}} 8177@itemize @bullet 8178@item 8179@emph{Character String Mode} which is displayed by 8180@smallexample 8181@code{CHARS(<string length>)} 8182@end smallexample 8183followed by the keyword @code{VARYING} if the String Mode is a varying 8184mode 8185@item 8186@emph{Bit String Mode} which is displayed by 8187@smallexample 8188@code{BOOLS(<string 8189length>)} 8190@end smallexample 8191@end itemize 8192 8193@item @r{@emph{Array Mode:}} 8194The Array Mode is displayed by the keyword @code{ARRAY(<range>)} 8195followed by the element mode (which may in turn be an array mode). 8196@smallexample 8197(@value{GDBP}) ptype x 8198type = ARRAY (1:42) 8199 ARRAY (1:20) 8200 SET (karli = 10, susi = 20, fritzi = 100) 8201@end smallexample 8202 8203@item @r{@emph{Structure Mode}} 8204The Structure mode is displayed by the keyword @code{STRUCT(<field 8205list>)}. The @code{<field list>} consists of names and modes of fields 8206of the structure. Variant structures have the keyword @code{CASE <field> 8207OF <variant fields> ESAC} in their field list. Since the current version 8208of the GNU Chill compiler doesn't implement tag processing (no runtime 8209checks of variant fields, and therefore no debugging info), the output 8210always displays all variant fields. 8211@smallexample 8212(@value{GDBP}) ptype str 8213type = STRUCT ( 8214 as x, 8215 bs x, 8216 CASE bs OF 8217 (karli): 8218 cs a 8219 (ott): 8220 ds x 8221 ESAC 8222) 8223@end smallexample 8224@end table 8225 8226@node Locations 8227@subsubsection Locations and their accesses 8228 8229A location in Chill is an object which can contain values. 8230 8231A value of a location is generally accessed by the (declared) name of 8232the location. The output conforms to the specification of values in 8233Chill programs. How values are specified 8234is the topic of the next section, @ref{Values and their Operations}. 8235 8236The pseudo-location @code{RESULT} (or @code{result}) can be used to 8237display or change the result of a currently-active procedure: 8238 8239@smallexample 8240set result := EXPR 8241@end smallexample 8242 8243@noindent 8244This does the same as the Chill action @code{RESULT EXPR} (which 8245is not available in @value{GDBN}). 8246 8247Values of reference mode locations are printed by @code{PTR(<hex 8248value>)} in case of a free reference mode, and by @code{(REF <reference 8249mode>) (<hex-value>)} in case of a bound reference. @code{<hex value>} 8250represents the address where the reference points to. To access the 8251value of the location referenced by the pointer, use the dereference 8252operator @samp{->}. 8253 8254Values of procedure mode locations are displayed by 8255@smallexample 8256@code{@{ PROC 8257(<argument modes> ) <return mode> @} <address> <name of procedure 8258location>} 8259@end smallexample 8260@code{<argument modes>} is a list of modes according to the parameter 8261specification of the procedure and @code{<address>} shows the address of 8262the entry point. 8263 8264@ignore 8265Locations of instance modes are displayed just like a structure with two 8266fields specifying the @emph{process type} and the @emph{copy number} of 8267the investigated instance location@footnote{This comes from the current 8268implementation of instances. They are implemented as a structure (no 8269na). The output should be something like @code{[<name of the process>; 8270<instance number>]}.}. The field names are @code{__proc_type} and 8271@code{__proc_copy}. 8272 8273Locations of synchronization modes are displayed like a structure with 8274the field name @code{__event_data} in case of a event mode location, and 8275like a structure with the field @code{__buffer_data} in case of a buffer 8276mode location (refer to previous paragraph). 8277 8278Structure Mode locations are printed by @code{[.<field name>: <value>, 8279...]}. The @code{<field name>} corresponds to the structure mode 8280definition and the layout of @code{<value>} varies depending of the mode 8281of the field. If the investigated structure mode location is of variant 8282structure mode, the variant parts of the structure are enclosed in curled 8283braces (@samp{@{@}}). Fields enclosed by @samp{@{,@}} are residing 8284on the same memory location and represent the current values of the 8285memory location in their specific modes. Since no tag processing is done 8286all variants are displayed. A variant field is printed by 8287@code{(<variant name>) = .<field name>: <value>}. (who implements the 8288stuff ???) 8289@smallexample 8290(@value{GDBP}) print str1 $4 = [.as: 0, .bs: karli, .<TAG>: { (karli) = 8291[.cs: []], (susi) = [.ds: susi]}] 8292@end smallexample 8293@end ignore 8294 8295Substructures of string mode-, array mode- or structure mode-values 8296(e.g. array slices, fields of structure locations) are accessed using 8297certain operations which are described in the next section, @ref{Values 8298and their Operations}. 8299 8300A location value may be interpreted as having a different mode using the 8301location conversion. This mode conversion is written as @code{<mode 8302name>(<location>)}. The user has to consider that the sizes of the modes 8303have to be equal otherwise an error occurs. Furthermore, no range 8304checking of the location against the destination mode is performed, and 8305therefore the result can be quite confusing. 8306 8307@smallexample 8308(@value{GDBP}) print int (s(3 up 4)) XXX TO be filled in !! XXX 8309@end smallexample 8310 8311@node Values and their Operations 8312@subsubsection Values and their Operations 8313 8314Values are used to alter locations, to investigate complex structures in 8315more detail or to filter relevant information out of a large amount of 8316data. There are several (mode dependent) operations defined which enable 8317such investigations. These operations are not only applicable to 8318constant values but also to locations, which can become quite useful 8319when debugging complex structures. During parsing the command line 8320(e.g. evaluating an expression) @value{GDBN} treats location names as 8321the values behind these locations. 8322 8323This section describes how values have to be specified and which 8324operations are legal to be used with such values. 8325 8326@table @code 8327@item Literal Values 8328Literal values are specified in the same manner as in @sc{gnu} Chill programs. 8329For detailed specification refer to the @sc{gnu} Chill implementation Manual 8330chapter 1.5. 8331@c FIXME: if the Chill Manual is a Texinfo documents, the above should 8332@c be converted to a @ref. 8333 8334@ignore 8335@itemize @bullet 8336@item 8337@emph{Integer Literals} are specified in the same manner as in Chill 8338programs (refer to the Chill Standard z200/88 chpt 5.2.4.2) 8339@item 8340@emph{Boolean Literals} are defined by @code{TRUE} and @code{FALSE}. 8341@item 8342@emph{Character Literals} are defined by @code{'<character>'}. (e.g. 8343@code{'M'}) 8344@item 8345@emph{Set Literals} are defined by a name which was specified in a set 8346mode. The value delivered by a Set Literal is the set value. This is 8347comparable to an enumeration in C/C@t{++} language. 8348@item 8349@emph{Emptiness Literal} is predefined by @code{NULL}. The value of the 8350emptiness literal delivers either the empty reference value, the empty 8351procedure value or the empty instance value. 8352 8353@item 8354@emph{Character String Literals} are defined by a sequence of characters 8355enclosed in single- or double quotes. If a single- or double quote has 8356to be part of the string literal it has to be stuffed (specified twice). 8357@item 8358@emph{Bitstring Literals} are specified in the same manner as in Chill 8359programs (refer z200/88 chpt 5.2.4.8). 8360@item 8361@emph{Floating point literals} are specified in the same manner as in 8362(gnu-)Chill programs (refer @sc{gnu} Chill implementation Manual chapter 1.5). 8363@end itemize 8364@end ignore 8365 8366@item Tuple Values 8367A tuple is specified by @code{<mode name>[<tuple>]}, where @code{<mode 8368name>} can be omitted if the mode of the tuple is unambiguous. This 8369unambiguity is derived from the context of a evaluated expression. 8370@code{<tuple>} can be one of the following: 8371 8372@itemize @bullet 8373@item @emph{Powerset Tuple} 8374@item @emph{Array Tuple} 8375@item @emph{Structure Tuple} 8376Powerset tuples, array tuples and structure tuples are specified in the 8377same manner as in Chill programs refer to z200/88 chpt 5.2.5. 8378@end itemize 8379 8380@item String Element Value 8381A string element value is specified by 8382@smallexample 8383@code{<string value>(<index>)} 8384@end smallexample 8385where @code{<index>} is a integer expression. It delivers a character 8386value which is equivalent to the character indexed by @code{<index>} in 8387the string. 8388 8389@item String Slice Value 8390A string slice value is specified by @code{<string value>(<slice 8391spec>)}, where @code{<slice spec>} can be either a range of integer 8392expressions or specified by @code{<start expr> up <size>}. 8393@code{<size>} denotes the number of elements which the slice contains. 8394The delivered value is a string value, which is part of the specified 8395string. 8396 8397@item Array Element Values 8398An array element value is specified by @code{<array value>(<expr>)} and 8399delivers a array element value of the mode of the specified array. 8400 8401@item Array Slice Values 8402An array slice is specified by @code{<array value>(<slice spec>)}, where 8403@code{<slice spec>} can be either a range specified by expressions or by 8404@code{<start expr> up <size>}. @code{<size>} denotes the number of 8405arrayelements the slice contains. The delivered value is an array value 8406which is part of the specified array. 8407 8408@item Structure Field Values 8409A structure field value is derived by @code{<structure value>.<field 8410name>}, where @code{<field name>} indicates the name of a field specified 8411in the mode definition of the structure. The mode of the delivered value 8412corresponds to this mode definition in the structure definition. 8413 8414@item Procedure Call Value 8415The procedure call value is derived from the return value of the 8416procedure@footnote{If a procedure call is used for instance in an 8417expression, then this procedure is called with all its side 8418effects. This can lead to confusing results if used carelessly.}. 8419 8420Values of duration mode locations are represented by @code{ULONG} literals. 8421 8422Values of time mode locations appear as 8423@smallexample 8424@code{TIME(<secs>:<nsecs>)} 8425@end smallexample 8426 8427 8428@ignore 8429This is not implemented yet: 8430@item Built-in Value 8431@noindent 8432The following built in functions are provided: 8433 8434@table @code 8435@item @code{ADDR()} 8436@item @code{NUM()} 8437@item @code{PRED()} 8438@item @code{SUCC()} 8439@item @code{ABS()} 8440@item @code{CARD()} 8441@item @code{MAX()} 8442@item @code{MIN()} 8443@item @code{SIZE()} 8444@item @code{UPPER()} 8445@item @code{LOWER()} 8446@item @code{LENGTH()} 8447@item @code{SIN()} 8448@item @code{COS()} 8449@item @code{TAN()} 8450@item @code{ARCSIN()} 8451@item @code{ARCCOS()} 8452@item @code{ARCTAN()} 8453@item @code{EXP()} 8454@item @code{LN()} 8455@item @code{LOG()} 8456@item @code{SQRT()} 8457@end table 8458 8459For a detailed description refer to the GNU Chill implementation manual 8460chapter 1.6. 8461@end ignore 8462 8463@item Zero-adic Operator Value 8464The zero-adic operator value is derived from the instance value for the 8465current active process. 8466 8467@item Expression Values 8468The value delivered by an expression is the result of the evaluation of 8469the specified expression. If there are error conditions (mode 8470incompatibility, etc.) the evaluation of expressions is aborted with a 8471corresponding error message. Expressions may be parenthesised which 8472causes the evaluation of this expression before any other expression 8473which uses the result of the parenthesised expression. The following 8474operators are supported by @value{GDBN}: 8475 8476@table @code 8477@item @code{OR, ORIF, XOR} 8478@itemx @code{AND, ANDIF} 8479@itemx @code{NOT} 8480Logical operators defined over operands of boolean mode. 8481 8482@item @code{=, /=} 8483Equality and inequality operators defined over all modes. 8484 8485@item @code{>, >=} 8486@itemx @code{<, <=} 8487Relational operators defined over predefined modes. 8488 8489@item @code{+, -} 8490@itemx @code{*, /, MOD, REM} 8491Arithmetic operators defined over predefined modes. 8492 8493@item @code{-} 8494Change sign operator. 8495 8496@item @code{//} 8497String concatenation operator. 8498 8499@item @code{()} 8500String repetition operator. 8501 8502@item @code{->} 8503Referenced location operator which can be used either to take the 8504address of a location (@code{->loc}), or to dereference a reference 8505location (@code{loc->}). 8506 8507@item @code{OR, XOR} 8508@itemx @code{AND} 8509@itemx @code{NOT} 8510Powerset and bitstring operators. 8511 8512@item @code{>, >=} 8513@itemx @code{<, <=} 8514Powerset inclusion operators. 8515 8516@item @code{IN} 8517Membership operator. 8518@end table 8519@end table 8520 8521@node Chill type and range checks 8522@subsubsection Chill type and range checks 8523 8524@value{GDBN} considers two Chill variables mode equivalent if the sizes 8525of the two modes are equal. This rule applies recursively to more 8526complex datatypes which means that complex modes are treated 8527equivalent if all element modes (which also can be complex modes like 8528structures, arrays, etc.) have the same size. 8529 8530Range checking is done on all mathematical operations, assignment, array 8531index bounds and all built in procedures. 8532 8533Strong type checks are forced using the @value{GDBN} command @code{set 8534check strong}. This enforces strong type and range checks on all 8535operations where Chill constructs are used (expressions, built in 8536functions, etc.) in respect to the semantics as defined in the z.200 8537language specification. 8538 8539All checks can be disabled by the @value{GDBN} command @code{set check 8540off}. 8541 8542@ignore 8543@c Deviations from the Chill Standard Z200/88 8544see last paragraph ? 8545@end ignore 8546 8547@node Chill defaults 8548@subsubsection Chill defaults 8549 8550If type and range checking are set automatically by @value{GDBN}, they 8551both default to @code{on} whenever the working language changes to 8552Chill. This happens regardless of whether you or @value{GDBN} 8553selected the working language. 8554 8555If you allow @value{GDBN} to set the language automatically, then entering 8556code compiled from a file whose name ends with @file{.ch} sets the 8557working language to Chill. @xref{Automatically, ,Having @value{GDBN} set 8558the language automatically}, for further details. 8559 8560@node Symbols |
| 7323@chapter Examining the Symbol Table 7324 | 8561@chapter Examining the Symbol Table 8562 |
| 7325The commands described in this section allow you to inquire about the | 8563The commands described in this chapter allow you to inquire about the |
| 7326symbols (names of variables, functions and types) defined in your 7327program. This information is inherent in the text of your program and 7328does not change as your program executes. @value{GDBN} finds it in your 7329program's symbol table, in the file indicated when you started @value{GDBN} 7330(@pxref{File Options, ,Choosing files}), or by one of the 7331file-management commands (@pxref{Files, ,Commands to specify files}). 7332 7333@cindex symbol names --- 12 unchanged lines hidden (view full) --- 7346p 'foo.c'::x 7347@end example 7348 7349@noindent 7350looks up the value of @code{x} in the scope of the file @file{foo.c}. 7351 7352@table @code 7353@kindex info address | 8564symbols (names of variables, functions and types) defined in your 8565program. This information is inherent in the text of your program and 8566does not change as your program executes. @value{GDBN} finds it in your 8567program's symbol table, in the file indicated when you started @value{GDBN} 8568(@pxref{File Options, ,Choosing files}), or by one of the 8569file-management commands (@pxref{Files, ,Commands to specify files}). 8570 8571@cindex symbol names --- 12 unchanged lines hidden (view full) --- 8584p 'foo.c'::x 8585@end example 8586 8587@noindent 8588looks up the value of @code{x} in the scope of the file @file{foo.c}. 8589 8590@table @code 8591@kindex info address |
| 8592@cindex address of a symbol |
|
| 7354@item info address @var{symbol} 7355Describe where the data for @var{symbol} is stored. For a register 7356variable, this says which register it is kept in. For a non-register 7357local variable, this prints the stack-frame offset at which the variable 7358is always stored. 7359 7360Note the contrast with @samp{print &@var{symbol}}, which does not work 7361at all for a register variable, and for a stack local variable prints 7362the exact address of the current instantiation of the variable. 7363 | 8593@item info address @var{symbol} 8594Describe where the data for @var{symbol} is stored. For a register 8595variable, this says which register it is kept in. For a non-register 8596local variable, this prints the stack-frame offset at which the variable 8597is always stored. 8598 8599Note the contrast with @samp{print &@var{symbol}}, which does not work 8600at all for a register variable, and for a stack local variable prints 8601the exact address of the current instantiation of the variable. 8602 |
| 8603@kindex info symbol 8604@cindex symbol from address 8605@item info symbol @var{addr} 8606Print the name of a symbol which is stored at the address @var{addr}. 8607If no symbol is stored exactly at @var{addr}, @value{GDBN} prints the 8608nearest symbol and an offset from it: 8609 8610@example 8611(@value{GDBP}) info symbol 0x54320 8612_initialize_vx + 396 in section .text 8613@end example 8614 8615@noindent 8616This is the opposite of the @code{info address} command. You can use 8617it to find out the name of a variable or a function given its address. 8618 |
|
| 7364@kindex whatis | 8619@kindex whatis |
| 7365@item whatis @var{exp} 7366Print the data type of expression @var{exp}. @var{exp} is not | 8620@item whatis @var{expr} 8621Print the data type of expression @var{expr}. @var{expr} is not |
| 7367actually evaluated, and any side-effecting operations (such as 7368assignments or function calls) inside it do not take place. 7369@xref{Expressions, ,Expressions}. 7370 7371@item whatis 7372Print the data type of @code{$}, the last value in the value history. 7373 7374@kindex ptype 7375@item ptype @var{typename} 7376Print a description of data type @var{typename}. @var{typename} may be | 8622actually evaluated, and any side-effecting operations (such as 8623assignments or function calls) inside it do not take place. 8624@xref{Expressions, ,Expressions}. 8625 8626@item whatis 8627Print the data type of @code{$}, the last value in the value history. 8628 8629@kindex ptype 8630@item ptype @var{typename} 8631Print a description of data type @var{typename}. @var{typename} may be |
| 7377the name of a type, or for C code it may have the form 7378@ifclear CONLY 7379@samp{class @var{class-name}}, 7380@end ifclear 7381@samp{struct @var{struct-tag}}, @samp{union @var{union-tag}} or 7382@samp{enum @var{enum-tag}}. | 8632the name of a type, or for C code it may have the form @samp{class 8633@var{class-name}}, @samp{struct @var{struct-tag}}, @samp{union 8634@var{union-tag}} or @samp{enum @var{enum-tag}}. |
| 7383 | 8635 |
| 7384@item ptype @var{exp} | 8636@item ptype @var{expr} |
| 7385@itemx ptype | 8637@itemx ptype |
| 7386Print a description of the type of expression @var{exp}. @code{ptype} | 8638Print a description of the type of expression @var{expr}. @code{ptype} |
| 7387differs from @code{whatis} by printing a detailed description, instead 7388of just the name of the type. 7389 7390For example, for this variable declaration: 7391 7392@example 7393struct complex @{double real; double imag;@} v; 7394@end example --- 15 unchanged lines hidden (view full) --- 7410 7411@noindent 7412As with @code{whatis}, using @code{ptype} without an argument refers to 7413the type of @code{$}, the last value in the value history. 7414 7415@kindex info types 7416@item info types @var{regexp} 7417@itemx info types | 8639differs from @code{whatis} by printing a detailed description, instead 8640of just the name of the type. 8641 8642For example, for this variable declaration: 8643 8644@example 8645struct complex @{double real; double imag;@} v; 8646@end example --- 15 unchanged lines hidden (view full) --- 8662 8663@noindent 8664As with @code{whatis}, using @code{ptype} without an argument refers to 8665the type of @code{$}, the last value in the value history. 8666 8667@kindex info types 8668@item info types @var{regexp} 8669@itemx info types |
| 7418Print a brief description of all types whose name matches @var{regexp} | 8670Print a brief description of all types whose names match @var{regexp} |
| 7419(or all types in your program, if you supply no argument). Each 7420complete typename is matched as though it were a complete line; thus, 7421@samp{i type value} gives information on all types in your program whose | 8671(or all types in your program, if you supply no argument). Each 8672complete typename is matched as though it were a complete line; thus, 8673@samp{i type value} gives information on all types in your program whose |
| 7422name includes the string @code{value}, but @samp{i type ^value$} gives | 8674names include the string @code{value}, but @samp{i type ^value$} gives |
| 7423information only on types whose complete name is @code{value}. 7424 7425This command differs from @code{ptype} in two ways: first, like 7426@code{whatis}, it does not print a detailed description; second, it 7427lists all source files where a type is defined. 7428 | 8675information only on types whose complete name is @code{value}. 8676 8677This command differs from @code{ptype} in two ways: first, like 8678@code{whatis}, it does not print a detailed description; second, it 8679lists all source files where a type is defined. 8680 |
| 8681@kindex info scope 8682@cindex local variables 8683@item info scope @var{addr} 8684List all the variables local to a particular scope. This command 8685accepts a location---a function name, a source line, or an address 8686preceded by a @samp{*}, and prints all the variables local to the 8687scope defined by that location. For example: 8688 8689@smallexample 8690(@value{GDBP}) @b{info scope command_line_handler} 8691Scope for command_line_handler: 8692Symbol rl is an argument at stack/frame offset 8, length 4. 8693Symbol linebuffer is in static storage at address 0x150a18, length 4. 8694Symbol linelength is in static storage at address 0x150a1c, length 4. 8695Symbol p is a local variable in register $esi, length 4. 8696Symbol p1 is a local variable in register $ebx, length 4. 8697Symbol nline is a local variable in register $edx, length 4. 8698Symbol repeat is a local variable at frame offset -8, length 4. 8699@end smallexample 8700 8701@noindent 8702This command is especially useful for determining what data to collect 8703during a @dfn{trace experiment}, see @ref{Tracepoint Actions, 8704collect}. 8705 |
|
| 7429@kindex info source 7430@item info source 7431Show the name of the current source file---that is, the source file for 7432the function containing the current point of execution---and the language 7433it was written in. 7434 7435@kindex info sources 7436@item info sources --- 5 unchanged lines hidden (view full) --- 7442@item info functions 7443Print the names and data types of all defined functions. 7444 7445@item info functions @var{regexp} 7446Print the names and data types of all defined functions 7447whose names contain a match for regular expression @var{regexp}. 7448Thus, @samp{info fun step} finds all functions whose names 7449include @code{step}; @samp{info fun ^step} finds those whose names | 8706@kindex info source 8707@item info source 8708Show the name of the current source file---that is, the source file for 8709the function containing the current point of execution---and the language 8710it was written in. 8711 8712@kindex info sources 8713@item info sources --- 5 unchanged lines hidden (view full) --- 8719@item info functions 8720Print the names and data types of all defined functions. 8721 8722@item info functions @var{regexp} 8723Print the names and data types of all defined functions 8724whose names contain a match for regular expression @var{regexp}. 8725Thus, @samp{info fun step} finds all functions whose names 8726include @code{step}; @samp{info fun ^step} finds those whose names |
| 7450start with @code{step}. | 8727start with @code{step}. If a function name contains characters 8728that conflict with the regular expression language (eg. 8729@samp{operator*()}), they may be quoted with a backslash. |
| 7451 7452@kindex info variables 7453@item info variables 7454Print the names and data types of all variables that are declared | 8730 8731@kindex info variables 8732@item info variables 8733Print the names and data types of all variables that are declared |
| 7455outside of functions (i.e., excluding local variables). | 8734outside of functions (i.e.@: excluding local variables). |
| 7456 7457@item info variables @var{regexp} 7458Print the names and data types of all variables (except for local 7459variables) whose names contain a match for regular expression 7460@var{regexp}. 7461 7462@ignore 7463This was never implemented. 7464@kindex info methods 7465@item info methods 7466@itemx info methods @var{regexp} 7467The @code{info methods} command permits the user to examine all defined | 8735 8736@item info variables @var{regexp} 8737Print the names and data types of all variables (except for local 8738variables) whose names contain a match for regular expression 8739@var{regexp}. 8740 8741@ignore 8742This was never implemented. 8743@kindex info methods 8744@item info methods 8745@itemx info methods @var{regexp} 8746The @code{info methods} command permits the user to examine all defined |
| 7468methods within C++ program, or (with the @var{regexp} argument) a 7469specific set of methods found in the various C++ classes. Many 7470C++ classes provide a large number of methods. Thus, the output | 8747methods within C@t{++} program, or (with the @var{regexp} argument) a 8748specific set of methods found in the various C@t{++} classes. Many 8749C@t{++} classes provide a large number of methods. Thus, the output |
| 7471from the @code{ptype} command can be overwhelming and hard to use. The 7472@code{info-methods} command filters the methods, printing only those 7473which match the regular-expression @var{regexp}. 7474@end ignore 7475 | 8750from the @code{ptype} command can be overwhelming and hard to use. The 8751@code{info-methods} command filters the methods, printing only those 8752which match the regular-expression @var{regexp}. 8753@end ignore 8754 |
| 7476@ifclear HPPA | |
| 7477@cindex reloading symbols 7478Some systems allow individual object files that make up your program to | 8755@cindex reloading symbols 8756Some systems allow individual object files that make up your program to |
| 7479be replaced without stopping and restarting your program. 7480@ifset VXWORKS 7481For example, in VxWorks you can simply recompile a defective object file 7482and keep on running. 7483@end ifset 7484If you are running on one of these systems, you can allow @value{GDBN} to 7485reload the symbols for automatically relinked modules: | 8757be replaced without stopping and restarting your program. For example, 8758in VxWorks you can simply recompile a defective object file and keep on 8759running. If you are running on one of these systems, you can allow 8760@value{GDBN} to reload the symbols for automatically relinked modules: |
| 7486 7487@table @code 7488@kindex set symbol-reloading 7489@item set symbol-reloading on 7490Replace symbol definitions for the corresponding source file when an 7491object file with a particular name is seen again. 7492 7493@item set symbol-reloading off | 8761 8762@table @code 8763@kindex set symbol-reloading 8764@item set symbol-reloading on 8765Replace symbol definitions for the corresponding source file when an 8766object file with a particular name is seen again. 8767 8768@item set symbol-reloading off |
| 7494Do not replace symbol definitions when re-encountering object files of 7495the same name. This is the default state; if you are not running on a 7496system that permits automatically relinking modules, you should leave 7497@code{symbol-reloading} off, since otherwise @value{GDBN} may discard symbols 7498when linking large programs, that may contain several modules (from 7499different directories or libraries) with the same name. | 8769Do not replace symbol definitions when encountering object files of the 8770same name more than once. This is the default state; if you are not 8771running on a system that permits automatic relinking of modules, you 8772should leave @code{symbol-reloading} off, since otherwise @value{GDBN} 8773may discard symbols when linking large programs, that may contain 8774several modules (from different directories or libraries) with the same 8775name. |
| 7500 7501@kindex show symbol-reloading 7502@item show symbol-reloading 7503Show the current @code{on} or @code{off} setting. 7504@end table | 8776 8777@kindex show symbol-reloading 8778@item show symbol-reloading 8779Show the current @code{on} or @code{off} setting. 8780@end table |
| 7505@end ifclear | |
| 7506 | 8781 |
| 7507@ifset HPPA | |
| 7508@kindex set opaque-type-resolution 7509@item set opaque-type-resolution on 7510Tell @value{GDBN} to resolve opaque types. An opaque type is a type 7511declared as a pointer to a @code{struct}, @code{class}, or 7512@code{union}---for example, @code{struct MyType *}---that is used in one 7513source file although the full declaration of @code{struct MyType} is in 7514another source file. The default is on. 7515 --- 5 unchanged lines hidden (view full) --- 7521is printed as follows: 7522@smallexample 7523@{<no data fields>@} 7524@end smallexample 7525 7526@kindex show opaque-type-resolution 7527@item show opaque-type-resolution 7528Show whether opaque types are resolved or not. | 8782@kindex set opaque-type-resolution 8783@item set opaque-type-resolution on 8784Tell @value{GDBN} to resolve opaque types. An opaque type is a type 8785declared as a pointer to a @code{struct}, @code{class}, or 8786@code{union}---for example, @code{struct MyType *}---that is used in one 8787source file although the full declaration of @code{struct MyType} is in 8788another source file. The default is on. 8789 --- 5 unchanged lines hidden (view full) --- 8795is printed as follows: 8796@smallexample 8797@{<no data fields>@} 8798@end smallexample 8799 8800@kindex show opaque-type-resolution 8801@item show opaque-type-resolution 8802Show whether opaque types are resolved or not. |
| 7529@end ifset | |
| 7530 7531@kindex maint print symbols 7532@cindex symbol dump 7533@kindex maint print psymbols 7534@cindex partial symbol dump 7535@item maint print symbols @var{filename} 7536@itemx maint print psymbols @var{filename} 7537@itemx maint print msymbols @var{filename} --- 8 unchanged lines hidden (view full) --- 7546symbols that @value{GDBN} only knows partially---that is, symbols defined in 7547files that @value{GDBN} has skimmed, but not yet read completely. Finally, 7548@samp{maint print msymbols} dumps just the minimal symbol information 7549required for each object file from which @value{GDBN} has read some symbols. 7550@xref{Files, ,Commands to specify files}, for a discussion of how 7551@value{GDBN} reads symbols (in the description of @code{symbol-file}). 7552@end table 7553 | 8803 8804@kindex maint print symbols 8805@cindex symbol dump 8806@kindex maint print psymbols 8807@cindex partial symbol dump 8808@item maint print symbols @var{filename} 8809@itemx maint print psymbols @var{filename} 8810@itemx maint print msymbols @var{filename} --- 8 unchanged lines hidden (view full) --- 8819symbols that @value{GDBN} only knows partially---that is, symbols defined in 8820files that @value{GDBN} has skimmed, but not yet read completely. Finally, 8821@samp{maint print msymbols} dumps just the minimal symbol information 8822required for each object file from which @value{GDBN} has read some symbols. 8823@xref{Files, ,Commands to specify files}, for a discussion of how 8824@value{GDBN} reads symbols (in the description of @code{symbol-file}). 8825@end table 8826 |
| 7554@node Altering, GDB Files, Symbols, Top | 8827@node Altering |
| 7555@chapter Altering Execution 7556 7557Once you think you have found an error in your program, you might want to 7558find out for certain whether correcting the apparent error would lead to 7559correct results in the rest of the run. You can find the answer by 7560experiment, using the @value{GDBN} features for altering execution of the 7561program. 7562 7563For example, you can store new values into variables or memory | 8828@chapter Altering Execution 8829 8830Once you think you have found an error in your program, you might want to 8831find out for certain whether correcting the apparent error would lead to 8832correct results in the rest of the run. You can find the answer by 8833experiment, using the @value{GDBN} features for altering execution of the 8834program. 8835 8836For example, you can store new values into variables or memory |
| 7564locations, 7565@ifclear BARETARGET 7566give your program a signal, restart it 7567@end ifclear 7568@ifset BARETARGET 7569restart your program 7570@end ifset 7571at a different address, or even return prematurely from a function. | 8837locations, give your program a signal, restart it at a different 8838address, or even return prematurely from a function. |
| 7572 7573@menu 7574* Assignment:: Assignment to variables 7575* Jumping:: Continuing at a different address | 8839 8840@menu 8841* Assignment:: Assignment to variables 8842* Jumping:: Continuing at a different address |
| 7576@ifclear BARETARGET | |
| 7577* Signaling:: Giving your program a signal | 8843* Signaling:: Giving your program a signal |
| 7578@end ifclear 7579 | |
| 7580* Returning:: Returning from a function 7581* Calling:: Calling your program's functions 7582* Patching:: Patching your program 7583@end menu 7584 | 8844* Returning:: Returning from a function 8845* Calling:: Calling your program's functions 8846* Patching:: Patching your program 8847@end menu 8848 |
| 7585@node Assignment, Jumping, Altering, Altering | 8849@node Assignment |
| 7586@section Assignment to variables 7587 7588@cindex assignment 7589@cindex setting variables 7590To alter the value of a variable, evaluate an assignment expression. 7591@xref{Expressions, ,Expressions}. For example, 7592 7593@example 7594print x=4 7595@end example 7596 7597@noindent 7598stores the value 4 into the variable @code{x}, and then prints the | 8850@section Assignment to variables 8851 8852@cindex assignment 8853@cindex setting variables 8854To alter the value of a variable, evaluate an assignment expression. 8855@xref{Expressions, ,Expressions}. For example, 8856 8857@example 8858print x=4 8859@end example 8860 8861@noindent 8862stores the value 4 into the variable @code{x}, and then prints the |
| 7599value of the assignment expression (which is 4). 7600@ifclear CONLY | 8863value of the assignment expression (which is 4). |
| 7601@xref{Languages, ,Using @value{GDBN} with Different Languages}, for more 7602information on operators in supported languages. | 8864@xref{Languages, ,Using @value{GDBN} with Different Languages}, for more 8865information on operators in supported languages. |
| 7603@end ifclear | |
| 7604 7605@kindex set variable 7606@cindex variables, setting 7607If you are not interested in seeing the value of the assignment, use the 7608@code{set} command instead of the @code{print} command. @code{set} is 7609really the same as @code{print} except that the expression's value is 7610not printed and is not put in the value history (@pxref{Value History, 7611,Value history}). The expression is evaluated only for its effects. 7612 | 8866 8867@kindex set variable 8868@cindex variables, setting 8869If you are not interested in seeing the value of the assignment, use the 8870@code{set} command instead of the @code{print} command. @code{set} is 8871really the same as @code{print} except that the expression's value is 8872not printed and is not put in the value history (@pxref{Value History, 8873,Value history}). The expression is evaluated only for its effects. 8874 |
| 7613@ifclear HPPA | |
| 7614If the beginning of the argument string of the @code{set} command 7615appears identical to a @code{set} subcommand, use the @code{set 7616variable} command instead of just @code{set}. This command is identical 7617to @code{set} except for its lack of subcommands. For example, if your 7618program has a variable @code{width}, you get an error if you try to set 7619a new value with just @samp{set width=13}, because @value{GDBN} has the 7620command @code{set width}: 7621 --- 8 unchanged lines hidden (view full) --- 7630 7631@noindent 7632The invalid expression, of course, is @samp{=47}. In 7633order to actually set the program's variable @code{width}, use 7634 7635@example 7636(@value{GDBP}) set var width=47 7637@end example | 8875If the beginning of the argument string of the @code{set} command 8876appears identical to a @code{set} subcommand, use the @code{set 8877variable} command instead of just @code{set}. This command is identical 8878to @code{set} except for its lack of subcommands. For example, if your 8879program has a variable @code{width}, you get an error if you try to set 8880a new value with just @samp{set width=13}, because @value{GDBN} has the 8881command @code{set width}: 8882 --- 8 unchanged lines hidden (view full) --- 8891 8892@noindent 8893The invalid expression, of course, is @samp{=47}. In 8894order to actually set the program's variable @code{width}, use 8895 8896@example 8897(@value{GDBP}) set var width=47 8898@end example |
| 7638@end ifclear 7639@ifset HPPA | 8899 |
| 7640Because the @code{set} command has many subcommands that can conflict 7641with the names of program variables, it is a good idea to use the 7642@code{set variable} command instead of just @code{set}. For example, if 7643your program has a variable @code{g}, you run into problems if you try 7644to set a new value with just @samp{set g=4}, because @value{GDBN} has 7645the command @code{set gnutarget}, abbreviated @code{set g}: 7646 7647@example 7648@group 7649(@value{GDBP}) whatis g 7650type = double 7651(@value{GDBP}) p g 7652$1 = 1 7653(@value{GDBP}) set g=4 | 8900Because the @code{set} command has many subcommands that can conflict 8901with the names of program variables, it is a good idea to use the 8902@code{set variable} command instead of just @code{set}. For example, if 8903your program has a variable @code{g}, you run into problems if you try 8904to set a new value with just @samp{set g=4}, because @value{GDBN} has 8905the command @code{set gnutarget}, abbreviated @code{set g}: 8906 8907@example 8908@group 8909(@value{GDBP}) whatis g 8910type = double 8911(@value{GDBP}) p g 8912$1 = 1 8913(@value{GDBP}) set g=4 |
| 7654(gdb) p g | 8914(@value{GDBP}) p g |
| 7655$2 = 1 7656(@value{GDBP}) r 7657The program being debugged has been started already. 7658Start it from the beginning? (y or n) y 7659Starting program: /home/smith/cc_progs/a.out | 8915$2 = 1 8916(@value{GDBP}) r 8917The program being debugged has been started already. 8918Start it from the beginning? (y or n) y 8919Starting program: /home/smith/cc_progs/a.out |
| 7660"/home/smith/cc_progs/a.out": can't open to read symbols: Invalid bfd target. | 8920"/home/smith/cc_progs/a.out": can't open to read symbols: 8921 Invalid bfd target. |
| 7661(@value{GDBP}) show g 7662The current BFD target is "=4". 7663@end group 7664@end example 7665 7666@noindent 7667The program variable @code{g} did not change, and you silently set the 7668@code{gnutarget} to an invalid value. In order to set the variable 7669@code{g}, use 7670 7671@example 7672(@value{GDBP}) set var g=4 7673@end example | 8922(@value{GDBP}) show g 8923The current BFD target is "=4". 8924@end group 8925@end example 8926 8927@noindent 8928The program variable @code{g} did not change, and you silently set the 8929@code{gnutarget} to an invalid value. In order to set the variable 8930@code{g}, use 8931 8932@example 8933(@value{GDBP}) set var g=4 8934@end example |
| 7674@end ifset | |
| 7675 7676@value{GDBN} allows more implicit conversions in assignments than C; you can 7677freely store an integer value into a pointer variable or vice versa, 7678and you can convert any structure to any other structure that is the 7679same length or shorter. 7680@comment FIXME: how do structs align/pad in these conversions? 7681@comment /doc@cygnus.com 18dec1990 7682 --- 5 unchanged lines hidden (view full) --- 7688 7689@example 7690set @{int@}0x83040 = 4 7691@end example 7692 7693@noindent 7694stores the value 4 into that memory location. 7695 | 8935 8936@value{GDBN} allows more implicit conversions in assignments than C; you can 8937freely store an integer value into a pointer variable or vice versa, 8938and you can convert any structure to any other structure that is the 8939same length or shorter. 8940@comment FIXME: how do structs align/pad in these conversions? 8941@comment /doc@cygnus.com 18dec1990 8942 --- 5 unchanged lines hidden (view full) --- 8948 8949@example 8950set @{int@}0x83040 = 4 8951@end example 8952 8953@noindent 8954stores the value 4 into that memory location. 8955 |
| 7696@node Jumping, Signaling, Assignment, Altering | 8956@node Jumping |
| 7697@section Continuing at a different address 7698 7699Ordinarily, when you continue your program, you do so at the place where 7700it stopped, with the @code{continue} command. You can instead continue at 7701an address of your own choosing, with the following commands: 7702 7703@table @code 7704@kindex jump --- 14 unchanged lines hidden (view full) --- 7719confirmation if the specified line is not in the function currently 7720executing. However, even bizarre results are predictable if you are 7721well acquainted with the machine-language code of your program. 7722 7723@item jump *@var{address} 7724Resume execution at the instruction at address @var{address}. 7725@end table 7726 | 8957@section Continuing at a different address 8958 8959Ordinarily, when you continue your program, you do so at the place where 8960it stopped, with the @code{continue} command. You can instead continue at 8961an address of your own choosing, with the following commands: 8962 8963@table @code 8964@kindex jump --- 14 unchanged lines hidden (view full) --- 8979confirmation if the specified line is not in the function currently 8980executing. However, even bizarre results are predictable if you are 8981well acquainted with the machine-language code of your program. 8982 8983@item jump *@var{address} 8984Resume execution at the instruction at address @var{address}. 8985@end table 8986 |
| 7727@ifclear HPPA | |
| 7728@c Doesn't work on HP-UX; have to set $pcoqh and $pcoqt. | 8987@c Doesn't work on HP-UX; have to set $pcoqh and $pcoqt. |
| 7729You can get much the same effect as the @code{jump} command by storing a 7730new value into the register @code{$pc}. The difference is that this 7731does not start your program running; it only changes the address of where it 7732@emph{will} run when you continue. For example, | 8988On many systems, you can get much the same effect as the @code{jump} 8989command by storing a new value into the register @code{$pc}. The 8990difference is that this does not start your program running; it only 8991changes the address of where it @emph{will} run when you continue. For 8992example, |
| 7733 7734@example 7735set $pc = 0x485 7736@end example 7737 7738@noindent 7739makes the next @code{continue} command or stepping command execute at 7740address @code{0x485}, rather than at the address where your program stopped. 7741@xref{Continuing and Stepping, ,Continuing and stepping}. | 8993 8994@example 8995set $pc = 0x485 8996@end example 8997 8998@noindent 8999makes the next @code{continue} command or stepping command execute at 9000address @code{0x485}, rather than at the address where your program stopped. 9001@xref{Continuing and Stepping, ,Continuing and stepping}. |
| 7742@end ifclear | |
| 7743 7744The most common occasion to use the @code{jump} command is to back 7745up---perhaps with more breakpoints set---over a portion of a program 7746that has already executed, in order to examine its execution in more 7747detail. 7748 | 9002 9003The most common occasion to use the @code{jump} command is to back 9004up---perhaps with more breakpoints set---over a portion of a program 9005that has already executed, in order to examine its execution in more 9006detail. 9007 |
| 7749@ifclear BARETARGET | |
| 7750@c @group | 9008@c @group |
| 7751@node Signaling, Returning, Jumping, Altering | 9009@node Signaling |
| 7752@section Giving your program a signal 7753 7754@table @code 7755@kindex signal 7756@item signal @var{signal} 7757Resume execution where your program stopped, but immediately give it the 7758signal @var{signal}. @var{signal} can be the name or the number of a 7759signal. For example, on many systems @code{signal 2} and @code{signal --- 11 unchanged lines hidden (view full) --- 7771@c @end group 7772 7773Invoking the @code{signal} command is not the same as invoking the 7774@code{kill} utility from the shell. Sending a signal with @code{kill} 7775causes @value{GDBN} to decide what to do with the signal depending on 7776the signal handling tables (@pxref{Signals}). The @code{signal} command 7777passes the signal directly to your program. 7778 | 9010@section Giving your program a signal 9011 9012@table @code 9013@kindex signal 9014@item signal @var{signal} 9015Resume execution where your program stopped, but immediately give it the 9016signal @var{signal}. @var{signal} can be the name or the number of a 9017signal. For example, on many systems @code{signal 2} and @code{signal --- 11 unchanged lines hidden (view full) --- 9029@c @end group 9030 9031Invoking the @code{signal} command is not the same as invoking the 9032@code{kill} utility from the shell. Sending a signal with @code{kill} 9033causes @value{GDBN} to decide what to do with the signal depending on 9034the signal handling tables (@pxref{Signals}). The @code{signal} command 9035passes the signal directly to your program. 9036 |
| 7779@end ifclear | |
| 7780 | 9037 |
| 7781@node Returning, Calling, Signaling, Altering | 9038@node Returning |
| 7782@section Returning from a function 7783 7784@table @code 7785@cindex returning from a function 7786@kindex return 7787@item return 7788@itemx return @var{expression} 7789You can cancel execution of a function call with the @code{return} --- 14 unchanged lines hidden (view full) --- 7804of functions. 7805 7806The @code{return} command does not resume execution; it leaves the 7807program stopped in the state that would exist if the function had just 7808returned. In contrast, the @code{finish} command (@pxref{Continuing 7809and Stepping, ,Continuing and stepping}) resumes execution until the 7810selected stack frame returns naturally. 7811 | 9039@section Returning from a function 9040 9041@table @code 9042@cindex returning from a function 9043@kindex return 9044@item return 9045@itemx return @var{expression} 9046You can cancel execution of a function call with the @code{return} --- 14 unchanged lines hidden (view full) --- 9061of functions. 9062 9063The @code{return} command does not resume execution; it leaves the 9064program stopped in the state that would exist if the function had just 9065returned. In contrast, the @code{finish} command (@pxref{Continuing 9066and Stepping, ,Continuing and stepping}) resumes execution until the 9067selected stack frame returns naturally. 9068 |
| 7812@node Calling, Patching, Returning, Altering | 9069@node Calling |
| 7813@section Calling program functions 7814 7815@cindex calling functions 7816@kindex call 7817@table @code 7818@item call @var{expr} 7819Evaluate the expression @var{expr} without displaying @code{void} 7820returned values. 7821@end table 7822 7823You can use this variant of the @code{print} command if you want to 7824execute a function from your program, but without cluttering the output | 9070@section Calling program functions 9071 9072@cindex calling functions 9073@kindex call 9074@table @code 9075@item call @var{expr} 9076Evaluate the expression @var{expr} without displaying @code{void} 9077returned values. 9078@end table 9079 9080You can use this variant of the @code{print} command if you want to 9081execute a function from your program, but without cluttering the output |
| 7825with @code{void} returned values. If the result is not void, it 7826is printed and saved in the value history. | 9082with @code{void} returned values. If the result is not void, it 9083is printed and saved in the value history. |
| 7827 | 9084 |
| 7828@ifclear HPPA 7829For the A29K, a user-controlled variable @code{call_scratch_address}, 7830specifies the location of a scratch area to be used when @value{GDBN} 7831calls a function in the target. This is necessary because the usual 7832method of putting the scratch area on the stack does not work in systems 7833that have separate instruction and data spaces. 7834@end ifclear | 9085@c OBSOLETE For the A29K, a user-controlled variable @code{call_scratch_address}, 9086@c OBSOLETE specifies the location of a scratch area to be used when @value{GDBN} 9087@c OBSOLETE calls a function in the target. This is necessary because the usual 9088@c OBSOLETE method of putting the scratch area on the stack does not work in systems 9089@c OBSOLETE that have separate instruction and data spaces. |
| 7835 | 9090 |
| 7836@node Patching, , Calling, Altering | 9091@node Patching |
| 7837@section Patching programs | 9092@section Patching programs |
| 9093 |
|
| 7838@cindex patching binaries 7839@cindex writing into executables | 9094@cindex patching binaries 9095@cindex writing into executables |
| 7840@ifclear BARETARGET | |
| 7841@cindex writing into corefiles | 9096@cindex writing into corefiles |
| 7842@end ifclear | |
| 7843 | 9097 |
| 7844By default, @value{GDBN} opens the file containing your program's executable 7845code 7846@ifclear BARETARGET 7847(or the corefile) 7848@end ifclear 7849read-only. This prevents accidental alterations 7850to machine code; but it also prevents you from intentionally patching 7851your program's binary. | 9098By default, @value{GDBN} opens the file containing your program's 9099executable code (or the corefile) read-only. This prevents accidental 9100alterations to machine code; but it also prevents you from intentionally 9101patching your program's binary. |
| 7852 7853If you'd like to be able to patch the binary, you can specify that 7854explicitly with the @code{set write} command. For example, you might 7855want to turn on internal debugging flags, or even to make emergency 7856repairs. 7857 7858@table @code 7859@kindex set write 7860@item set write on 7861@itemx set write off | 9102 9103If you'd like to be able to patch the binary, you can specify that 9104explicitly with the @code{set write} command. For example, you might 9105want to turn on internal debugging flags, or even to make emergency 9106repairs. 9107 9108@table @code 9109@kindex set write 9110@item set write on 9111@itemx set write off |
| 7862If you specify @samp{set write on}, @value{GDBN} opens executable 7863@ifclear BARETARGET 7864and core 7865@end ifclear 7866files for both reading and writing; if you specify @samp{set write | 9112If you specify @samp{set write on}, @value{GDBN} opens executable and 9113core files for both reading and writing; if you specify @samp{set write |
| 7867off} (the default), @value{GDBN} opens them read-only. 7868 7869If you have already loaded a file, you must load it again (using the | 9114off} (the default), @value{GDBN} opens them read-only. 9115 9116If you have already loaded a file, you must load it again (using the |
| 7870@code{exec-file} 7871@ifclear BARETARGET 7872or @code{core-file} 7873@end ifclear 7874command) after changing @code{set write}, for your new setting to take 7875effect. | 9117@code{exec-file} or @code{core-file} command) after changing @code{set 9118write}, for your new setting to take effect. |
| 7876 7877@item show write 7878@kindex show write | 9119 9120@item show write 9121@kindex show write |
| 7879Display whether executable files 7880@ifclear BARETARGET 7881and core files 7882@end ifclear 7883are opened for writing as well as reading. | 9122Display whether executable files and core files are opened for writing 9123as well as reading. |
| 7884@end table 7885 | 9124@end table 9125 |
| 7886@node GDB Files, Targets, Altering, Top | 9126@node GDB Files |
| 7887@chapter @value{GDBN} Files 7888 | 9127@chapter @value{GDBN} Files 9128 |
| 7889@value{GDBN} needs to know the file name of the program to be debugged, both in 7890order to read its symbol table and in order to start your program. 7891@ifclear BARETARGET 7892To debug a core dump of a previous run, you must also tell @value{GDBN} 7893the name of the core dump file. 7894@end ifclear | 9129@value{GDBN} needs to know the file name of the program to be debugged, 9130both in order to read its symbol table and in order to start your 9131program. To debug a core dump of a previous run, you must also tell 9132@value{GDBN} the name of the core dump file. |
| 7895 7896@menu 7897* Files:: Commands to specify files 7898* Symbol Errors:: Errors reading symbol files 7899@end menu 7900 | 9133 9134@menu 9135* Files:: Commands to specify files 9136* Symbol Errors:: Errors reading symbol files 9137@end menu 9138 |
| 7901@node Files, Symbol Errors, GDB Files, GDB Files | 9139@node Files |
| 7902@section Commands to specify files | 9140@section Commands to specify files |
| 7903@cindex symbol table | |
| 7904 | 9141 |
| 7905@ifclear BARETARGET | 9142@cindex symbol table |
| 7906@cindex core dump file | 9143@cindex core dump file |
| 7907You may want to specify executable and core dump file names. 7908The usual way to do this is at start-up time, using the arguments to 7909@value{GDBN}'s start-up commands (@pxref{Invocation, , 7910Getting In and Out of @value{GDBN}}). 7911@end ifclear 7912@ifset BARETARGET 7913The usual way to specify an executable file name is with 7914the command argument given when you start @value{GDBN}, (@pxref{Invocation, 7915,Getting In and Out of @value{GDBN}}. 7916@end ifset | |
| 7917 | 9144 |
| 9145You may want to specify executable and core dump file names. The usual 9146way to do this is at start-up time, using the arguments to 9147@value{GDBN}'s start-up commands (@pxref{Invocation, , Getting In and 9148Out of @value{GDBN}}). 9149 |
|
| 7918Occasionally it is necessary to change to a different file during a 7919@value{GDBN} session. Or you may run @value{GDBN} and forget to specify 7920a file you want to use. In these situations the @value{GDBN} commands 7921to specify new files are useful. 7922 7923@table @code 7924@cindex executable file 7925@kindex file 7926@item file @var{filename} 7927Use @var{filename} as the program to be debugged. It is read for its 7928symbols and for the contents of pure memory. It is also the program 7929executed when you use the @code{run} command. If you do not specify a | 9150Occasionally it is necessary to change to a different file during a 9151@value{GDBN} session. Or you may run @value{GDBN} and forget to specify 9152a file you want to use. In these situations the @value{GDBN} commands 9153to specify new files are useful. 9154 9155@table @code 9156@cindex executable file 9157@kindex file 9158@item file @var{filename} 9159Use @var{filename} as the program to be debugged. It is read for its 9160symbols and for the contents of pure memory. It is also the program 9161executed when you use the @code{run} command. If you do not specify a |
| 7930directory and the file is not found in the @value{GDBN} working directory, 7931@value{GDBN} uses the environment variable @code{PATH} as a list of 7932directories to search, just as the shell does when looking for a program 7933to run. You can change the value of this variable, for both @value{GDBN} | 9162directory and the file is not found in the @value{GDBN} working directory, 9163@value{GDBN} uses the environment variable @code{PATH} as a list of 9164directories to search, just as the shell does when looking for a program 9165to run. You can change the value of this variable, for both @value{GDBN} |
| 7934and your program, using the @code{path} command. 7935 | 9166and your program, using the @code{path} command. 9167 |
| 7936@ifclear HPPA 7937On systems with memory-mapped files, an auxiliary file | 9168On systems with memory-mapped files, an auxiliary file named |
| 7938@file{@var{filename}.syms} may hold symbol table information for 7939@var{filename}. If so, @value{GDBN} maps in the symbol table from 7940@file{@var{filename}.syms}, starting up more quickly. See the 7941descriptions of the file options @samp{-mapped} and @samp{-readnow} 7942(available on the command line, and with the commands @code{file}, | 9169@file{@var{filename}.syms} may hold symbol table information for 9170@var{filename}. If so, @value{GDBN} maps in the symbol table from 9171@file{@var{filename}.syms}, starting up more quickly. See the 9172descriptions of the file options @samp{-mapped} and @samp{-readnow} 9173(available on the command line, and with the commands @code{file}, |
| 7943@code{symbol-file}, or @code{add-symbol-file}, described below), | 9174@code{symbol-file}, or @code{add-symbol-file}, described below), |
| 7944for more information. | 9175for more information. |
| 7945@end ifclear | |
| 7946 7947@item file 7948@code{file} with no argument makes @value{GDBN} discard any information it 7949has on both executable file and the symbol table. 7950 7951@kindex exec-file 7952@item exec-file @r{[} @var{filename} @r{]} 7953Specify that the program to be run (but not the symbol table) is found --- 5 unchanged lines hidden (view full) --- 7959@item symbol-file @r{[} @var{filename} @r{]} 7960Read symbol table information from file @var{filename}. @code{PATH} is 7961searched when necessary. Use the @code{file} command to get both symbol 7962table and program to run from the same file. 7963 7964@code{symbol-file} with no argument clears out @value{GDBN} information on your 7965program's symbol table. 7966 | 9176 9177@item file 9178@code{file} with no argument makes @value{GDBN} discard any information it 9179has on both executable file and the symbol table. 9180 9181@kindex exec-file 9182@item exec-file @r{[} @var{filename} @r{]} 9183Specify that the program to be run (but not the symbol table) is found --- 5 unchanged lines hidden (view full) --- 9189@item symbol-file @r{[} @var{filename} @r{]} 9190Read symbol table information from file @var{filename}. @code{PATH} is 9191searched when necessary. Use the @code{file} command to get both symbol 9192table and program to run from the same file. 9193 9194@code{symbol-file} with no argument clears out @value{GDBN} information on your 9195program's symbol table. 9196 |
| 7967The @code{symbol-file} command causes @value{GDBN} to forget the contents | 9197The @code{symbol-file} command causes @value{GDBN} to forget the contents |
| 7968of its convenience variables, the value history, and all breakpoints and 7969auto-display expressions. This is because they may contain pointers to 7970the internal data recording symbols and data types, which are part of 7971the old symbol table data being discarded inside @value{GDBN}. 7972 7973@code{symbol-file} does not repeat if you press @key{RET} again after 7974executing it once. 7975 7976When @value{GDBN} is configured for a particular environment, it 7977understands debugging information in whatever format is the standard 7978generated for that environment; you may use either a @sc{gnu} compiler, or 7979other compilers that adhere to the local conventions. | 9198of its convenience variables, the value history, and all breakpoints and 9199auto-display expressions. This is because they may contain pointers to 9200the internal data recording symbols and data types, which are part of 9201the old symbol table data being discarded inside @value{GDBN}. 9202 9203@code{symbol-file} does not repeat if you press @key{RET} again after 9204executing it once. 9205 9206When @value{GDBN} is configured for a particular environment, it 9207understands debugging information in whatever format is the standard 9208generated for that environment; you may use either a @sc{gnu} compiler, or 9209other compilers that adhere to the local conventions. |
| 7980@ifclear HPPA | |
| 7981Best results are usually obtained from @sc{gnu} compilers; for example, 7982using @code{@value{GCC}} you can generate debugging information for 7983optimized code. | 9210Best results are usually obtained from @sc{gnu} compilers; for example, 9211using @code{@value{GCC}} you can generate debugging information for 9212optimized code. |
| 7984@end ifclear | |
| 7985 7986For most kinds of object files, with the exception of old SVR3 systems 7987using COFF, the @code{symbol-file} command does not normally read the 7988symbol table in full right away. Instead, it scans the symbol table 7989quickly to find which source files and which symbols are present. The 7990details are read later, one source file at a time, as they are needed. 7991 7992The purpose of this two-stage reading strategy is to make @value{GDBN} 7993start up faster. For the most part, it is invisible except for 7994occasional pauses while the symbol table details for a particular source 7995file are being read. (The @code{set verbose} command can turn these 7996pauses into messages if desired. @xref{Messages/Warnings, ,Optional 7997warnings and messages}.) 7998 | 9213 9214For most kinds of object files, with the exception of old SVR3 systems 9215using COFF, the @code{symbol-file} command does not normally read the 9216symbol table in full right away. Instead, it scans the symbol table 9217quickly to find which source files and which symbols are present. The 9218details are read later, one source file at a time, as they are needed. 9219 9220The purpose of this two-stage reading strategy is to make @value{GDBN} 9221start up faster. For the most part, it is invisible except for 9222occasional pauses while the symbol table details for a particular source 9223file are being read. (The @code{set verbose} command can turn these 9224pauses into messages if desired. @xref{Messages/Warnings, ,Optional 9225warnings and messages}.) 9226 |
| 7999@ifclear HPPA | |
| 8000We have not implemented the two-stage strategy for COFF yet. When the 8001symbol table is stored in COFF format, @code{symbol-file} reads the 8002symbol table data in full right away. Note that ``stabs-in-COFF'' 8003still does the two-stage strategy, since the debug info is actually 8004in stabs format. 8005 8006@kindex readnow 8007@cindex reading symbols immediately 8008@cindex symbols, reading immediately 8009@kindex mapped 8010@cindex memory-mapped symbol file 8011@cindex saving symbol table 8012@item symbol-file @var{filename} @r{[} -readnow @r{]} @r{[} -mapped @r{]} 8013@itemx file @var{filename} @r{[} -readnow @r{]} @r{[} -mapped @r{]} 8014You can override the @value{GDBN} two-stage strategy for reading symbol 8015tables by using the @samp{-readnow} option with any of the commands that 8016load symbol table information, if you want to be sure @value{GDBN} has the | 9227We have not implemented the two-stage strategy for COFF yet. When the 9228symbol table is stored in COFF format, @code{symbol-file} reads the 9229symbol table data in full right away. Note that ``stabs-in-COFF'' 9230still does the two-stage strategy, since the debug info is actually 9231in stabs format. 9232 9233@kindex readnow 9234@cindex reading symbols immediately 9235@cindex symbols, reading immediately 9236@kindex mapped 9237@cindex memory-mapped symbol file 9238@cindex saving symbol table 9239@item symbol-file @var{filename} @r{[} -readnow @r{]} @r{[} -mapped @r{]} 9240@itemx file @var{filename} @r{[} -readnow @r{]} @r{[} -mapped @r{]} 9241You can override the @value{GDBN} two-stage strategy for reading symbol 9242tables by using the @samp{-readnow} option with any of the commands that 9243load symbol table information, if you want to be sure @value{GDBN} has the |
| 8017entire symbol table available. 8018@end ifclear | 9244entire symbol table available. |
| 8019 | 9245 |
| 8020@ifclear BARETARGET 8021@ifclear HPPA | |
| 8022If memory-mapped files are available on your system through the 8023@code{mmap} system call, you can use another option, @samp{-mapped}, to 8024cause @value{GDBN} to write the symbols for your program into a reusable 8025file. Future @value{GDBN} debugging sessions map in symbol information 8026from this auxiliary symbol file (if the program has not changed), rather 8027than spending time reading the symbol table from the executable 8028program. Using the @samp{-mapped} option has the same effect as 8029starting @value{GDBN} with the @samp{-mapped} command-line option. --- 5 unchanged lines hidden (view full) --- 8035@samp{@var{myprog}.syms}. Once this file exists (so long as it is newer 8036than the corresponding executable), @value{GDBN} always attempts to use 8037it when you debug @var{myprog}; no special options or commands are 8038needed. 8039 8040The @file{.syms} file is specific to the host machine where you run 8041@value{GDBN}. It holds an exact image of the internal @value{GDBN} 8042symbol table. It cannot be shared across multiple host platforms. | 9246If memory-mapped files are available on your system through the 9247@code{mmap} system call, you can use another option, @samp{-mapped}, to 9248cause @value{GDBN} to write the symbols for your program into a reusable 9249file. Future @value{GDBN} debugging sessions map in symbol information 9250from this auxiliary symbol file (if the program has not changed), rather 9251than spending time reading the symbol table from the executable 9252program. Using the @samp{-mapped} option has the same effect as 9253starting @value{GDBN} with the @samp{-mapped} command-line option. --- 5 unchanged lines hidden (view full) --- 9259@samp{@var{myprog}.syms}. Once this file exists (so long as it is newer 9260than the corresponding executable), @value{GDBN} always attempts to use 9261it when you debug @var{myprog}; no special options or commands are 9262needed. 9263 9264The @file{.syms} file is specific to the host machine where you run 9265@value{GDBN}. It holds an exact image of the internal @value{GDBN} 9266symbol table. It cannot be shared across multiple host platforms. |
| 8043@end ifclear | |
| 8044 8045@c FIXME: for now no mention of directories, since this seems to be in 8046@c flux. 13mar1992 status is that in theory GDB would look either in 8047@c current dir or in same dir as myprog; but issues like competing 8048@c GDB's, or clutter in system dirs, mean that in practice right now 8049@c only current dir is used. FFish says maybe a special GDB hierarchy 8050@c (eg rooted in val of env var GDBSYMS) could exist for mappable symbol 8051@c files. --- 5 unchanged lines hidden (view full) --- 8057of memory''. Traditionally, core files contain only some parts of the 8058address space of the process that generated them; @value{GDBN} can access the 8059executable file itself for other parts. 8060 8061@code{core-file} with no argument specifies that no core file is 8062to be used. 8063 8064Note that the core file is ignored when your program is actually running | 9267 9268@c FIXME: for now no mention of directories, since this seems to be in 9269@c flux. 13mar1992 status is that in theory GDB would look either in 9270@c current dir or in same dir as myprog; but issues like competing 9271@c GDB's, or clutter in system dirs, mean that in practice right now 9272@c only current dir is used. FFish says maybe a special GDB hierarchy 9273@c (eg rooted in val of env var GDBSYMS) could exist for mappable symbol 9274@c files. --- 5 unchanged lines hidden (view full) --- 9280of memory''. Traditionally, core files contain only some parts of the 9281address space of the process that generated them; @value{GDBN} can access the 9282executable file itself for other parts. 9283 9284@code{core-file} with no argument specifies that no core file is 9285to be used. 9286 9287Note that the core file is ignored when your program is actually running |
| 8065under @value{GDBN}. So, if you have been running your program and you wish to 8066debug a core file instead, you must kill the subprocess in which the 8067program is running. To do this, use the @code{kill} command | 9288under @value{GDBN}. So, if you have been running your program and you 9289wish to debug a core file instead, you must kill the subprocess in which 9290the program is running. To do this, use the @code{kill} command |
| 8068(@pxref{Kill Process, ,Killing the child process}). | 9291(@pxref{Kill Process, ,Killing the child process}). |
| 8069@end ifclear | |
| 8070 | 9292 |
| 8071@ifclear BARETARGET 8072@ifclear HPPA | |
| 8073@kindex add-symbol-file 8074@cindex dynamic linking 8075@item add-symbol-file @var{filename} @var{address} 8076@itemx add-symbol-file @var{filename} @var{address} @r{[} -readnow @r{]} @r{[} -mapped @r{]} | 9293@kindex add-symbol-file 9294@cindex dynamic linking 9295@item add-symbol-file @var{filename} @var{address} 9296@itemx add-symbol-file @var{filename} @var{address} @r{[} -readnow @r{]} @r{[} -mapped @r{]} |
| 8077The @code{add-symbol-file} command reads additional symbol table information 8078from the file @var{filename}. You would use this command when @var{filename} 8079has been dynamically loaded (by some other means) into the program that 8080is running. @var{address} should be the memory address at which the 8081file has been loaded; @value{GDBN} cannot figure this out for itself. 8082You can specify @var{address} as an expression. | 9297@itemx add-symbol-file @var{filename} @r{-s}@var{section} @var{address} @dots{} 9298The @code{add-symbol-file} command reads additional symbol table 9299information from the file @var{filename}. You would use this command 9300when @var{filename} has been dynamically loaded (by some other means) 9301into the program that is running. @var{address} should be the memory 9302address at which the file has been loaded; @value{GDBN} cannot figure 9303this out for itself. You can additionally specify an arbitrary number 9304of @samp{@r{-s}@var{section} @var{address}} pairs, to give an explicit 9305section name and base address for that section. You can specify any 9306@var{address} as an expression. |
| 8083 8084The symbol table of the file @var{filename} is added to the symbol table 8085originally read with the @code{symbol-file} command. You can use the | 9307 9308The symbol table of the file @var{filename} is added to the symbol table 9309originally read with the @code{symbol-file} command. You can use the |
| 8086@code{add-symbol-file} command any number of times; the new symbol data thus 8087read keeps adding to the old. To discard all old symbol data instead, 8088use the @code{symbol-file} command. | 9310@code{add-symbol-file} command any number of times; the new symbol data 9311thus read keeps adding to the old. To discard all old symbol data 9312instead, use the @code{symbol-file} command without any arguments. |
| 8089 | 9313 |
| 9314@cindex relocatable object files, reading symbols from 9315@cindex object files, relocatable, reading symbols from 9316@cindex reading symbols from relocatable object files 9317@cindex symbols, reading from relocatable object files 9318@cindex @file{.o} files, reading symbols from 9319Although @var{filename} is typically a shared library file, an 9320executable file, or some other object file which has been fully 9321relocated for loading into a process, you can also load symbolic 9322information from relocatable @file{.o} files, as long as: 9323 9324@itemize @bullet 9325@item 9326the file's symbolic information refers only to linker symbols defined in 9327that file, not to symbols defined by other object files, 9328@item 9329every section the file's symbolic information refers to has actually 9330been loaded into the inferior, as it appears in the file, and 9331@item 9332you can determine the address at which every section was loaded, and 9333provide these to the @code{add-symbol-file} command. 9334@end itemize 9335 9336@noindent 9337Some embedded operating systems, like Sun Chorus and VxWorks, can load 9338relocatable files into an already running program; such systems 9339typically make the requirements above easy to meet. However, it's 9340important to recognize that many native systems use complex link 9341procedures (@code{.linkonce} section factoring and C++ constructor table 9342assembly, for example) that make the requirements difficult to meet. In 9343general, one cannot assume that using @code{add-symbol-file} to read a 9344relocatable object file's symbolic information will have the same effect 9345as linking the relocatable object file into the program in the normal 9346way. 9347 |
|
| 8090@code{add-symbol-file} does not repeat if you press @key{RET} after using it. 8091 8092You can use the @samp{-mapped} and @samp{-readnow} options just as with 8093the @code{symbol-file} command, to change how @value{GDBN} manages the symbol 8094table information for @var{filename}. 8095 8096@kindex add-shared-symbol-file 8097@item add-shared-symbol-file 8098The @code{add-shared-symbol-file} command can be used only under Harris' CXUX | 9348@code{add-symbol-file} does not repeat if you press @key{RET} after using it. 9349 9350You can use the @samp{-mapped} and @samp{-readnow} options just as with 9351the @code{symbol-file} command, to change how @value{GDBN} manages the symbol 9352table information for @var{filename}. 9353 9354@kindex add-shared-symbol-file 9355@item add-shared-symbol-file 9356The @code{add-shared-symbol-file} command can be used only under Harris' CXUX |
| 8099operating system for the Motorola 88k. @value{GDBN} automatically looks for 8100shared libraries, however if @value{GDBN} does not find yours, you can run | 9357operating system for the Motorola 88k. @value{GDBN} automatically looks for 9358shared libraries, however if @value{GDBN} does not find yours, you can run |
| 8101@code{add-shared-symbol-file}. It takes no arguments. | 9359@code{add-shared-symbol-file}. It takes no arguments. |
| 8102@end ifclear 8103@end ifclear | |
| 8104 | 9360 |
| 8105@ifclear HPPA | |
| 8106@kindex section 8107@item section | 9361@kindex section 9362@item section |
| 8108The @code{section} command changes the base address of section SECTION of 8109the exec file to ADDR. This can be used if the exec file does not contain 8110section addresses, (such as in the a.out format), or when the addresses 8111specified in the file itself are wrong. Each section must be changed 8112separately. The ``info files'' command lists all the sections and their 8113addresses. 8114@end ifclear | 9363The @code{section} command changes the base address of section SECTION of 9364the exec file to ADDR. This can be used if the exec file does not contain 9365section addresses, (such as in the a.out format), or when the addresses 9366specified in the file itself are wrong. Each section must be changed 9367separately. The @code{info files} command, described below, lists all 9368the sections and their addresses. |
| 8115 8116@kindex info files 8117@kindex info target 8118@item info files 8119@itemx info target | 9369 9370@kindex info files 9371@kindex info target 9372@item info files 9373@itemx info target |
| 8120@code{info files} and @code{info target} are synonymous; both print 8121the current target (@pxref{Targets, ,Specifying a Debugging Target}), 8122including the 8123@ifclear BARETARGET 8124names of the executable and core dump files 8125@end ifclear 8126@ifset BARETARGET 8127name of the executable file 8128@end ifset 8129currently in use by @value{GDBN}, and the files from which symbols were 8130loaded. The command @code{help target} lists all possible targets 8131rather than current ones. | 9374@code{info files} and @code{info target} are synonymous; both print the 9375current target (@pxref{Targets, ,Specifying a Debugging Target}), 9376including the names of the executable and core dump files currently in 9377use by @value{GDBN}, and the files from which symbols were loaded. The 9378command @code{help target} lists all possible targets rather than 9379current ones. 9380 9381@kindex maint info sections 9382@item maint info sections 9383Another command that can give you extra information about program sections 9384is @code{maint info sections}. In addition to the section information 9385displayed by @code{info files}, this command displays the flags and file 9386offset of each section in the executable and core dump files. In addition, 9387@code{maint info sections} provides the following command options (which 9388may be arbitrarily combined): 9389 9390@table @code 9391@item ALLOBJ 9392Display sections for all loaded object files, including shared libraries. 9393@item @var{sections} 9394Display info only for named @var{sections}. 9395@item @var{section-flags} 9396Display info only for sections for which @var{section-flags} are true. 9397The section flags that @value{GDBN} currently knows about are: 9398@table @code 9399@item ALLOC 9400Section will have space allocated in the process when loaded. 9401Set for all sections except those containing debug information. 9402@item LOAD 9403Section will be loaded from the file into the child process memory. 9404Set for pre-initialized code and data, clear for @code{.bss} sections. 9405@item RELOC 9406Section needs to be relocated before loading. 9407@item READONLY 9408Section cannot be modified by the child process. 9409@item CODE 9410Section contains executable code only. 9411@item DATA 9412Section contains data only (no executable code). 9413@item ROM 9414Section will reside in ROM. 9415@item CONSTRUCTOR 9416Section contains data for constructor/destructor lists. 9417@item HAS_CONTENTS 9418Section is not empty. 9419@item NEVER_LOAD 9420An instruction to the linker to not output the section. 9421@item COFF_SHARED_LIBRARY 9422A notification to the linker that the section contains 9423COFF shared library information. 9424@item IS_COMMON 9425Section contains common symbols. |
| 8132@end table | 9426@end table |
| 9427@end table 9428@kindex set trust-readonly-sections 9429@item set trust-readonly-sections on 9430Tell @value{GDBN} that readonly sections in your object file 9431really are read-only (i.e.@: that their contents will not change). 9432In that case, @value{GDBN} can fetch values from these sections 9433out of the object file, rather than from the target program. 9434For some targets (notably embedded ones), this can be a significant 9435enhancement to debugging performance. |
|
| 8133 | 9436 |
| 9437The default is off. 9438 9439@item set trust-readonly-sections off 9440Tell @value{GDBN} not to trust readonly sections. This means that 9441the contents of the section might change while the program is running, 9442and must therefore be fetched from the target when needed. 9443@end table 9444 |
|
| 8134All file-specifying commands allow both absolute and relative file names 8135as arguments. @value{GDBN} always converts the file name to an absolute file 8136name and remembers it that way. 8137 | 9445All file-specifying commands allow both absolute and relative file names 9446as arguments. @value{GDBN} always converts the file name to an absolute file 9447name and remembers it that way. 9448 |
| 8138@ifclear BARETARGET | |
| 8139@cindex shared libraries | 9449@cindex shared libraries |
| 8140@ifclear HPPA 8141@c added HP-UX -- Kim (HP writer) | |
| 8142@value{GDBN} supports HP-UX, SunOS, SVr4, Irix 5, and IBM RS/6000 shared 8143libraries. | 9450@value{GDBN} supports HP-UX, SunOS, SVr4, Irix 5, and IBM RS/6000 shared 9451libraries. |
| 8144@end ifclear 8145@ifset HPPA 8146@value{GDBN} supports HP-UX shared libraries. 8147@end ifset | 9452 |
| 8148@value{GDBN} automatically loads symbol definitions from shared libraries 8149when you use the @code{run} command, or when you examine a core file. 8150(Before you issue the @code{run} command, @value{GDBN} does not understand 8151references to a function in a shared library, however---unless you are 8152debugging a core file). | 9453@value{GDBN} automatically loads symbol definitions from shared libraries 9454when you use the @code{run} command, or when you examine a core file. 9455(Before you issue the @code{run} command, @value{GDBN} does not understand 9456references to a function in a shared library, however---unless you are 9457debugging a core file). |
| 8153@ifset HPPA 8154If the program loads a library explicitly, @value{GDBN} automatically 8155loads the symbols at the time of the @code{shl_load} call. 8156@end ifset | 9458 9459On HP-UX, if the program loads a library explicitly, @value{GDBN} 9460automatically loads the symbols at the time of the @code{shl_load} call. 9461 |
| 8157@c FIXME: some @value{GDBN} release may permit some refs to undef 8158@c FIXME...symbols---eg in a break cmd---assuming they are from a shared 8159@c FIXME...lib; check this from time to time when updating manual 8160 | 9462@c FIXME: some @value{GDBN} release may permit some refs to undef 9463@c FIXME...symbols---eg in a break cmd---assuming they are from a shared 9464@c FIXME...lib; check this from time to time when updating manual 9465 |
| 9466There are times, however, when you may wish to not automatically load 9467symbol definitions from shared libraries, such as when they are 9468particularly large or there are many of them. 9469 9470To control the automatic loading of shared library symbols, use the 9471commands: 9472 |
|
| 8161@table @code | 9473@table @code |
| 9474@kindex set auto-solib-add 9475@item set auto-solib-add @var{mode} 9476If @var{mode} is @code{on}, symbols from all shared object libraries 9477will be loaded automatically when the inferior begins execution, you 9478attach to an independently started inferior, or when the dynamic linker 9479informs @value{GDBN} that a new library has been loaded. If @var{mode} 9480is @code{off}, symbols must be loaded manually, using the 9481@code{sharedlibrary} command. The default value is @code{on}. 9482 9483@kindex show auto-solib-add 9484@item show auto-solib-add 9485Display the current autoloading mode. 9486@end table 9487 9488To explicitly load shared library symbols, use the @code{sharedlibrary} 9489command: 9490 9491@table @code |
|
| 8162@kindex info sharedlibrary 8163@kindex info share 8164@item info share 8165@itemx info sharedlibrary 8166Print the names of the shared libraries which are currently loaded. 8167 8168@kindex sharedlibrary 8169@kindex share 8170@item sharedlibrary @var{regex} 8171@itemx share @var{regex} | 9492@kindex info sharedlibrary 9493@kindex info share 9494@item info share 9495@itemx info sharedlibrary 9496Print the names of the shared libraries which are currently loaded. 9497 9498@kindex sharedlibrary 9499@kindex share 9500@item sharedlibrary @var{regex} 9501@itemx share @var{regex} |
| 8172 | |
| 8173Load shared object library symbols for files matching a 8174Unix regular expression. 8175As with files loaded automatically, it only loads shared libraries 8176required by your program for a core file or after typing @code{run}. If 8177@var{regex} is omitted all shared libraries required by your program are 8178loaded. 8179@end table 8180 | 9502Load shared object library symbols for files matching a 9503Unix regular expression. 9504As with files loaded automatically, it only loads shared libraries 9505required by your program for a core file or after typing @code{run}. If 9506@var{regex} is omitted all shared libraries required by your program are 9507loaded. 9508@end table 9509 |
| 8181@ifset HPPA 8182@value{GDBN} detects the loading of a shared library and automatically 8183reads in symbols from the newly loaded library, up to a threshold that 8184is initially set but that you can modify if you wish. | 9510On some systems, such as HP-UX systems, @value{GDBN} supports 9511autoloading shared library symbols until a limiting threshold size is 9512reached. This provides the benefit of allowing autoloading to remain on 9513by default, but avoids autoloading excessively large shared libraries, 9514up to a threshold that is initially set, but which you can modify if you 9515wish. |
| 8185 8186Beyond that threshold, symbols from shared libraries must be explicitly | 9516 9517Beyond that threshold, symbols from shared libraries must be explicitly |
| 8187loaded. To load these symbols, use the command @code{sharedlibrary} 8188@var{filename}. The base address of the shared library is determined | 9518loaded. To load these symbols, use the command @code{sharedlibrary 9519@var{filename}}. The base address of the shared library is determined |
| 8189automatically by @value{GDBN} and need not be specified. 8190 8191To display or set the threshold, use the commands: 8192 8193@table @code | 9520automatically by @value{GDBN} and need not be specified. 9521 9522To display or set the threshold, use the commands: 9523 9524@table @code |
| 8194@kindex set auto-solib-add 8195@item set auto-solib-add @var{threshold} 8196Set the autoloading size threshold, in megabytes. If @var{threshold} is 8197nonzero, symbols from all shared object libraries will be loaded 8198automatically when the inferior begins execution or when the dynamic 8199linker informs @value{GDBN} that a new library has been loaded, until 8200the symbol table of the program and libraries exceeds this threshold. | 9525@kindex set auto-solib-limit 9526@item set auto-solib-limit @var{threshold} 9527Set the autoloading size threshold, in an integral number of megabytes. 9528If @var{threshold} is nonzero and shared library autoloading is enabled, 9529symbols from all shared object libraries will be loaded until the total 9530size of the loaded shared library symbols exceeds this threshold. |
| 8201Otherwise, symbols must be loaded manually, using the | 9531Otherwise, symbols must be loaded manually, using the |
| 8202@code{sharedlibrary} command. The default threshold is 100 megabytes. | 9532@code{sharedlibrary} command. The default threshold is 100 (i.e.@: 100 9533Mb). |
| 8203 | 9534 |
| 8204@kindex show auto-solib-add 8205@item show auto-solib-add | 9535@kindex show auto-solib-limit 9536@item show auto-solib-limit |
| 8206Display the current autoloading size threshold, in megabytes. 8207@end table | 9537Display the current autoloading size threshold, in megabytes. 9538@end table |
| 8208@end ifset | |
| 8209 | 9539 |
| 8210@end ifclear 8211 8212@node Symbol Errors, , Files, GDB Files | 9540@node Symbol Errors |
| 8213@section Errors reading symbol files 8214 8215While reading a symbol file, @value{GDBN} occasionally encounters problems, 8216such as symbol types it does not recognize, or known bugs in compiler 8217output. By default, @value{GDBN} does not notify you of such problems, since 8218they are relatively common and primarily of interest to people 8219debugging compilers. If you are interested in seeing information 8220about ill-constructed symbol tables, you can either ask @value{GDBN} to print --- 46 unchanged lines hidden (view full) --- 8267larger than the size of the string table. 8268 8269@value{GDBN} circumvents the problem by considering the symbol to have the 8270name @code{foo}, which may cause other problems if many symbols end up 8271with this name. 8272 8273@item unknown symbol type @code{0x@var{nn}} 8274 | 9541@section Errors reading symbol files 9542 9543While reading a symbol file, @value{GDBN} occasionally encounters problems, 9544such as symbol types it does not recognize, or known bugs in compiler 9545output. By default, @value{GDBN} does not notify you of such problems, since 9546they are relatively common and primarily of interest to people 9547debugging compilers. If you are interested in seeing information 9548about ill-constructed symbol tables, you can either ask @value{GDBN} to print --- 46 unchanged lines hidden (view full) --- 9595larger than the size of the string table. 9596 9597@value{GDBN} circumvents the problem by considering the symbol to have the 9598name @code{foo}, which may cause other problems if many symbols end up 9599with this name. 9600 9601@item unknown symbol type @code{0x@var{nn}} 9602 |
| 8275The symbol information contains new data types that @value{GDBN} does not yet 8276know how to read. @code{0x@var{nn}} is the symbol type of the misunderstood 8277information, in hexadecimal. | 9603The symbol information contains new data types that @value{GDBN} does 9604not yet know how to read. @code{0x@var{nn}} is the symbol type of the 9605uncomprehended information, in hexadecimal. |
| 8278 | 9606 |
| 8279@value{GDBN} circumvents the error by ignoring this symbol information. This 8280usually allows you to debug your program, though certain symbols | 9607@value{GDBN} circumvents the error by ignoring this symbol information. 9608This usually allows you to debug your program, though certain symbols |
| 8281are not accessible. If you encounter such a problem and feel like | 9609are not accessible. If you encounter such a problem and feel like |
| 8282debugging it, you can debug @code{@value{GDBP}} with itself, breakpoint on 8283@code{complain}, then go up to the function @code{read_dbx_symtab} and 8284examine @code{*bufp} to see the symbol. | 9610debugging it, you can debug @code{@value{GDBP}} with itself, breakpoint 9611on @code{complain}, then go up to the function @code{read_dbx_symtab} 9612and examine @code{*bufp} to see the symbol. |
| 8285 8286@item stub type has NULL name | 9613 9614@item stub type has NULL name |
| 8287@value{GDBN} could not find the full definition for 8288@ifclear CONLY 8289a struct or class. 8290@end ifclear 8291@ifset CONLY 8292a struct. 8293@end ifset | |
| 8294 | 9615 |
| 8295@ifclear CONLY | 9616@value{GDBN} could not find the full definition for a struct or class. 9617 |
| 8296@item const/volatile indicator missing (ok if using g++ v1.x), got@dots{} | 9618@item const/volatile indicator missing (ok if using g++ v1.x), got@dots{} |
| 9619The symbol information for a C@t{++} member function is missing some 9620information that recent versions of the compiler should have output for 9621it. |
|
| 8297 | 9622 |
| 8298The symbol information for a C++ member function is missing some 8299information that recent versions of the compiler should have output 8300for it. 8301@end ifclear 8302 | |
| 8303@item info mismatch between compiler and debugger 8304 8305@value{GDBN} could not parse a type specification output by the compiler. | 9623@item info mismatch between compiler and debugger 9624 9625@value{GDBN} could not parse a type specification output by the compiler. |
| 9626 |
|
| 8306@end table 8307 | 9627@end table 9628 |
| 8308@node Targets, Controlling GDB, GDB Files, Top | 9629@node Targets |
| 8309@chapter Specifying a Debugging Target | 9630@chapter Specifying a Debugging Target |
| 9631 |
|
| 8310@cindex debugging target 8311@kindex target 8312 8313A @dfn{target} is the execution environment occupied by your program. | 9632@cindex debugging target 9633@kindex target 9634 9635A @dfn{target} is the execution environment occupied by your program. |
| 8314@ifclear HPPA 8315@ifclear BARETARGET 8316Often, @value{GDBN} runs in the same host environment as your program; in 8317that case, the debugging target is specified as a side effect when you 8318use the @code{file} or @code{core} commands. When you need more | 9636 9637Often, @value{GDBN} runs in the same host environment as your program; 9638in that case, the debugging target is specified as a side effect when 9639you use the @code{file} or @code{core} commands. When you need more |
| 8319flexibility---for example, running @value{GDBN} on a physically separate 8320host, or controlling a standalone system over a serial port or a | 9640flexibility---for example, running @value{GDBN} on a physically separate 9641host, or controlling a standalone system over a serial port or a |
| 8321realtime system over a TCP/IP connection---you 8322@end ifclear 8323@end ifclear 8324@ifset HPPA 8325On HP-UX systems, @value{GDBN} has been configured to support debugging 8326of processes running on the PA-RISC architecture. This means that the 8327only possible targets are: | 9642realtime system over a TCP/IP connection---you can use the @code{target} 9643command to specify one of the target types configured for @value{GDBN} 9644(@pxref{Target Commands, ,Commands for managing targets}). |
| 8328 | 9645 |
| 8329@itemize @bullet 8330@item 8331An executable that has been compiled and linked to run on HP-UX 8332 8333@item 8334A live HP-UX process, either started by @value{GDBN} (with the 8335@code{run} command) or started outside of @value{GDBN} and attached to 8336(with the @code{attach} command) 8337 8338@item 8339A core file generated by an HP-UX process that previously aborted 8340execution 8341@end itemize 8342 8343@value{GDBN} on HP-UX has not been configured to support remote 8344debugging, or to support programs running on other platforms. You 8345@end ifset 8346@ifset BARETARGET 8347You 8348@end ifset 8349can use the @code{target} command to specify one of the target types 8350configured for @value{GDBN} (@pxref{Target Commands, ,Commands for managing 8351targets}). 8352 | |
| 8353@menu 8354* Active Targets:: Active targets 8355* Target Commands:: Commands for managing targets | 9646@menu 9647* Active Targets:: Active targets 9648* Target Commands:: Commands for managing targets |
| 8356@ifset REMOTESTUB | |
| 8357* Byte Order:: Choosing target byte order 8358* Remote:: Remote debugging | 9649* Byte Order:: Choosing target byte order 9650* Remote:: Remote debugging |
| 8359@end ifset | 9651* KOD:: Kernel Object Display |
| 8360 8361@end menu 8362 | 9652 9653@end menu 9654 |
| 8363@node Active Targets, Target Commands, Targets, Targets | 9655@node Active Targets |
| 8364@section Active targets | 9656@section Active targets |
| 9657 |
|
| 8365@cindex stacking targets 8366@cindex active targets 8367@cindex multiple targets 8368 | 9658@cindex stacking targets 9659@cindex active targets 9660@cindex multiple targets 9661 |
| 8369@ifclear BARETARGET | |
| 8370There are three classes of targets: processes, core files, and | 9662There are three classes of targets: processes, core files, and |
| 8371executable files. @value{GDBN} can work concurrently on up to three active 8372targets, one in each class. This allows you to (for example) start a 8373process and inspect its activity without abandoning your work on a core 8374file. | 9663executable files. @value{GDBN} can work concurrently on up to three 9664active targets, one in each class. This allows you to (for example) 9665start a process and inspect its activity without abandoning your work on 9666a core file. |
| 8375 8376For example, if you execute @samp{gdb a.out}, then the executable file 8377@code{a.out} is the only active target. If you designate a core file as 8378well---presumably from a prior run that crashed and coredumped---then 8379@value{GDBN} has two active targets and uses them in tandem, looking 8380first in the corefile target, then in the executable file, to satisfy 8381requests for memory addresses. (Typically, these two classes of target 8382are complementary, since core files contain only a program's 8383read-write memory---variables and so on---plus machine status, while 8384executable files contain only the program text and initialized data.) | 9667 9668For example, if you execute @samp{gdb a.out}, then the executable file 9669@code{a.out} is the only active target. If you designate a core file as 9670well---presumably from a prior run that crashed and coredumped---then 9671@value{GDBN} has two active targets and uses them in tandem, looking 9672first in the corefile target, then in the executable file, to satisfy 9673requests for memory addresses. (Typically, these two classes of target 9674are complementary, since core files contain only a program's 9675read-write memory---variables and so on---plus machine status, while 9676executable files contain only the program text and initialized data.) |
| 8385@end ifclear | |
| 8386 8387When you type @code{run}, your executable file becomes an active process | 9677 9678When you type @code{run}, your executable file becomes an active process |
| 8388target as well. When a process target is active, all @value{GDBN} commands 8389requesting memory addresses refer to that target; addresses in an 8390@ifclear BARETARGET 8391active core file or 8392@end ifclear 8393executable file target are obscured while the process 8394target is active. | 9679target as well. When a process target is active, all @value{GDBN} 9680commands requesting memory addresses refer to that target; addresses in 9681an active core file or executable file target are obscured while the 9682process target is active. |
| 8395 | 9683 |
| 8396@ifset BARETARGET 8397Use the @code{exec-file} command to select a 8398new executable target (@pxref{Files, ,Commands to specify 8399files}). 8400@end ifset 8401@ifclear BARETARGET 8402Use the @code{core-file} and @code{exec-file} commands to select a 8403new core file or executable target (@pxref{Files, ,Commands to specify | 9684Use the @code{core-file} and @code{exec-file} commands to select a new 9685core file or executable target (@pxref{Files, ,Commands to specify |
| 8404files}). To specify as a target a process that is already running, use | 9686files}). To specify as a target a process that is already running, use |
| 8405the @code{attach} command (@pxref{Attach, ,Debugging an 8406already-running process}). 8407@end ifclear | 9687the @code{attach} command (@pxref{Attach, ,Debugging an already-running 9688process}). |
| 8408 | 9689 |
| 8409@node Target Commands, Byte Order, Active Targets, Targets | 9690@node Target Commands |
| 8410@section Commands for managing targets 8411 8412@table @code 8413@item target @var{type} @var{parameters} | 9691@section Commands for managing targets 9692 9693@table @code 9694@item target @var{type} @var{parameters} |
| 8414Connects the @value{GDBN} host environment to a target 8415@ifset BARETARGET 8416machine. 8417@end ifset 8418@ifclear BARETARGET 8419machine or process. A target is typically a protocol for talking to 8420debugging facilities. You use the argument @var{type} to specify the 8421type or protocol of the target machine. | 9695Connects the @value{GDBN} host environment to a target machine or 9696process. A target is typically a protocol for talking to debugging 9697facilities. You use the argument @var{type} to specify the type or 9698protocol of the target machine. |
| 8422 8423Further @var{parameters} are interpreted by the target protocol, but 8424typically include things like device names or host names to connect 8425with, process numbers, and baud rates. | 9699 9700Further @var{parameters} are interpreted by the target protocol, but 9701typically include things like device names or host names to connect 9702with, process numbers, and baud rates. |
| 8426@end ifclear | |
| 8427 8428The @code{target} command does not repeat if you press @key{RET} again 8429after executing the command. 8430 8431@kindex help target 8432@item help target 8433Displays the names of all targets available. To display targets 8434currently selected, use either @code{info target} or @code{info files} 8435(@pxref{Files, ,Commands to specify files}). 8436 8437@item help target @var{name} 8438Describe a particular target, including any parameters necessary to 8439select it. 8440 8441@kindex set gnutarget 8442@item set gnutarget @var{args} | 9703 9704The @code{target} command does not repeat if you press @key{RET} again 9705after executing the command. 9706 9707@kindex help target 9708@item help target 9709Displays the names of all targets available. To display targets 9710currently selected, use either @code{info target} or @code{info files} 9711(@pxref{Files, ,Commands to specify files}). 9712 9713@item help target @var{name} 9714Describe a particular target, including any parameters necessary to 9715select it. 9716 9717@kindex set gnutarget 9718@item set gnutarget @var{args} |
| 8443@value{GDBN} uses its own library BFD to read your files. @value{GDBN} | 9719@value{GDBN} uses its own library BFD to read your files. @value{GDBN} |
| 8444knows whether it is reading an @dfn{executable}, | 9720knows whether it is reading an @dfn{executable}, |
| 8445a @dfn{core}, or a @dfn{.o} file; however, you can specify the file format 8446with the @code{set gnutarget} command. Unlike most @code{target} commands, | 9721a @dfn{core}, or a @dfn{.o} file; however, you can specify the file format 9722with the @code{set gnutarget} command. Unlike most @code{target} commands, |
| 8447with @code{gnutarget} the @code{target} refers to a program, not a machine. 8448 | 9723with @code{gnutarget} the @code{target} refers to a program, not a machine. 9724 |
| 9725@quotation |
|
| 8449@emph{Warning:} To specify a file format with @code{set gnutarget}, 8450you must know the actual BFD name. | 9726@emph{Warning:} To specify a file format with @code{set gnutarget}, 9727you must know the actual BFD name. |
| 9728@end quotation |
|
| 8451 | 9729 |
| 8452@noindent @xref{Files, , Commands to specify files}. | 9730@noindent 9731@xref{Files, , Commands to specify files}. |
| 8453 | 9732 |
| 8454@kindex show gnutarget | 9733@kindex show gnutarget |
| 8455@item show gnutarget 8456Use the @code{show gnutarget} command to display what file format 8457@code{gnutarget} is set to read. If you have not set @code{gnutarget}, 8458@value{GDBN} will determine the file format for each file automatically, 8459and @code{show gnutarget} displays @samp{The current BDF target is "auto"}. 8460@end table 8461 | 9734@item show gnutarget 9735Use the @code{show gnutarget} command to display what file format 9736@code{gnutarget} is set to read. If you have not set @code{gnutarget}, 9737@value{GDBN} will determine the file format for each file automatically, 9738and @code{show gnutarget} displays @samp{The current BDF target is "auto"}. 9739@end table 9740 |
| 8462@ifclear HPPA | |
| 8463Here are some common targets (available, or not, depending on the GDB 8464configuration): | 9741Here are some common targets (available, or not, depending on the GDB 9742configuration): |
| 8465@end ifclear 8466@ifset HPPA 8467These are the valid targets on HP-UX systems: 8468@end ifset | |
| 8469 8470@table @code 8471@kindex target exec 8472@item target exec @var{program} 8473An executable file. @samp{target exec @var{program}} is the same as 8474@samp{exec-file @var{program}}. 8475 | 9743 9744@table @code 9745@kindex target exec 9746@item target exec @var{program} 9747An executable file. @samp{target exec @var{program}} is the same as 9748@samp{exec-file @var{program}}. 9749 |
| 8476@ifclear BARETARGET | |
| 8477@kindex target core 8478@item target core @var{filename} 8479A core dump file. @samp{target core @var{filename}} is the same as 8480@samp{core-file @var{filename}}. | 9750@kindex target core 9751@item target core @var{filename} 9752A core dump file. @samp{target core @var{filename}} is the same as 9753@samp{core-file @var{filename}}. |
| 8481@end ifclear | |
| 8482 8483@kindex target remote 8484@item target remote @var{dev} 8485Remote serial target in GDB-specific protocol. The argument @var{dev} 8486specifies what serial device to use for the connection (e.g. 8487@file{/dev/ttya}). @xref{Remote, ,Remote debugging}. @code{target remote} | 9754 9755@kindex target remote 9756@item target remote @var{dev} 9757Remote serial target in GDB-specific protocol. The argument @var{dev} 9758specifies what serial device to use for the connection (e.g. 9759@file{/dev/ttya}). @xref{Remote, ,Remote debugging}. @code{target remote} |
| 8488now supports the @code{load} command. This is only useful if you have | 9760supports the @code{load} command. This is only useful if you have |
| 8489some other way of getting the stub to the target system, and you can put 8490it somewhere in memory where it won't get clobbered by the download. 8491 | 9761some other way of getting the stub to the target system, and you can put 9762it somewhere in memory where it won't get clobbered by the download. 9763 |
| 8492@ifclear HPPA | |
| 8493@kindex target sim 8494@item target sim | 9764@kindex target sim 9765@item target sim |
| 8495CPU simulator. @xref{Simulator,,Simulated CPU Target}. 8496@end ifclear | 9766Builtin CPU simulator. @value{GDBN} includes simulators for most architectures. 9767In general, 9768@example 9769 target sim 9770 load 9771 run 9772@end example 9773@noindent 9774works; however, you cannot assume that a specific memory map, device 9775drivers, or even basic I/O is available, although some simulators do 9776provide these. For info about any processor-specific simulator details, 9777see the appropriate section in @ref{Embedded Processors, ,Embedded 9778Processors}. 9779 |
| 8497@end table 8498 | 9780@end table 9781 |
| 8499The following targets are all CPU-specific, and only available for 8500specific configurations. 8501@c should organize by CPU | 9782Some configurations may include these targets as well: |
| 8502 8503@table @code 8504 | 9783 9784@table @code 9785 |
| 8505@kindex target abug 8506@item target abug @var{dev} 8507ABug ROM monitor for M68K. 8508 8509@kindex target adapt 8510@item target adapt @var{dev} 8511Adapt monitor for A29K. 8512 8513@kindex target amd-eb 8514@item target amd-eb @var{dev} @var{speed} @var{PROG} 8515@cindex AMD EB29K 8516Remote PC-resident AMD EB29K board, attached over serial lines. 8517@var{dev} is the serial device, as for @code{target remote}; 8518@var{speed} allows you to specify the linespeed; and @var{PROG} is the 8519name of the program to be debugged, as it appears to DOS on the PC. 8520@xref{EB29K Remote, ,The EBMON protocol for AMD29K}. 8521 8522@kindex target array 8523@item target array @var{dev} 8524Array Tech LSI33K RAID controller board. 8525 8526@kindex target bug 8527@item target bug @var{dev} 8528BUG monitor, running on a MVME187 (m88k) board. 8529 8530@kindex target cpu32bug 8531@item target cpu32bug @var{dev} 8532CPU32BUG monitor, running on a CPU32 (M68K) board. 8533 8534@kindex target dbug 8535@item target dbug @var{dev} 8536dBUG ROM monitor for Motorola ColdFire. 8537 8538@kindex target ddb 8539@item target ddb @var{dev} 8540NEC's DDB monitor for Mips Vr4300. 8541 8542@kindex target dink32 8543@item target dink32 @var{dev} 8544DINK32 ROM monitor for PowerPC. 8545 8546@kindex target e7000 8547@item target e7000 @var{dev} 8548E7000 emulator for Hitachi H8 and SH. 8549 8550@kindex target es1800 8551@item target es1800 @var{dev} 8552ES-1800 emulator for M68K. 8553 8554@kindex target est 8555@item target est @var{dev} 8556EST-300 ICE monitor, running on a CPU32 (M68K) board. 8557 8558@kindex target hms 8559@item target hms @var{dev} 8560A Hitachi SH, H8/300, or H8/500 board, attached via serial line to your host. 8561@ifclear H8EXCLUSIVE 8562Use special commands @code{device} and @code{speed} to control the serial 8563line and the communications speed used. 8564@xref{Hitachi Remote,,@value{GDBN} and Hitachi Microprocessors}. 8565 8566@kindex target lsi 8567@item target lsi @var{dev} 8568LSI ROM monitor for Mips. 8569 8570@kindex target m32r 8571@item target m32r @var{dev} 8572Mitsubishi M32R/D ROM monitor. 8573 8574@kindex target mips 8575@item target mips @var{dev} 8576IDT/SIM ROM monitor for Mips. 8577 8578@kindex target mon960 8579@item target mon960 @var{dev} 8580MON960 monitor for Intel i960. 8581 8582@kindex target nindy 8583@item target nindy @var{devicename} 8584An Intel 960 board controlled by a Nindy Monitor. @var{devicename} is 8585the name of the serial device to use for the connection, e.g. 8586@file{/dev/ttya}. @xref{i960-Nindy Remote, ,@value{GDBN} with a remote i960 (Nindy)}. 8587 | |
| 8588@kindex target nrom 8589@item target nrom @var{dev} 8590NetROM ROM emulator. This target only supports downloading. 8591 | 9786@kindex target nrom 9787@item target nrom @var{dev} 9788NetROM ROM emulator. This target only supports downloading. 9789 |
| 8592@kindex target op50n 8593@item target op50n @var{dev} 8594OP50N monitor, running on an OKI HPPA board. 8595 8596@kindex target pmon 8597@item target pmon @var{dev} 8598PMON ROM monitor for Mips. 8599 8600@kindex target ppcbug 8601@item target ppcbug @var{dev} 8602@kindex target ppcbug1 8603@item target ppcbug1 @var{dev} 8604PPCBUG ROM monitor for PowerPC. 8605 8606@kindex target r3900 8607@item target r3900 @var{dev} 8608Densan DVE-R3900 ROM monitor for Toshiba R3900 Mips. 8609 8610@kindex target rdi 8611@item target rdi @var{dev} 8612ARM Angel monitor, via RDI library interface. 8613 8614@kindex target rdp 8615@item target rdp @var{dev} 8616ARM Demon monitor. 8617 8618@kindex target rom68k 8619@item target rom68k @var{dev} 8620ROM 68K monitor, running on an M68K IDP board. 8621 8622@kindex target rombug 8623@item target rombug @var{dev} 8624ROMBUG ROM monitor for OS/9000. 8625 8626@kindex target sds 8627@item target sds @var{dev} 8628SDS monitor, running on a PowerPC board (such as Motorola's ADS). 8629 8630@kindex target sparclite 8631@item target sparclite @var{dev} 8632Fujitsu sparclite boards, used only for the purpose of loading. 8633You must use an additional command to debug the program. 8634For example: target remote @var{dev} using @value{GDBN} standard 8635remote protocol. 8636 8637@kindex target sh3 8638@kindex target sh3e 8639@item target sh3 @var{dev} 8640@item target sh3e @var{dev} 8641Hitachi SH-3 and SH-3E target systems. 8642 8643@kindex target st2000 8644@item target st2000 @var{dev} @var{speed} 8645A Tandem ST2000 phone switch, running Tandem's STDBUG protocol. @var{dev} 8646is the name of the device attached to the ST2000 serial line; 8647@var{speed} is the communication line speed. The arguments are not used 8648if @value{GDBN} is configured to connect to the ST2000 using TCP or Telnet. 8649@xref{ST2000 Remote,,@value{GDBN} with a Tandem ST2000}. 8650 8651@kindex target udi 8652@item target udi @var{keyword} 8653Remote AMD29K target, using the AMD UDI protocol. The @var{keyword} 8654argument specifies which 29K board or simulator to use. @xref{UDI29K 8655Remote,,The UDI protocol for AMD29K}. 8656 8657@kindex target vxworks 8658@item target vxworks @var{machinename} 8659A VxWorks system, attached via TCP/IP. The argument @var{machinename} 8660is the target system's machine name or IP address. 8661@xref{VxWorks Remote, ,@value{GDBN} and VxWorks}. 8662 8663@kindex target w89k 8664@item target w89k @var{dev} 8665W89K monitor, running on a Winbond HPPA board. 8666 8667@end ifclear | |
| 8668@end table 8669 | 9790@end table 9791 |
| 8670@ifset GENERIC 8671Different targets are available on different configurations of @value{GDBN}; | 9792Different targets are available on different configurations of @value{GDBN}; |
| 8672your configuration may have more or fewer targets. | 9793your configuration may have more or fewer targets. |
| 8673@end ifset | |
| 8674 8675Many remote targets require you to download the executable's code 8676once you've successfully established a connection. 8677 8678@table @code 8679 8680@kindex load @var{filename} 8681@item load @var{filename} | 9794 9795Many remote targets require you to download the executable's code 9796once you've successfully established a connection. 9797 9798@table @code 9799 9800@kindex load @var{filename} 9801@item load @var{filename} |
| 8682@ifset GENERIC | |
| 8683Depending on what remote debugging facilities are configured into 8684@value{GDBN}, the @code{load} command may be available. Where it exists, it 8685is meant to make @var{filename} (an executable) available for debugging 8686on the remote system---by downloading, or dynamic linking, for example. 8687@code{load} also records the @var{filename} symbol table in @value{GDBN}, like 8688the @code{add-symbol-file} command. 8689 8690If your @value{GDBN} does not have a @code{load} command, attempting to 8691execute it gets the error message ``@code{You can't do that when your 8692target is @dots{}}'' | 9802Depending on what remote debugging facilities are configured into 9803@value{GDBN}, the @code{load} command may be available. Where it exists, it 9804is meant to make @var{filename} (an executable) available for debugging 9805on the remote system---by downloading, or dynamic linking, for example. 9806@code{load} also records the @var{filename} symbol table in @value{GDBN}, like 9807the @code{add-symbol-file} command. 9808 9809If your @value{GDBN} does not have a @code{load} command, attempting to 9810execute it gets the error message ``@code{You can't do that when your 9811target is @dots{}}'' |
| 8693@end ifset | |
| 8694 8695The file is loaded at whatever address is specified in the executable. 8696For some object file formats, you can specify the load address when you 8697link the program; for other formats, like a.out, the object file format 8698specifies a fixed address. 8699@c FIXME! This would be a good place for an xref to the GNU linker doc. 8700 | 9812 9813The file is loaded at whatever address is specified in the executable. 9814For some object file formats, you can specify the load address when you 9815link the program; for other formats, like a.out, the object file format 9816specifies a fixed address. 9817@c FIXME! This would be a good place for an xref to the GNU linker doc. 9818 |
| 8701@ifset VXWORKS 8702On VxWorks, @code{load} links @var{filename} dynamically on the 8703current target system as well as adding its symbols in @value{GDBN}. 8704@end ifset 8705 8706@ifset I960 8707@cindex download to Nindy-960 8708With the Nindy interface to an Intel 960 board, @code{load} 8709downloads @var{filename} to the 960 as well as adding its symbols in 8710@value{GDBN}. 8711@end ifset 8712 8713@ifset H8 8714@cindex download to H8/300 or H8/500 8715@cindex H8/300 or H8/500 download 8716@cindex download to Hitachi SH 8717@cindex Hitachi SH download 8718When you select remote debugging to a Hitachi SH, H8/300, or H8/500 board 8719(@pxref{Hitachi Remote,,@value{GDBN} and Hitachi Microprocessors}), 8720the @code{load} command downloads your program to the Hitachi board and also 8721opens it as the current executable target for @value{GDBN} on your host 8722(like the @code{file} command). 8723@end ifset 8724 | |
| 8725@code{load} does not repeat if you press @key{RET} again after using it. 8726@end table 8727 | 9819@code{load} does not repeat if you press @key{RET} again after using it. 9820@end table 9821 |
| 8728@ifset REMOTESTUB 8729@node Byte Order, Remote, Target Commands, Targets | 9822@node Byte Order |
| 8730@section Choosing target byte order | 9823@section Choosing target byte order |
| 9824 |
|
| 8731@cindex choosing target byte order 8732@cindex target byte order | 9825@cindex choosing target byte order 9826@cindex target byte order |
| 8733@kindex set endian big 8734@kindex set endian little 8735@kindex set endian auto 8736@kindex show endian | |
| 8737 8738Some types of processors, such as the MIPS, PowerPC, and Hitachi SH, 8739offer the ability to run either big-endian or little-endian byte 8740orders. Usually the executable or symbol will include a bit to 8741designate the endian-ness, and you will not need to worry about 8742which to use. However, you may still find it useful to adjust | 9827 9828Some types of processors, such as the MIPS, PowerPC, and Hitachi SH, 9829offer the ability to run either big-endian or little-endian byte 9830orders. Usually the executable or symbol will include a bit to 9831designate the endian-ness, and you will not need to worry about 9832which to use. However, you may still find it useful to adjust |
| 8743GDB's idea of processor endian-ness manually. | 9833@value{GDBN}'s idea of processor endian-ness manually. |
| 8744 8745@table @code 8746@kindex set endian big 8747@item set endian big 8748Instruct @value{GDBN} to assume the target is big-endian. 8749 8750@kindex set endian little 8751@item set endian little --- 8 unchanged lines hidden (view full) --- 8760Display @value{GDBN}'s current idea of the target byte order. 8761 8762@end table 8763 8764Note that these commands merely adjust interpretation of symbolic 8765data on the host, and that they have absolutely no effect on the 8766target system. 8767 | 9834 9835@table @code 9836@kindex set endian big 9837@item set endian big 9838Instruct @value{GDBN} to assume the target is big-endian. 9839 9840@kindex set endian little 9841@item set endian little --- 8 unchanged lines hidden (view full) --- 9850Display @value{GDBN}'s current idea of the target byte order. 9851 9852@end table 9853 9854Note that these commands merely adjust interpretation of symbolic 9855data on the host, and that they have absolutely no effect on the 9856target system. 9857 |
| 8768@node Remote, , Byte Order, Targets | 9858@node Remote |
| 8769@section Remote debugging 8770@cindex remote debugging 8771 8772If you are trying to debug a program running on a machine that cannot run | 9859@section Remote debugging 9860@cindex remote debugging 9861 9862If you are trying to debug a program running on a machine that cannot run |
| 8773@value{GDBN} in the usual way, it is often useful to use remote debugging. 8774For example, you might use remote debugging on an operating system kernel, | 9863@value{GDBN} in the usual way, it is often useful to use remote debugging. 9864For example, you might use remote debugging on an operating system kernel, |
| 8775or on a small system which does not have a general purpose operating system 8776powerful enough to run a full-featured debugger. 8777 8778Some configurations of @value{GDBN} have special serial or TCP/IP interfaces 8779to make this work with particular debugging targets. In addition, | 9865or on a small system which does not have a general purpose operating system 9866powerful enough to run a full-featured debugger. 9867 9868Some configurations of @value{GDBN} have special serial or TCP/IP interfaces 9869to make this work with particular debugging targets. In addition, |
| 8780@value{GDBN} comes with a generic serial protocol (specific to @value{GDBN}, | 9870@value{GDBN} comes with a generic serial protocol (specific to @value{GDBN}, |
| 8781but not specific to any particular target system) which you can use if you 8782write the remote stubs---the code that runs on the remote system to 8783communicate with @value{GDBN}. 8784 8785Other remote targets may be available in your 8786configuration of @value{GDBN}; use @code{help target} to list them. | 9871but not specific to any particular target system) which you can use if you 9872write the remote stubs---the code that runs on the remote system to 9873communicate with @value{GDBN}. 9874 9875Other remote targets may be available in your 9876configuration of @value{GDBN}; use @code{help target} to list them. |
| 8787@end ifset | |
| 8788 | 9877 |
| 8789@ifset GENERIC 8790@c Text on starting up GDB in various specific cases; it goes up front 8791@c in manuals configured for any of those particular situations, here 8792@c otherwise. | 9878@node KOD 9879@section Kernel Object Display 9880 9881@cindex kernel object display 9882@cindex kernel object 9883@cindex KOD 9884 9885Some targets support kernel object display. Using this facility, 9886@value{GDBN} communicates specially with the underlying operating system 9887and can display information about operating system-level objects such as 9888mutexes and other synchronization objects. Exactly which objects can be 9889displayed is determined on a per-OS basis. 9890 9891Use the @code{set os} command to set the operating system. This tells 9892@value{GDBN} which kernel object display module to initialize: 9893 9894@example 9895(@value{GDBP}) set os cisco 9896@end example 9897 9898If @code{set os} succeeds, @value{GDBN} will display some information 9899about the operating system, and will create a new @code{info} command 9900which can be used to query the target. The @code{info} command is named 9901after the operating system: 9902 9903@example 9904(@value{GDBP}) info cisco 9905List of Cisco Kernel Objects 9906Object Description 9907any Any and all objects 9908@end example 9909 9910Further subcommands can be used to query about particular objects known 9911by the kernel. 9912 9913There is currently no way to determine whether a given operating system 9914is supported other than to try it. 9915 9916 9917@node Remote Debugging 9918@chapter Debugging remote programs 9919 |
| 8793@menu | 9920@menu |
| 8794@ifset REMOTESTUB 8795* Remote Serial:: @value{GDBN} remote serial protocol 8796@end ifset 8797@ifset I960 8798* i960-Nindy Remote:: @value{GDBN} with a remote i960 (Nindy) 8799@end ifset 8800@ifset AMD29K 8801* UDI29K Remote:: The UDI protocol for AMD29K 8802* EB29K Remote:: The EBMON protocol for AMD29K 8803@end ifset 8804@ifset VXWORKS 8805* VxWorks Remote:: @value{GDBN} and VxWorks 8806@end ifset 8807@ifset ST2000 8808* ST2000 Remote:: @value{GDBN} with a Tandem ST2000 8809@end ifset 8810@ifset H8 8811* Hitachi Remote:: @value{GDBN} and Hitachi Microprocessors 8812@end ifset 8813@ifset MIPS 8814* MIPS Remote:: @value{GDBN} and MIPS boards 8815@end ifset 8816@ifset SPARCLET 8817* Sparclet Remote:: @value{GDBN} and Sparclet boards 8818@end ifset 8819@ifset SIMS 8820* Simulator:: Simulated CPU target 8821@end ifset | 9921* Server:: Using the gdbserver program 9922* NetWare:: Using the gdbserve.nlm program 9923* remote stub:: Implementing a remote stub |
| 8822@end menu 8823 | 9924@end menu 9925 |
| 8824@include remote.texi 8825@end ifset | 9926@node Server 9927@section Using the @code{gdbserver} program |
| 8826 | 9928 |
| 9929@kindex gdbserver 9930@cindex remote connection without stubs 9931@code{gdbserver} is a control program for Unix-like systems, which 9932allows you to connect your program with a remote @value{GDBN} via 9933@code{target remote}---but without linking in the usual debugging stub. 9934 9935@code{gdbserver} is not a complete replacement for the debugging stubs, 9936because it requires essentially the same operating-system facilities 9937that @value{GDBN} itself does. In fact, a system that can run 9938@code{gdbserver} to connect to a remote @value{GDBN} could also run 9939@value{GDBN} locally! @code{gdbserver} is sometimes useful nevertheless, 9940because it is a much smaller program than @value{GDBN} itself. It is 9941also easier to port than all of @value{GDBN}, so you may be able to get 9942started more quickly on a new system by using @code{gdbserver}. 9943Finally, if you develop code for real-time systems, you may find that 9944the tradeoffs involved in real-time operation make it more convenient to 9945do as much development work as possible on another system, for example 9946by cross-compiling. You can use @code{gdbserver} to make a similar 9947choice for debugging. 9948 9949@value{GDBN} and @code{gdbserver} communicate via either a serial line 9950or a TCP connection, using the standard @value{GDBN} remote serial 9951protocol. 9952 9953@table @emph 9954@item On the target machine, 9955you need to have a copy of the program you want to debug. 9956@code{gdbserver} does not need your program's symbol table, so you can 9957strip the program if necessary to save space. @value{GDBN} on the host 9958system does all the symbol handling. 9959 9960To use the server, you must tell it how to communicate with @value{GDBN}; 9961the name of your program; and the arguments for your program. The usual 9962syntax is: 9963 9964@smallexample 9965target> gdbserver @var{comm} @var{program} [ @var{args} @dots{} ] 9966@end smallexample 9967 9968@var{comm} is either a device name (to use a serial line) or a TCP 9969hostname and portnumber. For example, to debug Emacs with the argument 9970@samp{foo.txt} and communicate with @value{GDBN} over the serial port 9971@file{/dev/com1}: 9972 9973@smallexample 9974target> gdbserver /dev/com1 emacs foo.txt 9975@end smallexample 9976 9977@code{gdbserver} waits passively for the host @value{GDBN} to communicate 9978with it. 9979 9980To use a TCP connection instead of a serial line: 9981 9982@smallexample 9983target> gdbserver host:2345 emacs foo.txt 9984@end smallexample 9985 9986The only difference from the previous example is the first argument, 9987specifying that you are communicating with the host @value{GDBN} via 9988TCP. The @samp{host:2345} argument means that @code{gdbserver} is to 9989expect a TCP connection from machine @samp{host} to local TCP port 2345. 9990(Currently, the @samp{host} part is ignored.) You can choose any number 9991you want for the port number as long as it does not conflict with any 9992TCP ports already in use on the target system (for example, @code{23} is 9993reserved for @code{telnet}).@footnote{If you choose a port number that 9994conflicts with another service, @code{gdbserver} prints an error message 9995and exits.} You must use the same port number with the host @value{GDBN} 9996@code{target remote} command. 9997 9998On some targets, @code{gdbserver} can also attach to running programs. 9999This is accomplished via the @code{--attach} argument. The syntax is: 10000 10001@smallexample 10002target> gdbserver @var{comm} --attach @var{pid} 10003@end smallexample 10004 10005@var{pid} is the process ID of a currently running process. It isn't necessary 10006to point @code{gdbserver} at a binary for the running process. 10007 10008@item On the @value{GDBN} host machine, 10009you need an unstripped copy of your program, since @value{GDBN} needs 10010symbols and debugging information. Start up @value{GDBN} as usual, 10011using the name of the local copy of your program as the first argument. 10012(You may also need the @w{@samp{--baud}} option if the serial line is 10013running at anything other than 9600@dmn{bps}.) After that, use @code{target 10014remote} to establish communications with @code{gdbserver}. Its argument 10015is either a device name (usually a serial device, like 10016@file{/dev/ttyb}), or a TCP port descriptor in the form 10017@code{@var{host}:@var{PORT}}. For example: 10018 10019@smallexample 10020(@value{GDBP}) target remote /dev/ttyb 10021@end smallexample 10022 10023@noindent 10024communicates with the server via serial line @file{/dev/ttyb}, and 10025 10026@smallexample 10027(@value{GDBP}) target remote the-target:2345 10028@end smallexample 10029 10030@noindent 10031communicates via a TCP connection to port 2345 on host @w{@file{the-target}}. 10032For TCP connections, you must start up @code{gdbserver} prior to using 10033the @code{target remote} command. Otherwise you may get an error whose 10034text depends on the host system, but which usually looks something like 10035@samp{Connection refused}. 10036@end table 10037 10038@node NetWare 10039@section Using the @code{gdbserve.nlm} program 10040 10041@kindex gdbserve.nlm 10042@code{gdbserve.nlm} is a control program for NetWare systems, which 10043allows you to connect your program with a remote @value{GDBN} via 10044@code{target remote}. 10045 10046@value{GDBN} and @code{gdbserve.nlm} communicate via a serial line, 10047using the standard @value{GDBN} remote serial protocol. 10048 10049@table @emph 10050@item On the target machine, 10051you need to have a copy of the program you want to debug. 10052@code{gdbserve.nlm} does not need your program's symbol table, so you 10053can strip the program if necessary to save space. @value{GDBN} on the 10054host system does all the symbol handling. 10055 10056To use the server, you must tell it how to communicate with 10057@value{GDBN}; the name of your program; and the arguments for your 10058program. The syntax is: 10059 10060@smallexample 10061load gdbserve [ BOARD=@var{board} ] [ PORT=@var{port} ] 10062 [ BAUD=@var{baud} ] @var{program} [ @var{args} @dots{} ] 10063@end smallexample 10064 10065@var{board} and @var{port} specify the serial line; @var{baud} specifies 10066the baud rate used by the connection. @var{port} and @var{node} default 10067to 0, @var{baud} defaults to 9600@dmn{bps}. 10068 10069For example, to debug Emacs with the argument @samp{foo.txt}and 10070communicate with @value{GDBN} over serial port number 2 or board 1 10071using a 19200@dmn{bps} connection: 10072 10073@smallexample 10074load gdbserve BOARD=1 PORT=2 BAUD=19200 emacs foo.txt 10075@end smallexample 10076 10077@item On the @value{GDBN} host machine, 10078you need an unstripped copy of your program, since @value{GDBN} needs 10079symbols and debugging information. Start up @value{GDBN} as usual, 10080using the name of the local copy of your program as the first argument. 10081(You may also need the @w{@samp{--baud}} option if the serial line is 10082running at anything other than 9600@dmn{bps}. After that, use @code{target 10083remote} to establish communications with @code{gdbserve.nlm}. Its 10084argument is a device name (usually a serial device, like 10085@file{/dev/ttyb}). For example: 10086 10087@smallexample 10088(@value{GDBP}) target remote /dev/ttyb 10089@end smallexample 10090 10091@noindent 10092communications with the server via serial line @file{/dev/ttyb}. 10093@end table 10094 10095@node remote stub 10096@section Implementing a remote stub 10097 10098@cindex debugging stub, example 10099@cindex remote stub, example 10100@cindex stub example, remote debugging 10101The stub files provided with @value{GDBN} implement the target side of the 10102communication protocol, and the @value{GDBN} side is implemented in the 10103@value{GDBN} source file @file{remote.c}. Normally, you can simply allow 10104these subroutines to communicate, and ignore the details. (If you're 10105implementing your own stub file, you can still ignore the details: start 10106with one of the existing stub files. @file{sparc-stub.c} is the best 10107organized, and therefore the easiest to read.) 10108 10109@cindex remote serial debugging, overview 10110To debug a program running on another machine (the debugging 10111@dfn{target} machine), you must first arrange for all the usual 10112prerequisites for the program to run by itself. For example, for a C 10113program, you need: 10114 10115@enumerate 10116@item 10117A startup routine to set up the C runtime environment; these usually 10118have a name like @file{crt0}. The startup routine may be supplied by 10119your hardware supplier, or you may have to write your own. 10120 10121@item 10122A C subroutine library to support your program's 10123subroutine calls, notably managing input and output. 10124 10125@item 10126A way of getting your program to the other machine---for example, a 10127download program. These are often supplied by the hardware 10128manufacturer, but you may have to write your own from hardware 10129documentation. 10130@end enumerate 10131 10132The next step is to arrange for your program to use a serial port to 10133communicate with the machine where @value{GDBN} is running (the @dfn{host} 10134machine). In general terms, the scheme looks like this: 10135 10136@table @emph 10137@item On the host, 10138@value{GDBN} already understands how to use this protocol; when everything 10139else is set up, you can simply use the @samp{target remote} command 10140(@pxref{Targets,,Specifying a Debugging Target}). 10141 10142@item On the target, 10143you must link with your program a few special-purpose subroutines that 10144implement the @value{GDBN} remote serial protocol. The file containing these 10145subroutines is called a @dfn{debugging stub}. 10146 10147On certain remote targets, you can use an auxiliary program 10148@code{gdbserver} instead of linking a stub into your program. 10149@xref{Server,,Using the @code{gdbserver} program}, for details. 10150@end table 10151 10152The debugging stub is specific to the architecture of the remote 10153machine; for example, use @file{sparc-stub.c} to debug programs on 10154@sc{sparc} boards. 10155 10156@cindex remote serial stub list 10157These working remote stubs are distributed with @value{GDBN}: 10158 10159@table @code 10160 10161@item i386-stub.c 10162@cindex @file{i386-stub.c} 10163@cindex Intel 10164@cindex i386 10165For Intel 386 and compatible architectures. 10166 10167@item m68k-stub.c 10168@cindex @file{m68k-stub.c} 10169@cindex Motorola 680x0 10170@cindex m680x0 10171For Motorola 680x0 architectures. 10172 10173@item sh-stub.c 10174@cindex @file{sh-stub.c} 10175@cindex Hitachi 10176@cindex SH 10177For Hitachi SH architectures. 10178 10179@item sparc-stub.c 10180@cindex @file{sparc-stub.c} 10181@cindex Sparc 10182For @sc{sparc} architectures. 10183 10184@item sparcl-stub.c 10185@cindex @file{sparcl-stub.c} 10186@cindex Fujitsu 10187@cindex SparcLite 10188For Fujitsu @sc{sparclite} architectures. 10189 10190@end table 10191 10192The @file{README} file in the @value{GDBN} distribution may list other 10193recently added stubs. 10194 10195@menu 10196* Stub Contents:: What the stub can do for you 10197* Bootstrapping:: What you must do for the stub 10198* Debug Session:: Putting it all together 10199@end menu 10200 10201@node Stub Contents 10202@subsection What the stub can do for you 10203 10204@cindex remote serial stub 10205The debugging stub for your architecture supplies these three 10206subroutines: 10207 10208@table @code 10209@item set_debug_traps 10210@kindex set_debug_traps 10211@cindex remote serial stub, initialization 10212This routine arranges for @code{handle_exception} to run when your 10213program stops. You must call this subroutine explicitly near the 10214beginning of your program. 10215 10216@item handle_exception 10217@kindex handle_exception 10218@cindex remote serial stub, main routine 10219This is the central workhorse, but your program never calls it 10220explicitly---the setup code arranges for @code{handle_exception} to 10221run when a trap is triggered. 10222 10223@code{handle_exception} takes control when your program stops during 10224execution (for example, on a breakpoint), and mediates communications 10225with @value{GDBN} on the host machine. This is where the communications 10226protocol is implemented; @code{handle_exception} acts as the @value{GDBN} 10227representative on the target machine. It begins by sending summary 10228information on the state of your program, then continues to execute, 10229retrieving and transmitting any information @value{GDBN} needs, until you 10230execute a @value{GDBN} command that makes your program resume; at that point, 10231@code{handle_exception} returns control to your own code on the target 10232machine. 10233 10234@item breakpoint 10235@cindex @code{breakpoint} subroutine, remote 10236Use this auxiliary subroutine to make your program contain a 10237breakpoint. Depending on the particular situation, this may be the only 10238way for @value{GDBN} to get control. For instance, if your target 10239machine has some sort of interrupt button, you won't need to call this; 10240pressing the interrupt button transfers control to 10241@code{handle_exception}---in effect, to @value{GDBN}. On some machines, 10242simply receiving characters on the serial port may also trigger a trap; 10243again, in that situation, you don't need to call @code{breakpoint} from 10244your own program---simply running @samp{target remote} from the host 10245@value{GDBN} session gets control. 10246 10247Call @code{breakpoint} if none of these is true, or if you simply want 10248to make certain your program stops at a predetermined point for the 10249start of your debugging session. 10250@end table 10251 10252@node Bootstrapping 10253@subsection What you must do for the stub 10254 10255@cindex remote stub, support routines 10256The debugging stubs that come with @value{GDBN} are set up for a particular 10257chip architecture, but they have no information about the rest of your 10258debugging target machine. 10259 10260First of all you need to tell the stub how to communicate with the 10261serial port. 10262 10263@table @code 10264@item int getDebugChar() 10265@kindex getDebugChar 10266Write this subroutine to read a single character from the serial port. 10267It may be identical to @code{getchar} for your target system; a 10268different name is used to allow you to distinguish the two if you wish. 10269 10270@item void putDebugChar(int) 10271@kindex putDebugChar 10272Write this subroutine to write a single character to the serial port. 10273It may be identical to @code{putchar} for your target system; a 10274different name is used to allow you to distinguish the two if you wish. 10275@end table 10276 10277@cindex control C, and remote debugging 10278@cindex interrupting remote targets 10279If you want @value{GDBN} to be able to stop your program while it is 10280running, you need to use an interrupt-driven serial driver, and arrange 10281for it to stop when it receives a @code{^C} (@samp{\003}, the control-C 10282character). That is the character which @value{GDBN} uses to tell the 10283remote system to stop. 10284 10285Getting the debugging target to return the proper status to @value{GDBN} 10286probably requires changes to the standard stub; one quick and dirty way 10287is to just execute a breakpoint instruction (the ``dirty'' part is that 10288@value{GDBN} reports a @code{SIGTRAP} instead of a @code{SIGINT}). 10289 10290Other routines you need to supply are: 10291 10292@table @code 10293@item void exceptionHandler (int @var{exception_number}, void *@var{exception_address}) 10294@kindex exceptionHandler 10295Write this function to install @var{exception_address} in the exception 10296handling tables. You need to do this because the stub does not have any 10297way of knowing what the exception handling tables on your target system 10298are like (for example, the processor's table might be in @sc{rom}, 10299containing entries which point to a table in @sc{ram}). 10300@var{exception_number} is the exception number which should be changed; 10301its meaning is architecture-dependent (for example, different numbers 10302might represent divide by zero, misaligned access, etc). When this 10303exception occurs, control should be transferred directly to 10304@var{exception_address}, and the processor state (stack, registers, 10305and so on) should be just as it is when a processor exception occurs. So if 10306you want to use a jump instruction to reach @var{exception_address}, it 10307should be a simple jump, not a jump to subroutine. 10308 10309For the 386, @var{exception_address} should be installed as an interrupt 10310gate so that interrupts are masked while the handler runs. The gate 10311should be at privilege level 0 (the most privileged level). The 10312@sc{sparc} and 68k stubs are able to mask interrupts themselves without 10313help from @code{exceptionHandler}. 10314 10315@item void flush_i_cache() 10316@kindex flush_i_cache 10317On @sc{sparc} and @sc{sparclite} only, write this subroutine to flush the 10318instruction cache, if any, on your target machine. If there is no 10319instruction cache, this subroutine may be a no-op. 10320 10321On target machines that have instruction caches, @value{GDBN} requires this 10322function to make certain that the state of your program is stable. 10323@end table 10324 10325@noindent 10326You must also make sure this library routine is available: 10327 10328@table @code 10329@item void *memset(void *, int, int) 10330@kindex memset 10331This is the standard library function @code{memset} that sets an area of 10332memory to a known value. If you have one of the free versions of 10333@code{libc.a}, @code{memset} can be found there; otherwise, you must 10334either obtain it from your hardware manufacturer, or write your own. 10335@end table 10336 10337If you do not use the GNU C compiler, you may need other standard 10338library subroutines as well; this varies from one stub to another, 10339but in general the stubs are likely to use any of the common library 10340subroutines which @code{@value{GCC}} generates as inline code. 10341 10342 10343@node Debug Session 10344@subsection Putting it all together 10345 10346@cindex remote serial debugging summary 10347In summary, when your program is ready to debug, you must follow these 10348steps. 10349 10350@enumerate 10351@item 10352Make sure you have defined the supporting low-level routines 10353(@pxref{Bootstrapping,,What you must do for the stub}): 10354@display 10355@code{getDebugChar}, @code{putDebugChar}, 10356@code{flush_i_cache}, @code{memset}, @code{exceptionHandler}. 10357@end display 10358 10359@item 10360Insert these lines near the top of your program: 10361 10362@example 10363set_debug_traps(); 10364breakpoint(); 10365@end example 10366 10367@item 10368For the 680x0 stub only, you need to provide a variable called 10369@code{exceptionHook}. Normally you just use: 10370 10371@example 10372void (*exceptionHook)() = 0; 10373@end example 10374 10375@noindent 10376but if before calling @code{set_debug_traps}, you set it to point to a 10377function in your program, that function is called when 10378@code{@value{GDBN}} continues after stopping on a trap (for example, bus 10379error). The function indicated by @code{exceptionHook} is called with 10380one parameter: an @code{int} which is the exception number. 10381 10382@item 10383Compile and link together: your program, the @value{GDBN} debugging stub for 10384your target architecture, and the supporting subroutines. 10385 10386@item 10387Make sure you have a serial connection between your target machine and 10388the @value{GDBN} host, and identify the serial port on the host. 10389 10390@item 10391@c The "remote" target now provides a `load' command, so we should 10392@c document that. FIXME. 10393Download your program to your target machine (or get it there by 10394whatever means the manufacturer provides), and start it. 10395 10396@item 10397To start remote debugging, run @value{GDBN} on the host machine, and specify 10398as an executable file the program that is running in the remote machine. 10399This tells @value{GDBN} how to find your program's symbols and the contents 10400of its pure text. 10401 10402@item 10403@cindex serial line, @code{target remote} 10404Establish communication using the @code{target remote} command. 10405Its argument specifies how to communicate with the target 10406machine---either via a devicename attached to a direct serial line, or a 10407TCP port (usually to a terminal server which in turn has a serial line 10408to the target). For example, to use a serial line connected to the 10409device named @file{/dev/ttyb}: 10410 10411@example 10412target remote /dev/ttyb 10413@end example 10414 10415@cindex TCP port, @code{target remote} 10416To use a TCP connection, use an argument of the form 10417@code{@var{host}:port}. For example, to connect to port 2828 on a 10418terminal server named @code{manyfarms}: 10419 10420@example 10421target remote manyfarms:2828 10422@end example 10423 10424If your remote target is actually running on the same machine as 10425your debugger session (e.g.@: a simulator of your target running on 10426the same host), you can omit the hostname. For example, to connect 10427to port 1234 on your local machine: 10428 10429@example 10430target remote :1234 10431@end example 10432@noindent 10433 10434Note that the colon is still required here. 10435@end enumerate 10436 10437Now you can use all the usual commands to examine and change data and to 10438step and continue the remote program. 10439 10440To resume the remote program and stop debugging it, use the @code{detach} 10441command. 10442 10443@cindex interrupting remote programs 10444@cindex remote programs, interrupting 10445Whenever @value{GDBN} is waiting for the remote program, if you type the 10446interrupt character (often @key{C-C}), @value{GDBN} attempts to stop the 10447program. This may or may not succeed, depending in part on the hardware 10448and the serial drivers the remote system uses. If you type the 10449interrupt character once again, @value{GDBN} displays this prompt: 10450 10451@example 10452Interrupted while waiting for the program. 10453Give up (and stop debugging it)? (y or n) 10454@end example 10455 10456If you type @kbd{y}, @value{GDBN} abandons the remote debugging session. 10457(If you decide you want to try again later, you can use @samp{target 10458remote} again to connect once more.) If you type @kbd{n}, @value{GDBN} 10459goes back to waiting. 10460 10461 10462@node Configurations 10463@chapter Configuration-Specific Information 10464 10465While nearly all @value{GDBN} commands are available for all native and 10466cross versions of the debugger, there are some exceptions. This chapter 10467describes things that are only available in certain configurations. 10468 10469There are three major categories of configurations: native 10470configurations, where the host and target are the same, embedded 10471operating system configurations, which are usually the same for several 10472different processor architectures, and bare embedded processors, which 10473are quite different from each other. 10474 10475@menu 10476* Native:: 10477* Embedded OS:: 10478* Embedded Processors:: 10479* Architectures:: 10480@end menu 10481 10482@node Native 10483@section Native 10484 10485This section describes details specific to particular native 10486configurations. 10487 10488@menu 10489* HP-UX:: HP-UX 10490* SVR4 Process Information:: SVR4 process information 10491* DJGPP Native:: Features specific to the DJGPP port 10492* Cygwin Native:: Features specific to the Cygwin port 10493@end menu 10494 10495@node HP-UX 10496@subsection HP-UX 10497 10498On HP-UX systems, if you refer to a function or variable name that 10499begins with a dollar sign, @value{GDBN} searches for a user or system 10500name first, before it searches for a convenience variable. 10501 10502@node SVR4 Process Information 10503@subsection SVR4 process information 10504 10505@kindex /proc 10506@cindex process image 10507 10508Many versions of SVR4 provide a facility called @samp{/proc} that can be 10509used to examine the image of a running process using file-system 10510subroutines. If @value{GDBN} is configured for an operating system with 10511this facility, the command @code{info proc} is available to report on 10512several kinds of information about the process running your program. 10513@code{info proc} works only on SVR4 systems that include the 10514@code{procfs} code. This includes OSF/1 (Digital Unix), Solaris, Irix, 10515and Unixware, but not HP-UX or Linux, for example. 10516 10517@table @code 10518@kindex info proc 10519@item info proc 10520Summarize available information about the process. 10521 10522@kindex info proc mappings 10523@item info proc mappings 10524Report on the address ranges accessible in the program, with information 10525on whether your program may read, write, or execute each range. 10526@ignore 10527@comment These sub-options of 'info proc' were not included when 10528@comment procfs.c was re-written. Keep their descriptions around 10529@comment against the day when someone finds the time to put them back in. 10530@kindex info proc times 10531@item info proc times 10532Starting time, user CPU time, and system CPU time for your program and 10533its children. 10534 10535@kindex info proc id 10536@item info proc id 10537Report on the process IDs related to your program: its own process ID, 10538the ID of its parent, the process group ID, and the session ID. 10539 10540@kindex info proc status 10541@item info proc status 10542General information on the state of the process. If the process is 10543stopped, this report includes the reason for stopping, and any signal 10544received. 10545 10546@item info proc all 10547Show all the above information about the process. 10548@end ignore 10549@end table 10550 10551@node DJGPP Native 10552@subsection Features for Debugging @sc{djgpp} Programs 10553@cindex @sc{djgpp} debugging 10554@cindex native @sc{djgpp} debugging 10555@cindex MS-DOS-specific commands 10556 10557@sc{djgpp} is the port of @sc{gnu} development tools to MS-DOS and 10558MS-Windows. @sc{djgpp} programs are 32-bit protected-mode programs 10559that use the @dfn{DPMI} (DOS Protected-Mode Interface) API to run on 10560top of real-mode DOS systems and their emulations. 10561 10562@value{GDBN} supports native debugging of @sc{djgpp} programs, and 10563defines a few commands specific to the @sc{djgpp} port. This 10564subsection describes those commands. 10565 10566@table @code 10567@kindex info dos 10568@item info dos 10569This is a prefix of @sc{djgpp}-specific commands which print 10570information about the target system and important OS structures. 10571 10572@kindex sysinfo 10573@cindex MS-DOS system info 10574@cindex free memory information (MS-DOS) 10575@item info dos sysinfo 10576This command displays assorted information about the underlying 10577platform: the CPU type and features, the OS version and flavor, the 10578DPMI version, and the available conventional and DPMI memory. 10579 10580@cindex GDT 10581@cindex LDT 10582@cindex IDT 10583@cindex segment descriptor tables 10584@cindex descriptor tables display 10585@item info dos gdt 10586@itemx info dos ldt 10587@itemx info dos idt 10588These 3 commands display entries from, respectively, Global, Local, 10589and Interrupt Descriptor Tables (GDT, LDT, and IDT). The descriptor 10590tables are data structures which store a descriptor for each segment 10591that is currently in use. The segment's selector is an index into a 10592descriptor table; the table entry for that index holds the 10593descriptor's base address and limit, and its attributes and access 10594rights. 10595 10596A typical @sc{djgpp} program uses 3 segments: a code segment, a data 10597segment (used for both data and the stack), and a DOS segment (which 10598allows access to DOS/BIOS data structures and absolute addresses in 10599conventional memory). However, the DPMI host will usually define 10600additional segments in order to support the DPMI environment. 10601 10602@cindex garbled pointers 10603These commands allow to display entries from the descriptor tables. 10604Without an argument, all entries from the specified table are 10605displayed. An argument, which should be an integer expression, means 10606display a single entry whose index is given by the argument. For 10607example, here's a convenient way to display information about the 10608debugged program's data segment: 10609 10610@smallexample 10611@exdent @code{(@value{GDBP}) info dos ldt $ds} 10612@exdent @code{0x13f: base=0x11970000 limit=0x0009ffff 32-Bit Data (Read/Write, Exp-up)} 10613@end smallexample 10614 10615@noindent 10616This comes in handy when you want to see whether a pointer is outside 10617the data segment's limit (i.e.@: @dfn{garbled}). 10618 10619@cindex page tables display (MS-DOS) 10620@item info dos pde 10621@itemx info dos pte 10622These two commands display entries from, respectively, the Page 10623Directory and the Page Tables. Page Directories and Page Tables are 10624data structures which control how virtual memory addresses are mapped 10625into physical addresses. A Page Table includes an entry for every 10626page of memory that is mapped into the program's address space; there 10627may be several Page Tables, each one holding up to 4096 entries. A 10628Page Directory has up to 4096 entries, one each for every Page Table 10629that is currently in use. 10630 10631Without an argument, @kbd{info dos pde} displays the entire Page 10632Directory, and @kbd{info dos pte} displays all the entries in all of 10633the Page Tables. An argument, an integer expression, given to the 10634@kbd{info dos pde} command means display only that entry from the Page 10635Directory table. An argument given to the @kbd{info dos pte} command 10636means display entries from a single Page Table, the one pointed to by 10637the specified entry in the Page Directory. 10638 10639@cindex direct memory access (DMA) on MS-DOS 10640These commands are useful when your program uses @dfn{DMA} (Direct 10641Memory Access), which needs physical addresses to program the DMA 10642controller. 10643 10644These commands are supported only with some DPMI servers. 10645 10646@cindex physical address from linear address 10647@item info dos address-pte @var{addr} 10648This command displays the Page Table entry for a specified linear 10649address. The argument linear address @var{addr} should already have the 10650appropriate segment's base address added to it, because this command 10651accepts addresses which may belong to @emph{any} segment. For 10652example, here's how to display the Page Table entry for the page where 10653the variable @code{i} is stored: 10654 10655@smallexample 10656@exdent @code{(@value{GDBP}) info dos address-pte __djgpp_base_address + (char *)&i} 10657@exdent @code{Page Table entry for address 0x11a00d30:} 10658@exdent @code{Base=0x02698000 Dirty Acc. Not-Cached Write-Back Usr Read-Write +0xd30} 10659@end smallexample 10660 10661@noindent 10662This says that @code{i} is stored at offset @code{0xd30} from the page 10663whose physical base address is @code{0x02698000}, and prints all the 10664attributes of that page. 10665 10666Note that you must cast the addresses of variables to a @code{char *}, 10667since otherwise the value of @code{__djgpp_base_address}, the base 10668address of all variables and functions in a @sc{djgpp} program, will 10669be added using the rules of C pointer arithmetics: if @code{i} is 10670declared an @code{int}, @value{GDBN} will add 4 times the value of 10671@code{__djgpp_base_address} to the address of @code{i}. 10672 10673Here's another example, it displays the Page Table entry for the 10674transfer buffer: 10675 10676@smallexample 10677@exdent @code{(@value{GDBP}) info dos address-pte *((unsigned *)&_go32_info_block + 3)} 10678@exdent @code{Page Table entry for address 0x29110:} 10679@exdent @code{Base=0x00029000 Dirty Acc. Not-Cached Write-Back Usr Read-Write +0x110} 10680@end smallexample 10681 10682@noindent 10683(The @code{+ 3} offset is because the transfer buffer's address is the 106843rd member of the @code{_go32_info_block} structure.) The output of 10685this command clearly shows that addresses in conventional memory are 10686mapped 1:1, i.e.@: the physical and linear addresses are identical. 10687 10688This command is supported only with some DPMI servers. 10689@end table 10690 10691@node Cygwin Native 10692@subsection Features for Debugging MS Windows PE executables 10693@cindex MS Windows debugging 10694@cindex native Cygwin debugging 10695@cindex Cygwin-specific commands 10696 10697@value{GDBN} supports native debugging of MS Windows programs, and 10698defines a few commands specific to the Cygwin port. This 10699subsection describes those commands. 10700 10701@table @code 10702@kindex info w32 10703@item info w32 10704This is a prefix of MS Windows specific commands which print 10705information about the target system and important OS structures. 10706 10707@item info w32 selector 10708This command displays information returned by 10709the Win32 API @code{GetThreadSelectorEntry} function. 10710It takes an optional argument that is evaluated to 10711a long value to give the information about this given selector. 10712Without argument, this command displays information 10713about the the six segment registers. 10714 10715@kindex info dll 10716@item info dll 10717This is a Cygwin specific alias of info shared. 10718 10719@kindex dll-symbols 10720@item dll-symbols 10721This command loads symbols from a dll similarly to 10722add-sym command but without the need to specify a base address. 10723 10724@kindex set new-console 10725@item set new-console @var{mode} 10726If @var{mode} is @code{on} the debuggee will 10727be started in a new console on next start. 10728If @var{mode} is @code{off}i, the debuggee will 10729be started in the same console as the debugger. 10730 10731@kindex show new-console 10732@item show new-console 10733Displays whether a new console is used 10734when the debuggee is started. 10735 10736@kindex set new-group 10737@item set new-group @var{mode} 10738This boolean value controls whether the debuggee should 10739start a new group or stay in the same group as the debugger. 10740This affects the way the Windows OS handles 10741Ctrl-C. 10742 10743@kindex show new-group 10744@item show new-group 10745Displays current value of new-group boolean. 10746 10747@kindex set debugevents 10748@item set debugevents 10749This boolean value adds debug output concerning events seen by the debugger. 10750 10751@kindex set debugexec 10752@item set debugexec 10753This boolean value adds debug output concerning execute events 10754seen by the debugger. 10755 10756@kindex set debugexceptions 10757@item set debugexceptions 10758This boolean value adds debug ouptut concerning exception events 10759seen by the debugger. 10760 10761@kindex set debugmemory 10762@item set debugmemory 10763This boolean value adds debug ouptut concerning memory events 10764seen by the debugger. 10765 10766@kindex set shell 10767@item set shell 10768This boolean values specifies whether the debuggee is called 10769via a shell or directly (default value is on). 10770 10771@kindex show shell 10772@item show shell 10773Displays if the debuggee will be started with a shell. 10774 10775@end table 10776 10777@node Embedded OS 10778@section Embedded Operating Systems 10779 10780This section describes configurations involving the debugging of 10781embedded operating systems that are available for several different 10782architectures. 10783 10784@menu 10785* VxWorks:: Using @value{GDBN} with VxWorks 10786@end menu 10787 10788@value{GDBN} includes the ability to debug programs running on 10789various real-time operating systems. 10790 10791@node VxWorks 10792@subsection Using @value{GDBN} with VxWorks 10793 10794@cindex VxWorks 10795 10796@table @code 10797 10798@kindex target vxworks 10799@item target vxworks @var{machinename} 10800A VxWorks system, attached via TCP/IP. The argument @var{machinename} 10801is the target system's machine name or IP address. 10802 10803@end table 10804 10805On VxWorks, @code{load} links @var{filename} dynamically on the 10806current target system as well as adding its symbols in @value{GDBN}. 10807 10808@value{GDBN} enables developers to spawn and debug tasks running on networked 10809VxWorks targets from a Unix host. Already-running tasks spawned from 10810the VxWorks shell can also be debugged. @value{GDBN} uses code that runs on 10811both the Unix host and on the VxWorks target. The program 10812@code{@value{GDBP}} is installed and executed on the Unix host. (It may be 10813installed with the name @code{vxgdb}, to distinguish it from a 10814@value{GDBN} for debugging programs on the host itself.) 10815 10816@table @code 10817@item VxWorks-timeout @var{args} 10818@kindex vxworks-timeout 10819All VxWorks-based targets now support the option @code{vxworks-timeout}. 10820This option is set by the user, and @var{args} represents the number of 10821seconds @value{GDBN} waits for responses to rpc's. You might use this if 10822your VxWorks target is a slow software simulator or is on the far side 10823of a thin network line. 10824@end table 10825 10826The following information on connecting to VxWorks was current when 10827this manual was produced; newer releases of VxWorks may use revised 10828procedures. 10829 10830@kindex INCLUDE_RDB 10831To use @value{GDBN} with VxWorks, you must rebuild your VxWorks kernel 10832to include the remote debugging interface routines in the VxWorks 10833library @file{rdb.a}. To do this, define @code{INCLUDE_RDB} in the 10834VxWorks configuration file @file{configAll.h} and rebuild your VxWorks 10835kernel. The resulting kernel contains @file{rdb.a}, and spawns the 10836source debugging task @code{tRdbTask} when VxWorks is booted. For more 10837information on configuring and remaking VxWorks, see the manufacturer's 10838manual. 10839@c VxWorks, see the @cite{VxWorks Programmer's Guide}. 10840 10841Once you have included @file{rdb.a} in your VxWorks system image and set 10842your Unix execution search path to find @value{GDBN}, you are ready to 10843run @value{GDBN}. From your Unix host, run @code{@value{GDBP}} (or 10844@code{vxgdb}, depending on your installation). 10845 10846@value{GDBN} comes up showing the prompt: 10847 10848@example 10849(vxgdb) 10850@end example 10851 10852@menu 10853* VxWorks Connection:: Connecting to VxWorks 10854* VxWorks Download:: VxWorks download 10855* VxWorks Attach:: Running tasks 10856@end menu 10857 10858@node VxWorks Connection 10859@subsubsection Connecting to VxWorks 10860 10861The @value{GDBN} command @code{target} lets you connect to a VxWorks target on the 10862network. To connect to a target whose host name is ``@code{tt}'', type: 10863 10864@example 10865(vxgdb) target vxworks tt 10866@end example 10867 10868@need 750 10869@value{GDBN} displays messages like these: 10870 10871@smallexample 10872Attaching remote machine across net... 10873Connected to tt. 10874@end smallexample 10875 10876@need 1000 10877@value{GDBN} then attempts to read the symbol tables of any object modules 10878loaded into the VxWorks target since it was last booted. @value{GDBN} locates 10879these files by searching the directories listed in the command search 10880path (@pxref{Environment, ,Your program's environment}); if it fails 10881to find an object file, it displays a message such as: 10882 10883@example 10884prog.o: No such file or directory. 10885@end example 10886 10887When this happens, add the appropriate directory to the search path with 10888the @value{GDBN} command @code{path}, and execute the @code{target} 10889command again. 10890 10891@node VxWorks Download 10892@subsubsection VxWorks download 10893 10894@cindex download to VxWorks 10895If you have connected to the VxWorks target and you want to debug an 10896object that has not yet been loaded, you can use the @value{GDBN} 10897@code{load} command to download a file from Unix to VxWorks 10898incrementally. The object file given as an argument to the @code{load} 10899command is actually opened twice: first by the VxWorks target in order 10900to download the code, then by @value{GDBN} in order to read the symbol 10901table. This can lead to problems if the current working directories on 10902the two systems differ. If both systems have NFS mounted the same 10903filesystems, you can avoid these problems by using absolute paths. 10904Otherwise, it is simplest to set the working directory on both systems 10905to the directory in which the object file resides, and then to reference 10906the file by its name, without any path. For instance, a program 10907@file{prog.o} may reside in @file{@var{vxpath}/vw/demo/rdb} in VxWorks 10908and in @file{@var{hostpath}/vw/demo/rdb} on the host. To load this 10909program, type this on VxWorks: 10910 10911@example 10912-> cd "@var{vxpath}/vw/demo/rdb" 10913@end example 10914 10915@noindent 10916Then, in @value{GDBN}, type: 10917 10918@example 10919(vxgdb) cd @var{hostpath}/vw/demo/rdb 10920(vxgdb) load prog.o 10921@end example 10922 10923@value{GDBN} displays a response similar to this: 10924 10925@smallexample 10926Reading symbol data from wherever/vw/demo/rdb/prog.o... done. 10927@end smallexample 10928 10929You can also use the @code{load} command to reload an object module 10930after editing and recompiling the corresponding source file. Note that 10931this makes @value{GDBN} delete all currently-defined breakpoints, 10932auto-displays, and convenience variables, and to clear the value 10933history. (This is necessary in order to preserve the integrity of 10934debugger's data structures that reference the target system's symbol 10935table.) 10936 10937@node VxWorks Attach 10938@subsubsection Running tasks 10939 10940@cindex running VxWorks tasks 10941You can also attach to an existing task using the @code{attach} command as 10942follows: 10943 10944@example 10945(vxgdb) attach @var{task} 10946@end example 10947 10948@noindent 10949where @var{task} is the VxWorks hexadecimal task ID. The task can be running 10950or suspended when you attach to it. Running tasks are suspended at 10951the time of attachment. 10952 10953@node Embedded Processors 10954@section Embedded Processors 10955 10956This section goes into details specific to particular embedded 10957configurations. 10958 10959 10960@c OBSOLETE * A29K Embedded:: AMD A29K Embedded 10961@menu 10962* ARM:: ARM 10963* H8/300:: Hitachi H8/300 10964* H8/500:: Hitachi H8/500 10965* i960:: Intel i960 10966* M32R/D:: Mitsubishi M32R/D 10967* M68K:: Motorola M68K 10968* M88K:: Motorola M88K 10969* MIPS Embedded:: MIPS Embedded 10970* PA:: HP PA Embedded 10971* PowerPC: PowerPC 10972* SH:: Hitachi SH 10973* Sparclet:: Tsqware Sparclet 10974* Sparclite:: Fujitsu Sparclite 10975* ST2000:: Tandem ST2000 10976* Z8000:: Zilog Z8000 10977@end menu 10978 10979@c OBSOLETE @node A29K Embedded 10980@c OBSOLETE @subsection AMD A29K Embedded 10981@c OBSOLETE 10982@c OBSOLETE @menu 10983@c OBSOLETE * A29K UDI:: 10984@c OBSOLETE * A29K EB29K:: 10985@c OBSOLETE * Comms (EB29K):: Communications setup 10986@c OBSOLETE * gdb-EB29K:: EB29K cross-debugging 10987@c OBSOLETE * Remote Log:: Remote log 10988@c OBSOLETE @end menu 10989@c OBSOLETE 10990@c OBSOLETE @table @code 10991@c OBSOLETE 10992@c OBSOLETE @kindex target adapt 10993@c OBSOLETE @item target adapt @var{dev} 10994@c OBSOLETE Adapt monitor for A29K. 10995@c OBSOLETE 10996@c OBSOLETE @kindex target amd-eb 10997@c OBSOLETE @item target amd-eb @var{dev} @var{speed} @var{PROG} 10998@c OBSOLETE @cindex AMD EB29K 10999@c OBSOLETE Remote PC-resident AMD EB29K board, attached over serial lines. 11000@c OBSOLETE @var{dev} is the serial device, as for @code{target remote}; 11001@c OBSOLETE @var{speed} allows you to specify the linespeed; and @var{PROG} is the 11002@c OBSOLETE name of the program to be debugged, as it appears to DOS on the PC. 11003@c OBSOLETE @xref{A29K EB29K, ,EBMON protocol for AMD29K}. 11004@c OBSOLETE 11005@c OBSOLETE @end table 11006@c OBSOLETE 11007@c OBSOLETE @node A29K UDI 11008@c OBSOLETE @subsubsection A29K UDI 11009@c OBSOLETE 11010@c OBSOLETE @cindex UDI 11011@c OBSOLETE @cindex AMD29K via UDI 11012@c OBSOLETE 11013@c OBSOLETE @value{GDBN} supports AMD's UDI (``Universal Debugger Interface'') 11014@c OBSOLETE protocol for debugging the a29k processor family. To use this 11015@c OBSOLETE configuration with AMD targets running the MiniMON monitor, you need the 11016@c OBSOLETE program @code{MONTIP}, available from AMD at no charge. You can also 11017@c OBSOLETE use @value{GDBN} with the UDI-conformant a29k simulator program 11018@c OBSOLETE @code{ISSTIP}, also available from AMD. 11019@c OBSOLETE 11020@c OBSOLETE @table @code 11021@c OBSOLETE @item target udi @var{keyword} 11022@c OBSOLETE @kindex udi 11023@c OBSOLETE Select the UDI interface to a remote a29k board or simulator, where 11024@c OBSOLETE @var{keyword} is an entry in the AMD configuration file @file{udi_soc}. 11025@c OBSOLETE This file contains keyword entries which specify parameters used to 11026@c OBSOLETE connect to a29k targets. If the @file{udi_soc} file is not in your 11027@c OBSOLETE working directory, you must set the environment variable @samp{UDICONF} 11028@c OBSOLETE to its pathname. 11029@c OBSOLETE @end table 11030@c OBSOLETE 11031@c OBSOLETE @node A29K EB29K 11032@c OBSOLETE @subsubsection EBMON protocol for AMD29K 11033@c OBSOLETE 11034@c OBSOLETE @cindex EB29K board 11035@c OBSOLETE @cindex running 29K programs 11036@c OBSOLETE 11037@c OBSOLETE AMD distributes a 29K development board meant to fit in a PC, together 11038@c OBSOLETE with a DOS-hosted monitor program called @code{EBMON}. As a shorthand 11039@c OBSOLETE term, this development system is called the ``EB29K''. To use 11040@c OBSOLETE @value{GDBN} from a Unix system to run programs on the EB29K board, you 11041@c OBSOLETE must first connect a serial cable between the PC (which hosts the EB29K 11042@c OBSOLETE board) and a serial port on the Unix system. In the following, we 11043@c OBSOLETE assume you've hooked the cable between the PC's @file{COM1} port and 11044@c OBSOLETE @file{/dev/ttya} on the Unix system. 11045@c OBSOLETE 11046@c OBSOLETE @node Comms (EB29K) 11047@c OBSOLETE @subsubsection Communications setup 11048@c OBSOLETE 11049@c OBSOLETE The next step is to set up the PC's port, by doing something like this 11050@c OBSOLETE in DOS on the PC: 11051@c OBSOLETE 11052@c OBSOLETE @example 11053@c OBSOLETE C:\> MODE com1:9600,n,8,1,none 11054@c OBSOLETE @end example 11055@c OBSOLETE 11056@c OBSOLETE @noindent 11057@c OBSOLETE This example---run on an MS DOS 4.0 system---sets the PC port to 9600 11058@c OBSOLETE bps, no parity, eight data bits, one stop bit, and no ``retry'' action; 11059@c OBSOLETE you must match the communications parameters when establishing the Unix 11060@c OBSOLETE end of the connection as well. 11061@c OBSOLETE @c FIXME: Who knows what this "no retry action" crud from the DOS manual may 11062@c OBSOLETE @c mean? It's optional; leave it out? ---doc@cygnus.com, 25feb91 11063@c OBSOLETE @c 11064@c OBSOLETE @c It's optional, but it's unwise to omit it: who knows what is the 11065@c OBSOLETE @c default value set when the DOS machines boots? "No retry" means that 11066@c OBSOLETE @c the DOS serial device driver won't retry the operation if it fails; 11067@c OBSOLETE @c I understand that this is needed because the GDB serial protocol 11068@c OBSOLETE @c handles any errors and retransmissions itself. ---Eli Zaretskii, 3sep99 11069@c OBSOLETE 11070@c OBSOLETE To give control of the PC to the Unix side of the serial line, type 11071@c OBSOLETE the following at the DOS console: 11072@c OBSOLETE 11073@c OBSOLETE @example 11074@c OBSOLETE C:\> CTTY com1 11075@c OBSOLETE @end example 11076@c OBSOLETE 11077@c OBSOLETE @noindent 11078@c OBSOLETE (Later, if you wish to return control to the DOS console, you can use 11079@c OBSOLETE the command @code{CTTY con}---but you must send it over the device that 11080@c OBSOLETE had control, in our example over the @file{COM1} serial line.) 11081@c OBSOLETE 11082@c OBSOLETE From the Unix host, use a communications program such as @code{tip} or 11083@c OBSOLETE @code{cu} to communicate with the PC; for example, 11084@c OBSOLETE 11085@c OBSOLETE @example 11086@c OBSOLETE cu -s 9600 -l /dev/ttya 11087@c OBSOLETE @end example 11088@c OBSOLETE 11089@c OBSOLETE @noindent 11090@c OBSOLETE The @code{cu} options shown specify, respectively, the linespeed and the 11091@c OBSOLETE serial port to use. If you use @code{tip} instead, your command line 11092@c OBSOLETE may look something like the following: 11093@c OBSOLETE 11094@c OBSOLETE @example 11095@c OBSOLETE tip -9600 /dev/ttya 11096@c OBSOLETE @end example 11097@c OBSOLETE 11098@c OBSOLETE @noindent 11099@c OBSOLETE Your system may require a different name where we show 11100@c OBSOLETE @file{/dev/ttya} as the argument to @code{tip}. The communications 11101@c OBSOLETE parameters, including which port to use, are associated with the 11102@c OBSOLETE @code{tip} argument in the ``remote'' descriptions file---normally the 11103@c OBSOLETE system table @file{/etc/remote}. 11104@c OBSOLETE @c FIXME: What if anything needs doing to match the "n,8,1,none" part of 11105@c OBSOLETE @c the DOS side's comms setup? cu can support -o (odd 11106@c OBSOLETE @c parity), -e (even parity)---apparently no settings for no parity or 11107@c OBSOLETE @c for character size. Taken from stty maybe...? John points out tip 11108@c OBSOLETE @c can set these as internal variables, eg ~s parity=none; man stty 11109@c OBSOLETE @c suggests that it *might* work to stty these options with stdin or 11110@c OBSOLETE @c stdout redirected... ---doc@cygnus.com, 25feb91 11111@c OBSOLETE @c 11112@c OBSOLETE @c There's nothing to be done for the "none" part of the DOS MODE 11113@c OBSOLETE @c command. The rest of the parameters should be matched by the 11114@c OBSOLETE @c baudrate, bits, and parity used by the Unix side. ---Eli Zaretskii, 3Sep99 11115@c OBSOLETE 11116@c OBSOLETE @kindex EBMON 11117@c OBSOLETE Using the @code{tip} or @code{cu} connection, change the DOS working 11118@c OBSOLETE directory to the directory containing a copy of your 29K program, then 11119@c OBSOLETE start the PC program @code{EBMON} (an EB29K control program supplied 11120@c OBSOLETE with your board by AMD). You should see an initial display from 11121@c OBSOLETE @code{EBMON} similar to the one that follows, ending with the 11122@c OBSOLETE @code{EBMON} prompt @samp{#}--- 11123@c OBSOLETE 11124@c OBSOLETE @example 11125@c OBSOLETE C:\> G: 11126@c OBSOLETE 11127@c OBSOLETE G:\> CD \usr\joe\work29k 11128@c OBSOLETE 11129@c OBSOLETE G:\USR\JOE\WORK29K> EBMON 11130@c OBSOLETE Am29000 PC Coprocessor Board Monitor, version 3.0-18 11131@c OBSOLETE Copyright 1990 Advanced Micro Devices, Inc. 11132@c OBSOLETE Written by Gibbons and Associates, Inc. 11133@c OBSOLETE 11134@c OBSOLETE Enter '?' or 'H' for help 11135@c OBSOLETE 11136@c OBSOLETE PC Coprocessor Type = EB29K 11137@c OBSOLETE I/O Base = 0x208 11138@c OBSOLETE Memory Base = 0xd0000 11139@c OBSOLETE 11140@c OBSOLETE Data Memory Size = 2048KB 11141@c OBSOLETE Available I-RAM Range = 0x8000 to 0x1fffff 11142@c OBSOLETE Available D-RAM Range = 0x80002000 to 0x801fffff 11143@c OBSOLETE 11144@c OBSOLETE PageSize = 0x400 11145@c OBSOLETE Register Stack Size = 0x800 11146@c OBSOLETE Memory Stack Size = 0x1800 11147@c OBSOLETE 11148@c OBSOLETE CPU PRL = 0x3 11149@c OBSOLETE Am29027 Available = No 11150@c OBSOLETE Byte Write Available = Yes 11151@c OBSOLETE 11152@c OBSOLETE # ~. 11153@c OBSOLETE @end example 11154@c OBSOLETE 11155@c OBSOLETE Then exit the @code{cu} or @code{tip} program (done in the example by 11156@c OBSOLETE typing @code{~.} at the @code{EBMON} prompt). @code{EBMON} keeps 11157@c OBSOLETE running, ready for @value{GDBN} to take over. 11158@c OBSOLETE 11159@c OBSOLETE For this example, we've assumed what is probably the most convenient 11160@c OBSOLETE way to make sure the same 29K program is on both the PC and the Unix 11161@c OBSOLETE system: a PC/NFS connection that establishes ``drive @file{G:}'' on the 11162@c OBSOLETE PC as a file system on the Unix host. If you do not have PC/NFS or 11163@c OBSOLETE something similar connecting the two systems, you must arrange some 11164@c OBSOLETE other way---perhaps floppy-disk transfer---of getting the 29K program 11165@c OBSOLETE from the Unix system to the PC; @value{GDBN} does @emph{not} download it over the 11166@c OBSOLETE serial line. 11167@c OBSOLETE 11168@c OBSOLETE @node gdb-EB29K 11169@c OBSOLETE @subsubsection EB29K cross-debugging 11170@c OBSOLETE 11171@c OBSOLETE Finally, @code{cd} to the directory containing an image of your 29K 11172@c OBSOLETE program on the Unix system, and start @value{GDBN}---specifying as argument the 11173@c OBSOLETE name of your 29K program: 11174@c OBSOLETE 11175@c OBSOLETE @example 11176@c OBSOLETE cd /usr/joe/work29k 11177@c OBSOLETE @value{GDBP} myfoo 11178@c OBSOLETE @end example 11179@c OBSOLETE 11180@c OBSOLETE @need 500 11181@c OBSOLETE Now you can use the @code{target} command: 11182@c OBSOLETE 11183@c OBSOLETE @example 11184@c OBSOLETE target amd-eb /dev/ttya 9600 MYFOO 11185@c OBSOLETE @c FIXME: test above 'target amd-eb' as spelled, with caps! caps are meant to 11186@c OBSOLETE @c emphasize that this is the name as seen by DOS (since I think DOS is 11187@c OBSOLETE @c single-minded about case of letters). ---doc@cygnus.com, 25feb91 11188@c OBSOLETE @end example 11189@c OBSOLETE 11190@c OBSOLETE @noindent 11191@c OBSOLETE In this example, we've assumed your program is in a file called 11192@c OBSOLETE @file{myfoo}. Note that the filename given as the last argument to 11193@c OBSOLETE @code{target amd-eb} should be the name of the program as it appears to DOS. 11194@c OBSOLETE In our example this is simply @code{MYFOO}, but in general it can include 11195@c OBSOLETE a DOS path, and depending on your transfer mechanism may not resemble 11196@c OBSOLETE the name on the Unix side. 11197@c OBSOLETE 11198@c OBSOLETE At this point, you can set any breakpoints you wish; when you are ready 11199@c OBSOLETE to see your program run on the 29K board, use the @value{GDBN} command 11200@c OBSOLETE @code{run}. 11201@c OBSOLETE 11202@c OBSOLETE To stop debugging the remote program, use the @value{GDBN} @code{detach} 11203@c OBSOLETE command. 11204@c OBSOLETE 11205@c OBSOLETE To return control of the PC to its console, use @code{tip} or @code{cu} 11206@c OBSOLETE once again, after your @value{GDBN} session has concluded, to attach to 11207@c OBSOLETE @code{EBMON}. You can then type the command @code{q} to shut down 11208@c OBSOLETE @code{EBMON}, returning control to the DOS command-line interpreter. 11209@c OBSOLETE Type @kbd{CTTY con} to return command input to the main DOS console, 11210@c OBSOLETE and type @kbd{~.} to leave @code{tip} or @code{cu}. 11211@c OBSOLETE 11212@c OBSOLETE @node Remote Log 11213@c OBSOLETE @subsubsection Remote log 11214@c OBSOLETE @cindex @file{eb.log}, a log file for EB29K 11215@c OBSOLETE @cindex log file for EB29K 11216@c OBSOLETE 11217@c OBSOLETE The @code{target amd-eb} command creates a file @file{eb.log} in the 11218@c OBSOLETE current working directory, to help debug problems with the connection. 11219@c OBSOLETE @file{eb.log} records all the output from @code{EBMON}, including echoes 11220@c OBSOLETE of the commands sent to it. Running @samp{tail -f} on this file in 11221@c OBSOLETE another window often helps to understand trouble with @code{EBMON}, or 11222@c OBSOLETE unexpected events on the PC side of the connection. 11223 11224@node ARM 11225@subsection ARM 11226 11227@table @code 11228 11229@kindex target rdi 11230@item target rdi @var{dev} 11231ARM Angel monitor, via RDI library interface to ADP protocol. You may 11232use this target to communicate with both boards running the Angel 11233monitor, or with the EmbeddedICE JTAG debug device. 11234 11235@kindex target rdp 11236@item target rdp @var{dev} 11237ARM Demon monitor. 11238 11239@end table 11240 11241@node H8/300 11242@subsection Hitachi H8/300 11243 11244@table @code 11245 11246@kindex target hms@r{, with H8/300} 11247@item target hms @var{dev} 11248A Hitachi SH, H8/300, or H8/500 board, attached via serial line to your host. 11249Use special commands @code{device} and @code{speed} to control the serial 11250line and the communications speed used. 11251 11252@kindex target e7000@r{, with H8/300} 11253@item target e7000 @var{dev} 11254E7000 emulator for Hitachi H8 and SH. 11255 11256@kindex target sh3@r{, with H8/300} 11257@kindex target sh3e@r{, with H8/300} 11258@item target sh3 @var{dev} 11259@itemx target sh3e @var{dev} 11260Hitachi SH-3 and SH-3E target systems. 11261 11262@end table 11263 11264@cindex download to H8/300 or H8/500 11265@cindex H8/300 or H8/500 download 11266@cindex download to Hitachi SH 11267@cindex Hitachi SH download 11268When you select remote debugging to a Hitachi SH, H8/300, or H8/500 11269board, the @code{load} command downloads your program to the Hitachi 11270board and also opens it as the current executable target for 11271@value{GDBN} on your host (like the @code{file} command). 11272 11273@value{GDBN} needs to know these things to talk to your 11274Hitachi SH, H8/300, or H8/500: 11275 11276@enumerate 11277@item 11278that you want to use @samp{target hms}, the remote debugging interface 11279for Hitachi microprocessors, or @samp{target e7000}, the in-circuit 11280emulator for the Hitachi SH and the Hitachi 300H. (@samp{target hms} is 11281the default when @value{GDBN} is configured specifically for the Hitachi SH, 11282H8/300, or H8/500.) 11283 11284@item 11285what serial device connects your host to your Hitachi board (the first 11286serial device available on your host is the default). 11287 11288@item 11289what speed to use over the serial device. 11290@end enumerate 11291 11292@menu 11293* Hitachi Boards:: Connecting to Hitachi boards. 11294* Hitachi ICE:: Using the E7000 In-Circuit Emulator. 11295* Hitachi Special:: Special @value{GDBN} commands for Hitachi micros. 11296@end menu 11297 11298@node Hitachi Boards 11299@subsubsection Connecting to Hitachi boards 11300 11301@c only for Unix hosts 11302@kindex device 11303@cindex serial device, Hitachi micros 11304Use the special @code{@value{GDBN}} command @samp{device @var{port}} if you 11305need to explicitly set the serial device. The default @var{port} is the 11306first available port on your host. This is only necessary on Unix 11307hosts, where it is typically something like @file{/dev/ttya}. 11308 11309@kindex speed 11310@cindex serial line speed, Hitachi micros 11311@code{@value{GDBN}} has another special command to set the communications 11312speed: @samp{speed @var{bps}}. This command also is only used from Unix 11313hosts; on DOS hosts, set the line speed as usual from outside @value{GDBN} with 11314the DOS @code{mode} command (for instance, 11315@w{@kbd{mode com2:9600,n,8,1,p}} for a 9600@dmn{bps} connection). 11316 11317The @samp{device} and @samp{speed} commands are available only when you 11318use a Unix host to debug your Hitachi microprocessor programs. If you 11319use a DOS host, 11320@value{GDBN} depends on an auxiliary terminate-and-stay-resident program 11321called @code{asynctsr} to communicate with the development board 11322through a PC serial port. You must also use the DOS @code{mode} command 11323to set up the serial port on the DOS side. 11324 11325The following sample session illustrates the steps needed to start a 11326program under @value{GDBN} control on an H8/300. The example uses a 11327sample H8/300 program called @file{t.x}. The procedure is the same for 11328the Hitachi SH and the H8/500. 11329 11330First hook up your development board. In this example, we use a 11331board attached to serial port @code{COM2}; if you use a different serial 11332port, substitute its name in the argument of the @code{mode} command. 11333When you call @code{asynctsr}, the auxiliary comms program used by the 11334debugger, you give it just the numeric part of the serial port's name; 11335for example, @samp{asyncstr 2} below runs @code{asyncstr} on 11336@code{COM2}. 11337 11338@example 11339C:\H8300\TEST> asynctsr 2 11340C:\H8300\TEST> mode com2:9600,n,8,1,p 11341 11342Resident portion of MODE loaded 11343 11344COM2: 9600, n, 8, 1, p 11345 11346@end example 11347 11348@quotation 11349@emph{Warning:} We have noticed a bug in PC-NFS that conflicts with 11350@code{asynctsr}. If you also run PC-NFS on your DOS host, you may need to 11351disable it, or even boot without it, to use @code{asynctsr} to control 11352your development board. 11353@end quotation 11354 11355@kindex target hms@r{, and serial protocol} 11356Now that serial communications are set up, and the development board is 11357connected, you can start up @value{GDBN}. Call @code{@value{GDBP}} with 11358the name of your program as the argument. @code{@value{GDBN}} prompts 11359you, as usual, with the prompt @samp{(@value{GDBP})}. Use two special 11360commands to begin your debugging session: @samp{target hms} to specify 11361cross-debugging to the Hitachi board, and the @code{load} command to 11362download your program to the board. @code{load} displays the names of 11363the program's sections, and a @samp{*} for each 2K of data downloaded. 11364(If you want to refresh @value{GDBN} data on symbols or on the 11365executable file without downloading, use the @value{GDBN} commands 11366@code{file} or @code{symbol-file}. These commands, and @code{load} 11367itself, are described in @ref{Files,,Commands to specify files}.) 11368 11369@smallexample 11370(eg-C:\H8300\TEST) @value{GDBP} t.x 11371@value{GDBN} is free software and you are welcome to distribute copies 11372 of it under certain conditions; type "show copying" to see 11373 the conditions. 11374There is absolutely no warranty for @value{GDBN}; type "show warranty" 11375for details. 11376@value{GDBN} @value{GDBVN}, Copyright 1992 Free Software Foundation, Inc... 11377(@value{GDBP}) target hms 11378Connected to remote H8/300 HMS system. 11379(@value{GDBP}) load t.x 11380.text : 0x8000 .. 0xabde *********** 11381.data : 0xabde .. 0xad30 * 11382.stack : 0xf000 .. 0xf014 * 11383@end smallexample 11384 11385At this point, you're ready to run or debug your program. From here on, 11386you can use all the usual @value{GDBN} commands. The @code{break} command 11387sets breakpoints; the @code{run} command starts your program; 11388@code{print} or @code{x} display data; the @code{continue} command 11389resumes execution after stopping at a breakpoint. You can use the 11390@code{help} command at any time to find out more about @value{GDBN} commands. 11391 11392Remember, however, that @emph{operating system} facilities aren't 11393available on your development board; for example, if your program hangs, 11394you can't send an interrupt---but you can press the @sc{reset} switch! 11395 11396Use the @sc{reset} button on the development board 11397@itemize @bullet 11398@item 11399to interrupt your program (don't use @kbd{ctl-C} on the DOS host---it has 11400no way to pass an interrupt signal to the development board); and 11401 11402@item 11403to return to the @value{GDBN} command prompt after your program finishes 11404normally. The communications protocol provides no other way for @value{GDBN} 11405to detect program completion. 11406@end itemize 11407 11408In either case, @value{GDBN} sees the effect of a @sc{reset} on the 11409development board as a ``normal exit'' of your program. 11410 11411@node Hitachi ICE 11412@subsubsection Using the E7000 in-circuit emulator 11413 11414@kindex target e7000@r{, with Hitachi ICE} 11415You can use the E7000 in-circuit emulator to develop code for either the 11416Hitachi SH or the H8/300H. Use one of these forms of the @samp{target 11417e7000} command to connect @value{GDBN} to your E7000: 11418 11419@table @code 11420@item target e7000 @var{port} @var{speed} 11421Use this form if your E7000 is connected to a serial port. The 11422@var{port} argument identifies what serial port to use (for example, 11423@samp{com2}). The third argument is the line speed in bits per second 11424(for example, @samp{9600}). 11425 11426@item target e7000 @var{hostname} 11427If your E7000 is installed as a host on a TCP/IP network, you can just 11428specify its hostname; @value{GDBN} uses @code{telnet} to connect. 11429@end table 11430 11431@node Hitachi Special 11432@subsubsection Special @value{GDBN} commands for Hitachi micros 11433 11434Some @value{GDBN} commands are available only for the H8/300: 11435 11436@table @code 11437 11438@kindex set machine 11439@kindex show machine 11440@item set machine h8300 11441@itemx set machine h8300h 11442Condition @value{GDBN} for one of the two variants of the H8/300 11443architecture with @samp{set machine}. You can use @samp{show machine} 11444to check which variant is currently in effect. 11445 11446@end table 11447 11448@node H8/500 11449@subsection H8/500 11450 11451@table @code 11452 11453@kindex set memory @var{mod} 11454@cindex memory models, H8/500 11455@item set memory @var{mod} 11456@itemx show memory 11457Specify which H8/500 memory model (@var{mod}) you are using with 11458@samp{set memory}; check which memory model is in effect with @samp{show 11459memory}. The accepted values for @var{mod} are @code{small}, 11460@code{big}, @code{medium}, and @code{compact}. 11461 11462@end table 11463 11464@node i960 11465@subsection Intel i960 11466 11467@table @code 11468 11469@kindex target mon960 11470@item target mon960 @var{dev} 11471MON960 monitor for Intel i960. 11472 11473@kindex target nindy 11474@item target nindy @var{devicename} 11475An Intel 960 board controlled by a Nindy Monitor. @var{devicename} is 11476the name of the serial device to use for the connection, e.g. 11477@file{/dev/ttya}. 11478 11479@end table 11480 11481@cindex Nindy 11482@cindex i960 11483@dfn{Nindy} is a ROM Monitor program for Intel 960 target systems. When 11484@value{GDBN} is configured to control a remote Intel 960 using Nindy, you can 11485tell @value{GDBN} how to connect to the 960 in several ways: 11486 11487@itemize @bullet 11488@item 11489Through command line options specifying serial port, version of the 11490Nindy protocol, and communications speed; 11491 11492@item 11493By responding to a prompt on startup; 11494 11495@item 11496By using the @code{target} command at any point during your @value{GDBN} 11497session. @xref{Target Commands, ,Commands for managing targets}. 11498 11499@end itemize 11500 11501@cindex download to Nindy-960 11502With the Nindy interface to an Intel 960 board, @code{load} 11503downloads @var{filename} to the 960 as well as adding its symbols in 11504@value{GDBN}. 11505 11506@menu 11507* Nindy Startup:: Startup with Nindy 11508* Nindy Options:: Options for Nindy 11509* Nindy Reset:: Nindy reset command 11510@end menu 11511 11512@node Nindy Startup 11513@subsubsection Startup with Nindy 11514 11515If you simply start @code{@value{GDBP}} without using any command-line 11516options, you are prompted for what serial port to use, @emph{before} you 11517reach the ordinary @value{GDBN} prompt: 11518 11519@example 11520Attach /dev/ttyNN -- specify NN, or "quit" to quit: 11521@end example 11522 11523@noindent 11524Respond to the prompt with whatever suffix (after @samp{/dev/tty}) 11525identifies the serial port you want to use. You can, if you choose, 11526simply start up with no Nindy connection by responding to the prompt 11527with an empty line. If you do this and later wish to attach to Nindy, 11528use @code{target} (@pxref{Target Commands, ,Commands for managing targets}). 11529 11530@node Nindy Options 11531@subsubsection Options for Nindy 11532 11533These are the startup options for beginning your @value{GDBN} session with a 11534Nindy-960 board attached: 11535 11536@table @code 11537@item -r @var{port} 11538Specify the serial port name of a serial interface to be used to connect 11539to the target system. This option is only available when @value{GDBN} is 11540configured for the Intel 960 target architecture. You may specify 11541@var{port} as any of: a full pathname (e.g. @samp{-r /dev/ttya}), a 11542device name in @file{/dev} (e.g. @samp{-r ttya}), or simply the unique 11543suffix for a specific @code{tty} (e.g. @samp{-r a}). 11544 11545@item -O 11546(An uppercase letter ``O'', not a zero.) Specify that @value{GDBN} should use 11547the ``old'' Nindy monitor protocol to connect to the target system. 11548This option is only available when @value{GDBN} is configured for the Intel 960 11549target architecture. 11550 11551@quotation 11552@emph{Warning:} if you specify @samp{-O}, but are actually trying to 11553connect to a target system that expects the newer protocol, the connection 11554fails, appearing to be a speed mismatch. @value{GDBN} repeatedly 11555attempts to reconnect at several different line speeds. You can abort 11556this process with an interrupt. 11557@end quotation 11558 11559@item -brk 11560Specify that @value{GDBN} should first send a @code{BREAK} signal to the target 11561system, in an attempt to reset it, before connecting to a Nindy target. 11562 11563@quotation 11564@emph{Warning:} Many target systems do not have the hardware that this 11565requires; it only works with a few boards. 11566@end quotation 11567@end table 11568 11569The standard @samp{-b} option controls the line speed used on the serial 11570port. 11571 11572@c @group 11573@node Nindy Reset 11574@subsubsection Nindy reset command 11575 11576@table @code 11577@item reset 11578@kindex reset 11579For a Nindy target, this command sends a ``break'' to the remote target 11580system; this is only useful if the target has been equipped with a 11581circuit to perform a hard reset (or some other interesting action) when 11582a break is detected. 11583@end table 11584@c @end group 11585 11586@node M32R/D 11587@subsection Mitsubishi M32R/D 11588 11589@table @code 11590 11591@kindex target m32r 11592@item target m32r @var{dev} 11593Mitsubishi M32R/D ROM monitor. 11594 11595@end table 11596 11597@node M68K 11598@subsection M68k 11599 11600The Motorola m68k configuration includes ColdFire support, and 11601target command for the following ROM monitors. 11602 11603@table @code 11604 11605@kindex target abug 11606@item target abug @var{dev} 11607ABug ROM monitor for M68K. 11608 11609@kindex target cpu32bug 11610@item target cpu32bug @var{dev} 11611CPU32BUG monitor, running on a CPU32 (M68K) board. 11612 11613@kindex target dbug 11614@item target dbug @var{dev} 11615dBUG ROM monitor for Motorola ColdFire. 11616 11617@kindex target est 11618@item target est @var{dev} 11619EST-300 ICE monitor, running on a CPU32 (M68K) board. 11620 11621@kindex target rom68k 11622@item target rom68k @var{dev} 11623ROM 68K monitor, running on an M68K IDP board. 11624 11625@end table 11626 11627If @value{GDBN} is configured with @code{m68*-ericsson-*}, it will 11628instead have only a single special target command: 11629 11630@table @code 11631 11632@kindex target es1800 11633@item target es1800 @var{dev} 11634ES-1800 emulator for M68K. 11635 11636@end table 11637 11638[context?] 11639 11640@table @code 11641 11642@kindex target rombug 11643@item target rombug @var{dev} 11644ROMBUG ROM monitor for OS/9000. 11645 11646@end table 11647 11648@node M88K 11649@subsection M88K 11650 11651@table @code 11652 11653@kindex target bug 11654@item target bug @var{dev} 11655BUG monitor, running on a MVME187 (m88k) board. 11656 11657@end table 11658 11659@node MIPS Embedded 11660@subsection MIPS Embedded 11661 11662@cindex MIPS boards 11663@value{GDBN} can use the MIPS remote debugging protocol to talk to a 11664MIPS board attached to a serial line. This is available when 11665you configure @value{GDBN} with @samp{--target=mips-idt-ecoff}. 11666 11667@need 1000 11668Use these @value{GDBN} commands to specify the connection to your target board: 11669 11670@table @code 11671@item target mips @var{port} 11672@kindex target mips @var{port} 11673To run a program on the board, start up @code{@value{GDBP}} with the 11674name of your program as the argument. To connect to the board, use the 11675command @samp{target mips @var{port}}, where @var{port} is the name of 11676the serial port connected to the board. If the program has not already 11677been downloaded to the board, you may use the @code{load} command to 11678download it. You can then use all the usual @value{GDBN} commands. 11679 11680For example, this sequence connects to the target board through a serial 11681port, and loads and runs a program called @var{prog} through the 11682debugger: 11683 11684@example 11685host$ @value{GDBP} @var{prog} 11686@value{GDBN} is free software and @dots{} 11687(@value{GDBP}) target mips /dev/ttyb 11688(@value{GDBP}) load @var{prog} 11689(@value{GDBP}) run 11690@end example 11691 11692@item target mips @var{hostname}:@var{portnumber} 11693On some @value{GDBN} host configurations, you can specify a TCP 11694connection (for instance, to a serial line managed by a terminal 11695concentrator) instead of a serial port, using the syntax 11696@samp{@var{hostname}:@var{portnumber}}. 11697 11698@item target pmon @var{port} 11699@kindex target pmon @var{port} 11700PMON ROM monitor. 11701 11702@item target ddb @var{port} 11703@kindex target ddb @var{port} 11704NEC's DDB variant of PMON for Vr4300. 11705 11706@item target lsi @var{port} 11707@kindex target lsi @var{port} 11708LSI variant of PMON. 11709 11710@kindex target r3900 11711@item target r3900 @var{dev} 11712Densan DVE-R3900 ROM monitor for Toshiba R3900 Mips. 11713 11714@kindex target array 11715@item target array @var{dev} 11716Array Tech LSI33K RAID controller board. 11717 11718@end table 11719 11720 11721@noindent 11722@value{GDBN} also supports these special commands for MIPS targets: 11723 11724@table @code 11725@item set processor @var{args} 11726@itemx show processor 11727@kindex set processor @var{args} 11728@kindex show processor 11729Use the @code{set processor} command to set the type of MIPS 11730processor when you want to access processor-type-specific registers. 11731For example, @code{set processor @var{r3041}} tells @value{GDBN} 11732to use the CPU registers appropriate for the 3041 chip. 11733Use the @code{show processor} command to see what MIPS processor @value{GDBN} 11734is using. Use the @code{info reg} command to see what registers 11735@value{GDBN} is using. 11736 11737@item set mipsfpu double 11738@itemx set mipsfpu single 11739@itemx set mipsfpu none 11740@itemx show mipsfpu 11741@kindex set mipsfpu 11742@kindex show mipsfpu 11743@cindex MIPS remote floating point 11744@cindex floating point, MIPS remote 11745If your target board does not support the MIPS floating point 11746coprocessor, you should use the command @samp{set mipsfpu none} (if you 11747need this, you may wish to put the command in your @value{GDBN} init 11748file). This tells @value{GDBN} how to find the return value of 11749functions which return floating point values. It also allows 11750@value{GDBN} to avoid saving the floating point registers when calling 11751functions on the board. If you are using a floating point coprocessor 11752with only single precision floating point support, as on the @sc{r4650} 11753processor, use the command @samp{set mipsfpu single}. The default 11754double precision floating point coprocessor may be selected using 11755@samp{set mipsfpu double}. 11756 11757In previous versions the only choices were double precision or no 11758floating point, so @samp{set mipsfpu on} will select double precision 11759and @samp{set mipsfpu off} will select no floating point. 11760 11761As usual, you can inquire about the @code{mipsfpu} variable with 11762@samp{show mipsfpu}. 11763 11764@item set remotedebug @var{n} 11765@itemx show remotedebug 11766@kindex set remotedebug@r{, MIPS protocol} 11767@kindex show remotedebug@r{, MIPS protocol} 11768@cindex @code{remotedebug}, MIPS protocol 11769@cindex MIPS @code{remotedebug} protocol 11770@c FIXME! For this to be useful, you must know something about the MIPS 11771@c FIXME...protocol. Where is it described? 11772You can see some debugging information about communications with the board 11773by setting the @code{remotedebug} variable. If you set it to @code{1} using 11774@samp{set remotedebug 1}, every packet is displayed. If you set it 11775to @code{2}, every character is displayed. You can check the current value 11776at any time with the command @samp{show remotedebug}. 11777 11778@item set timeout @var{seconds} 11779@itemx set retransmit-timeout @var{seconds} 11780@itemx show timeout 11781@itemx show retransmit-timeout 11782@cindex @code{timeout}, MIPS protocol 11783@cindex @code{retransmit-timeout}, MIPS protocol 11784@kindex set timeout 11785@kindex show timeout 11786@kindex set retransmit-timeout 11787@kindex show retransmit-timeout 11788You can control the timeout used while waiting for a packet, in the MIPS 11789remote protocol, with the @code{set timeout @var{seconds}} command. The 11790default is 5 seconds. Similarly, you can control the timeout used while 11791waiting for an acknowledgement of a packet with the @code{set 11792retransmit-timeout @var{seconds}} command. The default is 3 seconds. 11793You can inspect both values with @code{show timeout} and @code{show 11794retransmit-timeout}. (These commands are @emph{only} available when 11795@value{GDBN} is configured for @samp{--target=mips-idt-ecoff}.) 11796 11797The timeout set by @code{set timeout} does not apply when @value{GDBN} 11798is waiting for your program to stop. In that case, @value{GDBN} waits 11799forever because it has no way of knowing how long the program is going 11800to run before stopping. 11801@end table 11802 11803@node PowerPC 11804@subsection PowerPC 11805 11806@table @code 11807 11808@kindex target dink32 11809@item target dink32 @var{dev} 11810DINK32 ROM monitor. 11811 11812@kindex target ppcbug 11813@item target ppcbug @var{dev} 11814@kindex target ppcbug1 11815@item target ppcbug1 @var{dev} 11816PPCBUG ROM monitor for PowerPC. 11817 11818@kindex target sds 11819@item target sds @var{dev} 11820SDS monitor, running on a PowerPC board (such as Motorola's ADS). 11821 11822@end table 11823 11824@node PA 11825@subsection HP PA Embedded 11826 11827@table @code 11828 11829@kindex target op50n 11830@item target op50n @var{dev} 11831OP50N monitor, running on an OKI HPPA board. 11832 11833@kindex target w89k 11834@item target w89k @var{dev} 11835W89K monitor, running on a Winbond HPPA board. 11836 11837@end table 11838 11839@node SH 11840@subsection Hitachi SH 11841 11842@table @code 11843 11844@kindex target hms@r{, with Hitachi SH} 11845@item target hms @var{dev} 11846A Hitachi SH board attached via serial line to your host. Use special 11847commands @code{device} and @code{speed} to control the serial line and 11848the communications speed used. 11849 11850@kindex target e7000@r{, with Hitachi SH} 11851@item target e7000 @var{dev} 11852E7000 emulator for Hitachi SH. 11853 11854@kindex target sh3@r{, with SH} 11855@kindex target sh3e@r{, with SH} 11856@item target sh3 @var{dev} 11857@item target sh3e @var{dev} 11858Hitachi SH-3 and SH-3E target systems. 11859 11860@end table 11861 11862@node Sparclet 11863@subsection Tsqware Sparclet 11864 11865@cindex Sparclet 11866 11867@value{GDBN} enables developers to debug tasks running on 11868Sparclet targets from a Unix host. 11869@value{GDBN} uses code that runs on 11870both the Unix host and on the Sparclet target. The program 11871@code{@value{GDBP}} is installed and executed on the Unix host. 11872 11873@table @code 11874@item remotetimeout @var{args} 11875@kindex remotetimeout 11876@value{GDBN} supports the option @code{remotetimeout}. 11877This option is set by the user, and @var{args} represents the number of 11878seconds @value{GDBN} waits for responses. 11879@end table 11880 11881@cindex compiling, on Sparclet 11882When compiling for debugging, include the options @samp{-g} to get debug 11883information and @samp{-Ttext} to relocate the program to where you wish to 11884load it on the target. You may also want to add the options @samp{-n} or 11885@samp{-N} in order to reduce the size of the sections. Example: 11886 11887@example 11888sparclet-aout-gcc prog.c -Ttext 0x12010000 -g -o prog -N 11889@end example 11890 11891You can use @code{objdump} to verify that the addresses are what you intended: 11892 11893@example 11894sparclet-aout-objdump --headers --syms prog 11895@end example 11896 11897@cindex running, on Sparclet 11898Once you have set 11899your Unix execution search path to find @value{GDBN}, you are ready to 11900run @value{GDBN}. From your Unix host, run @code{@value{GDBP}} 11901(or @code{sparclet-aout-gdb}, depending on your installation). 11902 11903@value{GDBN} comes up showing the prompt: 11904 11905@example 11906(gdbslet) 11907@end example 11908 11909@menu 11910* Sparclet File:: Setting the file to debug 11911* Sparclet Connection:: Connecting to Sparclet 11912* Sparclet Download:: Sparclet download 11913* Sparclet Execution:: Running and debugging 11914@end menu 11915 11916@node Sparclet File 11917@subsubsection Setting file to debug 11918 11919The @value{GDBN} command @code{file} lets you choose with program to debug. 11920 11921@example 11922(gdbslet) file prog 11923@end example 11924 11925@need 1000 11926@value{GDBN} then attempts to read the symbol table of @file{prog}. 11927@value{GDBN} locates 11928the file by searching the directories listed in the command search 11929path. 11930If the file was compiled with debug information (option "-g"), source 11931files will be searched as well. 11932@value{GDBN} locates 11933the source files by searching the directories listed in the directory search 11934path (@pxref{Environment, ,Your program's environment}). 11935If it fails 11936to find a file, it displays a message such as: 11937 11938@example 11939prog: No such file or directory. 11940@end example 11941 11942When this happens, add the appropriate directories to the search paths with 11943the @value{GDBN} commands @code{path} and @code{dir}, and execute the 11944@code{target} command again. 11945 11946@node Sparclet Connection 11947@subsubsection Connecting to Sparclet 11948 11949The @value{GDBN} command @code{target} lets you connect to a Sparclet target. 11950To connect to a target on serial port ``@code{ttya}'', type: 11951 11952@example 11953(gdbslet) target sparclet /dev/ttya 11954Remote target sparclet connected to /dev/ttya 11955main () at ../prog.c:3 11956@end example 11957 11958@need 750 11959@value{GDBN} displays messages like these: 11960 11961@example 11962Connected to ttya. 11963@end example 11964 11965@node Sparclet Download 11966@subsubsection Sparclet download 11967 11968@cindex download to Sparclet 11969Once connected to the Sparclet target, 11970you can use the @value{GDBN} 11971@code{load} command to download the file from the host to the target. 11972The file name and load offset should be given as arguments to the @code{load} 11973command. 11974Since the file format is aout, the program must be loaded to the starting 11975address. You can use @code{objdump} to find out what this value is. The load 11976offset is an offset which is added to the VMA (virtual memory address) 11977of each of the file's sections. 11978For instance, if the program 11979@file{prog} was linked to text address 0x1201000, with data at 0x12010160 11980and bss at 0x12010170, in @value{GDBN}, type: 11981 11982@example 11983(gdbslet) load prog 0x12010000 11984Loading section .text, size 0xdb0 vma 0x12010000 11985@end example 11986 11987If the code is loaded at a different address then what the program was linked 11988to, you may need to use the @code{section} and @code{add-symbol-file} commands 11989to tell @value{GDBN} where to map the symbol table. 11990 11991@node Sparclet Execution 11992@subsubsection Running and debugging 11993 11994@cindex running and debugging Sparclet programs 11995You can now begin debugging the task using @value{GDBN}'s execution control 11996commands, @code{b}, @code{step}, @code{run}, etc. See the @value{GDBN} 11997manual for the list of commands. 11998 11999@example 12000(gdbslet) b main 12001Breakpoint 1 at 0x12010000: file prog.c, line 3. 12002(gdbslet) run 12003Starting program: prog 12004Breakpoint 1, main (argc=1, argv=0xeffff21c) at prog.c:3 120053 char *symarg = 0; 12006(gdbslet) step 120074 char *execarg = "hello!"; 12008(gdbslet) 12009@end example 12010 12011@node Sparclite 12012@subsection Fujitsu Sparclite 12013 12014@table @code 12015 12016@kindex target sparclite 12017@item target sparclite @var{dev} 12018Fujitsu sparclite boards, used only for the purpose of loading. 12019You must use an additional command to debug the program. 12020For example: target remote @var{dev} using @value{GDBN} standard 12021remote protocol. 12022 12023@end table 12024 12025@node ST2000 12026@subsection Tandem ST2000 12027 12028@value{GDBN} may be used with a Tandem ST2000 phone switch, running Tandem's 12029STDBUG protocol. 12030 12031To connect your ST2000 to the host system, see the manufacturer's 12032manual. Once the ST2000 is physically attached, you can run: 12033 12034@example 12035target st2000 @var{dev} @var{speed} 12036@end example 12037 12038@noindent 12039to establish it as your debugging environment. @var{dev} is normally 12040the name of a serial device, such as @file{/dev/ttya}, connected to the 12041ST2000 via a serial line. You can instead specify @var{dev} as a TCP 12042connection (for example, to a serial line attached via a terminal 12043concentrator) using the syntax @code{@var{hostname}:@var{portnumber}}. 12044 12045The @code{load} and @code{attach} commands are @emph{not} defined for 12046this target; you must load your program into the ST2000 as you normally 12047would for standalone operation. @value{GDBN} reads debugging information 12048(such as symbols) from a separate, debugging version of the program 12049available on your host computer. 12050@c FIXME!! This is terribly vague; what little content is here is 12051@c basically hearsay. 12052 12053@cindex ST2000 auxiliary commands 12054These auxiliary @value{GDBN} commands are available to help you with the ST2000 12055environment: 12056 12057@table @code 12058@item st2000 @var{command} 12059@kindex st2000 @var{cmd} 12060@cindex STDBUG commands (ST2000) 12061@cindex commands to STDBUG (ST2000) 12062Send a @var{command} to the STDBUG monitor. See the manufacturer's 12063manual for available commands. 12064 12065@item connect 12066@cindex connect (to STDBUG) 12067Connect the controlling terminal to the STDBUG command monitor. When 12068you are done interacting with STDBUG, typing either of two character 12069sequences gets you back to the @value{GDBN} command prompt: 12070@kbd{@key{RET}~.} (Return, followed by tilde and period) or 12071@kbd{@key{RET}~@key{C-d}} (Return, followed by tilde and control-D). 12072@end table 12073 12074@node Z8000 12075@subsection Zilog Z8000 12076 12077@cindex Z8000 12078@cindex simulator, Z8000 12079@cindex Zilog Z8000 simulator 12080 12081When configured for debugging Zilog Z8000 targets, @value{GDBN} includes 12082a Z8000 simulator. 12083 12084For the Z8000 family, @samp{target sim} simulates either the Z8002 (the 12085unsegmented variant of the Z8000 architecture) or the Z8001 (the 12086segmented variant). The simulator recognizes which architecture is 12087appropriate by inspecting the object code. 12088 12089@table @code 12090@item target sim @var{args} 12091@kindex sim 12092@kindex target sim@r{, with Z8000} 12093Debug programs on a simulated CPU. If the simulator supports setup 12094options, specify them via @var{args}. 12095@end table 12096 12097@noindent 12098After specifying this target, you can debug programs for the simulated 12099CPU in the same style as programs for your host computer; use the 12100@code{file} command to load a new program image, the @code{run} command 12101to run your program, and so on. 12102 12103As well as making available all the usual machine registers 12104(@pxref{Registers, ,Registers}), the Z8000 simulator provides three 12105additional items of information as specially named registers: 12106 12107@table @code 12108 12109@item cycles 12110Counts clock-ticks in the simulator. 12111 12112@item insts 12113Counts instructions run in the simulator. 12114 12115@item time 12116Execution time in 60ths of a second. 12117 12118@end table 12119 12120You can refer to these values in @value{GDBN} expressions with the usual 12121conventions; for example, @w{@samp{b fputc if $cycles>5000}} sets a 12122conditional breakpoint that suspends only after at least 5000 12123simulated clock ticks. 12124 12125@node Architectures 12126@section Architectures 12127 12128This section describes characteristics of architectures that affect 12129all uses of @value{GDBN} with the architecture, both native and cross. 12130 12131@menu 12132* A29K:: 12133* Alpha:: 12134* MIPS:: 12135@end menu 12136 12137@node A29K 12138@subsection A29K 12139 12140@table @code 12141 12142@kindex set rstack_high_address 12143@cindex AMD 29K register stack 12144@cindex register stack, AMD29K 12145@item set rstack_high_address @var{address} 12146On AMD 29000 family processors, registers are saved in a separate 12147@dfn{register stack}. There is no way for @value{GDBN} to determine the 12148extent of this stack. Normally, @value{GDBN} just assumes that the 12149stack is ``large enough''. This may result in @value{GDBN} referencing 12150memory locations that do not exist. If necessary, you can get around 12151this problem by specifying the ending address of the register stack with 12152the @code{set rstack_high_address} command. The argument should be an 12153address, which you probably want to precede with @samp{0x} to specify in 12154hexadecimal. 12155 12156@kindex show rstack_high_address 12157@item show rstack_high_address 12158Display the current limit of the register stack, on AMD 29000 family 12159processors. 12160 12161@end table 12162 12163@node Alpha 12164@subsection Alpha 12165 12166See the following section. 12167 12168@node MIPS 12169@subsection MIPS 12170 12171@cindex stack on Alpha 12172@cindex stack on MIPS 12173@cindex Alpha stack 12174@cindex MIPS stack 12175Alpha- and MIPS-based computers use an unusual stack frame, which 12176sometimes requires @value{GDBN} to search backward in the object code to 12177find the beginning of a function. 12178 12179@cindex response time, MIPS debugging 12180To improve response time (especially for embedded applications, where 12181@value{GDBN} may be restricted to a slow serial line for this search) 12182you may want to limit the size of this search, using one of these 12183commands: 12184 12185@table @code 12186@cindex @code{heuristic-fence-post} (Alpha, MIPS) 12187@item set heuristic-fence-post @var{limit} 12188Restrict @value{GDBN} to examining at most @var{limit} bytes in its 12189search for the beginning of a function. A value of @var{0} (the 12190default) means there is no limit. However, except for @var{0}, the 12191larger the limit the more bytes @code{heuristic-fence-post} must search 12192and therefore the longer it takes to run. 12193 12194@item show heuristic-fence-post 12195Display the current limit. 12196@end table 12197 12198@noindent 12199These commands are available @emph{only} when @value{GDBN} is configured 12200for debugging programs on Alpha or MIPS processors. 12201 12202 |
|
| 8827@node Controlling GDB 8828@chapter Controlling @value{GDBN} 8829 | 12203@node Controlling GDB 12204@chapter Controlling @value{GDBN} 12205 |
| 8830You can alter the way @value{GDBN} interacts with you by using 8831the @code{set} command. For commands controlling how @value{GDBN} displays 8832data, @pxref{Print Settings, ,Print settings}; other settings are described 8833here. | 12206You can alter the way @value{GDBN} interacts with you by using the 12207@code{set} command. For commands controlling how @value{GDBN} displays 12208data, see @ref{Print Settings, ,Print settings}. Other settings are 12209described here. |
| 8834 8835@menu 8836* Prompt:: Prompt 8837* Editing:: Command editing 8838* History:: Command history 8839* Screen Size:: Screen size 8840* Numbers:: Numbers 8841* Messages/Warnings:: Optional warnings and messages | 12210 12211@menu 12212* Prompt:: Prompt 12213* Editing:: Command editing 12214* History:: Command history 12215* Screen Size:: Screen size 12216* Numbers:: Numbers 12217* Messages/Warnings:: Optional warnings and messages |
| 12218* Debugging Output:: Optional messages about internal happenings |
|
| 8842@end menu 8843 | 12219@end menu 12220 |
| 8844@node Prompt, Editing, Controlling GDB, Controlling GDB | 12221@node Prompt |
| 8845@section Prompt 8846 8847@cindex prompt 8848 8849@value{GDBN} indicates its readiness to read a command by printing a string 8850called the @dfn{prompt}. This string is normally @samp{(@value{GDBP})}. You 8851can change the prompt string with the @code{set prompt} command. For 8852instance, when debugging @value{GDBN} with @value{GDBN}, it is useful to change | 12222@section Prompt 12223 12224@cindex prompt 12225 12226@value{GDBN} indicates its readiness to read a command by printing a string 12227called the @dfn{prompt}. This string is normally @samp{(@value{GDBP})}. You 12228can change the prompt string with the @code{set prompt} command. For 12229instance, when debugging @value{GDBN} with @value{GDBN}, it is useful to change |
| 8853the prompt in one of the @value{GDBN} sessions so that you can always tell | 12230the prompt in one of the @value{GDBN} sessions so that you can always tell |
| 8854which one you are talking to. 8855 | 12231which one you are talking to. 12232 |
| 8856@emph{Note:} @code{set prompt} no longer adds a space for you after the | 12233@emph{Note:} @code{set prompt} does not add a space for you after the |
| 8857prompt you set. This allows you to set a prompt which ends in a space 8858or a prompt that does not. 8859 8860@table @code 8861@kindex set prompt 8862@item set prompt @var{newprompt} 8863Directs @value{GDBN} to use @var{newprompt} as its prompt string henceforth. 8864 8865@kindex show prompt 8866@item show prompt 8867Prints a line of the form: @samp{Gdb's prompt is: @var{your-prompt}} 8868@end table 8869 | 12234prompt you set. This allows you to set a prompt which ends in a space 12235or a prompt that does not. 12236 12237@table @code 12238@kindex set prompt 12239@item set prompt @var{newprompt} 12240Directs @value{GDBN} to use @var{newprompt} as its prompt string henceforth. 12241 12242@kindex show prompt 12243@item show prompt 12244Prints a line of the form: @samp{Gdb's prompt is: @var{your-prompt}} 12245@end table 12246 |
| 8870@node Editing, History, Prompt, Controlling GDB | 12247@node Editing |
| 8871@section Command editing 8872@cindex readline 8873@cindex command line editing 8874 8875@value{GDBN} reads its input commands via the @dfn{readline} interface. This 8876@sc{gnu} library provides consistent behavior for programs which provide a 8877command line interface to the user. Advantages are @sc{gnu} Emacs-style 8878or @dfn{vi}-style inline editing of commands, @code{csh}-like history --- 13 unchanged lines hidden (view full) --- 8892@item set editing off 8893Disable command line editing. 8894 8895@kindex show editing 8896@item show editing 8897Show whether command line editing is enabled. 8898@end table 8899 | 12248@section Command editing 12249@cindex readline 12250@cindex command line editing 12251 12252@value{GDBN} reads its input commands via the @dfn{readline} interface. This 12253@sc{gnu} library provides consistent behavior for programs which provide a 12254command line interface to the user. Advantages are @sc{gnu} Emacs-style 12255or @dfn{vi}-style inline editing of commands, @code{csh}-like history --- 13 unchanged lines hidden (view full) --- 12269@item set editing off 12270Disable command line editing. 12271 12272@kindex show editing 12273@item show editing 12274Show whether command line editing is enabled. 12275@end table 12276 |
| 8900@node History, Screen Size, Editing, Controlling GDB | 12277@node History |
| 8901@section Command history 8902 8903@value{GDBN} can keep track of the commands you type during your 8904debugging sessions, so that you can be certain of precisely what 8905happened. Use these commands to manage the @value{GDBN} command 8906history facility. 8907 8908@table @code 8909@cindex history substitution 8910@cindex history file 8911@kindex set history filename 8912@kindex GDBHISTFILE 8913@item set history filename @var{fname} 8914Set the name of the @value{GDBN} command history file to @var{fname}. 8915This is the file where @value{GDBN} reads an initial command history 8916list, and where it writes the command history from this session when it 8917exits. You can access this list through history expansion or through 8918the history command editing characters listed below. This file defaults 8919to the value of the environment variable @code{GDBHISTFILE}, or to | 12278@section Command history 12279 12280@value{GDBN} can keep track of the commands you type during your 12281debugging sessions, so that you can be certain of precisely what 12282happened. Use these commands to manage the @value{GDBN} command 12283history facility. 12284 12285@table @code 12286@cindex history substitution 12287@cindex history file 12288@kindex set history filename 12289@kindex GDBHISTFILE 12290@item set history filename @var{fname} 12291Set the name of the @value{GDBN} command history file to @var{fname}. 12292This is the file where @value{GDBN} reads an initial command history 12293list, and where it writes the command history from this session when it 12294exits. You can access this list through history expansion or through 12295the history command editing characters listed below. This file defaults 12296to the value of the environment variable @code{GDBHISTFILE}, or to |
| 8920@file{./.gdb_history} if this variable is not set. | 12297@file{./.gdb_history} (@file{./_gdb_history} on MS-DOS) if this variable 12298is not set. |
| 8921 8922@cindex history save 8923@kindex set history save 8924@item set history save 8925@itemx set history save on 8926Record command history in a file, whose name may be specified with the 8927@code{set history filename} command. By default, this option is disabled. 8928 --- 48 unchanged lines hidden (view full) --- 8977@itemx show history size 8978@itemx show history expansion 8979These commands display the state of the @value{GDBN} history parameters. 8980@code{show history} by itself displays all four states. 8981@c @end group 8982@end table 8983 8984@table @code | 12299 12300@cindex history save 12301@kindex set history save 12302@item set history save 12303@itemx set history save on 12304Record command history in a file, whose name may be specified with the 12305@code{set history filename} command. By default, this option is disabled. 12306 --- 48 unchanged lines hidden (view full) --- 12355@itemx show history size 12356@itemx show history expansion 12357These commands display the state of the @value{GDBN} history parameters. 12358@code{show history} by itself displays all four states. 12359@c @end group 12360@end table 12361 12362@table @code |
| 8985@kindex show commands | 12363@kindex shows |
| 8986@item show commands 8987Display the last ten commands in the command history. 8988 8989@item show commands @var{n} 8990Print ten commands centered on command number @var{n}. 8991 8992@item show commands + 8993Print ten commands just after the commands last printed. 8994@end table 8995 | 12364@item show commands 12365Display the last ten commands in the command history. 12366 12367@item show commands @var{n} 12368Print ten commands centered on command number @var{n}. 12369 12370@item show commands + 12371Print ten commands just after the commands last printed. 12372@end table 12373 |
| 8996@node Screen Size, Numbers, History, Controlling GDB | 12374@node Screen Size |
| 8997@section Screen size 8998@cindex size of screen 8999@cindex pauses in output 9000 9001Certain commands to @value{GDBN} may produce large amounts of 9002information output to the screen. To help you read all of it, 9003@value{GDBN} pauses and asks you for input at the end of each page of 9004output. Type @key{RET} when you want to continue the output, or @kbd{q} 9005to discard the remaining output. Also, the screen width setting 9006determines when to wrap lines of output. Depending on what is being 9007printed, @value{GDBN} tries to break the line at a readable place, 9008rather than simply letting it overflow onto the following line. 9009 | 12375@section Screen size 12376@cindex size of screen 12377@cindex pauses in output 12378 12379Certain commands to @value{GDBN} may produce large amounts of 12380information output to the screen. To help you read all of it, 12381@value{GDBN} pauses and asks you for input at the end of each page of 12382output. Type @key{RET} when you want to continue the output, or @kbd{q} 12383to discard the remaining output. Also, the screen width setting 12384determines when to wrap lines of output. Depending on what is being 12385printed, @value{GDBN} tries to break the line at a readable place, 12386rather than simply letting it overflow onto the following line. 12387 |
| 9010Normally @value{GDBN} knows the size of the screen from the termcap data base | 12388Normally @value{GDBN} knows the size of the screen from the terminal 12389driver software. For example, on Unix @value{GDBN} uses the termcap data base |
| 9011together with the value of the @code{TERM} environment variable and the | 12390together with the value of the @code{TERM} environment variable and the |
| 9012@code{stty rows} and @code{stty cols} settings. If this is not correct, | 12391@code{stty rows} and @code{stty cols} settings. If this is not correct, |
| 9013you can override it with the @code{set height} and @code{set 9014width} commands: 9015 9016@table @code 9017@kindex set height 9018@kindex set width 9019@kindex show width 9020@kindex show height 9021@item set height @var{lpp} 9022@itemx show height 9023@itemx set width @var{cpl} 9024@itemx show width 9025These @code{set} commands specify a screen height of @var{lpp} lines and 9026a screen width of @var{cpl} characters. The associated @code{show} 9027commands display the current settings. 9028 | 12392you can override it with the @code{set height} and @code{set 12393width} commands: 12394 12395@table @code 12396@kindex set height 12397@kindex set width 12398@kindex show width 12399@kindex show height 12400@item set height @var{lpp} 12401@itemx show height 12402@itemx set width @var{cpl} 12403@itemx show width 12404These @code{set} commands specify a screen height of @var{lpp} lines and 12405a screen width of @var{cpl} characters. The associated @code{show} 12406commands display the current settings. 12407 |
| 9029If you specify a height of zero lines, @value{GDBN} does not pause during 9030output no matter how long the output is. This is useful if output is to a | 12408If you specify a height of zero lines, @value{GDBN} does not pause during 12409output no matter how long the output is. This is useful if output is to a |
| 9031file or to an editor buffer. 9032 9033Likewise, you can specify @samp{set width 0} to prevent @value{GDBN} 9034from wrapping its output. 9035@end table 9036 | 12410file or to an editor buffer. 12411 12412Likewise, you can specify @samp{set width 0} to prevent @value{GDBN} 12413from wrapping its output. 12414@end table 12415 |
| 9037@node Numbers, Messages/Warnings, Screen Size, Controlling GDB | 12416@node Numbers |
| 9038@section Numbers 9039@cindex number representation 9040@cindex entering numbers 9041 | 12417@section Numbers 12418@cindex number representation 12419@cindex entering numbers 12420 |
| 9042You can always enter numbers in octal, decimal, or hexadecimal in @value{GDBN} by 9043the usual conventions: octal numbers begin with @samp{0}, decimal 9044numbers end with @samp{.}, and hexadecimal numbers begin with @samp{0x}. 9045Numbers that begin with none of these are, by default, entered in base 904610; likewise, the default display for numbers---when no particular 9047format is specified---is base 10. You can change the default base for 9048both input and output with the @code{set radix} command. | 12421You can always enter numbers in octal, decimal, or hexadecimal in 12422@value{GDBN} by the usual conventions: octal numbers begin with 12423@samp{0}, decimal numbers end with @samp{.}, and hexadecimal numbers 12424begin with @samp{0x}. Numbers that begin with none of these are, by 12425default, entered in base 10; likewise, the default display for 12426numbers---when no particular format is specified---is base 10. You can 12427change the default base for both input and output with the @code{set 12428radix} command. |
| 9049 9050@table @code 9051@kindex set input-radix 9052@item set input-radix @var{base} 9053Set the default base for numeric input. Supported choices 9054for @var{base} are decimal 8, 10, or 16. @var{base} must itself be 9055specified either unambiguously or using the current default radix; for 9056example, any of --- 18 unchanged lines hidden (view full) --- 9075@item show input-radix 9076Display the current default base for numeric input. 9077 9078@kindex show output-radix 9079@item show output-radix 9080Display the current default base for numeric display. 9081@end table 9082 | 12429 12430@table @code 12431@kindex set input-radix 12432@item set input-radix @var{base} 12433Set the default base for numeric input. Supported choices 12434for @var{base} are decimal 8, 10, or 16. @var{base} must itself be 12435specified either unambiguously or using the current default radix; for 12436example, any of --- 18 unchanged lines hidden (view full) --- 12455@item show input-radix 12456Display the current default base for numeric input. 12457 12458@kindex show output-radix 12459@item show output-radix 12460Display the current default base for numeric display. 12461@end table 12462 |
| 9083@node Messages/Warnings, , Numbers, Controlling GDB | 12463@node Messages/Warnings |
| 9084@section Optional warnings and messages 9085 | 12464@section Optional warnings and messages 12465 |
| 9086By default, @value{GDBN} is silent about its inner workings. If you are running 9087on a slow machine, you may want to use the @code{set verbose} command. 9088This makes @value{GDBN} tell you when it does a lengthy internal operation, so 9089you will not think it has crashed. | 12466By default, @value{GDBN} is silent about its inner workings. If you are 12467running on a slow machine, you may want to use the @code{set verbose} 12468command. This makes @value{GDBN} tell you when it does a lengthy 12469internal operation, so you will not think it has crashed. |
| 9090 9091Currently, the messages controlled by @code{set verbose} are those 9092which announce that the symbol table for a source file is being read; 9093see @code{symbol-file} in @ref{Files, ,Commands to specify files}. 9094 9095@table @code 9096@kindex set verbose 9097@item set verbose on 9098Enables @value{GDBN} output of certain informational messages. 9099 9100@item set verbose off 9101Disables @value{GDBN} output of certain informational messages. 9102 9103@kindex show verbose 9104@item show verbose 9105Displays whether @code{set verbose} is on or off. 9106@end table 9107 | 12470 12471Currently, the messages controlled by @code{set verbose} are those 12472which announce that the symbol table for a source file is being read; 12473see @code{symbol-file} in @ref{Files, ,Commands to specify files}. 12474 12475@table @code 12476@kindex set verbose 12477@item set verbose on 12478Enables @value{GDBN} output of certain informational messages. 12479 12480@item set verbose off 12481Disables @value{GDBN} output of certain informational messages. 12482 12483@kindex show verbose 12484@item show verbose 12485Displays whether @code{set verbose} is on or off. 12486@end table 12487 |
| 9108By default, if @value{GDBN} encounters bugs in the symbol table of an object 9109file, it is silent; but if you are debugging a compiler, you may find 9110this information useful (@pxref{Symbol Errors, ,Errors reading symbol files}). | 12488By default, if @value{GDBN} encounters bugs in the symbol table of an 12489object file, it is silent; but if you are debugging a compiler, you may 12490find this information useful (@pxref{Symbol Errors, ,Errors reading 12491symbol files}). |
| 9111 9112@table @code | 12492 12493@table @code |
| 12494 |
|
| 9113@kindex set complaints 9114@item set complaints @var{limit} | 12495@kindex set complaints 12496@item set complaints @var{limit} |
| 9115Permits @value{GDBN} to output @var{limit} complaints about each type of unusual 9116symbols before becoming silent about the problem. Set @var{limit} to 9117zero to suppress all complaints; set it to a large number to prevent 9118complaints from being suppressed. | 12497Permits @value{GDBN} to output @var{limit} complaints about each type of 12498unusual symbols before becoming silent about the problem. Set 12499@var{limit} to zero to suppress all complaints; set it to a large number 12500to prevent complaints from being suppressed. |
| 9119 9120@kindex show complaints 9121@item show complaints 9122Displays how many symbol complaints @value{GDBN} is permitted to produce. | 12501 12502@kindex show complaints 12503@item show complaints 12504Displays how many symbol complaints @value{GDBN} is permitted to produce. |
| 12505 |
|
| 9123@end table 9124 9125By default, @value{GDBN} is cautious, and asks what sometimes seems to be a 9126lot of stupid questions to confirm certain commands. For example, if 9127you try to run a program which is already running: 9128 9129@example 9130(@value{GDBP}) run 9131The program being debugged has been started already. 9132Start it from the beginning? (y or n) 9133@end example 9134 9135If you are willing to unflinchingly face the consequences of your own 9136commands, you can disable this ``feature'': 9137 9138@table @code | 12506@end table 12507 12508By default, @value{GDBN} is cautious, and asks what sometimes seems to be a 12509lot of stupid questions to confirm certain commands. For example, if 12510you try to run a program which is already running: 12511 12512@example 12513(@value{GDBP}) run 12514The program being debugged has been started already. 12515Start it from the beginning? (y or n) 12516@end example 12517 12518If you are willing to unflinchingly face the consequences of your own 12519commands, you can disable this ``feature'': 12520 12521@table @code |
| 12522 |
|
| 9139@kindex set confirm 9140@cindex flinching 9141@cindex confirmation 9142@cindex stupid questions 9143@item set confirm off 9144Disables confirmation requests. 9145 9146@item set confirm on 9147Enables confirmation requests (the default). 9148 9149@kindex show confirm 9150@item show confirm 9151Displays state of confirmation requests. | 12523@kindex set confirm 12524@cindex flinching 12525@cindex confirmation 12526@cindex stupid questions 12527@item set confirm off 12528Disables confirmation requests. 12529 12530@item set confirm on 12531Enables confirmation requests (the default). 12532 12533@kindex show confirm 12534@item show confirm 12535Displays state of confirmation requests. |
| 12536 |
|
| 9152@end table 9153 | 12537@end table 12538 |
| 9154@node Sequences, Emacs, Controlling GDB, Top | 12539@node Debugging Output 12540@section Optional messages about internal happenings 12541@table @code 12542@kindex set debug arch 12543@item set debug arch 12544Turns on or off display of gdbarch debugging info. The default is off 12545@kindex show debug arch 12546@item show debug arch 12547Displays the current state of displaying gdbarch debugging info. 12548@kindex set debug event 12549@item set debug event 12550Turns on or off display of @value{GDBN} event debugging info. The 12551default is off. 12552@kindex show debug event 12553@item show debug event 12554Displays the current state of displaying @value{GDBN} event debugging 12555info. 12556@kindex set debug expression 12557@item set debug expression 12558Turns on or off display of @value{GDBN} expression debugging info. The 12559default is off. 12560@kindex show debug expression 12561@item show debug expression 12562Displays the current state of displaying @value{GDBN} expression 12563debugging info. 12564@kindex set debug overload 12565@item set debug overload 12566Turns on or off display of @value{GDBN} C@t{++} overload debugging 12567info. This includes info such as ranking of functions, etc. The default 12568is off. 12569@kindex show debug overload 12570@item show debug overload 12571Displays the current state of displaying @value{GDBN} C@t{++} overload 12572debugging info. 12573@kindex set debug remote 12574@cindex packets, reporting on stdout 12575@cindex serial connections, debugging 12576@item set debug remote 12577Turns on or off display of reports on all packets sent back and forth across 12578the serial line to the remote machine. The info is printed on the 12579@value{GDBN} standard output stream. The default is off. 12580@kindex show debug remote 12581@item show debug remote 12582Displays the state of display of remote packets. 12583@kindex set debug serial 12584@item set debug serial 12585Turns on or off display of @value{GDBN} serial debugging info. The 12586default is off. 12587@kindex show debug serial 12588@item show debug serial 12589Displays the current state of displaying @value{GDBN} serial debugging 12590info. 12591@kindex set debug target 12592@item set debug target 12593Turns on or off display of @value{GDBN} target debugging info. This info 12594includes what is going on at the target level of GDB, as it happens. The 12595default is off. 12596@kindex show debug target 12597@item show debug target 12598Displays the current state of displaying @value{GDBN} target debugging 12599info. 12600@kindex set debug varobj 12601@item set debug varobj 12602Turns on or off display of @value{GDBN} variable object debugging 12603info. The default is off. 12604@kindex show debug varobj 12605@item show debug varobj 12606Displays the current state of displaying @value{GDBN} variable object 12607debugging info. 12608@end table 12609 12610@node Sequences |
| 9155@chapter Canned Sequences of Commands 9156 9157Aside from breakpoint commands (@pxref{Break Commands, ,Breakpoint | 12611@chapter Canned Sequences of Commands 12612 12613Aside from breakpoint commands (@pxref{Break Commands, ,Breakpoint |
| 9158command lists}), @value{GDBN} provides two ways to store sequences of commands 9159for execution as a unit: user-defined commands and command files. | 12614command lists}), @value{GDBN} provides two ways to store sequences of 12615commands for execution as a unit: user-defined commands and command 12616files. |
| 9160 9161@menu 9162* Define:: User-defined commands 9163* Hooks:: User-defined command hooks 9164* Command Files:: Command files 9165* Output:: Commands for controlled output 9166@end menu 9167 | 12617 12618@menu 12619* Define:: User-defined commands 12620* Hooks:: User-defined command hooks 12621* Command Files:: Command files 12622* Output:: Commands for controlled output 12623@end menu 12624 |
| 9168@node Define, Hooks, Sequences, Sequences | 12625@node Define |
| 9169@section User-defined commands 9170 9171@cindex user-defined command | 12626@section User-defined commands 12627 12628@cindex user-defined command |
| 9172A @dfn{user-defined command} is a sequence of @value{GDBN} commands to which 9173you assign a new name as a command. This is done with the @code{define} 9174command. User commands may accept up to 10 arguments separated by whitespace. 9175Arguments are accessed within the user command via @var{$arg0@dots{}$arg9}. 9176A trivial example: | 12629A @dfn{user-defined command} is a sequence of @value{GDBN} commands to 12630which you assign a new name as a command. This is done with the 12631@code{define} command. User commands may accept up to 10 arguments 12632separated by whitespace. Arguments are accessed within the user command 12633via @var{$arg0@dots{}$arg9}. A trivial example: |
| 9177 9178@smallexample 9179define adder 9180 print $arg0 + $arg1 + $arg2 9181@end smallexample 9182 | 12634 12635@smallexample 12636define adder 12637 print $arg0 + $arg1 + $arg2 12638@end smallexample 12639 |
| 9183@noindent To execute the command use: | 12640@noindent 12641To execute the command use: |
| 9184 9185@smallexample 9186adder 1 2 3 9187@end smallexample 9188 | 12642 12643@smallexample 12644adder 1 2 3 12645@end smallexample 12646 |
| 9189@noindent This defines the command @code{adder}, which prints the sum of 9190its three arguments. Note the arguments are text substitutions, so they may | 12647@noindent 12648This defines the command @code{adder}, which prints the sum of 12649its three arguments. Note the arguments are text substitutions, so they may |
| 9191reference variables, use complex expressions, or even perform inferior 9192functions calls. 9193 9194@table @code | 12650reference variables, use complex expressions, or even perform inferior 12651functions calls. 12652 12653@table @code |
| 12654 |
|
| 9195@kindex define 9196@item define @var{commandname} 9197Define a command named @var{commandname}. If there is already a command 9198by that name, you are asked to confirm that you want to redefine it. 9199 9200The definition of the command is made up of other @value{GDBN} command lines, 9201which are given following the @code{define} command. The end of these 9202commands is marked by a line containing @code{end}. --- 14 unchanged lines hidden (view full) --- 9217which is an expression to evaluate, and must be followed by the commands to 9218execute, one per line, terminated by an @code{end}. 9219The commands are executed repeatedly as long as the expression 9220evaluates to true. 9221 9222@kindex document 9223@item document @var{commandname} 9224Document the user-defined command @var{commandname}, so that it can be | 12655@kindex define 12656@item define @var{commandname} 12657Define a command named @var{commandname}. If there is already a command 12658by that name, you are asked to confirm that you want to redefine it. 12659 12660The definition of the command is made up of other @value{GDBN} command lines, 12661which are given following the @code{define} command. The end of these 12662commands is marked by a line containing @code{end}. --- 14 unchanged lines hidden (view full) --- 12677which is an expression to evaluate, and must be followed by the commands to 12678execute, one per line, terminated by an @code{end}. 12679The commands are executed repeatedly as long as the expression 12680evaluates to true. 12681 12682@kindex document 12683@item document @var{commandname} 12684Document the user-defined command @var{commandname}, so that it can be |
| 9225accessed by @code{help}. The command @var{commandname} must already be 9226defined. This command reads lines of documentation just as @code{define} 9227reads the lines of the command definition, ending with @code{end}. 9228After the @code{document} command is finished, @code{help} on command | 12685accessed by @code{help}. The command @var{commandname} must already be 12686defined. This command reads lines of documentation just as @code{define} 12687reads the lines of the command definition, ending with @code{end}. 12688After the @code{document} command is finished, @code{help} on command |
| 9229@var{commandname} displays the documentation you have written. 9230 9231You may use the @code{document} command again to change the 9232documentation of a command. Redefining the command with @code{define} 9233does not change the documentation. 9234 9235@kindex help user-defined 9236@item help user-defined 9237List all user-defined commands, with the first line of the documentation 9238(if any) for each. 9239 9240@kindex show user 9241@item show user 9242@itemx show user @var{commandname} | 12689@var{commandname} displays the documentation you have written. 12690 12691You may use the @code{document} command again to change the 12692documentation of a command. Redefining the command with @code{define} 12693does not change the documentation. 12694 12695@kindex help user-defined 12696@item help user-defined 12697List all user-defined commands, with the first line of the documentation 12698(if any) for each. 12699 12700@kindex show user 12701@item show user 12702@itemx show user @var{commandname} |
| 9243Display the @value{GDBN} commands used to define @var{commandname} (but not its 9244documentation). If no @var{commandname} is given, display the | 12703Display the @value{GDBN} commands used to define @var{commandname} (but 12704not its documentation). If no @var{commandname} is given, display the |
| 9245definitions for all user-defined commands. | 12705definitions for all user-defined commands. |
| 12706 |
|
| 9246@end table 9247 9248When user-defined commands are executed, the 9249commands of the definition are not printed. An error in any command 9250stops execution of the user-defined command. 9251 9252If used interactively, commands that would ask for confirmation proceed | 12707@end table 12708 12709When user-defined commands are executed, the 12710commands of the definition are not printed. An error in any command 12711stops execution of the user-defined command. 12712 12713If used interactively, commands that would ask for confirmation proceed |
| 9253without asking when used inside a user-defined command. Many @value{GDBN} 9254commands that normally print messages to say what they are doing omit the | 12714without asking when used inside a user-defined command. Many @value{GDBN} 12715commands that normally print messages to say what they are doing omit the |
| 9255messages when used in a user-defined command. 9256 | 12716messages when used in a user-defined command. 12717 |
| 9257@node Hooks, Command Files, Define, Sequences | 12718@node Hooks |
| 9258@section User-defined command hooks | 12719@section User-defined command hooks |
| 9259@cindex command files | 12720@cindex command hooks 12721@cindex hooks, for commands 12722@cindex hooks, pre-command |
| 9260 | 12723 |
| 9261You may define @emph{hooks}, which are a special kind of user-defined | 12724@kindex hook 12725@kindex hook- 12726You may define @dfn{hooks}, which are a special kind of user-defined |
| 9262command. Whenever you run the command @samp{foo}, if the user-defined 9263command @samp{hook-foo} exists, it is executed (with no arguments) 9264before that command. 9265 | 12727command. Whenever you run the command @samp{foo}, if the user-defined 12728command @samp{hook-foo} exists, it is executed (with no arguments) 12729before that command. 12730 |
| 12731@cindex hooks, post-command 12732@kindex hookpost 12733@kindex hookpost- 12734A hook may also be defined which is run after the command you executed. 12735Whenever you run the command @samp{foo}, if the user-defined command 12736@samp{hookpost-foo} exists, it is executed (with no arguments) after 12737that command. Post-execution hooks may exist simultaneously with 12738pre-execution hooks, for the same command. 12739 12740It is valid for a hook to call the command which it hooks. If this 12741occurs, the hook is not re-executed, thereby avoiding infinte recursion. 12742 12743@c It would be nice if hookpost could be passed a parameter indicating 12744@c if the command it hooks executed properly or not. FIXME! 12745 12746@kindex stop@r{, a pseudo-command} |
|
| 9266In addition, a pseudo-command, @samp{stop} exists. Defining 9267(@samp{hook-stop}) makes the associated commands execute every time 9268execution stops in your program: before breakpoint commands are run, 9269displays are printed, or the stack frame is printed. 9270 | 12747In addition, a pseudo-command, @samp{stop} exists. Defining 12748(@samp{hook-stop}) makes the associated commands execute every time 12749execution stops in your program: before breakpoint commands are run, 12750displays are printed, or the stack frame is printed. 12751 |
| 9271@ifclear BARETARGET | |
| 9272For example, to ignore @code{SIGALRM} signals while 9273single-stepping, but treat them normally during normal execution, 9274you could define: 9275 9276@example 9277define hook-stop 9278handle SIGALRM nopass 9279end 9280 9281define hook-run 9282handle SIGALRM pass 9283end 9284 9285define hook-continue 9286handle SIGLARM pass 9287end 9288@end example | 12752For example, to ignore @code{SIGALRM} signals while 12753single-stepping, but treat them normally during normal execution, 12754you could define: 12755 12756@example 12757define hook-stop 12758handle SIGALRM nopass 12759end 12760 12761define hook-run 12762handle SIGALRM pass 12763end 12764 12765define hook-continue 12766handle SIGLARM pass 12767end 12768@end example |
| 9289@end ifclear | |
| 9290 | 12769 |
| 12770As a further example, to hook at the begining and end of the @code{echo} 12771command, and to add extra text to the beginning and end of the message, 12772you could define: 12773 12774@example 12775define hook-echo 12776echo <<<--- 12777end 12778 12779define hookpost-echo 12780echo --->>>\n 12781end 12782 12783(@value{GDBP}) echo Hello World 12784<<<---Hello World--->>> 12785(@value{GDBP}) 12786 12787@end example 12788 |
|
| 9291You can define a hook for any single-word command in @value{GDBN}, but 9292not for command aliases; you should define a hook for the basic command 9293name, e.g. @code{backtrace} rather than @code{bt}. 9294@c FIXME! So how does Joe User discover whether a command is an alias 9295@c or not? 9296If an error occurs during the execution of your hook, execution of 9297@value{GDBN} commands stops and @value{GDBN} issues a prompt 9298(before the command that you actually typed had a chance to run). 9299 9300If you try to define a hook which does not match any known command, you 9301get a warning from the @code{define} command. 9302 | 12789You can define a hook for any single-word command in @value{GDBN}, but 12790not for command aliases; you should define a hook for the basic command 12791name, e.g. @code{backtrace} rather than @code{bt}. 12792@c FIXME! So how does Joe User discover whether a command is an alias 12793@c or not? 12794If an error occurs during the execution of your hook, execution of 12795@value{GDBN} commands stops and @value{GDBN} issues a prompt 12796(before the command that you actually typed had a chance to run). 12797 12798If you try to define a hook which does not match any known command, you 12799get a warning from the @code{define} command. 12800 |
| 9303@node Command Files, Output, Hooks, Sequences | 12801@node Command Files |
| 9304@section Command files 9305 9306@cindex command files | 12802@section Command files 12803 12804@cindex command files |
| 9307A command file for @value{GDBN} is a file of lines that are @value{GDBN} 9308commands. Comments (lines starting with @kbd{#}) may also be included. 9309An empty line in a command file does nothing; it does not mean to repeat | 12805A command file for @value{GDBN} is a file of lines that are @value{GDBN} 12806commands. Comments (lines starting with @kbd{#}) may also be included. 12807An empty line in a command file does nothing; it does not mean to repeat |
| 9310the last command, as it would from the terminal. 9311 9312@cindex init file 9313@cindex @file{.gdbinit} | 12808the last command, as it would from the terminal. 12809 12810@cindex init file 12811@cindex @file{.gdbinit} |
| 12812@cindex @file{gdb.ini} |
|
| 9314When you start @value{GDBN}, it automatically executes commands from its | 12813When you start @value{GDBN}, it automatically executes commands from its |
| 9315@dfn{init files}. These are files named @file{.gdbinit} on Unix, or 9316@file{gdb.ini} on DOS/Windows. @value{GDBN} reads the init file (if 9317any) in your home directory, then processes command line options and 9318operands, and then reads the init file (if any) in the current working 9319directory. This is so the init file in your home directory can set 9320options (such as @code{set complaints}) which affect the processing of 9321the command line options and operands. The init files are not executed 9322if you use the @samp{-nx} option; @pxref{Mode Options, ,Choosing modes}. | 12814@dfn{init files}, normally called @file{.gdbinit}@footnote{The DJGPP 12815port of @value{GDBN} uses the name @file{gdb.ini} instead, due to the 12816limitations of file names imposed by DOS filesystems.}. 12817During startup, @value{GDBN} does the following: |
| 9323 | 12818 |
| 9324@ifset GENERIC | 12819@enumerate 12820@item 12821Reads the init file (if any) in your home directory@footnote{On 12822DOS/Windows systems, the home directory is the one pointed to by the 12823@code{HOME} environment variable.}. 12824 12825@item 12826Processes command line options and operands. 12827 12828@item 12829Reads the init file (if any) in the current working directory. 12830 12831@item 12832Reads command files specified by the @samp{-x} option. 12833@end enumerate 12834 12835The init file in your home directory can set options (such as @samp{set 12836complaints}) that affect subsequent processing of command line options 12837and operands. Init files are not executed if you use the @samp{-nx} 12838option (@pxref{Mode Options, ,Choosing modes}). 12839 |
| 9325@cindex init file name 9326On some configurations of @value{GDBN}, the init file is known by a 9327different name (these are typically environments where a specialized 9328form of @value{GDBN} may need to coexist with other forms, hence a 9329different name for the specialized version's init file). These are the 9330environments with special init file names: 9331 | 12840@cindex init file name 12841On some configurations of @value{GDBN}, the init file is known by a 12842different name (these are typically environments where a specialized 12843form of @value{GDBN} may need to coexist with other forms, hence a 12844different name for the specialized version's init file). These are the 12845environments with special init file names: 12846 |
| 9332@kindex .vxgdbinit | 12847@cindex @file{.vxgdbinit} |
| 9333@itemize @bullet 9334@item | 12848@itemize @bullet 12849@item |
| 9335VxWorks (Wind River Systems real-time OS): @samp{.vxgdbinit} | 12850VxWorks (Wind River Systems real-time OS): @file{.vxgdbinit} |
| 9336 | 12851 |
| 9337@kindex .os68gdbinit | 12852@cindex @file{.os68gdbinit} |
| 9338@item | 12853@item |
| 9339OS68K (Enea Data Systems real-time OS): @samp{.os68gdbinit} | 12854OS68K (Enea Data Systems real-time OS): @file{.os68gdbinit} |
| 9340 | 12855 |
| 9341@kindex .esgdbinit | 12856@cindex @file{.esgdbinit} |
| 9342@item | 12857@item |
| 9343ES-1800 (Ericsson Telecom AB M68000 emulator): @samp{.esgdbinit} | 12858ES-1800 (Ericsson Telecom AB M68000 emulator): @file{.esgdbinit} |
| 9344@end itemize | 12859@end itemize |
| 9345@end ifset | |
| 9346 9347You can also request the execution of a command file with the 9348@code{source} command: 9349 9350@table @code 9351@kindex source 9352@item source @var{filename} 9353Execute the command file @var{filename}. 9354@end table 9355 9356The lines in a command file are executed sequentially. They are not 9357printed as they are executed. An error in any command terminates execution 9358of the command file. 9359 9360Commands that would ask for confirmation if used interactively proceed 9361without asking when used in a command file. Many @value{GDBN} commands that 9362normally print messages to say what they are doing omit the messages 9363when called from command files. 9364 | 12860 12861You can also request the execution of a command file with the 12862@code{source} command: 12863 12864@table @code 12865@kindex source 12866@item source @var{filename} 12867Execute the command file @var{filename}. 12868@end table 12869 12870The lines in a command file are executed sequentially. They are not 12871printed as they are executed. An error in any command terminates execution 12872of the command file. 12873 12874Commands that would ask for confirmation if used interactively proceed 12875without asking when used in a command file. Many @value{GDBN} commands that 12876normally print messages to say what they are doing omit the messages 12877when called from command files. 12878 |
| 9365@node Output, , Command Files, Sequences | 12879@value{GDBN} also accepts command input from standard input. In this 12880mode, normal output goes to standard output and error output goes to 12881standard error. Errors in a command file supplied on standard input do 12882not terminate execution of the command file --- execution continues with 12883the next command. 12884 12885@example 12886gdb < cmds > log 2>&1 12887@end example 12888 12889(The syntax above will vary depending on the shell used.) This example 12890will execute commands from the file @file{cmds}. All output and errors 12891would be directed to @file{log}. 12892 12893@node Output |
| 9366@section Commands for controlled output 9367 9368During the execution of a command file or a user-defined command, normal 9369@value{GDBN} output is suppressed; the only output that appears is what is 9370explicitly printed by the commands in the definition. This section 9371describes three commands useful for generating exactly the output you 9372want. 9373 9374@table @code 9375@kindex echo 9376@item echo @var{text} 9377@c I do not consider backslash-space a standard C escape sequence 9378@c because it is not in ANSI. 9379Print @var{text}. Nonprinting characters can be included in 9380@var{text} using C escape sequences, such as @samp{\n} to print a 9381newline. @strong{No newline is printed unless you specify one.} 9382In addition to the standard C escape sequences, a backslash followed 9383by a space stands for a space. This is useful for displaying a 9384string with spaces at the beginning or the end, since leading and | 12894@section Commands for controlled output 12895 12896During the execution of a command file or a user-defined command, normal 12897@value{GDBN} output is suppressed; the only output that appears is what is 12898explicitly printed by the commands in the definition. This section 12899describes three commands useful for generating exactly the output you 12900want. 12901 12902@table @code 12903@kindex echo 12904@item echo @var{text} 12905@c I do not consider backslash-space a standard C escape sequence 12906@c because it is not in ANSI. 12907Print @var{text}. Nonprinting characters can be included in 12908@var{text} using C escape sequences, such as @samp{\n} to print a 12909newline. @strong{No newline is printed unless you specify one.} 12910In addition to the standard C escape sequences, a backslash followed 12911by a space stands for a space. This is useful for displaying a 12912string with spaces at the beginning or the end, since leading and |
| 9385trailing spaces are otherwise trimmed from all arguments. | 12913trailing spaces are otherwise trimmed from all arguments. |
| 9386To print @samp{@w{ }and foo =@w{ }}, use the command 9387@samp{echo \@w{ }and foo = \@w{ }}. 9388 9389A backslash at the end of @var{text} can be used, as in C, to continue 9390the command onto subsequent lines. For example, 9391 9392@example 9393echo This is some text\n\ --- 8 unchanged lines hidden (view full) --- 9402echo which is continued\n 9403echo onto several lines.\n 9404@end example 9405 9406@kindex output 9407@item output @var{expression} 9408Print the value of @var{expression} and nothing but that value: no 9409newlines, no @samp{$@var{nn} = }. The value is not entered in the | 12914To print @samp{@w{ }and foo =@w{ }}, use the command 12915@samp{echo \@w{ }and foo = \@w{ }}. 12916 12917A backslash at the end of @var{text} can be used, as in C, to continue 12918the command onto subsequent lines. For example, 12919 12920@example 12921echo This is some text\n\ --- 8 unchanged lines hidden (view full) --- 12930echo which is continued\n 12931echo onto several lines.\n 12932@end example 12933 12934@kindex output 12935@item output @var{expression} 12936Print the value of @var{expression} and nothing but that value: no 12937newlines, no @samp{$@var{nn} = }. The value is not entered in the |
| 9410value history either. @xref{Expressions, ,Expressions}, for more information | 12938value history either. @xref{Expressions, ,Expressions}, for more information |
| 9411on expressions. 9412 9413@item output/@var{fmt} @var{expression} 9414Print the value of @var{expression} in format @var{fmt}. You can use 9415the same formats as for @code{print}. @xref{Output Formats,,Output 9416formats}, for more information. 9417 9418@kindex printf 9419@item printf @var{string}, @var{expressions}@dots{} 9420Print the values of the @var{expressions} under the control of 9421@var{string}. The @var{expressions} are separated by commas and may be 9422either numbers or pointers. Their values are printed as specified by 9423@var{string}, exactly as if your program were to execute the C 9424subroutine | 12939on expressions. 12940 12941@item output/@var{fmt} @var{expression} 12942Print the value of @var{expression} in format @var{fmt}. You can use 12943the same formats as for @code{print}. @xref{Output Formats,,Output 12944formats}, for more information. 12945 12946@kindex printf 12947@item printf @var{string}, @var{expressions}@dots{} 12948Print the values of the @var{expressions} under the control of 12949@var{string}. The @var{expressions} are separated by commas and may be 12950either numbers or pointers. Their values are printed as specified by 12951@var{string}, exactly as if your program were to execute the C 12952subroutine |
| 12953@c FIXME: the above implies that at least all ANSI C formats are 12954@c supported, but it isn't true: %E and %G don't work (or so it seems). 12955@c Either this is a bug, or the manual should document what formats are 12956@c supported. |
|
| 9425 9426@example 9427printf (@var{string}, @var{expressions}@dots{}); 9428@end example 9429 9430For example, you can print two values in hex like this: 9431 9432@smallexample 9433printf "foo, bar-foo = 0x%x, 0x%x\n", foo, bar-foo 9434@end smallexample 9435 9436The only backslash-escape sequences that you can use in the format 9437string are the simple ones that consist of backslash followed by a 9438letter. 9439@end table 9440 | 12957 12958@example 12959printf (@var{string}, @var{expressions}@dots{}); 12960@end example 12961 12962For example, you can print two values in hex like this: 12963 12964@smallexample 12965printf "foo, bar-foo = 0x%x, 0x%x\n", foo, bar-foo 12966@end smallexample 12967 12968The only backslash-escape sequences that you can use in the format 12969string are the simple ones that consist of backslash followed by a 12970letter. 12971@end table 12972 |
| 9441@ifclear DOSHOST 9442@node Emacs, GDB Bugs, Sequences, Top | 12973@node TUI 12974@chapter @value{GDBN} Text User Interface 12975@cindex TUI 12976 12977@menu 12978* TUI Overview:: TUI overview 12979* TUI Keys:: TUI key bindings 12980* TUI Commands:: TUI specific commands 12981* TUI Configuration:: TUI configuration variables 12982@end menu 12983 12984The @value{GDBN} Text User Interface, TUI in short, 12985is a terminal interface which uses the @code{curses} library 12986to show the source file, the assembly output, the program registers 12987and @value{GDBN} commands in separate text windows. 12988The TUI is available only when @value{GDBN} is configured 12989with the @code{--enable-tui} configure option (@pxref{Configure Options}). 12990 12991@node TUI Overview 12992@section TUI overview 12993 12994The TUI has two display modes that can be switched while 12995@value{GDBN} runs: 12996 12997@itemize @bullet 12998@item 12999A curses (or TUI) mode in which it displays several text 13000windows on the terminal. 13001 13002@item 13003A standard mode which corresponds to the @value{GDBN} configured without 13004the TUI. 13005@end itemize 13006 13007In the TUI mode, @value{GDBN} can display several text window 13008on the terminal: 13009 13010@table @emph 13011@item command 13012This window is the @value{GDBN} command window with the @value{GDBN} 13013prompt and the @value{GDBN} outputs. The @value{GDBN} input is still 13014managed using readline but through the TUI. The @emph{command} 13015window is always visible. 13016 13017@item source 13018The source window shows the source file of the program. The current 13019line as well as active breakpoints are displayed in this window. 13020The current program position is shown with the @samp{>} marker and 13021active breakpoints are shown with @samp{*} markers. 13022 13023@item assembly 13024The assembly window shows the disassembly output of the program. 13025 13026@item register 13027This window shows the processor registers. It detects when 13028a register is changed and when this is the case, registers that have 13029changed are highlighted. 13030 13031@end table 13032 13033The source, assembly and register windows are attached to the thread 13034and the frame position. They are updated when the current thread 13035changes, when the frame changes or when the program counter changes. 13036These three windows are arranged by the TUI according to several 13037layouts. The layout defines which of these three windows are visible. 13038The following layouts are available: 13039 13040@itemize @bullet 13041@item 13042source 13043 13044@item 13045assembly 13046 13047@item 13048source and assembly 13049 13050@item 13051source and registers 13052 13053@item 13054assembly and registers 13055 13056@end itemize 13057 13058@node TUI Keys 13059@section TUI Key Bindings 13060@cindex TUI key bindings 13061 13062The TUI installs several key bindings in the readline keymaps 13063(@pxref{Command Line Editing}). 13064They allow to leave or enter in the TUI mode or they operate 13065directly on the TUI layout and windows. The following key bindings 13066are installed for both TUI mode and the @value{GDBN} standard mode. 13067 13068@table @kbd 13069@kindex C-x C-a 13070@item C-x C-a 13071@kindex C-x a 13072@itemx C-x a 13073@kindex C-x A 13074@itemx C-x A 13075Enter or leave the TUI mode. When the TUI mode is left, 13076the curses window management is left and @value{GDBN} operates using 13077its standard mode writing on the terminal directly. When the TUI 13078mode is entered, the control is given back to the curses windows. 13079The screen is then refreshed. 13080 13081@kindex C-x 1 13082@item C-x 1 13083Use a TUI layout with only one window. The layout will 13084either be @samp{source} or @samp{assembly}. When the TUI mode 13085is not active, it will switch to the TUI mode. 13086 13087Think of this key binding as the Emacs @kbd{C-x 1} binding. 13088 13089@kindex C-x 2 13090@item C-x 2 13091Use a TUI layout with at least two windows. When the current 13092layout shows already two windows, a next layout with two windows is used. 13093When a new layout is chosen, one window will always be common to the 13094previous layout and the new one. 13095 13096Think of it as the Emacs @kbd{C-x 2} binding. 13097 13098@end table 13099 13100The following key bindings are handled only by the TUI mode: 13101 13102@table @key 13103@kindex PgUp 13104@item PgUp 13105Scroll the active window one page up. 13106 13107@kindex PgDn 13108@item PgDn 13109Scroll the active window one page down. 13110 13111@kindex Up 13112@item Up 13113Scroll the active window one line up. 13114 13115@kindex Down 13116@item Down 13117Scroll the active window one line down. 13118 13119@kindex Left 13120@item Left 13121Scroll the active window one column left. 13122 13123@kindex Right 13124@item Right 13125Scroll the active window one column right. 13126 13127@kindex C-L 13128@item C-L 13129Refresh the screen. 13130 13131@end table 13132 13133In the TUI mode, the arrow keys are used by the active window 13134for scrolling. This means they are not available for readline. It is 13135necessary to use other readline key bindings such as @key{C-p}, @key{C-n}, 13136@key{C-b} and @key{C-f}. 13137 13138@node TUI Commands 13139@section TUI specific commands 13140@cindex TUI commands 13141 13142The TUI has specific commands to control the text windows. 13143These commands are always available, that is they do not depend on 13144the current terminal mode in which @value{GDBN} runs. When @value{GDBN} 13145is in the standard mode, using these commands will automatically switch 13146in the TUI mode. 13147 13148@table @code 13149@item layout next 13150@kindex layout next 13151Display the next layout. 13152 13153@item layout prev 13154@kindex layout prev 13155Display the previous layout. 13156 13157@item layout src 13158@kindex layout src 13159Display the source window only. 13160 13161@item layout asm 13162@kindex layout asm 13163Display the assembly window only. 13164 13165@item layout split 13166@kindex layout split 13167Display the source and assembly window. 13168 13169@item layout regs 13170@kindex layout regs 13171Display the register window together with the source or assembly window. 13172 13173@item focus next | prev | src | asm | regs | split 13174@kindex focus 13175Set the focus to the named window. 13176This command allows to change the active window so that scrolling keys 13177can be affected to another window. 13178 13179@item refresh 13180@kindex refresh 13181Refresh the screen. This is similar to using @key{C-L} key. 13182 13183@item update 13184@kindex update 13185Update the source window and the current execution point. 13186 13187@item winheight @var{name} +@var{count} 13188@itemx winheight @var{name} -@var{count} 13189@kindex winheight 13190Change the height of the window @var{name} by @var{count} 13191lines. Positive counts increase the height, while negative counts 13192decrease it. 13193 13194@end table 13195 13196@node TUI Configuration 13197@section TUI configuration variables 13198@cindex TUI configuration variables 13199 13200The TUI has several configuration variables that control the 13201appearance of windows on the terminal. 13202 13203@table @code 13204@item set tui border-kind @var{kind} 13205@kindex set tui border-kind 13206Select the border appearance for the source, assembly and register windows. 13207The possible values are the following: 13208@table @code 13209@item space 13210Use a space character to draw the border. 13211 13212@item ascii 13213Use ascii characters + - and | to draw the border. 13214 13215@item acs 13216Use the Alternate Character Set to draw the border. The border is 13217drawn using character line graphics if the terminal supports them. 13218 13219@end table 13220 13221@item set tui active-border-mode @var{mode} 13222@kindex set tui active-border-mode 13223Select the attributes to display the border of the active window. 13224The possible values are @code{normal}, @code{standout}, @code{reverse}, 13225@code{half}, @code{half-standout}, @code{bold} and @code{bold-standout}. 13226 13227@item set tui border-mode @var{mode} 13228@kindex set tui border-mode 13229Select the attributes to display the border of other windows. 13230The @var{mode} can be one of the following: 13231@table @code 13232@item normal 13233Use normal attributes to display the border. 13234 13235@item standout 13236Use standout mode. 13237 13238@item reverse 13239Use reverse video mode. 13240 13241@item half 13242Use half bright mode. 13243 13244@item half-standout 13245Use half bright and standout mode. 13246 13247@item bold 13248Use extra bright or bold mode. 13249 13250@item bold-standout 13251Use extra bright or bold and standout mode. 13252 13253@end table 13254 13255@end table 13256 13257@node Emacs |
| 9443@chapter Using @value{GDBN} under @sc{gnu} Emacs 9444 9445@cindex Emacs 9446@cindex @sc{gnu} Emacs 9447A special interface allows you to use @sc{gnu} Emacs to view (and 9448edit) the source files for the program you are debugging with 9449@value{GDBN}. 9450 9451To use this interface, use the command @kbd{M-x gdb} in Emacs. Give the 9452executable file you want to debug as an argument. This command starts 9453@value{GDBN} as a subprocess of Emacs, with input and output through a newly 9454created Emacs buffer. | 13258@chapter Using @value{GDBN} under @sc{gnu} Emacs 13259 13260@cindex Emacs 13261@cindex @sc{gnu} Emacs 13262A special interface allows you to use @sc{gnu} Emacs to view (and 13263edit) the source files for the program you are debugging with 13264@value{GDBN}. 13265 13266To use this interface, use the command @kbd{M-x gdb} in Emacs. Give the 13267executable file you want to debug as an argument. This command starts 13268@value{GDBN} as a subprocess of Emacs, with input and output through a newly 13269created Emacs buffer. |
| 9455@ifset HPPA 9456(Do not use the @code{-tui} option to run @value{GDBN} from Emacs.) 9457@end ifset | 13270@c (Do not use the @code{-tui} option to run @value{GDBN} from Emacs.) |
| 9458 9459Using @value{GDBN} under Emacs is just like using @value{GDBN} normally except for two 9460things: 9461 9462@itemize @bullet 9463@item 9464All ``terminal'' input and output goes through the Emacs buffer. 9465@end itemize --- 46 unchanged lines hidden (view full) --- 9512several configurations around, with different names) you can set the 9513Emacs variable @code{gdb-command-name}; for example, 9514 9515@example 9516(setq gdb-command-name "mygdb") 9517@end example 9518 9519@noindent | 13271 13272Using @value{GDBN} under Emacs is just like using @value{GDBN} normally except for two 13273things: 13274 13275@itemize @bullet 13276@item 13277All ``terminal'' input and output goes through the Emacs buffer. 13278@end itemize --- 46 unchanged lines hidden (view full) --- 13325several configurations around, with different names) you can set the 13326Emacs variable @code{gdb-command-name}; for example, 13327 13328@example 13329(setq gdb-command-name "mygdb") 13330@end example 13331 13332@noindent |
| 9520(preceded by @kbd{ESC ESC}, or typed in the @code{*scratch*} buffer, or | 13333(preceded by @kbd{M-:} or @kbd{ESC :}, or typed in the @code{*scratch*} buffer, or |
| 9521in your @file{.emacs} file) makes Emacs call the program named 9522``@code{mygdb}'' instead. 9523 9524In the @value{GDBN} I/O buffer, you can use these special Emacs commands in 9525addition to the standard Shell mode commands: 9526 9527@table @kbd 9528@item C-h m --- 74 unchanged lines hidden (view full) --- 9603 9604@c The following dropped because Epoch is nonstandard. Reactivate 9605@c if/when v19 does something similar. ---doc@cygnus.com 19dec1990 9606@ignore 9607@kindex Emacs Epoch environment 9608@kindex Epoch 9609@kindex inspect 9610 | 13334in your @file{.emacs} file) makes Emacs call the program named 13335``@code{mygdb}'' instead. 13336 13337In the @value{GDBN} I/O buffer, you can use these special Emacs commands in 13338addition to the standard Shell mode commands: 13339 13340@table @kbd 13341@item C-h m --- 74 unchanged lines hidden (view full) --- 13416 13417@c The following dropped because Epoch is nonstandard. Reactivate 13418@c if/when v19 does something similar. ---doc@cygnus.com 19dec1990 13419@ignore 13420@kindex Emacs Epoch environment 13421@kindex Epoch 13422@kindex inspect 13423 |
| 9611Version 18 of @sc{gnu} Emacs has a built-in window system | 13424Version 18 of @sc{gnu} Emacs has a built-in window system |
| 9612called the @code{epoch} 9613environment. Users of this environment can use a new command, 9614@code{inspect} which performs identically to @code{print} except that 9615each value is printed in its own window. 9616@end ignore | 13425called the @code{epoch} 13426environment. Users of this environment can use a new command, 13427@code{inspect} which performs identically to @code{print} except that 13428each value is printed in its own window. 13429@end ignore |
| 9617@end ifclear | |
| 9618 | 13430 |
| 13431@include annotate.texi 13432@include gdbmi.texinfo 13433 |
|
| 9619@node GDB Bugs | 13434@node GDB Bugs |
| 9620@c links whacked to pacify makeinfo 9621@c , Command Line Editing, Emacs, Top | |
| 9622@chapter Reporting Bugs in @value{GDBN} 9623@cindex bugs in @value{GDBN} 9624@cindex reporting bugs in @value{GDBN} 9625 9626Your bug reports play an essential role in making @value{GDBN} reliable. 9627 9628Reporting a bug may help you by bringing a solution to your problem, or it 9629may not. But in any case the principal function of a bug report is to help 9630the entire community by making the next version of @value{GDBN} work better. Bug 9631reports are your contribution to the maintenance of @value{GDBN}. 9632 9633In order for a bug report to serve its purpose, you must include the 9634information that enables us to fix the bug. 9635 9636@menu 9637* Bug Criteria:: Have you found a bug? 9638* Bug Reporting:: How to report bugs 9639@end menu 9640 | 13435@chapter Reporting Bugs in @value{GDBN} 13436@cindex bugs in @value{GDBN} 13437@cindex reporting bugs in @value{GDBN} 13438 13439Your bug reports play an essential role in making @value{GDBN} reliable. 13440 13441Reporting a bug may help you by bringing a solution to your problem, or it 13442may not. But in any case the principal function of a bug report is to help 13443the entire community by making the next version of @value{GDBN} work better. Bug 13444reports are your contribution to the maintenance of @value{GDBN}. 13445 13446In order for a bug report to serve its purpose, you must include the 13447information that enables us to fix the bug. 13448 13449@menu 13450* Bug Criteria:: Have you found a bug? 13451* Bug Reporting:: How to report bugs 13452@end menu 13453 |
| 9641@node Bug Criteria, Bug Reporting, GDB Bugs, GDB Bugs | 13454@node Bug Criteria |
| 9642@section Have you found a bug? 9643@cindex bug criteria 9644 9645If you are not sure whether you have found a bug, here are some guidelines: 9646 9647@itemize @bullet 9648@cindex fatal signal 9649@cindex debugger crash --- 15 unchanged lines hidden (view full) --- 9665``invalid input'' might be our idea of ``an extension'' or ``support 9666for traditional practice''. 9667 9668@item 9669If you are an experienced user of debugging tools, your suggestions 9670for improvement of @value{GDBN} are welcome in any case. 9671@end itemize 9672 | 13455@section Have you found a bug? 13456@cindex bug criteria 13457 13458If you are not sure whether you have found a bug, here are some guidelines: 13459 13460@itemize @bullet 13461@cindex fatal signal 13462@cindex debugger crash --- 15 unchanged lines hidden (view full) --- 13478``invalid input'' might be our idea of ``an extension'' or ``support 13479for traditional practice''. 13480 13481@item 13482If you are an experienced user of debugging tools, your suggestions 13483for improvement of @value{GDBN} are welcome in any case. 13484@end itemize 13485 |
| 9673@node Bug Reporting, , Bug Criteria, GDB Bugs | 13486@node Bug Reporting |
| 9674@section How to report bugs 9675@cindex bug reports 9676@cindex @value{GDBN} bugs, reporting 9677 | 13487@section How to report bugs 13488@cindex bug reports 13489@cindex @value{GDBN} bugs, reporting 13490 |
| 9678@ifclear HPPA | |
| 9679A number of companies and individuals offer support for @sc{gnu} products. 9680If you obtained @value{GDBN} from a support organization, we recommend you 9681contact that organization first. 9682 9683You can find contact information for many support companies and 9684individuals in the file @file{etc/SERVICE} in the @sc{gnu} Emacs 9685distribution. 9686@c should add a web page ref... 9687 | 13491A number of companies and individuals offer support for @sc{gnu} products. 13492If you obtained @value{GDBN} from a support organization, we recommend you 13493contact that organization first. 13494 13495You can find contact information for many support companies and 13496individuals in the file @file{etc/SERVICE} in the @sc{gnu} Emacs 13497distribution. 13498@c should add a web page ref... 13499 |
| 9688In any event, we also recommend that you send bug reports for 9689@value{GDBN} to this addresses: | 13500In any event, we also recommend that you submit bug reports for 13501@value{GDBN}. The prefered method is to submit them directly using 13502@uref{http://www.gnu.org/software/gdb/bugs/, @value{GDBN}'s Bugs web 13503page}. Alternatively, the @email{bug-gdb@@gnu.org, e-mail gateway} can 13504be used. |
| 9690 | 13505 |
| 9691@example 9692bug-gdb@@prep.ai.mit.edu 9693@end example 9694 | |
| 9695@strong{Do not send bug reports to @samp{info-gdb}, or to | 13506@strong{Do not send bug reports to @samp{info-gdb}, or to |
| 9696@samp{help-gdb}, or to any newsgroups.} Most users of @value{GDBN} do | 13507@samp{help-gdb}, or to any newsgroups.} Most users of @value{GDBN} do |
| 9697not want to receive bug reports. Those that do have arranged to receive 9698@samp{bug-gdb}. 9699 9700The mailing list @samp{bug-gdb} has a newsgroup @samp{gnu.gdb.bug} which 9701serves as a repeater. The mailing list and the newsgroup carry exactly 9702the same messages. Often people think of posting bug reports to the 9703newsgroup instead of mailing them. This appears to work, but it has one 9704problem which can be crucial: a newsgroup posting often lacks a mail 9705path back to the sender. Thus, if we need to ask for more information, 9706we may be unable to reach you. For this reason, it is better to send 9707bug reports to the mailing list. 9708 | 13508not want to receive bug reports. Those that do have arranged to receive 13509@samp{bug-gdb}. 13510 13511The mailing list @samp{bug-gdb} has a newsgroup @samp{gnu.gdb.bug} which 13512serves as a repeater. The mailing list and the newsgroup carry exactly 13513the same messages. Often people think of posting bug reports to the 13514newsgroup instead of mailing them. This appears to work, but it has one 13515problem which can be crucial: a newsgroup posting often lacks a mail 13516path back to the sender. Thus, if we need to ask for more information, 13517we may be unable to reach you. For this reason, it is better to send 13518bug reports to the mailing list. 13519 |
| 9709As a last resort, send bug reports on paper to: 9710 9711@example 9712@sc{gnu} Debugger Bugs 9713Free Software Foundation Inc. 971459 Temple Place - Suite 330 9715Boston, MA 02111-1307 9716USA 9717@end example 9718@end ifclear 9719 9720@ifset HPPA 9721If you obtained HP GDB as part of your HP ANSI C or HP ANSI C++ compiler 9722kit, report problems to your HP Support Representative. 9723 9724If you obtained HP GDB from the Hewlett-Packard Web site, report 9725problems by electronic mail to @code{wdb-www@@ch.hp.com}. 9726@end ifset 9727 | |
| 9728The fundamental principle of reporting bugs usefully is this: 9729@strong{report all the facts}. If you are not sure whether to state a 9730fact or leave it out, state it! 9731 9732Often people omit facts because they think they know what causes the 9733problem and assume that some details do not matter. Thus, you might 9734assume that the name of the variable you use in an example does not matter. 9735Well, probably it does not, but one cannot be sure. Perhaps the bug is a --- 23 unchanged lines hidden (view full) --- 9759 9760Without this, we will not know whether there is any point in looking for 9761the bug in the current version of @value{GDBN}. 9762 9763@item 9764The type of machine you are using, and the operating system name and 9765version number. 9766 | 13520The fundamental principle of reporting bugs usefully is this: 13521@strong{report all the facts}. If you are not sure whether to state a 13522fact or leave it out, state it! 13523 13524Often people omit facts because they think they know what causes the 13525problem and assume that some details do not matter. Thus, you might 13526assume that the name of the variable you use in an example does not matter. 13527Well, probably it does not, but one cannot be sure. Perhaps the bug is a --- 23 unchanged lines hidden (view full) --- 13551 13552Without this, we will not know whether there is any point in looking for 13553the bug in the current version of @value{GDBN}. 13554 13555@item 13556The type of machine you are using, and the operating system name and 13557version number. 13558 |
| 9767@ifclear HPPA | |
| 9768@item 9769What compiler (and its version) was used to compile @value{GDBN}---e.g. 9770``@value{GCC}--2.8.1''. | 13559@item 13560What compiler (and its version) was used to compile @value{GDBN}---e.g. 13561``@value{GCC}--2.8.1''. |
| 9771@end ifclear | |
| 9772 9773@item 9774What compiler (and its version) was used to compile the program you are 9775debugging---e.g. ``@value{GCC}--2.8.1'', or ``HP92453-01 A.10.32.03 HP 9776C Compiler''. For GCC, you can say @code{gcc --version} to get this 9777information; for other compilers, see the documentation for those 9778compilers. 9779 --- 23 unchanged lines hidden (view full) --- 9803say so explicitly. Suppose something strange is going on, such as, your 9804copy of @value{GDBN} is out of synch, or you have encountered a bug in 9805the C library on your system. (This has happened!) Your copy might 9806crash and ours would not. If you told us to expect a crash, then when 9807ours fails to crash, we would know that the bug was not happening for 9808us. If you had not told us to expect a crash, then we would not be able 9809to draw any conclusion from our observations. 9810 | 13562 13563@item 13564What compiler (and its version) was used to compile the program you are 13565debugging---e.g. ``@value{GCC}--2.8.1'', or ``HP92453-01 A.10.32.03 HP 13566C Compiler''. For GCC, you can say @code{gcc --version} to get this 13567information; for other compilers, see the documentation for those 13568compilers. 13569 --- 23 unchanged lines hidden (view full) --- 13593say so explicitly. Suppose something strange is going on, such as, your 13594copy of @value{GDBN} is out of synch, or you have encountered a bug in 13595the C library on your system. (This has happened!) Your copy might 13596crash and ours would not. If you told us to expect a crash, then when 13597ours fails to crash, we would know that the bug was not happening for 13598us. If you had not told us to expect a crash, then we would not be able 13599to draw any conclusion from our observations. 13600 |
| 9811@ifclear HPPA | |
| 9812@item 9813If you wish to suggest changes to the @value{GDBN} source, send us context 9814diffs. If you even discuss something in the @value{GDBN} source, refer to 9815it by context, not by line number. 9816 9817The line numbers in our development sources will not match those in your 9818sources. Your line numbers would convey no useful information to us. | 13601@item 13602If you wish to suggest changes to the @value{GDBN} source, send us context 13603diffs. If you even discuss something in the @value{GDBN} source, refer to 13604it by context, not by line number. 13605 13606The line numbers in our development sources will not match those in your 13607sources. Your line numbers would convey no useful information to us. |
| 9819@end ifclear | 13608 |
| 9820@end itemize 9821 9822Here are some things that are not necessary: 9823 9824@itemize @bullet 9825@item 9826A description of the envelope of the bug. 9827 --- 33 unchanged lines hidden (view full) --- 9861 9862@item 9863A guess about what the bug is or what it depends on. 9864 9865Such guesses are usually wrong. Even we cannot guess right about such 9866things without first using the debugger to find the facts. 9867@end itemize 9868 | 13609@end itemize 13610 13611Here are some things that are not necessary: 13612 13613@itemize @bullet 13614@item 13615A description of the envelope of the bug. 13616 --- 33 unchanged lines hidden (view full) --- 13650 13651@item 13652A guess about what the bug is or what it depends on. 13653 13654Such guesses are usually wrong. Even we cannot guess right about such 13655things without first using the debugger to find the facts. 13656@end itemize 13657 |
| 9869@c The readline documentation is distributed with the readline code | 13658@c The readline documentation is distributed with the readline code |
| 9870@c and consists of the two following files: 9871@c rluser.texinfo | 13659@c and consists of the two following files: 13660@c rluser.texinfo |
| 9872@c inc-hist.texi | 13661@c inc-hist.texinfo |
| 9873@c Use -I with makeinfo to point to the appropriate directory, 9874@c environment var TEXINPUTS with TeX. 9875@include rluser.texinfo | 13662@c Use -I with makeinfo to point to the appropriate directory, 13663@c environment var TEXINPUTS with TeX. 13664@include rluser.texinfo |
| 9876@include inc-hist.texi | 13665@include inc-hist.texinfo |
| 9877 9878 | 13666 13667 |
| 9879@ifclear PRECONFIGURED 9880@ifclear HPPA | |
| 9881@node Formatting Documentation | 13668@node Formatting Documentation |
| 9882@c links whacked to pacify makeinfo 9883@c , Installing GDB, Renamed Commands, Top | |
| 9884@appendix Formatting Documentation 9885 9886@cindex @value{GDBN} reference card 9887@cindex reference card 9888The @value{GDBN} 4 release includes an already-formatted reference card, ready 9889for printing with PostScript or Ghostscript, in the @file{gdb} 9890subdirectory of the main source directory@footnote{In 9891@file{gdb-@value{GDBVN}/gdb/refcard.ps} of the version @value{GDBVN} 9892release.}. If you can use PostScript or Ghostscript with your printer, 9893you can print the reference card immediately with @file{refcard.ps}. 9894 9895The release also includes the source for the reference card. You 9896can format it, using @TeX{}, by typing: 9897 9898@example 9899make refcard.dvi 9900@end example 9901 | 13669@appendix Formatting Documentation 13670 13671@cindex @value{GDBN} reference card 13672@cindex reference card 13673The @value{GDBN} 4 release includes an already-formatted reference card, ready 13674for printing with PostScript or Ghostscript, in the @file{gdb} 13675subdirectory of the main source directory@footnote{In 13676@file{gdb-@value{GDBVN}/gdb/refcard.ps} of the version @value{GDBVN} 13677release.}. If you can use PostScript or Ghostscript with your printer, 13678you can print the reference card immediately with @file{refcard.ps}. 13679 13680The release also includes the source for the reference card. You 13681can format it, using @TeX{}, by typing: 13682 13683@example 13684make refcard.dvi 13685@end example 13686 |
| 9902The @value{GDBN} reference card is designed to print in @dfn{landscape} 9903mode on US ``letter'' size paper; | 13687The @value{GDBN} reference card is designed to print in @dfn{landscape} 13688mode on US ``letter'' size paper; |
| 9904that is, on a sheet 11 inches wide by 8.5 inches 9905high. You will need to specify this form of printing as an option to 9906your @sc{dvi} output program. 9907 9908@cindex documentation 9909 9910All the documentation for @value{GDBN} comes as part of the machine-readable 9911distribution. The documentation is written in Texinfo format, which is --- 48 unchanged lines hidden (view full) --- 9960subdirectory of the main source directory (for example, to 9961@file{gdb-@value{GDBVN}/gdb}) and type: 9962 9963@example 9964make gdb.dvi 9965@end example 9966 9967Then give @file{gdb.dvi} to your @sc{dvi} printing program. | 13689that is, on a sheet 11 inches wide by 8.5 inches 13690high. You will need to specify this form of printing as an option to 13691your @sc{dvi} output program. 13692 13693@cindex documentation 13694 13695All the documentation for @value{GDBN} comes as part of the machine-readable 13696distribution. The documentation is written in Texinfo format, which is --- 48 unchanged lines hidden (view full) --- 13745subdirectory of the main source directory (for example, to 13746@file{gdb-@value{GDBVN}/gdb}) and type: 13747 13748@example 13749make gdb.dvi 13750@end example 13751 13752Then give @file{gdb.dvi} to your @sc{dvi} printing program. |
| 9968@end ifclear | |
| 9969 | 13753 |
| 9970@node Installing GDB, Index, Using History Interactively, Top | 13754@node Installing GDB |
| 9971@appendix Installing @value{GDBN} 9972@cindex configuring @value{GDBN} 9973@cindex installation 9974 | 13755@appendix Installing @value{GDBN} 13756@cindex configuring @value{GDBN} 13757@cindex installation 13758 |
| 9975@ifset HPPA 9976If you obtain @value{GDBN} (HP WDB 0.75) as part of your HP ANSI C or 9977HP ANSI C++ Developer's Kit at HP-UX Release 11.0, you do not have to 9978take any special action to build or install @value{GDBN}. 9979 9980If you obtain @value{GDBN} (HP WDB 0.75) from an HP web site, you may 9981download either a @code{swinstall}-able package or a source tree, or 9982both. 9983 9984Most customers will want to install the @value{GDBN} binary that is part 9985of the @code{swinstall}-able package. To do so, use a command of the 9986form 9987 9988@smallexample 9989/usr/sbin/swinstall -s @var{package-name} WDB 9990@end smallexample 9991 9992Alternatively, it is possible to build @value{GDBN} from the source 9993distribution. Sophisticated customers who want to modify the debugger 9994sources to tailor @value{GDBN} to their their needs may wish to do this. 9995The source distribution consists of a @code{tar}'ed source tree rooted 9996at @file{gdb-4.16/...}. The instructions that follow describe how to 9997build a @file{gdb} executable from this source tree. HP believes that 9998these instructions apply to the WDB source tree that it distributes. 9999However, HP does not explicitly support building a @file{gdb} for any 10000non-HP platform from the WDB source tree. It may work, but HP has not 10001tested it for any platforms other than those described in the WDB 0.75 10002Release Notes. 10003@end ifset 10004 | |
| 10005@value{GDBN} comes with a @code{configure} script that automates the process 10006of preparing @value{GDBN} for installation; you can then use @code{make} to 10007build the @code{gdb} program. 10008@iftex 10009@c irrelevant in info file; it's as current as the code it lives with. 10010@footnote{If you have a more recent version of @value{GDBN} than @value{GDBVN}, 10011look at the @file{README} file in the sources; we may have improved the 10012installation procedures since publishing this manual.} 10013@end iftex 10014 | 13759@value{GDBN} comes with a @code{configure} script that automates the process 13760of preparing @value{GDBN} for installation; you can then use @code{make} to 13761build the @code{gdb} program. 13762@iftex 13763@c irrelevant in info file; it's as current as the code it lives with. 13764@footnote{If you have a more recent version of @value{GDBN} than @value{GDBVN}, 13765look at the @file{README} file in the sources; we may have improved the 13766installation procedures since publishing this manual.} 13767@end iftex 13768 |
| 10015The @value{GDBN} distribution includes all the source code you need for 10016@value{GDBN} in a single directory, whose name is usually composed by | 13769The @value{GDBN} distribution includes all the source code you need for 13770@value{GDBN} in a single directory, whose name is usually composed by |
| 10017appending the version number to @samp{gdb}. 10018 10019For example, the @value{GDBN} version @value{GDBVN} distribution is in the 10020@file{gdb-@value{GDBVN}} directory. That directory contains: 10021 10022@table @code 10023@item gdb-@value{GDBVN}/configure @r{(and supporting files)} 10024script for configuring @value{GDBN} and all its supporting libraries --- 87 unchanged lines hidden (view full) --- 10112let @value{GDBN} debug child processes whose programs are not readable. 10113 10114@menu 10115* Separate Objdir:: Compiling @value{GDBN} in another directory 10116* Config Names:: Specifying names for hosts and targets 10117* Configure Options:: Summary of options for configure 10118@end menu 10119 | 13771appending the version number to @samp{gdb}. 13772 13773For example, the @value{GDBN} version @value{GDBVN} distribution is in the 13774@file{gdb-@value{GDBVN}} directory. That directory contains: 13775 13776@table @code 13777@item gdb-@value{GDBVN}/configure @r{(and supporting files)} 13778script for configuring @value{GDBN} and all its supporting libraries --- 87 unchanged lines hidden (view full) --- 13866let @value{GDBN} debug child processes whose programs are not readable. 13867 13868@menu 13869* Separate Objdir:: Compiling @value{GDBN} in another directory 13870* Config Names:: Specifying names for hosts and targets 13871* Configure Options:: Summary of options for configure 13872@end menu 13873 |
| 10120@node Separate Objdir, Config Names, Installing GDB, Installing GDB | 13874@node Separate Objdir |
| 10121@section Compiling @value{GDBN} in another directory 10122 10123If you want to run @value{GDBN} versions for several host or target machines, 10124you need a different @code{gdb} compiled for each combination of 10125host and target. @code{configure} is designed to make this easy by 10126allowing you to generate each configuration in a separate subdirectory, 10127rather than in the source directory. If your @code{make} program 10128handles the @samp{VPATH} feature (@sc{gnu} @code{make} does), running 10129@code{make} in each of these directories builds the @code{gdb} 10130program specified there. 10131 10132To build @code{gdb} in a separate directory, run @code{configure} 10133with the @samp{--srcdir} option to specify where to find the source. 10134(You also need to specify a path to find @code{configure} 10135itself from your working directory. If the path to @code{configure} 10136would be the same as the argument to @samp{--srcdir}, you can leave out 10137the @samp{--srcdir} option; it is assumed.) 10138 | 13875@section Compiling @value{GDBN} in another directory 13876 13877If you want to run @value{GDBN} versions for several host or target machines, 13878you need a different @code{gdb} compiled for each combination of 13879host and target. @code{configure} is designed to make this easy by 13880allowing you to generate each configuration in a separate subdirectory, 13881rather than in the source directory. If your @code{make} program 13882handles the @samp{VPATH} feature (@sc{gnu} @code{make} does), running 13883@code{make} in each of these directories builds the @code{gdb} 13884program specified there. 13885 13886To build @code{gdb} in a separate directory, run @code{configure} 13887with the @samp{--srcdir} option to specify where to find the source. 13888(You also need to specify a path to find @code{configure} 13889itself from your working directory. If the path to @code{configure} 13890would be the same as the argument to @samp{--srcdir}, you can leave out 13891the @samp{--srcdir} option; it is assumed.) 13892 |
| 10139For example, with version @value{GDBVN}, you can build @value{GDBN} in a | 13893For example, with version @value{GDBVN}, you can build @value{GDBN} in a |
| 10140separate directory for a Sun 4 like this: 10141 10142@example 10143@group 10144cd gdb-@value{GDBVN} 10145mkdir ../gdb-sun4 10146cd ../gdb-sun4 10147../gdb-@value{GDBVN}/configure sun4 --- 4 unchanged lines hidden (view full) --- 10152When @code{configure} builds a configuration using a remote source 10153directory, it creates a tree for the binaries with the same structure 10154(and using the same names) as the tree under the source directory. In 10155the example, you'd find the Sun 4 library @file{libiberty.a} in the 10156directory @file{gdb-sun4/libiberty}, and @value{GDBN} itself in 10157@file{gdb-sun4/gdb}. 10158 10159One popular reason to build several @value{GDBN} configurations in separate | 13894separate directory for a Sun 4 like this: 13895 13896@example 13897@group 13898cd gdb-@value{GDBVN} 13899mkdir ../gdb-sun4 13900cd ../gdb-sun4 13901../gdb-@value{GDBVN}/configure sun4 --- 4 unchanged lines hidden (view full) --- 13906When @code{configure} builds a configuration using a remote source 13907directory, it creates a tree for the binaries with the same structure 13908(and using the same names) as the tree under the source directory. In 13909the example, you'd find the Sun 4 library @file{libiberty.a} in the 13910directory @file{gdb-sun4/libiberty}, and @value{GDBN} itself in 13911@file{gdb-sun4/gdb}. 13912 13913One popular reason to build several @value{GDBN} configurations in separate |
| 10160directories is to configure @value{GDBN} for cross-compiling (where 10161@value{GDBN} runs on one machine---the @dfn{host}---while debugging 10162programs that run on another machine---the @dfn{target}). | 13914directories is to configure @value{GDBN} for cross-compiling (where 13915@value{GDBN} runs on one machine---the @dfn{host}---while debugging 13916programs that run on another machine---the @dfn{target}). |
| 10163You specify a cross-debugging target by 10164giving the @samp{--target=@var{target}} option to @code{configure}. 10165 10166When you run @code{make} to build a program or library, you must run 10167it in a configured directory---whatever directory you were in when you 10168called @code{configure} (or one of its subdirectories). 10169 10170The @code{Makefile} that @code{configure} generates in each source 10171directory also runs recursively. If you type @code{make} in a source 10172directory such as @file{gdb-@value{GDBVN}} (or in a separate configured 10173directory configured with @samp{--srcdir=@var{dirname}/gdb-@value{GDBVN}}), you 10174will build all the required libraries, and then build GDB. 10175 10176When you have multiple hosts or targets configured in separate 10177directories, you can run @code{make} on them in parallel (for example, 10178if they are NFS-mounted on each of the hosts); they will not interfere 10179with each other. 10180 | 13917You specify a cross-debugging target by 13918giving the @samp{--target=@var{target}} option to @code{configure}. 13919 13920When you run @code{make} to build a program or library, you must run 13921it in a configured directory---whatever directory you were in when you 13922called @code{configure} (or one of its subdirectories). 13923 13924The @code{Makefile} that @code{configure} generates in each source 13925directory also runs recursively. If you type @code{make} in a source 13926directory such as @file{gdb-@value{GDBVN}} (or in a separate configured 13927directory configured with @samp{--srcdir=@var{dirname}/gdb-@value{GDBVN}}), you 13928will build all the required libraries, and then build GDB. 13929 13930When you have multiple hosts or targets configured in separate 13931directories, you can run @code{make} on them in parallel (for example, 13932if they are NFS-mounted on each of the hosts); they will not interfere 13933with each other. 13934 |
| 10181@node Config Names, Configure Options, Separate Objdir, Installing GDB | 13935@node Config Names |
| 10182@section Specifying names for hosts and targets 10183 10184The specifications used for hosts and targets in the @code{configure} 10185script are based on a three-part naming scheme, but some short predefined 10186aliases are also supported. The full naming scheme encodes three pieces 10187of information in the following pattern: 10188 10189@example --- 25 unchanged lines hidden (view full) --- 10215% sh config.sub i986v 10216Invalid configuration `i986v': machine `i986v' not recognized 10217@end smallexample 10218 10219@noindent 10220@code{config.sub} is also distributed in the @value{GDBN} source 10221directory (@file{gdb-@value{GDBVN}}, for version @value{GDBVN}). 10222 | 13936@section Specifying names for hosts and targets 13937 13938The specifications used for hosts and targets in the @code{configure} 13939script are based on a three-part naming scheme, but some short predefined 13940aliases are also supported. The full naming scheme encodes three pieces 13941of information in the following pattern: 13942 13943@example --- 25 unchanged lines hidden (view full) --- 13969% sh config.sub i986v 13970Invalid configuration `i986v': machine `i986v' not recognized 13971@end smallexample 13972 13973@noindent 13974@code{config.sub} is also distributed in the @value{GDBN} source 13975directory (@file{gdb-@value{GDBVN}}, for version @value{GDBVN}). 13976 |
| 10223@node Configure Options, , Config Names, Installing GDB | 13977@node Configure Options |
| 10224@section @code{configure} options 10225 10226Here is a summary of the @code{configure} options and arguments that 10227are most often useful for building @value{GDBN}. @code{configure} also has 10228several other options not listed here. @inforef{What Configure 10229Does,,configure.info}, for a full explanation of @code{configure}. 10230 10231@example --- 51 unchanged lines hidden (view full) --- 10283@item @var{host} @dots{} 10284Configure @value{GDBN} to run on the specified @var{host}. 10285 10286There is no convenient way to generate a list of all available hosts. 10287@end table 10288 10289There are many other options available as well, but they are generally 10290needed for special purposes only. | 13978@section @code{configure} options 13979 13980Here is a summary of the @code{configure} options and arguments that 13981are most often useful for building @value{GDBN}. @code{configure} also has 13982several other options not listed here. @inforef{What Configure 13983Does,,configure.info}, for a full explanation of @code{configure}. 13984 13985@example --- 51 unchanged lines hidden (view full) --- 14037@item @var{host} @dots{} 14038Configure @value{GDBN} to run on the specified @var{host}. 14039 14040There is no convenient way to generate a list of all available hosts. 14041@end table 14042 14043There are many other options available as well, but they are generally 14044needed for special purposes only. |
| 10291@end ifclear | |
| 10292 | 14045 |
| 10293 10294@node Index, , Installing GDB, Top | 14046@node Maintenance Commands 14047@appendix Maintenance Commands 14048@cindex maintenance commands 14049@cindex internal commands 14050 14051In addition to commands intended for @value{GDBN} users, @value{GDBN} 14052includes a number of commands intended for @value{GDBN} developers. 14053These commands are provided here for reference. 14054 14055@table @code 14056@kindex maint info breakpoints 14057@item @anchor{maint info breakpoints}maint info breakpoints 14058Using the same format as @samp{info breakpoints}, display both the 14059breakpoints you've set explicitly, and those @value{GDBN} is using for 14060internal purposes. Internal breakpoints are shown with negative 14061breakpoint numbers. The type column identifies what kind of breakpoint 14062is shown: 14063 14064@table @code 14065@item breakpoint 14066Normal, explicitly set breakpoint. 14067 14068@item watchpoint 14069Normal, explicitly set watchpoint. 14070 14071@item longjmp 14072Internal breakpoint, used to handle correctly stepping through 14073@code{longjmp} calls. 14074 14075@item longjmp resume 14076Internal breakpoint at the target of a @code{longjmp}. 14077 14078@item until 14079Temporary internal breakpoint used by the @value{GDBN} @code{until} command. 14080 14081@item finish 14082Temporary internal breakpoint used by the @value{GDBN} @code{finish} command. 14083 14084@item shlib events 14085Shared library events. 14086 14087@end table 14088 14089@end table 14090 14091 14092@node Remote Protocol 14093@appendix @value{GDBN} Remote Serial Protocol 14094 14095There may be occasions when you need to know something about the 14096protocol---for example, if there is only one serial port to your target 14097machine, you might want your program to do something special if it 14098recognizes a packet meant for @value{GDBN}. 14099 14100In the examples below, @samp{<-} and @samp{->} are used to indicate 14101transmitted and received data respectfully. 14102 14103@cindex protocol, @value{GDBN} remote serial 14104@cindex serial protocol, @value{GDBN} remote 14105@cindex remote serial protocol 14106All @value{GDBN} commands and responses (other than acknowledgments) are 14107sent as a @var{packet}. A @var{packet} is introduced with the character 14108@samp{$}, the actual @var{packet-data}, and the terminating character 14109@samp{#} followed by a two-digit @var{checksum}: 14110 14111@example 14112@code{$}@var{packet-data}@code{#}@var{checksum} 14113@end example 14114@noindent 14115 14116@cindex checksum, for @value{GDBN} remote 14117@noindent 14118The two-digit @var{checksum} is computed as the modulo 256 sum of all 14119characters between the leading @samp{$} and the trailing @samp{#} (an 14120eight bit unsigned checksum). 14121 14122Implementors should note that prior to @value{GDBN} 5.0 the protocol 14123specification also included an optional two-digit @var{sequence-id}: 14124 14125@example 14126@code{$}@var{sequence-id}@code{:}@var{packet-data}@code{#}@var{checksum} 14127@end example 14128 14129@cindex sequence-id, for @value{GDBN} remote 14130@noindent 14131That @var{sequence-id} was appended to the acknowledgment. @value{GDBN} 14132has never output @var{sequence-id}s. Stubs that handle packets added 14133since @value{GDBN} 5.0 must not accept @var{sequence-id}. 14134 14135@cindex acknowledgment, for @value{GDBN} remote 14136When either the host or the target machine receives a packet, the first 14137response expected is an acknowledgment: either @samp{+} (to indicate 14138the package was received correctly) or @samp{-} (to request 14139retransmission): 14140 14141@example 14142<- @code{$}@var{packet-data}@code{#}@var{checksum} 14143-> @code{+} 14144@end example 14145@noindent 14146 14147The host (@value{GDBN}) sends @var{command}s, and the target (the 14148debugging stub incorporated in your program) sends a @var{response}. In 14149the case of step and continue @var{command}s, the response is only sent 14150when the operation has completed (the target has again stopped). 14151 14152@var{packet-data} consists of a sequence of characters with the 14153exception of @samp{#} and @samp{$} (see @samp{X} packet for additional 14154exceptions). 14155 14156Fields within the packet should be separated using @samp{,} @samp{;} or 14157@samp{:}. Except where otherwise noted all numbers are represented in 14158HEX with leading zeros suppressed. 14159 14160Implementors should note that prior to @value{GDBN} 5.0, the character 14161@samp{:} could not appear as the third character in a packet (as it 14162would potentially conflict with the @var{sequence-id}). 14163 14164Response @var{data} can be run-length encoded to save space. A @samp{*} 14165means that the next character is an @sc{ascii} encoding giving a repeat count 14166which stands for that many repetitions of the character preceding the 14167@samp{*}. The encoding is @code{n+29}, yielding a printable character 14168where @code{n >=3} (which is where rle starts to win). The printable 14169characters @samp{$}, @samp{#}, @samp{+} and @samp{-} or with a numeric 14170value greater than 126 should not be used. 14171 14172Some remote systems have used a different run-length encoding mechanism 14173loosely refered to as the cisco encoding. Following the @samp{*} 14174character are two hex digits that indicate the size of the packet. 14175 14176So: 14177@example 14178"@code{0* }" 14179@end example 14180@noindent 14181means the same as "0000". 14182 14183The error response returned for some packets includes a two character 14184error number. That number is not well defined. 14185 14186For any @var{command} not supported by the stub, an empty response 14187(@samp{$#00}) should be returned. That way it is possible to extend the 14188protocol. A newer @value{GDBN} can tell if a packet is supported based 14189on that response. 14190 14191A stub is required to support the @samp{g}, @samp{G}, @samp{m}, @samp{M}, 14192@samp{c}, and @samp{s} @var{command}s. All other @var{command}s are 14193optional. 14194 14195Below is a complete list of all currently defined @var{command}s and 14196their corresponding response @var{data}: 14197@page 14198@multitable @columnfractions .30 .30 .40 14199@item Packet 14200@tab Request 14201@tab Description 14202 14203@item extended mode 14204@tab @code{!} 14205@tab 14206Enable extended mode. In extended mode, the remote server is made 14207persistent. The @samp{R} packet is used to restart the program being 14208debugged. 14209@item 14210@tab reply @samp{OK} 14211@tab 14212The remote target both supports and has enabled extended mode. 14213 14214@item last signal 14215@tab @code{?} 14216@tab 14217Indicate the reason the target halted. The reply is the same as for step 14218and continue. 14219@item 14220@tab reply 14221@tab see below 14222 14223 14224@item reserved 14225@tab @code{a} 14226@tab Reserved for future use 14227 14228@item set program arguments @strong{(reserved)} 14229@tab @code{A}@var{arglen}@code{,}@var{argnum}@code{,}@var{arg}@code{,...} 14230@tab 14231@item 14232@tab 14233@tab 14234Initialized @samp{argv[]} array passed into program. @var{arglen} 14235specifies the number of bytes in the hex encoded byte stream @var{arg}. 14236See @file{gdbserver} for more details. 14237@item 14238@tab reply @code{OK} 14239@item 14240@tab reply @code{E}@var{NN} 14241 14242@item set baud @strong{(deprecated)} 14243@tab @code{b}@var{baud} 14244@tab 14245Change the serial line speed to @var{baud}. JTC: @emph{When does the 14246transport layer state change? When it's received, or after the ACK is 14247transmitted. In either case, there are problems if the command or the 14248acknowledgment packet is dropped.} Stan: @emph{If people really wanted 14249to add something like this, and get it working for the first time, they 14250ought to modify ser-unix.c to send some kind of out-of-band message to a 14251specially-setup stub and have the switch happen "in between" packets, so 14252that from remote protocol's point of view, nothing actually 14253happened.} 14254 14255@item set breakpoint @strong{(deprecated)} 14256@tab @code{B}@var{addr},@var{mode} 14257@tab 14258Set (@var{mode} is @samp{S}) or clear (@var{mode} is @samp{C}) a 14259breakpoint at @var{addr}. @emph{This has been replaced by the @samp{Z} and 14260@samp{z} packets.} 14261 14262@item continue 14263@tab @code{c}@var{addr} 14264@tab 14265@var{addr} is address to resume. If @var{addr} is omitted, resume at 14266current address. 14267@item 14268@tab reply 14269@tab see below 14270 14271@item continue with signal 14272@tab @code{C}@var{sig}@code{;}@var{addr} 14273@tab 14274Continue with signal @var{sig} (hex signal number). If 14275@code{;}@var{addr} is omitted, resume at same address. 14276@item 14277@tab reply 14278@tab see below 14279 14280@item toggle debug @strong{(deprecated)} 14281@tab @code{d} 14282@tab 14283toggle debug flag. 14284 14285@item detach 14286@tab @code{D} 14287@tab 14288Detach @value{GDBN} from the remote system. Sent to the remote target before 14289@value{GDBN} disconnects. 14290@item 14291@tab reply @emph{no response} 14292@tab 14293@value{GDBN} does not check for any response after sending this packet. 14294 14295@item reserved 14296@tab @code{e} 14297@tab Reserved for future use 14298 14299@item reserved 14300@tab @code{E} 14301@tab Reserved for future use 14302 14303@item reserved 14304@tab @code{f} 14305@tab Reserved for future use 14306 14307@item reserved 14308@tab @code{F} 14309@tab Reserved for future use 14310 14311@item read registers 14312@tab @code{g} 14313@tab Read general registers. 14314@item 14315@tab reply @var{XX...} 14316@tab 14317Each byte of register data is described by two hex digits. The bytes 14318with the register are transmitted in target byte order. The size of 14319each register and their position within the @samp{g} @var{packet} are 14320determined by the @value{GDBN} internal macros @var{REGISTER_RAW_SIZE} and 14321@var{REGISTER_NAME} macros. The specification of several standard 14322@code{g} packets is specified below. 14323@item 14324@tab @code{E}@var{NN} 14325@tab for an error. 14326 14327@item write regs 14328@tab @code{G}@var{XX...} 14329@tab 14330See @samp{g} for a description of the @var{XX...} data. 14331@item 14332@tab reply @code{OK} 14333@tab for success 14334@item 14335@tab reply @code{E}@var{NN} 14336@tab for an error 14337 14338@item reserved 14339@tab @code{h} 14340@tab Reserved for future use 14341 14342@item set thread 14343@tab @code{H}@var{c}@var{t...} 14344@tab 14345Set thread for subsequent operations (@samp{m}, @samp{M}, @samp{g}, 14346@samp{G}, et.al.). @var{c} = @samp{c} for thread used in step and 14347continue; @var{t...} can be -1 for all threads. @var{c} = @samp{g} for 14348thread used in other operations. If zero, pick a thread, any thread. 14349@item 14350@tab reply @code{OK} 14351@tab for success 14352@item 14353@tab reply @code{E}@var{NN} 14354@tab for an error 14355 14356@c FIXME: JTC: 14357@c 'H': How restrictive (or permissive) is the thread model. If a 14358@c thread is selected and stopped, are other threads allowed 14359@c to continue to execute? As I mentioned above, I think the 14360@c semantics of each command when a thread is selected must be 14361@c described. For example: 14362@c 14363@c 'g': If the stub supports threads and a specific thread is 14364@c selected, returns the register block from that thread; 14365@c otherwise returns current registers. 14366@c 14367@c 'G' If the stub supports threads and a specific thread is 14368@c selected, sets the registers of the register block of 14369@c that thread; otherwise sets current registers. 14370 14371@item cycle step @strong{(draft)} 14372@tab @code{i}@var{addr}@code{,}@var{nnn} 14373@tab 14374Step the remote target by a single clock cycle. If @code{,}@var{nnn} is 14375present, cycle step @var{nnn} cycles. If @var{addr} is present, cycle 14376step starting at that address. 14377 14378@item signal then cycle step @strong{(reserved)} 14379@tab @code{I} 14380@tab 14381See @samp{i} and @samp{S} for likely syntax and semantics. 14382 14383@item reserved 14384@tab @code{j} 14385@tab Reserved for future use 14386 14387@item reserved 14388@tab @code{J} 14389@tab Reserved for future use 14390 14391@item kill request 14392@tab @code{k} 14393@tab 14394FIXME: @emph{There is no description of how to operate when a specific 14395thread context has been selected (i.e.@: does 'k' kill only that thread?)}. 14396 14397@item reserved 14398@tab @code{l} 14399@tab Reserved for future use 14400 14401@item reserved 14402@tab @code{L} 14403@tab Reserved for future use 14404 14405@item read memory 14406@tab @code{m}@var{addr}@code{,}@var{length} 14407@tab 14408Read @var{length} bytes of memory starting at address @var{addr}. 14409Neither @value{GDBN} nor the stub assume that sized memory transfers are assumed 14410using word alligned accesses. FIXME: @emph{A word aligned memory 14411transfer mechanism is needed.} 14412@item 14413@tab reply @var{XX...} 14414@tab 14415@var{XX...} is mem contents. Can be fewer bytes than requested if able 14416to read only part of the data. Neither @value{GDBN} nor the stub assume that 14417sized memory transfers are assumed using word alligned accesses. FIXME: 14418@emph{A word aligned memory transfer mechanism is needed.} 14419@item 14420@tab reply @code{E}@var{NN} 14421@tab @var{NN} is errno 14422 14423@item write mem 14424@tab @code{M}@var{addr},@var{length}@code{:}@var{XX...} 14425@tab 14426Write @var{length} bytes of memory starting at address @var{addr}. 14427@var{XX...} is the data. 14428@item 14429@tab reply @code{OK} 14430@tab for success 14431@item 14432@tab reply @code{E}@var{NN} 14433@tab 14434for an error (this includes the case where only part of the data was 14435written). 14436 14437@item reserved 14438@tab @code{n} 14439@tab Reserved for future use 14440 14441@item reserved 14442@tab @code{N} 14443@tab Reserved for future use 14444 14445@item reserved 14446@tab @code{o} 14447@tab Reserved for future use 14448 14449@item reserved 14450@tab @code{O} 14451@tab Reserved for future use 14452 14453@item read reg @strong{(reserved)} 14454@tab @code{p}@var{n...} 14455@tab 14456See write register. 14457@item 14458@tab return @var{r....} 14459@tab The hex encoded value of the register in target byte order. 14460 14461@item write reg 14462@tab @code{P}@var{n...}@code{=}@var{r...} 14463@tab 14464Write register @var{n...} with value @var{r...}, which contains two hex 14465digits for each byte in the register (target byte order). 14466@item 14467@tab reply @code{OK} 14468@tab for success 14469@item 14470@tab reply @code{E}@var{NN} 14471@tab for an error 14472 14473@item general query 14474@tab @code{q}@var{query} 14475@tab 14476Request info about @var{query}. In general @value{GDBN} queries 14477have a leading upper case letter. Custom vendor queries should use a 14478company prefix (in lower case) ex: @samp{qfsf.var}. @var{query} may 14479optionally be followed by a @samp{,} or @samp{;} separated list. Stubs 14480must ensure that they match the full @var{query} name. 14481@item 14482@tab reply @code{XX...} 14483@tab Hex encoded data from query. The reply can not be empty. 14484@item 14485@tab reply @code{E}@var{NN} 14486@tab error reply 14487@item 14488@tab reply @samp{} 14489@tab Indicating an unrecognized @var{query}. 14490 14491@item general set 14492@tab @code{Q}@var{var}@code{=}@var{val} 14493@tab 14494Set value of @var{var} to @var{val}. See @samp{q} for a discussing of 14495naming conventions. 14496 14497@item reset @strong{(deprecated)} 14498@tab @code{r} 14499@tab 14500Reset the entire system. 14501 14502@item remote restart 14503@tab @code{R}@var{XX} 14504@tab 14505Restart the program being debugged. @var{XX}, while needed, is ignored. 14506This packet is only available in extended mode. 14507@item 14508@tab 14509no reply 14510@tab 14511The @samp{R} packet has no reply. 14512 14513@item step 14514@tab @code{s}@var{addr} 14515@tab 14516@var{addr} is address to resume. If @var{addr} is omitted, resume at 14517same address. 14518@item 14519@tab reply 14520@tab see below 14521 14522@item step with signal 14523@tab @code{S}@var{sig}@code{;}@var{addr} 14524@tab 14525Like @samp{C} but step not continue. 14526@item 14527@tab reply 14528@tab see below 14529 14530@item search 14531@tab @code{t}@var{addr}@code{:}@var{PP}@code{,}@var{MM} 14532@tab 14533Search backwards starting at address @var{addr} for a match with pattern 14534@var{PP} and mask @var{MM}. @var{PP} and @var{MM} are 4 14535bytes. @var{addr} must be at least 3 digits. 14536 14537@item thread alive 14538@tab @code{T}@var{XX} 14539@tab Find out if the thread XX is alive. 14540@item 14541@tab reply @code{OK} 14542@tab thread is still alive 14543@item 14544@tab reply @code{E}@var{NN} 14545@tab thread is dead 14546 14547@item reserved 14548@tab @code{u} 14549@tab Reserved for future use 14550 14551@item reserved 14552@tab @code{U} 14553@tab Reserved for future use 14554 14555@item reserved 14556@tab @code{v} 14557@tab Reserved for future use 14558 14559@item reserved 14560@tab @code{V} 14561@tab Reserved for future use 14562 14563@item reserved 14564@tab @code{w} 14565@tab Reserved for future use 14566 14567@item reserved 14568@tab @code{W} 14569@tab Reserved for future use 14570 14571@item reserved 14572@tab @code{x} 14573@tab Reserved for future use 14574 14575@item write mem (binary) 14576@tab @code{X}@var{addr}@code{,}@var{length}@var{:}@var{XX...} 14577@tab 14578@var{addr} is address, @var{length} is number of bytes, @var{XX...} is 14579binary data. The characters @code{$}, @code{#}, and @code{0x7d} are 14580escaped using @code{0x7d}. 14581@item 14582@tab reply @code{OK} 14583@tab for success 14584@item 14585@tab reply @code{E}@var{NN} 14586@tab for an error 14587 14588@item reserved 14589@tab @code{y} 14590@tab Reserved for future use 14591 14592@item reserved 14593@tab @code{Y} 14594@tab Reserved for future use 14595 14596@item remove break or watchpoint @strong{(draft)} 14597@tab @code{z}@var{t}@code{,}@var{addr}@code{,}@var{length} 14598@tab 14599See @samp{Z}. 14600 14601@item insert break or watchpoint @strong{(draft)} 14602@tab @code{Z}@var{t}@code{,}@var{addr}@code{,}@var{length} 14603@tab 14604@var{t} is type: @samp{0} - software breakpoint, @samp{1} - hardware 14605breakpoint, @samp{2} - write watchpoint, @samp{3} - read watchpoint, 14606@samp{4} - access watchpoint; @var{addr} is address; @var{length} is in 14607bytes. For a software breakpoint, @var{length} specifies the size of 14608the instruction to be patched. For hardware breakpoints and watchpoints 14609@var{length} specifies the memory region to be monitored. To avoid 14610potential problems with duplicate packets, the operations should be 14611implemented in an idempotent way. 14612@item 14613@tab reply @code{E}@var{NN} 14614@tab for an error 14615@item 14616@tab reply @code{OK} 14617@tab for success 14618@item 14619@tab @samp{} 14620@tab If not supported. 14621 14622@item reserved 14623@tab <other> 14624@tab Reserved for future use 14625 14626@end multitable 14627 14628The @samp{C}, @samp{c}, @samp{S}, @samp{s} and @samp{?} packets can 14629receive any of the below as a reply. In the case of the @samp{C}, 14630@samp{c}, @samp{S} and @samp{s} packets, that reply is only returned 14631when the target halts. In the below the exact meaning of @samp{signal 14632number} is poorly defined. In general one of the UNIX signal numbering 14633conventions is used. 14634 14635@multitable @columnfractions .4 .6 14636 14637@item @code{S}@var{AA} 14638@tab @var{AA} is the signal number 14639 14640@item @code{T}@var{AA}@var{n...}@code{:}@var{r...}@code{;}@var{n...}@code{:}@var{r...}@code{;}@var{n...}@code{:}@var{r...}@code{;} 14641@tab 14642@var{AA} = two hex digit signal number; @var{n...} = register number 14643(hex), @var{r...} = target byte ordered register contents, size defined 14644by @code{REGISTER_RAW_SIZE}; @var{n...} = @samp{thread}, @var{r...} = 14645thread process ID, this is a hex integer; @var{n...} = other string not 14646starting with valid hex digit. @value{GDBN} should ignore this 14647@var{n...}, @var{r...} pair and go on to the next. This way we can 14648extend the protocol. 14649 14650@item @code{W}@var{AA} 14651@tab 14652The process exited, and @var{AA} is the exit status. This is only 14653applicable for certains sorts of targets. 14654 14655@item @code{X}@var{AA} 14656@tab 14657The process terminated with signal @var{AA}. 14658 14659@item @code{N}@var{AA}@code{;}@var{t...}@code{;}@var{d...}@code{;}@var{b...} @strong{(obsolete)} 14660@tab 14661@var{AA} = signal number; @var{t...} = address of symbol "_start"; 14662@var{d...} = base of data section; @var{b...} = base of bss section. 14663@emph{Note: only used by Cisco Systems targets. The difference between 14664this reply and the "qOffsets" query is that the 'N' packet may arrive 14665spontaneously whereas the 'qOffsets' is a query initiated by the host 14666debugger.} 14667 14668@item @code{O}@var{XX...} 14669@tab 14670@var{XX...} is hex encoding of @sc{ascii} data. This can happen at any time 14671while the program is running and the debugger should continue to wait 14672for 'W', 'T', etc. 14673 14674@end multitable 14675 14676The following set and query packets have already been defined. 14677 14678@multitable @columnfractions .2 .2 .6 14679 14680@item current thread 14681@tab @code{q}@code{C} 14682@tab Return the current thread id. 14683@item 14684@tab reply @code{QC}@var{pid} 14685@tab 14686Where @var{pid} is a HEX encoded 16 bit process id. 14687@item 14688@tab reply * 14689@tab Any other reply implies the old pid. 14690 14691@item all thread ids 14692@tab @code{q}@code{fThreadInfo} 14693@item 14694@tab @code{q}@code{sThreadInfo} 14695@tab 14696Obtain a list of active thread ids from the target (OS). Since there 14697may be too many active threads to fit into one reply packet, this query 14698works iteratively: it may require more than one query/reply sequence to 14699obtain the entire list of threads. The first query of the sequence will 14700be the @code{qf}@code{ThreadInfo} query; subsequent queries in the 14701sequence will be the @code{qs}@code{ThreadInfo} query. 14702@item 14703@tab 14704@tab NOTE: replaces the @code{qL} query (see below). 14705@item 14706@tab reply @code{m}@var{<id>} 14707@tab A single thread id 14708@item 14709@tab reply @code{m}@var{<id>},@var{<id>...} 14710@tab a comma-separated list of thread ids 14711@item 14712@tab reply @code{l} 14713@tab (lower case 'el') denotes end of list. 14714@item 14715@tab 14716@tab 14717In response to each query, the target will reply with a list of one 14718or more thread ids, in big-endian hex, separated by commas. GDB will 14719respond to each reply with a request for more thread ids (using the 14720@code{qs} form of the query), until the target responds with @code{l} 14721(lower-case el, for @code{'last'}). 14722 14723@item extra thread info 14724@tab @code{q}@code{ThreadExtraInfo}@code{,}@var{id} 14725@tab 14726@item 14727@tab 14728@tab 14729Where @var{<id>} is a thread-id in big-endian hex. 14730Obtain a printable string description of a thread's attributes from 14731the target OS. This string may contain anything that the target OS 14732thinks is interesting for @value{GDBN} to tell the user about the thread. 14733The string is displayed in @value{GDBN}'s @samp{info threads} display. 14734Some examples of possible thread extra info strings are "Runnable", or 14735"Blocked on Mutex". 14736@item 14737@tab reply @var{XX...} 14738@tab 14739Where @var{XX...} is a hex encoding of @sc{ascii} data, comprising the 14740printable string containing the extra information about the thread's 14741attributes. 14742 14743@item query @var{LIST} or @var{threadLIST} @strong{(deprecated)} 14744@tab @code{q}@code{L}@var{startflag}@var{threadcount}@var{nextthread} 14745@tab 14746@item 14747@tab 14748@tab 14749Obtain thread information from RTOS. Where: @var{startflag} (one hex 14750digit) is one to indicate the first query and zero to indicate a 14751subsequent query; @var{threadcount} (two hex digits) is the maximum 14752number of threads the response packet can contain; and @var{nextthread} 14753(eight hex digits), for subsequent queries (@var{startflag} is zero), is 14754returned in the response as @var{argthread}. 14755@item 14756@tab 14757@tab NOTE: this query is replaced by the @code{q}@code{fThreadInfo} 14758query (see above). 14759@item 14760@tab reply @code{q}@code{M}@var{count}@var{done}@var{argthread}@var{thread...} 14761@tab 14762@item 14763@tab 14764@tab 14765Where: @var{count} (two hex digits) is the number of threads being 14766returned; @var{done} (one hex digit) is zero to indicate more threads 14767and one indicates no further threads; @var{argthreadid} (eight hex 14768digits) is @var{nextthread} from the request packet; @var{thread...} is 14769a sequence of thread IDs from the target. @var{threadid} (eight hex 14770digits). See @code{remote.c:parse_threadlist_response()}. 14771 14772@item compute CRC of memory block 14773@tab @code{q}@code{CRC:}@var{addr}@code{,}@var{length} 14774@tab 14775@item 14776@tab reply @code{E}@var{NN} 14777@tab An error (such as memory fault) 14778@item 14779@tab reply @code{C}@var{CRC32} 14780@tab A 32 bit cyclic redundancy check of the specified memory region. 14781 14782@item query sect offs 14783@tab @code{q}@code{Offsets} 14784@tab 14785Get section offsets that the target used when re-locating the downloaded 14786image. @emph{Note: while a @code{Bss} offset is included in the 14787response, @value{GDBN} ignores this and instead applies the @code{Data} 14788offset to the @code{Bss} section.} 14789@item 14790@tab reply @code{Text=}@var{xxx}@code{;Data=}@var{yyy}@code{;Bss=}@var{zzz} 14791 14792@item thread info request 14793@tab @code{q}@code{P}@var{mode}@var{threadid} 14794@tab 14795@item 14796@tab 14797@tab 14798Returns information on @var{threadid}. Where: @var{mode} is a hex 14799encoded 32 bit mode; @var{threadid} is a hex encoded 64 bit thread ID. 14800@item 14801@tab reply * 14802@tab 14803See @code{remote.c:remote_unpack_thread_info_response()}. 14804 14805@item remote command 14806@tab @code{q}@code{Rcmd,}@var{COMMAND} 14807@tab 14808@item 14809@tab 14810@tab 14811@var{COMMAND} (hex encoded) is passed to the local interpreter for 14812execution. Invalid commands should be reported using the output string. 14813Before the final result packet, the target may also respond with a 14814number of intermediate @code{O}@var{OUTPUT} console output 14815packets. @emph{Implementors should note that providing access to a 14816stubs's interpreter may have security implications}. 14817@item 14818@tab reply @code{OK} 14819@tab 14820A command response with no output. 14821@item 14822@tab reply @var{OUTPUT} 14823@tab 14824A command response with the hex encoded output string @var{OUTPUT}. 14825@item 14826@tab reply @code{E}@var{NN} 14827@tab 14828Indicate a badly formed request. 14829 14830@item 14831@tab reply @samp{} 14832@tab 14833When @samp{q}@samp{Rcmd} is not recognized. 14834 14835@item symbol lookup 14836@tab @code{qSymbol::} 14837@tab 14838Notify the target that @value{GDBN} is prepared to serve symbol lookup 14839requests. Accept requests from the target for the values of symbols. 14840@item 14841@tab 14842@tab 14843@item 14844@tab reply @code{OK} 14845@tab 14846The target does not need to look up any (more) symbols. 14847@item 14848@tab reply @code{qSymbol:}@var{sym_name} 14849@tab 14850@sp 2 14851@noindent 14852The target requests the value of symbol @var{sym_name} (hex encoded). 14853@value{GDBN} may provide the value by using the 14854@code{qSymbol:}@var{sym_value}:@var{sym_name} 14855message, described below. 14856 14857@item symbol value 14858@tab @code{qSymbol:}@var{sym_value}:@var{sym_name} 14859@tab 14860@sp 1 14861@noindent 14862Set the value of SYM_NAME to SYM_VALUE. 14863@item 14864@tab 14865@tab 14866@var{sym_name} (hex encoded) is the name of a symbol whose value 14867the target has previously requested. 14868@item 14869@tab 14870@tab 14871@var{sym_value} (hex) is the value for symbol @var{sym_name}. 14872If @value{GDBN} cannot supply a value for @var{sym_name}, then this 14873field will be empty. 14874@item 14875@tab reply @code{OK} 14876@tab 14877The target does not need to look up any (more) symbols. 14878@item 14879@tab reply @code{qSymbol:}@var{sym_name} 14880@tab 14881@sp 2 14882@noindent 14883The target requests the value of a new symbol @var{sym_name} (hex encoded). 14884@value{GDBN} will continue to supply the values of symbols (if available), 14885until the target ceases to request them. 14886 14887@end multitable 14888 14889The following @samp{g}/@samp{G} packets have previously been defined. 14890In the below, some thirty-two bit registers are transferred as sixty-four 14891bits. Those registers should be zero/sign extended (which?) to fill the 14892space allocated. Register bytes are transfered in target byte order. 14893The two nibbles within a register byte are transfered most-significant - 14894least-significant. 14895 14896@multitable @columnfractions .5 .5 14897 14898@item MIPS32 14899@tab 14900All registers are transfered as thirty-two bit quantities in the order: 1490132 general-purpose; sr; lo; hi; bad; cause; pc; 32 floating-point 14902registers; fsr; fir; fp. 14903 14904@item MIPS64 14905@tab 14906All registers are transfered as sixty-four bit quantities (including 14907thirty-two bit registers such as @code{sr}). The ordering is the same 14908as @code{MIPS32}. 14909 14910@end multitable 14911 14912Example sequence of a target being re-started. Notice how the restart 14913does not get any direct output: 14914 14915@example 14916<- @code{R00} 14917-> @code{+} 14918@emph{target restarts} 14919<- @code{?} 14920-> @code{+} 14921-> @code{T001:1234123412341234} 14922<- @code{+} 14923@end example 14924 14925Example sequence of a target being stepped by a single instruction: 14926 14927@example 14928<- @code{G1445...} 14929-> @code{+} 14930<- @code{s} 14931-> @code{+} 14932@emph{time passes} 14933-> @code{T001:1234123412341234} 14934<- @code{+} 14935<- @code{g} 14936-> @code{+} 14937-> @code{1455...} 14938<- @code{+} 14939@end example 14940 14941@include gpl.texi 14942 14943@include fdl.texi 14944 14945@node Index |
| 10295@unnumbered Index 10296 10297@printindex cp 10298 10299@tex 10300% I think something like @colophon should be in texinfo. In the 10301% meantime: 10302\long\def\colophon{\hbox to0pt{}\vfill --- 4 unchanged lines hidden (view full) --- 10307\centerline{{\it\fontname\tenit\/},} 10308\centerline{{\bf\fontname\tenbf}, and} 10309\centerline{{\sl\fontname\tensl\/}} 10310\centerline{are used for emphasis.}\vfill} 10311\page\colophon 10312% Blame: doc@cygnus.com, 1991. 10313@end tex 10314 | 14946@unnumbered Index 14947 14948@printindex cp 14949 14950@tex 14951% I think something like @colophon should be in texinfo. In the 14952% meantime: 14953\long\def\colophon{\hbox to0pt{}\vfill --- 4 unchanged lines hidden (view full) --- 14958\centerline{{\it\fontname\tenit\/},} 14959\centerline{{\bf\fontname\tenbf}, and} 14960\centerline{{\sl\fontname\tensl\/}} 14961\centerline{are used for emphasis.}\vfill} 14962\page\colophon 14963% Blame: doc@cygnus.com, 1991. 14964@end tex 14965 |
| 10315@contents | |
| 10316@bye | 14966@bye |