source: trunk/src/lib/nt/kFsCache.h@ 2861

Last change on this file since 2861 was 2861, checked in by bird, 9 years ago

Updates
  • Property svn:eol-style set to native
  • Property svn:keywords set to Id
File size: 16.4 KB
Line 
1/* $Id: kFsCache.h 2861 2016-09-01 22:42:55Z bird $ */
2/** @file
3 * kFsCache.c - NT directory content cache.
4 */
5
6/*
7 * Copyright (c) 2016 knut st. osmundsen <bird-kBuild-spamx@anduin.net>
8 *
9 * Permission is hereby granted, free of charge, to any person obtaining a
10 * copy of this software and associated documentation files (the "Software"),
11 * to deal in the Software without restriction, including without limitation
12 * the rights to use, copy, modify, merge, publish, distribute, sublicense,
13 * and/or sell copies of the Software, and to permit persons to whom the
14 * Software is furnished to do so, subject to the following conditions:
15 *
16 * The above copyright notice and this permission notice shall be included
17 * in all copies or substantial portions of the Software.
18 *
19 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
20 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
21 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
22 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
23 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
24 * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
25 * IN THE SOFTWARE.
26 *
27 * Alternatively, the content of this file may be used under the terms of the
28 * GPL version 2 or later, or LGPL version 2.1 or later.
29 */
30
31#ifndef ___lib_nt_kFsCache_h___
32#define ___lib_nt_kFsCache_h___
33
34
35#include <k/kHlp.h>
36#include "ntstat.h"
37#ifndef NDEBUG
38# include <stdarg.h>
39#endif
40
41
42/** @def KFSCACHE_CFG_UTF16
43 * Whether to compile in the UTF-16 names support. */
44#define KFSCACHE_CFG_UTF16 1
45/** @def KFSCACHE_CFG_SHORT_NAMES
46 * Whether to compile in the short name support. */
47#define KFSCACHE_CFG_SHORT_NAMES 1
48/** @def KFSCACHE_CFG_PATH_HASH_TAB_SIZE
49 * Size of the path hash table. */
50#define KFSCACHE_CFG_PATH_HASH_TAB_SIZE 16381
51/** The max length paths we consider. */
52#define KFSCACHE_CFG_MAX_PATH 1024
53/** The max ANSI name length. */
54#define KFSCACHE_CFG_MAX_ANSI_NAME (256*3 + 16)
55/** The max UTF-16 name length. */
56#define KFSCACHE_CFG_MAX_UTF16_NAME (256*2 + 16)
57
58
59
60/** Special KFSOBJ::uCacheGen number indicating that it does not apply. */
61#define KFSOBJ_CACHE_GEN_IGNORE KU32_MAX
62
63
64/** @name KFSOBJ_TYPE_XXX - KFSOBJ::bObjType
65 * @{ */
66/** Directory, type KFSDIR. */
67#define KFSOBJ_TYPE_DIR KU8_C(0x01)
68/** Regular file - type KFSOBJ. */
69#define KFSOBJ_TYPE_FILE KU8_C(0x02)
70/** Other file - type KFSOBJ. */
71#define KFSOBJ_TYPE_OTHER KU8_C(0x03)
72/** Caching of a negative result - type KFSOBJ.
73 * @remarks We will allocate enough space for the largest cache node, so this
74 * can metamorph into any other object should it actually turn up. */
75#define KFSOBJ_TYPE_MISSING KU8_C(0x04)
76///** Invalidated entry flag. */
77//#define KFSOBJ_TYPE_F_INVALID KU8_C(0x20)
78/** @} */
79
80/** @name KFSOBJ_F_XXX - KFSOBJ::fFlags
81 * @{ */
82/** Whether the file system update the modified timestamp of directories
83 * when something is removed from it or added to it.
84 * @remarks They say NTFS is the only windows filesystem doing this. */
85#define KFSOBJ_F_WORKING_DIR_MTIME KU32_C(0x00000001)
86/** NTFS file system volume. */
87#define KFSOBJ_F_NTFS KU32_C(0x80000000)
88/** @} */
89
90
91#define IS_ALPHA(ch) ( ((ch) >= 'A' && (ch) <= 'Z') || ((ch) >= 'a' && (ch) <= 'z') )
92#define IS_SLASH(ch) ((ch) == '\\' || (ch) == '/')
93
94
95
96
97/** Pointer to a cache. */
98typedef struct KFSCACHE *PKFSCACHE;
99/** Pointer to a core object. */
100typedef struct KFSOBJ *PKFSOBJ;
101/** Pointer to a directory object. */
102typedef struct KFSDIR *PKFSDIR;
103/** Pointer to a directory hash table entry. */
104typedef struct KFSOBJHASH *PKFSOBJHASH;
105
106
107/**
108 * Directory hash table entry.
109 *
110 * There can be two of these per directory entry when the short name differs
111 * from the long name.
112 */
113typedef struct KFSOBJHASH
114{
115 /** Pointer to the next entry with the same hash. */
116 PKFSOBJHASH pNext;
117 /** Pointer to the object. */
118 PKFSOBJ pObj;
119} KFSOBJHASH;
120
121
122/** Pointer to a user data item. */
123typedef struct KFSUSERDATA *PKFSUSERDATA;
124/**
125 * User data item associated with a cache node.
126 */
127typedef struct KFSUSERDATA
128{
129 /** Pointer to the next piece of user data. */
130 PKFSUSERDATA pNext;
131 /** The key identifying this user. */
132 KUPTR uKey;
133 /** The destructor. */
134 void (*pfnDestructor)(PKFSCACHE pCache, PKFSOBJ pObj, PKFSUSERDATA pData);
135} KFSUSERDATA;
136
137
138/**
139 * Base cache node.
140 */
141typedef struct KFSOBJ
142{
143 /** Magic value (KFSOBJ_MAGIC). */
144 KU32 u32Magic;
145 /** Number of references. */
146 KU32 volatile cRefs;
147 /** The cache generation, see KFSOBJ_CACHE_GEN_IGNORE. */
148 KU32 uCacheGen;
149 /** The object type, KFSOBJ_TYPE_XXX. */
150 KU8 bObjType;
151 /** Set if the Stats member is valid, clear if not. */
152 KBOOL fHaveStats;
153 /** Unused flags. */
154 KBOOL abUnused[2];
155 /** Flags, KFSOBJ_F_XXX. */
156 KU32 fFlags;
157
158 /** Pointer to the parent (directory).
159 * This is only NULL for a root. */
160 PKFSDIR pParent;
161
162 /** The directory name. (Allocated after the structure.) */
163 const char *pszName;
164 /** The length of pszName. */
165 KU16 cchName;
166 /** The length of the parent path (up to where pszName starts).
167 * @note This is valuable when constructing an absolute path to this node by
168 * means of the parent pointer (no need for recursion). */
169 KU16 cchParent;
170#ifdef KFSCACHE_CFG_UTF16
171 /** The length of pwszName (in wchar_t's). */
172 KU16 cwcName;
173 /** The length of the parent UTF-16 path (in wchar_t's).
174 * @note This is valuable when constructing an absolute path to this node by
175 * means of the parent pointer (no need for recursion). */
176 KU16 cwcParent;
177 /** The UTF-16 object name. (Allocated after the structure.) */
178 const wchar_t *pwszName;
179#endif
180
181#ifdef KFSCACHE_CFG_SHORT_NAMES
182 /** The short object name. (Allocated after the structure, could be same
183 * as pszName.) */
184 const char *pszShortName;
185 /** The length of pszShortName. */
186 KU16 cchShortName;
187 /** The length of the short parent path (up to where pszShortName starts). */
188 KU16 cchShortParent;
189# ifdef KFSCACHE_CFG_UTF16
190 /** The length of pwszShortName (in wchar_t's). */
191 KU16 cwcShortName;
192 /** The length of the short parent UTF-16 path (in wchar_t's). */
193 KU16 cwcShortParent;
194 /** The UTF-16 short object name. (Allocated after the structure, possibly
195 * same as pwszName.) */
196 const wchar_t *pwszShortName;
197# endif
198#endif
199
200 /** Pointer to the first user data item */
201 PKFSUSERDATA pUserDataHead;
202
203 /** Stats - only valid when fHaveStats is set. */
204 BirdStat_T Stats;
205} KFSOBJ;
206
207/** The magic for a KFSOBJ structure (Thelonious Sphere Monk). */
208#define KFSOBJ_MAGIC KU32_C(0x19171010)
209
210
211/**
212 * Directory node in the cache.
213 */
214typedef struct KFSDIR
215{
216 /** The core object information. */
217 KFSOBJ Obj;
218
219 /** Child objects. */
220 PKFSOBJ *papChildren;
221 /** The number of child objects. */
222 KU32 cChildren;
223
224 /** The size of the hash table.
225 * @remarks The hash table is optional and only used when there are a lot of
226 * entries in the directory. */
227 KU32 cHashTab;
228 /** Pointer to the hash table.
229 * @todo this isn't quite there yet, structure wise. sigh. */
230 PKFSOBJHASH paHashTab;
231
232 /** Handle to the directory (we generally keep it open). */
233#ifndef DECLARE_HANDLE
234 KUPTR hDir;
235#else
236 HANDLE hDir;
237#endif
238 /** The device number we queried/inherited when opening it. */
239 KU64 uDevNo;
240
241 /** The last write time sampled the last time the directory was refreshed.
242 * @remarks May differ from st_mtim because it will be updated when the
243 * parent directory is refreshed. */
244 KI64 iLastWrite;
245
246 /** Set if populated. */
247 KBOOL fPopulated;
248} KFSDIR;
249
250
251/**
252 * Lookup errors.
253 */
254typedef enum KFSLOOKUPERROR
255{
256 /** Lookup was a success. */
257 KFSLOOKUPERROR_SUCCESS = 0,
258 /** A path component was not found. */
259 KFSLOOKUPERROR_PATH_COMP_NOT_FOUND,
260 /** A path component is not a directory. */
261 KFSLOOKUPERROR_PATH_COMP_NOT_DIR,
262 /** The final path entry is not a directory (trailing slash). */
263 KFSLOOKUPERROR_NOT_DIR,
264 /** Not found. */
265 KFSLOOKUPERROR_NOT_FOUND,
266 /** The path is too long. */
267 KFSLOOKUPERROR_PATH_TOO_LONG,
268 /** Unsupported path type. */
269 KFSLOOKUPERROR_UNSUPPORTED,
270 /** We're out of memory. */
271 KFSLOOKUPERROR_OUT_OF_MEMORY,
272
273 /** Error opening directory. */
274 KFSLOOKUPERROR_DIR_OPEN_ERROR,
275 /** Error reading directory. */
276 KFSLOOKUPERROR_DIR_READ_ERROR,
277 /** UTF-16 to ANSI conversion error. */
278 KFSLOOKUPERROR_ANSI_CONVERSION_ERROR,
279 /** ANSI to UTF-16 conversion error. */
280 KFSLOOKUPERROR_UTF16_CONVERSION_ERROR,
281 /** Internal error. */
282 KFSLOOKUPERROR_INTERNAL_ERROR
283} KFSLOOKUPERROR;
284
285
286/** Pointer to an ANSI path hash table entry. */
287typedef struct KFSHASHA *PKFSHASHA;
288/**
289 * ANSI file system path hash table entry.
290 * The path hash table allows us to skip parsing and walking a path.
291 */
292typedef struct KFSHASHA
293{
294 /** Next entry with the same hash table slot. */
295 PKFSHASHA pNext;
296 /** Path hash value. */
297 KU32 uHashPath;
298 /** The path length. */
299 KU16 cchPath;
300 /** Set if aboslute path. */
301 KBOOL fAbsolute;
302 /** The cache generation ID. */
303 KU32 uCacheGen;
304 /** The lookup error (when pFsObj is NULL). */
305 KFSLOOKUPERROR enmError;
306 /** The path. (Allocated after the structure.) */
307 const char *pszPath;
308 /** Pointer to the matching FS object.
309 * This is NULL for negative path entries? */
310 PKFSOBJ pFsObj;
311} KFSHASHA;
312
313
314#ifdef KFSCACHE_CFG_UTF16
315/** Pointer to an UTF-16 path hash table entry. */
316typedef struct KFSHASHW *PKFSHASHW;
317/**
318 * UTF-16 file system path hash table entry. The path hash table allows us
319 * to skip parsing and walking a path.
320 */
321typedef struct KFSHASHW
322{
323 /** Next entry with the same hash table slot. */
324 PKFSHASHW pNext;
325 /** Path hash value. */
326 KU32 uHashPath;
327 /** The path length (in wchar_t units). */
328 KU16 cwcPath;
329 /** Set if aboslute path. */
330 KBOOL fAbsolute;
331 /** The cache generation ID. */
332 KU32 uCacheGen;
333 /** The lookup error (when pFsObj is NULL). */
334 KFSLOOKUPERROR enmError;
335 /** The path. (Allocated after the structure.) */
336 const wchar_t *pwszPath;
337 /** Pointer to the matching FS object.
338 * This is NULL for negative path entries? */
339 PKFSOBJ pFsObj;
340} KFSHASHW;
341#endif
342
343
344/** @name KFSCACHE_F_XXX
345 * @{ */
346/** Whether to cache missing directory entries (KFSOBJ_TYPE_MISSING). */
347#define KFSCACHE_F_MISSING_OBJECTS KU32_C(0x00000001)
348/** Whether to cache missing paths. */
349#define KFSCACHE_F_MISSING_PATHS KU32_C(0x00000002)
350/** @} */
351
352
353/**
354 * Directory cache instance.
355 */
356typedef struct KFSCACHE
357{
358 /** Magic value (KFSCACHE_MAGIC). */
359 KU32 u32Magic;
360 /** Cache flags. */
361 KU32 fFlags;
362
363 /** The current cache generation for objects that already exists. */
364 KU32 uGeneration;
365 /** The current cache generation for missing objects, negative results, ++. */
366 KU32 uGenerationMissing;
367
368 /** Number of cache objects. */
369 KSIZE cObjects;
370 /** Memory occupied by the cache object structures. */
371 KSIZE cbObjects;
372 /** Number of lookups. */
373 KSIZE cLookups;
374 /** Number of hits in the path hash tables. */
375 KSIZE cPathHashHits;
376 /** Number of hits walking the file system hierarchy. */
377 KSIZE cWalkHits;
378
379 /** The root directory. */
380 KFSDIR RootDir;
381
382 /** File system hash table for ANSI filename strings. */
383 PKFSHASHA apAnsiPaths[KFSCACHE_CFG_PATH_HASH_TAB_SIZE];
384 /** Number of paths in the apAnsiPaths hash table. */
385 KSIZE cAnsiPaths;
386 /** Number of collisions in the apAnsiPaths hash table. */
387 KSIZE cAnsiPathCollisions;
388 /** Amount of memory used by the path entries. */
389 KSIZE cbAnsiPaths;
390
391#ifdef KFSCACHE_CFG_UTF16
392 /** Number of paths in the apUtf16Paths hash table. */
393 KSIZE cUtf16Paths;
394 /** Number of collisions in the apUtf16Paths hash table. */
395 KSIZE cUtf16PathCollisions;
396 /** Amount of memory used by the UTF-16 path entries. */
397 KSIZE cbUtf16Paths;
398 /** File system hash table for UTF-16 filename strings. */
399 PKFSHASHW apUtf16Paths[KFSCACHE_CFG_PATH_HASH_TAB_SIZE];
400#endif
401} KFSCACHE;
402
403/** Magic value for KFSCACHE::u32Magic (Jon Batiste). */
404#define KFSCACHE_MAGIC KU32_C(0x19861111)
405
406
407/** @def KW_LOG
408 * Generic logging.
409 * @param a Argument list for kFsCacheDbgPrintf */
410#ifdef NDEBUG
411# define KFSCACHE_LOG(a) do { } while (0)
412#else
413# define KFSCACHE_LOG(a) kFsCacheDbgPrintf a
414void kFsCacheDbgPrintfV(const char *pszFormat, va_list va);
415void kFsCacheDbgPrintf(const char *pszFormat, ...);
416#endif
417
418
419KBOOL kFsCacheDirEnsurePopuplated(PKFSCACHE pCache, PKFSDIR pDir, KFSLOOKUPERROR *penmError);
420KBOOL kFsCacheDirAddChild(PKFSCACHE pCache, PKFSDIR pParent, PKFSOBJ pChild, KFSLOOKUPERROR *penmError);
421PKFSOBJ kFsCacheCreateObject(PKFSCACHE pCache, PKFSDIR pParent,
422 char const *pszName, KU16 cchName, wchar_t const *pwszName, KU16 cwcName,
423#ifdef KFSCACHE_CFG_SHORT_NAMES
424 char const *pszShortName, KU16 cchShortName, wchar_t const *pwszShortName, KU16 cwcShortName,
425#endif
426 KU8 bObjType, KFSLOOKUPERROR *penmError);
427PKFSOBJ kFsCacheCreateObjectW(PKFSCACHE pCache, PKFSDIR pParent, wchar_t const *pwszName, KU32 cwcName,
428#ifdef KFSCACHE_CFG_SHORT_NAMES
429 wchar_t const *pwszShortName, KU32 cwcShortName,
430#endif
431 KU8 bObjType, KFSLOOKUPERROR *penmError);
432PKFSOBJ kFsCacheLookupA(PKFSCACHE pCache, const char *pszPath, KFSLOOKUPERROR *penmError);
433PKFSOBJ kFsCacheLookupW(PKFSCACHE pCache, const wchar_t *pwszPath, KFSLOOKUPERROR *penmError);
434PKFSOBJ kFsCacheLookupRelativeToDirA(PKFSCACHE pCache, PKFSDIR pParent, const char *pszPath, KU32 cchPath,
435 KFSLOOKUPERROR *penmError);
436PKFSOBJ kFsCacheLookupRelativeToDirW(PKFSCACHE pCache, PKFSDIR pParent, const wchar_t *pwszPath, KU32 cwcPath,
437 KFSLOOKUPERROR *penmError);
438PKFSOBJ kFsCacheLookupWithLengthA(PKFSCACHE pCache, const char *pchPath, KSIZE cchPath, KFSLOOKUPERROR *penmError);
439PKFSOBJ kFsCacheLookupWithLengthW(PKFSCACHE pCache, const wchar_t *pwcPath, KSIZE cwcPath, KFSLOOKUPERROR *penmError);
440PKFSOBJ kFsCacheLookupNoMissingA(PKFSCACHE pCache, const char *pszPath, KFSLOOKUPERROR *penmError);
441PKFSOBJ kFsCacheLookupNoMissingW(PKFSCACHE pCache, const wchar_t *pwszPath, KFSLOOKUPERROR *penmError);
442
443
444KU32 kFsCacheObjRelease(PKFSCACHE pCache, PKFSOBJ pObj);
445KU32 kFsCacheObjRetain(PKFSOBJ pObj);
446PKFSUSERDATA kFsCacheObjAddUserData(PKFSCACHE pCache, PKFSOBJ pObj, KUPTR uKey, KSIZE cbUserData);
447PKFSUSERDATA kFsCacheObjGetUserData(PKFSCACHE pCache, PKFSOBJ pObj, KUPTR uKey);
448KBOOL kFsCacheObjGetFullPathA(PKFSOBJ pObj, char *pszPath, KSIZE cbPath, char chSlash);
449KBOOL kFsCacheObjGetFullPathW(PKFSOBJ pObj, wchar_t *pwszPath, KSIZE cwcPath, wchar_t wcSlash);
450KBOOL kFsCacheObjGetFullShortPathA(PKFSOBJ pObj, char *pszPath, KSIZE cbPath, char chSlash);
451KBOOL kFsCacheObjGetFullShortPathW(PKFSOBJ pObj, wchar_t *pwszPath, KSIZE cwcPath, wchar_t wcSlash);
452
453KBOOL kFsCacheFileSimpleOpenReadClose(PKFSCACHE pCache, PKFSOBJ pFileObj, KU64 offStart, void *pvBuf, KSIZE cbToRead);
454
455PKFSCACHE kFsCacheCreate(KU32 fFlags);
456void kFsCacheDestroy(PKFSCACHE);
457void kFsCacheInvalidateMissing(PKFSCACHE pFsCache);
458void kFsCacheInvalidateAll(PKFSCACHE pFsCache);
459
460#endif
Note: See TracBrowser for help on using the repository browser.