vfs.h@ 106061

Last change on this file since 106061 was 106061, checked in by vboxsync, 2 months ago
Copyright year updates by scm.
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 82.6 KB

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

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

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

Download in other formats: