package: terminator

title: terminator_config(5)

text:
# terminator_config(5)

## NAME
terminator_config - the config file for Terminator terminal emulator

## DESCRIPTION
This file contains the configuration for terminator(1). Terminator manages its configuration file via the ConfigObj library to combine flexibility with clear, human editable files.

Terminator offers a full GUI preferences editor which automatically saves its config file so you don’t need to write a config file by hand.

## FILE LOCATION
Normally the config file will be ~/.config/terminator/config, but it may be overridden with $XDG_CONFIG_HOME (in which case it will be $XDG_CONFIG_HOME/terminator/config).

## FILE FORMAT
This is what a Terminator config file should look like:

```
# This is a comment
[global_config]

  focus = system
[keybindings]

  full_screen = <Ctrl><Shift>F11
[profiles]

  [[default]]

    font = Fixed 10

    background_color = "#000000" # A comment

    foreground_color = "#FFFFFF" # Note that hex colour values must be quoted

    scrollback_lines = '500' #More comment. Single quotes are valid too

    cursor_blink = True

    custom_command = "echo \"foo#bar\"" #Final comment - this will work as expected.
[layouts]

  [[default]]

    [[[window0]]]

      type = Window

      parent = ""

    [[[child1]]]

      type = Terminal

      parent = window0
[plugins]
```

## GLOBAL_CONFIG
These are the options Terminator currently supports in the global_config section.

### Window Behavior & Appearance
window_state = string

Control how the Terminator window opens. 'normal' to open normally. 'maximise' to open in a maximised state. 'fullscreen' to open in a fullscreen state. 'hidden' to stay hidden.

Default value: normal

always_on_top = boolean

If set to True, the window will always stay on top of other windows.

Default value: False

sticky = boolean

If set to True, the window will be visible on all workspaces.

Default value: False

hide_on_lose_focus = boolean

If set to True, the window will be hidden when focus is lost.

Default value: False

hide_from_taskbar = boolean

If set to True, the window will be hidden from the taskbar.

Default value: False

geometry_hinting = boolean

If set to True, the window will resize in step with font sizes.

Default value: False

ask_before_closing = string

Specify when to ask for confirmation before closing a window or a tab. Can be any of: 'always', 'multiple_terminals', 'never'. Default value: multiple_terminals

borderless = boolean

If set to True, the window will be started without window borders.

Default value: False

### Tab Behavior & Appearance
tab_position = string

Specify where tabs are placed. Can be any of: 'top', 'left', 'right', 'bottom', 'hidden'. If set to 'hidden', the tab bar will not be shown. Hiding the tab is not recommended, as it can be very confusing.

Default value: top

close_button_on_tab = boolean

If set to True, tabs will have a close button on them.

Default value: True

scroll_tabbar = boolean

If set to True, the tab bar will not fill the width of the window. The titlebars of the tabs will only take as much space as is necessary for the text they contain. Except, that is, if the tabs no longer fit the width of the window - in that case scroll buttons will appear to move through the tabs.

Default value: False

### Terminal Behavior & Appearance
focus = string

Specify how focus is given to terminals. 'click' means the focus only moves to a terminal after you click in it. 'sloppy' means the focus will follow the mouse pointer. 'system' means the focus will match that used by a GNOME window manager.

Default value: click

always_split_with_profile = boolean

Specify whether splits/tabs will continue to use the profile of their peer terminal. If set to False, they will always use the default profile.

Default value: False

link_single_click = boolean

If set to True, clicking a link will open it even if Ctrl is not pressed.

Default value: False

putty_paste_style = boolean

If set to True, right-click will paste text, while middle-click will popup the context menu. The source for the pasted text depends on the value of putty_paste_style_source_clipboard.

Default value: False

putty_paste_style_source_clipboard = boolean

If set to True, the Clipboard will be used as source for pasting in PuTTY style. Otherwise, the Primary Selection will be used.

This option is ignored unless putty_paste_style is set to True.

Default value: False

disable_mouse_paste = boolean

If set to True, mouse pasting will be disabled.

Default value: False

smart_copy = boolean

If set to True, and there is no selection, the shortcut is allowed to pass through. This is useful for overloading Ctrl-C to copy a selection, or send the SIGINT to the current process if there is no selection. If False, the shortcut does not pass through at all, and the SIGINT does not get sent.

Default value: True

clear_select_on_copy = boolean

If set to True, text selection will be cleared after copying using the copy keybinding.

Default value: False

handle_size = integer

Specify the width of the separator between terminals. Anything outside the range 0-20 (inclusive) will be ignored and the default theme value will be used instead.

Default value: 1

inactive_color_offset = float

Specify how much to reduce the color values of fonts in terminals that do not have focus.

Default value: 0.8

inactive_bg_color_offset = float

Specify how much to reduce the color values of the background in terminals that do not have focus.

Default value: 1.0

cell_width = float

Specify the horizontal scale of character cells in the terminal.

Default value: 1.0

cell_height = float

Specify the vertical scale of character cells in the terminal.

Default value: 1.0

title_at_bottom = boolean

If set to True, the terminal’s titlebar will be drawn at the bottom instead of the top.

Default value: False

### Miscellaneous
dbus = boolean

Specify whether Terminator will load its DBus server. When this server is loaded, running Terminator multiple times will cause the first Terminator process to open additional windows. If this configuration item is set to False, or the python dbus module is unavailable, running Terminator multiple times will run a separate Terminator process for each invocation.

