diff options
Diffstat (limited to 'gdb/doc/gdb.info-7')
| -rw-r--r-- | gdb/doc/gdb.info-7 | 1302 |
1 files changed, 1302 insertions, 0 deletions
diff --git a/gdb/doc/gdb.info-7 b/gdb/doc/gdb.info-7 new file mode 100644 index 00000000000..33d63e18ef5 --- /dev/null +++ b/gdb/doc/gdb.info-7 @@ -0,0 +1,1302 @@ +This is Info file ./gdb.info, produced by Makeinfo version 1.68 from +the input file gdb.texinfo. + +START-INFO-DIR-ENTRY +* Gdb: (gdb). The GNU debugger. +END-INFO-DIR-ENTRY + This file documents the GNU debugger GDB. + + This is the Seventh Edition, February 1999, of `Debugging with GDB: +the GNU Source-Level Debugger' for GDB Version 4.18. + + Copyright (C) 1988-1999 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 + +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 + +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' keeps 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 does *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 reads 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 gets 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.) + +`VxWorks-timeout ARGS' + All VxWorks-based targets now support the option `vxworks-timeout'. + This option is set by the user, and ARGS represents the number of + seconds GDB waits for responses to rpc's. You might use this if + your VxWorks target is a slow software simulator or is on the far + side of a thin network line. + + The following information on connecting to VxWorks was current when +this manual was produced; newer releases of VxWorks may use revised +procedures. + + To use GDB with VxWorks, you must rebuild your VxWorks kernel to +include the remote debugging interface routines in the VxWorks library +`rdb.a'. To do this, define `INCLUDE_RDB' in the VxWorks configuration +file `configAll.h' and rebuild your VxWorks kernel. The resulting +kernel contains `rdb.a', and spawns 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 `rdb.a' 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" + v 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 +makes GDB 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. Running tasks are suspended at the +time of attachment. + + +File: gdb.info, Node: Sparclet Remote, Next: Simulator, Prev: MIPS Remote, Up: Remote + +GDB and Sparclet +---------------- + + GDB enables developers to debug tasks running on Sparclet targets +from a Unix host. GDB uses code that runs on both the Unix host and on +the Sparclet target. The program `gdb' is installed and executed on +the Unix host. + +`timeout ARGS' + GDB now supports the option `remotetimeout'. This option is set + by the user, and ARGS represents the number of seconds GDB waits + for responses. + + When compiling for debugging, include the options "-g" to get debug +information and "-Ttext" to relocate the program to where you wish to +load it on the target. You may also want to add the options "-n" or +"-N" in order to reduce the size of the sections. + + sparclet-aout-gcc prog.c -Ttext 0x12010000 -g -o prog -N + + You can use objdump to verify that the addresses are what you +intended. + + sparclet-aout-objdump --headers --syms prog + + Once you have set your Unix execution search path to find GDB, you +are ready to run GDB. From your Unix host, run `gdb' (or +`sparclet-aout-gdb', depending on your installation). + + GDB comes up showing the prompt: + + (gdbslet) + +* Menu: + +* Sparclet File:: Setting the file to debug +* Sparclet Connection:: Connecting to Sparclet +* Sparclet Download:: Sparclet download +* Sparclet Execution:: Running and debugging + + +File: gdb.info, Node: Sparclet File, Next: Sparclet Connection, Up: Sparclet Remote + +Setting file to debug +..................... + + The GDB command `file' lets you choose with program to debug. + + (gdbslet) file prog + + GDB then attempts to read the symbol table of `prog'. GDB locates +the file by searching the directories listed in the command search path. +If the file was compiled with debug information (option "-g"), source +files will be searched as well. GDB locates the source files by +searching the directories listed in the directory search path (*note +Your program's environment: Environment.). If it fails to find a file, +it displays a message such as: + + prog: No such file or directory. + + When this happens, add the appropriate directories to the search +paths with the GDB commands `path' and `dir', and execute the `target' +command again. + + +File: gdb.info, Node: Sparclet Connection, Next: Sparclet Download, Prev: Sparclet File, Up: Sparclet Remote + +Connecting to Sparclet +...................... + + The GDB command `target' lets you connect to a Sparclet target. To +connect to a target on serial port "`ttya'", type: + + (gdbslet) target sparclet /dev/ttya + Remote target sparclet connected to /dev/ttya + main () at ../prog.c:3 + + GDB displays messages like these: + + Connected to ttya. + + +File: gdb.info, Node: Sparclet Download, Next: Sparclet Execution, Prev: Sparclet Connection, Up: Sparclet Remote + +Sparclet download +................. + + Once connected to the Sparclet target, you can use the GDB `load' +command to download the file from the host to the target. The file +name and load offset should be given as arguments to the `load' command. +Since the file format is aout, the program must be loaded to the +starting address. You can use objdump to find out what this value is. +The load offset is an offset which is added to the VMA (virtual memory +address) of each of the file's sections. For instance, if the program +`prog' was linked to text address 0x1201000, with data at 0x12010160 +and bss at 0x12010170, in GDB, type: + + (gdbslet) load prog 0x12010000 + Loading section .text, size 0xdb0 vma 0x12010000 + + If the code is loaded at a different address then what the program +was linked to, you may need to use the `section' and `add-symbol-file' +commands to tell GDB where to map the symbol table. + + +File: gdb.info, Node: Sparclet Execution, Prev: Sparclet Download, Up: Sparclet Remote + +Running and debugging +..................... + + You can now begin debugging the task using GDB's execution control +commands, `b', `step', `run', etc. See the GDB manual for the list of +commands. + + (gdbslet) b main + Breakpoint 1 at 0x12010000: file prog.c, line 3. + (gdbslet) run + Starting program: prog + Breakpoint 1, main (argc=1, argv=0xeffff21c) at prog.c:3 + 3 char *symarg = 0; + (gdbslet) step + 4 char *execarg = "hello!"; + (gdbslet) + + +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, or `target e7000', the in-circuit + emulator for the Hitachi SH and the Hitachi 300H. (`target hms' 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). + + 3. what speed to use over the serial device. + +* Menu: + +* Hitachi Boards:: Connecting to Hitachi boards. +* Hitachi ICE:: Using the E7000 In-Circuit Emulator. +* Hitachi Special:: Special GDB commands for Hitachi micros. + + +File: gdb.info, Node: Hitachi Boards, Next: Hitachi ICE, Up: Hitachi Remote + +Connecting to Hitachi boards +............................ + + 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: Hitachi ICE, Next: Hitachi Special, Prev: Hitachi Boards, Up: Hitachi Remote + +Using the E7000 in-circuit emulator +................................... + + You can use the E7000 in-circuit emulator to develop code for either +the Hitachi SH or the H8/300H. Use one of these forms of the `target +e7000' command to connect GDB to your E7000: + +`target e7000 PORT SPEED' + Use this form if your E7000 is connected to a serial port. The + PORT argument identifies what serial port to use (for example, + `com2'). The third argument is the line speed in bits per second + (for example, `9600'). + +`target e7000 HOSTNAME' + If your E7000 is installed as a host on a TCP/IP network, you can + just specify its hostname; GDB uses `telnet' to connect. + + +File: gdb.info, Node: Hitachi Special, Prev: Hitachi ICE, Up: Hitachi Remote + +Special GDB commands for Hitachi micros +....................................... + + Some GDB commands are available only on the H8/300 or the H8/500 +configurations: + +`set machine h8300' +`set machine h8300h' + Condition GDB for one of the two variants of the H8/300 + architecture with `set machine'. You can use `show machine' to + check which variant is currently in effect. + +`set memory MOD' +`show memory' + Specify which H8/500 memory model (MOD) you are using with `set + memory'; check which memory model is in effect with `show memory'. + The accepted values for MOD are `small', `big', `medium', and + `compact'. + + +File: gdb.info, Node: MIPS Remote, Next: Sparclet Remote, 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'. + + Use these GDB commands to specify the connection to your target +board: + +`target mips PORT' + 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. + + For example, this sequence connects to the target board through a + serial port, and loads and runs a program called PROG through the + debugger: + + host$ gdb PROG + GDB is free software and ... + (gdb) target mips /dev/ttyb + (gdb) load PROG + (gdb) run + +`target mips HOSTNAME:PORTNUMBER' + On some GDB host configurations, you can specify a TCP connection + (for instance, to a serial line managed by a terminal + concentrator) instead of a serial port, using the syntax + `HOSTNAME:PORTNUMBER'. + +`target pmon PORT' + +`target ddb PORT' + +`target lsi PORT' +GDB also supports these special commands for MIPS targets: + +`set processor ARGS' +`show processor' + Use the `set processor' command to set the type of MIPS processor + when you want to access processor-type-specific registers. For + example, `set processor R3041' tells GDB to use the CPO registers + appropriate for the 3041 chip. Use the `show processor' command + to see what MIPS processor GDB is using. Use the `info reg' + command to see what registers GDB is using. + +`set mipsfpu double' +`set mipsfpu single' +`set mipsfpu none' +`show mipsfpu' + If your target board does not support the MIPS floating point + coprocessor, you should use the command `set mipsfpu none' (if you + need this, you may wish to put the command in your {No Value For + "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. If you are using a floating point + coprocessor with only single precision floating point support, as + on the R4650 processor, use the command `set mipsfpu single'. The + default double precision floating point coprocessor may be + selected using `set mipsfpu double'. + + In previous versions the only choices were double precision or no + floating point, so `set mipsfpu on' will select double precision + and `set mipsfpu off' will select no floating point. + + As usual, you can inquire about the `mipsfpu' variable with `show + mipsfpu'. + +`set remotedebug N' +`show remotedebug' + 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 is displayed. If you + set it to `2', every character is displayed. You can check the + current value at any time with the command `show remotedebug'. + +`set timeout SECONDS' +`set retransmit-timeout SECONDS' +`show timeout' +`show retransmit-timeout' + 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'.) + + The timeout set by `set timeout' does not apply when GDB is + waiting for your program to stop. In that case, GDB waits forever + because it has no way of knowing how long the program is going to + run before stopping. + + +File: gdb.info, Node: Simulator, Prev: Sparclet 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, +simulators are available for ARM, D10V, D30V, FR30, H8/300, H8/500, +i960, M32R, MIPS, MN10200, MN10300, PowerPC, SH, Sparc, V850, W65, and +Z8000. + + 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 ARGS' + Debug programs on a simulated CPU. If the simulator supports setup + options, specify them via ARGS. + +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'), the Z8000 simulator 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 suspends 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, Prev: Controlling GDB, 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. + + *Note:* `set prompt' no longer adds a space for you after the +prompt you set. This allows you to set a prompt which ends in a space +or a prompt that does not. + +`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 GNU 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 where GDB reads an initial command history list, and + where it writes the command history from this session when it + exits. You can access this list 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 keeps 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 do 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 GNU + 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 does 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 input-radix BASE' + Set the default base for numeric input. 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 + + sets the base to decimal. On the other hand, `set radix 10' + leaves the radix unchanged no matter what it was. + +`set output-radix BASE' + Set the default base for numeric display. Supported choices for + BASE are decimal 8, 10, or 16. BASE must itself be specified + either unambiguously or using the current default radix. + +`show input-radix' + Display the current default base for numeric input. + +`show output-radix' + Display the current default base for numeric 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. This makes 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. + + +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, Prev: Sequences, 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. User commands may accept up to 10 arguments separated by +whitespace. Arguments are accessed within the user command via +$ARG0...$ARG9. A trivial example: + + define adder + print $arg0 + $arg1 + $arg2 + +To execute the command use: + + adder 1 2 3 + +This defines the command `adder', which prints the sum of its three +arguments. Note the arguments are text substitutions, so they may +reference variables, use complex expressions, or even perform inferior +functions calls. + +`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'. + +`if' + Takes a single argument, which is an expression to evaluate. It + is followed by a series of commands that are executed only if the + expression is true (nonzero). There can then optionally be a line + `else', followed by a series of commands that are only executed if + the expression was false. The end of the list is marked by a line + containing `end'. + +`while' + The syntax is similar to `if': the command takes a single argument, + which is an expression to evaluate, and must be followed by the + commands to execute, one per line, terminated by an `end'. The + commands are executed repeatedly as long as the expression + evaluates to true. + +`document COMMANDNAME' + Document the user-defined command COMMANDNAME, so that it can be + accessed by `help'. 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 displays the documentation you have written. + + 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. + + When user-defined commands are executed, the commands of the +definition are not printed. An error in any command stops execution of +the user-defined command. + + If used interactively, commands that would ask for confirmation +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 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' on Unix, or `gdb.ini' +on DOS/Windows. GDB reads the init file (if any) in your home +directory, then processes command line options and operands, and then +reads the init file (if any) in the current working directory. This is +so the init file in your home directory can set options (such as `set +complaints') which affect the processing of the command line options +and operands. 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 + is 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. + |