[Fontconfig] Structure of cache files

[Patrick Lam]

I wrote a freeform document that describes the structure of the cache
files; it's included below.  I'm not sure where I could put it in CVS...

---

Fontconfig maintains two cache files: a global cache (on a per-user
basis) and directory caches (created by the superuser).  The global
cache consists of a number of concatenated directory caches.

Here's the structure of a directory cache:

* a next-offset/machine signature line in plain ASCII:

    + (as a %8x string) the offset of the next architecture's block
    + (produced by FcCacheMachineSignature): an architecture signature
        - endian-testing signature 0x12345678
        - sizeof (char)
            - sizeof (char *)
            - sizeof (int)
            - sizeof (FcPattern)
            - sizeof (FcPatternEltPtr)
            - sizeof (struct _FcPatternElt *)
            - sizeof (FcPatternElt)
            - sizeof (FcObjectPtr)
            - sizeof (FcValueListPtr)
            - sizeof (FcValue)
            - sizeof (FcValueBinding)
            - sizeof (struct _FcValueList *)
            - sizeof (FcCharSet)
            - sizeof (FcCharLeaf **)
            - sizeof (FcChar16 *)
            - sizeof (FcChar16)
            - sizeof (FcCharLeaf)
            - sizeof (FcChar32)
            - sizeof (FcCache)

* a header block:

typedef struct _FcCache {
    int     magic;              /* 0xFC02FC02 */
    int     count;              /* number of bytes of data in block */
    int     bank;               /* bank ID */
    int     pattern_count;      /* number of FcPatterns */
    int     patternelt_count;   /* number of FcPatternElts */
    int     valuelist_count;    /* number of FcValueLists */
    int     str_count;       /* size of strings appearing as FcValues */
    int     langset_count;      /* number of FcLangSets */
    int     charset_count;      /* number of FcCharSets */
    int     charset_numbers_count;
    int     charset_leaf_count;
    int     charset_leaf_idx_count;
}

* pattern data:

Stored as a character array containing FcPatterns, FcPatternElts,
FcValueLists, strings, FcLangSets and FcCharSets.  To permit mmaping,
this data is aligned on an 8k boundary.

About banks: when caching a directory, fontconfig assigns a random
bank number to that directory.  This bank number combines with the
static IDs to canonically identify resources; for instance, a
FcPattern might refer to its first component FcPatternElt as
(92848929, 2).  The bank ids have to be part of the data structures so
that when given, for instance, an FcValueList in isolation, it is
possible to find where the FcValue is pointing to.  Since the bank ids
are chosen with rand(), the probability of collision is quite low (if
the random number generator isn't stupid).

The structure of a global cache is similar.  It also starts with a
machine identification line in plain ASCII.  Next, it contains a string
containing the directory name, followed by that directory's cache (as
above); this repeats for all of the directories in the cache.