diff options
Diffstat (limited to 'gnu/usr.bin/gdb/doc/gdb.info-6')
| -rw-r--r-- | gnu/usr.bin/gdb/doc/gdb.info-6 | 1220 |
1 files changed, 1220 insertions, 0 deletions
diff --git a/gnu/usr.bin/gdb/doc/gdb.info-6 b/gnu/usr.bin/gdb/doc/gdb.info-6 new file mode 100644 index 000000000000..8a746fd77b6d --- /dev/null +++ b/gnu/usr.bin/gdb/doc/gdb.info-6 @@ -0,0 +1,1220 @@ +This is Info file ./gdb.info, produced by Makeinfo-1.52 from the input +file gdb.texinfo. + +START-INFO-DIR-ENTRY +* Gdb:: The GNU debugger. +END-INFO-DIR-ENTRY + This file documents the GNU debugger GDB. + + This is Edition 4.09, August 1993, of `Debugging with GDB: the GNU +Source-Level Debugger' for GDB Version 4.11. + + Copyright (C) 1988, '89, '90, '91, '92, '93 Free Software +Foundation, Inc. + + Permission is granted to make and distribute verbatim copies of this +manual provided the copyright notice and this permission notice are +preserved on all copies. + + Permission is granted to copy and distribute modified versions of +this manual under the conditions for verbatim copying, provided also +that the entire resulting derived work is distributed under the terms +of a permission notice identical to this one. + + Permission is granted to copy and distribute translations of this +manual into another language, under the above conditions for modified +versions. + + +File: gdb.info, Node: Nindy Options, Next: Nindy Reset, Prev: Nindy Startup, Up: i960-Nindy Remote + +Options for Nindy +----------------- + + These are the startup options for beginning your GDB session with a +Nindy-960 board attached: + +`-r PORT' + Specify the serial port name of a serial interface to be used to + connect to the target system. This option is only available when + GDB is configured for the Intel 960 target architecture. You may + specify PORT as any of: a full pathname (e.g. `-r /dev/ttya'), a + device name in `/dev' (e.g. `-r ttya'), or simply the unique + suffix for a specific `tty' (e.g. `-r a'). + +`-O' + (An uppercase letter "O", not a zero.) Specify that GDB should use + the "old" Nindy monitor protocol to connect to the target system. + This option is only available when GDB is configured for the Intel + 960 target architecture. + + *Warning:* if you specify `-O', but are actually trying to + connect to a target system that expects the newer protocol, + the connection fails, appearing to be a speed mismatch. GDB + repeatedly attempts to reconnect at several different line + speeds. You can abort this process with an interrupt. + +`-brk' + Specify that GDB should first send a `BREAK' signal to the target + system, in an attempt to reset it, before connecting to a Nindy + target. + + *Warning:* Many target systems do not have the hardware that + this requires; it only works with a few boards. + + The standard `-b' option controls the line speed used on the serial +port. + + +File: gdb.info, Node: Nindy Reset, Prev: Nindy Options, Up: i960-Nindy Remote + +Nindy reset command +------------------- + +`reset' + For a Nindy target, this command sends a "break" to the remote + target system; this is only useful if the target has been equipped + with a circuit to perform a hard reset (or some other interesting + action) when a break is detected. + + +File: gdb.info, Node: UDI29K Remote, Next: EB29K Remote, Prev: i960-Nindy Remote, Up: Remote + +GDB and the UDI protocol for AMD29K +----------------------------------- + + GDB supports AMD's UDI ("Universal Debugger Interface") protocol for +debugging the a29k processor family. To use this configuration with +AMD targets running the MiniMON monitor, you need the program `MONTIP', +available from AMD at no charge. You can also use GDB with the UDI +conformant a29k simulator program `ISSTIP', also available from AMD. + +`target udi KEYWORD' + Select the UDI interface to a remote a29k board or simulator, where + KEYWORD is an entry in the AMD configuration file `udi_soc'. This + file contains keyword entries which specify parameters used to + connect to a29k targets. If the `udi_soc' file is not in your + working directory, you must set the environment variable `UDICONF' + to its pathname. + + +File: gdb.info, Node: EB29K Remote, Next: VxWorks Remote, Prev: UDI29K Remote, Up: Remote + +GDB and the EBMON protocol for AMD29K +------------------------------------- + + AMD distributes a 29K development board meant to fit in a PC, +together with a DOS-hosted monitor program called `EBMON'. As a +shorthand term, this development system is called the "EB29K". To use +GDB from a Unix system to run programs on the EB29K board, you must +first connect a serial cable between the PC (which hosts the EB29K +board) and a serial port on the Unix system. In the following, we +assume you've hooked the cable between the PC's `COM1' port and +`/dev/ttya' on the Unix system. + +* Menu: + +* Comms (EB29K):: Communications setup +* gdb-EB29K:: EB29K cross-debugging +* Remote Log:: Remote log + + +File: gdb.info, Node: Comms (EB29K), Next: gdb-EB29K, Up: EB29K Remote + +Communications setup +-------------------- + + The next step is to set up the PC's port, by doing something like +this in DOS on the PC: + + C:\> MODE com1:9600,n,8,1,none + +This example--run on an MS DOS 4.0 system--sets the PC port to 9600 +bps, no parity, eight data bits, one stop bit, and no "retry" action; +you must match the communications parameters when establishing the Unix +end of the connection as well. + + To give control of the PC to the Unix side of the serial line, type +the following at the DOS console: + + C:\> CTTY com1 + +(Later, if you wish to return control to the DOS console, you can use +the command `CTTY con'--but you must send it over the device that had +control, in our example over the `COM1' serial line). + + From the Unix host, use a communications program such as `tip' or +`cu' to communicate with the PC; for example, + + cu -s 9600 -l /dev/ttya + +The `cu' options shown specify, respectively, the linespeed and the +serial port to use. If you use `tip' instead, your command line may +look something like the following: + + tip -9600 /dev/ttya + +Your system may require a different name where we show `/dev/ttya' as +the argument to `tip'. The communications parameters, including which +port to use, are associated with the `tip' argument in the "remote" +descriptions file--normally the system table `/etc/remote'. + + Using the `tip' or `cu' connection, change the DOS working directory +to the directory containing a copy of your 29K program, then start the +PC program `EBMON' (an EB29K control program supplied with your board +by AMD). You should see an initial display from `EBMON' similar to the +one that follows, ending with the `EBMON' prompt `#'-- + + C:\> G: + + G:\> CD \usr\joe\work29k + + G:\USR\JOE\WORK29K> EBMON + Am29000 PC Coprocessor Board Monitor, version 3.0-18 + Copyright 1990 Advanced Micro Devices, Inc. + Written by Gibbons and Associates, Inc. + + Enter '?' or 'H' for help + + PC Coprocessor Type = EB29K + I/O Base = 0x208 + Memory Base = 0xd0000 + + Data Memory Size = 2048KB + Available I-RAM Range = 0x8000 to 0x1fffff + Available D-RAM Range = 0x80002000 to 0x801fffff + + PageSize = 0x400 + Register Stack Size = 0x800 + Memory Stack Size = 0x1800 + + CPU PRL = 0x3 + Am29027 Available = No + Byte Write Available = Yes + + # ~. + + Then exit the `cu' or `tip' program (done in the example by typing +`~.' at the `EBMON' prompt). `EBMON' will keep running, ready for GDB +to take over. + + For this example, we've assumed what is probably the most convenient +way to make sure the same 29K program is on both the PC and the Unix +system: a PC/NFS connection that establishes "drive `G:'" on the PC as +a file system on the Unix host. If you do not have PC/NFS or something +similar connecting the two systems, you must arrange some other +way--perhaps floppy-disk transfer--of getting the 29K program from the +Unix system to the PC; GDB will *not* download it over the serial line. + + +File: gdb.info, Node: gdb-EB29K, Next: Remote Log, Prev: Comms (EB29K), Up: EB29K Remote + +EB29K cross-debugging +--------------------- + + Finally, `cd' to the directory containing an image of your 29K +program on the Unix system, and start GDB--specifying as argument the +name of your 29K program: + + cd /usr/joe/work29k + gdb myfoo + + Now you can use the `target' command: + + target amd-eb /dev/ttya 9600 MYFOO + +In this example, we've assumed your program is in a file called +`myfoo'. Note that the filename given as the last argument to `target +amd-eb' should be the name of the program as it appears to DOS. In our +example this is simply `MYFOO', but in general it can include a DOS +path, and depending on your transfer mechanism may not resemble the +name on the Unix side. + + At this point, you can set any breakpoints you wish; when you are +ready to see your program run on the 29K board, use the GDB command +`run'. + + To stop debugging the remote program, use the GDB `detach' command. + + To return control of the PC to its console, use `tip' or `cu' once +again, after your GDB session has concluded, to attach to `EBMON'. You +can then type the command `q' to shut down `EBMON', returning control +to the DOS command-line interpreter. Type `CTTY con' to return command +input to the main DOS console, and type `~.' to leave `tip' or `cu'. + + +File: gdb.info, Node: Remote Log, Prev: gdb-EB29K, Up: EB29K Remote + +Remote log +---------- + + The `target amd-eb' command creates a file `eb.log' in the current +working directory, to help debug problems with the connection. +`eb.log' records all the output from `EBMON', including echoes of the +commands sent to it. Running `tail -f' on this file in another window +often helps to understand trouble with `EBMON', or unexpected events on +the PC side of the connection. + + +File: gdb.info, Node: ST2000 Remote, Next: Hitachi Remote, Prev: VxWorks Remote, Up: Remote + +GDB with a Tandem ST2000 +------------------------ + + To connect your ST2000 to the host system, see the manufacturer's +manual. Once the ST2000 is physically attached, you can run + + target st2000 DEV SPEED + +to establish it as your debugging environment. DEV is normally the +name of a serial device, such as `/dev/ttya', connected to the ST2000 +via a serial line. You can instead specify DEV as a TCP connection +(for example, to a serial line attached via a terminal concentrator) +using the syntax `HOSTNAME:PORTNUMBER'. + + The `load' and `attach' commands are *not* defined for this target; +you must load your program into the ST2000 as you normally would for +standalone operation. GDB will read debugging information (such as +symbols) from a separate, debugging version of the program available on +your host computer. + + These auxiliary GDB commands are available to help you with the +ST2000 environment: + +`st2000 COMMAND' + Send a COMMAND to the STDBUG monitor. See the manufacturer's + manual for available commands. + +`connect' + Connect the controlling terminal to the STDBUG command monitor. + When you are done interacting with STDBUG, typing either of two + character sequences will get you back to the GDB command prompt: + `RET~.' (Return, followed by tilde and period) or `RET~C-d' + (Return, followed by tilde and control-D). + + +File: gdb.info, Node: VxWorks Remote, Next: ST2000 Remote, Prev: EB29K Remote, Up: Remote + +GDB and VxWorks +--------------- + + GDB enables developers to spawn and debug tasks running on networked +VxWorks targets from a Unix host. Already-running tasks spawned from +the VxWorks shell can also be debugged. GDB uses code that runs on +both the Unix host and on the VxWorks target. The program `gdb' is +installed and executed on the Unix host. (It may be installed with the +name `vxgdb', to distinguish it from a GDB for debugging programs on +the host itself.) + + The following information on connecting to VxWorks was current when +this manual was produced; newer releases of VxWorks may use revised +procedures. + + The remote debugging interface (RDB) routines are installed and +executed on the VxWorks target. These routines are included in the +VxWorks library `rdb.a' and are incorporated into the system image when +source-level debugging is enabled in the VxWorks configuration. + + If you wish, you can define `INCLUDE_RDB' in the VxWorks +configuration file `configAll.h' to include the RDB interface routines +and spawn the source debugging task `tRdbTask' when VxWorks is booted. +For more information on configuring and remaking VxWorks, see the +manufacturer's manual. + + Once you have included the RDB interface in your VxWorks system image +and set your Unix execution search path to find GDB, you are ready to +run GDB. From your Unix host, run `gdb' (or `vxgdb', depending on your +installation). + + GDB comes up showing the prompt: + + (vxgdb) + +* Menu: + +* VxWorks Connection:: Connecting to VxWorks +* VxWorks Download:: VxWorks download +* VxWorks Attach:: Running tasks + + +File: gdb.info, Node: VxWorks Connection, Next: VxWorks Download, Up: VxWorks Remote + +Connecting to VxWorks +--------------------- + + The GDB command `target' lets you connect to a VxWorks target on the +network. To connect to a target whose host name is "`tt'", type: + + (vxgdb) target vxworks tt + + GDB displays messages like these: + + Attaching remote machine across net... + Connected to tt. + + GDB then attempts to read the symbol tables of any object modules +loaded into the VxWorks target since it was last booted. GDB locates +these files by searching the directories listed in the command search +path (*note Your program's environment: Environment.); if it fails to +find an object file, it displays a message such as: + + prog.o: No such file or directory. + + When this happens, add the appropriate directory to the search path +with the GDB command `path', and execute the `target' command again. + + +File: gdb.info, Node: VxWorks Download, Next: VxWorks Attach, Prev: VxWorks Connection, Up: VxWorks Remote + +VxWorks download +---------------- + + If you have connected to the VxWorks target and you want to debug an +object that has not yet been loaded, you can use the GDB `load' command +to download a file from Unix to VxWorks incrementally. The object file +given as an argument to the `load' command is actually opened twice: +first by the VxWorks target in order to download the code, then by GDB +in order to read the symbol table. This can lead to problems if the +current working directories on the two systems differ. If both systems +have NFS mounted the same filesystems, you can avoid these problems by +using absolute paths. Otherwise, it is simplest to set the working +directory on both systems to the directory in which the object file +resides, and then to reference the file by its name, without any path. +For instance, a program `prog.o' may reside in `VXPATH/vw/demo/rdb' in +VxWorks and in `HOSTPATH/vw/demo/rdb' on the host. To load this +program, type this on VxWorks: + + -> cd "VXPATH/vw/demo/rdb" + + Then, in GDB, type: + + (vxgdb) cd HOSTPATH/vw/demo/rdb + (vxgdb) load prog.o + + GDB displays a response similar to this: + + Reading symbol data from wherever/vw/demo/rdb/prog.o... done. + + You can also use the `load' command to reload an object module after +editing and recompiling the corresponding source file. Note that this +will cause GDB to delete all currently-defined breakpoints, +auto-displays, and convenience variables, and to clear the value +history. (This is necessary in order to preserve the integrity of +debugger data structures that reference the target system's symbol +table.) + + +File: gdb.info, Node: VxWorks Attach, Prev: VxWorks Download, Up: VxWorks Remote + +Running tasks +------------- + + You can also attach to an existing task using the `attach' command as +follows: + + (vxgdb) attach TASK + +where TASK is the VxWorks hexadecimal task ID. The task can be running +or suspended when you attach to it. If running, it will be suspended at +the time of attachment. + + +File: gdb.info, Node: Hitachi Remote, Next: MIPS Remote, Prev: ST2000 Remote, Up: Remote + +GDB and Hitachi Microprocessors +------------------------------- + + GDB needs to know these things to talk to your Hitachi SH, H8/300, +or H8/500: + + 1. that you want to use `target hms', the remote debugging interface + for Hitachi microprocessors (this is the default when GDB is + configured specifically for the Hitachi SH, H8/300, or H8/500); + + 2. what serial device connects your host to your Hitachi board (the + first serial device available on your host is the default); + + + Use the special `gdb' command `device PORT' if you need to +explicitly set the serial device. The default PORT is the first +available port on your host. This is only necessary on Unix hosts, +where it is typically something like `/dev/ttya'. + + `gdb' has another special command to set the communications speed: +`speed BPS'. This command also is only used from Unix hosts; on DOS +hosts, set the line speed as usual from outside GDB with the DOS `mode' +command (for instance, `mode com2:9600,n,8,1,p' for a 9600 bps +connection). + + The `device' and `speed' commands are available only when you use a +Unix host to debug your Hitachi microprocessor programs. If you use a +DOS host, GDB depends on an auxiliary terminate-and-stay-resident +program called `asynctsr' to communicate with the development board +through a PC serial port. You must also use the DOS `mode' command to +set up the serial port on the DOS side. + + +File: gdb.info, Node: MIPS Remote, Next: Simulator, Prev: Hitachi Remote, Up: Remote + +GDB and remote MIPS boards +-------------------------- + + GDB can use the MIPS remote debugging protocol to talk to a MIPS +board attached to a serial line. This is available when you configure +GDB with `--target=mips-idt-ecoff'. + + To run a program on the board, start up `gdb' with the name of your +program as the argument. To connect to the board, use the command +`target mips PORT', where PORT is the name of the serial port connected +to the board. If the program has not already been downloaded to the +board, you may use the `load' command to download it. You can then use +all the usual GDB commands. + + You can also specify PORT as a TCP connection (for instance, to a +serial line managed by a terminal concentrator), using the syntax +`HOSTNAME:PORTNUMBER'. + + You can see some debugging information about communications with the +board by setting the `remotedebug' variable. If you set it to 1 using +`set remotedebug 1' every packet will be displayed. If you set it to 2 +every character will be displayed. You can check the current value at +any time with the command `show remotedebug'. + + You can control the timeout used while waiting for a packet, in the +MIPS remote protocol, with the `set timeout SECONDS' command. The +default is 5 seconds. Similarly, you can control the timeout used while +waiting for an acknowledgement of a packet with the `set +retransmit-timeout SECONDS' command. The default is 3 seconds. You +can inspect both values with `show timeout' and `show +retransmit-timeout'. (These commands are *only* available when GDB is +configured for `--target=mips-idt-ecoff'.) + + If your target board does not support the MIPS floating point +coprocessor, you should use the command `set mipsfpu off' (you may wish +to put this in your .gdbinit file). This tells GDB how to find the +return value of functions which return floating point values. It also +allows GDB to avoid saving the floating point registers when calling +functions on the board. + + +File: gdb.info, Node: Simulator, Prev: MIPS Remote, Up: Remote + +Simulated CPU target +-------------------- + + For some configurations, GDB includes a CPU simulator that you can +use instead of a hardware CPU to debug your programs. Currently, a +simulator is available when GDB is configured to debug Zilog Z8000 or +Hitachi microprocessor targets. + + For the Z8000 family, `target sim' simulates either the Z8002 (the +unsegmented variant of the Z8000 architecture) or the Z8001 (the +segmented variant). The simulator recognizes which architecture is +appropriate by inspecting the object code. + +`target sim' + Debug programs on a simulated CPU (which CPU depends on the GDB + configuration) + +After specifying this target, you can debug programs for the simulated +CPU in the same style as programs for your host computer; use the +`file' command to load a new program image, the `run' command to run +your program, and so on. + + As well as making available all the usual machine registers (see +`info reg'), this debugging target provides three additional items of +information as specially named registers: + +`cycles' + Counts clock-ticks in the simulator. + +`insts' + Counts instructions run in the simulator. + +`time' + Execution time in 60ths of a second. + + You can refer to these values in GDB expressions with the usual +conventions; for example, `b fputc if $cycles>5000' sets a conditional +breakpoint that will suspend only after at least 5000 simulated clock +ticks. + + +File: gdb.info, Node: Controlling GDB, Next: Sequences, Prev: Targets, Up: Top + +Controlling GDB +*************** + + You can alter the way GDB interacts with you by using the `set' +command. For commands controlling how GDB displays data, *note Print +settings: Print Settings.; other settings are described here. + +* Menu: + +* Prompt:: Prompt +* Editing:: Command editing +* History:: Command history +* Screen Size:: Screen size +* Numbers:: Numbers +* Messages/Warnings:: Optional warnings and messages + + +File: gdb.info, Node: Prompt, Next: Editing, Up: Controlling GDB + +Prompt +====== + + GDB indicates its readiness to read a command by printing a string +called the "prompt". This string is normally `(gdb)'. You can change +the prompt string with the `set prompt' command. For instance, when +debugging GDB with GDB, it is useful to change the prompt in one of the +GDB sessions so that you can always tell which one you are talking to. + +`set prompt NEWPROMPT' + Directs GDB to use NEWPROMPT as its prompt string henceforth. + +`show prompt' + Prints a line of the form: `Gdb's prompt is: YOUR-PROMPT' + + +File: gdb.info, Node: Editing, Next: History, Prev: Prompt, Up: Controlling GDB + +Command editing +=============== + + GDB reads its input commands via the "readline" interface. This GNU +library provides consistent behavior for programs which provide a +command line interface to the user. Advantages are `emacs'-style or +`vi'-style inline editing of commands, `csh'-like history substitution, +and a storage and recall of command history across debugging sessions. + + You may control the behavior of command line editing in GDB with the +command `set'. + +`set editing' +`set editing on' + Enable command line editing (enabled by default). + +`set editing off' + Disable command line editing. + +`show editing' + Show whether command line editing is enabled. + + +File: gdb.info, Node: History, Next: Screen Size, Prev: Editing, Up: Controlling GDB + +Command history +=============== + + GDB can keep track of the commands you type during your debugging +sessions, so that you can be certain of precisely what happened. Use +these commands to manage the GDB command history facility. + +`set history filename FNAME' + Set the name of the GDB command history file to FNAME. This is + the file from which GDB will read an initial command history list + or to which it will write this list when it exits. This list is + accessed through history expansion or through the history command + editing characters listed below. This file defaults to the value + of the environment variable `GDBHISTFILE', or to `./.gdb_history' + if this variable is not set. + +`set history save' +`set history save on' + Record command history in a file, whose name may be specified with + the `set history filename' command. By default, this option is + disabled. + +`set history save off' + Stop recording command history in a file. + +`set history size SIZE' + Set the number of commands which GDB will keep in its history list. + This defaults to the value of the environment variable `HISTSIZE', + or to 256 if this variable is not set. + + History expansion assigns special meaning to the character `!'. + + Since `!' is also the logical not operator in C, history expansion +is off by default. If you decide to enable history expansion with the +`set history expansion on' command, you may sometimes need to follow +`!' (when it is used as logical not, in an expression) with a space or +a tab to prevent it from being expanded. The readline history +facilities will not attempt substitution on the strings `!=' and `!(', +even when history expansion is enabled. + + The commands to control history expansion are: + +`set history expansion on' +`set history expansion' + Enable history expansion. History expansion is off by default. + +`set history expansion off' + Disable history expansion. + + The readline code comes with more complete documentation of + editing and history expansion features. Users unfamiliar with + `emacs' or `vi' may wish to read it. + +`show history' +`show history filename' +`show history save' +`show history size' +`show history expansion' + These commands display the state of the GDB history parameters. + `show history' by itself displays all four states. + +`show commands' + Display the last ten commands in the command history. + +`show commands N' + Print ten commands centered on command number N. + +`show commands +' + Print ten commands just after the commands last printed. + + +File: gdb.info, Node: Screen Size, Next: Numbers, Prev: History, Up: Controlling GDB + +Screen size +=========== + + Certain commands to GDB may produce large amounts of information +output to the screen. To help you read all of it, GDB pauses and asks +you for input at the end of each page of output. Type RET when you +want to continue the output, or `q' to discard the remaining output. +Also, the screen width setting determines when to wrap lines of output. +Depending on what is being printed, GDB tries to break the line at a +readable place, rather than simply letting it overflow onto the +following line. + + Normally GDB knows the size of the screen from the termcap data base +together with the value of the `TERM' environment variable and the +`stty rows' and `stty cols' settings. If this is not correct, you can +override it with the `set height' and `set width' commands: + +`set height LPP' +`show height' +`set width CPL' +`show width' + These `set' commands specify a screen height of LPP lines and a + screen width of CPL characters. The associated `show' commands + display the current settings. + + If you specify a height of zero lines, GDB will not pause during + output no matter how long the output is. This is useful if output + is to a file or to an editor buffer. + + Likewise, you can specify `set width 0' to prevent GDB from + wrapping its output. + + +File: gdb.info, Node: Numbers, Next: Messages/Warnings, Prev: Screen Size, Up: Controlling GDB + +Numbers +======= + + You can always enter numbers in octal, decimal, or hexadecimal in +GDB by the usual conventions: octal numbers begin with `0', decimal +numbers end with `.', and hexadecimal numbers begin with `0x'. Numbers +that begin with none of these are, by default, entered in base 10; +likewise, the default display for numbers--when no particular format is +specified--is base 10. You can change the default base for both input +and output with the `set radix' command. + +`set radix BASE' + Set the default base for numeric input and display. Supported + choices for BASE are decimal 8, 10, or 16. BASE must itself be + specified either unambiguously or using the current default radix; + for example, any of + + set radix 012 + set radix 10. + set radix 0xa + + will set the base to decimal. On the other hand, `set radix 10' + will leave the radix unchanged no matter what it was. + +`show radix' + Display the current default base for numeric input and display. + + +File: gdb.info, Node: Messages/Warnings, Prev: Numbers, Up: Controlling GDB + +Optional warnings and messages +============================== + + By default, GDB is silent about its inner workings. If you are +running on a slow machine, you may want to use the `set verbose' +command. It will make GDB tell you when it does a lengthy internal +operation, so you will not think it has crashed. + + Currently, the messages controlled by `set verbose' are those which +announce that the symbol table for a source file is being read; see +`symbol-file' in *Note Commands to specify files: Files. + +`set verbose on' + Enables GDB output of certain informational messages. + +`set verbose off' + Disables GDB output of certain informational messages. + +`show verbose' + Displays whether `set verbose' is on or off. + + By default, if GDB encounters bugs in the symbol table of an object +file, it is silent; but if you are debugging a compiler, you may find +this information useful (*note Errors reading symbol files: Symbol +Errors.). + +`set complaints LIMIT' + Permits GDB to output LIMIT complaints about each type of unusual + symbols before becoming silent about the problem. Set LIMIT to + zero to suppress all complaints; set it to a large number to + prevent complaints from being suppressed. + +`show complaints' + Displays how many symbol complaints GDB is permitted to produce. + + By default, GDB is cautious, and asks what sometimes seems to be a +lot of stupid questions to confirm certain commands. For example, if +you try to run a program which is already running: + + (gdb) run + The program being debugged has been started already. + Start it from the beginning? (y or n) + + If you are willing to unflinchingly face the consequences of your own +commands, you can disable this "feature": + +`set confirm off' + Disables confirmation requests. + +`set confirm on' + Enables confirmation requests (the default). + +`show confirm' + Displays state of confirmation requests. + + Some systems allow individual object files that make up your program +to be replaced without stopping and restarting your program. For +example, in VxWorks you can simply recompile a defective object file +and keep on running. If you are running on one of these systems, you +can allow GDB to reload the symbols for automatically relinked modules: + +`set symbol-reloading on' + Replace symbol definitions for the corresponding source file when + an object file with a particular name is seen again. + +`set symbol-reloading off' + Do not replace symbol definitions when re-encountering object + files of the same name. This is the default state; if you are not + running on a system that permits automatically relinking modules, + you should leave `symbol-reloading' off, since otherwise GDB may + discard symbols when linking large programs, that may contain + several modules (from different directories or libraries) with the + same name. + +`show symbol-reloading' + Show the current `on' or `off' setting. + + +File: gdb.info, Node: Sequences, Next: Emacs, Prev: Controlling GDB, Up: Top + +Canned Sequences of Commands +**************************** + + Aside from breakpoint commands (*note Breakpoint command lists: +Break Commands.), GDB provides two ways to store sequences of commands +for execution as a unit: user-defined commands and command files. + +* Menu: + +* Define:: User-defined commands +* Hooks:: User-defined command hooks +* Command Files:: Command files +* Output:: Commands for controlled output + + +File: gdb.info, Node: Define, Next: Hooks, Up: Sequences + +User-defined commands +===================== + + A "user-defined command" is a sequence of GDB commands to which you +assign a new name as a command. This is done with the `define' command. + +`define COMMANDNAME' + Define a command named COMMANDNAME. If there is already a command + by that name, you are asked to confirm that you want to redefine + it. + + The definition of the command is made up of other GDB command + lines, which are given following the `define' command. The end of + these commands is marked by a line containing `end'. + +`document COMMANDNAME' + Give documentation to the user-defined command COMMANDNAME. The + command COMMANDNAME must already be defined. This command reads + lines of documentation just as `define' reads the lines of the + command definition, ending with `end'. After the `document' + command is finished, `help' on command COMMANDNAME will print the + documentation you have specified. + + You may use the `document' command again to change the + documentation of a command. Redefining the command with `define' + does not change the documentation. + +`help user-defined' + List all user-defined commands, with the first line of the + documentation (if any) for each. + +`show user' +`show user COMMANDNAME' + Display the GDB commands used to define COMMANDNAME (but not its + documentation). If no COMMANDNAME is given, display the + definitions for all user-defined commands. + + User-defined commands do not take arguments. When they are +executed, the commands of the definition are not printed. An error in +any command stops execution of the user-defined command. + + Commands that would ask for confirmation if used interactively +proceed without asking when used inside a user-defined command. Many +GDB commands that normally print messages to say what they are doing +omit the messages when used in a user-defined command. + + +File: gdb.info, Node: Hooks, Next: Command Files, Prev: Define, Up: Sequences + +User-defined command hooks +========================== + + You may define *hooks*, which are a special kind of user-defined +command. Whenever you run the command `foo', if the user-defined +command `hook-foo' exists, it is executed (with no arguments) before +that command. + + In addition, a pseudo-command, `stop' exists. Defining +(`hook-stop') makes the associated commands execute every time +execution stops in your program: before breakpoint commands are run, +displays are printed, or the stack frame is printed. + + For example, to ignore `SIGALRM' signals while single-stepping, but +treat them normally during normal execution, you could define: + + define hook-stop + handle SIGALRM nopass + end + + define hook-run + handle SIGALRM pass + end + + define hook-continue + handle SIGLARM pass + end + + You can define a hook for any single-word command in GDB, but not +for command aliases; you should define a hook for the basic command +name, e.g. `backtrace' rather than `bt'. If an error occurs during +the execution of your hook, execution of GDB commands stops and GDB +issues a prompt (before the command that you actually typed had a +chance to run). + + If you try to define a hook which does not match any known command, +you will get a warning from the `define' command. + + +File: gdb.info, Node: Command Files, Next: Output, Prev: Hooks, Up: Sequences + +Command files +============= + + A command file for GDB is a file of lines that are GDB commands. +Comments (lines starting with `#') may also be included. An empty line +in a command file does nothing; it does not mean to repeat the last +command, as it would from the terminal. + + When you start GDB, it automatically executes commands from its +"init files". These are files named `.gdbinit'. GDB reads the init +file (if any) in your home directory and then the init file (if any) in +the current working directory. (The init files are not executed if you +use the `-nx' option; *note Choosing modes: Mode Options..) + + On some configurations of GDB, the init file is known by a different +name (these are typically environments where a specialized form of GDB +may need to coexist with other forms, hence a different name for the +specialized version's init file). These are the environments with +special init file names: + + * VxWorks (Wind River Systems real-time OS): `.vxgdbinit' + + * OS68K (Enea Data Systems real-time OS): `.os68gdbinit' + + * ES-1800 (Ericsson Telecom AB M68000 emulator): `.esgdbinit' + + You can also request the execution of a command file with the +`source' command: + +`source FILENAME' + Execute the command file FILENAME. + + The lines in a command file are executed sequentially. They are not +printed as they are executed. An error in any command terminates +execution of the command file. + + Commands that would ask for confirmation if used interactively +proceed without asking when used in a command file. Many GDB commands +that normally print messages to say what they are doing omit the +messages when called from command files. + + +File: gdb.info, Node: Output, Prev: Command Files, Up: Sequences + +Commands for controlled output +============================== + + During the execution of a command file or a user-defined command, +normal GDB output is suppressed; the only output that appears is what is +explicitly printed by the commands in the definition. This section +describes three commands useful for generating exactly the output you +want. + +`echo TEXT' + Print TEXT. Nonprinting characters can be included in TEXT using + C escape sequences, such as `\n' to print a newline. *No newline + will be printed unless you specify one.* In addition to the + standard C escape sequences, a backslash followed by a space + stands for a space. This is useful for displaying a string with + spaces at the beginning or the end, since leading and trailing + spaces are otherwise trimmed from all arguments. To print ` and + foo = ', use the command `echo \ and foo = \ '. + + A backslash at the end of TEXT can be used, as in C, to continue + the command onto subsequent lines. For example, + + echo This is some text\n\ + which is continued\n\ + onto several lines.\n + + produces the same output as + + echo This is some text\n + echo which is continued\n + echo onto several lines.\n + +`output EXPRESSION' + Print the value of EXPRESSION and nothing but that value: no + newlines, no `$NN = '. The value is not entered in the value + history either. *Note Expressions: Expressions, for more + information on expressions. + +`output/FMT EXPRESSION' + Print the value of EXPRESSION in format FMT. You can use the same + formats as for `print'. *Note Output formats: Output Formats, for + more information. + +`printf STRING, EXPRESSIONS...' + Print the values of the EXPRESSIONS under the control of STRING. + The EXPRESSIONS are separated by commas and may be either numbers + or pointers. Their values are printed as specified by STRING, + exactly as if your program were to execute the C subroutine + + printf (STRING, EXPRESSIONS...); + + For example, you can print two values in hex like this: + + printf "foo, bar-foo = 0x%x, 0x%x\n", foo, bar-foo + + The only backslash-escape sequences that you can use in the format + string are the simple ones that consist of backslash followed by a + letter. + + +File: gdb.info, Node: Emacs, Next: GDB Bugs, Prev: Sequences, Up: Top + +Using GDB under GNU Emacs +************************* + + A special interface allows you to use GNU Emacs to view (and edit) +the source files for the program you are debugging with GDB. + + To use this interface, use the command `M-x gdb' in Emacs. Give the +executable file you want to debug as an argument. This command starts +GDB as a subprocess of Emacs, with input and output through a newly +created Emacs buffer. + + Using GDB under Emacs is just like using GDB normally except for two +things: + + * All "terminal" input and output goes through the Emacs buffer. + + This applies both to GDB commands and their output, and to the input +and output done by the program you are debugging. + + This is useful because it means that you can copy the text of +previous commands and input them again; you can even use parts of the +output in this way. + + All the facilities of Emacs' Shell mode are available for interacting +with your program. In particular, you can send signals the usual +way--for example, `C-c C-c' for an interrupt, `C-c C-z' for a stop. + + * GDB displays source code through Emacs. + + Each time GDB displays a stack frame, Emacs automatically finds the +source file for that frame and puts an arrow (`=>') at the left margin +of the current line. Emacs uses a separate buffer for source display, +and splits the screen to show both your GDB session and the source. + + Explicit GDB `list' or search commands still produce output as +usual, but you probably will have no reason to use them. + + *Warning:* If the directory where your program resides is not your + current directory, it can be easy to confuse Emacs about the + location of the source files, in which case the auxiliary display + buffer will not appear to show your source. GDB can find programs + by searching your environment's `PATH' variable, so the GDB input + and output session will proceed normally; but Emacs does not get + enough information back from GDB to locate the source files in + this situation. To avoid this problem, either start GDB mode from + the directory where your program resides, or specify a full path + name when prompted for the `M-x gdb' argument. + + A similar confusion can result if you use the GDB `file' command to + switch to debugging a program in some other location, from an + existing GDB buffer in Emacs. + + By default, `M-x gdb' calls the program called `gdb'. If you need +to call GDB by a different name (for example, if you keep several +configurations around, with different names) you can set the Emacs +variable `gdb-command-name'; for example, + + (setq gdb-command-name "mygdb") + +(preceded by `ESC ESC', or typed in the `*scratch*' buffer, or in your +`.emacs' file) will make Emacs call the program named "`mygdb'" instead. + + In the GDB I/O buffer, you can use these special Emacs commands in +addition to the standard Shell mode commands: + +`C-h m' + Describe the features of Emacs' GDB Mode. + +`M-s' + Execute to another source line, like the GDB `step' command; also + update the display window to show the current file and location. + +`M-n' + Execute to next source line in this function, skipping all function + calls, like the GDB `next' command. Then update the display window + to show the current file and location. + +`M-i' + Execute one instruction, like the GDB `stepi' command; update + display window accordingly. + +`M-x gdb-nexti' + Execute to next instruction, using the GDB `nexti' command; update + display window accordingly. + +`C-c C-f' + Execute until exit from the selected stack frame, like the GDB + `finish' command. + +`M-c' + Continue execution of your program, like the GDB `continue' + command. + + *Warning:* In Emacs v19, this command is `C-c C-p'. + +`M-u' + Go up the number of frames indicated by the numeric argument + (*note Numeric Arguments: (emacs)Arguments.), like the GDB `up' + command. + + *Warning:* In Emacs v19, this command is `C-c C-u'. + +`M-d' + Go down the number of frames indicated by the numeric argument, + like the GDB `down' command. + + *Warning:* In Emacs v19, this command is `C-c C-d'. + +`C-x &' + Read the number where the cursor is positioned, and insert it at + the end of the GDB I/O buffer. For example, if you wish to + disassemble code around an address that was displayed earlier, + type `disassemble'; then move the cursor to the address display, + and pick up the argument for `disassemble' by typing `C-x &'. + + You can customize this further by defining elements of the list + `gdb-print-command'; once it is defined, you can format or + otherwise process numbers picked up by `C-x &' before they are + inserted. A numeric argument to `C-x &' will both indicate that + you wish special formatting, and act as an index to pick an + element of the list. If the list element is a string, the number + to be inserted is formatted using the Emacs function `format'; + otherwise the number is passed as an argument to the corresponding + list element. + + In any source file, the Emacs command `C-x SPC' (`gdb-break') tells +GDB to set a breakpoint on the source line point is on. + + If you accidentally delete the source-display buffer, an easy way to +get it back is to type the command `f' in the GDB buffer, to request a +frame display; when you run under Emacs, this will recreate the source +buffer if necessary to show you the context of the current frame. + + The source files displayed in Emacs are in ordinary Emacs buffers +which are visiting the source files in the usual way. You can edit the +files with these buffers if you wish; but keep in mind that GDB +communicates with Emacs in terms of line numbers. If you add or delete +lines from the text, the line numbers that GDB knows will cease to +correspond properly with the code. + + +File: gdb.info, Node: GDB Bugs, Next: Command Line Editing, Prev: Emacs, Up: Top + +Reporting Bugs in GDB +********************* + + Your bug reports play an essential role in making GDB reliable. + + Reporting a bug may help you by bringing a solution to your problem, +or it may not. But in any case the principal function of a bug report +is to help the entire community by making the next version of GDB work +better. Bug reports are your contribution to the maintenance of GDB. + + In order for a bug report to serve its purpose, you must include the +information that enables us to fix the bug. + +* Menu: + +* Bug Criteria:: Have you found a bug? +* Bug Reporting:: How to report bugs + + +File: gdb.info, Node: Bug Criteria, Next: Bug Reporting, Up: GDB Bugs + +Have you found a bug? +===================== + + If you are not sure whether you have found a bug, here are some +guidelines: + + * If the debugger gets a fatal signal, for any input whatever, that + is a GDB bug. Reliable debuggers never crash. + + * If GDB produces an error message for valid input, that is a bug. + + * If GDB does not produce an error message for invalid input, that + is a bug. However, you should note that your idea of "invalid + input" might be our idea of "an extension" or "support for + traditional practice". + + * If you are an experienced user of debugging tools, your suggestions + for improvement of GDB are welcome in any case. + |