1This is gdb.info, produced by makeinfo version 4.8 from ./gdb.texinfo. 2 3INFO-DIR-SECTION Software development 4START-INFO-DIR-ENTRY 5* Gdb: (gdb). The GNU debugger. 6END-INFO-DIR-ENTRY 7 8 Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996, 91998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 102010 Free Software Foundation, Inc. 11 12 Permission is granted to copy, distribute and/or modify this document 13under the terms of the GNU Free Documentation License, Version 1.3 or 14any later version published by the Free Software Foundation; with the 15Invariant Sections being "Free Software" and "Free Software Needs Free 16Documentation", with the Front-Cover Texts being "A GNU Manual," and 17with the Back-Cover Texts as in (a) below. 18 19 (a) The FSF's Back-Cover Text is: "You are free to copy and modify 20this GNU Manual. Buying copies from GNU Press supports the FSF in 21developing GNU and promoting software freedom." 22 23 This file documents the GNU debugger GDB. 24 25 This is the Tenth Edition, of `Debugging with GDB: the GNU 26Source-Level Debugger' for GDB (GDB) Version 7.3.1. 27 28 Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996, 291998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 302010 Free Software Foundation, Inc. 31 32 Permission is granted to copy, distribute and/or modify this document 33under the terms of the GNU Free Documentation License, Version 1.3 or 34any later version published by the Free Software Foundation; with the 35Invariant Sections being "Free Software" and "Free Software Needs Free 36Documentation", with the Front-Cover Texts being "A GNU Manual," and 37with the Back-Cover Texts as in (a) below. 38 39 (a) The FSF's Back-Cover Text is: "You are free to copy and modify 40this GNU Manual. Buying copies from GNU Press supports the FSF in 41developing GNU and promoting software freedom." 42 43 44File: gdb.info, Node: GDB/MI Program Execution, Next: GDB/MI Stack Manipulation, Prev: GDB/MI Thread Commands, Up: GDB/MI 45 4627.11 GDB/MI Program Execution 47============================== 48 49These are the asynchronous commands which generate the out-of-band 50record `*stopped'. Currently GDB only really executes asynchronously 51with remote targets and this interaction is mimicked in other cases. 52 53The `-exec-continue' Command 54---------------------------- 55 56Synopsis 57........ 58 59 -exec-continue [--reverse] [--all|--thread-group N] 60 61 Resumes the execution of the inferior program, which will continue 62to execute until it reaches a debugger stop event. If the `--reverse' 63option is specified, execution resumes in reverse until it reaches a 64stop event. Stop events may include 65 * breakpoints or watchpoints 66 67 * signals or exceptions 68 69 * the end of the process (or its beginning under `--reverse') 70 71 * the end or beginning of a replay log if one is being used. 72 In all-stop mode (*note All-Stop Mode::), may resume only one 73thread, or all threads, depending on the value of the 74`scheduler-locking' variable. If `--all' is specified, all threads (in 75all inferiors) will be resumed. The `--all' option is ignored in 76all-stop mode. If the `--thread-group' options is specified, then all 77threads in that thread group are resumed. 78 79GDB Command 80........... 81 82The corresponding GDB corresponding is `continue'. 83 84Example 85....... 86 87 -exec-continue 88 ^running 89 (gdb) 90 @Hello world 91 *stopped,reason="breakpoint-hit",disp="keep",bkptno="2",frame={ 92 func="foo",args=[],file="hello.c",fullname="/home/foo/bar/hello.c", 93 line="13"} 94 (gdb) 95 96The `-exec-finish' Command 97-------------------------- 98 99Synopsis 100........ 101 102 -exec-finish [--reverse] 103 104 Resumes the execution of the inferior program until the current 105function is exited. Displays the results returned by the function. If 106the `--reverse' option is specified, resumes the reverse execution of 107the inferior program until the point where current function was called. 108 109GDB Command 110........... 111 112The corresponding GDB command is `finish'. 113 114Example 115....... 116 117Function returning `void'. 118 119 -exec-finish 120 ^running 121 (gdb) 122 @hello from foo 123 *stopped,reason="function-finished",frame={func="main",args=[], 124 file="hello.c",fullname="/home/foo/bar/hello.c",line="7"} 125 (gdb) 126 127 Function returning other than `void'. The name of the internal GDB 128variable storing the result is printed, together with the value itself. 129 130 -exec-finish 131 ^running 132 (gdb) 133 *stopped,reason="function-finished",frame={addr="0x000107b0",func="foo", 134 args=[{name="a",value="1"],{name="b",value="9"}}, 135 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"}, 136 gdb-result-var="$1",return-value="0" 137 (gdb) 138 139The `-exec-interrupt' Command 140----------------------------- 141 142Synopsis 143........ 144 145 -exec-interrupt [--all|--thread-group N] 146 147 Interrupts the background execution of the target. Note how the 148token associated with the stop message is the one for the execution 149command that has been interrupted. The token for the interrupt itself 150only appears in the `^done' output. If the user is trying to interrupt 151a non-running program, an error message will be printed. 152 153 Note that when asynchronous execution is enabled, this command is 154asynchronous just like other execution commands. That is, first the 155`^done' response will be printed, and the target stop will be reported 156after that using the `*stopped' notification. 157 158 In non-stop mode, only the context thread is interrupted by default. 159All threads (in all inferiors) will be interrupted if the `--all' 160option is specified. If the `--thread-group' option is specified, all 161threads in that group will be interrupted. 162 163GDB Command 164........... 165 166The corresponding GDB command is `interrupt'. 167 168Example 169....... 170 171 (gdb) 172 111-exec-continue 173 111^running 174 175 (gdb) 176 222-exec-interrupt 177 222^done 178 (gdb) 179 111*stopped,signal-name="SIGINT",signal-meaning="Interrupt", 180 frame={addr="0x00010140",func="foo",args=[],file="try.c", 181 fullname="/home/foo/bar/try.c",line="13"} 182 (gdb) 183 184 (gdb) 185 -exec-interrupt 186 ^error,msg="mi_cmd_exec_interrupt: Inferior not executing." 187 (gdb) 188 189The `-exec-jump' Command 190------------------------ 191 192Synopsis 193........ 194 195 -exec-jump LOCATION 196 197 Resumes execution of the inferior program at the location specified 198by parameter. *Note Specify Location::, for a description of the 199different forms of LOCATION. 200 201GDB Command 202........... 203 204The corresponding GDB command is `jump'. 205 206Example 207....... 208 209 -exec-jump foo.c:10 210 *running,thread-id="all" 211 ^running 212 213The `-exec-next' Command 214------------------------ 215 216Synopsis 217........ 218 219 -exec-next [--reverse] 220 221 Resumes execution of the inferior program, stopping when the 222beginning of the next source line is reached. 223 224 If the `--reverse' option is specified, resumes reverse execution of 225the inferior program, stopping at the beginning of the previous source 226line. If you issue this command on the first line of a function, it 227will take you back to the caller of that function, to the source line 228where the function was called. 229 230GDB Command 231........... 232 233The corresponding GDB command is `next'. 234 235Example 236....... 237 238 -exec-next 239 ^running 240 (gdb) 241 *stopped,reason="end-stepping-range",line="8",file="hello.c" 242 (gdb) 243 244The `-exec-next-instruction' Command 245------------------------------------ 246 247Synopsis 248........ 249 250 -exec-next-instruction [--reverse] 251 252 Executes one machine instruction. If the instruction is a function 253call, continues until the function returns. If the program stops at an 254instruction in the middle of a source line, the address will be printed 255as well. 256 257 If the `--reverse' option is specified, resumes reverse execution of 258the inferior program, stopping at the previous instruction. If the 259previously executed instruction was a return from another function, it 260will continue to execute in reverse until the call to that function 261(from the current stack frame) is reached. 262 263GDB Command 264........... 265 266The corresponding GDB command is `nexti'. 267 268Example 269....... 270 271 (gdb) 272 -exec-next-instruction 273 ^running 274 275 (gdb) 276 *stopped,reason="end-stepping-range", 277 addr="0x000100d4",line="5",file="hello.c" 278 (gdb) 279 280The `-exec-return' Command 281-------------------------- 282 283Synopsis 284........ 285 286 -exec-return 287 288 Makes current function return immediately. Doesn't execute the 289inferior. Displays the new current frame. 290 291GDB Command 292........... 293 294The corresponding GDB command is `return'. 295 296Example 297....... 298 299 (gdb) 300 200-break-insert callee4 301 200^done,bkpt={number="1",addr="0x00010734", 302 file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="8"} 303 (gdb) 304 000-exec-run 305 000^running 306 (gdb) 307 000*stopped,reason="breakpoint-hit",disp="keep",bkptno="1", 308 frame={func="callee4",args=[], 309 file="../../../devo/gdb/testsuite/gdb.mi/basics.c", 310 fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="8"} 311 (gdb) 312 205-break-delete 313 205^done 314 (gdb) 315 111-exec-return 316 111^done,frame={level="0",func="callee3", 317 args=[{name="strarg", 318 value="0x11940 \"A string argument.\""}], 319 file="../../../devo/gdb/testsuite/gdb.mi/basics.c", 320 fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="18"} 321 (gdb) 322 323The `-exec-run' Command 324----------------------- 325 326Synopsis 327........ 328 329 -exec-run [--all | --thread-group N] 330 331 Starts execution of the inferior from the beginning. The inferior 332executes until either a breakpoint is encountered or the program exits. 333In the latter case the output will include an exit code, if the 334program has exited exceptionally. 335 336 When no option is specified, the current inferior is started. If the 337`--thread-group' option is specified, it should refer to a thread group 338of type `process', and that thread group will be started. If the 339`--all' option is specified, then all inferiors will be started. 340 341GDB Command 342........... 343 344The corresponding GDB command is `run'. 345 346Examples 347........ 348 349 (gdb) 350 -break-insert main 351 ^done,bkpt={number="1",addr="0x0001072c",file="recursive2.c",line="4"} 352 (gdb) 353 -exec-run 354 ^running 355 (gdb) 356 *stopped,reason="breakpoint-hit",disp="keep",bkptno="1", 357 frame={func="main",args=[],file="recursive2.c", 358 fullname="/home/foo/bar/recursive2.c",line="4"} 359 (gdb) 360 361Program exited normally: 362 363 (gdb) 364 -exec-run 365 ^running 366 (gdb) 367 x = 55 368 *stopped,reason="exited-normally" 369 (gdb) 370 371Program exited exceptionally: 372 373 (gdb) 374 -exec-run 375 ^running 376 (gdb) 377 x = 55 378 *stopped,reason="exited",exit-code="01" 379 (gdb) 380 381 Another way the program can terminate is if it receives a signal 382such as `SIGINT'. In this case, GDB/MI displays this: 383 384 (gdb) 385 *stopped,reason="exited-signalled",signal-name="SIGINT", 386 signal-meaning="Interrupt" 387 388The `-exec-step' Command 389------------------------ 390 391Synopsis 392........ 393 394 -exec-step [--reverse] 395 396 Resumes execution of the inferior program, stopping when the 397beginning of the next source line is reached, if the next source line 398is not a function call. If it is, stop at the first instruction of the 399called function. If the `--reverse' option is specified, resumes 400reverse execution of the inferior program, stopping at the beginning of 401the previously executed source line. 402 403GDB Command 404........... 405 406The corresponding GDB command is `step'. 407 408Example 409....... 410 411Stepping into a function: 412 413 -exec-step 414 ^running 415 (gdb) 416 *stopped,reason="end-stepping-range", 417 frame={func="foo",args=[{name="a",value="10"}, 418 {name="b",value="0"}],file="recursive2.c", 419 fullname="/home/foo/bar/recursive2.c",line="11"} 420 (gdb) 421 422 Regular stepping: 423 424 -exec-step 425 ^running 426 (gdb) 427 *stopped,reason="end-stepping-range",line="14",file="recursive2.c" 428 (gdb) 429 430The `-exec-step-instruction' Command 431------------------------------------ 432 433Synopsis 434........ 435 436 -exec-step-instruction [--reverse] 437 438 Resumes the inferior which executes one machine instruction. If the 439`--reverse' option is specified, resumes reverse execution of the 440inferior program, stopping at the previously executed instruction. The 441output, once GDB has stopped, will vary depending on whether we have 442stopped in the middle of a source line or not. In the former case, the 443address at which the program stopped will be printed as well. 444 445GDB Command 446........... 447 448The corresponding GDB command is `stepi'. 449 450Example 451....... 452 453 (gdb) 454 -exec-step-instruction 455 ^running 456 457 (gdb) 458 *stopped,reason="end-stepping-range", 459 frame={func="foo",args=[],file="try.c", 460 fullname="/home/foo/bar/try.c",line="10"} 461 (gdb) 462 -exec-step-instruction 463 ^running 464 465 (gdb) 466 *stopped,reason="end-stepping-range", 467 frame={addr="0x000100f4",func="foo",args=[],file="try.c", 468 fullname="/home/foo/bar/try.c",line="10"} 469 (gdb) 470 471The `-exec-until' Command 472------------------------- 473 474Synopsis 475........ 476 477 -exec-until [ LOCATION ] 478 479 Executes the inferior until the LOCATION specified in the argument 480is reached. If there is no argument, the inferior executes until a 481source line greater than the current one is reached. The reason for 482stopping in this case will be `location-reached'. 483 484GDB Command 485........... 486 487The corresponding GDB command is `until'. 488 489Example 490....... 491 492 (gdb) 493 -exec-until recursive2.c:6 494 ^running 495 (gdb) 496 x = 55 497 *stopped,reason="location-reached",frame={func="main",args=[], 498 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="6"} 499 (gdb) 500 501 502File: gdb.info, Node: GDB/MI Stack Manipulation, Next: GDB/MI Variable Objects, Prev: GDB/MI Program Execution, Up: GDB/MI 503 50427.12 GDB/MI Stack Manipulation Commands 505======================================== 506 507The `-stack-info-frame' Command 508------------------------------- 509 510Synopsis 511........ 512 513 -stack-info-frame 514 515 Get info on the selected frame. 516 517GDB Command 518........... 519 520The corresponding GDB command is `info frame' or `frame' (without 521arguments). 522 523Example 524....... 525 526 (gdb) 527 -stack-info-frame 528 ^done,frame={level="1",addr="0x0001076c",func="callee3", 529 file="../../../devo/gdb/testsuite/gdb.mi/basics.c", 530 fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="17"} 531 (gdb) 532 533The `-stack-info-depth' Command 534------------------------------- 535 536Synopsis 537........ 538 539 -stack-info-depth [ MAX-DEPTH ] 540 541 Return the depth of the stack. If the integer argument MAX-DEPTH is 542specified, do not count beyond MAX-DEPTH frames. 543 544GDB Command 545........... 546 547There's no equivalent GDB command. 548 549Example 550....... 551 552For a stack with frame levels 0 through 11: 553 554 (gdb) 555 -stack-info-depth 556 ^done,depth="12" 557 (gdb) 558 -stack-info-depth 4 559 ^done,depth="4" 560 (gdb) 561 -stack-info-depth 12 562 ^done,depth="12" 563 (gdb) 564 -stack-info-depth 11 565 ^done,depth="11" 566 (gdb) 567 -stack-info-depth 13 568 ^done,depth="12" 569 (gdb) 570 571The `-stack-list-arguments' Command 572----------------------------------- 573 574Synopsis 575........ 576 577 -stack-list-arguments PRINT-VALUES 578 [ LOW-FRAME HIGH-FRAME ] 579 580 Display a list of the arguments for the frames between LOW-FRAME and 581HIGH-FRAME (inclusive). If LOW-FRAME and HIGH-FRAME are not provided, 582list the arguments for the whole call stack. If the two arguments are 583equal, show the single frame at the corresponding level. It is an 584error if LOW-FRAME is larger than the actual number of frames. On the 585other hand, HIGH-FRAME may be larger than the actual number of frames, 586in which case only existing frames will be returned. 587 588 If PRINT-VALUES is 0 or `--no-values', print only the names of the 589variables; if it is 1 or `--all-values', print also their values; and 590if it is 2 or `--simple-values', print the name, type and value for 591simple data types, and the name and type for arrays, structures and 592unions. 593 594 Use of this command to obtain arguments in a single frame is 595deprecated in favor of the `-stack-list-variables' command. 596 597GDB Command 598........... 599 600GDB does not have an equivalent command. `gdbtk' has a `gdb_get_args' 601command which partially overlaps with the functionality of 602`-stack-list-arguments'. 603 604Example 605....... 606 607 (gdb) 608 -stack-list-frames 609 ^done, 610 stack=[ 611 frame={level="0",addr="0x00010734",func="callee4", 612 file="../../../devo/gdb/testsuite/gdb.mi/basics.c", 613 fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="8"}, 614 frame={level="1",addr="0x0001076c",func="callee3", 615 file="../../../devo/gdb/testsuite/gdb.mi/basics.c", 616 fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="17"}, 617 frame={level="2",addr="0x0001078c",func="callee2", 618 file="../../../devo/gdb/testsuite/gdb.mi/basics.c", 619 fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="22"}, 620 frame={level="3",addr="0x000107b4",func="callee1", 621 file="../../../devo/gdb/testsuite/gdb.mi/basics.c", 622 fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="27"}, 623 frame={level="4",addr="0x000107e0",func="main", 624 file="../../../devo/gdb/testsuite/gdb.mi/basics.c", 625 fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="32"}] 626 (gdb) 627 -stack-list-arguments 0 628 ^done, 629 stack-args=[ 630 frame={level="0",args=[]}, 631 frame={level="1",args=[name="strarg"]}, 632 frame={level="2",args=[name="intarg",name="strarg"]}, 633 frame={level="3",args=[name="intarg",name="strarg",name="fltarg"]}, 634 frame={level="4",args=[]}] 635 (gdb) 636 -stack-list-arguments 1 637 ^done, 638 stack-args=[ 639 frame={level="0",args=[]}, 640 frame={level="1", 641 args=[{name="strarg",value="0x11940 \"A string argument.\""}]}, 642 frame={level="2",args=[ 643 {name="intarg",value="2"}, 644 {name="strarg",value="0x11940 \"A string argument.\""}]}, 645 {frame={level="3",args=[ 646 {name="intarg",value="2"}, 647 {name="strarg",value="0x11940 \"A string argument.\""}, 648 {name="fltarg",value="3.5"}]}, 649 frame={level="4",args=[]}] 650 (gdb) 651 -stack-list-arguments 0 2 2 652 ^done,stack-args=[frame={level="2",args=[name="intarg",name="strarg"]}] 653 (gdb) 654 -stack-list-arguments 1 2 2 655 ^done,stack-args=[frame={level="2", 656 args=[{name="intarg",value="2"}, 657 {name="strarg",value="0x11940 \"A string argument.\""}]}] 658 (gdb) 659 660The `-stack-list-frames' Command 661-------------------------------- 662 663Synopsis 664........ 665 666 -stack-list-frames [ LOW-FRAME HIGH-FRAME ] 667 668 List the frames currently on the stack. For each frame it displays 669the following info: 670 671`LEVEL' 672 The frame number, 0 being the topmost frame, i.e., the innermost 673 function. 674 675`ADDR' 676 The `$pc' value for that frame. 677 678`FUNC' 679 Function name. 680 681`FILE' 682 File name of the source file where the function lives. 683 684`FULLNAME' 685 The full file name of the source file where the function lives. 686 687`LINE' 688 Line number corresponding to the `$pc'. 689 690`FROM' 691 The shared library where this function is defined. This is only 692 given if the frame's function is not known. 693 694 If invoked without arguments, this command prints a backtrace for the 695whole stack. If given two integer arguments, it shows the frames whose 696levels are between the two arguments (inclusive). If the two arguments 697are equal, it shows the single frame at the corresponding level. It is 698an error if LOW-FRAME is larger than the actual number of frames. On 699the other hand, HIGH-FRAME may be larger than the actual number of 700frames, in which case only existing frames will be returned. 701 702GDB Command 703........... 704 705The corresponding GDB commands are `backtrace' and `where'. 706 707Example 708....... 709 710Full stack backtrace: 711 712 (gdb) 713 -stack-list-frames 714 ^done,stack= 715 [frame={level="0",addr="0x0001076c",func="foo", 716 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="11"}, 717 frame={level="1",addr="0x000107a4",func="foo", 718 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"}, 719 frame={level="2",addr="0x000107a4",func="foo", 720 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"}, 721 frame={level="3",addr="0x000107a4",func="foo", 722 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"}, 723 frame={level="4",addr="0x000107a4",func="foo", 724 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"}, 725 frame={level="5",addr="0x000107a4",func="foo", 726 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"}, 727 frame={level="6",addr="0x000107a4",func="foo", 728 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"}, 729 frame={level="7",addr="0x000107a4",func="foo", 730 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"}, 731 frame={level="8",addr="0x000107a4",func="foo", 732 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"}, 733 frame={level="9",addr="0x000107a4",func="foo", 734 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"}, 735 frame={level="10",addr="0x000107a4",func="foo", 736 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"}, 737 frame={level="11",addr="0x00010738",func="main", 738 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="4"}] 739 (gdb) 740 741 Show frames between LOW_FRAME and HIGH_FRAME: 742 743 (gdb) 744 -stack-list-frames 3 5 745 ^done,stack= 746 [frame={level="3",addr="0x000107a4",func="foo", 747 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"}, 748 frame={level="4",addr="0x000107a4",func="foo", 749 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"}, 750 frame={level="5",addr="0x000107a4",func="foo", 751 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"}] 752 (gdb) 753 754 Show a single frame: 755 756 (gdb) 757 -stack-list-frames 3 3 758 ^done,stack= 759 [frame={level="3",addr="0x000107a4",func="foo", 760 file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14"}] 761 (gdb) 762 763The `-stack-list-locals' Command 764-------------------------------- 765 766Synopsis 767........ 768 769 -stack-list-locals PRINT-VALUES 770 771 Display the local variable names for the selected frame. If 772PRINT-VALUES is 0 or `--no-values', print only the names of the 773variables; if it is 1 or `--all-values', print also their values; and 774if it is 2 or `--simple-values', print the name, type and value for 775simple data types, and the name and type for arrays, structures and 776unions. In this last case, a frontend can immediately display the 777value of simple data types and create variable objects for other data 778types when the user wishes to explore their values in more detail. 779 780 This command is deprecated in favor of the `-stack-list-variables' 781command. 782 783GDB Command 784........... 785 786`info locals' in GDB, `gdb_get_locals' in `gdbtk'. 787 788Example 789....... 790 791 (gdb) 792 -stack-list-locals 0 793 ^done,locals=[name="A",name="B",name="C"] 794 (gdb) 795 -stack-list-locals --all-values 796 ^done,locals=[{name="A",value="1"},{name="B",value="2"}, 797 {name="C",value="{1, 2, 3}"}] 798 -stack-list-locals --simple-values 799 ^done,locals=[{name="A",type="int",value="1"}, 800 {name="B",type="int",value="2"},{name="C",type="int [3]"}] 801 (gdb) 802 803The `-stack-list-variables' Command 804----------------------------------- 805 806Synopsis 807........ 808 809 -stack-list-variables PRINT-VALUES 810 811 Display the names of local variables and function arguments for the 812selected frame. If PRINT-VALUES is 0 or `--no-values', print only the 813names of the variables; if it is 1 or `--all-values', print also their 814values; and if it is 2 or `--simple-values', print the name, type and 815value for simple data types, and the name and type for arrays, 816structures and unions. 817 818Example 819....... 820 821 (gdb) 822 -stack-list-variables --thread 1 --frame 0 --all-values 823 ^done,variables=[{name="x",value="11"},{name="s",value="{a = 1, b = 2}"}] 824 (gdb) 825 826The `-stack-select-frame' Command 827--------------------------------- 828 829Synopsis 830........ 831 832 -stack-select-frame FRAMENUM 833 834 Change the selected frame. Select a different frame FRAMENUM on the 835stack. 836 837 This command in deprecated in favor of passing the `--frame' option 838to every command. 839 840GDB Command 841........... 842 843The corresponding GDB commands are `frame', `up', `down', 844`select-frame', `up-silent', and `down-silent'. 845 846Example 847....... 848 849 (gdb) 850 -stack-select-frame 2 851 ^done 852 (gdb) 853 854 855File: gdb.info, Node: GDB/MI Variable Objects, Next: GDB/MI Data Manipulation, Prev: GDB/MI Stack Manipulation, Up: GDB/MI 856 85727.13 GDB/MI Variable Objects 858============================= 859 860Introduction to Variable Objects 861-------------------------------- 862 863Variable objects are "object-oriented" MI interface for examining and 864changing values of expressions. Unlike some other MI interfaces that 865work with expressions, variable objects are specifically designed for 866simple and efficient presentation in the frontend. A variable object 867is identified by string name. When a variable object is created, the 868frontend specifies the expression for that variable object. The 869expression can be a simple variable, or it can be an arbitrary complex 870expression, and can even involve CPU registers. After creating a 871variable object, the frontend can invoke other variable object 872operations--for example to obtain or change the value of a variable 873object, or to change display format. 874 875 Variable objects have hierarchical tree structure. Any variable 876object that corresponds to a composite type, such as structure in C, has 877a number of child variable objects, for example corresponding to each 878element of a structure. A child variable object can itself have 879children, recursively. Recursion ends when we reach leaf variable 880objects, which always have built-in types. Child variable objects are 881created only by explicit request, so if a frontend is not interested in 882the children of a particular variable object, no child will be created. 883 884 For a leaf variable object it is possible to obtain its value as a 885string, or set the value from a string. String value can be also 886obtained for a non-leaf variable object, but it's generally a string 887that only indicates the type of the object, and does not list its 888contents. Assignment to a non-leaf variable object is not allowed. 889 890 A frontend does not need to read the values of all variable objects 891each time the program stops. Instead, MI provides an update command 892that lists all variable objects whose values has changed since the last 893update operation. This considerably reduces the amount of data that 894must be transferred to the frontend. As noted above, children variable 895objects are created on demand, and only leaf variable objects have a 896real value. As result, gdb will read target memory only for leaf 897variables that frontend has created. 898 899 The automatic update is not always desirable. For example, a 900frontend might want to keep a value of some expression for future 901reference, and never update it. For another example, fetching memory 902is relatively slow for embedded targets, so a frontend might want to 903disable automatic update for the variables that are either not visible 904on the screen, or "closed". This is possible using so called "frozen 905variable objects". Such variable objects are never implicitly updated. 906 907 Variable objects can be either "fixed" or "floating". For the fixed 908variable object, the expression is parsed when the variable object is 909created, including associating identifiers to specific variables. The 910meaning of expression never changes. For a floating variable object 911the values of variables whose names appear in the expressions are 912re-evaluated every time in the context of the current frame. Consider 913this example: 914 915 void do_work(...) 916 { 917 struct work_state state; 918 919 if (...) 920 do_work(...); 921 } 922 923 If a fixed variable object for the `state' variable is created in 924this function, and we enter the recursive call, the the variable object 925will report the value of `state' in the top-level `do_work' invocation. 926On the other hand, a floating variable object will report the value of 927`state' in the current frame. 928 929 If an expression specified when creating a fixed variable object 930refers to a local variable, the variable object becomes bound to the 931thread and frame in which the variable object is created. When such 932variable object is updated, GDB makes sure that the thread/frame 933combination the variable object is bound to still exists, and 934re-evaluates the variable object in context of that thread/frame. 935 936 The following is the complete set of GDB/MI operations defined to 937access this functionality: 938 939*Operation* *Description* 940`-enable-pretty-printing' enable Python-based pretty-printing 941`-var-create' create a variable object 942`-var-delete' delete the variable object and/or its 943 children 944`-var-set-format' set the display format of this variable 945`-var-show-format' show the display format of this variable 946`-var-info-num-children' tells how many children this object has 947`-var-list-children' return a list of the object's children 948`-var-info-type' show the type of this variable object 949`-var-info-expression' print parent-relative expression that this 950 variable object represents 951`-var-info-path-expression' print full expression that this variable 952 object represents 953`-var-show-attributes' is this variable editable? does it exist 954 here? 955`-var-evaluate-expression' get the value of this variable 956`-var-assign' set the value of this variable 957`-var-update' update the variable and its children 958`-var-set-frozen' set frozeness attribute 959`-var-set-update-range' set range of children to display on update 960 961 In the next subsection we describe each operation in detail and 962suggest how it can be used. 963 964Description And Use of Operations on Variable Objects 965----------------------------------------------------- 966 967The `-enable-pretty-printing' Command 968------------------------------------- 969 970 -enable-pretty-printing 971 972 GDB allows Python-based visualizers to affect the output of the MI 973variable object commands. However, because there was no way to 974implement this in a fully backward-compatible way, a front end must 975request that this functionality be enabled. 976 977 Once enabled, this feature cannot be disabled. 978 979 Note that if Python support has not been compiled into GDB, this 980command will still succeed (and do nothing). 981 982 This feature is currently (as of GDB 7.0) experimental, and may work 983differently in future versions of GDB. 984 985The `-var-create' Command 986------------------------- 987 988Synopsis 989........ 990 991 -var-create {NAME | "-"} 992 {FRAME-ADDR | "*" | "@"} EXPRESSION 993 994 This operation creates a variable object, which allows the 995monitoring of a variable, the result of an expression, a memory cell or 996a CPU register. 997 998 The NAME parameter is the string by which the object can be 999referenced. It must be unique. If `-' is specified, the varobj system 1000will generate a string "varNNNNNN" automatically. It will be unique 1001provided that one does not specify NAME of that format. The command 1002fails if a duplicate name is found. 1003 1004 The frame under which the expression should be evaluated can be 1005specified by FRAME-ADDR. A `*' indicates that the current frame should 1006be used. A `@' indicates that a floating variable object must be 1007created. 1008 1009 EXPRESSION is any expression valid on the current language set (must 1010not begin with a `*'), or one of the following: 1011 1012 * `*ADDR', where ADDR is the address of a memory cell 1013 1014 * `*ADDR-ADDR' -- a memory address range (TBD) 1015 1016 * `$REGNAME' -- a CPU register name 1017 1018 A varobj's contents may be provided by a Python-based 1019pretty-printer. In this case the varobj is known as a "dynamic 1020varobj". Dynamic varobjs have slightly different semantics in some 1021cases. If the `-enable-pretty-printing' command is not sent, then GDB 1022will never create a dynamic varobj. This ensures backward 1023compatibility for existing clients. 1024 1025Result 1026...... 1027 1028This operation returns attributes of the newly-created varobj. These 1029are: 1030 1031`name' 1032 The name of the varobj. 1033 1034`numchild' 1035 The number of children of the varobj. This number is not 1036 necessarily reliable for a dynamic varobj. Instead, you must 1037 examine the `has_more' attribute. 1038 1039`value' 1040 The varobj's scalar value. For a varobj whose type is some sort of 1041 aggregate (e.g., a `struct'), or for a dynamic varobj, this value 1042 will not be interesting. 1043 1044`type' 1045 The varobj's type. This is a string representation of the type, as 1046 would be printed by the GDB CLI. 1047 1048`thread-id' 1049 If a variable object is bound to a specific thread, then this is 1050 the thread's identifier. 1051 1052`has_more' 1053 For a dynamic varobj, this indicates whether there appear to be any 1054 children available. For a non-dynamic varobj, this will be 0. 1055 1056`dynamic' 1057 This attribute will be present and have the value `1' if the 1058 varobj is a dynamic varobj. If the varobj is not a dynamic varobj, 1059 then this attribute will not be present. 1060 1061`displayhint' 1062 A dynamic varobj can supply a display hint to the front end. The 1063 value comes directly from the Python pretty-printer object's 1064 `display_hint' method. *Note Pretty Printing API::. 1065 1066 Typical output will look like this: 1067 1068 name="NAME",numchild="N",type="TYPE",thread-id="M", 1069 has_more="HAS_MORE" 1070 1071The `-var-delete' Command 1072------------------------- 1073 1074Synopsis 1075........ 1076 1077 -var-delete [ -c ] NAME 1078 1079 Deletes a previously created variable object and all of its children. 1080With the `-c' option, just deletes the children. 1081 1082 Returns an error if the object NAME is not found. 1083 1084The `-var-set-format' Command 1085----------------------------- 1086 1087Synopsis 1088........ 1089 1090 -var-set-format NAME FORMAT-SPEC 1091 1092 Sets the output format for the value of the object NAME to be 1093FORMAT-SPEC. 1094 1095 The syntax for the FORMAT-SPEC is as follows: 1096 1097 FORMAT-SPEC ==> 1098 {binary | decimal | hexadecimal | octal | natural} 1099 1100 The natural format is the default format choosen automatically based 1101on the variable type (like decimal for an `int', hex for pointers, 1102etc.). 1103 1104 For a variable with children, the format is set only on the variable 1105itself, and the children are not affected. 1106 1107The `-var-show-format' Command 1108------------------------------ 1109 1110Synopsis 1111........ 1112 1113 -var-show-format NAME 1114 1115 Returns the format used to display the value of the object NAME. 1116 1117 FORMAT ==> 1118 FORMAT-SPEC 1119 1120The `-var-info-num-children' Command 1121------------------------------------ 1122 1123Synopsis 1124........ 1125 1126 -var-info-num-children NAME 1127 1128 Returns the number of children of a variable object NAME: 1129 1130 numchild=N 1131 1132 Note that this number is not completely reliable for a dynamic 1133varobj. It will return the current number of children, but more 1134children may be available. 1135 1136The `-var-list-children' Command 1137-------------------------------- 1138 1139Synopsis 1140........ 1141 1142 -var-list-children [PRINT-VALUES] NAME [FROM TO] 1143 1144 Return a list of the children of the specified variable object and 1145create variable objects for them, if they do not already exist. With a 1146single argument or if PRINT-VALUES has a value of 0 or `--no-values', 1147print only the names of the variables; if PRINT-VALUES is 1 or 1148`--all-values', also print their values; and if it is 2 or 1149`--simple-values' print the name and value for simple data types and 1150just the name for arrays, structures and unions. 1151 1152 FROM and TO, if specified, indicate the range of children to report. 1153If FROM or TO is less than zero, the range is reset and all children 1154will be reported. Otherwise, children starting at FROM (zero-based) 1155and up to and excluding TO will be reported. 1156 1157 If a child range is requested, it will only affect the current call 1158to `-var-list-children', but not future calls to `-var-update'. For 1159this, you must instead use `-var-set-update-range'. The intent of this 1160approach is to enable a front end to implement any update approach it 1161likes; for example, scrolling a view may cause the front end to request 1162more children with `-var-list-children', and then the front end could 1163call `-var-set-update-range' with a different range to ensure that 1164future updates are restricted to just the visible items. 1165 1166 For each child the following results are returned: 1167 1168NAME 1169 Name of the variable object created for this child. 1170 1171EXP 1172 The expression to be shown to the user by the front end to 1173 designate this child. For example this may be the name of a 1174 structure member. 1175 1176 For a dynamic varobj, this value cannot be used to form an 1177 expression. There is no way to do this at all with a dynamic 1178 varobj. 1179 1180 For C/C++ structures there are several pseudo children returned to 1181 designate access qualifiers. For these pseudo children EXP is 1182 `public', `private', or `protected'. In this case the type and 1183 value are not present. 1184 1185 A dynamic varobj will not report the access qualifying 1186 pseudo-children, regardless of the language. This information is 1187 not available at all with a dynamic varobj. 1188 1189NUMCHILD 1190 Number of children this child has. For a dynamic varobj, this 1191 will be 0. 1192 1193TYPE 1194 The type of the child. 1195 1196VALUE 1197 If values were requested, this is the value. 1198 1199THREAD-ID 1200 If this variable object is associated with a thread, this is the 1201 thread id. Otherwise this result is not present. 1202 1203FROZEN 1204 If the variable object is frozen, this variable will be present 1205 with a value of 1. 1206 1207 The result may have its own attributes: 1208 1209`displayhint' 1210 A dynamic varobj can supply a display hint to the front end. The 1211 value comes directly from the Python pretty-printer object's 1212 `display_hint' method. *Note Pretty Printing API::. 1213 1214`has_more' 1215 This is an integer attribute which is nonzero if there are children 1216 remaining after the end of the selected range. 1217 1218Example 1219....... 1220 1221 (gdb) 1222 -var-list-children n 1223 ^done,numchild=N,children=[child={name=NAME,exp=EXP, 1224 numchild=N,type=TYPE},(repeats N times)] 1225 (gdb) 1226 -var-list-children --all-values n 1227 ^done,numchild=N,children=[child={name=NAME,exp=EXP, 1228 numchild=N,value=VALUE,type=TYPE},(repeats N times)] 1229 1230The `-var-info-type' Command 1231---------------------------- 1232 1233Synopsis 1234........ 1235 1236 -var-info-type NAME 1237 1238 Returns the type of the specified variable NAME. The type is 1239returned as a string in the same format as it is output by the GDB CLI: 1240 1241 type=TYPENAME 1242 1243The `-var-info-expression' Command 1244---------------------------------- 1245 1246Synopsis 1247........ 1248 1249 -var-info-expression NAME 1250 1251 Returns a string that is suitable for presenting this variable 1252object in user interface. The string is generally not valid expression 1253in the current language, and cannot be evaluated. 1254 1255 For example, if `a' is an array, and variable object `A' was created 1256for `a', then we'll get this output: 1257 1258 (gdb) -var-info-expression A.1 1259 ^done,lang="C",exp="1" 1260 1261Here, the values of `lang' can be `{"C" | "C++" | "Java"}'. 1262 1263 Note that the output of the `-var-list-children' command also 1264includes those expressions, so the `-var-info-expression' command is of 1265limited use. 1266 1267The `-var-info-path-expression' Command 1268--------------------------------------- 1269 1270Synopsis 1271........ 1272 1273 -var-info-path-expression NAME 1274 1275 Returns an expression that can be evaluated in the current context 1276and will yield the same value that a variable object has. Compare this 1277with the `-var-info-expression' command, which result can be used only 1278for UI presentation. Typical use of the `-var-info-path-expression' 1279command is creating a watchpoint from a variable object. 1280 1281 This command is currently not valid for children of a dynamic varobj, 1282and will give an error when invoked on one. 1283 1284 For example, suppose `C' is a C++ class, derived from class `Base', 1285and that the `Base' class has a member called `m_size'. Assume a 1286variable `c' is has the type of `C' and a variable object `C' was 1287created for variable `c'. Then, we'll get this output: 1288 (gdb) -var-info-path-expression C.Base.public.m_size 1289 ^done,path_expr=((Base)c).m_size) 1290 1291The `-var-show-attributes' Command 1292---------------------------------- 1293 1294Synopsis 1295........ 1296 1297 -var-show-attributes NAME 1298 1299 List attributes of the specified variable object NAME: 1300 1301 status=ATTR [ ( ,ATTR )* ] 1302 1303where ATTR is `{ { editable | noneditable } | TBD }'. 1304 1305The `-var-evaluate-expression' Command 1306-------------------------------------- 1307 1308Synopsis 1309........ 1310 1311 -var-evaluate-expression [-f FORMAT-SPEC] NAME 1312 1313 Evaluates the expression that is represented by the specified 1314variable object and returns its value as a string. The format of the 1315string can be specified with the `-f' option. The possible values of 1316this option are the same as for `-var-set-format' (*note 1317-var-set-format::). If the `-f' option is not specified, the current 1318display format will be used. The current display format can be changed 1319using the `-var-set-format' command. 1320 1321 value=VALUE 1322 1323 Note that one must invoke `-var-list-children' for a variable before 1324the value of a child variable can be evaluated. 1325 1326The `-var-assign' Command 1327------------------------- 1328 1329Synopsis 1330........ 1331 1332 -var-assign NAME EXPRESSION 1333 1334 Assigns the value of EXPRESSION to the variable object specified by 1335NAME. The object must be `editable'. If the variable's value is 1336altered by the assign, the variable will show up in any subsequent 1337`-var-update' list. 1338 1339Example 1340....... 1341 1342 (gdb) 1343 -var-assign var1 3 1344 ^done,value="3" 1345 (gdb) 1346 -var-update * 1347 ^done,changelist=[{name="var1",in_scope="true",type_changed="false"}] 1348 (gdb) 1349 1350The `-var-update' Command 1351------------------------- 1352 1353Synopsis 1354........ 1355 1356 -var-update [PRINT-VALUES] {NAME | "*"} 1357 1358 Reevaluate the expressions corresponding to the variable object NAME 1359and all its direct and indirect children, and return the list of 1360variable objects whose values have changed; NAME must be a root 1361variable object. Here, "changed" means that the result of 1362`-var-evaluate-expression' before and after the `-var-update' is 1363different. If `*' is used as the variable object names, all existing 1364variable objects are updated, except for frozen ones (*note 1365-var-set-frozen::). The option PRINT-VALUES determines whether both 1366names and values, or just names are printed. The possible values of 1367this option are the same as for `-var-list-children' (*note 1368-var-list-children::). It is recommended to use the `--all-values' 1369option, to reduce the number of MI commands needed on each program stop. 1370 1371 With the `*' parameter, if a variable object is bound to a currently 1372running thread, it will not be updated, without any diagnostic. 1373 1374 If `-var-set-update-range' was previously used on a varobj, then 1375only the selected range of children will be reported. 1376 1377 `-var-update' reports all the changed varobjs in a tuple named 1378`changelist'. 1379 1380 Each item in the change list is itself a tuple holding: 1381 1382`name' 1383 The name of the varobj. 1384 1385`value' 1386 If values were requested for this update, then this field will be 1387 present and will hold the value of the varobj. 1388 1389`in_scope' 1390 This field is a string which may take one of three values: 1391 1392 `"true"' 1393 The variable object's current value is valid. 1394 1395 `"false"' 1396 The variable object does not currently hold a valid value but 1397 it may hold one in the future if its associated expression 1398 comes back into scope. 1399 1400 `"invalid"' 1401 The variable object no longer holds a valid value. This can 1402 occur when the executable file being debugged has changed, 1403 either through recompilation or by using the GDB `file' 1404 command. The front end should normally choose to delete 1405 these variable objects. 1406 1407 In the future new values may be added to this list so the front 1408 should be prepared for this possibility. *Note GDB/MI Development 1409 and Front Ends: GDB/MI Development and Front Ends. 1410 1411`type_changed' 1412 This is only present if the varobj is still valid. If the type 1413 changed, then this will be the string `true'; otherwise it will be 1414 `false'. 1415 1416`new_type' 1417 If the varobj's type changed, then this field will be present and 1418 will hold the new type. 1419 1420`new_num_children' 1421 For a dynamic varobj, if the number of children changed, or if the 1422 type changed, this will be the new number of children. 1423 1424 The `numchild' field in other varobj responses is generally not 1425 valid for a dynamic varobj - it will show the number of children 1426 that GDB knows about, but because dynamic varobjs lazily 1427 instantiate their children, this will not reflect the number of 1428 children which may be available. 1429 1430 The `new_num_children' attribute only reports changes to the 1431 number of children known by GDB. This is the only way to detect 1432 whether an update has removed children (which necessarily can only 1433 happen at the end of the update range). 1434 1435`displayhint' 1436 The display hint, if any. 1437 1438`has_more' 1439 This is an integer value, which will be 1 if there are more 1440 children available outside the varobj's update range. 1441 1442`dynamic' 1443 This attribute will be present and have the value `1' if the 1444 varobj is a dynamic varobj. If the varobj is not a dynamic varobj, 1445 then this attribute will not be present. 1446 1447`new_children' 1448 If new children were added to a dynamic varobj within the selected 1449 update range (as set by `-var-set-update-range'), then they will 1450 be listed in this attribute. 1451 1452Example 1453....... 1454 1455 (gdb) 1456 -var-assign var1 3 1457 ^done,value="3" 1458 (gdb) 1459 -var-update --all-values var1 1460 ^done,changelist=[{name="var1",value="3",in_scope="true", 1461 type_changed="false"}] 1462 (gdb) 1463 1464The `-var-set-frozen' Command 1465----------------------------- 1466 1467Synopsis 1468........ 1469 1470 -var-set-frozen NAME FLAG 1471 1472 Set the frozenness flag on the variable object NAME. The FLAG 1473parameter should be either `1' to make the variable frozen or `0' to 1474make it unfrozen. If a variable object is frozen, then neither itself, 1475nor any of its children, are implicitly updated by `-var-update' of a 1476parent variable or by `-var-update *'. Only `-var-update' of the 1477variable itself will update its value and values of its children. 1478After a variable object is unfrozen, it is implicitly updated by all 1479subsequent `-var-update' operations. Unfreezing a variable does not 1480update it, only subsequent `-var-update' does. 1481 1482Example 1483....... 1484 1485 (gdb) 1486 -var-set-frozen V 1 1487 ^done 1488 (gdb) 1489 1490The `-var-set-update-range' command 1491----------------------------------- 1492 1493Synopsis 1494........ 1495 1496 -var-set-update-range NAME FROM TO 1497 1498 Set the range of children to be returned by future invocations of 1499`-var-update'. 1500 1501 FROM and TO indicate the range of children to report. If FROM or TO 1502is less than zero, the range is reset and all children will be 1503reported. Otherwise, children starting at FROM (zero-based) and up to 1504and excluding TO will be reported. 1505 1506Example 1507....... 1508 1509 (gdb) 1510 -var-set-update-range V 1 2 1511 ^done 1512 1513The `-var-set-visualizer' command 1514--------------------------------- 1515 1516Synopsis 1517........ 1518 1519 -var-set-visualizer NAME VISUALIZER 1520 1521 Set a visualizer for the variable object NAME. 1522 1523 VISUALIZER is the visualizer to use. The special value `None' means 1524to disable any visualizer in use. 1525 1526 If not `None', VISUALIZER must be a Python expression. This 1527expression must evaluate to a callable object which accepts a single 1528argument. GDB will call this object with the value of the varobj NAME 1529as an argument (this is done so that the same Python pretty-printing 1530code can be used for both the CLI and MI). When called, this object 1531must return an object which conforms to the pretty-printing interface 1532(*note Pretty Printing API::). 1533 1534 The pre-defined function `gdb.default_visualizer' may be used to 1535select a visualizer by following the built-in process (*note Selecting 1536Pretty-Printers::). This is done automatically when a varobj is 1537created, and so ordinarily is not needed. 1538 1539 This feature is only available if Python support is enabled. The MI 1540command `-list-features' (*note GDB/MI Miscellaneous Commands::) can be 1541used to check this. 1542 1543Example 1544....... 1545 1546Resetting the visualizer: 1547 1548 (gdb) 1549 -var-set-visualizer V None 1550 ^done 1551 1552 Reselecting the default (type-based) visualizer: 1553 1554 (gdb) 1555 -var-set-visualizer V gdb.default_visualizer 1556 ^done 1557 1558 Suppose `SomeClass' is a visualizer class. A lambda expression can 1559be used to instantiate this class for a varobj: 1560 1561 (gdb) 1562 -var-set-visualizer V "lambda val: SomeClass()" 1563 ^done 1564 1565 1566File: gdb.info, Node: GDB/MI Data Manipulation, Next: GDB/MI Tracepoint Commands, Prev: GDB/MI Variable Objects, Up: GDB/MI 1567 156827.14 GDB/MI Data Manipulation 1569============================== 1570 1571This section describes the GDB/MI commands that manipulate data: 1572examine memory and registers, evaluate expressions, etc. 1573 1574The `-data-disassemble' Command 1575------------------------------- 1576 1577Synopsis 1578........ 1579 1580 -data-disassemble 1581 [ -s START-ADDR -e END-ADDR ] 1582 | [ -f FILENAME -l LINENUM [ -n LINES ] ] 1583 -- MODE 1584 1585Where: 1586 1587`START-ADDR' 1588 is the beginning address (or `$pc') 1589 1590`END-ADDR' 1591 is the end address 1592 1593`FILENAME' 1594 is the name of the file to disassemble 1595 1596`LINENUM' 1597 is the line number to disassemble around 1598 1599`LINES' 1600 is the number of disassembly lines to be produced. If it is -1, 1601 the whole function will be disassembled, in case no END-ADDR is 1602 specified. If END-ADDR is specified as a non-zero value, and 1603 LINES is lower than the number of disassembly lines between 1604 START-ADDR and END-ADDR, only LINES lines are displayed; if LINES 1605 is higher than the number of lines between START-ADDR and 1606 END-ADDR, only the lines up to END-ADDR are displayed. 1607 1608`MODE' 1609 is either 0 (meaning only disassembly), 1 (meaning mixed source and 1610 disassembly), 2 (meaning disassembly with raw opcodes), or 3 1611 (meaning mixed source and disassembly with raw opcodes). 1612 1613Result 1614...... 1615 1616The output for each instruction is composed of four fields: 1617 1618 * Address 1619 1620 * Func-name 1621 1622 * Offset 1623 1624 * Instruction 1625 1626 Note that whatever included in the instruction field, is not 1627manipulated directly by GDB/MI, i.e., it is not possible to adjust its 1628format. 1629 1630GDB Command 1631........... 1632 1633There's no direct mapping from this command to the CLI. 1634 1635Example 1636....... 1637 1638Disassemble from the current value of `$pc' to `$pc + 20': 1639 1640 (gdb) 1641 -data-disassemble -s $pc -e "$pc + 20" -- 0 1642 ^done, 1643 asm_insns=[ 1644 {address="0x000107c0",func-name="main",offset="4", 1645 inst="mov 2, %o0"}, 1646 {address="0x000107c4",func-name="main",offset="8", 1647 inst="sethi %hi(0x11800), %o2"}, 1648 {address="0x000107c8",func-name="main",offset="12", 1649 inst="or %o2, 0x140, %o1\t! 0x11940 <_lib_version+8>"}, 1650 {address="0x000107cc",func-name="main",offset="16", 1651 inst="sethi %hi(0x11800), %o2"}, 1652 {address="0x000107d0",func-name="main",offset="20", 1653 inst="or %o2, 0x168, %o4\t! 0x11968 <_lib_version+48>"}] 1654 (gdb) 1655 1656 Disassemble the whole `main' function. Line 32 is part of `main'. 1657 1658 -data-disassemble -f basics.c -l 32 -- 0 1659 ^done,asm_insns=[ 1660 {address="0x000107bc",func-name="main",offset="0", 1661 inst="save %sp, -112, %sp"}, 1662 {address="0x000107c0",func-name="main",offset="4", 1663 inst="mov 2, %o0"}, 1664 {address="0x000107c4",func-name="main",offset="8", 1665 inst="sethi %hi(0x11800), %o2"}, 1666 [...] 1667 {address="0x0001081c",func-name="main",offset="96",inst="ret "}, 1668 {address="0x00010820",func-name="main",offset="100",inst="restore "}] 1669 (gdb) 1670 1671 Disassemble 3 instructions from the start of `main': 1672 1673 (gdb) 1674 -data-disassemble -f basics.c -l 32 -n 3 -- 0 1675 ^done,asm_insns=[ 1676 {address="0x000107bc",func-name="main",offset="0", 1677 inst="save %sp, -112, %sp"}, 1678 {address="0x000107c0",func-name="main",offset="4", 1679 inst="mov 2, %o0"}, 1680 {address="0x000107c4",func-name="main",offset="8", 1681 inst="sethi %hi(0x11800), %o2"}] 1682 (gdb) 1683 1684 Disassemble 3 instructions from the start of `main' in mixed mode: 1685 1686 (gdb) 1687 -data-disassemble -f basics.c -l 32 -n 3 -- 1 1688 ^done,asm_insns=[ 1689 src_and_asm_line={line="31", 1690 file="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb/ \ 1691 testsuite/gdb.mi/basics.c",line_asm_insn=[ 1692 {address="0x000107bc",func-name="main",offset="0", 1693 inst="save %sp, -112, %sp"}]}, 1694 src_and_asm_line={line="32", 1695 file="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb/ \ 1696 testsuite/gdb.mi/basics.c",line_asm_insn=[ 1697 {address="0x000107c0",func-name="main",offset="4", 1698 inst="mov 2, %o0"}, 1699 {address="0x000107c4",func-name="main",offset="8", 1700 inst="sethi %hi(0x11800), %o2"}]}] 1701 (gdb) 1702 1703The `-data-evaluate-expression' Command 1704--------------------------------------- 1705 1706Synopsis 1707........ 1708 1709 -data-evaluate-expression EXPR 1710 1711 Evaluate EXPR as an expression. The expression could contain an 1712inferior function call. The function call will execute synchronously. 1713If the expression contains spaces, it must be enclosed in double quotes. 1714 1715GDB Command 1716........... 1717 1718The corresponding GDB commands are `print', `output', and `call'. In 1719`gdbtk' only, there's a corresponding `gdb_eval' command. 1720 1721Example 1722....... 1723 1724In the following example, the numbers that precede the commands are the 1725"tokens" described in *Note GDB/MI Command Syntax: GDB/MI Command 1726Syntax. Notice how GDB/MI returns the same tokens in its output. 1727 1728 211-data-evaluate-expression A 1729 211^done,value="1" 1730 (gdb) 1731 311-data-evaluate-expression &A 1732 311^done,value="0xefffeb7c" 1733 (gdb) 1734 411-data-evaluate-expression A+3 1735 411^done,value="4" 1736 (gdb) 1737 511-data-evaluate-expression "A + 3" 1738 511^done,value="4" 1739 (gdb) 1740 1741The `-data-list-changed-registers' Command 1742------------------------------------------ 1743 1744Synopsis 1745........ 1746 1747 -data-list-changed-registers 1748 1749 Display a list of the registers that have changed. 1750 1751GDB Command 1752........... 1753 1754GDB doesn't have a direct analog for this command; `gdbtk' has the 1755corresponding command `gdb_changed_register_list'. 1756 1757Example 1758....... 1759 1760On a PPC MBX board: 1761 1762 (gdb) 1763 -exec-continue 1764 ^running 1765 1766 (gdb) 1767 *stopped,reason="breakpoint-hit",disp="keep",bkptno="1",frame={ 1768 func="main",args=[],file="try.c",fullname="/home/foo/bar/try.c", 1769 line="5"} 1770 (gdb) 1771 -data-list-changed-registers 1772 ^done,changed-registers=["0","1","2","4","5","6","7","8","9", 1773 "10","11","13","14","15","16","17","18","19","20","21","22","23", 1774 "24","25","26","27","28","30","31","64","65","66","67","69"] 1775 (gdb) 1776 1777The `-data-list-register-names' Command 1778--------------------------------------- 1779 1780Synopsis 1781........ 1782 1783 -data-list-register-names [ ( REGNO )+ ] 1784 1785 Show a list of register names for the current target. If no 1786arguments are given, it shows a list of the names of all the registers. 1787If integer numbers are given as arguments, it will print a list of the 1788names of the registers corresponding to the arguments. To ensure 1789consistency between a register name and its number, the output list may 1790include empty register names. 1791 1792GDB Command 1793........... 1794 1795GDB does not have a command which corresponds to 1796`-data-list-register-names'. In `gdbtk' there is a corresponding 1797command `gdb_regnames'. 1798 1799Example 1800....... 1801 1802For the PPC MBX board: 1803 (gdb) 1804 -data-list-register-names 1805 ^done,register-names=["r0","r1","r2","r3","r4","r5","r6","r7", 1806 "r8","r9","r10","r11","r12","r13","r14","r15","r16","r17","r18", 1807 "r19","r20","r21","r22","r23","r24","r25","r26","r27","r28","r29", 1808 "r30","r31","f0","f1","f2","f3","f4","f5","f6","f7","f8","f9", 1809 "f10","f11","f12","f13","f14","f15","f16","f17","f18","f19","f20", 1810 "f21","f22","f23","f24","f25","f26","f27","f28","f29","f30","f31", 1811 "", "pc","ps","cr","lr","ctr","xer"] 1812 (gdb) 1813 -data-list-register-names 1 2 3 1814 ^done,register-names=["r1","r2","r3"] 1815 (gdb) 1816 1817The `-data-list-register-values' Command 1818---------------------------------------- 1819 1820Synopsis 1821........ 1822 1823 -data-list-register-values FMT [ ( REGNO )*] 1824 1825 Display the registers' contents. FMT is the format according to 1826which the registers' contents are to be returned, followed by an 1827optional list of numbers specifying the registers to display. A 1828missing list of numbers indicates that the contents of all the 1829registers must be returned. 1830 1831 Allowed formats for FMT are: 1832 1833`x' 1834 Hexadecimal 1835 1836`o' 1837 Octal 1838 1839`t' 1840 Binary 1841 1842`d' 1843 Decimal 1844 1845`r' 1846 Raw 1847 1848`N' 1849 Natural 1850 1851GDB Command 1852........... 1853 1854The corresponding GDB commands are `info reg', `info all-reg', and (in 1855`gdbtk') `gdb_fetch_registers'. 1856 1857Example 1858....... 1859 1860For a PPC MBX board (note: line breaks are for readability only, they 1861don't appear in the actual output): 1862 1863 (gdb) 1864 -data-list-register-values r 64 65 1865 ^done,register-values=[{number="64",value="0xfe00a300"}, 1866 {number="65",value="0x00029002"}] 1867 (gdb) 1868 -data-list-register-values x 1869 ^done,register-values=[{number="0",value="0xfe0043c8"}, 1870 {number="1",value="0x3fff88"},{number="2",value="0xfffffffe"}, 1871 {number="3",value="0x0"},{number="4",value="0xa"}, 1872 {number="5",value="0x3fff68"},{number="6",value="0x3fff58"}, 1873 {number="7",value="0xfe011e98"},{number="8",value="0x2"}, 1874 {number="9",value="0xfa202820"},{number="10",value="0xfa202808"}, 1875 {number="11",value="0x1"},{number="12",value="0x0"}, 1876 {number="13",value="0x4544"},{number="14",value="0xffdfffff"}, 1877 {number="15",value="0xffffffff"},{number="16",value="0xfffffeff"}, 1878 {number="17",value="0xefffffed"},{number="18",value="0xfffffffe"}, 1879 {number="19",value="0xffffffff"},{number="20",value="0xffffffff"}, 1880 {number="21",value="0xffffffff"},{number="22",value="0xfffffff7"}, 1881 {number="23",value="0xffffffff"},{number="24",value="0xffffffff"}, 1882 {number="25",value="0xffffffff"},{number="26",value="0xfffffffb"}, 1883 {number="27",value="0xffffffff"},{number="28",value="0xf7bfffff"}, 1884 {number="29",value="0x0"},{number="30",value="0xfe010000"}, 1885 {number="31",value="0x0"},{number="32",value="0x0"}, 1886 {number="33",value="0x0"},{number="34",value="0x0"}, 1887 {number="35",value="0x0"},{number="36",value="0x0"}, 1888 {number="37",value="0x0"},{number="38",value="0x0"}, 1889 {number="39",value="0x0"},{number="40",value="0x0"}, 1890 {number="41",value="0x0"},{number="42",value="0x0"}, 1891 {number="43",value="0x0"},{number="44",value="0x0"}, 1892 {number="45",value="0x0"},{number="46",value="0x0"}, 1893 {number="47",value="0x0"},{number="48",value="0x0"}, 1894 {number="49",value="0x0"},{number="50",value="0x0"}, 1895 {number="51",value="0x0"},{number="52",value="0x0"}, 1896 {number="53",value="0x0"},{number="54",value="0x0"}, 1897 {number="55",value="0x0"},{number="56",value="0x0"}, 1898 {number="57",value="0x0"},{number="58",value="0x0"}, 1899 {number="59",value="0x0"},{number="60",value="0x0"}, 1900 {number="61",value="0x0"},{number="62",value="0x0"}, 1901 {number="63",value="0x0"},{number="64",value="0xfe00a300"}, 1902 {number="65",value="0x29002"},{number="66",value="0x202f04b5"}, 1903 {number="67",value="0xfe0043b0"},{number="68",value="0xfe00b3e4"}, 1904 {number="69",value="0x20002b03"}] 1905 (gdb) 1906 1907The `-data-read-memory' Command 1908------------------------------- 1909 1910This command is deprecated, use `-data-read-memory-bytes' instead. 1911 1912Synopsis 1913........ 1914 1915 -data-read-memory [ -o BYTE-OFFSET ] 1916 ADDRESS WORD-FORMAT WORD-SIZE 1917 NR-ROWS NR-COLS [ ASCHAR ] 1918 1919where: 1920 1921`ADDRESS' 1922 An expression specifying the address of the first memory word to be 1923 read. Complex expressions containing embedded white space should 1924 be quoted using the C convention. 1925 1926`WORD-FORMAT' 1927 The format to be used to print the memory words. The notation is 1928 the same as for GDB's `print' command (*note Output Formats: 1929 Output Formats.). 1930 1931`WORD-SIZE' 1932 The size of each memory word in bytes. 1933 1934`NR-ROWS' 1935 The number of rows in the output table. 1936 1937`NR-COLS' 1938 The number of columns in the output table. 1939 1940`ASCHAR' 1941 If present, indicates that each row should include an ASCII dump. 1942 The value of ASCHAR is used as a padding character when a byte is 1943 not a member of the printable ASCII character set (printable ASCII 1944 characters are those whose code is between 32 and 126, 1945 inclusively). 1946 1947`BYTE-OFFSET' 1948 An offset to add to the ADDRESS before fetching memory. 1949 1950 This command displays memory contents as a table of NR-ROWS by 1951NR-COLS words, each word being WORD-SIZE bytes. In total, `NR-ROWS * 1952NR-COLS * WORD-SIZE' bytes are read (returned as `total-bytes'). 1953Should less than the requested number of bytes be returned by the 1954target, the missing words are identified using `N/A'. The number of 1955bytes read from the target is returned in `nr-bytes' and the starting 1956address used to read memory in `addr'. 1957 1958 The address of the next/previous row or page is available in 1959`next-row' and `prev-row', `next-page' and `prev-page'. 1960 1961GDB Command 1962........... 1963 1964The corresponding GDB command is `x'. `gdbtk' has `gdb_get_mem' memory 1965read command. 1966 1967Example 1968....... 1969 1970Read six bytes of memory starting at `bytes+6' but then offset by `-6' 1971bytes. Format as three rows of two columns. One byte per word. 1972Display each word in hex. 1973 1974 (gdb) 1975 9-data-read-memory -o -6 -- bytes+6 x 1 3 2 1976 9^done,addr="0x00001390",nr-bytes="6",total-bytes="6", 1977 next-row="0x00001396",prev-row="0x0000138e",next-page="0x00001396", 1978 prev-page="0x0000138a",memory=[ 1979 {addr="0x00001390",data=["0x00","0x01"]}, 1980 {addr="0x00001392",data=["0x02","0x03"]}, 1981 {addr="0x00001394",data=["0x04","0x05"]}] 1982 (gdb) 1983 1984 Read two bytes of memory starting at address `shorts + 64' and 1985display as a single word formatted in decimal. 1986 1987 (gdb) 1988 5-data-read-memory shorts+64 d 2 1 1 1989 5^done,addr="0x00001510",nr-bytes="2",total-bytes="2", 1990 next-row="0x00001512",prev-row="0x0000150e", 1991 next-page="0x00001512",prev-page="0x0000150e",memory=[ 1992 {addr="0x00001510",data=["128"]}] 1993 (gdb) 1994 1995 Read thirty two bytes of memory starting at `bytes+16' and format as 1996eight rows of four columns. Include a string encoding with `x' used as 1997the non-printable character. 1998 1999 (gdb) 2000 4-data-read-memory bytes+16 x 1 8 4 x 2001 4^done,addr="0x000013a0",nr-bytes="32",total-bytes="32", 2002 next-row="0x000013c0",prev-row="0x0000139c", 2003 next-page="0x000013c0",prev-page="0x00001380",memory=[ 2004 {addr="0x000013a0",data=["0x10","0x11","0x12","0x13"],ascii="xxxx"}, 2005 {addr="0x000013a4",data=["0x14","0x15","0x16","0x17"],ascii="xxxx"}, 2006 {addr="0x000013a8",data=["0x18","0x19","0x1a","0x1b"],ascii="xxxx"}, 2007 {addr="0x000013ac",data=["0x1c","0x1d","0x1e","0x1f"],ascii="xxxx"}, 2008 {addr="0x000013b0",data=["0x20","0x21","0x22","0x23"],ascii=" !\"#"}, 2009 {addr="0x000013b4",data=["0x24","0x25","0x26","0x27"],ascii="$%&'"}, 2010 {addr="0x000013b8",data=["0x28","0x29","0x2a","0x2b"],ascii="()*+"}, 2011 {addr="0x000013bc",data=["0x2c","0x2d","0x2e","0x2f"],ascii=",-./"}] 2012 (gdb) 2013 2014The `-data-read-memory-bytes' Command 2015------------------------------------- 2016 2017Synopsis 2018........ 2019 2020 -data-read-memory-bytes [ -o BYTE-OFFSET ] 2021 ADDRESS COUNT 2022 2023where: 2024 2025`ADDRESS' 2026 An expression specifying the address of the first memory word to be 2027 read. Complex expressions containing embedded white space should 2028 be quoted using the C convention. 2029 2030`COUNT' 2031 The number of bytes to read. This should be an integer literal. 2032 2033`BYTE-OFFSET' 2034 The offsets in bytes relative to ADDRESS at which to start 2035 reading. This should be an integer literal. This option is 2036 provided so that a frontend is not required to first evaluate 2037 address and then perform address arithmetics itself. 2038 2039 2040 This command attempts to read all accessible memory regions in the 2041specified range. First, all regions marked as unreadable in the memory 2042map (if one is defined) will be skipped. *Note Memory Region 2043Attributes::. Second, GDB will attempt to read the remaining regions. 2044For each one, if reading full region results in an errors, GDB will try 2045to read a subset of the region. 2046 2047 In general, every single byte in the region may be readable or not, 2048and the only way to read every readable byte is to try a read at every 2049address, which is not practical. Therefore, GDB will attempt to read 2050all accessible bytes at either beginning or the end of the region, 2051using a binary division scheme. This heuristic works well for reading 2052accross a memory map boundary. Note that if a region has a readable 2053range that is neither at the beginning or the end, GDB will not read it. 2054 2055 The result record (*note GDB/MI Result Records::) that is output of 2056the command includes a field named `memory' whose content is a list of 2057tuples. Each tuple represent a successfully read memory block and has 2058the following fields: 2059 2060`begin' 2061 The start address of the memory block, as hexadecimal literal. 2062 2063`end' 2064 The end address of the memory block, as hexadecimal literal. 2065 2066`offset' 2067 The offset of the memory block, as hexadecimal literal, relative to 2068 the start address passed to `-data-read-memory-bytes'. 2069 2070`contents' 2071 The contents of the memory block, in hex. 2072 2073 2074GDB Command 2075........... 2076 2077The corresponding GDB command is `x'. 2078 2079Example 2080....... 2081 2082 (gdb) 2083 -data-read-memory-bytes &a 10 2084 ^done,memory=[{begin="0xbffff154",offset="0x00000000", 2085 end="0xbffff15e", 2086 contents="01000000020000000300"}] 2087 (gdb) 2088 2089The `-data-write-memory-bytes' Command 2090-------------------------------------- 2091 2092Synopsis 2093........ 2094 2095 -data-write-memory-bytes ADDRESS CONTENTS 2096 2097where: 2098 2099`ADDRESS' 2100 An expression specifying the address of the first memory word to be 2101 read. Complex expressions containing embedded white space should 2102 be quoted using the C convention. 2103 2104`CONTENTS' 2105 The hex-encoded bytes to write. 2106 2107 2108GDB Command 2109........... 2110 2111There's no corresponding GDB command. 2112 2113Example 2114....... 2115 2116 (gdb) 2117 -data-write-memory-bytes &a "aabbccdd" 2118 ^done 2119 (gdb) 2120 2121 2122File: gdb.info, Node: GDB/MI Tracepoint Commands, Next: GDB/MI Symbol Query, Prev: GDB/MI Data Manipulation, Up: GDB/MI 2123 212427.15 GDB/MI Tracepoint Commands 2125================================ 2126 2127The commands defined in this section implement MI support for 2128tracepoints. For detailed introduction, see *Note Tracepoints::. 2129 2130The `-trace-find' Command 2131------------------------- 2132 2133Synopsis 2134........ 2135 2136 -trace-find MODE [PARAMETERS...] 2137 2138 Find a trace frame using criteria defined by MODE and PARAMETERS. 2139The following table lists permissible modes and their parameters. For 2140details of operation, see *Note tfind::. 2141 2142`none' 2143 No parameters are required. Stops examining trace frames. 2144 2145`frame-number' 2146 An integer is required as parameter. Selects tracepoint frame with 2147 that index. 2148 2149`tracepoint-number' 2150 An integer is required as parameter. Finds next trace frame that 2151 corresponds to tracepoint with the specified number. 2152 2153`pc' 2154 An address is required as parameter. Finds next trace frame that 2155 corresponds to any tracepoint at the specified address. 2156 2157`pc-inside-range' 2158 Two addresses are required as parameters. Finds next trace frame 2159 that corresponds to a tracepoint at an address inside the 2160 specified range. Both bounds are considered to be inside the 2161 range. 2162 2163`pc-outside-range' 2164 Two addresses are required as parameters. Finds next trace frame 2165 that corresponds to a tracepoint at an address outside the 2166 specified range. Both bounds are considered to be inside the 2167 range. 2168 2169`line' 2170 Line specification is required as parameter. *Note Specify 2171 Location::. Finds next trace frame that corresponds to a 2172 tracepoint at the specified location. 2173 2174 2175 If `none' was passed as MODE, the response does not have fields. 2176Otherwise, the response may have the following fields: 2177 2178`found' 2179 This field has either `0' or `1' as the value, depending on 2180 whether a matching tracepoint was found. 2181 2182`traceframe' 2183 The index of the found traceframe. This field is present iff the 2184 `found' field has value of `1'. 2185 2186`tracepoint' 2187 The index of the found tracepoint. This field is present iff the 2188 `found' field has value of `1'. 2189 2190`frame' 2191 The information about the frame corresponding to the found trace 2192 frame. This field is present only if a trace frame was found. 2193 *Note GDB/MI Frame Information::, for description of this field. 2194 2195 2196GDB Command 2197........... 2198 2199The corresponding GDB command is `tfind'. 2200 2201-trace-define-variable 2202---------------------- 2203 2204Synopsis 2205........ 2206 2207 -trace-define-variable NAME [ VALUE ] 2208 2209 Create trace variable NAME if it does not exist. If VALUE is 2210specified, sets the initial value of the specified trace variable to 2211that value. Note that the NAME should start with the `$' character. 2212 2213GDB Command 2214........... 2215 2216The corresponding GDB command is `tvariable'. 2217 2218-trace-list-variables 2219--------------------- 2220 2221Synopsis 2222........ 2223 2224 -trace-list-variables 2225 2226 Return a table of all defined trace variables. Each element of the 2227table has the following fields: 2228 2229`name' 2230 The name of the trace variable. This field is always present. 2231 2232`initial' 2233 The initial value. This is a 64-bit signed integer. This field 2234 is always present. 2235 2236`current' 2237 The value the trace variable has at the moment. This is a 64-bit 2238 signed integer. This field is absent iff current value is not 2239 defined, for example if the trace was never run, or is presently 2240 running. 2241 2242 2243GDB Command 2244........... 2245 2246The corresponding GDB command is `tvariables'. 2247 2248Example 2249....... 2250 2251 (gdb) 2252 -trace-list-variables 2253 ^done,trace-variables={nr_rows="1",nr_cols="3", 2254 hdr=[{width="15",alignment="-1",col_name="name",colhdr="Name"}, 2255 {width="11",alignment="-1",col_name="initial",colhdr="Initial"}, 2256 {width="11",alignment="-1",col_name="current",colhdr="Current"}], 2257 body=[variable={name="$trace_timestamp",initial="0"} 2258 variable={name="$foo",initial="10",current="15"}]} 2259 (gdb) 2260 2261-trace-save 2262----------- 2263 2264Synopsis 2265........ 2266 2267 -trace-save [-r ] FILENAME 2268 2269 Saves the collected trace data to FILENAME. Without the `-r' 2270option, the data is downloaded from the target and saved in a local 2271file. With the `-r' option the target is asked to perform the save. 2272 2273GDB Command 2274........... 2275 2276The corresponding GDB command is `tsave'. 2277 2278-trace-start 2279------------ 2280 2281Synopsis 2282........ 2283 2284 -trace-start 2285 2286 Starts a tracing experiments. The result of this command does not 2287have any fields. 2288 2289GDB Command 2290........... 2291 2292The corresponding GDB command is `tstart'. 2293 2294-trace-status 2295------------- 2296 2297Synopsis 2298........ 2299 2300 -trace-status 2301 2302 Obtains the status of a tracing experiment. The result may include 2303the following fields: 2304 2305`supported' 2306 May have a value of either `0', when no tracing operations are 2307 supported, `1', when all tracing operations are supported, or 2308 `file' when examining trace file. In the latter case, examining 2309 of trace frame is possible but new tracing experiement cannot be 2310 started. This field is always present. 2311 2312`running' 2313 May have a value of either `0' or `1' depending on whether tracing 2314 experiement is in progress on target. This field is present if 2315 `supported' field is not `0'. 2316 2317`stop-reason' 2318 Report the reason why the tracing was stopped last time. This 2319 field may be absent iff tracing was never stopped on target yet. 2320 The value of `request' means the tracing was stopped as result of 2321 the `-trace-stop' command. The value of `overflow' means the 2322 tracing buffer is full. The value of `disconnection' means 2323 tracing was automatically stopped when GDB has disconnected. The 2324 value of `passcount' means tracing was stopped when a tracepoint 2325 was passed a maximal number of times for that tracepoint. This 2326 field is present if `supported' field is not `0'. 2327 2328`stopping-tracepoint' 2329 The number of tracepoint whose passcount as exceeded. This field 2330 is present iff the `stop-reason' field has the value of 2331 `passcount'. 2332 2333`frames' 2334`frames-created' 2335 The `frames' field is a count of the total number of trace frames 2336 in the trace buffer, while `frames-created' is the total created 2337 during the run, including ones that were discarded, such as when a 2338 circular trace buffer filled up. Both fields are optional. 2339 2340`buffer-size' 2341`buffer-free' 2342 These fields tell the current size of the tracing buffer and the 2343 remaining space. These fields are optional. 2344 2345`circular' 2346 The value of the circular trace buffer flag. `1' means that the 2347 trace buffer is circular and old trace frames will be discarded if 2348 necessary to make room, `0' means that the trace buffer is linear 2349 and may fill up. 2350 2351`disconnected' 2352 The value of the disconnected tracing flag. `1' means that 2353 tracing will continue after GDB disconnects, `0' means that the 2354 trace run will stop. 2355 2356 2357GDB Command 2358........... 2359 2360The corresponding GDB command is `tstatus'. 2361 2362-trace-stop 2363----------- 2364 2365Synopsis 2366........ 2367 2368 -trace-stop 2369 2370 Stops a tracing experiment. The result of this command has the same 2371fields as `-trace-status', except that the `supported' and `running' 2372fields are not output. 2373 2374GDB Command 2375........... 2376 2377The corresponding GDB command is `tstop'. 2378 2379 2380File: gdb.info, Node: GDB/MI Symbol Query, Next: GDB/MI File Commands, Prev: GDB/MI Tracepoint Commands, Up: GDB/MI 2381 238227.16 GDB/MI Symbol Query Commands 2383================================== 2384 2385The `-symbol-list-lines' Command 2386-------------------------------- 2387 2388Synopsis 2389........ 2390 2391 -symbol-list-lines FILENAME 2392 2393 Print the list of lines that contain code and their associated 2394program addresses for the given source filename. The entries are 2395sorted in ascending PC order. 2396 2397GDB Command 2398........... 2399 2400There is no corresponding GDB command. 2401 2402Example 2403....... 2404 2405 (gdb) 2406 -symbol-list-lines basics.c 2407 ^done,lines=[{pc="0x08048554",line="7"},{pc="0x0804855a",line="8"}] 2408 (gdb) 2409 2410 2411File: gdb.info, Node: GDB/MI File Commands, Next: GDB/MI Target Manipulation, Prev: GDB/MI Symbol Query, Up: GDB/MI 2412 241327.17 GDB/MI File Commands 2414========================== 2415 2416This section describes the GDB/MI commands to specify executable file 2417names and to read in and obtain symbol table information. 2418 2419The `-file-exec-and-symbols' Command 2420------------------------------------ 2421 2422Synopsis 2423........ 2424 2425 -file-exec-and-symbols FILE 2426 2427 Specify the executable file to be debugged. This file is the one 2428from which the symbol table is also read. If no file is specified, the 2429command clears the executable and symbol information. If breakpoints 2430are set when using this command with no arguments, GDB will produce 2431error messages. Otherwise, no output is produced, except a completion 2432notification. 2433 2434GDB Command 2435........... 2436 2437The corresponding GDB command is `file'. 2438 2439Example 2440....... 2441 2442 (gdb) 2443 -file-exec-and-symbols /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx 2444 ^done 2445 (gdb) 2446 2447The `-file-exec-file' Command 2448----------------------------- 2449 2450Synopsis 2451........ 2452 2453 -file-exec-file FILE 2454 2455 Specify the executable file to be debugged. Unlike 2456`-file-exec-and-symbols', the symbol table is _not_ read from this 2457file. If used without argument, GDB clears the information about the 2458executable file. No output is produced, except a completion 2459notification. 2460 2461GDB Command 2462........... 2463 2464The corresponding GDB command is `exec-file'. 2465 2466Example 2467....... 2468 2469 (gdb) 2470 -file-exec-file /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx 2471 ^done 2472 (gdb) 2473 2474The `-file-list-exec-source-file' Command 2475----------------------------------------- 2476 2477Synopsis 2478........ 2479 2480 -file-list-exec-source-file 2481 2482 List the line number, the current source file, and the absolute path 2483to the current source file for the current executable. The macro 2484information field has a value of `1' or `0' depending on whether or not 2485the file includes preprocessor macro information. 2486 2487GDB Command 2488........... 2489 2490The GDB equivalent is `info source' 2491 2492Example 2493....... 2494 2495 (gdb) 2496 123-file-list-exec-source-file 2497 123^done,line="1",file="foo.c",fullname="/home/bar/foo.c,macro-info="1" 2498 (gdb) 2499 2500The `-file-list-exec-source-files' Command 2501------------------------------------------ 2502 2503Synopsis 2504........ 2505 2506 -file-list-exec-source-files 2507 2508 List the source files for the current executable. 2509 2510 It will always output the filename, but only when GDB can find the 2511absolute file name of a source file, will it output the fullname. 2512 2513GDB Command 2514........... 2515 2516The GDB equivalent is `info sources'. `gdbtk' has an analogous command 2517`gdb_listfiles'. 2518 2519Example 2520....... 2521 2522 (gdb) 2523 -file-list-exec-source-files 2524 ^done,files=[ 2525 {file=foo.c,fullname=/home/foo.c}, 2526 {file=/home/bar.c,fullname=/home/bar.c}, 2527 {file=gdb_could_not_find_fullpath.c}] 2528 (gdb) 2529 2530The `-file-symbol-file' Command 2531------------------------------- 2532 2533Synopsis 2534........ 2535 2536 -file-symbol-file FILE 2537 2538 Read symbol table info from the specified FILE argument. When used 2539without arguments, clears GDB's symbol table info. No output is 2540produced, except for a completion notification. 2541 2542GDB Command 2543........... 2544 2545The corresponding GDB command is `symbol-file'. 2546 2547Example 2548....... 2549 2550 (gdb) 2551 -file-symbol-file /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx 2552 ^done 2553 (gdb) 2554 2555 2556File: gdb.info, Node: GDB/MI Target Manipulation, Next: GDB/MI File Transfer Commands, Prev: GDB/MI File Commands, Up: GDB/MI 2557 255827.18 GDB/MI Target Manipulation Commands 2559========================================= 2560 2561The `-target-attach' Command 2562---------------------------- 2563 2564Synopsis 2565........ 2566 2567 -target-attach PID | GID | FILE 2568 2569 Attach to a process PID or a file FILE outside of GDB, or a thread 2570group GID. If attaching to a thread group, the id previously returned 2571by `-list-thread-groups --available' must be used. 2572 2573GDB Command 2574........... 2575 2576The corresponding GDB command is `attach'. 2577 2578Example 2579....... 2580 2581 (gdb) 2582 -target-attach 34 2583 =thread-created,id="1" 2584 *stopped,thread-id="1",frame={addr="0xb7f7e410",func="bar",args=[]} 2585 ^done 2586 (gdb) 2587 2588The `-target-detach' Command 2589---------------------------- 2590 2591Synopsis 2592........ 2593 2594 -target-detach [ PID | GID ] 2595 2596 Detach from the remote target which normally resumes its execution. 2597If either PID or GID is specified, detaches from either the specified 2598process, or specified thread group. There's no output. 2599 2600GDB Command 2601........... 2602 2603The corresponding GDB command is `detach'. 2604 2605Example 2606....... 2607 2608 (gdb) 2609 -target-detach 2610 ^done 2611 (gdb) 2612 2613The `-target-disconnect' Command 2614-------------------------------- 2615 2616Synopsis 2617........ 2618 2619 -target-disconnect 2620 2621 Disconnect from the remote target. There's no output and the target 2622is generally not resumed. 2623 2624GDB Command 2625........... 2626 2627The corresponding GDB command is `disconnect'. 2628 2629Example 2630....... 2631 2632 (gdb) 2633 -target-disconnect 2634 ^done 2635 (gdb) 2636 2637The `-target-download' Command 2638------------------------------ 2639 2640Synopsis 2641........ 2642 2643 -target-download 2644 2645 Loads the executable onto the remote target. It prints out an 2646update message every half second, which includes the fields: 2647 2648`section' 2649 The name of the section. 2650 2651`section-sent' 2652 The size of what has been sent so far for that section. 2653 2654`section-size' 2655 The size of the section. 2656 2657`total-sent' 2658 The total size of what was sent so far (the current and the 2659 previous sections). 2660 2661`total-size' 2662 The size of the overall executable to download. 2663 2664Each message is sent as status record (*note GDB/MI Output Syntax: 2665GDB/MI Output Syntax.). 2666 2667 In addition, it prints the name and size of the sections, as they are 2668downloaded. These messages include the following fields: 2669 2670`section' 2671 The name of the section. 2672 2673`section-size' 2674 The size of the section. 2675 2676`total-size' 2677 The size of the overall executable to download. 2678 2679At the end, a summary is printed. 2680 2681GDB Command 2682........... 2683 2684The corresponding GDB command is `load'. 2685 2686Example 2687....... 2688 2689Note: each status message appears on a single line. Here the messages 2690have been broken down so that they can fit onto a page. 2691 2692 (gdb) 2693 -target-download 2694 +download,{section=".text",section-size="6668",total-size="9880"} 2695 +download,{section=".text",section-sent="512",section-size="6668", 2696 total-sent="512",total-size="9880"} 2697 +download,{section=".text",section-sent="1024",section-size="6668", 2698 total-sent="1024",total-size="9880"} 2699 +download,{section=".text",section-sent="1536",section-size="6668", 2700 total-sent="1536",total-size="9880"} 2701 +download,{section=".text",section-sent="2048",section-size="6668", 2702 total-sent="2048",total-size="9880"} 2703 +download,{section=".text",section-sent="2560",section-size="6668", 2704 total-sent="2560",total-size="9880"} 2705 +download,{section=".text",section-sent="3072",section-size="6668", 2706 total-sent="3072",total-size="9880"} 2707 +download,{section=".text",section-sent="3584",section-size="6668", 2708 total-sent="3584",total-size="9880"} 2709 +download,{section=".text",section-sent="4096",section-size="6668", 2710 total-sent="4096",total-size="9880"} 2711 +download,{section=".text",section-sent="4608",section-size="6668", 2712 total-sent="4608",total-size="9880"} 2713 +download,{section=".text",section-sent="5120",section-size="6668", 2714 total-sent="5120",total-size="9880"} 2715 +download,{section=".text",section-sent="5632",section-size="6668", 2716 total-sent="5632",total-size="9880"} 2717 +download,{section=".text",section-sent="6144",section-size="6668", 2718 total-sent="6144",total-size="9880"} 2719 +download,{section=".text",section-sent="6656",section-size="6668", 2720 total-sent="6656",total-size="9880"} 2721 +download,{section=".init",section-size="28",total-size="9880"} 2722 +download,{section=".fini",section-size="28",total-size="9880"} 2723 +download,{section=".data",section-size="3156",total-size="9880"} 2724 +download,{section=".data",section-sent="512",section-size="3156", 2725 total-sent="7236",total-size="9880"} 2726 +download,{section=".data",section-sent="1024",section-size="3156", 2727 total-sent="7748",total-size="9880"} 2728 +download,{section=".data",section-sent="1536",section-size="3156", 2729 total-sent="8260",total-size="9880"} 2730 +download,{section=".data",section-sent="2048",section-size="3156", 2731 total-sent="8772",total-size="9880"} 2732 +download,{section=".data",section-sent="2560",section-size="3156", 2733 total-sent="9284",total-size="9880"} 2734 +download,{section=".data",section-sent="3072",section-size="3156", 2735 total-sent="9796",total-size="9880"} 2736 ^done,address="0x10004",load-size="9880",transfer-rate="6586", 2737 write-rate="429" 2738 (gdb) 2739 2740GDB Command 2741........... 2742 2743No equivalent. 2744 2745Example 2746....... 2747 2748N.A. 2749 2750The `-target-select' Command 2751---------------------------- 2752 2753Synopsis 2754........ 2755 2756 -target-select TYPE PARAMETERS ... 2757 2758 Connect GDB to the remote target. This command takes two args: 2759 2760`TYPE' 2761 The type of target, for instance `remote', etc. 2762 2763`PARAMETERS' 2764 Device names, host names and the like. *Note Commands for 2765 Managing Targets: Target Commands, for more details. 2766 2767 The output is a connection notification, followed by the address at 2768which the target program is, in the following form: 2769 2770 ^connected,addr="ADDRESS",func="FUNCTION NAME", 2771 args=[ARG LIST] 2772 2773GDB Command 2774........... 2775 2776The corresponding GDB command is `target'. 2777 2778Example 2779....... 2780 2781 (gdb) 2782 -target-select remote /dev/ttya 2783 ^connected,addr="0xfe00a300",func="??",args=[] 2784 (gdb) 2785 2786 2787File: gdb.info, Node: GDB/MI File Transfer Commands, Next: GDB/MI Miscellaneous Commands, Prev: GDB/MI Target Manipulation, Up: GDB/MI 2788 278927.19 GDB/MI File Transfer Commands 2790=================================== 2791 2792The `-target-file-put' Command 2793------------------------------ 2794 2795Synopsis 2796........ 2797 2798 -target-file-put HOSTFILE TARGETFILE 2799 2800 Copy file HOSTFILE from the host system (the machine running GDB) to 2801TARGETFILE on the target system. 2802 2803GDB Command 2804........... 2805 2806The corresponding GDB command is `remote put'. 2807 2808Example 2809....... 2810 2811 (gdb) 2812 -target-file-put localfile remotefile 2813 ^done 2814 (gdb) 2815 2816The `-target-file-get' Command 2817------------------------------ 2818 2819Synopsis 2820........ 2821 2822 -target-file-get TARGETFILE HOSTFILE 2823 2824 Copy file TARGETFILE from the target system to HOSTFILE on the host 2825system. 2826 2827GDB Command 2828........... 2829 2830The corresponding GDB command is `remote get'. 2831 2832Example 2833....... 2834 2835 (gdb) 2836 -target-file-get remotefile localfile 2837 ^done 2838 (gdb) 2839 2840The `-target-file-delete' Command 2841--------------------------------- 2842 2843Synopsis 2844........ 2845 2846 -target-file-delete TARGETFILE 2847 2848 Delete TARGETFILE from the target system. 2849 2850GDB Command 2851........... 2852 2853The corresponding GDB command is `remote delete'. 2854 2855Example 2856....... 2857 2858 (gdb) 2859 -target-file-delete remotefile 2860 ^done 2861 (gdb) 2862 2863 2864File: gdb.info, Node: GDB/MI Miscellaneous Commands, Prev: GDB/MI File Transfer Commands, Up: GDB/MI 2865 286627.20 Miscellaneous GDB/MI Commands 2867=================================== 2868 2869The `-gdb-exit' Command 2870----------------------- 2871 2872Synopsis 2873........ 2874 2875 -gdb-exit 2876 2877 Exit GDB immediately. 2878 2879GDB Command 2880........... 2881 2882Approximately corresponds to `quit'. 2883 2884Example 2885....... 2886 2887 (gdb) 2888 -gdb-exit 2889 ^exit 2890 2891The `-gdb-set' Command 2892---------------------- 2893 2894Synopsis 2895........ 2896 2897 -gdb-set 2898 2899 Set an internal GDB variable. 2900 2901GDB Command 2902........... 2903 2904The corresponding GDB command is `set'. 2905 2906Example 2907....... 2908 2909 (gdb) 2910 -gdb-set $foo=3 2911 ^done 2912 (gdb) 2913 2914The `-gdb-show' Command 2915----------------------- 2916 2917Synopsis 2918........ 2919 2920 -gdb-show 2921 2922 Show the current value of a GDB variable. 2923 2924GDB Command 2925........... 2926 2927The corresponding GDB command is `show'. 2928 2929Example 2930....... 2931 2932 (gdb) 2933 -gdb-show annotate 2934 ^done,value="0" 2935 (gdb) 2936 2937The `-gdb-version' Command 2938-------------------------- 2939 2940Synopsis 2941........ 2942 2943 -gdb-version 2944 2945 Show version information for GDB. Used mostly in testing. 2946 2947GDB Command 2948........... 2949 2950The GDB equivalent is `show version'. GDB by default shows this 2951information when you start an interactive session. 2952 2953Example 2954....... 2955 2956 (gdb) 2957 -gdb-version 2958 ~GNU gdb 5.2.1 2959 ~Copyright 2000 Free Software Foundation, Inc. 2960 ~GDB is free software, covered by the GNU General Public License, and 2961 ~you are welcome to change it and/or distribute copies of it under 2962 ~ certain conditions. 2963 ~Type "show copying" to see the conditions. 2964 ~There is absolutely no warranty for GDB. Type "show warranty" for 2965 ~ details. 2966 ~This GDB was configured as 2967 "--host=sparc-sun-solaris2.5.1 --target=ppc-eabi". 2968 ^done 2969 (gdb) 2970 2971The `-list-features' Command 2972---------------------------- 2973 2974Returns a list of particular features of the MI protocol that this 2975version of gdb implements. A feature can be a command, or a new field 2976in an output of some command, or even an important bugfix. While a 2977frontend can sometimes detect presence of a feature at runtime, it is 2978easier to perform detection at debugger startup. 2979 2980 The command returns a list of strings, with each string naming an 2981available feature. Each returned string is just a name, it does not 2982have any internal structure. The list of possible feature names is 2983given below. 2984 2985 Example output: 2986 2987 (gdb) -list-features 2988 ^done,result=["feature1","feature2"] 2989 2990 The current list of features is: 2991 2992`frozen-varobjs' 2993 Indicates presence of the `-var-set-frozen' command, as well as 2994 possible presense of the `frozen' field in the output of 2995 `-varobj-create'. 2996 2997`pending-breakpoints' 2998 Indicates presence of the `-f' option to the `-break-insert' 2999 command. 3000 3001`python' 3002 Indicates presence of Python scripting support, Python-based 3003 pretty-printing commands, and possible presence of the 3004 `display_hint' field in the output of `-var-list-children' 3005 3006`thread-info' 3007 Indicates presence of the `-thread-info' command. 3008 3009`data-read-memory-bytes' 3010 Indicates presense of the `-data-read-memory-bytes' and the 3011 `-data-write-memory-bytes' commands. 3012 3013 3014The `-list-target-features' Command 3015----------------------------------- 3016 3017Returns a list of particular features that are supported by the target. 3018Those features affect the permitted MI commands, but unlike the 3019features reported by the `-list-features' command, the features depend 3020on which target GDB is using at the moment. Whenever a target can 3021change, due to commands such as `-target-select', `-target-attach' or 3022`-exec-run', the list of target features may change, and the frontend 3023should obtain it again. Example output: 3024 3025 (gdb) -list-features 3026 ^done,result=["async"] 3027 3028 The current list of features is: 3029 3030`async' 3031 Indicates that the target is capable of asynchronous command 3032 execution, which means that GDB will accept further commands while 3033 the target is running. 3034 3035`reverse' 3036 Indicates that the target is capable of reverse execution. *Note 3037 Reverse Execution::, for more information. 3038 3039 3040The `-list-thread-groups' Command 3041--------------------------------- 3042 3043Synopsis 3044-------- 3045 3046 -list-thread-groups [ --available ] [ --recurse 1 ] [ GROUP ... ] 3047 3048 Lists thread groups (*note Thread groups::). When a single thread 3049group is passed as the argument, lists the children of that group. 3050When several thread group are passed, lists information about those 3051thread groups. Without any parameters, lists information about all 3052top-level thread groups. 3053 3054 Normally, thread groups that are being debugged are reported. With 3055the `--available' option, GDB reports thread groups available on the 3056target. 3057 3058 The output of this command may have either a `threads' result or a 3059`groups' result. The `thread' result has a list of tuples as value, 3060with each tuple describing a thread (*note GDB/MI Thread 3061Information::). The `groups' result has a list of tuples as value, 3062each tuple describing a thread group. If top-level groups are 3063requested (that is, no parameter is passed), or when several groups are 3064passed, the output always has a `groups' result. The format of the 3065`group' result is described below. 3066 3067 To reduce the number of roundtrips it's possible to list thread 3068groups together with their children, by passing the `--recurse' option 3069and the recursion depth. Presently, only recursion depth of 1 is 3070permitted. If this option is present, then every reported thread group 3071will also include its children, either as `group' or `threads' field. 3072 3073 In general, any combination of option and parameters is permitted, 3074with the following caveats: 3075 3076 * When a single thread group is passed, the output will typically be 3077 the `threads' result. Because threads may not contain anything, 3078 the `recurse' option will be ignored. 3079 3080 * When the `--available' option is passed, limited information may 3081 be available. In particular, the list of threads of a process 3082 might be inaccessible. Further, specifying specific thread groups 3083 might not give any performance advantage over listing all thread 3084 groups. The frontend should assume that `-list-thread-groups 3085 --available' is always an expensive operation and cache the 3086 results. 3087 3088 3089 The `groups' result is a list of tuples, where each tuple may have 3090the following fields: 3091 3092`id' 3093 Identifier of the thread group. This field is always present. 3094 The identifier is an opaque string; frontends should not try to 3095 convert it to an integer, even though it might look like one. 3096 3097`type' 3098 The type of the thread group. At present, only `process' is a 3099 valid type. 3100 3101`pid' 3102 The target-specific process identifier. This field is only present 3103 for thread groups of type `process' and only if the process exists. 3104 3105`num_children' 3106 The number of children this thread group has. This field may be 3107 absent for an available thread group. 3108 3109`threads' 3110 This field has a list of tuples as value, each tuple describing a 3111 thread. It may be present if the `--recurse' option is specified, 3112 and it's actually possible to obtain the threads. 3113 3114`cores' 3115 This field is a list of integers, each identifying a core that one 3116 thread of the group is running on. This field may be absent if 3117 such information is not available. 3118 3119`executable' 3120 The name of the executable file that corresponds to this thread 3121 group. The field is only present for thread groups of type 3122 `process', and only if there is a corresponding executable file. 3123 3124 3125Example 3126------- 3127 3128 gdb 3129 -list-thread-groups 3130 ^done,groups=[{id="17",type="process",pid="yyy",num_children="2"}] 3131 -list-thread-groups 17 3132 ^done,threads=[{id="2",target-id="Thread 0xb7e14b90 (LWP 21257)", 3133 frame={level="0",addr="0xffffe410",func="__kernel_vsyscall",args=[]},state="running"}, 3134 {id="1",target-id="Thread 0xb7e156b0 (LWP 21254)", 3135 frame={level="0",addr="0x0804891f",func="foo",args=[{name="i",value="10"}], 3136 file="/tmp/a.c",fullname="/tmp/a.c",line="158"},state="running"}]] 3137 -list-thread-groups --available 3138 ^done,groups=[{id="17",type="process",pid="yyy",num_children="2",cores=[1,2]}] 3139 -list-thread-groups --available --recurse 1 3140 ^done,groups=[{id="17", types="process",pid="yyy",num_children="2",cores=[1,2], 3141 threads=[{id="1",target-id="Thread 0xb7e14b90",cores=[1]}, 3142 {id="2",target-id="Thread 0xb7e14b90",cores=[2]}]},..] 3143 -list-thread-groups --available --recurse 1 17 18 3144 ^done,groups=[{id="17", types="process",pid="yyy",num_children="2",cores=[1,2], 3145 threads=[{id="1",target-id="Thread 0xb7e14b90",cores=[1]}, 3146 {id="2",target-id="Thread 0xb7e14b90",cores=[2]}]},...] 3147 3148The `-add-inferior' Command 3149--------------------------- 3150 3151Synopsis 3152-------- 3153 3154 -add-inferior 3155 3156 Creates a new inferior (*note Inferiors and Programs::). The created 3157inferior is not associated with any executable. Such association may 3158be established with the `-file-exec-and-symbols' command (*note GDB/MI 3159File Commands::). The command response has a single field, 3160`thread-group', whose value is the identifier of the thread group 3161corresponding to the new inferior. 3162 3163Example 3164------- 3165 3166 gdb 3167 -add-inferior 3168 ^done,thread-group="i3" 3169 3170The `-interpreter-exec' Command 3171------------------------------- 3172 3173Synopsis 3174-------- 3175 3176 -interpreter-exec INTERPRETER COMMAND 3177 3178 Execute the specified COMMAND in the given INTERPRETER. 3179 3180GDB Command 3181----------- 3182 3183The corresponding GDB command is `interpreter-exec'. 3184 3185Example 3186------- 3187 3188 (gdb) 3189 -interpreter-exec console "break main" 3190 &"During symbol reading, couldn't parse type; debugger out of date?.\n" 3191 &"During symbol reading, bad structure-type format.\n" 3192 ~"Breakpoint 1 at 0x8074fc6: file ../../src/gdb/main.c, line 743.\n" 3193 ^done 3194 (gdb) 3195 3196The `-inferior-tty-set' Command 3197------------------------------- 3198 3199Synopsis 3200-------- 3201 3202 -inferior-tty-set /dev/pts/1 3203 3204 Set terminal for future runs of the program being debugged. 3205 3206GDB Command 3207----------- 3208 3209The corresponding GDB command is `set inferior-tty' /dev/pts/1. 3210 3211Example 3212------- 3213 3214 (gdb) 3215 -inferior-tty-set /dev/pts/1 3216 ^done 3217 (gdb) 3218 3219The `-inferior-tty-show' Command 3220-------------------------------- 3221 3222Synopsis 3223-------- 3224 3225 -inferior-tty-show 3226 3227 Show terminal for future runs of program being debugged. 3228 3229GDB Command 3230----------- 3231 3232The corresponding GDB command is `show inferior-tty'. 3233 3234Example 3235------- 3236 3237 (gdb) 3238 -inferior-tty-set /dev/pts/1 3239 ^done 3240 (gdb) 3241 -inferior-tty-show 3242 ^done,inferior_tty_terminal="/dev/pts/1" 3243 (gdb) 3244 3245The `-enable-timings' Command 3246----------------------------- 3247 3248Synopsis 3249-------- 3250 3251 -enable-timings [yes | no] 3252 3253 Toggle the printing of the wallclock, user and system times for an MI 3254command as a field in its output. This command is to help frontend 3255developers optimize the performance of their code. No argument is 3256equivalent to `yes'. 3257 3258GDB Command 3259----------- 3260 3261No equivalent. 3262 3263Example 3264------- 3265 3266 (gdb) 3267 -enable-timings 3268 ^done 3269 (gdb) 3270 -break-insert main 3271 ^done,bkpt={number="1",type="breakpoint",disp="keep",enabled="y", 3272 addr="0x080484ed",func="main",file="myprog.c", 3273 fullname="/home/nickrob/myprog.c",line="73",times="0"}, 3274 time={wallclock="0.05185",user="0.00800",system="0.00000"} 3275 (gdb) 3276 -enable-timings no 3277 ^done 3278 (gdb) 3279 -exec-run 3280 ^running 3281 (gdb) 3282 *stopped,reason="breakpoint-hit",disp="keep",bkptno="1",thread-id="0", 3283 frame={addr="0x080484ed",func="main",args=[{name="argc",value="1"}, 3284 {name="argv",value="0xbfb60364"}],file="myprog.c", 3285 fullname="/home/nickrob/myprog.c",line="73"} 3286 (gdb) 3287 3288 3289File: gdb.info, Node: Annotations, Next: JIT Interface, Prev: GDB/MI, Up: Top 3290 329128 GDB Annotations 3292****************** 3293 3294This chapter describes annotations in GDB. Annotations were designed 3295to interface GDB to graphical user interfaces or other similar programs 3296which want to interact with GDB at a relatively high level. 3297 3298 The annotation mechanism has largely been superseded by GDB/MI 3299(*note GDB/MI::). 3300 3301* Menu: 3302 3303* Annotations Overview:: What annotations are; the general syntax. 3304* Server Prefix:: Issuing a command without affecting user state. 3305* Prompting:: Annotations marking GDB's need for input. 3306* Errors:: Annotations for error messages. 3307* Invalidation:: Some annotations describe things now invalid. 3308* Annotations for Running:: 3309 Whether the program is running, how it stopped, etc. 3310* Source Annotations:: Annotations describing source code. 3311 3312 3313File: gdb.info, Node: Annotations Overview, Next: Server Prefix, Up: Annotations 3314 331528.1 What is an Annotation? 3316=========================== 3317 3318Annotations start with a newline character, two `control-z' characters, 3319and the name of the annotation. If there is no additional information 3320associated with this annotation, the name of the annotation is followed 3321immediately by a newline. If there is additional information, the name 3322of the annotation is followed by a space, the additional information, 3323and a newline. The additional information cannot contain newline 3324characters. 3325 3326 Any output not beginning with a newline and two `control-z' 3327characters denotes literal output from GDB. Currently there is no need 3328for GDB to output a newline followed by two `control-z' characters, but 3329if there was such a need, the annotations could be extended with an 3330`escape' annotation which means those three characters as output. 3331 3332 The annotation LEVEL, which is specified using the `--annotate' 3333command line option (*note Mode Options::), controls how much 3334information GDB prints together with its prompt, values of expressions, 3335source lines, and other types of output. Level 0 is for no 3336annotations, level 1 is for use when GDB is run as a subprocess of GNU 3337Emacs, level 3 is the maximum annotation suitable for programs that 3338control GDB, and level 2 annotations have been made obsolete (*note 3339Limitations of the Annotation Interface: (annotate)Limitations.). 3340 3341`set annotate LEVEL' 3342 The GDB command `set annotate' sets the level of annotations to 3343 the specified LEVEL. 3344 3345`show annotate' 3346 Show the current annotation level. 3347 3348 This chapter describes level 3 annotations. 3349 3350 A simple example of starting up GDB with annotations is: 3351 3352 $ gdb --annotate=3 3353 GNU gdb 6.0 3354 Copyright 2003 Free Software Foundation, Inc. 3355 GDB is free software, covered by the GNU General Public License, 3356 and you are welcome to change it and/or distribute copies of it 3357 under certain conditions. 3358 Type "show copying" to see the conditions. 3359 There is absolutely no warranty for GDB. Type "show warranty" 3360 for details. 3361 This GDB was configured as "i386-pc-linux-gnu" 3362 3363 ^Z^Zpre-prompt 3364 (gdb) 3365 ^Z^Zprompt 3366 quit 3367 3368 ^Z^Zpost-prompt 3369 $ 3370 3371 Here `quit' is input to GDB; the rest is output from GDB. The three 3372lines beginning `^Z^Z' (where `^Z' denotes a `control-z' character) are 3373annotations; the rest is output from GDB. 3374 3375 3376File: gdb.info, Node: Server Prefix, Next: Prompting, Prev: Annotations Overview, Up: Annotations 3377 337828.2 The Server Prefix 3379====================== 3380 3381If you prefix a command with `server ' then it will not affect the 3382command history, nor will it affect GDB's notion of which command to 3383repeat if <RET> is pressed on a line by itself. This means that 3384commands can be run behind a user's back by a front-end in a 3385transparent manner. 3386 3387 The `server ' prefix does not affect the recording of values into 3388the value history; to print a value without recording it into the value 3389history, use the `output' command instead of the `print' command. 3390 3391 Using this prefix also disables confirmation requests (*note 3392confirmation requests::). 3393 3394 3395File: gdb.info, Node: Prompting, Next: Errors, Prev: Server Prefix, Up: Annotations 3396 339728.3 Annotation for GDB Input 3398============================= 3399 3400When GDB prompts for input, it annotates this fact so it is possible to 3401know when to send output, when the output from a given command is over, 3402etc. 3403 3404 Different kinds of input each have a different "input type". Each 3405input type has three annotations: a `pre-' annotation, which denotes 3406the beginning of any prompt which is being output, a plain annotation, 3407which denotes the end of the prompt, and then a `post-' annotation 3408which denotes the end of any echo which may (or may not) be associated 3409with the input. For example, the `prompt' input type features the 3410following annotations: 3411 3412 ^Z^Zpre-prompt 3413 ^Z^Zprompt 3414 ^Z^Zpost-prompt 3415 3416 The input types are 3417 3418`prompt' 3419 When GDB is prompting for a command (the main GDB prompt). 3420 3421`commands' 3422 When GDB prompts for a set of commands, like in the `commands' 3423 command. The annotations are repeated for each command which is 3424 input. 3425 3426`overload-choice' 3427 When GDB wants the user to select between various overloaded 3428 functions. 3429 3430`query' 3431 When GDB wants the user to confirm a potentially dangerous 3432 operation. 3433 3434`prompt-for-continue' 3435 When GDB is asking the user to press return to continue. Note: 3436 Don't expect this to work well; instead use `set height 0' to 3437 disable prompting. This is because the counting of lines is buggy 3438 in the presence of annotations. 3439 3440 3441File: gdb.info, Node: Errors, Next: Invalidation, Prev: Prompting, Up: Annotations 3442 344328.4 Errors 3444=========== 3445 3446 ^Z^Zquit 3447 3448 This annotation occurs right before GDB responds to an interrupt. 3449 3450 ^Z^Zerror 3451 3452 This annotation occurs right before GDB responds to an error. 3453 3454 Quit and error annotations indicate that any annotations which GDB 3455was in the middle of may end abruptly. For example, if a 3456`value-history-begin' annotation is followed by a `error', one cannot 3457expect to receive the matching `value-history-end'. One cannot expect 3458not to receive it either, however; an error annotation does not 3459necessarily mean that GDB is immediately returning all the way to the 3460top level. 3461 3462 A quit or error annotation may be preceded by 3463 3464 ^Z^Zerror-begin 3465 3466 Any output between that and the quit or error annotation is the error 3467message. 3468 3469 Warning messages are not yet annotated. 3470 3471 3472File: gdb.info, Node: Invalidation, Next: Annotations for Running, Prev: Errors, Up: Annotations 3473 347428.5 Invalidation Notices 3475========================= 3476 3477The following annotations say that certain pieces of state may have 3478changed. 3479 3480`^Z^Zframes-invalid' 3481 The frames (for example, output from the `backtrace' command) may 3482 have changed. 3483 3484`^Z^Zbreakpoints-invalid' 3485 The breakpoints may have changed. For example, the user just 3486 added or deleted a breakpoint. 3487 3488 3489File: gdb.info, Node: Annotations for Running, Next: Source Annotations, Prev: Invalidation, Up: Annotations 3490 349128.6 Running the Program 3492======================== 3493 3494When the program starts executing due to a GDB command such as `step' 3495or `continue', 3496 3497 ^Z^Zstarting 3498 3499 is output. When the program stops, 3500 3501 ^Z^Zstopped 3502 3503 is output. Before the `stopped' annotation, a variety of 3504annotations describe how the program stopped. 3505 3506`^Z^Zexited EXIT-STATUS' 3507 The program exited, and EXIT-STATUS is the exit status (zero for 3508 successful exit, otherwise nonzero). 3509 3510`^Z^Zsignalled' 3511 The program exited with a signal. After the `^Z^Zsignalled', the 3512 annotation continues: 3513 3514 INTRO-TEXT 3515 ^Z^Zsignal-name 3516 NAME 3517 ^Z^Zsignal-name-end 3518 MIDDLE-TEXT 3519 ^Z^Zsignal-string 3520 STRING 3521 ^Z^Zsignal-string-end 3522 END-TEXT 3523 3524 where NAME is the name of the signal, such as `SIGILL' or 3525 `SIGSEGV', and STRING is the explanation of the signal, such as 3526 `Illegal Instruction' or `Segmentation fault'. INTRO-TEXT, 3527 MIDDLE-TEXT, and END-TEXT are for the user's benefit and have no 3528 particular format. 3529 3530`^Z^Zsignal' 3531 The syntax of this annotation is just like `signalled', but GDB is 3532 just saying that the program received the signal, not that it was 3533 terminated with it. 3534 3535`^Z^Zbreakpoint NUMBER' 3536 The program hit breakpoint number NUMBER. 3537 3538`^Z^Zwatchpoint NUMBER' 3539 The program hit watchpoint number NUMBER. 3540 3541 3542File: gdb.info, Node: Source Annotations, Prev: Annotations for Running, Up: Annotations 3543 354428.7 Displaying Source 3545====================== 3546 3547The following annotation is used instead of displaying source code: 3548 3549 ^Z^Zsource FILENAME:LINE:CHARACTER:MIDDLE:ADDR 3550 3551 where FILENAME is an absolute file name indicating which source 3552file, LINE is the line number within that file (where 1 is the first 3553line in the file), CHARACTER is the character position within the file 3554(where 0 is the first character in the file) (for most debug formats 3555this will necessarily point to the beginning of a line), MIDDLE is 3556`middle' if ADDR is in the middle of the line, or `beg' if ADDR is at 3557the beginning of the line, and ADDR is the address in the target 3558program associated with the source which is being displayed. ADDR is 3559in the form `0x' followed by one or more lowercase hex digits (note 3560that this does not depend on the language). 3561 3562 3563File: gdb.info, Node: JIT Interface, Next: GDB Bugs, Prev: Annotations, Up: Top 3564 356529 JIT Compilation Interface 3566**************************** 3567 3568This chapter documents GDB's "just-in-time" (JIT) compilation 3569interface. A JIT compiler is a program or library that generates native 3570executable code at runtime and executes it, usually in order to achieve 3571good performance while maintaining platform independence. 3572 3573 Programs that use JIT compilation are normally difficult to debug 3574because portions of their code are generated at runtime, instead of 3575being loaded from object files, which is where GDB normally finds the 3576program's symbols and debug information. In order to debug programs 3577that use JIT compilation, GDB has an interface that allows the program 3578to register in-memory symbol files with GDB at runtime. 3579 3580 If you are using GDB to debug a program that uses this interface, 3581then it should work transparently so long as you have not stripped the 3582binary. If you are developing a JIT compiler, then the interface is 3583documented in the rest of this chapter. At this time, the only known 3584client of this interface is the LLVM JIT. 3585 3586 Broadly speaking, the JIT interface mirrors the dynamic loader 3587interface. The JIT compiler communicates with GDB by writing data into 3588a global variable and calling a fuction at a well-known symbol. When 3589GDB attaches, it reads a linked list of symbol files from the global 3590variable to find existing code, and puts a breakpoint in the function 3591so that it can find out about additional code. 3592 3593* Menu: 3594 3595* Declarations:: Relevant C struct declarations 3596* Registering Code:: Steps to register code 3597* Unregistering Code:: Steps to unregister code 3598 3599 3600File: gdb.info, Node: Declarations, Next: Registering Code, Up: JIT Interface 3601 360229.1 JIT Declarations 3603===================== 3604 3605These are the relevant struct declarations that a C program should 3606include to implement the interface: 3607 3608 typedef enum 3609 { 3610 JIT_NOACTION = 0, 3611 JIT_REGISTER_FN, 3612 JIT_UNREGISTER_FN 3613 } jit_actions_t; 3614 3615 struct jit_code_entry 3616 { 3617 struct jit_code_entry *next_entry; 3618 struct jit_code_entry *prev_entry; 3619 const char *symfile_addr; 3620 uint64_t symfile_size; 3621 }; 3622 3623 struct jit_descriptor 3624 { 3625 uint32_t version; 3626 /* This type should be jit_actions_t, but we use uint32_t 3627 to be explicit about the bitwidth. */ 3628 uint32_t action_flag; 3629 struct jit_code_entry *relevant_entry; 3630 struct jit_code_entry *first_entry; 3631 }; 3632 3633 /* GDB puts a breakpoint in this function. */ 3634 void __attribute__((noinline)) __jit_debug_register_code() { }; 3635 3636 /* Make sure to specify the version statically, because the 3637 debugger may check the version before we can set it. */ 3638 struct jit_descriptor __jit_debug_descriptor = { 1, 0, 0, 0 }; 3639 3640 If the JIT is multi-threaded, then it is important that the JIT 3641synchronize any modifications to this global data properly, which can 3642easily be done by putting a global mutex around modifications to these 3643structures. 3644 3645 3646File: gdb.info, Node: Registering Code, Next: Unregistering Code, Prev: Declarations, Up: JIT Interface 3647 364829.2 Registering Code 3649===================== 3650 3651To register code with GDB, the JIT should follow this protocol: 3652 3653 * Generate an object file in memory with symbols and other desired 3654 debug information. The file must include the virtual addresses of 3655 the sections. 3656 3657 * Create a code entry for the file, which gives the start and size 3658 of the symbol file. 3659 3660 * Add it to the linked list in the JIT descriptor. 3661 3662 * Point the relevant_entry field of the descriptor at the entry. 3663 3664 * Set `action_flag' to `JIT_REGISTER' and call 3665 `__jit_debug_register_code'. 3666 3667 When GDB is attached and the breakpoint fires, GDB uses the 3668`relevant_entry' pointer so it doesn't have to walk the list looking for 3669new code. However, the linked list must still be maintained in order 3670to allow GDB to attach to a running process and still find the symbol 3671files. 3672 3673 3674File: gdb.info, Node: Unregistering Code, Prev: Registering Code, Up: JIT Interface 3675 367629.3 Unregistering Code 3677======================= 3678 3679If code is freed, then the JIT should use the following protocol: 3680 3681 * Remove the code entry corresponding to the code from the linked 3682 list. 3683 3684 * Point the `relevant_entry' field of the descriptor at the code 3685 entry. 3686 3687 * Set `action_flag' to `JIT_UNREGISTER' and call 3688 `__jit_debug_register_code'. 3689 3690 If the JIT frees or recompiles code without unregistering it, then 3691GDB and the JIT will leak the memory used for the associated symbol 3692files. 3693 3694 3695File: gdb.info, Node: GDB Bugs, Next: Command Line Editing, Prev: JIT Interface, Up: Top 3696 369730 Reporting Bugs in GDB 3698************************ 3699 3700Your bug reports play an essential role in making GDB reliable. 3701 3702 Reporting a bug may help you by bringing a solution to your problem, 3703or it may not. But in any case the principal function of a bug report 3704is to help the entire community by making the next version of GDB work 3705better. Bug reports are your contribution to the maintenance of GDB. 3706 3707 In order for a bug report to serve its purpose, you must include the 3708information that enables us to fix the bug. 3709 3710* Menu: 3711 3712* Bug Criteria:: Have you found a bug? 3713* Bug Reporting:: How to report bugs 3714 3715 3716File: gdb.info, Node: Bug Criteria, Next: Bug Reporting, Up: GDB Bugs 3717 371830.1 Have You Found a Bug? 3719========================== 3720 3721If you are not sure whether you have found a bug, here are some 3722guidelines: 3723 3724 * If the debugger gets a fatal signal, for any input whatever, that 3725 is a GDB bug. Reliable debuggers never crash. 3726 3727 * If GDB produces an error message for valid input, that is a bug. 3728 (Note that if you're cross debugging, the problem may also be 3729 somewhere in the connection to the target.) 3730 3731 * If GDB does not produce an error message for invalid input, that 3732 is a bug. However, you should note that your idea of "invalid 3733 input" might be our idea of "an extension" or "support for 3734 traditional practice". 3735 3736 * If you are an experienced user of debugging tools, your suggestions 3737 for improvement of GDB are welcome in any case. 3738 3739 3740File: gdb.info, Node: Bug Reporting, Prev: Bug Criteria, Up: GDB Bugs 3741 374230.2 How to Report Bugs 3743======================= 3744 3745A number of companies and individuals offer support for GNU products. 3746If you obtained GDB from a support organization, we recommend you 3747contact that organization first. 3748 3749 You can find contact information for many support companies and 3750individuals in the file `etc/SERVICE' in the GNU Emacs distribution. 3751 3752 In any event, we also recommend that you submit bug reports for GDB. 3753The preferred method is to submit them directly using GDB's Bugs web 3754page (http://www.gnu.org/software/gdb/bugs/). Alternatively, the 3755e-mail gateway <bug-gdb@gnu.org> can be used. 3756 3757 *Do not send bug reports to `info-gdb', or to `help-gdb', or to any 3758newsgroups.* Most users of GDB do not want to receive bug reports. 3759Those that do have arranged to receive `bug-gdb'. 3760 3761 The mailing list `bug-gdb' has a newsgroup `gnu.gdb.bug' which 3762serves as a repeater. The mailing list and the newsgroup carry exactly 3763the same messages. Often people think of posting bug reports to the 3764newsgroup instead of mailing them. This appears to work, but it has one 3765problem which can be crucial: a newsgroup posting often lacks a mail 3766path back to the sender. Thus, if we need to ask for more information, 3767we may be unable to reach you. For this reason, it is better to send 3768bug reports to the mailing list. 3769 3770 The fundamental principle of reporting bugs usefully is this: 3771*report all the facts*. If you are not sure whether to state a fact or 3772leave it out, state it! 3773 3774 Often people omit facts because they think they know what causes the 3775problem and assume that some details do not matter. Thus, you might 3776assume that the name of the variable you use in an example does not 3777matter. Well, probably it does not, but one cannot be sure. Perhaps 3778the bug is a stray memory reference which happens to fetch from the 3779location where that name is stored in memory; perhaps, if the name were 3780different, the contents of that location would fool the debugger into 3781doing the right thing despite the bug. Play it safe and give a 3782specific, complete example. That is the easiest thing for you to do, 3783and the most helpful. 3784 3785 Keep in mind that the purpose of a bug report is to enable us to fix 3786the bug. It may be that the bug has been reported previously, but 3787neither you nor we can know that unless your bug report is complete and 3788self-contained. 3789 3790 Sometimes people give a few sketchy facts and ask, "Does this ring a 3791bell?" Those bug reports are useless, and we urge everyone to _refuse 3792to respond to them_ except to chide the sender to report bugs properly. 3793 3794 To enable us to fix the bug, you should include all these things: 3795 3796 * The version of GDB. GDB announces it if you start with no 3797 arguments; you can also print it at any time using `show version'. 3798 3799 Without this, we will not know whether there is any point in 3800 looking for the bug in the current version of GDB. 3801 3802 * The type of machine you are using, and the operating system name 3803 and version number. 3804 3805 * What compiler (and its version) was used to compile GDB--e.g. 3806 "gcc-2.8.1". 3807 3808 * What compiler (and its version) was used to compile the program 3809 you are debugging--e.g. "gcc-2.8.1", or "HP92453-01 A.10.32.03 HP 3810 C Compiler". For GCC, you can say `gcc --version' to get this 3811 information; for other compilers, see the documentation for those 3812 compilers. 3813 3814 * The command arguments you gave the compiler to compile your 3815 example and observe the bug. For example, did you use `-O'? To 3816 guarantee you will not omit something important, list them all. A 3817 copy of the Makefile (or the output from make) is sufficient. 3818 3819 If we were to try to guess the arguments, we would probably guess 3820 wrong and then we might not encounter the bug. 3821 3822 * A complete input script, and all necessary source files, that will 3823 reproduce the bug. 3824 3825 * A description of what behavior you observe that you believe is 3826 incorrect. For example, "It gets a fatal signal." 3827 3828 Of course, if the bug is that GDB gets a fatal signal, then we 3829 will certainly notice it. But if the bug is incorrect output, we 3830 might not notice unless it is glaringly wrong. You might as well 3831 not give us a chance to make a mistake. 3832 3833 Even if the problem you experience is a fatal signal, you should 3834 still say so explicitly. Suppose something strange is going on, 3835 such as, your copy of GDB is out of synch, or you have encountered 3836 a bug in the C library on your system. (This has happened!) Your 3837 copy might crash and ours would not. If you told us to expect a 3838 crash, then when ours fails to crash, we would know that the bug 3839 was not happening for us. If you had not told us to expect a 3840 crash, then we would not be able to draw any conclusion from our 3841 observations. 3842 3843 To collect all this information, you can use a session recording 3844 program such as `script', which is available on many Unix systems. 3845 Just run your GDB session inside `script' and then include the 3846 `typescript' file with your bug report. 3847 3848 Another way to record a GDB session is to run GDB inside Emacs and 3849 then save the entire buffer to a file. 3850 3851 * If you wish to suggest changes to the GDB source, send us context 3852 diffs. If you even discuss something in the GDB source, refer to 3853 it by context, not by line number. 3854 3855 The line numbers in our development sources will not match those 3856 in your sources. Your line numbers would convey no useful 3857 information to us. 3858 3859 3860 Here are some things that are not necessary: 3861 3862 * A description of the envelope of the bug. 3863 3864 Often people who encounter a bug spend a lot of time investigating 3865 which changes to the input file will make the bug go away and which 3866 changes will not affect it. 3867 3868 This is often time consuming and not very useful, because the way 3869 we will find the bug is by running a single example under the 3870 debugger with breakpoints, not by pure deduction from a series of 3871 examples. We recommend that you save your time for something else. 3872 3873 Of course, if you can find a simpler example to report _instead_ 3874 of the original one, that is a convenience for us. Errors in the 3875 output will be easier to spot, running under the debugger will take 3876 less time, and so on. 3877 3878 However, simplification is not vital; if you do not want to do 3879 this, report the bug anyway and send us the entire test case you 3880 used. 3881 3882 * A patch for the bug. 3883 3884 A patch for the bug does help us if it is a good one. But do not 3885 omit the necessary information, such as the test case, on the 3886 assumption that a patch is all we need. We might see problems 3887 with your patch and decide to fix the problem another way, or we 3888 might not understand it at all. 3889 3890 Sometimes with a program as complicated as GDB it is very hard to 3891 construct an example that will make the program follow a certain 3892 path through the code. If you do not send us the example, we will 3893 not be able to construct one, so we will not be able to verify 3894 that the bug is fixed. 3895 3896 And if we cannot understand what bug you are trying to fix, or why 3897 your patch should be an improvement, we will not install it. A 3898 test case will help us to understand. 3899 3900 * A guess about what the bug is or what it depends on. 3901 3902 Such guesses are usually wrong. Even we cannot guess right about 3903 such things without first using the debugger to find the facts. 3904 3905 3906File: gdb.info, Node: Command Line Editing, Next: Using History Interactively, Prev: GDB Bugs, Up: Top 3907 390831 Command Line Editing 3909*********************** 3910 3911This chapter describes the basic features of the GNU command line 3912editing interface. 3913 3914* Menu: 3915 3916* Introduction and Notation:: Notation used in this text. 3917* Readline Interaction:: The minimum set of commands for editing a line. 3918* Readline Init File:: Customizing Readline from a user's view. 3919* Bindable Readline Commands:: A description of most of the Readline commands 3920 available for binding 3921* Readline vi Mode:: A short description of how to make Readline 3922 behave like the vi editor. 3923 3924 3925File: gdb.info, Node: Introduction and Notation, Next: Readline Interaction, Up: Command Line Editing 3926 392731.1 Introduction to Line Editing 3928================================= 3929 3930The following paragraphs describe the notation used to represent 3931keystrokes. 3932 3933 The text `C-k' is read as `Control-K' and describes the character 3934produced when the <k> key is pressed while the Control key is depressed. 3935 3936 The text `M-k' is read as `Meta-K' and describes the character 3937produced when the Meta key (if you have one) is depressed, and the <k> 3938key is pressed. The Meta key is labeled <ALT> on many keyboards. On 3939keyboards with two keys labeled <ALT> (usually to either side of the 3940space bar), the <ALT> on the left side is generally set to work as a 3941Meta key. The <ALT> key on the right may also be configured to work as 3942a Meta key or may be configured as some other modifier, such as a 3943Compose key for typing accented characters. 3944 3945 If you do not have a Meta or <ALT> key, or another key working as a 3946Meta key, the identical keystroke can be generated by typing <ESC> 3947_first_, and then typing <k>. Either process is known as "metafying" 3948the <k> key. 3949 3950 The text `M-C-k' is read as `Meta-Control-k' and describes the 3951character produced by "metafying" `C-k'. 3952 3953 In addition, several keys have their own names. Specifically, 3954<DEL>, <ESC>, <LFD>, <SPC>, <RET>, and <TAB> all stand for themselves 3955when seen in this text, or in an init file (*note Readline Init File::). 3956If your keyboard lacks a <LFD> key, typing <C-j> will produce the 3957desired character. The <RET> key may be labeled <Return> or <Enter> on 3958some keyboards. 3959 3960 3961File: gdb.info, Node: Readline Interaction, Next: Readline Init File, Prev: Introduction and Notation, Up: Command Line Editing 3962 396331.2 Readline Interaction 3964========================= 3965 3966Often during an interactive session you type in a long line of text, 3967only to notice that the first word on the line is misspelled. The 3968Readline library gives you a set of commands for manipulating the text 3969as you type it in, allowing you to just fix your typo, and not forcing 3970you to retype the majority of the line. Using these editing commands, 3971you move the cursor to the place that needs correction, and delete or 3972insert the text of the corrections. Then, when you are satisfied with 3973the line, you simply press <RET>. You do not have to be at the end of 3974the line to press <RET>; the entire line is accepted regardless of the 3975location of the cursor within the line. 3976 3977* Menu: 3978 3979* Readline Bare Essentials:: The least you need to know about Readline. 3980* Readline Movement Commands:: Moving about the input line. 3981* Readline Killing Commands:: How to delete text, and how to get it back! 3982* Readline Arguments:: Giving numeric arguments to commands. 3983* Searching:: Searching through previous lines. 3984 3985 3986File: gdb.info, Node: Readline Bare Essentials, Next: Readline Movement Commands, Up: Readline Interaction 3987 398831.2.1 Readline Bare Essentials 3989------------------------------- 3990 3991In order to enter characters into the line, simply type them. The typed 3992character appears where the cursor was, and then the cursor moves one 3993space to the right. If you mistype a character, you can use your erase 3994character to back up and delete the mistyped character. 3995 3996 Sometimes you may mistype a character, and not notice the error 3997until you have typed several other characters. In that case, you can 3998type `C-b' to move the cursor to the left, and then correct your 3999mistake. Afterwards, you can move the cursor to the right with `C-f'. 4000 4001 When you add text in the middle of a line, you will notice that 4002characters to the right of the cursor are `pushed over' to make room 4003for the text that you have inserted. Likewise, when you delete text 4004behind the cursor, characters to the right of the cursor are `pulled 4005back' to fill in the blank space created by the removal of the text. A 4006list of the bare essentials for editing the text of an input line 4007follows. 4008 4009`C-b' 4010 Move back one character. 4011 4012`C-f' 4013 Move forward one character. 4014 4015<DEL> or <Backspace> 4016 Delete the character to the left of the cursor. 4017 4018`C-d' 4019 Delete the character underneath the cursor. 4020 4021Printing characters 4022 Insert the character into the line at the cursor. 4023 4024`C-_' or `C-x C-u' 4025 Undo the last editing command. You can undo all the way back to an 4026 empty line. 4027 4028(Depending on your configuration, the <Backspace> key be set to delete 4029the character to the left of the cursor and the <DEL> key set to delete 4030the character underneath the cursor, like `C-d', rather than the 4031character to the left of the cursor.) 4032 4033 4034File: gdb.info, Node: Readline Movement Commands, Next: Readline Killing Commands, Prev: Readline Bare Essentials, Up: Readline Interaction 4035 403631.2.2 Readline Movement Commands 4037--------------------------------- 4038 4039The above table describes the most basic keystrokes that you need in 4040order to do editing of the input line. For your convenience, many 4041other commands have been added in addition to `C-b', `C-f', `C-d', and 4042<DEL>. Here are some commands for moving more rapidly about the line. 4043 4044`C-a' 4045 Move to the start of the line. 4046 4047`C-e' 4048 Move to the end of the line. 4049 4050`M-f' 4051 Move forward a word, where a word is composed of letters and 4052 digits. 4053 4054`M-b' 4055 Move backward a word. 4056 4057`C-l' 4058 Clear the screen, reprinting the current line at the top. 4059 4060 Notice how `C-f' moves forward a character, while `M-f' moves 4061forward a word. It is a loose convention that control keystrokes 4062operate on characters while meta keystrokes operate on words. 4063 4064 4065File: gdb.info, Node: Readline Killing Commands, Next: Readline Arguments, Prev: Readline Movement Commands, Up: Readline Interaction 4066 406731.2.3 Readline Killing Commands 4068-------------------------------- 4069 4070"Killing" text means to delete the text from the line, but to save it 4071away for later use, usually by "yanking" (re-inserting) it back into 4072the line. (`Cut' and `paste' are more recent jargon for `kill' and 4073`yank'.) 4074 4075 If the description for a command says that it `kills' text, then you 4076can be sure that you can get the text back in a different (or the same) 4077place later. 4078 4079 When you use a kill command, the text is saved in a "kill-ring". 4080Any number of consecutive kills save all of the killed text together, so 4081that when you yank it back, you get it all. The kill ring is not line 4082specific; the text that you killed on a previously typed line is 4083available to be yanked back later, when you are typing another line. 4084 4085 Here is the list of commands for killing text. 4086 4087`C-k' 4088 Kill the text from the current cursor position to the end of the 4089 line. 4090 4091`M-d' 4092 Kill from the cursor to the end of the current word, or, if between 4093 words, to the end of the next word. Word boundaries are the same 4094 as those used by `M-f'. 4095 4096`M-<DEL>' 4097 Kill from the cursor the start of the current word, or, if between 4098 words, to the start of the previous word. Word boundaries are the 4099 same as those used by `M-b'. 4100 4101`C-w' 4102 Kill from the cursor to the previous whitespace. This is 4103 different than `M-<DEL>' because the word boundaries differ. 4104 4105 4106 Here is how to "yank" the text back into the line. Yanking means to 4107copy the most-recently-killed text from the kill buffer. 4108 4109`C-y' 4110 Yank the most recently killed text back into the buffer at the 4111 cursor. 4112 4113`M-y' 4114 Rotate the kill-ring, and yank the new top. You can only do this 4115 if the prior command is `C-y' or `M-y'. 4116 4117 4118File: gdb.info, Node: Readline Arguments, Next: Searching, Prev: Readline Killing Commands, Up: Readline Interaction 4119 412031.2.4 Readline Arguments 4121------------------------- 4122 4123You can pass numeric arguments to Readline commands. Sometimes the 4124argument acts as a repeat count, other times it is the sign of the 4125argument that is significant. If you pass a negative argument to a 4126command which normally acts in a forward direction, that command will 4127act in a backward direction. For example, to kill text back to the 4128start of the line, you might type `M-- C-k'. 4129 4130 The general way to pass numeric arguments to a command is to type 4131meta digits before the command. If the first `digit' typed is a minus 4132sign (`-'), then the sign of the argument will be negative. Once you 4133have typed one meta digit to get the argument started, you can type the 4134remainder of the digits, and then the command. For example, to give 4135the `C-d' command an argument of 10, you could type `M-1 0 C-d', which 4136will delete the next ten characters on the input line. 4137 4138 4139File: gdb.info, Node: Searching, Prev: Readline Arguments, Up: Readline Interaction 4140 414131.2.5 Searching for Commands in the History 4142-------------------------------------------- 4143 4144Readline provides commands for searching through the command history 4145for lines containing a specified string. There are two search modes: 4146"incremental" and "non-incremental". 4147 4148 Incremental searches begin before the user has finished typing the 4149search string. As each character of the search string is typed, 4150Readline displays the next entry from the history matching the string 4151typed so far. An incremental search requires only as many characters 4152as needed to find the desired history entry. To search backward in the 4153history for a particular string, type `C-r'. Typing `C-s' searches 4154forward through the history. The characters present in the value of 4155the `isearch-terminators' variable are used to terminate an incremental 4156search. If that variable has not been assigned a value, the <ESC> and 4157`C-J' characters will terminate an incremental search. `C-g' will 4158abort an incremental search and restore the original line. When the 4159search is terminated, the history entry containing the search string 4160becomes the current line. 4161 4162 To find other matching entries in the history list, type `C-r' or 4163`C-s' as appropriate. This will search backward or forward in the 4164history for the next entry matching the search string typed so far. 4165Any other key sequence bound to a Readline command will terminate the 4166search and execute that command. For instance, a <RET> will terminate 4167the search and accept the line, thereby executing the command from the 4168history list. A movement command will terminate the search, make the 4169last line found the current line, and begin editing. 4170 4171 Readline remembers the last incremental search string. If two 4172`C-r's are typed without any intervening characters defining a new 4173search string, any remembered search string is used. 4174 4175 Non-incremental searches read the entire search string before 4176starting to search for matching history lines. The search string may be 4177typed by the user or be part of the contents of the current line. 4178 4179 4180File: gdb.info, Node: Readline Init File, Next: Bindable Readline Commands, Prev: Readline Interaction, Up: Command Line Editing 4181 418231.3 Readline Init File 4183======================= 4184 4185Although the Readline library comes with a set of Emacs-like 4186keybindings installed by default, it is possible to use a different set 4187of keybindings. Any user can customize programs that use Readline by 4188putting commands in an "inputrc" file, conventionally in his home 4189directory. The name of this file is taken from the value of the 4190environment variable `INPUTRC'. If that variable is unset, the default 4191is `~/.inputrc'. 4192 4193 When a program which uses the Readline library starts up, the init 4194file is read, and the key bindings are set. 4195 4196 In addition, the `C-x C-r' command re-reads this init file, thus 4197incorporating any changes that you might have made to it. 4198 4199* Menu: 4200 4201* Readline Init File Syntax:: Syntax for the commands in the inputrc file. 4202 4203* Conditional Init Constructs:: Conditional key bindings in the inputrc file. 4204 4205* Sample Init File:: An example inputrc file. 4206 4207 4208File: gdb.info, Node: Readline Init File Syntax, Next: Conditional Init Constructs, Up: Readline Init File 4209 421031.3.1 Readline Init File Syntax 4211-------------------------------- 4212 4213There are only a few basic constructs allowed in the Readline init 4214file. Blank lines are ignored. Lines beginning with a `#' are 4215comments. Lines beginning with a `$' indicate conditional constructs 4216(*note Conditional Init Constructs::). Other lines denote variable 4217settings and key bindings. 4218 4219Variable Settings 4220 You can modify the run-time behavior of Readline by altering the 4221 values of variables in Readline using the `set' command within the 4222 init file. The syntax is simple: 4223 4224 set VARIABLE VALUE 4225 4226 Here, for example, is how to change from the default Emacs-like 4227 key binding to use `vi' line editing commands: 4228 4229 set editing-mode vi 4230 4231 Variable names and values, where appropriate, are recognized 4232 without regard to case. Unrecognized variable names are ignored. 4233 4234 Boolean variables (those that can be set to on or off) are set to 4235 on if the value is null or empty, ON (case-insensitive), or 1. 4236 Any other value results in the variable being set to off. 4237 4238 A great deal of run-time behavior is changeable with the following 4239 variables. 4240 4241 `bell-style' 4242 Controls what happens when Readline wants to ring the 4243 terminal bell. If set to `none', Readline never rings the 4244 bell. If set to `visible', Readline uses a visible bell if 4245 one is available. If set to `audible' (the default), 4246 Readline attempts to ring the terminal's bell. 4247 4248 `bind-tty-special-chars' 4249 If set to `on', Readline attempts to bind the control 4250 characters treated specially by the kernel's terminal driver 4251 to their Readline equivalents. 4252 4253 `comment-begin' 4254 The string to insert at the beginning of the line when the 4255 `insert-comment' command is executed. The default value is 4256 `"#"'. 4257 4258 `completion-ignore-case' 4259 If set to `on', Readline performs filename matching and 4260 completion in a case-insensitive fashion. The default value 4261 is `off'. 4262 4263 `completion-query-items' 4264 The number of possible completions that determines when the 4265 user is asked whether the list of possibilities should be 4266 displayed. If the number of possible completions is greater 4267 than this value, Readline will ask the user whether or not he 4268 wishes to view them; otherwise, they are simply listed. This 4269 variable must be set to an integer value greater than or 4270 equal to 0. A negative value means Readline should never ask. 4271 The default limit is `100'. 4272 4273 `convert-meta' 4274 If set to `on', Readline will convert characters with the 4275 eighth bit set to an ASCII key sequence by stripping the 4276 eighth bit and prefixing an <ESC> character, converting them 4277 to a meta-prefixed key sequence. The default value is `on'. 4278 4279 `disable-completion' 4280 If set to `On', Readline will inhibit word completion. 4281 Completion characters will be inserted into the line as if 4282 they had been mapped to `self-insert'. The default is `off'. 4283 4284 `editing-mode' 4285 The `editing-mode' variable controls which default set of key 4286 bindings is used. By default, Readline starts up in Emacs 4287 editing mode, where the keystrokes are most similar to Emacs. 4288 This variable can be set to either `emacs' or `vi'. 4289 4290 `enable-keypad' 4291 When set to `on', Readline will try to enable the application 4292 keypad when it is called. Some systems need this to enable 4293 the arrow keys. The default is `off'. 4294 4295 `expand-tilde' 4296 If set to `on', tilde expansion is performed when Readline 4297 attempts word completion. The default is `off'. 4298 4299 `history-preserve-point' 4300 If set to `on', the history code attempts to place point at 4301 the same location on each history line retrieved with 4302 `previous-history' or `next-history'. The default is `off'. 4303 4304 `horizontal-scroll-mode' 4305 This variable can be set to either `on' or `off'. Setting it 4306 to `on' means that the text of the lines being edited will 4307 scroll horizontally on a single screen line when they are 4308 longer than the width of the screen, instead of wrapping onto 4309 a new screen line. By default, this variable is set to `off'. 4310 4311 `input-meta' 4312 If set to `on', Readline will enable eight-bit input (it will 4313 not clear the eighth bit in the characters it reads), 4314 regardless of what the terminal claims it can support. The 4315 default value is `off'. The name `meta-flag' is a synonym 4316 for this variable. 4317 4318 `isearch-terminators' 4319 The string of characters that should terminate an incremental 4320 search without subsequently executing the character as a 4321 command (*note Searching::). If this variable has not been 4322 given a value, the characters <ESC> and `C-J' will terminate 4323 an incremental search. 4324 4325 `keymap' 4326 Sets Readline's idea of the current keymap for key binding 4327 commands. Acceptable `keymap' names are `emacs', 4328 `emacs-standard', `emacs-meta', `emacs-ctlx', `vi', `vi-move', 4329 `vi-command', and `vi-insert'. `vi' is equivalent to 4330 `vi-command'; `emacs' is equivalent to `emacs-standard'. The 4331 default value is `emacs'. The value of the `editing-mode' 4332 variable also affects the default keymap. 4333 4334 `mark-directories' 4335 If set to `on', completed directory names have a slash 4336 appended. The default is `on'. 4337 4338 `mark-modified-lines' 4339 This variable, when set to `on', causes Readline to display an 4340 asterisk (`*') at the start of history lines which have been 4341 modified. This variable is `off' by default. 4342 4343 `mark-symlinked-directories' 4344 If set to `on', completed names which are symbolic links to 4345 directories have a slash appended (subject to the value of 4346 `mark-directories'). The default is `off'. 4347 4348 `match-hidden-files' 4349 This variable, when set to `on', causes Readline to match 4350 files whose names begin with a `.' (hidden files) when 4351 performing filename completion, unless the leading `.' is 4352 supplied by the user in the filename to be completed. This 4353 variable is `on' by default. 4354 4355 `output-meta' 4356 If set to `on', Readline will display characters with the 4357 eighth bit set directly rather than as a meta-prefixed escape 4358 sequence. The default is `off'. 4359 4360 `page-completions' 4361 If set to `on', Readline uses an internal `more'-like pager 4362 to display a screenful of possible completions at a time. 4363 This variable is `on' by default. 4364 4365 `print-completions-horizontally' 4366 If set to `on', Readline will display completions with matches 4367 sorted horizontally in alphabetical order, rather than down 4368 the screen. The default is `off'. 4369 4370 `show-all-if-ambiguous' 4371 This alters the default behavior of the completion functions. 4372 If set to `on', words which have more than one possible 4373 completion cause the matches to be listed immediately instead 4374 of ringing the bell. The default value is `off'. 4375 4376 `show-all-if-unmodified' 4377 This alters the default behavior of the completion functions 4378 in a fashion similar to SHOW-ALL-IF-AMBIGUOUS. If set to 4379 `on', words which have more than one possible completion 4380 without any possible partial completion (the possible 4381 completions don't share a common prefix) cause the matches to 4382 be listed immediately instead of ringing the bell. The 4383 default value is `off'. 4384 4385 `visible-stats' 4386 If set to `on', a character denoting a file's type is 4387 appended to the filename when listing possible completions. 4388 The default is `off'. 4389 4390 4391Key Bindings 4392 The syntax for controlling key bindings in the init file is 4393 simple. First you need to find the name of the command that you 4394 want to change. The following sections contain tables of the 4395 command name, the default keybinding, if any, and a short 4396 description of what the command does. 4397 4398 Once you know the name of the command, simply place on a line in 4399 the init file the name of the key you wish to bind the command to, 4400 a colon, and then the name of the command. The name of the key 4401 can be expressed in different ways, depending on what you find most 4402 comfortable. 4403 4404 In addition to command names, readline allows keys to be bound to 4405 a string that is inserted when the key is pressed (a MACRO). 4406 4407 KEYNAME: FUNCTION-NAME or MACRO 4408 KEYNAME is the name of a key spelled out in English. For 4409 example: 4410 Control-u: universal-argument 4411 Meta-Rubout: backward-kill-word 4412 Control-o: "> output" 4413 4414 In the above example, `C-u' is bound to the function 4415 `universal-argument', `M-DEL' is bound to the function 4416 `backward-kill-word', and `C-o' is bound to run the macro 4417 expressed on the right hand side (that is, to insert the text 4418 `> output' into the line). 4419 4420 A number of symbolic character names are recognized while 4421 processing this key binding syntax: DEL, ESC, ESCAPE, LFD, 4422 NEWLINE, RET, RETURN, RUBOUT, SPACE, SPC, and TAB. 4423 4424 "KEYSEQ": FUNCTION-NAME or MACRO 4425 KEYSEQ differs from KEYNAME above in that strings denoting an 4426 entire key sequence can be specified, by placing the key 4427 sequence in double quotes. Some GNU Emacs style key escapes 4428 can be used, as in the following example, but the special 4429 character names are not recognized. 4430 4431 "\C-u": universal-argument 4432 "\C-x\C-r": re-read-init-file 4433 "\e[11~": "Function Key 1" 4434 4435 In the above example, `C-u' is again bound to the function 4436 `universal-argument' (just as it was in the first example), 4437 `C-x C-r' is bound to the function `re-read-init-file', and 4438 `<ESC> <[> <1> <1> <~>' is bound to insert the text `Function 4439 Key 1'. 4440 4441 4442 The following GNU Emacs style escape sequences are available when 4443 specifying key sequences: 4444 4445 `\C-' 4446 control prefix 4447 4448 `\M-' 4449 meta prefix 4450 4451 `\e' 4452 an escape character 4453 4454 `\\' 4455 backslash 4456 4457 `\"' 4458 <">, a double quotation mark 4459 4460 `\'' 4461 <'>, a single quote or apostrophe 4462 4463 In addition to the GNU Emacs style escape sequences, a second set 4464 of backslash escapes is available: 4465 4466 `\a' 4467 alert (bell) 4468 4469 `\b' 4470 backspace 4471 4472 `\d' 4473 delete 4474 4475 `\f' 4476 form feed 4477 4478 `\n' 4479 newline 4480 4481 `\r' 4482 carriage return 4483 4484 `\t' 4485 horizontal tab 4486 4487 `\v' 4488 vertical tab 4489 4490 `\NNN' 4491 the eight-bit character whose value is the octal value NNN 4492 (one to three digits) 4493 4494 `\xHH' 4495 the eight-bit character whose value is the hexadecimal value 4496 HH (one or two hex digits) 4497 4498 When entering the text of a macro, single or double quotes must be 4499 used to indicate a macro definition. Unquoted text is assumed to 4500 be a function name. In the macro body, the backslash escapes 4501 described above are expanded. Backslash will quote any other 4502 character in the macro text, including `"' and `''. For example, 4503 the following binding will make `C-x \' insert a single `\' into 4504 the line: 4505 "\C-x\\": "\\" 4506 4507 4508 4509File: gdb.info, Node: Conditional Init Constructs, Next: Sample Init File, Prev: Readline Init File Syntax, Up: Readline Init File 4510 451131.3.2 Conditional Init Constructs 4512---------------------------------- 4513 4514Readline implements a facility similar in spirit to the conditional 4515compilation features of the C preprocessor which allows key bindings 4516and variable settings to be performed as the result of tests. There 4517are four parser directives used. 4518 4519`$if' 4520 The `$if' construct allows bindings to be made based on the 4521 editing mode, the terminal being used, or the application using 4522 Readline. The text of the test extends to the end of the line; no 4523 characters are required to isolate it. 4524 4525 `mode' 4526 The `mode=' form of the `$if' directive is used to test 4527 whether Readline is in `emacs' or `vi' mode. This may be 4528 used in conjunction with the `set keymap' command, for 4529 instance, to set bindings in the `emacs-standard' and 4530 `emacs-ctlx' keymaps only if Readline is starting out in 4531 `emacs' mode. 4532 4533 `term' 4534 The `term=' form may be used to include terminal-specific key 4535 bindings, perhaps to bind the key sequences output by the 4536 terminal's function keys. The word on the right side of the 4537 `=' is tested against both the full name of the terminal and 4538 the portion of the terminal name before the first `-'. This 4539 allows `sun' to match both `sun' and `sun-cmd', for instance. 4540 4541 `application' 4542 The APPLICATION construct is used to include 4543 application-specific settings. Each program using the 4544 Readline library sets the APPLICATION NAME, and you can test 4545 for a particular value. This could be used to bind key 4546 sequences to functions useful for a specific program. For 4547 instance, the following command adds a key sequence that 4548 quotes the current or previous word in Bash: 4549 $if Bash 4550 # Quote the current or previous word 4551 "\C-xq": "\eb\"\ef\"" 4552 $endif 4553 4554`$endif' 4555 This command, as seen in the previous example, terminates an `$if' 4556 command. 4557 4558`$else' 4559 Commands in this branch of the `$if' directive are executed if the 4560 test fails. 4561 4562`$include' 4563 This directive takes a single filename as an argument and reads 4564 commands and bindings from that file. For example, the following 4565 directive reads from `/etc/inputrc': 4566 $include /etc/inputrc 4567 4568 4569File: gdb.info, Node: Sample Init File, Prev: Conditional Init Constructs, Up: Readline Init File 4570 457131.3.3 Sample Init File 4572----------------------- 4573 4574Here is an example of an INPUTRC file. This illustrates key binding, 4575variable assignment, and conditional syntax. 4576 4577 4578 # This file controls the behaviour of line input editing for 4579 # programs that use the GNU Readline library. Existing 4580 # programs include FTP, Bash, and GDB. 4581 # 4582 # You can re-read the inputrc file with C-x C-r. 4583 # Lines beginning with '#' are comments. 4584 # 4585 # First, include any systemwide bindings and variable 4586 # assignments from /etc/Inputrc 4587 $include /etc/Inputrc 4588 4589 # 4590 # Set various bindings for emacs mode. 4591 4592 set editing-mode emacs 4593 4594 $if mode=emacs 4595 4596 Meta-Control-h: backward-kill-word Text after the function name is ignored 4597 4598 # 4599 # Arrow keys in keypad mode 4600 # 4601 #"\M-OD": backward-char 4602 #"\M-OC": forward-char 4603 #"\M-OA": previous-history 4604 #"\M-OB": next-history 4605 # 4606 # Arrow keys in ANSI mode 4607 # 4608 "\M-[D": backward-char 4609 "\M-[C": forward-char 4610 "\M-[A": previous-history 4611 "\M-[B": next-history 4612 # 4613 # Arrow keys in 8 bit keypad mode 4614 # 4615 #"\M-\C-OD": backward-char 4616 #"\M-\C-OC": forward-char 4617 #"\M-\C-OA": previous-history 4618 #"\M-\C-OB": next-history 4619 # 4620 # Arrow keys in 8 bit ANSI mode 4621 # 4622 #"\M-\C-[D": backward-char 4623 #"\M-\C-[C": forward-char 4624 #"\M-\C-[A": previous-history 4625 #"\M-\C-[B": next-history 4626 4627 C-q: quoted-insert 4628 4629 $endif 4630 4631 # An old-style binding. This happens to be the default. 4632 TAB: complete 4633 4634 # Macros that are convenient for shell interaction 4635 $if Bash 4636 # edit the path 4637 "\C-xp": "PATH=${PATH}\e\C-e\C-a\ef\C-f" 4638 # prepare to type a quoted word -- 4639 # insert open and close double quotes 4640 # and move to just after the open quote 4641 "\C-x\"": "\"\"\C-b" 4642 # insert a backslash (testing backslash escapes 4643 # in sequences and macros) 4644 "\C-x\\": "\\" 4645 # Quote the current or previous word 4646 "\C-xq": "\eb\"\ef\"" 4647 # Add a binding to refresh the line, which is unbound 4648 "\C-xr": redraw-current-line 4649 # Edit variable on current line. 4650 "\M-\C-v": "\C-a\C-k$\C-y\M-\C-e\C-a\C-y=" 4651 $endif 4652 4653 # use a visible bell if one is available 4654 set bell-style visible 4655 4656 # don't strip characters to 7 bits when reading 4657 set input-meta on 4658 4659 # allow iso-latin1 characters to be inserted rather 4660 # than converted to prefix-meta sequences 4661 set convert-meta off 4662 4663 # display characters with the eighth bit set directly 4664 # rather than as meta-prefixed characters 4665 set output-meta on 4666 4667 # if there are more than 150 possible completions for 4668 # a word, ask the user if he wants to see all of them 4669 set completion-query-items 150 4670 4671 # For FTP 4672 $if Ftp 4673 "\C-xg": "get \M-?" 4674 "\C-xt": "put \M-?" 4675 "\M-.": yank-last-arg 4676 $endif 4677 4678 4679File: gdb.info, Node: Bindable Readline Commands, Next: Readline vi Mode, Prev: Readline Init File, Up: Command Line Editing 4680 468131.4 Bindable Readline Commands 4682=============================== 4683 4684* Menu: 4685 4686* Commands For Moving:: Moving about the line. 4687* Commands For History:: Getting at previous lines. 4688* Commands For Text:: Commands for changing text. 4689* Commands For Killing:: Commands for killing and yanking. 4690* Numeric Arguments:: Specifying numeric arguments, repeat counts. 4691* Commands For Completion:: Getting Readline to do the typing for you. 4692* Keyboard Macros:: Saving and re-executing typed characters 4693* Miscellaneous Commands:: Other miscellaneous commands. 4694 4695 This section describes Readline commands that may be bound to key 4696sequences. Command names without an accompanying key sequence are 4697unbound by default. 4698 4699 In the following descriptions, "point" refers to the current cursor 4700position, and "mark" refers to a cursor position saved by the 4701`set-mark' command. The text between the point and mark is referred to 4702as the "region". 4703 4704 4705File: gdb.info, Node: Commands For Moving, Next: Commands For History, Up: Bindable Readline Commands 4706 470731.4.1 Commands For Moving 4708-------------------------- 4709 4710`beginning-of-line (C-a)' 4711 Move to the start of the current line. 4712 4713`end-of-line (C-e)' 4714 Move to the end of the line. 4715 4716`forward-char (C-f)' 4717 Move forward a character. 4718 4719`backward-char (C-b)' 4720 Move back a character. 4721 4722`forward-word (M-f)' 4723 Move forward to the end of the next word. Words are composed of 4724 letters and digits. 4725 4726`backward-word (M-b)' 4727 Move back to the start of the current or previous word. Words are 4728 composed of letters and digits. 4729 4730`clear-screen (C-l)' 4731 Clear the screen and redraw the current line, leaving the current 4732 line at the top of the screen. 4733 4734`redraw-current-line ()' 4735 Refresh the current line. By default, this is unbound. 4736 4737 4738 4739File: gdb.info, Node: Commands For History, Next: Commands For Text, Prev: Commands For Moving, Up: Bindable Readline Commands 4740 474131.4.2 Commands For Manipulating The History 4742-------------------------------------------- 4743 4744`accept-line (Newline or Return)' 4745 Accept the line regardless of where the cursor is. If this line is 4746 non-empty, it may be added to the history list for future recall 4747 with `add_history()'. If this line is a modified history line, 4748 the history line is restored to its original state. 4749 4750`previous-history (C-p)' 4751 Move `back' through the history list, fetching the previous 4752 command. 4753 4754`next-history (C-n)' 4755 Move `forward' through the history list, fetching the next command. 4756 4757`beginning-of-history (M-<)' 4758 Move to the first line in the history. 4759 4760`end-of-history (M->)' 4761 Move to the end of the input history, i.e., the line currently 4762 being entered. 4763 4764`reverse-search-history (C-r)' 4765 Search backward starting at the current line and moving `up' 4766 through the history as necessary. This is an incremental search. 4767 4768`forward-search-history (C-s)' 4769 Search forward starting at the current line and moving `down' 4770 through the the history as necessary. This is an incremental 4771 search. 4772 4773`non-incremental-reverse-search-history (M-p)' 4774 Search backward starting at the current line and moving `up' 4775 through the history as necessary using a non-incremental search 4776 for a string supplied by the user. 4777 4778`non-incremental-forward-search-history (M-n)' 4779 Search forward starting at the current line and moving `down' 4780 through the the history as necessary using a non-incremental search 4781 for a string supplied by the user. 4782 4783`history-search-forward ()' 4784 Search forward through the history for the string of characters 4785 between the start of the current line and the point. This is a 4786 non-incremental search. By default, this command is unbound. 4787 4788`history-search-backward ()' 4789 Search backward through the history for the string of characters 4790 between the start of the current line and the point. This is a 4791 non-incremental search. By default, this command is unbound. 4792 4793`yank-nth-arg (M-C-y)' 4794 Insert the first argument to the previous command (usually the 4795 second word on the previous line) at point. With an argument N, 4796 insert the Nth word from the previous command (the words in the 4797 previous command begin with word 0). A negative argument inserts 4798 the Nth word from the end of the previous command. Once the 4799 argument N is computed, the argument is extracted as if the `!N' 4800 history expansion had been specified. 4801 4802`yank-last-arg (M-. or M-_)' 4803 Insert last argument to the previous command (the last word of the 4804 previous history entry). With an argument, behave exactly like 4805 `yank-nth-arg'. Successive calls to `yank-last-arg' move back 4806 through the history list, inserting the last argument of each line 4807 in turn. The history expansion facilities are used to extract the 4808 last argument, as if the `!$' history expansion had been specified. 4809 4810 4811 4812File: gdb.info, Node: Commands For Text, Next: Commands For Killing, Prev: Commands For History, Up: Bindable Readline Commands 4813 481431.4.3 Commands For Changing Text 4815--------------------------------- 4816 4817`delete-char (C-d)' 4818 Delete the character at point. If point is at the beginning of 4819 the line, there are no characters in the line, and the last 4820 character typed was not bound to `delete-char', then return EOF. 4821 4822`backward-delete-char (Rubout)' 4823 Delete the character behind the cursor. A numeric argument means 4824 to kill the characters instead of deleting them. 4825 4826`forward-backward-delete-char ()' 4827 Delete the character under the cursor, unless the cursor is at the 4828 end of the line, in which case the character behind the cursor is 4829 deleted. By default, this is not bound to a key. 4830 4831`quoted-insert (C-q or C-v)' 4832 Add the next character typed to the line verbatim. This is how to 4833 insert key sequences like `C-q', for example. 4834 4835`tab-insert (M-<TAB>)' 4836 Insert a tab character. 4837 4838`self-insert (a, b, A, 1, !, ...)' 4839 Insert yourself. 4840 4841`transpose-chars (C-t)' 4842 Drag the character before the cursor forward over the character at 4843 the cursor, moving the cursor forward as well. If the insertion 4844 point is at the end of the line, then this transposes the last two 4845 characters of the line. Negative arguments have no effect. 4846 4847`transpose-words (M-t)' 4848 Drag the word before point past the word after point, moving point 4849 past that word as well. If the insertion point is at the end of 4850 the line, this transposes the last two words on the line. 4851 4852`upcase-word (M-u)' 4853 Uppercase the current (or following) word. With a negative 4854 argument, uppercase the previous word, but do not move the cursor. 4855 4856`downcase-word (M-l)' 4857 Lowercase the current (or following) word. With a negative 4858 argument, lowercase the previous word, but do not move the cursor. 4859 4860`capitalize-word (M-c)' 4861 Capitalize the current (or following) word. With a negative 4862 argument, capitalize the previous word, but do not move the cursor. 4863 4864`overwrite-mode ()' 4865 Toggle overwrite mode. With an explicit positive numeric argument, 4866 switches to overwrite mode. With an explicit non-positive numeric 4867 argument, switches to insert mode. This command affects only 4868 `emacs' mode; `vi' mode does overwrite differently. Each call to 4869 `readline()' starts in insert mode. 4870 4871 In overwrite mode, characters bound to `self-insert' replace the 4872 text at point rather than pushing the text to the right. 4873 Characters bound to `backward-delete-char' replace the character 4874 before point with a space. 4875 4876 By default, this command is unbound. 4877 4878 4879 4880File: gdb.info, Node: Commands For Killing, Next: Numeric Arguments, Prev: Commands For Text, Up: Bindable Readline Commands 4881 488231.4.4 Killing And Yanking 4883-------------------------- 4884 4885`kill-line (C-k)' 4886 Kill the text from point to the end of the line. 4887 4888`backward-kill-line (C-x Rubout)' 4889 Kill backward to the beginning of the line. 4890 4891`unix-line-discard (C-u)' 4892 Kill backward from the cursor to the beginning of the current line. 4893 4894`kill-whole-line ()' 4895 Kill all characters on the current line, no matter where point is. 4896 By default, this is unbound. 4897 4898`kill-word (M-d)' 4899 Kill from point to the end of the current word, or if between 4900 words, to the end of the next word. Word boundaries are the same 4901 as `forward-word'. 4902 4903`backward-kill-word (M-<DEL>)' 4904 Kill the word behind point. Word boundaries are the same as 4905 `backward-word'. 4906 4907`unix-word-rubout (C-w)' 4908 Kill the word behind point, using white space as a word boundary. 4909 The killed text is saved on the kill-ring. 4910 4911`unix-filename-rubout ()' 4912 Kill the word behind point, using white space and the slash 4913 character as the word boundaries. The killed text is saved on the 4914 kill-ring. 4915 4916`delete-horizontal-space ()' 4917 Delete all spaces and tabs around point. By default, this is 4918 unbound. 4919 4920`kill-region ()' 4921 Kill the text in the current region. By default, this command is 4922 unbound. 4923 4924`copy-region-as-kill ()' 4925 Copy the text in the region to the kill buffer, so it can be yanked 4926 right away. By default, this command is unbound. 4927 4928`copy-backward-word ()' 4929 Copy the word before point to the kill buffer. The word 4930 boundaries are the same as `backward-word'. By default, this 4931 command is unbound. 4932 4933`copy-forward-word ()' 4934 Copy the word following point to the kill buffer. The word 4935 boundaries are the same as `forward-word'. By default, this 4936 command is unbound. 4937 4938`yank (C-y)' 4939 Yank the top of the kill ring into the buffer at point. 4940 4941`yank-pop (M-y)' 4942 Rotate the kill-ring, and yank the new top. You can only do this 4943 if the prior command is `yank' or `yank-pop'. 4944 4945 4946File: gdb.info, Node: Numeric Arguments, Next: Commands For Completion, Prev: Commands For Killing, Up: Bindable Readline Commands 4947 494831.4.5 Specifying Numeric Arguments 4949----------------------------------- 4950 4951`digit-argument (M-0, M-1, ... M--)' 4952 Add this digit to the argument already accumulating, or start a new 4953 argument. `M--' starts a negative argument. 4954 4955`universal-argument ()' 4956 This is another way to specify an argument. If this command is 4957 followed by one or more digits, optionally with a leading minus 4958 sign, those digits define the argument. If the command is 4959 followed by digits, executing `universal-argument' again ends the 4960 numeric argument, but is otherwise ignored. As a special case, if 4961 this command is immediately followed by a character that is 4962 neither a digit or minus sign, the argument count for the next 4963 command is multiplied by four. The argument count is initially 4964 one, so executing this function the first time makes the argument 4965 count four, a second time makes the argument count sixteen, and so 4966 on. By default, this is not bound to a key. 4967 4968 4969File: gdb.info, Node: Commands For Completion, Next: Keyboard Macros, Prev: Numeric Arguments, Up: Bindable Readline Commands 4970 497131.4.6 Letting Readline Type For You 4972------------------------------------ 4973 4974`complete (<TAB>)' 4975 Attempt to perform completion on the text before point. The 4976 actual completion performed is application-specific. The default 4977 is filename completion. 4978 4979`possible-completions (M-?)' 4980 List the possible completions of the text before point. 4981 4982`insert-completions (M-*)' 4983 Insert all completions of the text before point that would have 4984 been generated by `possible-completions'. 4985 4986`menu-complete ()' 4987 Similar to `complete', but replaces the word to be completed with 4988 a single match from the list of possible completions. Repeated 4989 execution of `menu-complete' steps through the list of possible 4990 completions, inserting each match in turn. At the end of the list 4991 of completions, the bell is rung (subject to the setting of 4992 `bell-style') and the original text is restored. An argument of N 4993 moves N positions forward in the list of matches; a negative 4994 argument may be used to move backward through the list. This 4995 command is intended to be bound to <TAB>, but is unbound by 4996 default. 4997 4998`delete-char-or-list ()' 4999 Deletes the character under the cursor if not at the beginning or 5000 end of the line (like `delete-char'). If at the end of the line, 5001 behaves identically to `possible-completions'. This command is 5002 unbound by default. 5003 5004 5005 5006File: gdb.info, Node: Keyboard Macros, Next: Miscellaneous Commands, Prev: Commands For Completion, Up: Bindable Readline Commands 5007 500831.4.7 Keyboard Macros 5009---------------------- 5010 5011`start-kbd-macro (C-x ()' 5012 Begin saving the characters typed into the current keyboard macro. 5013 5014`end-kbd-macro (C-x ))' 5015 Stop saving the characters typed into the current keyboard macro 5016 and save the definition. 5017 5018`call-last-kbd-macro (C-x e)' 5019 Re-execute the last keyboard macro defined, by making the 5020 characters in the macro appear as if typed at the keyboard. 5021 5022 5023 5024File: gdb.info, Node: Miscellaneous Commands, Prev: Keyboard Macros, Up: Bindable Readline Commands 5025 502631.4.8 Some Miscellaneous Commands 5027---------------------------------- 5028 5029`re-read-init-file (C-x C-r)' 5030 Read in the contents of the INPUTRC file, and incorporate any 5031 bindings or variable assignments found there. 5032 5033`abort (C-g)' 5034 Abort the current editing command and ring the terminal's bell 5035 (subject to the setting of `bell-style'). 5036 5037`do-uppercase-version (M-a, M-b, M-X, ...)' 5038 If the metafied character X is lowercase, run the command that is 5039 bound to the corresponding uppercase character. 5040 5041`prefix-meta (<ESC>)' 5042 Metafy the next character typed. This is for keyboards without a 5043 meta key. Typing `<ESC> f' is equivalent to typing `M-f'. 5044 5045`undo (C-_ or C-x C-u)' 5046 Incremental undo, separately remembered for each line. 5047 5048`revert-line (M-r)' 5049 Undo all changes made to this line. This is like executing the 5050 `undo' command enough times to get back to the beginning. 5051 5052`tilde-expand (M-~)' 5053 Perform tilde expansion on the current word. 5054 5055`set-mark (C-@)' 5056 Set the mark to the point. If a numeric argument is supplied, the 5057 mark is set to that position. 5058 5059`exchange-point-and-mark (C-x C-x)' 5060 Swap the point with the mark. The current cursor position is set 5061 to the saved position, and the old cursor position is saved as the 5062 mark. 5063 5064`character-search (C-])' 5065 A character is read and point is moved to the next occurrence of 5066 that character. A negative count searches for previous 5067 occurrences. 5068 5069`character-search-backward (M-C-])' 5070 A character is read and point is moved to the previous occurrence 5071 of that character. A negative count searches for subsequent 5072 occurrences. 5073 5074`insert-comment (M-#)' 5075 Without a numeric argument, the value of the `comment-begin' 5076 variable is inserted at the beginning of the current line. If a 5077 numeric argument is supplied, this command acts as a toggle: if 5078 the characters at the beginning of the line do not match the value 5079 of `comment-begin', the value is inserted, otherwise the 5080 characters in `comment-begin' are deleted from the beginning of 5081 the line. In either case, the line is accepted as if a newline 5082 had been typed. 5083 5084`dump-functions ()' 5085 Print all of the functions and their key bindings to the Readline 5086 output stream. If a numeric argument is supplied, the output is 5087 formatted in such a way that it can be made part of an INPUTRC 5088 file. This command is unbound by default. 5089 5090`dump-variables ()' 5091 Print all of the settable variables and their values to the 5092 Readline output stream. If a numeric argument is supplied, the 5093 output is formatted in such a way that it can be made part of an 5094 INPUTRC file. This command is unbound by default. 5095 5096`dump-macros ()' 5097 Print all of the Readline key sequences bound to macros and the 5098 strings they output. If a numeric argument is supplied, the 5099 output is formatted in such a way that it can be made part of an 5100 INPUTRC file. This command is unbound by default. 5101 5102`emacs-editing-mode (C-e)' 5103 When in `vi' command mode, this causes a switch to `emacs' editing 5104 mode. 5105 5106`vi-editing-mode (M-C-j)' 5107 When in `emacs' editing mode, this causes a switch to `vi' editing 5108 mode. 5109 5110 5111 5112File: gdb.info, Node: Readline vi Mode, Prev: Bindable Readline Commands, Up: Command Line Editing 5113 511431.5 Readline vi Mode 5115===================== 5116 5117While the Readline library does not have a full set of `vi' editing 5118functions, it does contain enough to allow simple editing of the line. 5119The Readline `vi' mode behaves as specified in the POSIX 1003.2 5120standard. 5121 5122 In order to switch interactively between `emacs' and `vi' editing 5123modes, use the command `M-C-j' (bound to emacs-editing-mode when in 5124`vi' mode and to vi-editing-mode in `emacs' mode). The Readline 5125default is `emacs' mode. 5126 5127 When you enter a line in `vi' mode, you are already placed in 5128`insertion' mode, as if you had typed an `i'. Pressing <ESC> switches 5129you into `command' mode, where you can edit the text of the line with 5130the standard `vi' movement keys, move to previous history lines with 5131`k' and subsequent lines with `j', and so forth. 5132 5133 5134File: gdb.info, Node: Using History Interactively, Next: In Memoriam, Prev: Command Line Editing, Up: Top 5135 513632 Using History Interactively 5137****************************** 5138 5139This chapter describes how to use the GNU History Library interactively, 5140from a user's standpoint. It should be considered a user's guide. For 5141information on using the GNU History Library in other programs, see the 5142GNU Readline Library Manual. 5143 5144* Menu: 5145 5146* History Interaction:: What it feels like using History as a user. 5147 5148 5149File: gdb.info, Node: History Interaction, Up: Using History Interactively 5150 515132.1 History Expansion 5152====================== 5153 5154The History library provides a history expansion feature that is similar 5155to the history expansion provided by `csh'. This section describes the 5156syntax used to manipulate the history information. 5157 5158 History expansions introduce words from the history list into the 5159input stream, making it easy to repeat commands, insert the arguments 5160to a previous command into the current input line, or fix errors in 5161previous commands quickly. 5162 5163 History expansion takes place in two parts. The first is to 5164determine which line from the history list should be used during 5165substitution. The second is to select portions of that line for 5166inclusion into the current one. The line selected from the history is 5167called the "event", and the portions of that line that are acted upon 5168are called "words". Various "modifiers" are available to manipulate 5169the selected words. The line is broken into words in the same fashion 5170that Bash does, so that several words surrounded by quotes are 5171considered one word. History expansions are introduced by the 5172appearance of the history expansion character, which is `!' by default. 5173 5174* Menu: 5175 5176* Event Designators:: How to specify which history line to use. 5177* Word Designators:: Specifying which words are of interest. 5178* Modifiers:: Modifying the results of substitution. 5179 5180 5181File: gdb.info, Node: Event Designators, Next: Word Designators, Up: History Interaction 5182 518332.1.1 Event Designators 5184------------------------ 5185 5186An event designator is a reference to a command line entry in the 5187history list. 5188 5189`!' 5190 Start a history substitution, except when followed by a space, tab, 5191 the end of the line, or `='. 5192 5193`!N' 5194 Refer to command line N. 5195 5196`!-N' 5197 Refer to the command N lines back. 5198 5199`!!' 5200 Refer to the previous command. This is a synonym for `!-1'. 5201 5202`!STRING' 5203 Refer to the most recent command starting with STRING. 5204 5205`!?STRING[?]' 5206 Refer to the most recent command containing STRING. The trailing 5207 `?' may be omitted if the STRING is followed immediately by a 5208 newline. 5209 5210`^STRING1^STRING2^' 5211 Quick Substitution. Repeat the last command, replacing STRING1 5212 with STRING2. Equivalent to `!!:s/STRING1/STRING2/'. 5213 5214`!#' 5215 The entire command line typed so far. 5216 5217 5218 5219File: gdb.info, Node: Word Designators, Next: Modifiers, Prev: Event Designators, Up: History Interaction 5220 522132.1.2 Word Designators 5222----------------------- 5223 5224Word designators are used to select desired words from the event. A 5225`:' separates the event specification from the word designator. It may 5226be omitted if the word designator begins with a `^', `$', `*', `-', or 5227`%'. Words are numbered from the beginning of the line, with the first 5228word being denoted by 0 (zero). Words are inserted into the current 5229line separated by single spaces. 5230 5231 For example, 5232 5233`!!' 5234 designates the preceding command. When you type this, the 5235 preceding command is repeated in toto. 5236 5237`!!:$' 5238 designates the last argument of the preceding command. This may be 5239 shortened to `!$'. 5240 5241`!fi:2' 5242 designates the second argument of the most recent command starting 5243 with the letters `fi'. 5244 5245 Here are the word designators: 5246 5247`0 (zero)' 5248 The `0'th word. For many applications, this is the command word. 5249 5250`N' 5251 The Nth word. 5252 5253`^' 5254 The first argument; that is, word 1. 5255 5256`$' 5257 The last argument. 5258 5259`%' 5260 The word matched by the most recent `?STRING?' search. 5261 5262`X-Y' 5263 A range of words; `-Y' abbreviates `0-Y'. 5264 5265`*' 5266 All of the words, except the `0'th. This is a synonym for `1-$'. 5267 It is not an error to use `*' if there is just one word in the 5268 event; the empty string is returned in that case. 5269 5270`X*' 5271 Abbreviates `X-$' 5272 5273`X-' 5274 Abbreviates `X-$' like `X*', but omits the last word. 5275 5276 5277 If a word designator is supplied without an event specification, the 5278previous command is used as the event. 5279 5280 5281File: gdb.info, Node: Modifiers, Prev: Word Designators, Up: History Interaction 5282 528332.1.3 Modifiers 5284---------------- 5285 5286After the optional word designator, you can add a sequence of one or 5287more of the following modifiers, each preceded by a `:'. 5288 5289`h' 5290 Remove a trailing pathname component, leaving only the head. 5291 5292`t' 5293 Remove all leading pathname components, leaving the tail. 5294 5295`r' 5296 Remove a trailing suffix of the form `.SUFFIX', leaving the 5297 basename. 5298 5299`e' 5300 Remove all but the trailing suffix. 5301 5302`p' 5303 Print the new command but do not execute it. 5304 5305`s/OLD/NEW/' 5306 Substitute NEW for the first occurrence of OLD in the event line. 5307 Any delimiter may be used in place of `/'. The delimiter may be 5308 quoted in OLD and NEW with a single backslash. If `&' appears in 5309 NEW, it is replaced by OLD. A single backslash will quote the 5310 `&'. The final delimiter is optional if it is the last character 5311 on the input line. 5312 5313`&' 5314 Repeat the previous substitution. 5315 5316`g' 5317`a' 5318 Cause changes to be applied over the entire event line. Used in 5319 conjunction with `s', as in `gs/OLD/NEW/', or with `&'. 5320 5321`G' 5322 Apply the following `s' modifier once to each word in the event. 5323 5324 5325 5326File: gdb.info, Node: In Memoriam, Next: Formatting Documentation, Prev: Using History Interactively, Up: Top 5327 5328Appendix A In Memoriam 5329********************** 5330 5331The GDB project mourns the loss of the following long-time contributors: 5332 5333`Fred Fish' 5334 Fred was a long-standing contributor to GDB (1991-2006), and to 5335 Free Software in general. Outside of GDB, he was known in the 5336 Amiga world for his series of Fish Disks, and the GeekGadget 5337 project. 5338 5339`Michael Snyder' 5340 Michael was one of the Global Maintainers of the GDB project, with 5341 contributions recorded as early as 1996, until 2011. In addition 5342 to his day to day participation, he was a large driving force 5343 behind adding Reverse Debugging to GDB. 5344 5345 Beyond their technical contributions to the project, they were also 5346enjoyable members of the Free Software Community. We will miss them. 5347 5348 5349File: gdb.info, Node: Formatting Documentation, Next: Installing GDB, Prev: In Memoriam, Up: Top 5350 5351Appendix B Formatting Documentation 5352*********************************** 5353 5354The GDB 4 release includes an already-formatted reference card, ready 5355for printing with PostScript or Ghostscript, in the `gdb' subdirectory 5356of the main source directory(1). If you can use PostScript or 5357Ghostscript with your printer, you can print the reference card 5358immediately with `refcard.ps'. 5359 5360 The release also includes the source for the reference card. You 5361can format it, using TeX, by typing: 5362 5363 make refcard.dvi 5364 5365 The GDB reference card is designed to print in "landscape" mode on 5366US "letter" size paper; that is, on a sheet 11 inches wide by 8.5 inches 5367high. You will need to specify this form of printing as an option to 5368your DVI output program. 5369 5370 All the documentation for GDB comes as part of the machine-readable 5371distribution. The documentation is written in Texinfo format, which is 5372a documentation system that uses a single source file to produce both 5373on-line information and a printed manual. You can use one of the Info 5374formatting commands to create the on-line version of the documentation 5375and TeX (or `texi2roff') to typeset the printed version. 5376 5377 GDB includes an already formatted copy of the on-line Info version 5378of this manual in the `gdb' subdirectory. The main Info file is 5379`gdb-7.3.1/gdb/gdb.info', and it refers to subordinate files matching 5380`gdb.info*' in the same directory. If necessary, you can print out 5381these files, or read them with any editor; but they are easier to read 5382using the `info' subsystem in GNU Emacs or the standalone `info' 5383program, available as part of the GNU Texinfo distribution. 5384 5385 If you want to format these Info files yourself, you need one of the 5386Info formatting programs, such as `texinfo-format-buffer' or `makeinfo'. 5387 5388 If you have `makeinfo' installed, and are in the top level GDB 5389source directory (`gdb-7.3.1', in the case of version 7.3.1), you can 5390make the Info file by typing: 5391 5392 cd gdb 5393 make gdb.info 5394 5395 If you want to typeset and print copies of this manual, you need TeX, 5396a program to print its DVI output files, and `texinfo.tex', the Texinfo 5397definitions file. 5398 5399 TeX is a typesetting program; it does not print files directly, but 5400produces output files called DVI files. To print a typeset document, 5401you need a program to print DVI files. If your system has TeX 5402installed, chances are it has such a program. The precise command to 5403use depends on your system; `lpr -d' is common; another (for PostScript 5404devices) is `dvips'. The DVI print command may require a file name 5405without any extension or a `.dvi' extension. 5406 5407 TeX also requires a macro definitions file called `texinfo.tex'. 5408This file tells TeX how to typeset a document written in Texinfo 5409format. On its own, TeX cannot either read or typeset a Texinfo file. 5410`texinfo.tex' is distributed with GDB and is located in the 5411`gdb-VERSION-NUMBER/texinfo' directory. 5412 5413 If you have TeX and a DVI printer program installed, you can typeset 5414and print this manual. First switch to the `gdb' subdirectory of the 5415main source directory (for example, to `gdb-7.3.1/gdb') and type: 5416 5417 make gdb.dvi 5418 5419 Then give `gdb.dvi' to your DVI printing program. 5420 5421 ---------- Footnotes ---------- 5422 5423 (1) In `gdb-7.3.1/gdb/refcard.ps' of the version 7.3.1 release. 5424 5425 5426File: gdb.info, Node: Installing GDB, Next: Maintenance Commands, Prev: Formatting Documentation, Up: Top 5427 5428Appendix C Installing GDB 5429************************* 5430 5431* Menu: 5432 5433* Requirements:: Requirements for building GDB 5434* Running Configure:: Invoking the GDB `configure' script 5435* Separate Objdir:: Compiling GDB in another directory 5436* Config Names:: Specifying names for hosts and targets 5437* Configure Options:: Summary of options for configure 5438* System-wide configuration:: Having a system-wide init file 5439 5440 5441File: gdb.info, Node: Requirements, Next: Running Configure, Up: Installing GDB 5442 5443C.1 Requirements for Building GDB 5444================================= 5445 5446Building GDB requires various tools and packages to be available. 5447Other packages will be used only if they are found. 5448 5449Tools/Packages Necessary for Building GDB 5450========================================= 5451 5452ISO C90 compiler 5453 GDB is written in ISO C90. It should be buildable with any 5454 working C90 compiler, e.g. GCC. 5455 5456 5457Tools/Packages Optional for Building GDB 5458======================================== 5459 5460Expat 5461 GDB can use the Expat XML parsing library. This library may be 5462 included with your operating system distribution; if it is not, you 5463 can get the latest version from `http://expat.sourceforge.net'. 5464 The `configure' script will search for this library in several 5465 standard locations; if it is installed in an unusual path, you can 5466 use the `--with-libexpat-prefix' option to specify its location. 5467 5468 Expat is used for: 5469 5470 * Remote protocol memory maps (*note Memory Map Format::) 5471 5472 * Target descriptions (*note Target Descriptions::) 5473 5474 * Remote shared library lists (*note Library List Format::) 5475 5476 * MS-Windows shared libraries (*note Shared Libraries::) 5477 5478 * Traceframe info (*note Traceframe Info Format::) 5479 5480zlib 5481 GDB will use the `zlib' library, if available, to read compressed 5482 debug sections. Some linkers, such as GNU gold, are capable of 5483 producing binaries with compressed debug sections. If GDB is 5484 compiled with `zlib', it will be able to read the debug 5485 information in such binaries. 5486 5487 The `zlib' library is likely included with your operating system 5488 distribution; if it is not, you can get the latest version from 5489 `http://zlib.net'. 5490 5491iconv 5492 GDB's features related to character sets (*note Character Sets::) 5493 require a functioning `iconv' implementation. If you are on a GNU 5494 system, then this is provided by the GNU C Library. Some other 5495 systems also provide a working `iconv'. 5496 5497 On systems with `iconv', you can install GNU Libiconv. If you 5498 have previously installed Libiconv, you can use the 5499 `--with-libiconv-prefix' option to configure. 5500 5501 GDB's top-level `configure' and `Makefile' will arrange to build 5502 Libiconv if a directory named `libiconv' appears in the top-most 5503 source directory. If Libiconv is built this way, and if the 5504 operating system does not provide a suitable `iconv' 5505 implementation, then the just-built library will automatically be 5506 used by GDB. One easy way to set this up is to download GNU 5507 Libiconv, unpack it, and then rename the directory holding the 5508 Libiconv source code to `libiconv'. 5509 5510 5511File: gdb.info, Node: Running Configure, Next: Separate Objdir, Prev: Requirements, Up: Installing GDB 5512 5513C.2 Invoking the GDB `configure' Script 5514======================================= 5515 5516GDB comes with a `configure' script that automates the process of 5517preparing GDB for installation; you can then use `make' to build the 5518`gdb' program. 5519 5520 The GDB distribution includes all the source code you need for GDB 5521in a single directory, whose name is usually composed by appending the 5522version number to `gdb'. 5523 5524 For example, the GDB version 7.3.1 distribution is in the 5525`gdb-7.3.1' directory. That directory contains: 5526 5527`gdb-7.3.1/configure (and supporting files)' 5528 script for configuring GDB and all its supporting libraries 5529 5530`gdb-7.3.1/gdb' 5531 the source specific to GDB itself 5532 5533`gdb-7.3.1/bfd' 5534 source for the Binary File Descriptor library 5535 5536`gdb-7.3.1/include' 5537 GNU include files 5538 5539`gdb-7.3.1/libiberty' 5540 source for the `-liberty' free software library 5541 5542`gdb-7.3.1/opcodes' 5543 source for the library of opcode tables and disassemblers 5544 5545`gdb-7.3.1/readline' 5546 source for the GNU command-line interface 5547 5548`gdb-7.3.1/glob' 5549 source for the GNU filename pattern-matching subroutine 5550 5551`gdb-7.3.1/mmalloc' 5552 source for the GNU memory-mapped malloc package 5553 5554 The simplest way to configure and build GDB is to run `configure' 5555from the `gdb-VERSION-NUMBER' source directory, which in this example 5556is the `gdb-7.3.1' directory. 5557 5558 First switch to the `gdb-VERSION-NUMBER' source directory if you are 5559not already in it; then run `configure'. Pass the identifier for the 5560platform on which GDB will run as an argument. 5561 5562 For example: 5563 5564 cd gdb-7.3.1 5565 ./configure HOST 5566 make 5567 5568where HOST is an identifier such as `sun4' or `decstation', that 5569identifies the platform where GDB will run. (You can often leave off 5570HOST; `configure' tries to guess the correct value by examining your 5571system.) 5572 5573 Running `configure HOST' and then running `make' builds the `bfd', 5574`readline', `mmalloc', and `libiberty' libraries, then `gdb' itself. 5575The configured source files, and the binaries, are left in the 5576corresponding source directories. 5577 5578 `configure' is a Bourne-shell (`/bin/sh') script; if your system 5579does not recognize this automatically when you run a different shell, 5580you may need to run `sh' on it explicitly: 5581 5582 sh configure HOST 5583 5584 If you run `configure' from a directory that contains source 5585directories for multiple libraries or programs, such as the `gdb-7.3.1' 5586source directory for version 7.3.1, `configure' creates configuration 5587files for every directory level underneath (unless you tell it not to, 5588with the `--norecursion' option). 5589 5590 You should run the `configure' script from the top directory in the 5591source tree, the `gdb-VERSION-NUMBER' directory. If you run 5592`configure' from one of the subdirectories, you will configure only 5593that subdirectory. That is usually not what you want. In particular, 5594if you run the first `configure' from the `gdb' subdirectory of the 5595`gdb-VERSION-NUMBER' directory, you will omit the configuration of 5596`bfd', `readline', and other sibling directories of the `gdb' 5597subdirectory. This leads to build errors about missing include files 5598such as `bfd/bfd.h'. 5599 5600 You can install `gdb' anywhere; it has no hardwired paths. However, 5601you should make sure that the shell on your path (named by the `SHELL' 5602environment variable) is publicly readable. Remember that GDB uses the 5603shell to start your program--some systems refuse to let GDB debug child 5604processes whose programs are not readable. 5605 5606 5607File: gdb.info, Node: Separate Objdir, Next: Config Names, Prev: Running Configure, Up: Installing GDB 5608 5609C.3 Compiling GDB in Another Directory 5610====================================== 5611 5612If you want to run GDB versions for several host or target machines, 5613you need a different `gdb' compiled for each combination of host and 5614target. `configure' is designed to make this easy by allowing you to 5615generate each configuration in a separate subdirectory, rather than in 5616the source directory. If your `make' program handles the `VPATH' 5617feature (GNU `make' does), running `make' in each of these directories 5618builds the `gdb' program specified there. 5619 5620 To build `gdb' in a separate directory, run `configure' with the 5621`--srcdir' option to specify where to find the source. (You also need 5622to specify a path to find `configure' itself from your working 5623directory. If the path to `configure' would be the same as the 5624argument to `--srcdir', you can leave out the `--srcdir' option; it is 5625assumed.) 5626 5627 For example, with version 7.3.1, you can build GDB in a separate 5628directory for a Sun 4 like this: 5629 5630 cd gdb-7.3.1 5631 mkdir ../gdb-sun4 5632 cd ../gdb-sun4 5633 ../gdb-7.3.1/configure sun4 5634 make 5635 5636 When `configure' builds a configuration using a remote source 5637directory, it creates a tree for the binaries with the same structure 5638(and using the same names) as the tree under the source directory. In 5639the example, you'd find the Sun 4 library `libiberty.a' in the 5640directory `gdb-sun4/libiberty', and GDB itself in `gdb-sun4/gdb'. 5641 5642 Make sure that your path to the `configure' script has just one 5643instance of `gdb' in it. If your path to `configure' looks like 5644`../gdb-7.3.1/gdb/configure', you are configuring only one subdirectory 5645of GDB, not the whole package. This leads to build errors about 5646missing include files such as `bfd/bfd.h'. 5647 5648 One popular reason to build several GDB configurations in separate 5649directories is to configure GDB for cross-compiling (where GDB runs on 5650one machine--the "host"--while debugging programs that run on another 5651machine--the "target"). You specify a cross-debugging target by giving 5652the `--target=TARGET' option to `configure'. 5653 5654 When you run `make' to build a program or library, you must run it 5655in a configured directory--whatever directory you were in when you 5656called `configure' (or one of its subdirectories). 5657 5658 The `Makefile' that `configure' generates in each source directory 5659also runs recursively. If you type `make' in a source directory such 5660as `gdb-7.3.1' (or in a separate configured directory configured with 5661`--srcdir=DIRNAME/gdb-7.3.1'), you will build all the required 5662libraries, and then build GDB. 5663 5664 When you have multiple hosts or targets configured in separate 5665directories, you can run `make' on them in parallel (for example, if 5666they are NFS-mounted on each of the hosts); they will not interfere 5667with each other. 5668 5669 5670File: gdb.info, Node: Config Names, Next: Configure Options, Prev: Separate Objdir, Up: Installing GDB 5671 5672C.4 Specifying Names for Hosts and Targets 5673========================================== 5674 5675The specifications used for hosts and targets in the `configure' script 5676are based on a three-part naming scheme, but some short predefined 5677aliases are also supported. The full naming scheme encodes three pieces 5678of information in the following pattern: 5679 5680 ARCHITECTURE-VENDOR-OS 5681 5682 For example, you can use the alias `sun4' as a HOST argument, or as 5683the value for TARGET in a `--target=TARGET' option. The equivalent 5684full name is `sparc-sun-sunos4'. 5685 5686 The `configure' script accompanying GDB does not provide any query 5687facility to list all supported host and target names or aliases. 5688`configure' calls the Bourne shell script `config.sub' to map 5689abbreviations to full names; you can read the script, if you wish, or 5690you can use it to test your guesses on abbreviations--for example: 5691 5692 % sh config.sub i386-linux 5693 i386-pc-linux-gnu 5694 % sh config.sub alpha-linux 5695 alpha-unknown-linux-gnu 5696 % sh config.sub hp9k700 5697 hppa1.1-hp-hpux 5698 % sh config.sub sun4 5699 sparc-sun-sunos4.1.1 5700 % sh config.sub sun3 5701 m68k-sun-sunos4.1.1 5702 % sh config.sub i986v 5703 Invalid configuration `i986v': machine `i986v' not recognized 5704 5705`config.sub' is also distributed in the GDB source directory 5706(`gdb-7.3.1', for version 7.3.1). 5707 5708 5709File: gdb.info, Node: Configure Options, Next: System-wide configuration, Prev: Config Names, Up: Installing GDB 5710 5711C.5 `configure' Options 5712======================= 5713 5714Here is a summary of the `configure' options and arguments that are 5715most often useful for building GDB. `configure' also has several other 5716options not listed here. *note (configure.info)What Configure Does::, 5717for a full explanation of `configure'. 5718 5719 configure [--help] 5720 [--prefix=DIR] 5721 [--exec-prefix=DIR] 5722 [--srcdir=DIRNAME] 5723 [--norecursion] [--rm] 5724 [--target=TARGET] 5725 HOST 5726 5727You may introduce options with a single `-' rather than `--' if you 5728prefer; but you may abbreviate option names if you use `--'. 5729 5730`--help' 5731 Display a quick summary of how to invoke `configure'. 5732 5733`--prefix=DIR' 5734 Configure the source to install programs and files under directory 5735 `DIR'. 5736 5737`--exec-prefix=DIR' 5738 Configure the source to install programs under directory `DIR'. 5739 5740`--srcdir=DIRNAME' 5741 *Warning: using this option requires GNU `make', or another `make' 5742 that implements the `VPATH' feature.* 5743 Use this option to make configurations in directories separate 5744 from the GDB source directories. Among other things, you can use 5745 this to build (or maintain) several configurations simultaneously, 5746 in separate directories. `configure' writes 5747 configuration-specific files in the current directory, but 5748 arranges for them to use the source in the directory DIRNAME. 5749 `configure' creates directories under the working directory in 5750 parallel to the source directories below DIRNAME. 5751 5752`--norecursion' 5753 Configure only the directory level where `configure' is executed; 5754 do not propagate configuration to subdirectories. 5755 5756`--target=TARGET' 5757 Configure GDB for cross-debugging programs running on the specified 5758 TARGET. Without this option, GDB is configured to debug programs 5759 that run on the same machine (HOST) as GDB itself. 5760 5761 There is no convenient way to generate a list of all available 5762 targets. 5763 5764`HOST ...' 5765 Configure GDB to run on the specified HOST. 5766 5767 There is no convenient way to generate a list of all available 5768 hosts. 5769 5770 There are many other options available as well, but they are 5771generally needed for special purposes only. 5772 5773 5774File: gdb.info, Node: System-wide configuration, Prev: Configure Options, Up: Installing GDB 5775 5776C.6 System-wide configuration and settings 5777========================================== 5778 5779GDB can be configured to have a system-wide init file; this file will 5780be read and executed at startup (*note What GDB does during startup: 5781Startup.). 5782 5783 Here is the corresponding configure option: 5784 5785`--with-system-gdbinit=FILE' 5786 Specify that the default location of the system-wide init file is 5787 FILE. 5788 5789 If GDB has been configured with the option `--prefix=$prefix', it 5790may be subject to relocation. Two possible cases: 5791 5792 * If the default location of this init file contains `$prefix', it 5793 will be subject to relocation. Suppose that the configure options 5794 are `--prefix=$prefix --with-system-gdbinit=$prefix/etc/gdbinit'; 5795 if GDB is moved from `$prefix' to `$install', the system init file 5796 is looked for as `$install/etc/gdbinit' instead of 5797 `$prefix/etc/gdbinit'. 5798 5799 * By contrast, if the default location does not contain the prefix, 5800 it will not be relocated. E.g. if GDB has been configured with 5801 `--prefix=/usr/local --with-system-gdbinit=/usr/share/gdb/gdbinit', 5802 then GDB will always look for `/usr/share/gdb/gdbinit', wherever 5803 GDB is installed. 5804 5805 5806File: gdb.info, Node: Maintenance Commands, Next: Remote Protocol, Prev: Installing GDB, Up: Top 5807 5808Appendix D Maintenance Commands 5809******************************* 5810 5811In addition to commands intended for GDB users, GDB includes a number 5812of commands intended for GDB developers, that are not documented 5813elsewhere in this manual. These commands are provided here for 5814reference. (For commands that turn on debugging messages, see *Note 5815Debugging Output::.) 5816 5817`maint agent EXPRESSION' 5818`maint agent-eval EXPRESSION' 5819 Translate the given EXPRESSION into remote agent bytecodes. This 5820 command is useful for debugging the Agent Expression mechanism 5821 (*note Agent Expressions::). The `agent' version produces an 5822 expression useful for data collection, such as by tracepoints, 5823 while `maint agent-eval' produces an expression that evaluates 5824 directly to a result. For instance, a collection expression for 5825 `globa + globb' will include bytecodes to record four bytes of 5826 memory at each of the addresses of `globa' and `globb', while 5827 discarding the result of the addition, while an evaluation 5828 expression will do the addition and return the sum. 5829 5830`maint info breakpoints' 5831 Using the same format as `info breakpoints', display both the 5832 breakpoints you've set explicitly, and those GDB is using for 5833 internal purposes. Internal breakpoints are shown with negative 5834 breakpoint numbers. The type column identifies what kind of 5835 breakpoint is shown: 5836 5837 `breakpoint' 5838 Normal, explicitly set breakpoint. 5839 5840 `watchpoint' 5841 Normal, explicitly set watchpoint. 5842 5843 `longjmp' 5844 Internal breakpoint, used to handle correctly stepping through 5845 `longjmp' calls. 5846 5847 `longjmp resume' 5848 Internal breakpoint at the target of a `longjmp'. 5849 5850 `until' 5851 Temporary internal breakpoint used by the GDB `until' command. 5852 5853 `finish' 5854 Temporary internal breakpoint used by the GDB `finish' 5855 command. 5856 5857 `shlib events' 5858 Shared library events. 5859 5860 5861`set displaced-stepping' 5862`show displaced-stepping' 5863 Control whether or not GDB will do "displaced stepping" if the 5864 target supports it. Displaced stepping is a way to single-step 5865 over breakpoints without removing them from the inferior, by 5866 executing an out-of-line copy of the instruction that was 5867 originally at the breakpoint location. It is also known as 5868 out-of-line single-stepping. 5869 5870 `set displaced-stepping on' 5871 If the target architecture supports it, GDB will use 5872 displaced stepping to step over breakpoints. 5873 5874 `set displaced-stepping off' 5875 GDB will not use displaced stepping to step over breakpoints, 5876 even if such is supported by the target architecture. 5877 5878 `set displaced-stepping auto' 5879 This is the default mode. GDB will use displaced stepping 5880 only if non-stop mode is active (*note Non-Stop Mode::) and 5881 the target architecture supports displaced stepping. 5882 5883`maint check-symtabs' 5884 Check the consistency of psymtabs and symtabs. 5885 5886`maint cplus first_component NAME' 5887 Print the first C++ class/namespace component of NAME. 5888 5889`maint cplus namespace' 5890 Print the list of possible C++ namespaces. 5891 5892`maint demangle NAME' 5893 Demangle a C++ or Objective-C mangled NAME. 5894 5895`maint deprecate COMMAND [REPLACEMENT]' 5896`maint undeprecate COMMAND' 5897 Deprecate or undeprecate the named COMMAND. Deprecated commands 5898 cause GDB to issue a warning when you use them. The optional 5899 argument REPLACEMENT says which newer command should be used in 5900 favor of the deprecated one; if it is given, GDB will mention the 5901 replacement as part of the warning. 5902 5903`maint dump-me' 5904 Cause a fatal signal in the debugger and force it to dump its core. 5905 This is supported only on systems which support aborting a program 5906 with the `SIGQUIT' signal. 5907 5908`maint internal-error [MESSAGE-TEXT]' 5909`maint internal-warning [MESSAGE-TEXT]' 5910 Cause GDB to call the internal function `internal_error' or 5911 `internal_warning' and hence behave as though an internal error or 5912 internal warning has been detected. In addition to reporting the 5913 internal problem, these functions give the user the opportunity to 5914 either quit GDB or create a core file of the current GDB session. 5915 5916 These commands take an optional parameter MESSAGE-TEXT that is 5917 used as the text of the error or warning message. 5918 5919 Here's an example of using `internal-error': 5920 5921 (gdb) maint internal-error testing, 1, 2 5922 .../maint.c:121: internal-error: testing, 1, 2 5923 A problem internal to GDB has been detected. Further 5924 debugging may prove unreliable. 5925 Quit this debugging session? (y or n) n 5926 Create a core file? (y or n) n 5927 (gdb) 5928 5929`maint set internal-error ACTION [ask|yes|no]' 5930`maint show internal-error ACTION' 5931`maint set internal-warning ACTION [ask|yes|no]' 5932`maint show internal-warning ACTION' 5933 When GDB reports an internal problem (error or warning) it gives 5934 the user the opportunity to both quit GDB and create a core file 5935 of the current GDB session. These commands let you override the 5936 default behaviour for each particular ACTION, described in the 5937 table below. 5938 5939 `quit' 5940 You can specify that GDB should always (yes) or never (no) 5941 quit. The default is to ask the user what to do. 5942 5943 `corefile' 5944 You can specify that GDB should always (yes) or never (no) 5945 create a core file. The default is to ask the user what to 5946 do. 5947 5948`maint packet TEXT' 5949 If GDB is talking to an inferior via the serial protocol, then 5950 this command sends the string TEXT to the inferior, and displays 5951 the response packet. GDB supplies the initial `$' character, the 5952 terminating `#' character, and the checksum. 5953 5954`maint print architecture [FILE]' 5955 Print the entire architecture configuration. The optional argument 5956 FILE names the file where the output goes. 5957 5958`maint print c-tdesc' 5959 Print the current target description (*note Target Descriptions::) 5960 as a C source file. The created source file can be used in GDB 5961 when an XML parser is not available to parse the description. 5962 5963`maint print dummy-frames' 5964 Prints the contents of GDB's internal dummy-frame stack. 5965 5966 (gdb) b add 5967 ... 5968 (gdb) print add(2,3) 5969 Breakpoint 2, add (a=2, b=3) at ... 5970 58 return (a + b); 5971 The program being debugged stopped while in a function called from GDB. 5972 ... 5973 (gdb) maint print dummy-frames 5974 0x1a57c80: pc=0x01014068 fp=0x0200bddc sp=0x0200bdd6 5975 top=0x0200bdd4 id={stack=0x200bddc,code=0x101405c} 5976 call_lo=0x01014000 call_hi=0x01014001 5977 (gdb) 5978 5979 Takes an optional file parameter. 5980 5981`maint print registers [FILE]' 5982`maint print raw-registers [FILE]' 5983`maint print cooked-registers [FILE]' 5984`maint print register-groups [FILE]' 5985 Print GDB's internal register data structures. 5986 5987 The command `maint print raw-registers' includes the contents of 5988 the raw register cache; the command `maint print cooked-registers' 5989 includes the (cooked) value of all registers, including registers 5990 which aren't available on the target nor visible to user; and the 5991 command `maint print register-groups' includes the groups that each 5992 register is a member of. *Note Registers: (gdbint)Registers. 5993 5994 These commands take an optional parameter, a file name to which to 5995 write the information. 5996 5997`maint print reggroups [FILE]' 5998 Print GDB's internal register group data structures. The optional 5999 argument FILE tells to what file to write the information. 6000 6001 The register groups info looks like this: 6002 6003 (gdb) maint print reggroups 6004 Group Type 6005 general user 6006 float user 6007 all user 6008 vector user 6009 system user 6010 save internal 6011 restore internal 6012 6013`flushregs' 6014 This command forces GDB to flush its internal register cache. 6015 6016`maint print objfiles' 6017 Print a dump of all known object files. For each object file, this 6018 command prints its name, address in memory, and all of its psymtabs 6019 and symtabs. 6020 6021`maint print section-scripts [REGEXP]' 6022 Print a dump of scripts specified in the `.debug_gdb_section' 6023 section. If REGEXP is specified, only print scripts loaded by 6024 object files matching REGEXP. For each script, this command 6025 prints its name as specified in the objfile, and the full path if 6026 known. *Note .debug_gdb_scripts section::. 6027 6028`maint print statistics' 6029 This command prints, for each object file in the program, various 6030 data about that object file followed by the byte cache ("bcache") 6031 statistics for the object file. The objfile data includes the 6032 number of minimal, partial, full, and stabs symbols, the number of 6033 types defined by the objfile, the number of as yet unexpanded psym 6034 tables, the number of line tables and string tables, and the 6035 amount of memory used by the various tables. The bcache 6036 statistics include the counts, sizes, and counts of duplicates of 6037 all and unique objects, max, average, and median entry size, total 6038 memory used and its overhead and savings, and various measures of 6039 the hash table size and chain lengths. 6040 6041`maint print target-stack' 6042 A "target" is an interface between the debugger and a particular 6043 kind of file or process. Targets can be stacked in "strata", so 6044 that more than one target can potentially respond to a request. 6045 In particular, memory accesses will walk down the stack of targets 6046 until they find a target that is interested in handling that 6047 particular address. 6048 6049 This command prints a short description of each layer that was 6050 pushed on the "target stack", starting from the top layer down to 6051 the bottom one. 6052 6053`maint print type EXPR' 6054 Print the type chain for a type specified by EXPR. The argument 6055 can be either a type name or a symbol. If it is a symbol, the 6056 type of that symbol is described. The type chain produced by this 6057 command is a recursive definition of the data type as stored in 6058 GDB's data structures, including its flags and contained types. 6059 6060`maint set dwarf2 always-disassemble' 6061 6062`maint show dwarf2 always-disassemble' 6063 Control the behavior of `info address' when using DWARF debugging 6064 information. 6065 6066 The default is `off', which means that GDB should try to describe 6067 a variable's location in an easily readable format. When `on', 6068 GDB will instead display the DWARF location expression in an 6069 assembly-like format. Note that some locations are too complex 6070 for GDB to describe simply; in this case you will always see the 6071 disassembly form. 6072 6073 Here is an example of the resulting disassembly: 6074 6075 (gdb) info addr argc 6076 Symbol "argc" is a complex DWARF expression: 6077 1: DW_OP_fbreg 0 6078 6079 For more information on these expressions, see the DWARF standard 6080 (http://www.dwarfstd.org/). 6081 6082`maint set dwarf2 max-cache-age' 6083`maint show dwarf2 max-cache-age' 6084 Control the DWARF 2 compilation unit cache. 6085 6086 In object files with inter-compilation-unit references, such as 6087 those produced by the GCC option `-feliminate-dwarf2-dups', the 6088 DWARF 2 reader needs to frequently refer to previously read 6089 compilation units. This setting controls how long a compilation 6090 unit will remain in the cache if it is not referenced. A higher 6091 limit means that cached compilation units will be stored in memory 6092 longer, and more total memory will be used. Setting it to zero 6093 disables caching, which will slow down GDB startup, but reduce 6094 memory consumption. 6095 6096`maint set profile' 6097`maint show profile' 6098 Control profiling of GDB. 6099 6100 Profiling will be disabled until you use the `maint set profile' 6101 command to enable it. When you enable profiling, the system will 6102 begin collecting timing and execution count data; when you disable 6103 profiling or exit GDB, the results will be written to a log file. 6104 Remember that if you use profiling, GDB will overwrite the 6105 profiling log file (often called `gmon.out'). If you have a 6106 record of important profiling data in a `gmon.out' file, be sure 6107 to move it to a safe location. 6108 6109 Configuring with `--enable-profiling' arranges for GDB to be 6110 compiled with the `-pg' compiler option. 6111 6112`maint set show-debug-regs' 6113`maint show show-debug-regs' 6114 Control whether to show variables that mirror the hardware debug 6115 registers. Use `ON' to enable, `OFF' to disable. If enabled, the 6116 debug registers values are shown when GDB inserts or removes a 6117 hardware breakpoint or watchpoint, and when the inferior triggers 6118 a hardware-assisted breakpoint or watchpoint. 6119 6120`maint set show-all-tib' 6121`maint show show-all-tib' 6122 Control whether to show all non zero areas within a 1k block 6123 starting at thread local base, when using the `info w32 6124 thread-information-block' command. 6125 6126`maint space' 6127 Control whether to display memory usage for each command. If set 6128 to a nonzero value, GDB will display how much memory each command 6129 took, following the command's own output. This can also be 6130 requested by invoking GDB with the `--statistics' command-line 6131 switch (*note Mode Options::). 6132 6133`maint time' 6134 Control whether to display the execution time for each command. If 6135 set to a nonzero value, GDB will display how much time it took to 6136 execute each command, following the command's own output. The 6137 time is not printed for the commands that run the target, since 6138 there's no mechanism currently to compute how much time was spend 6139 by GDB and how much time was spend by the program been debugged. 6140 it's not possibly currently This can also be requested by invoking 6141 GDB with the `--statistics' command-line switch (*note Mode 6142 Options::). 6143 6144`maint translate-address [SECTION] ADDR' 6145 Find the symbol stored at the location specified by the address 6146 ADDR and an optional section name SECTION. If found, GDB prints 6147 the name of the closest symbol and an offset from the symbol's 6148 location to the specified address. This is similar to the `info 6149 address' command (*note Symbols::), except that this command also 6150 allows to find symbols in other sections. 6151 6152 If section was not specified, the section in which the symbol was 6153 found is also printed. For dynamically linked executables, the 6154 name of executable or shared library containing the symbol is 6155 printed as well. 6156 6157 6158 The following command is useful for non-interactive invocations of 6159GDB, such as in the test suite. 6160 6161`set watchdog NSEC' 6162 Set the maximum number of seconds GDB will wait for the target 6163 operation to finish. If this time expires, GDB reports and error 6164 and the command is aborted. 6165 6166`show watchdog' 6167 Show the current setting of the target wait timeout. 6168 6169 6170File: gdb.info, Node: Remote Protocol, Next: Agent Expressions, Prev: Maintenance Commands, Up: Top 6171 6172Appendix E GDB Remote Serial Protocol 6173************************************* 6174 6175* Menu: 6176 6177* Overview:: 6178* Packets:: 6179* Stop Reply Packets:: 6180* General Query Packets:: 6181* Architecture-Specific Protocol Details:: 6182* Tracepoint Packets:: 6183* Host I/O Packets:: 6184* Interrupts:: 6185* Notification Packets:: 6186* Remote Non-Stop:: 6187* Packet Acknowledgment:: 6188* Examples:: 6189* File-I/O Remote Protocol Extension:: 6190* Library List Format:: 6191* Memory Map Format:: 6192* Thread List Format:: 6193* Traceframe Info Format:: 6194 6195 6196File: gdb.info, Node: Overview, Next: Packets, Up: Remote Protocol 6197 6198E.1 Overview 6199============ 6200 6201There may be occasions when you need to know something about the 6202protocol--for example, if there is only one serial port to your target 6203machine, you might want your program to do something special if it 6204recognizes a packet meant for GDB. 6205 6206 In the examples below, `->' and `<-' are used to indicate 6207transmitted and received data, respectively. 6208 6209 All GDB commands and responses (other than acknowledgments and 6210notifications, see *Note Notification Packets::) are sent as a PACKET. 6211A PACKET is introduced with the character `$', the actual PACKET-DATA, 6212and the terminating character `#' followed by a two-digit CHECKSUM: 6213 6214 `$'PACKET-DATA`#'CHECKSUM 6215 The two-digit CHECKSUM is computed as the modulo 256 sum of all 6216characters between the leading `$' and the trailing `#' (an eight bit 6217unsigned checksum). 6218 6219 Implementors should note that prior to GDB 5.0 the protocol 6220specification also included an optional two-digit SEQUENCE-ID: 6221 6222 `$'SEQUENCE-ID`:'PACKET-DATA`#'CHECKSUM 6223 6224That SEQUENCE-ID was appended to the acknowledgment. GDB has never 6225output SEQUENCE-IDs. Stubs that handle packets added since GDB 5.0 6226must not accept SEQUENCE-ID. 6227 6228 When either the host or the target machine receives a packet, the 6229first response expected is an acknowledgment: either `+' (to indicate 6230the package was received correctly) or `-' (to request retransmission): 6231 6232 -> `$'PACKET-DATA`#'CHECKSUM 6233 <- `+' 6234 The `+'/`-' acknowledgments can be disabled once a connection is 6235established. *Note Packet Acknowledgment::, for details. 6236 6237 The host (GDB) sends COMMANDs, and the target (the debugging stub 6238incorporated in your program) sends a RESPONSE. In the case of step 6239and continue COMMANDs, the response is only sent when the operation has 6240completed, and the target has again stopped all threads in all attached 6241processes. This is the default all-stop mode behavior, but the remote 6242protocol also supports GDB's non-stop execution mode; see *Note Remote 6243Non-Stop::, for details. 6244 6245 PACKET-DATA consists of a sequence of characters with the exception 6246of `#' and `$' (see `X' packet for additional exceptions). 6247 6248 Fields within the packet should be separated using `,' `;' or `:'. 6249Except where otherwise noted all numbers are represented in HEX with 6250leading zeros suppressed. 6251 6252 Implementors should note that prior to GDB 5.0, the character `:' 6253could not appear as the third character in a packet (as it would 6254potentially conflict with the SEQUENCE-ID). 6255 6256 Binary data in most packets is encoded either as two hexadecimal 6257digits per byte of binary data. This allowed the traditional remote 6258protocol to work over connections which were only seven-bit clean. 6259Some packets designed more recently assume an eight-bit clean 6260connection, and use a more efficient encoding to send and receive 6261binary data. 6262 6263 The binary data representation uses `7d' (ASCII `}') as an escape 6264character. Any escaped byte is transmitted as the escape character 6265followed by the original character XORed with `0x20'. For example, the 6266byte `0x7d' would be transmitted as the two bytes `0x7d 0x5d'. The 6267bytes `0x23' (ASCII `#'), `0x24' (ASCII `$'), and `0x7d' (ASCII `}') 6268must always be escaped. Responses sent by the stub must also escape 6269`0x2a' (ASCII `*'), so that it is not interpreted as the start of a 6270run-length encoded sequence (described next). 6271 6272 Response DATA can be run-length encoded to save space. Run-length 6273encoding replaces runs of identical characters with one instance of the 6274repeated character, followed by a `*' and a repeat count. The repeat 6275count is itself sent encoded, to avoid binary characters in DATA: a 6276value of N is sent as `N+29'. For a repeat count greater or equal to 62773, this produces a printable ASCII character, e.g. a space (ASCII code 627832) for a repeat count of 3. (This is because run-length encoding 6279starts to win for counts 3 or more.) Thus, for example, `0* ' is a 6280run-length encoding of "0000": the space character after `*' means 6281repeat the leading `0' `32 - 29 = 3' more times. 6282 6283 The printable characters `#' and `$' or with a numeric value greater 6284than 126 must not be used. Runs of six repeats (`#') or seven repeats 6285(`$') can be expanded using a repeat count of only five (`"'). For 6286example, `00000000' can be encoded as `0*"00'. 6287 6288 The error response returned for some packets includes a two character 6289error number. That number is not well defined. 6290 6291 For any COMMAND not supported by the stub, an empty response 6292(`$#00') should be returned. That way it is possible to extend the 6293protocol. A newer GDB can tell if a packet is supported based on that 6294response. 6295 6296 A stub is required to support the `g', `G', `m', `M', `c', and `s' 6297COMMANDs. All other COMMANDs are optional. 6298 6299 6300File: gdb.info, Node: Packets, Next: Stop Reply Packets, Prev: Overview, Up: Remote Protocol 6301 6302E.2 Packets 6303=========== 6304 6305The following table provides a complete list of all currently defined 6306COMMANDs and their corresponding response DATA. *Note File-I/O Remote 6307Protocol Extension::, for details about the File I/O extension of the 6308remote protocol. 6309 6310 Each packet's description has a template showing the packet's overall 6311syntax, followed by an explanation of the packet's meaning. We include 6312spaces in some of the templates for clarity; these are not part of the 6313packet's syntax. No GDB packet uses spaces to separate its components. 6314For example, a template like `foo BAR BAZ' describes a packet 6315beginning with the three ASCII bytes `foo', followed by a BAR, followed 6316directly by a BAZ. GDB does not transmit a space character between the 6317`foo' and the BAR, or between the BAR and the BAZ. 6318 6319 Several packets and replies include a THREAD-ID field to identify a 6320thread. Normally these are positive numbers with a target-specific 6321interpretation, formatted as big-endian hex strings. A THREAD-ID can 6322also be a literal `-1' to indicate all threads, or `0' to pick any 6323thread. 6324 6325 In addition, the remote protocol supports a multiprocess feature in 6326which the THREAD-ID syntax is extended to optionally include both 6327process and thread ID fields, as `pPID.TID'. The PID (process) and TID 6328(thread) components each have the format described above: a positive 6329number with target-specific interpretation formatted as a big-endian 6330hex string, literal `-1' to indicate all processes or threads 6331(respectively), or `0' to indicate an arbitrary process or thread. 6332Specifying just a process, as `pPID', is equivalent to `pPID.-1'. It 6333is an error to specify all processes but a specific thread, such as 6334`p-1.TID'. Note that the `p' prefix is _not_ used for those packets 6335and replies explicitly documented to include a process ID, rather than 6336a THREAD-ID. 6337 6338 The multiprocess THREAD-ID syntax extensions are only used if both 6339GDB and the stub report support for the `multiprocess' feature using 6340`qSupported'. *Note multiprocess extensions::, for more information. 6341 6342 Note that all packet forms beginning with an upper- or lower-case 6343letter, other than those described here, are reserved for future use. 6344 6345 Here are the packet descriptions. 6346 6347`!' 6348 Enable extended mode. In extended mode, the remote server is made 6349 persistent. The `R' packet is used to restart the program being 6350 debugged. 6351 6352 Reply: 6353 `OK' 6354 The remote target both supports and has enabled extended mode. 6355 6356`?' 6357 Indicate the reason the target halted. The reply is the same as 6358 for step and continue. This packet has a special interpretation 6359 when the target is in non-stop mode; see *Note Remote Non-Stop::. 6360 6361 Reply: *Note Stop Reply Packets::, for the reply specifications. 6362 6363`A ARGLEN,ARGNUM,ARG,...' 6364 Initialized `argv[]' array passed into program. ARGLEN specifies 6365 the number of bytes in the hex encoded byte stream ARG. See 6366 `gdbserver' for more details. 6367 6368 Reply: 6369 `OK' 6370 The arguments were set. 6371 6372 `E NN' 6373 An error occurred. 6374 6375`b BAUD' 6376 (Don't use this packet; its behavior is not well-defined.) Change 6377 the serial line speed to BAUD. 6378 6379 JTC: _When does the transport layer state change? When it's 6380 received, or after the ACK is transmitted. In either case, there 6381 are problems if the command or the acknowledgment packet is 6382 dropped._ 6383 6384 Stan: _If people really wanted to add something like this, and get 6385 it working for the first time, they ought to modify ser-unix.c to 6386 send some kind of out-of-band message to a specially-setup stub 6387 and have the switch happen "in between" packets, so that from 6388 remote protocol's point of view, nothing actually happened._ 6389 6390`B ADDR,MODE' 6391 Set (MODE is `S') or clear (MODE is `C') a breakpoint at ADDR. 6392 6393 Don't use this packet. Use the `Z' and `z' packets instead (*note 6394 insert breakpoint or watchpoint packet::). 6395 6396`bc' 6397 Backward continue. Execute the target system in reverse. No 6398 parameter. *Note Reverse Execution::, for more information. 6399 6400 Reply: *Note Stop Reply Packets::, for the reply specifications. 6401 6402`bs' 6403 Backward single step. Execute one instruction in reverse. No 6404 parameter. *Note Reverse Execution::, for more information. 6405 6406 Reply: *Note Stop Reply Packets::, for the reply specifications. 6407 6408`c [ADDR]' 6409 Continue. ADDR is address to resume. If ADDR is omitted, resume 6410 at current address. 6411 6412 Reply: *Note Stop Reply Packets::, for the reply specifications. 6413 6414`C SIG[;ADDR]' 6415 Continue with signal SIG (hex signal number). If `;ADDR' is 6416 omitted, resume at same address. 6417 6418 Reply: *Note Stop Reply Packets::, for the reply specifications. 6419 6420`d' 6421 Toggle debug flag. 6422 6423 Don't use this packet; instead, define a general set packet (*note 6424 General Query Packets::). 6425 6426`D' 6427`D;PID' 6428 The first form of the packet is used to detach GDB from the remote 6429 system. It is sent to the remote target before GDB disconnects 6430 via the `detach' command. 6431 6432 The second form, including a process ID, is used when multiprocess 6433 protocol extensions are enabled (*note multiprocess extensions::), 6434 to detach only a specific process. The PID is specified as a 6435 big-endian hex string. 6436 6437 Reply: 6438 `OK' 6439 for success 6440 6441 `E NN' 6442 for an error 6443 6444`F RC,EE,CF;XX' 6445 A reply from GDB to an `F' packet sent by the target. This is 6446 part of the File-I/O protocol extension. *Note File-I/O Remote 6447 Protocol Extension::, for the specification. 6448 6449`g' 6450 Read general registers. 6451 6452 Reply: 6453 `XX...' 6454 Each byte of register data is described by two hex digits. 6455 The bytes with the register are transmitted in target byte 6456 order. The size of each register and their position within 6457 the `g' packet are determined by the GDB internal gdbarch 6458 functions `DEPRECATED_REGISTER_RAW_SIZE' and 6459 `gdbarch_register_name'. The specification of several 6460 standard `g' packets is specified below. 6461 6462 When reading registers from a trace frame (*note Using the 6463 Collected Data: Analyze Collected Data.), the stub may also 6464 return a string of literal `x''s in place of the register 6465 data digits, to indicate that the corresponding register has 6466 not been collected, thus its value is unavailable. For 6467 example, for an architecture with 4 registers of 4 bytes 6468 each, the following reply indicates to GDB that registers 0 6469 and 2 have not been collected, while registers 1 and 3 have 6470 been collected, and both have zero value: 6471 6472 -> `g' 6473 <- `xxxxxxxx00000000xxxxxxxx00000000' 6474 6475 `E NN' 6476 for an error. 6477 6478`G XX...' 6479 Write general registers. *Note read registers packet::, for a 6480 description of the XX... data. 6481 6482 Reply: 6483 `OK' 6484 for success 6485 6486 `E NN' 6487 for an error 6488 6489`H C THREAD-ID' 6490 Set thread for subsequent operations (`m', `M', `g', `G', et.al.). 6491 C depends on the operation to be performed: it should be `c' for 6492 step and continue operations, `g' for other operations. The 6493 thread designator THREAD-ID has the format and interpretation 6494 described in *Note thread-id syntax::. 6495 6496 Reply: 6497 `OK' 6498 for success 6499 6500 `E NN' 6501 for an error 6502 6503`i [ADDR[,NNN]]' 6504 Step the remote target by a single clock cycle. If `,NNN' is 6505 present, cycle step NNN cycles. If ADDR is present, cycle step 6506 starting at that address. 6507 6508`I' 6509 Signal, then cycle step. *Note step with signal packet::. *Note 6510 cycle step packet::. 6511 6512`k' 6513 Kill request. 6514 6515 FIXME: _There is no description of how to operate when a specific 6516 thread context has been selected (i.e. does 'k' kill only that 6517 thread?)_. 6518 6519`m ADDR,LENGTH' 6520 Read LENGTH bytes of memory starting at address ADDR. Note that 6521 ADDR may not be aligned to any particular boundary. 6522 6523 The stub need not use any particular size or alignment when 6524 gathering data from memory for the response; even if ADDR is 6525 word-aligned and LENGTH is a multiple of the word size, the stub 6526 is free to use byte accesses, or not. For this reason, this 6527 packet may not be suitable for accessing memory-mapped I/O devices. 6528 6529 Reply: 6530 `XX...' 6531 Memory contents; each byte is transmitted as a two-digit 6532 hexadecimal number. The reply may contain fewer bytes than 6533 requested if the server was able to read only part of the 6534 region of memory. 6535 6536 `E NN' 6537 NN is errno 6538 6539`M ADDR,LENGTH:XX...' 6540 Write LENGTH bytes of memory starting at address ADDR. XX... is 6541 the data; each byte is transmitted as a two-digit hexadecimal 6542 number. 6543 6544 Reply: 6545 `OK' 6546 for success 6547 6548 `E NN' 6549 for an error (this includes the case where only part of the 6550 data was written). 6551 6552`p N' 6553 Read the value of register N; N is in hex. *Note read registers 6554 packet::, for a description of how the returned register value is 6555 encoded. 6556 6557 Reply: 6558 `XX...' 6559 the register's value 6560 6561 `E NN' 6562 for an error 6563 6564 `' 6565 Indicating an unrecognized QUERY. 6566 6567`P N...=R...' 6568 Write register N... with value R.... The register number N is in 6569 hexadecimal, and R... contains two hex digits for each byte in the 6570 register (target byte order). 6571 6572 Reply: 6573 `OK' 6574 for success 6575 6576 `E NN' 6577 for an error 6578 6579`q NAME PARAMS...' 6580`Q NAME PARAMS...' 6581 General query (`q') and set (`Q'). These packets are described 6582 fully in *Note General Query Packets::. 6583 6584`r' 6585 Reset the entire system. 6586 6587 Don't use this packet; use the `R' packet instead. 6588 6589`R XX' 6590 Restart the program being debugged. XX, while needed, is ignored. 6591 This packet is only available in extended mode (*note extended 6592 mode::). 6593 6594 The `R' packet has no reply. 6595 6596`s [ADDR]' 6597 Single step. ADDR is the address at which to resume. If ADDR is 6598 omitted, resume at same address. 6599 6600 Reply: *Note Stop Reply Packets::, for the reply specifications. 6601 6602`S SIG[;ADDR]' 6603 Step with signal. This is analogous to the `C' packet, but 6604 requests a single-step, rather than a normal resumption of 6605 execution. 6606 6607 Reply: *Note Stop Reply Packets::, for the reply specifications. 6608 6609`t ADDR:PP,MM' 6610 Search backwards starting at address ADDR for a match with pattern 6611 PP and mask MM. PP and MM are 4 bytes. ADDR must be at least 3 6612 digits. 6613 6614`T THREAD-ID' 6615 Find out if the thread THREAD-ID is alive. *Note thread-id 6616 syntax::. 6617 6618 Reply: 6619 `OK' 6620 thread is still alive 6621 6622 `E NN' 6623 thread is dead 6624 6625`v' 6626 Packets starting with `v' are identified by a multi-letter name, 6627 up to the first `;' or `?' (or the end of the packet). 6628 6629`vAttach;PID' 6630 Attach to a new process with the specified process ID PID. The 6631 process ID is a hexadecimal integer identifying the process. In 6632 all-stop mode, all threads in the attached process are stopped; in 6633 non-stop mode, it may be attached without being stopped if that is 6634 supported by the target. 6635 6636 This packet is only available in extended mode (*note extended 6637 mode::). 6638 6639 Reply: 6640 `E NN' 6641 for an error 6642 6643 `Any stop packet' 6644 for success in all-stop mode (*note Stop Reply Packets::) 6645 6646 `OK' 6647 for success in non-stop mode (*note Remote Non-Stop::) 6648 6649`vCont[;ACTION[:THREAD-ID]]...' 6650 Resume the inferior, specifying different actions for each thread. 6651 If an action is specified with no THREAD-ID, then it is applied to 6652 any threads that don't have a specific action specified; if no 6653 default action is specified then other threads should remain 6654 stopped in all-stop mode and in their current state in non-stop 6655 mode. Specifying multiple default actions is an error; specifying 6656 no actions is also an error. Thread IDs are specified using the 6657 syntax described in *Note thread-id syntax::. 6658 6659 Currently supported actions are: 6660 6661 `c' 6662 Continue. 6663 6664 `C SIG' 6665 Continue with signal SIG. The signal SIG should be two hex 6666 digits. 6667 6668 `s' 6669 Step. 6670 6671 `S SIG' 6672 Step with signal SIG. The signal SIG should be two hex 6673 digits. 6674 6675 `t' 6676 Stop. 6677 6678 The optional argument ADDR normally associated with the `c', `C', 6679 `s', and `S' packets is not supported in `vCont'. 6680 6681 The `t' action is only relevant in non-stop mode (*note Remote 6682 Non-Stop::) and may be ignored by the stub otherwise. A stop 6683 reply should be generated for any affected thread not already 6684 stopped. When a thread is stopped by means of a `t' action, the 6685 corresponding stop reply should indicate that the thread has 6686 stopped with signal `0', regardless of whether the target uses 6687 some other signal as an implementation detail. 6688 6689 Reply: *Note Stop Reply Packets::, for the reply specifications. 6690 6691`vCont?' 6692 Request a list of actions supported by the `vCont' packet. 6693 6694 Reply: 6695 `vCont[;ACTION...]' 6696 The `vCont' packet is supported. Each ACTION is a supported 6697 command in the `vCont' packet. 6698 6699 `' 6700 The `vCont' packet is not supported. 6701 6702`vFile:OPERATION:PARAMETER...' 6703 Perform a file operation on the target system. For details, see 6704 *Note Host I/O Packets::. 6705 6706`vFlashErase:ADDR,LENGTH' 6707 Direct the stub to erase LENGTH bytes of flash starting at ADDR. 6708 The region may enclose any number of flash blocks, but its start 6709 and end must fall on block boundaries, as indicated by the flash 6710 block size appearing in the memory map (*note Memory Map 6711 Format::). GDB groups flash memory programming operations 6712 together, and sends a `vFlashDone' request after each group; the 6713 stub is allowed to delay erase operation until the `vFlashDone' 6714 packet is received. 6715 6716 The stub must support `vCont' if it reports support for 6717 multiprocess extensions (*note multiprocess extensions::). Note 6718 that in this case `vCont' actions can be specified to apply to all 6719 threads in a process by using the `pPID.-1' form of the THREAD-ID. 6720 6721 Reply: 6722 `OK' 6723 for success 6724 6725 `E NN' 6726 for an error 6727 6728`vFlashWrite:ADDR:XX...' 6729 Direct the stub to write data to flash address ADDR. The data is 6730 passed in binary form using the same encoding as for the `X' 6731 packet (*note Binary Data::). The memory ranges specified by 6732 `vFlashWrite' packets preceding a `vFlashDone' packet must not 6733 overlap, and must appear in order of increasing addresses 6734 (although `vFlashErase' packets for higher addresses may already 6735 have been received; the ordering is guaranteed only between 6736 `vFlashWrite' packets). If a packet writes to an address that was 6737 neither erased by a preceding `vFlashErase' packet nor by some 6738 other target-specific method, the results are unpredictable. 6739 6740 Reply: 6741 `OK' 6742 for success 6743 6744 `E.memtype' 6745 for vFlashWrite addressing non-flash memory 6746 6747 `E NN' 6748 for an error 6749 6750`vFlashDone' 6751 Indicate to the stub that flash programming operation is finished. 6752 The stub is permitted to delay or batch the effects of a group of 6753 `vFlashErase' and `vFlashWrite' packets until a `vFlashDone' 6754 packet is received. The contents of the affected regions of flash 6755 memory are unpredictable until the `vFlashDone' request is 6756 completed. 6757 6758`vKill;PID' 6759 Kill the process with the specified process ID. PID is a 6760 hexadecimal integer identifying the process. This packet is used 6761 in preference to `k' when multiprocess protocol extensions are 6762 supported; see *Note multiprocess extensions::. 6763 6764 Reply: 6765 `E NN' 6766 for an error 6767 6768 `OK' 6769 for success 6770 6771`vRun;FILENAME[;ARGUMENT]...' 6772 Run the program FILENAME, passing it each ARGUMENT on its command 6773 line. The file and arguments are hex-encoded strings. If 6774 FILENAME is an empty string, the stub may use a default program 6775 (e.g. the last program run). The program is created in the stopped 6776 state. 6777 6778 This packet is only available in extended mode (*note extended 6779 mode::). 6780 6781 Reply: 6782 `E NN' 6783 for an error 6784 6785 `Any stop packet' 6786 for success (*note Stop Reply Packets::) 6787 6788`vStopped' 6789 In non-stop mode (*note Remote Non-Stop::), acknowledge a previous 6790 stop reply and prompt for the stub to report another one. 6791 6792 Reply: 6793 `Any stop packet' 6794 if there is another unreported stop event (*note Stop Reply 6795 Packets::) 6796 6797 `OK' 6798 if there are no unreported stop events 6799 6800`X ADDR,LENGTH:XX...' 6801 Write data to memory, where the data is transmitted in binary. 6802 ADDR is address, LENGTH is number of bytes, `XX...' is binary data 6803 (*note Binary Data::). 6804 6805 Reply: 6806 `OK' 6807 for success 6808 6809 `E NN' 6810 for an error 6811 6812`z TYPE,ADDR,KIND' 6813`Z TYPE,ADDR,KIND' 6814 Insert (`Z') or remove (`z') a TYPE breakpoint or watchpoint 6815 starting at address ADDRESS of kind KIND. 6816 6817 Each breakpoint and watchpoint packet TYPE is documented 6818 separately. 6819 6820 _Implementation notes: A remote target shall return an empty string 6821 for an unrecognized breakpoint or watchpoint packet TYPE. A 6822 remote target shall support either both or neither of a given 6823 `ZTYPE...' and `zTYPE...' packet pair. To avoid potential 6824 problems with duplicate packets, the operations should be 6825 implemented in an idempotent way._ 6826 6827`z0,ADDR,KIND' 6828`Z0,ADDR,KIND' 6829 Insert (`Z0') or remove (`z0') a memory breakpoint at address ADDR 6830 of type KIND. 6831 6832 A memory breakpoint is implemented by replacing the instruction at 6833 ADDR with a software breakpoint or trap instruction. The KIND is 6834 target-specific and typically indicates the size of the breakpoint 6835 in bytes that should be inserted. E.g., the ARM and MIPS can 6836 insert either a 2 or 4 byte breakpoint. Some architectures have 6837 additional meanings for KIND; see *Note Architecture-Specific 6838 Protocol Details::. 6839 6840 _Implementation note: It is possible for a target to copy or move 6841 code that contains memory breakpoints (e.g., when implementing 6842 overlays). The behavior of this packet, in the presence of such a 6843 target, is not defined._ 6844 6845 Reply: 6846 `OK' 6847 success 6848 6849 `' 6850 not supported 6851 6852 `E NN' 6853 for an error 6854 6855`z1,ADDR,KIND' 6856`Z1,ADDR,KIND' 6857 Insert (`Z1') or remove (`z1') a hardware breakpoint at address 6858 ADDR. 6859 6860 A hardware breakpoint is implemented using a mechanism that is not 6861 dependant on being able to modify the target's memory. KIND has 6862 the same meaning as in `Z0' packets. 6863 6864 _Implementation note: A hardware breakpoint is not affected by code 6865 movement._ 6866 6867 Reply: 6868 `OK' 6869 success 6870 6871 `' 6872 not supported 6873 6874 `E NN' 6875 for an error 6876 6877`z2,ADDR,KIND' 6878`Z2,ADDR,KIND' 6879 Insert (`Z2') or remove (`z2') a write watchpoint at ADDR. KIND 6880 is interpreted as the number of bytes to watch. 6881 6882 Reply: 6883 `OK' 6884 success 6885 6886 `' 6887 not supported 6888 6889 `E NN' 6890 for an error 6891 6892`z3,ADDR,KIND' 6893`Z3,ADDR,KIND' 6894 Insert (`Z3') or remove (`z3') a read watchpoint at ADDR. KIND is 6895 interpreted as the number of bytes to watch. 6896 6897 Reply: 6898 `OK' 6899 success 6900 6901 `' 6902 not supported 6903 6904 `E NN' 6905 for an error 6906 6907`z4,ADDR,KIND' 6908`Z4,ADDR,KIND' 6909 Insert (`Z4') or remove (`z4') an access watchpoint at ADDR. KIND 6910 is interpreted as the number of bytes to watch. 6911 6912 Reply: 6913 `OK' 6914 success 6915 6916 `' 6917 not supported 6918 6919 `E NN' 6920 for an error 6921 6922 6923 6924File: gdb.info, Node: Stop Reply Packets, Next: General Query Packets, Prev: Packets, Up: Remote Protocol 6925 6926E.3 Stop Reply Packets 6927====================== 6928 6929The `C', `c', `S', `s', `vCont', `vAttach', `vRun', `vStopped', and `?' 6930packets can receive any of the below as a reply. Except for `?' and 6931`vStopped', that reply is only returned when the target halts. In the 6932below the exact meaning of "signal number" is defined by the header 6933`include/gdb/signals.h' in the GDB source code. 6934 6935 As in the description of request packets, we include spaces in the 6936reply templates for clarity; these are not part of the reply packet's 6937syntax. No GDB stop reply packet uses spaces to separate its 6938components. 6939 6940`S AA' 6941 The program received signal number AA (a two-digit hexadecimal 6942 number). This is equivalent to a `T' response with no N:R pairs. 6943 6944`T AA N1:R1;N2:R2;...' 6945 The program received signal number AA (a two-digit hexadecimal 6946 number). This is equivalent to an `S' response, except that the 6947 `N:R' pairs can carry values of important registers and other 6948 information directly in the stop reply packet, reducing round-trip 6949 latency. Single-step and breakpoint traps are reported this way. 6950 Each `N:R' pair is interpreted as follows: 6951 6952 * If N is a hexadecimal number, it is a register number, and the 6953 corresponding R gives that register's value. R is a series 6954 of bytes in target byte order, with each byte given by a 6955 two-digit hex number. 6956 6957 * If N is `thread', then R is the THREAD-ID of the stopped 6958 thread, as specified in *Note thread-id syntax::. 6959 6960 * If N is `core', then R is the hexadecimal number of the core 6961 on which the stop event was detected. 6962 6963 * If N is a recognized "stop reason", it describes a more 6964 specific event that stopped the target. The currently 6965 defined stop reasons are listed below. AA should be `05', 6966 the trap signal. At most one stop reason should be present. 6967 6968 * Otherwise, GDB should ignore this `N:R' pair and go on to the 6969 next; this allows us to extend the protocol in the future. 6970 6971 The currently defined stop reasons are: 6972 6973 `watch' 6974 `rwatch' 6975 `awatch' 6976 The packet indicates a watchpoint hit, and R is the data 6977 address, in hex. 6978 6979 `library' 6980 The packet indicates that the loaded libraries have changed. 6981 GDB should use `qXfer:libraries:read' to fetch a new list of 6982 loaded libraries. R is ignored. 6983 6984 `replaylog' 6985 The packet indicates that the target cannot continue replaying 6986 logged execution events, because it has reached the end (or 6987 the beginning when executing backward) of the log. The value 6988 of R will be either `begin' or `end'. *Note Reverse 6989 Execution::, for more information. 6990 6991`W AA' 6992`W AA ; process:PID' 6993 The process exited, and AA is the exit status. This is only 6994 applicable to certain targets. 6995 6996 The second form of the response, including the process ID of the 6997 exited process, can be used only when GDB has reported support for 6998 multiprocess protocol extensions; see *Note multiprocess 6999 extensions::. The PID is formatted as a big-endian hex string. 7000 7001`X AA' 7002`X AA ; process:PID' 7003 The process terminated with signal AA. 7004 7005 The second form of the response, including the process ID of the 7006 terminated process, can be used only when GDB has reported support 7007 for multiprocess protocol extensions; see *Note multiprocess 7008 extensions::. The PID is formatted as a big-endian hex string. 7009 7010`O XX...' 7011 `XX...' is hex encoding of ASCII data, to be written as the 7012 program's console output. This can happen at any time while the 7013 program is running and the debugger should continue to wait for 7014 `W', `T', etc. This reply is not permitted in non-stop mode. 7015 7016`F CALL-ID,PARAMETER...' 7017 CALL-ID is the identifier which says which host system call should 7018 be called. This is just the name of the function. Translation 7019 into the correct system call is only applicable as it's defined in 7020 GDB. *Note File-I/O Remote Protocol Extension::, for a list of 7021 implemented system calls. 7022 7023 `PARAMETER...' is a list of parameters as defined for this very 7024 system call. 7025 7026 The target replies with this packet when it expects GDB to call a 7027 host system call on behalf of the target. GDB replies with an 7028 appropriate `F' packet and keeps up waiting for the next reply 7029 packet from the target. The latest `C', `c', `S' or `s' action is 7030 expected to be continued. *Note File-I/O Remote Protocol 7031 Extension::, for more details. 7032 7033 7034 7035File: gdb.info, Node: General Query Packets, Next: Architecture-Specific Protocol Details, Prev: Stop Reply Packets, Up: Remote Protocol 7036 7037E.4 General Query Packets 7038========================= 7039 7040Packets starting with `q' are "general query packets"; packets starting 7041with `Q' are "general set packets". General query and set packets are 7042a semi-unified form for retrieving and sending information to and from 7043the stub. 7044 7045 The initial letter of a query or set packet is followed by a name 7046indicating what sort of thing the packet applies to. For example, GDB 7047may use a `qSymbol' packet to exchange symbol definitions with the 7048stub. These packet names follow some conventions: 7049 7050 * The name must not contain commas, colons or semicolons. 7051 7052 * Most GDB query and set packets have a leading upper case letter. 7053 7054 * The names of custom vendor packets should use a company prefix, in 7055 lower case, followed by a period. For example, packets designed at 7056 the Acme Corporation might begin with `qacme.foo' (for querying 7057 foos) or `Qacme.bar' (for setting bars). 7058 7059 The name of a query or set packet should be separated from any 7060parameters by a `:'; the parameters themselves should be separated by 7061`,' or `;'. Stubs must be careful to match the full packet name, and 7062check for a separator or the end of the packet, in case two packet 7063names share a common prefix. New packets should not begin with `qC', 7064`qP', or `qL'(1). 7065 7066 Like the descriptions of the other packets, each description here 7067has a template showing the packet's overall syntax, followed by an 7068explanation of the packet's meaning. We include spaces in some of the 7069templates for clarity; these are not part of the packet's syntax. No 7070GDB packet uses spaces to separate its components. 7071 7072 Here are the currently defined query and set packets: 7073 7074`QAllow:OP:VAL...' 7075 Specify which operations GDB expects to request of the target, as 7076 a semicolon-separated list of operation name and value pairs. 7077 Possible values for OP include `WriteReg', `WriteMem', 7078 `InsertBreak', `InsertTrace', `InsertFastTrace', and `Stop'. VAL 7079 is either 0, indicating that GDB will not request the operation, 7080 or 1, indicating that it may. (The target can then use this to 7081 set up its own internals optimally, for instance if the debugger 7082 never expects to insert breakpoints, it may not need to install 7083 its own trap handler.) 7084 7085`qC' 7086 Return the current thread ID. 7087 7088 Reply: 7089 `QC THREAD-ID' 7090 Where THREAD-ID is a thread ID as documented in *Note 7091 thread-id syntax::. 7092 7093 `(anything else)' 7094 Any other reply implies the old thread ID. 7095 7096`qCRC:ADDR,LENGTH' 7097 Compute the CRC checksum of a block of memory using CRC-32 defined 7098 in IEEE 802.3. The CRC is computed byte at a time, taking the most 7099 significant bit of each byte first. The initial pattern code 7100 `0xffffffff' is used to ensure leading zeros affect the CRC. 7101 7102 _Note:_ This is the same CRC used in validating separate debug 7103 files (*note Debugging Information in Separate Files: Separate 7104 Debug Files.). However the algorithm is slightly different. When 7105 validating separate debug files, the CRC is computed taking the 7106 _least_ significant bit of each byte first, and the final result 7107 is inverted to detect trailing zeros. 7108 7109 Reply: 7110 `E NN' 7111 An error (such as memory fault) 7112 7113 `C CRC32' 7114 The specified memory region's checksum is CRC32. 7115 7116`qfThreadInfo' 7117`qsThreadInfo' 7118 Obtain a list of all active thread IDs from the target (OS). 7119 Since there may be too many active threads to fit into one reply 7120 packet, this query works iteratively: it may require more than one 7121 query/reply sequence to obtain the entire list of threads. The 7122 first query of the sequence will be the `qfThreadInfo' query; 7123 subsequent queries in the sequence will be the `qsThreadInfo' 7124 query. 7125 7126 NOTE: This packet replaces the `qL' query (see below). 7127 7128 Reply: 7129 `m THREAD-ID' 7130 A single thread ID 7131 7132 `m THREAD-ID,THREAD-ID...' 7133 a comma-separated list of thread IDs 7134 7135 `l' 7136 (lower case letter `L') denotes end of list. 7137 7138 In response to each query, the target will reply with a list of 7139 one or more thread IDs, separated by commas. GDB will respond to 7140 each reply with a request for more thread ids (using the `qs' form 7141 of the query), until the target responds with `l' (lower-case ell, 7142 for "last"). Refer to *Note thread-id syntax::, for the format of 7143 the THREAD-ID fields. 7144 7145`qGetTLSAddr:THREAD-ID,OFFSET,LM' 7146 Fetch the address associated with thread local storage specified 7147 by THREAD-ID, OFFSET, and LM. 7148 7149 THREAD-ID is the thread ID associated with the thread for which to 7150 fetch the TLS address. *Note thread-id syntax::. 7151 7152 OFFSET is the (big endian, hex encoded) offset associated with the 7153 thread local variable. (This offset is obtained from the debug 7154 information associated with the variable.) 7155 7156 LM is the (big endian, hex encoded) OS/ABI-specific encoding of the 7157 the load module associated with the thread local storage. For 7158 example, a GNU/Linux system will pass the link map address of the 7159 shared object associated with the thread local storage under 7160 consideration. Other operating environments may choose to 7161 represent the load module differently, so the precise meaning of 7162 this parameter will vary. 7163 7164 Reply: 7165 `XX...' 7166 Hex encoded (big endian) bytes representing the address of 7167 the thread local storage requested. 7168 7169 `E NN' 7170 An error occurred. NN are hex digits. 7171 7172 `' 7173 An empty reply indicates that `qGetTLSAddr' is not supported 7174 by the stub. 7175 7176`qGetTIBAddr:THREAD-ID' 7177 Fetch address of the Windows OS specific Thread Information Block. 7178 7179 THREAD-ID is the thread ID associated with the thread. 7180 7181 Reply: 7182 `XX...' 7183 Hex encoded (big endian) bytes representing the linear 7184 address of the thread information block. 7185 7186 `E NN' 7187 An error occured. This means that either the thread was not 7188 found, or the address could not be retrieved. 7189 7190 `' 7191 An empty reply indicates that `qGetTIBAddr' is not supported 7192 by the stub. 7193 7194`qL STARTFLAG THREADCOUNT NEXTTHREAD' 7195 Obtain thread information from RTOS. Where: STARTFLAG (one hex 7196 digit) is one to indicate the first query and zero to indicate a 7197 subsequent query; THREADCOUNT (two hex digits) is the maximum 7198 number of threads the response packet can contain; and NEXTTHREAD 7199 (eight hex digits), for subsequent queries (STARTFLAG is zero), is 7200 returned in the response as ARGTHREAD. 7201 7202 Don't use this packet; use the `qfThreadInfo' query instead (see 7203 above). 7204 7205 Reply: 7206 `qM COUNT DONE ARGTHREAD THREAD...' 7207 Where: COUNT (two hex digits) is the number of threads being 7208 returned; DONE (one hex digit) is zero to indicate more 7209 threads and one indicates no further threads; ARGTHREADID 7210 (eight hex digits) is NEXTTHREAD from the request packet; 7211 THREAD... is a sequence of thread IDs from the target. 7212 THREADID (eight hex digits). See 7213 `remote.c:parse_threadlist_response()'. 7214 7215`qOffsets' 7216 Get section offsets that the target used when relocating the 7217 downloaded image. 7218 7219 Reply: 7220 `Text=XXX;Data=YYY[;Bss=ZZZ]' 7221 Relocate the `Text' section by XXX from its original address. 7222 Relocate the `Data' section by YYY from its original address. 7223 If the object file format provides segment information (e.g. 7224 ELF `PT_LOAD' program headers), GDB will relocate entire 7225 segments by the supplied offsets. 7226 7227 _Note: while a `Bss' offset may be included in the response, 7228 GDB ignores this and instead applies the `Data' offset to the 7229 `Bss' section._ 7230 7231 `TextSeg=XXX[;DataSeg=YYY]' 7232 Relocate the first segment of the object file, which 7233 conventionally contains program code, to a starting address 7234 of XXX. If `DataSeg' is specified, relocate the second 7235 segment, which conventionally contains modifiable data, to a 7236 starting address of YYY. GDB will report an error if the 7237 object file does not contain segment information, or does not 7238 contain at least as many segments as mentioned in the reply. 7239 Extra segments are kept at fixed offsets relative to the last 7240 relocated segment. 7241 7242`qP MODE THREAD-ID' 7243 Returns information on THREAD-ID. Where: MODE is a hex encoded 32 7244 bit mode; THREAD-ID is a thread ID (*note thread-id syntax::). 7245 7246 Don't use this packet; use the `qThreadExtraInfo' query instead 7247 (see below). 7248 7249 Reply: see `remote.c:remote_unpack_thread_info_response()'. 7250 7251`QNonStop:1' 7252 7253`QNonStop:0' 7254 Enter non-stop (`QNonStop:1') or all-stop (`QNonStop:0') mode. 7255 *Note Remote Non-Stop::, for more information. 7256 7257 Reply: 7258 `OK' 7259 The request succeeded. 7260 7261 `E NN' 7262 An error occurred. NN are hex digits. 7263 7264 `' 7265 An empty reply indicates that `QNonStop' is not supported by 7266 the stub. 7267 7268 This packet is not probed by default; the remote stub must request 7269 it, by supplying an appropriate `qSupported' response (*note 7270 qSupported::). Use of this packet is controlled by the `set 7271 non-stop' command; *note Non-Stop Mode::. 7272 7273`QPassSignals: SIGNAL [;SIGNAL]...' 7274 Each listed SIGNAL should be passed directly to the inferior 7275 process. Signals are numbered identically to continue packets and 7276 stop replies (*note Stop Reply Packets::). Each SIGNAL list item 7277 should be strictly greater than the previous item. These signals 7278 do not need to stop the inferior, or be reported to GDB. All 7279 other signals should be reported to GDB. Multiple `QPassSignals' 7280 packets do not combine; any earlier `QPassSignals' list is 7281 completely replaced by the new list. This packet improves 7282 performance when using `handle SIGNAL nostop noprint pass'. 7283 7284 Reply: 7285 `OK' 7286 The request succeeded. 7287 7288 `E NN' 7289 An error occurred. NN are hex digits. 7290 7291 `' 7292 An empty reply indicates that `QPassSignals' is not supported 7293 by the stub. 7294 7295 Use of this packet is controlled by the `set remote pass-signals' 7296 command (*note set remote pass-signals: Remote Configuration.). 7297 This packet is not probed by default; the remote stub must request 7298 it, by supplying an appropriate `qSupported' response (*note 7299 qSupported::). 7300 7301`qRcmd,COMMAND' 7302 COMMAND (hex encoded) is passed to the local interpreter for 7303 execution. Invalid commands should be reported using the output 7304 string. Before the final result packet, the target may also 7305 respond with a number of intermediate `OOUTPUT' console output 7306 packets. _Implementors should note that providing access to a 7307 stubs's interpreter may have security implications_. 7308 7309 Reply: 7310 `OK' 7311 A command response with no output. 7312 7313 `OUTPUT' 7314 A command response with the hex encoded output string OUTPUT. 7315 7316 `E NN' 7317 Indicate a badly formed request. 7318 7319 `' 7320 An empty reply indicates that `qRcmd' is not recognized. 7321 7322 (Note that the `qRcmd' packet's name is separated from the command 7323 by a `,', not a `:', contrary to the naming conventions above. 7324 Please don't use this packet as a model for new packets.) 7325 7326`qSearch:memory:ADDRESS;LENGTH;SEARCH-PATTERN' 7327 Search LENGTH bytes at ADDRESS for SEARCH-PATTERN. ADDRESS and 7328 LENGTH are encoded in hex. SEARCH-PATTERN is a sequence of bytes, 7329 hex encoded. 7330 7331 Reply: 7332 `0' 7333 The pattern was not found. 7334 7335 `1,address' 7336 The pattern was found at ADDRESS. 7337 7338 `E NN' 7339 A badly formed request or an error was encountered while 7340 searching memory. 7341 7342 `' 7343 An empty reply indicates that `qSearch:memory' is not 7344 recognized. 7345 7346`QStartNoAckMode' 7347 Request that the remote stub disable the normal `+'/`-' protocol 7348 acknowledgments (*note Packet Acknowledgment::). 7349 7350 Reply: 7351 `OK' 7352 The stub has switched to no-acknowledgment mode. GDB 7353 acknowledges this reponse, but neither the stub nor GDB shall 7354 send or expect further `+'/`-' acknowledgments in the current 7355 connection. 7356 7357 `' 7358 An empty reply indicates that the stub does not support 7359 no-acknowledgment mode. 7360 7361`qSupported [:GDBFEATURE [;GDBFEATURE]... ]' 7362 Tell the remote stub about features supported by GDB, and query 7363 the stub for features it supports. This packet allows GDB and the 7364 remote stub to take advantage of each others' features. 7365 `qSupported' also consolidates multiple feature probes at startup, 7366 to improve GDB performance--a single larger packet performs better 7367 than multiple smaller probe packets on high-latency links. Some 7368 features may enable behavior which must not be on by default, e.g. 7369 because it would confuse older clients or stubs. Other features 7370 may describe packets which could be automatically probed for, but 7371 are not. These features must be reported before GDB will use 7372 them. This "default unsupported" behavior is not appropriate for 7373 all packets, but it helps to keep the initial connection time 7374 under control with new versions of GDB which support increasing 7375 numbers of packets. 7376 7377 Reply: 7378 `STUBFEATURE [;STUBFEATURE]...' 7379 The stub supports or does not support each returned 7380 STUBFEATURE, depending on the form of each STUBFEATURE (see 7381 below for the possible forms). 7382 7383 `' 7384 An empty reply indicates that `qSupported' is not recognized, 7385 or that no features needed to be reported to GDB. 7386 7387 The allowed forms for each feature (either a GDBFEATURE in the 7388 `qSupported' packet, or a STUBFEATURE in the response) are: 7389 7390 `NAME=VALUE' 7391 The remote protocol feature NAME is supported, and associated 7392 with the specified VALUE. The format of VALUE depends on the 7393 feature, but it must not include a semicolon. 7394 7395 `NAME+' 7396 The remote protocol feature NAME is supported, and does not 7397 need an associated value. 7398 7399 `NAME-' 7400 The remote protocol feature NAME is not supported. 7401 7402 `NAME?' 7403 The remote protocol feature NAME may be supported, and GDB 7404 should auto-detect support in some other way when it is 7405 needed. This form will not be used for GDBFEATURE 7406 notifications, but may be used for STUBFEATURE responses. 7407 7408 Whenever the stub receives a `qSupported' request, the supplied 7409 set of GDB features should override any previous request. This 7410 allows GDB to put the stub in a known state, even if the stub had 7411 previously been communicating with a different version of GDB. 7412 7413 The following values of GDBFEATURE (for the packet sent by GDB) 7414 are defined: 7415 7416 `multiprocess' 7417 This feature indicates whether GDB supports multiprocess 7418 extensions to the remote protocol. GDB does not use such 7419 extensions unless the stub also reports that it supports them 7420 by including `multiprocess+' in its `qSupported' reply. 7421 *Note multiprocess extensions::, for details. 7422 7423 `xmlRegisters' 7424 This feature indicates that GDB supports the XML target 7425 description. If the stub sees `xmlRegisters=' with target 7426 specific strings separated by a comma, it will report register 7427 description. 7428 7429 `qRelocInsn' 7430 This feature indicates whether GDB supports the `qRelocInsn' 7431 packet (*note Relocate instruction reply packet: Tracepoint 7432 Packets.). 7433 7434 Stubs should ignore any unknown values for GDBFEATURE. Any GDB 7435 which sends a `qSupported' packet supports receiving packets of 7436 unlimited length (earlier versions of GDB may reject overly long 7437 responses). Additional values for GDBFEATURE may be defined in 7438 the future to let the stub take advantage of new features in GDB, 7439 e.g. incompatible improvements in the remote protocol--the 7440 `multiprocess' feature is an example of such a feature. The 7441 stub's reply should be independent of the GDBFEATURE entries sent 7442 by GDB; first GDB describes all the features it supports, and then 7443 the stub replies with all the features it supports. 7444 7445 Similarly, GDB will silently ignore unrecognized stub feature 7446 responses, as long as each response uses one of the standard forms. 7447 7448 Some features are flags. A stub which supports a flag feature 7449 should respond with a `+' form response. Other features require 7450 values, and the stub should respond with an `=' form response. 7451 7452 Each feature has a default value, which GDB will use if 7453 `qSupported' is not available or if the feature is not mentioned 7454 in the `qSupported' response. The default values are fixed; a 7455 stub is free to omit any feature responses that match the defaults. 7456 7457 Not all features can be probed, but for those which can, the 7458 probing mechanism is useful: in some cases, a stub's internal 7459 architecture may not allow the protocol layer to know some 7460 information about the underlying target in advance. This is 7461 especially common in stubs which may be configured for multiple 7462 targets. 7463 7464 These are the currently defined stub features and their properties: 7465 7466 Feature Name Value Default Probe Allowed 7467 Required 7468 `PacketSize' Yes `-' No 7469 `qXfer:auxv:read' No `-' Yes 7470 `qXfer:features:read' No `-' Yes 7471 `qXfer:libraries:read' No `-' Yes 7472 `qXfer:memory-map:read' No `-' Yes 7473 `qXfer:sdata:read' No `-' Yes 7474 `qXfer:spu:read' No `-' Yes 7475 `qXfer:spu:write' No `-' Yes 7476 `qXfer:siginfo:read' No `-' Yes 7477 `qXfer:siginfo:write' No `-' Yes 7478 `qXfer:threads:read' No `-' Yes 7479 `qXfer:traceframe-info:read'No `-' Yes 7480 `QNonStop' No `-' Yes 7481 `QPassSignals' No `-' Yes 7482 `QStartNoAckMode' No `-' Yes 7483 `multiprocess' No `-' No 7484 `ConditionalTracepoints'No `-' No 7485 `ReverseContinue' No `-' No 7486 `ReverseStep' No `-' No 7487 `TracepointSource' No `-' No 7488 `QAllow' No `-' No 7489 7490 These are the currently defined stub features, in more detail: 7491 7492 `PacketSize=BYTES' 7493 The remote stub can accept packets up to at least BYTES in 7494 length. GDB will send packets up to this size for bulk 7495 transfers, and will never send larger packets. This is a 7496 limit on the data characters in the packet, including the 7497 frame and checksum. There is no trailing NUL byte in a 7498 remote protocol packet; if the stub stores packets in a 7499 NUL-terminated format, it should allow an extra byte in its 7500 buffer for the NUL. If this stub feature is not supported, 7501 GDB guesses based on the size of the `g' packet response. 7502 7503 `qXfer:auxv:read' 7504 The remote stub understands the `qXfer:auxv:read' packet 7505 (*note qXfer auxiliary vector read::). 7506 7507 `qXfer:features:read' 7508 The remote stub understands the `qXfer:features:read' packet 7509 (*note qXfer target description read::). 7510 7511 `qXfer:libraries:read' 7512 The remote stub understands the `qXfer:libraries:read' packet 7513 (*note qXfer library list read::). 7514 7515 `qXfer:memory-map:read' 7516 The remote stub understands the `qXfer:memory-map:read' packet 7517 (*note qXfer memory map read::). 7518 7519 `qXfer:sdata:read' 7520 The remote stub understands the `qXfer:sdata:read' packet 7521 (*note qXfer sdata read::). 7522 7523 `qXfer:spu:read' 7524 The remote stub understands the `qXfer:spu:read' packet 7525 (*note qXfer spu read::). 7526 7527 `qXfer:spu:write' 7528 The remote stub understands the `qXfer:spu:write' packet 7529 (*note qXfer spu write::). 7530 7531 `qXfer:siginfo:read' 7532 The remote stub understands the `qXfer:siginfo:read' packet 7533 (*note qXfer siginfo read::). 7534 7535 `qXfer:siginfo:write' 7536 The remote stub understands the `qXfer:siginfo:write' packet 7537 (*note qXfer siginfo write::). 7538 7539 `qXfer:threads:read' 7540 The remote stub understands the `qXfer:threads:read' packet 7541 (*note qXfer threads read::). 7542 7543 `qXfer:traceframe-info:read' 7544 The remote stub understands the `qXfer:traceframe-info:read' 7545 packet (*note qXfer traceframe info read::). 7546 7547 `QNonStop' 7548 The remote stub understands the `QNonStop' packet (*note 7549 QNonStop::). 7550 7551 `QPassSignals' 7552 The remote stub understands the `QPassSignals' packet (*note 7553 QPassSignals::). 7554 7555 `QStartNoAckMode' 7556 The remote stub understands the `QStartNoAckMode' packet and 7557 prefers to operate in no-acknowledgment mode. *Note Packet 7558 Acknowledgment::. 7559 7560 `multiprocess' 7561 The remote stub understands the multiprocess extensions to 7562 the remote protocol syntax. The multiprocess extensions 7563 affect the syntax of thread IDs in both packets and replies 7564 (*note thread-id syntax::), and add process IDs to the `D' 7565 packet and `W' and `X' replies. Note that reporting this 7566 feature indicates support for the syntactic extensions only, 7567 not that the stub necessarily supports debugging of more than 7568 one process at a time. The stub must not use multiprocess 7569 extensions in packet replies unless GDB has also indicated it 7570 supports them in its `qSupported' request. 7571 7572 `qXfer:osdata:read' 7573 The remote stub understands the `qXfer:osdata:read' packet 7574 ((*note qXfer osdata read::). 7575 7576 `ConditionalTracepoints' 7577 The remote stub accepts and implements conditional 7578 expressions defined for tracepoints (*note Tracepoint 7579 Conditions::). 7580 7581 `ReverseContinue' 7582 The remote stub accepts and implements the reverse continue 7583 packet (*note bc::). 7584 7585 `ReverseStep' 7586 The remote stub accepts and implements the reverse step packet 7587 (*note bs::). 7588 7589 `TracepointSource' 7590 The remote stub understands the `QTDPsrc' packet that supplies 7591 the source form of tracepoint definitions. 7592 7593 `QAllow' 7594 The remote stub understands the `QAllow' packet. 7595 7596 `StaticTracepoint' 7597 The remote stub supports static tracepoints. 7598 7599 7600`qSymbol::' 7601 Notify the target that GDB is prepared to serve symbol lookup 7602 requests. Accept requests from the target for the values of 7603 symbols. 7604 7605 Reply: 7606 `OK' 7607 The target does not need to look up any (more) symbols. 7608 7609 `qSymbol:SYM_NAME' 7610 The target requests the value of symbol SYM_NAME (hex 7611 encoded). GDB may provide the value by using the 7612 `qSymbol:SYM_VALUE:SYM_NAME' message, described below. 7613 7614`qSymbol:SYM_VALUE:SYM_NAME' 7615 Set the value of SYM_NAME to SYM_VALUE. 7616 7617 SYM_NAME (hex encoded) is the name of a symbol whose value the 7618 target has previously requested. 7619 7620 SYM_VALUE (hex) is the value for symbol SYM_NAME. If GDB cannot 7621 supply a value for SYM_NAME, then this field will be empty. 7622 7623 Reply: 7624 `OK' 7625 The target does not need to look up any (more) symbols. 7626 7627 `qSymbol:SYM_NAME' 7628 The target requests the value of a new symbol SYM_NAME (hex 7629 encoded). GDB will continue to supply the values of symbols 7630 (if available), until the target ceases to request them. 7631 7632`qTBuffer' 7633 7634`QTBuffer' 7635 7636`QTDisconnected' 7637`QTDP' 7638`QTDPsrc' 7639`QTDV' 7640`qTfP' 7641`qTfV' 7642`QTFrame' 7643 *Note Tracepoint Packets::. 7644 7645`qThreadExtraInfo,THREAD-ID' 7646 Obtain a printable string description of a thread's attributes from 7647 the target OS. THREAD-ID is a thread ID; see *Note thread-id 7648 syntax::. This string may contain anything that the target OS 7649 thinks is interesting for GDB to tell the user about the thread. 7650 The string is displayed in GDB's `info threads' display. Some 7651 examples of possible thread extra info strings are `Runnable', or 7652 `Blocked on Mutex'. 7653 7654 Reply: 7655 `XX...' 7656 Where `XX...' is a hex encoding of ASCII data, comprising the 7657 printable string containing the extra information about the 7658 thread's attributes. 7659 7660 (Note that the `qThreadExtraInfo' packet's name is separated from 7661 the command by a `,', not a `:', contrary to the naming 7662 conventions above. Please don't use this packet as a model for new 7663 packets.) 7664 7665`QTSave' 7666 7667`qTsP' 7668 7669`qTsV' 7670`QTStart' 7671`QTStop' 7672`QTinit' 7673`QTro' 7674`qTStatus' 7675`qTV' 7676`qTfSTM' 7677`qTsSTM' 7678`qTSTMat' 7679 *Note Tracepoint Packets::. 7680 7681`qXfer:OBJECT:read:ANNEX:OFFSET,LENGTH' 7682 Read uninterpreted bytes from the target's special data area 7683 identified by the keyword OBJECT. Request LENGTH bytes starting 7684 at OFFSET bytes into the data. The content and encoding of ANNEX 7685 is specific to OBJECT; it can supply additional details about what 7686 data to access. 7687 7688 Here are the specific requests of this form defined so far. All 7689 `qXfer:OBJECT:read:...' requests use the same reply formats, 7690 listed below. 7691 7692 `qXfer:auxv:read::OFFSET,LENGTH' 7693 Access the target's "auxiliary vector". *Note auxiliary 7694 vector: OS Information. Note ANNEX must be empty. 7695 7696 This packet is not probed by default; the remote stub must 7697 request it, by supplying an appropriate `qSupported' response 7698 (*note qSupported::). 7699 7700 `qXfer:features:read:ANNEX:OFFSET,LENGTH' 7701 Access the "target description". *Note Target 7702 Descriptions::. The annex specifies which XML document to 7703 access. The main description is always loaded from the 7704 `target.xml' annex. 7705 7706 This packet is not probed by default; the remote stub must 7707 request it, by supplying an appropriate `qSupported' response 7708 (*note qSupported::). 7709 7710 `qXfer:libraries:read:ANNEX:OFFSET,LENGTH' 7711 Access the target's list of loaded libraries. *Note Library 7712 List Format::. The annex part of the generic `qXfer' packet 7713 must be empty (*note qXfer read::). 7714 7715 Targets which maintain a list of libraries in the program's 7716 memory do not need to implement this packet; it is designed 7717 for platforms where the operating system manages the list of 7718 loaded libraries. 7719 7720 This packet is not probed by default; the remote stub must 7721 request it, by supplying an appropriate `qSupported' response 7722 (*note qSupported::). 7723 7724 `qXfer:memory-map:read::OFFSET,LENGTH' 7725 Access the target's "memory-map". *Note Memory Map Format::. 7726 The annex part of the generic `qXfer' packet must be empty 7727 (*note qXfer read::). 7728 7729 This packet is not probed by default; the remote stub must 7730 request it, by supplying an appropriate `qSupported' response 7731 (*note qSupported::). 7732 7733 `qXfer:sdata:read::OFFSET,LENGTH' 7734 Read contents of the extra collected static tracepoint marker 7735 information. The annex part of the generic `qXfer' packet 7736 must be empty (*note qXfer read::). *Note Tracepoint Action 7737 Lists: Tracepoint Actions. 7738 7739 This packet is not probed by default; the remote stub must 7740 request it, by supplying an appropriate `qSupported' response 7741 (*note qSupported::). 7742 7743 `qXfer:siginfo:read::OFFSET,LENGTH' 7744 Read contents of the extra signal information on the target 7745 system. The annex part of the generic `qXfer' packet must be 7746 empty (*note qXfer read::). 7747 7748 This packet is not probed by default; the remote stub must 7749 request it, by supplying an appropriate `qSupported' response 7750 (*note qSupported::). 7751 7752 `qXfer:spu:read:ANNEX:OFFSET,LENGTH' 7753 Read contents of an `spufs' file on the target system. The 7754 annex specifies which file to read; it must be of the form 7755 `ID/NAME', where ID specifies an SPU context ID in the target 7756 process, and NAME identifes the `spufs' file in that context 7757 to be accessed. 7758 7759 This packet is not probed by default; the remote stub must 7760 request it, by supplying an appropriate `qSupported' response 7761 (*note qSupported::). 7762 7763 `qXfer:threads:read::OFFSET,LENGTH' 7764 Access the list of threads on target. *Note Thread List 7765 Format::. The annex part of the generic `qXfer' packet must 7766 be empty (*note qXfer read::). 7767 7768 This packet is not probed by default; the remote stub must 7769 request it, by supplying an appropriate `qSupported' response 7770 (*note qSupported::). 7771 7772 `qXfer:traceframe-info:read::OFFSET,LENGTH' 7773 Return a description of the current traceframe's contents. 7774 *Note Traceframe Info Format::. The annex part of the generic 7775 `qXfer' packet must be empty (*note qXfer read::). 7776 7777 This packet is not probed by default; the remote stub must 7778 request it, by supplying an appropriate `qSupported' response 7779 (*note qSupported::). 7780 7781 `qXfer:osdata:read::OFFSET,LENGTH' 7782 Access the target's "operating system information". *Note 7783 Operating System Information::. 7784 7785 7786 Reply: 7787 `m DATA' 7788 Data DATA (*note Binary Data::) has been read from the 7789 target. There may be more data at a higher address (although 7790 it is permitted to return `m' even for the last valid block 7791 of data, as long as at least one byte of data was read). 7792 DATA may have fewer bytes than the LENGTH in the request. 7793 7794 `l DATA' 7795 Data DATA (*note Binary Data::) has been read from the target. 7796 There is no more data to be read. DATA may have fewer bytes 7797 than the LENGTH in the request. 7798 7799 `l' 7800 The OFFSET in the request is at the end of the data. There 7801 is no more data to be read. 7802 7803 `E00' 7804 The request was malformed, or ANNEX was invalid. 7805 7806 `E NN' 7807 The offset was invalid, or there was an error encountered 7808 reading the data. NN is a hex-encoded `errno' value. 7809 7810 `' 7811 An empty reply indicates the OBJECT string was not recognized 7812 by the stub, or that the object does not support reading. 7813 7814`qXfer:OBJECT:write:ANNEX:OFFSET:DATA...' 7815 Write uninterpreted bytes into the target's special data area 7816 identified by the keyword OBJECT, starting at OFFSET bytes into 7817 the data. DATA... is the binary-encoded data (*note Binary 7818 Data::) to be written. The content and encoding of ANNEX is 7819 specific to OBJECT; it can supply additional details about what 7820 data to access. 7821 7822 Here are the specific requests of this form defined so far. All 7823 `qXfer:OBJECT:write:...' requests use the same reply formats, 7824 listed below. 7825 7826 `qXfer:siginfo:write::OFFSET:DATA...' 7827 Write DATA to the extra signal information on the target 7828 system. The annex part of the generic `qXfer' packet must be 7829 empty (*note qXfer write::). 7830 7831 This packet is not probed by default; the remote stub must 7832 request it, by supplying an appropriate `qSupported' response 7833 (*note qSupported::). 7834 7835 `qXfer:spu:write:ANNEX:OFFSET:DATA...' 7836 Write DATA to an `spufs' file on the target system. The 7837 annex specifies which file to write; it must be of the form 7838 `ID/NAME', where ID specifies an SPU context ID in the target 7839 process, and NAME identifes the `spufs' file in that context 7840 to be accessed. 7841 7842 This packet is not probed by default; the remote stub must 7843 request it, by supplying an appropriate `qSupported' response 7844 (*note qSupported::). 7845 7846 Reply: 7847 `NN' 7848 NN (hex encoded) is the number of bytes written. This may be 7849 fewer bytes than supplied in the request. 7850 7851 `E00' 7852 The request was malformed, or ANNEX was invalid. 7853 7854 `E NN' 7855 The offset was invalid, or there was an error encountered 7856 writing the data. NN is a hex-encoded `errno' value. 7857 7858 `' 7859 An empty reply indicates the OBJECT string was not recognized 7860 by the stub, or that the object does not support writing. 7861 7862`qXfer:OBJECT:OPERATION:...' 7863 Requests of this form may be added in the future. When a stub does 7864 not recognize the OBJECT keyword, or its support for OBJECT does 7865 not recognize the OPERATION keyword, the stub must respond with an 7866 empty packet. 7867 7868`qAttached:PID' 7869 Return an indication of whether the remote server attached to an 7870 existing process or created a new process. When the multiprocess 7871 protocol extensions are supported (*note multiprocess 7872 extensions::), PID is an integer in hexadecimal format identifying 7873 the target process. Otherwise, GDB will omit the PID field and 7874 the query packet will be simplified as `qAttached'. 7875 7876 This query is used, for example, to know whether the remote process 7877 should be detached or killed when a GDB session is ended with the 7878 `quit' command. 7879 7880 Reply: 7881 `1' 7882 The remote server attached to an existing process. 7883 7884 `0' 7885 The remote server created a new process. 7886 7887 `E NN' 7888 A badly formed request or an error was encountered. 7889 7890 7891 ---------- Footnotes ---------- 7892 7893 (1) The `qP' and `qL' packets predate these conventions, and have 7894arguments without any terminator for the packet name; we suspect they 7895are in widespread use in places that are difficult to upgrade. The 7896`qC' packet has no arguments, but some existing stubs (e.g. RedBoot) 7897are known to not check for the end of the packet. 7898 7899 7900File: gdb.info, Node: Architecture-Specific Protocol Details, Next: Tracepoint Packets, Prev: General Query Packets, Up: Remote Protocol 7901 7902E.5 Architecture-Specific Protocol Details 7903========================================== 7904 7905This section describes how the remote protocol is applied to specific 7906target architectures. Also see *Note Standard Target Features::, for 7907details of XML target descriptions for each architecture. 7908 7909E.5.1 ARM 7910--------- 7911 7912E.5.1.1 Breakpoint Kinds 7913........................ 7914 7915These breakpoint kinds are defined for the `Z0' and `Z1' packets. 7916 79172 7918 16-bit Thumb mode breakpoint. 7919 79203 7921 32-bit Thumb mode (Thumb-2) breakpoint. 7922 79234 7924 32-bit ARM mode breakpoint. 7925 7926 7927E.5.2 MIPS 7928---------- 7929 7930E.5.2.1 Register Packet Format 7931.............................. 7932 7933The following `g'/`G' packets have previously been defined. In the 7934below, some thirty-two bit registers are transferred as sixty-four 7935bits. Those registers should be zero/sign extended (which?) to fill 7936the space allocated. Register bytes are transferred in target byte 7937order. The two nibbles within a register byte are transferred 7938most-significant - least-significant. 7939 7940MIPS32 7941 All registers are transferred as thirty-two bit quantities in the 7942 order: 32 general-purpose; sr; lo; hi; bad; cause; pc; 32 7943 floating-point registers; fsr; fir; fp. 7944 7945MIPS64 7946 All registers are transferred as sixty-four bit quantities 7947 (including thirty-two bit registers such as `sr'). The ordering 7948 is the same as `MIPS32'. 7949 7950 7951 7952File: gdb.info, Node: Tracepoint Packets, Next: Host I/O Packets, Prev: Architecture-Specific Protocol Details, Up: Remote Protocol 7953 7954E.6 Tracepoint Packets 7955====================== 7956 7957Here we describe the packets GDB uses to implement tracepoints (*note 7958Tracepoints::). 7959 7960`QTDP:N:ADDR:ENA:STEP:PASS[:FFLEN][:XLEN,BYTES][-]' 7961 Create a new tracepoint, number N, at ADDR. If ENA is `E', then 7962 the tracepoint is enabled; if it is `D', then the tracepoint is 7963 disabled. STEP is the tracepoint's step count, and PASS is its 7964 pass count. If an `F' is present, then the tracepoint is to be a 7965 fast tracepoint, and the FLEN is the number of bytes that the 7966 target should copy elsewhere to make room for the tracepoint. If 7967 an `X' is present, it introduces a tracepoint condition, which 7968 consists of a hexadecimal length, followed by a comma and 7969 hex-encoded bytes, in a manner similar to action encodings as 7970 described below. If the trailing `-' is present, further `QTDP' 7971 packets will follow to specify this tracepoint's actions. 7972 7973 Replies: 7974 `OK' 7975 The packet was understood and carried out. 7976 7977 `qRelocInsn' 7978 *Note Relocate instruction reply packet: Tracepoint Packets. 7979 7980 `' 7981 The packet was not recognized. 7982 7983`QTDP:-N:ADDR:[S]ACTION...[-]' 7984 Define actions to be taken when a tracepoint is hit. N and ADDR 7985 must be the same as in the initial `QTDP' packet for this 7986 tracepoint. This packet may only be sent immediately after 7987 another `QTDP' packet that ended with a `-'. If the trailing `-' 7988 is present, further `QTDP' packets will follow, specifying more 7989 actions for this tracepoint. 7990 7991 In the series of action packets for a given tracepoint, at most one 7992 can have an `S' before its first ACTION. If such a packet is 7993 sent, it and the following packets define "while-stepping" 7994 actions. Any prior packets define ordinary actions -- that is, 7995 those taken when the tracepoint is first hit. If no action packet 7996 has an `S', then all the packets in the series specify ordinary 7997 tracepoint actions. 7998 7999 The `ACTION...' portion of the packet is a series of actions, 8000 concatenated without separators. Each action has one of the 8001 following forms: 8002 8003 `R MASK' 8004 Collect the registers whose bits are set in MASK. MASK is a 8005 hexadecimal number whose I'th bit is set if register number I 8006 should be collected. (The least significant bit is numbered 8007 zero.) Note that MASK may be any number of digits long; it 8008 may not fit in a 32-bit word. 8009 8010 `M BASEREG,OFFSET,LEN' 8011 Collect LEN bytes of memory starting at the address in 8012 register number BASEREG, plus OFFSET. If BASEREG is `-1', 8013 then the range has a fixed address: OFFSET is the address of 8014 the lowest byte to collect. The BASEREG, OFFSET, and LEN 8015 parameters are all unsigned hexadecimal values (the `-1' 8016 value for BASEREG is a special case). 8017 8018 `X LEN,EXPR' 8019 Evaluate EXPR, whose length is LEN, and collect memory as it 8020 directs. EXPR is an agent expression, as described in *Note 8021 Agent Expressions::. Each byte of the expression is encoded 8022 as a two-digit hex number in the packet; LEN is the number of 8023 bytes in the expression (and thus one-half the number of hex 8024 digits in the packet). 8025 8026 8027 Any number of actions may be packed together in a single `QTDP' 8028 packet, as long as the packet does not exceed the maximum packet 8029 length (400 bytes, for many stubs). There may be only one `R' 8030 action per tracepoint, and it must precede any `M' or `X' actions. 8031 Any registers referred to by `M' and `X' actions must be 8032 collected by a preceding `R' action. (The "while-stepping" 8033 actions are treated as if they were attached to a separate 8034 tracepoint, as far as these restrictions are concerned.) 8035 8036 Replies: 8037 `OK' 8038 The packet was understood and carried out. 8039 8040 `qRelocInsn' 8041 *Note Relocate instruction reply packet: Tracepoint Packets. 8042 8043 `' 8044 The packet was not recognized. 8045 8046`QTDPsrc:N:ADDR:TYPE:START:SLEN:BYTES' 8047 Specify a source string of tracepoint N at address ADDR. This is 8048 useful to get accurate reproduction of the tracepoints originally 8049 downloaded at the beginning of the trace run. TYPE is the name of 8050 the tracepoint part, such as `cond' for the tracepoint's 8051 conditional expression (see below for a list of types), while 8052 BYTES is the string, encoded in hexadecimal. 8053 8054 START is the offset of the BYTES within the overall source string, 8055 while SLEN is the total length of the source string. This is 8056 intended for handling source strings that are longer than will fit 8057 in a single packet. 8058 8059 The available string types are `at' for the location, `cond' for 8060 the conditional, and `cmd' for an action command. GDB sends a 8061 separate packet for each command in the action list, in the same 8062 order in which the commands are stored in the list. 8063 8064 The target does not need to do anything with source strings except 8065 report them back as part of the replies to the `qTfP'/`qTsP' query 8066 packets. 8067 8068 Although this packet is optional, and GDB will only send it if the 8069 target replies with `TracepointSource' *Note General Query 8070 Packets::, it makes both disconnected tracing and trace files much 8071 easier to use. Otherwise the user must be careful that the 8072 tracepoints in effect while looking at trace frames are identical 8073 to the ones in effect during the trace run; even a small 8074 discrepancy could cause `tdump' not to work, or a particular trace 8075 frame not be found. 8076 8077`QTDV:N:VALUE' 8078 Create a new trace state variable, number N, with an initial value 8079 of VALUE, which is a 64-bit signed integer. Both N and VALUE are 8080 encoded as hexadecimal values. GDB has the option of not using 8081 this packet for initial values of zero; the target should simply 8082 create the trace state variables as they are mentioned in 8083 expressions. 8084 8085`QTFrame:N' 8086 Select the N'th tracepoint frame from the buffer, and use the 8087 register and memory contents recorded there to answer subsequent 8088 request packets from GDB. 8089 8090 A successful reply from the stub indicates that the stub has found 8091 the requested frame. The response is a series of parts, 8092 concatenated without separators, describing the frame we selected. 8093 Each part has one of the following forms: 8094 8095 `F F' 8096 The selected frame is number N in the trace frame buffer; F 8097 is a hexadecimal number. If F is `-1', then there was no 8098 frame matching the criteria in the request packet. 8099 8100 `T T' 8101 The selected trace frame records a hit of tracepoint number T; 8102 T is a hexadecimal number. 8103 8104 8105`QTFrame:pc:ADDR' 8106 Like `QTFrame:N', but select the first tracepoint frame after the 8107 currently selected frame whose PC is ADDR; ADDR is a hexadecimal 8108 number. 8109 8110`QTFrame:tdp:T' 8111 Like `QTFrame:N', but select the first tracepoint frame after the 8112 currently selected frame that is a hit of tracepoint T; T is a 8113 hexadecimal number. 8114 8115`QTFrame:range:START:END' 8116 Like `QTFrame:N', but select the first tracepoint frame after the 8117 currently selected frame whose PC is between START (inclusive) and 8118 END (inclusive); START and END are hexadecimal numbers. 8119 8120`QTFrame:outside:START:END' 8121 Like `QTFrame:range:START:END', but select the first frame 8122 _outside_ the given range of addresses (exclusive). 8123 8124`QTStart' 8125 Begin the tracepoint experiment. Begin collecting data from 8126 tracepoint hits in the trace frame buffer. This packet supports 8127 the `qRelocInsn' reply (*note Relocate instruction reply packet: 8128 Tracepoint Packets.). 8129 8130`QTStop' 8131 End the tracepoint experiment. Stop collecting trace frames. 8132 8133`QTinit' 8134 Clear the table of tracepoints, and empty the trace frame buffer. 8135 8136`QTro:START1,END1:START2,END2:...' 8137 Establish the given ranges of memory as "transparent". The stub 8138 will answer requests for these ranges from memory's current 8139 contents, if they were not collected as part of the tracepoint hit. 8140 8141 GDB uses this to mark read-only regions of memory, like those 8142 containing program code. Since these areas never change, they 8143 should still have the same contents they did when the tracepoint 8144 was hit, so there's no reason for the stub to refuse to provide 8145 their contents. 8146 8147`QTDisconnected:VALUE' 8148 Set the choice to what to do with the tracing run when GDB 8149 disconnects from the target. A VALUE of 1 directs the target to 8150 continue the tracing run, while 0 tells the target to stop tracing 8151 if GDB is no longer in the picture. 8152 8153`qTStatus' 8154 Ask the stub if there is a trace experiment running right now. 8155 8156 The reply has the form: 8157 8158 `TRUNNING[;FIELD]...' 8159 RUNNING is a single digit `1' if the trace is presently 8160 running, or `0' if not. It is followed by semicolon-separated 8161 optional fields that an agent may use to report additional 8162 status. 8163 8164 8165 If the trace is not running, the agent may report any of several 8166 explanations as one of the optional fields: 8167 8168 `tnotrun:0' 8169 No trace has been run yet. 8170 8171 `tstop:0' 8172 The trace was stopped by a user-originated stop command. 8173 8174 `tfull:0' 8175 The trace stopped because the trace buffer filled up. 8176 8177 `tdisconnected:0' 8178 The trace stopped because GDB disconnected from the target. 8179 8180 `tpasscount:TPNUM' 8181 The trace stopped because tracepoint TPNUM exceeded its pass 8182 count. 8183 8184 `terror:TEXT:TPNUM' 8185 The trace stopped because tracepoint TPNUM had an error. The 8186 string TEXT is available to describe the nature of the error 8187 (for instance, a divide by zero in the condition expression). 8188 TEXT is hex encoded. 8189 8190 `tunknown:0' 8191 The trace stopped for some other reason. 8192 8193 8194 Additional optional fields supply statistical and other 8195 information. Although not required, they are extremely useful for 8196 users monitoring the progress of a trace run. If a trace has 8197 stopped, and these numbers are reported, they must reflect the 8198 state of the just-stopped trace. 8199 8200 `tframes:N' 8201 The number of trace frames in the buffer. 8202 8203 `tcreated:N' 8204 The total number of trace frames created during the run. This 8205 may be larger than the trace frame count, if the buffer is 8206 circular. 8207 8208 `tsize:N' 8209 The total size of the trace buffer, in bytes. 8210 8211 `tfree:N' 8212 The number of bytes still unused in the buffer. 8213 8214 `circular:N' 8215 The value of the circular trace buffer flag. `1' means that 8216 the trace buffer is circular and old trace frames will be 8217 discarded if necessary to make room, `0' means that the trace 8218 buffer is linear and may fill up. 8219 8220 `disconn:N' 8221 The value of the disconnected tracing flag. `1' means that 8222 tracing will continue after GDB disconnects, `0' means that 8223 the trace run will stop. 8224 8225 8226`qTV:VAR' 8227 Ask the stub for the value of the trace state variable number VAR. 8228 8229 Replies: 8230 `VVALUE' 8231 The value of the variable is VALUE. This will be the current 8232 value of the variable if the user is examining a running 8233 target, or a saved value if the variable was collected in the 8234 trace frame that the user is looking at. Note that multiple 8235 requests may result in different reply values, such as when 8236 requesting values while the program is running. 8237 8238 `U' 8239 The value of the variable is unknown. This would occur, for 8240 example, if the user is examining a trace frame in which the 8241 requested variable was not collected. 8242 8243`qTfP' 8244`qTsP' 8245 These packets request data about tracepoints that are being used by 8246 the target. GDB sends `qTfP' to get the first piece of data, and 8247 multiple `qTsP' to get additional pieces. Replies to these 8248 packets generally take the form of the `QTDP' packets that define 8249 tracepoints. (FIXME add detailed syntax) 8250 8251`qTfV' 8252`qTsV' 8253 These packets request data about trace state variables that are on 8254 the target. GDB sends `qTfV' to get the first vari of data, and 8255 multiple `qTsV' to get additional variables. Replies to these 8256 packets follow the syntax of the `QTDV' packets that define trace 8257 state variables. 8258 8259`qTfSTM' 8260`qTsSTM' 8261 These packets request data about static tracepoint markers that 8262 exist in the target program. GDB sends `qTfSTM' to get the first 8263 piece of data, and multiple `qTsSTM' to get additional pieces. 8264 Replies to these packets take the following form: 8265 8266 Reply: 8267 `m ADDRESS:ID:EXTRA' 8268 A single marker 8269 8270 `m ADDRESS:ID:EXTRA,ADDRESS:ID:EXTRA...' 8271 a comma-separated list of markers 8272 8273 `l' 8274 (lower case letter `L') denotes end of list. 8275 8276 `E NN' 8277 An error occurred. NN are hex digits. 8278 8279 `' 8280 An empty reply indicates that the request is not supported by 8281 the stub. 8282 8283 ADDRESS is encoded in hex. ID and EXTRA are strings encoded in 8284 hex. 8285 8286 In response to each query, the target will reply with a list of 8287 one or more markers, separated by commas. GDB will respond to each 8288 reply with a request for more markers (using the `qs' form of the 8289 query), until the target responds with `l' (lower-case ell, for 8290 "last"). 8291 8292`qTSTMat:ADDRESS' 8293 This packets requests data about static tracepoint markers in the 8294 target program at ADDRESS. Replies to this packet follow the 8295 syntax of the `qTfSTM' and `qTsSTM' packets that list static 8296 tracepoint markers. 8297 8298`QTSave:FILENAME' 8299 This packet directs the target to save trace data to the file name 8300 FILENAME in the target's filesystem. FILENAME is encoded as a hex 8301 string; the interpretation of the file name (relative vs absolute, 8302 wild cards, etc) is up to the target. 8303 8304`qTBuffer:OFFSET,LEN' 8305 Return up to LEN bytes of the current contents of trace buffer, 8306 starting at OFFSET. The trace buffer is treated as if it were a 8307 contiguous collection of traceframes, as per the trace file format. 8308 The reply consists as many hex-encoded bytes as the target can 8309 deliver in a packet; it is not an error to return fewer than were 8310 asked for. A reply consisting of just `l' indicates that no bytes 8311 are available. 8312 8313`QTBuffer:circular:VALUE' 8314 This packet directs the target to use a circular trace buffer if 8315 VALUE is 1, or a linear buffer if the value is 0. 8316 8317 8318E.6.1 Relocate instruction reply packet 8319--------------------------------------- 8320 8321When installing fast tracepoints in memory, the target may need to 8322relocate the instruction currently at the tracepoint address to a 8323different address in memory. For most instructions, a simple copy is 8324enough, but, for example, call instructions that implicitly push the 8325return address on the stack, and relative branches or other PC-relative 8326instructions require offset adjustment, so that the effect of executing 8327the instruction at a different address is the same as if it had 8328executed in the original location. 8329 8330 In response to several of the tracepoint packets, the target may also 8331respond with a number of intermediate `qRelocInsn' request packets 8332before the final result packet, to have GDB handle this relocation 8333operation. If a packet supports this mechanism, its documentation will 8334explicitly say so. See for example the above descriptions for the 8335`QTStart' and `QTDP' packets. The format of the request is: 8336 8337`qRelocInsn:FROM;TO' 8338 This requests GDB to copy instruction at address FROM to address 8339 TO, possibly adjusted so that executing the instruction at TO has 8340 the same effect as executing it at FROM. GDB writes the adjusted 8341 instruction to target memory starting at TO. 8342 8343 Replies: 8344`qRelocInsn:ADJUSTED_SIZE' 8345 Informs the stub the relocation is complete. ADJUSTED_SIZE is the 8346 length in bytes of resulting relocated instruction sequence. 8347 8348`E NN' 8349 A badly formed request was detected, or an error was encountered 8350 while relocating the instruction. 8351 8352 8353File: gdb.info, Node: Host I/O Packets, Next: Interrupts, Prev: Tracepoint Packets, Up: Remote Protocol 8354 8355E.7 Host I/O Packets 8356==================== 8357 8358The "Host I/O" packets allow GDB to perform I/O operations on the far 8359side of a remote link. For example, Host I/O is used to upload and 8360download files to a remote target with its own filesystem. Host I/O 8361uses the same constant values and data structure layout as the 8362target-initiated File-I/O protocol. However, the Host I/O packets are 8363structured differently. The target-initiated protocol relies on target 8364memory to store parameters and buffers. Host I/O requests are 8365initiated by GDB, and the target's memory is not involved. *Note 8366File-I/O Remote Protocol Extension::, for more details on the 8367target-initiated protocol. 8368 8369 The Host I/O request packets all encode a single operation along with 8370its arguments. They have this format: 8371 8372`vFile:OPERATION: PARAMETER...' 8373 OPERATION is the name of the particular request; the target should 8374 compare the entire packet name up to the second colon when checking 8375 for a supported operation. The format of PARAMETER depends on the 8376 operation. Numbers are always passed in hexadecimal. Negative 8377 numbers have an explicit minus sign (i.e. two's complement is not 8378 used). Strings (e.g. filenames) are encoded as a series of 8379 hexadecimal bytes. The last argument to a system call may be a 8380 buffer of escaped binary data (*note Binary Data::). 8381 8382 8383 The valid responses to Host I/O packets are: 8384 8385`F RESULT [, ERRNO] [; ATTACHMENT]' 8386 RESULT is the integer value returned by this operation, usually 8387 non-negative for success and -1 for errors. If an error has 8388 occured, ERRNO will be included in the result. ERRNO will have a 8389 value defined by the File-I/O protocol (*note Errno Values::). For 8390 operations which return data, ATTACHMENT supplies the data as a 8391 binary buffer. Binary buffers in response packets are escaped in 8392 the normal way (*note Binary Data::). See the individual packet 8393 documentation for the interpretation of RESULT and ATTACHMENT. 8394 8395`' 8396 An empty response indicates that this operation is not recognized. 8397 8398 8399 These are the supported Host I/O operations: 8400 8401`vFile:open: PATHNAME, FLAGS, MODE' 8402 Open a file at PATHNAME and return a file descriptor for it, or 8403 return -1 if an error occurs. PATHNAME is a string, FLAGS is an 8404 integer indicating a mask of open flags (*note Open Flags::), and 8405 MODE is an integer indicating a mask of mode bits to use if the 8406 file is created (*note mode_t Values::). *Note open::, for 8407 details of the open flags and mode values. 8408 8409`vFile:close: FD' 8410 Close the open file corresponding to FD and return 0, or -1 if an 8411 error occurs. 8412 8413`vFile:pread: FD, COUNT, OFFSET' 8414 Read data from the open file corresponding to FD. Up to COUNT 8415 bytes will be read from the file, starting at OFFSET relative to 8416 the start of the file. The target may read fewer bytes; common 8417 reasons include packet size limits and an end-of-file condition. 8418 The number of bytes read is returned. Zero should only be 8419 returned for a successful read at the end of the file, or if COUNT 8420 was zero. 8421 8422 The data read should be returned as a binary attachment on success. 8423 If zero bytes were read, the response should include an empty 8424 binary attachment (i.e. a trailing semicolon). The return value 8425 is the number of target bytes read; the binary attachment may be 8426 longer if some characters were escaped. 8427 8428`vFile:pwrite: FD, OFFSET, DATA' 8429 Write DATA (a binary buffer) to the open file corresponding to FD. 8430 Start the write at OFFSET from the start of the file. Unlike 8431 many `write' system calls, there is no separate COUNT argument; 8432 the length of DATA in the packet is used. `vFile:write' returns 8433 the number of bytes written, which may be shorter than the length 8434 of DATA, or -1 if an error occurred. 8435 8436`vFile:unlink: PATHNAME' 8437 Delete the file at PATHNAME on the target. Return 0, or -1 if an 8438 error occurs. PATHNAME is a string. 8439 8440 8441 8442File: gdb.info, Node: Interrupts, Next: Notification Packets, Prev: Host I/O Packets, Up: Remote Protocol 8443 8444E.8 Interrupts 8445============== 8446 8447When a program on the remote target is running, GDB may attempt to 8448interrupt it by sending a `Ctrl-C', `BREAK' or a `BREAK' followed by 8449`g', control of which is specified via GDB's `interrupt-sequence'. 8450 8451 The precise meaning of `BREAK' is defined by the transport mechanism 8452and may, in fact, be undefined. GDB does not currently define a 8453`BREAK' mechanism for any of the network interfaces except for TCP, in 8454which case GDB sends the `telnet' BREAK sequence. 8455 8456 `Ctrl-C', on the other hand, is defined and implemented for all 8457transport mechanisms. It is represented by sending the single byte 8458`0x03' without any of the usual packet overhead described in the 8459Overview section (*note Overview::). When a `0x03' byte is transmitted 8460as part of a packet, it is considered to be packet data and does _not_ 8461represent an interrupt. E.g., an `X' packet (*note X packet::), used 8462for binary downloads, may include an unescaped `0x03' as part of its 8463packet. 8464 8465 `BREAK' followed by `g' is also known as Magic SysRq g. When Linux 8466kernel receives this sequence from serial port, it stops execution and 8467connects to gdb. 8468 8469 Stubs are not required to recognize these interrupt mechanisms and 8470the precise meaning associated with receipt of the interrupt is 8471implementation defined. If the target supports debugging of multiple 8472threads and/or processes, it should attempt to interrupt all 8473currently-executing threads and processes. If the stub is successful 8474at interrupting the running program, it should send one of the stop 8475reply packets (*note Stop Reply Packets::) to GDB as a result of 8476successfully stopping the program in all-stop mode, and a stop reply 8477for each stopped thread in non-stop mode. Interrupts received while the 8478program is stopped are discarded. 8479 8480 8481File: gdb.info, Node: Notification Packets, Next: Remote Non-Stop, Prev: Interrupts, Up: Remote Protocol 8482 8483E.9 Notification Packets 8484======================== 8485 8486The GDB remote serial protocol includes "notifications", packets that 8487require no acknowledgment. Both the GDB and the stub may send 8488notifications (although the only notifications defined at present are 8489sent by the stub). Notifications carry information without incurring 8490the round-trip latency of an acknowledgment, and so are useful for 8491low-impact communications where occasional packet loss is not a problem. 8492 8493 A notification packet has the form `% DATA # CHECKSUM', where DATA 8494is the content of the notification, and CHECKSUM is a checksum of DATA, 8495computed and formatted as for ordinary GDB packets. A notification's 8496DATA never contains `$', `%' or `#' characters. Upon receiving a 8497notification, the recipient sends no `+' or `-' to acknowledge the 8498notification's receipt or to report its corruption. 8499 8500 Every notification's DATA begins with a name, which contains no 8501colon characters, followed by a colon character. 8502 8503 Recipients should silently ignore corrupted notifications and 8504notifications they do not understand. Recipients should restart 8505timeout periods on receipt of a well-formed notification, whether or 8506not they understand it. 8507 8508 Senders should only send the notifications described here when this 8509protocol description specifies that they are permitted. In the future, 8510we may extend the protocol to permit existing notifications in new 8511contexts; this rule helps older senders avoid confusing newer 8512recipients. 8513 8514 (Older versions of GDB ignore bytes received until they see the `$' 8515byte that begins an ordinary packet, so new stubs may transmit 8516notifications without fear of confusing older clients. There are no 8517notifications defined for GDB to send at the moment, but we assume that 8518most older stubs would ignore them, as well.) 8519 8520 The following notification packets from the stub to GDB are defined: 8521 8522`Stop: REPLY' 8523 Report an asynchronous stop event in non-stop mode. The REPLY has 8524 the form of a stop reply, as described in *Note Stop Reply 8525 Packets::. Refer to *Note Remote Non-Stop::, for information on 8526 how these notifications are acknowledged by GDB. 8527 8528