vfs.h@ 80518

Last change on this file since 80518 was 80518, checked in by vboxsync, 5 years ago
Runtime/RTVfs: Implement RTVfsDirRewind
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 77.3 KB

Line
1	/** @file
2	* IPRT - Virtual Filesystem.
3	*/
4
5	/*
6	* Copyright (C) 2010-2019 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_vfs_h
27	#define IPRT_INCLUDED_vfs_h
28	#ifndef RT_WITHOUT_PRAGMA_ONCE
29	# pragma once
30	#endif
31
32	#include <iprt/cdefs.h>
33	#include <iprt/types.h>
34	#include <iprt/dir.h>
35	#include <iprt/fs.h>
36	#include <iprt/handle.h>
37	#include <iprt/symlink.h>
38	#include <iprt/sg.h>
39	#include <iprt/time.h>
40
41
42	RT_C_DECLS_BEGIN
43
44	/** @defgroup grp_rt_vfs RTVfs - Virtual Filesystem
45	* @ingroup grp_rt
46	*
47	* The virtual filesystem APIs are intended to make it possible to work on
48	* container files, file system sub-trees, file system overlays and other custom
49	* filesystem configurations. It also makes it possible to create filters, like
50	* automatically gunzipping a tar.gz file before feeding it to the RTTar API for
51	* unpacking - or wise versa.
52	*
53	* The virtual filesystem APIs are intended to mirror the RTDir, RTFile, RTPath
54	* and RTFs APIs pretty closely so that rewriting a piece of code to work with
55	* it should be easy. However there are some differences to the way the APIs
56	* works and the user should heed the documentation. The differences are
57	* usually motivated by simplification and in some case to make the VFS more
58	* flexible.
59	*
60	* @{
61	*/
62
63	/**
64	* The object type.
65	*/
66	typedef enum RTVFSOBJTYPE
67	{
68	/** Invalid type. */
69	RTVFSOBJTYPE_INVALID = 0,
70	/** Pure base object.
71	* This is returned by the filesystem stream to represent directories,
72	* devices, fifos and similar that needs to be created. */
73	RTVFSOBJTYPE_BASE,
74	/** Virtual filesystem. */
75	RTVFSOBJTYPE_VFS,
76	/** Filesystem stream. */
77	RTVFSOBJTYPE_FS_STREAM,
78	/** Pure I/O stream. */
79	RTVFSOBJTYPE_IO_STREAM,
80	/** Directory. */
81	RTVFSOBJTYPE_DIR,
82	/** File. */
83	RTVFSOBJTYPE_FILE,
84	/** Symbolic link. */
85	RTVFSOBJTYPE_SYMLINK,
86	/** End of valid object types. */
87	RTVFSOBJTYPE_END,
88	/** Pure I/O stream. */
89	RTVFSOBJTYPE_32BIT_HACK = 0x7fffffff
90	} RTVFSOBJTYPE;
91	/** Pointer to a VFS object type. */
92	typedef RTVFSOBJTYPE *PRTVFSOBJTYPE;
93
94
95
96	/** @name RTVfsCreate flags
97	* @{ */
98	/** Whether the file system is read-only. */
99	#define RTVFS_C_READONLY RT_BIT(0)
100	/** Whether we the VFS should be thread safe (i.e. automaticaly employ
101	* locks). */
102	#define RTVFS_C_THREAD_SAFE RT_BIT(1)
103	/** @} */
104
105	/**
106	* Creates an empty virtual filesystem.
107	*
108	* @returns IPRT status code.
109	* @param pszName Name, for logging and such.
110	* @param fFlags Flags, MBZ.
111	* @param phVfs Where to return the VFS handle. Release the returned
112	* reference by calling RTVfsRelease.
113	*/
114	RTDECL(int) RTVfsCreate(const char *pszName, uint32_t fFlags, PRTVFS phVfs);
115	RTDECL(uint32_t) RTVfsRetain(RTVFS hVfs);
116	RTDECL(uint32_t) RTVfsRetainDebug(RTVFS hVfs, RT_SRC_POS_DECL);
117	RTDECL(uint32_t) RTVfsRelease(RTVFS hVfs);
118
119	/** @name RTVFSMNT_F_XXX - Flags for RTVfsMount
120	* @{ */
121	/** Mount read-only. */
122	#define RTVFSMNT_F_READ_ONLY RT_BIT_32(0)
123	/** Purpose is . */
124	#define RTVFSMNT_F_FOR_RANGE_IN_USE RT_BIT_32(1)
125	/** Valid mask. */
126	#define RTVFSMNT_F_VALID_MASK UINT32_C(0x00000003)
127	/** @} */
128
129	/**
130	* Does the file system detection and mounting.
131	*
132	* @returns IPRT status code.
133	* @retval VERR_VFS_UNSUPPORTED_FORMAT if not recognized as a support file
134	* system.
135	* @param hVfsFileIn The file handle of the volume.
136	* @param fFlags RTVFSMTN_F_XXX.
137	* @param phVfs Where to return the VFS handle on success.
138	* @param pErrInfo Where to return additional error information.
139	* Optional.
140	*/
141	RTDECL(int) RTVfsMountVol(RTVFSFILE hVfsFileIn, uint32_t fFlags, PRTVFS phVfs, PRTERRINFO pErrInfo);
142
143	RTDECL(int) RTVfsAttach(RTVFS hVfs, const char *pszMountPoint, uint32_t fFlags, RTVFS hVfsAttach);
144	RTDECL(int) RTVfsDetach(RTVFS hVfs, const char pszMountPoint, RTVFS hVfsToDetach, PRTVFS phVfsDetached);
145	RTDECL(uint32_t) RTVfsGetAttachmentCount(RTVFS hVfs);
146	RTDECL(int) RTVfsGetAttachment(RTVFS hVfs, uint32_t iOrdinal, PRTVFS phVfsAttached, uint32_t pfFlags,
147	char *pszMountPoint, size_t cbMountPoint);
148
149	/**
150	* Opens the root director of the given VFS.
151	*
152	* @returns IPRT status code.
153	* @param hVfs VFS handle.
154	* @param phDir Where to return the root directory handle.
155	*/
156	RTDECL(int) RTVfsOpenRoot(RTVFS hVfs, PRTVFSDIR phDir);
157
158	/**
159	* Queries information about a object in the virtual filesystem.
160	*
161	* @returns IPRT Status code.
162	* @param hVfs VFS handle.
163	* @param pszPath Path to the object, relative to the VFS root.
164	* @param pObjInfo Where to return info.
165	* @param enmAddAttr What to return.
166	* @param fFlags RTPATH_F_XXX.
167	* @sa RTPathQueryInfoEx, RTVfsDirQueryPathInfo, RTVfsObjQueryInfo
168	*/
169	RTDECL(int) RTVfsQueryPathInfo(RTVFS hVfs, const char *pszPath, PRTFSOBJINFO pObjInfo,
170	RTFSOBJATTRADD enmAddAttr, uint32_t fFlags);
171
172	/**
173	* Checks whether a given range is in use by the virtual filesystem.
174	*
175	* @returns IPRT status code.
176	* @param hVfs VFS handle.
177	* @param off Start offset to check.
178	* @param cb Number of bytes to check.
179	* @param pfUsed Where to store the result.
180	*/
181	RTDECL(int) RTVfsQueryRangeState(RTVFS hVfs, uint64_t off, size_t cb, bool *pfUsed);
182
183
184	/** @defgroup grp_vfs_obj VFS Base Object API
185	* @{
186	*/
187
188	/**
189	* Retains a reference to the VFS base object handle.
190	*
191	* @returns New reference count on success, UINT32_MAX on failure.
192	* @param hVfsObj The VFS base object handle.
193	*/
194	RTDECL(uint32_t) RTVfsObjRetain(RTVFSOBJ hVfsObj);
195	RTDECL(uint32_t) RTVfsObjRetainDebug(RTVFSOBJ hVfsObj, RT_SRC_POS_DECL);
196
197	/**
198	* Releases a reference to the VFS base handle.
199	*
200	* @returns New reference count on success (0 if closed), UINT32_MAX on failure.
201	* @param hVfsObj The VFS base object handle.
202	*/
203	RTDECL(uint32_t) RTVfsObjRelease(RTVFSOBJ hVfsObj);
204
205	/** @name RTVFSOBJ_F_XXX - Flags or RTVfsObjOpen and RTVfsDirOpenObj.
206	* @note Must leave space for RTPATH_F_XXX.
207	* @{ */
208	/** Directory (RTFS_TYPE_DIRECTORY). */
209	#define RTVFSOBJ_F_OPEN_DIRECTORY RT_BIT_32(8)
210	/** Symbolic link (RTFS_TYPE_SYMLINK). */
211	#define RTVFSOBJ_F_OPEN_SYMLINK RT_BIT_32(9)
212	/** Regular file (RTFS_TYPE_FILE). */
213	#define RTVFSOBJ_F_OPEN_FILE RT_BIT_32(10)
214	/** Character device (RTFS_TYPE_DEV_CHAR). */
215	#define RTVFSOBJ_F_OPEN_DEV_CHAR RT_BIT_32(11)
216	/** Block device (RTFS_TYPE_DEV_BLOCK). */
217	#define RTVFSOBJ_F_OPEN_DEV_BLOCK RT_BIT_32(12)
218	/** Named pipe (fifo) (RTFS_TYPE_FIFO). */
219	#define RTVFSOBJ_F_OPEN_FIFO RT_BIT_32(13)
220	/** Socket (RTFS_TYPE_SOCKET). */
221	#define RTVFSOBJ_F_OPEN_SOCKET RT_BIT_32(14)
222	/** Mounted VFS. */
223	#define RTVFSOBJ_F_OPEN_MOUNT RT_BIT_32(15)
224	/** Mask object types we wish to open. */
225	#define RTVFSOBJ_F_OPEN_MASK UINT32_C(0x0000ff00)
226	/** Any kind of object that translates to RTVFSOBJTYPE_FILE. */
227	#define RTVFSOBJ_F_OPEN_ANY_FILE (RTVFSOBJ_F_OPEN_FILE \| RTVFSOBJ_F_OPEN_DEV_BLOCK)
228	/** Any kind of object that translates to RTVFSOBJTYPE_IOS or
229	* RTVFSOBJTYPE_FILE. */
230	#define RTVFSOBJ_F_OPEN_ANY_IO_STREAM ( RTVFSOBJ_F_ANY_OPEN_FILE \| RTVFSOBJ_F_DEV_OPEN_BLOCK \
231	\| RTVFSOBJ_F_OPEN_FIFO \| RTVFSOBJ_F_OPEN_SOCKET)
232	/** Any kind of object. */
233	#define RTVFSOBJ_F_OPEN_ANY RTVFSOBJ_F_OPEN_MASK
234
235	/** Do't create anything, return file not found. */
236	#define RTVFSOBJ_F_CREATE_NOTHING UINT32_C(0x00000000)
237	/** Create a file if the if the object was not found and the RTFILE_O_XXX
238	* flags allows it. */
239	#define RTVFSOBJ_F_CREATE_FILE UINT32_C(0x00010000)
240	/** Create a directory if the object was not found and the RTFILE_O_XXX
241	* flags allows it. */
242	#define RTVFSOBJ_F_CREATE_DIRECTORY UINT32_C(0x00020000)
243	/** The creation type mask. */
244	#define RTVFSOBJ_F_CREATE_MASK UINT32_C(0x00070000)
245
246	/** Indicate that this call is for traversal.
247	* @internal only */
248	#define RTVFSOBJ_F_TRAVERSAL RT_BIT_32(31)
249	/** Valid mask for external callers. */
250	#define RTVFSOBJ_F_VALID_MASK UINT32_C(0x0007ff00)
251	/** @} */
252
253	/**
254	* Opens any file system object in the given VFS.
255	*
256	* @returns IPRT status code.
257	* @param hVfs The VFS to open the object within.
258	* @param pszPath Path to the file.
259	* @param fFileOpen RTFILE_O_XXX flags.
260	* @param fObjFlags More flags: RTVFSOBJ_F_XXX, RTPATH_F_XXX.
261	* @param phVfsObj Where to return the object handle.
262	* @sa RTVfsDirOpenObj, RTVfsDirOpenDir, RTVfsDirOpenFile
263	*/
264	RTDECL(int) RTVfsObjOpen(RTVFS hVfs, const char *pszPath, uint64_t fFileOpen, uint32_t fObjFlags, PRTVFSOBJ phVfsObj);
265
266	/**
267	* Query information about the object.
268	*
269	* @returns IPRT status code.
270	* @retval VERR_NOT_SUPPORTED if the @a enmAddAttr value is not handled by the
271	* implementation.
272	*
273	* @param hVfsObj The VFS object handle.
274	* @param pObjInfo Where to return the info.
275	* @param enmAddAttr Which additional attributes should be retrieved.
276	* @sa RTVfsIoStrmQueryInfo, RTVfsFileQueryInfo, RTFileQueryInfo,
277	* RTPathQueryInfo
278	*/
279	RTDECL(int) RTVfsObjQueryInfo(RTVFSOBJ hVfsObj, PRTFSOBJINFO pObjInfo, RTFSOBJATTRADD enmAddAttr);
280
281	/**
282	* Sets the file mode for the given VFS object.
283	*
284	* @returns IPRT status code.
285	* @retval VERR_INVALID_FUNCTION if the object type has no file mode to set.
286	* Only directories, files and symbolic links support this operation.
287	*
288	* @param hVfsObj The VFS object handle.
289	* @param fMode The mode mask.
290	* @param fMask The bits in the mode mask which should be changed.
291	*/
292	RTDECL(int) RTVfsObjSetMode(RTVFSOBJ hVfsObj, RTFMODE fMode, RTFMODE fMask);
293
294	/**
295	* Sets one or more timestamps for the given VFS object.
296	*
297	* @returns IPRT status code.
298	* @retval VERR_INVALID_FUNCTION if the object type has no file mode to set.
299	* Only directories, files and symbolic links support this operation.
300	*
301	* @param hVfsObj The VFS object handle.
302	* @param pAccessTime Pointer to the new access time. NULL if not to
303	* be changed.
304	* @param pModificationTime Pointer to the new modifcation time. NULL if not
305	* to be changed.
306	* @param pChangeTime Pointer to the new change time. NULL if not to
307	* be changed.
308	* @param pBirthTime Pointer to the new time of birth. NULL if not to
309	* be changed.
310	*
311	* @remarks See RTFileSetTimes for restrictions and behavior imposed by the
312	* host OS or underlying VFS provider.
313	* @sa RTFileSetTimes, RTPathSetTimes
314	*/
315	RTDECL(int) RTVfsObjSetTimes(RTVFSOBJ hVfsObj, PCRTTIMESPEC pAccessTime, PCRTTIMESPEC pModificationTime,
316	PCRTTIMESPEC pChangeTime, PCRTTIMESPEC pBirthTime);
317
318	/**
319	* Set the unix style owner and group on the given VFS object.
320	*
321	* @returns IPRT status code.
322	* @retval VERR_INVALID_FUNCTION if the object type has no file mode to set.
323	* Only directories, files and symbolic links support this operation.
324	*
325	* @param hVfsObj The VFS object handle.
326	* @param uid The user ID of the new owner. NIL_RTUID if
327	* unchanged.
328	* @param gid The group ID of the new owner group. NIL_RTGID if
329	* unchanged.
330	*
331	* @sa RTFileSetOwner, RTPathSetOwner.
332	*/
333	RTDECL(int) RTVfsObjSetOwner(RTVFSOBJ hVfsObj, RTUID uid, RTGID gid);
334
335
336	/**
337	* Gets the type of a VFS object.
338	*
339	* @returns The VFS object type on success, RTVFSOBJTYPE_INVALID on failure.
340	* @param hVfsObj The VFS base object handle.
341	*/
342	RTDECL(RTVFSOBJTYPE) RTVfsObjGetType(RTVFSOBJ hVfsObj);
343
344	/**
345	* Converts a VFS base object handle to a VFS handle.
346	*
347	* @returns Referenced handle on success, NIL on failure.
348	* @param hVfsObj The VFS base object handle.
349	*/
350	RTDECL(RTVFS) RTVfsObjToVfs(RTVFSOBJ hVfsObj);
351
352	/**
353	* Converts a VFS base object handle to a VFS filesystem stream handle.
354	*
355	* @returns Referenced handle on success, NIL on failure.
356	* @param hVfsObj The VFS base object handle.
357	*/
358	RTDECL(RTVFSFSSTREAM) RTVfsObjToFsStream(RTVFSOBJ hVfsObj);
359
360	/**
361	* Converts a VFS base object handle to a VFS directory handle.
362	*
363	* @returns Referenced handle on success, NIL on failure.
364	* @param hVfsObj The VFS base object handle.
365	*/
366	RTDECL(RTVFSDIR) RTVfsObjToDir(RTVFSOBJ hVfsObj);
367
368	/**
369	* Converts a VFS base object handle to a VFS I/O stream handle.
370	*
371	* @returns Referenced handle on success, NIL on failure.
372	* @param hVfsObj The VFS base object handle.
373	*/
374	RTDECL(RTVFSIOSTREAM) RTVfsObjToIoStream(RTVFSOBJ hVfsObj);
375
376	/**
377	* Converts a VFS base object handle to a VFS file handle.
378	*
379	* @returns Referenced handle on success, NIL on failure.
380	* @param hVfsObj The VFS base object handle.
381	*/
382	RTDECL(RTVFSFILE) RTVfsObjToFile(RTVFSOBJ hVfsObj);
383
384	/**
385	* Converts a VFS base object handle to a VFS symbolic link handle.
386	*
387	* @returns Referenced handle on success, NIL on failure.
388	* @param hVfsObj The VFS base object handle.
389	*/
390	RTDECL(RTVFSSYMLINK) RTVfsObjToSymlink(RTVFSOBJ hVfsObj);
391
392
393	/**
394	* Converts a VFS handle to a VFS base object handle.
395	*
396	* @returns Referenced handle on success, NIL if the input handle was invalid.
397	* @param hVfs The VFS handle.
398	*/
399	RTDECL(RTVFSOBJ) RTVfsObjFromVfs(RTVFS hVfs);
400
401	/**
402	* Converts a VFS filesystem stream handle to a VFS base object handle.
403	*
404	* @returns Referenced handle on success, NIL if the input handle was invalid.
405	* @param hVfsFss The VFS filesystem stream handle.
406	*/
407	RTDECL(RTVFSOBJ) RTVfsObjFromFsStream(RTVFSFSSTREAM hVfsFss);
408
409	/**
410	* Converts a VFS directory handle to a VFS base object handle.
411	*
412	* @returns Referenced handle on success, NIL if the input handle was invalid.
413	* @param hVfsDir The VFS directory handle.
414	*/
415	RTDECL(RTVFSOBJ) RTVfsObjFromDir(RTVFSDIR hVfsDir);
416
417	/**
418	* Converts a VFS I/O stream handle to a VFS base object handle.
419	*
420	* @returns Referenced handle on success, NIL if the input handle was invalid.
421	* @param hVfsIos The VFS I/O stream handle.
422	*/
423	RTDECL(RTVFSOBJ) RTVfsObjFromIoStream(RTVFSIOSTREAM hVfsIos);
424
425	/**
426	* Converts a VFS file handle to a VFS base object handle.
427	*
428	* @returns Referenced handle on success, NIL if the input handle was invalid.
429	* @param hVfsFile The VFS file handle.
430	*/
431	RTDECL(RTVFSOBJ) RTVfsObjFromFile(RTVFSFILE hVfsFile);
432
433	/**
434	* Converts a VFS symbolic link handle to a VFS base object handle.
435	*
436	* @returns Referenced handle on success, NIL if the input handle was invalid.
437	* @param hVfsSym The VFS symbolic link handle.
438	*/
439	RTDECL(RTVFSOBJ) RTVfsObjFromSymlink(RTVFSSYMLINK hVfsSym);
440
441	/** @} */
442
443
444	/** @defgroup grp_vfs_fsstream VFS Filesystem Stream API
445	*
446	* Filesystem streams are for tar, cpio and similar. Any virtual filesystem can
447	* be turned into a filesystem stream using RTVfsFsStrmFromVfs.
448	*
449	* @{
450	*/
451
452	RTDECL(uint32_t) RTVfsFsStrmRetain(RTVFSFSSTREAM hVfsFss);
453	RTDECL(uint32_t) RTVfsFsStrmRetainDebug(RTVFSFSSTREAM hVfsFss, RT_SRC_POS_DECL);
454	RTDECL(uint32_t) RTVfsFsStrmRelease(RTVFSFSSTREAM hVfsFss);
455	RTDECL(int) RTVfsFsStrmQueryInfo(RTVFSFSSTREAM hVfsFss, PRTFSOBJINFO pObjInfo, RTFSOBJATTRADD enmAddAttr);
456
457	/**
458	* Gets the next object in the stream.
459	*
460	* This call may affect the stream posision of a previously returned object.
461	*
462	* The type of object returned here typically boils down to three types:
463	* - I/O streams (representing files),
464	* - symbolic links
465	* - base object
466	* The base objects represent anything not convered by the two other, i.e.
467	* directories, device nodes, fifos, sockets and whatnot. The details can be
468	* queried using RTVfsObjQueryInfo.
469	*
470	* That said, absolutely any object except for filesystem stream objects can be
471	* returned by this call. Any generic code is adviced to just deal with it all.
472	*
473	* @returns IPRT status code.
474	* @retval VINF_SUCCESS if a new object was retrieved.
475	* @retval VERR_EOF when there are no more objects.
476	* @retval VERR_INVALID_FUNCTION if called on a non-readable stream.
477	*
478	* @param hVfsFss The file system stream handle.
479	* @param ppszName Where to return the object name. Must be freed by
480	* calling RTStrFree.
481	* @param penmType Where to return the object type.
482	* @param phVfsObj Where to return the object handle (referenced). This
483	* must be cast to the desired type before use.
484	*/
485	RTDECL(int) RTVfsFsStrmNext(RTVFSFSSTREAM hVfsFss, char *ppszName, RTVFSOBJTYPE penmType, PRTVFSOBJ phVfsObj);
486
487	/**
488	* Appends a VFS object to the stream.
489	*
490	* The stream must be writable.
491	*
492	* @returns IPRT status code.
493	* @retval VERR_INVALID_FUNCTION if called on a non-writable stream.
494	* @param hVfsFss The file system stream handle.
495	* @param pszPath The path.
496	* @param hVfsObj The VFS object to add.
497	* @param fFlags RTVFSFSSTRM_ADD_F_XXX.
498	*/
499	RTDECL(int) RTVfsFsStrmAdd(RTVFSFSSTREAM hVfsFss, const char *pszPath, RTVFSOBJ hVfsObj, uint32_t fFlags);
500
501	/** @name RTVFSFSSTRM_ADD_F_XXX - Flags for RTVfsFsStrmAdd.
502	* @{ */
503	/** Input is an I/O stream of indeterminate length, read to the end and then
504	* update the file header.
505	* @note This is only possible if the output stream is actually a file. */
506	#define RTVFSFSSTRM_ADD_F_STREAM RT_BIT_32(0)
507	/** Mask of flags specific to the target stream. */
508	#define RTVFSFSSTRM_ADD_F_SPECIFIC_MASK UINT32_C(0xff000000)
509	/** Valid bits. */
510	#define RTVFSFSSTRM_ADD_F_VALID_MASK UINT32_C(0xff000001)
511	/** @} */
512
513	/**
514	* Pushes an byte stream onto the stream.
515	*
516	* The stream must be writable.
517	*
518	* This differs from RTVfsFsStrmAdd() in that it will create a regular file in
519	* the output file system stream and provide the actual content bytes via the
520	* returned I/O stream object.
521	*
522	* @returns IPRT status code.
523	* @retval VERR_INVALID_FUNCTION if called on a non-writable stream.
524	* @param hVfsFss The file system stream handle.
525	* @param pszPath The path to the file.
526	* @param cbFile The file size. This can also be set to UINT64_MAX if
527	* the file system stream is backed by a file.
528	* @param paObjInfo Array of zero or more RTFSOBJINFO structures containing
529	* different pieces of information about the file. If any
530	* provided, the first one should be a RTFSOBJATTRADD_UNIX
531	* one, additional can be supplied if wanted. What exactly
532	* is needed depends on the underlying FS stream
533	* implementation.
534	* @param cObjInfo Number of items in the array @a paObjInfo points at.
535	* @param fFlags RTVFSFSSTRM_PUSH_F_XXX.
536	* @param phVfsIos Where to return the I/O stream to feed the file content
537	* to. If the FS stream is backed by a file, the returned
538	* handle can be cast to a file if necessary.
539	*/
540	RTDECL(int) RTVfsFsStrmPushFile(RTVFSFSSTREAM hVfsFss, const char *pszPath, uint64_t cbFile,
541	PCRTFSOBJINFO paObjInfo, uint32_t cObjInfo, uint32_t fFlags, PRTVFSIOSTREAM phVfsIos);
542
543	/** @name RTVFSFSSTRM_PUSH_F_XXX - Flags for RTVfsFsStrmPushFile.
544	* @{ */
545	/** Input is an I/O stream of indeterminate length, read to the end and then
546	* update the file header.
547	* @note This is only possible if the output stream is actually a file. */
548	#define RTVFSFSSTRM_PUSH_F_STREAM RT_BIT_32(0)
549	/** Mask of flags specific to the target stream. */
550	#define RTVFSFSSTRM_PUSH_F_SPECIFIC_MASK UINT32_C(0xff000000)
551	/** Valid bits. */
552	#define RTVFSFSSTRM_PUSH_F_VALID_MASK UINT32_C(0xff000001)
553	/** @} */
554
555	/**
556	* Marks the end of the stream.
557	*
558	* The stream must be writable.
559	*
560	* @returns IPRT status code.
561	* @retval VERR_INVALID_FUNCTION if called on a non-writable stream.
562	* @param hVfsFss The file system stream handle.
563	*/
564	RTDECL(int) RTVfsFsStrmEnd(RTVFSFSSTREAM hVfsFss);
565
566	/** @} */
567
568
569	/** @defgroup grp_vfs_dir VFS Directory API
570	* @{
571	*/
572
573	/**
574	* Retains a reference to the VFS directory handle.
575	*
576	* @returns New reference count on success, UINT32_MAX on failure.
577	* @param hVfsDir The VFS directory handle.
578	*/
579	RTDECL(uint32_t) RTVfsDirRetain(RTVFSDIR hVfsDir);
580	RTDECL(uint32_t) RTVfsDirRetainDebug(RTVFSDIR hVfsDir, RT_SRC_POS_DECL);
581
582	/**
583	* Releases a reference to the VFS directory handle.
584	*
585	* @returns New reference count on success (0 if closed), UINT32_MAX on failure.
586	* @param hVfsDir The VFS directory handle.
587	*/
588	RTDECL(uint32_t) RTVfsDirRelease(RTVFSDIR hVfsDir);
589
590	/**
591	* Opens a directory in the specified file system.
592	*
593	* @returns IPRT status code.
594	* @param hVfs The VFS to open the directory within.
595	* @param pszPath Path to the directory, relative to the root.
596	* @param fFlags Reserved, MBZ.
597	* @param phVfsDir Where to return the directory.
598	*/
599	RTDECL(int) RTVfsDirOpen(RTVFS hVfs, const char *pszPath, uint32_t fFlags, PRTVFSDIR phVfsDir);
600
601	/**
602	* Opens any file system object in or under the given directory.
603	*
604	* @returns IPRT status code.
605	* @param hVfsDir The VFS directory start walking the @a pszPath
606	* relative to.
607	* @param pszPath Path to the file.
608	* @param fFileOpen RTFILE_O_XXX flags.
609	* @param fObjFlags More flags: RTVFSOBJ_F_XXX, RTPATH_F_XXX.
610	* @param phVfsObj Where to return the object handle.
611	* @sa RTVfsObjOpen, RTVfsDirOpenDir, RTVfsDirOpenFile
612	*/
613	RTDECL(int) RTVfsDirOpenObj(RTVFSDIR hVfsDir, const char *pszPath, uint64_t fFileOpen, uint32_t fObjFlags, PRTVFSOBJ phVfsObj);
614
615	/**
616	* Opens a file in or under the given directory.
617	*
618	* @returns IPRT status code.
619	* @param hVfsDir The VFS directory start walking the @a pszPath
620	* relative to.
621	* @param pszPath Path to the file.
622	* @param fOpen RTFILE_O_XXX flags.
623	* @param phVfsFile Where to return the file.
624	* @sa RTVfsDirOpenFileAsIoStream
625	*/
626	RTDECL(int) RTVfsDirOpenFile(RTVFSDIR hVfsDir, const char *pszPath, uint64_t fOpen, PRTVFSFILE phVfsFile);
627
628	/**
629	* Convenience wrapper around RTVfsDirOpenFile that returns an I/O stream.
630	*
631	* @returns IPRT status code.
632	* @param hVfsDir The VFS directory start walking the @a pszPath
633	* relative to.
634	* @param pszPath Path to the file.
635	* @param fOpen RTFILE_O_XXX flags.
636	* @param phVfsIos Where to return the I/O stream handle of the file.
637	* @sa RTVfsDirOpenFile
638	*/
639	RTDECL(int) RTVfsDirOpenFileAsIoStream(RTVFSDIR hVfsDir, const char *pszPath, uint64_t fOpen, PRTVFSIOSTREAM phVfsIos);
640
641	/**
642	* Opens a directory in or under the given directory.
643	*
644	* @returns IPRT status code.
645	* @param hVfsDir The VFS directory start walking the @a pszPath
646	* relative to.
647	* @param pszPath Path to the file.
648	* @param fFlags Reserved, MBZ.
649	* @param phVfsDir Where to return the directory.
650	*/
651	RTDECL(int) RTVfsDirOpenDir(RTVFSDIR hVfsDir, const char *pszPath, uint32_t fFlags, PRTVFSDIR phVfsDir);
652
653	/**
654	* Creates a directory relative to @a hVfsDir.
655	*
656	* @returns IPRT status code
657	* @param hVfsDir The directory the path is relative to.
658	* @param pszRelPath The relative path to the new directory.
659	* @param fMode The file mode for the new directory.
660	* @param fFlags Directory creation flags, RTDIRCREATE_FLAGS_XXX.
661	* @param phVfsDir Where to return the handle to the newly created
662	* directory. Optional.
663	* @sa RTDirCreate, RTDirRelDirCreate
664	*/
665	RTDECL(int) RTVfsDirCreateDir(RTVFSDIR hVfsDir, const char *pszRelPath, RTFMODE fMode, uint32_t fFlags, PRTVFSDIR phVfsDir);
666
667	/**
668	* Create a VFS directory handle from a standard IPRT directory handle (RTDIR).
669	*
670	* @returns IPRT status code.
671	* @param hDir The standard IPRT directory handle.
672	* @param fLeaveOpen Whether to leave the handle open when the VFS
673	* directory is released, or to close it (@c false).
674	* @param phVfsDir Where to return the VFS directory handle.
675	*/
676	RTDECL(int) RTVfsDirFromRTDir(RTDIR hDir, bool fLeaveOpen, PRTVFSDIR phVfsDir);
677
678	/**
679	* RTDirOpen + RTVfsDirFromRTDir.
680	*
681	* @returns IPRT status code.
682	* @param pszPath The path to the directory.
683	* @param fFlags RTDIR_F_XXX.
684	* @param phVfsDir Where to return the VFS directory handle.
685	*/
686	RTDECL(int) RTVfsDirOpenNormal(const char *pszPath, uint32_t fFlags, PRTVFSDIR phVfsDir);
687
688	/** Checks if @a hVfsDir was opened using RTVfsDirOpenNormal() or
689	* RTVfsDirFromRTDir(), either directly or indirectly. */
690	RTDECL(bool) RTVfsDirIsStdDir(RTVFSDIR hVfsDir);
691
692	/**
693	* Queries information about a object in or under the given directory.
694	*
695	* @returns IPRT Status code.
696	* @param hVfsDir The VFS directory start walking the @a pszPath
697	* relative to.
698	* @param pszPath Path to the object.
699	* @param pObjInfo Where to return info.
700	* @param enmAddAttr What to return.
701	* @param fFlags RTPATH_F_XXX.
702	* @sa RTPathQueryInfoEx, RTVfsQueryPathInfo, RTVfsObjQueryInfo
703	*/
704	RTDECL(int) RTVfsDirQueryPathInfo(RTVFSDIR hVfsDir, const char *pszPath, PRTFSOBJINFO pObjInfo,
705	RTFSOBJATTRADD enmAddAttr, uint32_t fFlags);
706
707	/**
708	* Removes a directory relative to @a hVfsDir.
709	*
710	* @returns IPRT status code.
711	* @param hVfsDir The VFS directory to start walking the @a pszRelPath
712	* relative to.
713	* @param pszRelPath The path to the directory that should be removed.
714	* @param fFlags Reserved, MBZ.
715	*/
716	RTDECL(int) RTVfsDirRemoveDir(RTVFSDIR hVfsDir, const char *pszRelPath, uint32_t fFlags);
717
718	/**
719	* Reads the next entry in the directory returning extended information.
720	*
721	* @returns VINF_SUCCESS and data in pDirEntry on success.
722	* @returns VERR_NO_MORE_FILES when the end of the directory has been reached.
723	* @returns VERR_BUFFER_OVERFLOW if the buffer is too small to contain the filename. If
724	* pcbDirEntry is specified it will be updated with the required buffer size.
725	* @returns suitable iprt status code on other errors.
726	*
727	* @param hVfsDir The VFS directory.
728	* @param pDirEntry Where to store the information about the next
729	* directory entry on success.
730	* @param pcbDirEntry Optional parameter used for variable buffer size.
731	*
732	* On input the variable pointed to contains the size of the pDirEntry
733	* structure. This must be at least OFFSET(RTDIRENTRYEX, szName[2]) bytes.
734	*
735	* On successful output the field is updated to
736	* OFFSET(RTDIRENTRYEX, szName[pDirEntry->cbName + 1]).
737	*
738	* When the data doesn't fit in the buffer and VERR_BUFFER_OVERFLOW is
739	* returned, this field contains the required buffer size.
740	*
741	* The value is unchanged in all other cases.
742	* @param enmAddAttr Which set of additional attributes to request.
743	* Use RTFSOBJATTRADD_NOTHING if this doesn't matter.
744	*
745	* @sa RTDirReadEx
746	*/
747	RTDECL(int) RTVfsDirReadEx(RTVFSDIR hVfsDir, PRTDIRENTRYEX pDirEntry, size_t *pcbDirEntry, RTFSOBJATTRADD enmAddAttr);
748
749	/**
750	* Rewind and restart the directory reading.
751	*
752	* @returns IRPT status code.
753	* @param hVfsDir The VFS directory.
754	*/
755	RTDECL(int) RTVfsDirRewind(RTVFSDIR hVfsDir);
756
757	/** @} */
758
759
760	/** @defgroup grp_vfs_symlink VFS Symbolic Link API
761	*
762	* @remarks The TAR VFS and filesystem stream uses symbolic links for
763	* describing hard links as well. The users must use RTFS_IS_SYMLINK
764	* to check if it is a real symlink in those cases.
765	*
766	* @remarks Any VFS which is backed by a real file system may be subject to
767	* races with other processes or threads, so the user may get
768	* unexpected errors when this happends. This is a bit host specific,
769	* i.e. it might be prevent on windows if we care.
770	*
771	* @{
772	*/
773
774
775	/**
776	* Retains a reference to the VFS symbolic link handle.
777	*
778	* @returns New reference count on success, UINT32_MAX on failure.
779	* @param hVfsSym The VFS symbolic link handle.
780	*/
781	RTDECL(uint32_t) RTVfsSymlinkRetain(RTVFSSYMLINK hVfsSym);
782	RTDECL(uint32_t) RTVfsSymlinkRetainDebug(RTVFSSYMLINK hVfsSym, RT_SRC_POS_DECL);
783
784	/**
785	* Releases a reference to the VFS symbolic link handle.
786	*
787	* @returns New reference count on success (0 if closed), UINT32_MAX on failure.
788	* @param hVfsSym The VFS symbolic link handle.
789	*/
790	RTDECL(uint32_t) RTVfsSymlinkRelease(RTVFSSYMLINK hVfsSym);
791
792	/**
793	* Query information about the symbolic link.
794	*
795	* @returns IPRT status code.
796	* @param hVfsSym The VFS symbolic link handle.
797	* @param pObjInfo Where to return the info.
798	* @param enmAddAttr Which additional attributes should be retrieved.
799	*
800	* @sa RTFileQueryInfo, RTPathQueryInfo, RTPathQueryInfoEx
801	*/
802	RTDECL(int) RTVfsSymlinkQueryInfo(RTVFSSYMLINK hVfsSym, PRTFSOBJINFO pObjInfo, RTFSOBJATTRADD enmAddAttr);
803
804	/**
805	* Set the unix style owner and group.
806	*
807	* @returns IPRT status code.
808	* @param hVfsSym The VFS symbolic link handle.
809	* @param fMode The new mode bits.
810	* @param fMask The mask indicating which bits we are changing.
811	* @sa RTFileSetMode, RTPathSetMode
812	*/
813	RTDECL(int) RTVfsSymlinkSetMode(RTVFSSYMLINK hVfsSym, RTFMODE fMode, RTFMODE fMask);
814
815	/**
816	* Set the timestamps associated with the object.
817	*
818	* @returns IPRT status code.
819	* @param hVfsSym The VFS symbolic link handle.
820	* @param pAccessTime Pointer to the new access time. NULL if not
821	* to be changed.
822	* @param pModificationTime Pointer to the new modifcation time. NULL if
823	* not to be changed.
824	* @param pChangeTime Pointer to the new change time. NULL if not to be
825	* changed.
826	* @param pBirthTime Pointer to the new time of birth. NULL if not to be
827	* changed.
828	* @remarks See RTFileSetTimes for restrictions and behavior imposed by the
829	* host OS or underlying VFS provider.
830	* @sa RTFileSetTimes, RTPathSetTimes
831	*/
832	RTDECL(int) RTVfsSymlinkSetTimes(RTVFSSYMLINK hVfsSym, PCRTTIMESPEC pAccessTime, PCRTTIMESPEC pModificationTime,
833	PCRTTIMESPEC pChangeTime, PCRTTIMESPEC pBirthTime);
834
835	/**
836	* Set the unix style owner and group.
837	*
838	* @returns IPRT status code.
839	* @param hVfsSym The VFS symbolic link handle.
840	* @param uid The user ID of the new owner. NIL_RTUID if
841	* unchanged.
842	* @param gid The group ID of the new owner group. NIL_RTGID if
843	* unchanged.
844	* @sa RTFileSetOwner, RTPathSetOwner.
845	*/
846	RTDECL(int) RTVfsSymlinkSetOwner(RTVFSSYMLINK hVfsSym, RTUID uid, RTGID gid);
847
848	/**
849	* Read the symbolic link target.
850	*
851	* @returns IPRT status code.
852	* @param hVfsSym The VFS symbolic link handle.
853	* @param pszTarget The target buffer.
854	* @param cbTarget The size of the target buffer.
855	* @sa RTSymlinkRead
856	*/
857	RTDECL(int) RTVfsSymlinkRead(RTVFSSYMLINK hVfsSym, char *pszTarget, size_t cbTarget);
858
859	/** @} */
860
861
862
863	/** @defgroup grp_vfs_iostream VFS I/O Stream API
864	* @{
865	*/
866
867	/**
868	* Creates a VFS file from a memory buffer.
869	*
870	* @returns IPRT status code.
871	*
872	* @param fFlags A combination of RTFILE_O_READ and RTFILE_O_WRITE.
873	* @param pvBuf The buffer. This will be copied and not referenced
874	* after this function returns.
875	* @param cbBuf The buffer size.
876	* @param phVfsIos Where to return the VFS I/O stream handle.
877	*/
878	RTDECL(int) RTVfsIoStrmFromBuffer(uint32_t fFlags, void const *pvBuf, size_t cbBuf, PRTVFSIOSTREAM phVfsIos);
879
880	/**
881	* Creates a VFS I/O stream handle from a standard IPRT file handle (RTFILE).
882	*
883	* @returns IPRT status code.
884	* @param hFile The standard IPRT file handle.
885	* @param fOpen The flags the handle was opened with. Pass 0 to
886	* have these detected.
887	* @param fLeaveOpen Whether to leave the handle open when the VFS file
888	* is released, or to close it (@c false).
889	* @param phVfsIos Where to return the VFS I/O stream handle.
890	*/
891	RTDECL(int) RTVfsIoStrmFromRTFile(RTFILE hFile, uint64_t fOpen, bool fLeaveOpen, PRTVFSIOSTREAM phVfsIos);
892
893	/**
894	* Creates a VFS I/O stream handle from a standard IPRT pipe handle (RTPIPE).
895	*
896	* @returns IPRT status code.
897	* @param hPipe The standard IPRT pipe handle.
898	* @param fLeaveOpen Whether to leave the handle open when the VFS file
899	* is released, or to close it (@c false).
900	* @param phVfsIos Where to return the VFS I/O stream handle.
901	*/
902	RTDECL(int) RTVfsIoStrmFromRTPipe(RTPIPE hPipe, bool fLeaveOpen, PRTVFSIOSTREAM phVfsIos);
903
904	/**
905	* Convenience function combining RTFileOpen with RTVfsIoStrmFromRTFile.
906	*
907	* @returns IPRT status code.
908	* @param pszFilename The path to the file in the normal file system.
909	* @param fOpen The flags to pass to RTFileOpen when opening the
910	* file, i.e. RTFILE_O_XXX.
911	* @param phVfsIos Where to return the VFS I/O stream handle.
912	*/
913	RTDECL(int) RTVfsIoStrmOpenNormal(const char *pszFilename, uint64_t fOpen, PRTVFSIOSTREAM phVfsIos);
914
915	/**
916	* Create a VFS I/O stream handle from one of the standard handles.
917	*
918	* @returns IPRT status code.
919	* @param enmStdHandle The standard IPRT file handle.
920	* @param fOpen The flags the handle was opened with. Pass 0 to
921	* have these detected.
922	* @param fLeaveOpen Whether to leave the handle open when the VFS file
923	* is released, or to close it (@c false).
924	* @param phVfsIos Where to return the VFS I/O stream handle.
925	*/
926	RTDECL(int) RTVfsIoStrmFromStdHandle(RTHANDLESTD enmStdHandle, uint64_t fOpen, bool fLeaveOpen,
927	PRTVFSIOSTREAM phVfsIos);
928
929	/**
930	* Retains a reference to the VFS I/O stream handle.
931	*
932	* @returns New reference count on success, UINT32_MAX on failure.
933	* @param hVfsIos The VFS I/O stream handle.
934	*/
935	RTDECL(uint32_t) RTVfsIoStrmRetain(RTVFSIOSTREAM hVfsIos);
936	RTDECL(uint32_t) RTVfsIoStrmRetainDebug(RTVFSIOSTREAM hVfsIos, RT_SRC_POS_DECL);
937
938	/**
939	* Releases a reference to the VFS I/O stream handle.
940	*
941	* @returns New reference count on success (0 if closed), UINT32_MAX on failure.
942	* @param hVfsIos The VFS I/O stream handle.
943	*/
944	RTDECL(uint32_t) RTVfsIoStrmRelease(RTVFSIOSTREAM hVfsIos);
945
946	/**
947	* Convert the VFS I/O stream handle to a VFS file handle.
948	*
949	* @returns The VFS file handle on success, this must be released.
950	* NIL_RTVFSFILE if the I/O stream handle is invalid.
951	* @param hVfsIos The VFS I/O stream handle.
952	* @sa RTVfsFileToIoStream
953	*/
954	RTDECL(RTVFSFILE) RTVfsIoStrmToFile(RTVFSIOSTREAM hVfsIos);
955
956	/**
957	* Query information about the I/O stream.
958	*
959	* @returns IPRT status code.
960	* @param hVfsIos The VFS I/O stream handle.
961	* @param pObjInfo Where to return the info.
962	* @param enmAddAttr Which additional attributes should be retrieved.
963	* @sa RTFileQueryInfo
964	*/
965	RTDECL(int) RTVfsIoStrmQueryInfo(RTVFSIOSTREAM hVfsIos, PRTFSOBJINFO pObjInfo, RTFSOBJATTRADD enmAddAttr);
966
967	/**
968	* Read bytes from the I/O stream.
969	*
970	* @returns IPRT status code.
971	* @retval VINF_SUCCESS and the number of bytes read written to @a pcbRead.
972	* @retval VINF_TRY_AGAIN if @a fBlocking is @c false, @a pcbRead is not NULL,
973	* and no data was available. @a *pcbRead will be set to 0.
974	* @retval VINF_EOF when trying to read __beyond__ the end of the stream and
975	* @a pcbRead is not NULL (it will be set to the number of bytes read,
976	* or 0 if the end of the stream was reached before this call).
977	* When the last byte of the read request is the last byte in the
978	* stream, this status code will not be used. However, VINF_EOF is
979	* returned when attempting to read 0 bytes while standing at the end
980	* of the stream.
981	* @retval VERR_EOF when trying to read __beyond__ the end of the stream and
982	* @a pcbRead is NULL.
983	* @retval VERR_ACCESS_DENIED if the stream is not readable.
984	*
985	* @param hVfsIos The VFS I/O stream handle.
986	* @param pvBuf Where to store the read bytes.
987	* @param cbToRead The number of bytes to read.
988	* @param fBlocking Whether the call is blocking (@c true) or not. If
989	* not, the @a pcbRead parameter must not be NULL.
990	* @param pcbRead Where to always store the number of bytes actually
991	* read. This can be NULL if @a fBlocking is true.
992	* @sa RTVfsFileRead, RTFileRead, RTPipeRead, RTPipeReadBlocking,
993	* RTSocketRead
994	*/
995	RTDECL(int) RTVfsIoStrmRead(RTVFSIOSTREAM hVfsIos, void pvBuf, size_t cbToRead, bool fBlocking, size_t pcbRead);
996
997	/**
998	* Read bytes from the I/O stream, optionally with offset.
999	*
1000	* @returns IPRT status code.
1001	* @retval VINF_SUCCESS and the number of bytes read written to @a pcbRead.
1002	* @retval VINF_TRY_AGAIN if @a fBlocking is @c false, @a pcbRead is not NULL,
1003	* and no data was available. @a *pcbRead will be set to 0.
1004	* @retval VINF_EOF when trying to read __beyond__ the end of the stream and
1005	* @a pcbRead is not NULL (it will be set to the number of bytes read,
1006	* or 0 if the end of the stream was reached before this call).
1007	* When the last byte of the read request is the last byte in the
1008	* stream, this status code will not be used. However, VINF_EOF is
1009	* returned when attempting to read 0 bytes while standing at the end
1010	* of the stream.
1011	* @retval VERR_EOF when trying to read __beyond__ the end of the stream and
1012	* @a pcbRead is NULL.
1013	* @retval VERR_ACCESS_DENIED if the stream is not readable.
1014	*
1015	* @param hVfsIos The VFS I/O stream handle.
1016	* @param off Where to read at, -1 for the current position.
1017	* @param pvBuf Where to store the read bytes.
1018	* @param cbToRead The number of bytes to read.
1019	* @param fBlocking Whether the call is blocking (@c true) or not. If
1020	* not, the @a pcbRead parameter must not be NULL.
1021	* @param pcbRead Where to always store the number of bytes actually
1022	* read. This can be NULL if @a fBlocking is true.
1023	* @sa RTVfsFileRead, RTFileRead, RTPipeRead, RTPipeReadBlocking,
1024	* RTSocketRead
1025	*/
1026	RTDECL(int) RTVfsIoStrmReadAt(RTVFSIOSTREAM hVfsIos, RTFOFF off, void pvBuf, size_t cbToRead, bool fBlocking, size_t pcbRead);
1027
1028	/**
1029	* Reads the remainder of the stream into a memory buffer.
1030	*
1031	* For simplifying string-style processing, the is a zero byte after the
1032	* returned buffer, making sure it can be used as a zero terminated string.
1033	*
1034	* @returns IPRT status code.
1035	* @param hVfsIos The VFS I/O stream handle.
1036	* @param ppvBuf Where to return the buffer. Must pass to
1037	* RTVfsIoStrmReadAllFree for freeing, not RTMemFree!
1038	* @param pcbBuf Where to return the buffer size.
1039	*/
1040	RTDECL(int) RTVfsIoStrmReadAll(RTVFSIOSTREAM hVfsIos, void *ppvBuf, size_t pcbBuf);
1041
1042	/**
1043	* Free memory buffer returned by RTVfsIoStrmReadAll.
1044	*
1045	* @param pvBuf What RTVfsIoStrmReadAll returned.
1046	* @param cbBuf What RTVfsIoStrmReadAll returned.
1047	*/
1048	RTDECL(void) RTVfsIoStrmReadAllFree(void *pvBuf, size_t cbBuf);
1049
1050	/**
1051	* Write bytes to the I/O stream.
1052	*
1053	* @returns IPRT status code.
1054	* @retval VERR_ACCESS_DENIED if the stream is not writable.
1055	*
1056	* @param hVfsIos The VFS I/O stream handle.
1057	* @param pvBuf The bytes to write.
1058	* @param cbToWrite The number of bytes to write.
1059	* @param fBlocking Whether the call is blocking (@c true) or not. If
1060	* not, the @a pcbWritten parameter must not be NULL.
1061	* @param pcbWritten Where to always store the number of bytes actually
1062	* written. This can be NULL if @a fBlocking is true.
1063	* @sa RTVfsFileWrite, RTFileWrite, RTPipeWrite, RTPipeWriteBlocking,
1064	* RTSocketWrite
1065	*/
1066	RTDECL(int) RTVfsIoStrmWrite(RTVFSIOSTREAM hVfsIos, const void pvBuf, size_t cbToWrite, bool fBlocking, size_t pcbWritten);
1067	RTDECL(int) RTVfsIoStrmWriteAt(RTVFSIOSTREAM hVfsIos, RTFOFF off, const void pvBuf, size_t cbToWrite, bool fBlocking, size_t pcbWritten);
1068
1069	/**
1070	* Reads bytes from the I/O stream into a scatter buffer.
1071	*
1072	* @returns IPRT status code.
1073	* @retval VINF_SUCCESS and the number of bytes read written to @a pcbRead.
1074	* @retval VINF_TRY_AGAIN if @a fBlocking is @c false, @a pcbRead is not NULL,
1075	* and no data was available. @a *pcbRead will be set to 0.
1076	* @retval VINF_EOF when trying to read __beyond__ the end of the stream and
1077	* @a pcbRead is not NULL (it will be set to the number of bytes read,
1078	* or 0 if the end of the stream was reached before this call).
1079	* When the last byte of the read request is the last byte in the
1080	* stream, this status code will not be used. However, VINF_EOF is
1081	* returned when attempting to read 0 bytes while standing at the end
1082	* of the stream.
1083	* @retval VERR_EOF when trying to read __beyond__ the end of the stream and
1084	* @a pcbRead is NULL.
1085	* @retval VERR_ACCESS_DENIED if the stream is not readable.
1086	*
1087	* @param hVfsIos The VFS I/O stream handle.
1088	* @param off Where to read at, -1 for the current position.
1089	* @param pSgBuf Pointer to a scatter buffer descriptor. The number
1090	* of bytes described by the segments is what will be
1091	* attemted read.
1092	* @param fBlocking Whether the call is blocking (@c true) or not. If
1093	* not, the @a pcbRead parameter must not be NULL.
1094	* @param pcbRead Where to always store the number of bytes actually
1095	* read. This can be NULL if @a fBlocking is true.
1096	* @sa RTFileSgRead, RTSocketSgRead, RTPipeRead, RTPipeReadBlocking
1097	*/
1098	RTDECL(int) RTVfsIoStrmSgRead(RTVFSIOSTREAM hVfsIos, RTFOFF off, PCRTSGBUF pSgBuf, bool fBlocking, size_t *pcbRead);
1099
1100	/**
1101	* Write bytes to the I/O stream from a gather buffer.
1102	*
1103	* @returns IPRT status code.
1104	* @retval VERR_ACCESS_DENIED if the stream is not writable.
1105	*
1106	* @param hVfsIos The VFS I/O stream handle.
1107	* @param off Where to write at, -1 for the current position.
1108	* @param pSgBuf Pointer to a gather buffer descriptor. The number
1109	* of bytes described by the segments is what will be
1110	* attemted written.
1111	* @param fBlocking Whether the call is blocking (@c true) or not. If
1112	* not, the @a pcbWritten parameter must not be NULL.
1113	* @param pcbWritten Where to always store the number of bytes actually
1114	* written. This can be NULL if @a fBlocking is true.
1115	* @sa RTFileSgWrite, RTSocketSgWrite
1116	*/
1117	RTDECL(int) RTVfsIoStrmSgWrite(RTVFSIOSTREAM hVfsIos, RTFOFF off, PCRTSGBUF pSgBuf, bool fBlocking, size_t *pcbWritten);
1118
1119	/**
1120	* Flush any buffered data to the I/O stream.
1121	*
1122	* @returns IPRT status code.
1123	* @param hVfsIos The VFS I/O stream handle.
1124	* @sa RTVfsFileFlush, RTFileFlush, RTPipeFlush
1125	*/
1126	RTDECL(int) RTVfsIoStrmFlush(RTVFSIOSTREAM hVfsIos);
1127
1128	/**
1129	* Poll for events.
1130	*
1131	* @returns IPRT status code.
1132	* @param hVfsIos The VFS I/O stream handle.
1133	* @param fEvents The events to poll for (RTPOLL_EVT_XXX).
1134	* @param cMillies How long to wait for event to eventuate.
1135	* @param fIntr Whether the wait is interruptible and can return
1136	* VERR_INTERRUPTED (@c true) or if this condition
1137	* should be hidden from the caller (@c false).
1138	* @param pfRetEvents Where to return the event mask.
1139	* @sa RTVfsFilePoll, RTPollSetAdd, RTPoll, RTPollNoResume.
1140	*/
1141	RTDECL(int) RTVfsIoStrmPoll(RTVFSIOSTREAM hVfsIos, uint32_t fEvents, RTMSINTERVAL cMillies, bool fIntr,
1142	uint32_t *pfRetEvents);
1143	/**
1144	* Tells the current I/O stream position.
1145	*
1146	* @returns Zero or higher - where to return the I/O stream offset. Values
1147	* below zero are IPRT status codes (VERR_XXX).
1148	* @param hVfsIos The VFS I/O stream handle.
1149	* @sa RTFileTell
1150	*/
1151	RTDECL(RTFOFF) RTVfsIoStrmTell(RTVFSIOSTREAM hVfsIos);
1152
1153	/**
1154	* Skips @a cb ahead in the stream.
1155	*
1156	* @returns IPRT status code.
1157	* @param hVfsIos The VFS I/O stream handle.
1158	* @param cb The number bytes to skip.
1159	*/
1160	RTDECL(int) RTVfsIoStrmSkip(RTVFSIOSTREAM hVfsIos, RTFOFF cb);
1161
1162	/**
1163	* Fills the stream with @a cb zeros.
1164	*
1165	* @returns IPRT status code.
1166	* @param hVfsIos The VFS I/O stream handle.
1167	* @param cb The number of zero bytes to insert.
1168	*/
1169	RTDECL(int) RTVfsIoStrmZeroFill(RTVFSIOSTREAM hVfsIos, RTFOFF cb);
1170
1171	/**
1172	* Checks if we're at the end of the I/O stream.
1173	*
1174	* @returns true if at EOS, otherwise false.
1175	* @param hVfsIos The VFS I/O stream handle.
1176	*/
1177	RTDECL(bool) RTVfsIoStrmIsAtEnd(RTVFSIOSTREAM hVfsIos);
1178
1179	/**
1180	* Get the RTFILE_O_XXX flags for the I/O stream.
1181	*
1182	* @returns RTFILE_O_XXX, 0 on failure.
1183	* @param hVfsIos The VFS I/O stream handle.
1184	*/
1185	RTDECL(uint64_t) RTVfsIoStrmGetOpenFlags(RTVFSIOSTREAM hVfsIos);
1186
1187	/**
1188	* Process the rest of the stream, checking if it's all valid UTF-8 encoding.
1189	*
1190	* @returns IPRT status code.
1191	*
1192	* @param hVfsIos The VFS I/O stream handle.
1193	* @param fFlags Flags governing the validation, see
1194	* RTVFS_VALIDATE_UTF8_XXX.
1195	* @param poffError Where to return the error offset. Optional.
1196	*/
1197	RTDECL(int) RTVfsIoStrmValidateUtf8Encoding(RTVFSIOSTREAM hVfsIos, uint32_t fFlags, PRTFOFF poffError);
1198
1199	/** @defgroup RTVFS_VALIDATE_UTF8_XXX RTVfsIoStrmValidateUtf8Encoding flags.
1200	* @{ */
1201	/** The text must not contain any null terminator codepoints. */
1202	#define RTVFS_VALIDATE_UTF8_NO_NULL RT_BIT_32(0)
1203	/** The codepoints must be in the range covered by RTC-3629. */
1204	#define RTVFS_VALIDATE_UTF8_BY_RTC_3629 RT_BIT_32(1)
1205	/** Mask of valid flags. */
1206	#define RTVFS_VALIDATE_UTF8_VALID_MASK UINT32_C(0x00000003)
1207	/** @} */
1208
1209	/** @} */
1210
1211
1212	/** @defgroup grp_vfs_file VFS File API
1213	* @{
1214	*/
1215	RTDECL(int) RTVfsFileOpen(RTVFS hVfs, const char *pszFilename, uint64_t fOpen, PRTVFSFILE phVfsFile);
1216
1217	/**
1218	* Create a VFS file handle from a standard IPRT file handle (RTFILE).
1219	*
1220	* @returns IPRT status code.
1221	* @param hFile The standard IPRT file handle.
1222	* @param fOpen The flags the handle was opened with. Pass 0 to
1223	* have these detected.
1224	* @param fLeaveOpen Whether to leave the handle open when the VFS file
1225	* is released, or to close it (@c false).
1226	* @param phVfsFile Where to return the VFS file handle.
1227	*/
1228	RTDECL(int) RTVfsFileFromRTFile(RTFILE hFile, uint64_t fOpen, bool fLeaveOpen, PRTVFSFILE phVfsFile);
1229	RTDECL(RTHCUINTPTR) RTVfsFileToNative(RTFILE hVfsFile);
1230
1231	/**
1232	* Convenience function combining RTFileOpen with RTVfsFileFromRTFile.
1233	*
1234	* @returns IPRT status code.
1235	* @param pszFilename The path to the file in the normal file system.
1236	* @param fOpen The flags to pass to RTFileOpen when opening the
1237	* file, i.e. RTFILE_O_XXX.
1238	* @param phVfsFile Where to return the VFS file handle.
1239	*/
1240	RTDECL(int) RTVfsFileOpenNormal(const char *pszFilename, uint64_t fOpen, PRTVFSFILE phVfsFile);
1241
1242	/**
1243	* Convert the VFS file handle to a VFS I/O stream handle.
1244	*
1245	* @returns The VFS I/O stream handle on success, this must be released.
1246	* NIL_RTVFSIOSTREAM if the file handle is invalid.
1247	* @param hVfsFile The VFS file handle.
1248	* @sa RTVfsIoStrmToFile
1249	*/
1250	RTDECL(RTVFSIOSTREAM) RTVfsFileToIoStream(RTVFSFILE hVfsFile);
1251
1252	/**
1253	* Retains a reference to the VFS file handle.
1254	*
1255	* @returns New reference count on success, UINT32_MAX on failure.
1256	* @param hVfsFile The VFS file handle.
1257	*/
1258	RTDECL(uint32_t) RTVfsFileRetain(RTVFSFILE hVfsFile);
1259	RTDECL(uint32_t) RTVfsFileRetainDebug(RTVFSFILE hVfsFile, RT_SRC_POS_DECL);
1260
1261	/**
1262	* Releases a reference to the VFS file handle.
1263	*
1264	* @returns New reference count on success (0 if closed), UINT32_MAX on failure.
1265	* @param hVfsFile The VFS file handle.
1266	*/
1267	RTDECL(uint32_t) RTVfsFileRelease(RTVFSFILE hVfsFile);
1268
1269	/**
1270	* Query information about the object.
1271	*
1272	* @returns IPRT status code.
1273	* @retval VERR_NOT_SUPPORTED if the @a enmAddAttr value is not handled by the
1274	* implementation.
1275	*
1276	* @param hVfsFile The VFS file handle.
1277	* @param pObjInfo Where to return the info.
1278	* @param enmAddAttr Which additional attributes should be retrieved.
1279	* @sa RTVfsObjQueryInfo, RTVfsFsStrmQueryInfo, RTVfsDirQueryInfo,
1280	* RTVfsIoStrmQueryInfo, RTVfsFileQueryInfo, RTFileQueryInfo,
1281	* RTPathQueryInfo.
1282	*/
1283	RTDECL(int) RTVfsFileQueryInfo(RTVFSFILE hVfsFile, PRTFSOBJINFO pObjInfo, RTFSOBJATTRADD enmAddAttr);
1284
1285	/**
1286	* Read bytes from the file at the current position.
1287	*
1288	* @returns IPRT status code.
1289	* @retval VINF_SUCCESS and the number of bytes read written to @a pcbRead.
1290	* @retval VINF_EOF when trying to read __beyond__ the end of the file and
1291	* @a pcbRead is not NULL (it will be set to the number of bytes read,
1292	* or 0 if the end of the file was reached before this call).
1293	* When the last byte of the read request is the last byte in the
1294	* file, this status code will not be used. However, VINF_EOF is
1295	* returned when attempting to read 0 bytes while standing at the end
1296	* of the file.
1297	* @retval VERR_EOF when trying to read __beyond__ the end of the file and
1298	* @a pcbRead is NULL.
1299	* @retval VERR_ACCESS_DENIED if the file is not readable.
1300	*
1301	* @param hVfsFile The VFS file handle.
1302	* @param pvBuf Where to store the read bytes.
1303	* @param cbToRead The number of bytes to read.
1304	* @param pcbRead Where to always store the number of bytes actually
1305	* read. Optional.
1306	* @sa RTVfsIoStrmRead, RTFileRead, RTPipeRead, RTPipeReadBlocking,
1307	* RTSocketRead
1308	*/
1309	RTDECL(int) RTVfsFileRead(RTVFSFILE hVfsFile, void pvBuf, size_t cbToRead, size_t pcbRead);
1310	RTDECL(int) RTVfsFileReadAt(RTVFSFILE hVfsFile, RTFOFF off, void pvBuf, size_t cbToRead, size_t pcbRead);
1311
1312	/**
1313	* Write bytes to the file at the current position.
1314	*
1315	* @returns IPRT status code.
1316	* @retval VERR_ACCESS_DENIED if the file is not writable.
1317	*
1318	* @param hVfsFile The VFS file handle.
1319	* @param pvBuf The bytes to write.
1320	* @param cbToWrite The number of bytes to write.
1321	* @param pcbWritten Where to always store the number of bytes actually
1322	* written. This can be NULL.
1323	* @sa RTVfsIoStrmRead, RTFileWrite, RTPipeWrite, RTPipeWriteBlocking,
1324	* RTSocketWrite
1325	*/
1326	RTDECL(int) RTVfsFileWrite(RTVFSFILE hVfsFile, const void pvBuf, size_t cbToWrite, size_t pcbWritten);
1327	RTDECL(int) RTVfsFileWriteAt(RTVFSFILE hVfsFile, RTFOFF off, const void pvBuf, size_t cbToWrite, size_t pcbWritten);
1328
1329
1330	/**
1331	* Reads bytes from the file into a scatter buffer.
1332	*
1333	* @returns IPRT status code.
1334	* @retval VINF_SUCCESS and the number of bytes read written to @a pcbRead.
1335	* @retval VINF_TRY_AGAIN if @a fBlocking is @c false, @a pcbRead is not NULL,
1336	* and no data was available. @a *pcbRead will be set to 0.
1337	* @retval VINF_EOF when trying to read __beyond__ the end of the stream and
1338	* @a pcbRead is not NULL (it will be set to the number of bytes read,
1339	* or 0 if the end of the stream was reached before this call).
1340	* When the last byte of the read request is the last byte in the
1341	* stream, this status code will not be used. However, VINF_EOF is
1342	* returned when attempting to read 0 bytes while standing at the end
1343	* of the stream.
1344	* @retval VERR_EOF when trying to read __beyond__ the end of the stream and
1345	* @a pcbRead is NULL.
1346	* @retval VERR_ACCESS_DENIED if the stream is not readable.
1347	*
1348	* @param hVfsFile The VFS file handle.
1349	* @param off Where to read at, -1 for the current position.
1350	* @param pSgBuf Pointer to a scatter buffer descriptor. The number
1351	* of bytes described by the segments is what will be
1352	* attemted read.
1353	* @param fBlocking Whether the call is blocking (@c true) or not. If
1354	* not, the @a pcbRead parameter must not be NULL.
1355	* @param pcbRead Where to always store the number of bytes actually
1356	* read. This can be NULL if @a fBlocking is true.
1357	* @sa RTFileSgRead, RTSocketSgRead, RTPipeRead, RTPipeReadBlocking
1358	*/
1359	RTDECL(int) RTVfsFileSgRead(RTVFSFILE hVfsFile, RTFOFF off, PCRTSGBUF pSgBuf, bool fBlocking, size_t *pcbRead);
1360
1361	/**
1362	* Write bytes to the file from a gather buffer.
1363	*
1364	* @returns IPRT status code.
1365	* @retval VERR_ACCESS_DENIED if the stream is not writable.
1366	*
1367	* @param hVfsFile The VFS file handle.
1368	* @param off Where to write at, -1 for the current position.
1369	* @param pSgBuf Pointer to a gather buffer descriptor. The number
1370	* of bytes described by the segments is what will be
1371	* attemted written.
1372	* @param fBlocking Whether the call is blocking (@c true) or not. If
1373	* not, the @a pcbWritten parameter must not be NULL.
1374	* @param pcbWritten Where to always store the number of bytes actually
1375	* written. This can be NULL if @a fBlocking is true.
1376	* @sa RTFileSgWrite, RTSocketSgWrite
1377	*/
1378	RTDECL(int) RTVfsFileSgWrite(RTVFSFILE hVfsFile, RTFOFF off, PCRTSGBUF pSgBuf, bool fBlocking, size_t *pcbWritten);
1379
1380	/**
1381	* Flush any buffered data to the file.
1382	*
1383	* @returns IPRT status code.
1384	* @param hVfsFile The VFS file handle.
1385	* @sa RTVfsIoStrmFlush, RTFileFlush, RTPipeFlush
1386	*/
1387	RTDECL(int) RTVfsFileFlush(RTVFSFILE hVfsFile);
1388
1389	/**
1390	* Poll for events.
1391	*
1392	* @returns IPRT status code.
1393	* @param hVfsFile The VFS file handle.
1394	* @param fEvents The events to poll for (RTPOLL_EVT_XXX).
1395	* @param cMillies How long to wait for event to eventuate.
1396	* @param fIntr Whether the wait is interruptible and can return
1397	* VERR_INTERRUPTED (@c true) or if this condition
1398	* should be hidden from the caller (@c false).
1399	* @param pfRetEvents Where to return the event mask.
1400	* @sa RTVfsIoStrmPoll, RTPollSetAdd, RTPoll, RTPollNoResume.
1401	*/
1402	RTDECL(RTFOFF) RTVfsFilePoll(RTVFSFILE hVfsFile, uint32_t fEvents, RTMSINTERVAL cMillies, bool fIntr,
1403	uint32_t *pfRetEvents);
1404
1405	/**
1406	* Tells the current file position.
1407	*
1408	* @returns Zero or higher - where to return the file offset. Values
1409	* below zero are IPRT status codes (VERR_XXX).
1410	* @param hVfsFile The VFS file handle.
1411	* @sa RTFileTell, RTVfsIoStrmTell.
1412	*/
1413	RTDECL(RTFOFF) RTVfsFileTell(RTVFSFILE hVfsFile);
1414
1415	/**
1416	* Changes the current read/write position of a file.
1417	*
1418	* @returns IPRT status code.
1419	*
1420	* @param hVfsFile The VFS file handle.
1421	* @param offSeek The seek offset.
1422	* @param uMethod The seek emthod.
1423	* @param poffActual Where to optionally return the new file offset.
1424	*
1425	* @sa RTFileSeek
1426	*/
1427	RTDECL(int) RTVfsFileSeek(RTVFSFILE hVfsFile, RTFOFF offSeek, uint32_t uMethod, uint64_t *poffActual);
1428
1429	/**
1430	* Sets the size of a file.
1431	*
1432	* This may also be used for preallocating space
1433	* (RTVFSFILE_SIZE_F_PREALLOC_KEEP_SIZE).
1434	*
1435	* @returns IPRT status code.
1436	* @retval VERR_ACCESS_DENIED if handle isn't writable.
1437	* @retval VERR_WRITE_PROTECT if read-only file system.
1438	* @retval VERR_FILE_TOO_BIG if cbSize is larger than what the file system can
1439	* theoretically deal with.
1440	* @retval VERR_DISK_FULL if the file system if full.
1441	* @retval VERR_NOT_SUPPORTED if fFlags indicates some operation that's not
1442	* supported by the file system / host operating system.
1443	*
1444	* @param hVfsFile The VFS file handle.
1445	* @param cbSize The new file size.
1446	* @param fFlags RTVFSFILE_SIZE_F_NORMAL, RTVFSFILE_SIZE_F_GROW, or
1447	* RTVFSFILE_SIZE_F_GROW_KEEP_SIZE.
1448	*
1449	* @sa RTFileSetSize, RTFileSetAllocationSize
1450	*/
1451	RTDECL(int) RTVfsFileSetSize(RTVFSFILE hVfsFile, uint64_t cbSize, uint32_t fFlags);
1452
1453	/** @name RTVFSFILE_SIZE_F_XXX - RTVfsFileSetSize flags.
1454	* @{ */
1455	/** Normal truncate or grow (zero'ed) like RTFileSetSize . */
1456	#define RTVFSFILE_SIZE_F_NORMAL UINT32_C(0x00000001)
1457	/** Only grow the file, ignore call if cbSize would trunacte the file.
1458	* This is what RTFileSetAllocationSize does by default. */
1459	#define RTVFSFILE_SIZE_F_GROW UINT32_C(0x00000002)
1460	/** Only grow the file, ignore call if cbSize would trunacte the file.
1461	* This is what RTFileSetAllocationSize does by default. */
1462	#define RTVFSFILE_SIZE_F_GROW_KEEP_SIZE UINT32_C(0x00000003)
1463	/** Action mask. */
1464	#define RTVFSFILE_SIZE_F_ACTION_MASK UINT32_C(0x00000003)
1465	/** Validate the flags.
1466	* Will reference @a a_fFlags more than once. */
1467	#define RTVFSFILE_SIZE_F_IS_VALID(a_fFlags) \
1468	( !((a_fFlags) & ~RTVFSFILE_SIZE_F_ACTION_MASK) && ((a_fFlags) & RTVFSFILE_SIZE_F_ACTION_MASK) != 0 )
1469	/** @} */
1470
1471
1472	/** Mask of valid flags. */
1473	#define RTFILE_ALLOC_SIZE_F_VALID (RTFILE_ALLOC_SIZE_F_KEEP_SIZE)
1474	/** @} */
1475
1476
1477	RTDECL(int) RTVfsFileGetSize(RTVFSFILE hVfsFile, uint64_t *pcbSize);
1478	RTDECL(RTFOFF) RTVfsFileGetMaxSize(RTVFSFILE hVfsFile);
1479	RTDECL(int) RTVfsFileQueryMaxSize(RTVFSFILE hVfsFile, uint64_t *pcbMax);
1480
1481	/**
1482	* Get the RTFILE_O_XXX flags for the I/O stream.
1483	*
1484	* @returns RTFILE_O_XXX, 0 on failure.
1485	* @param hVfsFile The VFS file handle.
1486	*/
1487	RTDECL(uint64_t) RTVfsFileGetOpenFlags(RTVFSFILE hVfsFile);
1488
1489	/** @} */
1490
1491
1492	#ifdef DEBUG
1493	# undef RTVfsRetain
1494	# define RTVfsRetain(hVfs) RTVfsRetainDebug(hVfs, RT_SRC_POS)
1495	# undef RTVfsObjRetain
1496	# define RTVfsObjRetain(hVfsObj) RTVfsObjRetainDebug(hVfsObj, RT_SRC_POS)
1497	# undef RTVfsDirRetain
1498	# define RTVfsDirRetain(hVfsDir) RTVfsDirRetainDebug(hVfsDir, RT_SRC_POS)
1499	# undef RTVfsFileRetain
1500	# define RTVfsFileRetain(hVfsFile) RTVfsFileRetainDebug(hVfsFile, RT_SRC_POS)
1501	# undef RTVfsIoStrmRetain
1502	# define RTVfsIoStrmRetain(hVfsIos) RTVfsIoStrmRetainDebug(hVfsIos, RT_SRC_POS)
1503	# undef RTVfsFsStrmRetain
1504	# define RTVfsFsStrmRetain(hVfsFss) RTVfsFsStrmRetainDebug(hVfsFss, RT_SRC_POS)
1505	#endif
1506
1507
1508
1509	/** @defgroup grp_vfs_misc VFS Miscellaneous
1510	* @{
1511	*/
1512
1513	/**
1514	* Memorizes the I/O stream as a file backed by memory.
1515	*
1516	* @returns IPRT status code.
1517	*
1518	* @param hVfsIos The VFS I/O stream to memorize. This will be read
1519	* to the end on success, on failure its position is
1520	* undefined.
1521	* @param fFlags A combination of RTFILE_O_READ and RTFILE_O_WRITE.
1522	* @param phVfsFile Where to return the handle to the memory file on
1523	* success.
1524	*/
1525	RTDECL(int) RTVfsMemorizeIoStreamAsFile(RTVFSIOSTREAM hVfsIos, uint32_t fFlags, PRTVFSFILE phVfsFile);
1526
1527	/**
1528	* Creates a VFS file from a memory buffer.
1529	*
1530	* @returns IPRT status code.
1531	*
1532	* @param fFlags A combination of RTFILE_O_READ and RTFILE_O_WRITE.
1533	* @param pvBuf The buffer. This will be copied and not referenced
1534	* after this function returns.
1535	* @param cbBuf The buffer size.
1536	* @param phVfsFile Where to return the handle to the memory file on
1537	* success.
1538	*/
1539	RTDECL(int) RTVfsFileFromBuffer(uint32_t fFlags, void const *pvBuf, size_t cbBuf, PRTVFSFILE phVfsFile);
1540
1541	/**
1542	* Creates a memory backed VFS file object for read and write.
1543	*
1544	* @returns IPRT status code.
1545	*
1546	* @param hVfsIos The VFS I/O stream to memorize. This will be read
1547	* to the end on success, on failure its position is
1548	* undefined.
1549	* @param cbEstimate The estimated file size.
1550	* @param phVfsFile Where to return the handle to the memory file on
1551	* success.
1552	* @sa RTVfsMemIoStrmCreate
1553	*/
1554	RTDECL(int) RTVfsMemFileCreate(RTVFSIOSTREAM hVfsIos, size_t cbEstimate, PRTVFSFILE phVfsFile);
1555
1556	/**
1557	* Creates a memory backed VFS file object for read and write.
1558	*
1559	* @returns IPRT status code.
1560	*
1561	* @param hVfsIos The VFS I/O stream to memorize. This will be read
1562	* to the end on success, on failure its position is
1563	* undefined.
1564	* @param cbEstimate The estimated file size.
1565	* @param phVfsIos Where to return the handle to the memory I/O stream
1566	* on success.
1567	* @sa RTVfsMemFileCreate
1568	*/
1569	RTDECL(int) RTVfsMemIoStrmCreate(RTVFSIOSTREAM hVfsIos, size_t cbEstimate, PRTVFSIOSTREAM phVfsIos);
1570
1571	/**
1572	* Pumps data from one I/O stream to another.
1573	*
1574	* The data is read in chunks from @a hVfsIosSrc and written to @a hVfsIosDst
1575	* until @a hVfsIosSrc indicates end of stream.
1576	*
1577	* @returns IPRT status code
1578	*
1579	* @param hVfsIosSrc The input stream.
1580	* @param hVfsIosDst The output stream.
1581	* @param cbBufHint Hints at a good temporary buffer size, pass 0 if
1582	* clueless.
1583	*/
1584	RTDECL(int) RTVfsUtilPumpIoStreams(RTVFSIOSTREAM hVfsIosSrc, RTVFSIOSTREAM hVfsIosDst, size_t cbBufHint);
1585
1586
1587	/**
1588	* Creates a progress wrapper for an I/O stream.
1589	*
1590	* @returns IRPT status code.
1591	* @param hVfsIos The I/O stream to wrap.
1592	* @param pfnProgress The progress callback. The return code is
1593	* ignored by default, see
1594	* RTVFSPROGRESS_F_CANCELABLE.
1595	* @param pvUser The user argument to @a pfnProgress.
1596	* @param fFlags RTVFSPROGRESS_F_XXX
1597	* @param cbExpectedRead The expected number of bytes read.
1598	* @param cbExpectedWritten The execpted number of bytes written.
1599	* @param phVfsIos Where to return the I/O stream handle.
1600	*/
1601	RTDECL(int) RTVfsCreateProgressForIoStream(RTVFSIOSTREAM hVfsIos, PFNRTPROGRESS pfnProgress, void *pvUser, uint32_t fFlags,
1602	uint64_t cbExpectedRead, uint64_t cbExpectedWritten, PRTVFSIOSTREAM phVfsIos);
1603
1604	/**
1605	* Creates a progress wrapper for a file stream.
1606	*
1607	* @returns IRPT status code.
1608	* @param hVfsFile The file to wrap.
1609	* @param pfnProgress The progress callback. The return code is
1610	* ignored by default, see
1611	* RTVFSPROGRESS_F_CANCELABLE.
1612	* @param pvUser The user argument to @a pfnProgress.
1613	* @param fFlags RTVFSPROGRESS_F_XXX
1614	* @param cbExpectedRead The expected number of bytes read.
1615	* @param cbExpectedWritten The execpted number of bytes written.
1616	* @param phVfsFile Where to return the file handle.
1617	*/
1618	RTDECL(int) RTVfsCreateProgressForFile(RTVFSFILE hVfsFile, PFNRTPROGRESS pfnProgress, void *pvUser, uint32_t fFlags,
1619	uint64_t cbExpectedRead, uint64_t cbExpectedWritten, PRTVFSFILE phVfsFile);
1620
1621	/** @name RTVFSPROGRESS_F_XXX - Flags for RTVfsCreateProcessForIoStream and
1622	* RTVfsCreateProcessForFile.
1623	* @{ */
1624	/** Cancel if the callback returns a failure status code.
1625	* This isn't default behavior because the cancelation is delayed one I/O
1626	* operation in most cases and it's uncertain how the VFS user will handle the
1627	* cancellation status code. */
1628	#define RTVFSPROGRESS_F_CANCELABLE RT_BIT_32(0)
1629	/** Account forward seeks as reads. */
1630	#define RTVFSPROGRESS_F_FORWARD_SEEK_AS_READ RT_BIT_32(1)
1631	/** Account fprward seeks as writes. */
1632	#define RTVFSPROGRESS_F_FORWARD_SEEK_AS_WRITE RT_BIT_32(2)
1633	/** Valid bits. */
1634	#define RTVFSPROGRESS_F_VALID_MASK UINT32_C(0x00000007)
1635	/** @} */
1636
1637
1638	/**
1639	* Create an I/O stream instance performing simple sequential read-ahead.
1640	*
1641	* @returns IPRT status code.
1642	* @param hVfsIos The input stream to perform read ahead on. If this is
1643	* actually for a file object, the returned I/O stream
1644	* handle can also be cast to a file handle.
1645	* @param fFlags Flags reserved for future use, MBZ.
1646	* @param cBuffers How many read ahead buffers to use. Specify 0 for
1647	* default value.
1648	* @param cbBuffer The size of each read ahead buffer. Specify 0 for
1649	* default value.
1650	* @param phVfsIos Where to return the read ahead I/O stream handle.
1651	*
1652	* @remarks Careful using this on a message pipe or socket. The reads are
1653	* performed in blocked mode and it may be host and/or implementation
1654	* dependent whether they will return ready data immediate or wait
1655	* until there's a whole @a cbBuffer (or default) worth ready.
1656	*
1657	* @sa RTVfsCreateReadAheadForFile
1658	*/
1659	RTDECL(int) RTVfsCreateReadAheadForIoStream(RTVFSIOSTREAM hVfsIos, uint32_t fFlags, uint32_t cBuffers, uint32_t cbBuffer,
1660	PRTVFSIOSTREAM phVfsIos);
1661
1662	/**
1663	* Create an I/O stream instance performing simple sequential read-ahead.
1664	*
1665	* @returns IPRT status code.
1666	* @param hVfsFile The input file to perform read ahead on.
1667	* @param fFlags Flags reserved for future use, MBZ.
1668	* @param cBuffers How many read ahead buffers to use. Specify 0 for
1669	* default value.
1670	* @param cbBuffer The size of each read ahead buffer. Specify 0 for
1671	* default value.
1672	* @param phVfsFile Where to return the read ahead file handle.
1673	* @sa RTVfsCreateReadAheadForIoStream
1674	*/
1675	RTDECL(int) RTVfsCreateReadAheadForFile(RTVFSFILE hVfsFile, uint32_t fFlags, uint32_t cBuffers, uint32_t cbBuffer,
1676	PRTVFSFILE phVfsFile);
1677
1678
1679	/**
1680	* Create a file system stream for writing to a directory.
1681	*
1682	* This is just supposed to be a drop in replacement for the TAR creator stream
1683	* that instead puts the files and stuff in a directory instead of a TAR
1684	* archive. In addition, it has an undo feature for simplying cleaning up after
1685	* a botched run
1686	*
1687	* @returns IPRT status code.
1688	* @param hVfsBaseDir The base directory.
1689	* @param fFlags RTVFSFSS2DIR_F_XXX
1690	* @param phVfsFss Where to return the FSS handle.
1691	* @sa RTVfsFsStrmToNormalDir, RTVfsFsStrmToDirUndo
1692	*/
1693	RTDECL(int) RTVfsFsStrmToDir(RTVFSDIR hVfsBaseDir, uint32_t fFlags, PRTVFSFSSTREAM phVfsFss);
1694
1695	/**
1696	* Create a file system stream for writing to a normal directory.
1697	*
1698	* This is just supposed to be a drop in replacement for the TAR creator stream
1699	* that instead puts the files and stuff in a directory instead of a TAR
1700	* archive. In addition, it has an undo feature for simplying cleaning up after
1701	* a botched run
1702	*
1703	* @returns IPRT status code.
1704	* @param pszBaseDir The base directory. Must exist.
1705	* @param fFlags RTVFSFSS2DIR_F_XXX
1706	* @param phVfsFss Where to return the FSS handle.
1707	* @sa RTVfsFsStrmToDir, RTVfsFsStrmToDirUndo
1708	*/
1709	RTDECL(int) RTVfsFsStrmToNormalDir(const char *pszBaseDir, uint32_t fFlags, PRTVFSFSSTREAM phVfsFss);
1710
1711	/** @name RTVFSFSS2DIR_F_XXX - Flags for RTVfsFsStrmToNormalDir
1712	* @{ */
1713	/** Overwrite existing files (default is to not overwrite anything). */
1714	#define RTVFSFSS2DIR_F_OVERWRITE_FILES RT_BIT_32(0)
1715	/** Valid bits. */
1716	#define RTVFSFSS2DIR_F_VALID_MASK UINT32_C(0x00000001)
1717	/** @} */
1718
1719	/**
1720	* Deletes files, directories, symlinks and stuff created by a FSS returned by
1721	* RTVfsFsStrmToNormalDir or RTVfsFsStrmToDir.
1722	*
1723	* @returns IPRT status code.
1724	* @param hVfsFss The write-to-directory FSS handle.
1725	*/
1726	RTDECL(int) RTVfsFsStrmToDirUndo(RTVFSFSSTREAM hVfsFss);
1727
1728
1729
1730	/** @} */
1731
1732
1733	/** @defgroup grp_rt_vfs_chain VFS Chains
1734	*
1735	* VFS chains is for doing pipe like things with VFS objects from the command
1736	* line. Imagine you want to cat the readme.gz of an ISO you could do
1737	* something like:
1738	* RTCat :iprtvfs:file(stdfile,live.iso)\|vfs(isofs)\|iso(open,readme.gz)\|ios(gunzip)
1739	* or
1740	* RTCat :iprtvfs:file(stdfile,live.iso)\|ios(isofs,readme.gz)\|ios(gunzip)
1741	*
1742	* Or say you want to read the README.TXT on a floppy image:
1743	* RTCat :iprtvfs:file(stdfile,floppy.img,r)\|vfs(fat)\|ios(open,README.TXT)
1744	* or
1745	* RTCat :iprtvfs:file(stdfile,floppy.img,r)\|vfs(fat)\|README.TXT
1746	*
1747	* Or in the other direction, you want to write a STUFF.TGZ file to the above
1748	* floppy image, using a lazy writer thread for compressing the data:
1749	* RTTar cf :iprtvfs:file(stdfile,floppy.img,rw)\|ios(fat,STUFF.TGZ)\|ios(gzip)\|ios(push) .
1750	*
1751	*
1752	* A bit more formally:
1753	* :iprtvfs:{type}({provider}[,provider-args])[{separator}{type}...][{separator}{path}]
1754	*
1755	* The @c type refers to VFS object that should be created by the @c provider.
1756	* Valid types:
1757	* - vfs: A virtual file system (volume).
1758	* - fss: A file system stream (e.g. tar).
1759	* - ios: An I/O stream.
1760	* - file: A file.
1761	* - dir: A directory.
1762	* - sym: A symbolic link (not sure how useful this is).
1763	*
1764	* The @c provider refers to registered chain element providers (see
1765	* RTVFSCHAINELEMENTREG for how that works internally). These are asked to
1766	* create a VFS object of the specified type using the given arguments (if any).
1767	* Default providers:
1768	* - std: Standard file, directory and file system.
1769	* - open: Opens a file, I/O stream or directory in a vfs or directory object.
1770	* - pull: Read-ahead buffering thread on file or I/O stream.
1771	* - push: Lazy-writer buffering thread on file or I/O stream.
1772	* - gzip: Compresses an I/O stream.
1773	* - gunzip: Decompresses an I/O stream.
1774	* - fat: FAT file system accessor.
1775	* - isofs: ISOFS file system accessor.
1776	*
1777	* As element @c separator we allow both colon (':') and the pipe character
1778	* ('\|'). The latter the conventional one, but since it's inconvenient on the
1779	* command line, colon is provided as an alternative.
1780	*
1781	* In the final element we allow a simple @a path to be specified instead of the
1782	* type-provider-arguments stuff. The previous object must be a directory, file
1783	* system or file system stream. The application will determin exactly which
1784	* operation or operations which will be performed.
1785	*
1786	* @{
1787	*/
1788
1789	/** The path prefix used to identify an VFS chain specification. */
1790	#define RTVFSCHAIN_SPEC_PREFIX ":iprtvfs:"
1791
1792	RTDECL(int) RTVfsChainOpenVfs(const char pszSpec, PRTVFS phVfs, uint32_t poffError, PRTERRINFO pErrInfo);
1793	RTDECL(int) RTVfsChainOpenFsStream(const char pszSpec, PRTVFSFSSTREAM phVfsFss, uint32_t poffError, PRTERRINFO pErrInfo);
1794
1795	/**
1796	* Opens any kind of file system object.
1797	*
1798	* @returns IPRT status code.
1799	* @param pszSpec The VFS chain specification or plain path.
1800	* @param fFileOpen RTFILE_O_XXX flags.
1801	* @param fObjFlags More flags: RTVFSOBJ_F_XXX, RTPATH_F_XXX.
1802	* @param phVfsObj Where to return the handle to the opened object.
1803	* @param poffError Where to on error return an offset into @a pszSpec
1804	* of what cause the error. Optional.
1805	* @param pErrInfo Where to return additional error information.
1806	* Optional.
1807	*/
1808	RTDECL(int) RTVfsChainOpenObj(const char *pszSpec, uint64_t fFileOpen, uint32_t fObjFlags,
1809	PRTVFSOBJ phVfsObj, uint32_t *poffError, PRTERRINFO pErrInfo);
1810
1811	RTDECL(int) RTVfsChainOpenDir(const char pszSpec, uint32_t fOpen, PRTVFSDIR phVfsDir, uint32_t poffError, PRTERRINFO pErrInfo);
1812	RTDECL(int) RTVfsChainOpenParentDir(const char pszSpec, uint32_t fOpen, PRTVFSDIR phVfsDir, const char *ppszChild,
1813	uint32_t *poffError, PRTERRINFO pErrInfo);
1814	RTDECL(int) RTVfsChainOpenFile(const char pszSpec, uint64_t fOpen, PRTVFSFILE phVfsFile, uint32_t poffError, PRTERRINFO pErrInfo);
1815	RTDECL(int) RTVfsChainOpenIoStream(const char pszSpec, uint64_t fOpen, PRTVFSIOSTREAM phVfsIos, uint32_t poffError, PRTERRINFO pErrInfo);
1816	RTDECL(int) RTVfsChainOpenSymlink(const char pszSpec, PRTVFSSYMLINK phVfsSym, uint32_t poffError, PRTERRINFO pErrInfo);
1817
1818	RTDECL(int) RTVfsChainQueryInfo(const char *pszSpec, PRTFSOBJINFO pObjInfo, RTFSOBJATTRADD enmAdditionalAttribs,
1819	uint32_t fFlags, uint32_t *poffError, PRTERRINFO pErrInfo);
1820
1821	/**
1822	* Tests if the given string is a chain specification or not.
1823	*
1824	* @returns true if it is, false if it isn't.
1825	* @param pszSpec The alleged chain spec.
1826	*/
1827	RTDECL(bool) RTVfsChainIsSpec(const char *pszSpec);
1828
1829	/**
1830	* Queries the path from the final element.
1831	*
1832	* @returns IPRT status code.
1833	* @retval VERR_VFS_CHAIN_NOT_PATH_ONLY if the final element isn't just a
1834	* simple path.
1835	* @param pszSpec The chain spec.
1836	* @param ppszFinalPath Where to return a copy of the final path on success.
1837	* Call RTStrFree when done.
1838	* @param poffError Where to on error return an offset into @a pszSpec
1839	* of what cause the error. Optional.
1840	*
1841	*/
1842	RTDECL(int) RTVfsChainQueryFinalPath(const char pszSpec, char ppszFinalPath, uint32_t poffError);
1843
1844	/**
1845	* Splits the given chain spec into a final path and the preceeding spec.
1846	*
1847	* This works on plain paths too.
1848	*
1849	* @returns IPRT status code.
1850	* @param pszSpec The chain spec to split. This will be modified!
1851	* @param ppszSpec Where to return the pointer to the chain spec part.
1852	* This is set to NULL if it's a plain path or a chain
1853	* spec with only a final-path element.
1854	* @param ppszFinalPath Where to return the pointer to the final path. This
1855	* is set to NULL if no final path.
1856	* @param poffError Where to on error return an offset into @a pszSpec
1857	* of what cause the error. Optional.
1858	*/
1859	RTDECL(int) RTVfsChainSplitOffFinalPath(char pszSpec, char ppszSpec, char ppszFinalPath, uint32_t poffError);
1860
1861	/**
1862	* Common code for reporting errors of a RTVfsChainOpen* API.
1863	*
1864	* @param pszFunction The API called.
1865	* @param pszSpec The VFS chain specification or file path passed to the.
1866	* @param rc The return code.
1867	* @param offError The error offset value returned (0 if not captured).
1868	* @param pErrInfo Additional error information. Optional.
1869	*
1870	* @sa RTVfsChainMsgErrorExitFailure
1871	* @sa RTVfsChainOpenVfs, RTVfsChainOpenFsStream, RTVfsChainOpenDir,
1872	* RTVfsChainOpenFile, RTVfsChainOpenIoStream, RTVfsChainOpenSymlink
1873	*/
1874	RTDECL(void) RTVfsChainMsgError(const char pszFunction, const char pszSpec, int rc, uint32_t offError, PRTERRINFO pErrInfo);
1875
1876	/**
1877	* Common code for reporting errors of a RTVfsChainOpen* API.
1878	*
1879	* @returns RTEXITCODE_FAILURE
1880	*
1881	* @param pszFunction The API called.
1882	* @param pszSpec The VFS chain specification or file path passed to the.
1883	* @param rc The return code.
1884	* @param offError The error offset value returned (0 if not captured).
1885	* @param pErrInfo Additional error information. Optional.
1886	*
1887	* @sa RTVfsChainMsgError
1888	* @sa RTVfsChainOpenVfs, RTVfsChainOpenFsStream, RTVfsChainOpenDir,
1889	* RTVfsChainOpenFile, RTVfsChainOpenIoStream, RTVfsChainOpenSymlink
1890	*/
1891	RTDECL(RTEXITCODE) RTVfsChainMsgErrorExitFailure(const char pszFunction, const char pszSpec,
1892	int rc, uint32_t offError, PRTERRINFO pErrInfo);
1893
1894
1895	/** @} */
1896
1897
1898	/** @} */
1899
1900	RT_C_DECLS_END
1901
1902	#endif /* !IPRT_INCLUDED_vfs_h */
1903

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

source: vbox/trunk/include/iprt/vfs.h@ 80518

Download in other formats: