Defining Commands

Aside from breakpoint commands (see Breakpoint Commands), DDD also allows you to define user-defined commands. A user-defined command is a sequence of commands to which you assign a new name as a command. This new command can be entered at the debugger prompt or invoked via a button.

GDB Simple Commands:
GDB Argument Commands:
Commands with Other Debuggers:

Node:GDB Simple Commands, Next:GDB Argument Commands, Up:Defining Commands

Defining Simple Commands using GDB

Aside from breakpoint commands (see Breakpoint commands, above), DDD also allows you to store sequences of commands as a user-defined GDB command. A user-defined command is a sequence of GDB commands to which you assign a new name as a command. Using DDD, this is done via the Command Editor, invoked via Commands => Define Command.

A GDB command is created in five steps:

Enter the name of the command in the Command field. Use the drop-down list on the right to select from already defined commands.
Click on Record to begin the recording of the command sequence.
Now interact with DDD. While recording, DDD does not execute commands, but simply records them to be executed when the breakpoint is hit. The recorded debugger commands are shown in the debugger console.
To stop the recording, click on End or enter end at the GDB prompt. To cancel the recording, click on Interrupt or press <ESC>.
Click on Edit >> to edit the recorded commands. When done with editing, click on Edit << to close the commands editor.

After the command is defined, you can enter it at the GDB prompt. You may also click on Execute to test the given user-defined command.

For convenience, you can assign a button to the defined command. Enabling one of the Button locations will add a button with the given command to the specified location. If you want to edit the button, select Commands => Edit Buttons. See Defining Buttons, for a discussion.

When user-defined GDB 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.

Command definitions are saved across DDD sessions.

Node:GDB Argument Commands, Next:Commands with Other Debuggers, Previous:GDB Simple Commands, Up:Defining Commands

Defining Argument Commands using GDB

If you want to pass arguments to user-defined commands, you can enable the () toggle button in the Command Editor. Enabling () has two effects:

While recording commands, all references to the argument field are taken symbolically instead of literally. The argument field value is frozen to $arg0, which is how GDB denotes the argument of a user-defined command. When GDB executes the command, it will replace $arg0 by the current command argument.
When assigning a button to the command, the command will be suffixed by the current contents of the argument field.

While defining a command, you can toggle the () button as you wish to switch between using the argument field symbolically and literally.

As an example, let us define a command contuntil that will set a breakpoint in the given argument and continue execution.

Enter contuntil in the Command field.
Enable the () toggle button.
Now click on Record to start recording. Note that the contents of the argument field change to $arg0.
Click on Break at () to create a breakpoint. Note that the recorded breakpoint command refers to $arg0.
Click on Cont to continue execution.
Click on End to end recording. Note that the argument field is restored to its original value.
Finally, click on one of the Button locations. This creates a Contuntil () button where () will be replaced by the current contents of the argument field--and thus passed to the contuntil command.
You can now either use the Contuntil () button or enter a contuntil command at the GDB prompt. (If you plan to use the command frequently, you may wish to define a cu command, which again calls contuntil with its argument. This is a nice exercise.)

There is a little drawback with argument commands: a user-defined command in GDB has no means to access the argument list as a whole; only the first argument (up to whitespace) is processed. This may change in future GDB releases.

Node:Commands with Other Debuggers, Previous:GDB Argument Commands, Up:Defining Commands

Defining Commands using Other Debuggers

If your inferior debugger allows you to define own command sequences, you can also use these user-defined commands within DDD; just enter them at the debugger prompt.

However, you may encounter some problems:

In contrast to the well-documented commands of the inferior debugger, DDD does not know what a user-defined command does. This may lead to inconsistencies between DDD and the inferior debugger. For instance, if your the user-defined command bp sets a breakpoint, DDD may not display it immediately, because DDD does not know that bp changes the breakpoint state.
You cannot use DDD graph commands within user-defined commands. This is only natural, because user-defined commands are interpreted by the inferior debugger, which does not know about DDD commands.

As a solution, DDD provides a simple facility called Illegal HTML tag removed : auto-commands. If DDD receives any output from the inferior debugger in the form Illegal HTML tag removed : prefixIllegal HTML tag removed : command, it will interpret Illegal HTML tag removed : command as if it had been entered at the debugger prompt. Illegal HTML tag removed : prefix is a user-defined string, for example ddd: .

Suppose you want to define a command gd that serves as abbreviation for graph display. All the command gd has to do is to issue a string

     ddd: graph display 

**Illegal HTML tag removed :** argument

where Illegal HTML tag removed : argument is the argument given to gd. Using GDB, this can be achieved using the echo command. In your ~/.gdbinit file, insert the lines

     define gd
       echo ddd: graph display $arg0\n
     end

To complete the setting, you must also set the autoCommandPrefix resource to the ddd: prefix you gave in your command. In ~/.ddd/init, write:

     Ddd*autoCommandPrefix: ddd:\

(Be sure to leave a space after the trailing backslash.)

Entering gd foo will now have the same effect as entering graph display foo at the debugger prompt.

Please note: In your commands, you should choose some other prefix than ddd: . This is because auto-commands raise a security problem, since arbitrary commands can be executed. Just imagine some malicious program issuing a string like Illegal HTML tag removed : prefix shell rm -fr ~ when being debugged! As a consequence, be sure to choose your own Illegal HTML tag removed : prefix; it must be at least three characters long.

Node:Application Defaults, Next:Bugs, Previous:Commands, Up:Top

Defining Commands