Default value: True

extra_styling = boolean

If set to True, Terminator may load an additional CSS styling file, depending on the theme.

Default value: True

broadcast_default = string

Specify the default broadcast behavior. Can be any of: 'all', 'group', 'off'.

Default value: group

use_custom_url_handler = boolean

If set to True, URL handling will be given over entirely to the program specified by 'custom_url_handler'.

Default value: False

custom_url_handler = string

Specify the path to a program which accepts a URI as an argument and does something relevant with it. This option is ignored unless use_custom_url_handler is set to True.

case_sensitive = boolean

If set to True, uppercase and lowercase characters will be considered different when searching text in the terminal.

Default value: True

invert_search = boolean

If set to True, the search direction will be inverted (bottom to top) when searching text in the terminal.

Default value: False

enabled_plugins = list of strings

Specify which plugins will be loaded by default. All other plugin classes will be ignored.

Default value: ['LaunchpadBugURLHandler', 'LaunchpadCodeURLHandler', 'APTURLHandler']

## KEYBINDINGS
These are the options Terminator currently supports in the keybindings section.

### Creation & Destruction
split_horiz

Split the current terminal horizontally.

Default value: <Ctrl><Shift>O

split_vert

Split the current terminal vertically.

Default value: <Ctrl><Shift>E

split_auto

Split the current terminal automatically, along the longer side.

Default value: <Ctrl><Shift>A

new_tab

Open a new tab.

Default value: <Ctrl><Shift>T

new_window

Open a new window as part of the existing process.

Default value: <Ctrl><Shift>I

new_terminator

Spawn a new Terminator process.

Default value: <Super>I

layout_launcher

Open the layout launcher.

Default value: <Alt>L

close_term

Close the current terminal.

Default value: <Ctrl><Shift>W

close_window

Close the current window.

Default value: <Ctrl><Shift>Q

### Navigation
cycle_next

Focus the next terminal. This is an alias for go_next.

Default value: <Ctrl>Tab

cycle_prev

Focus the previous terminal. This is an alias for go_prev.

Default value: <Ctrl><Shift>Tab

go_next

Focus the next terminal.

Default value: <Ctrl><Shift>N

go_prev

Focus the previous terminal.

Default value: <Ctrl><Shift>P

go_up

Focus the terminal above the current one.

Default value: <Alt>Up

go_down

Focus the terminal below the current one.

Default value: <Alt>Down

go_left

Focus the terminal to the left of the current one.

Default value: <Alt>Left

go_right

Focus the terminal to the right of the current one.

Default value: <Alt>Right

page_up

Scroll the terminal up one page.

page_down

Scroll the terminal down one page.

page_up_half

Scroll the terminal up half a page.

page_down_half

Scroll the terminal down half a page.

line_up

Scroll the terminal up one line.

line_down

Scroll the terminal down one line.

next_tab

Move to the next tab.

Default value: <Ctrl>Page_Down

prev_tab

Move to the previous tab.

Default value: <Ctrl>Page_Up

switch_to_tab_1, switch_to_tab_2, ... switch_to_tab_10

Move to the Nth tab. Note that <Alt><Shift>1 may be provided as <Alt>! or similar, depending on the keyboard layout.

### Organisation
resize_up

Move the parent dragbar up.

Default value: <Ctrl><Shift>Up

resize_down

Move the parent dragbar down.

Default value: <Ctrl><Shift>Down

resize_left

Move the parent dragbar left.

Default value: <Ctrl><Shift>Left

resize_right

Move the parent dragbar right.

Default value: <Ctrl><Shift>Right

rotate_cw

Rotate terminals clockwise.

Default value: <Super>R

rotate_ccw

Rotate terminals counter+clockwise.

Default value: <Super><Shift>R

move_tab_right

Move the current tab to the right by swapping position with the next tab.

Default value: <Ctrl><Shift>Page_Down

move_tab_left

Move the current tab to the left by swapping position with the previous tab.

Default value: <Ctrl><Shift>Page_Up

### Focus
full_screen

Toggle window to fullscreen.

Default value: F11

toggle_zoom

Toggle maximisation of the current terminal.

Default value: <Ctrl><Shift>X

scaled_zoom

Toggle maximisation of the current terminal and scale the font when maximised.

Default value: <Ctrl><Shift>Z

hide_window

Hide/Show all Terminator windows.

Default value: <Ctrl><Shift><Alt>A

### Grouping & Broadcasting
create_group

Create a new group.

group_all

Group all terminals together.

Default value: <Super>G

ungroup_all

Ungroup all terminals.

group_all_toggle

Toggle grouping of all terminals.

group_win

Group all terminals in the current window together.

ungroup_win

Ungroup all terminals in the current window.

Default value: <Super><Shift>W

group_win_toggle

Toggle grouping of all terminals in the current window.

group_tab

Group all terminals in the current tab together.

Default value: <Super>T

ungroup_tab

Ungroup all terminals in the current tab.

Default value: <Super><Shift>T

group_tab_toggle

Toggle grouping of all terminals in the current tab.

broadcast_off

Turn broadcasting off.

broadcast_group

Broadcast to all terminals in the same group as the current terminal.

broadcast_all

Broadcast to all terminals.

### Miscellaneous
help

Open the full HTML manual in the browser.

Default value: F1

preferences

Open the Preferences window.

preferences_keybindings

Open the Preferences window and show the Keybindings tab.

