idx

C library providing a standard for (non-standard) 64-bit file indexing functions.
git clone git://src.gearsix.net/idx
Log | Files | Refs | Atom | README

README.md (2217B)

      1 
      2 # idx.h
      3 
      4 **idx.h** is a small C library that provides a standard interface to the (non-standard) 64-bit system-alternatives of the standard library file indexing functions: `fseek` and `ftell`. These alternatives are required if you want to index a file that's potentially larger than 2GB (32-bits).
      5 
      6 
      7 ## Background
      8 
      9 This library exists because the standard library functions `fseek` and `ftell` are limited to using `long int` values (not even an `unsigned long int`). A `long int` has been defined as "at least 32-bits wide" in standard C; this limits the `fseek` and `ftell` to indexing files that are 2GB at most, which for some cases makes them fairly useless.
     10 The reason these functions use this data type is because they are from the pre-standard C days, before fixed-width data types and `long long int`, where `long int` was just a 'big integer' and not necessarily a 32-bit integer.
     11 
     12 Unfortunately, while the ISO-C committee standardised fixed-width data types with `stdint.h` in C99, they never added updated versions of functions that used the (now-defined, ergo limit) data types. This means that to index a file larger than 2GB on a modern system using C requires you to use platform-specific alternatives, such as `fseeko` in POSIX, or `fseeki64` in Windows, etc. *Even better*, most of these alternatives were written before ISO-C introduced fixed-width data types, so they don't even make use of those nice standard data types.
     13 
     14 It would be nice to have a `uintmax_t ftell(FILE *stream)` on all platforms (and the same for `fseek`) but instead we have `__int64 ftelli64(FILE *stream)` on *Windows*, `off_t ftello(FILE *stream)` on *POSIX.1*, etc.
     15 
     16 This isn't a huge inconvenience but writing cross-platform C with a bunch of `#ifdef`s is *ugly*. **idx.h** aims to replace that inconvenience with a functions that are just as nice to use as the standard library.
     17 
     18 
     19 ## API
     20 
     21 **idx_t** - The system's own 64-bit data type.
     22 
     23 - `off_t` on *POSIX*
     24 - `__int64` on *Windows*
     25 
     26 
     27 **idxseek**, `idx_t idxseek(FILE *f, idx_t origin, int origin);`
     28 
     29 **idxtell**, `idx_t idxtell(FILE *f);`
     30 
     31 
     32 ## Support
     33 
     34 Currently support platforms are:
     35 
     36 - Unixes (Linux, BSD's, etc) and MacOS
     37 - Windows
     38 
     39 
     40 ## Authors
     41 
     42 - gearsix, 2022