Class: Net::SSH::Process::Status

Inherits:
Object
  • Object
show all
Defined in:
lib/net-ssh-open3.rb

Overview

Encapsulates the information on the status of remote process, similar to ::Process::Status.

Note that it’s impossible to retrieve PID (process ID) via an SSH channel (thus impossible to properly signal it).

Although RFC4254 allows sending signals to the process (see tools.ietf.org/html/rfc4254#section-6.9), current OpenSSH server implementation does not support this feature, though there are some patches: bugzilla.mindrot.org/show_bug.cgi?id=1424 and marc.info/?l=openssh-unix-dev&m=104300802407848&w=2

As a workaround one can request a PTY and send SIGINT or SIGQUIT via ^C, ^\ or other sequences, see ‘pty’ option in Net::SSH::Open3 for more information.

Open3 prepends your command with ‘echo $$; ’ which will echo PID of your process, then intercepts this line from STDOUT.

Instance Attribute Summary collapse

Instance Method Summary collapse

Instance Attribute Details

#exitstatus ⇒ Object (readonly)

Integer exit code in range 0..255, 0 usually meaning success. Assigned only if the process has exited normally (i.e. not by a signal). More information about standard exit codes: tldp.org/LDP/abs/html/exitcodes.html



34
35
36
 
# File 'lib/net-ssh-open3.rb', line 34

def exitstatus
  @exitstatus
end

#pid ⇒ Object (readonly)

Process ID of a remote command interpreter or a remote process. See note on Net::SSH::Process::Status class for more information on how this is fetched. false if PID fetching was disabled.



39
40
41
 
# File 'lib/net-ssh-open3.rb', line 39

def pid
  @pid
end

Instance Method Details

#active? ⇒ Boolean

true if the process is still running (actually if we haven’t received it’s exit status or signal).

Returns:

  • (Boolean) 


69
70
71
 
# File 'lib/net-ssh-open3.rb', line 69

def active?
  not (exited? or signaled?)
end

#coredump? ⇒ Boolean

true when process has been killed by a signal and a core dump has been generated for it.

Returns:

  • (Boolean) 


42
43
44
 
# File 'lib/net-ssh-open3.rb', line 42

def coredump?
  @coredump
end

#exited? ⇒ Boolean

true if the process has exited normally and returned an exit code.

Returns:

  • (Boolean) 


59
60
61
 
# File 'lib/net-ssh-open3.rb', line 59

def exited?
  !!@exitstatus
end

#inspect ⇒ Object

Inspect this instance.



95
96
97
 
# File 'lib/net-ssh-open3.rb', line 95

def inspect
  "#<#{self.class}: #{to_s}>"
end

#signaled? ⇒ Boolean

true if the process has been killed by a signal.

Returns:

  • (Boolean) 


64
65
66
 
# File 'lib/net-ssh-open3.rb', line 64

def signaled?
  !!@termsig
end

#success? ⇒ Boolean

Returns true if the process has exited with code 0, false for other codes and nil if killed by a signal.

Returns:

  • (Boolean) 


74
75
76
 
# File 'lib/net-ssh-open3.rb', line 74

def success?
  exited? ? exitstatus == 0 : nil
end

#termsig ⇒ Object

Integer representation of a signal that killed a process, if available.

Translated to local system (so you can use Signal.list to map it to String). Explanation: when local system is Linux (USR1=10) and remote is FreeBSD (USR1=30), 10 will be returned in case remote process receives USR1 (30).

Not all signal names are delivered by ssh: for example, SIGTRAP is delivered as “[email protected]” and therefore may not be translated. Returns String in this case.



54
55
56
 
# File 'lib/net-ssh-open3.rb', line 54

def termsig
  Signal.list[@termsig] || @termsig
end

#to_s ⇒ Object

String representation of exit status.



79
80
81
82
83
84
85
86
87
88
89
90
91
92
 
# File 'lib/net-ssh-open3.rb', line 79

def to_s
  if @pid != nil
    "pid #@pid " <<
    if exited?
      "exit #@exitstatus"
    elsif signaled?
      "#@termsig (signal #{termsig}) core #@coredump"
    else
      'active'
    end
  else
    'uninitialized'
  end
end