6 IO::Handle - supply object methods for I/O handles
13 if ($fh->fdopen(fileno(STDIN),"r")) {
19 if ($fh->fdopen(fileno(STDOUT),"w")) {
20 $fh->print("Some text\n");
23 use IO::Handle '_IOLBF';
24 $fh->setvbuf($buffer_var, _IOLBF, 1024);
26 undef $fh; # automatically closes the file if it's open
32 C<IO::Handle> is the base class for all other IO handle classes. It is
33 not intended that objects of C<IO::Handle> would be created directly,
34 but instead C<IO::Handle> is inherited from by several other classes
37 If you are reading this documentation, looking for a replacement for
38 the C<FileHandle> package, then I suggest you read the documentation
41 A C<IO::Handle> object is a reference to a symbol (see the C<Symbol> package)
49 Creates a new C<IO::Handle> object.
51 =item new_from_fd ( FD, MODE )
53 Creates a C<IO::Handle> like C<new> does.
54 It requires two parameters, which are passed to the method C<fdopen>;
55 if the fdopen fails, the object is destroyed. Otherwise, it is returned
62 See L<perlfunc> for complete descriptions of each of the following
63 supported C<IO::Handle> methods, which are just front ends for the
64 corresponding built-in functions:
78 See L<perlvar> for complete descriptions of each of the following
79 supported C<IO::Handle> methods:
82 output_field_separator
83 output_record_separator
84 input_record_separator
91 format_line_break_characters
95 Furthermore, for doing normal I/O you might need these:
99 =item $fh->fdopen ( FD, MODE )
101 C<fdopen> is like an ordinary C<open> except that its first parameter
102 is not a filename but rather a file handle name, a IO::Handle object,
103 or a file descriptor number.
107 Returns true if the object is currently a valid file descriptor.
111 This works like <$fh> described in L<perlop/"I/O Operators">
112 except that it's more readable and can be safely called in an
113 array context but still returns just one line.
117 This works like <$fh> when called in an array context to
118 read all the remaining lines in a file, except that it's more readable.
119 It will also croak() if accidentally called in a scalar context.
121 =item $fh->ungetc ( ORD )
123 Pushes a character with the given ordinal value back onto the given
124 handle's input stream.
126 =item $fh->write ( BUF, LEN [, OFFSET }\] )
128 This C<write> is like C<write> found in C, that is it is the
129 opposite of read. The wrapper for the perl C<write> function is
130 called C<format_write>.
134 Flush the given handle's buffer.
138 Returns a true value if the given handle has experienced any errors
139 since it was opened or since the last call to C<clearerr>.
143 Clear the given handle's error indicator.
147 If the C functions setbuf() and/or setvbuf() are available, then
148 C<IO::Handle::setbuf> and C<IO::Handle::setvbuf> set the buffering
149 policy for an IO::Handle. The calling sequences for the Perl functions
150 are the same as their C counterparts--including the constants C<_IOFBF>,
151 C<_IOLBF>, and C<_IONBF> for setvbuf()--except that the buffer parameter
152 specifies a scalar variable to use as a buffer. WARNING: A variable
153 used as a buffer by C<setbuf> or C<setvbuf> must not be modified in any
154 way until the IO::Handle is closed or C<setbuf> or C<setvbuf> is called
155 again, or memory corruption may result! Note that you need to import
156 the constants C<_IOFBF>, C<_IOLBF>, and C<_IONBF> explicitly.
158 Lastly, there is a special method for working under B<-T> and setuid/gid
165 Marks the object as taint-clean, and as such data read from it will also
166 be considered taint-clean. Note that this is a very trusting action to
167 take, and appropriate consideration for the data source and potential
168 vulnerability should be kept in mind.
174 A C<IO::Handle> object is a GLOB reference. Some modules that
175 inherit from C<IO::Handle> may want to keep object related variables
176 in the hash table part of the GLOB. In an attempt to prevent modules
177 trampling on each other I propose the that any such module should prefix
178 its variables with its own name separated by _'s. For example the IO::Socket
179 module keeps a C<timeout> variable in 'io_socket_timeout'.
184 L<perlop/"I/O Operators">,
189 Due to backwards compatibility, all filehandles resemble objects
190 of class C<IO::Handle>, or actually classes derived from that class.
191 They actually aren't. Which means you can't derive your own
192 class from C<IO::Handle> and inherit those methods.
196 Derived from FileHandle.pm by Graham Barr E<lt>F<bodg@tiuk.ti.com>E<gt>
202 use vars qw($VERSION $XS_VERSION @EXPORT_OK $AUTOLOAD @ISA);
211 $XS_VERSION = "1.15";
215 output_field_separator
216 output_record_separator
217 input_record_separator
220 format_lines_per_page
224 format_line_break_characters
242 ################################################
243 ## Interaction with the XS.
247 @IO::ISA = qw(DynaLoader);
248 bootstrap IO $XS_VERSION;
251 if ($AUTOLOAD =~ /::(_?[a-z])/) {
252 $AutoLoader::AUTOLOAD = $AUTOLOAD;
253 goto &AutoLoader::AUTOLOAD
255 my $constname = $AUTOLOAD;
256 $constname =~ s/.*:://;
257 my $val = constant($constname);
258 defined $val or croak "$constname is not a valid IO::Handle macro";
260 *$AUTOLOAD = sub { $val };
265 ################################################
266 ## Constructors, destructors.
270 my $class = ref($_[0]) || $_[0] || "IO::Handle";
271 @_ == 1 or croak "usage: new $class";
277 my $class = ref($_[0]) || $_[0] || "IO::Handle";
278 @_ == 3 or croak "usage: new_from_fd $class FD, MODE";
281 IO::Handle::fdopen($fh, @_)
287 # There is no need for DESTROY to do anything, because when the
288 # last reference to an IO object is gone, Perl automatically
289 # closes its associated files (if any). However, to avoid any
290 # attempts to autoload DESTROY, we here define it to do nothing.
295 ################################################
299 sub _open_mode_string {
301 $mode =~ /^\+?(<|>>?)$/
302 or $mode =~ s/^r(\+?)$/$1</
303 or $mode =~ s/^w(\+?)$/$1>/
304 or $mode =~ s/^a(\+?)$/$1>>/
305 or croak "IO::Handle: bad open mode: $mode";
310 @_ == 3 or croak 'usage: $fh->fdopen(FD, MODE)';
311 my ($fh, $fd, $mode) = @_;
314 if (ref($fd) && "".$fd =~ /GLOB\(/o) {
315 # It's a glob reference; Alias it as we cannot get name of anon GLOBs
316 my $n = qualify(*GLOB);
319 } elsif ($fd =~ m#^\d+$#) {
320 # It's an FD number; prefix with "=".
324 open($fh, _open_mode_string($mode) . '&' . $fd)
329 @_ == 1 or croak 'usage: $fh->close()';
335 ################################################
336 ## Normal I/O functions.
343 @_ == 1 or croak 'usage: $fh->opened()';
344 defined fileno($_[0]);
348 @_ == 1 or croak 'usage: $fh->fileno()';
353 @_ == 1 or croak 'usage: $fh->getc()';
358 @_ == 1 or croak 'usage: $fh->eof()';
363 @_ or croak 'usage: $fh->print([ARGS])';
369 @_ >= 2 or croak 'usage: $fh->printf(FMT,[ARGS])';
375 @_ == 1 or croak 'usage: $fh->getline';
377 return scalar <$this>;
380 *gets = \&getline; # deprecated
383 @_ == 1 or croak 'usage: $fh->getline()';
385 croak 'Can\'t call $fh->getlines in a scalar context, use $fh->getline';
391 @_ == 2 or croak 'usage: $fh->truncate(LEN)';
392 truncate($_[0], $_[1]);
396 @_ == 3 || @_ == 4 or croak '$fh->read(BUF, LEN [, OFFSET])';
397 read($_[0], $_[1], $_[2], $_[3] || 0);
401 @_ == 3 || @_ == 4 or croak '$fh->sysread(BUF, LEN [, OFFSET])';
402 sysread($_[0], $_[1], $_[2], $_[3] || 0);
406 @_ == 3 || @_ == 4 or croak '$fh->write(BUF, LEN [, OFFSET])';
408 print { $_[0] } substr($_[1], $_[3] || 0, $_[2]);
412 @_ == 3 || @_ == 4 or croak '$fh->syswrite(BUF, LEN [, OFFSET])';
413 syswrite($_[0], $_[1], $_[2], $_[3] || 0);
417 @_ == 1 or croak 'usage: $fh->stat()';
421 ################################################
422 ## State modification functions.
426 my $old = new SelectSaver qualify($_[0], caller);
428 $| = @_ > 1 ? $_[1] : 1;
432 sub output_field_separator {
433 my $old = new SelectSaver qualify($_[0], caller);
435 $, = $_[1] if @_ > 1;
439 sub output_record_separator {
440 my $old = new SelectSaver qualify($_[0], caller);
442 $\ = $_[1] if @_ > 1;
446 sub input_record_separator {
448 $/ = $_[1] if @_ > 1;
452 sub input_line_number {
454 $. = $_[1] if @_ > 1;
458 sub format_page_number {
459 my $old = new SelectSaver qualify($_[0], caller);
461 $% = $_[1] if @_ > 1;
465 sub format_lines_per_page {
466 my $old = new SelectSaver qualify($_[0], caller);
468 $= = $_[1] if @_ > 1;
472 sub format_lines_left {
473 my $old = new SelectSaver qualify($_[0], caller);
475 $- = $_[1] if @_ > 1;
480 my $old = new SelectSaver qualify($_[0], caller);
482 $~ = qualify($_[1], caller) if @_ > 1;
486 sub format_top_name {
487 my $old = new SelectSaver qualify($_[0], caller);
489 $^ = qualify($_[1], caller) if @_ > 1;
493 sub format_line_break_characters {
494 my $old = new SelectSaver qualify($_[0], caller);
496 $: = $_[1] if @_ > 1;
500 sub format_formfeed {
501 my $old = new SelectSaver qualify($_[0], caller);
503 $^L = $_[1] if @_ > 1;
512 formline($picture, @_);
517 @_ < 3 || croak 'usage: $fh->write( [FORMAT_NAME] )';
520 my $oldfmt = $fh->format_name($fmt);
522 $fh->format_name($oldfmt);
529 @_ == 3 || croak 'usage: $fh->fcntl( OP, VALUE );';
530 my ($fh, $op, $val) = @_;
531 my $r = fcntl($fh, $op, $val);
532 defined $r && $r eq "0 but true" ? 0 : $r;
536 @_ == 3 || croak 'usage: $fh->ioctl( OP, VALUE );';
537 my ($fh, $op, $val) = @_;
538 my $r = ioctl($fh, $op, $val);
539 defined $r && $r eq "0 but true" ? 0 : $r;