IPC::PerlSSH::Library::IO - a library of file IO functions for IPC::PerlSSH
my $ips = IPC::PerlSSH->new( Host => "over.there" );
$ips->use_library( "IO", qw( open fchmod write close ) );
my $fd = $ips->call( "open", ">", "secret.txt" );
$ips->call( "fchmod", $fd, 0600 );
$ips->call( "write", $fd, "s3kr1t\n" );
$ips->call( "close" );
This module provides a library of functions for interacting with remote IO filehandles. It provides simple wrappers around the perl IO functions, taking or returning file descriptor numbers instead of filehandle objects. This allows filehandles to remain open in the remote perl instance, across many calls.
Because the filehandles remain open, the program must take care to call close at the appropriate time, so as not to leak file descriptors in the remote perl.
Open a new filehandle in the remote perl and return its FD number.
my $fd = $ips->call( "open", $mode, @args )
The filehandle is put into unbuffered mode, such that subsequent write calls will send the data directly to the underlying operating system.
The $mode argument supports the full range of perl open modes, including pipe opens with -|. If using a pipe open, you can close the file handle with pclose instead of close to obtain the child process exit status.
In the case of pipe opens, IPC::PerlSSH::Library::Run provides a selection of functions that may be more convenient for executing a child program on the remote perl, if interaction during its execution is not required.
In the case of simple open / read / close or open / write / close sequences, see also the IPC::PerlSSH::Library::FS functions readfile and writefile.
Close a remote filehandle.
$ips->call( "close", $fd )
Close a remote filehandle which was part of a pipe-open, and return the child process exit status.
$exitstatus = $ips->call( "pclose", $fd )
Perform a single read call on a remote filehandle.
my $data = $ips->call( "read", $fd, $length )
Returns empty string on EOF.
Read a single line from the remote filehandle.
my $line = $ips->call( "getline", $fd );
Perform a single write call on a remote filehandle.
$ips->call( "write", $fd, $data )
Note this is called write to match the system call, rather than print.
Return the current file position on a remote filehandle.
my $pos = $ips->call( "tell", $fd )
Seek to the given position in the remote filehandle and return the new position.
my $newpos = $ips->call( "seek", $fd, $pos, $whence )
You may find it useful to import the SEEK_* constants from the Fcntl module.
Truncates the file to the given length.
$ips->call( "truncate", $fd, $len );
Returns the status of the file (see "perldoc -f stat").
my ( $dev, $ino, $mode, $nlink, $uid, $gid, $rdev, $size, $atime,
$mtime, $ctime, $blksize, $blocks ) = $ips->call( "fstat", $fd )
Change the permissions on the remote filehandle.
$ips->call( "fchmod", $fd, 0755 )
Note the order of arguments does not match perl's chmod().
Only works on versions of remote perl 5.8.8 and above.
Changes the owner (and group) of the remote filehandle.
$ips->call( "fchown", $uid, $gid )
Note the order of arguments does not match perl's chown().
Paul Evans <email@example.com>
To install IPC::PerlSSH, copy and paste the appropriate command in to your terminal.
perl -MCPAN -e shell
For more information on module installation, please visit the detailed CPAN module installation guide.