Default value: <Ctrl><Shift>K

copy

Copy the selected text to the Clipboard.

Default value: <Ctrl><Shift>C

paste

Paste the current contents of the Clipboard.

Default value: <Ctrl><Shift>V

paste_selection

Paste the current contents of the Primary Selection.

toggle_scrollbar

Toggle the scrollbar.

Default value: <Ctrl><Shift>S

search

Search for text in the terminal scrollback history.

Default value: <Ctrl><Shift>F

reset

Reset the terminal state.

Default value: <Ctrl><Shift>R

reset_clear

Reset the terminal state and clear the terminal window.

Default value: <Ctrl><Shift>G

zoom_in

Increase the font size by one unit.

Default value: <Ctrl>plus

zoom_out

Decrease the font size by one unit.

Default value: <Ctrl>minus

zoom_normal

Restore the original font size.

Default value: <Ctrl>0

zoom_in_all

Increase the font size by one unit for all terminals.

zoom_out_all

Decrease the font size by one unit for all terminals.

zoom_normal_all

Restore the original font size for all terminals.

edit_window_title

Rename the current window.

Default value: <Ctrl><Alt>W

edit_tab_title

Rename the current tab.

Default value: <Ctrl><Alt>A

edit_terminal_title

Rename the current terminal.

Default value: <Ctrl><Alt>X

insert_number

Insert the current terminal’s number, i.e. 1 to 12.

Default value: <Super>1

insert_padded

Insert the current terminal’s number, but zero padded, i.e. 01 to 12.

Default value: <Super>0

next_profile

Switch to the next profile.

previous_profile

Switch to the previous profile.

## PROFILES
These are the options Terminator currently supports in the profiles section. Each profile should be its own subsection with a header in the format [[name]].

### General
allow_bold = boolean

If set to True, text in the terminal can displayed in bold.

Default value: True

copy_on_selection = boolean

If set to True, text selections will be automatically copied to the Clipboard, in addition to being copied to the Primary Selection.

Default value: False

disable_mousewheel_zoom = boolean

If set to True, Ctrl+mouse_wheel will not zoom or unzoom the terminal.

Default value: False

word_chars = string

Specify the characters that will be considered part of a single word when selecting text by word. Hyphen and alphanumerics do not need to be specified. Ranges can be given, e.g. "A-Z".

For example, if word_chars = "," then "foo,bar" is considered a single word.

Default value: -,./?%&#:_

mouse_autohide = boolean

If set to True, the mouse pointer will be hidden when typing.

Default value: True

term = string

Specify the value Terminator will assign to the 'TERM' environment variable.

Default value: xterm-256color

colorterm = string

Specify the value Terminator will assign to the 'COLORTERM' environment variable.

Default value: truecolor

split_to_group = boolean

If set to True, the terminal created by splitting will be inserted in the current terminal’s group.

Default value: False

autoclean_groups = boolean

If set to True, empty groups will be removed.

Default value: True

use_system_font = boolean

If set to True, the system default font will be used for text in the terminal. Otherwise, the value of font will be used.

Default value: True

font = string

Specify which font to use for text in the terminal. This option is ignored unless use_system_font is set to False.

Default value: Mono 10

cursor_blink = boolean

If set to True, the cursor will blink when not typing.

Default value: True

cursor_shape = string

Specify the shape of the cursor. Can be any of: 'block', 'underline', 'ibeam'.

Default value: block

cursor_color_default = boolean

If set to True, the background and foreground colors of the terminal will be used as foreground and background colors for the cursor, respectively.

Default value: True

cursor_fg_color = color string

Specify the foreground color to use for the cursor. This option is ignored unless cursor_color_default is set to False.

cursor_bg_color = color string

Specify the background color to use for the cursor. This option is ignored unless cursor_color_default is set to False.

audible_bell = boolean

If set to True, a sound will be played when an application writes the escape sequence for the terminal bell.

Default value: False

visible_bell = boolean

If set to True, the terminal will flash when an application writes the escape sequence for the terminal bell.

Default value: False

urgent_bell = boolean

If set to True, the window’s urgency hint will be set when an application writes the escape sequence for the terminal bell.

Default value: False

icon_bell = boolean

If set to True, a small icon will be shown on the terminal titlebar when an application writes the escape sequence for the terminal bell.

Default value: True

force_no_bell = boolean

If set to True, the terminal bell will be completely disabled.

Default value: False

### Command
login_shell = boolean

If set to True, the terminal will run the default shell (or the command specified by custom_command) as a login shell. This means the first argument passed to the shell/command will be '-l'.

Default value: False

use_custom_command = boolean

If set to True, the value of custom_command will be used instead of the default shell.

Default value: False

custom_command = string

Specify the command to execute instead of the default shell. This option is ignored unless use_custom_command is set to True.

exit_action = string

Specify the action to perform when the terminal is closed. 'close' to remove the terminal. 'restart' to restart the shell (or the command specified by custom_command). 'hold' to keep the terminal open, even if the process in it has terminated.

Default value: close

### Colors
use_theme_colors = boolean

If set to True, the theme’s foreground and background colors will be used for the terminal. Otherwise, the values of foreground_color and background_color will be used.

Default value: False

foreground_color = color string

Specify the foreground color to use for the terminal. This option is ignored unless use_theme_colors is set to False.

Default value: #AAAAAA

background_color = color string

Specify the background color to use for the terminal. This option is ignored unless use_theme_colors is set to False.

