5 IO::Handle - supply object methods for I/O handles
12 if ($fh->open "< file") {
17 $fh = new IO::Handle "> FOO";
23 $fh = new IO::Handle "file", "r";
26 undef $fh; # automatically closes the file
29 $fh = new IO::Handle "file", O_WRONLY|O_APPEND;
32 undef $fh; # automatically closes the file
38 $fh->setvbuf($buffer_var, _IOLBF, 1024);
44 C<IO::Handle> is the base class for all other IO handle classes.
45 A C<IO::Handle> object is a reference to a symbol (see the C<Symbol> package)
53 Creates a new C<IO::Handle> object.
55 =item new_from_fd ( FD, MODE )
57 Creates a C<IO::Handle> like C<new> does.
58 It requires two parameters, which are passed to the method C<fdopen>;
59 if the fdopen fails, the object is destroyed. Otherwise, it is returned
66 If the C function setvbuf() is available, then C<IO::Handle::setvbuf>
67 sets the buffering policy for the IO::Handle. The calling sequence
68 for the Perl function is the same as its C counterpart, including the
69 macros C<_IOFBF>, C<_IOLBF>, and C<_IONBF>, except that the buffer
70 parameter specifies a scalar variable to use as a buffer. WARNING: A
71 variable used as a buffer by C<IO::Handle::setvbuf> must not be
72 modified in any way until the IO::Handle is closed or until
73 C<IO::Handle::setvbuf> is called again, or memory corruption may
76 See L<perlfunc> for complete descriptions of each of the following
77 supported C<IO::Handle> methods, which are just front ends for the
78 corresponding built-in functions:
93 See L<perlvar> for complete descriptions of each of the following
94 supported C<IO::Handle> methods:
97 output_field_separator
98 output_record_separator
99 input_record_separator
102 format_lines_per_page
106 format_line_break_characters
110 Furthermore, for doing normal I/O you might need these:
116 This works like <$fh> described in L<perlop/"I/O Operators">
117 except that it's more readable and can be safely called in an
118 array context but still returns just one line.
122 This works like <$fh> when called in an array context to
123 read all the remaining lines in a file, except that it's more readable.
124 It will also croak() if accidentally called in a scalar context.
126 =item $fh->fdopen ( FD, MODE )
128 C<fdopen> is like an ordinary C<open> except that its first parameter
129 is not a filename but rather a file handle name, a IO::Handle object,
130 or a file descriptor number.
132 =item $fh->write ( BUF, LEN [, OFFSET }\] )
134 C<write> is like C<write> found in C, that is it is the
135 opposite of read. The wrapper for the perl C<write> function is
136 called C<format_write>.
140 Returns true if the object is currently a valid file descriptor.
144 Lastly, a special method for working under B<-T> and setuid/gid scripts:
150 Marks the object as taint-clean, and as such data read from it will also
151 be considered taint-clean. Note that this is a very trusting action to
152 take, and appropriate consideration for the data source and potential
153 vulnerability should be kept in mind.
159 A C<IO::Handle> object is a GLOB reference. Some modules that
160 inherit from C<IO::Handle> may want to keep object related variables
161 in the hash table part of the GLOB. In an attempt to prevent modules
162 trampling on each other I propose the that any such module should prefix
163 its variables with its own name separated by _'s. For example the IO::Socket
164 module keeps a C<timeout> variable in 'io_socket_timeout'.
169 L<perlop/"I/O Operators">,
174 Due to backwards compatibility, all filehandles resemble objects
175 of class C<IO::Handle>, or actually classes derived from that class.
176 They actually aren't. Which means you can't derive your own
177 class from C<IO::Handle> and inherit those methods.
181 Derived from FileHandle.pm by Graham Barr E<lt>F<bodg@tiuk.ti.com>E<gt>
187 use vars qw($VERSION @EXPORT_OK $AUTOLOAD @ISA);
199 output_field_separator
200 output_record_separator
201 input_record_separator
204 format_lines_per_page
208 format_line_break_characters
228 ################################################
229 ## Interaction with the XS.
233 @IO::ISA = qw(DynaLoader);
234 bootstrap IO $VERSION;
237 if ($AUTOLOAD =~ /::(_?[a-z])/) {
238 $AutoLoader::AUTOLOAD = $AUTOLOAD;
239 goto &AutoLoader::AUTOLOAD
241 my $constname = $AUTOLOAD;
242 $constname =~ s/.*:://;
243 my $val = constant($constname);
244 defined $val or croak "$constname is not a valid IO::Handle macro";
246 *$AUTOLOAD = sub { $val };
251 ################################################
252 ## Constructors, destructors.
256 my $class = ref($_[0]) || $_[0] || "IO::Handle";
257 @_ == 1 or croak "usage: new $class";
263 my $class = ref($_[0]) || $_[0] || "IO::Handle";
264 @_ == 3 or croak "usage: new_from_fd $class FD, MODE";
267 IO::Handle::fdopen($fh, @_)
273 # There is no need for DESTROY to do anything, because when the
274 # last reference to an IO object is gone, Perl automatically
275 # closes its associated files (if any). However, to avoid any
276 # attempts to autoload DESTROY, we here define it to do nothing.
281 ################################################
285 sub _open_mode_string {
287 $mode =~ /^\+?(<|>>?)$/
288 or $mode =~ s/^r(\+?)$/$1</
289 or $mode =~ s/^w(\+?)$/$1>/
290 or $mode =~ s/^a(\+?)$/$1>>/
291 or croak "IO::Handle: bad open mode: $mode";
296 @_ == 3 or croak 'usage: $fh->fdopen(FD, MODE)';
297 my ($fh, $fd, $mode) = @_;
300 if (ref($fd) && "".$fd =~ /GLOB\(/o) {
301 # It's a glob reference; Alias it as we cannot get name of anon GLOBs
302 my $n = qualify(*GLOB);
305 } elsif ($fd =~ m#^\d+$#) {
306 # It's an FD number; prefix with "=".
310 open($fh, _open_mode_string($mode) . '&' . $fd)
315 @_ == 1 or croak 'usage: $fh->close()';
319 # This may seem as though it should be in IO::Pipe, but the
320 # object gets blessed out of IO::Pipe when reader/writer is called
321 waitpid(${*$fh}{'io_pipe_pid'},0)
322 if(defined ${*$fh}{'io_pipe_pid'});
327 ################################################
328 ## Normal I/O functions.
335 @_ == 1 or croak 'usage: $fh->opened()';
336 defined fileno($_[0]);
340 @_ == 1 or croak 'usage: $fh->fileno()';
345 @_ == 1 or croak 'usage: $fh->getc()';
350 @_ == 1 or croak 'usage: $fh->gets()';
356 @_ == 1 or croak 'usage: $fh->eof()';
361 @_ or croak 'usage: $fh->print([ARGS])';
367 @_ >= 2 or croak 'usage: $fh->printf(FMT,[ARGS])';
373 @_ == 1 or croak 'usage: $fh->getline';
375 return scalar <$this>;
379 @_ == 1 or croak 'usage: $fh->getline()';
381 croak 'Can\'t call $fh->getlines in a scalar context, use $fh->getline';
387 @_ == 2 or croak 'usage: $fh->truncate(LEN)';
388 truncate($_[0], $_[1]);
392 @_ == 3 || @_ == 4 or croak '$fh->read(BUF, LEN [, OFFSET])';
393 read($_[0], $_[1], $_[2], $_[3] || 0);
397 @_ == 3 || @_ == 4 or croak '$fh->sysread(BUF, LEN [, OFFSET])';
398 sysread($_[0], $_[1], $_[2], $_[3] || 0);
402 @_ == 3 || @_ == 4 or croak '$fh->write(BUF, LEN [, OFFSET])';
404 print { $_[0] } substr($_[1], $_[3] || 0, $_[2]);
408 @_ == 3 || @_ == 4 or croak '$fh->syswrite(BUF, LEN [, OFFSET])';
409 syswrite($_[0], $_[1], $_[2], $_[3] || 0);
413 @_ == 1 or croak 'usage: $fh->stat()';
417 ################################################
418 ## State modification functions.
422 my $old = new SelectSaver qualify($_[0], caller);
424 $| = @_ > 1 ? $_[1] : 1;
428 sub output_field_separator {
429 my $old = new SelectSaver qualify($_[0], caller);
431 $, = $_[1] if @_ > 1;
435 sub output_record_separator {
436 my $old = new SelectSaver qualify($_[0], caller);
438 $\ = $_[1] if @_ > 1;
442 sub input_record_separator {
443 my $old = new SelectSaver qualify($_[0], caller);
445 $/ = $_[1] if @_ > 1;
449 sub input_line_number {
450 my $old = new SelectSaver qualify($_[0], caller);
452 $. = $_[1] if @_ > 1;
456 sub format_page_number {
457 my $old = new SelectSaver qualify($_[0], caller);
459 $% = $_[1] if @_ > 1;
463 sub format_lines_per_page {
464 my $old = new SelectSaver qualify($_[0], caller);
466 $= = $_[1] if @_ > 1;
470 sub format_lines_left {
471 my $old = new SelectSaver qualify($_[0], caller);
473 $- = $_[1] if @_ > 1;
478 my $old = new SelectSaver qualify($_[0], caller);
480 $~ = qualify($_[1], caller) if @_ > 1;
484 sub format_top_name {
485 my $old = new SelectSaver qualify($_[0], caller);
487 $^ = qualify($_[1], caller) if @_ > 1;
491 sub format_line_break_characters {
492 my $old = new SelectSaver qualify($_[0], caller);
494 $: = $_[1] if @_ > 1;
498 sub format_formfeed {
499 my $old = new SelectSaver qualify($_[0], caller);
501 $^L = $_[1] if @_ > 1;
510 formline($picture, @_);
515 @_ < 3 || croak 'usage: $fh->write( [FORMAT_NAME] )';
518 my $oldfmt = $fh->format_name($fmt);
520 $fh->format_name($oldfmt);
527 @_ == 3 || croak 'usage: $fh->fcntl( OP, VALUE );';
528 my ($fh, $op, $val) = @_;
529 my $r = fcntl($fh, $op, $val);
530 defined $r && $r eq "0 but true" ? 0 : $r;
534 @_ == 3 || croak 'usage: $fh->ioctl( OP, VALUE );';
535 my ($fh, $op, $val) = @_;
536 my $r = ioctl($fh, $op, $val);
537 defined $r && $r eq "0 but true" ? 0 : $r;