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

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

updates
  • Property svn:eol-style set to native
  • Property svn:keywords set to Id
File size: 16.5 KB
Line 
1/* $Id: kFsCache.h 2862 2016-09-02 02:39:56Z 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 /** Set if it needs re-populated. */
249 KBOOL fNeedRePopulating;
250} KFSDIR;
251
252
253/**
254 * Lookup errors.
255 */
256typedef enum KFSLOOKUPERROR
257{
258 /** Lookup was a success. */
259 KFSLOOKUPERROR_SUCCESS = 0,
260 /** A path component was not found. */
261 KFSLOOKUPERROR_PATH_COMP_NOT_FOUND,
262 /** A path component is not a directory. */
263 KFSLOOKUPERROR_PATH_COMP_NOT_DIR,
264 /** The final path entry is not a directory (trailing slash). */
265 KFSLOOKUPERROR_NOT_DIR,
266 /** Not found. */
267 KFSLOOKUPERROR_NOT_FOUND,
268 /** The path is too long. */
269 KFSLOOKUPERROR_PATH_TOO_LONG,
270 /** Unsupported path type. */
271 KFSLOOKUPERROR_UNSUPPORTED,
272 /** We're out of memory. */
273 KFSLOOKUPERROR_OUT_OF_MEMORY,
274
275 /** Error opening directory. */
276 KFSLOOKUPERROR_DIR_OPEN_ERROR,
277 /** Error reading directory. */
278 KFSLOOKUPERROR_DIR_READ_ERROR,
279 /** UTF-16 to ANSI conversion error. */
280 KFSLOOKUPERROR_ANSI_CONVERSION_ERROR,
281 /** ANSI to UTF-16 conversion error. */
282 KFSLOOKUPERROR_UTF16_CONVERSION_ERROR,
283 /** Internal error. */
284 KFSLOOKUPERROR_INTERNAL_ERROR
285} KFSLOOKUPERROR;
286
287
288/** Pointer to an ANSI path hash table entry. */
289typedef struct KFSHASHA *PKFSHASHA;
290/**
291 * ANSI file system path hash table entry.
292 * The path hash table allows us to skip parsing and walking a path.
293 */
294typedef struct KFSHASHA
295{
296 /** Next entry with the same hash table slot. */
297 PKFSHASHA pNext;
298 /** Path hash value. */
299 KU32 uHashPath;
300 /** The path length. */
301 KU16 cchPath;
302 /** Set if aboslute path. */
303 KBOOL fAbsolute;
304 /** The cache generation ID. */
305 KU32 uCacheGen;
306 /** The lookup error (when pFsObj is NULL). */
307 KFSLOOKUPERROR enmError;
308 /** The path. (Allocated after the structure.) */
309 const char *pszPath;
310 /** Pointer to the matching FS object.
311 * This is NULL for negative path entries? */
312 PKFSOBJ pFsObj;
313} KFSHASHA;
314
315
316#ifdef KFSCACHE_CFG_UTF16
317/** Pointer to an UTF-16 path hash table entry. */
318typedef struct KFSHASHW *PKFSHASHW;
319/**
320 * UTF-16 file system path hash table entry. The path hash table allows us
321 * to skip parsing and walking a path.
322 */
323typedef struct KFSHASHW
324{
325 /** Next entry with the same hash table slot. */
326 PKFSHASHW pNext;
327 /** Path hash value. */
328 KU32 uHashPath;
329 /** The path length (in wchar_t units). */
330 KU16 cwcPath;
331 /** Set if aboslute path. */
332 KBOOL fAbsolute;
333 /** The cache generation ID. */
334 KU32 uCacheGen;
335 /** The lookup error (when pFsObj is NULL). */
336 KFSLOOKUPERROR enmError;
337 /** The path. (Allocated after the structure.) */
338 const wchar_t *pwszPath;
339 /** Pointer to the matching FS object.
340 * This is NULL for negative path entries? */
341 PKFSOBJ pFsObj;
342} KFSHASHW;
343#endif
344
345
346/** @name KFSCACHE_F_XXX
347 * @{ */
348/** Whether to cache missing directory entries (KFSOBJ_TYPE_MISSING). */
349#define KFSCACHE_F_MISSING_OBJECTS KU32_C(0x00000001)
350/** Whether to cache missing paths. */
351#define KFSCACHE_F_MISSING_PATHS KU32_C(0x00000002)
352/** @} */
353
354
355/**
356 * Directory cache instance.
357 */
358typedef struct KFSCACHE
359{
360 /** Magic value (KFSCACHE_MAGIC). */
361 KU32 u32Magic;
362 /** Cache flags. */
363 KU32 fFlags;
364
365 /** The current cache generation for objects that already exists. */
366 KU32 uGeneration;
367 /** The current cache generation for missing objects, negative results, ++. */
368 KU32 uGenerationMissing;
369
370 /** Number of cache objects. */
371 KSIZE cObjects;
372 /** Memory occupied by the cache object structures. */
373 KSIZE cbObjects;
374 /** Number of lookups. */
375 KSIZE cLookups;
376 /** Number of hits in the path hash tables. */
377 KSIZE cPathHashHits;
378 /** Number of hits walking the file system hierarchy. */
379 KSIZE cWalkHits;
380
381 /** The root directory. */
382 KFSDIR RootDir;
383
384 /** File system hash table for ANSI filename strings. */
385 PKFSHASHA apAnsiPaths[KFSCACHE_CFG_PATH_HASH_TAB_SIZE];
386 /** Number of paths in the apAnsiPaths hash table. */
387 KSIZE cAnsiPaths;
388 /** Number of collisions in the apAnsiPaths hash table. */
389 KSIZE cAnsiPathCollisions;
390 /** Amount of memory used by the path entries. */
391 KSIZE cbAnsiPaths;
392
393#ifdef KFSCACHE_CFG_UTF16
394 /** Number of paths in the apUtf16Paths hash table. */
395 KSIZE cUtf16Paths;
396 /** Number of collisions in the apUtf16Paths hash table. */
397 KSIZE cUtf16PathCollisions;
398 /** Amount of memory used by the UTF-16 path entries. */
399 KSIZE cbUtf16Paths;
400 /** File system hash table for UTF-16 filename strings. */
401 PKFSHASHW apUtf16Paths[KFSCACHE_CFG_PATH_HASH_TAB_SIZE];
402#endif
403} KFSCACHE;
404
405/** Magic value for KFSCACHE::u32Magic (Jon Batiste). */
406#define KFSCACHE_MAGIC KU32_C(0x19861111)
407
408
409/** @def KW_LOG
410 * Generic logging.
411 * @param a Argument list for kFsCacheDbgPrintf */
412#ifdef NDEBUG
413# define KFSCACHE_LOG(a) do { } while (0)
414#else
415# define KFSCACHE_LOG(a) kFsCacheDbgPrintf a
416void kFsCacheDbgPrintfV(const char *pszFormat, va_list va);
417void kFsCacheDbgPrintf(const char *pszFormat, ...);
418#endif
419
420
421KBOOL kFsCacheDirEnsurePopuplated(PKFSCACHE pCache, PKFSDIR pDir, KFSLOOKUPERROR *penmError);
422KBOOL kFsCacheDirAddChild(PKFSCACHE pCache, PKFSDIR pParent, PKFSOBJ pChild, KFSLOOKUPERROR *penmError);
423PKFSOBJ kFsCacheCreateObject(PKFSCACHE pCache, PKFSDIR pParent,
424 char const *pszName, KU16 cchName, wchar_t const *pwszName, KU16 cwcName,
425#ifdef KFSCACHE_CFG_SHORT_NAMES
426 char const *pszShortName, KU16 cchShortName, wchar_t const *pwszShortName, KU16 cwcShortName,
427#endif
428 KU8 bObjType, KFSLOOKUPERROR *penmError);
429PKFSOBJ kFsCacheCreateObjectW(PKFSCACHE pCache, PKFSDIR pParent, wchar_t const *pwszName, KU32 cwcName,
430#ifdef KFSCACHE_CFG_SHORT_NAMES
431 wchar_t const *pwszShortName, KU32 cwcShortName,
432#endif
433 KU8 bObjType, KFSLOOKUPERROR *penmError);
434PKFSOBJ kFsCacheLookupA(PKFSCACHE pCache, const char *pszPath, KFSLOOKUPERROR *penmError);
435PKFSOBJ kFsCacheLookupW(PKFSCACHE pCache, const wchar_t *pwszPath, KFSLOOKUPERROR *penmError);
436PKFSOBJ kFsCacheLookupRelativeToDirA(PKFSCACHE pCache, PKFSDIR pParent, const char *pszPath, KU32 cchPath,
437 KFSLOOKUPERROR *penmError);
438PKFSOBJ kFsCacheLookupRelativeToDirW(PKFSCACHE pCache, PKFSDIR pParent, const wchar_t *pwszPath, KU32 cwcPath,
439 KFSLOOKUPERROR *penmError);
440PKFSOBJ kFsCacheLookupWithLengthA(PKFSCACHE pCache, const char *pchPath, KSIZE cchPath, KFSLOOKUPERROR *penmError);
441PKFSOBJ kFsCacheLookupWithLengthW(PKFSCACHE pCache, const wchar_t *pwcPath, KSIZE cwcPath, KFSLOOKUPERROR *penmError);
442PKFSOBJ kFsCacheLookupNoMissingA(PKFSCACHE pCache, const char *pszPath, KFSLOOKUPERROR *penmError);
443PKFSOBJ kFsCacheLookupNoMissingW(PKFSCACHE pCache, const wchar_t *pwszPath, KFSLOOKUPERROR *penmError);
444
445
446KU32 kFsCacheObjRelease(PKFSCACHE pCache, PKFSOBJ pObj);
447KU32 kFsCacheObjRetain(PKFSOBJ pObj);
448PKFSUSERDATA kFsCacheObjAddUserData(PKFSCACHE pCache, PKFSOBJ pObj, KUPTR uKey, KSIZE cbUserData);
449PKFSUSERDATA kFsCacheObjGetUserData(PKFSCACHE pCache, PKFSOBJ pObj, KUPTR uKey);
450KBOOL kFsCacheObjGetFullPathA(PKFSOBJ pObj, char *pszPath, KSIZE cbPath, char chSlash);
451KBOOL kFsCacheObjGetFullPathW(PKFSOBJ pObj, wchar_t *pwszPath, KSIZE cwcPath, wchar_t wcSlash);
452KBOOL kFsCacheObjGetFullShortPathA(PKFSOBJ pObj, char *pszPath, KSIZE cbPath, char chSlash);
453KBOOL kFsCacheObjGetFullShortPathW(PKFSOBJ pObj, wchar_t *pwszPath, KSIZE cwcPath, wchar_t wcSlash);
454
455KBOOL kFsCacheFileSimpleOpenReadClose(PKFSCACHE pCache, PKFSOBJ pFileObj, KU64 offStart, void *pvBuf, KSIZE cbToRead);
456
457PKFSCACHE kFsCacheCreate(KU32 fFlags);
458void kFsCacheDestroy(PKFSCACHE);
459void kFsCacheInvalidateMissing(PKFSCACHE pFsCache);
460void kFsCacheInvalidateAll(PKFSCACHE pFsCache);
461
462#endif
Note: See TracBrowser for help on using the repository browser.