General Info

Interface: FSManager
Files: fsmanager.h
Last change: 02/03/2003
Author: Luiz Henrique Shigunov 		Description
Structures
Configuration
System Functions

0x00 - Close - Close a file
0x02 - Mount - Mount a file system
0x03 - Open - Open a file
0x05 - Read - Read from a file
0x07 - Remove - Remove a file
0x09 - RewindDir - Seek to start of directory
0x0a - Seek - Reposition read/write file offset
0x0b - Status - Get informations about a file/directory
0x01 - StatusFD - Get informations about a file descriptor
0x0c - Unmount - Unmount a file system
0x0d - Write - Write into a file
User Functions

0x0e - UClose - Close a file/directory
0x0f - UChangeDir - Change current directory
0x10 - UChangeRoot - Change root directory
0x11 - UMount - Mount a file system
0x12 - UOpen - Open a file
0x14 - URead - Read from a file
0x16 - URemove - Remove a file
0x18 - URewindDir - Seek to start of directory
0x19 - USeek - Reposition read/write file offset
0x1a - UStatus - Get informations about a file/directory
0x04 - UStatusFD - Get informations about a file descriptor
0x1b - UUnmount - Unmount a file system
0x1c - UWrite - Write into a file

Description

This page describes the FSManager interface which provides access to file systems, making file access independent from file systems and allowing many file systems to be used transparently. So, a module doesn't need to know if it's using a FAT or Ext2 file system. But, if it needs so it can use a specific file system function.

To achieve this flexibility, each file system must be mounted, that is, linked to the file systems manager and to a device.

A module to be mounted must implement FileSystem interface and can only be mounted into a module that implements BlockDev interface.

The same file system from the same unit and device can be mounted on various differents directories, but only one file system can be mounted on a directory.

Mount a file system means to make it available to the system. So, it doesn't make sense to mount a file system in an inexistent directory, because it going to be unavailable. In the same manner, it doesn't make sense to remove the directory where the file system is mounted.

With this definition it's clear that the directory where a file system is going to be mounted must exist and must be blocked (can't be removed, moved, etc).

A file or directory handler provided by a system function is unique in all system. But a file or directory handler provided by user functions is unique only in the task.

Current interface only supports files with maximum size of 2 GB.

Structures

typedef struct {
    unsigned short size;
    char name[1];
} FSManager_DirEntry;

Where size is the size of this entire DirEntry. name is a null-terminated file name. 

typedef struct {
    unsigned int mode;
    unsigned int nlink;
    unsigned int uid;
    unsigned int gid;
    int size;
    unsigned int blksize;
    unsigned int blocks;
    unsigned int atime;
    unsigned int mtime;
    unsigned int ctime;
} FSManager_EntryStatus;

nlink is the number of hard links.

uid is the user ID of owner.

gid is the group ID of owner.

size is the size of the file (if it is a regular file or a symlink) in bytes. The size of a symlink is the length of the pathname it contains, without trailing NULL.

blksize is the "preferred" blocksize for efficient file system I/O. (Writing to a file in smaller chunks may cause an inefficient read-modify-rewrite.)

blocks is the size of the file in 512-byte blocks.

Not all filesystems implement all of the time fields.

atime is the time of last access. For instance: Read.

mtime is the time of last modification. For instance: Write. mtime of a directory is changed by the creation or deletion of files in that directory. mtime is not changed for changes in owner, group, hard link count, or mode.

ctime is the time of last change. For instance: Write. ctime is changed by setting inode information (i.e., owner, group, link count, mode, etc.).

mode can be (in octal):
0170000 - FSManager_TYPE_MASK - bitmask for the file type bitfields
0140000 - FSManager_TYPE_SOCKET - socket
0120000 - FSManager_TYPE_LINK - symbolic link
0100000 - FSManager_TYPE_FILE - regular file
0060000 - FSManager_TYPE_BLOCK_DEV - block device
0040000 - FSManager_TYPE_DIR - directory
0020000 - FSManager_TYPE_CHAR_DEV - character device
0010000 - FSManager_TYPE_FIFO - fifo
0004000 - FSManager_UID_BIT - set UID bit
0002000 - FSManager_GID_BIT - set GID bit
0001000 - FSManager_STICKY_BIT - sticky bit
0000700 - FSManager_USER_RWX - mask for file owner permissions
0000400 - FSManager_USER_READ - owner has read permission
0000200 - FSManager_USER_WRITE - owner has write permission
0000100 - FSManager_USER_EXEC - owner has execute permission
0000070 - FSManager_GROUP_RWX - mask for group permissions
0000040 - FSManager_GROUP_READ - group has read permission
0000020 - FSManager_GROUP_WRITE - group has write permission
0000010 - FSManager_GROUP_EXEC - group has execute permission
0000007 - FSManager_OTHER_RWX - mask for permissions for others
0000004 - FSManager_OTHER_READ - others have read permission
0000002 - FSManager_OTHER_WRITE - others have write permisson
0000001 - FSManager_OTHER_EXEC - others have execute permission 

typedef struct {
    FSManager_Handle *fd;
    int flags;
    void *buf;
    int size;
} FSManager_FDIO;

Where fd is the file descriptor, buf is the buffer where data will be written to if it is a read request or from where data will be read if it is a write request, size is the number of bytes to be read or written and flags must be 0 or the sum of:

If all goes ok size will have the number of bytes read or written. 

typedef struct {
    FileSystem_Handle *fd;
} FSManager_Handle;

It is used only by modules that implement FileSystem interface. 

typedef struct {
    const char *str;
    unsigned int len;
    unsigned int hash;
} FSManager_ExStr;

It is used only by modules that implement FileSystem interface. 

typedef struct FSManager__Dentry {
    unsigned int count;
    unsigned int mode;
    unsigned int flags;
    struct FSManager__Dentry *parent;
    FSManager_FS *fs;
    struct FSManager__Dentry *hashNext;
    struct FSManager__Dentry *hashPrior;
    struct FSManager__Dentry *lruNext;
    struct FSManager__Dentry *lruPrior;
    struct FSManager__Dentry *mounted;
    unsigned int version;
    TaskManager_Semaphore lock;
    FSManager_ExStr name;
    void *fsData;
    char iname[FSManager_INAME_LEN];
} FSManager_Dentry;

It is used only by modules that implement FileSystem interface.

Configuration

This interface defines the following groups and keys available using the CfgManager interface:

/system/FSManager/root

The following keys are defined in this group:

  • fsImp - name of the implementation of the FileSystem interface to be used to mount the root directory (the file system to be mounted)
  • devImp - name of the implementation of the BlockDev interface to be used to mount the root directory (the device to be mounted)
  • unit - unit number of devImp to be used
  • data - data to be passed to the file system

Some examples:

  • fsImp = Ext2FS
  • devImp = FDC
  • unit = 0x0
  • data =

System Functions

These functions are exclusive for system modules.

0x00 - Close

Syntax

int FSManager_Close(FSManager_Handle *fd);

Properties

Description

This function closes fd.

Return value

0x02 - Mount

Syntax

int FSManager_Mount(const char *fsImp, const char *devImp, unsigned int unit, const char *path, int prop, const char *data);

Properties

Description

This function mounts file system fsImp with properties prop. fsImp will use unit from device devImp.

fsImp must implement FileSystem interface. And devImp BlockDev interface.

data are specific data for the file system.

If path isn't a complete path, that is, one that starts with "/" and if the calling task has a current dir, it will be used. Otherwise, the root dir will be used.

prop can be:

It is not permited to mount a file system on a directory that has already a mounted file system.

Return value

0x03 - Open

Syntax

int FSManager_Open(const char *pathname, int prop, FSManager_Handle **fd);

Properties

Description

This function opens file pathname with properties prop.

prop can be:

FSManager_READ or FSManager_WRITE must be set, others can be added. (FSManager_WRITE + FSManager_CREATE, for instance).

In case prop has FSManager_CREATE, prop can have the follow values too (in octal):

If pathname isn't a complete path, that is, starts with "/" and if the calling task has a current dir, it will be used. Otherwise the root dir will be used.

The file offset is set to the beginning of the file.

Return value

0x05 - Read

Syntax

int FSManager_Read(FSManager_FDIO *request);

Properties

Description

This function processes read request.

In case of directory read, buf will have dir entries (FSManager_DirEntry).

If all goes ok, file position is advanced by the number of bytes read.

Return value

0x07 - Remove

Syntax

int FSManager_Remove(const char *pathname);

Properties

Description

This function removes pathname.

If pathname isn't a complete path, that is, starts with "/" and if the calling task has a current dir, it will be used. Otherwise the root dir will be used.

The file/directory pathname can be been used. Who is using it can continue to use, but won't be possible to open, list, etc.

A directory with files can't be removed.

Return value

0x09 - RewindDir

Syntax

int FSManager_RewindDir(FSManager_Handle *fd);

Properties

Description

This function repositions fd read offset to the beginning.

Return value

0x0a - Seek

Syntax

int FSManager_Seek(FSManager_Handle *fd, int count, int prop, int *newPos);

Properties

Description

This functions repositions fd read/write offset to count bytes according to prop.

prop can be:

