NAME

File::Open - wrap open/sysopen and give them a nice and simple interface

SYNOPSIS

use File::Open qw(fopen fopen_nothrow fsysopen fsysopen_nothrow);

my $fh = fopen $file;
my $fh = fopen $file, $mode;
my $fh = fopen $file, $mode, $layers;

my $fh = fopen_nothrow $file or die "$0: $file: $!\n";
my $fh = fopen_nothrow $file, $mode or die "$0: $file: $!\n";
my $fh = fopen_nothrow $file, $mode, $layers or die "$0: $file: $!\n";

my $fh = fsysopen $file, $mode;
my $fh = fsysopen $file, $mode, \%flags;

my $fh = fsysopen_nothrow $file, $mode or die "$0: $file: $!\n";
my $fh = fsysopen_nothrow $file, $mode, \%flags or die "$0: $file: $!\n";

DESCRIPTION

This module provides convenience wrappers around open and sysopen for opening simple files. Nothing is exported by default; you have to specify every function you want to import explicitly.

Functions

fopen FILE

fopen FILE, MODE

fopen FILE, MODE, LAYERS

Opens FILE and returns a filehandle. If the open fails, it throws an exception of the form "$program: $filename: $!\n".

MODE is a string specifying how the file should be opened. The following values are supported:

'r', '<'

Open the file for reading.

'w', '>'

Open the file for writing. If the file exists, wipe out its contents and make it empty; if it doesn't exist, create it.

'a', '>>'

Open the file for appending. If the file doesn't exist, create it. All writes will go to the end of the file.

'r+', '+<'

Open the file for reading (like 'r') but also allow writes.

'w+', '+>'

Open the file for writing (like 'w') but also allow reads.

'a+', '+>>'

Open the file for appending (like 'a') but also allow reads.

In addition you can append a 'b' to each of the mode strings listed above. This will cause binmode to be called on the filehandle.

If you don't specify a MODE, it defaults to 'r'.

If you pass LAYERS, fopen will call binmode $fh, LAYERS on the newly opened filehandle. This gives you greater control than the simple 'b' in MODE. For example, to read from a UTF-8 file:

my $fh = fopen $file, 'r', ':encoding(UTF-8)';
while (my $line = readline $fh) {
    ...
}

See PerlIO and Encode::Supported for a list of available layers and encoding names, respectively.

fopen_nothrow FILE

fopen_nothrow FILE, MODE

fopen_nothrow FILE, MODE, LAYERS

Works exactly like fopen but if the open fails it simply returns undef.

fsysopen FILE, MODE

fsysopen FILE, MODE, FLAGS

Uses the more low-level interface of sysopen to open FILE. If it succeeds, it returns a filehandle; if it fails, it throws an exception of the form "$program: $filename: $!\n".

MODE must be 'r', 'w', or 'rw' to open the file for reading, writing, or both reading and writing, respectively (this corresponds to the open flags O_RDONLY, O_WRONLY, and O_RDWR).

You can pass additional flags in FLAGS, which must be a hash reference. The hash keys are strings (specifying the flag) and the values are booleans (indicating whether the flag should be off (default) or on) - with one exception. The exception is the 'creat' flag; if set, its value must be a number that specifies the permissions of the newly created file. See "umask" in perlfunc for details.

The following flags are recognized:

'append' - sets O_APPEND

'async' - sets O_ASYNC

'creat' - sets O_CREAT and specifies file permissions

'direct' - sets O_DIRECT

'directory' - sets O_DIRECTORY

'excl' - sets O_EXCL

'noatime' - sets O_NOATIME

'noctty' - sets O_NOCTTY

'nofollow' - sets O_NOFOLLOW

'nonblock' - sets O_NONBLOCK

'sync' - sets O_SYNC

'trunc' - sets O_TRUNC

See Fcntl and open(2) for the meaning of these flags. Some of them may not exist on your system; in that case you'll get a runtime exception when you try to specify a non-existent flag.

fsysopen_nothrow FILE, MODE

fsysopen_nothrow FILE, MODE, FLAGS

Works exactly like fsysopen but if the sysopen fails it simply returns undef.

Methods

The returned filehandles behave like IO::Handle objects (actually IO::File objects, which is a subclass of IO::Handle). However, on perl versions before 5.14.0 you have to use IO::Handle; manually before you can call any methods on them. (Current perl versions will do this for you automatically but it doesn't hurt to load IO::Handle anyway.)

Here is a toy example that copies all lines from one file to another, using method calls instead of functions:

 use File::Open qw(fopen);
 use IO::Handle;  # not needed on 5.14+

 my $fh_in  = fopen $file_in,  'r';
 my $fh_out = fopen $file_out, 'w';

 while (defined(my $line = $fh_in->getline)) {
     $fh_out->print($line) or die "$0: $file_out: $!\n";
 }

 $fh_out->close or die "$0: $file_out: $!\n";
 $fh_in->close;

SEE ALSO

"open" in perlfunc, "binmode" in perlfunc, "sysopen" in perlfunc, perlopentut, IO::Handle, Fcntl, open(2)

AUTHOR

Lukas Mai, <l.mai at web.de>

COPYRIGHT & LICENSE

Copyright 2011, 2013 Lukas Mai.

This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.

See http://dev.perl.org/licenses/ for more information.