1IO::Handle(3pm) Perl Programmers Reference Guide IO::Handle(3pm)
2
6 IO::Handle - supply object methods for I/O handles
7
9 use IO::Handle;
10 $io = new IO::Handle;
12 if ($io->fdopen(fileno(STDIN),"r")) {
13 print $io->getline;
14 $io->close;
15 }
16 $io = new IO::Handle;
18 if ($io->fdopen(fileno(STDOUT),"w")) {
19 $io->print("Some text\n");
20 }
21 # 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 undef $io; # automatically closes the file if it's open
27 autoflush STDOUT 1;
29
31 "IO::Handle" is the base class for all other IO handle classes. It is
32 not intended that objects of "IO::Handle" would be created directly,
33 but instead "IO::Handle" is inherited from by several other classes in
34 the IO hierarchy.
35 If you are reading this documentation, looking for a replacement for
37 the "FileHandle" package, then I suggest you read the documentation for
38 "IO::File" too.
39
41 new ()
42 Creates a new "IO::Handle" object.
43 new_from_fd ( FD, MODE )
45 Creates an "IO::Handle" like "new" does. It requires two parame‐
46 ters, which are passed to the method "fdopen"; if the fdopen fails,
47 the object is destroyed. Otherwise, it is returned to the caller.
48
50 See perlfunc for complete descriptions of each of the following sup‐
51 ported "IO::Handle" methods, which are just front ends for the corre‐
52 sponding built-in functions:
53 $io->close
55 $io->eof
56 $io->fileno
57 $io->format_write( [FORMAT_NAME] )
58 $io->getc
59 $io->read ( BUF, LEN, [OFFSET] )
60 $io->print ( ARGS )
61 $io->printf ( FMT, [ARGS] )
62 $io->stat
63 $io->sysread ( BUF, LEN, [OFFSET] )
64 $io->syswrite ( BUF, [LEN, [OFFSET]] )
65 $io->truncate ( LEN )
66 See perlvar for complete descriptions of each of the following sup‐
68 ported "IO::Handle" methods. All of them return the previous value of
69 the attribute and takes an optional single argument that when given
70 will set the value. If no argument is given the previous value is
71 unchanged (except for $io->autoflush will actually turn ON autoflush by
72 default).
73 $io->autoflush ( [BOOL] ) $⎪
75 $io->format_page_number( [NUM] ) $%
76 $io->format_lines_per_page( [NUM] ) $=
77 $io->format_lines_left( [NUM] ) $-
78 $io->format_name( [STR] ) $~
79 $io->format_top_name( [STR] ) $^
80 $io->input_line_number( [NUM]) $.
81 The following methods are not supported on a per-filehandle basis.
83 IO::Handle->format_line_break_characters( [STR] ) $:
85 IO::Handle->format_formfeed( [STR]) $^L
86 IO::Handle->output_field_separator( [STR] ) $,
87 IO::Handle->output_record_separator( [STR] ) $\
88 IO::Handle->input_record_separator( [STR] ) $/
90 Furthermore, for doing normal I/O you might need these:
92 $io->fdopen ( FD, MODE )
94 "fdopen" is like an ordinary "open" except that its first parameter
95 is not a filename but rather a file handle name, an IO::Handle
96 object, or a file descriptor number.
97 $io->opened
99 Returns true if the object is currently a valid file descriptor,
100 false otherwise.
101 $io->getline
103 This works like <$io> described in "I/O Operators" in perlop except
104 that it's more readable and can be safely called in a list context
105 but still returns just one line. If used as the conditional
106 +within a "while" or C-style "for" loop, however, you will need to
107 +emulate the functionality of <$io> with "defined($_ = $io->get‐
108 line)".
109 $io->getlines
111 This works like <$io> when called in a list context to read all the
112 remaining lines in a file, except that it's more readable. It will
113 also croak() if accidentally called in a scalar context.
114 $io->ungetc ( ORD )
116 Pushes a character with the given ordinal value back onto the given
117 handle's input stream. Only one character of pushback per handle
118 is guaranteed.
119 $io->write ( BUF, LEN [, OFFSET ] )
121 This "write" is like "write" found in C, that is it is the opposite
122 of read. The wrapper for the perl "write" function is called "for‐
123 mat_write".
124 $io->error
126 Returns a true value if the given handle has experienced any errors
127 since it was opened or since the last call to "clearerr", or if the
128 handle is invalid. It only returns false for a valid handle with no
129 outstanding errors.
130 $io->clearerr
132 Clear the given handle's error indicator. Returns -1 if the handle
133 is invalid, 0 otherwise.
134 $io->sync
136 "sync" synchronizes a file's in-memory state with that on the
137 physical medium. "sync" does not operate at the perlio api level,
138 but operates on the file descriptor (similar to sysread, sysseek
139 and systell). This means that any data held at the perlio api level
140 will not be synchronized. To synchronize data that is buffered at
141 the perlio api level you must use the flush method. "sync" is not
142 implemented on all platforms. Returns "0 but true" on success,
143 "undef" on error, "undef" for an invalid handle. See fsync(3c).
144 $io->flush
146 "flush" causes perl to flush any buffered data at the perlio api
147 level. Any unread data in the buffer will be discarded, and any
148 unwritten data will be written to the underlying file descriptor.
149 Returns "0 but true" on success, "undef" on error.
150 $io->printflush ( ARGS )
152 Turns on autoflush, print ARGS and then restores the autoflush sta‐
153 tus of the "IO::Handle" object. Returns the return value from
154 print.
155 $io->blocking ( [ BOOL ] )
157 If called with an argument "blocking" will turn on non-blocking IO
158 if "BOOL" is false, and turn it off if "BOOL" is true.
159 "blocking" will return the value of the previous setting, or the
161 current setting if "BOOL" is not given.
162 If an error occurs "blocking" will return undef and $! will be set.
164 If the C functions setbuf() and/or setvbuf() are available, then
166 "IO::Handle::setbuf" and "IO::Handle::setvbuf" set the buffering policy
167 for an IO::Handle. The calling sequences for the Perl functions are
168 the same as their C counterparts--including the constants "_IOFBF",
169 "_IOLBF", and "_IONBF" for setvbuf()--except that the buffer parameter
170 specifies a scalar variable to use as a buffer. You should only change
171 the buffer before any I/O, or immediately after calling flush.
172 WARNING: The IO::Handle::setvbuf() is not available by default on Perls
174 5.8.0 and later because setvbuf() is rather specific to using the stdio
175 library, while Perl prefers the new perlio subsystem instead.
176 WARNING: A variable used as a buffer by "setbuf" or "setvbuf" must not
178 be modified in any way until the IO::Handle is closed or "setbuf" or
179 "setvbuf" is called again, or memory corruption may result! Remember
180 that the order of global destruction is undefined, so even if your buf‐
181 fer variable remains in scope until program termination, it may be
182 undefined before the file IO::Handle is closed. Note that you need to
183 import the constants "_IOFBF", "_IOLBF", and "_IONBF" explicitly. Like
184 C, setbuf returns nothing. setvbuf returns "0 but true", on success,
185 "undef" on failure.
186 Lastly, there is a special method for working under -T and setuid/gid
188 scripts:
189 $io->untaint
191 Marks the object as taint-clean, and as such data read from it will
192 also be considered taint-clean. Note that this is a very trusting
193 action to take, and appropriate consideration for the data source
194 and potential vulnerability should be kept in mind. Returns 0 on
195 success, -1 if setting the taint-clean flag failed. (eg invalid
196 handle)
197
199 An "IO::Handle" object is a reference to a symbol/GLOB reference (see
200 the "Symbol" package). Some modules that inherit from "IO::Handle" may
201 want to keep object related variables in the hash table part of the
202 GLOB. In an attempt to prevent modules trampling on each other I pro‐
203 pose the that any such module should prefix its variables with its own
204 name separated by _'s. For example the IO::Socket module keeps a "time‐
205 out" variable in 'io_socket_timeout'.
206
208 perlfunc, "I/O Operators" in perlop, IO::File
209
211 Due to backwards compatibility, all filehandles resemble objects of
212 class "IO::Handle", or actually classes derived from that class. They
213 actually aren't. Which means you can't derive your own class from
214 "IO::Handle" and inherit those methods.
215
217 Derived from FileHandle.pm by Graham Barr <gbarr@pobox.com>
218perl v5.8.8 2001-09-21 IO::Handle(3pm)