Asynchronous File IO

File module exposes a set of lua interfaces for the functions available in the efio asynchronous file library

platform.file_open(file_name, open_mode);

Opens a file and returns the file handle to be used for read and write operations
Parameters:
    file_name : type string, contains the filename with path which will be opened
    open_mode : mode in which the file will be opened
        "r" : Opens the file in read-only mode
        "w" : Opens the file in write mode and positions the file pointer at the begining of file
        "a" : Opens the file in append mode (reand and write and file pointer at the end)
        "r+" : Opens the file in read-write mode with pointer at the begining
        "w+" : Opens the file in read-write mode after truncating the file, if the file does not
               exist it is created
        "a+" : Opens the file in read-write mode in append mode, if the file does not exist it
               is created
Return values
    fh : file handle using which read and write operations can be achieved
    err: In case of any error during the opening process the error is returned in the second
         return parameter while fh will have null

file_handle.close(file_handle);

Closes a file which is opened via platform.file_open. In case of any unwritten data bufferes they
are synced to the disk before the file is closed.
Parameters:
    file_handle: The file handle that is returned when platform.file_open is called.

file_handle.read_text(file_handle, nbytes);

Reads nbytes of chars from the opened file represented by file_handle
Parameters:
    file_handle: The file handle that is returned when platform.file_open is called.
    nbytes: integer size, which represents the number of bytes to be read

Return values:
    buf: lua string containing the data read, it can be equal to or less than the size specified
         by nbytes
    err: In case of any errors, the error string is returned as the second parameter while buf
         will be nil

file_handle.read_binary(file_handle, buffer, size);

Reads the specified size of data into the allocated buffer

Parameters:
    file_handle: userdata
    buffer: userdata, memory buffer allocated via platform.alloc_buffer
    size: integer
Return:
    bytes: integer, number of bytes  copied

ERROR:
    Exceptions are thrown upon error, which can be caught via mechanism of pcall/xpcall

file_handle.write_text(file_handle, text);

Wrtes the string text passed to the file

Parameters:
    file_handle: userdata
    text: string
Return:
    bytes: number of bytes transferred

ERROR:
    Exceptions are thrown upon error, which can be caught via mechanism of pcall/xpcall

file_handle.write_binary(file_handle, buffer, size);

Wrtes the binary buffer passed to the file

Parameters:
    file_handle: userdata
    buffer: userdata, data buffer previously allocated via platform.alloc_buffer
    size: integer, number of bytes transferred
Return:
    bytes: number of bytes transferred

ERROR:
    Exceptions are thrown upon error, which can be caught via mechanism of pcall/xpcall