ELVGDB(1)

NAME
elvgdb - allows gdb and elvis to work together

SYNOPSIS
elvgdb [gdbargs]
elvgdb [-t gdbcommand]

DESCRIPTION
elvgdb is a program that allows the gdb(1) debugger and the elvis(1) editor to work together. It only functions properly in X windows.

There are two ways to use it. Without a -tgdbcommand flag it behaves as a "server", running an interactive gdb process and allowing that gdb to send information to elvis. With a -tgdbcommand flag it behaves as a "client", pasting the gdbcommand into the xterm(1X) where the elvgdb/gdb server is running.

Usually, you will use it by starting elvis with its "x11" user interface, and then running ":gdb program [core]". This will start an xterm process with elvgdb (running as a server, without "-t") and gdb running inside it. Various elvis aliases and buttons may invoke elvgdb with the "-t" to send a command to the debugger.

SERVER
When invoked without a -t flag, elvgdb invokes gdb, passing it all of the command-line parameters and also inserting a "--annotate=2" parameter which causes gdb to output extra information that may be useful to elvis.

elvgdb also filters gdb's output to extract that information (called "annotations" in the gdb info pages) so it can send it to elvis. There is a "elvgdb.ini" file (described in ELVGDB.INI below) which tells elvgdb which annotations elvis is likely to care about, and which surrounding text to send back.

The information is sent to elvis via the equivalent of elvis's -client mechanism, which is only supported by elvis's "x11" user interface. You must start elvis before you start elvgdb, because elvgdb only tries to locate elvis during its initialization.

The information is sent to elvis in the form of a ":fromgdb" command. elvis has no built-in command by that name; you are expected to define an ":fromgdb" alias in elvis. An example of such an alias is provided with elvis. You can load it (and some other useful gdb-related things) by running ":load gdb". The ":gdb" alias does this automatically.

The first argument of each ":fromgdb" command is the name of the annotation that triggered the message. Other text (either extra information in the annotation, or text enclosed between the triggering annotation and some later annotation) follows as extra arguments. Usually, the ":fromgdb" alias will be a big switch statement that checks the first argument (the annotation name), and then possibly also parses the extra information in some annotation-dependent way.

CLIENT
The server elvgdb process attaches an attribute to the display's root window, giving the Window ID of the xterm in which the server elvgdb/gdb is running. The client elvgdb uses this to find the server.

To send the gdbcommand text, it first creates an invisible window of its own and then claims the X selection, simulates a middle-click on the xterm window, and waits for the xterm to fetch the selection so the xterm can paste it.

ELVGDB.INI
The elvgdb.ini file tells elvgdb how to handle each annotion. It can reside anywhere in $ELVISPATH, just like elvis's own configuration files.

It is a text file. Blank lines, and lines that start with a "#" character, are ignored. All other lines should be of the form...

    annotations : attributes

... where annotations is a space-delimited list of annotation names, and attributes is a space-delimited list of attributes.

  ATTRIBUTES

The following attribute names control the way that the annotation is handled by elvgdb.

fromgdb | Start a new command to be sent to elvis
args | Append arguments to the next command sent to elvis
text | Append the following text to the next command sent to elvis
toelvis | Send a ":fromgdb name args text" command to elvis.
table | Store the annotation name for use with "record" attributes
record | Send previous record (if any), and start a new one.
flush | Flush output after each character because user is typing
trace | Show the annotation name, to help debug the configuration
server | If following text begins with "server" then suppress output
limit | Try to avoid sending multiple copies of the message

The "table" and "record" attributes, and the special "fieldn" pseudo-annotations described below, are all intended to help work around the obnoxious way that gdb annotates its breakpoints table. The idea is that the "breakpoints-table" annotation will have the "table" attribute, the "record" annotation will have the "record" attribute, selected "fieldn" annotations will have the "text" attribute, and the "breakpoints-table-end" annotation will have a normal "toelvis" attribute. This will cause each record to send a ":fromgdb breakpoints-table" message to elvis with selected fields appended as arguments.

