class File

extends Stream.StdioStream

This class provides a means for accessing a file for reading or writing

Description

Do not create instances of this class directly. The way to read / write a file is to use the File.open or File.create functions which will create an instance and return it for you. For methods that are availible for use please see below and Stream.StdioStream

class contents [NB. Highlighted attributes are static members]
Functions
function create(string,number) - Create a disk file with the specified modes
function create(string) - Create a system file using the flags specified
function length() - Get the length of the file stream
function lock(number,number) - Attempt to gain an advisory lock on the file
function move(string,string) - Move an item from one location to another
function open(string) - Open a system file using the flags specified
function open(string,number) - Open a system file using the flags specified
function pos() - Get the current position in the file
function remove(string) - Delete a name and possibly the file it refers to
function seek(number,number) - Seek to a certain offset in the file from the place specified
function toString() - Read the entire file into a string
function truncate(number) - Truncate the file to the length specified
function unlock() - Removes a lock that was placed with lock()
Variables
variable filename - The name of the file the object wraps

Functions
static function create Click to go up to the list
Create a disk file with the specified modes
Declaration:
    static function create( string filename, number mode )
Description:
This method will overwrite any existing file. The modes are in the form of an octal number eg. 0644 - This has three parts, the 6 and two 4's. The first dictates the access modes for the owner, the second the access modes for the group, and the third, the access modes for everyone else. In the case of 0644, it'll allow read/write for the owner, and read only for everyone else. This is the most common mode. If an object is returned, it'll be a FileStream object with the ability to write to.

object file = File.create( "path/to/file.txt", 0644 );

If passed a using block, it will pass the file object to the block and then close the file afterwards.
Parameters:
    Parameter #1: string filename - The name of the file to create
    Parameter #2: number mode - The modes to use in an octal form
Returns:
    A FileStream object on success, null otherwise

static function create Click to go up to the list
Create a system file using the flags specified
Declaration:
    static function create( string filename )
Description:
This is the method of creating a file in ferite ready to write. To create a file for writing you simply have to do:

object file = File.create( "path/to/file.txt" );

This function is equivalent to the following function call:

object file = File.create( "path/to/file.txt", 0644 );

If passed a using block, it will pass the file object to the block and then close the file afterwards.
Parameters:
    Parameter #1: string filename - The file to create
Returns:
    A FileStream object on success, null otherwise

function length Click to go up to the list
Get the length of the file stream
Declaration:
    function length( )
Returns:
    The length on success or -1 on fail

function lock Click to go up to the list
Attempt to gain an advisory lock on the file
Declaration:
    function lock(number shared, number wait)
Description:
This function attempts to obtain an advisory lock on the associated file using the flock() mechanism. Note that it is only useful if all mechanisms accessing the file also use the same locking mechanism as the OS itself will not enforce the lock. If shared is true, a shared lock will be attempted instead of the default exclusive type. A shared lock is one that multiple processes can share at the same time, but will still cause an attempted exclusive lock to fail. An exclusive lock is one that only one process can posess at a time. If wait is true and the lock is held by another process, the function will wait for the lock to become free and then take it straight away, rather than returning immediately. If an error occurs, it will return -1 and err.str will be set. If the lock attempt is successful, it will return 0. If wait is false and the lock is held by another process, it will return 1. To remove a lock, either call unlock() or close the file. Locks are automatically destroyed if the program exits. Note: this function is not available on all operating systems.
Parameters:
    Parameter #1: number shared - If true, get a shared lock instead of exclusive
    Parameter #2: number wait - If true, wait for the lock instead of failing
Returns:
    -1 on error, 0 on success, 1 if already locked

static function move Click to go up to the list
Move an item from one location to another
Declaration:
    static function move( string oldpath, string newpath )
Parameters:
    Parameter #1: string oldpath - The current location
    Parameter #2: string newpath - The new location
Returns:
    'true' on success, 'false' otherwise and err.str will be set with the error

static function open Click to go up to the list
Open a system file using the flags specified
Declaration:
    static function open( string filename )
Description:
This is the method of opening a file in ferite. To open a file for reading you simply have to do:

object file = File.open( "path/to/file.txt" );

This function is equivalent to the following function call:

object file = File.open( "path/to/file.txt", FileSystem.O_RDONLY );

If passed a using block, it will pass the file object to the block and then close the file afterwards.
Parameters:
    Parameter #1: string filename - The file to open
Returns:
    A FileStream object on success, null otherwise

static function open Click to go up to the list
Open a system file using the flags specified
Declaration:
    static function open( string filename, number flags )
Description:
This is the method of opening a file in ferite. Use the O_ variables in the FileSystem namespace to create the flags to pass. It will return a File object which will allow for clean interaction of the file, please see FileStream for more information. To open a file for reading you simply have to do:

object file = File.open( "path/to/file.txt", FileSystem.O_RDONLY );

It is possible for you to pass this function a block that takes one argument. The block will be passed a File object. Once the block has finished executing the file will be closed and the function will return null.
Parameters:
    Parameter #1: string filename - The file to open
    Parameter #2: number flags - Bit and'd flags
Returns:
    A FileStream object on success, null otherwise

function pos Click to go up to the list
Get the current position in the file
Declaration:
    function pos( )
Returns:
    The offset on success, or -1 on fail

static function remove Click to go up to the list
Delete a name and possibly the file it refers to
Declaration:
    static function remove( string filename )
Parameters:
    Parameter #1: string filename - The name to delete
Returns:
    'true' on success, 'false' otherwise and err.str will be set with the error

function seek Click to go up to the list
Seek to a certain offset in the file from the place specified
Declaration:
    function seek( number offset, number whence )
Description:
The whence parameter can be one of Stream.SEEK_SET (offset relative to start of file), Stream.SEEK_CUR (offset relative to current position), or Stream.SEEK_END (offset relative to the end of the file).
Parameters:
    Parameter #1: number offset - The offset to seek to
    Parameter #2: number whence - How the offset should be interpreted
Returns:
    The new offset on success, -1 on error

function toString Click to go up to the list
Read the entire file into a string
Returns:
    The file contents

function truncate Click to go up to the list
Truncate the file to the length specified
Declaration:
    function truncate( number length )
Parameters:
    Parameter #1: number length - The length to use
Returns:
    'true' on sucess, 'false' otherwise with err.str being set

function unlock Click to go up to the list
Removes a lock that was placed with lock()
Declaration:
    function unlock()
Description:
This function removes an advisory lock on the associated file which was created by the lock() function. If an error occurs, false is returned and err.str is set.
Returns:
    true on success or false on error

Variables
string filename Click to go up to the list
The name of the file the object wraps

Automatically generated at 12:07PM, Wednesday 25 May 2005 by feritedoc.