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