View on
MetaCPAN is shutting down
For details read Perl NOC. After June 25th this page will redirect to
Paul Evans > IPC-PerlSSH-0.16 > IPC::PerlSSH::Library::IO



Annotate this POD


New  1
Open  1
View/Report Bugs
Module Version: 0.16   Source   Latest Release: IPC-PerlSSH-0.17


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


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


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

Returns empty string on EOF.


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

Only works on versions of remote perl 5.8.8 and above.


Paul Evans <>

syntax highlighting: