=head1 NAME GRID::Machine::IOHandle - Supply object methods for Remote I/O handles =head1 SYNOPSIS use GRID::Machine; my $machine = shift || 'remote.machine'; my $m = GRID::Machine->new( host => $machine ); my $f = $m->open('> tutu.txt'); # Creates a GRID::Machine::IOHandle object $f->print("Hola Mundo!\n"); $f->print("Hello World!\n"); $f->printf("%s %d %4d\n","Bona Sera Signorina", 44, 77); $f->close(); $f = $m->open('tutu.txt'); my $x = <$f>; print "\n******diamond scalar********\n$x\n"; $f->close(); $f = $m->open('tutu.txt'); my $old = $m->input_record_separator(undef); $x = <$f>; print "\n******diamond scalar context and \$/ = undef********\n$x\n"; $f->close(); $old = $m->input_record_separator($old); =head1 DESCRIPTION C object very much resembles C objects. The difference being that the object refers to a remote C object. They can be used not only for remote files but for remote pipes. =head1 METHODS See L for complete descriptions of each of the following supported C methods, which are just front ends for the corresponding built-in functions: $io->close $io->getc $io->print ( ARGS ) $io->printf ( FMT, [ARGS] ) $io->stat See L for complete descriptions of each of the following supported C methods. All of them return the previous value of the attribute and takes an optional single argument that when given will set the value. If no argument is given the previous value is unchanged (except for $io->autoflush will actually turn ON autoflush by default). $io->autoflush ( [BOOL] ) $| The following methods are not supported on a per-filehandle basis. GRID::Machine::IOHandle->format_line_break_characters( [STR] ) $: GRID::Machine::IOHandle->format_formfeed( [STR]) $^L GRID::Machine::IOHandle->output_field_separator( [STR] ) $, GRID::Machine::IOHandle->output_record_separator( [STR] ) $\ GRID::Machine::IOHandle->input_record_separator( [STR] ) $/ Follows an example that uses methods C, C, C, C and C: $ cat getc.pl #!/usr/local/bin/perl -w use strict; use GRID::Machine; my $machine = shift || 'remote.machine'; my $m = GRID::Machine->new( host => $machine ); my $f = $m->open('> tutu.txt'); $f->print("Hola Mundo!\n"); $f->print("Hello World!\n"); $f->printf("%s %d %4d\n","Bona Sera Signorina", 44, 77); $f->close(); $f = $m->open('tutu.txt'); my $x; { $x = $f->getc(); last unless defined($x); print $x; redo; } $f->close(); Furthermore, for doing normal I/O you might need these: =over 4 =item $io->getline This works like <$io> on the remote machine, described in L except that it's more readable and can be safely called in a list context but still returns just one line. =item $io->getlines This works like <$io> when called in a list context to read all the remaining lines in a file, except that it's more readable. It will also croak() if accidentally called in a scalar context. =item The diamond operatos You can read from a remote file using <$io>, but it only works on scalar context. See the L example. =item $io->flush C causes perl to flush any buffered data at the perlio api level. Any unread data in the buffer will be discarded, and any unwritten data will be written to the underlying file descriptor. Returns "0 but true" on success, C on error. =item $io->blocking ( [ BOOL ] ) If called with an argument C will turn on non-blocking IO if C is false, and turn it off if C is true. C will return the value of the previous setting, or the current setting if C is not given. If an error occurs C will return undef and C<$!> will be set. =back =head1 REMOTE PIPES =head2 Opening pipes for input The C method of C objects can be used to pipe programs as in the following example: pp2@nereida:~/LGRID_Machine/examples$ cat -n pipes1.pl 1 #!/usr/local/bin/perl -w 2 use strict; 3 use GRID::Machine; 4 5 my $machine = shift || 'remote.machine.domain'; 6 my $m = GRID::Machine->new( host => $machine ); 7 8 my $f = $m->open('uname -a |'); 9 my $x = <$f>; 10 print "UNAME result: $x\n" In a scalar context C returns the handler. In list context returns the pair C<(handler, PID)>. See L for a more detailed example. When executed the program produces an output similar to this: pp2@nereida:~/LGRID_Machine/examples$ pipes1.pl UNAME result: Linux remote 2.6.8-2-686 #1 Tue Aug 16 13:22:48 UTC 2005 i686 GNU/Linux =head2 Opening pipes for output Pipes can be also for input as the following example shows: pp2@nereida:~/LGRID_Machine/examples$ cat -n pipes.pl 1 #!/usr/local/bin/perl -w 2 use strict; 3 use GRID::Machine; 4 5 my $machine = shift || 'remote.machine'; 6 my $m = GRID::Machine->new( host => $machine ); 7 8 my $i; 9 my $f = $m->open('| sort -n > /tmp/sorted.txt'); 10 for($i=10; $i>=0;$i--) { 11 $f->print("$i\n") 12 } 13 $f->close(); 14 15 my $g = $m->open('/tmp/sorted.txt'); 16 print while <$g>; when executed, the program produces the following output: pp2@nereida:~/LGRID_Machine/examples$ pipes.pl 0 1 2 3 4 5 6 7 8 9 10 When opening a pipe for output like in line 9 in the former example my $f = $m->open('| sort -n > /tmp/sorted.txt') be sure to redirect the C of the program. Otherwise, C will redirect it to the C device and the output will be lost. =head2 Bidirectional pipes: C Synopsis: my $WTR = IO::Handle->new(); my $RDR = IO::Handle->new(); my $pid = $m->open2($fromchild, $tochild, 'command and args'); The C method runs the given command in machine C<$m> and connects C<$fromchild> for reading from C and C<$tochild> for writing from C. Returns the PID of the process executing C. =head2 Bidirectional pipes: C Synopsis: my $pid = $m->open3($tochild, $fromchild, $errfromchild, 'command and args'); Spawns the given command and connects C<$fromchild> for reading from the child, C<$tochild> for writing to the child, and C<$errfromchild> for errors. See an example that opens the Unix calculator C in a remote machine: $ cat -n open3bc.pl 1 #!/usr/bin/perl -w 2 use strict; 3 use GRID::Machine; 4 5 my $machine = shift || 'orion.pcg.ull.es'; 6 my $m = GRID::Machine->new( host => $machine ); 7 8 my $WTR = IO::Handle->new(); 9 my $RDR = IO::Handle->new(); 10 my $ERR = IO::Handle->new(); 11 my $pid = $m->open3($WTR, $RDR, $ERR, 'bc'); 12 13 my $line; 14 15 print $WTR "3*2\n"; 16 $line = <$RDR>; 17 print STDOUT "3*2 = $line"; 18 19 print $WTR "3/(2-2)\n"; 20 $line = <$ERR>; 21 print STDOUT "3/(2-2) produces error = $line\n"; 22 23 print $WTR "quit\n"; 24 wait; When executed, the former program produces an output like this: $ open3bc.pl 3*2 = 6 3/(2-2) produces error = Runtime error (func=(main), adr=11): Divide by zero =head1 SEE ALSO L, L, L =head1 AUTHOR Casiano Rodriguez Leon Ecasiano@ull.esE =head1 ACKNOWLEDGMENTS This work has been supported by CEE (FEDER) and the Spanish Ministry of I through I number TIN2005-08818-C04-04 (ULL::OPLINK project L). Support from Gobierno de Canarias was through GC02210601 (I). The University of La Laguna has also supported my work in many ways and for many years. Thanks also to Juana, Coro, my students at La Laguna and to the Perl Community. =head1 LICENCE AND COPYRIGHT Copyright (c) 2007 Casiano Rodriguez-Leon (casiano@ull.es). All rights reserved. These modules are free software; you can redistribute it and/or modify it under the same terms as Perl itself. See L. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. =cut