IRIX Base Documentation 2001 May/SGI IRIX Base Documentation 2001 May.iso/usr/share/catman/p_man/cat3/perl5/IO::Handle.z/IO::Handle

Text File | 1998-10-30 | 7.6 KB | 265 lines

IIIIOOOO::::::::HHHHaaaannnnddddlllleeee((((3333))))                                                    IIIIOOOO::::::::HHHHaaaannnnddddlllleeee((((3333))))



NNNNAAAAMMMMEEEE
     IO::Handle - supply object methods for I/O handles

SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
         use IO::Handle;

         $fh = new IO::Handle;
         if ($fh->fdopen(fileno(STDIN),"r")) {
             print $fh->getline;
             $fh->close;
         }

         $fh = new IO::Handle;
         if ($fh->fdopen(fileno(STDOUT),"w")) {
             $fh->print("Some text\n");
         }

         use IO::Handle '_IOLBF';
         $fh->setvbuf($buffer_var, _IOLBF, 1024);

         undef $fh;       # automatically closes the file if it's open

         autoflush STDOUT 1;


DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
     IO::Handle is the base class for all other IO handle classes. It is not
     intended that objects of IO::Handle would be created directly, but
     instead IO::Handle is inherited from by several other classes in the IO
     hierarchy.

     If you are reading this documentation, looking for a replacement for the
     FileHandle package, then I suggest you read the documentation for
     IO::File

     A IO::Handle object is a reference to a symbol (see the Symbol package)

CCCCOOOONNNNSSSSTTTTRRRRUUUUCCCCTTTTOOOORRRR
     new ()
         Creates a new IO::Handle object.

     new_from_fd ( FD, MODE )
         Creates a IO::Handle like new does.  It requires two parameters,
         which are passed to the method fdopen; if the fdopen fails, the
         object is destroyed. Otherwise, it is returned to the caller.

MMMMEEEETTTTHHHHOOOODDDDSSSS
     See the _p_e_r_l_f_u_n_c manpage for complete descriptions of each of the
     following supported IO::Handle methods, which are just front ends for the
     corresponding built-in functions:





                                                                        PPPPaaaaggggeeee 1111






IIIIOOOO::::::::HHHHaaaannnnddddlllleeee((((3333))))                                                    IIIIOOOO::::::::HHHHaaaannnnddddlllleeee((((3333))))



         close
         fileno
         getc
         eof
         read
         truncate
         stat
         print
         printf
         sysread
         syswrite

     See the _p_e_r_l_v_a_r manpage for complete descriptions of each of the
     following supported IO::Handle methods:

         autoflush
         output_field_separator
         output_record_separator
         input_record_separator
         input_line_number
         format_page_number
         format_lines_per_page
         format_lines_left
         format_name
         format_top_name
         format_line_break_characters
         format_formfeed
         format_write

     Furthermore, for doing normal I/O you might need these:

     $fh->fdopen ( FD, MODE )
          fdopen is like an ordinary open except that its first parameter is
          not a filename but rather a file handle name, a IO::Handle object,
          or a file descriptor number.

     $fh->opened
          Returns true if the object is currently a valid file descriptor.

     $fh->getline
          This works like <$fh> described in the section on _I/_O _O_p_e_r_a_t_o_r_s in
          the _p_e_r_l_o_p manpage except that it's more readable and can be safely
          called in an array context but still returns just one line.

     $fh->getlines
          This works like <$fh> when called in an array context to read all
          the remaining lines in a file, except that it's more readable.  It
          will also _c_r_o_a_k() if accidentally called in a scalar context.

     $fh->ungetc ( ORD )
          Pushes a character with the given ordinal value back onto the given
          handle's input stream.



                                                                        PPPPaaaaggggeeee 2222






IIIIOOOO::::::::HHHHaaaannnnddddlllleeee((((3333))))                                                    IIIIOOOO::::::::HHHHaaaannnnddddlllleeee((((3333))))



     $fh->write ( BUF, LEN [, OFFSET }\] )
          This write is like write found in C, that is it is the opposite of
          read. The wrapper for the perl write function is called
          format_write.

     $fh->flush
          Flush the given handle's buffer.

     $fh->error
          Returns a true value if the given handle has experienced any errors
          since it was opened or since the last call to clearerr.

     $fh->clearerr
          Clear the given handle's error indicator.

     If the C functions _s_e_t_b_u_f() and/or _s_e_t_v_b_u_f() are available, then
     IO::Handle::setbuf and IO::Handle::setvbuf set the buffering policy for
     an IO::Handle.  The calling sequences for the Perl functions are the same
     as their C counterparts--including the constants _IOFBF, _IOLBF, and
     _IONBF for _s_e_t_v_b_u_f()--except that the buffer parameter specifies a scalar
     variable to use as a buffer.  WARNING: A variable used as a buffer by
     setbuf or setvbuf must not be modified in any way until the IO::Handle is
     closed or setbuf or setvbuf is called again, or memory corruption may
     result!  Note that you need to import the constants _IOFBF, _IOLBF, and
     _IONBF explicitly.

     Lastly, there is a special method for working under ----TTTT and setuid/gid
     scripts:

     $fh->untaint
          Marks the object as taint-clean, and as such data read from it will
          also be considered taint-clean. Note that this is a very trusting
          action to take, and appropriate consideration for the data source
          and potential vulnerability should be kept in mind.

NNNNOOOOTTTTEEEE
     A IO::Handle object is a GLOB reference. Some modules that inherit from
     IO::Handle may want to keep object related variables in the hash table
     part of the GLOB. In an attempt to prevent modules trampling on each
     other I propose the that any such module should prefix its variables with
     its own name separated by _'s. For example the IO::Socket module keeps a
     timeout variable in 'io_socket_timeout'.

SSSSEEEEEEEE AAAALLLLSSSSOOOO
     the _p_e_r_l_f_u_n_c manpage, the section on _I/_O _O_p_e_r_a_t_o_r_s in the _p_e_r_l_o_p manpage,
     the _I_O::_F_i_l_e manpage

BBBBUUUUGGGGSSSS
     Due to backwards compatibility, all filehandles resemble objects of class
     IO::Handle, or actually classes derived from that class.  They actually
     aren't.  Which means you can't derive your own class from IO::Handle and
     inherit those methods.



                                                                        PPPPaaaaggggeeee 3333






IIIIOOOO::::::::HHHHaaaannnnddddlllleeee((((3333))))                                                    IIIIOOOO::::::::HHHHaaaannnnddddlllleeee((((3333))))



HHHHIIIISSSSTTTTOOOORRRRYYYY
     Derived from FileHandle.pm by Graham Barr <_b_o_d_g@_t_i_u_k._t_i._c_o_m>





















































                                                                        PPPPaaaaggggeeee 4444