Previous Table of Contents Next


Module 139
tput (SV)

DESCRIPTION

The external tput command is used to initialize a terminal or query the terminfo database for terminal attribute strings. Terminal attribute strings are sequences of characters which cause the terminal to perform certain functions. They are often referred to as escape sequences. An example is the bold attribute. If your terminal can display text in bold mode, then a certain attribute string can be sent to the terminal to turn this attribute mode on and off.

COMMAND FORMAT

Following is the general format of the tput command.

     tput [ -Ttype ] capname [ parms ... ]
     tput [ -Ttype ] init
     tput [ -Ttype ] longname
     tput [ -Ttype ] reset
     tput [ -S <<!
     capnames [ parms ... ]
     !

Options

The following options and their arguments may be used to control how tput functions.

-S Reads capnames and any parameters from the standard input. Only one capname (and its parameters) is allowed per line.
-Ttype Allows you to specify the type of terminal you are using. If you have your terminal type set correctly (TERM=vt100), then this option is not necessary. If -T is specified, the shell variables LINES and COLUMNS are not referenced. The values are read from the terminfo entry.

Arguments

The following list describes the arguments that may be passed to the tput command.

capname A cap name indicating an attribute used from the terminfo(4) database. Capname refers to terminal capability name from the previous /etc/termcap database. For a complete listing of cap names refer to your Programmers Reference Manual, Section 4, terminfo.
parms If the attribute string associated with capname requires parameters, you must supply them as parameters to the command. The parms are inserted into the attribute string.
init Causes the initialization attributes to be sent to your terminal. The initialization attributes are accessed in terminfo via the is1, is2, is3, if, and iprog capname entries. If any delays are present in the entry, they are set in the tty driver. Depending on the entry, tab expansion will be turned on or off. If tabs are not expanded, standard tabs are set every 8 spaces. If any of the necessary information is not found to perform each of these tasks, the task is ignored.
reset Sends the reset attributes to your terminal. The capnames for the reset attributes are rs1, rs2, rs3, rf. If no reset attributes exist for the terminal type you specified, the initialization strings are used. The reset argument causes tput to perform the same as the init argument.
longname Displays the long descriptive name of the terminal you specified. The longname is the last name on the first line of the terminal's terminfo entry.

FURTHER DISCUSSION

A clever way to use the tput command is to use command substitution to assign the output of the tput command to a shell variable. Then when you need to perform the terminal function, you echo the variable. If you really want to get fancy, you can create a setup file with the variables being set by tput followed by functions that perform the echo command. The following examples illustrate some of the commands you might want in a setup file.

     cj>  cat term_setup
     BOLD=`tput smso`         # Turn bold display on
     CEOL=`tput ceol`         # Clear to the end of the line
     CLS=`tput clear`         # Home the cursor and clear the screen
     HOME=`tput home`         # Home the cursor
     NOBOLD=`tput rmso`       # Turn bold display off
     NORM=`tput sgr0`         # Set screen attributes to normal
      #
     function bold       { echo "$BOLD\c" ;}
     function cls        { echo "$CLS\c" ;}
     function ceol       { echo "$CEOL\c" ;}
     function home       { echo "$HOME\c" ;}
     function nobold     { echo "$NOBOLD\c" ;}
     function norm       { echo "$NORM\c" ;}

Once you have this file created you can execute it as part of another shell by using the . (dot) command. For example,

     . term_setup

would add all these variables to your local environment. If you want subprocesses to know about these variables, you can export them to your global environment. To use the set variables and functions you can use

     cj> cls

to clear the screen. You may need to perform the bold functions in lines of text and not as functions. To do this you can use the following syntax to change the word name to bold on your output.

     cj> echo "Type in your ${BOLD}name{NOBOLD} and press Return: \"

NOTE:  
Some terminals do not support certain attributes and therefore tput will not return strings for these unsupported attributes. You will need to check your terminal's programmer's manual for its capabilities.



You may find it useful to implement a cursor function for shell programming. To do this you simply create the following function.

     function cursor { tput cup $1 $2 ;}

To use the functions you simply type

     cj> cursor 4 20

and press Return. This positions the cursor on row 4 at column 20. If your system's tput does not support the cup capname, you might try the following code.

     cj> cat cursor_setup
     case "$TERM" in
     ansi|vt[123]*|pc*) function cursor { echo "\033[${1};${2}" ;} ;;
                 wyse*) function cursor { echo "\033a${1}R${2}C\c" ;} ;;
                     *) echo "Unsupported terminal type." ;;
     esac

You can use the . (dot) command to add this code to your shell script. To use the cursor function, type the following,

     . cursor_setup
     cursor 4 20

DIAGNOSTICS AND BUGS

The following error messages are displayed if a problem is encountered.

A usage message is displayed if you specify an invalid option.
-1 A -1 is displayed on the standard output if no integer capname attribute is defined for the terminal type specified.
unknown terminal type or no terminfo database
Displayed if the terminfo database does not exist or the terminal you specified does not exist in the terminfo database.
unknown terminfo capability capname
Displayed if the capname you requested is not valid.

RELATED COMMANDS

Refer to the stty and tabs commands described in modules 126 and 130.

RELATED FILES

The attribute strings associated with the capnames is displayed on the standard output. The tput command uses the following files during execution or when compiled.

/usr/lib/terminfo/?/* Compiled terminal description database entries.
/usr/include/curses.h Header file for compiling the tput.c source code.
/usr/include/term.h Header file for compiling the tput.c source code.
/usr/lib/tabset/* Files containing the appropriate escape sequences used for setting margins and tabs on more popular terminals.

RETURN CODES

The following return codes have special meanings as described.

-1 The integer type capname is not defined for this terminal type.
0 If capname is a Boolean and the attribute is TRUE for the terminal type specified.
If capname is a string and the attribute associated with capname for the terminal type exists. The attribute string is returned to the standard output.
If capname is an integer a 0 is always returned. If the integer attribute for the terminal type does not exist, a -1 is displayed on the standard output.
1 If capname is a Boolean and the attribute is FALSE for the terminal type specified.
If capname is a string and the attribute associated with capname for the terminal type does not exist. Nothing is sent to the standard output.
If -S option is specified a return code of 1 is impossible, since there is no way to know on which line the error occurred.
2 Usage error is displayed.
3 Unknown terminal type was specified or the terminfo database does not exist.
4 The capname you specified does not exist in the terminfo database.

APPLICATIONS

The tput command is useful in controlling the terminal attributes from the shell. It provides an interface into the terminfo database so you can perform most, if not all, of the terminal control functions supported in C. You can cursor the position, clear the screen, change the screen attributes, and other various terminal functions.

As described in the Further Discussion section previously, you can use command substitution to save the output strings and then later echo them to the terminal. This provides fast screen control. The implementation of terminal attribute functions provides another level of programming ease for controlling your terminal.

TYPICAL OPERATION

In this activity you use the tput command to clear the screen and place the cursor in the bottom left corner of the screen. Begin at the shell prompt.

1.  Type tput clear; tput cup 24 1 and press Return. Notice your screen is blank and your cursor is in the bottom left corner.
2.  Turn to Module 128 to continue the learning sequence.


Previous Table of Contents Next