console-ncurses-realizer 1 user commands nosh
console-ncurses-realizer realize a user-space virtual terminal on another terminal with ncurses
`console-ncurses-realizer` --display-only --wrong-way-up vcname

## Description

`console-ncurses-realizer` is the I/O back end for a (user-space) virtual terminal, that realizes the virtual terminal on another terminal. It uses wide-character ncurses (sometimes a.k.a. ncursesw) to do so, and thus expects that terminal to be already connected to its standard input and standard output. It only uses its standard error for diagnostic messages.

It opens the character/attribute buffer file `vcname/display` and the input FIFO `vcname/input`. These are the back-end interfaces of the user-space virtual terminal, as detailed in user-vt 5.

It then enters a loop where it simultaneously:

- (unless the --display-only option is used) writes all data received from its standard input to the input FIFO, using ncurses to retrive the input; and

- writes the contents of the character/attribute buffer file to its standard output, using ncursesw to write the output.

The --wrong-way-up command-line option causes the display to be realized the wrong way up, swapping the direction of increasing line numbers. This is an oft-requested terminal feature, albeit by people who have never actually experienced it.

## Security

`console-ncurses-realizer` only requires sufficient privileges to access the file and the FIFO. Superuser privileges are not necessary. The recommended configuration is that the file and the FIFO are (respectively) readable and writable by a dedicated unprivileged user or group.

It does not attempt to create the file or FIFO if they do not exist, because this would create them with the wrong owner and group, and thus requires no write access to their containing directory.

## Limitations

Because it employs ncursesw, `console-ncurses-realizer` has several limitations compared to a realizer with a more powerful rendering mechanism:

- There is essentially only one modifier key for most editing keys, shift; and even that isn't available for some editing keys.

- There's no distinction made between calculator keypad keys (in application mode) and editing/cursor keypad keys.

- There are no modifiers for function keys. You may find that the realizing terminal translates function keys plus modifiers into differently numbered sets of function keys, in any case. This is a common trick employed by terminals with only one row of function keys.

- The placeholders for control and zero-width characters in the display buffer are not visually very informative.

- Display attributes are badly translated by or entirely missing on the realizing terminal. For examples: Blink is wrongly displayed as a bright background colour. Underline and italics are not implemented; let alone the modern underline extensions for different kinds of underlining. Concealed text is not concealed. Framed and encircled are not implemented. Font weights are conflated with colour changes.

- The ncursesw colour system does not lend itself to 24-bit RGB. It is, in the terminology of the termcap 5 manual page, "HP-like" rather than "Tektronix-like". This means that colours are specified indirectly, first via one of 64 (at minimum) colour pairs that pair up foreground and background colours; and then via an (at minimum) 8-entry colour palette. The maximum number of simultaneously on-screen colours is nowhere near the size of the 24-bit RGB colour space, and is in fact 8 as standard.

## Bugs

If you run `console-ncurses-realizer` outputting to the very same user space virtual terminal whose display it is rendering (and input it is generating), you will get a loop. Because of the modular nature of user space virtual terminals, it is not possible for `console-ncurses-realizer` to detect this. Don't do it.

## SEE ALSO

console-termio-realizer 1

  an alternative realizer built upon TerminalCapabilities 3

## Author

Jonathan de Boyne Pollard