Mdc::FileIO

Mdc::FileIO

Name

FileIO - Disc file read and write methods

Version 1.04b - 3:57 PM 2004-10-06

Synopsis

 use Mdc::FileIO;
 $F = new Mdc::FileIO;
 $err = $F->open($myfile, 'create');
 $F->write($data);
 $F->close;

Description

The FileIO module provides a set of methods to read and write disc files. Built-in safety feature prevents the accidental accessing of files using an absolute pathname or via the parent directory. Runtime errors such as a file not existing or attempting to write to a read-only file will result in an error code being returned. Fatal errors such as supplying a null string for a filename will raise an exception and cause the program to die.

Methods

new

Create a new file object.

 $F = new Mdc::FileIO;
 $F = new Mdc::FileIO( safety => 1 );
Parameters:
safety
Prevent file access to an absolute path or the parent directory. Set value to 1 to enable. Default is 0.

open

Open a file for read, append, overwrite, or create. Returns a zero (0) if successful or an error code if not. See error messages section. If a subsequent open is called, the previous file will be closed.

 $err = $F->open( $filename );
 $err = $F->open( $filename, $mode );

Object properties that may be accessed are:

 $F->{safety}   prevent accessing absolute file path or parent dir
 $F->{eof}      1 if at end of file during read
 $F->{errno}    The last error code
 $F->{error}    The last error message
Modes
read
Open an existing file for reading. Returns error code if file does not exist or if permissions do not allow file to be read by current UID or GID.

create
Create a new file. Returns an error message if file already exists.

append
Open an existing file for appending. Returns an error code if existing file permissions do not allow it to be written to by the current UID or GID. If file does not already exist, a new one will be created.

overwrite
Overwrite an existing file. Returns an error code if existing file permissions do not allow it to be overwritten to by the current UID or GID. If file does not already exist, a new one will be created.

close

Close a currently open file.

 $F->close;

copy

Copy a file. If the file is currently open, it will be closed. Return 1 if copy successful.

 $F->copy( source, destination );

read

Read entire contents of the currently open file and place the data in the referenced scalar variable supplied as the argument. Return 1 if successful or 0 if at end of file.

 $result = $F->read(\$data);

readln

Read one line of data from the currently open file and place the data in the referenced scalar variable supplied as the argument. Return 1 if successful or 0 if at end of file.

 $result = $F->readln(\$data);

eof

Return end-of-file status.

write

Write data to the currently open file. Argument may be a scalar, scalar reference, a list, or a list reference.

 $F->write( SCALAR );
 $F->write( SCALAR REF );
 $F->write( LIST );
 $F->write( LIST REF );

Examples

Create a new file:
 use Mdc::FileIO;
 my $F = new Mdc::FileIO;
 $F->open('myfile.txt','create');
 die $F->{error} if $F->{errno};
 $F->write("My test data\n");
 $F->close;
Read an existing file:
 $F->open('myfile.txt');
 die $F->{error} if $F->{errno};
 $F->read(\my $data);
 $F->close;
 print $data;

Error Codes

 1301   Filename not defined
 1302   Unable to open file
 1303   File does not exist
 1304   File already exists
 1305   Invalid character(s) in filename
 1306   Absolute path not allowed while safety enabled
 1307   Parent path not allowed while safety enabled
 1308   File permissions do not allow read
 1309   File permissions do not allow overwrite
 1310   File permissions do not allow append
 1311   Invalid mode
 1312   Cannot write to unopened file
 1313   Cannot read from unopened file
 1314   File not open for writing
 1315   File not open for reading

Author and Copyright

 Mdc::FileIO Copyright (c) 2004 Mark K Mueller. All rights reserved.
 Mark K Mueller
 PO Box 576705
 Modesto, CA 95357
 http://www.markmueller.com/
MkM 26oct2004