home *** CD-ROM | disk | FTP | other *** search
/ rtsi.com / 2014.01.www.rtsi.com.tar / www.rtsi.com / OS9 / OSK / DRIVERS / SRC / ptys.lzh / ptyman.doc < prev    next >
Text File  |  1990-04-25  |  10KB  |  251 lines
  1.                    Pseudo-Terminal (PTY) File-Manager
  2.                    ==================================
  3. Overview:
  4.  
  5.         Pseudo-Terminals (PTY's) are a kind of Interprocess
  6. Communication (IPC), which are known on a wide variety of UN*X
  7. computers, mostly BSD-like systems.  They behave like any other SCF
  8. devices like terminals and printer but are in fact pseudo-devices i.e. 
  9. exists only in the memory the system. 
  10.  
  11.         PTY's have two distinct end-points, namely server-pty and
  12. client-pty, which behaves by default differently.  A server-pty
  13. symbolizes the terminal and a client-pty forms the connection to the
  14. application programs.  This implies, that the server-pty provides RAW
  15. input and output whereas the client-pty can handle line-editing, echoing
  16. and so on. 
  17.  
  18.         With this mechanism many programms can share one real device,
  19. like a real terminal, via one server which multiplexes all connected
  20. server-pty's.  Something similar can be reached with the usage of pipes,
  21. but pipes have the disadvantage of being not a tty-device with echo,
  22. line-editing, interrupt-chars etc. 
  23.  
  24. Examples:
  25.     - virtual Terminals: one program multiplexes ptys and displays the
  26.       outputs on a real Terminal (there exist a programm called 'screen'
  27.       which does exactly this). 
  28.     - In a TCP/IP environment, the program 'rlogin' starts a
  29.       login-process on a pty on the remote machine.
  30.  
  31. ___________________________________________________________________________
  32.  
  33.                       /***********\             /**************\
  34.                       *           *             *              *
  35.                       *   Server- * ----------> *  real Device *
  36.                       *    Prg.   *             *              *
  37.                       \***********/             \**************/
  38.                     ___+  +  +  +_______
  39.                 ___/       \  \         \_______
  40.             ___/            \  \________        \________
  41.            /                 \          \_______         \__________
  42.           |                   |                 |                   |
  43.     /***********\       /***********\       /***********\       /***********\
  44.     *           *       *           *       *           *       *           *
  45.     *  1st Prg. *       *  2nd Prg. *       *  3rd Prg. *       *  4th Prg. *
  46.     *           *       *           *       *           *       *           *
  47.     \***********/       \***********/       \***********/       \***********/
  48.  
  49. '|' meaning client-pty
  50. '+' meaning server-pty
  51.  
  52. Fig. 1:  Typical Server-Client Application
  53.  
  54.  
  55. Implementation:
  56.  
  57.         With OS9-68000 (OSK) a own File-Manager was written, which
  58. handles both types of PTY's : the client-ptys, and the server-ptys while
  59. using only *one* descriptor (device) for each.  Server-ptys must be
  60. opened as "/pty/any_valid_name" , client-ttys must be opened (i.e. 
  61. connected) with "/tty/any_valid_name".  The Open-Call for the client-pty
  62. will block until a server-pty with the same name is opened.  PTY's can
  63. be also implemented with the usage of a special device-driver for the
  64. SCF, but this has serveral draw-backs :
  65.  
  66.         - A System-Global Variable has to be introduced for the rendezvous
  67.           of the PTY-pairs (not implementation independent). 
  68.  
  69.         - For each pair of PTY's there must exist two Device-Descriptors
  70.           (waste of memory and Device-Table-entries).
  71.  
  72.         - The number of PTY's pairs are limited !!
  73.  
  74.         - Block-writes in RAW modus has still to be done on a char-by-char
  75.           basis with single calls to the driver, as required by the SCF
  76.  
  77.         When creating a server-PTY the Filemanager searches a list of
  78. already openend server-ptys for the same name.  The name can be any
  79. legal OS-9/68000 Filename (no distinction between upper- and
  80. lower-case).  When a identical name is found, the Filemanager return a
  81. E_CEF-error (File already exists), otherwise the Pathdescriptor (PD) is
  82. inserted into this list and some initialisation is done (allocating
  83. Data-Buffers etc.). 
  84.  
  85.         When opening a client-PTY the Filemanager looks thru the above
  86. mentioned list for a already openend server-pty.  If found, it sets a
  87. special pointer pointing to the PD of the server-pty.  (the Filemanager
  88. basicly distincts server-pty's and client-pty's by the value of this
  89. pointer). 
  90.  
  91. Remark:
  92.     There exist only *one* named server-pty but there can be many
  93.     client-ptys listening (although its possibly to I$DUP a
  94.     server-pty-fd). 
  95.  
  96.         When closing a Server-Pty, the Filemanager searches for all
  97. client-pty's and sets the special pointer to NULL indicating a
  98. HANGUP-condition.  He also tries to send a SIGHUP-Signal (value is
  99. changeable via the _ss_dcoff()-Call) to the last/current user of a
  100. client-pty.  Any further I/O calls to a disconnected client-pty will
  101. issue a E_HANGUP-Error and a SIGHUP signal !
  102.  
  103.         Closing a client-pty requires no special tasks but clearing all
  104. pending Signals (e.g.  pending _ss_signl() ), which is done automaticly. 
  105.  
  106.         Although total compatibility to a SCF-Device was intended, the
  107. PTY-Filemanager does differ in some small aspects from the SCF.  The
  108. reason for that were some features of the SCF, which I do consider
  109. faulty e.g.  with a ReadLn-count of one the only character you can read
  110. is CR and nothing else (:-( ). 
  111.  
  112. Differences:
  113.     - a Readln-Call with a character count of 1 will return the next
  114.       character available.
  115.  
  116.     - The Read-Call may behave differently: kbich and kbach will
  117.       abort with the appropriate Error-codes. No Echo, but raw-byte-transfer.
  118.  
  119.     - The Pause-char, Xon-char and Xoff-char are not supported !
  120.  
  121.     - Any signal < 32 and > 1 (SIGWAKE) will abort a pending I/O with an
  122.       error-code of the signal (this should be made standard).
  123.  
  124.     - A close of a server-pty will only generate a SIGHUP (see SS_DCOff)
  125.       and will *not* abort the reading processes (the program 'com'
  126.       seems to have problems with that !).
  127.  
  128.  
  129. Descriptions of operation:
  130.  
  131. - Read-calls:
  132.     absolute raw-read, ignores echo-parameter, but unterstands kbich and
  133.     kbach. 
  134.  
  135. - Write-calls:
  136.     absolute raw-write .... but sends QUIT and INT if set.
  137.  
  138. - Writeln-calls:
  139.     recognizes upc, tabch, tabs, alf, pause and returns on recognizing 
  140.     the eor-char (normaly CR). sends QUIT and INT if set.
  141.  
  142. - Readln-calls:
  143.     recognition of echo, upc, bso, bse, bspchar, eorchar, alf (when
  144.     echoing), kbich, kbach, eof, delchar, rprchar, dupchar and pause.
  145. CAVEAT:
  146.     - A final EOR in the input-stream is not necessary and this was
  147.       deliberatly avoided !!!
  148.     - The maximum readln-count is 256 Bytes (like in the SCF). You can
  149.       specify more but the Filemanger will cut it to 256...
  150.  
  151. - GetStat-calls:
  152.     supported codes are: SS_Opt, SS_Ready, SS_EOF, SS_DevNm (returns the
  153.     name of the pty), SS_BlkRd.
  154.  
  155. - SetStat-calls:
  156.     supported codes are: SS_Opt, SS_SSig, SS_Relea, SS_EnRTS, SS_DsRTS,
  157.     SS_DCOn, SS_DCOff, SS_BlkWr.
  158. CAVEAT:
  159.     - SS_DCOn, SS_EnRTS and SS_DsRTS are no-ops.
  160.  
  161. Not supported are null (for padding), pausechar, xon and xoff.
  162.  
  163.  
  164. Description of GetStat-Codes:
  165.  
  166.     - SS_Opt:
  167.         copy the first 28 Bytes of the option part to the users
  168.         (a0)-register.
  169.  
  170.     - SS_Ready:
  171.         return number of chars available for reading in users d1
  172.         register, or return E_NOTRDY if no input is available.
  173.  
  174.     - SS_EOF:
  175.         always returns 0 in callers d1 register (like SCF).
  176.  
  177.     - SS_DevNm:
  178.         return the null-terminated name of the pty into the callers
  179.         (a0)-register.
  180.  
  181.     - SS_BlkRd:
  182.         Read x (in users d2-register) Bytes into buffer, users
  183.         (a0)-register is pointing to.
  184.  
  185.  
  186. Description of SetStat-Codes:
  187.  
  188.     - SS_Opt:
  189.         copy the first 28 Byte from users (a0)-register into the option
  190.         part of the pathdescriptor.
  191.  
  192.     - SS_SSig:
  193.         Send signal in users d2-register on receiving the next
  194.         available character. If another Process is waiting for input,
  195.         return an E_NOTRDY error.
  196.  
  197.     - SS_Relea:
  198.         Clear a SS_SSig action...
  199.  
  200.     - SS_EnRTS:
  201.         no-op
  202.  
  203.     - SS_DsRTS:
  204.         no-op
  205.  
  206.     - SS_DCOn:
  207.         no-op
  208.  
  209.     - SS_DCOff:
  210.         Send Signal in users d2-register on closing the server-pty
  211.         (Carrier-lost condition). The Default signal is SIGHUP (Value: 4).
  212.  
  213.     - SS_BlkWr:
  214.         Write x ( in users d2-register ) Bytes from buffer users
  215.         (a0)-register is pointing to.
  216.  
  217.     - SS_Screen (Subfunction ScrOut):
  218.         Optional, like BlkWr. exists only on ST's (Cumana Implementation).
  219.  
  220.  
  221. Final Thoughts:
  222.  
  223.         Some tests have shown, that this Filemanager is about 100%
  224. faster than an orthodox implementation with a special device Driver for
  225. the SCF when doing readln/writeln calls.  By using only read/write calls
  226. some can expect even much more throughput (no line-editing stuff etc..). 
  227.  
  228. BUGS:
  229.  
  230.         This Filemanager seems to have problems in OSK-Versions lower
  231. than 2.0 (-> e.g. 1.2).  I think the 'openend-Path'-list isnt supported
  232. by the Kernel (IOMan); maybe the Filemanager should do it itself ??
  233.         'tmode normal' dont work, since it takes the name returned by
  234. DevNm as a Descriptor-module-name. This is easily changeable by returning
  235. 'pty' or 'tty' on SS_DevNm.
  236.  
  237. Things to do:
  238.     - shrinking the code
  239.     - treatment of dir-bit as in PipeMan, to see what ptys are open ?
  240.     - more lineediting (emacs-style, history ?)
  241.     - implementing the pausechar and maybe xon/xoff ?
  242.  
  243. Please send any suggestions/Bug-reports to:
  244.     Reimer Mellin
  245.     Sulenstr. 8
  246.     D-8000 Muenchen 71
  247.  
  248.     UUCP: mellin@lan.informatik.tu-muenchen.dbp.de (preferred)
  249.           mellin@altger.UUCP
  250.           ....!pyramid!tmpmbx!doitcr!ramsys!ram (home)
  251.