Default value: #000000

palette = string list of colors

Specify the 16-color palette to use for the terminal. The value must be a string containing a colon-separated list of colors in hex format.

For example, "#000000:#cd0000:#00cd00: ... ".

bold_is_bright = boolean

If set to True, bold text will have brighter colors.

Default value: False

### Background
background_darkness = float

Specify the transparency of the background color. The value must be between 0.0 and 1.0. This option is ignored unless background_type is set to 'transparent' or 'image'.

Default value: 0.5

background_type = string

Specify what type of background the terminal will have. 'solid' for a solid (opaque) background. 'transparent' for a transparent background. 'image' for a background image.

If this is set to 'transparent', the transparency of the background will be the value of background_darkness. If this is set to 'image', the image specified by background_image will be the background; the background color will then be drawn on top of it, with a transparency specified by background_darkness.

Default value: solid

background_image = path string

Specify the path to an image that will be used as background. This option is ignored unless background_type is set to 'image'.

background_image_mode = string

Specify how the background image will be drawn. 'stretch_and_fill' to fill the terminal entirely, without necessarily maintaining aspect ratio. 'scale_and_fit' to fit the image inside the terminal, eventually leaving blank bars, while maintaining aspect ratio. 'scale_and_crop' to fill the terminal entirely, eventually cropping the image, while maintaining aspect ratio. 'tiling' to repeat the image as to fill the terminal. This option is ignored unless background_type is set to 'image'.

Default value: stretch_and_fill

background_image_align_horiz = string

Specify the horizontal alignment of the background image. Can be any of: 'left', 'center', 'right'. This option is ignored unless background_type is set to 'image'.

Default value: center

background_image_align_vert = string

Specify the vertical alignment of the background image. Can be any of: 'top', 'middle', 'bottom'. This option is ignored unless background_type is set to 'image'.

Default value: middle

### Scrolling
scrollbar_position = string

Specify where the terminal scrollbar is put. Can be any of: 'left', 'right', 'hidden'.

Default value: right

scroll_on_output = boolean

If set to True, the terminall will scroll to the bottom when an application writes text to it.

Default value: False

scroll_on_keystroke = boolean

If set to True, the terminal will scroll to the bottom when typing.

Default value: True

scrollback_infinite = boolean

If set to True, the terminal will keep the entire scrollback history.

Default value: False

scrollback_lines = integer

Specify how many lines of scrollback history will be kept by the terminal. Lines that don’t fit in the scrollback history will be discarted. Note that setting large values can slow down rewrapping and resizing. This option is ignored unless scrollback_infinite is set to False.

Default value: 500

### Compatibility
backspace_binding = string

Specify what code will be generated by the backspace key. The value can be: 'ascii-del' for the ASCII DEL character; 'control-h' for the ASCII BS character (Ctrl+H); 'escape-sequence' for the escape sequence typically bound to backspace or delete; 'automatic' for letting the terminal automatically decide the character sequence to use.

Default value: ascii-del

delete_binding = string

Specify what code will be generated by the delete key. The value can be: 'ascii-del' for the ASCII DEL character; 'control-h' for the ASCII BS character (Ctrl+H); 'escape-sequence' for the escape sequence typically bound to backspace or delete; 'automatic' for letting the terminal automatically decide the character sequence to use.

Default value: escape-sequence

### Titlebar
show_titlebar = boolean

If set to True, the terminal will have a titlebar showing the current title of that terminal.

Default value: True

title_hide_sizetext = boolean

If set to True, the size of the terminal will not be written on its titlebar.

Default value: False

title_use_system_font = boolean

If set to True, the system default font will be used for text in the terminal’s titlebar. Otherwise, the value of title_font will be used.

Default value: True

title_font = string

Specify which font to use for text in the terminal’s titlebar. This option is ignored unless title_use_system_font is set to False.

Default value: Sans 9

title_transmit_fg_color = color string

Specify the foreground color to use for the terminal’s titlebar in case the terminal is focused.

Default value: #ffffff

title_transmit_bg_color = color string

Specify the background color to use for the terminal’s titlebar in case the terminal is focused.

Default value: #c80003

title_inactive_fg_color = color string

Specify the foreground color to use for the terminal’s titlebar in case the terminal is unfocused.

Default value: #000000

title_inactive_bg_color = color string

Specify the background color to use for the terminal’s titlebar in case the terminal is unfocused.

Default value: #c0bebf

title_receive_fg_color = color string

Specify the foreground color to use for the terminal’s titlebar in case the terminal is in a group and is receiving input while unfocused.

Default value: #ffffff

title_receive_bg_color = color string

Specify the background color to use for the terminal’s titlebar in case the terminal is in a group and is receiving input while unfocused.

Default value: #0076c9

## LAYOUTS
The layouts section contains all the saved layouts. Each layout should be its own subsection with a header in the format [[name]].

Each object in a layout is a named sub-sub-section with various properties.

type = string

Can be any of: 'Window', 'Notebook', 'HPaned', 'VPaned', 'Terminal'.

parent = string

Specify which object is the parent of the component being defined. All objects, except those of type Window, must specify a parent.

This is an example of a layouts section containing only the layout named "default".

```
[layouts]

  [[default]]

    [[[window0]]]

      type = Window

      parent = ""

    [[[child1]]]

      type = Terminal

      parent = window0
```

## PLUGINS
Terminator plugins can add their own configuration to the config file, and it will appear as a subsection. Please refer to the documentation of individual plugins for more information.

