ruby--ruby/ext/pty/README

pty extension version 0.3 by A.ito

1. Introduction

This extension module adds ruby a functionality to execute an 
arbitrary command through pseudo tty (pty).

2. Install

Follow the instruction below.

(1) Execute

      ruby extconf.rb

    then Makefile is generated.

(3) Do make; make install.

3. What you can do

This extension module defines a module named PTY, which contains
following module fungtions:

   getpty(command)
   spawn(command)

      This function reserves a pty, executes command over the pty 
      and returns an array. The return value is an array with three
      elements. The first element in the array is for reading and the 
      second for writing. The third element is the process ID of the
      child process. If this function is called with an iterator block,
      the array is passed to the block as block parameters, and the
      function itself returns nil.

      While the process spawned by this function is active, SIGCHLD
      is captured to handle the change of the child process. When the
      child process is suspended or finished, an exception is raised.
      As all SIGCHLD signal is captured and processed by PTY module,
      you can't use other function or method which spawns subprosesses
      (including signal() and IO.popen()) while the PTY subprocesses
      are active. Otherwise, unexpected exception will occur. To avoid
      this problem, see protect_signal() below.

      If this function is called with an iterator block, SIGCHLD signal
      is captured only within the block. Therefore, it is risky to use
      File objects for PTY subprocess outside the iterator block.


   protect_signal

      This function takes an iterator block. Within the iterator block,
      no exception is raised even if any subprocess is terminated.
      This function is used to enable functions like system() or IO.popen()
      while PTY subprocess is active. For example,

        PTY.spawn("command_foo") do |r,w|
          ...
          ...
          PTY.protect_signal do
            system "some other commands"
          end
          ...
        end

      disables to send exception when "some other commands" is 
      terminated. 

    reset_signal

      Disables to handle SIGCHLD while PTY subprocess is active.


4. License

(C) Copyright 1998 by Akinori Ito.

This software may be redistributed freely for this purpose, in full 
or in part, provided that this entire copyright notice is included 
on any copies of this software and applications and derivations thereof.

This software is provided on an "as is" basis, without warranty of any
kind, either expressed or implied, as to any matter including, but not
limited to warranty of fitness of purpose, or merchantability, or
results obtained from use of this software.

5. Bug report

Please feel free to send E-mail to

   aito@ei5sun.yz.yamagata-u.ac.jp

for any bug report, opinion, contribution, etc.