Module: PTY

Defined in:

pty.c

Defined Under Namespace

Classes: ChildExited

Class Method Summary

• .check(*args) ⇒ Object

  Checks the status of the child process specified by pid.

• .getpty(*args) ⇒ Object

  Spawns the specified command on a newly allocated pty.

• .open ⇒ Object

  Allocates a pty (pseudo-terminal).

• .spawn(*args) ⇒ Object

  Spawns the specified command on a newly allocated pty.

Class Method Details

.check(pid, raise = false) ⇒ Process::Status^? .check(pid, true) ⇒ nil, 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, 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.

Overloads:

• .check(pid, raise = false) ⇒ Process::Status^?

  Returns:

  • (Process::Status, nil)
• .check(pid, true) ⇒ nil, raises PTY::ChildExited

  Returns:

  • (nil, raises PTY::ChildExited)

# File 'pty.c', line 659

static VALUE
pty_check(int argc, VALUE *argv, VALUE self)
{
    VALUE pid, exc;
    rb_pid_t cpid;
    int status;
    const int flag =
#ifdef WNOHANG
	WNOHANG|
#endif
#ifdef WUNTRACED
	WUNTRACED|
#endif
	0;

    rb_scan_args(argc, argv, "11", &pid, &exc);
    cpid = rb_waitpid(NUM2PIDT(pid), &status, flag);
    if (cpid == -1 || cpid == 0) return Qnil;

    if (!RTEST(exc)) return rb_last_status_get();
    raise_from_check(cpid, status);

    UNREACHABLE_RETURN(Qnil);
}

.spawn(command_line) {|r, w, pid| ... } ⇒ Object .spawn(command_line) ⇒ Array .spawn(command, arguments, ...) {|r, w, pid| ... } ⇒ Object .spawn(command, arguments, ...) ⇒ Array

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 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 these same values will be yielded to the block:

r

A readable IO that contains the command’s standard output and standard error

w

A writable IO that is the command’s standard input

pid

The process identifier for the command.

Overloads:

• .spawn(command_line) {|r, w, pid| ... } ⇒ Object

  Yields:

  • (r, w, pid)
• .spawn(command_line) ⇒ Array

  Returns:

  • (Array)
• .spawn(command, arguments, ...) {|r, w, pid| ... } ⇒ Object

  Yields:

  • (r, w, pid)
• .spawn(command, arguments, ...) ⇒ Array

  Returns:

  • (Array)

# File 'pty.c', line 575

static VALUE
pty_getpty(int argc, VALUE *argv, VALUE self)
{
    VALUE res;
    struct pty_info info;
    rb_io_t *wfptr,*rfptr;
    VALUE rport = rb_obj_alloc(rb_cFile);
    VALUE wport = rb_obj_alloc(rb_cFile);
    char SlaveName[DEVICELEN];

    MakeOpenFile(rport, rfptr);
    MakeOpenFile(wport, wfptr);

    establishShell(argc, argv, &info, SlaveName);

    rfptr->mode = rb_io_modestr_fmode("r");
    rfptr->fd = info.fd;
    rfptr->pathv = rb_obj_freeze(rb_str_new_cstr(SlaveName));

    wfptr->mode = rb_io_modestr_fmode("w") | FMODE_SYNC;
    wfptr->fd = rb_cloexec_dup(info.fd);
    if (wfptr->fd == -1)
        rb_sys_fail("dup()");
    rb_update_max_fd(wfptr->fd);
    wfptr->pathv = rfptr->pathv;

    res = rb_ary_new2(3);
    rb_ary_store(res,0,(VALUE)rport);
    rb_ary_store(res,1,(VALUE)wport);
    rb_ary_store(res,2,PIDT2NUM(info.child_pid));

    if (rb_block_given_p()) {
	rb_ensure(rb_yield, res, pty_detach_process, (VALUE)&info);
	return Qnil;
    }
    return res;
}

.open ⇒ Array .open {|(master_io, slave_file)| ... } ⇒ Object

Allocates a pty (pseudo-terminal).

