| 1 | \input texinfo |
| 2 | @setfilename gdb.info |
| 3 | @settitle GDB, The GNU Debugger |
| 4 | @synindex ky cp |
| 5 | @ifinfo |
| 6 | This file documents the GNU debugger GDB. |
| 7 | |
| 8 | Copyright (C) 1988, 1989 Free Software Foundation, Inc. |
| 9 | |
| 10 | Permission is granted to make and distribute verbatim copies of |
| 11 | this manual provided the copyright notice and this permission notice |
| 12 | are preserved on all copies. |
| 13 | |
| 14 | @ignore |
| 15 | Permission is granted to process this file through Tex and print the |
| 16 | results, provided the printed document carries copying permission |
| 17 | notice identical to this one except for the removal of this paragraph |
| 18 | (this paragraph not being relevant to the printed manual). |
| 19 | |
| 20 | @end ignore |
| 21 | Permission is granted to copy and distribute modified versions of this |
| 22 | manual under the conditions for verbatim copying, provided also that the |
| 23 | section entitled ``GNU General Public License'' is included exactly as |
| 24 | in the original, and provided that the entire resulting derived work is |
| 25 | distributed under the terms of a permission notice identical to this |
| 26 | one. |
| 27 | |
| 28 | Permission is granted to copy and distribute translations of this manual |
| 29 | into another language, under the above conditions for modified versions, |
| 30 | except that the section entitled ``GNU General Public License'' may be |
| 31 | included in a translation approved by the author instead of in the |
| 32 | original English. |
| 33 | @end ifinfo |
| 34 | |
| 35 | @setchapternewpage odd |
| 36 | @settitle GDB Manual |
| 37 | @titlepage |
| 38 | @sp 6 |
| 39 | @center @titlefont{GDB Manual} |
| 40 | @sp 1 |
| 41 | @center The GNU Source-Level Debugger |
| 42 | @sp 4 |
| 43 | @center Third Edition, GDB version 3.4 |
| 44 | @sp 1 |
| 45 | @center October 1989 |
| 46 | @sp 5 |
| 47 | @center Richard M. Stallman |
| 48 | @page |
| 49 | @vskip 0pt plus 1filll |
| 50 | Copyright @copyright{} 1988, 1989 Free Software Foundation, Inc. |
| 51 | |
| 52 | Permission is granted to make and distribute verbatim copies of |
| 53 | this manual provided the copyright notice and this permission notice |
| 54 | are preserved on all copies. |
| 55 | |
| 56 | Permission is granted to copy and distribute modified versions of this |
| 57 | manual under the conditions for verbatim copying, provided also that the |
| 58 | section entitled ``GNU General Public License'' is included exactly as |
| 59 | in the original, and provided that the entire resulting derived work is |
| 60 | distributed under the terms of a permission notice identical to this |
| 61 | one. |
| 62 | |
| 63 | Permission is granted to copy and distribute translations of this manual |
| 64 | into another language, under the above conditions for modified versions, |
| 65 | except that the section entitled ``GNU General Public License'' may be |
| 66 | included in a translation approved by the author instead of in the |
| 67 | original English. |
| 68 | @end titlepage |
| 69 | @page |
| 70 | |
| 71 | @node Top, Top, Top, (DIR) |
| 72 | @unnumbered Summary of GDB |
| 73 | |
| 74 | The purpose of a debugger such as GDB is to allow you to execute another |
| 75 | program while examining what is going on inside it. We call the other |
| 76 | program ``your program'' or ``the program being debugged''. |
| 77 | |
| 78 | GDB can do four kinds of things (plus other things in support of these): |
| 79 | |
| 80 | @enumerate |
| 81 | @item |
| 82 | Start the program, specifying anything that might affect its behavior. |
| 83 | |
| 84 | @item |
| 85 | Make the program stop on specified conditions. |
| 86 | |
| 87 | @item |
| 88 | Examine what has happened, when the program has stopped, so that you |
| 89 | can see bugs happen. |
| 90 | |
| 91 | @item |
| 92 | Change things in the program, so you can correct the effects of one bug |
| 93 | and go on to learn about another without having to recompile first. |
| 94 | @end enumerate |
| 95 | |
| 96 | GDB can be used to debug programs written in C and C++. Pascal support |
| 97 | is being implemented, and Fortran support will be added when a GNU |
| 98 | Fortran compiler is written. |
| 99 | |
| 100 | @menu |
| 101 | * License:: The GNU General Public License gives you permission |
| 102 | to redistribute GDB on certain terms; and also |
| 103 | explains that there is no warranty. |
| 104 | * User Interface:: GDB command syntax and input and output conventions. |
| 105 | * Files:: Specifying files for GDB to operate on. |
| 106 | * Options:: GDB arguments and options. |
| 107 | * Compilation::Compiling your program so you can debug it. |
| 108 | * Running:: Running your program under GDB. |
| 109 | * Stopping:: Making your program stop. Why it may stop. What to do then. |
| 110 | * Stack:: Examining your program's stack. |
| 111 | * Source:: Examining your program's source files. |
| 112 | * Data:: Examining data in your program. |
| 113 | * Symbols:: Examining the debugger's symbol table. |
| 114 | * Altering:: Altering things in your program. |
| 115 | * Sequences:: Canned command sequences for repeated use. |
| 116 | * Emacs:: Using GDB through GNU Emacs. |
| 117 | * Remote:: Remote kernel debugging across a serial line. |
| 118 | * Commands:: Index of GDB commands. |
| 119 | * Concepts:: Index of GDB concepts. |
| 120 | @end menu |
| 121 | |
| 122 | @node License, User Interface, Top, Top |
| 123 | @unnumbered GNU GENERAL PUBLIC LICENSE |
| 124 | @center Version 1, February 1989 |
| 125 | |
| 126 | @display |
| 127 | Copyright @copyright{} 1989 Free Software Foundation, Inc. |
| 128 | 675 Mass Ave, Cambridge, MA 02139, USA |
| 129 | |
| 130 | Everyone is permitted to copy and distribute verbatim copies |
| 131 | of this license document, but changing it is not allowed. |
| 132 | @end display |
| 133 | |
| 134 | @unnumberedsec Preamble |
| 135 | |
| 136 | The license agreements of most software companies try to keep users |
| 137 | at the mercy of those companies. By contrast, our General Public |
| 138 | License is intended to guarantee your freedom to share and change free |
| 139 | software---to make sure the software is free for all its users. The |
| 140 | General Public License applies to the Free Software Foundation's |
| 141 | software and to any other program whose authors commit to using it. |
| 142 | You can use it for your programs, too. |
| 143 | |
| 144 | When we speak of free software, we are referring to freedom, not |
| 145 | price. Specifically, the General Public License is designed to make |
| 146 | sure that you have the freedom to give away or sell copies of free |
| 147 | software, that you receive source code or can get it if you want it, |
| 148 | that you can change the software or use pieces of it in new free |
| 149 | programs; and that you know you can do these things. |
| 150 | |
| 151 | To protect your rights, we need to make restrictions that forbid |
| 152 | anyone to deny you these rights or to ask you to surrender the rights. |
| 153 | These restrictions translate to certain responsibilities for you if you |
| 154 | distribute copies of the software, or if you modify it. |
| 155 | |
| 156 | For example, if you distribute copies of a such a program, whether |
| 157 | gratis or for a fee, you must give the recipients all the rights that |
| 158 | you have. You must make sure that they, too, receive or can get the |
| 159 | source code. And you must tell them their rights. |
| 160 | |
| 161 | We protect your rights with two steps: (1) copyright the software, and |
| 162 | (2) offer you this license which gives you legal permission to copy, |
| 163 | distribute and/or modify the software. |
| 164 | |
| 165 | Also, for each author's protection and ours, we want to make certain |
| 166 | that everyone understands that there is no warranty for this free |
| 167 | software. If the software is modified by someone else and passed on, we |
| 168 | want its recipients to know that what they have is not the original, so |
| 169 | that any problems introduced by others will not reflect on the original |
| 170 | authors' reputations. |
| 171 | |
| 172 | The precise terms and conditions for copying, distribution and |
| 173 | modification follow. |
| 174 | |
| 175 | @iftex |
| 176 | @unnumberedsec TERMS AND CONDITIONS |
| 177 | @end iftex |
| 178 | @ifinfo |
| 179 | @center TERMS AND CONDITIONS |
| 180 | @end ifinfo |
| 181 | |
| 182 | @enumerate |
| 183 | @item |
| 184 | This License Agreement applies to any program or other work which |
| 185 | contains a notice placed by the copyright holder saying it may be |
| 186 | distributed under the terms of this General Public License. The |
| 187 | ``Program'', below, refers to any such program or work, and a ``work based |
| 188 | on the Program'' means either the Program or any work containing the |
| 189 | Program or a portion of it, either verbatim or with modifications. Each |
| 190 | licensee is addressed as ``you''. |
| 191 | |
| 192 | @item |
| 193 | You may copy and distribute verbatim copies of the Program's source |
| 194 | code as you receive it, in any medium, provided that you conspicuously and |
| 195 | appropriately publish on each copy an appropriate copyright notice and |
| 196 | disclaimer of warranty; keep intact all the notices that refer to this |
| 197 | General Public License and to the absence of any warranty; and give any |
| 198 | other recipients of the Program a copy of this General Public License |
| 199 | along with the Program. You may charge a fee for the physical act of |
| 200 | transferring a copy. |
| 201 | |
| 202 | @item |
| 203 | You may modify your copy or copies of the Program or any portion of |
| 204 | it, and copy and distribute such modifications under the terms of Paragraph |
| 205 | 1 above, provided that you also do the following: |
| 206 | |
| 207 | @itemize @bullet |
| 208 | @item |
| 209 | cause the modified files to carry prominent notices stating that |
| 210 | you changed the files and the date of any change; and |
| 211 | |
| 212 | @item |
| 213 | cause the whole of any work that you distribute or publish, that |
| 214 | in whole or in part contains the Program or any part thereof, either |
| 215 | with or without modifications, to be licensed at no charge to all |
| 216 | third parties under the terms of this General Public License (except |
| 217 | that you may choose to grant warranty protection to some or all |
| 218 | third parties, at your option). |
| 219 | |
| 220 | @item |
| 221 | If the modified program normally reads commands interactively when |
| 222 | run, you must cause it, when started running for such interactive use |
| 223 | in the simplest and most usual way, to print or display an |
| 224 | announcement including an appropriate copyright notice and a notice |
| 225 | that there is no warranty (or else, saying that you provide a |
| 226 | warranty) and that users may redistribute the program under these |
| 227 | conditions, and telling the user how to view a copy of this General |
| 228 | Public License. |
| 229 | |
| 230 | @item |
| 231 | You may charge a fee for the physical act of transferring a |
| 232 | copy, and you may at your option offer warranty protection in |
| 233 | exchange for a fee. |
| 234 | @end itemize |
| 235 | |
| 236 | Mere aggregation of another independent work with the Program (or its |
| 237 | derivative) on a volume of a storage or distribution medium does not bring |
| 238 | the other work under the scope of these terms. |
| 239 | |
| 240 | @item |
| 241 | You may copy and distribute the Program (or a portion or derivative of |
| 242 | it, under Paragraph 2) in object code or executable form under the terms of |
| 243 | Paragraphs 1 and 2 above provided that you also do one of the following: |
| 244 | |
| 245 | @itemize @bullet |
| 246 | @item |
| 247 | accompany it with the complete corresponding machine-readable |
| 248 | source code, which must be distributed under the terms of |
| 249 | Paragraphs 1 and 2 above; or, |
| 250 | |
| 251 | @item |
| 252 | accompany it with a written offer, valid for at least three |
| 253 | years, to give any third party free (except for a nominal charge |
| 254 | for the cost of distribution) a complete machine-readable copy of the |
| 255 | corresponding source code, to be distributed under the terms of |
| 256 | Paragraphs 1 and 2 above; or, |
| 257 | |
| 258 | @item |
| 259 | accompany it with the information you received as to where the |
| 260 | corresponding source code may be obtained. (This alternative is |
| 261 | allowed only for noncommercial distribution and only if you |
| 262 | received the program in object code or executable form alone.) |
| 263 | @end itemize |
| 264 | |
| 265 | Source code for a work means the preferred form of the work for making |
| 266 | modifications to it. For an executable file, complete source code means |
| 267 | all the source code for all modules it contains; but, as a special |
| 268 | exception, it need not include source code for modules which are standard |
| 269 | libraries that accompany the operating system on which the executable |
| 270 | file runs, or for standard header files or definitions files that |
| 271 | accompany that operating system. |
| 272 | |
| 273 | @item |
| 274 | You may not copy, modify, sublicense, distribute or transfer the |
| 275 | Program except as expressly provided under this General Public License. |
| 276 | Any attempt otherwise to copy, modify, sublicense, distribute or transfer |
| 277 | the Program is void, and will automatically terminate your rights to use |
| 278 | the Program under this License. However, parties who have received |
| 279 | copies, or rights to use copies, from you under this General Public |
| 280 | License will not have their licenses terminated so long as such parties |
| 281 | remain in full compliance. |
| 282 | |
| 283 | @item |
| 284 | By copying, distributing or modifying the Program (or any work based |
| 285 | on the Program) you indicate your acceptance of this license to do so, |
| 286 | and all its terms and conditions. |
| 287 | |
| 288 | @item |
| 289 | Each time you redistribute the Program (or any work based on the |
| 290 | Program), the recipient automatically receives a license from the original |
| 291 | licensor to copy, distribute or modify the Program subject to these |
| 292 | terms and conditions. You may not impose any further restrictions on the |
| 293 | recipients' exercise of the rights granted herein. |
| 294 | |
| 295 | @item |
| 296 | The Free Software Foundation may publish revised and/or new versions |
| 297 | of the General Public License from time to time. Such new versions will |
| 298 | be similar in spirit to the present version, but may differ in detail to |
| 299 | address new problems or concerns. |
| 300 | |
| 301 | Each version is given a distinguishing version number. If the Program |
| 302 | specifies a version number of the license which applies to it and ``any |
| 303 | later version'', you have the option of following the terms and conditions |
| 304 | either of that version or of any later version published by the Free |
| 305 | Software Foundation. If the Program does not specify a version number of |
| 306 | the license, you may choose any version ever published by the Free Software |
| 307 | Foundation. |
| 308 | |
| 309 | @item |
| 310 | If you wish to incorporate parts of the Program into other free |
| 311 | programs whose distribution conditions are different, write to the author |
| 312 | to ask for permission. For software which is copyrighted by the Free |
| 313 | Software Foundation, write to the Free Software Foundation; we sometimes |
| 314 | make exceptions for this. Our decision will be guided by the two goals |
| 315 | of preserving the free status of all derivatives of our free software and |
| 316 | of promoting the sharing and reuse of software generally. |
| 317 | |
| 318 | @iftex |
| 319 | @heading NO WARRANTY |
| 320 | @end iftex |
| 321 | @ifinfo |
| 322 | @center NO WARRANTY |
| 323 | @end ifinfo |
| 324 | |
| 325 | @item |
| 326 | BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY |
| 327 | FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN |
| 328 | OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES |
| 329 | PROVIDE THE PROGRAM ``AS IS'' WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED |
| 330 | OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF |
| 331 | MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS |
| 332 | TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE |
| 333 | PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, |
| 334 | REPAIR OR CORRECTION. |
| 335 | |
| 336 | @item |
| 337 | IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL |
| 338 | ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR |
| 339 | REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, |
| 340 | INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES |
| 341 | ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT |
| 342 | LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES |
| 343 | SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE |
| 344 | WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN |
| 345 | ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. |
| 346 | @end enumerate |
| 347 | |
| 348 | @iftex |
| 349 | @heading END OF TERMS AND CONDITIONS |
| 350 | @end iftex |
| 351 | @ifinfo |
| 352 | @center END OF TERMS AND CONDITIONS |
| 353 | @end ifinfo |
| 354 | |
| 355 | @page |
| 356 | @unnumberedsec Appendix: How to Apply These Terms to Your New Programs |
| 357 | |
| 358 | If you develop a new program, and you want it to be of the greatest |
| 359 | possible use to humanity, the best way to achieve this is to make it |
| 360 | free software which everyone can redistribute and change under these |
| 361 | terms. |
| 362 | |
| 363 | To do so, attach the following notices to the program. It is safest to |
| 364 | attach them to the start of each source file to most effectively convey |
| 365 | the exclusion of warranty; and each file should have at least the |
| 366 | ``copyright'' line and a pointer to where the full notice is found. |
| 367 | |
| 368 | @smallexample |
| 369 | @var{one line to give the program's name and a brief idea of what it does.} |
| 370 | Copyright (C) 19@var{yy} @var{name of author} |
| 371 | |
| 372 | This program is free software; you can redistribute it and/or modify |
| 373 | it under the terms of the GNU General Public License as published by |
| 374 | the Free Software Foundation; either version 1, or (at your option) |
| 375 | any later version. |
| 376 | |
| 377 | This program is distributed in the hope that it will be useful, |
| 378 | but WITHOUT ANY WARRANTY; without even the implied warranty of |
| 379 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the |
| 380 | GNU General Public License for more details. |
| 381 | |
| 382 | You should have received a copy of the GNU General Public License |
| 383 | along with this program; if not, write to the Free Software |
| 384 | Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. |
| 385 | @end smallexample |
| 386 | |
| 387 | Also add information on how to contact you by electronic and paper mail. |
| 388 | |
| 389 | If the program is interactive, make it output a short notice like this |
| 390 | when it starts in an interactive mode: |
| 391 | |
| 392 | @smallexample |
| 393 | Gnomovision version 69, Copyright (C) 19@var{yy} @var{name of author} |
| 394 | Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'. |
| 395 | This is free software, and you are welcome to redistribute it |
| 396 | under certain conditions; type `show c' for details. |
| 397 | @end smallexample |
| 398 | |
| 399 | The hypothetical commands `show w' and `show c' should show the |
| 400 | appropriate parts of the General Public License. Of course, the |
| 401 | commands you use may be called something other than `show w' and `show |
| 402 | c'; they could even be mouse-clicks or menu items---whatever suits your |
| 403 | program. |
| 404 | |
| 405 | You should also get your employer (if you work as a programmer) or your |
| 406 | school, if any, to sign a ``copyright disclaimer'' for the program, if |
| 407 | necessary. Here a sample; alter the names: |
| 408 | |
| 409 | @example |
| 410 | Yoyodyne, Inc., hereby disclaims all copyright interest in the |
| 411 | program `Gnomovision' (a program to direct compilers to make passes |
| 412 | at assemblers) written by James Hacker. |
| 413 | |
| 414 | @var{signature of Ty Coon}, 1 April 1989 |
| 415 | Ty Coon, President of Vice |
| 416 | @end example |
| 417 | |
| 418 | That's all there is to it! |
| 419 | |
| 420 | @node User Interface, Files, License, Top |
| 421 | @chapter GDB Input and Output Conventions |
| 422 | |
| 423 | GDB is invoked with the shell command @samp{gdb}. Once started, it reads |
| 424 | commands from the terminal until you tell it to exit. |
| 425 | |
| 426 | A GDB command is a single line of input. There is no limit on how long |
| 427 | it can be. It starts with a command name, which is followed by arguments |
| 428 | whose meaning depends on the command name. For example, the command |
| 429 | @samp{step} accepts an argument which is the number of times to step, |
| 430 | as in @samp{step 5}. You can also use the @samp{step} command with |
| 431 | no arguments. Some command names do not allow any arguments. |
| 432 | |
| 433 | @cindex abbreviation |
| 434 | GDB command names may always be abbreviated if the abbreviation is |
| 435 | unambiguous. Sometimes even ambiguous abbreviations are allowed; for |
| 436 | example, @samp{s} is specially defined as equivalent to @samp{step} |
| 437 | even though there are other commands whose names start with @samp{s}. |
| 438 | Possible command abbreviations are often stated in the documentation |
| 439 | of the individual commands. |
| 440 | |
| 441 | @cindex repeating commands |
| 442 | A blank line as input to GDB means to repeat the previous command verbatim. |
| 443 | Certain commands do not allow themselves to be repeated this way; these are |
| 444 | commands for which unintentional repetition might cause trouble and which |
| 445 | you are unlikely to want to repeat. Certain others (@samp{list} and |
| 446 | @samp{x}) act differently when repeated because that is more useful. |
| 447 | |
| 448 | A line of input starting with @samp{#} is a comment; it does nothing. |
| 449 | This is useful mainly in command files (@xref{Command Files}). |
| 450 | |
| 451 | @cindex prompt |
| 452 | GDB indicates its readiness to read a command by printing a string |
| 453 | called the @dfn{prompt}. This string is normally @samp{(gdb)}. You can |
| 454 | change the prompt string with the @samp{set prompt} command. For |
| 455 | instance, when debugging GDB with GDB, it is useful to change the prompt |
| 456 | in one of the GDBs so that you tell which one you are talking to. |
| 457 | |
| 458 | @table @code |
| 459 | @item set prompt @var{newprompt} |
| 460 | @kindex set prompt |
| 461 | Directs GDB to use @var{newprompt} as its prompt string henceforth. |
| 462 | @end table |
| 463 | |
| 464 | @cindex exiting GDB |
| 465 | @kindex quit |
| 466 | To exit GDB, use the @samp{quit} command (abbreviated @samp{q}). |
| 467 | @kbd{Ctrl-c} will not exit from GDB, but rather will terminate the action |
| 468 | of any GDB command that is in progress and return to GDB command level. |
| 469 | It is safe to type @kbd{Ctrl-c} at any time because GDB does not allow |
| 470 | it to take effect until a time when it is safe. |
| 471 | |
| 472 | @cindex screen size |
| 473 | @cindex pauses in output |
| 474 | Certain commands to GDB may produce large amounts of information output |
| 475 | to the screen. To help you read all of it, GDB pauses and asks you for |
| 476 | input at the end of each page of output. Type @key{RET} when you want |
| 477 | to continue the output. Normally GDB knows the size of the screen from |
| 478 | on the termcap data base together with the value of the @code{TERM} |
| 479 | environment variable; if this is not correct, you can override it with |
| 480 | the @samp{set screensize} command: |
| 481 | |
| 482 | @table @code |
| 483 | @item set screensize @var{lpp} |
| 484 | @itemx set screensize @var{lpp} @var{cpl} |
| 485 | @kindex set screensize |
| 486 | Specify a screen height of @var{lpp} lines and (optionally) a width of |
| 487 | @var{cpl} characters. If you omit @var{cpl}, the width does not change. |
| 488 | |
| 489 | If you specify a height of zero lines, GDB will not pause during output |
| 490 | no matter how long the output is. This is useful if output is to a file |
| 491 | or to an editor buffer. |
| 492 | @end table |
| 493 | |
| 494 | Also, GDB may at times produce more information about its own workings |
| 495 | than is of interest to the user. Some of these informational messages |
| 496 | can be turned on and off with the @samp{set verbose} command: |
| 497 | |
| 498 | @table @code |
| 499 | @kindex set verbose |
| 500 | @item set verbose off |
| 501 | Disables GDB's output of certain informational messages. |
| 502 | |
| 503 | @item set verbose on |
| 504 | Re-enables GDB's output of certain informational messages. |
| 505 | @end table |
| 506 | |
| 507 | Currently, the messages controlled by @samp{set verbose} are those which |
| 508 | announce that the symbol table for a source file is being read |
| 509 | (@pxref{File Commands}, in the description of the command |
| 510 | @samp{symbol-file}). |
| 511 | @c The following is the right way to do it, but emacs 18.55 doesn't support |
| 512 | @c @ref, and neither the emacs lisp manual version of texinfmt or makeinfo |
| 513 | @c is released. |
| 514 | @ignore |
| 515 | see @samp{symbol-file} in @ref{File Commands}). |
| 516 | @end ignore |
| 517 | |
| 518 | @node Files, Compilation, User Interface, Top |
| 519 | @chapter Specifying GDB's Files |
| 520 | |
| 521 | @cindex core dump file |
| 522 | @cindex executable file |
| 523 | @cindex symbol table |
| 524 | GDB needs to know the file name of the program to be debugged, both in |
| 525 | order to read its symbol table and in order to start the program. To |
| 526 | debug a core dump of a previous run, GDB must be told the file name of |
| 527 | the core dump. |
| 528 | |
| 529 | @menu |
| 530 | * Arguments: File Arguments. Specifying files with arguments |
| 531 | (when you start GDB). |
| 532 | * Commands: File Commands. Specifying files with GDB commands. |
| 533 | @end menu |
| 534 | |
| 535 | @node File Arguments, File Commands, Files, Files |
| 536 | @section Specifying Files with Arguments |
| 537 | |
| 538 | The usual way to specify the executable and core dump file names is with |
| 539 | two command arguments given when you start GDB. The first argument is used |
| 540 | as the file for execution and symbols, and the second argument (if any) is |
| 541 | used as the core dump file name. Thus, |
| 542 | |
| 543 | @example |
| 544 | gdb progm core |
| 545 | @end example |
| 546 | |
| 547 | @noindent |
| 548 | specifies @file{progm} as the executable program and @file{core} as a core |
| 549 | dump file to examine. (You do not need to have a core dump file if what |
| 550 | you plan to do is debug the program interactively.) |
| 551 | |
| 552 | @xref{Options}, for full information on options and arguments for |
| 553 | invoking GDB. |
| 554 | |
| 555 | @node File Commands,, File Arguments, Files |
| 556 | @section Specifying Files with Commands |
| 557 | |
| 558 | Usually you specify the files for GDB to work with by giving arguments when |
| 559 | you invoke GDB. But occasionally it is necessary to change to a different |
| 560 | file during a GDB session. Or you may run GDB and forget to specify the |
| 561 | files you want to use. In these situations the GDB commands to specify new |
| 562 | files are useful. |
| 563 | |
| 564 | @table @code |
| 565 | @item exec-file @var{filename} |
| 566 | @kindex exec-file |
| 567 | Specify that the program to be run is found in @var{filename}. If you |
| 568 | do not specify a directory and the file is not found in GDB's working |
| 569 | directory, GDB will use the environment variable @code{PATH} as a list |
| 570 | of directories to search, just as the shell does when looking for a |
| 571 | program to run. |
| 572 | |
| 573 | @item symbol-file @var{filename} |
| 574 | @kindex symbol-file |
| 575 | Read symbol table information from file @var{filename}. @code{PATH} |
| 576 | is searched when necessary. Most of the time you will use both the |
| 577 | @samp{exec-file} and @samp{symbol-file} commands on the same file. |
| 578 | |
| 579 | @samp{symbol-file} with no argument clears out GDB's symbol table. |
| 580 | |
| 581 | The @samp{symbol-file} command does not actually read the symbol table in |
| 582 | full right away. Instead, it scans the symbol table quickly to find |
| 583 | which source files and which symbols are present. The details are read |
| 584 | later, one source file at a time, when they are needed. |
| 585 | |
| 586 | The purpose of this two-stage reading strategy is to make GDB start up |
| 587 | faster. For the most part, it is invisible except for occasional |
| 588 | messages telling you that the symbol table details for a particular |
| 589 | source file are being read. (The @samp{set verbose} command controls |
| 590 | whether these messages are printed; @pxref{User Interface}). |
| 591 | |
| 592 | However, you will sometimes see in backtraces lines for functions in |
| 593 | source files whose data has not been read in; these lines omit some of |
| 594 | the information, such as argument values, which cannot be printed |
| 595 | without full details of the symbol table. |
| 596 | |
| 597 | When the symbol table is stored in COFF format, @samp{symbol-file} does |
| 598 | read the symbol table data in full right away. We haven't bothered to |
| 599 | implement the two-stage strategy for COFF. |
| 600 | |
| 601 | @item core-file @var{filename} |
| 602 | @kindex core-file |
| 603 | Specify the whereabouts of a core dump file to be used as the |
| 604 | ``contents of memory''. Note that the core dump contains only the |
| 605 | writable parts of memory; the read-only parts must come from the |
| 606 | executable file. |
| 607 | |
| 608 | @samp{core-file} with no argument specifies that no core file is |
| 609 | to be used. |
| 610 | |
| 611 | Note that the core file is ignored when your program is actually running |
| 612 | under GDB. So, if you have been running the program and you wish to |
| 613 | debug a core file instead, you must kill the subprocess in which the |
| 614 | program is running. To do this, use the @samp{kill} command |
| 615 | (@pxref{Kill Process}). |
| 616 | |
| 617 | @item add-file @var{filename} @var{address} |
| 618 | @kindex add-file |
| 619 | @cindex dynamic linking |
| 620 | The @samp{add-file} command reads additional symbol table information |
| 621 | from the file @var{filename}. You would use this when that file has |
| 622 | been dynamically loaded into the program that is running. @var{address} |
| 623 | should be the memory address at which the file has been loaded; GDB cannot |
| 624 | figure this out for itself. |
| 625 | |
| 626 | The symbol table of the file @var{filename} is added to the symbol table |
| 627 | originally read with the @samp{symbol-file} command. You can use the |
| 628 | @samp{add-file} command any number of times; the new symbol data thus |
| 629 | read keeps adding to the old. The @samp{symbol-file} command forgets |
| 630 | all the symbol data GDB has read; that is the only time symbol data is |
| 631 | forgotten in GDB. |
| 632 | |
| 633 | @item info files |
| 634 | @kindex info files |
| 635 | Print the names of the executable and core dump files currently in |
| 636 | use by GDB, and the file from which symbols were loaded. |
| 637 | @end table |
| 638 | |
| 639 | While all three file-specifying commands allow both absolute and relative |
| 640 | file names as arguments, GDB always converts the file name to an absolute |
| 641 | one and remembers it that way. |
| 642 | |
| 643 | The @samp{symbol-file} command causes GDB to forget the contents of its |
| 644 | convenience variables, the value history, and all breakpoints and |
| 645 | auto-display expressions. This is because they may contain pointers to the |
| 646 | internal data recording symbols and data types, which are part of the old |
| 647 | symbol table data being discarded inside GDB. |
| 648 | |
| 649 | @node Compilation, Running, Files, Top |
| 650 | @chapter Compiling Your Program for Debugging |
| 651 | |
| 652 | In order to debug a program effectively, you need to ask for debugging |
| 653 | information when you compile it. This information in the object file |
| 654 | describes the data type of each variable or function and the correspondence |
| 655 | between source line numbers and addresses in the executable code. |
| 656 | |
| 657 | To request debugging information, specify the @samp{-g} option when you run |
| 658 | the compiler. |
| 659 | |
| 660 | The Unix C compiler is unable to handle the @samp{-g} and @samp{-O} options |
| 661 | together. This means that you cannot ask for optimization if you ask for |
| 662 | debugger information. |
| 663 | |
| 664 | The GNU C compiler supports @samp{-g} with or without @samp{-O}, making it |
| 665 | possible to debug optimized code. We recommend that you @emph{always} use |
| 666 | @samp{-g} whenever you compile a program. You may think the program is |
| 667 | correct, but there's no sense in pushing your luck. |
| 668 | |
| 669 | GDB no longer supports the debugging information produced by giving the |
| 670 | GNU C compiler the @samp{-gg} option, so do not use this option. |
| 671 | |
| 672 | @ignore |
| 673 | @comment As far as I know, there are no cases in which GDB will |
| 674 | @comment produce strange output in this case. (but no promises). |
| 675 | If your program includes archives made with the @code{ar} program, and |
| 676 | if the object files used as input to @code{ar} were compiled without the |
| 677 | @samp{-g} option and have names longer than 15 characters, GDB will get |
| 678 | confused reading the program's symbol table. No error message will be |
| 679 | given, but GDB may behave strangely. The reason for this problem is a |
| 680 | deficiency in the Unix archive file format, which cannot represent file |
| 681 | names longer than 15 characters. |
| 682 | |
| 683 | To avoid this problem, compile the archive members with the @samp{-g} |
| 684 | option or use shorter file names. Alternatively, use a version of GNU |
| 685 | @code{ar} dated more recently than August 1989. |
| 686 | @end ignore |
| 687 | |
| 688 | @node Running, Stopping, Compilation, Top |
| 689 | @chapter Running Your Program Under GDB |
| 690 | |
| 691 | @cindex running |
| 692 | @kindex run |
| 693 | To start your program under GDB, use the @samp{run} command. The program |
| 694 | must already have been specified using the @samp{exec-file} command or with |
| 695 | an argument to GDB (@pxref{Files}); what @samp{run} does is create an |
| 696 | inferior process, load the program into it, and set it in motion. |
| 697 | |
| 698 | The execution of a program is affected by certain information it |
| 699 | receives from its superior. GDB provides ways to specify this |
| 700 | information, which you must do @i{before} starting the program. (You |
| 701 | can change it after starting the program, but such changes do not affect |
| 702 | the program unless you start it over again.) This information may be |
| 703 | divided into three categories: |
| 704 | |
| 705 | @table @asis |
| 706 | @item The @i{arguments.} |
| 707 | You specify the arguments to give the program as the arguments of the |
| 708 | @samp{run} command. |
| 709 | |
| 710 | @item The @i{environment.} |
| 711 | The program normally inherits its environment from GDB, but you can |
| 712 | use the GDB commands @samp{set environment} and |
| 713 | @samp{unset environment} to change parts of the environment that will |
| 714 | be given to the program.@refill |
| 715 | |
| 716 | @item The @i{working directory.} |
| 717 | The program inherits its working directory from GDB. You can set GDB's |
| 718 | working directory with the @samp{cd} command in GDB. |
| 719 | @end table |
| 720 | |
| 721 | After the @samp{run} command, the debugger does nothing but wait for your |
| 722 | program to stop. @xref{Stopping}. |
| 723 | |
| 724 | Note that once your program has been started by the @samp{run} command, |
| 725 | you may evaluate expressions that involve calls to functions in the |
| 726 | inferior. @xref{Expressions}. If you wish to evaluate a function |
| 727 | simply for its side affects, you may use the @samp{set} command. |
| 728 | @xref{Assignment}. |
| 729 | |
| 730 | @menu |
| 731 | * Arguments:: Specifying the arguments for your program. |
| 732 | * Environment:: Specifying the environment for your program. |
| 733 | * Working Directory:: Specifying the working directory for giving |
| 734 | to your program when it is run. |
| 735 | * Input/Output:: Specifying the program's standard input and output. |
| 736 | * Attach:: Debugging a process started outside GDB. |
| 737 | * Kill Process:: Getting rid of the child process running your program. |
| 738 | @end menu |
| 739 | |
| 740 | @node Arguments, Environment, Running, Running |
| 741 | @section Your Program's Arguments |
| 742 | |
| 743 | @cindex arguments (to your program) |
| 744 | The arguments to your program are specified by the arguments of the |
| 745 | @samp{run} command. They are passed to a shell, which expands wildcard |
| 746 | characters and performs redirection of I/O, and thence to the program. |
| 747 | |
| 748 | @samp{run} with no arguments uses the same arguments used by the previous |
| 749 | @samp{run}. |
| 750 | |
| 751 | @kindex set args |
| 752 | The command @samp{set args} can be used to specify the arguments to be used |
| 753 | the next time the program is run. If @samp{set args} has no arguments, it |
| 754 | means to use no arguments the next time the program is run. If you have |
| 755 | run your program with arguments and want to run it again with no arguments, |
| 756 | this is the only way to do so. |
| 757 | |
| 758 | @node Environment, Working Directory, Arguments, Running |
| 759 | @section Your Program's Environment |
| 760 | |
| 761 | @cindex environment (of your program) |
| 762 | The @dfn{environment} consists of a set of @dfn{environment variables} and |
| 763 | their values. Environment variables conventionally record such things as |
| 764 | your user name, your home directory, your terminal type, and your search |
| 765 | path for programs to run. Usually you set up environment variables with |
| 766 | the shell and they are inherited by all the other programs you run. When |
| 767 | debugging, it can be useful to try running the program with different |
| 768 | environments without having to start the debugger over again. |
| 769 | |
| 770 | @table @code |
| 771 | @item info environment @var{varname} |
| 772 | @kindex info environment |
| 773 | Print the value of environment variable @var{varname} to be given to |
| 774 | your program when it is started. This command can be abbreviated |
| 775 | @samp{i env @var{varname}}. |
| 776 | |
| 777 | @item info environment |
| 778 | Print the names and values of all environment variables to be given to |
| 779 | your program when it is started. This command can be abbreviated |
| 780 | @samp{i env}. |
| 781 | |
| 782 | @item set environment @var{varname} @var{value} |
| 783 | @itemx set environment @var{varname} = @var{value} |
| 784 | @kindex set environment |
| 785 | Sets environment variable @var{varname} to @var{value}, for your program |
| 786 | only, not for GDB itself. @var{value} may be any string; the values of |
| 787 | environment variables are just strings, and any interpretation is |
| 788 | supplied by your program itself. The @var{value} parameter is optional; |
| 789 | if it is eliminated, the variable is set to a null value. This command |
| 790 | can be abbreviated as short as @samp{set e}. |
| 791 | |
| 792 | For example, this command: |
| 793 | |
| 794 | @example |
| 795 | set env USER = foo |
| 796 | @end example |
| 797 | |
| 798 | @noindent |
| 799 | tells the program, when subsequently run, to assume it is being run |
| 800 | on behalf of the user named @samp{foo}. |
| 801 | |
| 802 | @item delete environment @var{varname} |
| 803 | @itemx unset environment @var{varname} |
| 804 | @kindex delete environment |
| 805 | @kindex unset environment |
| 806 | Remove variable @var{varname} from the environment to be passed to your |
| 807 | program. This is different from @samp{set env @var{varname}@ =} because |
| 808 | @samp{delete environment} leaves the variable with no value, which is |
| 809 | distinguishable from an empty value. This command can be abbreviated |
| 810 | @samp{d e}. |
| 811 | @end table |
| 812 | |
| 813 | @node Working Directory, Input/Output, Environment, Running |
| 814 | @section Your Program's Working Directory |
| 815 | |
| 816 | @cindex working directory (of your program) |
| 817 | Each time you start your program with @samp{run}, it inherits its |
| 818 | working directory from the current working directory of GDB. GDB's |
| 819 | working directory is initially whatever it inherited from its parent |
| 820 | process (typically the shell), but you can specify a new working |
| 821 | directory in GDB with the @samp{cd} command. |
| 822 | |
| 823 | The GDB working directory also serves as a default for the commands |
| 824 | that specify files for GDB to operate on. @xref{Files}. |
| 825 | |
| 826 | @table @code |
| 827 | @item cd @var{directory} |
| 828 | @kindex cd |
| 829 | Set GDB's working directory to @var{directory}. |
| 830 | |
| 831 | @item pwd |
| 832 | @kindex pwd |
| 833 | Print GDB's working directory. |
| 834 | @end table |
| 835 | |
| 836 | @node Input/Output, Attach, Working Directory, Running |
| 837 | @section Your Program's Input and Output |
| 838 | |
| 839 | @cindex redirection |
| 840 | @cindex controlling terminal |
| 841 | By default, the program you run under GDB does input and output to the same |
| 842 | terminal that GDB uses. |
| 843 | |
| 844 | You can redirect the program's input and/or output using @samp{sh}-style |
| 845 | redirection commands in the @samp{run} command. For example, |
| 846 | |
| 847 | @example |
| 848 | run > outfile |
| 849 | @end example |
| 850 | |
| 851 | @noindent |
| 852 | starts the program, diverting its output to the file @file{outfile}. |
| 853 | |
| 854 | @kindex tty |
| 855 | Another way to specify where the program should do input and output is |
| 856 | with the @samp{tty} command. This command accepts a file name as |
| 857 | argument, and causes this file to be the default for future @samp{run} |
| 858 | commands. It also resets the controlling terminal for the child |
| 859 | process, for future @samp{run} commands. For example, |
| 860 | |
| 861 | @example |
| 862 | tty /dev/ttyb |
| 863 | @end example |
| 864 | |
| 865 | @noindent |
| 866 | directs that processes started with subsequent @samp{run} commands |
| 867 | default to do input and output on the terminal @file{/dev/ttyb} and have |
| 868 | that as their controlling terminal. |
| 869 | |
| 870 | An explicit redirection in @samp{run} overrides the @samp{tty} command's |
| 871 | effect on input/output redirection, but not its effect on the |
| 872 | controlling terminal. |
| 873 | |
| 874 | When you use the @samp{tty} command or redirect input in the @samp{run} |
| 875 | command, only the @emph{input for your program} is affected. The input |
| 876 | for GDB still comes from your terminal. |
| 877 | |
| 878 | @node Attach, Kill Process, Input/Output, Running |
| 879 | @section Debugging an Already-Running Process |
| 880 | @kindex detach |
| 881 | @kindex attach |
| 882 | @cindex attach |
| 883 | |
| 884 | Some operating systems allow GDB to debug an already-running process |
| 885 | that was started outside of GDB. To do this, you use the @samp{attach} |
| 886 | command instead of the @samp{run} command. |
| 887 | |
| 888 | The @samp{attach} command requires one argument, which is the process-id |
| 889 | of the process you want to debug. (The usual way to find out the |
| 890 | process-id of the process is with the @code{ps} utility.) |
| 891 | |
| 892 | The first thing GDB does after arranging to debug the process is to stop |
| 893 | it. You can examine and modify an attached process with all the GDB |
| 894 | commands that ordinarily available when you start processes with |
| 895 | @samp{run}. You can insert breakpoints; you can step and continue; you |
| 896 | can modify storage. If you would rather the process continue running, |
| 897 | you may use the @samp{continue} command after attaching GDB to the |
| 898 | process. |
| 899 | |
| 900 | When you have finished debugging the attached process, you can use the |
| 901 | @samp{detach} command to release it from GDB's control. Detaching |
| 902 | the process continues its execution. After the @samp{detach} command, |
| 903 | that process and GDB become completely independent once more, and you |
| 904 | are ready to @samp{attach} another process or start one with @samp{run}. |
| 905 | |
| 906 | If you exit GDB or use the @samp{run} command while you have an attached |
| 907 | process, you kill that process. You will be asked for confirmation if you |
| 908 | try to do either of these things. |
| 909 | |
| 910 | The @samp{attach} command is also used to debug a remote machine via a |
| 911 | serial connection. @xref{Attach}, for more info. |
| 912 | |
| 913 | @node Kill Process,, Attach, Running |
| 914 | @section Killing the Child Process |
| 915 | |
| 916 | @table @code |
| 917 | @item kill |
| 918 | @kindex kill |
| 919 | Kill the child process in which the program being debugged is running |
| 920 | under GDB. |
| 921 | |
| 922 | This command is useful if you wish to debug a core dump instead. GDB |
| 923 | ignores any core dump file if it is actually running the program, so the |
| 924 | @samp{kill} command is the only sure way to make sure the core dump file |
| 925 | is used once again. |
| 926 | |
| 927 | It is also useful if you wish to run the program outside the debugger |
| 928 | for once and then go back to debugging it. |
| 929 | |
| 930 | The @samp{kill} command is also useful if you wish to recompile and |
| 931 | relink the program, since on many systems it is impossible to modify an |
| 932 | executable file which is running in a process. But, in this case, it is |
| 933 | just as good to exit GDB, since you will need to read a new symbol table |
| 934 | after the program is recompiled if you wish to debug the new version, |
| 935 | and restarting GDB is the easiest way to do that. |
| 936 | @end table |
| 937 | |
| 938 | @node Stopping, Stack, Running, Top |
| 939 | @chapter Stopping and Continuing |
| 940 | |
| 941 | When you run a program normally, it runs until it terminates. The |
| 942 | principal purpose of using a debugger is so that you can stop it before |
| 943 | that point; or so that if the program runs into trouble you can |
| 944 | investigate and find out why. |
| 945 | |
| 946 | @menu |
| 947 | * Signals:: Fatal signals in your program just stop it; |
| 948 | then you can use GDB to see what is going on. |
| 949 | * Breakpoints:: Breakpoints let you stop your program when it |
| 950 | reaches a specified point in the code. |
| 951 | * Continuing:: Resuming execution until the next signal or breakpoint. |
| 952 | * Stepping:: Stepping runs the program a short distance and |
| 953 | then stops it wherever it has come to. |
| 954 | @end menu |
| 955 | |
| 956 | @node Signals, Breakpoints, Stopping, Stopping |
| 957 | @section Signals |
| 958 | @cindex signals |
| 959 | |
| 960 | A signal is an asynchronous event that can happen in a program. The |
| 961 | operating system defines the possible kinds of signals, and gives each kind |
| 962 | a name and a number. For example, @code{SIGINT} is the signal a program |
| 963 | gets when you type @kbd{Ctrl-c}; @code{SIGSEGV} is the signal a program |
| 964 | gets from referencing a place in memory far away from all the areas in use; |
| 965 | @code{SIGALRM} occurs when the alarm clock timer goes off (which happens |
| 966 | only if the program has requested an alarm). |
| 967 | |
| 968 | @cindex fatal signals |
| 969 | Some signals, including @code{SIGALRM}, are a normal part of the |
| 970 | functioning of the program. Others, such as @code{SIGSEGV}, indicate |
| 971 | errors; these signals are @dfn{fatal} (kill the program immediately) if the |
| 972 | program has not specified in advance some other way to handle the signal. |
| 973 | @code{SIGINT} does not indicate an error in the program, but it is normally |
| 974 | fatal so it can carry out the purpose of @kbd{Ctrl-c}: to kill the program. |
| 975 | |
| 976 | GDB has the ability to detect any occurrence of a signal in the program |
| 977 | running under GDB's control. You can tell GDB in advance what to do for |
| 978 | each kind of signal. |
| 979 | |
| 980 | @cindex handling signals |
| 981 | Normally, GDB is set up to ignore non-erroneous signals like @code{SIGALRM} |
| 982 | (so as not to interfere with their role in the functioning of the program) |
| 983 | but to stop the program immediately whenever an error signal happens. |
| 984 | You can change these settings with the @samp{handle} command. You must |
| 985 | specify which signal you are talking about with its number. |
| 986 | |
| 987 | @table @code |
| 988 | @item info signal |
| 989 | @kindex info signal |
| 990 | Print a table of all the kinds of signals and how GDB has been told to |
| 991 | handle each one. You can use this to see the signal numbers of all |
| 992 | the defined types of signals. |
| 993 | |
| 994 | @item handle @var{signalnum} @var{keywords}@dots{} |
| 995 | @kindex handle |
| 996 | Change the way GDB handles signal @var{signalnum}. The @var{keywords} |
| 997 | say what change to make. |
| 998 | @end table |
| 999 | |
| 1000 | To use the @samp{handle} command you must know the code number of the |
| 1001 | signal you are concerned with. To find the code number, type @samp{info |
| 1002 | signal} which prints a table of signal names and numbers. |
| 1003 | |
| 1004 | The keywords allowed by the handle command can be abbreviated. Their full |
| 1005 | names are |
| 1006 | |
| 1007 | @table @code |
| 1008 | @item stop |
| 1009 | GDB should stop the program when this signal happens. This implies |
| 1010 | the @samp{print} keyword as well. |
| 1011 | |
| 1012 | @item print |
| 1013 | GDB should print a message when this signal happens. |
| 1014 | |
| 1015 | @item nostop |
| 1016 | GDB should not stop the program when this signal happens. It may |
| 1017 | still print a message telling you that the signal has come in. |
| 1018 | |
| 1019 | @item noprint |
| 1020 | GDB should not mention the occurrence of the signal at all. This |
| 1021 | implies the @samp{nostop} keyword as well. |
| 1022 | |
| 1023 | @item pass |
| 1024 | GDB should allow the program to see this signal; the program will be |
| 1025 | able to handle the signal, or may be terminated if the signal is fatal |
| 1026 | and not handled. |
| 1027 | |
| 1028 | @item nopass |
| 1029 | GDB should not allow the program to see this signal. |
| 1030 | @end table |
| 1031 | |
| 1032 | When a signal has been set to stop the program, the program cannot see the |
| 1033 | signal until you continue. It will see the signal then, if @samp{pass} is |
| 1034 | in effect for the signal in question @i{at that time}. In other words, |
| 1035 | after GDB reports a signal, you can use the @samp{handle} command with |
| 1036 | @samp{pass} or @samp{nopass} to control whether that signal will be seen by |
| 1037 | the program when you later continue it. |
| 1038 | |
| 1039 | You can also use the @samp{signal} command to prevent the program from |
| 1040 | seeing a signal, or cause it to see a signal it normally would not see, |
| 1041 | or to give it any signal at any time. @xref{Signaling}. |
| 1042 | |
| 1043 | @node Breakpoints, Continuing, Signals, Stopping |
| 1044 | @section Breakpoints |
| 1045 | |
| 1046 | @cindex breakpoints |
| 1047 | A @dfn{breakpoint} makes your program stop whenever a certain point in the |
| 1048 | program is reached. You set breakpoints explicitly with GDB commands, |
| 1049 | specifying the place where the program should stop by line number, function |
| 1050 | name or exact address in the program. You can add various other conditions |
| 1051 | to control whether the program will stop. |
| 1052 | |
| 1053 | Each breakpoint is assigned a number when it is created; these numbers are |
| 1054 | successive integers starting with 1. In many of the commands for controlling |
| 1055 | various features of breakpoints you use the breakpoint number to say which |
| 1056 | breakpoint you want to change. Each breakpoint may be @dfn{enabled} or |
| 1057 | @dfn{disabled}; if disabled, it has no effect on the program until you |
| 1058 | enable it again. |
| 1059 | |
| 1060 | @kindex info break |
| 1061 | @kindex $_ |
| 1062 | The command @samp{info break} prints a list of all breakpoints set and not |
| 1063 | deleted, showing their numbers, where in the program they are, and any |
| 1064 | special features in use for them. Disabled breakpoints are included in the |
| 1065 | list, but marked as disabled. @samp{info break} with a breakpoint number |
| 1066 | as argument lists only that breakpoint. The convenience variable @code{$_} |
| 1067 | and the default examining-address for the @samp{x} command are set to the |
| 1068 | address of the last breakpoint listed (@pxref{Memory}). |
| 1069 | |
| 1070 | @menu |
| 1071 | * Set Breaks:: How to establish breakpoints. |
| 1072 | * Delete Breaks:: How to remove breakpoints no longer needed. |
| 1073 | * Disabling:: How to disable breakpoints (turn them off temporarily). |
| 1074 | * Conditions:: Making extra conditions on whether to stop. |
| 1075 | * Break Commands:: Commands to be executed at a breakpoint. |
| 1076 | * Error in Breakpoints:: "Cannot insert breakpoints" error--why, what to do. |
| 1077 | @end menu |
| 1078 | |
| 1079 | @node Set Breaks, Delete Breaks, Breakpoints, Breakpoints |
| 1080 | @subsection Setting Breakpoints |
| 1081 | |
| 1082 | @kindex break |
| 1083 | Breakpoints are set with the @samp{break} command (abbreviated @samp{b}). |
| 1084 | You have several ways to say where the breakpoint should go. |
| 1085 | |
| 1086 | @table @code |
| 1087 | @item break @var{function} |
| 1088 | Set a breakpoint at entry to function @var{function}. |
| 1089 | |
| 1090 | @item break @var{+offset} |
| 1091 | @itemx break @var{-offset} |
| 1092 | Set a breakpoint some number of lines forward or back from the position |
| 1093 | at which execution stopped in the currently selected frame. |
| 1094 | |
| 1095 | @item break @var{linenum} |
| 1096 | Set a breakpoint at line @var{linenum} in the current source file. |
| 1097 | That file is the last file whose source text was printed. This |
| 1098 | breakpoint will stop the program just before it executes any of the |
| 1099 | code on that line. |
| 1100 | |
| 1101 | @item break @var{filename}:@var{linenum} |
| 1102 | Set a breakpoint at line @var{linenum} in source file @var{filename}. |
| 1103 | |
| 1104 | @item break @var{filename}:@var{function} |
| 1105 | Set a breakpoint at entry to function @var{function} found in file |
| 1106 | @var{filename}. Specifying a file name as well as a function name is |
| 1107 | superfluous except when multiple files contain similarly named |
| 1108 | functions. |
| 1109 | |
| 1110 | @item break *@var{address} |
| 1111 | Set a breakpoint at address @var{address}. You can use this to set |
| 1112 | breakpoints in parts of the program which do not have debugging |
| 1113 | information or source files. |
| 1114 | |
| 1115 | @item break |
| 1116 | Set a breakpoint at the next instruction to be executed in the selected |
| 1117 | stack frame (@pxref{Stack}). In any selected frame but the innermost, |
| 1118 | this will cause the program to stop as soon as control returns to that |
| 1119 | frame. This is equivalent to a @samp{finish} command in the frame |
| 1120 | inside the selected frame. If this is done in the innermost frame, GDB |
| 1121 | will stop the next time it reaches the current location; this may be |
| 1122 | useful inside of loops. |
| 1123 | |
| 1124 | GDB normally ignores breakpoints when it resumes execution, until at |
| 1125 | least one instruction has been executed. If it did not do this, you |
| 1126 | would be unable to proceed past a breakpoint without first disabling the |
| 1127 | breakpoint. This rule applies whether or not the breakpoint already |
| 1128 | existed when the program stopped. |
| 1129 | |
| 1130 | @item break @dots{} if @var{cond} |
| 1131 | Set a breakpoint with condition @var{cond}; evaluate the expression |
| 1132 | @var{cond} each time the breakpoint is reached, and stop only if the |
| 1133 | value is nonzero. @samp{@dots{}} stands for one of the possible |
| 1134 | arguments described above (or no argument) specifying where to break. |
| 1135 | @xref{Conditions}, for more information on breakpoint conditions. |
| 1136 | |
| 1137 | @item tbreak @var{args} |
| 1138 | @kindex tbreak |
| 1139 | Set a breakpoint enabled only for one stop. @var{args} are the |
| 1140 | same as in the @samp{break} command, and the breakpoint is set in the same |
| 1141 | way, but the breakpoint is automatically disabled the first time it |
| 1142 | is hit. @xref{Disabling}. |
| 1143 | @end table |
| 1144 | |
| 1145 | GDB allows you to set any number of breakpoints at the same place in the |
| 1146 | program. There is nothing silly or meaningless about this. When the |
| 1147 | breakpoints are conditional, this is even useful (@pxref{Conditions}). |
| 1148 | |
| 1149 | @node Delete Breaks, Disabling, Set Breaks, Breakpoints |
| 1150 | @subsection Deleting Breakpoints |
| 1151 | |
| 1152 | @cindex clearing breakpoint |
| 1153 | @cindex deleting breakpoints |
| 1154 | It is often necessary to eliminate a breakpoint once it has done its job |
| 1155 | and you no longer want the program to stop there. This is called |
| 1156 | @dfn{deleting} the breakpoint. A breakpoint that has been deleted no |
| 1157 | longer exists in any sense; it is forgotten. |
| 1158 | |
| 1159 | With the @samp{clear} command you can delete breakpoints according to where |
| 1160 | they are in the program. With the @samp{delete} command you can delete |
| 1161 | individual breakpoints by specifying their breakpoint numbers. |
| 1162 | |
| 1163 | @b{It is not necessary to delete a breakpoint to proceed past it.} GDB |
| 1164 | automatically ignores breakpoints in the first instruction to be executed |
| 1165 | when you continue execution without changing the execution address. |
| 1166 | |
| 1167 | @table @code |
| 1168 | @item clear |
| 1169 | @kindex clear |
| 1170 | Delete any breakpoints at the next instruction to be executed in the |
| 1171 | selected stack frame (@pxref{Selection}). When the innermost frame |
| 1172 | is selected, this is a good way to delete a breakpoint that the program |
| 1173 | just stopped at. |
| 1174 | |
| 1175 | @item clear @var{function} |
| 1176 | @itemx clear @var{filename}:@var{function} |
| 1177 | Delete any breakpoints set at entry to the function @var{function}. |
| 1178 | |
| 1179 | @item clear @var{linenum} |
| 1180 | @itemx clear @var{filename}:@var{linenum} |
| 1181 | Delete any breakpoints set at or within the code of the specified line. |
| 1182 | |
| 1183 | @item delete @var{bnums}@dots{} |
| 1184 | @kindex delete |
| 1185 | Delete the breakpoints of the numbers specified as arguments. |
| 1186 | @end table |
| 1187 | |
| 1188 | @node Disabling, Conditions, Delete Breaks, Breakpoints |
| 1189 | @subsection Disabling Breakpoints |
| 1190 | |
| 1191 | @cindex disabled breakpoints |
| 1192 | @cindex enabled breakpoints |
| 1193 | Rather than deleting a breakpoint, you might prefer to @dfn{disable} it. |
| 1194 | This makes the breakpoint inoperative as if it had been deleted, but |
| 1195 | remembers the information on the breakpoint so that you can @dfn{enable} |
| 1196 | it again later. |
| 1197 | |
| 1198 | You disable and enable breakpoints with the @samp{enable} and |
| 1199 | @samp{disable} commands, specifying one or more breakpoint numbers as |
| 1200 | arguments. Use @samp{info break} to print a list of breakpoints if you |
| 1201 | don't know which breakpoint numbers to use. |
| 1202 | |
| 1203 | A breakpoint can have any of four different states of enablement: |
| 1204 | |
| 1205 | @itemize @bullet |
| 1206 | @item |
| 1207 | Enabled. The breakpoint will stop the program. A breakpoint made |
| 1208 | with the @samp{break} command starts out in this state. |
| 1209 | @item |
| 1210 | Disabled. The breakpoint has no effect on the program. |
| 1211 | @item |
| 1212 | Enabled once. The breakpoint will stop the program, but |
| 1213 | when it does so it will become disabled. A breakpoint made |
| 1214 | with the @samp{tbreak} command starts out in this state. |
| 1215 | @item |
| 1216 | Enabled for deletion. The breakpoint will stop the program, but |
| 1217 | immediately after it does so it will be deleted permanently. |
| 1218 | @end itemize |
| 1219 | |
| 1220 | You change the state of enablement of a breakpoint with the following |
| 1221 | commands: |
| 1222 | |
| 1223 | @table @code |
| 1224 | @item disable breakpoints @var{bnums}@dots{} |
| 1225 | @itemx disable @var{bnums}@dots{} |
| 1226 | @kindex disable breakpoints |
| 1227 | @kindex disable |
| 1228 | Disable the specified breakpoints. A disabled breakpoint has no |
| 1229 | effect but is not forgotten. All options such as ignore-counts, |
| 1230 | conditions and commands are remembered in case the breakpoint is |
| 1231 | enabled again later. |
| 1232 | |
| 1233 | @item enable breakpoints @var{bnums}@dots{} |
| 1234 | @itemx enable @var{bnums}@dots{} |
| 1235 | @kindex enable breakpoints |
| 1236 | @kindex enable |
| 1237 | Enable the specified breakpoints. They become effective once again in |
| 1238 | stopping the program, until you specify otherwise. |
| 1239 | |
| 1240 | @item enable breakpoints once @var{bnums}@dots{} |
| 1241 | @itemx enable once @var{bnums}@dots{} |
| 1242 | Enable the specified breakpoints temporarily. Each will be disabled |
| 1243 | again the next time it stops the program (unless you have used one of |
| 1244 | these commands to specify a different state before that time comes). |
| 1245 | |
| 1246 | @item enable breakpoints delete @var{bnums}@dots{} |
| 1247 | @itemx enable delete @var{bnums}@dots{} |
| 1248 | Enable the specified breakpoints to work once and then die. Each of |
| 1249 | the breakpoints will be deleted the next time it stops the program |
| 1250 | (unless you have used one of these commands to specify a different |
| 1251 | state before that time comes). |
| 1252 | @end table |
| 1253 | |
| 1254 | Aside from the automatic disablement or deletion of a breakpoint when it |
| 1255 | stops the program, which happens only in certain states, the state of |
| 1256 | enablement of a breakpoint changes only when one of the commands above |
| 1257 | is used. |
| 1258 | |
| 1259 | @node Conditions, Break Commands, Disabling, Breakpoints |
| 1260 | @subsection Break Conditions |
| 1261 | @cindex conditional breakpoints |
| 1262 | @cindex breakpoint conditions |
| 1263 | |
| 1264 | The simplest sort of breakpoint breaks every time the program reaches a |
| 1265 | specified place. You can also specify a @dfn{condition} for a |
| 1266 | breakpoint. A condition is just a boolean expression in your |
| 1267 | programming language. (@xref{Expressions}). A breakpoint with a |
| 1268 | condition evaluates the expression each time the program reaches it, and |
| 1269 | the program stops only if the condition is true. |
| 1270 | |
| 1271 | Break conditions may have side effects, and may even call functions in your |
| 1272 | program. These may sound like strange things to do, but their effects are |
| 1273 | completely predictable unless there is another enabled breakpoint at the |
| 1274 | same address. (In that case, GDB might see the other breakpoint first and |
| 1275 | stop the program without checking the condition of this one.) Note that |
| 1276 | breakpoint commands are usually more convenient and flexible for the |
| 1277 | purpose of performing side effects when a breakpoint is reached |
| 1278 | (@pxref{Break Commands}). |
| 1279 | |
| 1280 | Break conditions can be specified when a breakpoint is set, by using |
| 1281 | @samp{if} in the arguments to the @samp{break} command. @xref{Set Breaks}. |
| 1282 | They can also be changed at any time with the @samp{condition} command: |
| 1283 | |
| 1284 | @table @code |
| 1285 | @item condition @var{bnum} @var{expression} |
| 1286 | @kindex condition |
| 1287 | Specify @var{expression} as the break condition for breakpoint number |
| 1288 | @var{bnum}. From now on, this breakpoint will stop the program only if |
| 1289 | the value of @var{expression} is true (nonzero, in C). @var{expression} |
| 1290 | is not evaluated at the time the @samp{condition} command is given. |
| 1291 | @xref{Expressions}. |
| 1292 | |
| 1293 | @item condition @var{bnum} |
| 1294 | Remove the condition from breakpoint number @var{bnum}. It becomes |
| 1295 | an ordinary unconditional breakpoint. |
| 1296 | @end table |
| 1297 | |
| 1298 | @cindex ignore count (of breakpoint) |
| 1299 | A special case of a breakpoint condition is to stop only when the |
| 1300 | breakpoint has been reached a certain number of times. This is so |
| 1301 | useful that there is a special way to do it, using the @dfn{ignore |
| 1302 | count} of the breakpoint. Every breakpoint has an ignore count, which |
| 1303 | is an integer. Most of the time, the ignore count is zero, and |
| 1304 | therefore has no effect. But if the program reaches a breakpoint whose |
| 1305 | ignore count is positive, then instead of stopping, it just decrements |
| 1306 | the ignore count by one and continues. As a result, if the ignore count |
| 1307 | value is @var{n}, the breakpoint will not stop the next @var{n} times it |
| 1308 | is reached. |
| 1309 | |
| 1310 | @table @code |
| 1311 | @item ignore @var{bnum} @var{count} |
| 1312 | @kindex ignore |
| 1313 | Set the ignore count of breakpoint number @var{bnum} to @var{count}. |
| 1314 | The next @var{count} times the breakpoint is reached, it will not stop. |
| 1315 | |
| 1316 | To make the breakpoint stop the next time it is reached, specify |
| 1317 | a count of zero. |
| 1318 | |
| 1319 | @item cont @var{count} |
| 1320 | Continue execution of the program, setting the ignore count of the |
| 1321 | breakpoint that the program stopped at to @var{count} minus one. |
| 1322 | Thus, the program will not stop at this breakpoint until the |
| 1323 | @var{count}'th time it is reached. |
| 1324 | |
| 1325 | This command is allowed only when the program stopped due to a |
| 1326 | breakpoint. At other times, the argument to @samp{cont} is ignored. |
| 1327 | @end table |
| 1328 | |
| 1329 | If a breakpoint has a positive ignore count and a condition, the condition |
| 1330 | is not checked. Once the ignore count reaches zero, the condition will |
| 1331 | start to be checked. |
| 1332 | |
| 1333 | Note that you could achieve the effect of the ignore count with a |
| 1334 | condition such as @w{@samp{$foo-- <= 0}} using a debugger convenience |
| 1335 | variable that is decremented each time. @xref{Convenience Vars}. |
| 1336 | |
| 1337 | @node Break Commands, Error in Breakpoints, Conditions, Breakpoints |
| 1338 | @subsection Commands Executed on Breaking |
| 1339 | |
| 1340 | @cindex breakpoint commands |
| 1341 | You can give any breakpoint a series of commands to execute when the |
| 1342 | program stops due to that breakpoint. For example, you might want to |
| 1343 | print the values of certain expressions, or enable other breakpoints. |
| 1344 | |
| 1345 | @table @code |
| 1346 | @item commands @var{bnum} |
| 1347 | Specify commands for breakpoint number @var{bnum}. The commands |
| 1348 | themselves appear on the following lines. Type a line containing just |
| 1349 | @samp{end} to terminate the commands. |
| 1350 | |
| 1351 | To remove all commands from a breakpoint, use the command |
| 1352 | @samp{commands} and follow it immediately by @samp{end}; that is, give |
| 1353 | no commands. |
| 1354 | |
| 1355 | With no arguments, @samp{commands} refers to the last breakpoint set. |
| 1356 | @end table |
| 1357 | |
| 1358 | It is possible for breakpoint commands to start the program up again. |
| 1359 | Simply use the @samp{cont} command, or @samp{step}, or any other command |
| 1360 | to resume execution. However, any remaining breakpoint commands are |
| 1361 | ignored. When the program stops again, GDB will act according to the |
| 1362 | cause of that stop. |
| 1363 | |
| 1364 | @kindex silent |
| 1365 | If the first command specified is @samp{silent}, the usual message about |
| 1366 | stopping at a breakpoint is not printed. This may be desirable for |
| 1367 | breakpoints that are to print a specific message and then continue. |
| 1368 | If the remaining commands too print nothing, you will see no sign that |
| 1369 | the breakpoint was reached at all. @samp{silent} is not really a command; |
| 1370 | it is meaningful only at the beginning of the commands for a breakpoint. |
| 1371 | |
| 1372 | The commands @samp{echo} and @samp{output} that allow you to print precisely |
| 1373 | controlled output are often useful in silent breakpoints. @xref{Output}. |
| 1374 | |
| 1375 | For example, here is how you could use breakpoint commands to print the |
| 1376 | value of @code{x} at entry to @code{foo} whenever it is positive. |
| 1377 | |
| 1378 | @example |
| 1379 | break foo if x>0 |
| 1380 | commands |
| 1381 | silent |
| 1382 | echo x is\040 |
| 1383 | output x |
| 1384 | echo \n |
| 1385 | cont |
| 1386 | end |
| 1387 | @end example |
| 1388 | |
| 1389 | One application for breakpoint commands is to correct one bug so you can |
| 1390 | test another. Put a breakpoint just after the erroneous line of code, give |
| 1391 | it a condition to detect the case in which something erroneous has been |
| 1392 | done, and give it commands to assign correct values to any variables that |
| 1393 | need them. End with the @samp{cont} command so that the program does not |
| 1394 | stop, and start with the @samp{silent} command so that no output is |
| 1395 | produced. Here is an example: |
| 1396 | |
| 1397 | @example |
| 1398 | break 403 |
| 1399 | commands |
| 1400 | silent |
| 1401 | set x = y + 4 |
| 1402 | cont |
| 1403 | end |
| 1404 | @end example |
| 1405 | |
| 1406 | One deficiency in the operation of automatically continuing breakpoints |
| 1407 | under Unix appears when your program uses raw mode for the terminal. |
| 1408 | GDB switches back to its own terminal modes (not raw) before executing |
| 1409 | commands, and then must switch back to raw mode when your program is |
| 1410 | continued. This causes any pending terminal input to be lost. |
| 1411 | |
| 1412 | In the GNU system, this will be fixed by changing the behavior of |
| 1413 | terminal modes. |
| 1414 | |
| 1415 | Under Unix, when you have this problem, you might be able to get around |
| 1416 | it by putting your actions into the breakpoint condition instead of |
| 1417 | commands. For example |
| 1418 | |
| 1419 | @example |
| 1420 | condition 5 (x = y + 4), 0 |
| 1421 | @end example |
| 1422 | |
| 1423 | @noindent |
| 1424 | specifies a condition expression (@xref{Expressions}) that will change |
| 1425 | @code{x} as needed, then always have the value 0 so the program will not |
| 1426 | stop. Loss of input is avoided here because break conditions are |
| 1427 | evaluated without changing the terminal modes. When you want to have |
| 1428 | nontrivial conditions for performing the side effects, the operators |
| 1429 | @samp{&&}, @samp{||} and @samp{?@dots{}:} may be useful. |
| 1430 | |
| 1431 | @node Error in Breakpoints,, Break Commands, Breakpoints |
| 1432 | @subsection ``Cannot Insert Breakpoints'' Error |
| 1433 | |
| 1434 | Under some operating systems, breakpoints cannot be used in a program if |
| 1435 | any other process is running that program. Attempting to run or |
| 1436 | continue the program with a breakpoint in this case will cause GDB to |
| 1437 | stop it. |
| 1438 | |
| 1439 | When this happens, you have three ways to proceed: |
| 1440 | |
| 1441 | @enumerate |
| 1442 | @item |
| 1443 | Remove or disable the breakpoints, then continue. |
| 1444 | |
| 1445 | @item |
| 1446 | Suspend GDB, and copy the file containing the program to a new name. |
| 1447 | Resume GDB and use the @samp{exec-file} command to specify that GDB |
| 1448 | should run the program under that name. Then start the program again. |
| 1449 | |
| 1450 | @item |
| 1451 | Relink the program so that the text segment is nonsharable, using the |
| 1452 | linker option @samp{-N}. The operating system limitation may not apply |
| 1453 | to nonsharable executables. |
| 1454 | @end enumerate |
| 1455 | |
| 1456 | @node Continuing, Stepping, Breakpoints, Stopping |
| 1457 | @section Continuing |
| 1458 | |
| 1459 | After your program stops, most likely you will want it to run some more if |
| 1460 | the bug you are looking for has not happened yet. |
| 1461 | |
| 1462 | @table @code |
| 1463 | @item cont |
| 1464 | @kindex cont |
| 1465 | Continue running the program at the place where it stopped. |
| 1466 | @end table |
| 1467 | |
| 1468 | If the program stopped at a breakpoint, the place to continue running |
| 1469 | is the address of the breakpoint. You might expect that continuing would |
| 1470 | just stop at the same breakpoint immediately. In fact, @samp{cont} |
| 1471 | takes special care to prevent that from happening. You do not need |
| 1472 | to delete the breakpoint to proceed through it after stopping at it. |
| 1473 | |
| 1474 | You can, however, specify an ignore-count for the breakpoint that the |
| 1475 | program stopped at, by means of an argument to the @samp{cont} command. |
| 1476 | @xref{Conditions}. |
| 1477 | |
| 1478 | If the program stopped because of a signal other than @code{SIGINT} or |
| 1479 | @code{SIGTRAP}, continuing will cause the program to see that signal. |
| 1480 | You may not want this to happen. For example, if the program stopped |
| 1481 | due to some sort of memory reference error, you might store correct |
| 1482 | values into the erroneous variables and continue, hoping to see more |
| 1483 | execution; but the program would probably terminate immediately as |
| 1484 | a result of the fatal signal once it sees the signal. To prevent this, |
| 1485 | you can continue with @samp{signal 0}. @xref{Signaling}. You can |
| 1486 | also act in advance to prevent the program from seeing certain kinds |
| 1487 | of signals, using the @samp{handle} command (@pxref{Signals}). |
| 1488 | |
| 1489 | @node Stepping,, Continuing, Stopping |
| 1490 | @section Stepping |
| 1491 | |
| 1492 | @cindex stepping |
| 1493 | @dfn{Stepping} means setting your program in motion for a limited time, so |
| 1494 | that control will return automatically to the debugger after one line of |
| 1495 | code or one machine instruction. Breakpoints are active during stepping |
| 1496 | and the program will stop for them even if it has not gone as far as the |
| 1497 | stepping command specifies. |
| 1498 | |
| 1499 | @table @code |
| 1500 | @item step |
| 1501 | @kindex step |
| 1502 | Continue running the program until control reaches a different line, |
| 1503 | then stop it and return control to the debugger. This command is |
| 1504 | abbreviated @samp{s}. |
| 1505 | |
| 1506 | This command may be given when control is within a function for which |
| 1507 | there is no debugging information. In that case, execution will proceed |
| 1508 | until control reaches a different function, or is about to return from |
| 1509 | this function. An argument repeats this action. |
| 1510 | |
| 1511 | @item step @var{count} |
| 1512 | Continue running as in @samp{step}, but do so @var{count} times. If a |
| 1513 | breakpoint is reached or a signal not related to stepping occurs before |
| 1514 | @var{count} steps, stepping stops right away. |
| 1515 | |
| 1516 | @item next |
| 1517 | @kindex next |
| 1518 | Similar to @samp{step}, but any function calls appearing within the line of |
| 1519 | code are executed without stopping. Execution stops when control reaches a |
| 1520 | different line of code at the stack level which was executing when the |
| 1521 | @samp{next} command was given. This command is abbreviated @samp{n}. |
| 1522 | |
| 1523 | An argument is a repeat count, as in @samp{step}. |
| 1524 | |
| 1525 | @samp{next} within a function without debugging information acts as does |
| 1526 | @samp{step}, but any function calls appearing within the code of the |
| 1527 | function are executed without stopping. |
| 1528 | |
| 1529 | @item finish |
| 1530 | @kindex finish |
| 1531 | Continue running until just after the selected stack frame returns (or |
| 1532 | until there is some other reason to stop, such as a fatal signal or a |
| 1533 | breakpoint). Print value returned by the selected stack frame (if any). |
| 1534 | |
| 1535 | Contrast this with the @samp{return} command (@pxref{Returning}). |
| 1536 | |
| 1537 | @item until |
| 1538 | @kindex until |
| 1539 | This command is used to avoid single stepping through a loop more than |
| 1540 | once. It is like the @samp{next} command, except that when @samp{until} |
| 1541 | encounters a jump, it automatically continues execution until the |
| 1542 | program counter is greater than the address of the jump. |
| 1543 | |
| 1544 | This means that when you reach the end of a loop after single stepping |
| 1545 | though it, @samp{until} will cause the program to continue execution |
| 1546 | until the loop is exited. In contrast, a @samp{next} command at the end |
| 1547 | of a loop will simply step back to the beginning of the loop, which |
| 1548 | would force you to step through the next iteration. |
| 1549 | |
| 1550 | @samp{until} always stops the program if it attempts to exit the current |
| 1551 | stack frame. |
| 1552 | |
| 1553 | @samp{until} may produce somewhat counterintuitive results if the order |
| 1554 | of the source lines does not match the actual order of execution. For |
| 1555 | example, in a typical C @code{for}-loop, the third expression in the |
| 1556 | @code{for}-statement (the loop-step expression) is executed after the |
| 1557 | statements in the body of the loop, but is written before them. |
| 1558 | Therefore, the @samp{until} command would appear to step back to the |
| 1559 | beginning of the loop when it advances to this expression. However, it |
| 1560 | has not really done so, not in terms of the actual machine code. |
| 1561 | |
| 1562 | Note that @samp{until} with no argument works by means of single |
| 1563 | instruction stepping, and hence is slower than @samp{until} with an |
| 1564 | argument. |
| 1565 | |
| 1566 | @item until @var{location} |
| 1567 | Continue running the program until either the specified location is |
| 1568 | reached, or the current (innermost) stack frame returns. This form of |
| 1569 | the command uses breakpoints, and hence is quicker than @samp{until} |
| 1570 | without an argument. |
| 1571 | |
| 1572 | @item stepi |
| 1573 | @itemx si |
| 1574 | @kindex stepi |
| 1575 | @kindex si |
| 1576 | Execute one machine instruction, then stop and return to the debugger. |
| 1577 | |
| 1578 | It is often useful to do @samp{display/i $pc} when stepping by machine |
| 1579 | instructions. This will cause the next instruction to be executed to |
| 1580 | be displayed automatically at each stop. @xref{Auto Display}. |
| 1581 | |
| 1582 | An argument is a repeat count, as in @samp{step}. |
| 1583 | |
| 1584 | @item nexti |
| 1585 | @itemx ni |
| 1586 | @kindex nexti |
| 1587 | @kindex ni |
| 1588 | Execute one machine instruction, but if it is a subroutine call, |
| 1589 | proceed until the subroutine returns. |
| 1590 | |
| 1591 | An argument is a repeat count, as in @samp{next}. |
| 1592 | @end table |
| 1593 | |
| 1594 | A typical technique for using stepping is to put a breakpoint |
| 1595 | (@pxref{Breakpoints}) at the beginning of the function or the section of |
| 1596 | the program in which a problem is believed to lie, and then step through |
| 1597 | the suspect area, examining the variables that are interesting, until the |
| 1598 | problem happens. |
| 1599 | |
| 1600 | The @samp{cont} command can be used after stepping to resume execution |
| 1601 | until the next breakpoint or signal. |
| 1602 | |
| 1603 | @node Stack, Source, Stopping, Top |
| 1604 | @chapter Examining the Stack |
| 1605 | |
| 1606 | When your program has stopped, the first thing you need to know is where it |
| 1607 | stopped and how it got there. |
| 1608 | |
| 1609 | @cindex call stack |
| 1610 | Each time your program performs a function call, the information about |
| 1611 | where in the program the call was made from is saved in a block of data |
| 1612 | called a @dfn{stack frame}. The frame also contains the arguments of the |
| 1613 | call and the local variables of the function that was called. All the |
| 1614 | stack frames are allocated in a region of memory called the @dfn{call |
| 1615 | stack}. |
| 1616 | |
| 1617 | When your program stops, the GDB commands for examining the stack allow you |
| 1618 | to see all of this information. |
| 1619 | |
| 1620 | One of the stack frames is @dfn{selected} by GDB and many GDB commands |
| 1621 | refer implicitly to the selected frame. In particular, whenever you ask |
| 1622 | GDB for the value of a variable in the program, the value is found in the |
| 1623 | selected frame. There are special GDB commands to select whichever frame |
| 1624 | you are interested in. |
| 1625 | |
| 1626 | When the program stops, GDB automatically selects the currently executing |
| 1627 | frame and describes it briefly as the @samp{frame} command does |
| 1628 | (@pxref{Frame Info, Info}). |
| 1629 | |
| 1630 | @menu |
| 1631 | * Frames:: Explanation of stack frames and terminology. |
| 1632 | * Backtrace:: Summarizing many frames at once. |
| 1633 | * Selection:: How to select a stack frame. |
| 1634 | * Info: Frame Info, Commands to print information on stack frames. |
| 1635 | @end menu |
| 1636 | |
| 1637 | @node Frames, Backtrace, Stack, Stack |
| 1638 | @section Stack Frames |
| 1639 | |
| 1640 | @cindex frame |
| 1641 | @cindex stack frame |
| 1642 | The call stack is divided up into contiguous pieces called @dfn{stack |
| 1643 | frames}, or @dfn{frames} for short; each frame is the data associated |
| 1644 | with one call to one function. The frame contains the arguments given |
| 1645 | to the function, the function's local variables, and the address at |
| 1646 | which the function is executing. |
| 1647 | |
| 1648 | @cindex initial frame |
| 1649 | @cindex outermost frame |
| 1650 | @cindex innermost frame |
| 1651 | When your program is started, the stack has only one frame, that of the |
| 1652 | function @code{main}. This is called the @dfn{initial} frame or the |
| 1653 | @dfn{outermost} frame. Each time a function is called, a new frame is |
| 1654 | made. Each time a function returns, the frame for that function invocation |
| 1655 | is eliminated. If a function is recursive, there can be many frames for |
| 1656 | the same function. The frame for the function in which execution is |
| 1657 | actually occurring is called the @dfn{innermost} frame. This is the most |
| 1658 | recently created of all the stack frames that still exist. |
| 1659 | |
| 1660 | @cindex frame pointer |
| 1661 | Inside your program, stack frames are identified by their addresses. A |
| 1662 | stack frame consists of many bytes, each of which has its own address; each |
| 1663 | kind of computer has a convention for choosing one of those bytes whose |
| 1664 | address serves as the address of the frame. Usually this address is kept |
| 1665 | in a register called the @dfn{frame pointer register} while execution is |
| 1666 | going on in that frame. |
| 1667 | |
| 1668 | @cindex frame number |
| 1669 | GDB assigns numbers to all existing stack frames, starting with zero for |
| 1670 | the innermost frame, one for the frame that called it, and so on upward. |
| 1671 | These numbers do not really exist in your program; they are to give you a |
| 1672 | way of talking about stack frames in GDB commands. |
| 1673 | |
| 1674 | @cindex selected frame |
| 1675 | Many GDB commands refer implicitly to one stack frame. GDB records a stack |
| 1676 | frame that is called the @dfn{selected} stack frame; you can select any |
| 1677 | frame using one set of GDB commands, and then other commands will operate |
| 1678 | on that frame. When your program stops, GDB automatically selects the |
| 1679 | innermost frame. |
| 1680 | |
| 1681 | @cindex frameless execution |
| 1682 | Some functions can be compiled to run without a frame reserved for them |
| 1683 | on the stack. This is occasionally done with heavily used library |
| 1684 | functions to save the frame setup time. GDB has limited facilities for |
| 1685 | dealing with these function invocations; if the innermost function |
| 1686 | invocation has no stack frame, GDB will give it a virtual stack frame of |
| 1687 | 0 and correctly allow tracing of the function call chain. Results are |
| 1688 | undefined if a function invocation besides the innermost one is |
| 1689 | frameless. |
| 1690 | |
| 1691 | @node Backtrace, Selection, Frames, Stack |
| 1692 | @section Backtraces |
| 1693 | |
| 1694 | A backtrace is a summary of how the program got where it is. It shows one |
| 1695 | line per frame, for many frames, starting with the currently executing |
| 1696 | frame (frame zero), followed by its caller (frame one), and on up the |
| 1697 | stack. |
| 1698 | |
| 1699 | @table @code |
| 1700 | @item backtrace |
| 1701 | @itemx bt |
| 1702 | @kindex backtrace |
| 1703 | @kindex bt |
| 1704 | Print a backtrace of the entire stack: one line per frame for all |
| 1705 | frames in the stack. |
| 1706 | |
| 1707 | You can stop the backtrace at any time by typing the system interrupt |
| 1708 | character, normally @kbd{Control-C}. |
| 1709 | |
| 1710 | @item backtrace @var{n} |
| 1711 | @itemx bt @var{n} |
| 1712 | Similar, but print only the innermost @var{n} frames. |
| 1713 | |
| 1714 | @item backtrace @var{-n} |
| 1715 | @itemx bt @var{-n} |
| 1716 | Similar, but print only the outermost @var{n} frames. |
| 1717 | @end table |
| 1718 | |
| 1719 | @kindex where |
| 1720 | @kindex info stack |
| 1721 | The names @samp{where} and @samp{info stack} are additional aliases |
| 1722 | for @samp{backtrace}. |
| 1723 | |
| 1724 | Every line in the backtrace shows the frame number, the function name |
| 1725 | and the program counter value. |
| 1726 | |
| 1727 | If the function is in a source file whose symbol table data has been |
| 1728 | fully read, the backtrace shows the source file name and line number, as |
| 1729 | well as the arguments to the function. (The program counter value is |
| 1730 | omitted if it is at the beginning of the code for that line number.) |
| 1731 | |
| 1732 | If the source file's symbol data has not been fully read, just scanned, |
| 1733 | this extra information is replaced with an ellipsis. You can force the |
| 1734 | symbol data for that frame's source file to be read by selecting the |
| 1735 | frame. (@xref{Selection}). |
| 1736 | |
| 1737 | Here is an example of a backtrace. It was made with the command |
| 1738 | @samp{bt 3}, so it shows the innermost three frames. |
| 1739 | |
| 1740 | @example |
| 1741 | #0 rtx_equal_p (x=(rtx) 0x8e58c, y=(rtx) 0x1086c4) (/gp/rms/cc/rtlanal.c line 337) |
| 1742 | #1 0x246b0 in expand_call (...) (...) |
| 1743 | #2 0x21cfc in expand_expr (...) (...) |
| 1744 | (More stack frames follow...) |
| 1745 | @end example |
| 1746 | |
| 1747 | @noindent |
| 1748 | The functions @code{expand_call} and @code{expand_expr} are in a file |
| 1749 | whose symbol details have not been fully read. Full detail is available |
| 1750 | for the function @code{rtx_equal_p}, which is in the file |
| 1751 | @file{rtlanal.c}. Its arguments, named @code{x} and @code{y}, are shown |
| 1752 | with their typed values. |
| 1753 | |
| 1754 | @node Selection, Frame Info, Backtrace, Stack |
| 1755 | @section Selecting a Frame |
| 1756 | |
| 1757 | Most commands for examining the stack and other data in the program work on |
| 1758 | whichever stack frame is selected at the moment. Here are the commands for |
| 1759 | selecting a stack frame; all of them finish by printing a brief description |
| 1760 | of the stack frame just selected. |
| 1761 | |
| 1762 | @table @code |
| 1763 | @item frame @var{n} |
| 1764 | @kindex frame |
| 1765 | Select frame number @var{n}. Recall that frame zero is the innermost |
| 1766 | (currently executing) frame, frame one is the frame that called the |
| 1767 | innermost one, and so on. The highest-numbered frame is @code{main}'s |
| 1768 | frame. |
| 1769 | |
| 1770 | @item frame @var{addr} |
| 1771 | Select the frame at address @var{addr}. This is useful mainly if the |
| 1772 | chaining of stack frames has been damaged by a bug, making it |
| 1773 | impossible for GDB to assign numbers properly to all frames. In |
| 1774 | addition, this can be useful when the program has multiple stacks and |
| 1775 | switches between them. |
| 1776 | |
| 1777 | @item up @var{n} |
| 1778 | @kindex up |
| 1779 | Select the frame @var{n} frames up from the frame previously selected. |
| 1780 | For positive numbers @var{n}, this advances toward the outermost |
| 1781 | frame, to higher frame numbers, to frames that have existed longer. |
| 1782 | @var{n} defaults to one. |
| 1783 | |
| 1784 | @item down @var{n} |
| 1785 | @kindex down |
| 1786 | Select the frame @var{n} frames down from the frame previously |
| 1787 | selected. For positive numbers @var{n}, this advances toward the |
| 1788 | innermost frame, to lower frame numbers, to frames that were created |
| 1789 | more recently. @var{n} defaults to one. |
| 1790 | @end table |
| 1791 | |
| 1792 | All of these commands end by printing some information on the frame that |
| 1793 | has been selected: the frame number, the function name, the arguments, the |
| 1794 | source file and line number of execution in that frame, and the text of |
| 1795 | that source line. For example: |
| 1796 | |
| 1797 | @example |
| 1798 | #3 main (argc=3, argv=??, env=??) at main.c, line 67 |
| 1799 | 67 read_input_file (argv[i]); |
| 1800 | @end example |
| 1801 | |
| 1802 | After such a printout, the @samp{list} command with no arguments will print |
| 1803 | ten lines centered on the point of execution in the frame. @xref{List}. |
| 1804 | |
| 1805 | @node Frame Info,, Selection, Stack |
| 1806 | @section Information on a Frame |
| 1807 | |
| 1808 | There are several other commands to print information about the selected |
| 1809 | stack frame. |
| 1810 | |
| 1811 | @table @code |
| 1812 | @item frame |
| 1813 | This command prints a brief description of the selected stack frame. |
| 1814 | It can be abbreviated @samp{f}. With an argument, this command is |
| 1815 | used to select a stack frame; with no argument, it does not change |
| 1816 | which frame is selected, but still prints the same information. |
| 1817 | |
| 1818 | @item info frame |
| 1819 | @kindex info frame |
| 1820 | This command prints a verbose description of the selected stack frame, |
| 1821 | including the address of the frame, the addresses of the next frame in |
| 1822 | (called by this frame) and the next frame out (caller of this frame), |
| 1823 | the address of the frame's arguments, the program counter saved in it |
| 1824 | (the address of execution in the caller frame), and which registers |
| 1825 | were saved in the frame. The verbose description is useful when |
| 1826 | something has gone wrong that has made the stack format fail to fit |
| 1827 | the usual conventions. |
| 1828 | |
| 1829 | @item info frame @var{addr} |
| 1830 | Print a verbose description of the frame at address @var{addr}, |
| 1831 | without selecting that frame. The selected frame remains unchanged by |
| 1832 | this command. |
| 1833 | |
| 1834 | @item info args |
| 1835 | @kindex info args |
| 1836 | Print the arguments of the selected frame, each on a separate line. |
| 1837 | |
| 1838 | @item info locals |
| 1839 | @kindex info locals |
| 1840 | Print the local variables of the selected frame, each on a separate |
| 1841 | line. These are all variables declared static or automatic within all |
| 1842 | program blocks that execution in this frame is currently inside of. |
| 1843 | @end table |
| 1844 | |
| 1845 | @node Source, Data, Stack, Top |
| 1846 | @chapter Examining Source Files |
| 1847 | |
| 1848 | GDB knows which source files your program was compiled from, and |
| 1849 | can print parts of their text. When your program stops, GDB |
| 1850 | spontaneously prints the line it stopped in. Likewise, when you |
| 1851 | select a stack frame (@pxref{Selection}), GDB prints the line |
| 1852 | which execution in that frame has stopped in. You can also |
| 1853 | print parts of source files by explicit command. |
| 1854 | |
| 1855 | @menu |
| 1856 | * List:: Using the @samp{list} command to print source files. |
| 1857 | * Search:: Commands for searching source files. |
| 1858 | * Source Path:: Specifying the directories to search for source files. |
| 1859 | @end menu |
| 1860 | |
| 1861 | @node List, Search, Source, Source |
| 1862 | @section Printing Source Lines |
| 1863 | |
| 1864 | @kindex list |
| 1865 | To print lines from a source file, use the @samp{list} command |
| 1866 | (abbreviated @samp{l}). There are several ways to specify what part |
| 1867 | of the file you want to print. |
| 1868 | |
| 1869 | Here are the forms of the @samp{list} command most commonly used: |
| 1870 | |
| 1871 | @table @code |
| 1872 | @item list @var{linenum} |
| 1873 | Print ten lines centered around line number @var{linenum} in the |
| 1874 | current source file. |
| 1875 | |
| 1876 | @item list @var{function} |
| 1877 | Print ten lines centered around the beginning of function |
| 1878 | @var{function}. |
| 1879 | |
| 1880 | @item list |
| 1881 | Print ten more lines. If the last lines printed were printed with a |
| 1882 | @samp{list} command, this prints ten lines following the last lines |
| 1883 | printed; however, if the last line printed was a solitary line printed |
| 1884 | as part of displaying a stack frame (@pxref{Stack}), this prints ten |
| 1885 | lines centered around that line. |
| 1886 | |
| 1887 | @item list - |
| 1888 | Print ten lines just before the lines last printed. |
| 1889 | @end table |
| 1890 | |
| 1891 | Repeating a @samp{list} command with @key{RET} discards the argument, |
| 1892 | so it is equivalent to typing just @samp{list}. This is more useful |
| 1893 | than listing the same lines again. An exception is made for an |
| 1894 | argument of @samp{-}; that argument is preserved in repetition so that |
| 1895 | each repetition moves up in the file. |
| 1896 | |
| 1897 | @cindex linespec |
| 1898 | In general, the @samp{list} command expects you to supply zero, one or two |
| 1899 | @dfn{linespecs}. Linespecs specify source lines; there are several ways |
| 1900 | of writing them but the effect is always to specify some source line. |
| 1901 | Here is a complete description of the possible arguments for @samp{list}: |
| 1902 | |
| 1903 | @table @code |
| 1904 | @item list @var{linespec} |
| 1905 | Print ten lines centered around the line specified by @var{linespec}. |
| 1906 | |
| 1907 | @item list @var{first},@var{last} |
| 1908 | Print lines from @var{first} to @var{last}. Both arguments are |
| 1909 | linespecs. |
| 1910 | |
| 1911 | @item list ,@var{last} |
| 1912 | Print ten lines ending with @var{last}. |
| 1913 | |
| 1914 | @item list @var{first}, |
| 1915 | Print ten lines starting with @var{first}. |
| 1916 | |
| 1917 | @item list + |
| 1918 | Print ten lines just after the lines last printed. |
| 1919 | |
| 1920 | @item list - |
| 1921 | Print ten lines just before the lines last printed. |
| 1922 | |
| 1923 | @item list |
| 1924 | As described in the preceding table. |
| 1925 | @end table |
| 1926 | |
| 1927 | Here are the ways of specifying a single source line---all the |
| 1928 | kinds of linespec. |
| 1929 | |
| 1930 | @table @code |
| 1931 | @item @var{linenum} |
| 1932 | Specifies line @var{linenum} of the current source file. |
| 1933 | When a @samp{list} command has two linespecs, this refers to |
| 1934 | the same source file as the first linespec. |
| 1935 | |
| 1936 | @item +@var{offset} |
| 1937 | Specifies the line @var{offset} lines after the last line printed. |
| 1938 | When used as the second linespec in a @samp{list} command that has |
| 1939 | two, this specifies the line @var{offset} lines down from the |
| 1940 | first linespec. |
| 1941 | |
| 1942 | @item -@var{offset} |
| 1943 | Specifies the line @var{offset} lines before the last line printed. |
| 1944 | |
| 1945 | @item @var{filename}:@var{linenum} |
| 1946 | Specifies line @var{linenum} in the source file @var{filename}. |
| 1947 | |
| 1948 | @item @var{function} |
| 1949 | Specifies the line of the open-brace that begins the body of the |
| 1950 | function @var{function}. |
| 1951 | |
| 1952 | @item @var{filename}:@var{function} |
| 1953 | Specifies the line of the open-brace that begins the body of the |
| 1954 | function @var{function} in the file @var{filename}. The file name is |
| 1955 | needed with a function name only for disambiguation of identically |
| 1956 | named functions in different source files. |
| 1957 | |
| 1958 | @item *@var{address} |
| 1959 | Specifies the line containing the program address @var{address}. |
| 1960 | @var{address} may be any expression. |
| 1961 | @end table |
| 1962 | |
| 1963 | One other command is used to map source lines to program addresses. |
| 1964 | |
| 1965 | @table @code |
| 1966 | @item info line @var{linenum} |
| 1967 | @kindex info line |
| 1968 | Print the starting and ending addresses of the compiled code for |
| 1969 | source line @var{linenum}. |
| 1970 | |
| 1971 | @kindex $_ |
| 1972 | The default examine address for the @samp{x} command is changed to the |
| 1973 | starting address of the line, so that @samp{x/i} is sufficient to |
| 1974 | begin examining the machine code (@pxref{Memory}). Also, this address |
| 1975 | is saved as the value of the convenience variable @code{$_} |
| 1976 | (@pxref{Convenience Vars}). |
| 1977 | @end table |
| 1978 | |
| 1979 | @node Search, Source Path, List, Source |
| 1980 | @section Searching Source Files |
| 1981 | @cindex searching |
| 1982 | @kindex forward-search |
| 1983 | @kindex reverse-search |
| 1984 | |
| 1985 | There are two commands for searching through the current source file for a |
| 1986 | regular expression. |
| 1987 | |
| 1988 | The command @samp{forward-search @var{regexp}} checks each line, starting |
| 1989 | with the one following the last line listed, for a match for @var{regexp}. |
| 1990 | It lists the line that is found. You can abbreviate the command name |
| 1991 | as @samp{fo}. |
| 1992 | |
| 1993 | The command @samp{reverse-search @var{regexp}} checks each line, starting |
| 1994 | with the one before the last line listed and going backward, for a match |
| 1995 | for @var{regexp}. It lists the line that is found. You can abbreviate |
| 1996 | this command with as little as @samp{rev}. |
| 1997 | |
| 1998 | @node Source Path,, Search, Source |
| 1999 | @section Specifying Source Directories |
| 2000 | |
| 2001 | @cindex source path |
| 2002 | @cindex directories for source files |
| 2003 | Executable programs do not record the directories of the source files |
| 2004 | from which they were compiled, just the names. GDB remembers a list of |
| 2005 | directories to search for source files; this is called the @dfn{source |
| 2006 | path}. Each time GDB wants a source file, it tries all the directories |
| 2007 | in the list, in the order they are present in the list, until it finds a |
| 2008 | file with the desired name. @b{Note that the executable search path is |
| 2009 | @i{not} used for this purpose. Neither is the current working |
| 2010 | directory, unless it happens to be in the source path.} |
| 2011 | |
| 2012 | @kindex directory |
| 2013 | When you start GDB, its source path contains just the current working |
| 2014 | directory. To add other directories, use the @samp{directory} command. |
| 2015 | |
| 2016 | @table @code |
| 2017 | @item directory @var{dirnames...} |
| 2018 | Add directory @var{dirname} to the end of the source path. Several |
| 2019 | directory names may be given to this command, separated by whitespace or |
| 2020 | @samp{:}. |
| 2021 | |
| 2022 | @item directory |
| 2023 | Reset the source path to just the current working directory of GDB. |
| 2024 | This requires confirmation. |
| 2025 | |
| 2026 | Since this command deletes directories from the search path, it may |
| 2027 | change the directory in which a previously read source file will be |
| 2028 | discovered. To make this work correctly, this command also clears out |
| 2029 | the tables GDB maintains about the source files it has already found. |
| 2030 | |
| 2031 | @item info directories |
| 2032 | @kindex info directories |
| 2033 | Print the source path: show which directories it contains. |
| 2034 | @end table |
| 2035 | |
| 2036 | Because the @samp{directory} command adds to the end of the source path, |
| 2037 | it does not affect any file that GDB has already found. If the source |
| 2038 | path contains directories that you do not want, and these directories |
| 2039 | contain misleading files with names matching your source files, the |
| 2040 | way to correct the situation is as follows: |
| 2041 | |
| 2042 | @enumerate |
| 2043 | @item |
| 2044 | Choose the directory you want at the beginning of the source path. |
| 2045 | Use the @samp{cd} command to make that the current working directory. |
| 2046 | |
| 2047 | @item |
| 2048 | Use @samp{directory} with no argument to reset the source path to just |
| 2049 | that directory. |
| 2050 | |
| 2051 | @item |
| 2052 | Use @samp{directory} with suitable arguments to add any other |
| 2053 | directories you want in the source path. |
| 2054 | @end enumerate |
| 2055 | |
| 2056 | @node Data, Symbols, Source, Top |
| 2057 | @chapter Examining Data |
| 2058 | |
| 2059 | @cindex printing data |
| 2060 | @cindex examining data |
| 2061 | @kindex print |
| 2062 | The usual way to examine data in your program is with the @samp{print} |
| 2063 | command (abbreviated @samp{p}). It evaluates and prints the value of any |
| 2064 | valid expression of the language the program is written in (for now, C). |
| 2065 | You type |
| 2066 | |
| 2067 | @example |
| 2068 | print @var{exp} |
| 2069 | @end example |
| 2070 | |
| 2071 | @noindent |
| 2072 | where @var{exp} is any valid expression, and the value of @var{exp} |
| 2073 | is printed in a format appropriate to its data type. |
| 2074 | |
| 2075 | A more low-level way of examining data is with the @samp{x} command. |
| 2076 | It examines data in memory at a specified address and prints it in a |
| 2077 | specified format. |
| 2078 | |
| 2079 | @menu |
| 2080 | * Expressions:: Expressions that can be computed and printed. |
| 2081 | * Variables:: Using your program's variables in expressions. |
| 2082 | * Assignment:: Setting your program's variables. |
| 2083 | * Arrays:: Examining part of memory as an array. |
| 2084 | * Format Options:: Controlling how structures and arrays are printed. |
| 2085 | * Output formats:: Specifying formats for printing values. |
| 2086 | * Memory:: Examining memory explicitly. |
| 2087 | * Auto Display:: Printing certain expressions whenever program stops. |
| 2088 | * Value History:: Referring to values previously printed. |
| 2089 | * Convenience Vars:: Giving names to values for future reference. |
| 2090 | * Registers:: Referring to and storing in machine registers. |
| 2091 | @end menu |
| 2092 | |
| 2093 | @node Expressions, Variables, Data, Data |
| 2094 | @section Expressions |
| 2095 | |
| 2096 | @cindex expressions |
| 2097 | Many different GDB commands accept an expression and compute its value. |
| 2098 | Any kind of constant, variable or operator defined by the programming |
| 2099 | language you are using is legal in an expression in GDB. This includes |
| 2100 | conditional expressions, function calls, casts and string constants. |
| 2101 | It unfortunately does not include symbols defined by preprocessor |
| 2102 | @code{#define} commands. |
| 2103 | |
| 2104 | Casts are supported in all languages, not just in C, because it is so |
| 2105 | useful to cast a number into a pointer so as to examine a structure |
| 2106 | at that address in memory. |
| 2107 | |
| 2108 | GDB supports three kinds of operator in addition to those of programming |
| 2109 | languages: |
| 2110 | |
| 2111 | @table @code |
| 2112 | @item @@ |
| 2113 | @samp{@@} is a binary operator for treating parts of memory as arrays. |
| 2114 | @xref{Arrays}, for more information. |
| 2115 | |
| 2116 | @item :: |
| 2117 | @samp{::} allows you to specify a variable in terms of the file or |
| 2118 | function it is defined in. @xref{Variables}. |
| 2119 | |
| 2120 | @item @{@var{type}@} @var{addr} |
| 2121 | Refers to an object of type @var{type} stored at address @var{addr} in |
| 2122 | memory. @var{addr} may be any expression whose value is an integer or |
| 2123 | pointer (but parentheses are required around nonunary operators, just as in |
| 2124 | a cast). This construct is allowed regardless of what kind of data is |
| 2125 | officially supposed to reside at @var{addr}.@refill |
| 2126 | @end table |
| 2127 | |
| 2128 | @node Variables, Arrays, Expressions, Data |
| 2129 | @section Program Variables |
| 2130 | |
| 2131 | The most common kind of expression to use is the name of a variable |
| 2132 | in your program. |
| 2133 | |
| 2134 | Variables in expressions are understood in the selected stack frame |
| 2135 | (@pxref{Selection}); they must either be global (or static) or be visible |
| 2136 | according to the scope rules of the programming language from the point of |
| 2137 | execution in that frame. This means that in the function |
| 2138 | |
| 2139 | @example |
| 2140 | foo (a) |
| 2141 | int a; |
| 2142 | @{ |
| 2143 | bar (a); |
| 2144 | @{ |
| 2145 | int b = test (); |
| 2146 | bar (b); |
| 2147 | @} |
| 2148 | @} |
| 2149 | @end example |
| 2150 | |
| 2151 | @noindent |
| 2152 | the variable @code{a} is usable whenever the program is executing |
| 2153 | within the function @code{foo}, but the variable @code{b} is visible |
| 2154 | only while the program is executing inside the block in which @code{b} |
| 2155 | is declared. |
| 2156 | |
| 2157 | As a special exception, you can refer to a variable or function whose |
| 2158 | scope is a single source file even if the current execution point is not |
| 2159 | in this file. But it is possible to have more than one such variable |
| 2160 | or function with the same name (if they are in different source files). |
| 2161 | In such a case, it is not defined which one you will get. If you wish, |
| 2162 | you can specify any one of them using the colon-colon construct: |
| 2163 | |
| 2164 | @example |
| 2165 | @var{block}::@var{variable} |
| 2166 | @end example |
| 2167 | |
| 2168 | @noindent |
| 2169 | Here @var{block} is the name of the source file whose variable you want. |
| 2170 | |
| 2171 | @node Arrays, Format options, Variables, Data |
| 2172 | @section Artificial Arrays |
| 2173 | |
| 2174 | @cindex artificial array |
| 2175 | It is often useful to print out several successive objects of the |
| 2176 | same type in memory; a section of an array, or an array of |
| 2177 | dynamically determined size for which only a pointer exists in the |
| 2178 | program. |
| 2179 | |
| 2180 | This can be done by constructing an @dfn{artificial array} with the |
| 2181 | binary operator @samp{@@}. The left operand of @samp{@@} should be |
| 2182 | the first element of the desired array, as an individual object. |
| 2183 | The right operand should be the length of the array. The result is |
| 2184 | an array value whose elements are all of the type of the left argument. |
| 2185 | The first element is actually the left argument; the second element |
| 2186 | comes from bytes of memory immediately following those that hold the |
| 2187 | first element, and so on. Here is an example. If a program says |
| 2188 | |
| 2189 | @example |
| 2190 | int *array = (int *) malloc (len * sizeof (int)); |
| 2191 | @end example |
| 2192 | |
| 2193 | @noindent |
| 2194 | you can print the contents of @code{array} with |
| 2195 | |
| 2196 | @example |
| 2197 | p *array@@len |
| 2198 | @end example |
| 2199 | |
| 2200 | The left operand of @samp{@@} must reside in memory. Array values made |
| 2201 | with @samp{@@} in this way behave just like other arrays in terms of |
| 2202 | subscripting, and are coerced to pointers when used in expressions. |
| 2203 | (It would probably appear in an expression via the value history, |
| 2204 | after you had printed it out.) |
| 2205 | |
| 2206 | @node Format options, Output formats, Arrays, Data |
| 2207 | @section Format options |
| 2208 | |
| 2209 | @cindex format options |
| 2210 | GDB provides a few ways to control how arrays and structures are |
| 2211 | printed. |
| 2212 | |
| 2213 | @table @code |
| 2214 | @item info format |
| 2215 | @kindex info format |
| 2216 | Display the current settings for the format options. |
| 2217 | |
| 2218 | @item set array-max @var{number-of-elements} |
| 2219 | @kindex set array-max |
| 2220 | If GDB is printing a large array, it will stop printing after it has |
| 2221 | printed the number of elements set by the @samp{set array-max} command. |
| 2222 | This limit also applies to the display of strings. |
| 2223 | |
| 2224 | @item set prettyprint on |
| 2225 | @kindex set prettyprint |
| 2226 | Cause GDB to print structures in an indented format with one member per |
| 2227 | line, like this: |
| 2228 | |
| 2229 | @example |
| 2230 | $1 = @{ |
| 2231 | next = 0x0, |
| 2232 | flags = @{ |
| 2233 | sweet = 1, |
| 2234 | sour = 1 |
| 2235 | @}, |
| 2236 | meat = 0x54 "Pork" |
| 2237 | @} |
| 2238 | @end example |
| 2239 | |
| 2240 | @item set prettyprint off |
| 2241 | Cause GDB to print structures in a compact format, like this: |
| 2242 | |
| 2243 | @example |
| 2244 | $1 = @{next = 0x0, flags = @{sweet = 1, sour = 1@}, meat = 0x54 "Pork"@} |
| 2245 | @end example |
| 2246 | |
| 2247 | This is the default format. |
| 2248 | |
| 2249 | @item set unionprint on |
| 2250 | @kindex set unionprint |
| 2251 | Tell GDB to print unions which are contained in structures. This is the |
| 2252 | default setting. |
| 2253 | @item set unionprint off |
| 2254 | Tell GDB not to print unions which are contained in structures. |
| 2255 | |
| 2256 | For example, given the declarations |
| 2257 | |
| 2258 | @example |
| 2259 | typedef enum @{Tree, Bug@} Species; |
| 2260 | typedef enum @{Big_tree, Acorn, Seedling@} Tree_forms; |
| 2261 | typedef enum @{Caterpiller, Cocoon, Butterfly@} Bug_forms; |
| 2262 | |
| 2263 | struct thing @{ |
| 2264 | Species it; |
| 2265 | union @{ |
| 2266 | Tree_forms tree; |
| 2267 | Bug_forms bug; |
| 2268 | @} form; |
| 2269 | @}; |
| 2270 | |
| 2271 | struct thing foo = @{Tree, @{Acorn@}@}; |
| 2272 | @end example |
| 2273 | |
| 2274 | @noindent |
| 2275 | with @samp{set unionprint on} in effect @samp{p foo} would print |
| 2276 | |
| 2277 | @example |
| 2278 | $1 = @{it = Tree, form = @{tree = Acorn, bug = Cocoon@}@} |
| 2279 | @end example |
| 2280 | |
| 2281 | @noindent |
| 2282 | and with @samp{set unionprint off} in effect it would print |
| 2283 | |
| 2284 | @example |
| 2285 | $1 = @{it = Tree, form = @{...@}@} |
| 2286 | @end example |
| 2287 | @end table |
| 2288 | |
| 2289 | @node Output formats, Memory, Format options, Data |
| 2290 | @section Output formats |
| 2291 | |
| 2292 | @cindex formatted output |
| 2293 | @cindex output formats |
| 2294 | GDB normally prints all values according to their data types. Sometimes |
| 2295 | this is not what you want. For example, you might want to print a number |
| 2296 | in hex, or a pointer in decimal. Or you might want to view data in memory |
| 2297 | at a certain address as a character string or an instruction. These things |
| 2298 | can be done with @dfn{output formats}. |
| 2299 | |
| 2300 | The simplest use of output formats is to say how to print a value |
| 2301 | already computed. This is done by starting the arguments of the |
| 2302 | @samp{print} command with a slash and a format letter. The format |
| 2303 | letters supported are: |
| 2304 | |
| 2305 | @table @samp |
| 2306 | @item x |
| 2307 | Regard the bits of the value as an integer, and print the integer in |
| 2308 | hexadecimal. |
| 2309 | |
| 2310 | @item d |
| 2311 | Print as integer in signed decimal. |
| 2312 | |
| 2313 | @item u |
| 2314 | Print as integer in unsigned decimal. |
| 2315 | |
| 2316 | @item o |
| 2317 | Print as integer in octal. |
| 2318 | |
| 2319 | @item a |
| 2320 | Print as an address, both absolute in hex and then relative |
| 2321 | to a symbol defined as an address below it. |
| 2322 | |
| 2323 | @item c |
| 2324 | Regard as an integer and print it as a character constant. |
| 2325 | |
| 2326 | @item f |
| 2327 | Regard the bits of the value as a floating point number and print |
| 2328 | using typical floating point syntax. |
| 2329 | @end table |
| 2330 | |
| 2331 | For example, to print the program counter in hex (@pxref{Registers}), type |
| 2332 | |
| 2333 | @example |
| 2334 | p/x $pc |
| 2335 | @end example |
| 2336 | |
| 2337 | @noindent |
| 2338 | Note that no space is required before the slash; this is because command |
| 2339 | names in GDB cannot contain a slash. |
| 2340 | |
| 2341 | To reprint the last value in the value history with a different format, |
| 2342 | you can use the @samp{print} command with just a format and no |
| 2343 | expression. For example, @samp{p/x} reprints the last value in hex. |
| 2344 | |
| 2345 | @node Memory, Auto Display, Output formats, Data |
| 2346 | @subsection Examining Memory |
| 2347 | |
| 2348 | @cindex examining memory |
| 2349 | @kindex x |
| 2350 | The command @samp{x} (for `examine') can be used to examine memory |
| 2351 | without reference to the program's data types. The format in which you |
| 2352 | wish to examine memory is instead explicitly specified. The allowable |
| 2353 | formats are a superset of the formats described in the previous section. |
| 2354 | |
| 2355 | @samp{x} is followed by a slash and an output format specification, |
| 2356 | followed by an expression for an address. The expression need not have |
| 2357 | a pointer value (though it may); it is used as an integer, as the |
| 2358 | address of a byte of memory. @xref{Expressions} for more information on |
| 2359 | expressions. For example, @samp{x/4xw $sp} prints the four words of |
| 2360 | memory above the stack pointer in hexadecimal. |
| 2361 | |
| 2362 | The output format in this case specifies both how big a unit of memory |
| 2363 | to examine and how to print the contents of that unit. It is done |
| 2364 | with one or two of the following letters: |
| 2365 | |
| 2366 | These letters specify just the size of unit to examine: |
| 2367 | |
| 2368 | @table @samp |
| 2369 | @item b |
| 2370 | Examine individual bytes. |
| 2371 | |
| 2372 | @item h |
| 2373 | Examine halfwords (two bytes each). |
| 2374 | |
| 2375 | @item w |
| 2376 | Examine words (four bytes each). |
| 2377 | |
| 2378 | @cindex word |
| 2379 | Many assemblers and cpu designers still use `word' for a 16-bit quantity, |
| 2380 | as a holdover from specific predecessor machines of the 1970's that really |
| 2381 | did use two-byte words. But more generally the term `word' has always |
| 2382 | referred to the size of quantity that a machine normally operates on and |
| 2383 | stores in its registers. This is 32 bits for all the machines that GDB |
| 2384 | runs on. |
| 2385 | |
| 2386 | @item g |
| 2387 | Examine giant words (8 bytes). |
| 2388 | @end table |
| 2389 | |
| 2390 | These letters specify just the way to print the contents: |
| 2391 | |
| 2392 | @table @samp |
| 2393 | @item x |
| 2394 | Print as integers in unsigned hexadecimal. |
| 2395 | |
| 2396 | @item d |
| 2397 | Print as integers in signed decimal. |
| 2398 | |
| 2399 | @item u |
| 2400 | Print as integers in unsigned decimal. |
| 2401 | |
| 2402 | @item o |
| 2403 | Print as integers in unsigned octal. |
| 2404 | |
| 2405 | @item a |
| 2406 | Print as an address, both absolute in hex and then relative |
| 2407 | to a symbol defined as an address below it. |
| 2408 | |
| 2409 | @item c |
| 2410 | Print as character constants. |
| 2411 | |
| 2412 | @item f |
| 2413 | Print as floating point. This works only with sizes @samp{w} and |
| 2414 | @samp{g}. |
| 2415 | |
| 2416 | @item s |
| 2417 | Print a null-terminated string of characters. The specified unit size |
| 2418 | is ignored; instead, the unit is however many bytes it takes to reach |
| 2419 | a null character (including the null character). |
| 2420 | |
| 2421 | @item i |
| 2422 | Print a machine instruction in assembler syntax (or nearly). The |
| 2423 | specified unit size is ignored; the number of bytes in an instruction |
| 2424 | varies depending on the type of machine, the opcode and the addressing |
| 2425 | modes used. |
| 2426 | @end table |
| 2427 | |
| 2428 | If either the manner of printing or the size of unit fails to be specified, |
| 2429 | the default is to use the same one that was used last. If you don't want |
| 2430 | to use any letters after the slash, you can omit the slash as well. |
| 2431 | |
| 2432 | You can also omit the address to examine. Then the address used is |
| 2433 | just after the last unit examined. This is why string and instruction |
| 2434 | formats actually compute a unit-size based on the data: so that the |
| 2435 | next string or instruction examined will start in the right place. |
| 2436 | The @samp{print} command sometimes sets the default address for |
| 2437 | the @samp{x} command; when the value printed resides in memory, the |
| 2438 | default is set to examine the same location. @samp{info line} also |
| 2439 | sets the default for @samp{x}, to the address of the start of the |
| 2440 | machine code for the specified line and @samp{info breakpoints} sets |
| 2441 | it to the address of the last breakpoint listed. |
| 2442 | |
| 2443 | When you use @key{RET} to repeat an @samp{x} command, it does not repeat |
| 2444 | exactly the same: the address specified previously (if any) is ignored, so |
| 2445 | that the repeated command examines the successive locations in memory |
| 2446 | rather than the same ones. |
| 2447 | |
| 2448 | You can examine several consecutive units of memory with one command by |
| 2449 | writing a repeat-count after the slash (before the format letters, if any). |
| 2450 | The repeat count must be a decimal integer. It has the same effect as |
| 2451 | repeating the @samp{x} command that many times except that the output may |
| 2452 | be more compact with several units per line. For example, |
| 2453 | |
| 2454 | @example |
| 2455 | x/10i $pc |
| 2456 | @end example |
| 2457 | |
| 2458 | @noindent |
| 2459 | prints ten instructions starting with the one to be executed next in the |
| 2460 | selected frame. After doing this, you could print another ten following |
| 2461 | instructions with |
| 2462 | |
| 2463 | @example |
| 2464 | x/10 |
| 2465 | @end example |
| 2466 | |
| 2467 | @noindent |
| 2468 | in which the format and address are allowed to default. |
| 2469 | |
| 2470 | @kindex $_ |
| 2471 | @kindex $__ |
| 2472 | The addresses and contents printed by the @samp{x} command are not put in |
| 2473 | the value history because there is often too much of them and they would |
| 2474 | get in the way. Instead, GDB makes these values available for subsequent |
| 2475 | use in expressions as values of the convenience variables @code{$_} and |
| 2476 | @code{$__}. |
| 2477 | |
| 2478 | After an @samp{x} command, the last address examined is available for use |
| 2479 | in expressions in the convenience variable @code{$_}. The contents of that |
| 2480 | address, as examined, are available in the convenience variable @code{$__}. |
| 2481 | |
| 2482 | If the @samp{x} command has a repeat count, the address and contents saved |
| 2483 | are from the last memory unit printed; this is not the same as the last |
| 2484 | address printed if several units were printed on the last line of output. |
| 2485 | |
| 2486 | @kindex disassemble |
| 2487 | The specialized command @samp{disassemble} is also provided to dump a |
| 2488 | range of memory as machine instructions. The default memory range is |
| 2489 | the function surrounding the program counter of the selected frame. A |
| 2490 | single argument to this command is a program counter value; the function |
| 2491 | surrounding this value will be dumped. Two arguments specify a range of |
| 2492 | addresss (first inclusive, second exclusive) to be dumped. |
| 2493 | |
| 2494 | @node Auto Display, Value History, Memory, Data |
| 2495 | @section Automatic Display |
| 2496 | @cindex automatic display |
| 2497 | @cindex display of expressions |
| 2498 | |
| 2499 | If you find that you want to print the value of an expression frequently |
| 2500 | (to see how it changes), you might want to add it to the @dfn{automatic |
| 2501 | display list} so that GDB will print its value each time the program stops. |
| 2502 | Each expression added to the list is given a number to identify it; |
| 2503 | to remove an expression from the list, you specify that number. |
| 2504 | The automatic display looks like this: |
| 2505 | |
| 2506 | @example |
| 2507 | 2: foo = 38 |
| 2508 | 3: bar[5] = (struct hack *) 0x3804 |
| 2509 | @end example |
| 2510 | |
| 2511 | @noindent |
| 2512 | showing item numbers, expressions and their current values. |
| 2513 | |
| 2514 | If the expression refers to local variables, then it does not make sense |
| 2515 | outside the lexical context for which it was set up. Such an expression |
| 2516 | is printed only when execution is inside that lexical context. For |
| 2517 | example, if you give the command @samp{display name} while inside a |
| 2518 | function with an argument @code{name}, then this argument will be |
| 2519 | displayed whenever the program stops inside that function, but not when |
| 2520 | it stops elsewhere (since this argument doesn't exist elsewhere). |
| 2521 | |
| 2522 | @table @code |
| 2523 | @item display @var{exp} |
| 2524 | @kindex display |
| 2525 | Add the expression @var{exp} to the list of expressions to display |
| 2526 | each time the program stops. @xref{Expressions}. |
| 2527 | |
| 2528 | @item display/@var{fmt} @var{exp} |
| 2529 | For @var{fmt} specifying only a display format and not a size or |
| 2530 | count, add the expression @var{exp} to the auto-display list but |
| 2531 | arranges to display it each time in the specified format @var{fmt}. |
| 2532 | |
| 2533 | @item display/@var{fmt} @var{addr} |
| 2534 | For @var{fmt} @samp{i} or @samp{s}, or including a unit-size or a |
| 2535 | number of units, add the expression @var{addr} as a memory address to |
| 2536 | be examined each time the program stops. Examining means in effect |
| 2537 | doing @samp{x/@var{fmt} @var{addr}}. @xref{Memory}. |
| 2538 | |
| 2539 | @item undisplay @var{dnums}@dots{} |
| 2540 | @itemx delete display @var{dnums}@dots{} |
| 2541 | @kindex delete display |
| 2542 | @kindex undisplay |
| 2543 | Remove item numbers @var{dnums} from the list of expressions to display. |
| 2544 | |
| 2545 | @item disable display @var{dnums}@dots{} |
| 2546 | @kindex disable display |
| 2547 | Disable the display of item numbers @var{dnums}. A disabled display |
| 2548 | item is not printed automatically, but is not forgotten. It may be |
| 2549 | reenabled later. |
| 2550 | |
| 2551 | @item enable display @var{dnums}@dots{} |
| 2552 | @kindex enable display |
| 2553 | Enable display of item numbers @var{dnums}. It becomes effective once |
| 2554 | again in auto display of its expression, until you specify otherwise. |
| 2555 | |
| 2556 | @item display |
| 2557 | Display the current values of the expressions on the list, just as is |
| 2558 | done when the program stops. |
| 2559 | |
| 2560 | @item info display |
| 2561 | @kindex info display |
| 2562 | Print the list of expressions previously set up to display |
| 2563 | automatically, each one with its item number, but without showing the |
| 2564 | values. This includes disabled expressions, which are marked as such. |
| 2565 | It also includes expressions which would not be displayed right now |
| 2566 | because they refer to automatic variables not currently available. |
| 2567 | @end table |
| 2568 | |
| 2569 | @node Value History, Convenience Vars, Auto Display, Data |
| 2570 | @section Value History |
| 2571 | |
| 2572 | @cindex value history |
| 2573 | Every value printed by the @samp{print} command is saved for the entire |
| 2574 | session in GDB's @dfn{value history} so that you can refer to it in |
| 2575 | other expressions. |
| 2576 | |
| 2577 | @cindex @code{$} |
| 2578 | @cindex @code{$$} |
| 2579 | @cindex history number |
| 2580 | The values printed are given @dfn{history numbers} for you to refer to them |
| 2581 | by. These are successive integers starting with 1. @samp{print} shows you |
| 2582 | the history number assigned to a value by printing @samp{$@var{num} = } |
| 2583 | before the value; here @var{num} is the history number. |
| 2584 | |
| 2585 | To refer to any previous value, use @samp{$} followed by the value's |
| 2586 | history number. The output printed by @samp{print} is designed to remind |
| 2587 | you of this. Just @code{$} refers to the most recent value in the history, |
| 2588 | and @code{$$} refers to the value before that. |
| 2589 | |
| 2590 | For example, suppose you have just printed a pointer to a structure and |
| 2591 | want to see the contents of the structure. It suffices to type |
| 2592 | |
| 2593 | @example |
| 2594 | p *$ |
| 2595 | @end example |
| 2596 | |
| 2597 | If you have a chain of structures where the component @samp{next} points |
| 2598 | to the next one, you can print the contents of the next one with this: |
| 2599 | |
| 2600 | @example |
| 2601 | p *$.next |
| 2602 | @end example |
| 2603 | |
| 2604 | @noindent |
| 2605 | It might be useful to repeat this command many times by typing @key{RET}. |
| 2606 | |
| 2607 | Note that the history records values, not expressions. If the value of |
| 2608 | @code{x} is 4 and you type this command: |
| 2609 | |
| 2610 | @example |
| 2611 | print x |
| 2612 | set x=5 |
| 2613 | @end example |
| 2614 | |
| 2615 | @noindent |
| 2616 | then the value recorded in the value history by the @samp{print} command |
| 2617 | remains 4 even though the value of @code{x} has changed. |
| 2618 | |
| 2619 | @table @code |
| 2620 | @item info values |
| 2621 | @kindex info values |
| 2622 | Print the last ten values in the value history, with their item |
| 2623 | numbers. This is like @samp{p $$9} repeated ten times, except that |
| 2624 | @samp{info values} does not change the history. |
| 2625 | |
| 2626 | @item info values @var{n} |
| 2627 | Print ten history values centered on history item number @var{n}. |
| 2628 | |
| 2629 | @item info values + |
| 2630 | Print ten history values just after the values last printed. |
| 2631 | @end table |
| 2632 | |
| 2633 | @node Convenience Vars, Registers, Value History, Data |
| 2634 | @section Convenience Variables |
| 2635 | |
| 2636 | @cindex convenience variables |
| 2637 | GDB provides @dfn{convenience variables} that you can use within GDB to |
| 2638 | hold on to a value and refer to it later. These variables exist entirely |
| 2639 | within GDB; they are not part of your program, and setting a convenience |
| 2640 | variable has no effect on further execution of your program. That's why |
| 2641 | you can use them freely. |
| 2642 | |
| 2643 | Convenience variables have names starting with @samp{$}. Any name starting |
| 2644 | with @samp{$} can be used for a convenience variable, unless it is one of |
| 2645 | the predefined set of register names (@pxref{Registers}). |
| 2646 | |
| 2647 | You can save a value in a convenience variable with an assignment |
| 2648 | expression, just as you would set a variable in your program. Example: |
| 2649 | |
| 2650 | @example |
| 2651 | set $foo = *object_ptr |
| 2652 | @end example |
| 2653 | |
| 2654 | @noindent |
| 2655 | would save in @code{$foo} the value contained in the object pointed to by |
| 2656 | @code{object_ptr}. |
| 2657 | |
| 2658 | Using a convenience variable for the first time creates it; but its value |
| 2659 | is @code{void} until you assign a new value. You can alter the value with |
| 2660 | another assignment at any time. |
| 2661 | |
| 2662 | Convenience variables have no fixed types. You can assign a convenience |
| 2663 | variable any type of value, even if it already has a value of a different |
| 2664 | type. The convenience variable as an expression has whatever type its |
| 2665 | current value has. |
| 2666 | |
| 2667 | @table @code |
| 2668 | @item info convenience |
| 2669 | @kindex info convenience |
| 2670 | Print a list of convenience variables used so far, and their values. |
| 2671 | Abbreviated @samp{i con}. |
| 2672 | @end table |
| 2673 | |
| 2674 | One of the ways to use a convenience variable is as a counter to be |
| 2675 | incremented or a pointer to be advanced. For example: |
| 2676 | |
| 2677 | @example |
| 2678 | set $i = 0 |
| 2679 | print bar[$i++]->contents |
| 2680 | @i{@dots{}repeat that command by typing @key{RET}.} |
| 2681 | @end example |
| 2682 | |
| 2683 | Some convenience variables are created automatically by GDB and given |
| 2684 | values likely to be useful. |
| 2685 | |
| 2686 | @table @code |
| 2687 | @item $_ |
| 2688 | The variable @code{$_} is automatically set by the @samp{x} command to |
| 2689 | the last address examined (@pxref{Memory}). Other commands which |
| 2690 | provide a default address for @samp{x} to examine also set @code{$_} |
| 2691 | to that address; these commands include @samp{info line} and @samp{info |
| 2692 | breakpoint}. |
| 2693 | |
| 2694 | @item $__ |
| 2695 | The variable @code{$__} is automatically set by the @samp{x} command |
| 2696 | to the value found in the last address examined. |
| 2697 | @end table |
| 2698 | |
| 2699 | @node Registers,, Convenience Vars, Data |
| 2700 | @section Registers |
| 2701 | |
| 2702 | @cindex registers |
| 2703 | Machine register contents can be referred to in expressions as variables |
| 2704 | with names starting with @samp{$}. The names of registers are different |
| 2705 | for each machine; use @samp{info registers} to see the names used on your |
| 2706 | machine. The names @code{$pc} and @code{$sp} are used on all machines for |
| 2707 | the program counter register and the stack pointer. Often @code{$fp} is |
| 2708 | used for a register that contains a pointer to the current stack frame, |
| 2709 | and @code{$ps} is used for a register that contains the processor |
| 2710 | status. These standard register names may be available on your machine |
| 2711 | even though the @code{info registers} command displays them with a |
| 2712 | different name. For example, on the SPARC, @code{info registers} |
| 2713 | displays the processor status register as @code{$psr} but you can also |
| 2714 | refer to it as @code{$ps}. |
| 2715 | |
| 2716 | GDB always considers the contents of an ordinary register as an integer |
| 2717 | when the register is examined in this way. Some machines have special |
| 2718 | registers which can hold nothing but floating point; these registers are |
| 2719 | considered floating point. There is no way to refer to the contents of an |
| 2720 | ordinary register as floating point value (although you can @emph{print} |
| 2721 | it as a floating point value with @samp{print/f $@var{regname}}). |
| 2722 | |
| 2723 | Some registers have distinct ``raw'' and ``virtual'' data formats. This |
| 2724 | means that the data format in which the register contents are saved by the |
| 2725 | operating system is not the same one that your program normally sees. For |
| 2726 | example, the registers of the 68881 floating point coprocessor are always |
| 2727 | saved in ``extended'' format, but all C programs expect to work with |
| 2728 | ``double'' format. In such cases, GDB normally works with the virtual |
| 2729 | format only (the format that makes sense for your program), but the |
| 2730 | @samp{info registers} command prints the data in both formats. |
| 2731 | |
| 2732 | Register values are relative to the selected stack frame |
| 2733 | (@pxref{Selection}). This means that you get the value that the register |
| 2734 | would contain if all stack frames farther in were exited and their saved |
| 2735 | registers restored. In order to see the real contents of all registers, |
| 2736 | you must select the innermost frame (with @samp{frame 0}). |
| 2737 | |
| 2738 | Some registers are never saved (typically those numbered zero or one) |
| 2739 | because they are used for returning function values; for these registers, |
| 2740 | relativization makes no difference. |
| 2741 | |
| 2742 | @table @code |
| 2743 | @item info registers |
| 2744 | @kindex info registers |
| 2745 | Print the names and relativized values of all registers. |
| 2746 | |
| 2747 | @item info registers @var{regname} |
| 2748 | Print the relativized value of register @var{regname}. @var{regname} |
| 2749 | may be any register name valid on the machine you are using, with |
| 2750 | or without the initial @samp{$}. |
| 2751 | @end table |
| 2752 | |
| 2753 | @subsection Examples |
| 2754 | |
| 2755 | You could print the program counter in hex with |
| 2756 | |
| 2757 | @example |
| 2758 | p/x $pc |
| 2759 | @end example |
| 2760 | |
| 2761 | @noindent |
| 2762 | or print the instruction to be executed next with |
| 2763 | |
| 2764 | @example |
| 2765 | x/i $pc |
| 2766 | @end example |
| 2767 | |
| 2768 | @noindent |
| 2769 | or add four to the stack pointer with |
| 2770 | |
| 2771 | @example |
| 2772 | set $sp += 4 |
| 2773 | @end example |
| 2774 | |
| 2775 | @noindent |
| 2776 | The last is a way of removing one word from the stack, on machines where |
| 2777 | stacks grow downward in memory (most machines, nowadays). This assumes |
| 2778 | that the innermost stack frame is selected. Setting @code{$sp} is |
| 2779 | not allowed when other stack frames are selected. |
| 2780 | |
| 2781 | @node Symbols, Altering, Data, Top |
| 2782 | @chapter Examining the Symbol Table |
| 2783 | |
| 2784 | The commands described in this section allow you to make inquiries for |
| 2785 | information about the symbols (names of variables, functions and types) |
| 2786 | defined in your program. This information is found by GDB in the symbol |
| 2787 | table loaded by the @samp{symbol-file} command; it is inherent in the text |
| 2788 | of your program and does not change as the program executes. |
| 2789 | |
| 2790 | @table @code |
| 2791 | @item whatis @var{exp} |
| 2792 | @kindex whatis |
| 2793 | Print the data type of expression @var{exp}. @var{exp} is not |
| 2794 | actually evaluated, and any side-effecting operations (such as |
| 2795 | assignments or function calls) inside it do not take place. |
| 2796 | @xref{Expressions}. |
| 2797 | |
| 2798 | @item whatis |
| 2799 | Print the data type of @code{$}, the last value in the value history. |
| 2800 | |
| 2801 | @item info address @var{symbol} |
| 2802 | @kindex info address |
| 2803 | Describe where the data for @var{symbol} is stored. For a register |
| 2804 | variable, this says which register it is kept in. For a non-register |
| 2805 | local variable, this prints the stack-frame offset at which the variable |
| 2806 | is always stored. |
| 2807 | |
| 2808 | Note the contrast with @samp{print &@var{symbol}}, which does not work |
| 2809 | at all for a register variables, and for a stack local variable prints |
| 2810 | the exact address of the current instantiation of the variable. |
| 2811 | |
| 2812 | @item ptype @var{typename} |
| 2813 | @kindex ptype |
| 2814 | Print a description of data type @var{typename}. @var{typename} may be |
| 2815 | the name of a type, or for C code it may have the form |
| 2816 | @samp{struct @var{struct-tag}}, @samp{union @var{union-tag}} or |
| 2817 | @samp{enum @var{enum-tag}}.@refill |
| 2818 | |
| 2819 | @item info sources |
| 2820 | @kindex info sources |
| 2821 | Print the names of all source files in the program for which there |
| 2822 | is debugging information. |
| 2823 | |
| 2824 | @item info functions |
| 2825 | @kindex info functions |
| 2826 | Print the names and data types of all defined functions. |
| 2827 | |
| 2828 | @item info functions @var{regexp} |
| 2829 | Print the names and data types of all defined functions |
| 2830 | whose names contain a match for regular expression @var{regexp}. |
| 2831 | Thus, @samp{info fun step} finds all functions whose names |
| 2832 | include @samp{step}; @samp{info fun ^step} finds those whose names |
| 2833 | start with @samp{step}. |
| 2834 | |
| 2835 | @item info variables |
| 2836 | @kindex info variables |
| 2837 | Print the names and data types of all variables that are declared |
| 2838 | outside of functions (i.e., except for local variables). |
| 2839 | |
| 2840 | @item info variables @var{regexp} |
| 2841 | Print the names and data types of all variables (except for local |
| 2842 | variables) whose names contain a match for regular expression |
| 2843 | @var{regexp}. |
| 2844 | |
| 2845 | @item info types |
| 2846 | @kindex info types |
| 2847 | Print all data types that are defined in the program. |
| 2848 | |
| 2849 | @item info types @var{regexp} |
| 2850 | Print all data types that are defined in the program whose names |
| 2851 | contain a match for regular expression @var{regexp}. |
| 2852 | |
| 2853 | @ignore |
| 2854 | This was never implemented. |
| 2855 | @item info methods |
| 2856 | @itemx info methods @var{regexp} |
| 2857 | @kindex info methods |
| 2858 | The @samp{info-methods} command permits the user to examine all defined |
| 2859 | methods within C++ program, or (with the @var{regexp} argument) a |
| 2860 | specific set of methods found in the various C++ classes. Many |
| 2861 | C++ classes provide a large number of methods. Thus, the output |
| 2862 | from the @samp{ptype} command can be overwhelming and hard to use. The |
| 2863 | @samp{info-methods} command filters the methods, printing only those |
| 2864 | which match the regular-expression @var{regexp}. |
| 2865 | @end ignore |
| 2866 | |
| 2867 | @item printsyms @var{filename} |
| 2868 | @kindex printsyms |
| 2869 | Write a complete dump of the debugger's symbol data into the |
| 2870 | file @var{filename}. |
| 2871 | @end table |
| 2872 | |
| 2873 | @node Altering, Sequences, Symbols, Top |
| 2874 | @chapter Altering Execution |
| 2875 | |
| 2876 | Once you think you have find an error in the program, you might want to |
| 2877 | find out for certain whether correcting the apparent error would lead to |
| 2878 | correct results in the rest of the run. You can find the answer by |
| 2879 | experiment, using the GDB features for altering execution of the |
| 2880 | program. |
| 2881 | |
| 2882 | For example, you can store new values into variables or memory |
| 2883 | locations, give the program a signal, restart it at a different address, |
| 2884 | or even return prematurely from a function to its caller. |
| 2885 | |
| 2886 | @menu |
| 2887 | * Assignment:: Altering variable values or memory contents. |
| 2888 | * Jumping:: Altering control flow. |
| 2889 | * Signaling:: Making signals happen in the program. |
| 2890 | * Returning:: Making a function return prematurely. |
| 2891 | @end menu |
| 2892 | |
| 2893 | @node Assignment, Jumping, Altering, Altering |
| 2894 | @section Assignment to Variables |
| 2895 | |
| 2896 | @cindex assignment |
| 2897 | @cindex setting variables |
| 2898 | To alter the value of a variable, evaluate an assignment expression. |
| 2899 | @xref{Expressions}. For example, |
| 2900 | |
| 2901 | @example |
| 2902 | print x=4 |
| 2903 | @end example |
| 2904 | |
| 2905 | @noindent |
| 2906 | would store the value 4 into the variable @code{x}, and then print |
| 2907 | the value of the assignment expression (which is 4). |
| 2908 | |
| 2909 | All the assignment operators of C are supported, including the |
| 2910 | incrementation operators @samp{++} and @samp{--}, and combining |
| 2911 | assignments such as @samp{+=} and @samp{<<=}. |
| 2912 | |
| 2913 | @kindex set |
| 2914 | @kindex set variable |
| 2915 | If you are not interested in seeing the value of the assignment, use the |
| 2916 | @samp{set} command instead of the @samp{print} command. @samp{set} is |
| 2917 | really the same as @samp{print} except that the expression's value is not |
| 2918 | printed and is not put in the value history (@pxref{Value History}). The |
| 2919 | expression is evaluated only for side effects. |
| 2920 | |
| 2921 | Note that if the beginning of the argument string of the @samp{set} command |
| 2922 | appears identical to a @samp{set} subcommand, it may be necessary to use |
| 2923 | the @samp{set variable} command. This command is identical to @samp{set} |
| 2924 | except for its lack of subcommands. |
| 2925 | |
| 2926 | GDB allows more implicit conversions in assignments than C does; you can |
| 2927 | freely store an integer value into a pointer variable or vice versa, and |
| 2928 | any structure can be converted to any other structure that is the same |
| 2929 | length or shorter. |
| 2930 | |
| 2931 | To store values into arbitrary places in memory, use the @samp{@{@dots{}@}} |
| 2932 | construct to generate a value of specified type at a specified address |
| 2933 | (@pxref{Expressions}). For example, @code{@{int@}0x83040} would refer |
| 2934 | to memory location 0x83040 as an integer (which implies a certain size |
| 2935 | and representation in memory), and |
| 2936 | |
| 2937 | @example |
| 2938 | set @{int@}0x83040 = 4 |
| 2939 | @end example |
| 2940 | |
| 2941 | would store the value 4 into that memory location. |
| 2942 | |
| 2943 | @node Jumping, Signaling, Assignment, Altering |
| 2944 | @section Continuing at a Different Address |
| 2945 | |
| 2946 | Ordinarily, when you continue the program, you do so at the place where |
| 2947 | it stopped, with the @samp{cont} command. You can instead continue at |
| 2948 | an address of your own choosing, with the following commands: |
| 2949 | |
| 2950 | @table @code |
| 2951 | @item jump @var{linenum} |
| 2952 | @kindex jump |
| 2953 | Resume execution at line number @var{linenum}. Execution may stop |
| 2954 | immediately if there is a breakpoint there. |
| 2955 | |
| 2956 | The @samp{jump} command does not change the current stack frame, or |
| 2957 | the stack pointer, or the contents of any memory location or any |
| 2958 | register other than the program counter. If line @var{linenum} is in |
| 2959 | a different function from the one currently executing, the results may |
| 2960 | be bizarre if the two functions expect different patterns of arguments or |
| 2961 | of local variables. For this reason, the @samp{jump} command requests |
| 2962 | confirmation if the specified line is not in the function currently |
| 2963 | executing. However, even bizarre results are predictable based on |
| 2964 | careful study of the machine-language code of the program. |
| 2965 | |
| 2966 | @item jump *@var{address} |
| 2967 | Resume execution at the instruction at address @var{address}. |
| 2968 | @end table |
| 2969 | |
| 2970 | You can get much the same effect as the @code{jump} command by storing a |
| 2971 | new value into the register @code{$pc}. The difference is that this |
| 2972 | does not start the program running; it only changes the address where it |
| 2973 | @emph{will} run when it is continued. For example, |
| 2974 | |
| 2975 | @example |
| 2976 | set $pc = 0x485 |
| 2977 | @end example |
| 2978 | |
| 2979 | @noindent |
| 2980 | causes the next @samp{cont} command or stepping command to execute at |
| 2981 | address 0x485, rather than at the address where the program stopped. |
| 2982 | @xref{Stepping}. |
| 2983 | |
| 2984 | The most common occasion to use the @samp{jump} command is when you have |
| 2985 | stepped across a function call with @code{next}, and found that the |
| 2986 | return value is incorrect. If all the relevant data appeared correct |
| 2987 | before the function call, the error is probably in the function that |
| 2988 | just returned. |
| 2989 | |
| 2990 | In general, your next step would now be to rerun the program and execute |
| 2991 | up to this function call, and then step into it to see where it goes |
| 2992 | astray. But this may be time consuming. If the function did not have |
| 2993 | significant side effects, you could get the same information by resuming |
| 2994 | execution just before the function call and stepping through it. To do this, |
| 2995 | first put a breakpoint on that function; then, use the @samp{jump} command |
| 2996 | to continue on the line with the function call. |
| 2997 | |
| 2998 | @node Signaling, Returning, Jumping, Altering |
| 2999 | @section Giving the Program a Signal |
| 3000 | |
| 3001 | @table @code |
| 3002 | @item signal @var{signalnum} |
| 3003 | @kindex signal |
| 3004 | Resume execution where the program stopped, but give it immediately the |
| 3005 | signal number @var{signalnum}. |
| 3006 | |
| 3007 | Alternatively, if @var{signalnum} is zero, continue execution without |
| 3008 | giving a signal. This is useful when the program stopped on account of |
| 3009 | a signal and would ordinary see the signal when resumed with the |
| 3010 | @samp{cont} command; @samp{signal 0} causes it to resume without a |
| 3011 | signal. |
| 3012 | @end table |
| 3013 | |
| 3014 | @node Returning,, Signaling, Altering |
| 3015 | @section Returning from a Function |
| 3016 | |
| 3017 | @cindex returning from a function |
| 3018 | @kindex return |
| 3019 | You can cancel execution of a function call with the @samp{return} |
| 3020 | command. This command has the effect of discarding the selected stack |
| 3021 | frame (and all frames within it), so that control moves to the caller of |
| 3022 | that function. You can think of this as making the discarded frame |
| 3023 | return prematurely. |
| 3024 | |
| 3025 | First select the stack frame that you wish to return from |
| 3026 | (@pxref{Selection}). Then type the @samp{return} command. If you wish |
| 3027 | to specify the value to be returned, give that as an argument. |
| 3028 | |
| 3029 | This pops the selected stack frame (and any other frames inside of it), |
| 3030 | leaving its caller as the innermost remaining frame. That frame becomes |
| 3031 | selected. The specified value is stored in the registers used for |
| 3032 | returning values of functions. |
| 3033 | |
| 3034 | The @samp{return} command does not resume execution; it leaves the |
| 3035 | program stopped in the state that would exist if the function had just |
| 3036 | returned. Contrast this with the @samp{finish} command |
| 3037 | (@pxref{Stepping}), which resumes execution until the selected stack |
| 3038 | frame returns @emph{naturally}. |
| 3039 | |
| 3040 | @node Sequences, Options, Altering, Top |
| 3041 | @chapter Canned Sequences of Commands |
| 3042 | |
| 3043 | GDB provides two ways to store sequences of commands for execution as a |
| 3044 | unit: user-defined commands and command files. |
| 3045 | |
| 3046 | @menu |
| 3047 | * Define:: User-defined commands. |
| 3048 | * Command Files:: Command files. |
| 3049 | * Output:: Controlled output commands useful in |
| 3050 | user-defined commands and command files. |
| 3051 | @end menu |
| 3052 | |
| 3053 | @node Define, Command Files, Sequences, Sequences |
| 3054 | @section User-Defined Commands |
| 3055 | |
| 3056 | @cindex user-defined command |
| 3057 | A @dfn{user-defined command} is a sequence of GDB commands to which you |
| 3058 | assign a new name as a command. This is done with the @samp{define} |
| 3059 | command. |
| 3060 | |
| 3061 | @table @code |
| 3062 | @item define @var{commandname} |
| 3063 | @kindex define |
| 3064 | Define a command named @var{commandname}. If there is already a command |
| 3065 | by that name, you are asked to confirm that you want to redefine it. |
| 3066 | |
| 3067 | The definition of the command is made up of other GDB command lines, |
| 3068 | which are given following the @samp{define} command. The end of these |
| 3069 | commands is marked by a line containing @samp{end}. |
| 3070 | |
| 3071 | @item document @var{commandname} |
| 3072 | @kindex document |
| 3073 | Give documentation to the user-defined command @var{commandname}. The |
| 3074 | command @var{commandname} must already be defined. This command reads |
| 3075 | lines of documentation just as @samp{define} reads the lines of the |
| 3076 | command definition, ending with @samp{end}. After the @samp{document} |
| 3077 | command is finished, @samp{help} on command @var{commandname} will print |
| 3078 | the documentation you have specified. |
| 3079 | |
| 3080 | You may use the @samp{document} command again to change the |
| 3081 | documentation of a command. Redefining the command with @samp{define} |
| 3082 | does not change the documentation. |
| 3083 | @end table |
| 3084 | |
| 3085 | User-defined commands do not take arguments. When they are executed, the |
| 3086 | commands of the definition are not printed. An error in any command |
| 3087 | stops execution of the user-defined command. |
| 3088 | |
| 3089 | Commands that would ask for confirmation if used interactively proceed |
| 3090 | without asking when used inside a user-defined command. Many GDB commands |
| 3091 | that normally print messages to say what they are doing omit the messages |
| 3092 | when used in user-defined command. |
| 3093 | |
| 3094 | @node Command Files, Output, Define, Sequences |
| 3095 | @section Command Files |
| 3096 | |
| 3097 | @cindex command files |
| 3098 | A command file for GDB is a file of lines that are GDB commands. Comments |
| 3099 | (lines starting with @samp{#}) may also be included. An empty line in a |
| 3100 | command file does nothing; it does not mean to repeat the last command, as |
| 3101 | it would from the terminal. |
| 3102 | |
| 3103 | @cindex init file |
| 3104 | @cindex @file{.gdbinit} |
| 3105 | When GDB starts, it automatically executes its @dfn{init files}, command |
| 3106 | files named @file{.gdbinit}. GDB reads the init file (if any) in your home |
| 3107 | directory and then the init file (if any) in the current working |
| 3108 | directory. (The init files are not executed if the @samp{-nx} option |
| 3109 | is given.) You can also request the execution of a command file with the |
| 3110 | @samp{source} command: |
| 3111 | |
| 3112 | @table @code |
| 3113 | @item source @var{filename} |
| 3114 | @kindex source |
| 3115 | Execute the command file @var{filename}. |
| 3116 | @end table |
| 3117 | |
| 3118 | The lines in a command file are executed sequentially. They are not |
| 3119 | printed as they are executed. An error in any command terminates execution |
| 3120 | of the command file. |
| 3121 | |
| 3122 | Commands that would ask for confirmation if used interactively proceed |
| 3123 | without asking when used in a command file. Many GDB commands that |
| 3124 | normally print messages to say what they are doing omit the messages |
| 3125 | when used in a command file. |
| 3126 | |
| 3127 | @node Output,, Command Files, Sequences |
| 3128 | @section Commands for Controlled Output |
| 3129 | |
| 3130 | During the execution of a command file or a user-defined command, the only |
| 3131 | output that appears is what is explicitly printed by the commands of the |
| 3132 | definition. This section describes three commands useful for generating |
| 3133 | exactly the output you want. |
| 3134 | |
| 3135 | @table @code |
| 3136 | @item echo @var{text} |
| 3137 | @kindex echo |
| 3138 | @comment I don't consider backslash-space a standard C escape sequence |
| 3139 | @comment because it's not in ANSI. |
| 3140 | Print @var{text}. Nonprinting characters can be included in @var{text} |
| 3141 | using C escape sequences, such as @samp{\n} to print a newline. @b{No |
| 3142 | newline will be printed unless you specify one.} In addition to the |
| 3143 | standard C escape sequences a backslash followed by a space stands for a |
| 3144 | space. This is useful for outputting a string with spaces at the |
| 3145 | beginning or the end, since leading and trailing spaces are trimmed from |
| 3146 | all arguments. Thus, to print @w{`` and foo = ''}, use the command |
| 3147 | @w{``echo \ and foo = \ ''}. |
| 3148 | @comment AAARGGG! How am I supposed to do @samp{ and foo = } and not |
| 3149 | @comment have the spaces be invisible in TeX? |
| 3150 | |
| 3151 | A backslash at the end of @var{text} can be used, as in C, to continue |
| 3152 | the command onto subsequent lines. For example, |
| 3153 | |
| 3154 | @example |
| 3155 | echo This is some text\n\ |
| 3156 | which is continued\n\ |
| 3157 | onto several lines.\n |
| 3158 | @end example |
| 3159 | |
| 3160 | produces the same output as |
| 3161 | |
| 3162 | @example |
| 3163 | echo This is some text\n |
| 3164 | echo which is continued\n |
| 3165 | echo onto several lines.\n |
| 3166 | @end example |
| 3167 | |
| 3168 | @item output @var{expression} |
| 3169 | @kindex output |
| 3170 | Print the value of @var{expression} and nothing but that value: no |
| 3171 | newlines, no @samp{$@var{nn} = }. The value is not entered in the |
| 3172 | value history either. @xref{Expressions} for more information on |
| 3173 | expressions. |
| 3174 | |
| 3175 | @item output/@var{fmt} @var{expression} |
| 3176 | Print the value of @var{expression} in format @var{fmt}. |
| 3177 | @xref{Output formats}, for more information. |
| 3178 | |
| 3179 | @item printf @var{string}, @var{expressions}@dots{} |
| 3180 | @kindex printf |
| 3181 | Print the values of the @var{expressions} under the control of |
| 3182 | @var{string}. The @var{expressions} are separated by commas and may |
| 3183 | be either numbers or pointers. Their values are printed as specified |
| 3184 | by @var{string}, exactly as if the program were to execute |
| 3185 | |
| 3186 | @example |
| 3187 | printf (@var{string}, @var{expressions}@dots{}); |
| 3188 | @end example |
| 3189 | |
| 3190 | For example, you can print two values in hex like this: |
| 3191 | |
| 3192 | @example |
| 3193 | printf "foo, bar-foo = 0x%x, 0x%x\n", foo, bar-foo |
| 3194 | @end example |
| 3195 | |
| 3196 | The only backslash-escape sequences that you can use in the string are |
| 3197 | the simple ones that consist of backslash followed by a letter. |
| 3198 | @end table |
| 3199 | |
| 3200 | @node Options, Emacs, Sequences, Top |
| 3201 | @chapter Options and Arguments for GDB |
| 3202 | |
| 3203 | When you invoke GDB, you can specify arguments telling it what files to |
| 3204 | operate on and what other things to do. |
| 3205 | |
| 3206 | @menu |
| 3207 | * Mode Options:: Options controlling modes of operation. |
| 3208 | * File Options:: Options to specify files (executable, coredump, commands) |
| 3209 | * Other Arguments:: Any other arguments without options |
| 3210 | also specify files. |
| 3211 | @end menu |
| 3212 | |
| 3213 | @node Mode Options, File Options, Options, Options |
| 3214 | @section Mode Options |
| 3215 | |
| 3216 | @table @samp |
| 3217 | @item -nx |
| 3218 | Do not execute commands from the init files @file{.gdbinit}. |
| 3219 | Normally, the commands in these files are executed after all the |
| 3220 | command options and arguments have been processed. @xref{Command |
| 3221 | Files}. |
| 3222 | |
| 3223 | @item -q |
| 3224 | ``Quiet''. Do not print the usual introductory messages. |
| 3225 | |
| 3226 | @item -batch |
| 3227 | Run in batch mode. Exit with code 0 after processing all the command |
| 3228 | files specified with @samp{-x} (and @file{.gdbinit}, if not inhibited). |
| 3229 | Exit with nonzero status if an error occurs in executing the GDB |
| 3230 | commands in the command files. |
| 3231 | |
| 3232 | @item -fullname |
| 3233 | This option is used when Emacs runs GDB as a subprocess. It tells GDB |
| 3234 | to output the full file name and line number in a standard, |
| 3235 | recognizable fashion each time a stack frame is displayed (which |
| 3236 | includes each time the program stops). This recognizable format looks |
| 3237 | like two @samp{\032} characters, followed by the file name, line number |
| 3238 | and character position separated by colons, and a newline. The |
| 3239 | Emacs-to-GDB interface program uses the two @samp{\032} characters as |
| 3240 | a signal to display the source code for the frame. |
| 3241 | @end table |
| 3242 | |
| 3243 | @node File Options, Other Arguments, Mode Options, Options |
| 3244 | @section File-specifying Options |
| 3245 | |
| 3246 | All the options and command line arguments given are processed |
| 3247 | in sequential order. The order makes a difference when the |
| 3248 | @samp{-x} option is used. |
| 3249 | |
| 3250 | @table @samp |
| 3251 | @item -s @var{file} |
| 3252 | Read symbol table from file @var{file}. |
| 3253 | |
| 3254 | @item -e @var{file} |
| 3255 | Use file @var{file} as the executable file to execute when |
| 3256 | appropriate, and for examining pure data in conjunction with a core |
| 3257 | dump. |
| 3258 | |
| 3259 | @item -se @var{file} |
| 3260 | Read symbol table from file @var{file} and use it as the executable |
| 3261 | file. |
| 3262 | |
| 3263 | @item -c @var{file} |
| 3264 | Use file @var{file} as a core dump to examine. |
| 3265 | |
| 3266 | @item -x @var{file} |
| 3267 | Execute GDB commands from file @var{file}. |
| 3268 | |
| 3269 | @item -d @var{directory} |
| 3270 | Add @var{directory} to the path to search for source files. |
| 3271 | @end table |
| 3272 | |
| 3273 | @node Other Arguments,, File Options, Options |
| 3274 | @section Other Arguments |
| 3275 | |
| 3276 | If there are arguments to GDB that are not options or associated with |
| 3277 | options, the first one specifies the symbol table and executable file name |
| 3278 | (as if it were preceded by @samp{-se}) and the second one specifies a core |
| 3279 | dump file name (as if it were preceded by @samp{-c}). |
| 3280 | |
| 3281 | @node Emacs, Remote, Options, Top |
| 3282 | @chapter Using GDB under GNU Emacs |
| 3283 | |
| 3284 | A special interface allows you to use GNU Emacs to view (and |
| 3285 | edit) the source files for the program you are debugging with |
| 3286 | GDB. |
| 3287 | |
| 3288 | To use this interface, use the command @kbd{M-x gdb} in Emacs. Give the |
| 3289 | executable file you want to debug as an argument. This command starts |
| 3290 | GDB as a subprocess of Emacs, with input and output through a newly |
| 3291 | created Emacs buffer. |
| 3292 | |
| 3293 | Using GDB under Emacs is just like using GDB normally except for two |
| 3294 | things: |
| 3295 | |
| 3296 | @itemize @bullet |
| 3297 | @item |
| 3298 | All ``terminal'' input and output goes through the Emacs buffer. This |
| 3299 | applies both to GDB commands and their output, and to the input and |
| 3300 | output done by the program you are debugging. |
| 3301 | |
| 3302 | This is useful because it means that you can copy the text of previous |
| 3303 | commands and input them again; you can even use parts of the output |
| 3304 | in this way. |
| 3305 | |
| 3306 | All the facilities of Emacs's Shell mode are available for this purpose. |
| 3307 | |
| 3308 | @item |
| 3309 | GDB displays source code through Emacs. Each time GDB displays a |
| 3310 | stack frame, Emacs automatically finds the source file for that frame |
| 3311 | and puts an arrow (@samp{=>}) at the left margin of the current line. |
| 3312 | |
| 3313 | Explicit GDB @samp{list} or search commands still produce output as |
| 3314 | usual, but you probably will have no reason to use them. |
| 3315 | @end itemize |
| 3316 | |
| 3317 | In the GDB I/O buffer, you can use these special Emacs commands: |
| 3318 | |
| 3319 | @table @kbd |
| 3320 | @item M-s |
| 3321 | Execute to another source line, like the GDB @samp{step} command. |
| 3322 | |
| 3323 | @item M-n |
| 3324 | Execute to next source line in this function, skipping all function |
| 3325 | calls, like the GDB @samp{next} command. |
| 3326 | |
| 3327 | @item M-i |
| 3328 | Execute one instruction, like the GDB @samp{stepi} command. |
| 3329 | |
| 3330 | @item C-c C-f |
| 3331 | Execute until exit from the selected stack frame, like the GDB |
| 3332 | @samp{finish} command. |
| 3333 | |
| 3334 | @item M-c |
| 3335 | @comment C-c C-p in emacs 19 |
| 3336 | Continue execution of the program, like the GDB @samp{cont} command. |
| 3337 | |
| 3338 | @item M-u |
| 3339 | @comment C-c C-u in emacs 19 |
| 3340 | Go up the number of frames indicated by the numeric argument |
| 3341 | (@pxref{Arguments, , Numeric Arguments, emacs, The GNU Emacs Manual}), |
| 3342 | like the GDB @samp{up} command.@refill |
| 3343 | |
| 3344 | @item M-d |
| 3345 | @comment C-c C-d in emacs 19 |
| 3346 | Go down the number of frames indicated by the numeric argument, like the |
| 3347 | GDB @samp{down} command. |
| 3348 | @end table |
| 3349 | |
| 3350 | In any source file, the Emacs command @kbd{C-x SPC} (@code{gdb-break}) |
| 3351 | tells GDB to set a breakpoint on the source line point is on. |
| 3352 | |
| 3353 | The source files displayed in Emacs are in ordinary Emacs buffers |
| 3354 | which are visiting the source files in the usual way. You can edit |
| 3355 | the files with these buffers if you wish; but keep in mind that GDB |
| 3356 | communicates with Emacs in terms of line numbers. If you add or |
| 3357 | delete lines from the text, the line numbers that GDB knows will cease |
| 3358 | to correspond properly to the code. |
| 3359 | |
| 3360 | @node Remote, Commands, Emacs, Top |
| 3361 | @chapter Remote Kernel Debugging |
| 3362 | |
| 3363 | If you are trying to debug a program running on a machine that can't run |
| 3364 | GDB in the usual way, it is often useful to use remote debugging. For |
| 3365 | example, you might be debugging an operating system kernel, or debugging |
| 3366 | a small system which does not have a general purpose operating system |
| 3367 | powerful enough to run a full-featured debugger. Currently GDB supports |
| 3368 | remote debugging over a serial connection. |
| 3369 | |
| 3370 | The program to be debugged on the remote machine needs to contain a |
| 3371 | debugging device driver which talks to GDB over the serial line using the |
| 3372 | protocol described below. The same version of GDB that is used ordinarily |
| 3373 | can be used for this. Several sample remote debugging drivers are |
| 3374 | distributed with GDB; see the @file{README} file in the GDB distribution for |
| 3375 | more information. |
| 3376 | |
| 3377 | @menu |
| 3378 | * Remote Commands:: Commands used to start and finish remote debugging. |
| 3379 | @end menu |
| 3380 | |
| 3381 | For details of the communication protocol, see the comments in the GDB |
| 3382 | source file @file{remote.c}. |
| 3383 | |
| 3384 | @node Remote Commands,, Remote, Remote |
| 3385 | @section Commands for Remote Debugging |
| 3386 | |
| 3387 | To start remote debugging, first run GDB and specify as an executable file |
| 3388 | the program that is running in the remote machine. This tells GDB how |
| 3389 | to find the program's symbols and the contents of its pure text. Then |
| 3390 | establish communication using the @samp{attach} command with a device |
| 3391 | name rather than a pid as an argument. For example: |
| 3392 | |
| 3393 | @example |
| 3394 | attach /dev/ttyd |
| 3395 | @end example |
| 3396 | |
| 3397 | @noindent |
| 3398 | if the serial line is connected to the device named @file{/dev/ttyd}. This |
| 3399 | will stop the remote machine if it is not already stopped. |
| 3400 | |
| 3401 | Now you can use all the usual commands to examine and change data and to |
| 3402 | step and continue the remote program. |
| 3403 | |
| 3404 | To resume the remote program and stop debugging it, use the @samp{detach} |
| 3405 | command. |
| 3406 | |
| 3407 | @ignore |
| 3408 | This material will be merged in when better Readline documentation |
| 3409 | is done. |
| 3410 | |
| 3411 | @node GDB Readline, History Top ,Readline Top, Command Editing |
| 3412 | @subsection GDB Readline |
| 3413 | |
| 3414 | You may control the behavior of command line editing in GDB with the |
| 3415 | following commands: |
| 3416 | |
| 3417 | @table @code |
| 3418 | @kindex set editing |
| 3419 | @item set editing |
| 3420 | @itemx set editing on |
| 3421 | Enable command line editing (enabled by default). |
| 3422 | |
| 3423 | @item set editing off |
| 3424 | Disable command line editing. |
| 3425 | |
| 3426 | @kindex set history file |
| 3427 | @item set history file @var{filename} |
| 3428 | Set the name of the GDB command history file to @var{filename}. This is |
| 3429 | the file from which GDB will read an initial command history |
| 3430 | list or to which it will write this list when it exits. This list is |
| 3431 | accessed through history expansion or through the history |
| 3432 | command editing characters listed below. This file defaults to the |
| 3433 | value of the environmental variable @code{GDBHISTFILE}, or to |
| 3434 | @code{./.gdb_history} if this variable is not set. |
| 3435 | |
| 3436 | @kindex set history write |
| 3437 | @item set history write |
| 3438 | @itemx set history write on |
| 3439 | Enable the writing of the command history to the command history file |
| 3440 | named above. This is enabled by default. |
| 3441 | |
| 3442 | @item set history write off |
| 3443 | Disable the writing of the command history to the command history file. |
| 3444 | |
| 3445 | @kindex set history size |
| 3446 | @item set history size @var{size} |
| 3447 | Set the number of commands which GDB will keep in its history list. |
| 3448 | This defaults to the value of the environmental variable |
| 3449 | @code{HISTSIZE}, or to 256 if this variable is not set. |
| 3450 | |
| 3451 | @kindex info editing |
| 3452 | @item info editing |
| 3453 | Display the current settings relating to command line editing, and also |
| 3454 | display the last ten commands in the command history. |
| 3455 | |
| 3456 | @item info editing @var{n} |
| 3457 | Print ten commands centered on command number @var{n}. |
| 3458 | |
| 3459 | @item info editing + |
| 3460 | Print ten commands just after the commands last printed. |
| 3461 | @end table |
| 3462 | |
| 3463 | @node GDB History, , History Top, Command editing |
| 3464 | @comment node-name, next, previous, up |
| 3465 | Note that because of the additional meaning of @code{!} to GDB (as the |
| 3466 | logical not operator in C), history expansion is off by default. If you |
| 3467 | decide to enable history expansion with the @samp{set history expansion |
| 3468 | on} command, you will need to follow @samp{!} with a space or a tab to |
| 3469 | prevent it from being expanded. |
| 3470 | |
| 3471 | The commands to control history expansion are: |
| 3472 | |
| 3473 | @table @code |
| 3474 | |
| 3475 | @kindex set history expansion |
| 3476 | @item set history expansion on |
| 3477 | @itemx set history expansion |
| 3478 | Enable history expansion. |
| 3479 | |
| 3480 | @item set history expansion off |
| 3481 | Disable history expansion. History expansion is off by default. |
| 3482 | |
| 3483 | @end table |
| 3484 | @end ignore |
| 3485 | |
| 3486 | @node Commands, Concepts, Remote, Top |
| 3487 | @unnumbered Command Index |
| 3488 | |
| 3489 | @printindex ky |
| 3490 | |
| 3491 | @node Concepts, , Commands, Top |
| 3492 | @unnumbered Concept Index |
| 3493 | |
| 3494 | @printindex cp |
| 3495 | |
| 3496 | @contents |
| 3497 | @bye |
| 3498 | |
| 3499 | |
| 3500 | |
| 3501 | |
| 3502 | Occasionally it is useful to execute a shell command from within GDB. |
| 3503 | This can be done with the @samp{shell} command. |
| 3504 | |
| 3505 | @table @code |
| 3506 | @item shell @var{shell command string} |
| 3507 | @kindex shell |
| 3508 | @cindex shell escape |
| 3509 | Directs GDB to invoke an inferior shell to execute @var{shell command string}. |
| 3510 | The environment variable @code{SHELL} is used if it exists, otherwise GDB |
| 3511 | uses @samp{/bin/sh}. |
| 3512 | @end table |