Documentation

Mistake on this page? Email us
Functions
pal_plat_fileSystem.h File Reference

PAL file system - platform. This file contains the file system APIs that need to be implemented in the platform layer. More...

#include "pal_fileSystem.h"

Go to the source code of this file.

Functions

palStatus_t pal_plat_fsMkdir (const char *pathName)
 This function attempts to create a directory named pathName. More...
 
palStatus_t pal_plat_fsRmdir (const char *pathName)
 This function deletes a directory. More...
 
palStatus_t pal_plat_fsFopen (const char *pathName, pal_fsFileMode_t mode, palFileDescriptor_t *fd)
 This function opens the file whose name is specified in the parameter pathName and associates it with a stream that can be identified in future operations by the fd pointer returned. More...
 
palStatus_t pal_plat_fsFclose (palFileDescriptor_t *fd)
 This function closes an open file object. More...
 
palStatus_t pal_plat_fsFread (palFileDescriptor_t *fd, void *buffer, size_t numOfBytes, size_t *numberOfBytesRead)
 This function reads an array of bytes from the stream and stores them in the block of memory specified by the buffer. More...
 
palStatus_t pal_plat_fsFwrite (palFileDescriptor_t *fd, const void *buffer, size_t numOfBytes, size_t *numberOfBytesWritten)
 This function starts to write data from the buffer to the file at the position pointed by the read/write pointer. More...
 
palStatus_t pal_plat_fsFseek (palFileDescriptor_t *fd, off_t offset, pal_fsOffset_t whence)
 This function moves the file read/write pointer without any read/write operation to the file. More...
 
palStatus_t pal_plat_fsFtell (palFileDescriptor_t *fd, off_t *pos)
 This function gets the current read/write pointer of a file. More...
 
palStatus_t pal_plat_fsUnlink (const char *pathName)
 This function deletes a single file from the file system. More...
 
palStatus_t pal_plat_fsRmFiles (const char *pathName)
 This function deletes all files in a folder from the file system (FLAT remove only). More...
 
palStatus_t pal_plat_fsCpFolder (const char *pathNameSrc, char *pathNameDest)
 This function copies all files from a source folder to a destination folder (FLAT copy only). More...
 
const char * pal_plat_fsGetDefaultRootFolder (pal_fsStorageID_t dataID)
 This function gets the default value for the root directory. More...
 
size_t pal_plat_fsSizeCheck (const char *stringToChk)
 This function finds the length of the string received. More...
 
palStatus_t pal_plat_fsFormat (pal_fsStorageID_t dataID)
 This function formats the chosen SD partition. More...
 

Detailed Description

PAL file system - platform. This file contains the file system APIs that need to be implemented in the platform layer.

Note
You need to add the prefix of the ESFS folder root stored in g_esfsRootFolder to all files and folders. To change this, call pal_plat_fsSetEsfsRootFolder().

Function Documentation

palStatus_t pal_plat_fsCpFolder ( const char *  pathNameSrc,
char *  pathNameDest 
)

This function copies all files from a source folder to a destination folder (FLAT copy only).

Parameters
[in]pathNameSrcA pointer to a null-terminated string that specifies the source folder.
[in]pathNameDestA pointer to a null-terminated string that specifies the destination folder. The destination folder MUST exist.
Returns
PAL_SUCCESS upon a successful operation.
PAL_FILE_SYSTEM_ERROR - see the error code description palError_t.
Note
Both folders must not be open. If a folder does not exist the function fails.
The process copies one file at a time until all files are copied.
The function does not copy a directory found in the path.
palStatus_t pal_plat_fsFclose ( palFileDescriptor_t fd)

This function closes an open file object.

Parameters
[in]fdA pointer to the open file object structure to be closed.
Returns
PAL_SUCCESS upon a successful operation. return PAL_FILE_SYSTEM_ERROR - see the error code palError_t.
Note
After the successful execution of the function, the file object is no longer valid and it can be discarded.
In some platforms, this function needs to free the file descriptor memory.
palStatus_t pal_plat_fsFopen ( const char *  pathName,
pal_fsFileMode_t  mode,
palFileDescriptor_t fd 
)

This function opens the file whose name is specified in the parameter pathName and associates it with a stream that can be identified in future operations by the fd pointer returned.

Parameters
[out]fdA file descriptor for the file entered in the pathName.
[in]*pathNameA pointer to the null-terminated string that specifies the file name to open or create.
[in]modeA mode flag that specifies the type of access and open method for the file.
Returns
PAL_SUCCESS upon a successful operation.
PAL_FILE_SYSTEM_ERROR - see the error code description palError_t.
Note
The folder path must end with "/".
If necessary, the platform layer allocates memory for the file descriptor. The structure pal_plat_fclose() frees that buffer.
The mode flags sent to this function are normalized to pal_fsFileMode_t and each platform needs to replace them with the proper values.
palStatus_t pal_plat_fsFormat ( pal_fsStorageID_t  dataID)

This function formats the chosen SD partition.

Mapping the ID to an actual partition is done in the porting layer.

Parameters
[in]dataIDThe ID of the partition to be formatted.
Returns
PAL_SUCCESS upon a successful operation.
PAL_FILE_SYSTEM_ERROR - see the error code description palError_t.
palStatus_t pal_plat_fsFread ( palFileDescriptor_t fd,
void *  buffer,
size_t  numOfBytes,
size_t *  numberOfBytesRead 
)

This function reads an array of bytes from the stream and stores them in the block of memory specified by the buffer.

The position indicator of the stream is advanced by the total amount of bytes read.

Parameters
[in]fdA pointer to the open file object structure.
[in]bufferA buffer for storing the read data.
[in]numOfBytesThe number of bytes to read.
[out]numberOfBytesReadThe number of bytes read.
Returns
PAL_SUCCESS upon a successful operation.
PAL_FILE_SYSTEM_ERROR - see the error code description palError_t.
Note
After successful execution of the function, numberOfBytesRead should be checked to detect end of the file. If numberOfBytesRead is less than numOfBytes, the read/write pointer has reached the end of the file during the read operation or an error has occurred.
palStatus_t pal_plat_fsFseek ( palFileDescriptor_t fd,
off_t  offset,
pal_fsOffset_t  whence 
)

This function moves the file read/write pointer without any read/write operation to the file.

Parameters
[in]fdA pointer to the open file object structure.
[in]offsetThe byte offset from whence to set the read/write pointer.
[out]whenceThe offset is relative to this.
Note
- The whence options are:
  1. PAL_ERR_FS_SEEKSET - relative to the start of the file.
  2. PAL_ERR_FS_SEEKCUR - relative to the current position indicator.
  3. PAL_ERR_FS_SEEKEND - relative to the end-of-file.
In some systems, there is no whence argument. If you need to implement the whence argument:
PAL_ERR_FS_SEEKEND - The function first finds the length of the file, then subtracts the file length from the position to find the relative path from the beginning.
PAL_ERR_FS_SEEKCUR - The function finds the current stream position and calculates the relative path from the file start.
In both options, fseek() needs to verify that the offset is smaller than the file end or start.
Returns
PAL_SUCCESS upon a successful operation.
PAL_FILE_SYSTEM_ERROR - see the error code description palError_t.
palStatus_t pal_plat_fsFtell ( palFileDescriptor_t fd,
off_t *  pos 
)

This function gets the current read/write pointer of a file.

Parameters
[in]fdA pointer to the open file object structure.
[out]posA pointer to a variable that receives the current file position.
Returns
PAL_SUCCESS upon a successful operation.
PAL_FILE_SYSTEM_ERROR - see the error code description palError_t.
palStatus_t pal_plat_fsFwrite ( palFileDescriptor_t fd,
const void *  buffer,
size_t  numOfBytes,
size_t *  numberOfBytesWritten 
)

This function starts to write data from the buffer to the file at the position pointed by the read/write pointer.

Parameters
[in]fdA pointer to the open file object structure.
[in]bufferA pointer to the data to be written.
[in]numOfBytesThe number of bytes to write.
[out]numberOfBytesWrittenThe number of bytes written.
Returns
PAL_SUCCESS upon a successful operation.
PAL_FILE_SYSTEM_ERROR - see the error code palError_t.
Note
The read/write pointer advances with number of bytes written. After successful execution of the function,
numberOfBytesWritten should be checked to detect if the disk is full. If numberOfBytesWritten is less than numOfBytes, the volume became full during the write operation.
const char* pal_plat_fsGetDefaultRootFolder ( pal_fsStorageID_t  dataID)

This function gets the default value for the root directory.

Parameters
[in]dataID- ID of the data to get the root folder for.
Returns
Pointer to the default path.
palStatus_t pal_plat_fsMkdir ( const char *  pathName)

This function attempts to create a directory named pathName.

Parameters
[in]*pathNameA pointer to the null-terminated string that specifies the directory name to create.
Returns
PAL_SUCCESS upon a successful operation.
PAL_FILE_SYSTEM_ERROR - see the error code description palError_t.
Note
To remove a directory use PAL_ERR_FS_rmdir.

Example

ret = PAL_ERR_FS_mkdir("Dir1");
if(!ret)
{
//Error
}
palStatus_t pal_plat_fsRmdir ( const char *  pathName)

This function deletes a directory.

Parameters
[in]*pathNameA pointer to the null-terminated string that specifies the name of the directory to be deleted.
Returns
PAL_SUCCESS upon a successful operation.
PAL_FILE_SYSTEM_ERROR - see the error code description palError_t.
Note
The directory to be deleted must be Empty and closed. The folder path must end with "/". If given .., the function changes the root directory to one directory down and deletes the working directory.
palStatus_t pal_plat_fsRmFiles ( const char *  pathName)

This function deletes all files in a folder from the file system (FLAT remove only).

Parameters
[in]pathNameA pointer to a null-terminated string that specifies the folder.
Returns
PAL_SUCCESS upon a successful operation.
PAL_FILE_SYSTEM_ERROR - see the error code description palError_t.
Note
The folder must not be open and the folder path must end with /.
The process deletes one file at a time by calling pal_plat_fsUnlink until all files are removed.
The function does not remove a directory found in the path.
size_t pal_plat_fsSizeCheck ( const char *  stringToChk)

This function finds the length of the string received.

Parameters
[in]stringToChkA pointer to the string received with a null terminator.
Returns
The size of the string.
palStatus_t pal_plat_fsUnlink ( const char *  pathName)

This function deletes a single file from the file system.

Parameters
[in]pathNameA pointer to a null-terminated string that specifies the file to be removed.
Returns
PAL_SUCCESS upon a successful operation.
PAL_FILE_SYSTEM_ERROR - see the error code description palError_t.
Note
The file must not be open.