NAME

IPC::PerlSSH - a class for executing remote perl code over an SSH link

DESCRIPTION

This module provides an object class that provides a mechanism to execute perl code in a remote instance of perl running on another host, communicated via an SSH link or similar connection. Where it differs from most other IPC modules is that no special software is required on the remote end, other than the ability to run perl. In particular, it is not required that the IPC::PerlSSH module is installed there. Nor are any special administrative rights required; any account that has shell access and can execute the perl binary on the remote host can use this module.

SYNOPSIS

use IPC::PerlSSH;

my $ips = IPC::PerlSSH->new( Host => "over.there" );

$ips->eval( "use POSIX qw( uname )" );
my @remote_uname = $ips->eval( "uname()" );

# We can pass arguments
$ips->eval( "open FILE, ">", shift; print FILE shift; close FILE;",
            "foo.txt",
            "Hello, world!" );

# We can pre-compile stored procedures
$ips->store( "get_file", "local $/; 
                          open FILE, "<", shift;
                          $_ = <FILE>;
                          close FILE;
                          return $_;" );
foreach my $file ( @files ) {
   my $content = $ips->call( "get_file", $file );
   ...
}

FUNCTIONS

$ips = IPC::PerlSSH->new( @args )

This function returns a new instance of a IPC::PerlSSH object. The connection can be specified in one of three ways, given in the @args list:

• Connecting to a named host.

  Host => $hostname

  Optionally passing in the path to the perl binary in the remote host

  Perl => $perl

  Optionally passing in an alternative username

  User => $user

  Optionally specifying a different path to the ssh binary

  SshPath => $path

• Running a specified command, connecting to its standard input and output.

  Command => $command

  Or

  Command => [ $command, @args ]

• Using a given pair of functions as read and write operators.

  Readfunc => \&read, Writefunc => \&write

  Usually this form won't be used in practice; it largely exists to assist the test scripts. But since it works, it is included in the interface in case the earlier alternatives are not suitable.

  The functions are called as

  read( my $buffer, $len );
  
  write( $buffer );

  In each case, the returned value should be the number of bytes read or written.

@result = $ips->eval( $code, @args )

This method evaluates code in the remote host, passing arguments and returning the result.

The code should be passed in a string, and is evaluated using a string eval in the remote host, in list context. If this method is called in scalar context, then only the first element of the returned list is returned. Only string scalar values are supported in either the arguments or the return values; no deeply-nested structures can be passed.

To pass or return a more complex structure, consider using a module such as Storable, which can serialise the structure into a plain string, to be deserialised on the remote end.

If the remote code threw an exception, then this function propagates it as a plain string.

$ips->store( $name, $code )

This method sends code to the remote host to store in a named procedure which can be executed later. The code should be passed in a string, along with a name which can later be called by the call method.

While the code is not executed, it will still be compiled into a CODE reference in the remote host. Any compile errors that occur will be throw as exceptions by this method.

$ips->bind( $name, $code )

This method is identical to the store method, except that the remote function will be available as a plain function within the local perl program, as a function of the given name in the caller's package.

@result = $ips->call( $name, @args )

This method invokes a remote method that has earlier been defined using the store or bind methods. The arguments are passed and the result is returned in the same way as with the eval method.

If an exception occurs during execution, it is propagated and thrown by this method.

$ips->use_library( $library, @funcs )

This method loads a library of code from a module, and stores them to the remote perl by calling store on each one. The $library name may be a full class name, or a name within the IPC::PerlSSH::Library:: space.

If the @funcs list is non-empty, then only those named functions are stored (analogous to the use perl statement). This may be useful in large libraries that define many functions, only a few of which are actually used.

For more information, see IPC::PerlSSH::Library.

AUTHOR

Paul Evans <leonerd@leonerd.org.uk>