Main Page | Modules | Data Structures | Directories | File List | Data Fields | Globals

# Embedded File System

## Data Structures
struct | fsys_time
struct | fsys_stat
struct | fsys_finddata
## Defines
#define | FS_MAXFILES 10
#define | FS_STANDARD_API 0
#define | FS_SUBDIRECTORIES 1
#define | FS_MAXFNAMELEN 256
#define | FSO_RDWR 0x000
#define | FSO_RDONLY 0x001
#define | FSO_WRONLY 0x002
#define | FSO_CREAT 0x004
#define | FSO_TRUNC 0x008
#define | FSO_SEQUENTIAL 0x000
#define | FSO_RANDOM 0x010
#define | FSO_BINARY 0x000
#define | FSO_TEXT 0x020
#define | FSO_EXCL 0x040
#define | FSO_APPEND 0x080
#define | FSS_IFMT 0x00170000
#define | FSS_IFDIR 0x00040000
#define | FSS_IFCHR 0x00020000
#define | FSS_IFIFO 0x00010000
#define | FSS_IFREG 0x00100000
#define | FSS_IREAD 0x00000400
#define | FSS_IWRITE 0x00000200
#define | FSS_IEXEC 0x00000100
#define | FSA_NORMAL 0x00
#define | FSA_RDONLY 0x01
#define | FSA_HIDDEN 0x02
#define | FSA_SYSTEM 0x04
#define | FSA_SUBDIR 0x08
#define | FSA_ARCH 0x10
#define | FSSEEK_SET 0
#define | FSSEEK_CUR 1
#define | FSSEEK_END 2
## Functions
sint_t | fsys_open (const char *filename, const sint_t mode)
sint_t | fsys_opent (char *filename, const sint_t mode)
void | fsys_close (const sint_t file)
sint_t | fsys_write (const sint_t file, const char *buf, const sint_t count)
sint_t | fsys_read (const sint_t file, const char *buf, const sint_t count)
sint_t | fsys_eof (const sint_t file)
sint_t | fsys_seek (const sint_t file, const sint_t position, const sint_t origin)
sint_t | fsys_tell (const sint_t file)
sint_t | fsys_stat (const char *fname, struct fsys_stat *stat)
sint_t | fsys_findfirst (char *filespec, struct fsys_finddata *fileinfo)
sint_t | fsys_findnext (sint_t handle, struct fsys_finddata *fileinfo)
sint_t | fsys_findclose (sint_t handle)
sint_t | fsys_remove (const char *filename)
sint_t | fsys_rename (const char *from, const char *to)
sint_t | fsys_replace (const char *oldfile, const char *newfile)
sint_t | fsys_mkdir (const char *pathname)
sint_t | fsys_rmdir (const char *pathname)
sint_t | fsys_buildPathName (char *outbuf, const char *pathname, const char *filename)
sint_t | fsys_format (u32_t blocksize, u32_t maxFilenameLength)
u32_t | fsys_free (void)
u32_t | fsys_shrinkImage (void *image)
sint_t | fsys_addDriveImage (void *img, sint_t readonly)
sint_t | fsys_init (u32_t size, u32_t blocksize, u32_t maxFilenameLength)
sint_t | fsys_term (void)
void * | fsys_lockAndGetImage (u32_t *size)
void | fsys_unlockImage (void)

## Define Documentation

#define FS_MAXFILES 10

| Set the maximum number of simultanousely opened files. Default is 10.

#define FS_MAXFNAMELEN 256

| Maximum length of a filename

#define FS_STANDARD_API 0

| Set this define to 1 to enable standard I/O function names for open/close/read/write etc.

#define FS_SUBDIRECTORIES 1

| Enable support for 'virtual' subdiretories when set to 1. The filesystem API will be extendet by some subdirectory functions.

#define FSA_ARCH 0x10

| archive file

#define FSA_HIDDEN 0x02

| hidden file

#define FSA_NORMAL 0x00

| normal file - No read/write restrictions

#define FSA_RDONLY 0x01

| read only file

#define FSA_SUBDIR 0x08

| subdirectory

#define FSA_SYSTEM 0x04

| system file

#define FSO_APPEND 0x080

| writes are done at end of file

#define FSO_BINARY 0x000

| file mode is binary (untranslated)

#define FSO_CREAT 0x004

| create new file and open it

#define FSO_EXCL 0x040

| open only if file doesn't already exist

#define FSO_RANDOM 0x010

| file access is primarily random

#define FSO_RDONLY 0x001

| open for reading only

#define FSO_RDWR 0x000

| open for reading and writing

#define FSO_SEQUENTIAL 0x000

| file access is primarily sequential

#define FSO_TEXT 0x020

| file mode is text (translated)

#define FSO_TRUNC 0x008

| open and truncate file to zero length

#define FSO_WRONLY 0x002

| open for writing only

#define FSS_IEXEC 0x00000100

| execute/search permission, owner

#define FSS_IFCHR 0x00020000

| character special

#define FSS_IFDIR 0x00040000

| directory

#define FSS_IFIFO 0x00010000

| pipe

#define FSS_IFMT 0x00170000

| file type mask

#define FSS_IFREG 0x00100000

| regular

#define FSS_IREAD 0x00000400

| read permission, owner

#define FSS_IWRITE 0x00000200

| write permission, owner

#define FSSEEK_CUR 1

| seek starts from current position

#define FSSEEK_END 2

| seek starts from end of file

#define FSSEEK_SET 0

| seek starts at beginning of file

## Function Documentation

sint_t fsys_addDriveImage | ( | void * | img,
|  | sint_t | readonly
| ) |

  | Add an filesystem image to the filesystem. The image can be marked as readonly when the image resides in a non writable (Flash-) ROM. Parameters:
  | img | pointer to the filesystem image
  | readonly | set this flag to nonzero to add a non-writable image.
Returns: zero on success. Note: The filesystem must be initialized before this function can be called. See function fsys_init. If more than one image is added to the filesystem, there might be a conflict with doubled file names. To prevent this issue, you should only add one image directly after calling fsys_init. See also: fsys_init

sint_t fsys_buildPathName | ( | char * | outbuf,
|  | const char * | pathname,
|  | const char * | filename
| ) |

  | Build a valid path string from pathname and filename. Parameters:
  | outbuf | Pointer to a user provided buffer to which the built string will be stored.
  | pathname | name of the path, may include '/..' or '/.'
  | filename | name of the file
Returns: the length of the generated path on success. -1 is returned when no valid path could be built. Note: FS_SUBDIRECTORIES must be set to 1 to have this function compiled in.

void fsys_close | ( | const sint_t | file | ) |

  | Close a file again. This function is equivalent to the one from the runtime library. Parameters:
  | file | Handle to the file to close.
See also: fsys_open, fsys_read, fsys_write

sint_t fsys_eof | ( | const sint_t | file | ) |

  | Tests if the file pointer has reached the end of the file. Parameters:
  | file | Handle to an open file.
Returns: True (1) when the file pointer is at the end of the file, False (0) when there is more data available to be read from the file, or -1 when an error has happened. See also: fsys_open, fsys_read, fsys_write

sint_t fsys_findclose | ( | sint_t | handle | ) |

  | Closes the handle that was returned by fsys_findfirst. This function is equivalent to the one from the runtime library. Parameters:
  | handle | This is the value that was returned by the function fsys_findfirst.
Returns: Zero when at least one more matching file was found, or -1 when no more files are matching. Note that -1 does not denote an error.

sint_t fsys_findfirst | ( | char * | filespec,
|  | struct fsys_finddata * | fileinfo
| ) |

  | Find the first file on the drive. This function is equivalent to the one from the runtime library. Parameters:
  | filespec | A mask specifying the filename that shall be searched for. Only the asterisk wildcard is allowed.
  | fileinfo | Pointer to a user-provided structure that will be filled with the information about the found file.
Returns: On success, when a matching file was found, a handle is returned that can be used for the subsequent call to fsys_findnext or to the final call to fsys_findclose. If no matching file was found, -1 is returned. Note: Do not forget to call fsys_findclose! See also: fsys_findnext, fsys_findclose.

sint_t fsys_findnext | ( | sint_t | handle,
|  | struct fsys_finddata * | fileinfo
| ) |

  | Find the next file on the drive that matches the search mask passed to the function fsys_findfirst. This function is equivalent to the one from the runtime library. Parameters:
  | handle | This is the value that was returned by the function fsys_findfirst.
  | fileinfo | Pointer to a user-provided structure that will be filled with the information about the found file.
Returns: On success, when a matching file was found, zero is returned. When no more files can be found, -1 is returned. Note: Do not forget to call fsys_findclose! See also: fsys_findfirst, fsys_findclose.

sint_t fsys_format | ( | u32_t | blocksize,
|  | u32_t | maxFilenameLength
| ) |

  | Formats the RAM-Disk, and erases all data stored in writeable RAM. Parameters:
  | blocksize | Size in bytes of each data block. Can be set to 0 to take the default value (= 512 bytes, this is the recommended block size.)
  | maxFilenameLength | maximum length a filename can have. This value should be big enough if subdirectories are enabled. But this value should not be greater than 3/4 of the block size. This value may be set to zero to take a default value.
Returns: zero on success. This function may fail when no writable image is present or the given parameters are not valid in its combination.

u32_t fsys_free | ( | void |  | ) |

| Returns the free drive space in bytes. Returns: free space on the drive (in bytes)

sint_t fsys_init | ( | u32_t | size,
|  | u32_t | blocksize,
|  | u32_t | maxFilenameLength
| ) |

  | Initialize the file system. This function must be called before all others. Parameters:
  | size | If this parameter is nonzero, a new and empty RAM based drive image with this size will be created and added to the file system.
  | blocksize | This value is a don't care when size is zero. Otherwise: cluster size (data block size). 512 bytes is the recommended value (this is the default when blocksize is set to zero).
  | maxFilenameLength | This value is a don't care when size is zero. Otherwise, it is the maximum length a filename can have on the drive. When subdirectories are used, this value should be big enough (this is the size of the pathname and filename).
Returns: zero on success. See also: fsys_term, fsys_addDriveImage

void* fsys_lockAndGetImage | ( | u32_t * | size | ) |

  | This function returns a pointer to the RAM based image in memory. The image is locked after this operation, so no file operation will change the image. After processing the image, the function fsys_unlockImage must be called. Parameters:
  | size | Optional. When non NULL, pointer to a variable in which the size (in bytes) of the image will be stored.
Returns: pointer to the filesystem image on success, NULL on error. See also: fsys_unlockImage, fsys_init

sint_t fsys_mkdir | ( | const char * | pathname | ) |

  | Make a new subdirectory. Parameters:
  | pathname | Path and name of the new directory to create.
Returns: zero on success. Note: FS_SUBDIRECTORIES must be set to 1 to have this function compiled in.

sint_t fsys_open | ( | const char * | filename,
|  | const sint_t | mode
| ) |

  | Open a file for read or write access. This function is equivalent to the one from the runtime library. Parameters:
  | filename | Name of the file that shall be opened. No wildcards are allowed.
  | mode | Bitfield of file attributes: FSO_RDWR Open an existing file for reading and writing. FSO_RDONLY Open an existing file for read access only. FSO_WRONLY Open an existing file for write access only. FSO_CREAT Open a file for reading or writing. If the file does not exist, it will be created. You may also use the flags FSO_WRONLY, FSO_EXCL and FSO_TRUNC together with this flag. FSO_EXCL If this flag is set together with FSO_CREAT, a new file will be created and opend for writing, but only when no file with this name just exist. Thus, this flag prevents from overwriting an existing file. FSO_TRUNC Open an existing file for reading or writing. The file size will be set to 0. This flag may be used together with FSO_CREAT to create a fresh new file; an existing file will be overwritten. FSO_APPEND Append new data always to the end of the file. The file pointer is automatically set to the end of the file before a write is performed.
Returns: A file handle on success, or -1 when an error has happened. See also: fsys_close

sint_t fsys_opent | ( | char * | filename,
|  | const sint_t | mode
| ) |

  | Create and open a temporary file. Sometimes it is useful to create a temporary file to store some data for a short time. This function automatically generates an unique file name, creates an empty file and returns the handle to the file. Note that this function is useful in conjunction with fsys_replace to provide dynamic html pages for a http demon. Parameters:
  | filename | Pointer to a user-provided buffer. The name of the temporary file will be copied into this buffer.
  | mode | Mode flags (see fsys_open). Only the flags FSO_WRONLY and FSO_APPEND do make sense, the flag FSO_CREAT is implied by this function.
Returns: A file handle on success, or -1 when an error has happened. See also: fsys_replace, fsys_open, fsys_close

sint_t fsys_read | ( | const sint_t | file,
|  | const char * | buf,
|  | const sint_t | count
| ) |

  | Read a block of data from a file. This function is equivalent to the one from the runtime library. Parameters:
  | file | Handle to the file to read from.
  | buf | Pointer to a user provided buffer that shall be filled with the read data.
  | count | Maximum number of bytes that shall be read.
Returns: The number of bytes that have successfully been read, or -1 when an error has happened. Zero is returned when no more data is available (-> End Of File). See also: fsys_open, fsys_close, fsys_write

sint_t fsys_remove | ( | const char * | filename | ) |

  | Delete a file from a writeable RAM-Drive. Parameters:
  | filename | name of the file to delete, wildcards are not allowed.
Returns: zero on success or -1 on error

sint_t fsys_rename | ( | const char * | from,
|  | const char * | to
| ) |

  | Rename a file in a writable RAM-Drive. Parameters:
  | from | name of the file to rename, wildcards are not allowed.
  | to | new name for the file
Returns: returns zero on success

sint_t fsys_replace | ( | const char * | oldfile,
|  | const char * | newfile
| ) |

  | Replace an old file by a new file. This function can be used to replace a file by a new one, while the old one is still in use. This allows the implementation of http servers that use static and dynamic html pages: A client can load the old dynamic page while the new one is just writing to the drive. When the new file is fully written, the old one is replaced by it. Then the data area of the old file is freed as soon as the last file handle referencing the file is closed. Please see also the function fsys_opent which can be used to create a temporary file for the new dynamic html page. In principle, this replace function does no more than 'rename' and 'delete', but with the exception that it can be applyed on files that are currently in use. Parameters:
  | oldfile | name of the old file that shall be replaced by the new one.
  | newfile | name of the new file. The new file will be renamed to the name of the old file.
Returns: zero on success. See also: fsys_opent

sint_t fsys_rmdir | ( | const char * | pathname | ) |

  | Remove an existing but empty subdirectory. Parameters:
  | pathname | Path and name of the directory to remove.
Returns: zero on success. Note: FS_SUBDIRECTORIES must be set to 1 to have this function compiled in.

sint_t fsys_seek | ( | const sint_t | file,
|  | const sint_t | position,
|  | const sint_t | origin
| ) |

  | Set the file pointer to a new position. This function is equivalent to the one from the runtime library. Parameters:
  | file | Handle to an open file.
  | position | New position of the file pointer. Note that this value denotes a relative position, based on the root position described by the mode flag.
  | origin | Describes the position within the file that is used as base for the calculation of the new file pointer position. One of the following three flags must be used: FSSEEK_SET The new position is calculated from the beginning of the file. FSSEEK_CUR The new position is calculated from the current file pointer position. FSSEEK_END The new position is calculated from the end of the file.
Returns: The new position withing the file on success, or -1 when the function failed. See also: fsys_open, fsys_read, fsys_write

u32_t fsys_shrinkImage | ( | void * | image | ) |

  | Shrink an image to the smallest possible size (remove all unused blocks from the image). This function is useful when a small, ROM-able image shall be generated. Note that this function works best with an unfragmented image file. Parameters:
  | image | pointer to the image
Returns: new size of the image in bytes

sint_t fsys_stat | ( | const char * | fname,
|  | struct fsys_stat * | stat
| ) |

  | Get some status information about a file. This function is equivalent to the one from the runtime library. Parameters:
  | fname | Filename of the file to return the status about.
  | stat | Pointer to a user provided structure that will be filled with the status information. See struct fsys_stat for details.
Returns: Zero on success, -1 denotes an error.

sint_t fsys_tell | ( | const sint_t | file | ) |

sint_t fsys_term | ( | void |  | ) |

| Terminate the filesystem. All memory allocated by the filesystem will be freed. Returns: zero on success. See also: fsys_init

void fsys_unlockImage | ( | void |  | ) |

| Unlock an image that was previously locked by a call to the function fsys_lockAndGetImage(). See also: fsys_lockAndGetImage

sint_t fsys_write | ( | const sint_t | file,
|  | const char * | buf,
|  | const sint_t | count
| ) |

  | Write a block of data to a file. This function is equivalent to the one from the runtime library. Parameters:
  | file | Handle to the file to write to.
  | buf | Pointer to a user provided buffer that contains the data to write.
  | count | Number of bytes to write.
Returns: The number of bytes that have successfully been written, or -1 when an error has happened. See also: fsys_open, fsys_close, fsys_read