NAME
   `IPC::PerlSSH' - execute remote perl code over an SSH link

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, ">", $_[0]; print FILE $_[1]; close FILE;',
                "foo.txt", "Hello, world!" );

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

    # We can use existing libraries for remote stored procedures
    $ips->use_library( "FS", qw( readfile ) );
    foreach my $file ( @files ) {
       my $content = $ips->call( "readfile", $file );
       ...
    }

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.

 Argument Passing
   The arguments to, and return values from, remote code are always
   transferred as lists of strings. This has the following effects on
   various types of values:

   *       String values are passed as they stand.

   *       Booleans and integers will become stringified, but will work as
           expected once they reach the other side of the connection.

   *       Floating-point numbers will get converted to a decimal notation,
           which may lose precision.

   *       A single array of strings, or a single hash of string values,
           can be passed by-value as a list, possibly after positional
           arguments:

            $ips->store( 'foo', 'my ( $arg, @list ) = @_; ...' );

            $ips->store( 'bar', 'my %opts = @_; ...' );

   *       No reference value, including IO handles, can be passed; instead
           it will be stringified.

   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. Be aware however, that `Storable' was
   only added to core in perl 5.7.3, so if the remote perl is older, it may
   not be available.

   To work with remote IO handles, see the IPC::PerlSSH::Library::IO
   module.

CONSTRUCTORS
 $ips = IPC::PerlSSH->new( Host => $host, ... )
   Returns a new instance of a `IPC::PerlSSH' object connected to the
   specified host. The following arguments can be specified:

   Host => STRING
           Connect to a named host.

   Port => INT
           Optionally specify a non-default port.

   Perl => STRING
           Optionally pass in the path to the perl binary in the remote
           host.

   User => STRING
           Optionally pass in an alternative username

   SshPath => STRING
           Optionally specify a different path to the ssh binary

   SshOptions => ARRAY
           Optionally specify any other options to pass to the ssh binary,
           in an `ARRAY' reference

 $ips = IPC::PerlSSH->new( Command => \@command, ... )
   Returns a new instance of a `IPC::PerlSSH' object which uses the
   STDIN/STDOUT streams of a command it executes, as the streams to
   communicate with the remote perl.

   Command => ARRAY
           Specifies the command to execute

   Command => STRING
           Shorthand form for executing a single simple path

   The `Command' key can be used to create an `IPC::PerlSSH' running perl
   directly on the local machine, for example; so that the "remote" perl is
   in fact running locally, but still in its own process.

    my $ips = IPC::PerlSSH->new( Command => $^X );

 $ips = IPC::PerlSSH->new( Readh => $rd, Writeh => $wr )
   Returns a new instance of a `IPC::PerlSSH' object using a given pair of
   filehandles to read from and write to the remote perl process. It is
   allowable for both filehandles to be the same - for example using a
   socket.

 $ips = IPC::PerlSSH->new( Readfunc => \&read, Writefunc => \&write )
   Returns a new instance of a `IPC::PerlSSH' object using a given pair of
   functions as read and write operators.

   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

    $len = $Readfunc->( my $buffer, $maxlen );

    $len = $Writewrite->( $buffer );

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

METHODS
 @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.

   If the remote code threw an exception, then this function propagates it
   as a plain string. If the remote process exits before responding, this
   will be propagated as an exception.

 $ips->store( $name, $code )
 $ips->store( %funcs )
   This method sends code to the remote host to store in named procedure(s)
   which can be executed later. The code should be passed in strings.

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

   Multiple functions may be passed in a hash, to reduce the number of
   network roundtrips, which may help latency.

 $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. If the remote process exits before responding, this will be
   propagated as an exception.

 $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 <[email protected]>

You are viewing proxied material from ftp.icm.edu.pl. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.