libany(3)

NAME
libany - anyfs-tools library.

SYNOPSIS
#include <any.h>

#include <super.h>

#include <bitops.h>

#include <block_map.h>

#include <new_inode.h>

#include <release_fssys.h>

#include <progress.h>

#include <version.h>

DESCRIPTION
libany library used by anyfs-tools.

INODE TABLE STRUCTURES
Structures to keeps inode table in memory declared in any.h file.

  SUPERBLOCK INFORMATION
struct any_sb_info {
	char *si_itfilename;               /* inode table filename */
	unsigned long si_blocksize;        /* blocksize */
	unsigned long si_inodes;           /* count of inodes */
	unsigned long *si_inode_bitmap;    /* map of inodes */
	struct any_inode *si_inode_table;  /* array of inodes */
};
The structure is superblock analog in other filesystems. The si_itfilename field fills with opening inode table and may be used with writing inode table if wasn't specified other filename. The si_inode_bitmap field is bitmap which says if a inode is busy. The si_inode_table field is actually inode table. Array of si_inodes any_inode structures (described below).

  INODE
struct any_inode {
    uint16_t  i_mode;         /* File mode */
    uint16_t  i_uid;          /* Low 16 bits of Owner Uid */
    uint16_t  i_gid;          /* Low 16 bits of Group Id */
    uint64_t  i_size;         /* Size in bytes */
    uint32_t  i_atime;        /* Access time */
    uint32_t  i_ctime;        /* Creation time */
    uint32_t  i_mtime;        /* Modification time */
    uint16_t  i_links_count;  /* Links count */
    union {
        struct any_file_frags   *file_frags; /* File fragments */
        struct any_dir          *dir;        /* Directory entries */
        char   *symlink;                     /* Symbolic link */
        dev_t  device;                       /* Device */
    } i_info;
    size_t    i_it_file_offset; /* Offset in inode table file */
}
The structure is some modified of ext2fs inode structure ext2_inode. The most entries description you may find in stat(2). Union i_info keeps link to inode table information part which depend on inode type. For regular file is description of location its fragment on the disk. For directories is its entries list. For symbolic links is link string. For device is device type (see description of st_rdev entry in stat(2) structure) The i_it_file_offset field used by writing inode table function.

  DIRECTORY
Directory has the next description:
struct any_dir {
        uint32_t              d_ndirents; /* count of entries */
        struct any_dirent*    d_dirent;   /* first directory entry */
        void*                 d_data;     /* link to additional data
					  	(used in GUI) */
};
The d_dirent field is pointer to Singly-linked directory entries list.

  DIRECTORY ENTRY
struct any_dirent {
        char*               d_name;  /* entry name */
        uint32_t            d_inode; /* inode number */
        struct any_dirent   *d_next; /* the next directory entry */
};

  FILE FRAGMENTS
For regular file there is keeps information about its location on the disk in the next structure:
struct any_file_frags {
        uint32_t                   fr_nfrags; /* fragments count */
        struct any_file_fragment   *fr_frags; /* fragments */
};
The fr_frags field is array of fr_nfrags enties which describes each file fragment.

  FILE FRAGMENT
struct any_file_fragment {
        uint32_t    fr_start;     /* start fragment block number */
        uint32_t    fr_length;    /* fragment length in blocks */
};
Blocksize used in the structure as unit of measurement defined in any_sb_info structure. 0 value of fr_start entry means sparse-fragment (i.e. which doesn't keeps on the disk, but considered that it filled with zeroes)

CREATE/OPEN/WRITE INODE TABLE
The next functions declared in super.h.

int alloc_it(struct any_sb_info **it, unsigned long blocksize,
            unsigned long inodes);
    Allocate memory for inode table with blocksize and maximal count of inodes inodes, puts pointer on the any_sb_info structure to *it. New inode table fills with zeroes. Returns 0 if successful or -ENOMEM if not enough memory.

int realloc_it(struct any_sb_info *it, unsigned long inodes);
    Uses realloc to change maximal number of entries in it inode table to inodes. Mean that after this call the si_inode_bitmap and si_inode_table entries of any_sb_info structure of inode table may change its values i.e. inode table and map may change its location in the memory) and any pointers on inodes calculated before the call with expression like (it->si_inode_table + ino) or &(it->si_inode_table[ino]) will needed to update. Returns 0 if successful or exit from program with ENOMEM status.

int read_it(struct any_sb_info **it, char itfilename[]);
    Read inode table from itfilename file to the memory, puts inode table pointer to *it. Returns 0 if successful or -ENOMEM, -ENAMETOOLONG, -EINVAL in case of error. If there was input/output error errno variable keeps more detailed error code.

int write_it(struct any_sb_info *it, char itfilename[]);
    Write it inode table to the itfilename file. If itfilename == NULL, then it gets filename from it->si_itfilename. Mean that the call doesn't free memory with inode table (although read_it call allocate memory for new inode table) Return 0 if successful or 1 if there is error. In case of input/output error errno variable keeps more detailed error code.

void free_it(struct any_sb_info *info);
    Free memory with inode table.

WORK WITH BITMAPS
The next functions declared in bitops.h

int test_and_set_bit(unsigned int nr, unsigned long* addr);
    Set nr bit in addr bitmap. Returns the value of bit before setting.

set_bit(unsigned int nr, unsigned long* addr);
    Set nr bit in addr bitmap.

int test_and_clear_bit(unsigned int nr, unsigned long* addr);
    Clear nr bit in addr bitmap. Returns the value of bit before clearing.

clear_bit(unsigned int nr, unsigned long* addr);
    Clear nr bit in addr bitmap.

int test_bit(unsigned int nr, unsigned long* addr);
    Returns the value of nr bit in the addr bitmap.

int find_first_zero_bit(const unsigned long* addr, int size);
    Search the first zero bit in the addr bitmap size. Return number of founded bit, or value which not less than size in unsuccessful case.

int find_next_zero_bit(const unsigned long* addr, int size,
            int offset);
    Search the first zero bit in the addr bitmap with size beginning from offset. Return number of founded bit, or value which not less than size in unsuccessful case.

CREATE BLOCKS MAP
The next functions declared in block_map.h

int fill_block_bitmap(struct any_sb_info *info,
            unsigned long *block_bitmap,
            any_blk_t dev_size,
            int check_intersects);
    Fills blocks map, sets blocks of regular files, according to information from info inode table for device with dev_size size in blocks. Map before the call must be allocated and filled with zeroes. Besides the functions set the zero block as system. The function returns 0 if successful or -1, if in the inode table was founded files, with shared blocks (set last check_intersect parameter to disable check for block intersects, it used in anysurrect). It means that the function must never find already set bit in the bitmap (possibly, set by itself as used block with other inode).

CREATE FILES IN ANYFS
The next functions declared in new_inode.h

int any_new_inode(struct any_sb_info *info, int mode, void* data,
            uint32_t dirino, uint32_t *newino);
    Creates inode in info inode table with mode in directory inode dirino. New inode number puts to *newino. In case device creating (special file), data pointer must link to variable with dev_t type which keep device type. Returns zero in successful case. Close program (with exit) if not enough memory.

int getpathino(char *path, uint32_t root, struct any_sb_info* info,
            uint32_t *ino);
    Search (directory) entry with name path from directory inode root as root in info inodetable. Puts founded inode number to *ino. Returns 0 in successful case, 1 if entry doesn't exist, or -1 if root inode is not directory or free inode.

int mkpathino(char *path, uint32_t root, struct any_sb_info* info,
            uint32_t *ino);
    like getpathino(), but creates all directories in path if they doesn't exit. In the program must be difined mode_t dir_umask; variable whick keeps umask for new directories.

FREEING SYSTEM BLOCKS
The next functions declared in release_fssys.h

typedef int any_rwblk_t(unsigned long from, unsigned long n,
            char *buffer);
    Type function to read/write block. Function of this type must read/write n blocks beginning from in/from (before allocated) buffer. The function must returns 0 in successful case or negative value in case of input/output error.

