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 ter-
       minfo(4) entry is not looked up, but the argument is used instead.  The matching entry in the configuration file is  executed  uncondition-
       ally; therefore the -x option should be used with caution.  The -x option is most useful for testing modules, and in switching between con-
       figurations 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

       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 execution
	      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 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  pro-
       grams.

       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.  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
       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 sin-
       gle 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(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 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 directory /usr/share/lib/setterm, 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(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 sup-
       port, 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 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 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
       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 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 configurations.  The "run" command may help where multiplexing configurations
       are required.  Setterm will neither save nor restore termio(7) 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 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  exis-
       tence 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

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)