7.5 Specification of FS API functions

Functions called by PART module for imported partitions

int fc_getparlist(struct fs_pars *,ERR_PARAM);

• Input pars: none
• Output pars: filled struct fs_pars with filesystem parameters
• Actions: global initialization if necessary (function must be reentrant)
• Memory alloc: struct fs_pars members; not the structure itself
• Memory free: none
• Return value: zero if success, negative if error

int fc_identify(int pt_fh,struct partition_base *,ERR_PARAM);

• Input pars: filehandle of opened device, location of partition on device
• Output pars: none
• Actions: none
• Memory alloc: none
• Memory free: none
• Return value: zero if successful identification of filesystem, positive if unsuccessful identification of filesystem, negative if error

int fc_getparams(int fh,struct user_partition *,struct fs_pars *,ERR_PARAM);

• Input pars: filehandle of opened device, allocated and partially filled struct user_partition, struct fs_pars returned by fc_getparlist()
• Output pars: filled struct user_partition -- filled filesystem parameter entries (up_upcount,up_up), filled entry for root directory (up_dircount,up_dirs)
• Actions: none
• Memory alloc: array up_up, array up_dirs in struct user_partition, paramater entries in array up_up
• Memory free: none
• Return value: zero if success, negative if error

int fc_get_rootdirs(int fh,struct partition_base *,struct user_directory **,ERR_PARAM);

• Input pars: filehandle of opened device, location of partition on device
• Output pars: filled array of struct user_directory representing root subdirectories
• Actions: none
• Memory alloc: array of struct user_directory and its entries
• Memory free: none
• Return value: number of members in array of struct user_directory, negative if error

int fc_get_info(int fh,struct partition_base *,struct part_info **, int numdir,struct user_directory *,struct fs_info **,ERR_PARAM);

• Input pars: filehandle of opened device, location of partition on device, number of directories in array of struct user_directory, array of struct user_directory
• Output pars: filled array of struct fs_info, filled struct part_info
• Actions: none
• Memory alloc: array of struct fs_info, struct part_info
• Memory free: none
• Return value: zero if success, negative if error

Functions called by GCONV module for imported partitions

int fc_init(struct partition *,ERR_PARAM);

• Input pars: partition
• Output pars: none
• Action: initialize internal data structures
• Memory alloc: pt_fsdata
• Memory free: none
• Return value: zero if success

int fc_done(struct partition *,ERR_PARAM);

• Input pars: partition
• Output pars: none
• Action: none
• Memory alloc: none
• Memory free: pt_fsdata and other internal data structures
• Return value: zero if success

int fc_open_rootdir(struct partition *,struct entry_info **,ERR_PARAM);

• Input pars: partition
• Output pars: entry_info
• Action: allocates and opens root directory of fs
• Memory alloc: struct entry_info * and internal data ei_fsdata
• Memory free: none
• Return value: zero if success

int fc_open_subdir(struct partition *,struct entry_info **, struct entry_info *,ERR_PARAM);

• Input pars: partition, entry_info
• Output pars: entry_info
• Action: allocates and opens subdirectory specified by entry_info
• Memory alloc: struct entry_info and internal data ei_fsdata
• Memory free: none
• Return value: zero if success, negative if error

int fc_close_dir(struct partition *,struct entry_info *,ERR_PARAM);

• Input pars: partition, entry_info
• Output pars: none
• Action: closes and deallocates directory
• Memory alloc: none
• Memory free: internal data ei_fsdata and struct entry_info
• Return value: zero if success, negative if error

int fc_nextentry(struct partition *,struct entry_info **,ERR_PARAM);

• Input pars: partition, entry_info
• Output pars: entry_info
• Action: fills struct entry_info about next entry in its directory, allocates and initializes data internal structures used for fc_getdata(), can alloc new memory for next entry.
• Memory alloc: entry_info, ei_fsdata for fc_getdata in entry_info, filename
• Memory free: can free previous entry
• Return value: zero if success, positive if no more entries, negative if error

int fc_getdata(struct partition *,struct entry_info *,struct block_list *, ERR_PARAM);

• Input pars: partition, entry_info
• Output pars: block_list
• Action: sequentially fills struct block_list with extents of blocks of entry in entry_info, in once returns no more than block_list->fd_alloced extents, but at least one extent if exists, fd_blocks is already alloced
• Memory alloc: none
• Memory free: none
• Return value: zero if success, positive if no more blocks, negative if error

int fc_getdone(struct partition *,struct entry_info *,ERR_PARAM);

• Input pars: partition, entry_info
• Output pars: none
• Action: deallocating internal data structures
• Memory alloc: none
• Memory free: ei_fsdata for fc_getdata in entry_info, filename
• Return value: zero if success

int fc_freeblocks(struct partition *,struct block_list *,ERR_PARAM);

• Input pars: partition
• Output pars: block_list
• Action: fills block_list with extents of free blocks, no more than fd_alloced, but at least one if exists Can be NULL.
• Memory alloc: none
• Memory free: none
• Return value: zero if success, positive if no more free blocks, negative if error

int fc_hardlink_get_imported(struct partition *, struct entry_info *, struct hardlink_imported*, ERR_PARAM);

• Input pars: struct partition, struct entry_info
• Output pars: struct hardlink_imported
• Action: fills hi_fsdata, other is filled automatically
• Memory alloc: hi_fsdata
• Memory free: none
• Return value: zero if success

unsigned int fc_hardlink_hashkey(struct partition *, struct entry_info *, ERR_PARAM);

• Input pars: struct partition, struct entry_info
• Output pars: none
• Action: computes hashkey of hardlink, each entry for one hardlink must return the same value, value is modulo HARDLINK_HASHKEYS
• Memory alloc: none
• Memory free: none
• Return value: hashkey

int fc_hardlink_compare(struct partition *, struct hardlink_imported *, struct entry_info *, ERR_PARAM);

• Input pars: struct partition, struct hardlink, struct entry_info
• Output pars: none
• Action: compares if hardlink_imported and entry_info are equal hardlinks is guaranteed that ei_inode == hi_inode
• Memory alloc: none
• Memory free: none
• Return value: zero if equal, negative if non equal

int fc_hardlink_get_entry(struct partition *, struct hardlink_imported *, struct entry_info **, ERR_PARAM);

• Input pars: struct partition, struct hardlink_imported,
• Output pars: struct entry_info
• Action: allocs and fills entry_info, follows fc_getdata() calls, fc_getdone() and fc_closedir() for this entry_info. Note: can be called several times
• Memory alloc: struct entry_info
• Memory free: none
• Return value: zero if success

int fc_hardlink_free_imported(struct partition *, struct hardlink_imported *, ERR_PARAM);

• Input pars: struct partition, struct hardlink_imported
• Output pars: none
• Action: free all data structures for hardlink_imported
• Memory alloc: none
• Memory free: struct hardlink_imported
• Return value: zero if success

Functions called by PART module for exported partitions

int fc_check(struct user_partition *,struct fs_info *,ERR_PARAM);

• Input pars: struct user_partition filled by user, struct fs_info summarizing size of files to be stored there
• Output pars: modified struct user_partition (esp. up_upcount, up_up), if not set up_entryvalid then filesystem type filled in up_entry
• Action: none
• Memory alloc: new entries in struct user_partition
• Memory free: removed entries in struct user_partition
• Return value: zero if okay, positive if conflict, negative if error

block_t fc_getsize(struct user_partition *,struct fs_info *,ERR_PARAM);

• Input pars: struct user_partition filled by user, struct fs_info summarizing size of files to be stored there
• Output pars: none
• Action: none
• Memory alloc: none
• Memory free: none
• Return value: number of blocks needed to store (i.e. without free blocks) the whole filesystem including filesystem structures, negative if error

block_t fc_getsize_struct(struct user_partition *,struct fs_info *,ERR_PARAM);

• Input pars: struct user_partition filled by user, struct fs_info summarizing size of files to be stored there
• Output pars: none
• Action: none
• Memory alloc: none
• Memory free: none
• Return value: number of blocks needed to store filesystem structures, negative if error

Functions called by GCONV module for exported partitions

int fc_superblock(struct partition *exported, struct partition *imported, ERR_PARAM);

• Input pars: import, export
• Output pars: none
• Action: sets values in superblock, only if it NOT requires rebuilding filesystem -- fs must check whether the most important parameters have not changed between import and export.
• Memory alloc: none
• Memory free: none
• Return value: zero if success, positive if requires rebuilding filesystem, negative on error

int fc_mkfs(struct partition *,ERR_PARAM);

