Shell
=====

A high-level interface to a remote shell built upon (ssh popen) API. The procedures described in this section uses GNU Coreutils on the remote side and may depend on some other packages; see the notes for each procedure.

 -- Scheme Procedure: rexec session command
     Execute a COMMAND on the remote side.  Return two values: list of output lines returned by a COMMAND and its exit code.

 -- Scheme Procedure: which session program-name
     Check if a PROGRAM-NAME is available on a remote side.  Return two values: a path to a command if it is found and a return code.

     The procedure uses shell build-in command which on the remote side.

     Example:

          (use-modules (ssh session)
                       (ssh auth)
                       (ssh shell))

          (let ((s (make-session #:host "example.org")))
            (connect! s)
            (userauth-agent! s)
            (which s "guile"))
          => ("/usr/bin/guile")
          => 0

 -- Scheme Procedure: command-available? session command
     Check if a COMMAND is available on a remote machine represented by a SESSION.

 -- Scheme Procedure: pgrep session pattern
     [#:full?=#f]
     [#:use-guile?=#f]
     Search for a process with a PATTERN cmdline on a machine represented by a SESSION.  Return two values: a list of PIDs and a return code.

     The procedure uses a pgrep from procps package on the remote side when USE-GUILE? is set to #f (this is by default.)

     When USE-GUILE? is set to #t, the procedure will execute a Scheme code using GNU Guile on the remote side to kill processes.

 -- Scheme Procedure: pkill session pattern
     [#:full?=#f]
     [#:signal=SIGTERM]
     [#:use-guile?=#f]

     Send a SIGNAL to a process which name matches to PATTERN on a remote machine represented by a SESSION. Return two values: a list of PIDs of killed processes and a return code.

     The SIGNAL must be a numeric value as for Guile kill procedure.

     The procedure uses a pkill from procps package on the remote side when USE-GUILE? is set to #f (this is by default.)

     When USE-GUILE? is set to #t, the procedure will execute a Scheme code using GNU Guile on the remote side to kill processes.

 -- Scheme Procedure: loadavg session
     Get average load of a host using a SESSION.  Return a list of five elements as described in proc(5) man page.

     Example:

          (use-modules (ssh session)
                       (ssh auth)
                       (ssh shell))

          (let ((s (make-session #:host "example.org")))
            (connect! s)
            (userauth-agent! s)
            (loadavg s))
          => ("0.01" "0.05" "0.10" "4/1927" "242011")