The comment "from the top of the screen to the current line" is ambiguous. If you meant from the top of the visible part of the screen, that is not the scrollback. The scrollback of a terminal is the part that you can see only by using the scrollbar (or suitable keys such as shift pageup).
XTerm Control Sequences documents the relevant escape sequence:
CSI Ps J Erase in Display (ED).
Ps = 0 -> Erase Below (default).
Ps = 1 -> Erase Above.
Ps = 2 -> Erase All.
Ps = 3 -> Erase Saved Lines (xterm).
The terminal description capability clear
uses the next-to-last one, e.g.,
clear=\E[H\E[2J
to position the cursor to the upper left and then clear the whole (visible) screen. You could use the Erase Below, but that is not used in the terminal description.
Referring to clearing the scrollback: That's a terminal-specific feature, originally an escape sequence in xterm (1999, documented in ctlseqs.ms but not mentioned in changes) and later (2011) implemented as an extension for Linux console and the corresponding terminal description. The terminal database lists it as a "miscellaneous extension".
Currently, these terminal descriptions have the feature:
Whether it is supported in xterm look-alikes such as VTE would have to be answered by testing (there is no useful documentation for VTE or Konsole).
If you prefer to not use the extension, you could remove the E3
capability from the terminal description which you use, e.g.,
infocmp -1x >foo
edit foo, removing the line with "E3="
tic -x foo
I suggested using the options -1
and -x
to simplify the formatting and to show the feature to change. The example given in https://ghostbin.com/paste/kfsbj is consistent with that advice:
- the pathname
/home/flowerpick/.terminfo/x/xterm
would be used by ncurses
- the capabilities
AX
and XT
are extended capabilities (like E3
), shown with the -x
option.
If you are using more than one terminal type, you would have to do this for each (value of $TERM
), and the change only applies to the machine where you run clear
. The first couple of lines of the infocmp
output show which one you are working on:
# Reconstructed via infocmp from file: /home/flowerpick/.terminfo/x/xterm
xterm|xterm terminal emulator (X Window System),
For instance, uxrvt
sets $TERM
to something like rxvt-unicode
, producing lines like this in infocmp
:
# Reconstructed via infocmp from file: /lib/terminfo/r/rxvt-unicode
rxvt-unicode|rxvt-unicode terminal (X Window System),
The st
program uses xterm
(or possibly xterm-256color
), though it's been a while since I saw a copy of that which worked well enough to comment upon.
By the way, you could have an alias for clear
which is sending the given escape sequence (ignoring the terminal description), but I haven't seen this reported by anyone.
If you wanted to "clear above", that is not as straightforward as typing "clear". The escape \033[1J
erases from the upper-left to the current cursor position. You could make a script which does this, to clear only the lines above your current cursor:
- use the cursor position report to find the row/column on which the cursor currently is, and
- if the cursor is not on the first line, (saving that position), move the cursor up one line and then (with the
hpa
sequence) move right a large number,
- issue the "clear above", and
- return to the original position using
cup
(cursor addressing).
That part with the cursor position report doesn't seem as if it would work in (for example) a readline binding, so I suggested a script. You could make a binding that used the save/restore cursor capabilities if there were not the problem of being on the first line.
Best Answer
This is a bit of a complicated question. I'll try to answer your questions in turn, but first a general description:
The scrollback buffer is implemented by your terminal emulator (
xterm
, Konsole, GNOME Terminal). It contains all the text that has been displayed on the screen, including both standard output and standard error from every program you run in the terminal. It's entirely terminal functionality to let you look at past output that may have scrolled past you or to check on what something said earlier.You can think of the scrollback buffer as a long page of logged output and your terminal window as a window looking at just part of it at any one time. If you haven't scrolled up any, what you're looking at is the tail end of the buffer. Usually there will be a limit configured in the terminal of how many lines it keeps track of before it starts to forget.
Suppose that limit is 1000 lines. For the first thousand lines of output in your session you just append to the buffer, and you can scroll up right to the start of your session. As soon as get the 1001st line of output the first line in the buffer is erased, and the furthest back you can scroll will be the second line of your session. The buffer will always contain the most recent thousand lines of output that were displayed on your screen, and you can scroll up to look at earlier output at any time.
Does it mean "function" as in "subroutine" or as in "feature"?
This is "function" as in "feature". The terminal emulator has a functionality that records what's on the screen and lets you scroll up and down in it. The consoles on some systems also support limited scrollback.
It gets a bit more complicated once you throw
screen
into the mix. At that point,screen
is emulating the scrollback buffer itself - that's why you can copy and paste from it within the program, rather than only with (say) X selection.Is there is a Unix standard or API for this scrollback buffer?
The short answer is no, it's just provided by your terminal. The longer answer we'll get to at the bottom.
In a "stack" of programs, such as vim launched in screen launched in bash launched in ssh launched in a terminal emulator, which of these programs are controlling the scrollback buffer?
In the case of
vim
andbash
, they aren't controlling it at all (caveat, again, below). Your terminal provides the scrollback buffer for all the programs inside it, starting from your shell.screen
, as mentioned above, is simulating scrollback itself.I also used screen to dump the scrollback to a file. This file had a lot of white space at the top, and it seems the "view" my terminal emulator shows me is simply the bottom few lines of the of the buffer.
This is
screen
's internal buffer. What's on your screen at the time will generally be what's at the very bottom of the buffer.Is this why a program like vim can "clear" my entire terminal window, because it gets temporary access to the parent shell's scrollback buffer?
Here is one part of where it gets much more complex. Virtually all X-based terminal emulators are simulating a VT100, and one thing they do there is support an "Alternate Screen Buffer". Unlike the ordinary buffer that's used for most terminal interaction with sequential output, the alternate screen buffer is just the exact size of your terminal. There's no scrolling up or down in it because it's no bigger than what's displayed.
The idea there is to allow a full-screen application to do what it needs to do without being interfered with by anything you already had on the screen, and then to let you go back to exactly the display you had before. That's why when you enter
vim
it fills the whole screen, but when you leave it then the terminal output you had beforehand — all your past prompts and command output — comes back again.vim
switches into the alternate screen buffer when it starts and back to the normal buffer when it exits.This alternate buffer is one of the caveats I mentioned above. Sometimes, the program really does have the ability to tell the terminal what to do with the buffer.
screen
is another program that does this, which is why your terminal's scrolling functionality generally doesn't work while you're in a screen session —screen
emulates the scrollback buffer itself, so you have to use its internal functionality to get to old output.Or does vim use its own scrollback buffer that is somehow overlaid on top of the parent scrollback buffer?
I've mostly answered this in the previous question, but the short answer to this particular question is that
vim
does get its own temporary buffer, with no scrollback, from the terminal, and then performs all its own scrolling of your documents internally.All those exceptions I mentioned:
It gets slightly more complicated again. I said that applications don't have any control over the scrollback and that it's provided entirely by the terminal. In some cases, with some terminals, there is limited interaction. The program prints out certain escape sequences — if you've ever used terminal colouring manually in the past you'll have seen what they look like — and the terminal can interpret those and change its behaviour, or even send back information to the program. Which escape sequences are available are described in the termcap (terminal capability) database.
Some terminals do support limited querying and manipulation of the scrollback buffer. Many
xterm
derivatives have escape sequences that direct the terminal to scroll its view. Many terminals also support specifying a particular area of the screen to scroll, leaving all the rest intact. That tends to break the scrollback buffer.Almost all terminals support sequences to move the cursor around the screen, which is how the
ncurses
library is able to update all different parts of the display. You can look at the VT100 sequences supported byxterm
. The way that these interact with the scrollback buffer can be a bit odd at times, particularly in the case of something that implements its own scrolling behaviour, like theless
command. You can end up with duplicated or missing lines in your scrollback becauseless
redrew text over the top in a way your terminal didn't expect. Other programs sometimes end up filling your buffer with multiple copies of their entire display.