See also: Part 1 and Part 2.

The termcap file is a text file found in /etc/termcap on a Unix system. As it was ported to other operating systems, the default location would change accordingly. The contents of the termcap file is basically a series of entries for each terminal supported. Each entry contains various elements separated by colons. To make the file more readable, a backslash can be used at the end of a line to break it up.

See the Wikipedia page for a summary, or the GNU Software page for a more descriptive summary… Or see this for a vague summary:

For example:

2characterterminalname|longerterminalname|verboseterminalname:
  :capability=characetersqeuence:
  :capability=charactersequence:

The 2 character name is legacy and is no longer used, but remains for ancient backwards compatibility. For a DEC VT-52 terminal, it might look like this:

dw|vt52|DEC vt52:
  :cr=^M:do=^J:nl=^Jbl=^G:
  ...etc...

Each capability has a two character abbreviation. Above, we see that to generate a carriage return (cr) we send a control-M (enter key). A new line (nl) is ^J. The bell (bl) is a ^G (beep!). There are many other simple codes.

For moving the cursor position, a DEC VT52 terminal used the sequence: ESCAPE followed by [ (left bracket) followed by line followed by semicolon followed by column followed by H.

ESCAPE [ 10 ; 4 H

That would mean move the cursor to line 10, column 4. To represent sequences like this with variables inside of them (line, column, etc.), there are more complex termcap entries:

:cm=E%i%d;%dH:

Above, E represents ESCAPE (just like ^ represents CONTROL). %i is a special flag that means “increment the two values supplied” (base 1 numbering) then the two %ds are the variables similar to a C printf() call.

The %i is because termcap assumes base 0, so an 80 column screen would be 0-79. The VT terminal (and PC ANSI, I think) assume base 1, 1-80, so to make it universal, all termcap applications expect a screen that is base 0 (0-79) and the entry knows whether or not to output 0-79 or 1-80. Fun.

Termcap has pages of codes for all kinds of features, like cursor up, delete line, clear screen, clear to end of line, etc. If a terminal does not support a feature, the entry is not present. Applications that use termcap will query these capabilities then use what they can. In my situation, I needed “cm” for cursor movement — and if that feature was not there, I couldn’t work (or, better, I could default to a mode of just lines of text).

There are more advanced features where a termcap entry can reference another entry. For instance, there were series of terminals made and as new models came out, they added new features but maintained the earlier ones as well. The first version terminal would have an entry, then the “v2” terminal would have an entry that described the new features, but by adding a capability of “tc=terminal-v1” or whatever, it would get any other capabilities from the “terminal-v1” entry.

This cuts down on redundant information but also means you can’t just look at one termcap entry and necessarily know everything the terminal does. If you were writing your own code to parse a termcap file, you would have to take this in to consideration.

In a C program that will be linking to the termcap library, to load the terminal type you want, you need a buffer for it to be loaded (2K is the defined max size):

char term_buffer[2048];

…and then you just use the termcap tgetent() function:

status = tgetent(term_buffer, "ANSI");

If the termcap file is found, and there is an entry called “ANSI”, it will be copied in to the term_buffer. By checking for errors (always a good idea), you will know if the entry was not found.

But hard coding is bad. What if this code ever runs on a non-ANSI terminal? Termcap programs typically read the TERM environment variable, then get whatever that is set to. In windows you might “set TERM=ansi” and on Linux you might “export TERM=vt100”. Then the C program would query that environment variable first:

char termtype;
termtype = getenv("TERM");
if (termtype==NULL) { / handle error if env var not set */ }

termtype will come back pointing to whatever the TERM environment variable is set to (“ANSI” in the windows example above, or “vt100” in the Linux example above). Then the tgetent() is done using that response:

status = tgetend(term_buffer, termtype);

If both of those are successful, the individual capabilities can be loaded using the tgetstr() function. tgetstr() will parse capabilities in the loaded termcap entry and write them to a buffer that is processed to be the actual output (less any variables that get substituted when the actual sequence is used later). For instance, the termcap entry might say:

:bl=^G:

…but when you use tgetstr() to parse for the “bl” entry, it will write out the control-G (ASCII 7) character in the output buffer. Basically, it converts all the E (escape) and ^X (control) ASCII characters to what they really represent. This saves work later when they are output to the screen.

A second buffer (that must remain around) needs to be allocated to store the resulting output. Most examples also do a 2K buffer:

char capbuff[2048]; // output sequences are stored here

Then, as each capability is obtained, a pointer is passed in to where the output should be written, and when the call returns, that pointer is advanced to the next place in the buffer where the next capability will go. As tgetstr() is called over and over, the pointer increments filling up the output buffer with entries, and returning the location where each one the user cares about is located within that buffer.

char *tempPtr = capbuff; // start out pointing to our output buffer

If you want to know the code that clears the screen, it would be:

char *cl; // clear screen sequence

cl = tgetstr("cl", &tempPtr);

If cl comes back non-NULL, you know have a pointer to the byte sequence that will clear the screen. tempPtr returns with a higher value, so when you get the next capability you use it again:

ce = tgetstr("ce", &tempPtr);

This is repeated over and over for every code you wish to send. You check for NULL to know which capabilities actually exist, so you could write functions like this:

void clearscreen()
{
if (cl==NULL)
{
printf("Sorry, I cannot clear the screen...");
} else {
tputs(cl, 1, outchar);
}
}

And now we see how these pointers get used. The tputs() function is a special output routine that handles padding (time delays for slower terminals) and other features (though it ends up writing the character out using a function you specify — such as outchar() in this example).

For the cursor movement (cm) capability, it uses a special tgoto() function that knows how to substitute the X and Y values:

void setcursor(int x, int y)
{
tputs(tgoto(cm, x, y), 1, outchar);
}

tgoto() processes the cm output string and returns one that has everything set up with the x and y coordinate in it.

By now, you may see where I cam going with this… Read the termcap entry, parse the ones you care about, then create simple functions that output the screen code sequences:

void clearscreen();
void setcursor(int x, int y);
void underlineon();
void underlineoff();

…etc…

In the next installment, I will share with you my very basic and simple 1995 code that let me convert OS-9 L2 (and MM/1 K-Windows) text programs to run under Termcap on any supported type of terminal.

And then I will explain why I decided NOT to use termcap for my current project.

To be continued…

Previously, I mentioned a bit about the ancient termcap system which is used to send display codes (clear, move cursor, underline, blink) to terminals of different kinds. In this modern GUI world, none of this is necessary … folks pretty much have to rewrite the whole program to work with native Mac, Windows, Linux, Java, etc. I suppose the modern equivalent to termcap would be a cross platform GUI (kind of like a graphical termcap?) which turns things like “create a pop up window” or “create a menu with the following options” in to whatever it takes to display them on the end operating system.

I suppose that’s truly what I should be learning right now — my program could make use of graphics on the Linux-based Raspberry Pi, Windows or Mac. However, since my program is not intended to be a windows-based program (no pull down menus, no mouse, etc.) and really had no use for graphics, I decided to write everything using text.

My original prototype was rather bland, spitting out 80 column descriptive text. This was perfect for debugging, but certainly not what we want the end-user to have to deal with:

By writing the application as a strict ANSI-C program, and just using text, it would compile and run on a Windows PC as well, in a DOS-style COMMAND window (CMD.EXE):

The target system for this project would be Raspberry Pis, the $25-$35 micro-Linux computer designed for educational use. We would be using the $35 model, which has more RAM (512mb) and USB/ethernet. The Pis support HDMI and composite video output. Instead of using large (pricy) HDMI TV/monitors, I found tiny composite color monitors for under $20 (4.3″, about the size of a GPS unit or large smartphone screen).

By setting the resolution of the Pi to match the display’s 480×272 resolution (/boot/config.txt: framebuffer_width=480 and framebuffer_height=272), and by choosing the largest font available (setfont /usr/share/consolefonts/Uni3-Terminus32x16.psf.gz) I was able to get a large, easy to read (on the tiny screen) 30×8 display. It would look something like this:

+------------------------------+
|123456789012345678901234567890|
|2                             |
|3                             |
|4                             |
|5                             |
|6                             |
|7                             |
|8                             |
+------------------------------+

The actual screen ends up much wider than this text drawing, since the displays I am using are 16×9 widescreen.

Have you noticed the lack of mentioning Termcap so far? Let’s correct that now.

If I was going to be using this particular screen and run on just a Raspberry Pi, I could just hard-code everything to expect 30×8 characters, and whatever display codes were needed to clear the screen or change colors.

And that would be bad programming. Doing this “because this is all it is planned to ever run on” is like not having insurance because you never plan to get in an accident. It’s certainly fine to write anything for yourself any way you darn well please (I do that all the time, too), but I try to think ahead and write things to be as portable and as flexible as I can.

Fortunately, I wrote such portable code back around 1995. At the time, I had created a text-based user interface called EthaWin. It was written for OS-9 Level 2 on the Tandy Color Computer 3, and later ported to the OS-9/68000 MM/1 computer. The CoCo 3’s terminal window system supported all kinds of screen codes for basic things like color, blinking, move cursor, etc., much like ANSI graphics on a PC did. The MM/1 was meant to be a next generation replacement for the CoCo OS-9 users, so it’s K-Windows system replicated (and expanded upon) those same screen codes.

My EthaWin was not the “portable code” I am speaking of. It would only run on a CoCo or MM/1 under OS-9. When I began working for Microware, the company that had created OS-9, none of my stuff would run on the “headless” OS-9 computers in the building — most didn’t even have video displays. The way you accessed them was via an RS232 serial port and a hardware terminal (or software terminal program), or from telnetting in across the network.

OS-9, being created as a very Unix-like operating system, supported termcap, and text editors like vim, uMacs, etc. made use of this to give full screen editing. If I wanted EthaWin to work on these OS-9 machines, I was going to have to learn how termcap worked.

In the next installment, I will finally talk about termcap and show how very simple it is to do very simple things.

Until then…

Before stand-alone computers became common, most computer time was spent in front of a dumb terminal — basically a keyboard and screen that would send whatever the user typed to a big computer somewhere, and display whatever it received back from the big computer:

http://en.wikipedia.org/wiki/Computer_terminal

As I mentioned in an earlier posting, my first interaction with a computer in the 1970s was via a printing terminal at my elementary school. The next time I used a computer, it was a TRS-80 at Radio Shack. I kind of missed the whole dumb terminal phase of computing, but I certainly spent endless time with my home computer acting as a dumb terminal as it dialed in across the phone lines to other computers running BBSes (bulletin board software).

In a way, this concept lives on via the Internet and cloud computing. Our computers are just far smarter “dumb terminals” when they display all the content generated from Facebook’s servers, or display virtual shopping catalogs that are indexed at Amazon.

I guess there really isn’t anything new.

While today, a modern smart “dumb terminal” may be running JavaScript or (can you believe it?) Flash, decades ago dumb terminals were doing similar rendering – though limited to simple things like moving a cursor around the screen, or turning on underlined text. Or blinking. Anyone remember when things blinked?

Frighteningly enough, you probably still see examples of this at some modern businesses. My car dealer still uses some text-based program in its service department, and it is not that uncommon to see the same in banks or other businesses.

Dedicated terminals were still alive and well in the mid-1990s when I took my first dream job and was teaching week-long OS-9 courses around America (and sometimes in Canada). I would arrive on Sunday night, and at the hotel would be a bunch of boxes that had been delivered. We would rent dumb terminals from local suppliers, and I would unbox and set up eight of them and wire them all up via RS232 serial cables up to the multi-user OS-9 computer I brought with me.

I would then go through the task of configuring the settings on each terminal (they were pretty smart for dumb terminals) to make sure all the settings matched what we would need for the class (like baud rate and serial port settings, as well as emulation mode).

Just like today, there were competing standards back then. A VT100 terminal might expect a particular series of bytes to indicate “clear the screen”, but a DEC terminal might use a different set. What a mess this must have been in the early years!

Fortunately, smart people came up with smart solutions to deal with all these different standards. One such solution was called Termcap – which stood for terminal capabilities.

http://en.wikipedia.org/wiki/Termcap

Created in 1978, termcap was a database of various terminal types with entries describing how each one did things like move the cursor or clear the screen. Programs could be written to use the termcap library and then, on startup, they would load the proper codes to match whatever terminal type the user was using — provided it was in the database.

This must have been a major breakthru for writing portable apps, much like Java was a breakthru to let the same app run on Mac, Unix and Windows… Today, HTML5 and JavaScript allow web content to run on desktops, tablets or phones.

I guess there really isn’t anything new.

During my OS-9 days, termcap was important since almost all connections were done via a terminal (or terminal/telnet program). Most industrial OS-9 machines did not have video screens. I found this surprising, since I had come from the hobbyist OS-9 world where all our systems (Radio Shack Color Computer, Delmar, Tomcat, MM/1, etc.) all had graphics and user interfaces. But in the embedded/industrial space, they were just a box of realtime computing, and if the user did need to interact with it, they hooked up a terminal.

But I digress.

Recently, I began working on a new ticket barcode project that would ultimately run on small Raspberry Pi computers. I was doing all the prototyping work on Windows, and also compiling the same for Mac. Since I do not know anything about writing GUI programs, let alone how I would write something that would work on Windows, Mac and ultimately Linux, I was writing everything as an old style text-mode program.

This was more than enough to test all the functions, even if ultimately we would be using small 7″ color displays at each system. (I sense that I will be writing some articles on Raspberry Pi video in the future.)

Because I am now at the stage where I want to do more than just scroll text, I decided to revisit the old Termcap system and see if I could at least write fancy text programs that could use color, and create fancier text screens, and actually work on all my development platforms. I actually looked in to termcap few months ago when I wanted to do something similar on Arduinos, but at the time I decided it was impossible due to limited memory. (Update: That may not actually be the case.)

My goals of the next few articles will be:

1. Explain how termcap works.
2. Explain how to get termcap running on a Windows system (as well as Mac, and Raspberry Pi).
3. Create a simple library of common screen features (actually based on code I wrote in late 1995, to convert my EthaWin OS-9 user interface to run on the OS-9 machines at work via termcap).

…and after all this, I think I will have a version that works on Arduino as well.

More to come…