Go to main content

man pages section 1: User Commands

Exit Print View

Updated: Wednesday, August 8, 2018
 
 

setterm (1)

Name

setterm - build a Stream on a tty line

Synopsis


setterm [ -t TERMNAME ]
setterm -x NAME
setterm -v

AVAILABILITY

system/locale/setterm

Description

setterm is used to build a STREAMS configuration on a tty line. setterm expects to be called with stdin, stdout, and stderr all attached to a terminal line, though it will usually work if only standard input is connected to a terminal line. It will normally be called with some kind of line discipline already pushed onto the line, since getty needs to push a line discipline that can be used by login.

If invoked with no arguments, setterm looks at the user's environment for a $TERM variable. If none is found, setterm exits, since it needs the $TERM information to do any further processing. If the -t option is given with an argument, the next argument (TERMNAME) is taken to be the name of a terminal type. The terminal name is looked up in the terminfo(5) database and the field devt (if one exists) is extracted from the entry. If there is no devt field, the terminal is assumed to be ASCII, requiring no additional processing, and setterm will then print the message "Device is ASCII" and exit.

setterm then runs the commands in its configuration file associated with the devt field in the terminfo(5) entry. If the –t option is not given, or if there are no command line arguments, then it is an error for no entry to match. In that case, setterm exits with an error message.

If the –x option is given, the following argument (NAME) is taken to be a devt field appearing in the configuration file. The terminfo(5) entry is not looked up, but the argument is used instead. The matching entry in the configuration file is executed unconditionally; therefore the –x option should be used with caution. The –x option is most useful for testing modules, and in switching between configurations dynamically, or for overriding the default entry for a particular devt type. The following devt fields are registered in each locale's configuration file:

Chinese/PRC locale (locale name = "zh")
GenericEUC|EUC

For EUC terminal

ASCII

For ASCII terminal

Error

For recovery from error in setterm execution

sane

For reset of STREAMS

Chinese/Taiwan locale (locale name = "zh_TW" / "zh_TW.BIG5")
big5

For Big-5 terminal

GenericEUC|EUC

For EUC terminal

ASCII

For ASCII terminal

Error

For recovery from error in setterm execution

sane

For reset of STREAMS

Japanese locale (locale name = "ja")
JapanPCK|PCK|JapanSJIS|SJIS

For PCK (Shift-JIS) terminal

JapanNewJIS7|NewJIS7

For 7Bit new JIS terminal

JapanOldJIS7|OldJIS7

For 7Bit old JIS terminal

JapanNewJIS8|NewJIS8

For 8Bit new JIS terminal

JapanOldJIS8|OldJIS8

For 8Bit old JIS terminal

GenericEUC|JapanEUC|EUC

For EUC terminal

ASCII

For ASCII terminal

Error

For recovery from error in setterm execution

sane

For reset of STREAMS

Japanese locale (locale name = "ja_JP.PCK")
JapanPCK|PCK|JapanSJIS|SJIS

For PCK (Shift-JIS) terminal

JapanNewJIS7|NewJIS7

For 7Bit new JIS terminal

JapanOldJIS7|OldJIS7

For 7Bit old JIS terminal

JapanNewJIS8|NewJIS8

For 8Bit new JIS terminal

JapanOldJIS8|OldJIS8

For 8Bit old JIS terminal

GenericEUC|JapanEUC|EUC

For EUC terminal

ASCII

For ASCII terminal

Error

For recovery from error in setterm execution

sane

For reset of STREAMS

The –v option is used to verify that the contents of the configuration file are correct. It prints debugging output for each entry in the configuration file, but does not perform any of the actions. It is only used for syntactic verification of configurations.

If the devt field is present for the given terminal, its value is used in searching the configuration file for an appropriate entry. The line in the configuration file is parsed and the actions carried out by setterm.

If the user's environment contains the variable $SETTLIB, it is taken to be the pathname of a file to use as the configuration file instead of the default configuration file, allowing per-user customization.

