tgoto

The special case of cursor motion is handled by tgoto. There are two reasons why you might choose to use tgoto:

• For Unix compatibility, because Unix termcap does not have tparam.
• For the `cm' capability, since tgoto has a special feature to avoid problems with null characters, tabs and newlines on certain old terminal types that use `%.' encoding for that capability.

Here is how tgoto might be declared in ANSI C:

char *tgoto (char *cstring, int hpos, int vpos)

There are three arguments, the terminal description's `cm' string and the two cursor position numbers; tgoto computes the parametrized string in an internal static buffer and returns the address of that buffer. The next time you use tgoto the same buffer will be reused.

Parameters encoded with `%.' encoding can generate null characters, tabs or newlines. These might cause trouble: the null character because tputs would think that was the end of the string, the tab because the kernel or other software might expand it into spaces, and the newline becaue the kernel might add a carriage-return, or padding characters normally used for a newline. To prevent such problems, tgoto is careful to avoid these characters. Here is how this works: if the target cursor position value is such as to cause a problem (that is to say, zero, nine or ten), tgoto increments it by one, then compensates by appending a string to move the cursor back or up one position.

The compensation strings to use for moving back or up are found in global variables named BC and UP. These are actual external C variables with upper case names; they are declared char *. It is up to you to store suitable values in them, normally obtained from the `le' and `up' terminal capabilities in the terminal description with tgetstr. Alternatively, if these two variables are both zero, the feature of avoiding nulls, tabs and newlines is turned off.

It is safe to use tgoto for commands other than `cm' only if you have stored zero in BC and UP.

Note that tgoto reverses the order of its operands: the horizontal position comes before the vertical position in the arguments to tgoto, even though the vertical position comes before the horizontal in the parameters of the `cm' string. If you use tgoto with a command such as `AL' that takes one parameter, you must pass the parameter to tgoto as the "vertical position".

Go to the first, previous, next, last section, table of contents.