Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
IPC::PerlSSH(3)	      User Contributed Perl Documentation      IPC::PerlSSH(3)

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:

       o       String values are passed	as they	stand.

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

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

       o       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 =	@_; ...' );

       o       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
   new (with Host)
	  $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

   new (with Command)
	  $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 );

   new (with Readh + Writeh)
	  $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.

   new (with Readfunc +	Writefunc)
	  $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
   eval
	  @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.

   store
	  $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.

   bind
	  $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.

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

   use_library
	  $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>

perl v5.32.0			  2020-08-11		       IPC::PerlSSH(3)

NAME | SYNOPSIS | DESCRIPTION | CONSTRUCTORS | METHODS | AUTHOR

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=IPC::PerlSSH&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help