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

• 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.

  In this case, the write functions are called as

   read( my $buffer, undef );    # read a line, like <$handle>
   read( my $buffer, $len );     # read a fixed-length buffer
  
   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.

AUTHOR

Paul Evans <leonerd@leonerd.org.uk>