Module: PTY

Defined in:
pty.c

Defined Under Namespace

Classes: ChildExited

Class Method Summary collapse

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:



671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
 
# File 'pty.c', line 671

static VALUE
pty_check(int argc, VALUE *argv, VALUE self)
{
    VALUE pid, exc;
    rb_pid_t cpid;
    int status;

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

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

    UNREACHABLE;
}

.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) 


587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
 
# File 'pty.c', line 587

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 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.

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) 


517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
 
# File 'pty.c', line 517

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) 


587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
 
# File 'pty.c', line 587

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;
}