From 98715f199830ef13f40b8af613804da553673341 Mon Sep 17 00:00:00 2001 From: Dave Copeland Date: Thu, 19 May 2011 20:33:54 -0400 Subject: [PATCH 2/3] Clean up docs for pty --- ext/pty/README.rdoc | 3 ++ ext/pty/pty.c | 97 ++++++++++++++++++++++++++++++++++++--------------- 2 files changed, 72 insertions(+), 28 deletions(-) create mode 100644 ext/pty/README.rdoc diff --git a/ext/pty/README.rdoc b/ext/pty/README.rdoc new file mode 100644 index 0000000..82e1514 --- /dev/null +++ b/ext/pty/README.rdoc @@ -0,0 +1,3 @@ +Code useful for creating and managing PTYs[http://en.wikipedia.org/wiki/Pseudo_terminal] + +See PTY for more info diff --git a/ext/pty/pty.c b/ext/pty/pty.c index 0c9f37e..5e48037 100644 --- a/ext/pty/pty.c +++ b/ext/pty/pty.c @@ -120,8 +120,11 @@ char MasterDevice[] = "/dev/pty%s", # endif /* HAVE_SETREUID */ #endif /* NO_SETEUID */ -static VALUE eChildExited; +static VALUE eChildExited; +/* Returns the exit status of the child for which PTY#check + * raised this exception + */ static VALUE echild_status(VALUE self) { @@ -133,6 +136,12 @@ struct pty_info { rb_pid_t child_pid; }; +/** + * Document-class: PTY + * + * Creates and managed pseudo terminals (ptys). + */ + static void getDevice(int*, int*, char [DEVICELEN], int); struct child_info { @@ -433,15 +442,20 @@ pty_close_pty(VALUE assoc) * * 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. + * In the non-block form, returns a two element array, [master_io,slave_file]. * - * 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. + * In the block form, yields two arguments |master_io,slave_file| + * and the value of the block is returned from +open+. + * The arguments are both closed after the block completes if + * they haven't been already closed. * - * The path name of the terminal device can be gotten by slave_file.path. + * The arguments in both forms are: + * + * 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 + * + * === Example * * PTY.open {|m, s| * p m #=> # @@ -513,24 +527,34 @@ pty_detach_process(struct pty_info *info) /* * call-seq: - * PTY.spawn(command...) {|r, w, pid| ... } => nil - * PTY.spawn(command...) => r, w, pid - * PTY.getpty(command...) {|r, w, pid| ... } => nil - * PTY.getpty(command...) => r, w, pid - * - * spawns the specified command on a newly allocated pty. + * 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] * - * The command's controlling tty is set to the slave device of the pty. - * Also its standard input/output/error is redirected to the slave device. + * Spawns the specified command on a newly allocated pty. * - * PTY.spawn returns two IO objects and PID. - * PID is the process ID of the command. - * The two IO objects are connected to the master device of the pty. - * The first IO object is opened as read mode and - * The second is opened as write mode. + * 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. * - * If a block is given, two IO objects and PID is yielded. + * 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+ + * + * In the non-block form, this returns an array of size three + * [r,w,pid]. In the block form, the block will be given + * these as arguments, |r,w,pid|: * + * +r+:: an IO that can be read from 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 + * +pid+:: a process identifier for the command. */ static VALUE pty_getpty(int argc, VALUE *argv, VALUE self) @@ -599,12 +623,19 @@ raise_from_check(pid_t pid, int status) /* * call-seq: - * PTY.check(pid[, raise=false]) => Process::Status or nil + * PTY.check(pid) => Process::Status or nil + * PTY.check(pid,true) => nil or raises PTY::ChildExited * - * 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. + * 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). + * + * +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. + * + * Returns nil or a Process::Status. */ static VALUE pty_check(int argc, VALUE *argv, VALUE self) @@ -619,11 +650,21 @@ pty_check(int argc, VALUE *argv, VALUE self) if (!RTEST(exc)) return rb_last_status_get(); raise_from_check(cpid, status); - return Qnil; /* not reached */ + return Qnil; } static VALUE cPTY; +// Since this is the last comment, it gets used by default for +// classes with no docs, and I can't seem to give ChildExited +// an explicit doc, so this hack seems to work. +/** + * Thrown when PTY#check is called for a pid + * that represents a process that has exited. + */ + + + void Init_pty() { -- 1.7.3.4