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