"Fossies" - the Fresh Open Source Software Archive

Member "install-tl-20200916/tlpkg/tlperl/lib/IO/Handle.pm" (7 Mar 2020, 17142 Bytes) of package /windows/misc/install-tl.zip:


As a special service "Fossies" has tried to format the requested source page into HTML format using (guessed) Perl source code syntax highlighting (style: standard) with prefixed line numbers and code folding option. Alternatively you can here view or download the uninterpreted source code file.

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