• Input pars: partition
• Output pars: none
• Action: initialize internal data structures, create structures of partition on disk, fs is recommended to create its clusters aligned from block part->pt_align.
• Memory alloc: pt_fsdata
• Memory free: none
• Return value: zero if success

int fc_fsdone(struct partition *,ERR_PARAM);

• Input pars: partition
• Output pars: none
• Action: free memory
• Memory alloc: none
• Memory free: pt_fsdata and other internal data structures
• Return value: zero if success

int fc_putbadblocks(struct partition *,struct block_list *,ERR_PARAM);

• Input pars: partition, block_list
• Output pars: none
• Action: adds extents of blocks in block_list to the end of currently open entry (opened with fc_createentry())
• Memory alloc: none
• Memory free: none
• Return value: zero if success, negative if error

int fc_createentry(struct partition *,struct entry_info *dir, struct entry_info *file,struct block_list *free,ERR_PARAM);

• Input pars: partition, struct entry_info dir, struct entry_info file, struct block_list free
• Output pars: struct entry_info dir
• Action: creates new file/directory in opened directory dir. dir->ei_fsdata must be filled to let gconv call fc_putdata (for files) and fc_open_subdir (for directories). fc_putdone will be called after action is performed. fs is recommended to use extents from array free for its internal directory data.
• Memory alloc: dir->ei_fsdata
• Memory free: none
• Return value: zero if success, negative if error

int fc_putdata(struct partition *,struct entry_info *,struct block_list *used, struct block_list *free,struct block_list *target,ERR_PARAM);

• Input pars: partition, entry, used, free
• Output pars: target
• Action: adds blocks to the end of currently open entry, extents of current location are in used, but can if index of extent is INVALID_BLOCK, extent must be moved. For new locations of extents is recommended to use extents from free. New location is returned in targed.
• Memory alloc: none
• Memory free: none
• Return value: zero if success, negative if error

int fc_putdone(struct partition *,struct entry_info *,ERR_PARAM);

• Input pars: partition, entry
• Output pars: none
• Action: free memory used for puting blocks or creating directory
• Memory alloc: none
• Memory free: ei_fsdata
• Return value: zero if success

int fc_align(struct partition *,struct extent *,ERR_PARAM);

• Input pars: partition, extent
• Output pars: extent
• Action: changes extent to be aligned subextent
• Memory alloc: none
• Memory free: none
• Return value: zero if success

int fc_hardlink_create(struct partition *, struct entry_info **dir, struct entry_info *file, struct hardlink_exported *temple, struct hardlink_exported **dupl, ERR_PARAM);

• Input pars: struct partition, dir, file, temple
• Output pars: dupl
• Action: analogical to fc_createentry(), creates entry (with values in argument file) in directory dir. May be hardlinked to temple (if !=NULL). If may be duplicated, then alloc and fill argument dupl. Duplicating follows moving all other files to all exported filesystems.
• Memory alloc: possible alloc dupl and dupl->he_fsdata
• Memory free: none
• Return value: zero if success

int fc_hardlink_get_exported(struct partition *, struct entry_info *, struct hardlink_exported*, ERR_PARAM);

• Input pars: struct partition, struct entry_info
• Output pars: struct hardlink_exported
• Action: fills hardlink_exported about entry, will be used as temple in fc_hardlink_create() calls, this call follows call fc_putdone().
• Memory alloc: he_fsdata
• Memory free: none
• Return value: zero if success

int fc_hardlink_duplicate(struct partition *, struct hardlink_exported *, struct entry_info **, int isreg, ERR_PARAM);

• Input pars: struct partition, struct hardlink_exported
• Output pars: struct entry_info
• Action: creates duplicated entry, if isreg is true, will be followed by fc_putdata() calls, fc_putdone() and fc_closedir(). Note: isreg is equal to S_ISREG of original entry
• Memory alloc: struct entry_info
• Memory free: none
• Return value: zero if success

int fc_hardlink_free_exported(struct partition *, struct hardlink_exported *, ERR_PARAM);

• Input pars: struct partition, struct hardlink_exported
• Output pars: none
• Action: free all data structures for hardlink_exported
• Memory alloc: none
• Memory free: struct hardlink_exported
• Return value: zero if success

fc_open_rootdir, fc_open_subdir, fc_close_dir

These functions work exactly like for imported filesystem. Any created directory could (and should) be opened to be able to create entries in it.