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