From 206d1c890720dc73ac236495b821c6585e7e1228 Mon Sep 17 00:00:00 2001 From: zzak Date: Wed, 20 Feb 2013 04:37:35 +0000 Subject: * ext/pty/pty.c: Documentation for the PTY module git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@39331 b2dd03c8-39d4-4d8f-98ff-823fe69b080e --- ext/pty/pty.c | 135 ++++++++++++++++++++++++++++++++-------------------------- 1 file changed, 74 insertions(+), 61 deletions(-) (limited to 'ext/pty/pty.c') diff --git a/ext/pty/pty.c b/ext/pty/pty.c index 359e5bff1a..8ac731404a 100644 --- a/ext/pty/pty.c +++ b/ext/pty/pty.c @@ -476,54 +476,29 @@ pty_close_pty(VALUE assoc) * * Allocates a pty (pseudo-terminal). * - * In the non-block form, returns a two element array, [master_io, - * slave_file]. - * * In the block form, yields two arguments master_io, slave_file * and the value of the block is returned from +open+. * * The IO and File are both closed after the block completes if they haven't * been already closed. * - * The arguments in both forms are: + * PTY.open {|master, slave| + * p master #=> # + * p slave #=> # + * p slave.path #=> "/dev/pts/1" + * } * - * master_io:: the master of the pty, as an IO. - * slave_file:: the slave of the pty, as a File. The path to the - * terminal device is available via - * slave_file.path + * In the non-block form, returns a two element array, [master_io, + * slave_file]. * - * === Example + * master, slave = PTY.open + * # do something with master for IO, or the slave file * - * PTY.open {|m, s| - * p m #=> # - * p s #=> # - * p s.path #=> "/dev/pts/1" - * } + * The arguments in both forms are: * - * # Change the buffering type in factor command, - * # assuming that factor uses stdio for stdout buffering. - * # If IO.pipe is used instead of PTY.open, - * # this code deadlocks because factor's stdout is fully buffered. - * require 'io/console' # for IO#raw! - * m, s = PTY.open - * s.raw! # disable newline conversion. - * r, w = IO.pipe - * pid = spawn("factor", :in=>r, :out=>s) - * r.close - * s.close - * w.puts "42" - * p m.gets #=> "42: 2 3 7\n" - * w.puts "144" - * p m.gets #=> "144: 2 2 2 2 3 3\n" - * w.close - * # The result of read operation when pty slave is closed is platform - * # dependent. - * ret = begin - * m.gets # FreeBSD returns nil. - * rescue Errno::EIO # GNU/Linux raises EIO. - * nil - * end - * p ret #=> nil + * +master_io+:: the master of the pty, as an IO. + * +slave_file+:: the slave of the pty, as a File. The path to the + * terminal device is available via +slave_file.path+ * */ static VALUE @@ -567,31 +542,28 @@ pty_detach_process(struct pty_info *info) * call-seq: * PTY.spawn(command_line) { |r, w, pid| ... } * PTY.spawn(command_line) => [r, w, pid] - * PTY.spawn(command, args, ...) { |r, w, pid| ... } - * PTY.spawn(command, args, ...) => [r, w, pid] - * PTY.getpty(command_line) { |r, w, pid| ... } - * PTY.getpty(command_line) => [r, w, pid] - * PTY.getpty(command, args, ...) { |r, w, pid| ... } - * PTY.getpty(command, args, ...) => [r, w, pid] + * PTY.spawn(command, arguments, ...) { |r, w, pid| ... } + * PTY.spawn(command, arguments, ...) => [r, w, pid] * - * Spawns the specified command on a newly allocated pty. + * Spawns the specified command on a newly allocated pty. You can also use the + * alias ::getpty. * * The command's controlling tty is set to the slave device of the pty * and its standard input/output/error is redirected to the slave device. * - * command_line:: The full command line to run - * command:: The command to run, as a String. - * args:: Zero or more arguments, as Strings, representing - * the arguments to +command+ + * +command+ and +command_line+ are the full commands to run, given a String. + * Any additional +arguments+ will be passed to the command. + * + * === Return values * * In the non-block form this returns an array of size three, - * [r, w, pid]. In the block form the block will be called with - * these as arguments, |r,w,pid|: + * [r, w, pid]. + * + * In the block form these same values will be yielded to the block: * - * +r+:: An IO that can be read from that contains the command's + * +r+:: A readable IO that that contains the command's * standard output and standard error - * +w+:: An IO that can be written to that is the command's - * standard input + * +w+:: A writable IO that is the command's standard input * +pid+:: The process identifier for the command. */ static VALUE @@ -667,15 +639,16 @@ raise_from_check(pid_t pid, int status) * PTY.check(pid, true) => nil or raises PTY::ChildExited * * Checks the status of the child process specified by +pid+. - * Returns +nil+ if the process is still alive. If the process - * is not alive, will return a Process::Status or raise - * a PTY::ChildExited (if +raise+ was true). + * Returns +nil+ if the process is still alive. + * + * If the process is not alive, and +raise+ was true, a PTY::ChildExited + * exception will be raised. Otherwise it will return a Process::Status + * instance. * * +pid+:: The process id of the process to check - * +raise+:: If true and the process identified by +pid+ is no longer - * alive a PTY::ChildExited is raised. + * +raise+:: If +true+ and the process identified by +pid+ is no longer + * alive a PTY::ChildExited is raised. * - * Returns nil or a Process::Status when +raise+ is false. */ static VALUE pty_check(int argc, VALUE *argv, VALUE self) @@ -699,7 +672,7 @@ static VALUE cPTY; /* * Document-class: PTY::ChildExited * - * Thrown when PTY#check is called for a pid that represents a process that + * Thrown when PTY::check is called for a pid that represents a process that * has exited. */ @@ -709,6 +682,45 @@ static VALUE cPTY; * Creates and managed pseudo terminals (PTYs). See also * http://en.wikipedia.org/wiki/Pseudo_terminal * + * PTY allows you to allocate new terminals using ::open or ::spawn a new + * terminal with a specific command. + * + * == Example + * + * In this example we will change the buffering type in the +factor+ command, + * assuming that factor uses stdio for stdout buffering. + * + * If IO.pipe is used instead of PTY.open, this code deadlocks because factor's + * stdout is fully buffered. + * + * # start by requiring the standard library PTY + * require 'pty' + * + * master, slave = PTY.open + * read, write = IO.pipe + * pid = spawn("factor", :in=>read, :out=>slave) + * read.close # we dont need the read + * slave.close # or the slave + * + * # pipe "42" to the factor command + * write.puts "42" + * # output the response from factor + * p master.gets #=> "42: 2 3 7\n" + * + * # pipe "144" to factor and print out the response + * write.puts "144" + * p master.gets #=> "144: 2 2 2 2 3 3\n" + * write.close # close the pipe + * + * # The result of read operation when pty slave is closed is platform + * # dependent. + * ret = begin + * m.gets # FreeBSD returns nil. + * rescue Errno::EIO # GNU/Linux raises EIO. + * nil + * end + * p ret #=> nil + * * == License * * C) Copyright 1998 by Akinori Ito. @@ -727,6 +739,7 @@ void Init_pty() { cPTY = rb_define_module("PTY"); + /* :nodoc */ rb_define_module_function(cPTY,"getpty",pty_getpty,-1); rb_define_module_function(cPTY,"spawn",pty_getpty,-1); rb_define_singleton_method(cPTY,"check",pty_check,-1); -- cgit v1.2.3