lib/fprint.h

   1 #ifndef H_FINGERPRINT
   2 #define H_FINGERPRINT
   3
   4 /** \file lib/fprint.h
   5  * Identify a file name path by a unique "finger print".
   6  */
   7
   8 #include "hash.h"
   9 #include "header.h"
  10
  11 /**
  12  * Finger print cache entry.
  13  * This is really a directory and symlink cache. We don't differentiate between
  14  * the two. We can prepopulate it, which allows us to easily conduct "fake"
  15  * installs of a system w/o actually mounting filesystems.
  16  */
  17 struct fprintCacheEntry_s {
  18     const char * dirName;               /*!< path to existing directory */
  19     dev_t dev;                          /*!< stat(2) device number */
  20     ino_t ino;                          /*!< stat(2) inode number */
  21     int isFake;                         /*!< (currently unused) */
  22 };
  23
  24 /**
  25  * Finger print cache.
  26  */
  27 typedef /*@abstract@*/ struct fprintCache_s {
  28     hashTable ht;                       /*!< hashed by dirName */
  29 } * fingerPrintCache;
  30
  31 /**
  32  * Associates a trailing sub-directory and final base name with an existing
  33  * directory finger print.
  34  */
  35 typedef struct fingerPrint_s {
  36 /*! directory finger print entry (the directory path is stat(2)-able */
  37     const struct fprintCacheEntry_s * entry;
  38 /*! trailing sub-directory path (directories that are not stat(2)-able */
  39 /*@owned@*/ /*@null@*/ const char * subDir;
  40 /*@dependent@*/ const char * baseName;  /*!< file base name */
  41 } fingerPrint;
  42
  43 /* only if !scarceMemory */
  44 /** */
  45 #define fpFree(a) free((void *)(a).baseName)
  46
  47 /** */
  48 #define FP_ENTRY_EQUAL(a, b) (((a)->dev == (b)->dev) && ((a)->ino == (b)->ino))
  49
  50 /** */
  51 #define FP_EQUAL(a, b) ( \
  52         FP_ENTRY_EQUAL((a).entry, (b).entry) && \
  53         !strcmp((a).baseName, (b).baseName) && ( \
  54             ((a).subDir == (b).subDir) || \
  55             ((a).subDir && (b).subDir && !strcmp((a).subDir, (b).subDir)) \
  56         ) \
  57     )
  58
  59 #ifdef __cplusplus
  60 extern "C" {
  61 #endif
  62
  63 /* Be carefull with the memory... assert(*fullName == '/' || !scareMemory) */
  64
  65 /**
  66  * Create finger print cache.
  67  * @param sizeHint      number of elements expected
  68  * @return pointer to initialized fingerprint cache
  69  */
  70 /*@only@*/ fingerPrintCache fpCacheCreate(int sizeHint) /*@*/;
  71
  72 /**
  73  * Destroy finger print cache.
  74  * @param cache         pointer to fingerprint cache
  75  */
  76 void            fpCacheFree(/*@only@*/ fingerPrintCache cache);
  77
  78 /**
  79  * Return finger print of a file path.
  80  * @param cache         pointer to fingerprint cache
  81  * @param dirName       leading directory name of file path
  82  * @param baseName      base name of file path
  83  * @param scareMemory
  84  * @return pointer to the finger print associated with a file path.
  85  */
  86 fingerPrint     fpLookup(fingerPrintCache cache, const char * dirName,
  87                         const char * baseName, int scareMemory) /*@*/;
  88
  89 /**
  90  * Return hash value for a finger print.
  91  * Hash based on dev and inode only!
  92  * @param key           pointer to finger print entry
  93  * @return hash value
  94  */
  95 unsigned int fpHashFunction(const void * key)   /*@*/;
  96
  97 /**
  98  * Compare two finger print entries.
  99  * exactly equivalent to FP_EQUAL macro.
 100  * @param key1          finger print 1
 101  * @param key2          finger print 2
 102  * @return result of comparing key1 and key2
 103  */
 104 int fpEqual(const void * key1, const void * key2)       /*@*/;
 105
 106 /**
 107  * Return finger prints of an array of file paths.
 108  * @warning: scareMemory is assumed!
 109  * @param cache         pointer to fingerprint cache
 110  * @param dirNames      directory names
 111  * @param baseNames     file base names
 112  * @param dirIndexes    index into dirNames for each baseNames
 113  * @param fileCount     number of file entries
 114  * @retval fpList       pointer to array of finger prints
 115  */
 116 void fpLookupList(fingerPrintCache cache, const char ** dirNames,
 117                   const char ** baseNames, const int * dirIndexes,
 118                   int fileCount, fingerPrint * fpList)
 119                         /*@modifies cache, *fpList @*/;
 120
 121 /**
 122  * Return finger prints of all file names in header.
 123  * @warning: scareMemory is assumed!
 124  * @param cache         pointer to fingerprint cache
 125  * @param h             package header
 126  * @retval fpList       pointer to array of finger prints
 127  */
 128 void fpLookupHeader(fingerPrintCache cache, Header h, fingerPrint * fpList)
 129         /*@modifies h, cache, *fpList @*/;
 130
 131 #ifdef __cplusplus
 132 }
 133 #endif
 134
 135 #endif