## SEE ALSO
terminator(1), <https://configobj.readthedocs.io/>


package: terminfo

title: scr_dump(5)

text:
# scr_dump(5)

## NAME
scr_dump - curses screen dump

## DESCRIPTION
The curses library provides applications with the ability to write the contents of a window to an external file using scr_dump or putwin, and read it back using scr_restore or getwin.

The putwin and getwin functions do the work; while scr_dump and scr_restore conveniently save and restore the whole screen, i.e., stdscr.

### ncurses6
A longstanding implementation of screen-dump was revised with ncurses6 to remedy problems with the earlier approach:

•

A “magic number” is written to the beginning of the dump file, allowing applications (such as file(1)) to recognize curses dump files.

Because ncurses6 uses a new format, that requires a new magic number was unused by other applications. This 16-bit number was unused:

```
0x8888 (octal “\210\210”)
```

but to be more certain, this 32-bit number was chosen:

```
0x88888888 (octal “\210\210\210\210”)
```

This is the pattern submitted to the maintainers of the file program:

```
#
# ncurses5 (and before) did not use a magic number,
# making screen dumps "data".
#
# ncurses6 (2015) uses this format, ignoring byte-order
0    string    \210\210\210\210ncurses    ncurses6 screen image
#
```

•

The screen dumps are written in textual form, so that internal data sizes are not directly related to the dump-format, and enabling the library to read dumps from either narrow- or wide-character- configurations.

The narrow library configuration holds characters and video attributes in a 32-bit chtype, while the wide-character library stores this information in the cchar_t structure, which is much larger than 32-bits.

- It is possible to read a screen dump into a terminal with a different screen-size, because the library truncates or fills the screen as necessary.

- The ncurses6 getwin reads the legacy screen dumps from ncurses5.

### ncurses5 (Legacy)
The screen-dump feature was added to ncurses in June 1995. While there were fixes and improvements in succeeding years, the basic scheme was unchanged:

- The WINDOW structure was written in binary form.

- The WINDOW structure refers to lines of data, which were written as an array of binary data following the WINDOW.

- When getwin restored the window, it would keep track of offsets into the array of line-data and adjust the WINDOW structure which was read back into memory.

This is similar to Unix System V, but does not write a “magic number” to identify the file format.

## PORTABILITY
There is no standard format for curses screen dumps. A brief survey of the existing implementations follows.

### X/Open Curses
X/Open Curses Issue 7 specifies little. It says (boldface emphasis added)

“[t]he getwin() function reads window-related data stored in the file by putwin(). The function then creates and initializes a new window using that data.

The putwin() function writes all data associated with win into the stdio stream to which filep points, using an unspecified format. This information can be retrieved later using getwin().”

In the mid-1990s when the X/Open Curses document was written, there were still System V systems using older, less capable curses libraries. BSD curses was not relevant to X/Open because it did not meet the criteria for base-level conformance; see ncurses(3X).

### System V
System V curses identified the file format by writing a “magic number” at the beginning of the dump. The WINDOW data and the lines of text follow, all in binary form.

Solaris curses has the following definitions.

```
/* terminfo magic number */
#define MAGNUM  0432
/* curses screen dump magic number */
#define SVR2_DUMP_MAGIC_NUMBER  0433
#define SVR3_DUMP_MAGIC_NUMBER  0434
```

That is, the feature was likely introduced in SVr2 (1984), and improved in SVr3 (1987). Solaris curses has no magic number for SVr4 (1989). Other System V operating systems (AIX and HP-UX) use a magic number that would correspond to the following.

```
/* curses screen dump magic number */
#define SVR4_DUMP_MAGIC_NUMBER  0435
```

That octal number in bytes is 001, 035. Because most Unix vendors at the time used big-endian hardware, the magic number is written with the high-order byte first.

```
\001\035
```

After the magic number, the WINDOW structure and line data are written in binary format. While the magic number used by these systems can be observed with od(1), none of them documents the format used for screen dumps.

Nor do they use an identical format, even with the System V family. The ncurses savescreen test program was used to collect information for this manual page. It produced dumps of different size (all on 64-bit hardware, on 40x80 screens):

- AIX (51817 bytes)

- HP-UX (90093 bytes)

- Solaris 10 (13273 bytes)

- ncurses5 (12888 bytes)

### Solaris
As noted above, Solaris curses has no magic number corresponding to SVr4 curses. This is odd, since Solaris was the first operating system to meet the SVr4 guidelines. Solaris furthermore supplies two versions of curses.

- The default curses library uses the SVr3 magic number.

- An alternate curses library (which we term xcurses), available in /usr/xpg4, uses a textual format with no magic number.

According to its copyright notice, this xcurses library was developed by MKS (Mortice Kern Systems) from 1990 to 1995.

Like ncurses6, it includes a header with parameters. Unlike ncurses6, the contents of the window are written piecemeal, with coordinates and attributes for each chunk of text rather than writing the whole window from top to bottom.

### PDCurses
PDCurses added support for screen dumps in version 2.7 (2005). Like System V and ncurses5, it writes the WINDOW structure in binary, but begins the file with its three-byte identifier “PDC”, followed by a single-byte version number.

```
	“PDC\001”
```

### NetBSD
As of April 2017, NetBSD curses does not support scr_dump and scr_restore (or scr_init, scr_set), although it has putwin and getwin.

Like ncurses5, NetBSD putwin does not identify its dumps with a useful magic number. It writes

- the curses shared library major and minor versions as the first two bytes (for example, 7 and 1),

- followed by a binary dump of the WINDOW,

- some data for wide characters referenced by the WINDOW structure, and

- finally, lines as done by other implementations.

## EXAMPLES
Given a simple program which writes text to the screen (and for the sake of example, limiting the screen-size to 10x20):

```
#include <curses.h>
int
main(void)
{

    putenv("LINES=10");

    putenv("COLUMNS=20");

    initscr();

    start_color();

    init_pair(1, COLOR_WHITE, COLOR_BLUE);

    init_pair(2, COLOR_RED, COLOR_BLACK);

    bkgd(COLOR_PAIR(1));

    move(4, 5);

    attron(A_BOLD);

    addstr("Hello");

    move(5, 5);

    attroff(A_BOLD);

    attrset(A_REVERSE | COLOR_PAIR(2));

    addstr("World!");

    refresh();

    scr_dump("foo.out");

    endwin();

    return 0;
}
```

When run using ncurses6, the output looks like this:

```
\210\210\210\210ncurses 6.0.20170415
_cury=5
_curx=11
_maxy=9
_maxx=19
_flags=14
_attrs=\{REVERSE|C2}
flag=_idcok
_delay=-1
_regbottom=9
_bkgrnd=\{NORMAL|C1}\s
rows:
1:\{NORMAL|C1}\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s
2:\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s
3:\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s
4:\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s
5:\s\s\s\s\s\{BOLD}Hello\{NORMAL}\s\s\s\s\s\s\s\s\s\s
6:\s\s\s\s\s\{REVERSE|C2}World!\{NORMAL|C1}\s\s\s\s\s\s\s\s\s
7:\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s
8:\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s
9:\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s
10:\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s\s
```

The first four octal escapes are actually nonprinting characters, while the remainder of the file is printable text. You may notice:

- The actual color pair values are not written to the file.

- All characters are shown in printable form; spaces are “\s” to ensure they are not overlooked.

- Attributes are written in escaped curly braces, e.g., “\{BOLD}”, and may include a color pair (C1 or C2 in this example).

- The parameters in the header are written out only if they are nonzero. When reading back, order does not matter.

Running the same program with Solaris xpg4 curses gives this dump:

```
MAX=10,20
BEG=0,0
SCROLL=0,10
VMIN=1
VTIME=0
FLAGS=0x1000
FG=0,0
BG=0,0,
0,0,0,1,
0,19,0,0,
1,0,0,1,
1,19,0,0,
2,0,0,1,
2,19,0,0,
3,0,0,1,
3,19,0,0,
4,0,0,1,
4,5,0x20,0,Hello
4,10,0,1,
4,19,0,0,
5,0,0,1,
5,5,0x4,2,World!
5,11,0,1,
5,19,0,0,
6,0,0,1,
6,19,0,0,
7,0,0,1,
7,19,0,0,
8,0,0,1,
8,19,0,0,
9,0,0,1,
9,19,0,0,
CUR=11,5
```

Solaris getwin requires that all parameters are present, and in the same order. The xpg4 curses library does not know about the bce (back color erase) capability, and does not color the window background.

On the other hand, the SVr4 curses library does know about the background color. However, its screen dumps are in binary. Here is the corresponding dump (using “od -t x1”):

```
0000000 1c 01 c3 d6 f3 58 05 00 0b 00 0a 00 14 00 00 00
0000020 00 00 02 00 00 00 00 00 00 00 00 00 00 00 00 00
0000040 00 00 b8 1a 06 08 cc 1a 06 08 00 00 09 00 10 00
0000060 00 00 00 80 00 00 20 00 00 00 ff ff ff ff 00 00
0000100 ff ff ff ff 00 00 00 00 20 80 00 00 20 80 00 00
0000120 20 80 00 00 20 80 00 00 20 80 00 00 20 80 00 00
*
0000620 20 80 00 00 20 80 00 00 20 80 00 00 48 80 00 04
0000640 65 80 00 04 6c 80 00 04 6c 80 00 04 6f 80 00 04
0000660 20 80 00 00 20 80 00 00 20 80 00 00 20 80 00 00
*
0000740 20 80 00 00 20 80 00 00 20 80 00 00 57 00 81 00
0000760 6f 00 81 00 72 00 81 00 6c 00 81 00 64 00 81 00
0001000 21 00 81 00 20 80 00 00 20 80 00 00 20 80 00 00
0001020 20 80 00 00 20 80 00 00 20 80 00 00 20 80 00 00
*
0001540 20 80 00 00 20 80 00 00 00 00 f6 d1 01 00 f6 d1
0001560 08 00 00 00 40 00 00 00 00 00 00 00 00 00 00 07
0001600 00 04 00 01 00 01 00 00 00 01 00 00 00 00 00 00
0001620 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
*
0002371
```

## AUTHORS
Thomas E. Dickey

extended screen-dump format for ncurses 6.0 (2015)

Eric S. Raymond

screen dump feature in ncurses 1.9.2d (1995)

## SEE ALSO
curs_scr_dump(3X), curs_util(3X)


term

title: term(5)

text:
# term(5)

## NAME
term - compiled terminfo terminal description

## DESCRIPTION
tic(1) compiles a terminfo terminal type description, and setupterm(3X) reads it. A compiled description may be stored in a file or in a database of, potentially, many such descriptions. Further, a compiled description may be in one of two formats: one similar to that used by System V, and a newer, extensible format employed exclusively by ncurses.

