FF_Open()
Opens file on the specified device, volume or partition (FF_IOMAN object) and returns an FF_FILE object for use with all further FILE I/O transactions.
This FF_FILE object must be closed using FF_Close() after use, this frees all used resources, and ensures that all modifications to that file are physically written to the disk.
Contents |
Prototype
FF_FILE *FF_Open(FF_IOMAN *pIoman, const FF_T_INT8 *path, FF_T_UINT8 Mode, FF_ERROR *pError);
Back to API.
Parameters
pIoman
Pointer to an FF_IOMAN object, as returned from the FF_CreateIOMAN() function. FF_Open() can only be used once the FF_IOMAN object has been fully initialised and mounted. See FF_MountPartition() and FF_RegisterBlkDevice().
path
The path to the file to be opened. This is an ASCII string, and always begins with a '\' or '/', hence FullFAT only deals with absolute paths. FullFAT considers a working directory to be a part of an operating system, and not a filesystem driver. Therefore to separate concerns, we recommend that the developer do this themselves. See the demo for a simple working directory implementation. Also see WorkingDIR.
Mode
Mode defines several bit masks. It is however simple to just place a call to FF_GetModeBits() here, if you wish to use standard fopen() mode strings.
Alternatively, see this excerpt from the in-source documentation:
/**
* FF_Open() Mode Information
* - FF_MODE_WRITE
* - Allows WRITE access to the file.
* .
* - FF_MODE_READ
* - Allows READ access to the file.
* .
* - FF_MODE_CREATE
* - Create file if it doesn't exist.
* .
* - FF_MODE_TRUNCATE
* - Erase the file if it already exists and overwrite.
* *
* - FF_MODE_APPEND
* - Causes all writes to occur at the end of the file. (Its impossible to overwrite other data in a file with this flag set).
* .
* .
*
* Some sample modes:
* - (FF_MODE_WRITE | FF_MODE_CREATE | FF_MODE_TRUNCATE)
* - Write access to the file. (Equivalent to "w").
* .
* - (FF_MODE_WRITE | FF_MODE_READ)
* - Read and Write access to the file. (Equivalent to "rb+").
* .
* - (FF_MODE_WRITE | FF_MODE_READ | FF_MODE_APPEND | FF_MODE_CREATE)
* - Read and Write append mode access to the file. (Equivalent to "a+").
* .
* .
* Be careful when choosing modes. For those using FF_Open() at the application layer
* its best to use the provided FF_GetModeBits() function, as this complies to the same
* behaviour as the stdio.h fopen() function.
*
**/pError
A pointer to an FF_ERROR variable. This can be NULL if you aren't checking for errors. The error code returned from here, can be passed to FF_GetErrMessage() to get a useful message describing the error.
The value of pError should only be checked if FF_CreateIOMAN() returns NULL.
Return Value
The function returns a non-zero value if it succeeds. If the function fails, it returns NULL (0) and sets the provided FF_ERROR parameter.
Example
#include "fullfat.h" FF_FILE *pF; pF = FF_Open(pIoman, "\\example.txt", FF_GetModeBits("rb+"), NULL); // Or pF = FF_Open(pIoman, "/example.txt", FF_MODE_READ | FF_MODE_WRITE | FF_MODE_CREATE, NULL);
Back to API.