In the block form, yields an array of two elements (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.

PTY.open {|master, slave|
  p master      #=> #<IO:masterpty:/dev/pts/1>
  p slave      #=> #<File:/dev/pts/1>
  p slave.path #=> "/dev/pts/1"
}

In the non-block form, returns a two element array, [master_io, slave_file].

master, slave = PTY.open
# do something with master for IO, or the slave file

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

IO#raw! is usable to disable newline conversions:

require 'io/console'
PTY.open {|m, s|
  s.raw!
  ...
}

Overloads:

• .open ⇒ Array

  Returns:

  • (Array)
• .open {|(master_io, slave_file)| ... } ⇒ Object

  Yields:

  • ((master_io, slave_file))

# File 'pty.c', line 504

static VALUE
pty_open(VALUE klass)
{
    int master_fd, slave_fd;
    char slavename[DEVICELEN];
    VALUE master_io, slave_file;
    rb_io_t *master_fptr, *slave_fptr;
    VALUE assoc;

    getDevice(&master_fd, &slave_fd, slavename, 1);

    master_io = rb_obj_alloc(rb_cIO);
    MakeOpenFile(master_io, master_fptr);
    master_fptr->mode = FMODE_READWRITE | FMODE_SYNC | FMODE_DUPLEX;
    master_fptr->fd = master_fd;
    master_fptr->pathv = rb_obj_freeze(rb_sprintf("masterpty:%s", slavename));

    slave_file = rb_obj_alloc(rb_cFile);
    MakeOpenFile(slave_file, slave_fptr);
    slave_fptr->mode = FMODE_READWRITE | FMODE_SYNC | FMODE_DUPLEX | FMODE_TTY;
    slave_fptr->fd = slave_fd;
    slave_fptr->pathv = rb_obj_freeze(rb_str_new_cstr(slavename));

    assoc = rb_assoc_new(master_io, slave_file);
    if (rb_block_given_p()) {
	return rb_ensure(rb_yield, assoc, pty_close_pty, assoc);
    }
    return assoc;
}

.spawn(command_line) {|r, w, pid| ... } ⇒ Object .spawn(command_line) ⇒ Array .spawn(command, arguments, ...) {|r, w, pid| ... } ⇒ Object .spawn(command, arguments, ...) ⇒ Array

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 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 these same values will be yielded to the block:

r

A readable IO that contains the command’s standard output and standard error

w

A writable IO that is the command’s standard input

pid

The process identifier for the command.

Overloads:

• .spawn(command_line) {|r, w, pid| ... } ⇒ Object

  Yields:

  • (r, w, pid)
• .spawn(command_line) ⇒ Array

  Returns:

  • (Array)
• .spawn(command, arguments, ...) {|r, w, pid| ... } ⇒ Object

  Yields:

  • (r, w, pid)
• .spawn(command, arguments, ...) ⇒ Array

  Returns:

  • (Array)

# File 'pty.c', line 575

static VALUE
pty_getpty(int argc, VALUE *argv, VALUE self)
{
    VALUE res;
    struct pty_info info;
    rb_io_t *wfptr,*rfptr;
    VALUE rport = rb_obj_alloc(rb_cFile);
    VALUE wport = rb_obj_alloc(rb_cFile);
    char SlaveName[DEVICELEN];

    MakeOpenFile(rport, rfptr);
    MakeOpenFile(wport, wfptr);

    establishShell(argc, argv, &info, SlaveName);

    rfptr->mode = rb_io_modestr_fmode("r");
    rfptr->fd = info.fd;
    rfptr->pathv = rb_obj_freeze(rb_str_new_cstr(SlaveName));

    wfptr->mode = rb_io_modestr_fmode("w") | FMODE_SYNC;
    wfptr->fd = rb_cloexec_dup(info.fd);
    if (wfptr->fd == -1)
        rb_sys_fail("dup()");
    rb_update_max_fd(wfptr->fd);
    wfptr->pathv = rfptr->pathv;

    res = rb_ary_new2(3);
    rb_ary_store(res,0,(VALUE)rport);
    rb_ary_store(res,1,(VALUE)wport);
    rb_ary_store(res,2,PIDT2NUM(info.child_pid));

    if (rb_block_given_p()) {
	rb_ensure(rb_yield, res, pty_detach_process, (VALUE)&info);
	return Qnil;
    }
    return res;
}