| 1 | #!/usr/bin/env perl | ||||||||||||||||||||||||||||
| 2 | # vim: fdm=marker sw=4 et | ||||||||||||||||||||||||||||
| 3 | # Documentation head {{{ | ||||||||||||||||||||||||||||
| 4 | |||||||||||||||||||||||||||||
| 5 | =head1 NAME | ||||||||||||||||||||||||||||
| 6 | |||||||||||||||||||||||||||||
| 7 | IO::Pty::HalfDuplex::JobControl - the default backend of IO::Pty::HalfDuplex | ||||||||||||||||||||||||||||
| 8 | |||||||||||||||||||||||||||||
| 9 | =head1 SYNOPSIS | ||||||||||||||||||||||||||||
| 10 | |||||||||||||||||||||||||||||
| 11 | IO::Pty::HalfDuplex->new(backend => 'JobControl') | ||||||||||||||||||||||||||||
| 12 | |||||||||||||||||||||||||||||
| 13 | =head1 CAVEATS | ||||||||||||||||||||||||||||
| 14 | |||||||||||||||||||||||||||||
| 15 | C<IO::Pty::HalfDuplex::JobControl> is implemented using POSIX job control, and | ||||||||||||||||||||||||||||
| 16 | as such it requires foreground access to a controlling terminal. Programs | ||||||||||||||||||||||||||||
| 17 | which interfere with process hierarchies, such as C<strace -f>, will break | ||||||||||||||||||||||||||||
| 18 | C<IO::Pty::HalfDuplex::JobControl>. | ||||||||||||||||||||||||||||
| 19 | |||||||||||||||||||||||||||||
| 20 | Certain ioctls used by terminal-aware programs are treated as reads by POSIX | ||||||||||||||||||||||||||||
| 21 | job control. If this is done while the input buffer is empty, it may cause a | ||||||||||||||||||||||||||||
| 22 | spurious stop by C<IO::Pty::HalfDuplex::JobControl>. Under normal | ||||||||||||||||||||||||||||
| 23 | circumstances this manifests as a need to transmit at least one character | ||||||||||||||||||||||||||||
| 24 | before the starting screen is displayed. | ||||||||||||||||||||||||||||
| 25 | |||||||||||||||||||||||||||||
| 26 | C<IO::Pty::HalfDuplex::JobControl> relies on a forked-but-not-execed process to | ||||||||||||||||||||||||||||
| 27 | mediate job control, and as such any files open at spawn time will be closed | ||||||||||||||||||||||||||||
| 28 | until the slave is killed. | ||||||||||||||||||||||||||||
| 29 | |||||||||||||||||||||||||||||
| 30 | C<IO::Pty::HalfDuplex::JobControl> sends many continue signals to the slave | ||||||||||||||||||||||||||||
| 31 | process. If the slave catches SIGCONT, you may see many spurious redraws. If | ||||||||||||||||||||||||||||
| 32 | possible, modify your child to handle SIGTSTP instead. | ||||||||||||||||||||||||||||
| 33 | |||||||||||||||||||||||||||||
| 34 | While this module will theoretically work on any POSIX.1 compliant operating | ||||||||||||||||||||||||||||
| 35 | system, in practice it exercises many dark corners and has required | ||||||||||||||||||||||||||||
| 36 | bug-workaround code everywhere it has been tested. It is known to work on | ||||||||||||||||||||||||||||
| 37 | Mac OS 10.5.7 and Linux 2.6.16. On FreeBSD 7.0 it passes tests but is | ||||||||||||||||||||||||||||
| 38 | extremely slow due to a kernel bug with no obvious workaround. | ||||||||||||||||||||||||||||
| 39 | |||||||||||||||||||||||||||||
| 40 | =head1 BUGS | ||||||||||||||||||||||||||||
| 41 | |||||||||||||||||||||||||||||
| 42 | See L<IO::Pty::HalfDuplex>. | ||||||||||||||||||||||||||||
| 43 | |||||||||||||||||||||||||||||
| 44 | =head1 COPYRIGHT AND LICENSE | ||||||||||||||||||||||||||||
| 45 | |||||||||||||||||||||||||||||
| 46 | Copyright 2008-2009 Stefan O'Rear. | ||||||||||||||||||||||||||||
| 47 | |||||||||||||||||||||||||||||
| 48 | This program is free software; you can redistribute it and/or modify it | ||||||||||||||||||||||||||||
| 49 | under the same terms as Perl itself. | ||||||||||||||||||||||||||||
| 50 | |||||||||||||||||||||||||||||
| 51 | =cut | ||||||||||||||||||||||||||||
| 52 | |||||||||||||||||||||||||||||
| 53 | # }}} | ||||||||||||||||||||||||||||
| 54 | # header {{{ | ||||||||||||||||||||||||||||
| 55 | # This code pretends to be a shell to the operating system, and as such needs | ||||||||||||||||||||||||||||
| 56 | # to run in a separate process, inside the pty. The stub code doesn't have | ||||||||||||||||||||||||||||
| 57 | # to manipulate the pty at all, luckily. | ||||||||||||||||||||||||||||
| 58 | |||||||||||||||||||||||||||||
| 59 | # XXX Running this in a forked process holds all cloexec file descriptors open. | ||||||||||||||||||||||||||||
| 60 | |||||||||||||||||||||||||||||
| 61 | package IO::Pty::HalfDuplex::JobControl; | ||||||||||||||||||||||||||||
| 62 | |||||||||||||||||||||||||||||
| 63 | 4 | ▶ | use strict; | ||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||
| 64 | 4 | ▶ | use warnings; | ||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||
| 65 | |||||||||||||||||||||||||||||
| 66 | 4 | ▶ | use base 'IO::Pty::HalfDuplex::Ptyish'; | ||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||
| 67 | |||||||||||||||||||||||||||||
| 68 | 4 | ▶ | use POSIX qw(:signal_h :sys_wait_h :termios_h :unistd_h); | ||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||
| 69 | 4 | my $need_bsd_hack = ($^O =~ /bsd|darwin/i); | |||||||||||||||||||||||||||
| 70 | |||||||||||||||||||||||||||||
| 71 | # }}} | ||||||||||||||||||||||||||||
| 72 | # do_wait {{{ | ||||||||||||||||||||||||||||
| 73 | # Properly wait for the child; does not return (and emits d-code) on exit | ||||||||||||||||||||||||||||
| 74 | 0 | ▶ | sub _do_wait { | ||||||||||||||||||||||||||
|
Subroutine
_do_wait: not called CC=8 SCAR=42.8
| |||||||||||||||||||||||||||||
| 75 | 0 | my $self = shift; | |||||||||||||||||||||||||||
| 76 | |||||||||||||||||||||||||||||
| 77 | waitpid($self->{slave_pid}, WUNTRACED) == $self->{slave_pid} | ||||||||||||||||||||||||||||
| 78 | 0 | ▶ | or die "waitpid: $!"; | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 79 | |||||||||||||||||||||||||||||
| 80 | # Older Perls (<= 5.8.8) put all status codes into $?. Newer ones | ||||||||||||||||||||||||||||
| 81 | # will only put exits there, and signals go elsewhere. Argh. | ||||||||||||||||||||||||||||
| 82 | 0 | ▶ | my $stat = ${^CHILD_ERROR_NATIVE} || $?; | ||||||||||||||||||||||||||
|
Condition0%0/3
${^CHILD_ERROR_NATIVE} || $?
MC/DC0%0/2
${^CHILD_ERROR_NATIVE} || $?
${^CHILD_ERROR_NATIVE}
$?
Truth table0%0/3
A || B
A= ${^CHILD_ERROR_NATIVE}B= $?
| |||||||||||||||||||||||||||||
| 83 | |||||||||||||||||||||||||||||
| 84 | 0 | ▶ | if (WIFEXITED($stat) || WIFSIGNALED($stat)) { | ||||||||||||||||||||||||||
|
Branch: 1 branch
Condition0%0/3
WIFEXITED($stat) or WIFSIGNALED($stat)
MC/DC0%0/2
WIFEXITED($stat) or WIFSIGNALED($stat)
WIFEXITED($stat)
WIFSIGNALED($stat)
Truth table0%0/3
A or B
A= WIFEXITED($stat)B= WIFSIGNALED($stat)
| |||||||||||||||||||||||||||||
| 85 | 0 | ▶ | syswrite $self->{info_pipe}, "d" . | ||||||||||||||||||||||||||
|
Branch: 2 branches
| |||||||||||||||||||||||||||||
| 86 | chr(WIFSIGNALED($stat) ? WTERMSIG($stat) : 0) . | ||||||||||||||||||||||||||||
| 87 | chr(WIFEXITED($stat) ? WEXITSTATUS($stat) : 0); | ||||||||||||||||||||||||||||
| 88 | |||||||||||||||||||||||||||||
| 89 | # We got here by a fork, so we certainly have stale buffers | ||||||||||||||||||||||||||||
| 90 | 0 | _exit 0; | |||||||||||||||||||||||||||
| 91 | } | ||||||||||||||||||||||||||||
| 92 | |||||||||||||||||||||||||||||
| 93 | 0 | ▶ | die "POSIX.1 says this can't happen" if !WIFSTOPPED($stat); | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 94 | } | ||||||||||||||||||||||||||||
| 95 | # }}} | ||||||||||||||||||||||||||||
| 96 | # try_step {{{ | ||||||||||||||||||||||||||||
| 97 | # Try once to get the slave to process input. Returns true if successful. | ||||||||||||||||||||||||||||
| 98 | # The slave _will_ be stopped(TTIN) on entry to this function. | ||||||||||||||||||||||||||||
| 99 | 0 | ▶ | sub _try_step_slave { | ||||||||||||||||||||||||||
|
Subroutine
_try_step_slave: not called CC=3 SCAR=24.8
| |||||||||||||||||||||||||||||
| 100 | 0 | my ($self, $lag) = @_; | |||||||||||||||||||||||||||
| 101 | |||||||||||||||||||||||||||||
| 102 | # Put the process into the foreground so it can read input | ||||||||||||||||||||||||||||
| 103 | 0 | tcsetpgrp(0, $self->{slave_pid}); | |||||||||||||||||||||||||||
| 104 | 0 | kill -(SIGCONT), $self->{slave_pid}; | |||||||||||||||||||||||||||
| 105 | |||||||||||||||||||||||||||||
| 106 | # Force a context switch | ||||||||||||||||||||||||||||
| 107 | 0 | select undef, undef, undef, $lag; | |||||||||||||||||||||||||||
| 108 | |||||||||||||||||||||||||||||
| 109 | # Stop it so it can be put in the background | ||||||||||||||||||||||||||||
| 110 | 0 | kill -(SIGSTOP), $self->{slave_pid}; | |||||||||||||||||||||||||||
| 111 | 0 | $self->_do_wait; | |||||||||||||||||||||||||||
| 112 | |||||||||||||||||||||||||||||
| 113 | # Now put it there | ||||||||||||||||||||||||||||
| 114 | 0 | tcsetpgrp(0, $self->{pid}); | |||||||||||||||||||||||||||
| 115 | 0 | kill -(SIGCONT), $self->{slave_pid}; | |||||||||||||||||||||||||||
| 116 | |||||||||||||||||||||||||||||
| 117 | # If the process was not in the tty driver, it's now on its way to | ||||||||||||||||||||||||||||
| 118 | # stopping. If it was, and you're on Linux, it will transition to T | ||||||||||||||||||||||||||||
| 119 | # automatically. On BSDs it needs a bit of an extra kick, because | ||||||||||||||||||||||||||||
| 120 | # even tcsetpgrp, sigstop, and sigcont won't interrupt a tty wait. | ||||||||||||||||||||||||||||
| 121 | # | ||||||||||||||||||||||||||||
| 122 | # Insidiously, this doesn't manifest in the shell because typing "bg" | ||||||||||||||||||||||||||||
| 123 | # kicks all processes waiting on the tty wchan. | ||||||||||||||||||||||||||||
| 124 | # | ||||||||||||||||||||||||||||
| 125 | # This is the best non-destructive way I could find. Requires three | ||||||||||||||||||||||||||||
| 126 | # system calls, grr. | ||||||||||||||||||||||||||||
| 127 | 0 | ▶ | if ($need_bsd_hack) { | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 128 | 0 | my $attr = POSIX::Termios->new; | |||||||||||||||||||||||||||
| 129 | 0 | $attr->getattr(0); | |||||||||||||||||||||||||||
| 130 | 0 | $attr->setcc(&POSIX::VMIN, $attr->getcc(&POSIX::VMIN) + 1); | |||||||||||||||||||||||||||
| 131 | 0 | $attr->setattr(0, &POSIX::TCSANOW); | |||||||||||||||||||||||||||
| 132 | 0 | $attr->setcc(&POSIX::VMIN, $attr->getcc(&POSIX::VMIN) - 1); | |||||||||||||||||||||||||||
| 133 | 0 | $attr->setattr(0, &POSIX::TCSANOW); | |||||||||||||||||||||||||||
| 134 | } | ||||||||||||||||||||||||||||
| 135 | |||||||||||||||||||||||||||||
| 136 | # Wait until it blocks on input | ||||||||||||||||||||||||||||
| 137 | 0 | $self->_do_wait; | |||||||||||||||||||||||||||
| 138 | |||||||||||||||||||||||||||||
| 139 | # Slave has stopped on tty input. Hopefully, it's read and processed | ||||||||||||||||||||||||||||
| 140 | # everything and we can send the over; but it could also just have taken a | ||||||||||||||||||||||||||||
| 141 | # long time to read and outwaited out feeding sleep. | ||||||||||||||||||||||||||||
| 142 | # | ||||||||||||||||||||||||||||
| 143 | # We can tell the difference by seeing if there is readable data. Note | ||||||||||||||||||||||||||||
| 144 | # that in ICANON mode, it is possible for there to be unreadable data. | ||||||||||||||||||||||||||||
| 145 | # That's OK, since it's equally unreadable to both of us. | ||||||||||||||||||||||||||||
| 146 | 0 | my $rin = ''; | |||||||||||||||||||||||||||
| 147 | 0 | vec($rin, 0, 1) = 1; | |||||||||||||||||||||||||||
| 148 | 0 | ▶ | return select($rin, undef, undef, 0) ? 0 : 1; | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 149 | } | ||||||||||||||||||||||||||||
| 150 | # }}} | ||||||||||||||||||||||||||||
| 151 | # control loop and startup {{{ | ||||||||||||||||||||||||||||
| 152 | # Wait for, and process, commands | ||||||||||||||||||||||||||||
| 153 | 0 | ▶ | sub _shell_loop { | ||||||||||||||||||||||||||
|
Subroutine
_shell_loop: not called CC=4 SCAR=30.0
| |||||||||||||||||||||||||||||
| 154 | 0 | my $self = shift; | |||||||||||||||||||||||||||
| 155 | |||||||||||||||||||||||||||||
| 156 | 0 | while(1) { | |||||||||||||||||||||||||||
| 157 | 0 | my $buf = ''; | |||||||||||||||||||||||||||
| 158 | 0 | ▶ | sysread($self->{ctl_pipe}, $buf, 1) > 0 or die "read(ctl): $!"; | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 159 | |||||||||||||||||||||||||||||
| 160 | # BSD adds a 0.5 second delay to every time a process reads while | ||||||||||||||||||||||||||||
| 161 | # in the background. This is a real problem for us, so minimize | ||||||||||||||||||||||||||||
| 162 | # needed read attempts. | ||||||||||||||||||||||||||||
| 163 | 0 | ▶ | for (my $lag = ($need_bsd_hack ? 0.15 : 0.02); | ||||||||||||||||||||||||||
|
Branch: 2 branches
| |||||||||||||||||||||||||||||
| 164 | !$self->_try_step_slave($lag); $lag *= 1.5) {} | ||||||||||||||||||||||||||||
| 165 | 0 | syswrite($self->{info_pipe}, "r"); | |||||||||||||||||||||||||||
| 166 | } | ||||||||||||||||||||||||||||
| 167 | } | ||||||||||||||||||||||||||||
| 168 | |||||||||||||||||||||||||||||
| 169 | # This routine is responsible for creating the proper environment for the | ||||||||||||||||||||||||||||
| 170 | # slave to run in. | ||||||||||||||||||||||||||||
| 171 | 2 | ▶ | sub _shell_spawn { | ||||||||||||||||||||||||||
|
Subroutine
_shell_spawn: called CC=3 SCAR=12.2
| |||||||||||||||||||||||||||||
| 172 | 2 | my $self = shift; | |||||||||||||||||||||||||||
| 173 | |||||||||||||||||||||||||||||
| 174 | 2 | ▶ | die "fork: $!" unless defined ($self->{slave_pid} = fork); | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 175 | |||||||||||||||||||||||||||||
| 176 | 2 | ▶ | unless($self->{slave_pid}) { | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 177 | # The child process to be. Force it to start as a process leader | ||||||||||||||||||||||||||||
| 178 | # in the background. | ||||||||||||||||||||||||||||
| 179 | 2 | $self->{slave_pid} = $$; | |||||||||||||||||||||||||||
| 180 | 2 | setpgrp($self->{slave_pid}, $self->{slave_pid}); | |||||||||||||||||||||||||||
| 181 | # Make sure the important job control signals aren't ignored | ||||||||||||||||||||||||||||
| 182 | 2 | $SIG{CHLD} = $SIG{TTIN} = $SIG{TSTP} = $SIG{CONT} = 'DEFAULT'; | |||||||||||||||||||||||||||
| 183 | 2 | kill SIGSTOP, $self->{slave_pid}; | |||||||||||||||||||||||||||
| 184 | |||||||||||||||||||||||||||||
| 185 | 2 | exec(@{$self->{command}}); | |||||||||||||||||||||||||||
| 186 | 0 | die "exec: $!"; | |||||||||||||||||||||||||||
| 187 | } | ||||||||||||||||||||||||||||
| 188 | |||||||||||||||||||||||||||||
| 189 | 0 | syswrite($self->{info_pipe}, pack('N', $self->{slave_pid})); | |||||||||||||||||||||||||||
| 190 | |||||||||||||||||||||||||||||
| 191 | 0 | setpgrp($self->{slave_pid}, $self->{slave_pid}); | |||||||||||||||||||||||||||
| 192 | |||||||||||||||||||||||||||||
| 193 | # It simplifies the API if the child can be assumed to start stopped | ||||||||||||||||||||||||||||
| 194 | 0 | $self->_do_wait; | |||||||||||||||||||||||||||
| 195 | } | ||||||||||||||||||||||||||||
| 196 | |||||||||||||||||||||||||||||
| 197 | 2 | ▶ | sub _shell { | ||||||||||||||||||||||||||
|
Subroutine
_shell: called CC=1 SCAR=0.1
| |||||||||||||||||||||||||||||
| 198 | 2 | my $self = shift; | |||||||||||||||||||||||||||
| 199 | 2 | %$self = ( | |||||||||||||||||||||||||||
| 200 | %$self, | ||||||||||||||||||||||||||||
| 201 | pid => $$, | ||||||||||||||||||||||||||||
| 202 | @_ | ||||||||||||||||||||||||||||
| 203 | ); | ||||||||||||||||||||||||||||
| 204 | |||||||||||||||||||||||||||||
| 205 | # disable tostop, also allows tcsetpgrp stealing | ||||||||||||||||||||||||||||
| 206 | 2 | $SIG{TTOU} = 'IGNORE'; | |||||||||||||||||||||||||||
| 207 | |||||||||||||||||||||||||||||
| 208 | 2 | $self->_shell_spawn(); | |||||||||||||||||||||||||||
| 209 | 0 | $self->_shell_loop(); | |||||||||||||||||||||||||||
| 210 | } | ||||||||||||||||||||||||||||
| 211 | 4 | 1; | |||||||||||||||||||||||||||
| 212 | # }}} | ||||||||||||||||||||||||||||