FileHandle(3pm)

1FileHandle(3pm)        Perl Programmers Reference Guide        FileHandle(3pm)
2
3
4

NAME

6       FileHandle - supply object methods for filehandles
7

SYNOPSIS

9           use FileHandle;
10
11           $fh = new FileHandle;
12           if ($fh->open("< file")) {
13               print <$fh>;
14               $fh->close;
15           }
16
17           $fh = new FileHandle "> FOO";
18           if (defined $fh) {
19               print $fh "bar\n";
20               $fh->close;
21           }
22
23           $fh = new FileHandle "file", "r";
24           if (defined $fh) {
25               print <$fh>;
26               undef $fh;       # automatically closes the file
27           }
28
29           $fh = new FileHandle "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           ($readfh, $writefh) = FileHandle::pipe;
41
42           autoflush STDOUT 1;
43

DESCRIPTION

45       NOTE: This class is now a front-end to the IO::* classes.
46
47       "FileHandle::new" creates a "FileHandle", which is a reference to a
48       newly created symbol (see the "Symbol" package).  If it receives any
49       parameters, they are passed to "FileHandle::open"; if the open fails,
50       the "FileHandle" object is destroyed.  Otherwise, it is returned to the
51       caller.
52
53       "FileHandle::new_from_fd" creates a "FileHandle" like "new" does.  It
54       requires two parameters, which are passed to "FileHandle::fdopen"; if
55       the fdopen fails, the "FileHandle" object is destroyed.  Otherwise, it
56       is returned to the caller.
57
58       "FileHandle::open" accepts one parameter or two.  With one parameter,
59       it is just a front end for the built-in "open" function.  With two
60       parameters, the first parameter is a filename that may include white‐
61       space or other special characters, and the second parameter is the open
62       mode, optionally followed by a file permission value.
63
64       If "FileHandle::open" receives a Perl mode string (">", "+<", etc.)  or
65       a POSIX fopen() mode string ("w", "r+", etc.), it uses the basic Perl
66       "open" operator.
67
68       If "FileHandle::open" is given a numeric mode, it passes that mode and
69       the optional permissions value to the Perl "sysopen" operator.  For
70       convenience, "FileHandle::import" tries to import the O_XXX constants
71       from the Fcntl module.  If dynamic loading is not available, this may
72       fail, but the rest of FileHandle will still work.
73
74       "FileHandle::fdopen" is like "open" except that its first parameter is
75       not a filename but rather a file handle name, a FileHandle object, or a
76       file descriptor number.
77
78       If the C functions fgetpos() and fsetpos() are available, then "File‐
79       Handle::getpos" returns an opaque value that represents the current
80       position of the FileHandle, and "FileHandle::setpos" uses that value to
81       return to a previously visited position.
82
83       If the C function setvbuf() is available, then "FileHandle::setvbuf"
84       sets the buffering policy for the FileHandle.  The calling sequence for
85       the Perl function is the same as its C counterpart, including the
86       macros "_IOFBF", "_IOLBF", and "_IONBF", except that the buffer parame‐
87       ter specifies a scalar variable to use as a buffer.  WARNING: A vari‐
88       able used as a buffer by "FileHandle::setvbuf" must not be modified in
89       any way until the FileHandle is closed or until "FileHandle::setvbuf"
90       is called again, or memory corruption may result!
91
92       See perlfunc for complete descriptions of each of the following sup‐
93       ported "FileHandle" methods, which are just front ends for the corre‐
94       sponding built-in functions:
95
96           close
97           fileno
98           getc
99           gets
100           eof
101           clearerr
102           seek
103           tell
104
105       See perlvar for complete descriptions of each of the following sup‐
106       ported "FileHandle" methods:
107
108           autoflush
109           output_field_separator
110           output_record_separator
111           input_record_separator
112           input_line_number
113           format_page_number
114           format_lines_per_page
115           format_lines_left
116           format_name
117           format_top_name
118           format_line_break_characters
119           format_formfeed
120
121       Furthermore, for doing normal I/O you might need these:
122
123       $fh->print
124           See "print" in perlfunc.
125
126       $fh->printf
127           See "printf" in perlfunc.
128
129       $fh->getline
130           This works like <$fh> described in "I/O Operators" in perlop except
131           that it's more readable and can be safely called in a list context
132           but still returns just one line.
133
134       $fh->getlines
135           This works like <$fh> when called in a list context to read all the
136           remaining lines in a file, except that it's more readable.  It will
137           also croak() if accidentally called in a scalar context.
138
139       There are many other functions available since FileHandle is descended
140       from IO::File, IO::Seekable, and IO::Handle.  Please see those respec‐
141       tive pages for documentation on more functions.
142

NAME

SYNOPSIS

DESCRIPTION

SEE ALSO