unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (SunOS-5.10)
Page:
Section:
Apropos / Subsearch:
optional field

setterm(1)                  General Commands Manual                 setterm(1)



NAME
       setterm - build a Stream on a tty line

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

AVAILABILITY
       SUNWale

DESCRIPTION
       Setterm  is  used  to  build a STREAMS configuration on a tty line.  It
       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(4)  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(4) 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(4)
       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  use-
       ful for testing modules, and in switching between configurations dynam-
       ically, or for overriding the default entry  for  a  particular  "devt"
       type.  The following "devt" fields are registered in each locale's con-
       figuration file:

       Chinese/PRC locale (locale name = "zh")

              GenericEUC|EUC          For EUC terminal
              ASCII                   For ASCII terminal
              Error                   For recovery from error in setterm  exe-
                                      cution
              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 exe-
                                      cution
              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  exe-
                                      cution
              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 exe-
                                      cution
              sane                    For reset of STREAMS

       Korean locale (locale name = "ko")

              KoreanPACK|PACK         For   Packed   code   terminal   (KS   C
                                      5601-1987)
              KoreanJOHAP|JOHAP       For  Combination  code  terminal  (KS  C
                                      5601-1992)
              GenericEUC|EUC          For EUC (Wansung) terminal
              ASCII                   For ASCII terminal
              Error                   For recovery from error in setterm  exe-
                                      cution
              sane                    For reset of STREAMS

       Korean locale (locale name = "ko.UTF-8")

              U8|u8|UTF-8|utf-8       For UTF-8 (of KS C 5700) terminal
              KoreanU8EUC|KU8EUC      For EUC (Wansung) terminal
              KoreanU8JOHAP|KU8JOHAP  For  Combination  code  terminal  (KS  C
                                      5601-1992)
              GenericEUC|EUC          For EUC (Wansung) terminal without UTF-8
                                      code conversion
              ASCII                   For ASCII terminal
              Error                   For  recovery from error in setterm exe-
                                      cution
              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  pro-
       cessing  capability  the  "run" command can be used to send appropriate
       ioctl(2) commands and do special purpose (i.e. language dependent) pro-
       cessing  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 exam-
       ples, 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.  Newlines 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(4) database) and
       a list of actions.  Each action is  separated  by  whitespace  (spaces,
       tabs,  or  escaped newlines).  A "word" is defined as a block of alpha-
       numeric or special printing characters containing no whitespace or con-
       trol 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  ("|"  sym-
       bol);  "CMD"  indicates  a shell command line; "VAR" indicates a single
       letter variable name from "A" through "F"; "WORDLIST" indicates a  spe-
       cial 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(7) settings
                 catch     none                restore termio(7) 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,  has  the  following
       meaning:  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.  The action for a module name is, by default,  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, of course be used as the  right  word  of  a
       pair,  nor  can  the  "END" keyword be used as the left word of a pair;
       "NUL" can be either.

       The "run" command is exceptional in that its argument may contain  spa-
       ces 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 direc-
       tory /usr/share/lib/setterm, though this is not required.  They  should
       not require too many arguments as they are intended to be very special-
       ized.  In general, they perform any device- or language-dependent  pro-
       cessing  on behalf of setterm, which has no language-dependent process-
       ing 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(7) 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,
       as  a minimum, the termio(7) 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 con-
       figuration 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 newlines are necessary since the  entry  must  be
       all  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(3) 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 driv-
       ers, 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 just that.  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  configura-
       tions.   The  "run"  command may help where multiplexing configurations
       are required.  Setterm will neither save  nor  restore  termio(7)  set-
       tings, 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 worse, with a completely useless  con-
       figuration  from which there is no escape except by logging out (if any
       input is possible at all!).  "Throw", "catch", and tests for  existence
       of  a  reasonable  top-level module should help reduce these possibili-
       ties.  Rigorous testing of new entries under varying conditions is rec-
       ommended.   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 ... <&lt; /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

SEE ALSO
       getty(1M), tic(1M), terminfo(4), streamio(7), termio(7)

       Documentation on various local modules

BUGS
       A missing "}" 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.




                                 6 March 1992                       setterm(1)