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