This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
[perl #63234] [DOC PATCH] fix some missing parts of IO::Handle pod
[perl5.git] / ext / IO / lib / IO / Handle.pm
CommitLineData
8add82fc
PP
1package IO::Handle;
2
3=head1 NAME
4
27d4819a 5IO::Handle - supply object methods for I/O handles
8add82fc
PP
6
7=head1 SYNOPSIS
8
9 use IO::Handle;
10
cf7fe8a2
GS
11 $io = new IO::Handle;
12 if ($io->fdopen(fileno(STDIN),"r")) {
13 print $io->getline;
14 $io->close;
8add82fc
PP
15 }
16
cf7fe8a2
GS
17 $io = new IO::Handle;
18 if ($io->fdopen(fileno(STDOUT),"w")) {
19 $io->print("Some text\n");
8add82fc
PP
20 }
21
284196a3 22 # setvbuf is not available by default on Perls 5.8.0 and later.
3370baa8 23 use IO::Handle '_IOLBF';
cf7fe8a2 24 $io->setvbuf($buffer_var, _IOLBF, 1024);
8add82fc 25
cf7fe8a2 26 undef $io; # automatically closes the file if it's open
774d564b 27
8add82fc
PP
28 autoflush STDOUT 1;
29
30=head1 DESCRIPTION
31
774d564b
PP
32C<IO::Handle> is the base class for all other IO handle classes. It is
33not intended that objects of C<IO::Handle> would be created directly,
34but instead C<IO::Handle> is inherited from by several other classes
35in the IO hierarchy.
36
37If you are reading this documentation, looking for a replacement for
38the C<FileHandle> package, then I suggest you read the documentation
cf7fe8a2 39for C<IO::File> too.
8add82fc 40
27d4819a
JM
41=head1 CONSTRUCTOR
42
43=over 4
44
45=item new ()
8add82fc 46
27d4819a 47Creates a new C<IO::Handle> object.
8add82fc 48
27d4819a
JM
49=item new_from_fd ( FD, MODE )
50
d1be9408 51Creates an C<IO::Handle> like C<new> does.
27d4819a
JM
52It requires two parameters, which are passed to the method C<fdopen>;
53if the fdopen fails, the object is destroyed. Otherwise, it is returned
54to the caller.
55
56=back
57
58=head1 METHODS
8add82fc 59
8add82fc
PP
60See L<perlfunc> for complete descriptions of each of the following
61supported C<IO::Handle> methods, which are just front ends for the
62corresponding built-in functions:
a6006777 63
cf7fe8a2
GS
64 $io->close
65 $io->eof
2b93ed32 66 $io->fcntl( FUNCTION, SCALAR )
cf7fe8a2
GS
67 $io->fileno
68 $io->format_write( [FORMAT_NAME] )
69 $io->getc
2b93ed32 70 $io->ioctl( FUNCTION, SCALAR )
cf7fe8a2
GS
71 $io->read ( BUF, LEN, [OFFSET] )
72 $io->print ( ARGS )
73 $io->printf ( FMT, [ARGS] )
0d863452 74 $io->say ( ARGS )
cf7fe8a2
GS
75 $io->stat
76 $io->sysread ( BUF, LEN, [OFFSET] )
2ecf2f18 77 $io->syswrite ( BUF, [LEN, [OFFSET]] )
cf7fe8a2 78 $io->truncate ( LEN )
8add82fc
PP
79
80See L<perlvar> for complete descriptions of each of the following
cf7fe8a2
GS
81supported C<IO::Handle> methods. All of them return the previous
82value of the attribute and takes an optional single argument that when
83given will set the value. If no argument is given the previous value
84is unchanged (except for $io->autoflush will actually turn ON
85autoflush by default).
8add82fc 86
cf7fe8a2
GS
87 $io->autoflush ( [BOOL] ) $|
88 $io->format_page_number( [NUM] ) $%
89 $io->format_lines_per_page( [NUM] ) $=
90 $io->format_lines_left( [NUM] ) $-
91 $io->format_name( [STR] ) $~
92 $io->format_top_name( [STR] ) $^
93 $io->input_line_number( [NUM]) $.
94
95The following methods are not supported on a per-filehandle basis.
96
97 IO::Handle->format_line_break_characters( [STR] ) $:
98 IO::Handle->format_formfeed( [STR]) $^L
99 IO::Handle->output_field_separator( [STR] ) $,
100 IO::Handle->output_record_separator( [STR] ) $\
101
102 IO::Handle->input_record_separator( [STR] ) $/
8add82fc
PP
103
104Furthermore, for doing normal I/O you might need these:
105
bbc7dcd2 106=over 4
8add82fc 107
cf7fe8a2 108=item $io->fdopen ( FD, MODE )
948ecc40
CS
109
110C<fdopen> is like an ordinary C<open> except that its first parameter
d1be9408 111is not a filename but rather a file handle name, an IO::Handle object,
2b93ed32
ZA
112or a file descriptor number. (For the documentation of the C<open>
113method, see L<IO::File>.)
948ecc40 114
cf7fe8a2 115=item $io->opened
948ecc40 116
a47f745f
NC
117Returns true if the object is currently a valid file descriptor, false
118otherwise.
948ecc40 119
cf7fe8a2 120=item $io->getline
8add82fc 121
cf7fe8a2 122This works like <$io> described in L<perlop/"I/O Operators">
91e74348 123except that it's more readable and can be safely called in a
bb4e8523
SP
124list context but still returns just one line. If used as the conditional
125+within a C<while> or C-style C<for> loop, however, you will need to
126+emulate the functionality of <$io> with C<< defined($_ = $io->getline) >>.
8add82fc 127
cf7fe8a2 128=item $io->getlines
8add82fc 129
91e74348
JH
130This works like <$io> when called in a list context to read all
131the remaining lines in a file, except that it's more readable.
8add82fc
PP
132It will also croak() if accidentally called in a scalar context.
133
cf7fe8a2 134=item $io->ungetc ( ORD )
27d4819a 135
948ecc40 136Pushes a character with the given ordinal value back onto the given
cf7fe8a2
GS
137handle's input stream. Only one character of pushback per handle is
138guaranteed.
27d4819a 139
cf7fe8a2 140=item $io->write ( BUF, LEN [, OFFSET ] )
27d4819a 141
948ecc40 142This C<write> is like C<write> found in C, that is it is the
27d4819a
JM
143opposite of read. The wrapper for the perl C<write> function is
144called C<format_write>.
145
cf7fe8a2 146=item $io->error
948ecc40
CS
147
148Returns a true value if the given handle has experienced any errors
a47f745f
NC
149since it was opened or since the last call to C<clearerr>, or if the
150handle is invalid. It only returns false for a valid handle with no
151outstanding errors.
948ecc40 152
cf7fe8a2 153=item $io->clearerr
948ecc40 154
a47f745f
NC
155Clear the given handle's error indicator. Returns -1 if the handle is
156invalid, 0 otherwise.
27d4819a 157
cf7fe8a2
GS
158=item $io->sync
159
160C<sync> synchronizes a file's in-memory state with that on the
161physical medium. C<sync> does not operate at the perlio api level, but
a47f745f
NC
162operates on the file descriptor (similar to sysread, sysseek and
163systell). This means that any data held at the perlio api level will not
164be synchronized. To synchronize data that is buffered at the perlio api
165level you must use the flush method. C<sync> is not implemented on all
54d9745e
NC
166platforms. Returns "0 but true" on success, C<undef> on error, C<undef>
167for an invalid handle. See L<fsync(3c)>.
cf7fe8a2
GS
168
169=item $io->flush
170
171C<flush> causes perl to flush any buffered data at the perlio api level.
172Any unread data in the buffer will be discarded, and any unwritten data
54d9745e
NC
173will be written to the underlying file descriptor. Returns "0 but true"
174on success, C<undef> on error.
cf7fe8a2
GS
175
176=item $io->printflush ( ARGS )
177
178Turns on autoflush, print ARGS and then restores the autoflush status of the
a47f745f 179C<IO::Handle> object. Returns the return value from print.
cf7fe8a2
GS
180
181=item $io->blocking ( [ BOOL ] )
182
183If called with an argument C<blocking> will turn on non-blocking IO if
184C<BOOL> is false, and turn it off if C<BOOL> is true.
185
186C<blocking> will return the value of the previous setting, or the
187current setting if C<BOOL> is not given.
188
189If an error occurs C<blocking> will return undef and C<$!> will be set.
190
8add82fc
PP
191=back
192
cf7fe8a2 193
948ecc40
CS
194If the C functions setbuf() and/or setvbuf() are available, then
195C<IO::Handle::setbuf> and C<IO::Handle::setvbuf> set the buffering
196policy for an IO::Handle. The calling sequences for the Perl functions
197are the same as their C counterparts--including the constants C<_IOFBF>,
198C<_IOLBF>, and C<_IONBF> for setvbuf()--except that the buffer parameter
a47f745f
NC
199specifies a scalar variable to use as a buffer. You should only
200change the buffer before any I/O, or immediately after calling flush.
201
284196a3
JH
202WARNING: The IO::Handle::setvbuf() is not available by default on
203Perls 5.8.0 and later because setvbuf() is rather specific to using
204the stdio library, while Perl prefers the new perlio subsystem instead.
205
a47f745f
NC
206WARNING: A variable used as a buffer by C<setbuf> or C<setvbuf> B<must not
207be modified> in any way until the IO::Handle is closed or C<setbuf> or
208C<setvbuf> is called again, or memory corruption may result! Remember that
209the order of global destruction is undefined, so even if your buffer
210variable remains in scope until program termination, it may be undefined
211before the file IO::Handle is closed. Note that you need to import the
212constants C<_IOFBF>, C<_IOLBF>, and C<_IONBF> explicitly. Like C, setbuf
54d9745e
NC
213returns nothing. setvbuf returns "0 but true", on success, C<undef> on
214failure.
948ecc40
CS
215
216Lastly, there is a special method for working under B<-T> and setuid/gid
217scripts:
515e7bd7 218
bbc7dcd2 219=over 4
515e7bd7 220
cf7fe8a2 221=item $io->untaint
515e7bd7
RR
222
223Marks the object as taint-clean, and as such data read from it will also
224be considered taint-clean. Note that this is a very trusting action to
225take, and appropriate consideration for the data source and potential
a47f745f
NC
226vulnerability should be kept in mind. Returns 0 on success, -1 if setting
227the taint-clean flag failed. (eg invalid handle)
515e7bd7
RR
228
229=back
230
27d4819a 231=head1 NOTE
8add82fc 232
d1be9408 233An C<IO::Handle> object is a reference to a symbol/GLOB reference (see
cf7fe8a2 234the C<Symbol> package). Some modules that
8add82fc
PP
235inherit from C<IO::Handle> may want to keep object related variables
236in the hash table part of the GLOB. In an attempt to prevent modules
237trampling on each other I propose the that any such module should prefix
238its variables with its own name separated by _'s. For example the IO::Socket
239module keeps a C<timeout> variable in 'io_socket_timeout'.
240
241=head1 SEE ALSO
242
243L<perlfunc>,
244L<perlop/"I/O Operators">,
774d564b 245L<IO::File>
8add82fc
PP
246
247=head1 BUGS
248
249Due to backwards compatibility, all filehandles resemble objects
250of class C<IO::Handle>, or actually classes derived from that class.
251They actually aren't. Which means you can't derive your own
252class from C<IO::Handle> and inherit those methods.
253
254=head1 HISTORY
255
cf7fe8a2 256Derived from FileHandle.pm by Graham Barr E<lt>F<gbarr@pobox.com>E<gt>
8add82fc
PP
257
258=cut
259
3b825e41 260use 5.006_001;
7a4c00b4 261use strict;
17f410f9 262our($VERSION, @EXPORT_OK, @ISA);
8add82fc
PP
263use Carp;
264use Symbol;
265use SelectSaver;
cf7fe8a2 266use IO (); # Load the XS module
8add82fc
PP
267
268require Exporter;
269@ISA = qw(Exporter);
270
2b93ed32 271$VERSION = "1.27_02";
105cd853 272$VERSION = eval $VERSION;
8add82fc
PP
273
274@EXPORT_OK = qw(
275 autoflush
276 output_field_separator
277 output_record_separator
278 input_record_separator
279 input_line_number
280 format_page_number
281 format_lines_per_page
282 format_lines_left
283 format_name
284 format_top_name
285 format_line_break_characters
286 format_formfeed
287 format_write
288
289 print
290 printf
0d863452 291 say
8add82fc
PP
292 getline
293 getlines
294
cf7fe8a2
GS
295 printflush
296 flush
297
8add82fc
PP
298 SEEK_SET
299 SEEK_CUR
300 SEEK_END
301 _IOFBF
302 _IOLBF
303 _IONBF
8add82fc
PP
304);
305
8add82fc
PP
306################################################
307## Constructors, destructors.
308##
309
310sub new {
27d4819a
JM
311 my $class = ref($_[0]) || $_[0] || "IO::Handle";
312 @_ == 1 or croak "usage: new $class";
cf7fe8a2
GS
313 my $io = gensym;
314 bless $io, $class;
8add82fc
PP
315}
316
317sub new_from_fd {
27d4819a
JM
318 my $class = ref($_[0]) || $_[0] || "IO::Handle";
319 @_ == 3 or croak "usage: new_from_fd $class FD, MODE";
cf7fe8a2 320 my $io = gensym;
c927212d 321 shift;
cf7fe8a2 322 IO::Handle::fdopen($io, @_)
8add82fc 323 or return undef;
cf7fe8a2 324 bless $io, $class;
8add82fc
PP
325}
326
98d4926f
CS
327#
328# There is no need for DESTROY to do anything, because when the
329# last reference to an IO object is gone, Perl automatically
330# closes its associated files (if any). However, to avoid any
331# attempts to autoload DESTROY, we here define it to do nothing.
332#
333sub DESTROY {}
7a4c00b4 334
8add82fc
PP
335
336################################################
337## Open and close.
338##
339
340sub _open_mode_string {
341 my ($mode) = @_;
342 $mode =~ /^\+?(<|>>?)$/
343 or $mode =~ s/^r(\+?)$/$1</
344 or $mode =~ s/^w(\+?)$/$1>/
345 or $mode =~ s/^a(\+?)$/$1>>/
346 or croak "IO::Handle: bad open mode: $mode";
347 $mode;
348}
349
350sub fdopen {
cf7fe8a2
GS
351 @_ == 3 or croak 'usage: $io->fdopen(FD, MODE)';
352 my ($io, $fd, $mode) = @_;
8add82fc
PP
353 local(*GLOB);
354
355 if (ref($fd) && "".$fd =~ /GLOB\(/o) {
356 # It's a glob reference; Alias it as we cannot get name of anon GLOBs
357 my $n = qualify(*GLOB);
358 *GLOB = *{*$fd};
359 $fd = $n;
360 } elsif ($fd =~ m#^\d+$#) {
361 # It's an FD number; prefix with "=".
362 $fd = "=$fd";
363 }
364
cf7fe8a2
GS
365 open($io, _open_mode_string($mode) . '&' . $fd)
366 ? $io : undef;
8add82fc
PP
367}
368
369sub close {
cf7fe8a2
GS
370 @_ == 1 or croak 'usage: $io->close()';
371 my($io) = @_;
8add82fc 372
cf7fe8a2 373 close($io);
8add82fc
PP
374}
375
376################################################
377## Normal I/O functions.
378##
379
8add82fc 380# flock
8add82fc 381# select
8add82fc
PP
382
383sub opened {
cf7fe8a2 384 @_ == 1 or croak 'usage: $io->opened()';
8add82fc
PP
385 defined fileno($_[0]);
386}
387
388sub fileno {
cf7fe8a2 389 @_ == 1 or croak 'usage: $io->fileno()';
8add82fc
PP
390 fileno($_[0]);
391}
392
393sub getc {
cf7fe8a2 394 @_ == 1 or croak 'usage: $io->getc()';
8add82fc
PP
395 getc($_[0]);
396}
397
8add82fc 398sub eof {
cf7fe8a2 399 @_ == 1 or croak 'usage: $io->eof()';
8add82fc
PP
400 eof($_[0]);
401}
402
403sub print {
cf7fe8a2 404 @_ or croak 'usage: $io->print(ARGS)';
8add82fc
PP
405 my $this = shift;
406 print $this @_;
407}
408
409sub printf {
cf7fe8a2 410 @_ >= 2 or croak 'usage: $io->printf(FMT,[ARGS])';
8add82fc
PP
411 my $this = shift;
412 printf $this @_;
413}
414
1576e684
GA
415sub say {
416 @_ or croak 'usage: $io->say(ARGS)';
417 my $this = shift;
5eb30066
GA
418 local $\ = "\n";
419 print $this @_;
0d863452
RH
420}
421
8add82fc 422sub getline {
cf7fe8a2 423 @_ == 1 or croak 'usage: $io->getline()';
8add82fc
PP
424 my $this = shift;
425 return scalar <$this>;
426}
427
f86702cc
PP
428*gets = \&getline; # deprecated
429
8add82fc 430sub getlines {
cf7fe8a2 431 @_ == 1 or croak 'usage: $io->getlines()';
8add82fc 432 wantarray or
cf7fe8a2 433 croak 'Can\'t call $io->getlines in a scalar context, use $io->getline';
27d4819a 434 my $this = shift;
8add82fc
PP
435 return <$this>;
436}
437
438sub truncate {
cf7fe8a2 439 @_ == 2 or croak 'usage: $io->truncate(LEN)';
8add82fc
PP
440 truncate($_[0], $_[1]);
441}
442
443sub read {
cf7fe8a2 444 @_ == 3 || @_ == 4 or croak 'usage: $io->read(BUF, LEN [, OFFSET])';
8add82fc
PP
445 read($_[0], $_[1], $_[2], $_[3] || 0);
446}
447
27d4819a 448sub sysread {
cf7fe8a2 449 @_ == 3 || @_ == 4 or croak 'usage: $io->sysread(BUF, LEN [, OFFSET])';
27d4819a
JM
450 sysread($_[0], $_[1], $_[2], $_[3] || 0);
451}
452
8add82fc 453sub write {
8fd73a68 454 @_ >= 2 && @_ <= 4 or croak 'usage: $io->write(BUF [, LEN [, OFFSET]])';
8add82fc 455 local($\) = "";
8fd73a68 456 $_[2] = length($_[1]) unless defined $_[2];
8add82fc
PP
457 print { $_[0] } substr($_[1], $_[3] || 0, $_[2]);
458}
459
27d4819a 460sub syswrite {
8fd73a68 461 @_ >= 2 && @_ <= 4 or croak 'usage: $io->syswrite(BUF [, LEN [, OFFSET]])';
2ecf2f18
GB
462 if (defined($_[2])) {
463 syswrite($_[0], $_[1], $_[2], $_[3] || 0);
464 } else {
465 syswrite($_[0], $_[1]);
466 }
27d4819a
JM
467}
468
8add82fc 469sub stat {
cf7fe8a2 470 @_ == 1 or croak 'usage: $io->stat()';
8add82fc
PP
471 stat($_[0]);
472}
473
474################################################
475## State modification functions.
476##
477
478sub autoflush {
cf7fe8a2 479 my $old = new SelectSaver qualify($_[0], caller);
8add82fc
PP
480 my $prev = $|;
481 $| = @_ > 1 ? $_[1] : 1;
482 $prev;
483}
484
485sub output_field_separator {
cf7fe8a2
GS
486 carp "output_field_separator is not supported on a per-handle basis"
487 if ref($_[0]);
8add82fc
PP
488 my $prev = $,;
489 $, = $_[1] if @_ > 1;
490 $prev;
491}
492
493sub output_record_separator {
cf7fe8a2
GS
494 carp "output_record_separator is not supported on a per-handle basis"
495 if ref($_[0]);
8add82fc
PP
496 my $prev = $\;
497 $\ = $_[1] if @_ > 1;
498 $prev;
499}
500
501sub input_record_separator {
cf7fe8a2
GS
502 carp "input_record_separator is not supported on a per-handle basis"
503 if ref($_[0]);
8add82fc
PP
504 my $prev = $/;
505 $/ = $_[1] if @_ > 1;
506 $prev;
507}
508
509sub input_line_number {
91cce263 510 local $.;
76df5e8f 511 () = tell qualify($_[0], caller) if ref($_[0]);
91cce263
PJ
512 my $prev = $.;
513 $. = $_[1] if @_ > 1;
514 $prev;
515}
91cce263 516
8add82fc 517sub format_page_number {
76df5e8f
DM
518 my $old;
519 $old = new SelectSaver qualify($_[0], caller) if ref($_[0]);
8add82fc
PP
520 my $prev = $%;
521 $% = $_[1] if @_ > 1;
522 $prev;
523}
524
525sub format_lines_per_page {
76df5e8f
DM
526 my $old;
527 $old = new SelectSaver qualify($_[0], caller) if ref($_[0]);
8add82fc
PP
528 my $prev = $=;
529 $= = $_[1] if @_ > 1;
530 $prev;
531}
532
533sub format_lines_left {
76df5e8f
DM
534 my $old;
535 $old = new SelectSaver qualify($_[0], caller) if ref($_[0]);
8add82fc
PP
536 my $prev = $-;
537 $- = $_[1] if @_ > 1;
538 $prev;
539}
540
541sub format_name {
76df5e8f
DM
542 my $old;
543 $old = new SelectSaver qualify($_[0], caller) if ref($_[0]);
8add82fc
PP
544 my $prev = $~;
545 $~ = qualify($_[1], caller) if @_ > 1;
546 $prev;
547}
548
549sub format_top_name {
76df5e8f
DM
550 my $old;
551 $old = new SelectSaver qualify($_[0], caller) if ref($_[0]);
8add82fc
PP
552 my $prev = $^;
553 $^ = qualify($_[1], caller) if @_ > 1;
554 $prev;
555}
556
557sub format_line_break_characters {
cf7fe8a2
GS
558 carp "format_line_break_characters is not supported on a per-handle basis"
559 if ref($_[0]);
8add82fc
PP
560 my $prev = $:;
561 $: = $_[1] if @_ > 1;
562 $prev;
563}
564
565sub format_formfeed {
cf7fe8a2
GS
566 carp "format_formfeed is not supported on a per-handle basis"
567 if ref($_[0]);
8add82fc
PP
568 my $prev = $^L;
569 $^L = $_[1] if @_ > 1;
570 $prev;
571}
572
573sub formline {
cf7fe8a2 574 my $io = shift;
8add82fc
PP
575 my $picture = shift;
576 local($^A) = $^A;
577 local($\) = "";
578 formline($picture, @_);
cf7fe8a2 579 print $io $^A;
8add82fc
PP
580}
581
582sub format_write {
cf7fe8a2 583 @_ < 3 || croak 'usage: $io->write( [FORMAT_NAME] )';
8add82fc 584 if (@_ == 2) {
cf7fe8a2 585 my ($io, $fmt) = @_;
90b9a713 586 my $oldfmt = $io->format_name(qualify($fmt,caller));
cf7fe8a2
GS
587 CORE::write($io);
588 $io->format_name($oldfmt);
8add82fc 589 } else {
56f7f34b 590 CORE::write($_[0]);
8add82fc
PP
591 }
592}
593
27d4819a 594sub fcntl {
cf7fe8a2 595 @_ == 3 || croak 'usage: $io->fcntl( OP, VALUE );';
21e970cc
GS
596 my ($io, $op) = @_;
597 return fcntl($io, $op, $_[2]);
27d4819a
JM
598}
599
600sub ioctl {
cf7fe8a2 601 @_ == 3 || croak 'usage: $io->ioctl( OP, VALUE );';
21e970cc
GS
602 my ($io, $op) = @_;
603 return ioctl($io, $op, $_[2]);
27d4819a 604}
8add82fc 605
cf7fe8a2
GS
606# this sub is for compatability with older releases of IO that used
607# a sub called constant to detemine if a constant existed -- GMB
608#
609# The SEEK_* and _IO?BF constants were the only constants at that time
610# any new code should just chech defined(&CONSTANT_NAME)
611
612sub constant {
613 no strict 'refs';
614 my $name = shift;
615 (($name =~ /^(SEEK_(SET|CUR|END)|_IO[FLN]BF)$/) && defined &{$name})
616 ? &{$name}() : undef;
617}
618
619
6facdfff 620# so that flush.pl can be deprecated
cf7fe8a2
GS
621
622sub printflush {
623 my $io = shift;
76df5e8f
DM
624 my $old;
625 $old = new SelectSaver qualify($io, caller) if ref($io);
cf7fe8a2
GS
626 local $| = 1;
627 if(ref($io)) {
628 print $io @_;
629 }
630 else {
631 print @_;
632 }
633}
634
8add82fc 6351;