For languages requiring dictionary modules or other specialized processing capability the run command can be used to send appropriate ioctl(2) commands and do special purpose (i.e. language dependent) processing once the stream has been built, or appropriate modules pushed. Programs run via the run command for this purpose, generally residing in the setterm library, are known as initialization programs.

As distributed, the setterm configuration file comes with a few examples, and the format should be self-explanatory. Lines beginning with "#" (in the first column only) are ignored as comments.

COMMAND LANGUAGE

The setterm command language is very simple. Each entry occupies a single logical line in the configuration file. New lines may be escaped with a backslash so that entries may be spread over several physical lines for ease of editing. Each entry consists of an identifying word (which normally matches a devt entry of the terminfo(5) database) and a list of actions. Each action is separated by whitespace (spaces, tabs, or escaped new lines). A "word" is defined as a block of alpha-numeric or special printing characters containing no whitespace or control characters.

An action consists of a command word, which may be followed by a single argument word. The argument word is separated from the command word by either a comma or whitespace.

An argument word must not contain any spaces or tabs, but may have internal delimiters, such as colons and commas.

For example:

 
          Acceptable:    A=ldterm:eldterm,ld0:eld0
          Unacceptable:  A = ldterm: eldterm , ld0:eld0
     
      

The following commands are recognized. "NAME", "NAMELIST", "MOD1", and "MOD2 ", indicate the names of modules; "NAMELIST" indicates one or more of module names separated (with no space) by a vertical bar ("|" symbol); "CMD" indicates a shell command line; "VAR" indicates a single letter variable name from "A" through "F"; "WORDLIST" indicates a special wordlist for the "select" command:

 
               cmd       Arguments           Action(s)

               pop       none                pop one module
               popto     NAMELIST            pop until it encounters one of
                                             modules in NAMELIST or there is no
                                             more to pop
               popall    none                pop all modules
               throw     none                save termio(4i) settings
               catch     none                restore termio(4i) settings
               push      NAME                push module name
               run       { CMD }             run command line between {}
               set       VAR                 set VAR to name of top module
               if        VAR=NAME?MOD1:MOD2  if the value of VAR is equal
                                             to NAME, then push MOD1, else
                                             push MOD2
               test      VAR=NAME            set VAR to
                                             NAME if the module "NAME" is in the
                                             STREAM
               select    VAR=WORDLIST        test "VAR" against the left
                                             word of each pair in "WORDLIST";
                                             push the first right word that matches
     
      

Some special words are recognized for the if, test and select commands. These words are:

 
          END  stop processing and exit
          NUL  do nothing
          POP  pop a module rather than pushing
          ELSE as first of a pair in a WORDLIST,
               match any value including a NULL string
     
      

The argument to an if command as shown above means that if the value of the given variable matches the literal module name "NAME", then the action " MOD1" is taken, otherwise the action "MOD2" is taken. If no alternate action is desired, the colon and "MOD2 " may be elided. By default, the action for a module name is to push it. If the module name is one of the special names, then the action associated with the special name is taken. An "ELSE" keyword may not appear in a test or if command. The END keyword may not appear as the value to test a variable against, but only as an action to take on a match.

The "WORDLIST" for a select command is a variable name, an equal sign, then a list of word pairs of the form "WORD.WORD". Each word pair is separated from the others by a comma. Thus, a whole select command might look like:

select A=eld0:ld0epld:ppld,ELSE:ld0

The "ELSE" keyword cannot be used as the right word of a pair, nor can the "END" keyword be used as the left word of a pair; "NULL" can be either.

The run command is exceptional in that its argument may contain spaces between the curly braces. An action for a run command might be:

run { /usr/share/lib/setterm/a_prog an_arg }

Commands invoked through the run command should reside in the /usr/share/lib/setterm directory, though this is not required. They should not require too many arguments as they are intended to be very specialized. In general, they perform any device or language-dependent processing on behalf of setterm , which has no language-dependent processing capability.

