vfslowlevel.h@ 84546

Last change on this file since 84546 was 84194, checked in by vboxsync, 5 years ago
IPRT: Adding RTZIPTAR_C_UPDATE, RTZipTarFsStreamForFile and RTZipTarFsStreamTruncate. Also added some new VFS functions and changed the fReadOnly argument of RTVfsNewFsStream into RTFILE_O_ACCESS_MASK, so it is possible to specify read+write. Untested. [doxyfix] bugref:9699
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 59.9 KB

Line
1	/** @file
2	* IPRT - Virtual Filesystem.
3	*/
4
5	/*
6	* Copyright (C) 2010-2020 Oracle Corporation
7	*
8	* This file is part of VirtualBox Open Source Edition (OSE), as
9	* available from http://www.virtualbox.org. This file is free software;
10	* you can redistribute it and/or modify it under the terms of the GNU
11	* General Public License (GPL) as published by the Free Software
12	* Foundation, in version 2 as it comes in the "COPYING" file of the
13	* VirtualBox OSE distribution. VirtualBox OSE is distributed in the
14	* hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
15	*
16	* The contents of this file may alternatively be used under the terms
17	* of the Common Development and Distribution License Version 1.0
18	* (CDDL) only, as it comes in the "COPYING.CDDL" file of the
19	* VirtualBox OSE distribution, in which case the provisions of the
20	* CDDL are applicable instead of those of the GPL.
21	*
22	* You may elect to license modified versions of this file under the
23	* terms and conditions of either the GPL or the CDDL or both.
24	*/
25
26	#ifndef IPRT_INCLUDED_vfslowlevel_h
27	#define IPRT_INCLUDED_vfslowlevel_h
28	#ifndef RT_WITHOUT_PRAGMA_ONCE
29	# pragma once
30	#endif
31
32	#include <iprt/vfs.h>
33	#include <iprt/errcore.h>
34	#include <iprt/list.h>
35	#include <iprt/param.h>
36
37
38	RT_C_DECLS_BEGIN
39
40	/** @defgroup grp_rt_vfs_lowlevel RTVfs - Low-level Interface.
41	* @ingroup grp_rt_vfs
42	* @{
43	*/
44
45
46	/** @name VFS Lock Abstraction
47	* @todo This should be moved somewhere else as it is of general use.
48	* @{ */
49
50	/**
51	* VFS lock types.
52	*/
53	typedef enum RTVFSLOCKTYPE
54	{
55	/** Invalid lock type. */
56	RTVFSLOCKTYPE_INVALID = 0,
57	/** Read write semaphore. */
58	RTVFSLOCKTYPE_RW,
59	/** Fast mutex semaphore (critical section in ring-3). */
60	RTVFSLOCKTYPE_FASTMUTEX,
61	/** Full fledged mutex semaphore. */
62	RTVFSLOCKTYPE_MUTEX,
63	/** The end of valid lock types. */
64	RTVFSLOCKTYPE_END,
65	/** The customary 32-bit type hack. */
66	RTVFSLOCKTYPE_32BIT_HACK = 0x7fffffff
67	} RTVFSLOCKTYPE;
68
69	/** VFS lock handle. */
70	typedef struct RTVFSLOCKINTERNAL *RTVFSLOCK;
71	/** Pointer to a VFS lock handle. */
72	typedef RTVFSLOCK *PRTVFSLOCK;
73	/** Nil VFS lock handle. */
74	#define NIL_RTVFSLOCK ((RTVFSLOCK)~(uintptr_t)0)
75
76	/** Special handle value for creating a new read/write semaphore based lock. */
77	#define RTVFSLOCK_CREATE_RW ((RTVFSLOCK)~(uintptr_t)1)
78	/** Special handle value for creating a new fast mutex semaphore based lock. */
79	#define RTVFSLOCK_CREATE_FASTMUTEX ((RTVFSLOCK)~(uintptr_t)2)
80	/** Special handle value for creating a new mutex semaphore based lock. */
81	#define RTVFSLOCK_CREATE_MUTEX ((RTVFSLOCK)~(uintptr_t)3)
82
83	/**
84	* Retains a reference to the VFS lock handle.
85	*
86	* @returns New reference count on success, UINT32_MAX on failure.
87	* @param hLock The VFS lock handle.
88	*/
89	RTDECL(uint32_t) RTVfsLockRetain(RTVFSLOCK hLock);
90
91	/**
92	* Releases a reference to the VFS lock handle.
93	*
94	* @returns New reference count on success (0 if closed), UINT32_MAX on failure.
95	* @param hLock The VFS lock handle.
96	*/
97	RTDECL(uint32_t) RTVfsLockRelease(RTVFSLOCK hLock);
98
99	/**
100	* Gets the lock type.
101	*
102	* @returns The lock type on success, RTVFSLOCKTYPE_INVALID if the handle is
103	* not valid.
104	* @param hLock The lock handle.
105	*/
106	RTDECL(RTVFSLOCKTYPE) RTVfsLockGetType(RTVFSLOCK hLock);
107
108
109
110	RTDECL(void) RTVfsLockAcquireReadSlow(RTVFSLOCK hLock);
111	RTDECL(void) RTVfsLockReleaseReadSlow(RTVFSLOCK hLock);
112	RTDECL(void) RTVfsLockAcquireWriteSlow(RTVFSLOCK hLock);
113	RTDECL(void) RTVfsLockReleaseWriteSlow(RTVFSLOCK hLock);
114
115	/**
116	* Acquire a read lock.
117	*
118	* @param hLock The lock handle, can be NIL.
119	*/
120	DECLINLINE(void) RTVfsLockAcquireRead(RTVFSLOCK hLock)
121	{
122	if (hLock != NIL_RTVFSLOCK)
123	RTVfsLockAcquireReadSlow(hLock);
124	}
125
126
127	/**
128	* Release a read lock.
129	*
130	* @param hLock The lock handle, can be NIL.
131	*/
132	DECLINLINE(void) RTVfsLockReleaseRead(RTVFSLOCK hLock)
133	{
134	if (hLock != NIL_RTVFSLOCK)
135	RTVfsLockReleaseReadSlow(hLock);
136	}
137
138
139	/**
140	* Acquire a write lock.
141	*
142	* @param hLock The lock handle, can be NIL.
143	*/
144	DECLINLINE(void) RTVfsLockAcquireWrite(RTVFSLOCK hLock)
145	{
146	if (hLock != NIL_RTVFSLOCK)
147	RTVfsLockAcquireWriteSlow(hLock);
148	}
149
150
151	/**
152	* Release a write lock.
153	*
154	* @param hLock The lock handle, can be NIL.
155	*/
156	DECLINLINE(void) RTVfsLockReleaseWrite(RTVFSLOCK hLock)
157	{
158	if (hLock != NIL_RTVFSLOCK)
159	RTVfsLockReleaseWriteSlow(hLock);
160	}
161
162	/** @} */
163
164	/**
165	* The basis for all virtual file system objects.
166	*/
167	typedef struct RTVFSOBJOPS
168	{
169	/** The structure version (RTVFSOBJOPS_VERSION). */
170	uint32_t uVersion;
171	/** The object type for type introspection. */
172	RTVFSOBJTYPE enmType;
173	/** The name of the operations. */
174	const char *pszName;
175
176	/**
177	* Close the object.
178	*
179	* @returns IPRT status code.
180	* @param pvThis The implementation specific file data.
181	*/
182	DECLCALLBACKMEMBER(int, pfnClose)(void *pvThis);
183
184	/**
185	* Get information about the file.
186	*
187	* @returns IPRT status code. See RTVfsObjQueryInfo.
188	* @retval VERR_WRONG_TYPE if file system or file system stream.
189	* @param pvThis The implementation specific file data.
190	* @param pObjInfo Where to return the object info on success.
191	* @param enmAddAttr Which set of additional attributes to request.
192	* @sa RTVfsObjQueryInfo, RTFileQueryInfo, RTPathQueryInfo
193	*/
194	DECLCALLBACKMEMBER(int, pfnQueryInfo)(void *pvThis, PRTFSOBJINFO pObjInfo, RTFSOBJATTRADD enmAddAttr);
195
196	/** Marks the end of the structure (RTVFSOBJOPS_VERSION). */
197	uintptr_t uEndMarker;
198	} RTVFSOBJOPS;
199	/** Pointer to constant VFS object operations. */
200	typedef RTVFSOBJOPS const *PCRTVFSOBJOPS;
201
202	/** The RTVFSOBJOPS structure version. */
203	#define RTVFSOBJOPS_VERSION RT_MAKE_U32_FROM_U8(0xff,0x1f,1,0)
204
205
206	/**
207	* The VFS operations.
208	*/
209	typedef struct RTVFSOPS
210	{
211	/** The basic object operation. */
212	RTVFSOBJOPS Obj;
213	/** The structure version (RTVFSOPS_VERSION). */
214	uint32_t uVersion;
215	/** The virtual file system feature mask. */
216	uint32_t fFeatures;
217
218	/**
219	* Opens the root directory.
220	*
221	* @returns IPRT status code.
222	* @param pvThis The implementation specific data.
223	* @param phVfsDir Where to return the handle to the root directory.
224	*/
225	DECLCALLBACKMEMBER(int, pfnOpenRoot)(void *pvThis, PRTVFSDIR phVfsDir);
226
227	/**
228	* Query the status of the given storage range (optional).
229	*
230	* This can be used by the image compaction utilites to evict non-zero blocks
231	* that aren't currently being used by the file system.
232	*
233	* @returns IPRT status code.
234	* @param pvThis The implementation specific data.
235	* @param off Start offset to check.
236	* @param cb Number of bytes to check.
237	* @param pfUsed Where to store whether the given range is in use.
238	*/
239	DECLCALLBACKMEMBER(int, pfnQueryRangeState)(void pvThis, uint64_t off, size_t cb, bool pfUsed);
240
241	/** @todo There will be more methods here to optimize opening and
242	* querying. */
243
244	#if 0
245	/**
246	* Optional entry point for optimizing path traversal within the file system.
247	*
248	* @returns IPRT status code.
249	* @param pvThis The implementation specific data.
250	* @param pszPath The path to resolve.
251	* @param poffPath The current path offset on input, what we've
252	* traversed to on successful return.
253	* @param phVfs??? Return handle to what we've traversed.
254	* @param p??? Return other stuff...
255	*/
256	DECLCALLBACKMEMBER(int, pfnTraverse)(void pvThis, const char pszPath, size_t poffPath, PRTVFS??? phVfs?, ??? p???);
257	#endif
258
259	/** @todo need rename API */
260
261	/** Marks the end of the structure (RTVFSOPS_VERSION). */
262	uintptr_t uEndMarker;
263	} RTVFSOPS;
264	/** Pointer to constant VFS operations. */
265	typedef RTVFSOPS const *PCRTVFSOPS;
266
267	/** The RTVFSOPS structure version. */
268	#define RTVFSOPS_VERSION RT_MAKE_U32_FROM_U8(0xff,0x0f,1,0)
269
270	/** @name RTVFSOPS::fFeatures
271	* @{ */
272	/** The VFS supports attaching other systems. */
273	#define RTVFSOPS_FEAT_ATTACH RT_BIT_32(0)
274	/** @} */
275
276	/**
277	* Creates a new VFS handle.
278	*
279	* @returns IPRT status code
280	* @param pVfsOps The VFS operations.
281	* @param cbInstance The size of the instance data.
282	* @param hVfs The VFS handle to associate this VFS with.
283	* NIL_VFS is ok.
284	* @param hLock Handle to a custom lock to be used with the new
285	* object. The reference is consumed. NIL and
286	* special lock handles are fine.
287	* @param phVfs Where to return the new handle.
288	* @param ppvInstance Where to return the pointer to the instance data
289	* (size is @a cbInstance).
290	*/
291	RTDECL(int) RTVfsNew(PCRTVFSOPS pVfsOps, size_t cbInstance, RTVFS hVfs, RTVFSLOCK hLock,
292	PRTVFS phVfs, void **ppvInstance);
293
294
295	/**
296	* Creates a new VFS base object handle.
297	*
298	* @returns IPRT status code
299	* @param pObjOps The base object operations.
300	* @param cbInstance The size of the instance data.
301	* @param hVfs The VFS handle to associate this base object
302	* with. NIL_VFS is ok.
303	* @param hLock Handle to a custom lock to be used with the new
304	* object. The reference is consumed. NIL and
305	* special lock handles are fine.
306	* @param phVfsObj Where to return the new handle.
307	* @param ppvInstance Where to return the pointer to the instance data
308	* (size is @a cbInstance).
309	*/
310	RTDECL(int) RTVfsNewBaseObj(PCRTVFSOBJOPS pObjOps, size_t cbInstance, RTVFS hVfs, RTVFSLOCK hLock,
311	PRTVFSOBJ phVfsObj, void **ppvInstance);
312
313
314	/**
315	* Gets the private data of a base object.
316	*
317	* @returns Pointer to the private data. NULL if the handle is invalid in some
318	* way.
319	* @param hVfsObj The I/O base object handle.
320	* @param pObjOps The base object operations. This servers as a
321	* sort of password.
322	*/
323	RTDECL(void *) RTVfsObjToPrivate(RTVFSOBJ hVfsObj, PCRTVFSOBJOPS pObjOps);
324
325	/**
326	* Additional operations for setting object attributes.
327	*/
328	typedef struct RTVFSOBJSETOPS
329	{
330	/** The structure version (RTVFSOBJSETOPS_VERSION). */
331	uint32_t uVersion;
332	/** The offset back to the RTVFSOBJOPS structure. */
333	uint32_t offObjOps;
334
335	/**
336	* Set the unix style owner and group.
337	*
338	* @returns IPRT status code.
339	* @param pvThis The implementation specific file data.
340	* @param fMode The new mode bits.
341	* @param fMask The mask indicating which bits we are
342	* changing.
343	* @note Optional, failing with VERR_WRITE_PROTECT if NULL.
344	* @sa RTFileSetMode
345	*/
346	DECLCALLBACKMEMBER(int, pfnSetMode)(void *pvThis, RTFMODE fMode, RTFMODE fMask);
347
348	/**
349	* Set the timestamps associated with the object.
350	*
351	* @returns IPRT status code.
352	* @param pvThis The implementation specific file data.
353	* @param pAccessTime Pointer to the new access time. NULL if not
354	* to be changed.
355	* @param pModificationTime Pointer to the new modifcation time. NULL if
356	* not to be changed.
357	* @param pChangeTime Pointer to the new change time. NULL if not
358	* to be changed.
359	* @param pBirthTime Pointer to the new time of birth. NULL if
360	* not to be changed.
361	* @remarks See RTFileSetTimes for restrictions and behavior imposed by the
362	* host OS or underlying VFS provider.
363	* @note Optional, failing with VERR_WRITE_PROTECT if NULL.
364	* @sa RTFileSetTimes
365	*/
366	DECLCALLBACKMEMBER(int, pfnSetTimes)(void *pvThis, PCRTTIMESPEC pAccessTime, PCRTTIMESPEC pModificationTime,
367	PCRTTIMESPEC pChangeTime, PCRTTIMESPEC pBirthTime);
368
369	/**
370	* Set the unix style owner and group.
371	*
372	* @returns IPRT status code.
373	* @param pvThis The implementation specific file data.
374	* @param uid The user ID of the new owner. NIL_RTUID if
375	* unchanged.
376	* @param gid The group ID of the new owner group. NIL_RTGID if
377	* unchanged.
378	* @note Optional, failing with VERR_WRITE_PROTECT if NULL.
379	* @sa RTFileSetOwner
380	*/
381	DECLCALLBACKMEMBER(int, pfnSetOwner)(void *pvThis, RTUID uid, RTGID gid);
382
383	/** Marks the end of the structure (RTVFSOBJSETOPS_VERSION). */
384	uintptr_t uEndMarker;
385	} RTVFSOBJSETOPS;
386	/** Pointer to const object attribute setter operations. */
387	typedef RTVFSOBJSETOPS const *PCRTVFSOBJSETOPS;
388
389	/** The RTVFSOBJSETOPS structure version. */
390	#define RTVFSOBJSETOPS_VERSION RT_MAKE_U32_FROM_U8(0xff,0x2f,1,0)
391
392
393	/**
394	* The filesystem stream operations.
395	*
396	* @extends RTVFSOBJOPS
397	*/
398	typedef struct RTVFSFSSTREAMOPS
399	{
400	/** The basic object operation. */
401	RTVFSOBJOPS Obj;
402	/** The structure version (RTVFSFSSTREAMOPS_VERSION). */
403	uint32_t uVersion;
404	/** Reserved field, MBZ. */
405	uint32_t fReserved;
406
407	/**
408	* Gets the next object in the stream.
409	*
410	* Readable streams only.
411	*
412	* @returns IPRT status code.
413	* @retval VINF_SUCCESS if a new object was retrieved.
414	* @retval VERR_EOF when there are no more objects.
415	* @param pvThis The implementation specific directory data.
416	* @param ppszName Where to return the object name. Must be freed by
417	* calling RTStrFree.
418	* @param penmType Where to return the object type.
419	* @param phVfsObj Where to return the object handle (referenced). This
420	* must be cast to the desired type before use.
421	* @sa RTVfsFsStrmNext
422	*
423	* @note Setting this member to NULL is okay for write-only streams.
424	*/
425	DECLCALLBACKMEMBER(int, pfnNext)(void pvThis, char ppszName, RTVFSOBJTYPE penmType, PRTVFSOBJ phVfsObj);
426
427	/**
428	* Adds another object into the stream.
429	*
430	* Writable streams only.
431	*
432	* @returns IPRT status code.
433	* @param pvThis The implementation specific directory data.
434	* @param pszPath The path to the object.
435	* @param hVfsObj The object to add.
436	* @param fFlags Reserved for the future, MBZ.
437	* @sa RTVfsFsStrmAdd
438	*
439	* @note Setting this member to NULL is okay for read-only streams.
440	*/
441	DECLCALLBACKMEMBER(int, pfnAdd)(void pvThis, const char pszPath, RTVFSOBJ hVfsObj, uint32_t fFlags);
442
443	/**
444	* Pushes an byte stream onto the stream (optional).
445	*
446	* Writable streams only.
447	*
448	* This differs from RTVFSFSSTREAMOPS::pfnAdd() in that it will create a regular
449	* file in the output file system stream and provide the actual content bytes
450	* via the returned I/O stream object.
451	*
452	* @returns IPRT status code.
453	* @param pvThis The implementation specific directory data.
454	* @param pszPath The path to the file.
455	* @param cbFile The file size. This can also be set to UINT64_MAX if
456	* the file system stream is backed by a file.
457	* @param paObjInfo Array of zero or more RTFSOBJINFO structures containing
458	* different pieces of information about the file. If any
459	* provided, the first one should be a RTFSOBJATTRADD_UNIX
460	* one, additional can be supplied if wanted. What exactly
461	* is needed depends on the underlying FS stream
462	* implementation.
463	* @param cObjInfo Number of items in the array @a paObjInfo points at.
464	* @param fFlags RTVFSFSSTRM_PUSH_F_XXX.
465	* @param phVfsIos Where to return the I/O stream to feed the file content
466	* to. If the FS stream is backed by a file, the returned
467	* handle can be cast to a file if necessary.
468	*/
469	DECLCALLBACKMEMBER(int, pfnPushFile)(void pvThis, const char pszPath, uint64_t cbFile,
470	PCRTFSOBJINFO paObjInfo, uint32_t cObjInfo, uint32_t fFlags, PRTVFSIOSTREAM phVfsIos);
471
472	/**
473	* Marks the end of the stream.
474	*
475	* Writable streams only.
476	*
477	* @returns IPRT status code.
478	* @param pvThis The implementation specific directory data.
479	* @sa RTVfsFsStrmEnd
480	*
481	* @note Setting this member to NULL is okay for read-only streams.
482	*/
483	DECLCALLBACKMEMBER(int, pfnEnd)(void *pvThis);
484
485	/** Marks the end of the structure (RTVFSFSSTREAMOPS_VERSION). */
486	uintptr_t uEndMarker;
487	} RTVFSFSSTREAMOPS;
488	/** Pointer to const object attribute setter operations. */
489	typedef RTVFSFSSTREAMOPS const *PCRTVFSFSSTREAMOPS;
490
491	/** The RTVFSFSSTREAMOPS structure version. */
492	#define RTVFSFSSTREAMOPS_VERSION RT_MAKE_U32_FROM_U8(0xff,0x3f,2,0)
493
494
495	/**
496	* Creates a new VFS filesystem stream handle.
497	*
498	* @returns IPRT status code
499	* @param pFsStreamOps The filesystem stream operations.
500	* @param cbInstance The size of the instance data.
501	* @param hVfs The VFS handle to associate this filesystem
502	* stream with. NIL_VFS is ok.
503	* @param hLock Handle to a custom lock to be used with the new
504	* object. The reference is consumed. NIL and
505	* special lock handles are fine.
506	* @param fAccess RTFILE_O_READ and/or RTFILE_O_WRITE.
507	* @param phVfsFss Where to return the new handle.
508	* @param ppvInstance Where to return the pointer to the instance data
509	* (size is @a cbInstance).
510	*/
511	RTDECL(int) RTVfsNewFsStream(PCRTVFSFSSTREAMOPS pFsStreamOps, size_t cbInstance, RTVFS hVfs, RTVFSLOCK hLock, uint32_t fAccess,
512	PRTVFSFSSTREAM phVfsFss, void **ppvInstance);
513
514	/**
515	* Gets the private data of an filesystem stream.
516	*
517	* @returns Pointer to the private data. NULL if the handle is invalid in some
518	* way.
519	* @param hVfsFss The FS stream handle.
520	* @param pFsStreamOps The FS stream operations. This servers as a
521	* sort of password.
522	*/
523	RTDECL(void *) RTVfsFsStreamToPrivate(RTVFSFSSTREAM hVfsFss, PCRTVFSFSSTREAMOPS pFsStreamOps);
524
525
526	/**
527	* The directory operations.
528	*
529	* @extends RTVFSOBJOPS
530	* @extends RTVFSOBJSETOPS
531	*/
532	typedef struct RTVFSDIROPS
533	{
534	/** The basic object operation. */
535	RTVFSOBJOPS Obj;
536	/** The structure version (RTVFSDIROPS_VERSION). */
537	uint32_t uVersion;
538	/** Reserved field, MBZ. */
539	uint32_t fReserved;
540	/** The object setter operations. */
541	RTVFSOBJSETOPS ObjSet;
542
543	/**
544	* Generic method for opening any kind of file system object.
545	*
546	* Can also create files and directories. Symbolic links, devices and such
547	* needs to be created using special methods or this would end up being way more
548	* complicated than it already is.
549	*
550	* There are optional specializations available.
551	*
552	* @returns IPRT status code.
553	* @retval VERR_PATH_NOT_FOUND or VERR_FILE_NOT_FOUND if @a pszEntry was not
554	* found.
555	* @retval VERR_IS_A_FILE if @a pszEntry is a file or similar but @a fFlags
556	* indicates that the type of object should not be opened.
557	* @retval VERR_IS_A_DIRECTORY if @a pszEntry is a directory but @a fFlags
558	* indicates that directories should not be opened.
559	* @retval VERR_IS_A_SYMLINK if @a pszEntry is a symbolic link but @a fFlags
560	* indicates that symbolic links should not be opened (or followed).
561	* @retval VERR_IS_A_FIFO if @a pszEntry is a FIFO but @a fFlags indicates that
562	* FIFOs should not be opened.
563	* @retval VERR_IS_A_SOCKET if @a pszEntry is a socket but @a fFlags indicates
564	* that sockets should not be opened.
565	* @retval VERR_IS_A_BLOCK_DEVICE if @a pszEntry is a block device but
566	* @a fFlags indicates that block devices should not be opened, or vice
567	* versa.
568	*
569	* @param pvThis The implementation specific directory data.
570	* @param pszEntry The name of the immediate file to open or create.
571	* @param fOpenFile RTFILE_O_XXX combination.
572	* @param fObjFlags More flags: RTVFSOBJ_F_XXX, RTPATH_F_XXX.
573	* The meaning of RTPATH_F_FOLLOW_LINK differs here, if
574	* @a pszEntry is a symlink it should be opened for
575	* traversal rather than according to @a fOpenFile.
576	* @param phVfsObj Where to return the handle to the opened object.
577	* @sa RTFileOpen, RTDirOpen
578	*/
579	DECLCALLBACKMEMBER(int, pfnOpen)(void pvThis, const char pszEntry, uint64_t fOpenFile,
580	uint32_t fObjFlags, PRTVFSOBJ phVfsObj);
581
582	/**
583	* Optional method for symbolic link handling in the vfsstddir.cpp.
584	*
585	* This is really just a hack to make symbolic link handling work when working
586	* with directory objects that doesn't have an associated VFS. It also helps
587	* deal with drive letters in symbolic links on Windows and OS/2.
588	*
589	* @returns IPRT status code.
590	* @retval VERR_PATH_IS_RELATIVE if @a pszPath isn't absolute and should be
591	* handled using pfnOpen().
592	*
593	* @param pvThis The implementation specific directory data.
594	* @param pszRoot Path to the alleged root.
595	* @param phVfsDir Where to return the handle to the specified root
596	* directory (or may current dir on a drive letter).
597	*/
598	DECLCALLBACKMEMBER(int, pfnFollowAbsoluteSymlink)(void pvThis, const char pszRoot, PRTVFSDIR phVfsDir);
599
600	/**
601	* Open or create a file.
602	*
603	* @returns IPRT status code.
604	* @param pvThis The implementation specific directory data.
605	* @param pszFilename The name of the immediate file to open or create.
606	* @param fOpen The open flags (RTFILE_O_XXX).
607	* @param phVfsFile Where to return the handle to the opened file.
608	* @note Optional. RTVFSDIROPS::pfnOpenObj will be used if NULL.
609	* @sa RTFileOpen.
610	*/
611	DECLCALLBACKMEMBER(int, pfnOpenFile)(void pvThis, const char pszFilename, uint64_t fOpen, PRTVFSFILE phVfsFile);
612
613	/**
614	* Open an existing subdirectory.
615	*
616	* @returns IPRT status code.
617	* @retval VERR_IS_A_SYMLINK if @a pszSubDir is a symbolic link.
618	* @retval VERR_NOT_A_DIRECTORY is okay for symbolic links too.
619	*
620	* @param pvThis The implementation specific directory data.
621	* @param pszSubDir The name of the immediate subdirectory to open.
622	* @param fFlags RTDIR_F_XXX.
623	* @param phVfsDir Where to return the handle to the opened directory.
624	* Optional.
625	* @note Optional. RTVFSDIROPS::pfnOpenObj will be used if NULL.
626	* @sa RTDirOpen.
627	*/
628	DECLCALLBACKMEMBER(int, pfnOpenDir)(void pvThis, const char pszSubDir, uint32_t fFlags, PRTVFSDIR phVfsDir);
629
630	/**
631	* Creates a new subdirectory.
632	*
633	* @returns IPRT status code.
634	* @param pvThis The implementation specific directory data.
635	* @param pszSubDir The name of the immediate subdirectory to create.
636	* @param fMode The mode mask of the new directory.
637	* @param phVfsDir Where to optionally return the handle to the newly
638	* create directory.
639	* @note Optional. RTVFSDIROPS::pfnOpenObj will be used if NULL.
640	* @sa RTDirCreate.
641	*/
642	DECLCALLBACKMEMBER(int, pfnCreateDir)(void pvThis, const char pszSubDir, RTFMODE fMode, PRTVFSDIR phVfsDir);
643
644	/**
645	* Opens an existing symbolic link.
646	*
647	* @returns IPRT status code.
648	* @param pvThis The implementation specific directory data.
649	* @param pszSymlink The name of the immediate symbolic link to open.
650	* @param phVfsSymlink Where to optionally return the handle to the
651	* newly create symbolic link.
652	* @note Optional. RTVFSDIROPS::pfnOpenObj will be used if NULL.
653	* @sa RTSymlinkCreate.
654	*/
655	DECLCALLBACKMEMBER(int, pfnOpenSymlink)(void pvThis, const char pszSymlink, PRTVFSSYMLINK phVfsSymlink);
656
657	/**
658	* Creates a new symbolic link.
659	*
660	* @returns IPRT status code.
661	* @param pvThis The implementation specific directory data.
662	* @param pszSymlink The name of the immediate symbolic link to create.
663	* @param pszTarget The symbolic link target.
664	* @param enmType The symbolic link type.
665	* @param phVfsSymlink Where to optionally return the handle to the
666	* newly create symbolic link.
667	* @sa RTSymlinkCreate.
668	*/
669	DECLCALLBACKMEMBER(int, pfnCreateSymlink)(void pvThis, const char pszSymlink, const char *pszTarget,
670	RTSYMLINKTYPE enmType, PRTVFSSYMLINK phVfsSymlink);
671
672	/**
673	* Query information about an entry.
674	*
675	* @returns IPRT status code.
676	* @param pvThis The implementation specific directory data.
677	* @param pszEntry The name of the directory entry to remove.
678	* @param pObjInfo Where to return the info on success.
679	* @param enmAddAttr Which set of additional attributes to request.
680	* @note Optional. RTVFSDIROPS::pfnOpenObj and RTVFSOBJOPS::pfnQueryInfo
681	* will be used if NULL.
682	* @sa RTPathQueryInfo, RTVFSOBJOPS::pfnQueryInfo
683	*/
684	DECLCALLBACKMEMBER(int, pfnQueryEntryInfo)(void pvThis, const char pszEntry,
685	PRTFSOBJINFO pObjInfo, RTFSOBJATTRADD enmAddAttr);
686
687	/**
688	* Removes a directory entry.
689	*
690	* @returns IPRT status code.
691	* @param pvThis The implementation specific directory data.
692	* @param pszEntry The name of the directory entry to remove.
693	* @param fType If non-zero, this restricts the type of the entry to
694	* the object type indicated by the mask
695	* (RTFS_TYPE_XXX).
696	* @sa RTFileRemove, RTDirRemove, RTSymlinkRemove.
697	*/
698	DECLCALLBACKMEMBER(int, pfnUnlinkEntry)(void pvThis, const char pszEntry, RTFMODE fType);
699
700	/**
701	* Renames a directory entry.
702	*
703	* @returns IPRT status code.
704	* @param pvThis The implementation specific directory data.
705	* @param pszEntry The name of the directory entry to rename.
706	* @param fType If non-zero, this restricts the type of the entry to
707	* the object type indicated by the mask
708	* (RTFS_TYPE_XXX).
709	* @param pszNewName The new entry name.
710	* @sa RTPathRename
711	*
712	* @todo This API is not flexible enough, must be able to rename between
713	* directories within a file system.
714	*/
715	DECLCALLBACKMEMBER(int, pfnRenameEntry)(void pvThis, const char pszEntry, RTFMODE fType, const char *pszNewName);
716
717	/**
718	* Rewind the directory stream so that the next read returns the first
719	* entry.
720	*
721	* @returns IPRT status code.
722	* @param pvThis The implementation specific directory data.
723	*/
724	DECLCALLBACKMEMBER(int, pfnRewindDir)(void *pvThis);
725
726	/**
727	* Rewind the directory stream so that the next read returns the first
728	* entry.
729	*
730	* @returns IPRT status code.
731	* @param pvThis The implementation specific directory data.
732	* @param pDirEntry Output buffer.
733	* @param pcbDirEntry Complicated, see RTDirReadEx.
734	* @param enmAddAttr Which set of additional attributes to request.
735	* @sa RTDirReadEx
736	*/
737	DECLCALLBACKMEMBER(int, pfnReadDir)(void pvThis, PRTDIRENTRYEX pDirEntry, size_t pcbDirEntry, RTFSOBJATTRADD enmAddAttr);
738
739	/** Marks the end of the structure (RTVFSDIROPS_VERSION). */
740	uintptr_t uEndMarker;
741	} RTVFSDIROPS;
742	/** Pointer to const directory operations. */
743	typedef RTVFSDIROPS const *PCRTVFSDIROPS;
744	/** The RTVFSDIROPS structure version. */
745	#define RTVFSDIROPS_VERSION RT_MAKE_U32_FROM_U8(0xff,0x4f,1,0)
746
747
748	/**
749	* Creates a new VFS directory handle.
750	*
751	* @returns IPRT status code
752	* @param pDirOps The directory operations.
753	* @param cbInstance The size of the instance data.
754	* @param fFlags RTVFSDIR_F_XXX
755	* @param hVfs The VFS handle to associate this directory with.
756	* NIL_VFS is ok.
757	* @param hLock Handle to a custom lock to be used with the new
758	* object. The reference is consumed. NIL and
759	* special lock handles are fine.
760	* @param phVfsDir Where to return the new handle.
761	* @param ppvInstance Where to return the pointer to the instance data
762	* (size is @a cbInstance).
763	*/
764	RTDECL(int) RTVfsNewDir(PCRTVFSDIROPS pDirOps, size_t cbInstance, uint32_t fFlags, RTVFS hVfs, RTVFSLOCK hLock,
765	PRTVFSDIR phVfsDir, void **ppvInstance);
766
767	/** @name RTVFSDIR_F_XXX
768	* @{ */
769	/** Don't reference the @a hVfs parameter passed to RTVfsNewDir.
770	* This is a permanent root directory hack. */
771	#define RTVFSDIR_F_NO_VFS_REF RT_BIT_32(0)
772	/** @} */
773
774	/**
775	* Gets the private data of a directory.
776	*
777	* @returns Pointer to the private data. NULL if the handle is invalid in some
778	* way.
779	* @param hVfsDir The directory handle.
780	* @param pDirOps The directory operations. This servers as a
781	* sort of password.
782	*/
783	RTDECL(void *) RTVfsDirToPrivate(RTVFSDIR hVfsDir, PCRTVFSDIROPS pDirOps);
784
785
786	/**
787	* The symbolic link operations.
788	*
789	* @extends RTVFSOBJOPS
790	* @extends RTVFSOBJSETOPS
791	*/
792	typedef struct RTVFSSYMLINKOPS
793	{
794	/** The basic object operation. */
795	RTVFSOBJOPS Obj;
796	/** The structure version (RTVFSSYMLINKOPS_VERSION). */
797	uint32_t uVersion;
798	/** Reserved field, MBZ. */
799	uint32_t fReserved;
800	/** The object setter operations. */
801	RTVFSOBJSETOPS ObjSet;
802
803	/**
804	* Read the symbolic link target.
805	*
806	* @returns IPRT status code.
807	* @param pvThis The implementation specific symbolic link data.
808	* @param pszTarget The target buffer.
809	* @param cbTarget The size of the target buffer.
810	* @sa RTSymlinkRead
811	*/
812	DECLCALLBACKMEMBER(int, pfnRead)(void pvThis, char pszTarget, size_t cbTarget);
813
814	/** Marks the end of the structure (RTVFSSYMLINKOPS_VERSION). */
815	uintptr_t uEndMarker;
816	} RTVFSSYMLINKOPS;
817	/** Pointer to const symbolic link operations. */
818	typedef RTVFSSYMLINKOPS const *PCRTVFSSYMLINKOPS;
819	/** The RTVFSSYMLINKOPS structure version. */
820	#define RTVFSSYMLINKOPS_VERSION RT_MAKE_U32_FROM_U8(0xff,0x5f,1,0)
821
822
823	/**
824	* Creates a new VFS symlink handle.
825	*
826	* @returns IPRT status code
827	* @param pSymlinkOps The symlink operations.
828	* @param cbInstance The size of the instance data.
829	* @param hVfs The VFS handle to associate this symlink object
830	* with. NIL_VFS is ok.
831	* @param hLock Handle to a custom lock to be used with the new
832	* object. The reference is consumed. NIL and
833	* special lock handles are fine.
834	* @param phVfsSym Where to return the new handle.
835	* @param ppvInstance Where to return the pointer to the instance data
836	* (size is @a cbInstance).
837	*/
838	RTDECL(int) RTVfsNewSymlink(PCRTVFSSYMLINKOPS pSymlinkOps, size_t cbInstance, RTVFS hVfs, RTVFSLOCK hLock,
839	PRTVFSSYMLINK phVfsSym, void **ppvInstance);
840
841
842	/**
843	* Gets the private data of a symbolic link.
844	*
845	* @returns Pointer to the private data. NULL if the handle is invalid in some
846	* way.
847	* @param hVfsSym The symlink handle.
848	* @param pSymlinkOps The symlink operations. This servers as a sort
849	* of password.
850	*/
851	RTDECL(void *) RTVfsSymlinkToPrivate(RTVFSSYMLINK hVfsSym, PCRTVFSSYMLINKOPS pSymlinkOps);
852
853	/**
854	* The basis for all I/O objects (files, pipes, sockets, devices, ++).
855	*
856	* @extends RTVFSOBJOPS
857	*/
858	typedef struct RTVFSIOSTREAMOPS
859	{
860	/** The basic object operation. */
861	RTVFSOBJOPS Obj;
862	/** The structure version (RTVFSIOSTREAMOPS_VERSION). */
863	uint32_t uVersion;
864	/** Feature field. */
865	uint32_t fFeatures;
866
867	/**
868	* Reads from the file/stream.
869	*
870	* @returns IPRT status code. See RTVfsIoStrmRead.
871	* @param pvThis The implementation specific file data.
872	* @param off Where to read at, -1 for the current position.
873	* @param pSgBuf Gather buffer describing the bytes that are to be
874	* written.
875	* @param fBlocking If @c true, the call is blocking, if @c false it
876	* should not block.
877	* @param pcbRead Where return the number of bytes actually read.
878	* This is set it 0 by the caller. If NULL, try read
879	* all and fail if incomplete.
880	* @sa RTVfsIoStrmRead, RTVfsIoStrmSgRead, RTVfsFileRead,
881	* RTVfsFileReadAt, RTFileRead, RTFileReadAt.
882	*/
883	DECLCALLBACKMEMBER(int, pfnRead)(void pvThis, RTFOFF off, PCRTSGBUF pSgBuf, bool fBlocking, size_t pcbRead);
884
885	/**
886	* Writes to the file/stream.
887	*
888	* @returns IPRT status code.
889	* @param pvThis The implementation specific file data.
890	* @param off Where to start wrinting, -1 for the current
891	* position.
892	* @param pSgBuf Gather buffers describing the bytes that are to be
893	* written.
894	* @param fBlocking If @c true, the call is blocking, if @c false it
895	* should not block.
896	* @param pcbWritten Where to return the number of bytes actually
897	* written. This is set it 0 by the caller. If
898	* NULL, try write it all and fail if incomplete.
899	* @note Optional, failing with VERR_WRITE_PROTECT if NULL.
900	* @sa RTFileWrite, RTFileWriteAt.
901	*/
902	DECLCALLBACKMEMBER(int, pfnWrite)(void pvThis, RTFOFF off, PCRTSGBUF pSgBuf, bool fBlocking, size_t pcbWritten);
903
904	/**
905	* Flushes any pending data writes to the stream.
906	*
907	* @returns IPRT status code.
908	* @param pvThis The implementation specific file data.
909	* @sa RTFileFlush.
910	*/
911	DECLCALLBACKMEMBER(int, pfnFlush)(void *pvThis);
912
913	/**
914	* Poll for events.
915	*
916	* @returns IPRT status code.
917	* @param pvThis The implementation specific file data.
918	* @param fEvents The events to poll for (RTPOLL_EVT_XXX).
919	* @param cMillies How long to wait for event to eventuate.
920	* @param fIntr Whether the wait is interruptible and can return
921	* VERR_INTERRUPTED (@c true) or if this condition
922	* should be hidden from the caller (@c false).
923	* @param pfRetEvents Where to return the event mask.
924	* @note Optional. If NULL, immediately return all requested non-error
925	* events, waiting for errors works like sleep.
926	* @sa RTPollSetAdd, RTPoll, RTPollNoResume.
927	*/
928	DECLCALLBACKMEMBER(int, pfnPollOne)(void *pvThis, uint32_t fEvents, RTMSINTERVAL cMillies, bool fIntr,
929	uint32_t *pfRetEvents);
930
931	/**
932	* Tells the current file/stream position.
933	*
934	* @returns IPRT status code.
935	* @param pvThis The implementation specific file data.
936	* @param poffActual Where to return the actual offset.
937	* @sa RTFileTell
938	*/
939	DECLCALLBACKMEMBER(int, pfnTell)(void *pvThis, PRTFOFF poffActual);
940
941	/**
942	* Skips @a cb ahead in the stream.
943	*
944	* @returns IPRT status code.
945	* @param pvThis The implementation specific file data.
946	* @param cb The number bytes to skip.
947	* @remarks This is optional and can be NULL.
948	*/
949	DECLCALLBACKMEMBER(int, pfnSkip)(void *pvThis, RTFOFF cb);
950
951	/**
952	* Fills the stream with @a cb zeros.
953	*
954	* @returns IPRT status code.
955	* @param pvThis The implementation specific file data.
956	* @param cb The number of zero bytes to insert.
957	* @remarks This is optional and can be NULL.
958	*/
959	DECLCALLBACKMEMBER(int, pfnZeroFill)(void *pvThis, RTFOFF cb);
960
961	/** Marks the end of the structure (RTVFSIOSTREAMOPS_VERSION). */
962	uintptr_t uEndMarker;
963	} RTVFSIOSTREAMOPS;
964	/** Pointer to const I/O stream operations. */
965	typedef RTVFSIOSTREAMOPS const *PCRTVFSIOSTREAMOPS;
966
967	/** The RTVFSIOSTREAMOPS structure version. */
968	#define RTVFSIOSTREAMOPS_VERSION RT_MAKE_U32_FROM_U8(0xff,0x6f,1,0)
969
970	/** @name RTVFSIOSTREAMOPS::fFeatures
971	* @{ */
972	/** No scatter gather lists, thank you. */
973	#define RTVFSIOSTREAMOPS_FEAT_NO_SG RT_BIT_32(0)
974	/** Mask of the valid I/O stream feature flags. */
975	#define RTVFSIOSTREAMOPS_FEAT_VALID_MASK UINT32_C(0x00000001)
976	/** @} */
977
978
979	/**
980	* Creates a new VFS I/O stream handle.
981	*
982	* @returns IPRT status code
983	* @param pIoStreamOps The I/O stream operations.
984	* @param cbInstance The size of the instance data.
985	* @param fOpen The open flags. The minimum is the access mask.
986	* @param hVfs The VFS handle to associate this I/O stream
987	* with. NIL_VFS is ok.
988	* @param hLock Handle to a custom lock to be used with the new
989	* object. The reference is consumed. NIL and
990	* special lock handles are fine.
991	* @param phVfsIos Where to return the new handle.
992	* @param ppvInstance Where to return the pointer to the instance data
993	* (size is @a cbInstance).
994	*/
995	RTDECL(int) RTVfsNewIoStream(PCRTVFSIOSTREAMOPS pIoStreamOps, size_t cbInstance, uint32_t fOpen, RTVFS hVfs, RTVFSLOCK hLock,
996	PRTVFSIOSTREAM phVfsIos, void **ppvInstance);
997
998
999	/**
1000	* Gets the private data of an I/O stream.
1001	*
1002	* @returns Pointer to the private data. NULL if the handle is invalid in some
1003	* way.
1004	* @param hVfsIos The I/O stream handle.
1005	* @param pIoStreamOps The I/O stream operations. This servers as a
1006	* sort of password.
1007	*/
1008	RTDECL(void *) RTVfsIoStreamToPrivate(RTVFSIOSTREAM hVfsIos, PCRTVFSIOSTREAMOPS pIoStreamOps);
1009
1010
1011	/**
1012	* The file operations.
1013	*
1014	* @extends RTVFSIOSTREAMOPS
1015	* @extends RTVFSOBJSETOPS
1016	*/
1017	typedef struct RTVFSFILEOPS
1018	{
1019	/** The I/O stream and basis object operations. */
1020	RTVFSIOSTREAMOPS Stream;
1021	/** The structure version (RTVFSFILEOPS_VERSION). */
1022	uint32_t uVersion;
1023	/** Reserved field, MBZ. */
1024	uint32_t fReserved;
1025	/** The object setter operations. */
1026	RTVFSOBJSETOPS ObjSet;
1027
1028	/**
1029	* Changes the current file position.
1030	*
1031	* @returns IPRT status code.
1032	* @param pvThis The implementation specific file data.
1033	* @param offSeek The offset to seek.
1034	* @param uMethod The seek method, i.e. what the seek is relative to.
1035	* @param poffActual Where to return the actual offset.
1036	* @sa RTFileSeek
1037	*/
1038	DECLCALLBACKMEMBER(int, pfnSeek)(void *pvThis, RTFOFF offSeek, unsigned uMethod, PRTFOFF poffActual);
1039
1040	/**
1041	* Get the current file size.
1042	*
1043	* @returns IPRT status code.
1044	* @param pvThis The implementation specific file data.
1045	* @param pcbFile Where to store the current file size.
1046	* @sa RTFileQuerySize
1047	*/
1048	DECLCALLBACKMEMBER(int, pfnQuerySize)(void pvThis, uint64_t pcbFile);
1049
1050	/**
1051	* Change the file size.
1052	*
1053	* @returns IPRT status code.
1054	* @retval VERR_ACCESS_DENIED if handle isn't writable.
1055	* @retval VERR_WRITE_PROTECT if read-only file system.
1056	* @retval VERR_FILE_TOO_BIG if cbSize is larger than what the file system can
1057	* theoretically deal with.
1058	* @retval VERR_DISK_FULL if the file system if full.
1059	* @retval VERR_NOT_SUPPORTED if fFlags indicates some operation that's not
1060	* supported by the file system / host operating system.
1061	*
1062	* @param pvThis The implementation specific file data.
1063	* @param pcbFile Where to store the current file size.
1064	* @param fFlags RTVFSFILE_SET_SIZE_F_XXX.
1065	* @note Optional. If NULL, VERR_WRITE_PROTECT will be returned.
1066	* @sa RTFileSetSize, RTFileSetAllocationSize
1067	*/
1068	DECLCALLBACKMEMBER(int, pfnSetSize)(void *pvThis, uint64_t cbFile, uint32_t fFlags);
1069
1070	/**
1071	* Determine the maximum file size.
1072	*
1073	* This won't take amount of freespace into account, just the limitations of the
1074	* underlying file system / host operating system.
1075	*
1076	* @returns IPRT status code.
1077	* @param pvThis The implementation specific file data.
1078	* @param pcbMax Where to return the max file size.
1079	* @note Optional. If NULL, VERR_NOT_IMPLEMENTED will be returned.
1080	* @sa RTFileQueryMaxSizeEx
1081	*/
1082	DECLCALLBACKMEMBER(int, pfnQueryMaxSize)(void pvThis, uint64_t pcbMax);
1083
1084	/** @todo There will be more methods here. */
1085
1086	/** Marks the end of the structure (RTVFSFILEOPS_VERSION). */
1087	uintptr_t uEndMarker;
1088	} RTVFSFILEOPS;
1089	/** Pointer to const file operations. */
1090	typedef RTVFSFILEOPS const *PCRTVFSFILEOPS;
1091
1092	/** The RTVFSFILEOPS structure version. */
1093	#define RTVFSFILEOPS_VERSION RT_MAKE_U32_FROM_U8(0xff,0x7f,2,0)
1094
1095	/**
1096	* Creates a new VFS file handle.
1097	*
1098	* @returns IPRT status code
1099	* @param pFileOps The file operations.
1100	* @param cbInstance The size of the instance data.
1101	* @param fOpen The open flags. The minimum is the access mask.
1102	* @param hVfs The VFS handle to associate this file with.
1103	* NIL_VFS is ok.
1104	* @param hLock Handle to a custom lock to be used with the new
1105	* object. The reference is consumed. NIL and
1106	* special lock handles are fine.
1107	* @param phVfsFile Where to return the new handle.
1108	* @param ppvInstance Where to return the pointer to the instance data
1109	* (size is @a cbInstance).
1110	*/
1111	RTDECL(int) RTVfsNewFile(PCRTVFSFILEOPS pFileOps, size_t cbInstance, uint32_t fOpen, RTVFS hVfs, RTVFSLOCK hLock,
1112	PRTVFSFILE phVfsFile, void **ppvInstance);
1113
1114
1115	/** @defgroup grp_rt_vfs_ll_util VFS Utility APIs
1116	* @{ */
1117
1118	/**
1119	* Parsed path.
1120	*/
1121	typedef struct RTVFSPARSEDPATH
1122	{
1123	/** The length of the path in szCopy. */
1124	uint16_t cch;
1125	/** The number of path components. */
1126	uint16_t cComponents;
1127	/** Set if the path ends with slash, indicating that it's a directory
1128	* reference and not a file reference. The slash has been removed from
1129	* the copy. */
1130	bool fDirSlash;
1131	/** Set if absolute. */
1132	bool fAbsolute;
1133	/** The offset where each path component starts, i.e. the char after the
1134	* slash. The array has cComponents + 1 entries, where the final one is
1135	* cch + 1 so that one can always terminate the current component by
1136	* szPath[aoffComponent[i] - 1] = '\0'. */
1137	uint16_t aoffComponents[RTPATH_MAX / 2 + 1];
1138	/** A normalized copy of the path.
1139	* Reserve some extra space so we can be more relaxed about overflow
1140	* checks and terminator paddings, especially when recursing. */
1141	char szPath[RTPATH_MAX];
1142	} RTVFSPARSEDPATH;
1143	/** Pointer to a parsed path. */
1144	typedef RTVFSPARSEDPATH *PRTVFSPARSEDPATH;
1145
1146	/** The max accepted path length.
1147	* This must be a few chars shorter than RTVFSPARSEDPATH::szPath because we
1148	* use two terminators and wish be a little bit lazy with checking. */
1149	#define RTVFSPARSEDPATH_MAX (RTPATH_MAX - 4)
1150
1151	/**
1152	* Appends @a pszPath (relative) to the already parsed path @a pPath.
1153	*
1154	* @retval VINF_SUCCESS
1155	* @retval VERR_FILENAME_TOO_LONG
1156	* @retval VERR_INTERNAL_ERROR_4
1157	* @param pPath The parsed path to append @a pszPath onto.
1158	* This is both input and output.
1159	* @param pszPath The path to append. This must be relative.
1160	* @param piRestartComp The component to restart parsing at. This is
1161	* input/output. The input does not have to be
1162	* within the valid range. Optional.
1163	*/
1164	RTDECL(int) RTVfsParsePathAppend(PRTVFSPARSEDPATH pPath, const char pszPath, uint16_t piRestartComp);
1165
1166	/**
1167	* Parses a path.
1168	*
1169	* @retval VINF_SUCCESS
1170	* @retval VERR_FILENAME_TOO_LONG
1171	* @param pPath Where to store the parsed path.
1172	* @param pszPath The path to parse. Absolute or relative to @a
1173	* pszCwd.
1174	* @param pszCwd The current working directory. Must be
1175	* absolute.
1176	*/
1177	RTDECL(int) RTVfsParsePath(PRTVFSPARSEDPATH pPath, const char pszPath, const char pszCwd);
1178
1179	/**
1180	* Same as RTVfsParsePath except that it allocates a temporary buffer.
1181	*
1182	* @retval VINF_SUCCESS
1183	* @retval VERR_NO_TMP_MEMORY
1184	* @retval VERR_FILENAME_TOO_LONG
1185	* @param pszPath The path to parse. Absolute or relative to @a
1186	* pszCwd.
1187	* @param pszCwd The current working directory. Must be
1188	* absolute.
1189	* @param ppPath Where to store the pointer to the allocated
1190	* buffer containing the parsed path. This must
1191	* be freed by calling RTVfsParsePathFree. NULL
1192	* will be stored on failured.
1193	*/
1194	RTDECL(int) RTVfsParsePathA(const char pszPath, const char pszCwd, PRTVFSPARSEDPATH *ppPath);
1195
1196	/**
1197	* Frees a buffer returned by RTVfsParsePathA.
1198	*
1199	* @param pPath The parsed path buffer to free. NULL is fine.
1200	*/
1201	RTDECL(void) RTVfsParsePathFree(PRTVFSPARSEDPATH pPath);
1202
1203	/**
1204	* Dummy implementation of RTVFSIOSTREAMOPS::pfnPollOne.
1205	*
1206	* This handles the case where there is no chance any events my be raised and
1207	* all that is required is to wait according to the parameters.
1208	*
1209	* @returns IPRT status code.
1210	* @param fEvents The events to poll for (RTPOLL_EVT_XXX).
1211	* @param cMillies How long to wait for event to eventuate.
1212	* @param fIntr Whether the wait is interruptible and can return
1213	* VERR_INTERRUPTED (@c true) or if this condition
1214	* should be hidden from the caller (@c false).
1215	* @param pfRetEvents Where to return the event mask.
1216	* @sa RTVFSIOSTREAMOPS::pfnPollOne, RTPollSetAdd, RTPoll, RTPollNoResume.
1217	*/
1218	RTDECL(int) RTVfsUtilDummyPollOne(uint32_t fEvents, RTMSINTERVAL cMillies, bool fIntr, uint32_t *pfRetEvents);
1219
1220	/** @} */
1221
1222
1223	/** @defgroup grp_rt_vfs_lowlevel_chain VFS Chains (Low Level)
1224	* @ref grp_rt_vfs_chain
1225	* @{
1226	*/
1227
1228	/** Pointer to a VFS chain element registration record. */
1229	typedef struct RTVFSCHAINELEMENTREG *PRTVFSCHAINELEMENTREG;
1230	/** Pointer to a const VFS chain element registration record. */
1231	typedef struct RTVFSCHAINELEMENTREG const *PCRTVFSCHAINELEMENTREG;
1232
1233	/**
1234	* VFS chain element argument.
1235	*/
1236	typedef struct RTVFSCHAINELEMENTARG
1237	{
1238	/** The string argument value. */
1239	char *psz;
1240	/** The specification offset of this argument. */
1241	uint16_t offSpec;
1242	/** Provider specific value. */
1243	uint64_t uProvider;
1244	} RTVFSCHAINELEMENTARG;
1245	/** Pointer to a VFS chain element argument. */
1246	typedef RTVFSCHAINELEMENTARG *PRTVFSCHAINELEMENTARG;
1247
1248
1249	/**
1250	* VFS chain element specification.
1251	*/
1252	typedef struct RTVFSCHAINELEMSPEC
1253	{
1254	/** The provider name.
1255	* This can be NULL if this is the final component and it's just a path. */
1256	char *pszProvider;
1257	/** The input type, RTVFSOBJTYPE_INVALID if first. */
1258	RTVFSOBJTYPE enmTypeIn;
1259	/** The element type.
1260	* RTVFSOBJTYPE_END if this is the final component and it's just a path. */
1261	RTVFSOBJTYPE enmType;
1262	/** The input spec offset of this element. */
1263	uint16_t offSpec;
1264	/** The length of the input spec. */
1265	uint16_t cchSpec;
1266	/** The number of arguments. */
1267	uint32_t cArgs;
1268	/** Arguments. */
1269	PRTVFSCHAINELEMENTARG paArgs;
1270
1271	/** The provider. */
1272	PCRTVFSCHAINELEMENTREG pProvider;
1273	/** Provider specific value. */
1274	uint64_t uProvider;
1275	/** The object (with reference). */
1276	RTVFSOBJ hVfsObj;
1277	} RTVFSCHAINELEMSPEC;
1278	/** Pointer to a chain element specification. */
1279	typedef RTVFSCHAINELEMSPEC *PRTVFSCHAINELEMSPEC;
1280	/** Pointer to a const chain element specification. */
1281	typedef RTVFSCHAINELEMSPEC const *PCRTVFSCHAINELEMSPEC;
1282
1283
1284	/**
1285	* Parsed VFS chain specification.
1286	*/
1287	typedef struct RTVFSCHAINSPEC
1288	{
1289	/** Open directory flags (RTFILE_O_XXX). */
1290	uint64_t fOpenFile;
1291	/** To be defined. */
1292	uint32_t fOpenDir;
1293	/** The type desired by the caller. */
1294	RTVFSOBJTYPE enmDesiredType;
1295	/** The number of elements. */
1296	uint32_t cElements;
1297	/** The elements. */
1298	PRTVFSCHAINELEMSPEC paElements;
1299	} RTVFSCHAINSPEC;
1300	/** Pointer to a parsed VFS chain specification. */
1301	typedef RTVFSCHAINSPEC *PRTVFSCHAINSPEC;
1302	/** Pointer to a const, parsed VFS chain specification. */
1303	typedef RTVFSCHAINSPEC const *PCRTVFSCHAINSPEC;
1304
1305
1306	/**
1307	* A chain element provider registration record.
1308	*/
1309	typedef struct RTVFSCHAINELEMENTREG
1310	{
1311	/** The version (RTVFSCHAINELEMENTREG_VERSION). */
1312	uint32_t uVersion;
1313	/** Reserved, MBZ. */
1314	uint32_t fReserved;
1315	/** The provider name (unique). */
1316	const char *pszName;
1317	/** For chaining the providers. */
1318	RTLISTNODE ListEntry;
1319	/** Help text. */
1320	const char *pszHelp;
1321
1322	/**
1323	* Checks the element specification.
1324	*
1325	* This is allowed to parse arguments and use pSpec->uProvider and
1326	* pElement->paArgs[].uProvider to store information that pfnInstantiate and
1327	* pfnCanReuseElement may use later on, thus avoiding duplicating work/code.
1328	*
1329	* @returns IPRT status code.
1330	* @param pProviderReg Pointer to the element provider registration.
1331	* @param pSpec The chain specification.
1332	* @param pElement The chain element specification to validate.
1333	* @param poffError Where to return error offset on failure. This is
1334	* set to the pElement->offSpec on input, so it only
1335	* needs to be adjusted if an argument is at fault.
1336	* @param pErrInfo Where to return additional error information, if
1337	* available. Optional.
1338	*/
1339	DECLCALLBACKMEMBER(int, pfnValidate)(PCRTVFSCHAINELEMENTREG pProviderReg, PRTVFSCHAINSPEC pSpec,
1340	PRTVFSCHAINELEMSPEC pElement, uint32_t *poffError, PRTERRINFO pErrInfo);
1341
1342	/**
1343	* Create a VFS object according to the element specification.
1344	*
1345	* @returns IPRT status code.
1346	* @param pProviderReg Pointer to the element provider registration.
1347	* @param pSpec The chain specification.
1348	* @param pElement The chain element specification to instantiate.
1349	* @param hPrevVfsObj Handle to the previous VFS object, NIL_RTVFSOBJ if
1350	* first.
1351	* @param phVfsObj Where to return the VFS object handle.
1352	* @param poffError Where to return error offset on failure. This is
1353	* set to the pElement->offSpec on input, so it only
1354	* needs to be adjusted if an argument is at fault.
1355	* @param pErrInfo Where to return additional error information, if
1356	* available. Optional.
1357	*/
1358	DECLCALLBACKMEMBER(int, pfnInstantiate)(PCRTVFSCHAINELEMENTREG pProviderReg, PCRTVFSCHAINSPEC pSpec,
1359	PCRTVFSCHAINELEMSPEC pElement, RTVFSOBJ hPrevVfsObj,
1360	PRTVFSOBJ phVfsObj, uint32_t *poffError, PRTERRINFO pErrInfo);
1361
1362	/**
1363	* Determins whether the element can be reused.
1364	*
1365	* This is for handling situations accessing the same file system twice, like
1366	* for both the source and destiation of a copy operation. This allows not only
1367	* sharing resources and avoid doing things twice, but also helps avoid file
1368	* sharing violations and inconsistencies araising from the image being updated
1369	* and read independently.
1370	*
1371	* @returns true if the element from @a pReuseSpec an be reused, false if not.
1372	* @param pProviderReg Pointer to the element provider registration.
1373	* @param pSpec The chain specification.
1374	* @param pElement The chain element specification.
1375	* @param pReuseSpec The chain specification of the existing chain.
1376	* @param pReuseElement The chain element specification of the existing
1377	* element that is being considered for reuse.
1378	*/
1379	DECLCALLBACKMEMBER(bool, pfnCanReuseElement)(PCRTVFSCHAINELEMENTREG pProviderReg,
1380	PCRTVFSCHAINSPEC pSpec, PCRTVFSCHAINELEMSPEC pElement,
1381	PCRTVFSCHAINSPEC pReuseSpec, PCRTVFSCHAINELEMSPEC pReuseElement);
1382
1383	/** End marker (RTVFSCHAINELEMENTREG_VERSION). */
1384	uintptr_t uEndMarker;
1385	} RTVFSCHAINELEMENTREG;
1386
1387	/** The VFS chain element registration record version number. */
1388	#define RTVFSCHAINELEMENTREG_VERSION RT_MAKE_U32_FROM_U8(0xff, 0x7f, 1, 0)
1389
1390
1391	/**
1392	* Parses the specification.
1393	*
1394	* @returns IPRT status code.
1395	* @param pszSpec The specification string to parse.
1396	* @param fFlags Flags, see RTVFSCHAIN_PF_XXX.
1397	* @param enmDesiredType The object type the caller wants to interface with.
1398	* @param ppSpec Where to return the pointer to the parsed
1399	* specification. This must be freed by calling
1400	* RTVfsChainSpecFree. Will always be set (unless
1401	* invalid parameters.)
1402	* @param poffError Where to return the offset into the input
1403	* specification of what's causing trouble. Always
1404	* set, unless this argument causes an invalid pointer
1405	* error.
1406	*/
1407	RTDECL(int) RTVfsChainSpecParse(const char *pszSpec, uint32_t fFlags, RTVFSOBJTYPE enmDesiredType,
1408	PRTVFSCHAINSPEC ppSpec, uint32_t poffError);
1409
1410	/** @name RTVfsChainSpecParse
1411	* @{ */
1412	/** Mask of valid flags. */
1413	#define RTVFSCHAIN_PF_VALID_MASK UINT32_C(0x00000000)
1414	/** @} */
1415
1416	/**
1417	* Checks and setups the chain.
1418	*
1419	* @returns IPRT status code.
1420	* @param pSpec The parsed specification.
1421	* @param pReuseSpec Spec to reuse if applicable. Optional.
1422	* @param phVfsObj Where to return the VFS object.
1423	* @param ppszFinalPath Where to return the pointer to the final path if
1424	* applicable. The caller needs to check whether this
1425	* is NULL or a path, in the former case nothing more
1426	* needs doing, whereas in the latter the caller must
1427	* perform the desired operation(s) on *phVfsObj using
1428	* the final path.
1429	* @param poffError Where to return the offset into the input
1430	* specification of what's causing trouble. Always
1431	* set, unless this argument causes an invalid pointer
1432	* error.
1433	* @param pErrInfo Where to return additional error information, if
1434	* available. Optional.
1435	*/
1436	RTDECL(int) RTVfsChainSpecCheckAndSetup(PRTVFSCHAINSPEC pSpec, PCRTVFSCHAINSPEC pReuseSpec,
1437	PRTVFSOBJ phVfsObj, const char *ppszFinalPath, uint32_t poffError, PRTERRINFO pErrInfo);
1438
1439	/**
1440	* Frees a parsed chain specification.
1441	*
1442	* @param pSpec What RTVfsChainSpecParse returned. NULL is
1443	* quietly ignored.
1444	*/
1445	RTDECL(void) RTVfsChainSpecFree(PRTVFSCHAINSPEC pSpec);
1446
1447	/**
1448	* Registers a chain element provider.
1449	*
1450	* @returns IPRT status code
1451	* @param pRegRec The registration record.
1452	* @param fFromCtor Indicates where we're called from.
1453	*/
1454	RTDECL(int) RTVfsChainElementRegisterProvider(PRTVFSCHAINELEMENTREG pRegRec, bool fFromCtor);
1455
1456	/**
1457	* Deregisters a chain element provider.
1458	*
1459	* @returns IPRT status code
1460	* @param pRegRec The registration record.
1461	* @param fFromDtor Indicates where we're called from.
1462	*/
1463	RTDECL(int) RTVfsChainElementDeregisterProvider(PRTVFSCHAINELEMENTREG pRegRec, bool fFromDtor);
1464
1465
1466	/** @def RTVFSCHAIN_AUTO_REGISTER_ELEMENT_PROVIDER
1467	* Automatically registers a chain element provider using a global constructor
1468	* and destructor hack.
1469	*
1470	* @param pRegRec Pointer to the registration record.
1471	* @param name Some unique variable name prefix.
1472	*/
1473
1474	#ifdef __cplusplus
1475	/**
1476	* Class used for registering a VFS chain element provider.
1477	*/
1478	class RTVfsChainElementAutoRegisterHack
1479	{
1480	private:
1481	/** The registration record, NULL if registration failed. */
1482	PRTVFSCHAINELEMENTREG m_pRegRec;
1483
1484	public:
1485	RTVfsChainElementAutoRegisterHack(PRTVFSCHAINELEMENTREG a_pRegRec)
1486	: m_pRegRec(a_pRegRec)
1487	{
1488	int rc = RTVfsChainElementRegisterProvider(m_pRegRec, true);
1489	if (RT_FAILURE(rc))
1490	m_pRegRec = NULL;
1491	}
1492
1493	~RTVfsChainElementAutoRegisterHack()
1494	{
1495	RTVfsChainElementDeregisterProvider(m_pRegRec, true);
1496	m_pRegRec = NULL;
1497	}
1498	};
1499
1500	# define RTVFSCHAIN_AUTO_REGISTER_ELEMENT_PROVIDER(pRegRec, name) \
1501	static RTVfsChainElementAutoRegisterHack name ## AutoRegistrationHack(pRegRec)
1502
1503	#else
1504	# define RTVFSCHAIN_AUTO_REGISTER_ELEMENT_PROVIDER(pRegRec, name) \
1505	extern void *name ## AutoRegistrationHack = \
1506	&Sorry_but_RTVFSCHAIN_AUTO_REGISTER_ELEMENT_PROVIDER_does_not_work_in_c_source_files
1507	#endif
1508
1509
1510	/**
1511	* Common worker for the 'stdfile' and 'open' providers for implementing
1512	* RTVFSCHAINELEMENTREG::pfnValidate.
1513	*
1514	* Stores the RTFILE_O_XXX flags in pSpec->uProvider.
1515	*
1516	* @returns IPRT status code.
1517	* @param pSpec The chain specification.
1518	* @param pElement The chain element specification to validate.
1519	* @param poffError Where to return error offset on failure. This is set to
1520	* the pElement->offSpec on input, so it only needs to be
1521	* adjusted if an argument is at fault.
1522	* @param pErrInfo Where to return additional error information, if
1523	* available. Optional.
1524	*/
1525	RTDECL(int) RTVfsChainValidateOpenFileOrIoStream(PRTVFSCHAINSPEC pSpec, PRTVFSCHAINELEMSPEC pElement,
1526	uint32_t *poffError, PRTERRINFO pErrInfo);
1527
1528
1529	/** @} */
1530
1531
1532	/** @} */
1533
1534	RT_C_DECLS_END
1535
1536	#endif /* !IPRT_INCLUDED_vfslowlevel_h */
1537

Note: See TracBrowser for help on using the repository browser.

source: vbox/trunk/include/iprt/vfslowlevel.h@ 84546

Download in other formats: