4 CGDB configuration commands

By default, CGDB stores its user-specific files (such as command history, program logs, and config files) in the ~/.cgdb/ directory. This location is configurable; if the environment variable CGDB_DIR is set to a directory name, CGDB will use the specified directory instead of ~/.cgdb/.

There may be several features that you find useful in CGDB. CGDB is capable of automating any of these commands through the use of the config file called cgdbrc. It looks in $CGDB_DIR for that file, or in HOME/.cgdb/ if the CGDB_DIR environment variable is not set. If the cgdbrc file exists, CGDB executes each one of its lines in order. It is as if the user typed in all the commands into the status bar after the tui was initialized.

The following variables change the behavior of some aspect of CGDB. Many of these commands may be abbreviated in some way, and all boolean commands my be negated by appending ‘no’ to the front. For example: :set ignorecase turns on case-insensitive searching; while :set noignorecase turns on case-sensitive searching.

:set asr

:set autosourcereload

If this is on, CGDB will automatically reload a source file if it has changed since CGDB has opened it. If it is off, the file will never be reloaded, until you start CGDB again. The default is on. This feature is useful when you are debugging a program, then you modify a source file, recompile, and type r in GDB’s CLI window. The file in this case will be updated to show the new version. Note, CGDB only looks at the timestamp of the source file to determine if it has changed. So if you modify the source file, and didn’t recompile yet, CGDB will still pick up on the changes.

:set cgdbmodekey=key

This option is used to determine what key puts CGDB into CGDB Mode. By default, the ESC key is used. key can be any normal key on the keyboard. It can also be any keycode, as long as the keycode notation is used. This option is especially useful when the user wants to use readline in vi mode. If the user types set cgdbmodekey=<PageUp> then the Page Up key will put CGDB into CGDB mode and the ESC key will flow through to readline.

:set color

This option is used to enable or disable color support in CGDB. The default is on. When enabled, CGDB can display color when appropriate. This typically occurs when syntax highlighting source files in the source viewer. When disabled, CGDB will not display colors. It may instead use other terminal attributes for syntax highlighting, including bold and reverse attributes. See the highlight commamnd and look for the ‘cterm’ option.

It should be noted that even when color is enabled in CGDB, if ncurses declares that the terminal does not support colors, CGDB will not use colors.

:set dwc

:set debugwincolor

This option controls if the debug window will display colors or not. The default value is on. When enabled, if GDB or the program being debugged output an ANSI escape code representing color, then CGDB will display the corresponding color instead of the escape code. When disabled, CGDB will display the ANSI escape code in the debug window. See https://en.wikipedia.org/wiki/ANSI_escape_code#Colors to learn more about ANSI escape codes.

:set dis

:set disasm

This option is used to enable or disable showing assembly code in cgdb. The default value is off. When off, CGDB will display the source code to the user. When no source code is available, CGDB will display the assembly code. When this option is enabled, CGDB will display the mixed source and assembly when the source code is enabled and assembly code when the source code is not available. Please note that when assembly mode is displayed, it’s displayed per function instead of per file.

:set eld=style

:set executinglinedisplay=style

Set the executing line display to style. Possible values for style are ‘shortarrow’, ‘longarrow’, ‘highlight’, and ‘block’. Changes the display that is used to indicate the currently executing line in the source viewer. The default value is ‘longarrow’. The ‘shortarrow’ option draws an arrow next to the source line number. The ‘longarrow’ option also draws an arrow next to the source line number, but extends the arrow until the source code. The ‘highlight’ option draws the entire line in inverse video and the ‘block’ option draws an inverse block (cursor) next to the source code being executed.

:set hls

:set hlsearch

When enabled, if there is a previous search pattern, highlight all its matches. The default is disabled.

:set ic

:set ignorecase

Sets searching case insensitive. The default is off.

:set sbbs

:set scrollbackbuffersize

Set the size of the scrollback buffer for the gdb window to num lines. The default scrollback is 10000 lines.

:set sld=style

:set selectedlinedisplay=style

Set the selected line display to style. Possible values for style are ‘shortarrow’, ‘longarrow’, ‘highlight’, and ‘block’. Changes the display that is used to indicate the currently selected line in the source viewer. The default value is ‘block’. The ‘shortarrow’ option draws an arrow next to the source line number. The ‘longarrow’ option also draws an arrow next to the source line number, but extends the arrow until the source code. The ‘highlight’ option draws the entire line in inverse video and the ‘block’ option draws an inverse block (cursor) next to the source code being selected.

:set showmarks

This option controls if the source window will show marks or not. The default value is on. When enabled, CGDB will show the marks that the user has set in the vertical bar in the source window separating the line number from the source code.

:set sdc

:set showdebugcommands

If this is on, CGDB will show all of the commands that it sends to GDB. If it is off, CGDB will not show the commands that it gives to GDB. The default is off.

:set syn=style

:set syntax=style

Sets the current highlighting mode of the current file to have the syntax style. Possible values for syntax are ‘c’, ‘asm’, ‘d’, ‘go’, ‘ada’, ‘rust’, ‘off’, ‘no’, ‘on’ or ‘yes’. Normally, the user will never have to do this, since CGDB automatically detects what syntax a file should be based on its file extension. However, this feature can currently be useful for debugging purposes. ‘on’ and ‘yes’ enable syntax highlighting based on the source files extension. ‘off’ and ‘no’ disable syntax highlighting. The remaining values set the specific language highlighters independent of the source files extension.

:set to

