console-termio-realizer 1 user commands nosh console-termio-realizer realize a user-space virtual terminal on another terminal with straight terminal I/O console-termio-realizer --display-only --wrong-way-up --bold-as-colour --faint-as-colour --permit-fake-truecolour --cursor-keypad-application-mode --calculator-keypad-application-mode --no-alternate-screen-buffer --inversescreen boolean --tui-level level --mouse-primary vcname keyboard-state-file mouse-state-file console-termio-realizer is the I/O back end for a (user-space) virtual terminal, that realizes the virtual terminal on another terminal. It expects that other terminal to be already connected to its standard input and standard output, and its type to be specified in the TERM environment variable. 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-vt5. It opens the keyboard-state-file and mouse-state-file, which are (potentially shared) keyboard modifier and mouse state files, as described in user-vt-realizer-configuration5. 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; and (if the --mouse-primary option is used) writes all mouse state changes recorded in the mouse-state-file to the input FIFO; and writes the contents of the character/attribute buffer file to its standard output. Next to the virtual terminal area it displays, if there is room, a toolbar of widgets: various indicators and buttons. The indicators show the current (shared) keyboard state as read from keyboard-state-file: the ⇭ Num Lock, ⇬ Caps Lock, ⇫ Level 2 Shift Lock, ⇯ Level 3 Shift Lock, the ⇒ Group 2 latch, and the states of the ⎈ Control, ⇧ Level 2 shift, ⇮ Level 3 shift, ⌘ Super, and ⎇ Alt keys. These are what real HIDs would display using lights on a panel. These are not the keyboard states of the local terminal. console-termio-realizer has no access to local terminal transient keyboard modifier state; as that is not part of the I/O protocol for terminals. It does not apply these states to input that it reads from the terminal. The buttons can be clicked with the mouse, if the realized-upon terminal supports mouse input. These send multiplexor control commands to the user-space virtual terminal, to switch to the start/previous/next session; and likewise input method control commands, to select conversion mode. console-termio-realizer has a slightly more powerful rendering mechanism than console-ncurses-realizer1, because it does not use (wide character) ncurses. It instead uses straight terminal I/O, with ECMA and ISO standard output control sequences, DEC VT input and output control sequences, and SCO Unix Multiscreen virtual terminal input control sequences. It can recognize DEC VT modifier parameters to function, numeric keypad, and cursor/editing keypad key control sequences; and recognize modifier key combinations that ncurses has no concept of. This presumes that the terminal is actually capable of sending such modifiers. If the terminal distinguishes between calculator keypad keys (in application mode) and editing/cursor keypad keys, this too is recognized. It will attempt to use the correct ECMA-48 control sequencs for underline, italics, framed, and encircled. If the terminal supports them, it uses ISO 8613-6/ITU T.416 SGR indexed and direct colour extensions for 8-bit palette look-up or 24-bit RGB. Where the terminal family is known to support it, it will attempt to pass through things like the SGR 4 sub-parameter extensions for various different kinds of underlining. The disadvantage of not using ncurses is that console-termio-realizer will not interoperate with terminals that do not adhere to the ISO and ECMA standards, and to the DEC VT and SCO Unix Multiscreen virtual terminal conventions. However, such terminals whilst possible to regularly encounter in the 1960s and 1970s are exceedingly rare nowadays. What the terminal supports is determined from the terminal type specified in the TERM7 environment variable. Terminal types are, per TerminalCapabilities3, assumed to comprise "families" that share a common name as a prefix (e.g. gnome and gnome-256color) console-termio-realizer mainly only looks at these families, not the trailing "subfamily" denotations (with a couple of exceptions such as checking for "256color"). Virtual terminal display buffers encompass various kinds of glyph for the cursor and the pointer. The support for these is completely dependent from the capabilities of the realized-upon terminal. Cursor glyphs and attributes are requested largely as-is from the realized-upon terminal, excepting that some non-DEC or non-XTerm extensions are reduced to their DEC/XTerm equivalents as appropriate for the terminal type family. The same goes for pointer glyphs. Virtual terminal display buffers also encompass a "light/dark background" screen flag. Many terminal emulators get this flag backwards, relative to a DEC VT. They also disagree on whether this should swap all foreground and background colours of all text (Konsole); swap indexed colours 0 and 7, indexed colours 8 and 15, and the foreground and background of default-coloured text (XTerm); or only swap the foreground and background of default-coloured text (rxvt). console-termio-realizer handles this flag itself, therefore, for consistency across realized-upon terminals and with other realizers. It swaps all foreground and background colours, which is also what a DEC VT is documented as doing. A "default" foreground or background cell colour is realized using the realized-upon terminal's own default colour. This produces a more visually acceptable effect on terminal emulators which come up in reverse video screen mode, at the expense of the "default" colour not being the same across multiple realizations of the same user-space virtual terminal. Modern GUI terminal emulators, such as XTerm since the 1990s, work like the DEC VT420 did in its native mode. The F1 to F12 keys on the keyboard do not change numbers when modifiers are used. The terminal emulators encode modifier key information in the control sequences that they send, and thus leave it to the receiver to process the difference between (say) ⎈ Control+⇧ Shift+FN and just plain FN. console-termio-realizer decodes the modifier information and simply passes it along to the user-space virtual terminal's input as part of the input message. There is thus a relatively "straight paper path", when it comes to function keys, between the realizing terminal and what the applications on the far side of the user-space virtual terminal see. (Teken emulation by the user-space virtual terminal confounds this somewhat.) Old-fashioned GUI terminal emulators, which unfortunately still includes rxvt and Unicode rxvt, swallow parts of the modifier information. They do so on the supposition that the GUI input device is a supposed IBM Model F (PC/XT) keyboard with 10 function keys. They use the ⇧ Shift modifier to internally map those 10 function keys onto the 20 function keys of a DEC VT. This causes significant confusion on modern keyboards derived from the IBM Model M (PC/AT) keyboard with 12 instead of 10 function keys. console-termio-realizer receives only part of the modifier information, and is told about a confusing set of function keys where F11 and F12 behave especially oddly. Teken emulation by the user-space virtual terminal makes this even worse. Various workarounds for deficiencies in the realizing terminal are available. The --bold-as-colour and --faint-as-colour command-line options accomodate terminals that do not yet implement the bold and faint SGR attributes that were standardized by ECMA-48 in 1976. The --permit-fake-truecolour command-line option permits the use of ISO 8613-6/ITU T.416 Direct colour control sequences even on terminals which are known to fake this by mapping 24-bit RGB colours to entries in their 8-bit colour palettes. 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. The --cursor-keypad-application-mode and --calculator-keypad-application-mode command-line options instruct console-termio-realizer to switch, respectively, the cursor keypad and the calculator keypad of the realizing terminal into their "application" modes. Otherwise it switches them into their "normal" modes. "application" mode is generally not useful to console-termio-realizer, since it makes cursor and calculator keys indistinguishable from accelerator keys. The --no-alternate-screen-buffer command-line option instructs console-termio-realizer to not switch to the alternative screen buffer. This has two uses. First, it allows one to retain visibility of displayed information after the program has exited (although setterm1 provides access to the alternative screen buffer). Second, it works around problems with some (yet more!) broken terminal emulators that attempt to be and fail at being like XTerm, which forcibly change cursor and editing keys into application mode when the alternative screen buffer is active. The --inversescreen command-line option instructs console-termio-realizer to switch the DECSCNM ("light"/"dark" screen mode) private mode on or off. The --tui-level command-line option constrains the use of MouseText or Unicode block graphics and line drawing characters in TUI widgets and the mouse pointer. console-termio-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. If you run console-termio-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-termio-realizer to detect this. Don't do it. Jonathan de Boyne Pollard