5 FileHandle - supply object methods for filehandles
12 if ($fh->open "< file") {
17 $fh = new FileHandle "> FOO";
23 $fh = new FileHandle "file", "r";
26 undef $fh; # automatically closes the file
29 $fh = new FileHandle "file", O_WRONLY|O_APPEND;
32 undef $fh; # automatically closes the file
35 ($readfh, $writefh) = FileHandle::pipe;
41 C<FileHandle::new> creates a C<FileHandle>, which is a reference to a
42 newly created symbol (see the C<Symbol> package). If it receives any
43 parameters, they are passed to C<FileHandle::open>; if the open fails,
44 the C<FileHandle> object is destroyed. Otherwise, it is returned to
47 C<FileHandle::new_from_fd> creates a C<FileHandle> like C<new> does.
48 It requires two parameters, which are passed to C<FileHandle::fdopen>;
49 if the fdopen fails, the C<FileHandle> object is destroyed.
50 Otherwise, it is returned to the caller.
52 C<FileHandle::open> accepts one parameter or two. With one parameter,
53 it is just a front end for the built-in C<open> function. With two
54 parameters, the first parameter is a filename that may include
55 whitespace or other special characters, and the second parameter is
56 the open mode in either Perl form (">", "+<", etc.) or POSIX form
59 C<FileHandle::fdopen> is like C<open> except that its first parameter
60 is not a filename but rather a file handle name, a FileHandle object,
61 or a file descriptor number.
63 See L<perlfunc> for complete descriptions of each of the following
64 supported C<FileHandle> methods, which are just front ends for the
65 corresponding built-in functions:
76 See L<perlvar> for complete descriptions of each of the following
77 supported C<FileHandle> methods:
80 output_field_separator
81 output_record_separator
82 input_record_separator
89 format_line_break_characters
92 Furthermore, for doing normal I/O you might need these:
98 See L<perlfunc/print>.
102 See L<perlfunc/printf>.
106 This works like <$fh> described in L<perlop/"I/O Operators">
107 except that it's more readable and can be safely called in an
108 array context but still returns just one line.
112 This works like <$fh> when called in an array context to
113 read all the remaining lines in a file, except that it's more readable.
114 It will also croak() if accidentally called in a scalar context.
121 L<perlop/"I/O Operators">,
122 L<POSIX/"FileHandle">
126 Due to backwards compatibility, all filehandles resemble objects
127 of class C<FileHandle>, or actually classes derived from that class.
128 They actually aren't. Which means you can't derive your own
129 class from C<FileHandle> and inherit those methods.
142 @ISA = qw(Exporter DynaLoader);
144 @EXPORT = (@Fcntl::EXPORT,
145 qw(_IOFBF _IOLBF _IONBF));
149 output_field_separator
150 output_record_separator
151 input_record_separator
154 format_lines_per_page
158 format_line_break_characters
168 ################################################
169 ## Interaction with the XS.
172 bootstrap FileHandle;
175 if ($AUTOLOAD =~ /::(_?[a-z])/) {
176 $AutoLoader::AUTOLOAD = $AUTOLOAD;
177 goto &AutoLoader::AUTOLOAD
179 my $constname = $AUTOLOAD;
180 $constname =~ s/.*:://;
181 my $val = constant($constname);
182 defined $val or croak "$constname is not a valid FileHandle macro";
183 *$AUTOLOAD = sub { $val };
188 ################################################
189 ## Constructors, destructors.
193 @_ >= 1 && @_ <= 3 or croak 'usage: new FileHandle [FILENAME [,MODE]]';
197 FileHandle::open($fh, @_)
204 @_ == 3 or croak 'usage: new_from_fd FileHandle FD, MODE';
207 FileHandle::fdopen($fh, @_)
217 ################################################
222 @_ and croak 'usage: FileHandle::pipe()';
223 my $readfh = new FileHandle;
224 my $writefh = new FileHandle;
225 pipe($readfh, $writefh)
230 sub _open_mode_string {
232 $mode =~ /^\+?(<|>>?)$/
233 or $mode =~ s/^r(\+?)$/$1</
234 or $mode =~ s/^w(\+?)$/$1>/
235 or $mode =~ s/^a(\+?)$/$1>>/
236 or croak "FileHandle: bad open mode: $mode";
241 @_ >= 2 && @_ <= 4 or croak 'usage: $fh->open(FILENAME [,MODE [,PERMS]])';
242 my ($fh, $file) = @_;
244 my ($mode, $perms) = @_[2, 3];
245 if ($mode =~ /^\d+$/) {
246 defined $perms or $perms = 0666;
247 return sysopen($fh, $file, $mode, $perms);
249 $file = "./" . $file unless $file =~ m#^/#;
250 $file = _open_mode_string($mode) . " $file\0";
256 @_ == 3 or croak 'usage: $fh->fdopen(FD, MODE)';
257 my ($fh, $fd, $mode) = @_;
258 if (ref($fd) =~ /GLOB\(/) {
259 # It's a glob reference; remove the star from its name.
260 ($fd = "".$$fd) =~ s/^\*//;
261 } elsif ($fd =~ m#^\d+$#) {
262 # It's an FD number; prefix with "=".
265 open($fh, _open_mode_string($mode) . '&' . $fd);
269 @_ == 1 or croak 'usage: $fh->close()';
273 ################################################
274 ## Normal I/O functions.
278 @_ == 1 or croak 'usage: $fh->fileno()';
283 @_ == 1 or croak 'usage: $fh->getc()';
288 @_ == 1 or croak 'usage: $fh->gets()';
294 @_ == 1 or croak 'usage: $fh->eof()';
299 @_ == 1 or croak 'usage: $fh->clearerr()';
304 @_ == 3 or croak 'usage: $fh->seek(POS, WHENCE)';
305 seek($_[0], $_[1], $_[2]);
309 @_ == 1 or croak 'usage: $fh->tell()';
314 @_ or croak 'usage: $fh->print([ARGS])';
320 @_ or croak 'usage: $fh->printf([ARGS])';
326 @_ == 1 or croak 'usage: $fh->getline';
328 return scalar <$this>;
332 @_ == 1 or croak 'usage: $fh->getline()';
334 wantarray or croak "Can't call FileHandle::getlines in a scalar context";
338 ################################################
339 ## State modification functions.
343 my $old = new SelectSaver qualify($_[0], caller);
344 my $prev = $OUTPUT_AUTOFLUSH;
345 $OUTPUT_AUTOFLUSH = @_ > 1 ? $_[1] : 1;
349 sub output_field_separator {
350 my $old = new SelectSaver qualify($_[0], caller);
351 my $prev = $OUTPUT_FIELD_SEPARATOR;
352 $OUTPUT_FIELD_SEPARATOR = $_[1] if @_ > 1;
356 sub output_record_separator {
357 my $old = new SelectSaver qualify($_[0], caller);
358 my $prev = $OUTPUT_RECORD_SEPARATOR;
359 $OUTPUT_RECORD_SEPARATOR = $_[1] if @_ > 1;
363 sub input_record_separator {
364 my $old = new SelectSaver qualify($_[0], caller);
365 my $prev = $INPUT_RECORD_SEPARATOR;
366 $INPUT_RECORD_SEPARATOR = $_[1] if @_ > 1;
370 sub input_line_number {
371 my $old = new SelectSaver qualify($_[0], caller);
372 my $prev = $INPUT_LINE_NUMBER;
373 $INPUT_LINE_NUMBER = $_[1] if @_ > 1;
377 sub format_page_number {
378 my $old = new SelectSaver qualify($_[0], caller);
379 my $prev = $FORMAT_PAGE_NUMBER;
380 $FORMAT_PAGE_NUMBER = $_[1] if @_ > 1;
384 sub format_lines_per_page {
385 my $old = new SelectSaver qualify($_[0], caller);
386 my $prev = $FORMAT_LINES_PER_PAGE;
387 $FORMAT_LINES_PER_PAGE = $_[1] if @_ > 1;
391 sub format_lines_left {
392 my $old = new SelectSaver qualify($_[0], caller);
393 my $prev = $FORMAT_LINES_LEFT;
394 $FORMAT_LINES_LEFT = $_[1] if @_ > 1;
399 my $old = new SelectSaver qualify($_[0], caller);
400 my $prev = $FORMAT_NAME;
401 $FORMAT_NAME = qualify($_[1], caller) if @_ > 1;
405 sub format_top_name {
406 my $old = new SelectSaver qualify($_[0], caller);
407 my $prev = $FORMAT_TOP_NAME;
408 $FORMAT_TOP_NAME = qualify($_[1], caller) if @_ > 1;
412 sub format_line_break_characters {
413 my $old = new SelectSaver qualify($_[0], caller);
414 my $prev = $FORMAT_LINE_BREAK_CHARACTERS;
415 $FORMAT_LINE_BREAK_CHARACTERS = $_[1] if @_ > 1;
419 sub format_formfeed {
420 my $old = new SelectSaver qualify($_[0], caller);
421 my $prev = $FORMAT_FORMFEED;
422 $FORMAT_FORMFEED = $_[1] if @_ > 1;