The "server" attribute is used to suppress output from commands issued by elvis (via "elvgdb -t gdbcommands"), as opposed to those commands entered into gdb directly by the user. Generally, any annotation which has the "flush" attribute should also have the "server" attribute.

The "limit" attribute is mostly due to the fact that gdb sometimes sends many "breakpoints-invalid" messages between prompts, but we only want elvis to update its breakpoints once.

In addition, the following attributes can be used to alter the appearance of text that follows particular annotations:
black | Use black foreground for the following text
gray | Use gray foreground for the following text
red | Use red foreground for the following text
green | Use green foreground for the following text
brown | Use brown foreground for the following text
yellow | Use yellow foreground for the following text
blue | Use blue foreground for the following text
magenta | Use magenta foreground for the following text
cyan | Use cyan foreground for the following text
white | Use white foreground for the following text
bold | Switch to bold/bright text
underline Switch to underlined text
highlight Don't switch back to normal

  ANNOTATIONS

For the names and descriptions of annotations, see the gdb info pages. elvgdb also uses a few pseudo-annotations for special purposes. These are:

fieldn
    When gdb emits a "field" annotation with a numeric argument n, elvgdb converts that into a "fieldn" annotation before looking up its attributes. In other words, "fieldn" in the elvgdb.ini file is used to specify the attributes of a "field" annotation that has the argument "n". This is intented to help work around the obnoxious annotations used for the breakpoint table.

elvgdb-all
    Merged with the attributes of all real annotations. This is mostly so you can say "elvgdb-all:trace" to trace all annotations.

elvgdb-default
    Used to supply the attributes of any annotation that isn't specifically mentioned in the elvgdb.ini configuration file. For example, "elvgdb-default: trace" would cause any recently added (or otherwise unhandled) annotations to be shown.

elvgdb-init
    Simulated before gdb starts. Its highlighting attributes are used for the gdb copyright statement.

elvgdb-term
    Simulated after gdb terminates. You can use the "fromgdb toelvis" attribute pair to have a message be sent to elvis so it knows when elvgdb/gdb isn't running anymore.

elvgdb-trace
    The highlighting attributes of this pseudo-annotation are used when displaying the name of any traced annotation. For example, "elvgdb-trace: magenta" would cause traced annotations to appear in magenta.

    Also, if the "elvgdb-trace" annotation has the "fromgdb" attribute, then elvgdb will mark the start of any command that it is preparing to send to elvis. The "toelvis" attribute will cause it to display the whole command when it is actually sent. The "table" attribute will cause elvis to mark the start and end of any table. The "server" attribute will inhibit the effect of "server" on any real annotation, so that server commands will be visible.

OPTIONS

When used as a server (without -tcommands), elvgdb passes all of its parameters to gdb. See gdb(1) for a description of the options that it supports.

When used as a filter, you must use a -tgdbcommand flag, as follows:

-t gdbcommand
    Paste gdbcommand into the xterm(1X) where the elvgdb/gdb server is running. Assuming gdb is prompting for a command, this should cause gdb to execute the gdbcommand.

ENVIRONMENT

$ELVISPATH
    This is a list of directories where the "elvis.ini" file may reside.

$secret
    This contains the value of elvis' secret option. elvgdb includes this in the requests that it sends back to elvis. This is important because the for elvis to respond to the "breakpoints-invalid" annotation, it must send an "info breakpoints" command back to elvgdb by running ":!elvgdb -t info breakpoints". Normally elvis would refuse to execute ":!shellcmd" for a client due to security concerns, but we know that elvgdb can be trusted because it knows the right "secret" value.

FILES

elvgdb.ini
    This file resides somewhere in $ELVISPATH. It describes the appearance and behavior of each annotation. See the ELVGDB.INI section, above, for details.

SEE ALSO
elvis(1), gdb(1), xterm(1X)

Run "info gdb Annotations" for information about gdb's annotations.

AUTHOR
Steve Kirkendall
kirkenda@cs.pdx.edu