Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/dlbeer/ufat

Low-memory feature-complete VFAT implementation
https://github.com/dlbeer/ufat

Last synced: 23 days ago
JSON representation

Low-memory feature-complete VFAT implementation

Awesome Lists containing this project

README 

        
uFAT

====



uFAT is small but feature-complete VFAT/FAT32 implementation. It

supports all basic filesystem operations and has minimal memory

requirements. Its key features are:



  * No global data: can be used to access multiple filesystems

    simultaneously without issue.



  * Small memory footprint: only a few kB required for metadata

    caching and long filename parsing (the cache size is configurable

    and can be as low as 512 bytes).



  * No heap allocation is used.



  * Highly portable: no external dependencies except for a few

    easily-implementable ANSI C functions (memcpy, memset, atoi).



  * Unicode filenames are supported (via translation to and from UTF-8

    for function call arguments).



  * Supports reading, writing and creating FAT12, FAT16 and FAT32,

    including long filenames.



Using uFAT as a library

-----------------------



The interface to the underlying block device is abstract and specified

though a structure containing some key parameters and access functions:



    typedef unsigned long long ufat_block_t;



    struct ufat_device {

      unsigned int  log2_block_size;

      int   (*read)(const struct ufat_device *dev, ufat_block_t start,

            ufat_block_t count, void *buffer);

      int   (*write)(const struct ufat_device *dev, ufat_block_t start,

            ufat_block_t count, const void *buffer);

    };



A pointer to the ``struct ufat_device`` is passed with each call to

``read`` or ``write``, so driver-private data can be kept by embedding

the structure in a larger structure.



All ``ufat_block_t`` arguments are block indices relative to the

beginning of the partition. ``log2_block_size`` should be the base-2

logarithm of the block size (that is, ``1 << log2_block_size`` is the

actual block size in bytes). Having filled out a ``struct

ufat_device`` for the partition/device you want to access, Use

``ufat_open``/``ufat_close`` to open and close the filesystem:



    struct ufat_device dev;

    struct ufat uf;

    int err;



    dev.log2_block_size = 9;

    dev.read = my_read;

    dev.write = my_write;



    err = ufat_open(&uf, &dev);

    if (err < 0) {

      fprintf(stderr, "Error: %s\n", ufat_strerror(err));

      return -1;

    }



    /* ... */



    ufat_close(&uf);



No memory is allocated when a filesystem is opened, but ``ufat_close``

must be called to flush caches if the filesystem has been modified.



There are three basic objects used by the filesystem implementation:



``struct ufat_dirent``



  ~ This represents a directory entry. It holds information on a file or

    directory and contains the location of the entry on the underlying

    device, attributes and file size (for regular files).



``struct ufat_directory``



  ~ This structure is a directory iterator. There are two ways to

    construct this object: either by opening the root directory, or by

    opening a subdirectory represented by a ``ufat_dirent`` using

    ``ufat_open_subdir``. Iterating through the contents of a

    directory returns a series of ``ufat_dirent`` structures.



``struct ufat_file``



  ~ This structure represents an open file. It is constructed from a

    ``ufat_dirent`` via a call to ``ufat_open_file``.



Functions for manipulating the filesystem and the associated objects

are detailed in the ``ufat.h`` header file. Examples may be found in

the included image-manipulation program (``main.c`` in the source

distribution).



All functions with ``int`` return types will return 0 on success or a

negative error code if there is a problem with the underlying

filesystem or device. These error codes can be translated into

human-readable strings with ``ufat_strerror``. Error codes are

declared as values for the enum ``ufat_error_t``.



Directories may be traversed by a series of

``ufat_open_subdir``/``ufat_dir_find`` calls. For cases where a full

slash-separated path is known, the following function is useful:



    int ufat_dir_find_path(struct ufat_directory *dir,

              const char *path, struct ufat_dirent *inf,

              const char **path_out);



Its arguments are:



``dir``



  ~ An open directory from which to start the search. This will in

    most cases be the root directory, but it can be any subdirectory,

    and the path given will be treated as relative to the initial

    directory.



``path``



  ~ A slash-separated path, relative to the starting directory. Path

    components may be separated by either a forward-slash or a

    backslash. This path should be UTF-8 encoded.



``inf``



  ~ A pointer to a ``ufat_dirent`` which will be filled out with the

    details of the file/directory found.



``path_out``



  ~ A pointer to the remainder of the path not processed if the file

    could not be found.



If an IO or filesystem error occurs, a negative error code is

returned. When the given path identifies an existing file or

directory, the structure pointed to ``inf`` is filled out and the

function returns 0.



If the given path doesn't name an existing file or directory, 1 is

returned. In this case, ``inf`` is not filled out, but the pointer

pointed to by ``path_out`` will be filled out with a pointer to the

remainder of ``path`` which was not processed.



In all cases, ``dir`` will be reinitialized to be an iterator for the

directory where the search terminated.



Copyright

---------



Copyright (C) 2012 TracMap Holdings Ltd



Redistribution and use in source and binary forms, with or without

modification, are permitted provided that the following conditions are

met:



1. Redistributions of source code must retain the above copyright

notice, this list of conditions and the following disclaimer.



2. Redistributions in binary form must reproduce the above copyright

notice, this list of conditions and the following disclaimer in the

documentation and/or other materials provided with the distribution.



3. Neither the name of the copyright holder nor the names of its

contributors may be used to endorse or promote products derived from

this software without specific prior written permission.



THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS

IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED

TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A

PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT

HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,

SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED

TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR

PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF

LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING

NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS

SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.