@c -*-texinfo-*-
@c This file is part of Guile-SSH Reference Manual.
@c Copyright (C) 2017 Artyom V. Poptsov
@c See the file guile-ssh.texi for copying conditions.

@node Shell
@section Shell

@cindex secure shell

A high-level interface to a remote shell built upon @code{(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.

@deffn {Scheme Procedure} rexec session command
Execute a @var{command} on the remote side.  Return two values: list of output
lines returned by a @var{command} and its exit code.
@end deffn

@deffn {Scheme Procedure} which session program-name
Check if a @var{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 @command{which} on the remote side.

Example:

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

(let ((s (make-session #:host "example.org")))
  (connect! s)
  (userauth-agent! s)
  (which s "guile"))
@result{} ("/usr/bin/guile")
@result{} 0
@end lisp

@end deffn

@deffn {Scheme Procedure} command-available? session command
Check if a @var{command} is available on a remote machine represented by a
@var{session}.
@end deffn

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

The procedure uses a @command{pgrep} from procps package on the remote side
when @var{use-guile?} is set to @code{#f} (this is by default.)

When @var{use-guile?} is set to @code{#t}, the procedure will execute a Scheme
code using GNU Guile on the remote side to kill processes.

@end deffn

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

Send a @var{signal} to a process which name matches to @var{pattern} on a
remote machine represented by a @var{session}. Return two values: a list of
PIDs of killed processes and a return code.

The @var{signal} must be a numeric value as for Guile @code{kill} procedure.

The procedure uses a @command{pkill} from procps package on the remote side
when @var{use-guile?} is set to @code{#f} (this is by default.)

When @var{use-guile?} is set to @code{#t}, the procedure will execute a Scheme
code using GNU Guile on the remote side to kill processes.
@end deffn

@deffn {Scheme Procedure} loadavg session
Get average load of a host using a @var{session}.  Return a list of five
elements as described in proc(5) man page.

Example:

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

(let ((s (make-session #:host "example.org")))
  (connect! s)
  (userauth-agent! s)
  (loadavg s))
@result{} ("0.01" "0.05" "0.10" "4/1927" "242011")
@end lisp

@end deffn