:set timeout

This option is used along with the ttimeout option to determine the behavior CGDB should have when it receives part of a mapped key sequence or a keyboard code sequence. If this option is on, CGDB will time out on both user defined mappings and on key codes from the keyboard. If this option is off, user defined mappings will not be timed out on. In this case, CGDB will determine if it should time out on key codes from the keyboard by examining the ttimeout option. To determine how CGDB will time out on mappings and key codes, and what time out lengths CGDB will use, please refer to the chart in Key User Interface. The default value for this option is on.

:set tm=delay

:set timeoutlen=delay

This option is used along with the ttimeoutlen option. It represents the number of milliseconds that CGDB should wait for a key code from the keyboard or for a mapped key sequence to complete. If delay is 0, CGDB immediately accepts each character it receives. This will prevent any mappings or key codes to complete. delay may be any value between 0 and 10000, inclusive. The default setting for the delay variable is 1000 (one second).

:set ttimeout

This option is used along with the timeout option to determine the behavior CGDB should have when it receives part of keyboard code sequence. If this option is on, CGDB will time out on key codes from the keyboard. If this option is off, CGDB will determine if it should time out on key codes from the keyboard by examining the timeout option. To determine how CGDB will time out on key codes, what what time length it will use, please refer to the chart in Key User Interface. The default value for this option is on.

:set ttm=delay

:set ttimeoutlen=delay

This option is used along with the ttimeoutlen option. It represents the number of milliseconds that CGDB should wait for a key code from the keyboard. If delay is 0, CGDB immediately accepts each character it receives. This will prevent any key codes to complete. delay may be any value between 0 and 10000, inclusive. The default setting for the delay variable is 100 (one tenth of a second).

:set ts=number

:set tabstop=number

Sets the number of spaces that should be rendered on the screen for TAB characters. The default value for number is 8.

:set wmh=number

:set winminheight=number

The minimal height of a window. Windows will never become smaller than this value. The default value for number is 0. This is useful when winsplitorientation is set to ‘horizontal’.

:set wmw=number

:set winminwidth=number

The minimal width of a window. Windows will never become smaller than this value. The default value for number is 0. This is useful when winsplitorientation is set to ‘vertical’.

:set winsplit=style

Set the split point between source and GDB window. This is especially useful as an init setting in your cgdbrc file. See Configuring CGDB. The possible values for style are ‘src_full’, ‘src_big’, ‘even’, ‘gdb_big’, and ‘gdb_full’.

:set wso=style

:set winsplitorientation=style

Sets the window split orientation to either ‘horizontal’ (which places the source window above and the GDB window below), or ‘vertical’ ( hich places the source window on the left and the GDB window on the right). See Configuring CGDB.

:set ws

:set wrapscan

Searches wrap around the end of file. The default is on.

:c

:continue

Send a continue command to GDB.

:down

Send a down command to GDB.

:e

:edit

reloads the file in the source window. this can be useful if the file has changed since it was opened by cgdb.

:f

:finish

Send a finish command to GDB.

:help

This will display the current manual in text format, in the source window.

:logo

This will display one of CGDB’s logos in the source window.

:hi group cterm=attributes ctermfg=color ctermbg=color term=attributes

:highlight group cterm=attributes ctermfg=color ctermbg=color term=attributes

Set the color and attributes for a highlighting group. The syntax mimics vim’s “highlight” command. Possible values for group, attributes and color are available in Highlighting Groups.

You can give as many or as few of the name=value pairs as you wish, in any order. ‘ctermfg’ and ‘ctermbg’ set the foreground and background colors. These can be specified by color number or by using the same color names that vim uses. When CGDB is linked with ncurses, the number you use to represent the color can be between -1 and COLORS. When CGDB is linked against curses, it must be between 0 and COLORS.

‘cterm’ sets the video attributes for color terminals. ‘term’ sets the video attributes for monochrome terminals. Some examples are,

:highlight Logo cterm=bold,underline ctermfg=Red ctermbg=Black
:highlight Normal cterm=reverse ctermfg=White ctermbg=Black
:hi Normal term=bold

:insert

Move focus to the GDB window.

:n

:next

Send a next command to GDB.

:nexti

Send a nexti command to GDB.

:q

:quit

Quit CGDB.

:r

:run

Send a run command to GDB.

:start

Send a start command to GDB.

:k

:kill

Send a kill command to GDB.

:s

:step

Send a step command to GDB.

:stepi

Send a stepi command to GDB.

:syntax

Turn the syntax on or off.

:u

:until

Send an until command to GDB.

:up

Send an up command to GDB.

:map lhs rhs

Create a new mapping or overwrite an existing mapping in CGDB mode. After the command is run, if lhs is typed, CGDB will get rhs instead. For more details on how to use the map command look in Using Maps.

:unm lhs

:unmap lhs

Delete an existing mapping from CGDB mode. lhs is what was typed in the left hand side when the user created the mapping. For example, if the user typed :map a<Space>b foo then the user could delete the existing mapping with :unmap a<Space>b.

:im lhs rhs

:imap lhs rhs

Create a new mapping or overwrite an existing mapping in GDB mode. After the command is run, if lhs is typed, CGDB will get rhs instead. For more details on how to use the map command look in Using Maps.

:iu lhs

:iunmap lhs

Delete an existing mapping from GDB mode. lhs is what was typed in the left hand side when the user created the mapping. For example, if the user typed :imap a<Space>b foo then the user could delete the existing mapping with :iunmap a<Space>b.