### Storage Location
Compiled terminfo descriptions are placed under the directory /usr/share/terminfo. One of two configurations is selected when building the ncurses libraries.

directory tree

A two-level scheme is used to avoid a linear search of a huge Unix system directory: /usr/share/terminfo/c/name where name is the name of the terminal, and c is the first character of name. Thus, the compiled description of terminal type “act4” is found in the file /usr/share/terminfo/a/act4. Synonyms for the same terminal are implemented by multiple links to the same compiled file.

hashed database

Using the Berkeley database API, two types of records are stored: the terminfo data in the same format as that stored in a directory tree with the terminal's primary type name as a key, and records containing only aliases pointing to the primary name.

If built to write hashed databases, ncurses can still read terminfo databases organized as a directory tree, but cannot write entries into the directory tree. It can write (or rewrite) entries in the hashed database.

ncurses distinguishes the two cases in the TERMINFO and TERMINFO_DIRS environment variable by assuming a directory tree for entries that correspond to an existing directory, and a hashed database otherwise.

### Legacy Storage Format
The format has been chosen so that it will be the same on all hardware. A byte of at least eight bits' width is assumed, but no assumptions about bit ordering or sign extension are made.

The file is divided into six parts:

(a)

header,

(b)

terminal names,

(c)

Boolean flags,

(d)

numbers,

(e)

strings, and

(f)

a string table.

The header section begins the file. This section contains six short integers in the format described below. These integers are

(1) the magic number

(octal 0432);

(2) the size,

in bytes, of the terminal names section;

(3) the number of bytes in the Boolean flags section;

(4) the number of short integers in the numbers section;

(5) the number of offsets

(short integers) in the strings section;

(6) the size,

in bytes, of the string table.

The capabilities in the Boolean flags, numbers, and strings sections are in the same order as in the header file term.h.

Short integers are signed, in the range -32768 to 32767, and stored in little-endian format.

Numbers in a terminal description, whether they are entries in the numbers or strings table, are positive integers. Boolean flags are treated as positive one-byte integers. In each case, those positive integers represent a terminal capability. The terminal compiler tic uses negative integers to handle the cases where a capability is not available:

•

If a capability is absent from this terminal, tic stores a -1 in the corresponding table.

The integer value -1 is represented by two bytes 0377, 0377.

Absent Boolean values are represented by the byte 0 (false).

•

If a capability has been canceled from this terminal, tic stores a -2 in the corresponding table.

The integer value -2 is represented by two bytes 0377, 0376.

The Boolean value -2 is represented by the byte 0376.

•

Other negative values are illegal.

The terminal names section comes after the header. It contains the first line of the terminfo description, listing the various names for the terminal, separated by the “|” character. The terminal names section is terminated with an ASCII NUL character.

The Boolean flags section has one byte for each flag. Boolean capabilities are either 1 or 0 (true or false) according to whether the terminal supports the given capability or not.

Between the Boolean flags section and the number section, a null byte will be inserted, if necessary, to ensure that the number section begins on an even byte This is a relic of the PDP-11's word-addressed architecture, originally designed to avoid traps induced by addressing a word on an odd byte boundary. All short integers are aligned on a short word boundary.

The numbers section is similar to the Boolean flags section. Each capability takes up two bytes, and is stored as a little-endian short integer.

The strings section is also similar. Each capability is stored as a short integer. The capability value is an index into the string table.

The string table is the last section. It contains all of the values of string capabilities referenced in the strings section. Each string is null-terminated. Special characters in ^X or \c notation are stored in their interpreted form, not the printing representation. Padding information $<nn> and parameter information %x are stored intact in uninterpreted form.

### Extended Storage Format
The previous section describes the conventional terminfo binary format. With some minor variations of the offsets (see PORTABILITY), the same binary format is used in all modern Unix systems. Each system uses a predefined set of Boolean, number or string capabilities.

The ncurses libraries and applications support extended terminfo binary format, allowing users to define capabilities that are loaded at runtime. This extension is made possible by using the fact that the other implementations stop reading the terminfo data when they reach the end of the size given in the header. ncurses checks the size, and if it exceeds that due to the predefined data, continues to parse according to its own scheme.

First, it reads the extended header (5 short integers):

(1)

count of extended Boolean capabilities

(2)

count of extended numeric capabilities

(3)

count of extended string capabilities

(4)

count of the items in extended string table

(5)

size of the extended string table in bytes

The count- and size-values for the extended string table include the extended capability names as well as extended capability values.

Using the counts and sizes, ncurses allocates arrays and reads data for the extended capabilities in the same order as the header information.

The extended string table contains values for string capabilities. After the end of these values, it contains the names for each of the extended capabilities in order: Boolean, numeric, and string.

By storing terminal descriptions in this way, ncurses is able to provide a database useful with legacy applications, as well as providing data for applications that require more information about a terminal type than was anticipated by X/Open Curses. See user_caps(5) for an overview of the way ncurses uses this extended information.

Applications that manipulate terminal data can use the definitions described in term_variables(3X) associating the long capability names with members of a TERMTYPE structure.

### Extended Number Format
On occasion, 16-bit signed integers are not large enough. ncurses 6.1 introduced a new format by making a few changes to the legacy format:

- a different magic number (octal 01036)

