* NEWS (ptr): new method and deprecated methods. [ruby-dev:41681]

* ext/pty/{README,README.ja}: ditto.

* ext/pty/pty.c (pty_check): add rdoc.


git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@28399 b2dd03c8-39d4-4d8f-98ff-823fe69b080e

3 files changed, 46 insertions, 31 deletions

diff --git a/ext/pty/README b/ext/pty/README
index 42c7d4f891..d6368f3758 100644
--- a/ext/pty/README
+++ b/ext/pty/README
@@ -43,6 +43,25 @@ following module fungtions:
 
       These functions are obsolete in this version of pty.
 
+   PTY.open
+
+      Allocates a pty (pseudo-terminal).
+
+      It returns an array which contains an IO object and a File object.
+      The former is the master of the pty.
+      The latter is the slave of the pty.
+
+      If a block is given, it yields the array instead of return.
+      The value of the block is returned.
+      master_io and slave_file is closed when return if they are not closed.
+
+   PTY.check(pid[, raise=false])
+
+      checks the status of the child process specified by pid, and
+      returns nil if the process is still alive and active.
+      Otherwise, returns Process::Status about the process if raise is
+      false, or PTY::ChildExited exception is raised.
+
 4. License
 
 (C) Copyright 1998 by Akinori Ito.
diff --git a/ext/pty/README.ja b/ext/pty/README.ja
index 5ae4fb06a0..ca2a01442a 100644
--- a/ext/pty/README.ja
+++ b/ext/pty/README.ja
@@ -30,43 +30,30 @@ pty 拡張モジュール version 0.3 by A.ito
       セスIDです．この関数がイテレータとして呼ばれた場合，これらの
       要素はブロックパラメータとして渡され，関数自体はnilを返します．
 
-      この関数によって作られたサブプロセスが動いている間，子プロセス
-      の状態を監視するために SIGCHLD シグナルを捕捉します．子プロセス
-      が終了したり停止した場合には，例外が発生します．この間，すべての
-      SIGCHLD が PTY モジュールのシグナルハンドラに捕捉されるので，
-      サブプロセスを生成する他の関数(system() とか IO.popen()など)を
-      使うと，予期しない例外が発生することがあります．これを防ぐため
-      には，下記のprotect_signal()を参照してください．
-
-      この関数がブロックパラメータ付きで呼ばれた場合には，そのブロック
-      の中でのみ SIGCHLD が捕捉されます．したがって，ブロックパラメータ
-      として渡されたIOオブジェクトを，ブロックの外に持ち出して使うの
-      は勧められません．
-
-
+      子プロセスが終了したり停止した場合には，例外が発生します．この関
+      数がブロックパラメータ付きで呼ばれた場合には，そのブロックの中で
+      のみ例外が発生します．子プロセスをモニターしているスレッドはブロッ
+      クを抜けるときに終了します．
+      
    protect_signal
+   reset_signal
 
-      この関数はイテレータです．ここで指定されたブロックの中では，
-      子プロセスが終了しても例外を発生しません．この関数を使うことで，
-      PTYの子プロセスが動いている間でも，system()や IO.popen()などの
-      関数を安全に使うことができます．例えば，
+      廃止予定です．
 
-        PTY.spawn("command_foo") do |r,w|
-          ...
-          ...
-          PTY.protect_signal do
-            system "some other commands"
-          end
-          ...
-        end
+   PTY.open
 
-      このような記述により，"some other commands" が終了したときに
-      例外が発生するのを防げます．
+      仮想ttyを確保し，マスター側に対応するIOオブジェクトとスレーブ側に
+      対応するFileオブジェクトの配列を返します．ブロック付きで呼び出さ
+      れた場合は，これらの要素はブロックパラメータとして渡され，ブロッ
+      クから返された結果を返します．また、このマスターIOとスレーブFile
+      は、ブロックを抜けるときにクローズ済みでなければクローズされます．
 
-    reset_signal
+   PTY.check(pid[, raise=false])
 
-      PTY の子プロセスが動いていても，そのプロセスの終了時に例外が発生
-      しないようにします．
+      pidで指定された子プロセスの状態をチェックし，実行中であればnilを
+      返します．終了しているか停止している場合、第二引数が偽であれば、
+      対応するProcess::Statusオブジェクトを返します。真であれば
+      PTY::ChildExited例外が発生します．
 
 4. 利用について
 
diff --git a/ext/pty/pty.c b/ext/pty/pty.c
index 9026dafee6..e212b49434 100644
--- a/ext/pty/pty.c
+++ b/ext/pty/pty.c
@@ -606,6 +606,15 @@ raise_from_check(pid_t pid, int status)
     rb_exc_raise(exc);
 }
 
+/*
+ * call-seq:
+ *   PTY.check(pid[, raise=false])   => Process::Status or nil
+ *
+ * checks the status of the child process specified by _pid_, and
+ * returns +nil+ if the process is still alive and active.  Otherwise,
+ * returns +Process::Status+ about the process if _raise_ is false, or
+ * +PTY::ChildExited+ exception is raised.
+ */
 static VALUE
 pty_check(int argc, VALUE *argv, VALUE self)
 {