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