If setterm was invoked with the –t option, then programs invoked through the run command will have their environment $TERM variable replaced with the terminal name indicated in the argument to the –t option.

The throw command saves the termio(4I) settings of the tty. They can be restored (presumably after the line discipline or other module has changed) through the catch command. These are useful for switching line disciplines, when both the old and new line disciplines support the termio(4I) interface. If a catch is done without a prior throw, then the command line stty sane will be done instead of the catch (useful for restoring badly messed up Streams); thus a catch with no throw is equivalent to run{stty sane}. Two throw cannot be done without a catch between them.

Examples

The following example shows how a complete entry might look in the configuration file:

 
          #
          # Japanese 7-bit JIS terminal
          JapanJIS7|JIS7throw\
               popto zs|mcp|mti|ptem\
               push jconv7\
               push ldterm\
               push ttcompat\
               catch
          #
     
      

This entry can be invoked with:


%  setterm -x JIS7


As noted, the escaped new lines are necessary since the entry must be on a single logical line. Escaped newlines are treated as single space characters.

The devt label in the configuration file may optionally be a list of words separated (with no spaces) by a vertical bar ("|" symbol). In this case, each one is scanned by setterm for a match when looking for an entry in the file; if any word of the "|" separated list matches, that entry is used.

There is an extra variable, T, which when set with the set command, takes on a generic device name. When this variable is set, a call to ttyname(3C) on file descriptor zero is issued by setterm. The resulting device name is stripped of any trailing ASCII digits (i.e., 0-9), and the result becomes the value of the T variable. This is useful if specialized processing is necessary for different device types or drivers, for example if the console requires special-purpose processing. Actual device names, such as /dev/tty33 are turned into names such as /dev/tty. Beware that names containing no trailing digits cannot be stripped of them, so that /dev/console remains the same. An example of usage might be:

set T select T=/dev/console:this,/dev/tty:that,ELSE:other

LIMITATIONS

Currently, the maximum size of a single "action" entry is limited to 2047 bytes. The number of items in a "select" list is limited to 30. setterm unfortunately cannot be used to build multiplexing configurations. The run command may help where multiplexing configurations are required. setterm will neither save nor restore termio(4I) settings, except through "throw" and "catch".

Error reporting is minimal; all errors are fatal. Inability to pop a module is not an error, since it may signal the "bottom " of the STREAM.

The configuration file is scanned sequentially, and only the first entry found for a particular devt is executed.

CAVEATS

Since all errors are fatal, the user could be left with an extremely raw terminal configuration, or with a completely useless configuration from which there is no escape except by logging out. "Throw", "catch", and tests for existence of a reasonable top-level module should help reduce these possibilities. Rigorous testing of new entries under varying conditions is recommended. It is also recommended that a "sane" entry of some type be inserted into the configuration file for use with the –x option.

setterm uses its standard input file (file descriptor zero) for all ioctl(2) calls to the terminal. Therefore, if the terminal should hang (for example, if all modules have been popped but it is impossible to push anything, or in the event of a module hangup or failure) it is possible to run setterm from another terminal (assuming appropriate permissions) with standard input redirected to the errant terminal line. For example, if tty12 is hung due to a module problem, "setterm-x ... < /dev/tty12" should clear the problem.

Beware of infinite recursion when calling setterm recursively (i.,e., when "run { setterm ... }" from within an entry; setterm cannot detect infinite recursion.

Files

/usr/share/lib/setterm

setterm library

/usr/share/lib/setterm/locale/conf.file

default configuration file

/usr/share/lib/setterm/NOTES

explanation and notes on format

Attributes

See attributes(7) for descriptions of the following attributes:

ATTRIBUTE TYPE
ATTRIBUTE VALUE
Availability
system/locale/extra

See Also

streamio(4I), termio(4I), terminfo(5), getty(8), tic(8)

Documentation on various local modules

Bugs

A missing curly bracket (}) to a run command may not be caught by the parser, which is relatively crude. This can result in bad arguments to commands, without the syntax error being caught.