- changing the type for the number array from signed 16-bit integers to signed 32-bit integers.

To maintain compatibility, the library presents the same data structures to direct users of the TERMTYPE structure as in previous formats. However, that cannot provide callers with the extended numbers. The library uses a similar but hidden data structure TERMTYPE2 to provide data for the terminfo functions.

## FILES
/usr/share/terminfo

compiled terminal description database

## PORTABILITY

### setupterm
Note that it is possible for setupterm to expect a different set of capabilities than are actually present in the file. Either the database may have been updated since setupterm was recompiled (resulting in extra unrecognized entries in the file) or the program may have been recompiled more recently than the database was updated (resulting in missing entries). The routine setupterm must be prepared for both possibilities - this is why the numbers and sizes are included. Also, new capabilities must always be added at the end of the lists of Boolean, number, and string capabilities.

### Binary Format
X/Open Curses does not specify a format for the terminfo database. System V curses used a directory-tree of binary files, one per terminal description.

Despite the consistent use of little-endian numbers and the otherwise self-describing format, it is not wise to count on portability of binary terminfo entries between commercial Unix versions. The problem is that there are at least three versions of terminfo (under HP-UX, AIX, and OSF/1) each of which diverged from System V terminfo after SVr1, and added extension capabilities to the string table that (in the binary format) collide with System V and X/Open Curses extensions. See terminfo(5) for detailed discussion of terminfo source compatibility issues.

This implementation is by default compatible with the binary terminfo format used by Solaris curses, except in a few less-used details where it was found that the latter did not match X/Open Curses. The format used by the other Unix versions can be matched by building ncurses with different configuration options.

### Magic Codes
The magic number in a binary terminfo file is the first 16 bits (two bytes). Besides making it more reliable for the library to check that a file is terminfo, utilities such as file(1) also use that to tell what the file-format is. System V defined more than one magic number, with 0433, 0435 as screen-dumps (see scr_dump(5)). This implementation uses 01036 as a continuation of that sequence, but with a different high-order byte to avoid confusion.

### The TERMTYPE Structure
Direct access to the TERMTYPE structure is provided for legacy applications. Portable applications should use tigetflag(3X) and related functions to read terminal capabilities.

### Mixed-case Terminal Names
A small number of terminal descriptions use uppercase characters in their names. If the underlying file system ignores the difference between uppercase and lowercase, ncurses represents the “first character” of the terminal name used as the intermediate level of a directory tree in (two-character) hexadecimal form.

### Limits
ncurses stores compiled terminal descriptions in three related formats, described in the subsections

- Legacy Storage Format, and

- Extended Storage Format, and

- Extended Number Format.

The legacy storage format and the extended number format differ by the types of numeric capability that they can store (for example, 16- versus 32-bit integers). The extended storage format introduced by ncurses 5.0 adds data to either of these formats.

Some limitations apply:

- total compiled entries cannot exceed 4096 bytes in the legacy format.

- total compiled entries cannot exceed 32768 bytes in the extended format.

- the name field cannot exceed 128 bytes.

Compiled entries are limited to 32768 bytes because offsets into the strings table use two-byte integers. The legacy format could have supported 32768-byte entries, but was limited to a virtual memory page's 4096 bytes.

## EXAMPLES
Here is a terminfo description of the Lear-Siegler ADM-3, a popular though rather stupid early terminal.

```
adm3a|lsi adm3a,

        am,

        cols#80, lines#24,

        bel=^G, clear=\032$<1>, cr=^M, cub1=^H, cud1=^J,

        cuf1=^L, cup=\E=%p1%{32}%+%c%p2%{32}%+%c, cuu1=^K,

        home=^^, ind=^J,
```

A hexadecimal dump of its compiled terminal description (in legacy format) follows.

0000 1a 01 10 00 02 00 03 00 82 00 31 00 61 64 6d 33 ........ ..1.adm3

0010 61 7c 6c 73 69 20 61 64 6d 33 61 00 00 01 50 00 a|lsi ad m3a...P.

0020 ff ff 18 00 ff ff 00 00 02 00 ff ff ff ff 04 00 ........ ........

0030 ff ff ff ff ff ff ff ff 0a 00 25 00 27 00 ff ff ........ ..%.'...

0040 29 00 ff ff ff ff 2b 00 ff ff 2d 00 ff ff ff ff ).....+. ..-.....

0050 ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ........ ........

0060 ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ........ ........

0070 ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ........ ........

0080 ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ........ ........

0090 ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ........ ........

00a0 ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ........ ........

00b0 ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ........ ........

00c0 ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ........ ........

00d0 ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ........ ........

00e0 ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ........ ........

00f0 ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ........ ........

0100 ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ........ ........

0110 ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ........ ........

0120 ff ff ff ff ff ff 2f 00 07 00 0d 00 1a 24 3c 31 ....../. .....$<1

0130 3e 00 1b 3d 25 70 31 25 7b 33 32 7d 25 2b 25 63 >..=%p1% {32}%+%c

0140 25 70 32 25 7b 33 32 7d 25 2b 25 63 00 0a 00 1e %p2%{32} %+%c....

0150 00 08 00 0c 00 0b 00 0a 00 ........ .

## AUTHORS
Thomas E. Dickey

extended terminfo format for ncurses 5.0

hashed database support for ncurses 5.6

extended number support for ncurses 6.1

Eric S. Raymond

documented legacy terminfo format (that used by pcurses).

## SEE ALSO
curses(3X), curs_terminfo(3X), terminfo(5), user_caps(5)