Name

console-clear, clear_console — clear a user-space virtual terminal

Synopsis

console-clear [--7bit] [--8bit]

clear_console [--7bit] [--8bit]

Description

console-clear emits control sequences to its standard output that instruct a compatible terminal emulator to clear its entire output, both display and any off-screen buffers.

It does not employ operating system and device specific ioctl(2) calls, and so can be used remotely and with terminal emulators other than the ones built into operating system kernels.

Rather, it emits simple terminal control sequences, as follows:

  • To clear the display, it always emits the standard (ECMA-48) ED control sequence with argument value 2.

  • To clear the off-screen "scrollback" buffer, it emits a non-standard extension to ED that replaces the argument value 2 with 3.

If the --7bit command-line option is used, the CSI control character that begins all of the control sequences is sent using the ECMA-48 7-bit encoding scheme. If it is not used but the --8bit command-line option is used, the CSI control character is sent as a raw 8-bit character. By default, in the absence of either option, the CSI control character is sent encoded as UTF-8, in the expectation that the terminal is Unicode aware and decodes all output from UTF-8.

COMPATIBILITY

For compatibility with the Bourne Again shell toolset, this command is also available as clear_console, whose functionality it duplicates. Unlike the Bourne Again shell toolset's clear_console command, this command is not specific to kernel virtual terminal character devices, does not involve switching virtual terminals (a process that can go wrong if an X server happens to be using the "other" virtual terminal), and respects redirection of its standard output.

This command makes no attempt to behave differently if its output is not to a terminal, since one might want to use it to generate the control sequences to send to a file, a pipe, or a non-terminal device.

Moreover, it only works with compatible terminal emulators. It simply assumes that its standard output is a terminal device that understands these particular control sequences, as it has no way to know. There is a termcap/terminfo capability covering this, E3. However, annoyingly, in many Linux operating systems and the BSDs it isn't actually yet present in the terminfo database entries for any of the terminals that support the capability, resulting in capability detection by terminfo failing when it should succeed.

Compatible terminal emulators are:

  • console-terminal-emulator(1)

    This is Unicode aware and correctly decodes the default UTF-8-encoded CSI sequence. UTF-8 encoding is mandatory, so using the --8bit option is inappropriate. However, note that the use case for clear_console is clearing the whole display buffer on user logoff, which console-terminal-emulator does anyway, as standard.

  • xterm(1)

    This extension was added on 1999-06-12 by Stephen P. Wall. xterm requires the --7bit option be used as it does not ever treat UTF-8-encoded C1 characters as control characters, irrespective of the setting of its UTF-8 encoding options. This will work however xterm is configured. One can use the --8bit option instead if xterm is configured to be in plain 8-bit ( +u8 ) mode.

  • PuTTY

    This extension was added in 2006 by Jacob Nevins. PuTTY requires the --7bit option be used as it does not treat C1 characters as control characters, and only recognizes the 7-bit extension of ECMA-48 section 5 as C1 controls.

  • the Linux kernel built-in terminal emulator

    This extension was added in 2011, albeit slightly erroneously, differing from the long-standing xterm and PuTTY semantics of clearing only the scrollback buffer.

Author

Jonathan de Boyne Pollard