Bash – How does “man” restore the screen when I quit the program

bashmanshellterminal

If I open a man page of a program like cat or ls, it prints (may not be the appropriate word) the contents of the man page and when I press q, it shows the screen just like before invoking the man command. How does the restore happen? What erases everything and then prints the previous contents of the shell?

Example:

[VAR121@Tesla Testing]$  man ls

Output:

LS(1)                                                        User Commands                                                        LS(1)

NAME
       ls - list directory contents

SYNOPSIS
       ls [OPTION]... [FILE]...

 ............

When I press q, the screen goes back to shells default appearance, such as the prompt shown below.

[VAR121@Tesla Testing]$  man ls
[VAR121@Tesla Testing]$

How is the screen restored ?

Best Answer

"Clearing" and "restoring" the screen is actually a function of the terminal emulator you are using (xterm, gnome-terminal, konsole, screen).

By default, the pager that man uses is less.

From man 1 man

   -P  pager
          Specify  which pager to use.  This option overrides the 
          MANPAGER environment variable, which in turn overrides 
          the PAGER variable.  By default, man  uses /usr/bin/less -is.

When less is invoked, an altscreen is launched by the terminal emulator to display the contents of the man page. When less exits, the altscreen is destroyed and the terminal displays what was saved in the buffer.

There is an answer here which discusses this further and how to keep programs like less from launching an altscreen and thus clearing the screen when it exits. In a nutshell, you could define an environment variable so that less does not launch an altscreen on invocation. If you are using bash, place this in ~/.bashrc:

export MANPAGER="/usr/bin/less -r -X -is"

Disable alternate screen switching

What should work for all terminals is to adjust local terminfo entries, i.e. removing the mapping of abstract clear/restore screen commands.

You can do it like this - for the current $TERM entry (for gnome-terminal on Fedora 19 for example):

$ echo $TERM
xterm-256color
$ infocmp -1 > xterm-256color
$ sed 's/^\(xterm-256color\)|/\1-na|/ ; /smcup\|rmcup/d ' \
    xterm-256color > xterm-256color-na
$ diff -u xterm-256color* 
--- xterm-256color  2013-08-04 16:33:52.041393461 +0200
+++ xterm-256color-na   2013-08-04 16:36:56.829930520 +0200
@@ -1,5 +1,5 @@
 #  Reconstructed via infocmp from file: /usr/share/terminfo/x/xterm-256color
-xterm-256color|xterm with 256 colors,
+xterm-256color-na|xterm with 256 colors,
    am,
    bce,
    ccc,
@@ -155,7 +155,6 @@
    rin=\E[%p1%dT,
    rmacs=\E(B,
    rmam=\E[?7l,
-   rmcup=\E[?1049l,
    rmir=\E[4l,
    rmkx=\E[?1l\E>,
    rmm=\E[?1034l,
@@ -170,7 +169,6 @@
    sgr0=\E(B\E[m,
    smacs=\E(0,
    smam=\E[?7h,
-   smcup=\E[?1049h,
    smir=\E[4h,
    smkx=\E[?1h\E=,
    smm=\E[?1034h,
$ tic xterm-256color-na # loads the file to $HOME/.terminfo
$ find ~/.terminfo -type f
$ HOME/.terminfo/x/xterm-256color-na

Now you can test it via:

$ TERM=xterm-256color-na man man # and then hit q

You can repeat the above steps for other terminals if you use multiple ones. If everything works as expected you can set TERM via your shell rc-file.

You can also directly specify the terminal name as a parameter to infocmp, e.g.:

$ infocmp -1 screen > screen

Enable alternate screen switching

Some terminals support the alternate screen switching feature (e.g. screen), but disable it on default.

For screen you can enable it via your ~/.screenrc:

$ cat ~/.screenrc
altscreen

If you remote login via ssh to - say - a Solaris system perhaps the remotely configured system-wide terminfo-database is kind-of historic, broken or includes some unusual/Solaris-specific defaults that don't match the 'bleeding edge' terminals you run ssh in.

Thus, it is an option to just copy the local terminfo database from /usr/share/info (on the client) to host:~/.terminfo (on the server).

In case the compiled terminfo format is not compatible you can also export/import the entries like in the previous paragraph.

I've tried in with a terminfo-db from a Cygwin installation and copying it directly to a Solaris 10 system worked.

In case you want to share an alternative terminfo db between users you specify its path via the TERMINFO environment variable.

Ignore the Control Sequence

Some terminals support disabling the control sequence for alternate screen switching. For example xterm has an option, gnome-terminal has not.

For xterm it is the X-ressource, e.g.

XTerm*titeInhibit: true

Program specific configurations

Some programs have configuration files to configure what control sequence/terminfo commands they send. For example

$ LESS=X less foo

configures less to not clear/restore the screen.

For vim you can include something like

set t_ti= t_te=

in you ~/.vimrc.

I haven't found on option how to configure that behavior for top - by default it does not send restore-screen.

Any way to cat few lines of man page to show on stdout for reference

You could run the output of man into the col command and then pipe this to less. Once in less you can drop to a shell while still maintaining your location in less.

$ man col | col -b | less

Once in less you can use !bash to get to a prompt to do what you want. When you're done you type exit to return back to your location in less.

Example

Here's a demo showing the whole operation.

ss of demo

Tell man to use a different pager

You can also tell man to use different pagers via the -P switch. So we could streamline the above method like so:

$ man -P less col

This is invoking man and then outputting the contents of the page to less, where again we can use !bash to get to a shell. To return we use the same steps as above, exit.

What's wrong with the default pager?

Actually nothing.

$ man col

It too can take the command !bash to escape to a shell, where again we can type exit to get back to the location where we were previously within the man page.

What else?

If you're feeling really crazy you can use vim as an alternative pager too. Setting this up is a bit of a task but it's doable, directions for doing so are here in the vim wikia topic titled: Using vim as a man-page viewer under Unix.

Don't let the above page fool you, it doesn't just cover vim methods. That topic covers dozens of ways you can change your man page pager in addition to using vim.