1This is gdb.info, produced by makeinfo version 4.8 from 2../.././gdb/doc/gdb.texinfo. 3 4INFO-DIR-SECTION Software development 5START-INFO-DIR-ENTRY 6* Gdb: (gdb). The GNU debugger. 7END-INFO-DIR-ENTRY 8 9 This file documents the GNU debugger GDB. 10 11 This is the Ninth Edition, of `Debugging with GDB: the GNU 12Source-Level Debugger' for GDB Version 6.7.1. 13 14 Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996, 151998, 161999, 2000, 2001, 2002, 2003, 2004, 2005, 2006 17Free Software Foundation, Inc. 18 19 Permission is granted to copy, distribute and/or modify this document 20under the terms of the GNU Free Documentation License, Version 1.1 or 21any later version published by the Free Software Foundation; with the 22Invariant Sections being "Free Software" and "Free Software Needs Free 23Documentation", with the Front-Cover Texts being "A GNU Manual," and 24with the Back-Cover Texts as in (a) below. 25 26 (a) The FSF's Back-Cover Text is: "You are free to copy and modify 27this GNU Manual. Buying copies from GNU Press supports the FSF in 28developing GNU and promoting software freedom." 29 30 31File: gdb.info, Node: Manually, Next: Automatically, Prev: Filenames, Up: Setting 32 3312.1.2 Setting the Working Language 34----------------------------------- 35 36If you allow GDB to set the language automatically, expressions are 37interpreted the same way in your debugging session and your program. 38 39 If you wish, you may set the language manually. To do this, issue 40the command `set language LANG', where LANG is the name of a language, 41such as `c' or `modula-2'. For a list of the supported languages, type 42`set language'. 43 44 Setting the language manually prevents GDB from updating the working 45language automatically. This can lead to confusion if you try to debug 46a program when the working language is not the same as the source 47language, when an expression is acceptable to both languages--but means 48different things. For instance, if the current source file were 49written in C, and GDB was parsing Modula-2, a command such as: 50 51 print a = b + c 52 53might not have the effect you intended. In C, this means to add `b' 54and `c' and place the result in `a'. The result printed would be the 55value of `a'. In Modula-2, this means to compare `a' to the result of 56`b+c', yielding a `BOOLEAN' value. 57 58 59File: gdb.info, Node: Automatically, Prev: Manually, Up: Setting 60 6112.1.3 Having GDB Infer the Source Language 62------------------------------------------- 63 64To have GDB set the working language automatically, use `set language 65local' or `set language auto'. GDB then infers the working language. 66That is, when your program stops in a frame (usually by encountering a 67breakpoint), GDB sets the working language to the language recorded for 68the function in that frame. If the language for a frame is unknown 69(that is, if the function or block corresponding to the frame was 70defined in a source file that does not have a recognized extension), 71the current working language is not changed, and GDB issues a warning. 72 73 This may not seem necessary for most programs, which are written 74entirely in one source language. However, program modules and libraries 75written in one source language can be used by a main program written in 76a different source language. Using `set language auto' in this case 77frees you from having to set the working language manually. 78 79 80File: gdb.info, Node: Show, Next: Checks, Prev: Setting, Up: Languages 81 8212.2 Displaying the Language 83============================ 84 85The following commands help you find out which language is the working 86language, and also what language source files were written in. 87 88`show language' 89 Display the current working language. This is the language you 90 can use with commands such as `print' to build and compute 91 expressions that may involve variables in your program. 92 93`info frame' 94 Display the source language for this frame. This language becomes 95 the working language if you use an identifier from this frame. 96 *Note Information about a Frame: Frame Info, to identify the other 97 information listed here. 98 99`info source' 100 Display the source language of this source file. *Note Examining 101 the Symbol Table: Symbols, to identify the other information 102 listed here. 103 104 In unusual circumstances, you may have source files with extensions 105not in the standard list. You can then set the extension associated 106with a language explicitly: 107 108`set extension-language EXT LANGUAGE' 109 Tell GDB that source files with extension EXT are to be assumed as 110 written in the source language LANGUAGE. 111 112`info extensions' 113 List all the filename extensions and the associated languages. 114 115 116File: gdb.info, Node: Checks, Next: Supported Languages, Prev: Show, Up: Languages 117 11812.3 Type and Range Checking 119============================ 120 121 _Warning:_ In this release, the GDB commands for type and range 122 checking are included, but they do not yet have any effect. This 123 section documents the intended facilities. 124 125 Some languages are designed to guard you against making seemingly 126common errors through a series of compile- and run-time checks. These 127include checking the type of arguments to functions and operators, and 128making sure mathematical overflows are caught at run time. Checks such 129as these help to ensure a program's correctness once it has been 130compiled by eliminating type mismatches, and providing active checks 131for range errors when your program is running. 132 133 GDB can check for conditions like the above if you wish. Although 134GDB does not check the statements in your program, it can check 135expressions entered directly into GDB for evaluation via the `print' 136command, for example. As with the working language, GDB can also 137decide whether or not to check automatically based on your program's 138source language. *Note Supported Languages: Supported Languages, for 139the default settings of supported languages. 140 141* Menu: 142 143* Type Checking:: An overview of type checking 144* Range Checking:: An overview of range checking 145 146 147File: gdb.info, Node: Type Checking, Next: Range Checking, Up: Checks 148 14912.3.1 An Overview of Type Checking 150----------------------------------- 151 152Some languages, such as Modula-2, are strongly typed, meaning that the 153arguments to operators and functions have to be of the correct type, 154otherwise an error occurs. These checks prevent type mismatch errors 155from ever causing any run-time problems. For example, 156 157 1 + 2 => 3 158but 159 error--> 1 + 2.3 160 161 The second example fails because the `CARDINAL' 1 is not 162type-compatible with the `REAL' 2.3. 163 164 For the expressions you use in GDB commands, you can tell the GDB 165type checker to skip checking; to treat any mismatches as errors and 166abandon the expression; or to only issue warnings when type mismatches 167occur, but evaluate the expression anyway. When you choose the last of 168these, GDB evaluates expressions like the second example above, but 169also issues a warning. 170 171 Even if you turn type checking off, there may be other reasons 172related to type that prevent GDB from evaluating an expression. For 173instance, GDB does not know how to add an `int' and a `struct foo'. 174These particular type errors have nothing to do with the language in 175use, and usually arise from expressions, such as the one described 176above, which make little sense to evaluate anyway. 177 178 Each language defines to what degree it is strict about type. For 179instance, both Modula-2 and C require the arguments to arithmetical 180operators to be numbers. In C, enumerated types and pointers can be 181represented as numbers, so that they are valid arguments to mathematical 182operators. *Note Supported Languages: Supported Languages, for further 183details on specific languages. 184 185 GDB provides some additional commands for controlling the type 186checker: 187 188`set check type auto' 189 Set type checking on or off based on the current working language. 190 *Note Supported Languages: Supported Languages, for the default 191 settings for each language. 192 193`set check type on' 194`set check type off' 195 Set type checking on or off, overriding the default setting for the 196 current working language. Issue a warning if the setting does not 197 match the language default. If any type mismatches occur in 198 evaluating an expression while type checking is on, GDB prints a 199 message and aborts evaluation of the expression. 200 201`set check type warn' 202 Cause the type checker to issue warnings, but to always attempt to 203 evaluate the expression. Evaluating the expression may still be 204 impossible for other reasons. For example, GDB cannot add numbers 205 and structures. 206 207`show type' 208 Show the current setting of the type checker, and whether or not 209 GDB is setting it automatically. 210 211 212File: gdb.info, Node: Range Checking, Prev: Type Checking, Up: Checks 213 21412.3.2 An Overview of Range Checking 215------------------------------------ 216 217In some languages (such as Modula-2), it is an error to exceed the 218bounds of a type; this is enforced with run-time checks. Such range 219checking is meant to ensure program correctness by making sure 220computations do not overflow, or indices on an array element access do 221not exceed the bounds of the array. 222 223 For expressions you use in GDB commands, you can tell GDB to treat 224range errors in one of three ways: ignore them, always treat them as 225errors and abandon the expression, or issue warnings but evaluate the 226expression anyway. 227 228 A range error can result from numerical overflow, from exceeding an 229array index bound, or when you type a constant that is not a member of 230any type. Some languages, however, do not treat overflows as an error. 231In many implementations of C, mathematical overflow causes the result 232to "wrap around" to lower values--for example, if M is the largest 233integer value, and S is the smallest, then 234 235 M + 1 => S 236 237 This, too, is specific to individual languages, and in some cases 238specific to individual compilers or machines. *Note Supported 239Languages: Supported Languages, for further details on specific 240languages. 241 242 GDB provides some additional commands for controlling the range 243checker: 244 245`set check range auto' 246 Set range checking on or off based on the current working language. 247 *Note Supported Languages: Supported Languages, for the default 248 settings for each language. 249 250`set check range on' 251`set check range off' 252 Set range checking on or off, overriding the default setting for 253 the current working language. A warning is issued if the setting 254 does not match the language default. If a range error occurs and 255 range checking is on, then a message is printed and evaluation of 256 the expression is aborted. 257 258`set check range warn' 259 Output messages when the GDB range checker detects a range error, 260 but attempt to evaluate the expression anyway. Evaluating the 261 expression may still be impossible for other reasons, such as 262 accessing memory that the process does not own (a typical example 263 from many Unix systems). 264 265`show range' 266 Show the current setting of the range checker, and whether or not 267 it is being set automatically by GDB. 268 269 270File: gdb.info, Node: Supported Languages, Next: Unsupported Languages, Prev: Checks, Up: Languages 271 27212.4 Supported Languages 273======================== 274 275GDB supports C, C++, Objective-C, Fortran, Java, Pascal, assembly, 276Modula-2, and Ada. Some GDB features may be used in expressions 277regardless of the language you use: the GDB `@' and `::' operators, and 278the `{type}addr' construct (*note Expressions: Expressions.) can be 279used with the constructs of any supported language. 280 281 The following sections detail to what degree each source language is 282supported by GDB. These sections are not meant to be language 283tutorials or references, but serve only as a reference guide to what the 284GDB expression parser accepts, and what input and output formats should 285look like for different languages. There are many good books written 286on each of these languages; please look to these for a language 287reference or tutorial. 288 289* Menu: 290 291* C:: C and C++ 292* Objective-C:: Objective-C 293* Fortran:: Fortran 294* Pascal:: Pascal 295* Modula-2:: Modula-2 296* Ada:: Ada 297 298 299File: gdb.info, Node: C, Next: Objective-C, Up: Supported Languages 300 30112.4.1 C and C++ 302---------------- 303 304Since C and C++ are so closely related, many features of GDB apply to 305both languages. Whenever this is the case, we discuss those languages 306together. 307 308 The C++ debugging facilities are jointly implemented by the C++ 309compiler and GDB. Therefore, to debug your C++ code effectively, you 310must compile your C++ programs with a supported C++ compiler, such as 311GNU `g++', or the HP ANSI C++ compiler (`aCC'). 312 313 For best results when using GNU C++, use the DWARF 2 debugging 314format; if it doesn't work on your system, try the stabs+ debugging 315format. You can select those formats explicitly with the `g++' 316command-line options `-gdwarf-2' and `-gstabs+'. *Note Options for 317Debugging Your Program or GCC: (gcc.info)Debugging Options. 318 319* Menu: 320 321* C Operators:: C and C++ operators 322* C Constants:: C and C++ constants 323* C Plus Plus Expressions:: C++ expressions 324* C Defaults:: Default settings for C and C++ 325* C Checks:: C and C++ type and range checks 326* Debugging C:: GDB and C 327* Debugging C Plus Plus:: GDB features for C++ 328 329 330File: gdb.info, Node: C Operators, Next: C Constants, Up: C 331 33212.4.1.1 C and C++ Operators 333............................ 334 335Operators must be defined on values of specific types. For instance, 336`+' is defined on numbers, but not on structures. Operators are often 337defined on groups of types. 338 339 For the purposes of C and C++, the following definitions hold: 340 341 * _Integral types_ include `int' with any of its storage-class 342 specifiers; `char'; `enum'; and, for C++, `bool'. 343 344 * _Floating-point types_ include `float', `double', and `long 345 double' (if supported by the target platform). 346 347 * _Pointer types_ include all types defined as `(TYPE *)'. 348 349 * _Scalar types_ include all of the above. 350 351 352The following operators are supported. They are listed here in order 353of increasing precedence: 354 355`,' 356 The comma or sequencing operator. Expressions in a 357 comma-separated list are evaluated from left to right, with the 358 result of the entire expression being the last expression 359 evaluated. 360 361`=' 362 Assignment. The value of an assignment expression is the value 363 assigned. Defined on scalar types. 364 365`OP=' 366 Used in an expression of the form `A OP= B', and translated to 367 `A = A OP B'. `OP=' and `=' have the same precedence. OP is any 368 one of the operators `|', `^', `&', `<<', `>>', `+', `-', `*', 369 `/', `%'. 370 371`?:' 372 The ternary operator. `A ? B : C' can be thought of as: if A 373 then B else C. A should be of an integral type. 374 375`||' 376 Logical OR. Defined on integral types. 377 378`&&' 379 Logical AND. Defined on integral types. 380 381`|' 382 Bitwise OR. Defined on integral types. 383 384`^' 385 Bitwise exclusive-OR. Defined on integral types. 386 387`&' 388 Bitwise AND. Defined on integral types. 389 390`==, !=' 391 Equality and inequality. Defined on scalar types. The value of 392 these expressions is 0 for false and non-zero for true. 393 394`<, >, <=, >=' 395 Less than, greater than, less than or equal, greater than or equal. 396 Defined on scalar types. The value of these expressions is 0 for 397 false and non-zero for true. 398 399`<<, >>' 400 left shift, and right shift. Defined on integral types. 401 402`@' 403 The GDB "artificial array" operator (*note Expressions: 404 Expressions.). 405 406`+, -' 407 Addition and subtraction. Defined on integral types, 408 floating-point types and pointer types. 409 410`*, /, %' 411 Multiplication, division, and modulus. Multiplication and 412 division are defined on integral and floating-point types. 413 Modulus is defined on integral types. 414 415`++, --' 416 Increment and decrement. When appearing before a variable, the 417 operation is performed before the variable is used in an 418 expression; when appearing after it, the variable's value is used 419 before the operation takes place. 420 421`*' 422 Pointer dereferencing. Defined on pointer types. Same precedence 423 as `++'. 424 425`&' 426 Address operator. Defined on variables. Same precedence as `++'. 427 428 For debugging C++, GDB implements a use of `&' beyond what is 429 allowed in the C++ language itself: you can use `&(&REF)' (or, if 430 you prefer, simply `&&REF') to examine the address where a C++ 431 reference variable (declared with `&REF') is stored. 432 433`-' 434 Negative. Defined on integral and floating-point types. Same 435 precedence as `++'. 436 437`!' 438 Logical negation. Defined on integral types. Same precedence as 439 `++'. 440 441`~' 442 Bitwise complement operator. Defined on integral types. Same 443 precedence as `++'. 444 445`., ->' 446 Structure member, and pointer-to-structure member. For 447 convenience, GDB regards the two as equivalent, choosing whether 448 to dereference a pointer based on the stored type information. 449 Defined on `struct' and `union' data. 450 451`.*, ->*' 452 Dereferences of pointers to members. 453 454`[]' 455 Array indexing. `A[I]' is defined as `*(A+I)'. Same precedence 456 as `->'. 457 458`()' 459 Function parameter list. Same precedence as `->'. 460 461`::' 462 C++ scope resolution operator. Defined on `struct', `union', and 463 `class' types. 464 465`::' 466 Doubled colons also represent the GDB scope operator (*note 467 Expressions: Expressions.). Same precedence as `::', above. 468 469 If an operator is redefined in the user code, GDB usually attempts 470to invoke the redefined version instead of using the operator's 471predefined meaning. 472 473 474File: gdb.info, Node: C Constants, Next: C Plus Plus Expressions, Prev: C Operators, Up: C 475 47612.4.1.2 C and C++ Constants 477............................ 478 479GDB allows you to express the constants of C and C++ in the following 480ways: 481 482 * Integer constants are a sequence of digits. Octal constants are 483 specified by a leading `0' (i.e. zero), and hexadecimal constants 484 by a leading `0x' or `0X'. Constants may also end with a letter 485 `l', specifying that the constant should be treated as a `long' 486 value. 487 488 * Floating point constants are a sequence of digits, followed by a 489 decimal point, followed by a sequence of digits, and optionally 490 followed by an exponent. An exponent is of the form: 491 `e[[+]|-]NNN', where NNN is another sequence of digits. The `+' 492 is optional for positive exponents. A floating-point constant may 493 also end with a letter `f' or `F', specifying that the constant 494 should be treated as being of the `float' (as opposed to the 495 default `double') type; or with a letter `l' or `L', which 496 specifies a `long double' constant. 497 498 * Enumerated constants consist of enumerated identifiers, or their 499 integral equivalents. 500 501 * Character constants are a single character surrounded by single 502 quotes (`''), or a number--the ordinal value of the corresponding 503 character (usually its ASCII value). Within quotes, the single 504 character may be represented by a letter or by "escape sequences", 505 which are of the form `\NNN', where NNN is the octal representation 506 of the character's ordinal value; or of the form `\X', where `X' 507 is a predefined special character--for example, `\n' for newline. 508 509 * String constants are a sequence of character constants surrounded 510 by double quotes (`"'). Any valid character constant (as described 511 above) may appear. Double quotes within the string must be 512 preceded by a backslash, so for instance `"a\"b'c"' is a string of 513 five characters. 514 515 * Pointer constants are an integral value. You can also write 516 pointers to constants using the C operator `&'. 517 518 * Array constants are comma-separated lists surrounded by braces `{' 519 and `}'; for example, `{1,2,3}' is a three-element array of 520 integers, `{{1,2}, {3,4}, {5,6}}' is a three-by-two array, and 521 `{&"hi", &"there", &"fred"}' is a three-element array of pointers. 522 523 524File: gdb.info, Node: C Plus Plus Expressions, Next: C Defaults, Prev: C Constants, Up: C 525 52612.4.1.3 C++ Expressions 527........................ 528 529GDB expression handling can interpret most C++ expressions. 530 531 _Warning:_ GDB can only debug C++ code if you use the proper 532 compiler and the proper debug format. Currently, GDB works best 533 when debugging C++ code that is compiled with GCC 2.95.3 or with 534 GCC 3.1 or newer, using the options `-gdwarf-2' or `-gstabs+'. 535 DWARF 2 is preferred over stabs+. Most configurations of GCC emit 536 either DWARF 2 or stabs+ as their default debug format, so you 537 usually don't need to specify a debug format explicitly. Other 538 compilers and/or debug formats are likely to work badly or not at 539 all when using GDB to debug C++ code. 540 541 1. Member function calls are allowed; you can use expressions like 542 543 count = aml->GetOriginal(x, y) 544 545 2. While a member function is active (in the selected stack frame), 546 your expressions have the same namespace available as the member 547 function; that is, GDB allows implicit references to the class 548 instance pointer `this' following the same rules as C++. 549 550 3. You can call overloaded functions; GDB resolves the function call 551 to the right definition, with some restrictions. GDB does not 552 perform overload resolution involving user-defined type 553 conversions, calls to constructors, or instantiations of templates 554 that do not exist in the program. It also cannot handle ellipsis 555 argument lists or default arguments. 556 557 It does perform integral conversions and promotions, floating-point 558 promotions, arithmetic conversions, pointer conversions, 559 conversions of class objects to base classes, and standard 560 conversions such as those of functions or arrays to pointers; it 561 requires an exact match on the number of function arguments. 562 563 Overload resolution is always performed, unless you have specified 564 `set overload-resolution off'. *Note GDB Features for C++: 565 Debugging C Plus Plus. 566 567 You must specify `set overload-resolution off' in order to use an 568 explicit function signature to call an overloaded function, as in 569 p 'foo(char,int)'('x', 13) 570 571 The GDB command-completion facility can simplify this; see *Note 572 Command Completion: Completion. 573 574 4. GDB understands variables declared as C++ references; you can use 575 them in expressions just as you do in C++ source--they are 576 automatically dereferenced. 577 578 In the parameter list shown when GDB displays a frame, the values 579 of reference variables are not displayed (unlike other variables); 580 this avoids clutter, since references are often used for large 581 structures. The _address_ of a reference variable is always 582 shown, unless you have specified `set print address off'. 583 584 5. GDB supports the C++ name resolution operator `::'--your 585 expressions can use it just as expressions in your program do. 586 Since one scope may be defined in another, you can use `::' 587 repeatedly if necessary, for example in an expression like 588 `SCOPE1::SCOPE2::NAME'. GDB also allows resolving name scope by 589 reference to source files, in both C and C++ debugging (*note 590 Program Variables: Variables.). 591 592 In addition, when used with HP's C++ compiler, GDB supports calling 593virtual functions correctly, printing out virtual bases of objects, 594calling functions in a base subobject, casting objects, and invoking 595user-defined operators. 596 597 598File: gdb.info, Node: C Defaults, Next: C Checks, Prev: C Plus Plus Expressions, Up: C 599 60012.4.1.4 C and C++ Defaults 601........................... 602 603If you allow GDB to set type and range checking automatically, they 604both default to `off' whenever the working language changes to C or 605C++. This happens regardless of whether you or GDB selects the working 606language. 607 608 If you allow GDB to set the language automatically, it recognizes 609source files whose names end with `.c', `.C', or `.cc', etc, and when 610GDB enters code compiled from one of these files, it sets the working 611language to C or C++. *Note Having GDB Infer the Source Language: 612Automatically, for further details. 613 614 615File: gdb.info, Node: C Checks, Next: Debugging C, Prev: C Defaults, Up: C 616 61712.4.1.5 C and C++ Type and Range Checks 618........................................ 619 620By default, when GDB parses C or C++ expressions, type checking is not 621used. However, if you turn type checking on, GDB considers two 622variables type equivalent if: 623 624 * The two variables are structured and have the same structure, 625 union, or enumerated tag. 626 627 * The two variables have the same type name, or types that have been 628 declared equivalent through `typedef'. 629 630 631 Range checking, if turned on, is done on mathematical operations. 632Array indices are not checked, since they are often used to index a 633pointer that is not itself an array. 634 635 636File: gdb.info, Node: Debugging C, Next: Debugging C Plus Plus, Prev: C Checks, Up: C 637 63812.4.1.6 GDB and C 639.................. 640 641The `set print union' and `show print union' commands apply to the 642`union' type. When set to `on', any `union' that is inside a `struct' 643or `class' is also printed. Otherwise, it appears as `{...}'. 644 645 The `@' operator aids in the debugging of dynamic arrays, formed 646with pointers and a memory allocation function. *Note Expressions: 647Expressions. 648 649 650File: gdb.info, Node: Debugging C Plus Plus, Prev: Debugging C, Up: C 651 65212.4.1.7 GDB Features for C++ 653............................. 654 655Some GDB commands are particularly useful with C++, and some are 656designed specifically for use with C++. Here is a summary: 657 658`breakpoint menus' 659 When you want a breakpoint in a function whose name is overloaded, 660 GDB breakpoint menus help you specify which function definition 661 you want. *Note Breakpoint Menus: Breakpoint Menus. 662 663`rbreak REGEX' 664 Setting breakpoints using regular expressions is helpful for 665 setting breakpoints on overloaded functions that are not members 666 of any special classes. *Note Setting Breakpoints: Set Breaks. 667 668`catch throw' 669`catch catch' 670 Debug C++ exception handling using these commands. *Note Setting 671 Catchpoints: Set Catchpoints. 672 673`ptype TYPENAME' 674 Print inheritance relationships as well as other information for 675 type TYPENAME. *Note Examining the Symbol Table: Symbols. 676 677`set print demangle' 678`show print demangle' 679`set print asm-demangle' 680`show print asm-demangle' 681 Control whether C++ symbols display in their source form, both when 682 displaying code as C++ source and when displaying disassemblies. 683 *Note Print Settings: Print Settings. 684 685`set print object' 686`show print object' 687 Choose whether to print derived (actual) or declared types of 688 objects. *Note Print Settings: Print Settings. 689 690`set print vtbl' 691`show print vtbl' 692 Control the format for printing virtual function tables. *Note 693 Print Settings: Print Settings. (The `vtbl' commands do not work 694 on programs compiled with the HP ANSI C++ compiler (`aCC').) 695 696`set overload-resolution on' 697 Enable overload resolution for C++ expression evaluation. The 698 default is on. For overloaded functions, GDB evaluates the 699 arguments and searches for a function whose signature matches the 700 argument types, using the standard C++ conversion rules (see *Note 701 C++ Expressions: C Plus Plus Expressions, for details). If it 702 cannot find a match, it emits a message. 703 704`set overload-resolution off' 705 Disable overload resolution for C++ expression evaluation. For 706 overloaded functions that are not class member functions, GDB 707 chooses the first function of the specified name that it finds in 708 the symbol table, whether or not its arguments are of the correct 709 type. For overloaded functions that are class member functions, 710 GDB searches for a function whose signature _exactly_ matches the 711 argument types. 712 713`show overload-resolution' 714 Show the current setting of overload resolution. 715 716`Overloaded symbol names' 717 You can specify a particular definition of an overloaded symbol, 718 using the same notation that is used to declare such symbols in 719 C++: type `SYMBOL(TYPES)' rather than just SYMBOL. You can also 720 use the GDB command-line word completion facilities to list the 721 available choices, or to finish the type list for you. *Note 722 Command Completion: Completion, for details on how to do this. 723 724 725File: gdb.info, Node: Objective-C, Next: Fortran, Prev: C, Up: Supported Languages 726 72712.4.2 Objective-C 728------------------ 729 730This section provides information about some commands and command 731options that are useful for debugging Objective-C code. See also *Note 732info classes: Symbols, and *Note info selectors: Symbols, for a few 733more commands specific to Objective-C support. 734 735* Menu: 736 737* Method Names in Commands:: 738* The Print Command with Objective-C:: 739 740 741File: gdb.info, Node: Method Names in Commands, Next: The Print Command with Objective-C, Up: Objective-C 742 74312.4.2.1 Method Names in Commands 744................................. 745 746The following commands have been extended to accept Objective-C method 747names as line specifications: 748 749 * `clear' 750 751 * `break' 752 753 * `info line' 754 755 * `jump' 756 757 * `list' 758 759 A fully qualified Objective-C method name is specified as 760 761 -[CLASS METHODNAME] 762 763 where the minus sign is used to indicate an instance method and a 764plus sign (not shown) is used to indicate a class method. The class 765name CLASS and method name METHODNAME are enclosed in brackets, similar 766to the way messages are specified in Objective-C source code. For 767example, to set a breakpoint at the `create' instance method of class 768`Fruit' in the program currently being debugged, enter: 769 770 break -[Fruit create] 771 772 To list ten program lines around the `initialize' class method, 773enter: 774 775 list +[NSText initialize] 776 777 In the current version of GDB, the plus or minus sign is required. 778In future versions of GDB, the plus or minus sign will be optional, but 779you can use it to narrow the search. It is also possible to specify 780just a method name: 781 782 break create 783 784 You must specify the complete method name, including any colons. If 785your program's source files contain more than one `create' method, 786you'll be presented with a numbered list of classes that implement that 787method. Indicate your choice by number, or type `0' to exit if none 788apply. 789 790 As another example, to clear a breakpoint established at the 791`makeKeyAndOrderFront:' method of the `NSWindow' class, enter: 792 793 clear -[NSWindow makeKeyAndOrderFront:] 794 795 796File: gdb.info, Node: The Print Command with Objective-C, Prev: Method Names in Commands, Up: Objective-C 797 79812.4.2.2 The Print Command With Objective-C 799........................................... 800 801The print command has also been extended to accept methods. For 802example: 803 804 print -[OBJECT hash] 805 806will tell GDB to send the `hash' message to OBJECT and print the 807result. Also, an additional command has been added, `print-object' or 808`po' for short, which is meant to print the description of an object. 809However, this command may only work with certain Objective-C libraries 810that have a particular hook function, `_NSPrintForDebugger', defined. 811 812 813File: gdb.info, Node: Fortran, Next: Pascal, Prev: Objective-C, Up: Supported Languages 814 81512.4.3 Fortran 816-------------- 817 818GDB can be used to debug programs written in Fortran, but it currently 819supports only the features of Fortran 77 language. 820 821 Some Fortran compilers (GNU Fortran 77 and Fortran 95 compilers 822among them) append an underscore to the names of variables and 823functions. When you debug programs compiled by those compilers, you 824will need to refer to variables and functions with a trailing 825underscore. 826 827* Menu: 828 829* Fortran Operators:: Fortran operators and expressions 830* Fortran Defaults:: Default settings for Fortran 831* Special Fortran Commands:: Special GDB commands for Fortran 832 833 834File: gdb.info, Node: Fortran Operators, Next: Fortran Defaults, Up: Fortran 835 83612.4.3.1 Fortran Operators and Expressions 837.......................................... 838 839Operators must be defined on values of specific types. For instance, 840`+' is defined on numbers, but not on characters or other non- 841arithmetic types. Operators are often defined on groups of types. 842 843`**' 844 The exponentiation operator. It raises the first operand to the 845 power of the second one. 846 847`:' 848 The range operator. Normally used in the form of array(low:high) 849 to represent a section of array. 850 851 852File: gdb.info, Node: Fortran Defaults, Next: Special Fortran Commands, Prev: Fortran Operators, Up: Fortran 853 85412.4.3.2 Fortran Defaults 855......................... 856 857Fortran symbols are usually case-insensitive, so GDB by default uses 858case-insensitive matches for Fortran symbols. You can change that with 859the `set case-insensitive' command, see *Note Symbols::, for the 860details. 861 862 863File: gdb.info, Node: Special Fortran Commands, Prev: Fortran Defaults, Up: Fortran 864 86512.4.3.3 Special Fortran Commands 866................................. 867 868GDB has some commands to support Fortran-specific features, such as 869displaying common blocks. 870 871`info common [COMMON-NAME]' 872 This command prints the values contained in the Fortran `COMMON' 873 block whose name is COMMON-NAME. With no argument, the names of 874 all `COMMON' blocks visible at the current program location are 875 printed. 876 877 878File: gdb.info, Node: Pascal, Next: Modula-2, Prev: Fortran, Up: Supported Languages 879 88012.4.4 Pascal 881------------- 882 883Debugging Pascal programs which use sets, subranges, file variables, or 884nested functions does not currently work. GDB does not support 885entering expressions, printing values, or similar features using Pascal 886syntax. 887 888 The Pascal-specific command `set print pascal_static-members' 889controls whether static members of Pascal objects are displayed. *Note 890pascal_static-members: Print Settings. 891 892 893File: gdb.info, Node: Modula-2, Next: Ada, Prev: Pascal, Up: Supported Languages 894 89512.4.5 Modula-2 896--------------- 897 898The extensions made to GDB to support Modula-2 only support output from 899the GNU Modula-2 compiler (which is currently being developed). Other 900Modula-2 compilers are not currently supported, and attempting to debug 901executables produced by them is most likely to give an error as GDB 902reads in the executable's symbol table. 903 904* Menu: 905 906* M2 Operators:: Built-in operators 907* Built-In Func/Proc:: Built-in functions and procedures 908* M2 Constants:: Modula-2 constants 909* M2 Types:: Modula-2 types 910* M2 Defaults:: Default settings for Modula-2 911* Deviations:: Deviations from standard Modula-2 912* M2 Checks:: Modula-2 type and range checks 913* M2 Scope:: The scope operators `::' and `.' 914* GDB/M2:: GDB and Modula-2 915 916 917File: gdb.info, Node: M2 Operators, Next: Built-In Func/Proc, Up: Modula-2 918 91912.4.5.1 Operators 920.................. 921 922Operators must be defined on values of specific types. For instance, 923`+' is defined on numbers, but not on structures. Operators are often 924defined on groups of types. For the purposes of Modula-2, the 925following definitions hold: 926 927 * _Integral types_ consist of `INTEGER', `CARDINAL', and their 928 subranges. 929 930 * _Character types_ consist of `CHAR' and its subranges. 931 932 * _Floating-point types_ consist of `REAL'. 933 934 * _Pointer types_ consist of anything declared as `POINTER TO TYPE'. 935 936 * _Scalar types_ consist of all of the above. 937 938 * _Set types_ consist of `SET' and `BITSET' types. 939 940 * _Boolean types_ consist of `BOOLEAN'. 941 942The following operators are supported, and appear in order of 943increasing precedence: 944 945`,' 946 Function argument or array index separator. 947 948`:=' 949 Assignment. The value of VAR `:=' VALUE is VALUE. 950 951`<, >' 952 Less than, greater than on integral, floating-point, or enumerated 953 types. 954 955`<=, >=' 956 Less than or equal to, greater than or equal to on integral, 957 floating-point and enumerated types, or set inclusion on set 958 types. Same precedence as `<'. 959 960`=, <>, #' 961 Equality and two ways of expressing inequality, valid on scalar 962 types. Same precedence as `<'. In GDB scripts, only `<>' is 963 available for inequality, since `#' conflicts with the script 964 comment character. 965 966`IN' 967 Set membership. Defined on set types and the types of their 968 members. Same precedence as `<'. 969 970`OR' 971 Boolean disjunction. Defined on boolean types. 972 973`AND, &' 974 Boolean conjunction. Defined on boolean types. 975 976`@' 977 The GDB "artificial array" operator (*note Expressions: 978 Expressions.). 979 980`+, -' 981 Addition and subtraction on integral and floating-point types, or 982 union and difference on set types. 983 984`*' 985 Multiplication on integral and floating-point types, or set 986 intersection on set types. 987 988`/' 989 Division on floating-point types, or symmetric set difference on 990 set types. Same precedence as `*'. 991 992`DIV, MOD' 993 Integer division and remainder. Defined on integral types. Same 994 precedence as `*'. 995 996`-' 997 Negative. Defined on `INTEGER' and `REAL' data. 998 999`^' 1000 Pointer dereferencing. Defined on pointer types. 1001 1002`NOT' 1003 Boolean negation. Defined on boolean types. Same precedence as 1004 `^'. 1005 1006`.' 1007 `RECORD' field selector. Defined on `RECORD' data. Same 1008 precedence as `^'. 1009 1010`[]' 1011 Array indexing. Defined on `ARRAY' data. Same precedence as `^'. 1012 1013`()' 1014 Procedure argument list. Defined on `PROCEDURE' objects. Same 1015 precedence as `^'. 1016 1017`::, .' 1018 GDB and Modula-2 scope operators. 1019 1020 _Warning:_ Set expressions and their operations are not yet 1021 supported, so GDB treats the use of the operator `IN', or the use 1022 of operators `+', `-', `*', `/', `=', , `<>', `#', `<=', and `>=' 1023 on sets as an error. 1024 1025 1026File: gdb.info, Node: Built-In Func/Proc, Next: M2 Constants, Prev: M2 Operators, Up: Modula-2 1027 102812.4.5.2 Built-in Functions and Procedures 1029.......................................... 1030 1031Modula-2 also makes available several built-in procedures and functions. 1032In describing these, the following metavariables are used: 1033 1034A 1035 represents an `ARRAY' variable. 1036 1037C 1038 represents a `CHAR' constant or variable. 1039 1040I 1041 represents a variable or constant of integral type. 1042 1043M 1044 represents an identifier that belongs to a set. Generally used in 1045 the same function with the metavariable S. The type of S should 1046 be `SET OF MTYPE' (where MTYPE is the type of M). 1047 1048N 1049 represents a variable or constant of integral or floating-point 1050 type. 1051 1052R 1053 represents a variable or constant of floating-point type. 1054 1055T 1056 represents a type. 1057 1058V 1059 represents a variable. 1060 1061X 1062 represents a variable or constant of one of many types. See the 1063 explanation of the function for details. 1064 1065 All Modula-2 built-in procedures also return a result, described 1066below. 1067 1068`ABS(N)' 1069 Returns the absolute value of N. 1070 1071`CAP(C)' 1072 If C is a lower case letter, it returns its upper case equivalent, 1073 otherwise it returns its argument. 1074 1075`CHR(I)' 1076 Returns the character whose ordinal value is I. 1077 1078`DEC(V)' 1079 Decrements the value in the variable V by one. Returns the new 1080 value. 1081 1082`DEC(V,I)' 1083 Decrements the value in the variable V by I. Returns the new 1084 value. 1085 1086`EXCL(M,S)' 1087 Removes the element M from the set S. Returns the new set. 1088 1089`FLOAT(I)' 1090 Returns the floating point equivalent of the integer I. 1091 1092`HIGH(A)' 1093 Returns the index of the last member of A. 1094 1095`INC(V)' 1096 Increments the value in the variable V by one. Returns the new 1097 value. 1098 1099`INC(V,I)' 1100 Increments the value in the variable V by I. Returns the new 1101 value. 1102 1103`INCL(M,S)' 1104 Adds the element M to the set S if it is not already there. 1105 Returns the new set. 1106 1107`MAX(T)' 1108 Returns the maximum value of the type T. 1109 1110`MIN(T)' 1111 Returns the minimum value of the type T. 1112 1113`ODD(I)' 1114 Returns boolean TRUE if I is an odd number. 1115 1116`ORD(X)' 1117 Returns the ordinal value of its argument. For example, the 1118 ordinal value of a character is its ASCII value (on machines 1119 supporting the ASCII character set). X must be of an ordered 1120 type, which include integral, character and enumerated types. 1121 1122`SIZE(X)' 1123 Returns the size of its argument. X can be a variable or a type. 1124 1125`TRUNC(R)' 1126 Returns the integral part of R. 1127 1128`VAL(T,I)' 1129 Returns the member of the type T whose ordinal value is I. 1130 1131 _Warning:_ Sets and their operations are not yet supported, so 1132 GDB treats the use of procedures `INCL' and `EXCL' as an error. 1133 1134 1135File: gdb.info, Node: M2 Constants, Next: M2 Types, Prev: Built-In Func/Proc, Up: Modula-2 1136 113712.4.5.3 Constants 1138.................. 1139 1140GDB allows you to express the constants of Modula-2 in the following 1141ways: 1142 1143 * Integer constants are simply a sequence of digits. When used in an 1144 expression, a constant is interpreted to be type-compatible with 1145 the rest of the expression. Hexadecimal integers are specified by 1146 a trailing `H', and octal integers by a trailing `B'. 1147 1148 * Floating point constants appear as a sequence of digits, followed 1149 by a decimal point and another sequence of digits. An optional 1150 exponent can then be specified, in the form `E[+|-]NNN', where 1151 `[+|-]NNN' is the desired exponent. All of the digits of the 1152 floating point constant must be valid decimal (base 10) digits. 1153 1154 * Character constants consist of a single character enclosed by a 1155 pair of like quotes, either single (`'') or double (`"'). They may 1156 also be expressed by their ordinal value (their ASCII value, 1157 usually) followed by a `C'. 1158 1159 * String constants consist of a sequence of characters enclosed by a 1160 pair of like quotes, either single (`'') or double (`"'). Escape 1161 sequences in the style of C are also allowed. *Note C and C++ 1162 Constants: C Constants, for a brief explanation of escape 1163 sequences. 1164 1165 * Enumerated constants consist of an enumerated identifier. 1166 1167 * Boolean constants consist of the identifiers `TRUE' and `FALSE'. 1168 1169 * Pointer constants consist of integral values only. 1170 1171 * Set constants are not yet supported. 1172 1173 1174File: gdb.info, Node: M2 Types, Next: M2 Defaults, Prev: M2 Constants, Up: Modula-2 1175 117612.4.5.4 Modula-2 Types 1177....................... 1178 1179Currently GDB can print the following data types in Modula-2 syntax: 1180array types, record types, set types, pointer types, procedure types, 1181enumerated types, subrange types and base types. You can also print 1182the contents of variables declared using these type. This section 1183gives a number of simple source code examples together with sample GDB 1184sessions. 1185 1186 The first example contains the following section of code: 1187 1188 VAR 1189 s: SET OF CHAR ; 1190 r: [20..40] ; 1191 1192and you can request GDB to interrogate the type and value of `r' and 1193`s'. 1194 1195 (gdb) print s 1196 {'A'..'C', 'Z'} 1197 (gdb) ptype s 1198 SET OF CHAR 1199 (gdb) print r 1200 21 1201 (gdb) ptype r 1202 [20..40] 1203 1204Likewise if your source code declares `s' as: 1205 1206 VAR 1207 s: SET ['A'..'Z'] ; 1208 1209then you may query the type of `s' by: 1210 1211 (gdb) ptype s 1212 type = SET ['A'..'Z'] 1213 1214Note that at present you cannot interactively manipulate set 1215expressions using the debugger. 1216 1217 The following example shows how you might declare an array in 1218Modula-2 and how you can interact with GDB to print its type and 1219contents: 1220 1221 VAR 1222 s: ARRAY [-10..10] OF CHAR ; 1223 1224 (gdb) ptype s 1225 ARRAY [-10..10] OF CHAR 1226 1227 Note that the array handling is not yet complete and although the 1228type is printed correctly, expression handling still assumes that all 1229arrays have a lower bound of zero and not `-10' as in the example 1230above. Unbounded arrays are also not yet recognized in GDB. 1231 1232 Here are some more type related Modula-2 examples: 1233 1234 TYPE 1235 colour = (blue, red, yellow, green) ; 1236 t = [blue..yellow] ; 1237 VAR 1238 s: t ; 1239 BEGIN 1240 s := blue ; 1241 1242The GDB interaction shows how you can query the data type and value of 1243a variable. 1244 1245 (gdb) print s 1246 $1 = blue 1247 (gdb) ptype t 1248 type = [blue..yellow] 1249 1250In this example a Modula-2 array is declared and its contents 1251displayed. Observe that the contents are written in the same way as 1252their `C' counterparts. 1253 1254 VAR 1255 s: ARRAY [1..5] OF CARDINAL ; 1256 BEGIN 1257 s[1] := 1 ; 1258 1259 (gdb) print s 1260 $1 = {1, 0, 0, 0, 0} 1261 (gdb) ptype s 1262 type = ARRAY [1..5] OF CARDINAL 1263 1264 The Modula-2 language interface to GDB also understands pointer 1265types as shown in this example: 1266 1267 VAR 1268 s: POINTER TO ARRAY [1..5] OF CARDINAL ; 1269 BEGIN 1270 NEW(s) ; 1271 s^[1] := 1 ; 1272 1273and you can request that GDB describes the type of `s'. 1274 1275 (gdb) ptype s 1276 type = POINTER TO ARRAY [1..5] OF CARDINAL 1277 1278 GDB handles compound types as we can see in this example. Here we 1279combine array types, record types, pointer types and subrange types: 1280 1281 TYPE 1282 foo = RECORD 1283 f1: CARDINAL ; 1284 f2: CHAR ; 1285 f3: myarray ; 1286 END ; 1287 1288 myarray = ARRAY myrange OF CARDINAL ; 1289 myrange = [-2..2] ; 1290 VAR 1291 s: POINTER TO ARRAY myrange OF foo ; 1292 1293and you can ask GDB to describe the type of `s' as shown below. 1294 1295 (gdb) ptype s 1296 type = POINTER TO ARRAY [-2..2] OF foo = RECORD 1297 f1 : CARDINAL; 1298 f2 : CHAR; 1299 f3 : ARRAY [-2..2] OF CARDINAL; 1300 END 1301 1302 1303File: gdb.info, Node: M2 Defaults, Next: Deviations, Prev: M2 Types, Up: Modula-2 1304 130512.4.5.5 Modula-2 Defaults 1306.......................... 1307 1308If type and range checking are set automatically by GDB, they both 1309default to `on' whenever the working language changes to Modula-2. 1310This happens regardless of whether you or GDB selected the working 1311language. 1312 1313 If you allow GDB to set the language automatically, then entering 1314code compiled from a file whose name ends with `.mod' sets the working 1315language to Modula-2. *Note Having GDB Infer the Source Language: 1316Automatically, for further details. 1317 1318 1319File: gdb.info, Node: Deviations, Next: M2 Checks, Prev: M2 Defaults, Up: Modula-2 1320 132112.4.5.6 Deviations from Standard Modula-2 1322.......................................... 1323 1324A few changes have been made to make Modula-2 programs easier to debug. 1325This is done primarily via loosening its type strictness: 1326 1327 * Unlike in standard Modula-2, pointer constants can be formed by 1328 integers. This allows you to modify pointer variables during 1329 debugging. (In standard Modula-2, the actual address contained in 1330 a pointer variable is hidden from you; it can only be modified 1331 through direct assignment to another pointer variable or 1332 expression that returned a pointer.) 1333 1334 * C escape sequences can be used in strings and characters to 1335 represent non-printable characters. GDB prints out strings with 1336 these escape sequences embedded. Single non-printable characters 1337 are printed using the `CHR(NNN)' format. 1338 1339 * The assignment operator (`:=') returns the value of its right-hand 1340 argument. 1341 1342 * All built-in procedures both modify _and_ return their argument. 1343 1344 1345File: gdb.info, Node: M2 Checks, Next: M2 Scope, Prev: Deviations, Up: Modula-2 1346 134712.4.5.7 Modula-2 Type and Range Checks 1348....................................... 1349 1350 _Warning:_ in this release, GDB does not yet perform type or range 1351 checking. 1352 1353 GDB considers two Modula-2 variables type equivalent if: 1354 1355 * They are of types that have been declared equivalent via a `TYPE 1356 T1 = T2' statement 1357 1358 * They have been declared on the same line. (Note: This is true of 1359 the GNU Modula-2 compiler, but it may not be true of other 1360 compilers.) 1361 1362 As long as type checking is enabled, any attempt to combine variables 1363whose types are not equivalent is an error. 1364 1365 Range checking is done on all mathematical operations, assignment, 1366array index bounds, and all built-in functions and procedures. 1367 1368 1369File: gdb.info, Node: M2 Scope, Next: GDB/M2, Prev: M2 Checks, Up: Modula-2 1370 137112.4.5.8 The Scope Operators `::' and `.' 1372......................................... 1373 1374There are a few subtle differences between the Modula-2 scope operator 1375(`.') and the GDB scope operator (`::'). The two have similar syntax: 1376 1377 1378 MODULE . ID 1379 SCOPE :: ID 1380 1381where SCOPE is the name of a module or a procedure, MODULE the name of 1382a module, and ID is any declared identifier within your program, except 1383another module. 1384 1385 Using the `::' operator makes GDB search the scope specified by 1386SCOPE for the identifier ID. If it is not found in the specified 1387scope, then GDB searches all scopes enclosing the one specified by 1388SCOPE. 1389 1390 Using the `.' operator makes GDB search the current scope for the 1391identifier specified by ID that was imported from the definition module 1392specified by MODULE. With this operator, it is an error if the 1393identifier ID was not imported from definition module MODULE, or if ID 1394is not an identifier in MODULE. 1395 1396 1397File: gdb.info, Node: GDB/M2, Prev: M2 Scope, Up: Modula-2 1398 139912.4.5.9 GDB and Modula-2 1400......................... 1401 1402Some GDB commands have little use when debugging Modula-2 programs. 1403Five subcommands of `set print' and `show print' apply specifically to 1404C and C++: `vtbl', `demangle', `asm-demangle', `object', and `union'. 1405The first four apply to C++, and the last to the C `union' type, which 1406has no direct analogue in Modula-2. 1407 1408 The `@' operator (*note Expressions: Expressions.), while available 1409with any language, is not useful with Modula-2. Its intent is to aid 1410the debugging of "dynamic arrays", which cannot be created in Modula-2 1411as they can in C or C++. However, because an address can be specified 1412by an integral constant, the construct `{TYPE}ADREXP' is still useful. 1413 1414 In GDB scripts, the Modula-2 inequality operator `#' is interpreted 1415as the beginning of a comment. Use `<>' instead. 1416 1417 1418File: gdb.info, Node: Ada, Prev: Modula-2, Up: Supported Languages 1419 142012.4.6 Ada 1421---------- 1422 1423The extensions made to GDB for Ada only support output from the GNU Ada 1424(GNAT) compiler. Other Ada compilers are not currently supported, and 1425attempting to debug executables produced by them is most likely to be 1426difficult. 1427 1428* Menu: 1429 1430* Ada Mode Intro:: General remarks on the Ada syntax 1431 and semantics supported by Ada mode 1432 in GDB. 1433* Omissions from Ada:: Restrictions on the Ada expression syntax. 1434* Additions to Ada:: Extensions of the Ada expression syntax. 1435* Stopping Before Main Program:: Debugging the program during elaboration. 1436* Ada Glitches:: Known peculiarities of Ada mode. 1437 1438 1439File: gdb.info, Node: Ada Mode Intro, Next: Omissions from Ada, Up: Ada 1440 144112.4.6.1 Introduction 1442..................... 1443 1444The Ada mode of GDB supports a fairly large subset of Ada expression 1445syntax, with some extensions. The philosophy behind the design of this 1446subset is 1447 1448 * That GDB should provide basic literals and access to operations for 1449 arithmetic, dereferencing, field selection, indexing, and 1450 subprogram calls, leaving more sophisticated computations to 1451 subprograms written into the program (which therefore may be 1452 called from GDB). 1453 1454 * That type safety and strict adherence to Ada language restrictions 1455 are not particularly important to the GDB user. 1456 1457 * That brevity is important to the GDB user. 1458 1459 Thus, for brevity, the debugger acts as if there were implicit 1460`with' and `use' clauses in effect for all user-written packages, 1461making it unnecessary to fully qualify most names with their packages, 1462regardless of context. Where this causes ambiguity, GDB asks the 1463user's intent. 1464 1465 The debugger will start in Ada mode if it detects an Ada main 1466program. As for other languages, it will enter Ada mode when stopped 1467in a program that was translated from an Ada source file. 1468 1469 While in Ada mode, you may use `-' for comments. This is useful 1470mostly for documenting command files. The standard GDB comment (`#') 1471still works at the beginning of a line in Ada mode, but not in the 1472middle (to allow based literals). 1473 1474 The debugger supports limited overloading. Given a subprogram call 1475in which the function symbol has multiple definitions, it will use the 1476number of actual parameters and some information about their types to 1477attempt to narrow the set of definitions. It also makes very limited 1478use of context, preferring procedures to functions in the context of 1479the `call' command, and functions to procedures elsewhere. 1480 1481 1482File: gdb.info, Node: Omissions from Ada, Next: Additions to Ada, Prev: Ada Mode Intro, Up: Ada 1483 148412.4.6.2 Omissions from Ada 1485........................... 1486 1487Here are the notable omissions from the subset: 1488 1489 * Only a subset of the attributes are supported: 1490 1491 - 'First, 'Last, and 'Length on array objects (not on types 1492 and subtypes). 1493 1494 - 'Min and 'Max. 1495 1496 - 'Pos and 'Val. 1497 1498 - 'Tag. 1499 1500 - 'Range on array objects (not subtypes), but only as the right 1501 operand of the membership (`in') operator. 1502 1503 - 'Access, 'Unchecked_Access, and 'Unrestricted_Access (a GNAT 1504 extension). 1505 1506 - 'Address. 1507 1508 * The names in `Characters.Latin_1' are not available and 1509 concatenation is not implemented. Thus, escape characters in 1510 strings are not currently available. 1511 1512 * Equality tests (`=' and `/=') on arrays test for bitwise equality 1513 of representations. They will generally work correctly for 1514 strings and arrays whose elements have integer or enumeration 1515 types. They may not work correctly for arrays whose element types 1516 have user-defined equality, for arrays of real values (in 1517 particular, IEEE-conformant floating point, because of negative 1518 zeroes and NaNs), and for arrays whose elements contain unused 1519 bits with indeterminate values. 1520 1521 * The other component-by-component array operations (`and', `or', 1522 `xor', `not', and relational tests other than equality) are not 1523 implemented. 1524 1525 * There is limited support for array and record aggregates. They are 1526 permitted only on the right sides of assignments, as in these 1527 examples: 1528 1529 set An_Array := (1, 2, 3, 4, 5, 6) 1530 set An_Array := (1, others => 0) 1531 set An_Array := (0|4 => 1, 1..3 => 2, 5 => 6) 1532 set A_2D_Array := ((1, 2, 3), (4, 5, 6), (7, 8, 9)) 1533 set A_Record := (1, "Peter", True); 1534 set A_Record := (Name => "Peter", Id => 1, Alive => True) 1535 1536 Changing a discriminant's value by assigning an aggregate has an 1537 undefined effect if that discriminant is used within the record. 1538 However, you can first modify discriminants by directly assigning 1539 to them (which normally would not be allowed in Ada), and then 1540 performing an aggregate assignment. For example, given a variable 1541 `A_Rec' declared to have a type such as: 1542 1543 type Rec (Len : Small_Integer := 0) is record 1544 Id : Integer; 1545 Vals : IntArray (1 .. Len); 1546 end record; 1547 1548 you can assign a value with a different size of `Vals' with two 1549 assignments: 1550 1551 set A_Rec.Len := 4 1552 set A_Rec := (Id => 42, Vals => (1, 2, 3, 4)) 1553 1554 As this example also illustrates, GDB is very loose about the usual 1555 rules concerning aggregates. You may leave out some of the 1556 components of an array or record aggregate (such as the `Len' 1557 component in the assignment to `A_Rec' above); they will retain 1558 their original values upon assignment. You may freely use dynamic 1559 values as indices in component associations. You may even use 1560 overlapping or redundant component associations, although which 1561 component values are assigned in such cases is not defined. 1562 1563 * Calls to dispatching subprograms are not implemented. 1564 1565 * The overloading algorithm is much more limited (i.e., less 1566 selective) than that of real Ada. It makes only limited use of 1567 the context in which a subexpression appears to resolve its 1568 meaning, and it is much looser in its rules for allowing type 1569 matches. As a result, some function calls will be ambiguous, and 1570 the user will be asked to choose the proper resolution. 1571 1572 * The `new' operator is not implemented. 1573 1574 * Entry calls are not implemented. 1575 1576 * Aside from printing, arithmetic operations on the native VAX 1577 floating-point formats are not supported. 1578 1579 * It is not possible to slice a packed array. 1580 1581 1582File: gdb.info, Node: Additions to Ada, Next: Stopping Before Main Program, Prev: Omissions from Ada, Up: Ada 1583 158412.4.6.3 Additions to Ada 1585......................... 1586 1587As it does for other languages, GDB makes certain generic extensions to 1588Ada (*note Expressions::): 1589 1590 * If the expression E is a variable residing in memory (typically a 1591 local variable or array element) and N is a positive integer, then 1592 `E@N' displays the values of E and the N-1 adjacent variables 1593 following it in memory as an array. In Ada, this operator is 1594 generally not necessary, since its prime use is in displaying 1595 parts of an array, and slicing will usually do this in Ada. 1596 However, there are occasional uses when debugging programs in 1597 which certain debugging information has been optimized away. 1598 1599 * `B::VAR' means "the variable named VAR that appears in function or 1600 file B." When B is a file name, you must typically surround it in 1601 single quotes. 1602 1603 * The expression `{TYPE} ADDR' means "the variable of type TYPE that 1604 appears at address ADDR." 1605 1606 * A name starting with `$' is a convenience variable (*note 1607 Convenience Vars::) or a machine register (*note Registers::). 1608 1609 In addition, GDB provides a few other shortcuts and outright 1610additions specific to Ada: 1611 1612 * The assignment statement is allowed as an expression, returning 1613 its right-hand operand as its value. Thus, you may enter 1614 1615 set x := y + 3 1616 print A(tmp := y + 1) 1617 1618 * The semicolon is allowed as an "operator," returning as its value 1619 the value of its right-hand operand. This allows, for example, 1620 complex conditional breaks: 1621 1622 break f 1623 condition 1 (report(i); k += 1; A(k) > 100) 1624 1625 * Rather than use catenation and symbolic character names to 1626 introduce special characters into strings, one may instead use a 1627 special bracket notation, which is also used to print strings. A 1628 sequence of characters of the form `["XX"]' within a string or 1629 character literal denotes the (single) character whose numeric 1630 encoding is XX in hexadecimal. The sequence of characters `["""]' 1631 also denotes a single quotation mark in strings. For example, 1632 "One line.["0a"]Next line.["0a"]" 1633 contains an ASCII newline character (`Ada.Characters.Latin_1.LF') 1634 after each period. 1635 1636 * The subtype used as a prefix for the attributes 'Pos, 'Min, and 1637 'Max is optional (and is ignored in any case). For example, it is 1638 valid to write 1639 1640 print 'max(x, y) 1641 1642 * When printing arrays, GDB uses positional notation when the array 1643 has a lower bound of 1, and uses a modified named notation 1644 otherwise. For example, a one-dimensional array of three integers 1645 with a lower bound of 3 might print as 1646 1647 (3 => 10, 17, 1) 1648 1649 That is, in contrast to valid Ada, only the first component has a 1650 `=>' clause. 1651 1652 * You may abbreviate attributes in expressions with any unique, 1653 multi-character subsequence of their names (an exact match gets 1654 preference). For example, you may use a'len, a'gth, or a'lh in 1655 place of a'length. 1656 1657 * Since Ada is case-insensitive, the debugger normally maps 1658 identifiers you type to lower case. The GNAT compiler uses 1659 upper-case characters for some of its internal identifiers, which 1660 are normally of no interest to users. For the rare occasions when 1661 you actually have to look at them, enclose them in angle brackets 1662 to avoid the lower-case mapping. For example, 1663 gdb print <JMPBUF_SAVE>[0] 1664 1665 * Printing an object of class-wide type or dereferencing an 1666 access-to-class-wide value will display all the components of the 1667 object's specific type (as indicated by its run-time tag). 1668 Likewise, component selection on such a value will operate on the 1669 specific type of the object. 1670 1671 1672 1673File: gdb.info, Node: Stopping Before Main Program, Next: Ada Glitches, Prev: Additions to Ada, Up: Ada 1674 167512.4.6.4 Stopping at the Very Beginning 1676....................................... 1677 1678It is sometimes necessary to debug the program during elaboration, and 1679before reaching the main procedure. As defined in the Ada Reference 1680Manual, the elaboration code is invoked from a procedure called 1681`adainit'. To run your program up to the beginning of elaboration, 1682simply use the following two commands: `tbreak adainit' and `run'. 1683 1684 1685File: gdb.info, Node: Ada Glitches, Prev: Stopping Before Main Program, Up: Ada 1686 168712.4.6.5 Known Peculiarities of Ada Mode 1688........................................ 1689 1690Besides the omissions listed previously (*note Omissions from Ada::), 1691we know of several problems with and limitations of Ada mode in GDB, 1692some of which will be fixed with planned future releases of the debugger 1693and the GNU Ada compiler. 1694 1695 * Currently, the debugger has insufficient information to determine 1696 whether certain pointers represent pointers to objects or the 1697 objects themselves. Thus, the user may have to tack an extra 1698 `.all' after an expression to get it printed properly. 1699 1700 * Static constants that the compiler chooses not to materialize as 1701 objects in storage are invisible to the debugger. 1702 1703 * Named parameter associations in function argument lists are 1704 ignored (the argument lists are treated as positional). 1705 1706 * Many useful library packages are currently invisible to the 1707 debugger. 1708 1709 * Fixed-point arithmetic, conversions, input, and output is carried 1710 out using floating-point arithmetic, and may give results that 1711 only approximate those on the host machine. 1712 1713 * The type of the 'Address attribute may not be `System.Address'. 1714 1715 * The GNAT compiler never generates the prefix `Standard' for any of 1716 the standard symbols defined by the Ada language. GDB knows about 1717 this: it will strip the prefix from names when you use it, and 1718 will never look for a name you have so qualified among local 1719 symbols, nor match against symbols in other packages or 1720 subprograms. If you have defined entities anywhere in your 1721 program other than parameters and local variables whose simple 1722 names match names in `Standard', GNAT's lack of qualification here 1723 can cause confusion. When this happens, you can usually resolve 1724 the confusion by qualifying the problematic names with package 1725 `Standard' explicitly. 1726 1727 1728File: gdb.info, Node: Unsupported Languages, Prev: Supported Languages, Up: Languages 1729 173012.5 Unsupported Languages 1731========================== 1732 1733In addition to the other fully-supported programming languages, GDB 1734also provides a pseudo-language, called `minimal'. It does not 1735represent a real programming language, but provides a set of 1736capabilities close to what the C or assembly languages provide. This 1737should allow most simple operations to be performed while debugging an 1738application that uses a language currently not supported by GDB. 1739 1740 If the language is set to `auto', GDB will automatically select this 1741language if the current frame corresponds to an unsupported language. 1742 1743 1744File: gdb.info, Node: Symbols, Next: Altering, Prev: Languages, Up: Top 1745 174613 Examining the Symbol Table 1747***************************** 1748 1749The commands described in this chapter allow you to inquire about the 1750symbols (names of variables, functions and types) defined in your 1751program. This information is inherent in the text of your program and 1752does not change as your program executes. GDB finds it in your 1753program's symbol table, in the file indicated when you started GDB 1754(*note Choosing Files: File Options.), or by one of the file-management 1755commands (*note Commands to Specify Files: Files.). 1756 1757 Occasionally, you may need to refer to symbols that contain unusual 1758characters, which GDB ordinarily treats as word delimiters. The most 1759frequent case is in referring to static variables in other source files 1760(*note Program Variables: Variables.). File names are recorded in 1761object files as debugging symbols, but GDB would ordinarily parse a 1762typical file name, like `foo.c', as the three words `foo' `.' `c'. To 1763allow GDB to recognize `foo.c' as a single symbol, enclose it in single 1764quotes; for example, 1765 1766 p 'foo.c'::x 1767 1768looks up the value of `x' in the scope of the file `foo.c'. 1769 1770`set case-sensitive on' 1771`set case-sensitive off' 1772`set case-sensitive auto' 1773 Normally, when GDB looks up symbols, it matches their names with 1774 case sensitivity determined by the current source language. 1775 Occasionally, you may wish to control that. The command `set 1776 case-sensitive' lets you do that by specifying `on' for 1777 case-sensitive matches or `off' for case-insensitive ones. If you 1778 specify `auto', case sensitivity is reset to the default suitable 1779 for the source language. The default is case-sensitive matches 1780 for all languages except for Fortran, for which the default is 1781 case-insensitive matches. 1782 1783`show case-sensitive' 1784 This command shows the current setting of case sensitivity for 1785 symbols lookups. 1786 1787`info address SYMBOL' 1788 Describe where the data for SYMBOL is stored. For a register 1789 variable, this says which register it is kept in. For a 1790 non-register local variable, this prints the stack-frame offset at 1791 which the variable is always stored. 1792 1793 Note the contrast with `print &SYMBOL', which does not work at all 1794 for a register variable, and for a stack local variable prints the 1795 exact address of the current instantiation of the variable. 1796 1797`info symbol ADDR' 1798 Print the name of a symbol which is stored at the address ADDR. 1799 If no symbol is stored exactly at ADDR, GDB prints the nearest 1800 symbol and an offset from it: 1801 1802 (gdb) info symbol 0x54320 1803 _initialize_vx + 396 in section .text 1804 1805 This is the opposite of the `info address' command. You can use 1806 it to find out the name of a variable or a function given its 1807 address. 1808 1809`whatis [ARG]' 1810 Print the data type of ARG, which can be either an expression or a 1811 data type. With no argument, print the data type of `$', the last 1812 value in the value history. If ARG is an expression, it is not 1813 actually evaluated, and any side-effecting operations (such as 1814 assignments or function calls) inside it do not take place. If 1815 ARG is a type name, it may be the name of a type or typedef, or 1816 for C code it may have the form `class CLASS-NAME', `struct 1817 STRUCT-TAG', `union UNION-TAG' or `enum ENUM-TAG'. *Note 1818 Expressions: Expressions. 1819 1820`ptype [ARG]' 1821 `ptype' accepts the same arguments as `whatis', but prints a 1822 detailed description of the type, instead of just the name of the 1823 type. *Note Expressions: Expressions. 1824 1825 For example, for this variable declaration: 1826 1827 struct complex {double real; double imag;} v; 1828 1829 the two commands give this output: 1830 1831 (gdb) whatis v 1832 type = struct complex 1833 (gdb) ptype v 1834 type = struct complex { 1835 double real; 1836 double imag; 1837 } 1838 1839 As with `whatis', using `ptype' without an argument refers to the 1840 type of `$', the last value in the value history. 1841 1842 Sometimes, programs use opaque data types or incomplete 1843 specifications of complex data structure. If the debug 1844 information included in the program does not allow GDB to display 1845 a full declaration of the data type, it will say `<incomplete 1846 type>'. For example, given these declarations: 1847 1848 struct foo; 1849 struct foo *fooptr; 1850 1851 but no definition for `struct foo' itself, GDB will say: 1852 1853 (gdb) ptype foo 1854 $1 = <incomplete type> 1855 1856 "Incomplete type" is C terminology for data types that are not 1857 completely specified. 1858 1859`info types REGEXP' 1860`info types' 1861 Print a brief description of all types whose names match the 1862 regular expression REGEXP (or all types in your program, if you 1863 supply no argument). Each complete typename is matched as though 1864 it were a complete line; thus, `i type value' gives information on 1865 all types in your program whose names include the string `value', 1866 but `i type ^value$' gives information only on types whose complete 1867 name is `value'. 1868 1869 This command differs from `ptype' in two ways: first, like 1870 `whatis', it does not print a detailed description; second, it 1871 lists all source files where a type is defined. 1872 1873`info scope LOCATION' 1874 List all the variables local to a particular scope. This command 1875 accepts a LOCATION argument--a function name, a source line, or an 1876 address preceded by a `*', and prints all the variables local to 1877 the scope defined by that location. For example: 1878 1879 (gdb) info scope command_line_handler 1880 Scope for command_line_handler: 1881 Symbol rl is an argument at stack/frame offset 8, length 4. 1882 Symbol linebuffer is in static storage at address 0x150a18, length 4. 1883 Symbol linelength is in static storage at address 0x150a1c, length 4. 1884 Symbol p is a local variable in register $esi, length 4. 1885 Symbol p1 is a local variable in register $ebx, length 4. 1886 Symbol nline is a local variable in register $edx, length 4. 1887 Symbol repeat is a local variable at frame offset -8, length 4. 1888 1889 This command is especially useful for determining what data to 1890 collect during a "trace experiment", see *Note collect: Tracepoint 1891 Actions. 1892 1893`info source' 1894 Show information about the current source file--that is, the 1895 source file for the function containing the current point of 1896 execution: 1897 * the name of the source file, and the directory containing it, 1898 1899 * the directory it was compiled in, 1900 1901 * its length, in lines, 1902 1903 * which programming language it is written in, 1904 1905 * whether the executable includes debugging information for 1906 that file, and if so, what format the information is in 1907 (e.g., STABS, Dwarf 2, etc.), and 1908 1909 * whether the debugging information includes information about 1910 preprocessor macros. 1911 1912`info sources' 1913 Print the names of all source files in your program for which 1914 there is debugging information, organized into two lists: files 1915 whose symbols have already been read, and files whose symbols will 1916 be read when needed. 1917 1918`info functions' 1919 Print the names and data types of all defined functions. 1920 1921`info functions REGEXP' 1922 Print the names and data types of all defined functions whose 1923 names contain a match for regular expression REGEXP. Thus, `info 1924 fun step' finds all functions whose names include `step'; `info 1925 fun ^step' finds those whose names start with `step'. If a 1926 function name contains characters that conflict with the regular 1927 expression language (e.g. `operator*()'), they may be quoted with 1928 a backslash. 1929 1930`info variables' 1931 Print the names and data types of all variables that are declared 1932 outside of functions (i.e. excluding local variables). 1933 1934`info variables REGEXP' 1935 Print the names and data types of all variables (except for local 1936 variables) whose names contain a match for regular expression 1937 REGEXP. 1938 1939`info classes' 1940`info classes REGEXP' 1941 Display all Objective-C classes in your program, or (with the 1942 REGEXP argument) all those matching a particular regular 1943 expression. 1944 1945`info selectors' 1946`info selectors REGEXP' 1947 Display all Objective-C selectors in your program, or (with the 1948 REGEXP argument) all those matching a particular regular 1949 expression. 1950 1951 Some systems allow individual object files that make up your 1952 program to be replaced without stopping and restarting your 1953 program. For example, in VxWorks you can simply recompile a 1954 defective object file and keep on running. If you are running on 1955 one of these systems, you can allow GDB to reload the symbols for 1956 automatically relinked modules: 1957 1958 `set symbol-reloading on' 1959 Replace symbol definitions for the corresponding source file 1960 when an object file with a particular name is seen again. 1961 1962 `set symbol-reloading off' 1963 Do not replace symbol definitions when encountering object 1964 files of the same name more than once. This is the default 1965 state; if you are not running on a system that permits 1966 automatic relinking of modules, you should leave 1967 `symbol-reloading' off, since otherwise GDB may discard 1968 symbols when linking large programs, that may contain several 1969 modules (from different directories or libraries) with the 1970 same name. 1971 1972 `show symbol-reloading' 1973 Show the current `on' or `off' setting. 1974 1975`set opaque-type-resolution on' 1976 Tell GDB to resolve opaque types. An opaque type is a type 1977 declared as a pointer to a `struct', `class', or `union'--for 1978 example, `struct MyType *'--that is used in one source file 1979 although the full declaration of `struct MyType' is in another 1980 source file. The default is on. 1981 1982 A change in the setting of this subcommand will not take effect 1983 until the next time symbols for a file are loaded. 1984 1985`set opaque-type-resolution off' 1986 Tell GDB not to resolve opaque types. In this case, the type is 1987 printed as follows: 1988 {<no data fields>} 1989 1990`show opaque-type-resolution' 1991 Show whether opaque types are resolved or not. 1992 1993`maint print symbols FILENAME' 1994`maint print psymbols FILENAME' 1995`maint print msymbols FILENAME' 1996 Write a dump of debugging symbol data into the file FILENAME. 1997 These commands are used to debug the GDB symbol-reading code. Only 1998 symbols with debugging data are included. If you use `maint print 1999 symbols', GDB includes all the symbols for which it has already 2000 collected full details: that is, FILENAME reflects symbols for 2001 only those files whose symbols GDB has read. You can use the 2002 command `info sources' to find out which files these are. If you 2003 use `maint print psymbols' instead, the dump shows information 2004 about symbols that GDB only knows partially--that is, symbols 2005 defined in files that GDB has skimmed, but not yet read 2006 completely. Finally, `maint print msymbols' dumps just the 2007 minimal symbol information required for each object file from 2008 which GDB has read some symbols. *Note Commands to Specify Files: 2009 Files, for a discussion of how GDB reads symbols (in the 2010 description of `symbol-file'). 2011 2012`maint info symtabs [ REGEXP ]' 2013`maint info psymtabs [ REGEXP ]' 2014 List the `struct symtab' or `struct partial_symtab' structures 2015 whose names match REGEXP. If REGEXP is not given, list them all. 2016 The output includes expressions which you can copy into a GDB 2017 debugging this one to examine a particular structure in more 2018 detail. For example: 2019 2020 (gdb) maint info psymtabs dwarf2read 2021 { objfile /home/gnu/build/gdb/gdb 2022 ((struct objfile *) 0x82e69d0) 2023 { psymtab /home/gnu/src/gdb/dwarf2read.c 2024 ((struct partial_symtab *) 0x8474b10) 2025 readin no 2026 fullname (null) 2027 text addresses 0x814d3c8 -- 0x8158074 2028 globals (* (struct partial_symbol **) 0x8507a08 @ 9) 2029 statics (* (struct partial_symbol **) 0x40e95b78 @ 2882) 2030 dependencies (none) 2031 } 2032 } 2033 (gdb) maint info symtabs 2034 (gdb) 2035 We see that there is one partial symbol table whose filename 2036 contains the string `dwarf2read', belonging to the `gdb' 2037 executable; and we see that GDB has not read in any symtabs yet at 2038 all. If we set a breakpoint on a function, that will cause GDB to 2039 read the symtab for the compilation unit containing that function: 2040 2041 (gdb) break dwarf2_psymtab_to_symtab 2042 Breakpoint 1 at 0x814e5da: file /home/gnu/src/gdb/dwarf2read.c, 2043 line 1574. 2044 (gdb) maint info symtabs 2045 { objfile /home/gnu/build/gdb/gdb 2046 ((struct objfile *) 0x82e69d0) 2047 { symtab /home/gnu/src/gdb/dwarf2read.c 2048 ((struct symtab *) 0x86c1f38) 2049 dirname (null) 2050 fullname (null) 2051 blockvector ((struct blockvector *) 0x86c1bd0) (primary) 2052 debugformat DWARF 2 2053 } 2054 } 2055 (gdb) 2056 2057 2058File: gdb.info, Node: Altering, Next: GDB Files, Prev: Symbols, Up: Top 2059 206014 Altering Execution 2061********************* 2062 2063Once you think you have found an error in your program, you might want 2064to find out for certain whether correcting the apparent error would 2065lead to correct results in the rest of the run. You can find the 2066answer by experiment, using the GDB features for altering execution of 2067the program. 2068 2069 For example, you can store new values into variables or memory 2070locations, give your program a signal, restart it at a different 2071address, or even return prematurely from a function. 2072 2073* Menu: 2074 2075* Assignment:: Assignment to variables 2076* Jumping:: Continuing at a different address 2077* Signaling:: Giving your program a signal 2078* Returning:: Returning from a function 2079* Calling:: Calling your program's functions 2080* Patching:: Patching your program 2081 2082 2083File: gdb.info, Node: Assignment, Next: Jumping, Up: Altering 2084 208514.1 Assignment to Variables 2086============================ 2087 2088To alter the value of a variable, evaluate an assignment expression. 2089*Note Expressions: Expressions. For example, 2090 2091 print x=4 2092 2093stores the value 4 into the variable `x', and then prints the value of 2094the assignment expression (which is 4). *Note Using GDB with Different 2095Languages: Languages, for more information on operators in supported 2096languages. 2097 2098 If you are not interested in seeing the value of the assignment, use 2099the `set' command instead of the `print' command. `set' is really the 2100same as `print' except that the expression's value is not printed and 2101is not put in the value history (*note Value History: Value History.). 2102The expression is evaluated only for its effects. 2103 2104 If the beginning of the argument string of the `set' command appears 2105identical to a `set' subcommand, use the `set variable' command instead 2106of just `set'. This command is identical to `set' except for its lack 2107of subcommands. For example, if your program has a variable `width', 2108you get an error if you try to set a new value with just `set 2109width=13', because GDB has the command `set width': 2110 2111 (gdb) whatis width 2112 type = double 2113 (gdb) p width 2114 $4 = 13 2115 (gdb) set width=47 2116 Invalid syntax in expression. 2117 2118The invalid expression, of course, is `=47'. In order to actually set 2119the program's variable `width', use 2120 2121 (gdb) set var width=47 2122 2123 Because the `set' command has many subcommands that can conflict 2124with the names of program variables, it is a good idea to use the `set 2125variable' command instead of just `set'. For example, if your program 2126has a variable `g', you run into problems if you try to set a new value 2127with just `set g=4', because GDB has the command `set gnutarget', 2128abbreviated `set g': 2129 2130 (gdb) whatis g 2131 type = double 2132 (gdb) p g 2133 $1 = 1 2134 (gdb) set g=4 2135 (gdb) p g 2136 $2 = 1 2137 (gdb) r 2138 The program being debugged has been started already. 2139 Start it from the beginning? (y or n) y 2140 Starting program: /home/smith/cc_progs/a.out 2141 "/home/smith/cc_progs/a.out": can't open to read symbols: 2142 Invalid bfd target. 2143 (gdb) show g 2144 The current BFD target is "=4". 2145 2146The program variable `g' did not change, and you silently set the 2147`gnutarget' to an invalid value. In order to set the variable `g', use 2148 2149 (gdb) set var g=4 2150 2151 GDB allows more implicit conversions in assignments than C; you can 2152freely store an integer value into a pointer variable or vice versa, 2153and you can convert any structure to any other structure that is the 2154same length or shorter. 2155 2156 To store values into arbitrary places in memory, use the `{...}' 2157construct to generate a value of specified type at a specified address 2158(*note Expressions: Expressions.). For example, `{int}0x83040' refers 2159to memory location `0x83040' as an integer (which implies a certain size 2160and representation in memory), and 2161 2162 set {int}0x83040 = 4 2163 2164stores the value 4 into that memory location. 2165 2166 2167File: gdb.info, Node: Jumping, Next: Signaling, Prev: Assignment, Up: Altering 2168 216914.2 Continuing at a Different Address 2170====================================== 2171 2172Ordinarily, when you continue your program, you do so at the place where 2173it stopped, with the `continue' command. You can instead continue at 2174an address of your own choosing, with the following commands: 2175 2176`jump LINESPEC' 2177 Resume execution at line LINESPEC. Execution stops again 2178 immediately if there is a breakpoint there. *Note Printing Source 2179 Lines: List, for a description of the different forms of LINESPEC. 2180 It is common practice to use the `tbreak' command in conjunction 2181 with `jump'. *Note Setting Breakpoints: Set Breaks. 2182 2183 The `jump' command does not change the current stack frame, or the 2184 stack pointer, or the contents of any memory location or any 2185 register other than the program counter. If line LINESPEC is in a 2186 different function from the one currently executing, the results 2187 may be bizarre if the two functions expect different patterns of 2188 arguments or of local variables. For this reason, the `jump' 2189 command requests confirmation if the specified line is not in the 2190 function currently executing. However, even bizarre results are 2191 predictable if you are well acquainted with the machine-language 2192 code of your program. 2193 2194`jump *ADDRESS' 2195 Resume execution at the instruction at address ADDRESS. 2196 2197 On many systems, you can get much the same effect as the `jump' 2198command by storing a new value into the register `$pc'. The difference 2199is that this does not start your program running; it only changes the 2200address of where it _will_ run when you continue. For example, 2201 2202 set $pc = 0x485 2203 2204makes the next `continue' command or stepping command execute at 2205address `0x485', rather than at the address where your program stopped. 2206*Note Continuing and Stepping: Continuing and Stepping. 2207 2208 The most common occasion to use the `jump' command is to back 2209up--perhaps with more breakpoints set--over a portion of a program that 2210has already executed, in order to examine its execution in more detail. 2211 2212 2213File: gdb.info, Node: Signaling, Next: Returning, Prev: Jumping, Up: Altering 2214 221514.3 Giving your Program a Signal 2216================================= 2217 2218`signal SIGNAL' 2219 Resume execution where your program stopped, but immediately give 2220 it the signal SIGNAL. SIGNAL can be the name or the number of a 2221 signal. For example, on many systems `signal 2' and `signal 2222 SIGINT' are both ways of sending an interrupt signal. 2223 2224 Alternatively, if SIGNAL is zero, continue execution without 2225 giving a signal. This is useful when your program stopped on 2226 account of a signal and would ordinary see the signal when resumed 2227 with the `continue' command; `signal 0' causes it to resume 2228 without a signal. 2229 2230 `signal' does not repeat when you press <RET> a second time after 2231 executing the command. 2232 2233 Invoking the `signal' command is not the same as invoking the `kill' 2234utility from the shell. Sending a signal with `kill' causes GDB to 2235decide what to do with the signal depending on the signal handling 2236tables (*note Signals::). The `signal' command passes the signal 2237directly to your program. 2238 2239 2240File: gdb.info, Node: Returning, Next: Calling, Prev: Signaling, Up: Altering 2241 224214.4 Returning from a Function 2243============================== 2244 2245`return' 2246`return EXPRESSION' 2247 You can cancel execution of a function call with the `return' 2248 command. If you give an EXPRESSION argument, its value is used as 2249 the function's return value. 2250 2251 When you use `return', GDB discards the selected stack frame (and 2252all frames within it). You can think of this as making the discarded 2253frame return prematurely. If you wish to specify a value to be 2254returned, give that value as the argument to `return'. 2255 2256 This pops the selected stack frame (*note Selecting a Frame: 2257Selection.), and any other frames inside of it, leaving its caller as 2258the innermost remaining frame. That frame becomes selected. The 2259specified value is stored in the registers used for returning values of 2260functions. 2261 2262 The `return' command does not resume execution; it leaves the 2263program stopped in the state that would exist if the function had just 2264returned. In contrast, the `finish' command (*note Continuing and 2265Stepping: Continuing and Stepping.) resumes execution until the 2266selected stack frame returns naturally. 2267 2268 2269File: gdb.info, Node: Calling, Next: Patching, Prev: Returning, Up: Altering 2270 227114.5 Calling Program Functions 2272============================== 2273 2274`print EXPR' 2275 Evaluate the expression EXPR and display the resulting value. 2276 EXPR may include calls to functions in the program being debugged. 2277 2278`call EXPR' 2279 Evaluate the expression EXPR without displaying `void' returned 2280 values. 2281 2282 You can use this variant of the `print' command if you want to 2283 execute a function from your program that does not return anything 2284 (a.k.a. "a void function"), but without cluttering the output with 2285 `void' returned values that GDB will otherwise print. If the 2286 result is not void, it is printed and saved in the value history. 2287 2288 It is possible for the function you call via the `print' or `call' 2289command to generate a signal (e.g., if there's a bug in the function, 2290or if you passed it incorrect arguments). What happens in that case is 2291controlled by the `set unwindonsignal' command. 2292 2293`set unwindonsignal' 2294 Set unwinding of the stack if a signal is received while in a 2295 function that GDB called in the program being debugged. If set to 2296 on, GDB unwinds the stack it created for the call and restores the 2297 context to what it was before the call. If set to off (the 2298 default), GDB stops in the frame where the signal was received. 2299 2300`show unwindonsignal' 2301 Show the current setting of stack unwinding in the functions 2302 called by GDB. 2303 2304 Sometimes, a function you wish to call is actually a "weak alias" 2305for another function. In such case, GDB might not pick up the type 2306information, including the types of the function arguments, which 2307causes GDB to call the inferior function incorrectly. As a result, the 2308called function will function erroneously and may even crash. A 2309solution to that is to use the name of the aliased function instead. 2310 2311 2312File: gdb.info, Node: Patching, Prev: Calling, Up: Altering 2313 231414.6 Patching Programs 2315====================== 2316 2317By default, GDB opens the file containing your program's executable 2318code (or the corefile) read-only. This prevents accidental alterations 2319to machine code; but it also prevents you from intentionally patching 2320your program's binary. 2321 2322 If you'd like to be able to patch the binary, you can specify that 2323explicitly with the `set write' command. For example, you might want 2324to turn on internal debugging flags, or even to make emergency repairs. 2325 2326`set write on' 2327`set write off' 2328 If you specify `set write on', GDB opens executable and core files 2329 for both reading and writing; if you specify `set write off' (the 2330 default), GDB opens them read-only. 2331 2332 If you have already loaded a file, you must load it again (using 2333 the `exec-file' or `core-file' command) after changing `set 2334 write', for your new setting to take effect. 2335 2336`show write' 2337 Display whether executable files and core files are opened for 2338 writing as well as reading. 2339 2340 2341File: gdb.info, Node: GDB Files, Next: Targets, Prev: Altering, Up: Top 2342 234315 GDB Files 2344************ 2345 2346GDB needs to know the file name of the program to be debugged, both in 2347order to read its symbol table and in order to start your program. To 2348debug a core dump of a previous run, you must also tell GDB the name of 2349the core dump file. 2350 2351* Menu: 2352 2353* Files:: Commands to specify files 2354* Separate Debug Files:: Debugging information in separate files 2355* Symbol Errors:: Errors reading symbol files 2356 2357 2358File: gdb.info, Node: Files, Next: Separate Debug Files, Up: GDB Files 2359 236015.1 Commands to Specify Files 2361============================== 2362 2363You may want to specify executable and core dump file names. The usual 2364way to do this is at start-up time, using the arguments to GDB's 2365start-up commands (*note Getting In and Out of GDB: Invocation.). 2366 2367 Occasionally it is necessary to change to a different file during a 2368GDB session. Or you may run GDB and forget to specify a file you want 2369to use. Or you are debugging a remote target via `gdbserver' (*note 2370file: Server.). In these situations the GDB commands to specify new 2371files are useful. 2372 2373`file FILENAME' 2374 Use FILENAME as the program to be debugged. It is read for its 2375 symbols and for the contents of pure memory. It is also the 2376 program executed when you use the `run' command. If you do not 2377 specify a directory and the file is not found in the GDB working 2378 directory, GDB uses the environment variable `PATH' as a list of 2379 directories to search, just as the shell does when looking for a 2380 program to run. You can change the value of this variable, for 2381 both GDB and your program, using the `path' command. 2382 2383 You can load unlinked object `.o' files into GDB using the `file' 2384 command. You will not be able to "run" an object file, but you 2385 can disassemble functions and inspect variables. Also, if the 2386 underlying BFD functionality supports it, you could use `gdb 2387 -write' to patch object files using this technique. Note that GDB 2388 can neither interpret nor modify relocations in this case, so 2389 branches and some initialized variables will appear to go to the 2390 wrong place. But this feature is still handy from time to time. 2391 2392`file' 2393 `file' with no argument makes GDB discard any information it has 2394 on both executable file and the symbol table. 2395 2396`exec-file [ FILENAME ]' 2397 Specify that the program to be run (but not the symbol table) is 2398 found in FILENAME. GDB searches the environment variable `PATH' 2399 if necessary to locate your program. Omitting FILENAME means to 2400 discard information on the executable file. 2401 2402`symbol-file [ FILENAME ]' 2403 Read symbol table information from file FILENAME. `PATH' is 2404 searched when necessary. Use the `file' command to get both symbol 2405 table and program to run from the same file. 2406 2407 `symbol-file' with no argument clears out GDB information on your 2408 program's symbol table. 2409 2410 The `symbol-file' command causes GDB to forget the contents of 2411 some breakpoints and auto-display expressions. This is because 2412 they may contain pointers to the internal data recording symbols 2413 and data types, which are part of the old symbol table data being 2414 discarded inside GDB. 2415 2416 `symbol-file' does not repeat if you press <RET> again after 2417 executing it once. 2418 2419 When GDB is configured for a particular environment, it 2420 understands debugging information in whatever format is the 2421 standard generated for that environment; you may use either a GNU 2422 compiler, or other compilers that adhere to the local conventions. 2423 Best results are usually obtained from GNU compilers; for example, 2424 using `GCC' you can generate debugging information for optimized 2425 code. 2426 2427 For most kinds of object files, with the exception of old SVR3 2428 systems using COFF, the `symbol-file' command does not normally 2429 read the symbol table in full right away. Instead, it scans the 2430 symbol table quickly to find which source files and which symbols 2431 are present. The details are read later, one source file at a 2432 time, as they are needed. 2433 2434 The purpose of this two-stage reading strategy is to make GDB 2435 start up faster. For the most part, it is invisible except for 2436 occasional pauses while the symbol table details for a particular 2437 source file are being read. (The `set verbose' command can turn 2438 these pauses into messages if desired. *Note Optional Warnings 2439 and Messages: Messages/Warnings.) 2440 2441 We have not implemented the two-stage strategy for COFF yet. When 2442 the symbol table is stored in COFF format, `symbol-file' reads the 2443 symbol table data in full right away. Note that "stabs-in-COFF" 2444 still does the two-stage strategy, since the debug info is actually 2445 in stabs format. 2446 2447`symbol-file FILENAME [ -readnow ]' 2448`file FILENAME [ -readnow ]' 2449 You can override the GDB two-stage strategy for reading symbol 2450 tables by using the `-readnow' option with any of the commands that 2451 load symbol table information, if you want to be sure GDB has the 2452 entire symbol table available. 2453 2454`core-file [FILENAME]' 2455`core' 2456 Specify the whereabouts of a core dump file to be used as the 2457 "contents of memory". Traditionally, core files contain only some 2458 parts of the address space of the process that generated them; GDB 2459 can access the executable file itself for other parts. 2460 2461 `core-file' with no argument specifies that no core file is to be 2462 used. 2463 2464 Note that the core file is ignored when your program is actually 2465 running under GDB. So, if you have been running your program and 2466 you wish to debug a core file instead, you must kill the 2467 subprocess in which the program is running. To do this, use the 2468 `kill' command (*note Killing the Child Process: Kill Process.). 2469 2470`add-symbol-file FILENAME ADDRESS' 2471`add-symbol-file FILENAME ADDRESS [ -readnow ]' 2472`add-symbol-file FILENAME -sSECTION ADDRESS ...' 2473 The `add-symbol-file' command reads additional symbol table 2474 information from the file FILENAME. You would use this command 2475 when FILENAME has been dynamically loaded (by some other means) 2476 into the program that is running. ADDRESS should be the memory 2477 address at which the file has been loaded; GDB cannot figure this 2478 out for itself. You can additionally specify an arbitrary number 2479 of `-sSECTION ADDRESS' pairs, to give an explicit section name and 2480 base address for that section. You can specify any ADDRESS as an 2481 expression. 2482 2483 The symbol table of the file FILENAME is added to the symbol table 2484 originally read with the `symbol-file' command. You can use the 2485 `add-symbol-file' command any number of times; the new symbol data 2486 thus read keeps adding to the old. To discard all old symbol data 2487 instead, use the `symbol-file' command without any arguments. 2488 2489 Although FILENAME is typically a shared library file, an 2490 executable file, or some other object file which has been fully 2491 relocated for loading into a process, you can also load symbolic 2492 information from relocatable `.o' files, as long as: 2493 2494 * the file's symbolic information refers only to linker symbols 2495 defined in that file, not to symbols defined by other object 2496 files, 2497 2498 * every section the file's symbolic information refers to has 2499 actually been loaded into the inferior, as it appears in the 2500 file, and 2501 2502 * you can determine the address at which every section was 2503 loaded, and provide these to the `add-symbol-file' command. 2504 2505 Some embedded operating systems, like Sun Chorus and VxWorks, can 2506 load relocatable files into an already running program; such 2507 systems typically make the requirements above easy to meet. 2508 However, it's important to recognize that many native systems use 2509 complex link procedures (`.linkonce' section factoring and C++ 2510 constructor table assembly, for example) that make the 2511 requirements difficult to meet. In general, one cannot assume 2512 that using `add-symbol-file' to read a relocatable object file's 2513 symbolic information will have the same effect as linking the 2514 relocatable object file into the program in the normal way. 2515 2516 `add-symbol-file' does not repeat if you press <RET> after using 2517 it. 2518 2519`add-symbol-file-from-memory ADDRESS' 2520 Load symbols from the given ADDRESS in a dynamically loaded object 2521 file whose image is mapped directly into the inferior's memory. 2522 For example, the Linux kernel maps a `syscall DSO' into each 2523 process's address space; this DSO provides kernel-specific code for 2524 some system calls. The argument can be any expression whose 2525 evaluation yields the address of the file's shared object file 2526 header. For this command to work, you must have used 2527 `symbol-file' or `exec-file' commands in advance. 2528 2529`add-shared-symbol-files LIBRARY-FILE' 2530`assf LIBRARY-FILE' 2531 The `add-shared-symbol-files' command can currently be used only 2532 in the Cygwin build of GDB on MS-Windows OS, where it is an alias 2533 for the `dll-symbols' command (*note Cygwin Native::). GDB 2534 automatically looks for shared libraries, however if GDB does not 2535 find yours, you can invoke `add-shared-symbol-files'. It takes 2536 one argument: the shared library's file name. `assf' is a 2537 shorthand alias for `add-shared-symbol-files'. 2538 2539`section SECTION ADDR' 2540 The `section' command changes the base address of the named 2541 SECTION of the exec file to ADDR. This can be used if the exec 2542 file does not contain section addresses, (such as in the `a.out' 2543 format), or when the addresses specified in the file itself are 2544 wrong. Each section must be changed separately. The `info files' 2545 command, described below, lists all the sections and their 2546 addresses. 2547 2548`info files' 2549`info target' 2550 `info files' and `info target' are synonymous; both print the 2551 current target (*note Specifying a Debugging Target: Targets.), 2552 including the names of the executable and core dump files 2553 currently in use by GDB, and the files from which symbols were 2554 loaded. The command `help target' lists all possible targets 2555 rather than current ones. 2556 2557`maint info sections' 2558 Another command that can give you extra information about program 2559 sections is `maint info sections'. In addition to the section 2560 information displayed by `info files', this command displays the 2561 flags and file offset of each section in the executable and core 2562 dump files. In addition, `maint info sections' provides the 2563 following command options (which may be arbitrarily combined): 2564 2565 `ALLOBJ' 2566 Display sections for all loaded object files, including 2567 shared libraries. 2568 2569 `SECTIONS' 2570 Display info only for named SECTIONS. 2571 2572 `SECTION-FLAGS' 2573 Display info only for sections for which SECTION-FLAGS are 2574 true. The section flags that GDB currently knows about are: 2575 `ALLOC' 2576 Section will have space allocated in the process when 2577 loaded. Set for all sections except those containing 2578 debug information. 2579 2580 `LOAD' 2581 Section will be loaded from the file into the child 2582 process memory. Set for pre-initialized code and data, 2583 clear for `.bss' sections. 2584 2585 `RELOC' 2586 Section needs to be relocated before loading. 2587 2588 `READONLY' 2589 Section cannot be modified by the child process. 2590 2591 `CODE' 2592 Section contains executable code only. 2593 2594 `DATA' 2595 Section contains data only (no executable code). 2596 2597 `ROM' 2598 Section will reside in ROM. 2599 2600 `CONSTRUCTOR' 2601 Section contains data for constructor/destructor lists. 2602 2603 `HAS_CONTENTS' 2604 Section is not empty. 2605 2606 `NEVER_LOAD' 2607 An instruction to the linker to not output the section. 2608 2609 `COFF_SHARED_LIBRARY' 2610 A notification to the linker that the section contains 2611 COFF shared library information. 2612 2613 `IS_COMMON' 2614 Section contains common symbols. 2615 2616`set trust-readonly-sections on' 2617 Tell GDB that readonly sections in your object file really are 2618 read-only (i.e. that their contents will not change). In that 2619 case, GDB can fetch values from these sections out of the object 2620 file, rather than from the target program. For some targets 2621 (notably embedded ones), this can be a significant enhancement to 2622 debugging performance. 2623 2624 The default is off. 2625 2626`set trust-readonly-sections off' 2627 Tell GDB not to trust readonly sections. This means that the 2628 contents of the section might change while the program is running, 2629 and must therefore be fetched from the target when needed. 2630 2631`show trust-readonly-sections' 2632 Show the current setting of trusting readonly sections. 2633 2634 All file-specifying commands allow both absolute and relative file 2635names as arguments. GDB always converts the file name to an absolute 2636file name and remembers it that way. 2637 2638 GDB supports GNU/Linux, MS-Windows, HP-UX, SunOS, SVr4, Irix, and 2639IBM RS/6000 AIX shared libraries. 2640 2641 GDB automatically loads symbol definitions from shared libraries 2642when you use the `run' command, or when you examine a core file. 2643(Before you issue the `run' command, GDB does not understand references 2644to a function in a shared library, however--unless you are debugging a 2645core file). 2646 2647 On HP-UX, if the program loads a library explicitly, GDB 2648automatically loads the symbols at the time of the `shl_load' call. 2649 2650 There are times, however, when you may wish to not automatically load 2651symbol definitions from shared libraries, such as when they are 2652particularly large or there are many of them. 2653 2654 To control the automatic loading of shared library symbols, use the 2655commands: 2656 2657`set auto-solib-add MODE' 2658 If MODE is `on', symbols from all shared object libraries will be 2659 loaded automatically when the inferior begins execution, you 2660 attach to an independently started inferior, or when the dynamic 2661 linker informs GDB that a new library has been loaded. If MODE is 2662 `off', symbols must be loaded manually, using the `sharedlibrary' 2663 command. The default value is `on'. 2664 2665 If your program uses lots of shared libraries with debug info that 2666 takes large amounts of memory, you can decrease the GDB memory 2667 footprint by preventing it from automatically loading the symbols 2668 from shared libraries. To that end, type `set auto-solib-add off' 2669 before running the inferior, then load each library whose debug 2670 symbols you do need with `sharedlibrary REGEXP', where REGEXP is a 2671 regular expression that matches the libraries whose symbols you 2672 want to be loaded. 2673 2674`show auto-solib-add' 2675 Display the current autoloading mode. 2676 2677 To explicitly load shared library symbols, use the `sharedlibrary' 2678command: 2679 2680`info share' 2681`info sharedlibrary' 2682 Print the names of the shared libraries which are currently loaded. 2683 2684`sharedlibrary REGEX' 2685`share REGEX' 2686 Load shared object library symbols for files matching a Unix 2687 regular expression. As with files loaded automatically, it only 2688 loads shared libraries required by your program for a core file or 2689 after typing `run'. If REGEX is omitted all shared libraries 2690 required by your program are loaded. 2691 2692`nosharedlibrary' 2693 Unload all shared object library symbols. This discards all 2694 symbols that have been loaded from all shared libraries. Symbols 2695 from shared libraries that were loaded by explicit user requests 2696 are not discarded. 2697 2698 Sometimes you may wish that GDB stops and gives you control when any 2699of shared library events happen. Use the `set stop-on-solib-events' 2700command for this: 2701 2702`set stop-on-solib-events' 2703 This command controls whether GDB should give you control when the 2704 dynamic linker notifies it about some shared library event. The 2705 most common event of interest is loading or unloading of a new 2706 shared library. 2707 2708`show stop-on-solib-events' 2709 Show whether GDB stops and gives you control when shared library 2710 events happen. 2711 2712 Shared libraries are also supported in many cross or remote debugging 2713configurations. A copy of the target's libraries need to be present on 2714the host system; they need to be the same as the target libraries, 2715although the copies on the target can be stripped as long as the copies 2716on the host are not. 2717 2718 For remote debugging, you need to tell GDB where the target 2719libraries are, so that it can load the correct copies--otherwise, it 2720may try to load the host's libraries. GDB has two variables to specify 2721the search directories for target libraries. 2722 2723`set sysroot PATH' 2724 Use PATH as the system root for the program being debugged. Any 2725 absolute shared library paths will be prefixed with PATH; many 2726 runtime loaders store the absolute paths to the shared library in 2727 the target program's memory. If you use `set sysroot' to find 2728 shared libraries, they need to be laid out in the same way that 2729 they are on the target, with e.g. a `/lib' and `/usr/lib' hierarchy 2730 under PATH. 2731 2732 The `set solib-absolute-prefix' command is an alias for `set 2733 sysroot'. 2734 2735 You can set the default system root by using the configure-time 2736 `--with-sysroot' option. If the system root is inside GDB's 2737 configured binary prefix (set with `--prefix' or `--exec-prefix'), 2738 then the default system root will be updated automatically if the 2739 installed GDB is moved to a new location. 2740 2741`show sysroot' 2742 Display the current shared library prefix. 2743 2744`set solib-search-path PATH' 2745 If this variable is set, PATH is a colon-separated list of 2746 directories to search for shared libraries. `solib-search-path' 2747 is used after `sysroot' fails to locate the library, or if the 2748 path to the library is relative instead of absolute. If you want 2749 to use `solib-search-path' instead of `sysroot', be sure to set 2750 `sysroot' to a nonexistent directory to prevent GDB from finding 2751 your host's libraries. `sysroot' is preferred; setting it to a 2752 nonexistent directory may interfere with automatic loading of 2753 shared library symbols. 2754 2755`show solib-search-path' 2756 Display the current shared library search path. 2757 2758 2759File: gdb.info, Node: Separate Debug Files, Next: Symbol Errors, Prev: Files, Up: GDB Files 2760 276115.2 Debugging Information in Separate Files 2762============================================ 2763 2764GDB allows you to put a program's debugging information in a file 2765separate from the executable itself, in a way that allows GDB to find 2766and load the debugging information automatically. Since debugging 2767information can be very large--sometimes larger than the executable 2768code itself--some systems distribute debugging information for their 2769executables in separate files, which users can install only when they 2770need to debug a problem. 2771 2772 GDB supports two ways of specifying the separate debug info file: 2773 2774 * The executable contains a "debug link" that specifies the name of 2775 the separate debug info file. The separate debug file's name is 2776 usually `EXECUTABLE.debug', where EXECUTABLE is the name of the 2777 corresponding executable file without leading directories (e.g., 2778 `ls.debug' for `/usr/bin/ls'). In addition, the debug link 2779 specifies a CRC32 checksum for the debug file, which GDB uses to 2780 validate that the executable and the debug file came from the same 2781 build. 2782 2783 * The executable contains a "build ID", a unique signature that is 2784 also present in the corresponding debug info file. (This is 2785 supported only on some operating systems, notably on GNU/Linux. 2786 For more details about this feature, see the Fedora Project's 2787 description of the buid ID feature 2788 (http://fedoraproject.org/wiki/Releases/FeatureBuildId).) The 2789 debug info file's name is not specified explicitly by the build 2790 ID, but can be computed from the build ID, see below. 2791 2792 Depending on the way the debug info file is specified, GDB uses two 2793different methods of looking for the debug file: 2794 2795 * For the "debug link" method, GDB looks up the named file in the 2796 directory of the executable file, then in a subdirectory of that 2797 directory named `.debug', and finally under the global debug 2798 directory, in a subdirectory whose name is identical to the leading 2799 directories of the executable's absolute file name. 2800 2801 * For the "build ID" method, GDB looks in the `.build-id' 2802 subdirectory of the global debug directory for a file named 2803 `NN/NNNNNNNN.debug', where NN are the first 2 hex characters of 2804 the build ID signature, and NNNNNNNN are the rest of the 2805 signature. (Real signatures are 32 or more characters, not 10.) 2806 2807 So, for example, suppose you ask GDB to debug `/usr/bin/ls', which 2808has a "debug link" that specifies the file `ls.debug', and a "build id" 2809whose value in hex is `abcdef1234'. If the global debug directory is 2810`/usr/lib/debug', then GDB will look for the following debug 2811information files, in the indicated order: 2812 2813 - `/usr/lib/debug/.build-id/ab/cdef1234.debug' 2814 2815 - `/usr/bin/ls.debug' 2816 2817 - `/usr/bin/.debug/ls.debug' 2818 2819 - `/usr/lib/debug/usr/bin/ls.debug'. 2820 2821 You can set the global debugging info directory's name, and view the 2822name GDB is currently using. 2823 2824`set debug-file-directory DIRECTORY' 2825 Set the directory which GDB searches for separate debugging 2826 information files to DIRECTORY. 2827 2828`show debug-file-directory' 2829 Show the directory GDB searches for separate debugging information 2830 files. 2831 2832 2833 A debug link is a special section of the executable file named 2834`.gnu_debuglink'. The section must contain: 2835 2836 * A filename, with any leading directory components removed, 2837 followed by a zero byte, 2838 2839 * zero to three bytes of padding, as needed to reach the next 2840 four-byte boundary within the section, and 2841 2842 * a four-byte CRC checksum, stored in the same endianness used for 2843 the executable file itself. The checksum is computed on the 2844 debugging information file's full contents by the function given 2845 below, passing zero as the CRC argument. 2846 2847 Any executable file format can carry a debug link, as long as it can 2848contain a section named `.gnu_debuglink' with the contents described 2849above. 2850 2851 A build ID is a special section of the executable file named 2852`.note.gnu.build-id'. This section contains unique identification for 2853the built files--it remains the same across multiple builds of the same 2854build tree. The default algorithm SHA1 produces 160 bits (40 2855hexadecimal characters) of the content. The same section with an 2856identical value is present in the original built binary with symbols, 2857in its stripped variant, and in the separate debugging information file. 2858 2859 The debugging information file itself should be an ordinary 2860executable, containing a full set of linker symbols, sections, and 2861debugging information. The sections of the debugging information file 2862should have the same names, addresses, and sizes as the original file, 2863but they need not contain any data--much like a `.bss' section in an 2864ordinary executable. 2865 2866 GNU binary utilities (Binutils) package includes the `objcopy' 2867utility that can produce the separated executable / debugging 2868information file pairs using the following commands: 2869 2870 objcopy --only-keep-debug foo foo.debug 2871 strip -g foo 2872 2873These commands remove the debugging information from the executable 2874file `foo' and place it in the file `foo.debug'. You can use the 2875first, second or both methods to link the two files: 2876 2877 * The debug link method needs the following additional command to 2878 also leave behind a debug link in `foo': 2879 2880 objcopy --add-gnu-debuglink=foo.debug foo 2881 2882 Ulrich Drepper's `elfutils' package, starting with version 0.53, 2883 contains a version of the `strip' command such that the command 2884 `strip foo -f foo.debug' has the same functionality as the two 2885 `objcopy' commands and the `ln -s' command above, together. 2886 2887 * Build ID gets embedded into the main executable using `ld 2888 --build-id' or the GCC counterpart `gcc -Wl,--build-id'. Build ID 2889 support plus compatibility fixes for debug files separation are 2890 present in GNU binary utilities (Binutils) since version 2.18. 2891 2892Since there are many different ways to compute CRC's for the debug link 2893(different polynomials, reversals, byte ordering, etc.), the simplest 2894way to describe the CRC used in `.gnu_debuglink' sections is to give 2895the complete code for a function that computes it: 2896 2897 unsigned long 2898 gnu_debuglink_crc32 (unsigned long crc, 2899 unsigned char *buf, size_t len) 2900 { 2901 static const unsigned long crc32_table[256] = 2902 { 2903 0x00000000, 0x77073096, 0xee0e612c, 0x990951ba, 0x076dc419, 2904 0x706af48f, 0xe963a535, 0x9e6495a3, 0x0edb8832, 0x79dcb8a4, 2905 0xe0d5e91e, 0x97d2d988, 0x09b64c2b, 0x7eb17cbd, 0xe7b82d07, 2906 0x90bf1d91, 0x1db71064, 0x6ab020f2, 0xf3b97148, 0x84be41de, 2907 0x1adad47d, 0x6ddde4eb, 0xf4d4b551, 0x83d385c7, 0x136c9856, 2908 0x646ba8c0, 0xfd62f97a, 0x8a65c9ec, 0x14015c4f, 0x63066cd9, 2909 0xfa0f3d63, 0x8d080df5, 0x3b6e20c8, 0x4c69105e, 0xd56041e4, 2910 0xa2677172, 0x3c03e4d1, 0x4b04d447, 0xd20d85fd, 0xa50ab56b, 2911 0x35b5a8fa, 0x42b2986c, 0xdbbbc9d6, 0xacbcf940, 0x32d86ce3, 2912 0x45df5c75, 0xdcd60dcf, 0xabd13d59, 0x26d930ac, 0x51de003a, 2913 0xc8d75180, 0xbfd06116, 0x21b4f4b5, 0x56b3c423, 0xcfba9599, 2914 0xb8bda50f, 0x2802b89e, 0x5f058808, 0xc60cd9b2, 0xb10be924, 2915 0x2f6f7c87, 0x58684c11, 0xc1611dab, 0xb6662d3d, 0x76dc4190, 2916 0x01db7106, 0x98d220bc, 0xefd5102a, 0x71b18589, 0x06b6b51f, 2917 0x9fbfe4a5, 0xe8b8d433, 0x7807c9a2, 0x0f00f934, 0x9609a88e, 2918 0xe10e9818, 0x7f6a0dbb, 0x086d3d2d, 0x91646c97, 0xe6635c01, 2919 0x6b6b51f4, 0x1c6c6162, 0x856530d8, 0xf262004e, 0x6c0695ed, 2920 0x1b01a57b, 0x8208f4c1, 0xf50fc457, 0x65b0d9c6, 0x12b7e950, 2921 0x8bbeb8ea, 0xfcb9887c, 0x62dd1ddf, 0x15da2d49, 0x8cd37cf3, 2922 0xfbd44c65, 0x4db26158, 0x3ab551ce, 0xa3bc0074, 0xd4bb30e2, 2923 0x4adfa541, 0x3dd895d7, 0xa4d1c46d, 0xd3d6f4fb, 0x4369e96a, 2924 0x346ed9fc, 0xad678846, 0xda60b8d0, 0x44042d73, 0x33031de5, 2925 0xaa0a4c5f, 0xdd0d7cc9, 0x5005713c, 0x270241aa, 0xbe0b1010, 2926 0xc90c2086, 0x5768b525, 0x206f85b3, 0xb966d409, 0xce61e49f, 2927 0x5edef90e, 0x29d9c998, 0xb0d09822, 0xc7d7a8b4, 0x59b33d17, 2928 0x2eb40d81, 0xb7bd5c3b, 0xc0ba6cad, 0xedb88320, 0x9abfb3b6, 2929 0x03b6e20c, 0x74b1d29a, 0xead54739, 0x9dd277af, 0x04db2615, 2930 0x73dc1683, 0xe3630b12, 0x94643b84, 0x0d6d6a3e, 0x7a6a5aa8, 2931 0xe40ecf0b, 0x9309ff9d, 0x0a00ae27, 0x7d079eb1, 0xf00f9344, 2932 0x8708a3d2, 0x1e01f268, 0x6906c2fe, 0xf762575d, 0x806567cb, 2933 0x196c3671, 0x6e6b06e7, 0xfed41b76, 0x89d32be0, 0x10da7a5a, 2934 0x67dd4acc, 0xf9b9df6f, 0x8ebeeff9, 0x17b7be43, 0x60b08ed5, 2935 0xd6d6a3e8, 0xa1d1937e, 0x38d8c2c4, 0x4fdff252, 0xd1bb67f1, 2936 0xa6bc5767, 0x3fb506dd, 0x48b2364b, 0xd80d2bda, 0xaf0a1b4c, 2937 0x36034af6, 0x41047a60, 0xdf60efc3, 0xa867df55, 0x316e8eef, 2938 0x4669be79, 0xcb61b38c, 0xbc66831a, 0x256fd2a0, 0x5268e236, 2939 0xcc0c7795, 0xbb0b4703, 0x220216b9, 0x5505262f, 0xc5ba3bbe, 2940 0xb2bd0b28, 0x2bb45a92, 0x5cb36a04, 0xc2d7ffa7, 0xb5d0cf31, 2941 0x2cd99e8b, 0x5bdeae1d, 0x9b64c2b0, 0xec63f226, 0x756aa39c, 2942 0x026d930a, 0x9c0906a9, 0xeb0e363f, 0x72076785, 0x05005713, 2943 0x95bf4a82, 0xe2b87a14, 0x7bb12bae, 0x0cb61b38, 0x92d28e9b, 2944 0xe5d5be0d, 0x7cdcefb7, 0x0bdbdf21, 0x86d3d2d4, 0xf1d4e242, 2945 0x68ddb3f8, 0x1fda836e, 0x81be16cd, 0xf6b9265b, 0x6fb077e1, 2946 0x18b74777, 0x88085ae6, 0xff0f6a70, 0x66063bca, 0x11010b5c, 2947 0x8f659eff, 0xf862ae69, 0x616bffd3, 0x166ccf45, 0xa00ae278, 2948 0xd70dd2ee, 0x4e048354, 0x3903b3c2, 0xa7672661, 0xd06016f7, 2949 0x4969474d, 0x3e6e77db, 0xaed16a4a, 0xd9d65adc, 0x40df0b66, 2950 0x37d83bf0, 0xa9bcae53, 0xdebb9ec5, 0x47b2cf7f, 0x30b5ffe9, 2951 0xbdbdf21c, 0xcabac28a, 0x53b39330, 0x24b4a3a6, 0xbad03605, 2952 0xcdd70693, 0x54de5729, 0x23d967bf, 0xb3667a2e, 0xc4614ab8, 2953 0x5d681b02, 0x2a6f2b94, 0xb40bbe37, 0xc30c8ea1, 0x5a05df1b, 2954 0x2d02ef8d 2955 }; 2956 unsigned char *end; 2957 2958 crc = ~crc & 0xffffffff; 2959 for (end = buf + len; buf < end; ++buf) 2960 crc = crc32_table[(crc ^ *buf) & 0xff] ^ (crc >> 8); 2961 return ~crc & 0xffffffff; 2962 } 2963 2964This computation does not apply to the "build ID" method. 2965 2966 2967File: gdb.info, Node: Symbol Errors, Prev: Separate Debug Files, Up: GDB Files 2968 296915.3 Errors Reading Symbol Files 2970================================ 2971 2972While reading a symbol file, GDB occasionally encounters problems, such 2973as symbol types it does not recognize, or known bugs in compiler 2974output. By default, GDB does not notify you of such problems, since 2975they are relatively common and primarily of interest to people 2976debugging compilers. If you are interested in seeing information about 2977ill-constructed symbol tables, you can either ask GDB to print only one 2978message about each such type of problem, no matter how many times the 2979problem occurs; or you can ask GDB to print more messages, to see how 2980many times the problems occur, with the `set complaints' command (*note 2981Optional Warnings and Messages: Messages/Warnings.). 2982 2983 The messages currently printed, and their meanings, include: 2984 2985`inner block not inside outer block in SYMBOL' 2986 The symbol information shows where symbol scopes begin and end 2987 (such as at the start of a function or a block of statements). 2988 This error indicates that an inner scope block is not fully 2989 contained in its outer scope blocks. 2990 2991 GDB circumvents the problem by treating the inner block as if it 2992 had the same scope as the outer block. In the error message, 2993 SYMBOL may be shown as "`(don't know)'" if the outer block is not a 2994 function. 2995 2996`block at ADDRESS out of order' 2997 The symbol information for symbol scope blocks should occur in 2998 order of increasing addresses. This error indicates that it does 2999 not do so. 3000 3001 GDB does not circumvent this problem, and has trouble locating 3002 symbols in the source file whose symbols it is reading. (You can 3003 often determine what source file is affected by specifying `set 3004 verbose on'. *Note Optional Warnings and Messages: 3005 Messages/Warnings.) 3006 3007`bad block start address patched' 3008 The symbol information for a symbol scope block has a start address 3009 smaller than the address of the preceding source line. This is 3010 known to occur in the SunOS 4.1.1 (and earlier) C compiler. 3011 3012 GDB circumvents the problem by treating the symbol scope block as 3013 starting on the previous source line. 3014 3015`bad string table offset in symbol N' 3016 Symbol number N contains a pointer into the string table which is 3017 larger than the size of the string table. 3018 3019 GDB circumvents the problem by considering the symbol to have the 3020 name `foo', which may cause other problems if many symbols end up 3021 with this name. 3022 3023`unknown symbol type `0xNN'' 3024 The symbol information contains new data types that GDB does not 3025 yet know how to read. `0xNN' is the symbol type of the 3026 uncomprehended information, in hexadecimal. 3027 3028 GDB circumvents the error by ignoring this symbol information. 3029 This usually allows you to debug your program, though certain 3030 symbols are not accessible. If you encounter such a problem and 3031 feel like debugging it, you can debug `gdb' with itself, breakpoint 3032 on `complain', then go up to the function `read_dbx_symtab' and 3033 examine `*bufp' to see the symbol. 3034 3035`stub type has NULL name' 3036 GDB could not find the full definition for a struct or class. 3037 3038`const/volatile indicator missing (ok if using g++ v1.x), got...' 3039 The symbol information for a C++ member function is missing some 3040 information that recent versions of the compiler should have 3041 output for it. 3042 3043`info mismatch between compiler and debugger' 3044 GDB could not parse a type specification output by the compiler. 3045 3046 3047 3048File: gdb.info, Node: Targets, Next: Remote Debugging, Prev: GDB Files, Up: Top 3049 305016 Specifying a Debugging Target 3051******************************** 3052 3053A "target" is the execution environment occupied by your program. 3054 3055 Often, GDB runs in the same host environment as your program; in 3056that case, the debugging target is specified as a side effect when you 3057use the `file' or `core' commands. When you need more flexibility--for 3058example, running GDB on a physically separate host, or controlling a 3059standalone system over a serial port or a realtime system over a TCP/IP 3060connection--you can use the `target' command to specify one of the 3061target types configured for GDB (*note Commands for Managing Targets: 3062Target Commands.). 3063 3064 It is possible to build GDB for several different "target 3065architectures". When GDB is built like that, you can choose one of the 3066available architectures with the `set architecture' command. 3067 3068`set architecture ARCH' 3069 This command sets the current target architecture to ARCH. The 3070 value of ARCH can be `"auto"', in addition to one of the supported 3071 architectures. 3072 3073`show architecture' 3074 Show the current target architecture. 3075 3076`set processor' 3077`processor' 3078 These are alias commands for, respectively, `set architecture' and 3079 `show architecture'. 3080 3081* Menu: 3082 3083* Active Targets:: Active targets 3084* Target Commands:: Commands for managing targets 3085* Byte Order:: Choosing target byte order 3086 3087 3088File: gdb.info, Node: Active Targets, Next: Target Commands, Up: Targets 3089 309016.1 Active Targets 3091=================== 3092 3093There are three classes of targets: processes, core files, and 3094executable files. GDB can work concurrently on up to three active 3095targets, one in each class. This allows you to (for example) start a 3096process and inspect its activity without abandoning your work on a core 3097file. 3098 3099 For example, if you execute `gdb a.out', then the executable file 3100`a.out' is the only active target. If you designate a core file as 3101well--presumably from a prior run that crashed and coredumped--then GDB 3102has two active targets and uses them in tandem, looking first in the 3103corefile target, then in the executable file, to satisfy requests for 3104memory addresses. (Typically, these two classes of target are 3105complementary, since core files contain only a program's read-write 3106memory--variables and so on--plus machine status, while executable 3107files contain only the program text and initialized data.) 3108 3109 When you type `run', your executable file becomes an active process 3110target as well. When a process target is active, all GDB commands 3111requesting memory addresses refer to that target; addresses in an 3112active core file or executable file target are obscured while the 3113process target is active. 3114 3115 Use the `core-file' and `exec-file' commands to select a new core 3116file or executable target (*note Commands to Specify Files: Files.). 3117To specify as a target a process that is already running, use the 3118`attach' command (*note Debugging an Already-running Process: Attach.). 3119 3120 3121File: gdb.info, Node: Target Commands, Next: Byte Order, Prev: Active Targets, Up: Targets 3122 312316.2 Commands for Managing Targets 3124================================== 3125 3126`target TYPE PARAMETERS' 3127 Connects the GDB host environment to a target machine or process. 3128 A target is typically a protocol for talking to debugging 3129 facilities. You use the argument TYPE to specify the type or 3130 protocol of the target machine. 3131 3132 Further PARAMETERS are interpreted by the target protocol, but 3133 typically include things like device names or host names to connect 3134 with, process numbers, and baud rates. 3135 3136 The `target' command does not repeat if you press <RET> again 3137 after executing the command. 3138 3139`help target' 3140 Displays the names of all targets available. To display targets 3141 currently selected, use either `info target' or `info files' 3142 (*note Commands to Specify Files: Files.). 3143 3144`help target NAME' 3145 Describe a particular target, including any parameters necessary to 3146 select it. 3147 3148`set gnutarget ARGS' 3149 GDB uses its own library BFD to read your files. GDB knows 3150 whether it is reading an "executable", a "core", or a ".o" file; 3151 however, you can specify the file format with the `set gnutarget' 3152 command. Unlike most `target' commands, with `gnutarget' the 3153 `target' refers to a program, not a machine. 3154 3155 _Warning:_ To specify a file format with `set gnutarget', you 3156 must know the actual BFD name. 3157 3158 *Note Commands to Specify Files: Files. 3159 3160`show gnutarget' 3161 Use the `show gnutarget' command to display what file format 3162 `gnutarget' is set to read. If you have not set `gnutarget', GDB 3163 will determine the file format for each file automatically, and 3164 `show gnutarget' displays `The current BDF target is "auto"'. 3165 3166 Here are some common targets (available, or not, depending on the GDB 3167configuration): 3168 3169`target exec PROGRAM' 3170 An executable file. `target exec PROGRAM' is the same as 3171 `exec-file PROGRAM'. 3172 3173`target core FILENAME' 3174 A core dump file. `target core FILENAME' is the same as 3175 `core-file FILENAME'. 3176 3177`target remote MEDIUM' 3178 A remote system connected to GDB via a serial line or network 3179 connection. This command tells GDB to use its own remote protocol 3180 over MEDIUM for debugging. *Note Remote Debugging::. 3181 3182 For example, if you have a board connected to `/dev/ttya' on the 3183 machine running GDB, you could say: 3184 3185 target remote /dev/ttya 3186 3187 `target remote' supports the `load' command. This is only useful 3188 if you have some other way of getting the stub to the target 3189 system, and you can put it somewhere in memory where it won't get 3190 clobbered by the download. 3191 3192`target sim' 3193 Builtin CPU simulator. GDB includes simulators for most 3194 architectures. In general, 3195 target sim 3196 load 3197 run 3198 works; however, you cannot assume that a specific memory map, 3199 device drivers, or even basic I/O is available, although some 3200 simulators do provide these. For info about any 3201 processor-specific simulator details, see the appropriate section 3202 in *Note Embedded Processors: Embedded Processors. 3203 3204 3205 Some configurations may include these targets as well: 3206 3207`target nrom DEV' 3208 NetROM ROM emulator. This target only supports downloading. 3209 3210 3211 Different targets are available on different configurations of GDB; 3212your configuration may have more or fewer targets. 3213 3214 Many remote targets require you to download the executable's code 3215once you've successfully established a connection. You may wish to 3216control various aspects of this process. 3217 3218`set hash' 3219 This command controls whether a hash mark `#' is displayed while 3220 downloading a file to the remote monitor. If on, a hash mark is 3221 displayed after each S-record is successfully downloaded to the 3222 monitor. 3223 3224`show hash' 3225 Show the current status of displaying the hash mark. 3226 3227`set debug monitor' 3228 Enable or disable display of communications messages between GDB 3229 and the remote monitor. 3230 3231`show debug monitor' 3232 Show the current status of displaying communications between GDB 3233 and the remote monitor. 3234 3235`load FILENAME' 3236 Depending on what remote debugging facilities are configured into 3237 GDB, the `load' command may be available. Where it exists, it is 3238 meant to make FILENAME (an executable) available for debugging on 3239 the remote system--by downloading, or dynamic linking, for example. 3240 `load' also records the FILENAME symbol table in GDB, like the 3241 `add-symbol-file' command. 3242 3243 If your GDB does not have a `load' command, attempting to execute 3244 it gets the error message "`You can't do that when your target is 3245 ...'" 3246 3247 The file is loaded at whatever address is specified in the 3248 executable. For some object file formats, you can specify the 3249 load address when you link the program; for other formats, like 3250 a.out, the object file format specifies a fixed address. 3251 3252 Depending on the remote side capabilities, GDB may be able to load 3253 programs into flash memory. 3254 3255 `load' does not repeat if you press <RET> again after using it. 3256 3257 3258File: gdb.info, Node: Byte Order, Prev: Target Commands, Up: Targets 3259 326016.3 Choosing Target Byte Order 3261=============================== 3262 3263Some types of processors, such as the MIPS, PowerPC, and Renesas SH, 3264offer the ability to run either big-endian or little-endian byte 3265orders. Usually the executable or symbol will include a bit to 3266designate the endian-ness, and you will not need to worry about which 3267to use. However, you may still find it useful to adjust GDB's idea of 3268processor endian-ness manually. 3269 3270`set endian big' 3271 Instruct GDB to assume the target is big-endian. 3272 3273`set endian little' 3274 Instruct GDB to assume the target is little-endian. 3275 3276`set endian auto' 3277 Instruct GDB to use the byte order associated with the executable. 3278 3279`show endian' 3280 Display GDB's current idea of the target byte order. 3281 3282 3283 Note that these commands merely adjust interpretation of symbolic 3284data on the host, and that they have absolutely no effect on the target 3285system. 3286 3287 3288File: gdb.info, Node: Remote Debugging, Next: Configurations, Prev: Targets, Up: Top 3289 329017 Debugging Remote Programs 3291**************************** 3292 3293If you are trying to debug a program running on a machine that cannot 3294run GDB in the usual way, it is often useful to use remote debugging. 3295For example, you might use remote debugging on an operating system 3296kernel, or on a small system which does not have a general purpose 3297operating system powerful enough to run a full-featured debugger. 3298 3299 Some configurations of GDB have special serial or TCP/IP interfaces 3300to make this work with particular debugging targets. In addition, GDB 3301comes with a generic serial protocol (specific to GDB, but not specific 3302to any particular target system) which you can use if you write the 3303remote stubs--the code that runs on the remote system to communicate 3304with GDB. 3305 3306 Other remote targets may be available in your configuration of GDB; 3307use `help target' to list them. 3308 3309* Menu: 3310 3311* Connecting:: Connecting to a remote target 3312* Server:: Using the gdbserver program 3313* Remote Configuration:: Remote configuration 3314* Remote Stub:: Implementing a remote stub 3315 3316 3317File: gdb.info, Node: Connecting, Next: Server, Up: Remote Debugging 3318 331917.1 Connecting to a Remote Target 3320================================== 3321 3322On the GDB host machine, you will need an unstripped copy of your 3323program, since GDB needs symbol and debugging information. Start up 3324GDB as usual, using the name of the local copy of your program as the 3325first argument. 3326 3327 GDB can communicate with the target over a serial line, or over an 3328IP network using TCP or UDP. In each case, GDB uses the same protocol 3329for debugging your program; only the medium carrying the debugging 3330packets varies. The `target remote' command establishes a connection 3331to the target. Its arguments indicate which medium to use: 3332 3333`target remote SERIAL-DEVICE' 3334 Use SERIAL-DEVICE to communicate with the target. For example, to 3335 use a serial line connected to the device named `/dev/ttyb': 3336 3337 target remote /dev/ttyb 3338 3339 If you're using a serial line, you may want to give GDB the 3340 `--baud' option, or use the `set remotebaud' command (*note set 3341 remotebaud: Remote Configuration.) before the `target' command. 3342 3343`target remote `HOST:PORT'' 3344`target remote `tcp:HOST:PORT'' 3345 Debug using a TCP connection to PORT on HOST. The HOST may be 3346 either a host name or a numeric IP address; PORT must be a decimal 3347 number. The HOST could be the target machine itself, if it is 3348 directly connected to the net, or it might be a terminal server 3349 which in turn has a serial line to the target. 3350 3351 For example, to connect to port 2828 on a terminal server named 3352 `manyfarms': 3353 3354 target remote manyfarms:2828 3355 3356 If your remote target is actually running on the same machine as 3357 your debugger session (e.g. a simulator for your target running on 3358 the same host), you can omit the hostname. For example, to 3359 connect to port 1234 on your local machine: 3360 3361 target remote :1234 3362 Note that the colon is still required here. 3363 3364`target remote `udp:HOST:PORT'' 3365 Debug using UDP packets to PORT on HOST. For example, to connect 3366 to UDP port 2828 on a terminal server named `manyfarms': 3367 3368 target remote udp:manyfarms:2828 3369 3370 When using a UDP connection for remote debugging, you should keep 3371 in mind that the `U' stands for "Unreliable". UDP can silently 3372 drop packets on busy or unreliable networks, which will cause 3373 havoc with your debugging session. 3374 3375`target remote | COMMAND' 3376 Run COMMAND in the background and communicate with it using a 3377 pipe. The COMMAND is a shell command, to be parsed and expanded 3378 by the system's command shell, `/bin/sh'; it should expect remote 3379 protocol packets on its standard input, and send replies on its 3380 standard output. You could use this to run a stand-alone simulator 3381 that speaks the remote debugging protocol, to make net connections 3382 using programs like `ssh', or for other similar tricks. 3383 3384 If COMMAND closes its standard output (perhaps by exiting), GDB 3385 will try to send it a `SIGTERM' signal. (If the program has 3386 already exited, this will have no effect.) 3387 3388 3389 Once the connection has been established, you can use all the usual 3390commands to examine and change data and to step and continue the remote 3391program. 3392 3393 Whenever GDB is waiting for the remote program, if you type the 3394interrupt character (often `Ctrl-c'), GDB attempts to stop the program. 3395This may or may not succeed, depending in part on the hardware and the 3396serial drivers the remote system uses. If you type the interrupt 3397character once again, GDB displays this prompt: 3398 3399 Interrupted while waiting for the program. 3400 Give up (and stop debugging it)? (y or n) 3401 3402 If you type `y', GDB abandons the remote debugging session. (If you 3403decide you want to try again later, you can use `target remote' again 3404to connect once more.) If you type `n', GDB goes back to waiting. 3405 3406`detach' 3407 When you have finished debugging the remote program, you can use 3408 the `detach' command to release it from GDB control. Detaching 3409 from the target normally resumes its execution, but the results 3410 will depend on your particular remote stub. After the `detach' 3411 command, GDB is free to connect to another target. 3412 3413`disconnect' 3414 The `disconnect' command behaves like `detach', except that the 3415 target is generally not resumed. It will wait for GDB (this 3416 instance or another one) to connect and continue debugging. After 3417 the `disconnect' command, GDB is again free to connect to another 3418 target. 3419 3420`monitor CMD' 3421 This command allows you to send arbitrary commands directly to the 3422 remote monitor. Since GDB doesn't care about the commands it 3423 sends like this, this command is the way to extend GDB--you can 3424 add new commands that only the external monitor will understand 3425 and implement. 3426 3427 3428File: gdb.info, Node: Server, Next: Remote Configuration, Prev: Connecting, Up: Remote Debugging 3429 343017.2 Using the `gdbserver' Program 3431================================== 3432 3433`gdbserver' is a control program for Unix-like systems, which allows 3434you to connect your program with a remote GDB via `target remote'--but 3435without linking in the usual debugging stub. 3436 3437 `gdbserver' is not a complete replacement for the debugging stubs, 3438because it requires essentially the same operating-system facilities 3439that GDB itself does. In fact, a system that can run `gdbserver' to 3440connect to a remote GDB could also run GDB locally! `gdbserver' is 3441sometimes useful nevertheless, because it is a much smaller program 3442than GDB itself. It is also easier to port than all of GDB, so you may 3443be able to get started more quickly on a new system by using 3444`gdbserver'. Finally, if you develop code for real-time systems, you 3445may find that the tradeoffs involved in real-time operation make it 3446more convenient to do as much development work as possible on another 3447system, for example by cross-compiling. You can use `gdbserver' to 3448make a similar choice for debugging. 3449 3450 GDB and `gdbserver' communicate via either a serial line or a TCP 3451connection, using the standard GDB remote serial protocol. 3452 3453_On the target machine,_ 3454 you need to have a copy of the program you want to debug. 3455 `gdbserver' does not need your program's symbol table, so you can 3456 strip the program if necessary to save space. GDB on the host 3457 system does all the symbol handling. 3458 3459 To use the server, you must tell it how to communicate with GDB; 3460 the name of your program; and the arguments for your program. The 3461 usual syntax is: 3462 3463 target> gdbserver COMM PROGRAM [ ARGS ... ] 3464 3465 COMM is either a device name (to use a serial line) or a TCP 3466 hostname and portnumber. For example, to debug Emacs with the 3467 argument `foo.txt' and communicate with GDB over the serial port 3468 `/dev/com1': 3469 3470 target> gdbserver /dev/com1 emacs foo.txt 3471 3472 `gdbserver' waits passively for the host GDB to communicate with 3473 it. 3474 3475 To use a TCP connection instead of a serial line: 3476 3477 target> gdbserver host:2345 emacs foo.txt 3478 3479 The only difference from the previous example is the first 3480 argument, specifying that you are communicating with the host GDB 3481 via TCP. The `host:2345' argument means that `gdbserver' is to 3482 expect a TCP connection from machine `host' to local TCP port 2345. 3483 (Currently, the `host' part is ignored.) You can choose any number 3484 you want for the port number as long as it does not conflict with 3485 any TCP ports already in use on the target system (for example, 3486 `23' is reserved for `telnet').(1) You must use the same port 3487 number with the host GDB `target remote' command. 3488 3489 On some targets, `gdbserver' can also attach to running programs. 3490 This is accomplished via the `--attach' argument. The syntax is: 3491 3492 target> gdbserver COMM --attach PID 3493 3494 PID is the process ID of a currently running process. It isn't 3495 necessary to point `gdbserver' at a binary for the running process. 3496 3497 You can debug processes by name instead of process ID if your 3498 target has the `pidof' utility: 3499 3500 target> gdbserver COMM --attach `pidof PROGRAM` 3501 3502 In case more than one copy of PROGRAM is running, or PROGRAM has 3503 multiple threads, most versions of `pidof' support the `-s' option 3504 to only return the first process ID. 3505 3506_On the host machine,_ 3507 first make sure you have the necessary symbol files. Load symbols 3508 for your application using the `file' command before you connect. 3509 Use `set sysroot' to locate target libraries (unless your GDB was 3510 compiled with the correct sysroot using `--with-system-root'). 3511 3512 The symbol file and target libraries must exactly match the 3513 executable and libraries on the target, with one exception: the 3514 files on the host system should not be stripped, even if the files 3515 on the target system are. Mismatched or missing files will lead 3516 to confusing results during debugging. On GNU/Linux targets, 3517 mismatched or missing files may also prevent `gdbserver' from 3518 debugging multi-threaded programs. 3519 3520 Connect to your target (*note Connecting to a Remote Target: 3521 Connecting.). For TCP connections, you must start up `gdbserver' 3522 prior to using the `target remote' command. Otherwise you may get 3523 an error whose text depends on the host system, but which usually 3524 looks something like `Connection refused'. You don't need to use 3525 the `load' command in GDB when using `gdbserver', since the 3526 program is already on the target. 3527 3528 352917.2.1 Monitor Commands for `gdbserver' 3530--------------------------------------- 3531 3532During a GDB session using `gdbserver', you can use the `monitor' 3533command to send special requests to `gdbserver'. Here are the 3534available commands; they are only of interest when debugging GDB or 3535`gdbserver'. 3536 3537`monitor help' 3538 List the available monitor commands. 3539 3540`monitor set debug 0' 3541`monitor set debug 1' 3542 Disable or enable general debugging messages. 3543 3544`monitor set remote-debug 0' 3545`monitor set remote-debug 1' 3546 Disable or enable specific debugging messages associated with the 3547 remote protocol (*note Remote Protocol::). 3548 3549 3550 ---------- Footnotes ---------- 3551 3552 (1) If you choose a port number that conflicts with another service, 3553`gdbserver' prints an error message and exits. 3554 3555 3556File: gdb.info, Node: Remote Configuration, Next: Remote Stub, Prev: Server, Up: Remote Debugging 3557 355817.3 Remote Configuration 3559========================= 3560 3561This section documents the configuration options available when 3562debugging remote programs. For the options related to the File I/O 3563extensions of the remote protocol, see *Note system-call-allowed: 3564system. 3565 3566`set remoteaddresssize BITS' 3567 Set the maximum size of address in a memory packet to the specified 3568 number of bits. GDB will mask off the address bits above that 3569 number, when it passes addresses to the remote target. The 3570 default value is the number of bits in the target's address. 3571 3572`show remoteaddresssize' 3573 Show the current value of remote address size in bits. 3574 3575`set remotebaud N' 3576 Set the baud rate for the remote serial I/O to N baud. The value 3577 is used to set the speed of the serial port used for debugging 3578 remote targets. 3579 3580`show remotebaud' 3581 Show the current speed of the remote connection. 3582 3583`set remotebreak' 3584 If set to on, GDB sends a `BREAK' signal to the remote when you 3585 type `Ctrl-c' to interrupt the program running on the remote. If 3586 set to off, GDB sends the `Ctrl-C' character instead. The default 3587 is off, since most remote systems expect to see `Ctrl-C' as the 3588 interrupt signal. 3589 3590`show remotebreak' 3591 Show whether GDB sends `BREAK' or `Ctrl-C' to interrupt the remote 3592 program. 3593 3594`set remoteflow on' 3595`set remoteflow off' 3596 Enable or disable hardware flow control (`RTS'/`CTS') on the 3597 serial port used to communicate to the remote target. 3598 3599`show remoteflow' 3600 Show the current setting of hardware flow control. 3601 3602`set remotelogbase BASE' 3603 Set the base (a.k.a. radix) of logging serial protocol 3604 communications to BASE. Supported values of BASE are: `ascii', 3605 `octal', and `hex'. The default is `ascii'. 3606 3607`show remotelogbase' 3608 Show the current setting of the radix for logging remote serial 3609 protocol. 3610 3611`set remotelogfile FILE' 3612 Record remote serial communications on the named FILE. The 3613 default is not to record at all. 3614 3615`show remotelogfile.' 3616 Show the current setting of the file name on which to record the 3617 serial communications. 3618 3619`set remotetimeout NUM' 3620 Set the timeout limit to wait for the remote target to respond to 3621 NUM seconds. The default is 2 seconds. 3622 3623`show remotetimeout' 3624 Show the current number of seconds to wait for the remote target 3625 responses. 3626 3627`set remote hardware-watchpoint-limit LIMIT' 3628`set remote hardware-breakpoint-limit LIMIT' 3629 Restrict GDB to using LIMIT remote hardware breakpoint or 3630 watchpoints. A limit of -1, the default, is treated as unlimited. 3631 3632 The GDB remote protocol autodetects the packets supported by your 3633debugging stub. If you need to override the autodetection, you can use 3634these commands to enable or disable individual packets. Each packet 3635can be set to `on' (the remote target supports this packet), `off' (the 3636remote target does not support this packet), or `auto' (detect remote 3637target support for this packet). They all default to `auto'. For more 3638information about each packet, see *Note Remote Protocol::. 3639 3640 During normal use, you should not have to use any of these commands. 3641If you do, that may be a bug in your remote debugging stub, or a bug in 3642GDB. You may want to report the problem to the GDB developers. 3643 3644 For each packet NAME, the command to enable or disable the packet is 3645`set remote NAME-packet'. The available settings are: 3646 3647Command Name Remote Packet Related Features 3648`fetch-register' `p' `info registers' 3649`set-register' `P' `set' 3650`binary-download' `X' `load', `set' 3651`read-aux-vector' `qXfer:auxv:read' `info auxv' 3652`symbol-lookup' `qSymbol' Detecting 3653 multiple threads 3654`verbose-resume' `vCont' Stepping or 3655 resuming multiple 3656 threads 3657`software-breakpoint'`Z0' `break' 3658`hardware-breakpoint'`Z1' `hbreak' 3659`write-watchpoint' `Z2' `watch' 3660`read-watchpoint' `Z3' `rwatch' 3661`access-watchpoint' `Z4' `awatch' 3662`target-features' `qXfer:features:read' `set architecture' 3663`library-info' `qXfer:libraries:read' `info 3664 sharedlibrary' 3665`memory-map' `qXfer:memory-map:read' `info mem' 3666`read-spu-object' `qXfer:spu:read' `info spu' 3667`write-spu-object' `qXfer:spu:write' `info spu' 3668`get-thread-local- `qGetTLSAddr' Displaying 3669storage-address' `__thread' 3670 variables 3671`supported-packets' `qSupported' Remote 3672 communications 3673 parameters 3674`pass-signals' `QPassSignals' `handle SIGNAL' 3675 3676 3677File: gdb.info, Node: Remote Stub, Prev: Remote Configuration, Up: Remote Debugging 3678 367917.4 Implementing a Remote Stub 3680=============================== 3681 3682The stub files provided with GDB implement the target side of the 3683communication protocol, and the GDB side is implemented in the GDB 3684source file `remote.c'. Normally, you can simply allow these 3685subroutines to communicate, and ignore the details. (If you're 3686implementing your own stub file, you can still ignore the details: start 3687with one of the existing stub files. `sparc-stub.c' is the best 3688organized, and therefore the easiest to read.) 3689 3690 To debug a program running on another machine (the debugging 3691"target" machine), you must first arrange for all the usual 3692prerequisites for the program to run by itself. For example, for a C 3693program, you need: 3694 3695 1. A startup routine to set up the C runtime environment; these 3696 usually have a name like `crt0'. The startup routine may be 3697 supplied by your hardware supplier, or you may have to write your 3698 own. 3699 3700 2. A C subroutine library to support your program's subroutine calls, 3701 notably managing input and output. 3702 3703 3. A way of getting your program to the other machine--for example, a 3704 download program. These are often supplied by the hardware 3705 manufacturer, but you may have to write your own from hardware 3706 documentation. 3707 3708 The next step is to arrange for your program to use a serial port to 3709communicate with the machine where GDB is running (the "host" machine). 3710In general terms, the scheme looks like this: 3711 3712_On the host,_ 3713 GDB already understands how to use this protocol; when everything 3714 else is set up, you can simply use the `target remote' command 3715 (*note Specifying a Debugging Target: Targets.). 3716 3717_On the target,_ 3718 you must link with your program a few special-purpose subroutines 3719 that implement the GDB remote serial protocol. The file 3720 containing these subroutines is called a "debugging stub". 3721 3722 On certain remote targets, you can use an auxiliary program 3723 `gdbserver' instead of linking a stub into your program. *Note 3724 Using the `gdbserver' Program: Server, for details. 3725 3726 The debugging stub is specific to the architecture of the remote 3727machine; for example, use `sparc-stub.c' to debug programs on SPARC 3728boards. 3729 3730 These working remote stubs are distributed with GDB: 3731 3732`i386-stub.c' 3733 For Intel 386 and compatible architectures. 3734 3735`m68k-stub.c' 3736 For Motorola 680x0 architectures. 3737 3738`sh-stub.c' 3739 For Renesas SH architectures. 3740 3741`sparc-stub.c' 3742 For SPARC architectures. 3743 3744`sparcl-stub.c' 3745 For Fujitsu SPARCLITE architectures. 3746 3747 3748 The `README' file in the GDB distribution may list other recently 3749added stubs. 3750 3751* Menu: 3752 3753* Stub Contents:: What the stub can do for you 3754* Bootstrapping:: What you must do for the stub 3755* Debug Session:: Putting it all together 3756 3757 3758File: gdb.info, Node: Stub Contents, Next: Bootstrapping, Up: Remote Stub 3759 376017.4.1 What the Stub Can Do for You 3761----------------------------------- 3762 3763The debugging stub for your architecture supplies these three 3764subroutines: 3765 3766`set_debug_traps' 3767 This routine arranges for `handle_exception' to run when your 3768 program stops. You must call this subroutine explicitly near the 3769 beginning of your program. 3770 3771`handle_exception' 3772 This is the central workhorse, but your program never calls it 3773 explicitly--the setup code arranges for `handle_exception' to run 3774 when a trap is triggered. 3775 3776 `handle_exception' takes control when your program stops during 3777 execution (for example, on a breakpoint), and mediates 3778 communications with GDB on the host machine. This is where the 3779 communications protocol is implemented; `handle_exception' acts as 3780 the GDB representative on the target machine. It begins by 3781 sending summary information on the state of your program, then 3782 continues to execute, retrieving and transmitting any information 3783 GDB needs, until you execute a GDB command that makes your program 3784 resume; at that point, `handle_exception' returns control to your 3785 own code on the target machine. 3786 3787`breakpoint' 3788 Use this auxiliary subroutine to make your program contain a 3789 breakpoint. Depending on the particular situation, this may be 3790 the only way for GDB to get control. For instance, if your target 3791 machine has some sort of interrupt button, you won't need to call 3792 this; pressing the interrupt button transfers control to 3793 `handle_exception'--in effect, to GDB. On some machines, simply 3794 receiving characters on the serial port may also trigger a trap; 3795 again, in that situation, you don't need to call `breakpoint' from 3796 your own program--simply running `target remote' from the host GDB 3797 session gets control. 3798 3799 Call `breakpoint' if none of these is true, or if you simply want 3800 to make certain your program stops at a predetermined point for the 3801 start of your debugging session. 3802 3803 3804File: gdb.info, Node: Bootstrapping, Next: Debug Session, Prev: Stub Contents, Up: Remote Stub 3805 380617.4.2 What You Must Do for the Stub 3807------------------------------------ 3808 3809The debugging stubs that come with GDB are set up for a particular chip 3810architecture, but they have no information about the rest of your 3811debugging target machine. 3812 3813 First of all you need to tell the stub how to communicate with the 3814serial port. 3815 3816`int getDebugChar()' 3817 Write this subroutine to read a single character from the serial 3818 port. It may be identical to `getchar' for your target system; a 3819 different name is used to allow you to distinguish the two if you 3820 wish. 3821 3822`void putDebugChar(int)' 3823 Write this subroutine to write a single character to the serial 3824 port. It may be identical to `putchar' for your target system; a 3825 different name is used to allow you to distinguish the two if you 3826 wish. 3827 3828 If you want GDB to be able to stop your program while it is running, 3829you need to use an interrupt-driven serial driver, and arrange for it 3830to stop when it receives a `^C' (`\003', the control-C character). 3831That is the character which GDB uses to tell the remote system to stop. 3832 3833 Getting the debugging target to return the proper status to GDB 3834probably requires changes to the standard stub; one quick and dirty way 3835is to just execute a breakpoint instruction (the "dirty" part is that 3836GDB reports a `SIGTRAP' instead of a `SIGINT'). 3837 3838 Other routines you need to supply are: 3839 3840`void exceptionHandler (int EXCEPTION_NUMBER, void *EXCEPTION_ADDRESS)' 3841 Write this function to install EXCEPTION_ADDRESS in the exception 3842 handling tables. You need to do this because the stub does not 3843 have any way of knowing what the exception handling tables on your 3844 target system are like (for example, the processor's table might 3845 be in ROM, containing entries which point to a table in RAM). 3846 EXCEPTION_NUMBER is the exception number which should be changed; 3847 its meaning is architecture-dependent (for example, different 3848 numbers might represent divide by zero, misaligned access, etc). 3849 When this exception occurs, control should be transferred directly 3850 to EXCEPTION_ADDRESS, and the processor state (stack, registers, 3851 and so on) should be just as it is when a processor exception 3852 occurs. So if you want to use a jump instruction to reach 3853 EXCEPTION_ADDRESS, it should be a simple jump, not a jump to 3854 subroutine. 3855 3856 For the 386, EXCEPTION_ADDRESS should be installed as an interrupt 3857 gate so that interrupts are masked while the handler runs. The 3858 gate should be at privilege level 0 (the most privileged level). 3859 The SPARC and 68k stubs are able to mask interrupts themselves 3860 without help from `exceptionHandler'. 3861 3862`void flush_i_cache()' 3863 On SPARC and SPARCLITE only, write this subroutine to flush the 3864 instruction cache, if any, on your target machine. If there is no 3865 instruction cache, this subroutine may be a no-op. 3866 3867 On target machines that have instruction caches, GDB requires this 3868 function to make certain that the state of your program is stable. 3869 3870You must also make sure this library routine is available: 3871 3872`void *memset(void *, int, int)' 3873 This is the standard library function `memset' that sets an area of 3874 memory to a known value. If you have one of the free versions of 3875 `libc.a', `memset' can be found there; otherwise, you must either 3876 obtain it from your hardware manufacturer, or write your own. 3877 3878 If you do not use the GNU C compiler, you may need other standard 3879library subroutines as well; this varies from one stub to another, but 3880in general the stubs are likely to use any of the common library 3881subroutines which `GCC' generates as inline code. 3882 3883 3884File: gdb.info, Node: Debug Session, Prev: Bootstrapping, Up: Remote Stub 3885 388617.4.3 Putting it All Together 3887------------------------------ 3888 3889In summary, when your program is ready to debug, you must follow these 3890steps. 3891 3892 1. Make sure you have defined the supporting low-level routines 3893 (*note What You Must Do for the Stub: Bootstrapping.): 3894 `getDebugChar', `putDebugChar', 3895 `flush_i_cache', `memset', `exceptionHandler'. 3896 3897 2. Insert these lines near the top of your program: 3898 3899 set_debug_traps(); 3900 breakpoint(); 3901 3902 3. For the 680x0 stub only, you need to provide a variable called 3903 `exceptionHook'. Normally you just use: 3904 3905 void (*exceptionHook)() = 0; 3906 3907 but if before calling `set_debug_traps', you set it to point to a 3908 function in your program, that function is called when `GDB' 3909 continues after stopping on a trap (for example, bus error). The 3910 function indicated by `exceptionHook' is called with one 3911 parameter: an `int' which is the exception number. 3912 3913 4. Compile and link together: your program, the GDB debugging stub for 3914 your target architecture, and the supporting subroutines. 3915 3916 5. Make sure you have a serial connection between your target machine 3917 and the GDB host, and identify the serial port on the host. 3918 3919 6. Download your program to your target machine (or get it there by 3920 whatever means the manufacturer provides), and start it. 3921 3922 7. Start GDB on the host, and connect to the target (*note Connecting 3923 to a Remote Target: Connecting.). 3924 3925 3926 3927File: gdb.info, Node: Configurations, Next: Controlling GDB, Prev: Remote Debugging, Up: Top 3928 392918 Configuration-Specific Information 3930************************************* 3931 3932While nearly all GDB commands are available for all native and cross 3933versions of the debugger, there are some exceptions. This chapter 3934describes things that are only available in certain configurations. 3935 3936 There are three major categories of configurations: native 3937configurations, where the host and target are the same, embedded 3938operating system configurations, which are usually the same for several 3939different processor architectures, and bare embedded processors, which 3940are quite different from each other. 3941 3942* Menu: 3943 3944* Native:: 3945* Embedded OS:: 3946* Embedded Processors:: 3947* Architectures:: 3948 3949 3950File: gdb.info, Node: Native, Next: Embedded OS, Up: Configurations 3951 395218.1 Native 3953=========== 3954 3955This section describes details specific to particular native 3956configurations. 3957 3958* Menu: 3959 3960* HP-UX:: HP-UX 3961* BSD libkvm Interface:: Debugging BSD kernel memory images 3962* SVR4 Process Information:: SVR4 process information 3963* DJGPP Native:: Features specific to the DJGPP port 3964* Cygwin Native:: Features specific to the Cygwin port 3965* Hurd Native:: Features specific to GNU Hurd 3966* Neutrino:: Features specific to QNX Neutrino 3967 3968 3969File: gdb.info, Node: HP-UX, Next: BSD libkvm Interface, Up: Native 3970 397118.1.1 HP-UX 3972------------ 3973 3974On HP-UX systems, if you refer to a function or variable name that 3975begins with a dollar sign, GDB searches for a user or system name 3976first, before it searches for a convenience variable. 3977 3978 3979File: gdb.info, Node: BSD libkvm Interface, Next: SVR4 Process Information, Prev: HP-UX, Up: Native 3980 398118.1.2 BSD libkvm Interface 3982--------------------------- 3983 3984BSD-derived systems (FreeBSD/NetBSD/OpenBSD) have a kernel memory 3985interface that provides a uniform interface for accessing kernel virtual 3986memory images, including live systems and crash dumps. GDB uses this 3987interface to allow you to debug live kernels and kernel crash dumps on 3988many native BSD configurations. This is implemented as a special `kvm' 3989debugging target. For debugging a live system, load the currently 3990running kernel into GDB and connect to the `kvm' target: 3991 3992 (gdb) target kvm 3993 3994 For debugging crash dumps, provide the file name of the crash dump 3995as an argument: 3996 3997 (gdb) target kvm /var/crash/bsd.0 3998 3999 Once connected to the `kvm' target, the following commands are 4000available: 4001 4002`kvm pcb' 4003 Set current context from the "Process Control Block" (PCB) address. 4004 4005`kvm proc' 4006 Set current context from proc address. This command isn't 4007 available on modern FreeBSD systems. 4008 4009 4010File: gdb.info, Node: SVR4 Process Information, Next: DJGPP Native, Prev: BSD libkvm Interface, Up: Native 4011 401218.1.3 SVR4 Process Information 4013------------------------------- 4014 4015Many versions of SVR4 and compatible systems provide a facility called 4016`/proc' that can be used to examine the image of a running process 4017using file-system subroutines. If GDB is configured for an operating 4018system with this facility, the command `info proc' is available to 4019report information about the process running your program, or about any 4020process running on your system. `info proc' works only on SVR4 systems 4021that include the `procfs' code. This includes, as of this writing, 4022GNU/Linux, OSF/1 (Digital Unix), Solaris, Irix, and Unixware, but not 4023HP-UX, for example. 4024 4025`info proc' 4026`info proc PROCESS-ID' 4027 Summarize available information about any running process. If a 4028 process ID is specified by PROCESS-ID, display information about 4029 that process; otherwise display information about the program being 4030 debugged. The summary includes the debugged process ID, the 4031 command line used to invoke it, its current working directory, and 4032 its executable file's absolute file name. 4033 4034 On some systems, PROCESS-ID can be of the form `[PID]/TID' which 4035 specifies a certain thread ID within a process. If the optional 4036 PID part is missing, it means a thread from the process being 4037 debugged (the leading `/' still needs to be present, or else GDB 4038 will interpret the number as a process ID rather than a thread ID). 4039 4040`info proc mappings' 4041 Report the memory address space ranges accessible in the program, 4042 with information on whether the process has read, write, or 4043 execute access rights to each range. On GNU/Linux systems, each 4044 memory range includes the object file which is mapped to that 4045 range, instead of the memory access rights to that range. 4046 4047`info proc stat' 4048`info proc status' 4049 These subcommands are specific to GNU/Linux systems. They show 4050 the process-related information, including the user ID and group 4051 ID; how many threads are there in the process; its virtual memory 4052 usage; the signals that are pending, blocked, and ignored; its 4053 TTY; its consumption of system and user time; its stack size; its 4054 `nice' value; etc. For more information, see the `proc' man page 4055 (type `man 5 proc' from your shell prompt). 4056 4057`info proc all' 4058 Show all the information about the process described under all of 4059 the above `info proc' subcommands. 4060 4061`set procfs-trace' 4062 This command enables and disables tracing of `procfs' API calls. 4063 4064`show procfs-trace' 4065 Show the current state of `procfs' API call tracing. 4066 4067`set procfs-file FILE' 4068 Tell GDB to write `procfs' API trace to the named FILE. GDB 4069 appends the trace info to the previous contents of the file. The 4070 default is to display the trace on the standard output. 4071 4072`show procfs-file' 4073 Show the file to which `procfs' API trace is written. 4074 4075`proc-trace-entry' 4076`proc-trace-exit' 4077`proc-untrace-entry' 4078`proc-untrace-exit' 4079 These commands enable and disable tracing of entries into and exits 4080 from the `syscall' interface. 4081 4082`info pidlist' 4083 For QNX Neutrino only, this command displays the list of all the 4084 processes and all the threads within each process. 4085 4086`info meminfo' 4087 For QNX Neutrino only, this command displays the list of all 4088 mapinfos. 4089 4090 4091File: gdb.info, Node: DJGPP Native, Next: Cygwin Native, Prev: SVR4 Process Information, Up: Native 4092 409318.1.4 Features for Debugging DJGPP Programs 4094-------------------------------------------- 4095 4096DJGPP is a port of the GNU development tools to MS-DOS and MS-Windows. 4097DJGPP programs are 32-bit protected-mode programs that use the "DPMI" 4098(DOS Protected-Mode Interface) API to run on top of real-mode DOS 4099systems and their emulations. 4100 4101 GDB supports native debugging of DJGPP programs, and defines a few 4102commands specific to the DJGPP port. This subsection describes those 4103commands. 4104 4105`info dos' 4106 This is a prefix of DJGPP-specific commands which print 4107 information about the target system and important OS structures. 4108 4109`info dos sysinfo' 4110 This command displays assorted information about the underlying 4111 platform: the CPU type and features, the OS version and flavor, the 4112 DPMI version, and the available conventional and DPMI memory. 4113 4114`info dos gdt' 4115`info dos ldt' 4116`info dos idt' 4117 These 3 commands display entries from, respectively, Global, Local, 4118 and Interrupt Descriptor Tables (GDT, LDT, and IDT). The 4119 descriptor tables are data structures which store a descriptor for 4120 each segment that is currently in use. The segment's selector is 4121 an index into a descriptor table; the table entry for that index 4122 holds the descriptor's base address and limit, and its attributes 4123 and access rights. 4124 4125 A typical DJGPP program uses 3 segments: a code segment, a data 4126 segment (used for both data and the stack), and a DOS segment 4127 (which allows access to DOS/BIOS data structures and absolute 4128 addresses in conventional memory). However, the DPMI host will 4129 usually define additional segments in order to support the DPMI 4130 environment. 4131 4132 These commands allow to display entries from the descriptor tables. 4133 Without an argument, all entries from the specified table are 4134 displayed. An argument, which should be an integer expression, 4135 means display a single entry whose index is given by the argument. 4136 For example, here's a convenient way to display information about 4137 the debugged program's data segment: 4138 4139 `(gdb) info dos ldt $ds' 4140 `0x13f: base=0x11970000 limit=0x0009ffff 32-Bit Data (Read/Write, Exp-up)' 4141 4142 4143 This comes in handy when you want to see whether a pointer is 4144 outside the data segment's limit (i.e. "garbled"). 4145 4146`info dos pde' 4147`info dos pte' 4148 These two commands display entries from, respectively, the Page 4149 Directory and the Page Tables. Page Directories and Page Tables 4150 are data structures which control how virtual memory addresses are 4151 mapped into physical addresses. A Page Table includes an entry 4152 for every page of memory that is mapped into the program's address 4153 space; there may be several Page Tables, each one holding up to 4154 4096 entries. A Page Directory has up to 4096 entries, one each 4155 for every Page Table that is currently in use. 4156 4157 Without an argument, `info dos pde' displays the entire Page 4158 Directory, and `info dos pte' displays all the entries in all of 4159 the Page Tables. An argument, an integer expression, given to the 4160 `info dos pde' command means display only that entry from the Page 4161 Directory table. An argument given to the `info dos pte' command 4162 means display entries from a single Page Table, the one pointed to 4163 by the specified entry in the Page Directory. 4164 4165 These commands are useful when your program uses "DMA" (Direct 4166 Memory Access), which needs physical addresses to program the DMA 4167 controller. 4168 4169 These commands are supported only with some DPMI servers. 4170 4171`info dos address-pte ADDR' 4172 This command displays the Page Table entry for a specified linear 4173 address. The argument ADDR is a linear address which should 4174 already have the appropriate segment's base address added to it, 4175 because this command accepts addresses which may belong to _any_ 4176 segment. For example, here's how to display the Page Table entry 4177 for the page where a variable `i' is stored: 4178 4179 `(gdb) info dos address-pte __djgpp_base_address + (char *)&i' 4180 `Page Table entry for address 0x11a00d30:' 4181 `Base=0x02698000 Dirty Acc. Not-Cached Write-Back Usr Read-Write +0xd30' 4182 4183 4184 This says that `i' is stored at offset `0xd30' from the page whose 4185 physical base address is `0x02698000', and shows all the 4186 attributes of that page. 4187 4188 Note that you must cast the addresses of variables to a `char *', 4189 since otherwise the value of `__djgpp_base_address', the base 4190 address of all variables and functions in a DJGPP program, will be 4191 added using the rules of C pointer arithmetics: if `i' is declared 4192 an `int', GDB will add 4 times the value of `__djgpp_base_address' 4193 to the address of `i'. 4194 4195 Here's another example, it displays the Page Table entry for the 4196 transfer buffer: 4197 4198 `(gdb) info dos address-pte *((unsigned *)&_go32_info_block + 3)' 4199 `Page Table entry for address 0x29110:' 4200 `Base=0x00029000 Dirty Acc. Not-Cached Write-Back Usr Read-Write +0x110' 4201 4202 4203 (The `+ 3' offset is because the transfer buffer's address is the 4204 3rd member of the `_go32_info_block' structure.) The output 4205 clearly shows that this DPMI server maps the addresses in 4206 conventional memory 1:1, i.e. the physical (`0x00029000' + 4207 `0x110') and linear (`0x29110') addresses are identical. 4208 4209 This command is supported only with some DPMI servers. 4210 4211 In addition to native debugging, the DJGPP port supports remote 4212debugging via a serial data link. The following commands are specific 4213to remote serial debugging in the DJGPP port of GDB. 4214 4215`set com1base ADDR' 4216 This command sets the base I/O port address of the `COM1' serial 4217 port. 4218 4219`set com1irq IRQ' 4220 This command sets the "Interrupt Request" (`IRQ') line to use for 4221 the `COM1' serial port. 4222 4223 There are similar commands `set com2base', `set com3irq', etc. for 4224 setting the port address and the `IRQ' lines for the other 3 COM 4225 ports. 4226 4227 The related commands `show com1base', `show com1irq' etc. display 4228 the current settings of the base address and the `IRQ' lines used 4229 by the COM ports. 4230 4231`info serial' 4232 This command prints the status of the 4 DOS serial ports. For each 4233 port, it prints whether it's active or not, its I/O base address 4234 and IRQ number, whether it uses a 16550-style FIFO, its baudrate, 4235 and the counts of various errors encountered so far. 4236 4237 4238File: gdb.info, Node: Cygwin Native, Next: Hurd Native, Prev: DJGPP Native, Up: Native 4239 424018.1.5 Features for Debugging MS Windows PE Executables 4241------------------------------------------------------- 4242 4243GDB supports native debugging of MS Windows programs, including DLLs 4244with and without symbolic debugging information. There are various 4245additional Cygwin-specific commands, described in this section. 4246Working with DLLs that have no debugging symbols is described in *Note 4247Non-debug DLL Symbols::. 4248 4249`info w32' 4250 This is a prefix of MS Windows-specific commands which print 4251 information about the target system and important OS structures. 4252 4253`info w32 selector' 4254 This command displays information returned by the Win32 API 4255 `GetThreadSelectorEntry' function. It takes an optional argument 4256 that is evaluated to a long value to give the information about 4257 this given selector. Without argument, this command displays 4258 information about the six segment registers. 4259 4260`info dll' 4261 This is a Cygwin-specific alias of `info shared'. 4262 4263`dll-symbols' 4264 This command loads symbols from a dll similarly to add-sym command 4265 but without the need to specify a base address. 4266 4267`set cygwin-exceptions MODE' 4268 If MODE is `on', GDB will break on exceptions that happen inside 4269 the Cygwin DLL. If MODE is `off', GDB will delay recognition of 4270 exceptions, and may ignore some exceptions which seem to be caused 4271 by internal Cygwin DLL "bookkeeping". This option is meant 4272 primarily for debugging the Cygwin DLL itself; the default value 4273 is `off' to avoid annoying GDB users with false `SIGSEGV' signals. 4274 4275`show cygwin-exceptions' 4276 Displays whether GDB will break on exceptions that happen inside 4277 the Cygwin DLL itself. 4278 4279`set new-console MODE' 4280 If MODE is `on' the debuggee will be started in a new console on 4281 next start. If MODE is `off'i, the debuggee will be started in 4282 the same console as the debugger. 4283 4284`show new-console' 4285 Displays whether a new console is used when the debuggee is 4286 started. 4287 4288`set new-group MODE' 4289 This boolean value controls whether the debuggee should start a 4290 new group or stay in the same group as the debugger. This affects 4291 the way the Windows OS handles `Ctrl-C'. 4292 4293`show new-group' 4294 Displays current value of new-group boolean. 4295 4296`set debugevents' 4297 This boolean value adds debug output concerning kernel events 4298 related to the debuggee seen by the debugger. This includes 4299 events that signal thread and process creation and exit, DLL 4300 loading and unloading, console interrupts, and debugging messages 4301 produced by the Windows `OutputDebugString' API call. 4302 4303`set debugexec' 4304 This boolean value adds debug output concerning execute events 4305 (such as resume thread) seen by the debugger. 4306 4307`set debugexceptions' 4308 This boolean value adds debug output concerning exceptions in the 4309 debuggee seen by the debugger. 4310 4311`set debugmemory' 4312 This boolean value adds debug output concerning debuggee memory 4313 reads and writes by the debugger. 4314 4315`set shell' 4316 This boolean values specifies whether the debuggee is called via a 4317 shell or directly (default value is on). 4318 4319`show shell' 4320 Displays if the debuggee will be started with a shell. 4321 4322 4323* Menu: 4324 4325* Non-debug DLL Symbols:: Support for DLLs without debugging symbols 4326 4327 4328File: gdb.info, Node: Non-debug DLL Symbols, Up: Cygwin Native 4329 433018.1.5.1 Support for DLLs without Debugging Symbols 4331................................................... 4332 4333Very often on windows, some of the DLLs that your program relies on do 4334not include symbolic debugging information (for example, 4335`kernel32.dll'). When GDB doesn't recognize any debugging symbols in a 4336DLL, it relies on the minimal amount of symbolic information contained 4337in the DLL's export table. This section describes working with such 4338symbols, known internally to GDB as "minimal symbols". 4339 4340 Note that before the debugged program has started execution, no DLLs 4341will have been loaded. The easiest way around this problem is simply to 4342start the program -- either by setting a breakpoint or letting the 4343program run once to completion. It is also possible to force GDB to 4344load a particular DLL before starting the executable -- see the shared 4345library information in *Note Files::, or the `dll-symbols' command in 4346*Note Cygwin Native::. Currently, explicitly loading symbols from a 4347DLL with no debugging information will cause the symbol names to be 4348duplicated in GDB's lookup table, which may adversely affect symbol 4349lookup performance. 4350 435118.1.5.2 DLL Name Prefixes 4352.......................... 4353 4354In keeping with the naming conventions used by the Microsoft debugging 4355tools, DLL export symbols are made available with a prefix based on the 4356DLL name, for instance `KERNEL32!CreateFileA'. The plain name is also 4357entered into the symbol table, so `CreateFileA' is often sufficient. In 4358some cases there will be name clashes within a program (particularly if 4359the executable itself includes full debugging symbols) necessitating 4360the use of the fully qualified name when referring to the contents of 4361the DLL. Use single-quotes around the name to avoid the exclamation 4362mark ("!") being interpreted as a language operator. 4363 4364 Note that the internal name of the DLL may be all upper-case, even 4365though the file name of the DLL is lower-case, or vice-versa. Since 4366symbols within GDB are _case-sensitive_ this may cause some confusion. 4367If in doubt, try the `info functions' and `info variables' commands or 4368even `maint print msymbols' (*note Symbols::). Here's an example: 4369 4370 (gdb) info function CreateFileA 4371 All functions matching regular expression "CreateFileA": 4372 4373 Non-debugging symbols: 4374 0x77e885f4 CreateFileA 4375 0x77e885f4 KERNEL32!CreateFileA 4376 4377 (gdb) info function ! 4378 All functions matching regular expression "!": 4379 4380 Non-debugging symbols: 4381 0x6100114c cygwin1!__assert 4382 0x61004034 cygwin1!_dll_crt0@0 4383 0x61004240 cygwin1!dll_crt0(per_process *) 4384 [etc...] 4385 438618.1.5.3 Working with Minimal Symbols 4387..................................... 4388 4389Symbols extracted from a DLL's export table do not contain very much 4390type information. All that GDB can do is guess whether a symbol refers 4391to a function or variable depending on the linker section that contains 4392the symbol. Also note that the actual contents of the memory contained 4393in a DLL are not available unless the program is running. This means 4394that you cannot examine the contents of a variable or disassemble a 4395function within a DLL without a running program. 4396 4397 Variables are generally treated as pointers and dereferenced 4398automatically. For this reason, it is often necessary to prefix a 4399variable name with the address-of operator ("&") and provide explicit 4400type information in the command. Here's an example of the type of 4401problem: 4402 4403 (gdb) print 'cygwin1!__argv' 4404 $1 = 268572168 4405 4406 (gdb) x 'cygwin1!__argv' 4407 0x10021610: "\230y\"" 4408 4409 And two possible solutions: 4410 4411 (gdb) print ((char **)'cygwin1!__argv')[0] 4412 $2 = 0x22fd98 "/cygdrive/c/mydirectory/myprogram" 4413 4414 (gdb) x/2x &'cygwin1!__argv' 4415 0x610c0aa8 <cygwin1!__argv>: 0x10021608 0x00000000 4416 (gdb) x/x 0x10021608 4417 0x10021608: 0x0022fd98 4418 (gdb) x/s 0x0022fd98 4419 0x22fd98: "/cygdrive/c/mydirectory/myprogram" 4420 4421 Setting a break point within a DLL is possible even before the 4422program starts execution. However, under these circumstances, GDB can't 4423examine the initial instructions of the function in order to skip the 4424function's frame set-up code. You can work around this by using "*&" to 4425set the breakpoint at a raw memory address: 4426 4427 (gdb) break *&'python22!PyOS_Readline' 4428 Breakpoint 1 at 0x1e04eff0 4429 4430 The author of these extensions is not entirely convinced that 4431setting a break point within a shared DLL like `kernel32.dll' is 4432completely safe. 4433 4434 4435File: gdb.info, Node: Hurd Native, Next: Neutrino, Prev: Cygwin Native, Up: Native 4436 443718.1.6 Commands Specific to GNU Hurd Systems 4438-------------------------------------------- 4439 4440This subsection describes GDB commands specific to the GNU Hurd native 4441debugging. 4442 4443`set signals' 4444`set sigs' 4445 This command toggles the state of inferior signal interception by 4446 GDB. Mach exceptions, such as breakpoint traps, are not affected 4447 by this command. `sigs' is a shorthand alias for `signals'. 4448 4449`show signals' 4450`show sigs' 4451 Show the current state of intercepting inferior's signals. 4452 4453`set signal-thread' 4454`set sigthread' 4455 This command tells GDB which thread is the `libc' signal thread. 4456 That thread is run when a signal is delivered to a running 4457 process. `set sigthread' is the shorthand alias of `set 4458 signal-thread'. 4459 4460`show signal-thread' 4461`show sigthread' 4462 These two commands show which thread will run when the inferior is 4463 delivered a signal. 4464 4465`set stopped' 4466 This commands tells GDB that the inferior process is stopped, as 4467 with the `SIGSTOP' signal. The stopped process can be continued 4468 by delivering a signal to it. 4469 4470`show stopped' 4471 This command shows whether GDB thinks the debuggee is stopped. 4472 4473`set exceptions' 4474 Use this command to turn off trapping of exceptions in the 4475 inferior. When exception trapping is off, neither breakpoints nor 4476 single-stepping will work. To restore the default, set exception 4477 trapping on. 4478 4479`show exceptions' 4480 Show the current state of trapping exceptions in the inferior. 4481 4482`set task pause' 4483 This command toggles task suspension when GDB has control. 4484 Setting it to on takes effect immediately, and the task is 4485 suspended whenever GDB gets control. Setting it to off will take 4486 effect the next time the inferior is continued. If this option is 4487 set to off, you can use `set thread default pause on' or `set 4488 thread pause on' (see below) to pause individual threads. 4489 4490`show task pause' 4491 Show the current state of task suspension. 4492 4493`set task detach-suspend-count' 4494 This command sets the suspend count the task will be left with when 4495 GDB detaches from it. 4496 4497`show task detach-suspend-count' 4498 Show the suspend count the task will be left with when detaching. 4499 4500`set task exception-port' 4501`set task excp' 4502 This command sets the task exception port to which GDB will 4503 forward exceptions. The argument should be the value of the "send 4504 rights" of the task. `set task excp' is a shorthand alias. 4505 4506`set noninvasive' 4507 This command switches GDB to a mode that is the least invasive as 4508 far as interfering with the inferior is concerned. This is the 4509 same as using `set task pause', `set exceptions', and `set 4510 signals' to values opposite to the defaults. 4511 4512`info send-rights' 4513`info receive-rights' 4514`info port-rights' 4515`info port-sets' 4516`info dead-names' 4517`info ports' 4518`info psets' 4519 These commands display information about, respectively, send 4520 rights, receive rights, port rights, port sets, and dead names of 4521 a task. There are also shorthand aliases: `info ports' for `info 4522 port-rights' and `info psets' for `info port-sets'. 4523 4524`set thread pause' 4525 This command toggles current thread suspension when GDB has 4526 control. Setting it to on takes effect immediately, and the 4527 current thread is suspended whenever GDB gets control. Setting it 4528 to off will take effect the next time the inferior is continued. 4529 Normally, this command has no effect, since when GDB has control, 4530 the whole task is suspended. However, if you used `set task pause 4531 off' (see above), this command comes in handy to suspend only the 4532 current thread. 4533 4534`show thread pause' 4535 This command shows the state of current thread suspension. 4536 4537`set thread run' 4538 This command sets whether the current thread is allowed to run. 4539 4540`show thread run' 4541 Show whether the current thread is allowed to run. 4542 4543`set thread detach-suspend-count' 4544 This command sets the suspend count GDB will leave on a thread 4545 when detaching. This number is relative to the suspend count 4546 found by GDB when it notices the thread; use `set thread 4547 takeover-suspend-count' to force it to an absolute value. 4548 4549`show thread detach-suspend-count' 4550 Show the suspend count GDB will leave on the thread when detaching. 4551 4552`set thread exception-port' 4553`set thread excp' 4554 Set the thread exception port to which to forward exceptions. This 4555 overrides the port set by `set task exception-port' (see above). 4556 `set thread excp' is the shorthand alias. 4557 4558`set thread takeover-suspend-count' 4559 Normally, GDB's thread suspend counts are relative to the value 4560 GDB finds when it notices each thread. This command changes the 4561 suspend counts to be absolute instead. 4562 4563`set thread default' 4564`show thread default' 4565 Each of the above `set thread' commands has a `set thread default' 4566 counterpart (e.g., `set thread default pause', `set thread default 4567 exception-port', etc.). The `thread default' variety of commands 4568 sets the default thread properties for all threads; you can then 4569 change the properties of individual threads with the non-default 4570 commands. 4571 4572 4573File: gdb.info, Node: Neutrino, Prev: Hurd Native, Up: Native 4574 457518.1.7 QNX Neutrino 4576------------------- 4577 4578GDB provides the following commands specific to the QNX Neutrino target: 4579 4580`set debug nto-debug' 4581 When set to on, enables debugging messages specific to the QNX 4582 Neutrino support. 4583 4584`show debug nto-debug' 4585 Show the current state of QNX Neutrino messages. 4586 4587 4588File: gdb.info, Node: Embedded OS, Next: Embedded Processors, Prev: Native, Up: Configurations 4589 459018.2 Embedded Operating Systems 4591=============================== 4592 4593This section describes configurations involving the debugging of 4594embedded operating systems that are available for several different 4595architectures. 4596 4597* Menu: 4598 4599* VxWorks:: Using GDB with VxWorks 4600 4601 GDB includes the ability to debug programs running on various 4602real-time operating systems. 4603 4604 4605File: gdb.info, Node: VxWorks, Up: Embedded OS 4606 460718.2.1 Using GDB with VxWorks 4608----------------------------- 4609 4610`target vxworks MACHINENAME' 4611 A VxWorks system, attached via TCP/IP. The argument MACHINENAME 4612 is the target system's machine name or IP address. 4613 4614 4615 On VxWorks, `load' links FILENAME dynamically on the current target 4616system as well as adding its symbols in GDB. 4617 4618 GDB enables developers to spawn and debug tasks running on networked 4619VxWorks targets from a Unix host. Already-running tasks spawned from 4620the VxWorks shell can also be debugged. GDB uses code that runs on 4621both the Unix host and on the VxWorks target. The program `gdb' is 4622installed and executed on the Unix host. (It may be installed with the 4623name `vxgdb', to distinguish it from a GDB for debugging programs on 4624the host itself.) 4625 4626`VxWorks-timeout ARGS' 4627 All VxWorks-based targets now support the option `vxworks-timeout'. 4628 This option is set by the user, and ARGS represents the number of 4629 seconds GDB waits for responses to rpc's. You might use this if 4630 your VxWorks target is a slow software simulator or is on the far 4631 side of a thin network line. 4632 4633 The following information on connecting to VxWorks was current when 4634this manual was produced; newer releases of VxWorks may use revised 4635procedures. 4636 4637 To use GDB with VxWorks, you must rebuild your VxWorks kernel to 4638include the remote debugging interface routines in the VxWorks library 4639`rdb.a'. To do this, define `INCLUDE_RDB' in the VxWorks configuration 4640file `configAll.h' and rebuild your VxWorks kernel. The resulting 4641kernel contains `rdb.a', and spawns the source debugging task 4642`tRdbTask' when VxWorks is booted. For more information on configuring 4643and remaking VxWorks, see the manufacturer's manual. 4644 4645 Once you have included `rdb.a' in your VxWorks system image and set 4646your Unix execution search path to find GDB, you are ready to run GDB. 4647From your Unix host, run `gdb' (or `vxgdb', depending on your 4648installation). 4649 4650 GDB comes up showing the prompt: 4651 4652 (vxgdb) 4653 4654* Menu: 4655 4656* VxWorks Connection:: Connecting to VxWorks 4657* VxWorks Download:: VxWorks download 4658* VxWorks Attach:: Running tasks 4659 4660 4661File: gdb.info, Node: VxWorks Connection, Next: VxWorks Download, Up: VxWorks 4662 466318.2.1.1 Connecting to VxWorks 4664.............................. 4665 4666The GDB command `target' lets you connect to a VxWorks target on the 4667network. To connect to a target whose host name is "`tt'", type: 4668 4669 (vxgdb) target vxworks tt 4670 4671 GDB displays messages like these: 4672 4673 Attaching remote machine across net... 4674 Connected to tt. 4675 4676 GDB then attempts to read the symbol tables of any object modules 4677loaded into the VxWorks target since it was last booted. GDB locates 4678these files by searching the directories listed in the command search 4679path (*note Your Program's Environment: Environment.); if it fails to 4680find an object file, it displays a message such as: 4681 4682 prog.o: No such file or directory. 4683 4684 When this happens, add the appropriate directory to the search path 4685with the GDB command `path', and execute the `target' command again. 4686 4687 4688File: gdb.info, Node: VxWorks Download, Next: VxWorks Attach, Prev: VxWorks Connection, Up: VxWorks 4689 469018.2.1.2 VxWorks Download 4691......................... 4692 4693If you have connected to the VxWorks target and you want to debug an 4694object that has not yet been loaded, you can use the GDB `load' command 4695to download a file from Unix to VxWorks incrementally. The object file 4696given as an argument to the `load' command is actually opened twice: 4697first by the VxWorks target in order to download the code, then by GDB 4698in order to read the symbol table. This can lead to problems if the 4699current working directories on the two systems differ. If both systems 4700have NFS mounted the same filesystems, you can avoid these problems by 4701using absolute paths. Otherwise, it is simplest to set the working 4702directory on both systems to the directory in which the object file 4703resides, and then to reference the file by its name, without any path. 4704For instance, a program `prog.o' may reside in `VXPATH/vw/demo/rdb' in 4705VxWorks and in `HOSTPATH/vw/demo/rdb' on the host. To load this 4706program, type this on VxWorks: 4707 4708 -> cd "VXPATH/vw/demo/rdb" 4709 4710Then, in GDB, type: 4711 4712 (vxgdb) cd HOSTPATH/vw/demo/rdb 4713 (vxgdb) load prog.o 4714 4715 GDB displays a response similar to this: 4716 4717 Reading symbol data from wherever/vw/demo/rdb/prog.o... done. 4718 4719 You can also use the `load' command to reload an object module after 4720editing and recompiling the corresponding source file. Note that this 4721makes GDB delete all currently-defined breakpoints, auto-displays, and 4722convenience variables, and to clear the value history. (This is 4723necessary in order to preserve the integrity of debugger's data 4724structures that reference the target system's symbol table.) 4725 4726 4727File: gdb.info, Node: VxWorks Attach, Prev: VxWorks Download, Up: VxWorks 4728 472918.2.1.3 Running Tasks 4730...................... 4731 4732You can also attach to an existing task using the `attach' command as 4733follows: 4734 4735 (vxgdb) attach TASK 4736 4737where TASK is the VxWorks hexadecimal task ID. The task can be running 4738or suspended when you attach to it. Running tasks are suspended at the 4739time of attachment. 4740 4741 4742File: gdb.info, Node: Embedded Processors, Next: Architectures, Prev: Embedded OS, Up: Configurations 4743 474418.3 Embedded Processors 4745======================== 4746 4747This section goes into details specific to particular embedded 4748configurations. 4749 4750 Whenever a specific embedded processor has a simulator, GDB allows 4751to send an arbitrary command to the simulator. 4752 4753`sim COMMAND' 4754 Send an arbitrary COMMAND string to the simulator. Consult the 4755 documentation for the specific simulator in use for information 4756 about acceptable commands. 4757 4758* Menu: 4759 4760* ARM:: ARM RDI 4761* M32R/D:: Renesas M32R/D 4762* M68K:: Motorola M68K 4763* MIPS Embedded:: MIPS Embedded 4764* OpenRISC 1000:: OpenRisc 1000 4765* PA:: HP PA Embedded 4766* PowerPC:: PowerPC 4767* Sparclet:: Tsqware Sparclet 4768* Sparclite:: Fujitsu Sparclite 4769* Z8000:: Zilog Z8000 4770* AVR:: Atmel AVR 4771* CRIS:: CRIS 4772* Super-H:: Renesas Super-H 4773 4774 4775File: gdb.info, Node: ARM, Next: M32R/D, Up: Embedded Processors 4776 477718.3.1 ARM 4778---------- 4779 4780`target rdi DEV' 4781 ARM Angel monitor, via RDI library interface to ADP protocol. You 4782 may use this target to communicate with both boards running the 4783 Angel monitor, or with the EmbeddedICE JTAG debug device. 4784 4785`target rdp DEV' 4786 ARM Demon monitor. 4787 4788 4789 GDB provides the following ARM-specific commands: 4790 4791`set arm disassembler' 4792 This commands selects from a list of disassembly styles. The 4793 `"std"' style is the standard style. 4794 4795`show arm disassembler' 4796 Show the current disassembly style. 4797 4798`set arm apcs32' 4799 This command toggles ARM operation mode between 32-bit and 26-bit. 4800 4801`show arm apcs32' 4802 Display the current usage of the ARM 32-bit mode. 4803 4804`set arm fpu FPUTYPE' 4805 This command sets the ARM floating-point unit (FPU) type. The 4806 argument FPUTYPE can be one of these: 4807 4808 `auto' 4809 Determine the FPU type by querying the OS ABI. 4810 4811 `softfpa' 4812 Software FPU, with mixed-endian doubles on little-endian ARM 4813 processors. 4814 4815 `fpa' 4816 GCC-compiled FPA co-processor. 4817 4818 `softvfp' 4819 Software FPU with pure-endian doubles. 4820 4821 `vfp' 4822 VFP co-processor. 4823 4824`show arm fpu' 4825 Show the current type of the FPU. 4826 4827`set arm abi' 4828 This command forces GDB to use the specified ABI. 4829 4830`show arm abi' 4831 Show the currently used ABI. 4832 4833`set debug arm' 4834 Toggle whether to display ARM-specific debugging messages from the 4835 ARM target support subsystem. 4836 4837`show debug arm' 4838 Show whether ARM-specific debugging messages are enabled. 4839 4840 The following commands are available when an ARM target is debugged 4841using the RDI interface: 4842 4843`rdilogfile [FILE]' 4844 Set the filename for the ADP (Angel Debugger Protocol) packet log. 4845 With an argument, sets the log file to the specified FILE. With 4846 no argument, show the current log file name. The default log file 4847 is `rdi.log'. 4848 4849`rdilogenable [ARG]' 4850 Control logging of ADP packets. With an argument of 1 or `"yes"' 4851 enables logging, with an argument 0 or `"no"' disables it. With 4852 no arguments displays the current setting. When logging is 4853 enabled, ADP packets exchanged between GDB and the RDI target 4854 device are logged to a file. 4855 4856`set rdiromatzero' 4857 Tell GDB whether the target has ROM at address 0. If on, vector 4858 catching is disabled, so that zero address can be used. If off 4859 (the default), vector catching is enabled. For this command to 4860 take effect, it needs to be invoked prior to the `target rdi' 4861 command. 4862 4863`show rdiromatzero' 4864 Show the current setting of ROM at zero address. 4865 4866`set rdiheartbeat' 4867 Enable or disable RDI heartbeat packets. It is not recommended to 4868 turn on this option, since it confuses ARM and EPI JTAG interface, 4869 as well as the Angel monitor. 4870 4871`show rdiheartbeat' 4872 Show the setting of RDI heartbeat packets. 4873 4874 4875File: gdb.info, Node: M32R/D, Next: M68K, Prev: ARM, Up: Embedded Processors 4876 487718.3.2 Renesas M32R/D and M32R/SDI 4878---------------------------------- 4879 4880`target m32r DEV' 4881 Renesas M32R/D ROM monitor. 4882 4883`target m32rsdi DEV' 4884 Renesas M32R SDI server, connected via parallel port to the board. 4885 4886 The following GDB commands are specific to the M32R monitor: 4887 4888`set download-path PATH' 4889 Set the default path for finding downloadable SREC files. 4890 4891`show download-path' 4892 Show the default path for downloadable SREC files. 4893 4894`set board-address ADDR' 4895 Set the IP address for the M32R-EVA target board. 4896 4897`show board-address' 4898 Show the current IP address of the target board. 4899 4900`set server-address ADDR' 4901 Set the IP address for the download server, which is the GDB's 4902 host machine. 4903 4904`show server-address' 4905 Display the IP address of the download server. 4906 4907`upload [FILE]' 4908 Upload the specified SREC FILE via the monitor's Ethernet upload 4909 capability. If no FILE argument is given, the current executable 4910 file is uploaded. 4911 4912`tload [FILE]' 4913 Test the `upload' command. 4914 4915 The following commands are available for M32R/SDI: 4916 4917`sdireset' 4918 This command resets the SDI connection. 4919 4920`sdistatus' 4921 This command shows the SDI connection status. 4922 4923`debug_chaos' 4924 Instructs the remote that M32R/Chaos debugging is to be used. 4925 4926`use_debug_dma' 4927 Instructs the remote to use the DEBUG_DMA method of accessing 4928 memory. 4929 4930`use_mon_code' 4931 Instructs the remote to use the MON_CODE method of accessing 4932 memory. 4933 4934`use_ib_break' 4935 Instructs the remote to set breakpoints by IB break. 4936 4937`use_dbt_break' 4938 Instructs the remote to set breakpoints by DBT. 4939 4940 4941File: gdb.info, Node: M68K, Next: MIPS Embedded, Prev: M32R/D, Up: Embedded Processors 4942 494318.3.3 M68k 4944----------- 4945 4946The Motorola m68k configuration includes ColdFire support, and a target 4947command for the following ROM monitor. 4948 4949`target dbug DEV' 4950 dBUG ROM monitor for Motorola ColdFire. 4951 4952 4953 4954File: gdb.info, Node: MIPS Embedded, Next: OpenRISC 1000, Prev: M68K, Up: Embedded Processors 4955 495618.3.4 MIPS Embedded 4957-------------------- 4958 4959GDB can use the MIPS remote debugging protocol to talk to a MIPS board 4960attached to a serial line. This is available when you configure GDB 4961with `--target=mips-idt-ecoff'. 4962 4963 Use these GDB commands to specify the connection to your target 4964board: 4965 4966`target mips PORT' 4967 To run a program on the board, start up `gdb' with the name of 4968 your program as the argument. To connect to the board, use the 4969 command `target mips PORT', where PORT is the name of the serial 4970 port connected to the board. If the program has not already been 4971 downloaded to the board, you may use the `load' command to 4972 download it. You can then use all the usual GDB commands. 4973 4974 For example, this sequence connects to the target board through a 4975 serial port, and loads and runs a program called PROG through the 4976 debugger: 4977 4978 host$ gdb PROG 4979 GDB is free software and ... 4980 (gdb) target mips /dev/ttyb 4981 (gdb) load PROG 4982 (gdb) run 4983 4984`target mips HOSTNAME:PORTNUMBER' 4985 On some GDB host configurations, you can specify a TCP connection 4986 (for instance, to a serial line managed by a terminal 4987 concentrator) instead of a serial port, using the syntax 4988 `HOSTNAME:PORTNUMBER'. 4989 4990`target pmon PORT' 4991 PMON ROM monitor. 4992 4993`target ddb PORT' 4994 NEC's DDB variant of PMON for Vr4300. 4995 4996`target lsi PORT' 4997 LSI variant of PMON. 4998 4999`target r3900 DEV' 5000 Densan DVE-R3900 ROM monitor for Toshiba R3900 Mips. 5001 5002`target array DEV' 5003 Array Tech LSI33K RAID controller board. 5004 5005 5006GDB also supports these special commands for MIPS targets: 5007 5008`set mipsfpu double' 5009`set mipsfpu single' 5010`set mipsfpu none' 5011`set mipsfpu auto' 5012`show mipsfpu' 5013 If your target board does not support the MIPS floating point 5014 coprocessor, you should use the command `set mipsfpu none' (if you 5015 need this, you may wish to put the command in your GDB init file). 5016 This tells GDB how to find the return value of functions which 5017 return floating point values. It also allows GDB to avoid saving 5018 the floating point registers when calling functions on the board. 5019 If you are using a floating point coprocessor with only single 5020 precision floating point support, as on the R4650 processor, use 5021 the command `set mipsfpu single'. The default double precision 5022 floating point coprocessor may be selected using `set mipsfpu 5023 double'. 5024 5025 In previous versions the only choices were double precision or no 5026 floating point, so `set mipsfpu on' will select double precision 5027 and `set mipsfpu off' will select no floating point. 5028 5029 As usual, you can inquire about the `mipsfpu' variable with `show 5030 mipsfpu'. 5031 5032`set timeout SECONDS' 5033`set retransmit-timeout SECONDS' 5034`show timeout' 5035`show retransmit-timeout' 5036 You can control the timeout used while waiting for a packet, in 5037 the MIPS remote protocol, with the `set timeout SECONDS' command. 5038 The default is 5 seconds. Similarly, you can control the timeout 5039 used while waiting for an acknowledgement of a packet with the `set 5040 retransmit-timeout SECONDS' command. The default is 3 seconds. 5041 You can inspect both values with `show timeout' and `show 5042 retransmit-timeout'. (These commands are _only_ available when 5043 GDB is configured for `--target=mips-idt-ecoff'.) 5044 5045 The timeout set by `set timeout' does not apply when GDB is 5046 waiting for your program to stop. In that case, GDB waits forever 5047 because it has no way of knowing how long the program is going to 5048 run before stopping. 5049 5050`set syn-garbage-limit NUM' 5051 Limit the maximum number of characters GDB should ignore when it 5052 tries to synchronize with the remote target. The default is 10 5053 characters. Setting the limit to -1 means there's no limit. 5054 5055`show syn-garbage-limit' 5056 Show the current limit on the number of characters to ignore when 5057 trying to synchronize with the remote system. 5058 5059`set monitor-prompt PROMPT' 5060 Tell GDB to expect the specified PROMPT string from the remote 5061 monitor. The default depends on the target: 5062 pmon target 5063 `PMON' 5064 5065 ddb target 5066 `NEC010' 5067 5068 lsi target 5069 `PMON>' 5070 5071`show monitor-prompt' 5072 Show the current strings GDB expects as the prompt from the remote 5073 monitor. 5074 5075`set monitor-warnings' 5076 Enable or disable monitor warnings about hardware breakpoints. 5077 This has effect only for the `lsi' target. When on, GDB will 5078 display warning messages whose codes are returned by the `lsi' 5079 PMON monitor for breakpoint commands. 5080 5081`show monitor-warnings' 5082 Show the current setting of printing monitor warnings. 5083 5084`pmon COMMAND' 5085 This command allows sending an arbitrary COMMAND string to the 5086 monitor. The monitor must be in debug mode for this to work. 5087 5088 5089File: gdb.info, Node: OpenRISC 1000, Next: PA, Prev: MIPS Embedded, Up: Embedded Processors 5090 509118.3.5 OpenRISC 1000 5092-------------------- 5093 5094See OR1k Architecture document (`www.opencores.org') for more 5095information about platform and commands. 5096 5097`target jtag jtag://HOST:PORT' 5098 Connects to remote JTAG server. JTAG remote server can be either 5099 an or1ksim or JTAG server, connected via parallel port to the 5100 board. 5101 5102 Example: `target jtag jtag://localhost:9999' 5103 5104`or1ksim COMMAND' 5105 If connected to `or1ksim' OpenRISC 1000 Architectural Simulator, 5106 proprietary commands can be executed. 5107 5108`info or1k spr' 5109 Displays spr groups. 5110 5111`info or1k spr GROUP' 5112`info or1k spr GROUPNO' 5113 Displays register names in selected group. 5114 5115`info or1k spr GROUP REGISTER' 5116`info or1k spr REGISTER' 5117`info or1k spr GROUPNO REGISTERNO' 5118`info or1k spr REGISTERNO' 5119 Shows information about specified spr register. 5120 5121`spr GROUP REGISTER VALUE' 5122`spr REGISTER VALUE' 5123`spr GROUPNO REGISTERNO VALUE' 5124`spr REGISTERNO VALUE' 5125 Writes VALUE to specified spr register. 5126 5127 Some implementations of OpenRISC 1000 Architecture also have 5128hardware trace. It is very similar to GDB trace, except it does not 5129interfere with normal program execution and is thus much faster. 5130Hardware breakpoints/watchpoint triggers can be set using: 5131`$LEA/$LDATA' 5132 Load effective address/data 5133 5134`$SEA/$SDATA' 5135 Store effective address/data 5136 5137`$AEA/$ADATA' 5138 Access effective address ($SEA or $LEA) or data ($SDATA/$LDATA) 5139 5140`$FETCH' 5141 Fetch data 5142 5143 When triggered, it can capture low level data, like: `PC', `LSEA', 5144`LDATA', `SDATA', `READSPR', `WRITESPR', `INSTR'. 5145 5146 `htrace' commands: 5147`hwatch CONDITIONAL' 5148 Set hardware watchpoint on combination of Load/Store Effective 5149 Address(es) or Data. For example: 5150 5151 `hwatch ($LEA == my_var) && ($LDATA < 50) || ($SEA == my_var) && 5152 ($SDATA >= 50)' 5153 5154 `hwatch ($LEA == my_var) && ($LDATA < 50) || ($SEA == my_var) && 5155 ($SDATA >= 50)' 5156 5157`htrace info' 5158 Display information about current HW trace configuration. 5159 5160`htrace trigger CONDITIONAL' 5161 Set starting criteria for HW trace. 5162 5163`htrace qualifier CONDITIONAL' 5164 Set acquisition qualifier for HW trace. 5165 5166`htrace stop CONDITIONAL' 5167 Set HW trace stopping criteria. 5168 5169`htrace record [DATA]*' 5170 Selects the data to be recorded, when qualifier is met and HW 5171 trace was triggered. 5172 5173`htrace enable' 5174`htrace disable' 5175 Enables/disables the HW trace. 5176 5177`htrace rewind [FILENAME]' 5178 Clears currently recorded trace data. 5179 5180 If filename is specified, new trace file is made and any newly 5181 collected data will be written there. 5182 5183`htrace print [START [LEN]]' 5184 Prints trace buffer, using current record configuration. 5185 5186`htrace mode continuous' 5187 Set continuous trace mode. 5188 5189`htrace mode suspend' 5190 Set suspend trace mode. 5191 5192 5193 5194File: gdb.info, Node: PowerPC, Next: Sparclet, Prev: PA, Up: Embedded Processors 5195 519618.3.6 PowerPC 5197-------------- 5198 5199`target dink32 DEV' 5200 DINK32 ROM monitor. 5201 5202`target ppcbug DEV' 5203 5204`target ppcbug1 DEV' 5205 PPCBUG ROM monitor for PowerPC. 5206 5207`target sds DEV' 5208 SDS monitor, running on a PowerPC board (such as Motorola's ADS). 5209 5210 The following commands specific to the SDS protocol are supported 5211byGDB: 5212 5213`set sdstimeout NSEC' 5214 Set the timeout for SDS protocol reads to be NSEC seconds. The 5215 default is 2 seconds. 5216 5217`show sdstimeout' 5218 Show the current value of the SDS timeout. 5219 5220`sds COMMAND' 5221 Send the specified COMMAND string to the SDS monitor. 5222 5223 5224File: gdb.info, Node: PA, Next: PowerPC, Prev: OpenRISC 1000, Up: Embedded Processors 5225 522618.3.7 HP PA Embedded 5227--------------------- 5228 5229`target op50n DEV' 5230 OP50N monitor, running on an OKI HPPA board. 5231 5232`target w89k DEV' 5233 W89K monitor, running on a Winbond HPPA board. 5234 5235 5236 5237File: gdb.info, Node: Sparclet, Next: Sparclite, Prev: PowerPC, Up: Embedded Processors 5238 523918.3.8 Tsqware Sparclet 5240----------------------- 5241 5242GDB enables developers to debug tasks running on Sparclet targets from 5243a Unix host. GDB uses code that runs on both the Unix host and on the 5244Sparclet target. The program `gdb' is installed and executed on the 5245Unix host. 5246 5247`remotetimeout ARGS' 5248 GDB supports the option `remotetimeout'. This option is set by 5249 the user, and ARGS represents the number of seconds GDB waits for 5250 responses. 5251 5252 When compiling for debugging, include the options `-g' to get debug 5253information and `-Ttext' to relocate the program to where you wish to 5254load it on the target. You may also want to add the options `-n' or 5255`-N' in order to reduce the size of the sections. Example: 5256 5257 sparclet-aout-gcc prog.c -Ttext 0x12010000 -g -o prog -N 5258 5259 You can use `objdump' to verify that the addresses are what you 5260intended: 5261 5262 sparclet-aout-objdump --headers --syms prog 5263 5264 Once you have set your Unix execution search path to find GDB, you 5265are ready to run GDB. From your Unix host, run `gdb' (or 5266`sparclet-aout-gdb', depending on your installation). 5267 5268 GDB comes up showing the prompt: 5269 5270 (gdbslet) 5271 5272* Menu: 5273 5274* Sparclet File:: Setting the file to debug 5275* Sparclet Connection:: Connecting to Sparclet 5276* Sparclet Download:: Sparclet download 5277* Sparclet Execution:: Running and debugging 5278 5279 5280File: gdb.info, Node: Sparclet File, Next: Sparclet Connection, Up: Sparclet 5281 528218.3.8.1 Setting File to Debug 5283.............................. 5284 5285The GDB command `file' lets you choose with program to debug. 5286 5287 (gdbslet) file prog 5288 5289 GDB then attempts to read the symbol table of `prog'. GDB locates 5290the file by searching the directories listed in the command search path. 5291If the file was compiled with debug information (option `-g'), source 5292files will be searched as well. GDB locates the source files by 5293searching the directories listed in the directory search path (*note 5294Your Program's Environment: Environment.). If it fails to find a file, 5295it displays a message such as: 5296 5297 prog: No such file or directory. 5298 5299 When this happens, add the appropriate directories to the search 5300paths with the GDB commands `path' and `dir', and execute the `target' 5301command again. 5302 5303 5304File: gdb.info, Node: Sparclet Connection, Next: Sparclet Download, Prev: Sparclet File, Up: Sparclet 5305 530618.3.8.2 Connecting to Sparclet 5307............................... 5308 5309The GDB command `target' lets you connect to a Sparclet target. To 5310connect to a target on serial port "`ttya'", type: 5311 5312 (gdbslet) target sparclet /dev/ttya 5313 Remote target sparclet connected to /dev/ttya 5314 main () at ../prog.c:3 5315 5316 GDB displays messages like these: 5317 5318 Connected to ttya. 5319 5320 5321File: gdb.info, Node: Sparclet Download, Next: Sparclet Execution, Prev: Sparclet Connection, Up: Sparclet 5322 532318.3.8.3 Sparclet Download 5324.......................... 5325 5326Once connected to the Sparclet target, you can use the GDB `load' 5327command to download the file from the host to the target. The file 5328name and load offset should be given as arguments to the `load' command. 5329Since the file format is aout, the program must be loaded to the 5330starting address. You can use `objdump' to find out what this value 5331is. The load offset is an offset which is added to the VMA (virtual 5332memory address) of each of the file's sections. For instance, if the 5333program `prog' was linked to text address 0x1201000, with data at 53340x12010160 and bss at 0x12010170, in GDB, type: 5335 5336 (gdbslet) load prog 0x12010000 5337 Loading section .text, size 0xdb0 vma 0x12010000 5338 5339 If the code is loaded at a different address then what the program 5340was linked to, you may need to use the `section' and `add-symbol-file' 5341commands to tell GDB where to map the symbol table. 5342 5343 5344File: gdb.info, Node: Sparclet Execution, Prev: Sparclet Download, Up: Sparclet 5345 534618.3.8.4 Running and Debugging 5347.............................. 5348 5349You can now begin debugging the task using GDB's execution control 5350commands, `b', `step', `run', etc. See the GDB manual for the list of 5351commands. 5352 5353 (gdbslet) b main 5354 Breakpoint 1 at 0x12010000: file prog.c, line 3. 5355 (gdbslet) run 5356 Starting program: prog 5357 Breakpoint 1, main (argc=1, argv=0xeffff21c) at prog.c:3 5358 3 char *symarg = 0; 5359 (gdbslet) step 5360 4 char *execarg = "hello!"; 5361 (gdbslet) 5362 5363 5364File: gdb.info, Node: Sparclite, Next: Z8000, Prev: Sparclet, Up: Embedded Processors 5365 536618.3.9 Fujitsu Sparclite 5367------------------------ 5368 5369`target sparclite DEV' 5370 Fujitsu sparclite boards, used only for the purpose of loading. 5371 You must use an additional command to debug the program. For 5372 example: target remote DEV using GDB standard remote protocol. 5373 5374 5375 5376File: gdb.info, Node: Z8000, Next: AVR, Prev: Sparclite, Up: Embedded Processors 5377 537818.3.10 Zilog Z8000 5379------------------- 5380 5381When configured for debugging Zilog Z8000 targets, GDB includes a Z8000 5382simulator. 5383 5384 For the Z8000 family, `target sim' simulates either the Z8002 (the 5385unsegmented variant of the Z8000 architecture) or the Z8001 (the 5386segmented variant). The simulator recognizes which architecture is 5387appropriate by inspecting the object code. 5388 5389`target sim ARGS' 5390 Debug programs on a simulated CPU. If the simulator supports setup 5391 options, specify them via ARGS. 5392 5393After specifying this target, you can debug programs for the simulated 5394CPU in the same style as programs for your host computer; use the 5395`file' command to load a new program image, the `run' command to run 5396your program, and so on. 5397 5398 As well as making available all the usual machine registers (*note 5399Registers: Registers.), the Z8000 simulator provides three additional 5400items of information as specially named registers: 5401 5402`cycles' 5403 Counts clock-ticks in the simulator. 5404 5405`insts' 5406 Counts instructions run in the simulator. 5407 5408`time' 5409 Execution time in 60ths of a second. 5410 5411 5412 You can refer to these values in GDB expressions with the usual 5413conventions; for example, `b fputc if $cycles>5000' sets a conditional 5414breakpoint that suspends only after at least 5000 simulated clock ticks. 5415 5416 5417File: gdb.info, Node: AVR, Next: CRIS, Prev: Z8000, Up: Embedded Processors 5418 541918.3.11 Atmel AVR 5420----------------- 5421 5422When configured for debugging the Atmel AVR, GDB supports the following 5423AVR-specific commands: 5424 5425`info io_registers' 5426 This command displays information about the AVR I/O registers. For 5427 each register, GDB prints its number and value. 5428 5429 5430File: gdb.info, Node: CRIS, Next: Super-H, Prev: AVR, Up: Embedded Processors 5431 543218.3.12 CRIS 5433------------ 5434 5435When configured for debugging CRIS, GDB provides the following 5436CRIS-specific commands: 5437 5438`set cris-version VER' 5439 Set the current CRIS version to VER, either `10' or `32'. The 5440 CRIS version affects register names and sizes. This command is 5441 useful in case autodetection of the CRIS version fails. 5442 5443`show cris-version' 5444 Show the current CRIS version. 5445 5446`set cris-dwarf2-cfi' 5447 Set the usage of DWARF-2 CFI for CRIS debugging. The default is 5448 `on'. Change to `off' when using `gcc-cris' whose version is below 5449 `R59'. 5450 5451`show cris-dwarf2-cfi' 5452 Show the current state of using DWARF-2 CFI. 5453 5454`set cris-mode MODE' 5455 Set the current CRIS mode to MODE. It should only be changed when 5456 debugging in guru mode, in which case it should be set to `guru' 5457 (the default is `normal'). 5458 5459`show cris-mode' 5460 Show the current CRIS mode. 5461 5462 5463File: gdb.info, Node: Super-H, Prev: CRIS, Up: Embedded Processors 5464 546518.3.13 Renesas Super-H 5466----------------------- 5467 5468For the Renesas Super-H processor, GDB provides these commands: 5469 5470`regs' 5471 Show the values of all Super-H registers. 5472 5473 5474File: gdb.info, Node: Architectures, Prev: Embedded Processors, Up: Configurations 5475 547618.4 Architectures 5477================== 5478 5479This section describes characteristics of architectures that affect all 5480uses of GDB with the architecture, both native and cross. 5481 5482* Menu: 5483 5484* i386:: 5485* A29K:: 5486* Alpha:: 5487* MIPS:: 5488* HPPA:: HP PA architecture 5489* SPU:: Cell Broadband Engine SPU architecture 5490 5491 5492File: gdb.info, Node: i386, Next: A29K, Up: Architectures 5493 549418.4.1 x86 Architecture-specific Issues 5495--------------------------------------- 5496 5497`set struct-convention MODE' 5498 Set the convention used by the inferior to return `struct's and 5499 `union's from functions to MODE. Possible values of MODE are 5500 `"pcc"', `"reg"', and `"default"' (the default). `"default"' or 5501 `"pcc"' means that `struct's are returned on the stack, while 5502 `"reg"' means that a `struct' or a `union' whose size is 1, 2, 4, 5503 or 8 bytes will be returned in a register. 5504 5505`show struct-convention' 5506 Show the current setting of the convention to return `struct's 5507 from functions. 5508 5509 5510File: gdb.info, Node: A29K, Next: Alpha, Prev: i386, Up: Architectures 5511 551218.4.2 A29K 5513----------- 5514 5515`set rstack_high_address ADDRESS' 5516 On AMD 29000 family processors, registers are saved in a separate 5517 "register stack". There is no way for GDB to determine the extent 5518 of this stack. Normally, GDB just assumes that the stack is 5519 "large enough". This may result in GDB referencing memory 5520 locations that do not exist. If necessary, you can get around 5521 this problem by specifying the ending address of the register 5522 stack with the `set rstack_high_address' command. The argument 5523 should be an address, which you probably want to precede with `0x' 5524 to specify in hexadecimal. 5525 5526`show rstack_high_address' 5527 Display the current limit of the register stack, on AMD 29000 5528 family processors. 5529 5530 5531 5532File: gdb.info, Node: Alpha, Next: MIPS, Prev: A29K, Up: Architectures 5533 553418.4.3 Alpha 5535------------ 5536 5537See the following section. 5538 5539 5540File: gdb.info, Node: MIPS, Next: HPPA, Prev: Alpha, Up: Architectures 5541 554218.4.4 MIPS 5543----------- 5544 5545Alpha- and MIPS-based computers use an unusual stack frame, which 5546sometimes requires GDB to search backward in the object code to find 5547the beginning of a function. 5548 5549 To improve response time (especially for embedded applications, where 5550GDB may be restricted to a slow serial line for this search) you may 5551want to limit the size of this search, using one of these commands: 5552 5553`set heuristic-fence-post LIMIT' 5554 Restrict GDB to examining at most LIMIT bytes in its search for 5555 the beginning of a function. A value of 0 (the default) means 5556 there is no limit. However, except for 0, the larger the limit 5557 the more bytes `heuristic-fence-post' must search and therefore 5558 the longer it takes to run. You should only need to use this 5559 command when debugging a stripped executable. 5560 5561`show heuristic-fence-post' 5562 Display the current limit. 5563 5564These commands are available _only_ when GDB is configured for 5565debugging programs on Alpha or MIPS processors. 5566 5567 Several MIPS-specific commands are available when debugging MIPS 5568programs: 5569 5570`set mips abi ARG' 5571 Tell GDB which MIPS ABI is used by the inferior. Possible values 5572 of ARG are: 5573 5574 `auto' 5575 The default ABI associated with the current binary (this is 5576 the default). 5577 5578 `o32' 5579 5580 `o64' 5581 5582 `n32' 5583 5584 `n64' 5585 5586 `eabi32' 5587 5588 `eabi64' 5589 5590 `auto' 5591 5592`show mips abi' 5593 Show the MIPS ABI used by GDB to debug the inferior. 5594 5595`set mipsfpu' 5596`show mipsfpu' 5597 *Note set mipsfpu: MIPS Embedded. 5598 5599`set mips mask-address ARG' 5600 This command determines whether the most-significant 32 bits of 5601 64-bit MIPS addresses are masked off. The argument ARG can be 5602 `on', `off', or `auto'. The latter is the default setting, which 5603 lets GDB determine the correct value. 5604 5605`show mips mask-address' 5606 Show whether the upper 32 bits of MIPS addresses are masked off or 5607 not. 5608 5609`set remote-mips64-transfers-32bit-regs' 5610 This command controls compatibility with 64-bit MIPS targets that 5611 transfer data in 32-bit quantities. If you have an old MIPS 64 5612 target that transfers 32 bits for some registers, like SR and FSR, 5613 and 64 bits for other registers, set this option to `on'. 5614 5615`show remote-mips64-transfers-32bit-regs' 5616 Show the current setting of compatibility with older MIPS 64 5617 targets. 5618 5619`set debug mips' 5620 This command turns on and off debugging messages for the 5621 MIPS-specific target code in GDB. 5622 5623`show debug mips' 5624 Show the current setting of MIPS debugging messages. 5625 5626 5627File: gdb.info, Node: HPPA, Next: SPU, Prev: MIPS, Up: Architectures 5628 562918.4.5 HPPA 5630----------- 5631 5632When GDB is debugging the HP PA architecture, it provides the following 5633special commands: 5634 5635`set debug hppa' 5636 This command determines whether HPPA architecture-specific 5637 debugging messages are to be displayed. 5638 5639`show debug hppa' 5640 Show whether HPPA debugging messages are displayed. 5641 5642`maint print unwind ADDRESS' 5643 This command displays the contents of the unwind table entry at the 5644 given ADDRESS. 5645 5646 5647 5648File: gdb.info, Node: SPU, Prev: HPPA, Up: Architectures 5649 565018.4.6 Cell Broadband Engine SPU architecture 5651--------------------------------------------- 5652 5653When GDB is debugging the Cell Broadband Engine SPU architecture, it 5654provides the following special commands: 5655 5656`info spu event' 5657 Display SPU event facility status. Shows current event mask and 5658 pending event status. 5659 5660`info spu signal' 5661 Display SPU signal notification facility status. Shows pending 5662 signal-control word and signal notification mode of both signal 5663 notification channels. 5664 5665`info spu mailbox' 5666 Display SPU mailbox facility status. Shows all pending entries, 5667 in order of processing, in each of the SPU Write Outbound, SPU 5668 Write Outbound Interrupt, and SPU Read Inbound mailboxes. 5669 5670`info spu dma' 5671 Display MFC DMA status. Shows all pending commands in the MFC DMA 5672 queue. For each entry, opcode, tag, class IDs, effective and 5673 local store addresses and transfer size are shown. 5674 5675`info spu proxydma' 5676 Display MFC Proxy-DMA status. Shows all pending commands in the 5677 MFC Proxy-DMA queue. For each entry, opcode, tag, class IDs, 5678 effective and local store addresses and transfer size are shown. 5679 5680 5681 5682File: gdb.info, Node: Controlling GDB, Next: Sequences, Prev: Configurations, Up: Top 5683 568419 Controlling GDB 5685****************** 5686 5687You can alter the way GDB interacts with you by using the `set' 5688command. For commands controlling how GDB displays data, see *Note 5689Print Settings: Print Settings. Other settings are described here. 5690 5691* Menu: 5692 5693* Prompt:: Prompt 5694* Editing:: Command editing 5695* Command History:: Command history 5696* Screen Size:: Screen size 5697* Numbers:: Numbers 5698* ABI:: Configuring the current ABI 5699* Messages/Warnings:: Optional warnings and messages 5700* Debugging Output:: Optional messages about internal happenings 5701 5702 5703File: gdb.info, Node: Prompt, Next: Editing, Up: Controlling GDB 5704 570519.1 Prompt 5706=========== 5707 5708GDB indicates its readiness to read a command by printing a string 5709called the "prompt". This string is normally `(gdb)'. You can change 5710the prompt string with the `set prompt' command. For instance, when 5711debugging GDB with GDB, it is useful to change the prompt in one of the 5712GDB sessions so that you can always tell which one you are talking to. 5713 5714 _Note:_ `set prompt' does not add a space for you after the prompt 5715you set. This allows you to set a prompt which ends in a space or a 5716prompt that does not. 5717 5718`set prompt NEWPROMPT' 5719 Directs GDB to use NEWPROMPT as its prompt string henceforth. 5720 5721`show prompt' 5722 Prints a line of the form: `Gdb's prompt is: YOUR-PROMPT' 5723 5724 5725File: gdb.info, Node: Editing, Next: Command History, Prev: Prompt, Up: Controlling GDB 5726 572719.2 Command Editing 5728==================== 5729 5730GDB reads its input commands via the "Readline" interface. This GNU 5731library provides consistent behavior for programs which provide a 5732command line interface to the user. Advantages are GNU Emacs-style or 5733"vi"-style inline editing of commands, `csh'-like history substitution, 5734and a storage and recall of command history across debugging sessions. 5735 5736 You may control the behavior of command line editing in GDB with the 5737command `set'. 5738 5739`set editing' 5740`set editing on' 5741 Enable command line editing (enabled by default). 5742 5743`set editing off' 5744 Disable command line editing. 5745 5746`show editing' 5747 Show whether command line editing is enabled. 5748 5749 *Note Command Line Editing::, for more details about the Readline 5750interface. Users unfamiliar with GNU Emacs or `vi' are encouraged to 5751read that chapter. 5752 5753 5754File: gdb.info, Node: Command History, Next: Screen Size, Prev: Editing, Up: Controlling GDB 5755 575619.3 Command History 5757==================== 5758 5759GDB can keep track of the commands you type during your debugging 5760sessions, so that you can be certain of precisely what happened. Use 5761these commands to manage the GDB command history facility. 5762 5763 GDB uses the GNU History library, a part of the Readline package, to 5764provide the history facility. *Note Using History Interactively::, for 5765the detailed description of the History library. 5766 5767 To issue a command to GDB without affecting certain aspects of the 5768state which is seen by users, prefix it with `server ' (*note Server 5769Prefix::). This means that this command will not affect the command 5770history, nor will it affect GDB's notion of which command to repeat if 5771<RET> is pressed on a line by itself. 5772 5773 The server prefix does not affect the recording of values into the 5774value history; to print a value without recording it into the value 5775history, use the `output' command instead of the `print' command. 5776 5777 Here is the description of GDB commands related to command history. 5778 5779`set history filename FNAME' 5780 Set the name of the GDB command history file to FNAME. This is 5781 the file where GDB reads an initial command history list, and 5782 where it writes the command history from this session when it 5783 exits. You can access this list through history expansion or 5784 through the history command editing characters listed below. This 5785 file defaults to the value of the environment variable 5786 `GDBHISTFILE', or to `./.gdb_history' (`./_gdb_history' on MS-DOS) 5787 if this variable is not set. 5788 5789`set history save' 5790`set history save on' 5791 Record command history in a file, whose name may be specified with 5792 the `set history filename' command. By default, this option is 5793 disabled. 5794 5795`set history save off' 5796 Stop recording command history in a file. 5797 5798`set history size SIZE' 5799 Set the number of commands which GDB keeps in its history list. 5800 This defaults to the value of the environment variable `HISTSIZE', 5801 or to 256 if this variable is not set. 5802 5803 History expansion assigns special meaning to the character `!'. 5804*Note Event Designators::, for more details. 5805 5806 Since `!' is also the logical not operator in C, history expansion 5807is off by default. If you decide to enable history expansion with the 5808`set history expansion on' command, you may sometimes need to follow 5809`!' (when it is used as logical not, in an expression) with a space or 5810a tab to prevent it from being expanded. The readline history 5811facilities do not attempt substitution on the strings `!=' and `!(', 5812even when history expansion is enabled. 5813 5814 The commands to control history expansion are: 5815 5816`set history expansion on' 5817`set history expansion' 5818 Enable history expansion. History expansion is off by default. 5819 5820`set history expansion off' 5821 Disable history expansion. 5822 5823`show history' 5824`show history filename' 5825`show history save' 5826`show history size' 5827`show history expansion' 5828 These commands display the state of the GDB history parameters. 5829 `show history' by itself displays all four states. 5830 5831`show commands' 5832 Display the last ten commands in the command history. 5833 5834`show commands N' 5835 Print ten commands centered on command number N. 5836 5837`show commands +' 5838 Print ten commands just after the commands last printed. 5839 5840 5841File: gdb.info, Node: Screen Size, Next: Numbers, Prev: Command History, Up: Controlling GDB 5842 584319.4 Screen Size 5844================ 5845 5846Certain commands to GDB may produce large amounts of information output 5847to the screen. To help you read all of it, GDB pauses and asks you for 5848input at the end of each page of output. Type <RET> when you want to 5849continue the output, or `q' to discard the remaining output. Also, the 5850screen width setting determines when to wrap lines of output. 5851Depending on what is being printed, GDB tries to break the line at a 5852readable place, rather than simply letting it overflow onto the 5853following line. 5854 5855 Normally GDB knows the size of the screen from the terminal driver 5856software. For example, on Unix GDB uses the termcap data base together 5857with the value of the `TERM' environment variable and the `stty rows' 5858and `stty cols' settings. If this is not correct, you can override it 5859with the `set height' and `set width' commands: 5860 5861`set height LPP' 5862`show height' 5863`set width CPL' 5864`show width' 5865 These `set' commands specify a screen height of LPP lines and a 5866 screen width of CPL characters. The associated `show' commands 5867 display the current settings. 5868 5869 If you specify a height of zero lines, GDB does not pause during 5870 output no matter how long the output is. This is useful if output 5871 is to a file or to an editor buffer. 5872 5873 Likewise, you can specify `set width 0' to prevent GDB from 5874 wrapping its output. 5875 5876`set pagination on' 5877`set pagination off' 5878 Turn the output pagination on or off; the default is on. Turning 5879 pagination off is the alternative to `set height 0'. 5880 5881`show pagination' 5882 Show the current pagination mode. 5883 5884 5885File: gdb.info, Node: Numbers, Next: ABI, Prev: Screen Size, Up: Controlling GDB 5886 588719.5 Numbers 5888============ 5889 5890You can always enter numbers in octal, decimal, or hexadecimal in GDB 5891by the usual conventions: octal numbers begin with `0', decimal numbers 5892end with `.', and hexadecimal numbers begin with `0x'. Numbers that 5893neither begin with `0' or `0x', nor end with a `.' are, by default, 5894entered in base 10; likewise, the default display for numbers--when no 5895particular format is specified--is base 10. You can change the default 5896base for both input and output with the commands described below. 5897 5898`set input-radix BASE' 5899 Set the default base for numeric input. Supported choices for 5900 BASE are decimal 8, 10, or 16. BASE must itself be specified 5901 either unambiguously or using the current input radix; for 5902 example, any of 5903 5904 set input-radix 012 5905 set input-radix 10. 5906 set input-radix 0xa 5907 5908 sets the input base to decimal. On the other hand, `set 5909 input-radix 10' leaves the input radix unchanged, no matter what 5910 it was, since `10', being without any leading or trailing signs of 5911 its base, is interpreted in the current radix. Thus, if the 5912 current radix is 16, `10' is interpreted in hex, i.e. as 16 5913 decimal, which doesn't change the radix. 5914 5915`set output-radix BASE' 5916 Set the default base for numeric display. Supported choices for 5917 BASE are decimal 8, 10, or 16. BASE must itself be specified 5918 either unambiguously or using the current input radix. 5919 5920`show input-radix' 5921 Display the current default base for numeric input. 5922 5923`show output-radix' 5924 Display the current default base for numeric display. 5925 5926`set radix [BASE]' 5927`show radix' 5928 These commands set and show the default base for both input and 5929 output of numbers. `set radix' sets the radix of input and output 5930 to the same base; without an argument, it resets the radix back to 5931 its default value of 10. 5932 5933 5934 5935File: gdb.info, Node: ABI, Next: Messages/Warnings, Prev: Numbers, Up: Controlling GDB 5936 593719.6 Configuring the Current ABI 5938================================ 5939 5940GDB can determine the "ABI" (Application Binary Interface) of your 5941application automatically. However, sometimes you need to override its 5942conclusions. Use these commands to manage GDB's view of the current 5943ABI. 5944 5945 One GDB configuration can debug binaries for multiple operating 5946system targets, either via remote debugging or native emulation. GDB 5947will autodetect the "OS ABI" (Operating System ABI) in use, but you can 5948override its conclusion using the `set osabi' command. One example 5949where this is useful is in debugging of binaries which use an alternate 5950C library (e.g. UCLIBC for GNU/Linux) which does not have the same 5951identifying marks that the standard C library for your platform 5952provides. 5953 5954`show osabi' 5955 Show the OS ABI currently in use. 5956 5957`set osabi' 5958 With no argument, show the list of registered available OS ABI's. 5959 5960`set osabi ABI' 5961 Set the current OS ABI to ABI. 5962 5963 Generally, the way that an argument of type `float' is passed to a 5964function depends on whether the function is prototyped. For a 5965prototyped (i.e. ANSI/ISO style) function, `float' arguments are passed 5966unchanged, according to the architecture's convention for `float'. For 5967unprototyped (i.e. K&R style) functions, `float' arguments are first 5968promoted to type `double' and then passed. 5969 5970 Unfortunately, some forms of debug information do not reliably 5971indicate whether a function is prototyped. If GDB calls a function 5972that is not marked as prototyped, it consults `set 5973coerce-float-to-double'. 5974 5975`set coerce-float-to-double' 5976`set coerce-float-to-double on' 5977 Arguments of type `float' will be promoted to `double' when passed 5978 to an unprototyped function. This is the default setting. 5979 5980`set coerce-float-to-double off' 5981 Arguments of type `float' will be passed directly to unprototyped 5982 functions. 5983 5984`show coerce-float-to-double' 5985 Show the current setting of promoting `float' to `double'. 5986 5987 GDB needs to know the ABI used for your program's C++ objects. The 5988correct C++ ABI depends on which C++ compiler was used to build your 5989application. GDB only fully supports programs with a single C++ ABI; 5990if your program contains code using multiple C++ ABI's or if GDB can 5991not identify your program's ABI correctly, you can tell GDB which ABI 5992to use. Currently supported ABI's include "gnu-v2", for `g++' versions 5993before 3.0, "gnu-v3", for `g++' versions 3.0 and later, and "hpaCC" for 5994the HP ANSI C++ compiler. Other C++ compilers may use the "gnu-v2" or 5995"gnu-v3" ABI's as well. The default setting is "auto". 5996 5997`show cp-abi' 5998 Show the C++ ABI currently in use. 5999 6000`set cp-abi' 6001 With no argument, show the list of supported C++ ABI's. 6002 6003`set cp-abi ABI' 6004`set cp-abi auto' 6005 Set the current C++ ABI to ABI, or return to automatic detection. 6006 6007 6008File: gdb.info, Node: Messages/Warnings, Next: Debugging Output, Prev: ABI, Up: Controlling GDB 6009 601019.7 Optional Warnings and Messages 6011=================================== 6012 6013By default, GDB is silent about its inner workings. If you are running 6014on a slow machine, you may want to use the `set verbose' command. This 6015makes GDB tell you when it does a lengthy internal operation, so you 6016will not think it has crashed. 6017 6018 Currently, the messages controlled by `set verbose' are those which 6019announce that the symbol table for a source file is being read; see 6020`symbol-file' in *Note Commands to Specify Files: Files. 6021 6022`set verbose on' 6023 Enables GDB output of certain informational messages. 6024 6025`set verbose off' 6026 Disables GDB output of certain informational messages. 6027 6028`show verbose' 6029 Displays whether `set verbose' is on or off. 6030 6031 By default, if GDB encounters bugs in the symbol table of an object 6032file, it is silent; but if you are debugging a compiler, you may find 6033this information useful (*note Errors Reading Symbol Files: Symbol 6034Errors.). 6035 6036`set complaints LIMIT' 6037 Permits GDB to output LIMIT complaints about each type of unusual 6038 symbols before becoming silent about the problem. Set LIMIT to 6039 zero to suppress all complaints; set it to a large number to 6040 prevent complaints from being suppressed. 6041 6042`show complaints' 6043 Displays how many symbol complaints GDB is permitted to produce. 6044 6045 6046 By default, GDB is cautious, and asks what sometimes seems to be a 6047lot of stupid questions to confirm certain commands. For example, if 6048you try to run a program which is already running: 6049 6050 (gdb) run 6051 The program being debugged has been started already. 6052 Start it from the beginning? (y or n) 6053 6054 If you are willing to unflinchingly face the consequences of your own 6055commands, you can disable this "feature": 6056 6057`set confirm off' 6058 Disables confirmation requests. 6059 6060`set confirm on' 6061 Enables confirmation requests (the default). 6062 6063`show confirm' 6064 Displays state of confirmation requests. 6065 6066 6067 If you need to debug user-defined commands or sourced files you may 6068find it useful to enable "command tracing". In this mode each command 6069will be printed as it is executed, prefixed with one or more `+' 6070symbols, the quantity denoting the call depth of each command. 6071 6072`set trace-commands on' 6073 Enable command tracing. 6074 6075`set trace-commands off' 6076 Disable command tracing. 6077 6078`show trace-commands' 6079 Display the current state of command tracing. 6080 6081 6082File: gdb.info, Node: Debugging Output, Prev: Messages/Warnings, Up: Controlling GDB 6083 608419.8 Optional Messages about Internal Happenings 6085================================================ 6086 6087GDB has commands that enable optional debugging messages from various 6088GDB subsystems; normally these commands are of interest to GDB 6089maintainers, or when reporting a bug. This section documents those 6090commands. 6091 6092`set exec-done-display' 6093 Turns on or off the notification of asynchronous commands' 6094 completion. When on, GDB will print a message when an 6095 asynchronous command finishes its execution. The default is off. 6096 6097`show exec-done-display' 6098 Displays the current setting of asynchronous command completion 6099 notification. 6100 6101`set debug arch' 6102 Turns on or off display of gdbarch debugging info. The default is 6103 off 6104 6105`show debug arch' 6106 Displays the current state of displaying gdbarch debugging info. 6107 6108`set debug aix-thread' 6109 Display debugging messages about inner workings of the AIX thread 6110 module. 6111 6112`show debug aix-thread' 6113 Show the current state of AIX thread debugging info display. 6114 6115`set debug event' 6116 Turns on or off display of GDB event debugging info. The default 6117 is off. 6118 6119`show debug event' 6120 Displays the current state of displaying GDB event debugging info. 6121 6122`set debug expression' 6123 Turns on or off display of debugging info about GDB expression 6124 parsing. The default is off. 6125 6126`show debug expression' 6127 Displays the current state of displaying debugging info about GDB 6128 expression parsing. 6129 6130`set debug frame' 6131 Turns on or off display of GDB frame debugging info. The default 6132 is off. 6133 6134`show debug frame' 6135 Displays the current state of displaying GDB frame debugging info. 6136 6137`set debug infrun' 6138 Turns on or off display of GDB debugging info for running the 6139 inferior. The default is off. `infrun.c' contains GDB's runtime 6140 state machine used for implementing operations such as 6141 single-stepping the inferior. 6142 6143`show debug infrun' 6144 Displays the current state of GDB inferior debugging. 6145 6146`set debug lin-lwp' 6147 Turns on or off debugging messages from the Linux LWP debug 6148 support. 6149 6150`show debug lin-lwp' 6151 Show the current state of Linux LWP debugging messages. 6152 6153`set debug observer' 6154 Turns on or off display of GDB observer debugging. This includes 6155 info such as the notification of observable events. 6156 6157`show debug observer' 6158 Displays the current state of observer debugging. 6159 6160`set debug overload' 6161 Turns on or off display of GDB C++ overload debugging info. This 6162 includes info such as ranking of functions, etc. The default is 6163 off. 6164 6165`show debug overload' 6166 Displays the current state of displaying GDB C++ overload 6167 debugging info. 6168 6169`set debug remote' 6170 Turns on or off display of reports on all packets sent back and 6171 forth across the serial line to the remote machine. The info is 6172 printed on the GDB standard output stream. The default is off. 6173 6174`show debug remote' 6175 Displays the state of display of remote packets. 6176 6177`set debug serial' 6178 Turns on or off display of GDB serial debugging info. The default 6179 is off. 6180 6181`show debug serial' 6182 Displays the current state of displaying GDB serial debugging info. 6183 6184`set debug solib-frv' 6185 Turns on or off debugging messages for FR-V shared-library code. 6186 6187`show debug solib-frv' 6188 Display the current state of FR-V shared-library code debugging 6189 messages. 6190 6191`set debug target' 6192 Turns on or off display of GDB target debugging info. This info 6193 includes what is going on at the target level of GDB, as it 6194 happens. The default is 0. Set it to 1 to track events, and to 2 6195 to also track the value of large memory transfers. Changes to 6196 this flag do not take effect until the next time you connect to a 6197 target or use the `run' command. 6198 6199`show debug target' 6200 Displays the current state of displaying GDB target debugging info. 6201 6202`set debugvarobj' 6203 Turns on or off display of GDB variable object debugging info. The 6204 default is off. 6205 6206`show debugvarobj' 6207 Displays the current state of displaying GDB variable object 6208 debugging info. 6209 6210`set debug xml' 6211 Turns on or off debugging messages for built-in XML parsers. 6212 6213`show debug xml' 6214 Displays the current state of XML debugging messages. 6215 6216 6217File: gdb.info, Node: Sequences, Next: Interpreters, Prev: Controlling GDB, Up: Top 6218 621920 Canned Sequences of Commands 6220******************************* 6221 6222Aside from breakpoint commands (*note Breakpoint Command Lists: Break 6223Commands.), GDB provides two ways to store sequences of commands for 6224execution as a unit: user-defined commands and command files. 6225 6226* Menu: 6227 6228* Define:: How to define your own commands 6229* Hooks:: Hooks for user-defined commands 6230* Command Files:: How to write scripts of commands to be stored in a file 6231* Output:: Commands for controlled output 6232 6233 6234File: gdb.info, Node: Define, Next: Hooks, Up: Sequences 6235 623620.1 User-defined Commands 6237========================== 6238 6239A "user-defined command" is a sequence of GDB commands to which you 6240assign a new name as a command. This is done with the `define' 6241command. User commands may accept up to 10 arguments separated by 6242whitespace. Arguments are accessed within the user command via 6243`$arg0...$arg9'. A trivial example: 6244 6245 define adder 6246 print $arg0 + $arg1 + $arg2 6247 end 6248 6249To execute the command use: 6250 6251 adder 1 2 3 6252 6253This defines the command `adder', which prints the sum of its three 6254arguments. Note the arguments are text substitutions, so they may 6255reference variables, use complex expressions, or even perform inferior 6256functions calls. 6257 6258 In addition, `$argc' may be used to find out how many arguments have 6259been passed. This expands to a number in the range 0...10. 6260 6261 define adder 6262 if $argc == 2 6263 print $arg0 + $arg1 6264 end 6265 if $argc == 3 6266 print $arg0 + $arg1 + $arg2 6267 end 6268 end 6269 6270`define COMMANDNAME' 6271 Define a command named COMMANDNAME. If there is already a command 6272 by that name, you are asked to confirm that you want to redefine 6273 it. 6274 6275 The definition of the command is made up of other GDB command 6276 lines, which are given following the `define' command. The end of 6277 these commands is marked by a line containing `end'. 6278 6279`document COMMANDNAME' 6280 Document the user-defined command COMMANDNAME, so that it can be 6281 accessed by `help'. The command COMMANDNAME must already be 6282 defined. This command reads lines of documentation just as 6283 `define' reads the lines of the command definition, ending with 6284 `end'. After the `document' command is finished, `help' on command 6285 COMMANDNAME displays the documentation you have written. 6286 6287 You may use the `document' command again to change the 6288 documentation of a command. Redefining the command with `define' 6289 does not change the documentation. 6290 6291`dont-repeat' 6292 Used inside a user-defined command, this tells GDB that this 6293 command should not be repeated when the user hits <RET> (*note 6294 repeat last command: Command Syntax.). 6295 6296`help user-defined' 6297 List all user-defined commands, with the first line of the 6298 documentation (if any) for each. 6299 6300`show user' 6301`show user COMMANDNAME' 6302 Display the GDB commands used to define COMMANDNAME (but not its 6303 documentation). If no COMMANDNAME is given, display the 6304 definitions for all user-defined commands. 6305 6306`show max-user-call-depth' 6307`set max-user-call-depth' 6308 The value of `max-user-call-depth' controls how many recursion 6309 levels are allowed in user-defined commands before GDB suspects an 6310 infinite recursion and aborts the command. 6311 6312 In addition to the above commands, user-defined commands frequently 6313use control flow commands, described in *Note Command Files::. 6314 6315 When user-defined commands are executed, the commands of the 6316definition are not printed. An error in any command stops execution of 6317the user-defined command. 6318 6319 If used interactively, commands that would ask for confirmation 6320proceed without asking when used inside a user-defined command. Many 6321GDB commands that normally print messages to say what they are doing 6322omit the messages when used in a user-defined command. 6323 6324 6325File: gdb.info, Node: Hooks, Next: Command Files, Prev: Define, Up: Sequences 6326 632720.2 User-defined Command Hooks 6328=============================== 6329 6330You may define "hooks", which are a special kind of user-defined 6331command. Whenever you run the command `foo', if the user-defined 6332command `hook-foo' exists, it is executed (with no arguments) before 6333that command. 6334 6335 A hook may also be defined which is run after the command you 6336executed. Whenever you run the command `foo', if the user-defined 6337command `hookpost-foo' exists, it is executed (with no arguments) after 6338that command. Post-execution hooks may exist simultaneously with 6339pre-execution hooks, for the same command. 6340 6341 It is valid for a hook to call the command which it hooks. If this 6342occurs, the hook is not re-executed, thereby avoiding infinite 6343recursion. 6344 6345 In addition, a pseudo-command, `stop' exists. Defining 6346(`hook-stop') makes the associated commands execute every time 6347execution stops in your program: before breakpoint commands are run, 6348displays are printed, or the stack frame is printed. 6349 6350 For example, to ignore `SIGALRM' signals while single-stepping, but 6351treat them normally during normal execution, you could define: 6352 6353 define hook-stop 6354 handle SIGALRM nopass 6355 end 6356 6357 define hook-run 6358 handle SIGALRM pass 6359 end 6360 6361 define hook-continue 6362 handle SIGALRM pass 6363 end 6364 6365 As a further example, to hook at the beginning and end of the `echo' 6366command, and to add extra text to the beginning and end of the message, 6367you could define: 6368 6369 define hook-echo 6370 echo <<<--- 6371 end 6372 6373 define hookpost-echo 6374 echo --->>>\n 6375 end 6376 6377 (gdb) echo Hello World 6378 <<<---Hello World--->>> 6379 (gdb) 6380 6381 You can define a hook for any single-word command in GDB, but not 6382for command aliases; you should define a hook for the basic command 6383name, e.g. `backtrace' rather than `bt'. If an error occurs during 6384the execution of your hook, execution of GDB commands stops and GDB 6385issues a prompt (before the command that you actually typed had a 6386chance to run). 6387 6388 If you try to define a hook which does not match any known command, 6389you get a warning from the `define' command. 6390 6391 6392File: gdb.info, Node: Command Files, Next: Output, Prev: Hooks, Up: Sequences 6393 639420.3 Command Files 6395================== 6396 6397A command file for GDB is a text file made of lines that are GDB 6398commands. Comments (lines starting with `#') may also be included. An 6399empty line in a command file does nothing; it does not mean to repeat 6400the last command, as it would from the terminal. 6401 6402 You can request the execution of a command file with the `source' 6403command: 6404 6405`source [`-v'] FILENAME' 6406 Execute the command file FILENAME. 6407 6408 The lines in a command file are generally executed sequentially, 6409unless the order of execution is changed by one of the _flow-control 6410commands_ described below. The commands are not printed as they are 6411executed. An error in any command terminates execution of the command 6412file and control is returned to the console. 6413 6414 GDB searches for FILENAME in the current directory and then on the 6415search path (specified with the `directory' command). 6416 6417 If `-v', for verbose mode, is given then GDB displays each command 6418as it is executed. The option must be given before FILENAME, and is 6419interpreted as part of the filename anywhere else. 6420 6421 Commands that would ask for confirmation if used interactively 6422proceed without asking when used in a command file. Many GDB commands 6423that normally print messages to say what they are doing omit the 6424messages when called from command files. 6425 6426 GDB also accepts command input from standard input. In this mode, 6427normal output goes to standard output and error output goes to standard 6428error. Errors in a command file supplied on standard input do not 6429terminate execution of the command file--execution continues with the 6430next command. 6431 6432 gdb < cmds > log 2>&1 6433 6434 (The syntax above will vary depending on the shell used.) This 6435example will execute commands from the file `cmds'. All output and 6436errors would be directed to `log'. 6437 6438 Since commands stored on command files tend to be more general than 6439commands typed interactively, they frequently need to deal with 6440complicated situations, such as different or unexpected values of 6441variables and symbols, changes in how the program being debugged is 6442built, etc. GDB provides a set of flow-control commands to deal with 6443these complexities. Using these commands, you can write complex 6444scripts that loop over data structures, execute commands conditionally, 6445etc. 6446 6447`if' 6448`else' 6449 This command allows to include in your script conditionally 6450 executed commands. The `if' command takes a single argument, which 6451 is an expression to evaluate. It is followed by a series of 6452 commands that are executed only if the expression is true (its 6453 value is nonzero). There can then optionally be an `else' line, 6454 followed by a series of commands that are only executed if the 6455 expression was false. The end of the list is marked by a line 6456 containing `end'. 6457 6458`while' 6459 This command allows to write loops. Its syntax is similar to 6460 `if': the command takes a single argument, which is an expression 6461 to evaluate, and must be followed by the commands to execute, one 6462 per line, terminated by an `end'. These commands are called the 6463 "body" of the loop. The commands in the body of `while' are 6464 executed repeatedly as long as the expression evaluates to true. 6465 6466`loop_break' 6467 This command exits the `while' loop in whose body it is included. 6468 Execution of the script continues after that `while's `end' line. 6469 6470`loop_continue' 6471 This command skips the execution of the rest of the body of 6472 commands in the `while' loop in whose body it is included. 6473 Execution branches to the beginning of the `while' loop, where it 6474 evaluates the controlling expression. 6475 6476`end' 6477 Terminate the block of commands that are the body of `if', `else', 6478 or `while' flow-control commands. 6479 6480 6481File: gdb.info, Node: Output, Prev: Command Files, Up: Sequences 6482 648320.4 Commands for Controlled Output 6484=================================== 6485 6486During the execution of a command file or a user-defined command, normal 6487GDB output is suppressed; the only output that appears is what is 6488explicitly printed by the commands in the definition. This section 6489describes three commands useful for generating exactly the output you 6490want. 6491 6492`echo TEXT' 6493 Print TEXT. Nonprinting characters can be included in TEXT using 6494 C escape sequences, such as `\n' to print a newline. *No newline 6495 is printed unless you specify one.* In addition to the standard C 6496 escape sequences, a backslash followed by a space stands for a 6497 space. This is useful for displaying a string with spaces at the 6498 beginning or the end, since leading and trailing spaces are 6499 otherwise trimmed from all arguments. To print ` and foo = ', use 6500 the command `echo \ and foo = \ '. 6501 6502 A backslash at the end of TEXT can be used, as in C, to continue 6503 the command onto subsequent lines. For example, 6504 6505 echo This is some text\n\ 6506 which is continued\n\ 6507 onto several lines.\n 6508 6509 produces the same output as 6510 6511 echo This is some text\n 6512 echo which is continued\n 6513 echo onto several lines.\n 6514 6515`output EXPRESSION' 6516 Print the value of EXPRESSION and nothing but that value: no 6517 newlines, no `$NN = '. The value is not entered in the value 6518 history either. *Note Expressions: Expressions, for more 6519 information on expressions. 6520 6521`output/FMT EXPRESSION' 6522 Print the value of EXPRESSION in format FMT. You can use the same 6523 formats as for `print'. *Note Output Formats: Output Formats, for 6524 more information. 6525 6526`printf STRING, EXPRESSIONS...' 6527 Print the values of the EXPRESSIONS under the control of STRING. 6528 The EXPRESSIONS are separated by commas and may be either numbers 6529 or pointers. Their values are printed as specified by STRING, 6530 exactly as if your program were to execute the C subroutine 6531 6532 printf (STRING, EXPRESSIONS...); 6533 6534 For example, you can print two values in hex like this: 6535 6536 printf "foo, bar-foo = 0x%x, 0x%x\n", foo, bar-foo 6537 6538 The only backslash-escape sequences that you can use in the format 6539 string are the simple ones that consist of backslash followed by a 6540 letter. 6541 6542 6543File: gdb.info, Node: Interpreters, Next: TUI, Prev: Sequences, Up: Top 6544 654521 Command Interpreters 6546*********************** 6547 6548GDB supports multiple command interpreters, and some command 6549infrastructure to allow users or user interface writers to switch 6550between interpreters or run commands in other interpreters. 6551 6552 GDB currently supports two command interpreters, the console 6553interpreter (sometimes called the command-line interpreter or CLI) and 6554the machine interface interpreter (or GDB/MI). This manual describes 6555both of these interfaces in great detail. 6556 6557 By default, GDB will start with the console interpreter. However, 6558the user may choose to start GDB with another interpreter by specifying 6559the `-i' or `--interpreter' startup options. Defined interpreters 6560include: 6561 6562`console' 6563 The traditional console or command-line interpreter. This is the 6564 most often used interpreter with GDB. With no interpreter 6565 specified at runtime, GDB will use this interpreter. 6566 6567`mi' 6568 The newest GDB/MI interface (currently `mi2'). Used primarily by 6569 programs wishing to use GDB as a backend for a debugger GUI or an 6570 IDE. For more information, see *Note The GDB/MI Interface: GDB/MI. 6571 6572`mi2' 6573 The current GDB/MI interface. 6574 6575`mi1' 6576 The GDB/MI interface included in GDB 5.1, 5.2, and 5.3. 6577 6578 6579 The interpreter being used by GDB may not be dynamically switched at 6580runtime. Although possible, this could lead to a very precarious 6581situation. Consider an IDE using GDB/MI. If a user enters the command 6582"interpreter-set console" in a console view, GDB would switch to using 6583the console interpreter, rendering the IDE inoperable! 6584 6585 Although you may only choose a single interpreter at startup, you 6586may execute commands in any interpreter from the current interpreter 6587using the appropriate command. If you are running the console 6588interpreter, simply use the `interpreter-exec' command: 6589 6590 interpreter-exec mi "-data-list-register-names" 6591 6592 GDB/MI has a similar command, although it is only available in 6593versions of GDB which support GDB/MI version 2 (or greater). 6594 6595 6596File: gdb.info, Node: TUI, Next: Emacs, Prev: Interpreters, Up: Top 6597 659822 GDB Text User Interface 6599************************** 6600 6601* Menu: 6602 6603* TUI Overview:: TUI overview 6604* TUI Keys:: TUI key bindings 6605* TUI Single Key Mode:: TUI single key mode 6606* TUI Commands:: TUI-specific commands 6607* TUI Configuration:: TUI configuration variables 6608 6609 The GDB Text User Interface (TUI) is a terminal interface which uses 6610the `curses' library to show the source file, the assembly output, the 6611program registers and GDB commands in separate text windows. The TUI 6612mode is supported only on platforms where a suitable version of the 6613`curses' library is available. 6614 6615 The TUI mode is enabled by default when you invoke GDB as either 6616`gdbtui' or `gdb -tui'. You can also switch in and out of TUI mode 6617while GDB runs by using various TUI commands and key bindings, such as 6618`C-x C-a'. *Note TUI Key Bindings: TUI Keys. 6619 6620 6621File: gdb.info, Node: TUI Overview, Next: TUI Keys, Up: TUI 6622 662322.1 TUI Overview 6624================= 6625 6626In TUI mode, GDB can display several text windows: 6627 6628_command_ 6629 This window is the GDB command window with the GDB prompt and the 6630 GDB output. The GDB input is still managed using readline. 6631 6632_source_ 6633 The source window shows the source file of the program. The 6634 current line and active breakpoints are displayed in this window. 6635 6636_assembly_ 6637 The assembly window shows the disassembly output of the program. 6638 6639_register_ 6640 This window shows the processor registers. Registers are 6641 highlighted when their values change. 6642 6643 The source and assembly windows show the current program position by 6644highlighting the current line and marking it with a `>' marker. 6645Breakpoints are indicated with two markers. The first marker indicates 6646the breakpoint type: 6647 6648`B' 6649 Breakpoint which was hit at least once. 6650 6651`b' 6652 Breakpoint which was never hit. 6653 6654`H' 6655 Hardware breakpoint which was hit at least once. 6656 6657`h' 6658 Hardware breakpoint which was never hit. 6659 6660 The second marker indicates whether the breakpoint is enabled or not: 6661 6662`+' 6663 Breakpoint is enabled. 6664 6665`-' 6666 Breakpoint is disabled. 6667 6668 The source, assembly and register windows are updated when the 6669current thread changes, when the frame changes, or when the program 6670counter changes. 6671 6672 These windows are not all visible at the same time. The command 6673window is always visible. The others can be arranged in several 6674layouts: 6675 6676 * source only, 6677 6678 * assembly only, 6679 6680 * source and assembly, 6681 6682 * source and registers, or 6683 6684 * assembly and registers. 6685 6686 A status line above the command window shows the following 6687information: 6688 6689_target_ 6690 Indicates the current GDB target. (*note Specifying a Debugging 6691 Target: Targets.). 6692 6693_process_ 6694 Gives the current process or thread number. When no process is 6695 being debugged, this field is set to `No process'. 6696 6697_function_ 6698 Gives the current function name for the selected frame. The name 6699 is demangled if demangling is turned on (*note Print Settings::). 6700 When there is no symbol corresponding to the current program 6701 counter, the string `??' is displayed. 6702 6703_line_ 6704 Indicates the current line number for the selected frame. When 6705 the current line number is not known, the string `??' is displayed. 6706 6707_pc_ 6708 Indicates the current program counter address. 6709 6710 6711File: gdb.info, Node: TUI Keys, Next: TUI Single Key Mode, Prev: TUI Overview, Up: TUI 6712 671322.2 TUI Key Bindings 6714===================== 6715 6716The TUI installs several key bindings in the readline keymaps (*note 6717Command Line Editing::). The following key bindings are installed for 6718both TUI mode and the GDB standard mode. 6719 6720`C-x C-a' 6721`C-x a' 6722`C-x A' 6723 Enter or leave the TUI mode. When leaving the TUI mode, the 6724 curses window management stops and GDB operates using its standard 6725 mode, writing on the terminal directly. When reentering the TUI 6726 mode, control is given back to the curses windows. The screen is 6727 then refreshed. 6728 6729`C-x 1' 6730 Use a TUI layout with only one window. The layout will either be 6731 `source' or `assembly'. When the TUI mode is not active, it will 6732 switch to the TUI mode. 6733 6734 Think of this key binding as the Emacs `C-x 1' binding. 6735 6736`C-x 2' 6737 Use a TUI layout with at least two windows. When the current 6738 layout already has two windows, the next layout with two windows 6739 is used. When a new layout is chosen, one window will always be 6740 common to the previous layout and the new one. 6741 6742 Think of it as the Emacs `C-x 2' binding. 6743 6744`C-x o' 6745 Change the active window. The TUI associates several key bindings 6746 (like scrolling and arrow keys) with the active window. This 6747 command gives the focus to the next TUI window. 6748 6749 Think of it as the Emacs `C-x o' binding. 6750 6751`C-x s' 6752 Switch in and out of the TUI SingleKey mode that binds single keys 6753 to GDB commands (*note TUI Single Key Mode::). 6754 6755 The following key bindings only work in the TUI mode: 6756 6757<PgUp> 6758 Scroll the active window one page up. 6759 6760<PgDn> 6761 Scroll the active window one page down. 6762 6763<Up> 6764 Scroll the active window one line up. 6765 6766<Down> 6767 Scroll the active window one line down. 6768 6769<Left> 6770 Scroll the active window one column left. 6771 6772<Right> 6773 Scroll the active window one column right. 6774 6775`C-L' 6776 Refresh the screen. 6777 6778 Because the arrow keys scroll the active window in the TUI mode, they 6779are not available for their normal use by readline unless the command 6780window has the focus. When another window is active, you must use 6781other readline key bindings such as `C-p', `C-n', `C-b' and `C-f' to 6782control the command window. 6783 6784 6785File: gdb.info, Node: TUI Single Key Mode, Next: TUI Commands, Prev: TUI Keys, Up: TUI 6786 678722.3 TUI Single Key Mode 6788======================== 6789 6790The TUI also provides a "SingleKey" mode, which binds several 6791frequently used GDB commands to single keys. Type `C-x s' to switch 6792into this mode, where the following key bindings are used: 6793 6794`c' 6795 continue 6796 6797`d' 6798 down 6799 6800`f' 6801 finish 6802 6803`n' 6804 next 6805 6806`q' 6807 exit the SingleKey mode. 6808 6809`r' 6810 run 6811 6812`s' 6813 step 6814 6815`u' 6816 up 6817 6818`v' 6819 info locals 6820 6821`w' 6822 where 6823 6824 Other keys temporarily switch to the GDB command prompt. The key 6825that was pressed is inserted in the editing buffer so that it is 6826possible to type most GDB commands without interaction with the TUI 6827SingleKey mode. Once the command is entered the TUI SingleKey mode is 6828restored. The only way to permanently leave this mode is by typing `q' 6829or `C-x s'. 6830 6831 6832File: gdb.info, Node: TUI Commands, Next: TUI Configuration, Prev: TUI Single Key Mode, Up: TUI 6833 683422.4 TUI-specific Commands 6835========================== 6836 6837The TUI has specific commands to control the text windows. These 6838commands are always available, even when GDB is not in the TUI mode. 6839When GDB is in the standard mode, most of these commands will 6840automatically switch to the TUI mode. 6841 6842`info win' 6843 List and give the size of all displayed windows. 6844 6845`layout next' 6846 Display the next layout. 6847 6848`layout prev' 6849 Display the previous layout. 6850 6851`layout src' 6852 Display the source window only. 6853 6854`layout asm' 6855 Display the assembly window only. 6856 6857`layout split' 6858 Display the source and assembly window. 6859 6860`layout regs' 6861 Display the register window together with the source or assembly 6862 window. 6863 6864`focus next' 6865 Make the next window active for scrolling. 6866 6867`focus prev' 6868 Make the previous window active for scrolling. 6869 6870`focus src' 6871 Make the source window active for scrolling. 6872 6873`focus asm' 6874 Make the assembly window active for scrolling. 6875 6876`focus regs' 6877 Make the register window active for scrolling. 6878 6879`focus cmd' 6880 Make the command window active for scrolling. 6881 6882`refresh' 6883 Refresh the screen. This is similar to typing `C-L'. 6884 6885`tui reg float' 6886 Show the floating point registers in the register window. 6887 6888`tui reg general' 6889 Show the general registers in the register window. 6890 6891`tui reg next' 6892 Show the next register group. The list of register groups as well 6893 as their order is target specific. The predefined register groups 6894 are the following: `general', `float', `system', `vector', `all', 6895 `save', `restore'. 6896 6897`tui reg system' 6898 Show the system registers in the register window. 6899 6900`update' 6901 Update the source window and the current execution point. 6902 6903`winheight NAME +COUNT' 6904`winheight NAME -COUNT' 6905 Change the height of the window NAME by COUNT lines. Positive 6906 counts increase the height, while negative counts decrease it. 6907 6908`tabset NCHARS' 6909 Set the width of tab stops to be NCHARS characters. 6910 6911 6912File: gdb.info, Node: TUI Configuration, Prev: TUI Commands, Up: TUI 6913 691422.5 TUI Configuration Variables 6915================================ 6916 6917Several configuration variables control the appearance of TUI windows. 6918 6919`set tui border-kind KIND' 6920 Select the border appearance for the source, assembly and register 6921 windows. The possible values are the following: 6922 `space' 6923 Use a space character to draw the border. 6924 6925 `ascii' 6926 Use ASCII characters `+', `-' and `|' to draw the border. 6927 6928 `acs' 6929 Use the Alternate Character Set to draw the border. The 6930 border is drawn using character line graphics if the terminal 6931 supports them. 6932 6933`set tui border-mode MODE' 6934`set tui active-border-mode MODE' 6935 Select the display attributes for the borders of the inactive 6936 windows or the active window. The MODE can be one of the 6937 following: 6938 `normal' 6939 Use normal attributes to display the border. 6940 6941 `standout' 6942 Use standout mode. 6943 6944 `reverse' 6945 Use reverse video mode. 6946 6947 `half' 6948 Use half bright mode. 6949 6950 `half-standout' 6951 Use half bright and standout mode. 6952 6953 `bold' 6954 Use extra bright or bold mode. 6955 6956 `bold-standout' 6957 Use extra bright or bold and standout mode. 6958 6959 6960File: gdb.info, Node: Emacs, Next: GDB/MI, Prev: TUI, Up: Top 6961 696223 Using GDB under GNU Emacs 6963**************************** 6964 6965A special interface allows you to use GNU Emacs to view (and edit) the 6966source files for the program you are debugging with GDB. 6967 6968 To use this interface, use the command `M-x gdb' in Emacs. Give the 6969executable file you want to debug as an argument. This command starts 6970GDB as a subprocess of Emacs, with input and output through a newly 6971created Emacs buffer. 6972 6973 Running GDB under Emacs can be just like running GDB normally except 6974for two things: 6975 6976 * All "terminal" input and output goes through an Emacs buffer, 6977 called the GUD buffer. 6978 6979 This applies both to GDB commands and their output, and to the 6980 input and output done by the program you are debugging. 6981 6982 This is useful because it means that you can copy the text of 6983 previous commands and input them again; you can even use parts of 6984 the output in this way. 6985 6986 All the facilities of Emacs' Shell mode are available for 6987 interacting with your program. In particular, you can send 6988 signals the usual way--for example, `C-c C-c' for an interrupt, 6989 `C-c C-z' for a stop. 6990 6991 * GDB displays source code through Emacs. 6992 6993 Each time GDB displays a stack frame, Emacs automatically finds the 6994 source file for that frame and puts an arrow (`=>') at the left 6995 margin of the current line. Emacs uses a separate buffer for 6996 source display, and splits the screen to show both your GDB session 6997 and the source. 6998 6999 Explicit GDB `list' or search commands still produce output as 7000 usual, but you probably have no reason to use them from Emacs. 7001 7002 We call this "text command mode". Emacs 22.1, and later, also uses 7003a graphical mode, enabled by default, which provides further buffers 7004that can control the execution and describe the state of your program. 7005*Note GDB Graphical Interface: (Emacs)GDB Graphical Interface. 7006 7007 If you specify an absolute file name when prompted for the `M-x gdb' 7008argument, then Emacs sets your current working directory to where your 7009program resides. If you only specify the file name, then Emacs sets 7010your current working directory to to the directory associated with the 7011previous buffer. In this case, GDB may find your program by searching 7012your environment's `PATH' variable, but on some operating systems it 7013might not find the source. So, although the GDB input and output 7014session proceeds normally, the auxiliary buffer does not display the 7015current source and line of execution. 7016 7017 The initial working directory of GDB is printed on the top line of 7018the GUD buffer and this serves as a default for the commands that 7019specify files for GDB to operate on. *Note Commands to Specify Files: 7020Files. 7021 7022 By default, `M-x gdb' calls the program called `gdb'. If you need 7023to call GDB by a different name (for example, if you keep several 7024configurations around, with different names) you can customize the 7025Emacs variable `gud-gdb-command-name' to run the one you want. 7026 7027 In the GUD buffer, you can use these special Emacs commands in 7028addition to the standard Shell mode commands: 7029 7030`C-h m' 7031 Describe the features of Emacs' GUD Mode. 7032 7033`C-c C-s' 7034 Execute to another source line, like the GDB `step' command; also 7035 update the display window to show the current file and location. 7036 7037`C-c C-n' 7038 Execute to next source line in this function, skipping all function 7039 calls, like the GDB `next' command. Then update the display window 7040 to show the current file and location. 7041 7042`C-c C-i' 7043 Execute one instruction, like the GDB `stepi' command; update 7044 display window accordingly. 7045 7046`C-c C-f' 7047 Execute until exit from the selected stack frame, like the GDB 7048 `finish' command. 7049 7050`C-c C-r' 7051 Continue execution of your program, like the GDB `continue' 7052 command. 7053 7054`C-c <' 7055 Go up the number of frames indicated by the numeric argument 7056 (*note Numeric Arguments: (Emacs)Arguments.), like the GDB `up' 7057 command. 7058 7059`C-c >' 7060 Go down the number of frames indicated by the numeric argument, 7061 like the GDB `down' command. 7062 7063 In any source file, the Emacs command `C-x <SPC>' (`gud-break') 7064tells GDB to set a breakpoint on the source line point is on. 7065 7066 In text command mode, if you type `M-x speedbar', Emacs displays a 7067separate frame which shows a backtrace when the GUD buffer is current. 7068Move point to any frame in the stack and type <RET> to make it become 7069the current frame and display the associated source in the source 7070buffer. Alternatively, click `Mouse-2' to make the selected frame 7071become the current one. In graphical mode, the speedbar displays watch 7072expressions. 7073 7074 If you accidentally delete the source-display buffer, an easy way to 7075get it back is to type the command `f' in the GDB buffer, to request a 7076frame display; when you run under Emacs, this recreates the source 7077buffer if necessary to show you the context of the current frame. 7078 7079 The source files displayed in Emacs are in ordinary Emacs buffers 7080which are visiting the source files in the usual way. You can edit the 7081files with these buffers if you wish; but keep in mind that GDB 7082communicates with Emacs in terms of line numbers. If you add or delete 7083lines from the text, the line numbers that GDB knows cease to 7084correspond properly with the code. 7085 7086 A more detailed description of Emacs' interaction with GDB is given 7087in the Emacs manual (*note Debuggers: (Emacs)Debuggers.). 7088 7089 7090File: gdb.info, Node: GDB/MI, Next: Annotations, Prev: Emacs, Up: Top 7091 709224 The GDB/MI Interface 7093*********************** 7094 7095Function and Purpose 7096==================== 7097 7098GDB/MI is a line based machine oriented text interface to GDB and is 7099activated by specifying using the `--interpreter' command line option 7100(*note Mode Options::). It is specifically intended to support the 7101development of systems which use the debugger as just one small 7102component of a larger system. 7103 7104 This chapter is a specification of the GDB/MI interface. It is 7105written in the form of a reference manual. 7106 7107 Note that GDB/MI is still under construction, so some of the 7108features described below are incomplete and subject to change (*note 7109GDB/MI Development and Front Ends: GDB/MI Development and Front Ends.). 7110 7111Notation and Terminology 7112======================== 7113 7114This chapter uses the following notation: 7115 7116 * `|' separates two alternatives. 7117 7118 * `[ SOMETHING ]' indicates that SOMETHING is optional: it may or 7119 may not be given. 7120 7121 * `( GROUP )*' means that GROUP inside the parentheses may repeat 7122 zero or more times. 7123 7124 * `( GROUP )+' means that GROUP inside the parentheses may repeat 7125 one or more times. 7126 7127 * `"STRING"' means a literal STRING. 7128 7129* Menu: 7130 7131* GDB/MI Command Syntax:: 7132* GDB/MI Compatibility with CLI:: 7133* GDB/MI Development and Front Ends:: 7134* GDB/MI Output Records:: 7135* GDB/MI Simple Examples:: 7136* GDB/MI Command Description Format:: 7137* GDB/MI Breakpoint Commands:: 7138* GDB/MI Program Context:: 7139* GDB/MI Thread Commands:: 7140* GDB/MI Program Execution:: 7141* GDB/MI Stack Manipulation:: 7142* GDB/MI Variable Objects:: 7143* GDB/MI Data Manipulation:: 7144* GDB/MI Tracepoint Commands:: 7145* GDB/MI Symbol Query:: 7146* GDB/MI File Commands:: 7147* GDB/MI Target Manipulation:: 7148* GDB/MI Miscellaneous Commands:: 7149 7150 7151File: gdb.info, Node: GDB/MI Command Syntax, Next: GDB/MI Compatibility with CLI, Up: GDB/MI 7152 715324.1 GDB/MI Command Syntax 7154========================== 7155 7156* Menu: 7157 7158* GDB/MI Input Syntax:: 7159* GDB/MI Output Syntax:: 7160 7161 7162File: gdb.info, Node: GDB/MI Input Syntax, Next: GDB/MI Output Syntax, Up: GDB/MI Command Syntax 7163 716424.1.1 GDB/MI Input Syntax 7165-------------------------- 7166 7167`COMMAND ==>' 7168 `CLI-COMMAND | MI-COMMAND' 7169 7170`CLI-COMMAND ==>' 7171 `[ TOKEN ] CLI-COMMAND NL', where CLI-COMMAND is any existing GDB 7172 CLI command. 7173 7174`MI-COMMAND ==>' 7175 `[ TOKEN ] "-" OPERATION ( " " OPTION )* `[' " --" `]' ( " " 7176 PARAMETER )* NL' 7177 7178`TOKEN ==>' 7179 "any sequence of digits" 7180 7181`OPTION ==>' 7182 `"-" PARAMETER [ " " PARAMETER ]' 7183 7184`PARAMETER ==>' 7185 `NON-BLANK-SEQUENCE | C-STRING' 7186 7187`OPERATION ==>' 7188 _any of the operations described in this chapter_ 7189 7190`NON-BLANK-SEQUENCE ==>' 7191 _anything, provided it doesn't contain special characters such as 7192 "-", NL, """ and of course " "_ 7193 7194`C-STRING ==>' 7195 `""" SEVEN-BIT-ISO-C-STRING-CONTENT """' 7196 7197`NL ==>' 7198 `CR | CR-LF' 7199 7200Notes: 7201 7202 * The CLI commands are still handled by the MI interpreter; their 7203 output is described below. 7204 7205 * The `TOKEN', when present, is passed back when the command 7206 finishes. 7207 7208 * Some MI commands accept optional arguments as part of the parameter 7209 list. Each option is identified by a leading `-' (dash) and may be 7210 followed by an optional argument parameter. Options occur first 7211 in the parameter list and can be delimited from normal parameters 7212 using `--' (this is useful when some parameters begin with a dash). 7213 7214 Pragmatics: 7215 7216 * We want easy access to the existing CLI syntax (for debugging). 7217 7218 * We want it to be easy to spot a MI operation. 7219 7220 7221File: gdb.info, Node: GDB/MI Output Syntax, Prev: GDB/MI Input Syntax, Up: GDB/MI Command Syntax 7222 722324.1.2 GDB/MI Output Syntax 7224--------------------------- 7225 7226The output from GDB/MI consists of zero or more out-of-band records 7227followed, optionally, by a single result record. This result record is 7228for the most recent command. The sequence of output records is 7229terminated by `(gdb)'. 7230 7231 If an input command was prefixed with a `TOKEN' then the 7232corresponding output for that command will also be prefixed by that same 7233TOKEN. 7234 7235`OUTPUT ==>' 7236 `( OUT-OF-BAND-RECORD )* [ RESULT-RECORD ] "(gdb)" NL' 7237 7238`RESULT-RECORD ==>' 7239 ` [ TOKEN ] "^" RESULT-CLASS ( "," RESULT )* NL' 7240 7241`OUT-OF-BAND-RECORD ==>' 7242 `ASYNC-RECORD | STREAM-RECORD' 7243 7244`ASYNC-RECORD ==>' 7245 `EXEC-ASYNC-OUTPUT | STATUS-ASYNC-OUTPUT | NOTIFY-ASYNC-OUTPUT' 7246 7247`EXEC-ASYNC-OUTPUT ==>' 7248 `[ TOKEN ] "*" ASYNC-OUTPUT' 7249 7250`STATUS-ASYNC-OUTPUT ==>' 7251 `[ TOKEN ] "+" ASYNC-OUTPUT' 7252 7253`NOTIFY-ASYNC-OUTPUT ==>' 7254 `[ TOKEN ] "=" ASYNC-OUTPUT' 7255 7256`ASYNC-OUTPUT ==>' 7257 `ASYNC-CLASS ( "," RESULT )* NL' 7258 7259`RESULT-CLASS ==>' 7260 `"done" | "running" | "connected" | "error" | "exit"' 7261 7262`ASYNC-CLASS ==>' 7263 `"stopped" | OTHERS' (where OTHERS will be added depending on the 7264 needs--this is still in development). 7265 7266`RESULT ==>' 7267 ` VARIABLE "=" VALUE' 7268 7269`VARIABLE ==>' 7270 ` STRING ' 7271 7272`VALUE ==>' 7273 ` CONST | TUPLE | LIST ' 7274 7275`CONST ==>' 7276 `C-STRING' 7277 7278`TUPLE ==>' 7279 ` "{}" | "{" RESULT ( "," RESULT )* "}" ' 7280 7281`LIST ==>' 7282 ` "[]" | "[" VALUE ( "," VALUE )* "]" | "[" RESULT ( "," RESULT )* 7283 "]" ' 7284 7285`STREAM-RECORD ==>' 7286 `CONSOLE-STREAM-OUTPUT | TARGET-STREAM-OUTPUT | LOG-STREAM-OUTPUT' 7287 7288`CONSOLE-STREAM-OUTPUT ==>' 7289 `"~" C-STRING' 7290 7291`TARGET-STREAM-OUTPUT ==>' 7292 `"@" C-STRING' 7293 7294`LOG-STREAM-OUTPUT ==>' 7295 `"&" C-STRING' 7296 7297`NL ==>' 7298 `CR | CR-LF' 7299 7300`TOKEN ==>' 7301 _any sequence of digits_. 7302 7303Notes: 7304 7305 * All output sequences end in a single line containing a period. 7306 7307 * The `TOKEN' is from the corresponding request. If an execution 7308 command is interrupted by the `-exec-interrupt' command, the TOKEN 7309 associated with the `*stopped' message is the one of the original 7310 execution command, not the one of the interrupt command. 7311 7312 * STATUS-ASYNC-OUTPUT contains on-going status information about the 7313 progress of a slow operation. It can be discarded. All status 7314 output is prefixed by `+'. 7315 7316 * EXEC-ASYNC-OUTPUT contains asynchronous state change on the target 7317 (stopped, started, disappeared). All async output is prefixed by 7318 `*'. 7319 7320 * NOTIFY-ASYNC-OUTPUT contains supplementary information that the 7321 client should handle (e.g., a new breakpoint information). All 7322 notify output is prefixed by `='. 7323 7324 * CONSOLE-STREAM-OUTPUT is output that should be displayed as is in 7325 the console. It is the textual response to a CLI command. All 7326 the console output is prefixed by `~'. 7327 7328 * TARGET-STREAM-OUTPUT is the output produced by the target program. 7329 All the target output is prefixed by `@'. 7330 7331 * LOG-STREAM-OUTPUT is output text coming from GDB's internals, for 7332 instance messages that should be displayed as part of an error 7333 log. All the log output is prefixed by `&'. 7334 7335 * New GDB/MI commands should only output LISTS containing VALUES. 7336 7337 7338 *Note GDB/MI Stream Records: GDB/MI Stream Records, for more details 7339about the various output records. 7340 7341 7342File: gdb.info, Node: GDB/MI Compatibility with CLI, Next: GDB/MI Development and Front Ends, Prev: GDB/MI Command Syntax, Up: GDB/MI 7343 734424.2 GDB/MI Compatibility with CLI 7345================================== 7346 7347For the developers convenience CLI commands can be entered directly, 7348but there may be some unexpected behaviour. For example, commands that 7349query the user will behave as if the user replied yes, breakpoint 7350command lists are not executed and some CLI commands, such as `if', 7351`when' and `define', prompt for further input with `>', which is not 7352valid MI output. 7353 7354 This feature may be removed at some stage in the future and it is 7355recommended that front ends use the `-interpreter-exec' command (*note 7356-interpreter-exec::). 7357 7358 7359File: gdb.info, Node: GDB/MI Development and Front Ends, Next: GDB/MI Output Records, Prev: GDB/MI Compatibility with CLI, Up: GDB/MI 7360 736124.3 GDB/MI Development and Front Ends 7362====================================== 7363 7364The application which takes the MI output and presents the state of the 7365program being debugged to the user is called a "front end". 7366 7367 Although GDB/MI is still incomplete, it is currently being used by a 7368variety of front ends to GDB. This makes it difficult to introduce new 7369functionality without breaking existing usage. This section tries to 7370minimize the problems by describing how the protocol might change. 7371 7372 Some changes in MI need not break a carefully designed front end, and 7373for these the MI version will remain unchanged. The following is a 7374list of changes that may occur within one level, so front ends should 7375parse MI output in a way that can handle them: 7376 7377 * New MI commands may be added. 7378 7379 * New fields may be added to the output of any MI command. 7380 7381 * The range of values for fields with specified values, e.g., 7382 `in_scope' (*note -var-update::) may be extended. 7383 7384 7385 If the changes are likely to break front ends, the MI version level 7386will be increased by one. This will allow the front end to parse the 7387output according to the MI version. Apart from mi0, new versions of 7388GDB will not support old versions of MI and it will be the 7389responsibility of the front end to work with the new one. 7390 7391 The best way to avoid unexpected changes in MI that might break your 7392front end is to make your project known to GDB developers and follow 7393development on <gdb@sourceware.org> and <gdb-patches@sourceware.org>. 7394There is also the mailing list <dmi-discuss@lists.freestandards.org>, 7395hosted by the Free Standards Group, which has the aim of creating a 7396more general MI protocol called Debugger Machine Interface (DMI) that 7397will become a standard for all debuggers, not just GDB. 7398 7399 7400File: gdb.info, Node: GDB/MI Output Records, Next: GDB/MI Simple Examples, Prev: GDB/MI Development and Front Ends, Up: GDB/MI 7401 740224.4 GDB/MI Output Records 7403========================== 7404 7405* Menu: 7406 7407* GDB/MI Result Records:: 7408* GDB/MI Stream Records:: 7409* GDB/MI Out-of-band Records:: 7410 7411 7412File: gdb.info, Node: GDB/MI Result Records, Next: GDB/MI Stream Records, Up: GDB/MI Output Records 7413 741424.4.1 GDB/MI Result Records 7415---------------------------- 7416 7417In addition to a number of out-of-band notifications, the response to a 7418GDB/MI command includes one of the following result indications: 7419 7420`"^done" [ "," RESULTS ]' 7421 The synchronous operation was successful, `RESULTS' are the return 7422 values. 7423 7424`"^running"' 7425 The asynchronous operation was successfully started. The target is 7426 running. 7427 7428`"^connected"' 7429 GDB has connected to a remote target. 7430 7431`"^error" "," C-STRING' 7432 The operation failed. The `C-STRING' contains the corresponding 7433 error message. 7434 7435`"^exit"' 7436 GDB has terminated. 7437 7438 7439 7440File: gdb.info, Node: GDB/MI Stream Records, Next: GDB/MI Out-of-band Records, Prev: GDB/MI Result Records, Up: GDB/MI Output Records 7441 744224.4.2 GDB/MI Stream Records 7443---------------------------- 7444 7445GDB internally maintains a number of output streams: the console, the 7446target, and the log. The output intended for each of these streams is 7447funneled through the GDB/MI interface using "stream records". 7448 7449 Each stream record begins with a unique "prefix character" which 7450identifies its stream (*note GDB/MI Output Syntax: GDB/MI Output 7451Syntax.). In addition to the prefix, each stream record contains a 7452`STRING-OUTPUT'. This is either raw text (with an implicit new line) 7453or a quoted C string (which does not contain an implicit newline). 7454 7455`"~" STRING-OUTPUT' 7456 The console output stream contains text that should be displayed 7457 in the CLI console window. It contains the textual responses to 7458 CLI commands. 7459 7460`"@" STRING-OUTPUT' 7461 The target output stream contains any textual output from the 7462 running target. This is only present when GDB's event loop is 7463 truly asynchronous, which is currently only the case for remote 7464 targets. 7465 7466`"&" STRING-OUTPUT' 7467 The log stream contains debugging messages being produced by GDB's 7468 internals. 7469 7470 7471File: gdb.info, Node: GDB/MI Out-of-band Records, Prev: GDB/MI Stream Records, Up: GDB/MI Output Records 7472 747324.4.3 GDB/MI Out-of-band Records 7474--------------------------------- 7475 7476"Out-of-band" records are used to notify the GDB/MI client of 7477additional changes that have occurred. Those changes can either be a 7478consequence of GDB/MI (e.g., a breakpoint modified) or a result of 7479target activity (e.g., target stopped). 7480 7481 The following is a preliminary list of possible out-of-band records. 7482In particular, the EXEC-ASYNC-OUTPUT records. 7483 7484`*stopped,reason="REASON"' 7485 7486 REASON can be one of the following: 7487 7488`breakpoint-hit' 7489 A breakpoint was reached. 7490 7491`watchpoint-trigger' 7492 A watchpoint was triggered. 7493 7494`read-watchpoint-trigger' 7495 A read watchpoint was triggered. 7496 7497`access-watchpoint-trigger' 7498 An access watchpoint was triggered. 7499 7500`function-finished' 7501 An -exec-finish or similar CLI command was accomplished. 7502 7503`location-reached' 7504 An -exec-until or similar CLI command was accomplished. 7505 7506`watchpoint-scope' 7507 A watchpoint has gone out of scope. 7508 7509`end-stepping-range' 7510 An -exec-next, -exec-next-instruction, -exec-step, 7511 -exec-step-instruction or similar CLI command was accomplished. 7512 7513`exited-signalled' 7514 The inferior exited because of a signal. 7515 7516`exited' 7517 The inferior exited. 7518 7519`exited-normally' 7520 The inferior exited normally. 7521 7522`signal-received' 7523 A signal was received by the inferior. 7524 7525 7526File: gdb.info, Node: GDB/MI Simple Examples, Next: GDB/MI Command Description Format, Prev: GDB/MI Output Records, Up: GDB/MI 7527 752824.5 Simple Examples of GDB/MI Interaction 7529========================================== 7530 7531This subsection presents several simple examples of interaction using 7532the GDB/MI interface. In these examples, `->' means that the following 7533line is passed to GDB/MI as input, while `<-' means the output received 7534from GDB/MI. 7535 7536 Note the line breaks shown in the examples are here only for 7537readability, they don't appear in the real output. 7538 7539Setting a Breakpoint 7540-------------------- 7541 7542Setting a breakpoint generates synchronous output which contains 7543detailed information of the breakpoint. 7544 7545 -> -break-insert main 7546 <- ^done,bkpt={number="1",type="breakpoint",disp="keep", 7547 enabled="y",addr="0x08048564",func="main",file="myprog.c", 7548 fullname="/home/nickrob/myprog.c",line="68",times="0"} 7549 <- (gdb) 7550 7551Program Execution 7552----------------- 7553 7554Program execution generates asynchronous records and MI gives the 7555reason that execution stopped. 7556 7557 -> -exec-run 7558 <- ^running 7559 <- (gdb) 7560 <- *stopped,reason="breakpoint-hit",bkptno="1",thread-id="0", 7561 frame={addr="0x08048564",func="main", 7562 args=[{name="argc",value="1"},{name="argv",value="0xbfc4d4d4"}], 7563 file="myprog.c",fullname="/home/nickrob/myprog.c",line="68"} 7564 <- (gdb) 7565 -> -exec-continue 7566 <- ^running 7567 <- (gdb) 7568 <- *stopped,reason="exited-normally" 7569 <- (gdb) 7570 7571Quitting GDB 7572------------ 7573 7574Quitting GDB just prints the result class `^exit'. 7575 7576 -> (gdb) 7577 <- -gdb-exit 7578 <- ^exit 7579 7580A Bad Command 7581------------- 7582 7583Here's what happens if you pass a non-existent command: 7584 7585 -> -rubbish 7586 <- ^error,msg="Undefined MI command: rubbish" 7587 <- (gdb) 7588 7589 7590File: gdb.info, Node: GDB/MI Command Description Format, Next: GDB/MI Breakpoint Commands, Prev: GDB/MI Simple Examples, Up: GDB/MI 7591 759224.6 GDB/MI Command Description Format 7593====================================== 7594 7595The remaining sections describe blocks of commands. Each block of 7596commands is laid out in a fashion similar to this section. 7597 7598Motivation 7599---------- 7600 7601The motivation for this collection of commands. 7602 7603Introduction 7604------------ 7605 7606A brief introduction to this collection of commands as a whole. 7607 7608Commands 7609-------- 7610 7611For each command in the block, the following is described: 7612 7613Synopsis 7614........ 7615 7616 -command ARGS... 7617 7618Result 7619...... 7620 7621GDB Command 7622........... 7623 7624The corresponding GDB CLI command(s), if any. 7625 7626Example 7627....... 7628 7629Example(s) formatted for readability. Some of the described commands 7630have not been implemented yet and these are labeled N.A. (not 7631available). 7632 7633 7634File: gdb.info, Node: GDB/MI Breakpoint Commands, Next: GDB/MI Program Context, Prev: GDB/MI Command Description Format, Up: GDB/MI 7635 763624.7 GDB/MI Breakpoint Commands 7637=============================== 7638 7639This section documents GDB/MI commands for manipulating breakpoints. 7640 7641The `-break-after' Command 7642-------------------------- 7643 7644Synopsis 7645........ 7646 7647 -break-after NUMBER COUNT 7648 7649 The breakpoint number NUMBER is not in effect until it has been hit 7650COUNT times. To see how this is reflected in the output of the 7651`-break-list' command, see the description of the `-break-list' command 7652below. 7653 7654GDB Command 7655........... 7656 7657The corresponding GDB command is `ignore'. 7658 7659Example 7660....... 7661 7662 (gdb) 7663 -break-insert main 7664 ^done,bkpt={number="1",addr="0x000100d0",file="hello.c", 7665 fullname="/home/foo/hello.c",line="5",times="0"} 7666 (gdb) 7667 -break-after 1 3 7668 ~ 7669 ^done 7670 (gdb) 7671 -break-list 7672 ^done,BreakpointTable={nr_rows="1",nr_cols="6", 7673 hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"}, 7674 {width="14",alignment="-1",col_name="type",colhdr="Type"}, 7675 {width="4",alignment="-1",col_name="disp",colhdr="Disp"}, 7676 {width="3",alignment="-1",col_name="enabled",colhdr="Enb"}, 7677 {width="10",alignment="-1",col_name="addr",colhdr="Address"}, 7678 {width="40",alignment="2",col_name="what",colhdr="What"}], 7679 body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y", 7680 addr="0x000100d0",func="main",file="hello.c",fullname="/home/foo/hello.c", 7681 line="5",times="0",ignore="3"}]} 7682 (gdb) 7683 7684The `-break-condition' Command 7685------------------------------ 7686 7687Synopsis 7688........ 7689 7690 -break-condition NUMBER EXPR 7691 7692 Breakpoint NUMBER will stop the program only if the condition in 7693EXPR is true. The condition becomes part of the `-break-list' output 7694(see the description of the `-break-list' command below). 7695 7696GDB Command 7697........... 7698 7699The corresponding GDB command is `condition'. 7700 7701Example 7702....... 7703 7704 (gdb) 7705 -break-condition 1 1 7706 ^done 7707 (gdb) 7708 -break-list 7709 ^done,BreakpointTable={nr_rows="1",nr_cols="6", 7710 hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"}, 7711 {width="14",alignment="-1",col_name="type",colhdr="Type"}, 7712 {width="4",alignment="-1",col_name="disp",colhdr="Disp"}, 7713 {width="3",alignment="-1",col_name="enabled",colhdr="Enb"}, 7714 {width="10",alignment="-1",col_name="addr",colhdr="Address"}, 7715 {width="40",alignment="2",col_name="what",colhdr="What"}], 7716 body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y", 7717 addr="0x000100d0",func="main",file="hello.c",fullname="/home/foo/hello.c", 7718 line="5",cond="1",times="0",ignore="3"}]} 7719 (gdb) 7720 7721The `-break-delete' Command 7722--------------------------- 7723 7724Synopsis 7725........ 7726 7727 -break-delete ( BREAKPOINT )+ 7728 7729 Delete the breakpoint(s) whose number(s) are specified in the 7730argument list. This is obviously reflected in the breakpoint list. 7731 7732GDB Command 7733........... 7734 7735The corresponding GDB command is `delete'. 7736 7737Example 7738....... 7739 7740 (gdb) 7741 -break-delete 1 7742 ^done 7743 (gdb) 7744 -break-list 7745 ^done,BreakpointTable={nr_rows="0",nr_cols="6", 7746 hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"}, 7747 {width="14",alignment="-1",col_name="type",colhdr="Type"}, 7748 {width="4",alignment="-1",col_name="disp",colhdr="Disp"}, 7749 {width="3",alignment="-1",col_name="enabled",colhdr="Enb"}, 7750 {width="10",alignment="-1",col_name="addr",colhdr="Address"}, 7751 {width="40",alignment="2",col_name="what",colhdr="What"}], 7752 body=[]} 7753 (gdb) 7754 7755The `-break-disable' Command 7756---------------------------- 7757 7758Synopsis 7759........ 7760 7761 -break-disable ( BREAKPOINT )+ 7762 7763 Disable the named BREAKPOINT(s). The field `enabled' in the break 7764list is now set to `n' for the named BREAKPOINT(s). 7765 7766GDB Command 7767........... 7768 7769The corresponding GDB command is `disable'. 7770 7771Example 7772....... 7773 7774 (gdb) 7775 -break-disable 2 7776 ^done 7777 (gdb) 7778 -break-list 7779 ^done,BreakpointTable={nr_rows="1",nr_cols="6", 7780 hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"}, 7781 {width="14",alignment="-1",col_name="type",colhdr="Type"}, 7782 {width="4",alignment="-1",col_name="disp",colhdr="Disp"}, 7783 {width="3",alignment="-1",col_name="enabled",colhdr="Enb"}, 7784 {width="10",alignment="-1",col_name="addr",colhdr="Address"}, 7785 {width="40",alignment="2",col_name="what",colhdr="What"}], 7786 body=[bkpt={number="2",type="breakpoint",disp="keep",enabled="n", 7787 addr="0x000100d0",func="main",file="hello.c",fullname="/home/foo/hello.c", 7788 line="5",times="0"}]} 7789 (gdb) 7790 7791The `-break-enable' Command 7792--------------------------- 7793 7794Synopsis 7795........ 7796 7797 -break-enable ( BREAKPOINT )+ 7798 7799 Enable (previously disabled) BREAKPOINT(s). 7800 7801GDB Command 7802........... 7803 7804The corresponding GDB command is `enable'. 7805 7806Example 7807....... 7808 7809 (gdb) 7810 -break-enable 2 7811 ^done 7812 (gdb) 7813 -break-list 7814 ^done,BreakpointTable={nr_rows="1",nr_cols="6", 7815 hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"}, 7816 {width="14",alignment="-1",col_name="type",colhdr="Type"}, 7817 {width="4",alignment="-1",col_name="disp",colhdr="Disp"}, 7818 {width="3",alignment="-1",col_name="enabled",colhdr="Enb"}, 7819 {width="10",alignment="-1",col_name="addr",colhdr="Address"}, 7820 {width="40",alignment="2",col_name="what",colhdr="What"}], 7821 body=[bkpt={number="2",type="breakpoint",disp="keep",enabled="y", 7822 addr="0x000100d0",func="main",file="hello.c",fullname="/home/foo/hello.c", 7823 line="5",times="0"}]} 7824 (gdb) 7825 7826The `-break-info' Command 7827------------------------- 7828 7829Synopsis 7830........ 7831 7832 -break-info BREAKPOINT 7833 7834 Get information about a single breakpoint. 7835 7836GDB Command 7837........... 7838 7839The corresponding GDB command is `info break BREAKPOINT'. 7840 7841Example 7842....... 7843 7844N.A. 7845 7846The `-break-insert' Command 7847--------------------------- 7848 7849Synopsis 7850........ 7851 7852 -break-insert [ -t ] [ -h ] [ -r ] 7853 [ -c CONDITION ] [ -i IGNORE-COUNT ] 7854 [ -p THREAD ] [ LINE | ADDR ] 7855 7856If specified, LINE, can be one of: 7857 7858 * function 7859 7860 * filename:linenum 7861 7862 * filename:function 7863 7864 * *address 7865 7866 The possible optional parameters of this command are: 7867 7868`-t' 7869 Insert a temporary breakpoint. 7870 7871`-h' 7872 Insert a hardware breakpoint. 7873 7874`-c CONDITION' 7875 Make the breakpoint conditional on CONDITION. 7876 7877`-i IGNORE-COUNT' 7878 Initialize the IGNORE-COUNT. 7879 7880`-r' 7881 Insert a regular breakpoint in all the functions whose names match 7882 the given regular expression. Other flags are not applicable to 7883 regular expressions. 7884 7885Result 7886...... 7887 7888The result is in the form: 7889 7890 ^done,bkpt={number="NUMBER",type="TYPE",disp="del"|"keep", 7891 enabled="y"|"n",addr="HEX",func="FUNCNAME",file="FILENAME", 7892 fullname="FULL_FILENAME",line="LINENO",[thread="THREADNO,] 7893 times="TIMES"} 7894 7895where NUMBER is the GDB number for this breakpoint, FUNCNAME is the 7896name of the function where the breakpoint was inserted, FILENAME is the 7897name of the source file which contains this function, LINENO is the 7898source line number within that file and TIMES the number of times that 7899the breakpoint has been hit (always 0 for -break-insert but may be 7900greater for -break-info or -break-list which use the same output). 7901 7902 Note: this format is open to change. 7903 7904GDB Command 7905........... 7906 7907The corresponding GDB commands are `break', `tbreak', `hbreak', 7908`thbreak', and `rbreak'. 7909 7910Example 7911....... 7912 7913 (gdb) 7914 -break-insert main 7915 ^done,bkpt={number="1",addr="0x0001072c",file="recursive2.c", 7916 fullname="/home/foo/recursive2.c,line="4",times="0"} 7917 (gdb) 7918 -break-insert -t foo 7919 ^done,bkpt={number="2",addr="0x00010774",file="recursive2.c", 7920 fullname="/home/foo/recursive2.c,line="11",times="0"} 7921 (gdb) 7922 -break-list 7923 ^done,BreakpointTable={nr_rows="2",nr_cols="6", 7924 hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"}, 7925 {width="14",alignment="-1",col_name="type",colhdr="Type"}, 7926 {width="4",alignment="-1",col_name="disp",colhdr="Disp"}, 7927 {width="3",alignment="-1",col_name="enabled",colhdr="Enb"}, 7928 {width="10",alignment="-1",col_name="addr",colhdr="Address"}, 7929 {width="40",alignment="2",col_name="what",colhdr="What"}], 7930 body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y", 7931 addr="0x0001072c", func="main",file="recursive2.c", 7932 fullname="/home/foo/recursive2.c,"line="4",times="0"}, 7933 bkpt={number="2",type="breakpoint",disp="del",enabled="y", 7934 addr="0x00010774",func="foo",file="recursive2.c", 7935 fullname="/home/foo/recursive2.c",line="11",times="0"}]} 7936 (gdb) 7937 -break-insert -r foo.* 7938 ~int foo(int, int); 7939 ^done,bkpt={number="3",addr="0x00010774",file="recursive2.c, 7940 "fullname="/home/foo/recursive2.c",line="11",times="0"} 7941 (gdb) 7942 7943The `-break-list' Command 7944------------------------- 7945 7946Synopsis 7947........ 7948 7949 -break-list 7950 7951 Displays the list of inserted breakpoints, showing the following 7952fields: 7953 7954`Number' 7955 number of the breakpoint 7956 7957`Type' 7958 type of the breakpoint: `breakpoint' or `watchpoint' 7959 7960`Disposition' 7961 should the breakpoint be deleted or disabled when it is hit: `keep' 7962 or `nokeep' 7963 7964`Enabled' 7965 is the breakpoint enabled or no: `y' or `n' 7966 7967`Address' 7968 memory location at which the breakpoint is set 7969 7970`What' 7971 logical location of the breakpoint, expressed by function name, 7972 file name, line number 7973 7974`Times' 7975 number of times the breakpoint has been hit 7976 7977 If there are no breakpoints or watchpoints, the `BreakpointTable' 7978`body' field is an empty list. 7979 7980GDB Command 7981........... 7982 7983The corresponding GDB command is `info break'. 7984 7985Example 7986....... 7987 7988 (gdb) 7989 -break-list 7990 ^done,BreakpointTable={nr_rows="2",nr_cols="6", 7991 hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"}, 7992 {width="14",alignment="-1",col_name="type",colhdr="Type"}, 7993 {width="4",alignment="-1",col_name="disp",colhdr="Disp"}, 7994 {width="3",alignment="-1",col_name="enabled",colhdr="Enb"}, 7995 {width="10",alignment="-1",col_name="addr",colhdr="Address"}, 7996 {width="40",alignment="2",col_name="what",colhdr="What"}], 7997 body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y", 7998 addr="0x000100d0",func="main",file="hello.c",line="5",times="0"}, 7999 bkpt={number="2",type="breakpoint",disp="keep",enabled="y", 8000 addr="0x00010114",func="foo",file="hello.c",fullname="/home/foo/hello.c", 8001 line="13",times="0"}]} 8002 (gdb) 8003 8004 Here's an example of the result when there are no breakpoints: 8005 8006 (gdb) 8007 -break-list 8008 ^done,BreakpointTable={nr_rows="0",nr_cols="6", 8009 hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"}, 8010 {width="14",alignment="-1",col_name="type",colhdr="Type"}, 8011 {width="4",alignment="-1",col_name="disp",colhdr="Disp"}, 8012 {width="3",alignment="-1",col_name="enabled",colhdr="Enb"}, 8013 {width="10",alignment="-1",col_name="addr",colhdr="Address"}, 8014 {width="40",alignment="2",col_name="what",colhdr="What"}], 8015 body=[]} 8016 (gdb) 8017 8018The `-break-watch' Command 8019-------------------------- 8020 8021Synopsis 8022........ 8023 8024 -break-watch [ -a | -r ] 8025 8026 Create a watchpoint. With the `-a' option it will create an 8027"access" watchpoint, i.e., a watchpoint that triggers either on a read 8028from or on a write to the memory location. With the `-r' option, the 8029watchpoint created is a "read" watchpoint, i.e., it will trigger only 8030when the memory location is accessed for reading. Without either of 8031the options, the watchpoint created is a regular watchpoint, i.e., it 8032will trigger when the memory location is accessed for writing. *Note 8033Setting Watchpoints: Set Watchpoints. 8034 8035 Note that `-break-list' will report a single list of watchpoints and 8036breakpoints inserted. 8037 8038GDB Command 8039........... 8040 8041The corresponding GDB commands are `watch', `awatch', and `rwatch'. 8042 8043Example 8044....... 8045 8046Setting a watchpoint on a variable in the `main' function: 8047 8048 (gdb) 8049 -break-watch x 8050 ^done,wpt={number="2",exp="x"} 8051 (gdb) 8052 -exec-continue 8053 ^running 8054 (gdb) 8055 *stopped,reason="watchpoint-trigger",wpt={number="2",exp="x"}, 8056 value={old="-268439212",new="55"}, 8057 frame={func="main",args=[],file="recursive2.c", 8058 fullname="/home/foo/bar/recursive2.c",line="5"} 8059 (gdb) 8060 8061 Setting a watchpoint on a variable local to a function. GDB will 8062stop the program execution twice: first for the variable changing 8063value, then for the watchpoint going out of scope. 8064 8065 (gdb) 8066 -break-watch C 8067 ^done,wpt={number="5",exp="C"} 8068 (gdb) 8069 -exec-continue 8070 ^running 8071 (gdb) 8072 *stopped,reason="watchpoint-trigger", 8073 wpt={number="5",exp="C"},value={old="-276895068",new="3"}, 8074 frame={func="callee4",args=[], 8075 file="../../../devo/gdb/testsuite/gdb.mi/basics.c", 8076 fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="13"} 8077 (gdb) 8078 -exec-continue 8079 ^running 8080 (gdb) 8081 *stopped,reason="watchpoint-scope",wpnum="5", 8082 frame={func="callee3",args=[{name="strarg", 8083 value="0x11940 \"A string argument.\""}], 8084 file="../../../devo/gdb/testsuite/gdb.mi/basics.c", 8085 fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="18"} 8086 (gdb) 8087 8088 Listing breakpoints and watchpoints, at different points in the 8089program execution. Note that once the watchpoint goes out of scope, it 8090is deleted. 8091 8092 (gdb) 8093 -break-watch C 8094 ^done,wpt={number="2",exp="C"} 8095 (gdb) 8096 -break-list 8097 ^done,BreakpointTable={nr_rows="2",nr_cols="6", 8098 hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"}, 8099 {width="14",alignment="-1",col_name="type",colhdr="Type"}, 8100 {width="4",alignment="-1",col_name="disp",colhdr="Disp"}, 8101 {width="3",alignment="-1",col_name="enabled",colhdr="Enb"}, 8102 {width="10",alignment="-1",col_name="addr",colhdr="Address"}, 8103 {width="40",alignment="2",col_name="what",colhdr="What"}], 8104 body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y", 8105 addr="0x00010734",func="callee4", 8106 file="../../../devo/gdb/testsuite/gdb.mi/basics.c", 8107 fullname="/home/foo/devo/gdb/testsuite/gdb.mi/basics.c"line="8",times="1"}, 8108 bkpt={number="2",type="watchpoint",disp="keep", 8109 enabled="y",addr="",what="C",times="0"}]} 8110 (gdb) 8111 -exec-continue 8112 ^running 8113 (gdb) 8114 *stopped,reason="watchpoint-trigger",wpt={number="2",exp="C"}, 8115 value={old="-276895068",new="3"}, 8116 frame={func="callee4",args=[], 8117 file="../../../devo/gdb/testsuite/gdb.mi/basics.c", 8118 fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="13"} 8119 (gdb) 8120 -break-list 8121 ^done,BreakpointTable={nr_rows="2",nr_cols="6", 8122 hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"}, 8123 {width="14",alignment="-1",col_name="type",colhdr="Type"}, 8124 {width="4",alignment="-1",col_name="disp",colhdr="Disp"}, 8125 {width="3",alignment="-1",col_name="enabled",colhdr="Enb"}, 8126 {width="10",alignment="-1",col_name="addr",colhdr="Address"}, 8127 {width="40",alignment="2",col_name="what",colhdr="What"}], 8128 body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y", 8129 addr="0x00010734",func="callee4", 8130 file="../../../devo/gdb/testsuite/gdb.mi/basics.c", 8131 fullname="/home/foo/devo/gdb/testsuite/gdb.mi/basics.c",line="8",times="1"}, 8132 bkpt={number="2",type="watchpoint",disp="keep", 8133 enabled="y",addr="",what="C",times="-5"}]} 8134 (gdb) 8135 -exec-continue 8136 ^running 8137 ^done,reason="watchpoint-scope",wpnum="2", 8138 frame={func="callee3",args=[{name="strarg", 8139 value="0x11940 \"A string argument.\""}], 8140 file="../../../devo/gdb/testsuite/gdb.mi/basics.c", 8141 fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="18"} 8142 (gdb) 8143 -break-list 8144 ^done,BreakpointTable={nr_rows="1",nr_cols="6", 8145 hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"}, 8146 {width="14",alignment="-1",col_name="type",colhdr="Type"}, 8147 {width="4",alignment="-1",col_name="disp",colhdr="Disp"}, 8148 {width="3",alignment="-1",col_name="enabled",colhdr="Enb"}, 8149 {width="10",alignment="-1",col_name="addr",colhdr="Address"}, 8150 {width="40",alignment="2",col_name="what",colhdr="What"}], 8151 body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y", 8152 addr="0x00010734",func="callee4", 8153 file="../../../devo/gdb/testsuite/gdb.mi/basics.c", 8154 fullname="/home/foo/devo/gdb/testsuite/gdb.mi/basics.c",line="8", 8155 times="1"}]} 8156 (gdb) 8157 8158