```{index} single: open; modes single: read mode single: write mode single: append mode ``` # Reading, writing, appending The three everyday tasks - read an existing file, create one from scratch, add to the end of one - are three different modes of the same [`open`](../../p5/core/perlfunc/open) call. This page shows each in the form that actually belongs in new code. ```{index} single: open; 3-arg form single: open; 2-arg form pair: open; security ``` ## The three-argument form ```perl open my $fh, MODE, EXPR or die "open: $!"; ``` - `my $fh` is a fresh lexical. `open` fills it in with a handle reference when it succeeds; on failure it leaves `$fh` undefined and sets `$!`. - `MODE` is a short string - `"<"`, `">"`, `">>"`, and a handful of others - that says what you want to do. - `EXPR` is the pathname. It is treated as a plain string: leading or trailing whitespace is preserved, and the string is never reinterpreted as a shell command. The older two-argument form (`open $fh, "<$path"`) still works, but it re-parses the string looking for mode characters and for the "magic" pipe syntax. Do not feed it a filename that came from a user. ```{index} single: readline single: diamond operator single: chomp single: close single: $/ ``` ## Reading ```perl my $path = "/etc/hostname"; open my $fh, "<", $path or die "open $path: $!"; while (my $line = <$fh>) { chomp $line; # ... work with $line ... } close $fh or die "close $path: $!"; ``` Two observations that trip up beginners: - `<$fh>` calls [`readline`](../../p5/core/perlfunc/readline) under the hood. Inside a `while` head the result is tested for being defined, not truthy. That matters because a file containing the line `"0\n"` would otherwise stop the loop early. `while (<$fh>)` is a special-case spelling that Perl rewrites to `while (defined($_ = <$fh>))` for you. - `close` can fail. On a read handle that is rare, but on a write handle it is the moment buffered data is finally flushed, so a closing error is a real error. Check it. ```{index} single: slurp mode single: $/; slurp single: local ``` If you want the whole file as one string, slurp it: ```perl open my $fh, "<", $path or die "open $path: $!"; local $/; # undef = slurp mode my $all = <$fh>; close $fh or die "close $path: $!"; ``` The `local $/` is the idiomatic "for the rest of this scope, turn off line splitting". When control leaves the enclosing block, `$/` returns to its previous value. ```{index} single: print; to filehandle single: truncate; on open single: buffered I/O ``` ## Writing (clobber) ```perl open my $fh, ">", $path or die "open $path: $!"; print $fh "first line\n"; print $fh "second line\n"; close $fh or die "close $path: $!"; ``` - `">"` **creates** the file if it does not exist, and **truncates** it to zero bytes if it does. There is no confirmation step. - The filehandle does not need a comma after it in a `print` invocation. `print $fh "text"` is correct; `print $fh, "text"` is a different expression that treats `$fh` as a list element. - Buffered writes are held in memory until `close`, an explicit flush, or the buffer fills. If your program crashes between `print` and `close`, a writer with pending buffered data loses it. Always pair a writing `open` with a checked `close`. ```{index} single: append mode single: PIPE_BUF single: atomic append ``` ## Appending ```perl open my $fh, ">>", $path or die "open $path: $!"; print $fh scalar(localtime), " event\n"; close $fh or die "close $path: $!"; ``` - `">>"` creates the file if needed and positions the write cursor at the end. - On a POSIX kernel, each `write(2)` on an append-mode descriptor starts at the current end of file, so two processes appending to the same log never overwrite each other. A line only stays whole if it goes out in one `write(2)`: a Perl filehandle is buffered and writes whole buffers, which can end in the middle of a line. Turn on autoflush (`$fh->autoflush(1)`) so that each short `print` is one write. `PIPE_BUF` is the size limit for atomic writes to pipes; POSIX gives regular files no such number. ```{index} single: close; error checking single: flush ``` ## Closing as a real step, not a formality A failed `close` on a write handle typically means the kernel refused to flush - out of space, I/O error, network filesystem trouble. Treat it exactly like a failed `print`: ```perl close $fh or die "close $path: $!"; ``` Ignoring it is how "the file looked fine during testing" becomes "production wrote half a log entry and moved on." ```{index} single: read-write mode single: sysopen single: sysread single: syswrite single: atomic rename ``` ## What about read-write? `"+<"` opens a file for both reading and writing, without truncating. It is a real mode and it works, but it is also the source of most "my file came out corrupted" bug reports. If you need random-access reads with in-place overwrites, reach for [`sysopen`](../../p5/core/perlfunc/sysopen), [`sysread`](../../p5/core/perlfunc/sysread), and [`syswrite`](../../p5/core/perlfunc/syswrite) so the buffering layer does not guess at seek positions on your behalf. For almost every job labelled "edit the file", the right answer is write a new file, fsync, rename over the old one. That is the pattern atomic editors use. ## Next With reading, writing, and appending covered, the next question is what the bytes *mean*. See [Encoding and layers](encoding-and-layers).