README.md

   1 ## ⚠️ This repository has moved to: https://gitlab.com/mbitsnbites/mfat
   2
   3 # MFAT
   4
   5 MFAT is a minimal I/O library for [FAT (File Allocation Table)](https://en.wikipedia.org/wiki/File_Allocation_Table) volumes.
   6
   7 The library has been designed for embedded systems, and its small code and memory footprint makes it suitable for inclusion in firmware/ROM and/or small OS kernels.
   8
   9 ## Features
  10
  11 * Works with any storage medium that supports random access block I/O (SD cards, hard drives, raw disk image files, etc).
  12 * Supports both FAT16 and FAT32.
  13 * Supports multiple partitions (both [MBR](https://en.wikipedia.org/wiki/Master_boot_record) and [GPT](https://en.wikipedia.org/wiki/GUID_Partition_Table) partition tables are supported).
  14 * Cached I/O (configurable cache size).
  15 * Small memory footprint.
  16 * No dynamic memory allocation (only static/BSS).
  17 * Configurable to tune code and memory requirements.
  18 * Completely dependency-free.
  19 * Implemented in portable C99.
  20 * Easy to integrate into your project (only two files are needed: mfat.h and mfat.c).
  21 * Familiar and easy-to-use POSIX-like API.
  22 * Liberal license ([BSD-2-Clause](https://opensource.org/licenses/BSD-2-Clause)).
  23
  24 ## Limitations
  25
  26 The internal MFAT context is statically allocated, meaning:
  27
  28 * Only a single device may be mounted at any time.
  29 * The API is not thread safe.
  30
  31 Also: **MFAT is still work-in-progress**.
  32
  33 * Writing is not supported yet.
  34 * Long file names are not supported yet.
  35
  36 ## POSIX compatibility
  37
  38 The API of this library is modelled after the [POSIX.1-2017](https://pubs.opengroup.org/onlinepubs/9699919799/) file I/O C API:s.
  39
  40 These are the MFAT functions that are inspired by POSIX functions:
  41
  42 | MFAT function | POSIX prototype |
  43 | --- | --- |
  44 | `mfat_close()` | [`close()`](https://pubs.opengroup.org/onlinepubs/9699919799/functions/close.html) |
  45 | `mfat_closedir()` | [`closedir()`](https://pubs.opengroup.org/onlinepubs/9699919799/functions/closedir.html) |
  46 | `mfat_fdopendir()` | [`fdopendir()`](https://pubs.opengroup.org/onlinepubs/9699919799/functions/fdopendir.html) |
  47 | `mfat_fstat()` | [`fstat()`](https://pubs.opengroup.org/onlinepubs/9699919799/functions/fstat.html) |
  48 | `mfat_lseek()` | [`lseek()`](https://pubs.opengroup.org/onlinepubs/9699919799/functions/lseek.html) |
  49 | `mfat_open()` | [`open()`](https://pubs.opengroup.org/onlinepubs/9699919799/functions/open.html) |
  50 | `mfat_opendir()` | [`opendir()`](https://pubs.opengroup.org/onlinepubs/9699919799/functions/opendir.html) |
  51 | `mfat_read()` | [`read()`](https://pubs.opengroup.org/onlinepubs/9699919799/functions/read.html) |
  52 | `mfat_readdir()` | [`readdir()`](https://pubs.opengroup.org/onlinepubs/9699919799/functions/readdir.html) |
  53 | `mfat_stat()` | [`stat()`](https://pubs.opengroup.org/onlinepubs/9699919799/functions/stat.html) |
  54 | `mfat_sync()` | [`sync()`](https://pubs.opengroup.org/onlinepubs/9699919799/functions/sync.html) |
  55 | `mfat_write()` | [`write()`](https://pubs.opengroup.org/onlinepubs/9699919799/functions/write.html) |
  56
  57 Note that the library is not fully POSIX compliant. For instance:
  58
  59 * Names of functions, types, and macros differ (an mfat_/MFAT_ prefix is used).
  60 * Some types are different (e.g. date/time types and sizes/names of integral types).
  61 * Some semantics are slightly different.
  62 * Some functionality is missing.
  63 * errno is not supported.
  64
  65 While the library itself is not fully POSIX compliant, it is suitable as a low level I/O implementation layer for higher level libraries, such as [newlib](https://sourceware.org/newlib/).
  66
  67 It is also easy to modify existing programs that use POSIX I/O routines to use the MFAT library instead.
  68
  69 ## FAT Documentation
  70
  71 [FAT.md](FAT.md)