This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
don't use SelectSaver on IO::Handle->input_*() methods
[perl5.git] / ext / IO / lib / IO / Handle.pm
CommitLineData
774d564b 1
8add82fc
PP
2package IO::Handle;
3
4=head1 NAME
5
27d4819a 6IO::Handle - supply object methods for I/O handles
8add82fc
PP
7
8=head1 SYNOPSIS
9
10 use IO::Handle;
11
12 $fh = new IO::Handle;
774d564b
PP
13 if ($fh->fdopen(fileno(STDIN),"r")) {
14 print $fh->getline;
8add82fc
PP
15 $fh->close;
16 }
17
774d564b
PP
18 $fh = new IO::Handle;
19 if ($fh->fdopen(fileno(STDOUT),"w")) {
20 $fh->print("Some text\n");
8add82fc
PP
21 }
22
3370baa8 23 use IO::Handle '_IOLBF';
8add82fc
PP
24 $fh->setvbuf($buffer_var, _IOLBF, 1024);
25
774d564b
PP
26 undef $fh; # automatically closes the file if it's open
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
39for C<IO::File>
40
27d4819a 41A C<IO::Handle> object is a reference to a symbol (see the C<Symbol> package)
8add82fc 42
27d4819a
JM
43=head1 CONSTRUCTOR
44
45=over 4
46
47=item new ()
8add82fc 48
27d4819a 49Creates a new C<IO::Handle> object.
8add82fc 50
27d4819a
JM
51=item new_from_fd ( FD, MODE )
52
53Creates a C<IO::Handle> like C<new> does.
54It requires two parameters, which are passed to the method C<fdopen>;
55if the fdopen fails, the object is destroyed. Otherwise, it is returned
56to the caller.
57
58=back
59
60=head1 METHODS
8add82fc 61
8add82fc
PP
62See L<perlfunc> for complete descriptions of each of the following
63supported C<IO::Handle> methods, which are just front ends for the
64corresponding built-in functions:
a6006777 65
8add82fc
PP
66 close
67 fileno
68 getc
8add82fc
PP
69 eof
70 read
71 truncate
72 stat
27d4819a
JM
73 print
74 printf
75 sysread
76 syswrite
8add82fc
PP
77
78See L<perlvar> for complete descriptions of each of the following
79supported C<IO::Handle> methods:
80
81 autoflush
82 output_field_separator
83 output_record_separator
84 input_record_separator
85 input_line_number
86 format_page_number
87 format_lines_per_page
88 format_lines_left
89 format_name
90 format_top_name
91 format_line_break_characters
92 format_formfeed
93 format_write
94
95Furthermore, for doing normal I/O you might need these:
96
97=over
98
948ecc40
CS
99=item $fh->fdopen ( FD, MODE )
100
101C<fdopen> is like an ordinary C<open> except that its first parameter
102is not a filename but rather a file handle name, a IO::Handle object,
103or a file descriptor number.
104
105=item $fh->opened
106
107Returns true if the object is currently a valid file descriptor.
108
8add82fc
PP
109=item $fh->getline
110
111This works like <$fh> described in L<perlop/"I/O Operators">
112except that it's more readable and can be safely called in an
113array context but still returns just one line.
114
115=item $fh->getlines
116
117This works like <$fh> when called in an array context to
118read all the remaining lines in a file, except that it's more readable.
119It will also croak() if accidentally called in a scalar context.
120
948ecc40 121=item $fh->ungetc ( ORD )
27d4819a 122
948ecc40
CS
123Pushes a character with the given ordinal value back onto the given
124handle's input stream.
27d4819a
JM
125
126=item $fh->write ( BUF, LEN [, OFFSET }\] )
127
948ecc40 128This C<write> is like C<write> found in C, that is it is the
27d4819a
JM
129opposite of read. The wrapper for the perl C<write> function is
130called C<format_write>.
131
948ecc40 132=item $fh->flush
27d4819a 133
948ecc40
CS
134Flush the given handle's buffer.
135
136=item $fh->error
137
138Returns a true value if the given handle has experienced any errors
139since it was opened or since the last call to C<clearerr>.
140
141=item $fh->clearerr
142
143Clear the given handle's error indicator.
27d4819a 144
8add82fc
PP
145=back
146
948ecc40
CS
147If the C functions setbuf() and/or setvbuf() are available, then
148C<IO::Handle::setbuf> and C<IO::Handle::setvbuf> set the buffering
149policy for an IO::Handle. The calling sequences for the Perl functions
150are the same as their C counterparts--including the constants C<_IOFBF>,
151C<_IOLBF>, and C<_IONBF> for setvbuf()--except that the buffer parameter
152specifies a scalar variable to use as a buffer. WARNING: A variable
153used as a buffer by C<setbuf> or C<setvbuf> must not be modified in any
154way until the IO::Handle is closed or C<setbuf> or C<setvbuf> is called
3370baa8
IZ
155again, or memory corruption may result! Note that you need to import
156the constants C<_IOFBF>, C<_IOLBF>, and C<_IONBF> explicitly.
948ecc40
CS
157
158Lastly, there is a special method for working under B<-T> and setuid/gid
159scripts:
515e7bd7
RR
160
161=over
162
163=item $fh->untaint
164
165Marks the object as taint-clean, and as such data read from it will also
166be considered taint-clean. Note that this is a very trusting action to
167take, and appropriate consideration for the data source and potential
168vulnerability should be kept in mind.
169
170=back
171
27d4819a 172=head1 NOTE
8add82fc 173
27d4819a 174A C<IO::Handle> object is a GLOB reference. Some modules that
8add82fc
PP
175inherit from C<IO::Handle> may want to keep object related variables
176in the hash table part of the GLOB. In an attempt to prevent modules
177trampling on each other I propose the that any such module should prefix
178its variables with its own name separated by _'s. For example the IO::Socket
179module keeps a C<timeout> variable in 'io_socket_timeout'.
180
181=head1 SEE ALSO
182
183L<perlfunc>,
184L<perlop/"I/O Operators">,
774d564b 185L<IO::File>
8add82fc
PP
186
187=head1 BUGS
188
189Due to backwards compatibility, all filehandles resemble objects
190of class C<IO::Handle>, or actually classes derived from that class.
191They actually aren't. Which means you can't derive your own
192class from C<IO::Handle> and inherit those methods.
193
194=head1 HISTORY
195
27d4819a 196Derived from FileHandle.pm by Graham Barr E<lt>F<bodg@tiuk.ti.com>E<gt>
8add82fc
PP
197
198=cut
199
200require 5.000;
7a4c00b4 201use strict;
774d564b 202use vars qw($VERSION $XS_VERSION @EXPORT_OK $AUTOLOAD @ISA);
8add82fc
PP
203use Carp;
204use Symbol;
205use SelectSaver;
206
207require Exporter;
208@ISA = qw(Exporter);
209
56f7f34b 210$VERSION = "1.1505";
774d564b 211$XS_VERSION = "1.15";
8add82fc
PP
212
213@EXPORT_OK = qw(
214 autoflush
215 output_field_separator
216 output_record_separator
217 input_record_separator
218 input_line_number
219 format_page_number
220 format_lines_per_page
221 format_lines_left
222 format_name
223 format_top_name
224 format_line_break_characters
225 format_formfeed
226 format_write
227
228 print
229 printf
230 getline
231 getlines
232
233 SEEK_SET
234 SEEK_CUR
235 SEEK_END
236 _IOFBF
237 _IOLBF
238 _IONBF
8add82fc
PP
239);
240
241
242################################################
243## Interaction with the XS.
244##
245
246require DynaLoader;
247@IO::ISA = qw(DynaLoader);
774d564b 248bootstrap IO $XS_VERSION;
8add82fc
PP
249
250sub AUTOLOAD {
251 if ($AUTOLOAD =~ /::(_?[a-z])/) {
252 $AutoLoader::AUTOLOAD = $AUTOLOAD;
253 goto &AutoLoader::AUTOLOAD
254 }
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";
7a4c00b4 259 no strict 'refs';
8add82fc
PP
260 *$AUTOLOAD = sub { $val };
261 goto &$AUTOLOAD;
262}
263
264
265################################################
266## Constructors, destructors.
267##
268
269sub new {
27d4819a
JM
270 my $class = ref($_[0]) || $_[0] || "IO::Handle";
271 @_ == 1 or croak "usage: new $class";
8add82fc
PP
272 my $fh = gensym;
273 bless $fh, $class;
274}
275
276sub new_from_fd {
27d4819a
JM
277 my $class = ref($_[0]) || $_[0] || "IO::Handle";
278 @_ == 3 or croak "usage: new_from_fd $class FD, MODE";
8add82fc 279 my $fh = gensym;
c927212d 280 shift;
8add82fc
PP
281 IO::Handle::fdopen($fh, @_)
282 or return undef;
283 bless $fh, $class;
8add82fc
PP
284}
285
98d4926f
CS
286#
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.
291#
292sub DESTROY {}
7a4c00b4 293
8add82fc
PP
294
295################################################
296## Open and close.
297##
298
299sub _open_mode_string {
300 my ($mode) = @_;
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";
306 $mode;
307}
308
309sub fdopen {
310 @_ == 3 or croak 'usage: $fh->fdopen(FD, MODE)';
311 my ($fh, $fd, $mode) = @_;
312 local(*GLOB);
313
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);
317 *GLOB = *{*$fd};
318 $fd = $n;
319 } elsif ($fd =~ m#^\d+$#) {
320 # It's an FD number; prefix with "=".
321 $fd = "=$fd";
322 }
323
324 open($fh, _open_mode_string($mode) . '&' . $fd)
325 ? $fh : undef;
326}
327
328sub close {
329 @_ == 1 or croak 'usage: $fh->close()';
330 my($fh) = @_;
8add82fc 331
774d564b 332 close($fh);
8add82fc
PP
333}
334
335################################################
336## Normal I/O functions.
337##
338
8add82fc 339# flock
8add82fc 340# select
8add82fc
PP
341
342sub opened {
343 @_ == 1 or croak 'usage: $fh->opened()';
344 defined fileno($_[0]);
345}
346
347sub fileno {
348 @_ == 1 or croak 'usage: $fh->fileno()';
349 fileno($_[0]);
350}
351
352sub getc {
353 @_ == 1 or croak 'usage: $fh->getc()';
354 getc($_[0]);
355}
356
8add82fc
PP
357sub eof {
358 @_ == 1 or croak 'usage: $fh->eof()';
359 eof($_[0]);
360}
361
362sub print {
363 @_ or croak 'usage: $fh->print([ARGS])';
364 my $this = shift;
365 print $this @_;
366}
367
368sub printf {
369 @_ >= 2 or croak 'usage: $fh->printf(FMT,[ARGS])';
370 my $this = shift;
371 printf $this @_;
372}
373
374sub getline {
375 @_ == 1 or croak 'usage: $fh->getline';
376 my $this = shift;
377 return scalar <$this>;
378}
379
f86702cc
PP
380*gets = \&getline; # deprecated
381
8add82fc
PP
382sub getlines {
383 @_ == 1 or croak 'usage: $fh->getline()';
8add82fc 384 wantarray or
27d4819a
JM
385 croak 'Can\'t call $fh->getlines in a scalar context, use $fh->getline';
386 my $this = shift;
8add82fc
PP
387 return <$this>;
388}
389
390sub truncate {
391 @_ == 2 or croak 'usage: $fh->truncate(LEN)';
392 truncate($_[0], $_[1]);
393}
394
395sub read {
396 @_ == 3 || @_ == 4 or croak '$fh->read(BUF, LEN [, OFFSET])';
397 read($_[0], $_[1], $_[2], $_[3] || 0);
398}
399
27d4819a
JM
400sub sysread {
401 @_ == 3 || @_ == 4 or croak '$fh->sysread(BUF, LEN [, OFFSET])';
402 sysread($_[0], $_[1], $_[2], $_[3] || 0);
403}
404
8add82fc
PP
405sub write {
406 @_ == 3 || @_ == 4 or croak '$fh->write(BUF, LEN [, OFFSET])';
407 local($\) = "";
408 print { $_[0] } substr($_[1], $_[3] || 0, $_[2]);
409}
410
27d4819a
JM
411sub syswrite {
412 @_ == 3 || @_ == 4 or croak '$fh->syswrite(BUF, LEN [, OFFSET])';
5f05dabc 413 syswrite($_[0], $_[1], $_[2], $_[3] || 0);
27d4819a
JM
414}
415
8add82fc
PP
416sub stat {
417 @_ == 1 or croak 'usage: $fh->stat()';
418 stat($_[0]);
419}
420
421################################################
422## State modification functions.
423##
424
425sub autoflush {
426 my $old = new SelectSaver qualify($_[0], caller);
427 my $prev = $|;
428 $| = @_ > 1 ? $_[1] : 1;
429 $prev;
430}
431
432sub output_field_separator {
433 my $old = new SelectSaver qualify($_[0], caller);
434 my $prev = $,;
435 $, = $_[1] if @_ > 1;
436 $prev;
437}
438
439sub output_record_separator {
440 my $old = new SelectSaver qualify($_[0], caller);
441 my $prev = $\;
442 $\ = $_[1] if @_ > 1;
443 $prev;
444}
445
446sub input_record_separator {
8add82fc
PP
447 my $prev = $/;
448 $/ = $_[1] if @_ > 1;
449 $prev;
450}
451
452sub input_line_number {
8add82fc
PP
453 my $prev = $.;
454 $. = $_[1] if @_ > 1;
455 $prev;
456}
457
458sub format_page_number {
459 my $old = new SelectSaver qualify($_[0], caller);
460 my $prev = $%;
461 $% = $_[1] if @_ > 1;
462 $prev;
463}
464
465sub format_lines_per_page {
466 my $old = new SelectSaver qualify($_[0], caller);
467 my $prev = $=;
468 $= = $_[1] if @_ > 1;
469 $prev;
470}
471
472sub format_lines_left {
473 my $old = new SelectSaver qualify($_[0], caller);
474 my $prev = $-;
475 $- = $_[1] if @_ > 1;
476 $prev;
477}
478
479sub format_name {
480 my $old = new SelectSaver qualify($_[0], caller);
481 my $prev = $~;
482 $~ = qualify($_[1], caller) if @_ > 1;
483 $prev;
484}
485
486sub format_top_name {
487 my $old = new SelectSaver qualify($_[0], caller);
488 my $prev = $^;
489 $^ = qualify($_[1], caller) if @_ > 1;
490 $prev;
491}
492
493sub format_line_break_characters {
494 my $old = new SelectSaver qualify($_[0], caller);
495 my $prev = $:;
496 $: = $_[1] if @_ > 1;
497 $prev;
498}
499
500sub format_formfeed {
501 my $old = new SelectSaver qualify($_[0], caller);
502 my $prev = $^L;
503 $^L = $_[1] if @_ > 1;
504 $prev;
505}
506
507sub formline {
508 my $fh = shift;
509 my $picture = shift;
510 local($^A) = $^A;
511 local($\) = "";
512 formline($picture, @_);
513 print $fh $^A;
514}
515
516sub format_write {
517 @_ < 3 || croak 'usage: $fh->write( [FORMAT_NAME] )';
518 if (@_ == 2) {
519 my ($fh, $fmt) = @_;
520 my $oldfmt = $fh->format_name($fmt);
56f7f34b 521 CORE::write($fh);
8add82fc
PP
522 $fh->format_name($oldfmt);
523 } else {
56f7f34b 524 CORE::write($_[0]);
8add82fc
PP
525 }
526}
527
27d4819a
JM
528sub fcntl {
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;
533}
534
535sub ioctl {
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;
540}
8add82fc
PP
541
5421;