NAME

IPC::PerlSSH::Library::IO - a library of file IO functions for IPC::PerlSSH

SYNOPSIS

 use 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" );

DESCRIPTION

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.

FUNCTIONS

open

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

Close a remote filehandle.

 $ips->call( "close", $fd )

pclose

Close a remote filehandle which was part of a pipe-open, and return the child process exit status.

 $exitstatus = $ips->call( "pclose", $fd )

read

Perform a single read call on a remote filehandle.

 my $data = $ips->call( "read", $fd, $length )

Returns empty string on EOF.

getline

Read a single line from the remote filehandle.

 my $line = $ips->call( "getline", $fd );

Returns empty string on EOF.

write

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.

tell

Return the current file position on a remote filehandle.

 my $pos = $ips->call( "tell", $fd )

seek

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.

truncate

Truncates the file to the given length.

 $ips->call( "truncate", $fd, $len );

fstat

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 )

fchmod

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.

fchown

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().