diff options
Diffstat (limited to 'gdb/doc/gdb.info-7')
| -rw-r--r-- | gdb/doc/gdb.info-7 | 1302 |
1 files changed, 0 insertions, 1302 deletions
diff --git a/gdb/doc/gdb.info-7 b/gdb/doc/gdb.info-7 deleted file mode 100644 index 33d63e18ef5..00000000000 --- a/gdb/doc/gdb.info-7 +++ /dev/null @@ -1,1302 +0,0 @@ -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. - |