vfs.h@ 86716

Last change on this file since 86716 was 84762, checked in by vboxsync, 5 years ago
IPRT/vfs: Docs nit.
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 80.3 KB

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

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

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

Download in other formats: