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

---