extern any_rwblk_t *any_readblk;
    Pointer to the function to read blocks from device. Put to this variable right value before any_release() call.

extern any_rwblk_t *any_writeblk;
    Pointer to the function to write blocks from device. Put to this variable right value before any_release() call.

typedef int any_testblk_t(unsigned long bitno);
    Type function to test if block busy bitno. The function of the type must return 0, if tested block is free.

extern any_testblk_t *any_testblk;
    Pointer to function for test if device block busy. The function must return 1, only, if device block will kept with system information. Put to this variable right value before any_release() call.

typedef unsigned long any_getblkcount_t();
    Type function to get device size in blocks.

extern any_getblkcount_t *any_getblkcount;
    Pointer to function to get device size. Put to this variable right value before any_release() call.

int any_release(struct any_sb_info *info, unsigned long *block_bitmap,
            unsigned long start, unsigned long length);
    Free length (in future) system blocks of FS, beginning from start block from user information. It gets information from info inodetable, blocks map (of user information) block_bitmap. The function uses any_readblk and any_writeblk functions to read/write device, any_getblkcount function to get device size, also any_testblk function to get information about system blocks on device.

int any_release_sysinfo(struct any_sb_info *info,
            unsigned long *block_bitmap,
            any_rwblk_t *readblk,
            any_rwblk_t *writeblk,
            any_testblk_t *testblk,
            any_getblkcount_t *getblkcount);
    Free all (in future) system blocks of FS from user information. It gets information from info inodetable, blocks map (of user information) block_bitmap. The function uses readblk and writeblk functions to read/write device, getblkcount function to get device size, also testblk function to get information about system blocks on device.

int any_adddadd(struct any_sb_info *info);
    The function add to all directories of info inodetable "." and ".." entries. The function used in utilities for filesystem building build_e2fs and build_xfs, after freing blocks from system information. Because its declaration wasn't move to other file.

PROGRESS LINE
The next functions declared in progress.h The functions was get from e2fsprogs with some modifications.

struct progress_struct;
    The structure keeps some progress data. The structure fields uses by functions below. The programmer which uses that functions not needed to edit this fields self.

void progress_init(struct progress_struct *progress,
            const char *label, uint32_t max);
    Initialize progress progress line with label (program action explanation for user) and max maximal value. Maximal value may be set to zero if count of precessed units (blocks, files and so on) not known (maybe the progress line will show counting if the entries), in this case the progress line will not
    <label>: <number of processed entry>/<total entries> but without printing "total entries" field:
    <label>: <number of processed entry> The possibility used in build_it for filesystems which don't returns right count of used inodes (e.g. VFAT).

void progress_update(struct progress_struct *progress, uint32_t val);
    Updates progress progress line to val value. The function returns cursor and write new progress value.

int if_progress_update(struct progress_struct *progress, uint32_t val);
    Return 1 if progress progress line will updated with updating its value to val. Function used in anysurrect utility to decide if need return cursor to necessary position for progress updating, which changed with printing type of the working surrecter indicator.

int if_progress_updated(struct progress_struct *progress, uint32_t val);
    Return 1 if progress progress line was updated with updating its value to val. Function used in anysurrect utility to decide if need print new value of type of the working surrecter indicator after progress line updating.

void progress_close(struct progress_struct *progress);
    Close progress progress line.

ANYFS-TOOLS VERSION
The version.h file has declaration of two macroses.

ANYFSTOOLS_VERSION
    String of version anyfs-tools package.

ANYFSTOOLS_DATE
    String with release date of the version anyfs-tools package.

AUTHOR
Nikolaj Krivchenkov aka unDEFER <undefer@gmail.com>

BUG REPORTS
Messages about any problem with using anyfs-tools package send to undefer@gmail.com

AVAILABILITY
You can obtain the last version of package at http://anyfs-tools.sourceforge.net

SEE ALSO
anyfs-tools(8), build_it(8), anysurrect(8), stat(2)