If all goes ok, newPos, if different than NULL, will contain the new position.

Return value

0x0b - Status

Syntax

int FSManager_Status(const char *pathname, FSManager_EntryStatus *buf, int prop);

Properties

Description

This function gets informations about pathname and puts them in buf.

If pathname isn't a complete path, that is, one that starts with "/" and if the calling task has a current dir, it will be used. Otherwise the root dir will be used.

prop can be:

Return value

0x01 - StatusFD

Syntax

int FSManager_StatusFD(FSManager_Handle *fd, FSManager_EntryStatus *buf, int prop);

Properties

Description

This function gets informations about fd, which must have been opened by Open, and puts them in buf.

prop can be:

Return value

0x0c - Unmount

Syntax

int FSManager_Unmount(const char *path, int prop);

Properties

Description

This function unmounts the file system mounted in path.

If pathname isn't a complete path, that is, one that starts with "/" and if the calling task has a current dir, it will be used. Otherwise the root dir will be used.

prop can be zero or the sum of:

Return value

0x0d - Write

Syntax

int FSManager_Write(FSManager_FDIO *request);

Properties

Description

This function processes write request.

If all goes ok, file position is advanced by the number bytes written.

Return value

User Functions

These functions are exclusive for user modules.

0x0e - UClose

Syntax

int FSManager_UClose(int fd);

Properties

User modules

Description

This function closes fd.

Return value

0x0f - UChangeDir

Syntax

int FSManager_UChangeDir(const char *path);

Properties

User modules

Description

This function changes task's current directory to path.

Current directory is used when a path doesn't start with "/".

Return value

0x10 - UChangeRoot

Syntax

int FSManager_UChangeRoot(const char *path);

Properties

User modules

Description

This function changes task's root directory to path.

Root directory is used when a path starts with "/".

Return value

0x11 - UMount

Syntax

int FSManager_UMount(const char *fsImp, const char *devImp, unsigned int unit, const char *path, int prop, const char *data);

Properties

User modules

Description

This function mounts file system fsImp with properties prop. fsImp will use unit from device devImp.

fsImp must implement FileSystem interface. And devImp BlockDev interface.

data are specific data for the file system.

prop can be:

Return value

0x12 - UOpen

Syntax

int FSManager_UOpen(const char *pathname, int prop);

Properties

User modules

Description

This function opens pathname with properties prop.

prop can be:

FSManager_READ or FSManager_WRITE must be set, others can be added. (FSManager_WRITE + FSManager_CREATE, for instance).

In case prop has FSManager_CREATE, prop can have the follow values too (in octal):

If pathname isn't a complete path, that is, starts with "/" current directory will be used.

The file offset is set to the beginning of the file.

Return value

0x14 - URead

Syntax

int FSManager_URead(int fd, void *buf, int size);

Properties

User modules

Description

This function reads size bytes from fd into buf.

In case of directory read, buf will have dir entries (FSManager_DirEntry).

If all goes ok, file position is advanced by the number of bytes read.

Return value

0x16 - URemove

Syntax

int FSManager_URemove(const char *pathname);

Properties

User modules

Description

This function removes pathname.

If pathname isn't a complete path, that is, starts with "/" current directory will be used.

The file/directory pathname can be been used. Who is using it can continue to use, but won't be possible to open, list, etc.

A directory with files can't be removed.

Return value

0x18 - URewindDir

Syntax

int FSManager_URewindDir(int fd);

Properties

User modules

Description

This function repositions fd read offset to the beginning.

Return value

0x19 - USeek

Syntax

int FSManager_USeek(int fd, int count, int prop);

Properties

User modules

Description

This functions repositions fd read/write offset to count bytes according to prop.

prop can be:

Return value

0x1a - UStatus

Syntax

int FSManager_UStatus(const char *pathname, FSManager_EntryStatus *buf, int prop);

Properties

User modules

Description

This function gets informations about pathname and puts them in buf.

prop can be:

Return value

0x04 - UStatusFD

Syntax

int FSManager_UStatusFD(int fd, FSManager_EntryStatus *buf, int prop);

Properties

User modules

Description

This function gets informations about fd, which must have been opened by UOpen, and puts them in buf.

prop is not used yet.

Return value

0x1b - UUnmount

Syntax

int FSManager_UUnmount(const char *path, int prop);

Properties

User modules

Description

This function unmounts the file system mounted in path.

prop can be zero or the sum of:

Return value

0x1c - UWrite

Syntax

int FSManager_UWrite(int fd, void *buf, int count);

Properties

User modules

Description

This function writes count bytes from buf in fd.

If all goes ok, file position is advanced by the number of bytes written.

Return value