vfs.h@ 67139

Last change on this file since 67139 was 67134, checked in by vboxsync, 8 years ago
IPRT: Got the new tar writer working and did basic RTZipTarCmd integration.
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 56.1 KB

Line
1	/** @file
2	* IPRT - Virtual Filesystem.
3	*/
4
5	/*
6	* Copyright (C) 2010-2016 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_vfs_h
27	#define ___iprt_vfs_h
28
29	#include <iprt/cdefs.h>
30	#include <iprt/types.h>
31	#include <iprt/dir.h>
32	#include <iprt/fs.h>
33	#include <iprt/handle.h>
34	#include <iprt/symlink.h>
35	#include <iprt/sg.h>
36	#include <iprt/time.h>
37
38
39	RT_C_DECLS_BEGIN
40
41	/** @defgroup grp_rt_vfs RTVfs - Virtual Filesystem
42	* @ingroup grp_rt
43	*
44	* The virtual filesystem APIs are intended to make it possible to work on
45	* container files, file system sub-trees, file system overlays and other custom
46	* filesystem configurations. It also makes it possible to create filters, like
47	* automatically gunzipping a tar.gz file before feeding it to the RTTar API for
48	* unpacking - or wise versa.
49	*
50	* The virtual filesystem APIs are intended to mirror the RTDir, RTFile, RTPath
51	* and RTFs APIs pretty closely so that rewriting a piece of code to work with
52	* it should be easy. However there are some differences to the way the APIs
53	* works and the user should heed the documentation. The differences are
54	* usually motivated by simplification and in some case to make the VFS more
55	* flexible.
56	*
57	* @{
58	*/
59
60	/**
61	* The object type.
62	*/
63	typedef enum RTVFSOBJTYPE
64	{
65	/** Invalid type. */
66	RTVFSOBJTYPE_INVALID = 0,
67	/** Pure base object.
68	* This is returned by the filesystem stream to represent directories,
69	* devices, fifos and similar that needs to be created. */
70	RTVFSOBJTYPE_BASE,
71	/** Virtual filesystem. */
72	RTVFSOBJTYPE_VFS,
73	/** Filesystem stream. */
74	RTVFSOBJTYPE_FS_STREAM,
75	/** Pure I/O stream. */
76	RTVFSOBJTYPE_IO_STREAM,
77	/** Directory. */
78	RTVFSOBJTYPE_DIR,
79	/** File. */
80	RTVFSOBJTYPE_FILE,
81	/** Symbolic link. */
82	RTVFSOBJTYPE_SYMLINK,
83	/** End of valid object types. */
84	RTVFSOBJTYPE_END,
85	/** Pure I/O stream. */
86	RTVFSOBJTYPE_32BIT_HACK = 0x7fffffff
87	} RTVFSOBJTYPE;
88	/** Pointer to a VFS object type. */
89	typedef RTVFSOBJTYPE *PRTVFSOBJTYPE;
90
91
92
93	/** @name RTVfsCreate flags
94	* @{ */
95	/** Whether the file system is read-only. */
96	#define RTVFS_C_READONLY RT_BIT(0)
97	/** Whether we the VFS should be thread safe (i.e. automaticaly employ
98	* locks). */
99	#define RTVFS_C_THREAD_SAFE RT_BIT(1)
100	/** @} */
101
102	/**
103	* Creates an empty virtual filesystem.
104	*
105	* @returns IPRT status code.
106	* @param pszName Name, for logging and such.
107	* @param fFlags Flags, MBZ.
108	* @param phVfs Where to return the VFS handle. Release the returned
109	* reference by calling RTVfsRelease.
110	*/
111	RTDECL(int) RTVfsCreate(const char *pszName, uint32_t fFlags, PRTVFS phVfs);
112	RTDECL(uint32_t) RTVfsRetain(RTVFS hVfs);
113	RTDECL(uint32_t) RTVfsRetainDebug(RTVFS hVfs, RT_SRC_POS_DECL);
114	RTDECL(uint32_t) RTVfsRelease(RTVFS hVfs);
115	RTDECL(int) RTVfsAttach(RTVFS hVfs, const char *pszMountPoint, uint32_t fFlags, RTVFS hVfsAttach);
116	RTDECL(int) RTVfsDetach(RTVFS hVfs, const char pszMountPoint, RTVFS hVfsToDetach, PRTVFS phVfsDetached);
117	RTDECL(uint32_t) RTVfsGetAttachmentCount(RTVFS hVfs);
118	RTDECL(int) RTVfsGetAttachment(RTVFS hVfs, uint32_t iOrdinal, PRTVFS phVfsAttached, uint32_t pfFlags,
119	char *pszMountPoint, size_t cbMountPoint);
120
121	/**
122	* Queries information about a object in the virtual filesystem.
123	*
124	* @returns IPRT Status code.
125	* @param hVfs VFS handle.
126	* relative to.
127	* @param pszPath Path to the object, relative to the VFS root.
128	* @param pObjInfo Where to return info.
129	* @param enmAddAttr What to return.
130	* @param fFlags RTPATH_F_XXX.
131	* @sa RTPathQueryInfoEx, RTVfsDirQueryPathInfo, RTVfsObjQueryInfo
132	*/
133	RTDECL(int) RTVfsQueryPathInfo(RTVFS hVfs, const char *pszPath, PRTFSOBJINFO pObjInfo,
134	RTFSOBJATTRADD enmAddAttr, uint32_t fFlags);
135
136	/**
137	* Checks whether a given range is in use by the virtual filesystem.
138	*
139	* @returns IPRT status code.
140	* @param hVfs VFS handle.
141	* @param off Start offset to check.
142	* @param cb Number of bytes to check.
143	* @param pfUsed Where to store the result.
144	*/
145	RTDECL(int) RTVfsIsRangeInUse(RTVFS hVfs, uint64_t off, size_t cb, bool *pfUsed);
146
147	/** @defgroup grp_vfs_obj VFS Base Object API
148	* @{
149	*/
150
151	/**
152	* Retains a reference to the VFS base object handle.
153	*
154	* @returns New reference count on success, UINT32_MAX on failure.
155	* @param hVfsObj The VFS base object handle.
156	*/
157	RTDECL(uint32_t) RTVfsObjRetain(RTVFSOBJ hVfsObj);
158	RTDECL(uint32_t) RTVfsObjRetainDebug(RTVFSOBJ hVfsObj, RT_SRC_POS_DECL);
159
160	/**
161	* Releases a reference to the VFS base handle.
162	*
163	* @returns New reference count on success (0 if closed), UINT32_MAX on failure.
164	* @param hVfsObj The VFS base object handle.
165	*/
166	RTDECL(uint32_t) RTVfsObjRelease(RTVFSOBJ hVfsObj);
167
168	/**
169	* Query information about the object.
170	*
171	* @returns IPRT status code.
172	* @retval VERR_NOT_SUPPORTED if the @a enmAddAttr value is not handled by the
173	* implementation.
174	*
175	* @param hVfsObj The VFS object handle.
176	* @param pObjInfo Where to return the info.
177	* @param enmAddAttr Which additional attributes should be retrieved.
178	* @sa RTVfsIoStrmQueryInfo, RTVfsFileQueryInfo, RTFileQueryInfo,
179	* RTPathQueryInfo
180	*/
181	RTDECL(int) RTVfsObjQueryInfo(RTVFSOBJ hVfsObj, PRTFSOBJINFO pObjInfo, RTFSOBJATTRADD enmAddAttr);
182
183
184	/**
185	* Converts a VFS base object handle to a VFS handle.
186	*
187	* @returns Referenced handle on success, NIL on failure.
188	* @param hVfsObj The VFS base object handle.
189	*/
190	RTDECL(RTVFS) RTVfsObjToVfs(RTVFSOBJ hVfsObj);
191
192	/**
193	* Converts a VFS base object handle to a VFS filesystem stream handle.
194	*
195	* @returns Referenced handle on success, NIL on failure.
196	* @param hVfsObj The VFS base object handle.
197	*/
198	RTDECL(RTVFSFSSTREAM) RTVfsObjToFsStream(RTVFSOBJ hVfsObj);
199
200	/**
201	* Converts a VFS base object handle to a VFS directory handle.
202	*
203	* @returns Referenced handle on success, NIL on failure.
204	* @param hVfsObj The VFS base object handle.
205	*/
206	RTDECL(RTVFSDIR) RTVfsObjToDir(RTVFSOBJ hVfsObj);
207
208	/**
209	* Converts a VFS base object handle to a VFS I/O stream handle.
210	*
211	* @returns Referenced handle on success, NIL on failure.
212	* @param hVfsObj The VFS base object handle.
213	*/
214	RTDECL(RTVFSIOSTREAM) RTVfsObjToIoStream(RTVFSOBJ hVfsObj);
215
216	/**
217	* Converts a VFS base object handle to a VFS file handle.
218	*
219	* @returns Referenced handle on success, NIL on failure.
220	* @param hVfsObj The VFS base object handle.
221	*/
222	RTDECL(RTVFSFILE) RTVfsObjToFile(RTVFSOBJ hVfsObj);
223
224	/**
225	* Converts a VFS base object handle to a VFS symbolic link handle.
226	*
227	* @returns Referenced handle on success, NIL on failure.
228	* @param hVfsObj The VFS base object handle.
229	*/
230	RTDECL(RTVFSSYMLINK) RTVfsObjToSymlink(RTVFSOBJ hVfsObj);
231
232
233	/**
234	* Converts a VFS handle to a VFS base object handle.
235	*
236	* @returns Referenced handle on success, NIL if the input handle was invalid.
237	* @param hVfs The VFS handle.
238	*/
239	RTDECL(RTVFSOBJ) RTVfsObjFromVfs(RTVFS hVfs);
240
241	/**
242	* Converts a VFS filesystem stream handle to a VFS base object handle.
243	*
244	* @returns Referenced handle on success, NIL if the input handle was invalid.
245	* @param hVfsFss The VFS filesystem stream handle.
246	*/
247	RTDECL(RTVFSOBJ) RTVfsObjFromFsStream(RTVFSFSSTREAM hVfsFss);
248
249	/**
250	* Converts a VFS directory handle to a VFS base object handle.
251	*
252	* @returns Referenced handle on success, NIL if the input handle was invalid.
253	* @param hVfsDir The VFS directory handle.
254	*/
255	RTDECL(RTVFSOBJ) RTVfsObjFromDir(RTVFSDIR hVfsDir);
256
257	/**
258	* Converts a VFS I/O stream handle to a VFS base object handle.
259	*
260	* @returns Referenced handle on success, NIL if the input handle was invalid.
261	* @param hVfsIos The VFS I/O stream handle.
262	*/
263	RTDECL(RTVFSOBJ) RTVfsObjFromIoStream(RTVFSIOSTREAM hVfsIos);
264
265	/**
266	* Converts a VFS file handle to a VFS base object handle.
267	*
268	* @returns Referenced handle on success, NIL if the input handle was invalid.
269	* @param hVfsFile The VFS file handle.
270	*/
271	RTDECL(RTVFSOBJ) RTVfsObjFromFile(RTVFSFILE hVfsFile);
272
273	/**
274	* Converts a VFS symbolic link handle to a VFS base object handle.
275	*
276	* @returns Referenced handle on success, NIL if the input handle was invalid.
277	* @param hVfsSym The VFS symbolic link handle.
278	*/
279	RTDECL(RTVFSOBJ) RTVfsObjFromSymlink(RTVFSSYMLINK hVfsSym);
280
281	/** @} */
282
283
284	/** @defgroup grp_vfs_fsstream VFS Filesystem Stream API
285	*
286	* Filesystem streams are for tar, cpio and similar. Any virtual filesystem can
287	* be turned into a filesystem stream using RTVfsFsStrmFromVfs.
288	*
289	* @{
290	*/
291
292	RTDECL(uint32_t) RTVfsFsStrmRetain(RTVFSFSSTREAM hVfsFss);
293	RTDECL(uint32_t) RTVfsFsStrmRetainDebug(RTVFSFSSTREAM hVfsFss, RT_SRC_POS_DECL);
294	RTDECL(uint32_t) RTVfsFsStrmRelease(RTVFSFSSTREAM hVfsFss);
295	RTDECL(int) RTVfsFsStrmQueryInfo(RTVFSFSSTREAM hVfsFss, PRTFSOBJINFO pObjInfo, RTFSOBJATTRADD enmAddAttr);
296
297	/**
298	* Gets the next object in the stream.
299	*
300	* This call may affect the stream posision of a previously returned object.
301	*
302	* The type of object returned here typically boils down to three types:
303	* - I/O streams (representing files),
304	* - symbolic links
305	* - base object
306	* The base objects represent anything not convered by the two other, i.e.
307	* directories, device nodes, fifos, sockets and whatnot. The details can be
308	* queried using RTVfsObjQueryInfo.
309	*
310	* That said, absolutely any object except for filesystem stream objects can be
311	* returned by this call. Any generic code is adviced to just deal with it all.
312	*
313	* @returns IPRT status code.
314	* @retval VINF_SUCCESS if a new object was retrieved.
315	* @retval VERR_EOF when there are no more objects.
316	* @retval VERR_INVALID_FUNCTION if called on a non-readable stream.
317	*
318	* @param hVfsFss The file system stream handle.
319	* @param ppszName Where to return the object name. Must be freed by
320	* calling RTStrFree.
321	* @param penmType Where to return the object type.
322	* @param phVfsObj Where to return the object handle (referenced). This
323	* must be cast to the desired type before use.
324	*/
325	RTDECL(int) RTVfsFsStrmNext(RTVFSFSSTREAM hVfsFss, char *ppszName, RTVFSOBJTYPE penmType, PRTVFSOBJ phVfsObj);
326
327	/**
328	* Appends a VFS object to the stream.
329	*
330	* The stream must be writable.
331	*
332	* @returns IPRT status code.
333	* @retval VERR_INVALID_FUNCTION if called on a non-writable stream.
334	* @param hVfsFss The file system stream handle.
335	* @param pszPath The path.
336	* @param hVfsObj The VFS object to add.
337	* @param fFlags RTVFSFSSTRM_ADD_F_XXX.
338	*/
339	RTDECL(int) RTVfsFsStrmAdd(RTVFSFSSTREAM hVfsFss, const char *pszPath, RTVFSOBJ hVfsObj, uint32_t fFlags);
340
341	/** @name RTVFSFSSTRM_ADD_F_XXX - Flags for RTVfsFsStrmAdd.
342	* @{ */
343	/** Input is an I/O stream of indeterminate length, read to the end and then
344	* update the file header.
345	* @note This is only possible if the output stream is actually a file. */
346	#define RTVFSFSSTRM_ADD_F_STREAM RT_BIT_32(0)
347	/** Mask of flags specific to the target stream. */
348	#define RTVFSFSSTRM_ADD_F_SPECIFIC_MASK UINT32_C(0xff000000)
349	/** Valid bits. */
350	#define RTVFSFSSTRM_ADD_F_VALID_MASK UINT32_C(0xff000001)
351	/** @} */
352
353	/**
354	* Marks the end of the stream.
355	*
356	* The stream must be writable.
357	*
358	* @returns IPRT status code.
359	* @retval VERR_INVALID_FUNCTION if called on a non-writable stream.
360	* @param hVfsFss The file system stream handle.
361	*/
362	RTDECL(int) RTVfsFsStrmEnd(RTVFSFSSTREAM hVfsFss);
363
364	/** @} */
365
366
367	/** @defgroup grp_vfs_dir VFS Directory API
368	* @{
369	*/
370
371	/**
372	* Retains a reference to the VFS directory handle.
373	*
374	* @returns New reference count on success, UINT32_MAX on failure.
375	* @param hVfsDir The VFS directory handle.
376	*/
377	RTDECL(uint32_t) RTVfsDirRetain(RTVFSDIR hVfsDir);
378	RTDECL(uint32_t) RTVfsDirRetainDebug(RTVFSDIR hVfsDir, RT_SRC_POS_DECL);
379
380	/**
381	* Releases a reference to the VFS directory handle.
382	*
383	* @returns New reference count on success (0 if closed), UINT32_MAX on failure.
384	* @param hVfsDir The VFS directory handle.
385	*/
386	RTDECL(uint32_t) RTVfsDirRelease(RTVFSDIR hVfsDir);
387
388	/**
389	* Opens a directory in the specified file system.
390	*
391	* @returns IPRT status code.
392	* @param hVfs The VFS to open the directory within.
393	* @param pszPath Path to the directory, relative to the root.
394	* @param fFlags Reserved, MBZ.
395	* @param phVfsDir Where to return the directory.
396	*/
397	RTDECL(int) RTVfsDirOpen(RTVFS hVfs, const char *pszPath, uint32_t fFlags, PRTVFSDIR phVfsDir);
398
399	/**
400	* Opens a file in or under the given directory.
401	*
402	* @returns IPRT status code.
403	* @param hVfsDir The VFS directory start walking the @a pszPath
404	* relative to.
405	* @param pszPath Path to the file.
406	* @param fOpen RTFILE_O_XXX flags.
407	* @param phVfsFile Where to return the file.
408	*/
409	RTDECL(int) RTVfsDirOpenFile(RTVFSDIR hVfsDir, const char *pszPath, uint64_t fOpen, PRTVFSFILE phVfsFile);
410
411	/**
412	* Opens a directory in or under the given directory.
413	*
414	* @returns IPRT status code.
415	* @param hVfsDir The VFS directory start walking the @a pszPath
416	* relative to.
417	* @param pszPath Path to the file.
418	* @param fFlags Reserved, MBZ.
419	* @param phVfsDir Where to return the directory.
420	*/
421	RTDECL(int) RTVfsDirOpenDir(RTVFSDIR hVfsDir, const char *pszPath, uint32_t fFlags, PRTVFSDIR phVfsDir);
422
423	/**
424	* Queries information about a object in or under the given directory.
425	*
426	* @returns IPRT Status code.
427	* @param hVfsDir The VFS directory start walking the @a pszPath
428	* relative to.
429	* @param pszPath Path to the object.
430	* @param pObjInfo Where to return info.
431	* @param enmAddAttr What to return.
432	* @param fFlags RTPATH_F_XXX.
433	* @sa RTPathQueryInfoEx, RTVfsQueryPathInfo, RTVfsObjQueryInfo
434	*/
435	RTDECL(int) RTVfsDirQueryPathInfo(RTVFSDIR hVfsDir, const char *pszPath, PRTFSOBJINFO pObjInfo,
436	RTFSOBJATTRADD enmAddAttr, uint32_t fFlags);
437
438	/**
439	* Reads the next entry in the directory returning extended information.
440	*
441	* @returns VINF_SUCCESS and data in pDirEntry on success.
442	* @returns VERR_NO_MORE_FILES when the end of the directory has been reached.
443	* @returns VERR_BUFFER_OVERFLOW if the buffer is too small to contain the filename. If
444	* pcbDirEntry is specified it will be updated with the required buffer size.
445	* @returns suitable iprt status code on other errors.
446	*
447	* @param hVfsDir The VFS directory.
448	* @param pDirEntry Where to store the information about the next
449	* directory entry on success.
450	* @param pcbDirEntry Optional parameter used for variable buffer size.
451	*
452	* On input the variable pointed to contains the size of the pDirEntry
453	* structure. This must be at least OFFSET(RTDIRENTRYEX, szName[2]) bytes.
454	*
455	* On successful output the field is updated to
456	* OFFSET(RTDIRENTRYEX, szName[pDirEntry->cbName + 1]).
457	*
458	* When the data doesn't fit in the buffer and VERR_BUFFER_OVERFLOW is
459	* returned, this field contains the required buffer size.
460	*
461	* The value is unchanged in all other cases.
462	* @param enmAddAttr Which set of additional attributes to request.
463	* Use RTFSOBJATTRADD_NOTHING if this doesn't matter.
464	*
465	* @sa RTDirReadEx
466	*/
467	RTDECL(int) RTVfsDirReadEx(RTVFSDIR hVfsDir, PRTDIRENTRYEX pDirEntry, size_t *pcbDirEntry, RTFSOBJATTRADD enmAddAttr);
468
469	/** @} */
470
471
472	/** @defgroup grp_vfs_symlink VFS Symbolic Link API
473	*
474	* @remarks The TAR VFS and filesystem stream uses symbolic links for
475	* describing hard links as well. The users must use RTFS_IS_SYMLINK
476	* to check if it is a real symlink in those cases.
477	*
478	* @remarks Any VFS which is backed by a real file system may be subject to
479	* races with other processes or threads, so the user may get
480	* unexpected errors when this happends. This is a bit host specific,
481	* i.e. it might be prevent on windows if we care.
482	*
483	* @{
484	*/
485
486
487	/**
488	* Retains a reference to the VFS symbolic link handle.
489	*
490	* @returns New reference count on success, UINT32_MAX on failure.
491	* @param hVfsSym The VFS symbolic link handle.
492	*/
493	RTDECL(uint32_t) RTVfsSymlinkRetain(RTVFSSYMLINK hVfsSym);
494	RTDECL(uint32_t) RTVfsSymlinkRetainDebug(RTVFSSYMLINK hVfsSym, RT_SRC_POS_DECL);
495
496	/**
497	* Releases a reference to the VFS symbolic link handle.
498	*
499	* @returns New reference count on success (0 if closed), UINT32_MAX on failure.
500	* @param hVfsSym The VFS symbolic link handle.
501	*/
502	RTDECL(uint32_t) RTVfsSymlinkRelease(RTVFSSYMLINK hVfsSym);
503
504	/**
505	* Query information about the symbolic link.
506	*
507	* @returns IPRT status code.
508	* @param hVfsSym The VFS symbolic link handle.
509	* @param pObjInfo Where to return the info.
510	* @param enmAddAttr Which additional attributes should be retrieved.
511	*
512	* @sa RTFileQueryInfo, RTPathQueryInfo, RTPathQueryInfoEx
513	*/
514	RTDECL(int) RTVfsSymlinkQueryInfo(RTVFSSYMLINK hVfsSym, PRTFSOBJINFO pObjInfo, RTFSOBJATTRADD enmAddAttr);
515
516	/**
517	* Set the unix style owner and group.
518	*
519	* @returns IPRT status code.
520	* @param hVfsSym The VFS symbolic link handle.
521	* @param fMode The new mode bits.
522	* @param fMask The mask indicating which bits we are changing.
523	* @sa RTFileSetMode, RTPathSetMode
524	*/
525	RTDECL(int) RTVfsSymlinkSetMode(RTVFSSYMLINK hVfsSym, RTFMODE fMode, RTFMODE fMask);
526
527	/**
528	* Set the timestamps associated with the object.
529	*
530	* @returns IPRT status code.
531	* @param hVfsSym The VFS symbolic link handle.
532	* @param pAccessTime Pointer to the new access time. NULL if not
533	* to be changed.
534	* @param pModificationTime Pointer to the new modifcation time. NULL if
535	* not to be changed.
536	* @param pChangeTime Pointer to the new change time. NULL if not to be
537	* changed.
538	* @param pBirthTime Pointer to the new time of birth. NULL if not to be
539	* changed.
540	* @remarks See RTFileSetTimes for restrictions and behavior imposed by the
541	* host OS or underlying VFS provider.
542	* @sa RTFileSetTimes, RTPathSetTimes
543	*/
544	RTDECL(int) RTVfsSymlinkSetTimes(RTVFSSYMLINK hVfsSym, PCRTTIMESPEC pAccessTime, PCRTTIMESPEC pModificationTime,
545	PCRTTIMESPEC pChangeTime, PCRTTIMESPEC pBirthTime);
546
547	/**
548	* Set the unix style owner and group.
549	*
550	* @returns IPRT status code.
551	* @param hVfsSym The VFS symbolic link handle.
552	* @param uid The user ID of the new owner. NIL_RTUID if
553	* unchanged.
554	* @param gid The group ID of the new owner group. NIL_RTGID if
555	* unchanged.
556	* @sa RTFileSetOwner, RTPathSetOwner.
557	*/
558	RTDECL(int) RTVfsSymlinkSetOwner(RTVFSSYMLINK hVfsSym, RTUID uid, RTGID gid);
559
560	/**
561	* Read the symbolic link target.
562	*
563	* @returns IPRT status code.
564	* @param hVfsSym The VFS symbolic link handle.
565	* @param pszTarget The target buffer.
566	* @param cbTarget The size of the target buffer.
567	* @sa RTSymlinkRead
568	*/
569	RTDECL(int) RTVfsSymlinkRead(RTVFSSYMLINK hVfsSym, char *pszTarget, size_t cbTarget);
570
571	/** @} */
572
573
574
575	/** @defgroup grp_vfs_iostream VFS I/O Stream API
576	* @{
577	*/
578
579	/**
580	* Creates a VFS file from a memory buffer.
581	*
582	* @returns IPRT status code.
583	*
584	* @param fFlags A combination of RTFILE_O_READ and RTFILE_O_WRITE.
585	* @param pvBuf The buffer. This will be copied and not referenced
586	* after this function returns.
587	* @param cbBuf The buffer size.
588	* @param phVfsIos Where to return the VFS I/O stream handle.
589	*/
590	RTDECL(int) RTVfsIoStrmFromBuffer(uint32_t fFlags, void const *pvBuf, size_t cbBuf, PRTVFSIOSTREAM phVfsIos);
591
592	/**
593	* Creates a VFS I/O stream handle from a standard IPRT file handle (RTFILE).
594	*
595	* @returns IPRT status code.
596	* @param hFile The standard IPRT file handle.
597	* @param fOpen The flags the handle was opened with. Pass 0 to
598	* have these detected.
599	* @param fLeaveOpen Whether to leave the handle open when the VFS file
600	* is released, or to close it (@c false).
601	* @param phVfsIos Where to return the VFS I/O stream handle.
602	*/
603	RTDECL(int) RTVfsIoStrmFromRTFile(RTFILE hFile, uint64_t fOpen, bool fLeaveOpen, PRTVFSIOSTREAM phVfsIos);
604
605	/**
606	* Creates a VFS I/O stream handle from a standard IPRT pipe handle (RTPIPE).
607	*
608	* @returns IPRT status code.
609	* @param hPipe The standard IPRT pipe handle.
610	* @param fLeaveOpen Whether to leave the handle open when the VFS file
611	* is released, or to close it (@c false).
612	* @param phVfsIos Where to return the VFS I/O stream handle.
613	*/
614	RTDECL(int) RTVfsIoStrmFromRTPipe(RTPIPE hPipe, bool fLeaveOpen, PRTVFSIOSTREAM phVfsIos);
615
616	/**
617	* Convenience function combining RTFileOpen with RTVfsIoStrmFromRTFile.
618	*
619	* @returns IPRT status code.
620	* @param pszFilename The path to the file in the normal file system.
621	* @param fOpen The flags to pass to RTFileOpen when opening the
622	* file, i.e. RTFILE_O_XXX.
623	* @param phVfsIos Where to return the VFS I/O stream handle.
624	*/
625	RTDECL(int) RTVfsIoStrmOpenNormal(const char *pszFilename, uint64_t fOpen, PRTVFSIOSTREAM phVfsIos);
626
627	/**
628	* Create a VFS I/O stream handle from one of the standard handles.
629	*
630	* @returns IPRT status code.
631	* @param enmStdHandle The standard IPRT file handle.
632	* @param fOpen The flags the handle was opened with. Pass 0 to
633	* have these detected.
634	* @param fLeaveOpen Whether to leave the handle open when the VFS file
635	* is released, or to close it (@c false).
636	* @param phVfsIos Where to return the VFS I/O stream handle.
637	*/
638	RTDECL(int) RTVfsIoStrmFromStdHandle(RTHANDLESTD enmStdHandle, uint64_t fOpen, bool fLeaveOpen,
639	PRTVFSIOSTREAM phVfsIos);
640
641	/**
642	* Retains a reference to the VFS I/O stream handle.
643	*
644	* @returns New reference count on success, UINT32_MAX on failure.
645	* @param hVfsIos The VFS I/O stream handle.
646	*/
647	RTDECL(uint32_t) RTVfsIoStrmRetain(RTVFSIOSTREAM hVfsIos);
648	RTDECL(uint32_t) RTVfsIoStrmRetainDebug(RTVFSIOSTREAM hVfsIos, RT_SRC_POS_DECL);
649
650	/**
651	* Releases a reference to the VFS I/O stream handle.
652	*
653	* @returns New reference count on success (0 if closed), UINT32_MAX on failure.
654	* @param hVfsIos The VFS I/O stream handle.
655	*/
656	RTDECL(uint32_t) RTVfsIoStrmRelease(RTVFSIOSTREAM hVfsIos);
657
658	/**
659	* Convert the VFS I/O stream handle to a VFS file handle.
660	*
661	* @returns The VFS file handle on success, this must be released.
662	* NIL_RTVFSFILE if the I/O stream handle is invalid.
663	* @param hVfsIos The VFS I/O stream handle.
664	* @sa RTVfsFileToIoStream
665	*/
666	RTDECL(RTVFSFILE) RTVfsIoStrmToFile(RTVFSIOSTREAM hVfsIos);
667
668	/**
669	* Query information about the I/O stream.
670	*
671	* @returns IPRT status code.
672	* @param hVfsIos The VFS I/O stream handle.
673	* @param pObjInfo Where to return the info.
674	* @param enmAddAttr Which additional attributes should be retrieved.
675	* @sa RTFileQueryInfo
676	*/
677	RTDECL(int) RTVfsIoStrmQueryInfo(RTVFSIOSTREAM hVfsIos, PRTFSOBJINFO pObjInfo, RTFSOBJATTRADD enmAddAttr);
678
679	/**
680	* Read bytes from the I/O stream.
681	*
682	* @returns IPRT status code.
683	* @retval VINF_SUCCESS and the number of bytes read written to @a pcbRead.
684	* @retval VINF_TRY_AGAIN if @a fBlocking is @c false, @a pcbRead is not NULL,
685	* and no data was available. @a *pcbRead will be set to 0.
686	* @retval VINF_EOF when trying to read __beyond__ the end of the stream and
687	* @a pcbRead is not NULL (it will be set to the number of bytes read,
688	* or 0 if the end of the stream was reached before this call).
689	* When the last byte of the read request is the last byte in the
690	* stream, this status code will not be used. However, VINF_EOF is
691	* returned when attempting to read 0 bytes while standing at the end
692	* of the stream.
693	* @retval VERR_EOF when trying to read __beyond__ the end of the stream and
694	* @a pcbRead is NULL.
695	* @retval VERR_ACCESS_DENIED if the stream is not readable.
696	*
697	* @param hVfsIos The VFS I/O stream handle.
698	* @param pvBuf Where to store the read bytes.
699	* @param cbToRead The number of bytes to read.
700	* @param fBlocking Whether the call is blocking (@c true) or not. If
701	* not, the @a pcbRead parameter must not be NULL.
702	* @param pcbRead Where to always store the number of bytes actually
703	* read. This can be NULL if @a fBlocking is true.
704	* @sa RTVfsFileRead, RTFileRead, RTPipeRead, RTPipeReadBlocking,
705	* RTSocketRead
706	*/
707	RTDECL(int) RTVfsIoStrmRead(RTVFSIOSTREAM hVfsIos, void pvBuf, size_t cbToRead, bool fBlocking, size_t pcbRead);
708
709	/**
710	* Read bytes from the I/O stream, optionally with offset.
711	*
712	* @returns IPRT status code.
713	* @retval VINF_SUCCESS and the number of bytes read written to @a pcbRead.
714	* @retval VINF_TRY_AGAIN if @a fBlocking is @c false, @a pcbRead is not NULL,
715	* and no data was available. @a *pcbRead will be set to 0.
716	* @retval VINF_EOF when trying to read __beyond__ the end of the stream and
717	* @a pcbRead is not NULL (it will be set to the number of bytes read,
718	* or 0 if the end of the stream was reached before this call).
719	* When the last byte of the read request is the last byte in the
720	* stream, this status code will not be used. However, VINF_EOF is
721	* returned when attempting to read 0 bytes while standing at the end
722	* of the stream.
723	* @retval VERR_EOF when trying to read __beyond__ the end of the stream and
724	* @a pcbRead is NULL.
725	* @retval VERR_ACCESS_DENIED if the stream is not readable.
726	*
727	* @param hVfsIos The VFS I/O stream handle.
728	* @param off Where to read at, -1 for the current position.
729	* @param pvBuf Where to store the read bytes.
730	* @param cbToRead The number of bytes to read.
731	* @param fBlocking Whether the call is blocking (@c true) or not. If
732	* not, the @a pcbRead parameter must not be NULL.
733	* @param pcbRead Where to always store the number of bytes actually
734	* read. This can be NULL if @a fBlocking is true.
735	* @sa RTVfsFileRead, RTFileRead, RTPipeRead, RTPipeReadBlocking,
736	* RTSocketRead
737	*/
738	RTDECL(int) RTVfsIoStrmReadAt(RTVFSIOSTREAM hVfsIos, RTFOFF off, void pvBuf, size_t cbToRead, bool fBlocking, size_t pcbRead);
739
740	/**
741	* Reads the remainder of the stream into a memory buffer.
742	*
743	* For simplifying string-style processing, the is a zero byte after the
744	* returned buffer, making sure it can be used as a zero terminated string.
745	*
746	* @returns IPRT status code.
747	* @param hVfsIos The VFS I/O stream handle.
748	* @param ppvBuf Where to return the buffer. Must pass to
749	* RTVfsIoStrmReadAllFree for freeing, not RTMemFree!
750	* @param pcbBuf Where to return the buffer size.
751	*/
752	RTDECL(int) RTVfsIoStrmReadAll(RTVFSIOSTREAM hVfsIos, void *ppvBuf, size_t pcbBuf);
753
754	/**
755	* Free memory buffer returned by RTVfsIoStrmReadAll.
756	*
757	* @param pvBuf What RTVfsIoStrmReadAll returned.
758	* @param cbBuf What RTVfsIoStrmReadAll returned.
759	*/
760	RTDECL(void) RTVfsIoStrmReadAllFree(void *pvBuf, size_t cbBuf);
761
762	/**
763	* Write bytes to the I/O stream.
764	*
765	* @returns IPRT status code.
766	* @retval VERR_ACCESS_DENIED if the stream is not writable.
767	*
768	* @param hVfsIos The VFS I/O stream handle.
769	* @param pvBuf The bytes to write.
770	* @param cbToWrite The number of bytes to write.
771	* @param fBlocking Whether the call is blocking (@c true) or not. If
772	* not, the @a pcbWritten parameter must not be NULL.
773	* @param pcbWritten Where to always store the number of bytes actually
774	* written. This can be NULL if @a fBlocking is true.
775	* @sa RTVfsFileWrite, RTFileWrite, RTPipeWrite, RTPipeWriteBlocking,
776	* RTSocketWrite
777	*/
778	RTDECL(int) RTVfsIoStrmWrite(RTVFSIOSTREAM hVfsIos, const void pvBuf, size_t cbToWrite, bool fBlocking, size_t pcbWritten);
779	RTDECL(int) RTVfsIoStrmWriteAt(RTVFSIOSTREAM hVfsIos, RTFOFF off, const void pvBuf, size_t cbToWrite, bool fBlocking, size_t pcbWritten);
780
781	/**
782	* Reads bytes from the I/O stream into a scatter buffer.
783	*
784	* @returns IPRT status code.
785	* @retval VINF_SUCCESS and the number of bytes read written to @a pcbRead.
786	* @retval VINF_TRY_AGAIN if @a fBlocking is @c false, @a pcbRead is not NULL,
787	* and no data was available. @a *pcbRead will be set to 0.
788	* @retval VINF_EOF when trying to read __beyond__ the end of the stream and
789	* @a pcbRead is not NULL (it will be set to the number of bytes read,
790	* or 0 if the end of the stream was reached before this call).
791	* When the last byte of the read request is the last byte in the
792	* stream, this status code will not be used. However, VINF_EOF is
793	* returned when attempting to read 0 bytes while standing at the end
794	* of the stream.
795	* @retval VERR_EOF when trying to read __beyond__ the end of the stream and
796	* @a pcbRead is NULL.
797	* @retval VERR_ACCESS_DENIED if the stream is not readable.
798	*
799	* @param hVfsIos The VFS I/O stream handle.
800	* @param off Where to read at, -1 for the current position.
801	* @param pSgBuf Pointer to a scatter buffer descriptor. The number
802	* of bytes described by the segments is what will be
803	* attemted read.
804	* @param fBlocking Whether the call is blocking (@c true) or not. If
805	* not, the @a pcbRead parameter must not be NULL.
806	* @param pcbRead Where to always store the number of bytes actually
807	* read. This can be NULL if @a fBlocking is true.
808	* @sa RTFileSgRead, RTSocketSgRead, RTPipeRead, RTPipeReadBlocking
809	*/
810	RTDECL(int) RTVfsIoStrmSgRead(RTVFSIOSTREAM hVfsIos, RTFOFF off, PCRTSGBUF pSgBuf, bool fBlocking, size_t *pcbRead);
811
812	/**
813	* Write bytes to the I/O stream from a gather buffer.
814	*
815	* @returns IPRT status code.
816	* @retval VERR_ACCESS_DENIED if the stream is not writable.
817	*
818	* @param hVfsIos The VFS I/O stream handle.
819	* @param off Where to write at, -1 for the current position.
820	* @param pSgBuf Pointer to a gather buffer descriptor. The number
821	* of bytes described by the segments is what will be
822	* attemted written.
823	* @param fBlocking Whether the call is blocking (@c true) or not. If
824	* not, the @a pcbWritten parameter must not be NULL.
825	* @param pcbWritten Where to always store the number of bytes actually
826	* written. This can be NULL if @a fBlocking is true.
827	* @sa RTFileSgWrite, RTSocketSgWrite
828	*/
829	RTDECL(int) RTVfsIoStrmSgWrite(RTVFSIOSTREAM hVfsIos, RTFOFF off, PCRTSGBUF pSgBuf, bool fBlocking, size_t *pcbWritten);
830
831	/**
832	* Flush any buffered data to the I/O stream.
833	*
834	* @returns IPRT status code.
835	* @param hVfsIos The VFS I/O stream handle.
836	* @sa RTVfsFileFlush, RTFileFlush, RTPipeFlush
837	*/
838	RTDECL(int) RTVfsIoStrmFlush(RTVFSIOSTREAM hVfsIos);
839
840	/**
841	* Poll for events.
842	*
843	* @returns IPRT status code.
844	* @param hVfsIos The VFS I/O stream handle.
845	* @param fEvents The events to poll for (RTPOLL_EVT_XXX).
846	* @param cMillies How long to wait for event to eventuate.
847	* @param fIntr Whether the wait is interruptible and can return
848	* VERR_INTERRUPTED (@c true) or if this condition
849	* should be hidden from the caller (@c false).
850	* @param pfRetEvents Where to return the event mask.
851	* @sa RTVfsFilePoll, RTPollSetAdd, RTPoll, RTPollNoResume.
852	*/
853	RTDECL(int) RTVfsIoStrmPoll(RTVFSIOSTREAM hVfsIos, uint32_t fEvents, RTMSINTERVAL cMillies, bool fIntr,
854	uint32_t *pfRetEvents);
855	/**
856	* Tells the current I/O stream position.
857	*
858	* @returns Zero or higher - where to return the I/O stream offset. Values
859	* below zero are IPRT status codes (VERR_XXX).
860	* @param hVfsIos The VFS I/O stream handle.
861	* @sa RTFileTell
862	*/
863	RTDECL(RTFOFF) RTVfsIoStrmTell(RTVFSIOSTREAM hVfsIos);
864
865	/**
866	* Skips @a cb ahead in the stream.
867	*
868	* @returns IPRT status code.
869	* @param hVfsIos The VFS I/O stream handle.
870	* @param cb The number bytes to skip.
871	*/
872	RTDECL(int) RTVfsIoStrmSkip(RTVFSIOSTREAM hVfsIos, RTFOFF cb);
873
874	/**
875	* Fills the stream with @a cb zeros.
876	*
877	* @returns IPRT status code.
878	* @param hVfsIos The VFS I/O stream handle.
879	* @param cb The number of zero bytes to insert.
880	*/
881	RTDECL(int) RTVfsIoStrmZeroFill(RTVFSIOSTREAM hVfsIos, RTFOFF cb);
882
883	/**
884	* Checks if we're at the end of the I/O stream.
885	*
886	* @returns true if at EOS, otherwise false.
887	* @param hVfsIos The VFS I/O stream handle.
888	*/
889	RTDECL(bool) RTVfsIoStrmIsAtEnd(RTVFSIOSTREAM hVfsIos);
890
891	/**
892	* Process the rest of the stream, checking if it's all valid UTF-8 encoding.
893	*
894	* @returns IPRT status code.
895	*
896	* @param hVfsIos The VFS I/O stream handle.
897	* @param fFlags Flags governing the validation, see
898	* RTVFS_VALIDATE_UTF8_XXX.
899	* @param poffError Where to return the error offset. Optional.
900	*/
901	RTDECL(int) RTVfsIoStrmValidateUtf8Encoding(RTVFSIOSTREAM hVfsIos, uint32_t fFlags, PRTFOFF poffError);
902
903	/** @defgroup RTVFS_VALIDATE_UTF8_XXX RTVfsIoStrmValidateUtf8Encoding flags.
904	* @{ */
905	/** The text must not contain any null terminator codepoints. */
906	#define RTVFS_VALIDATE_UTF8_NO_NULL RT_BIT_32(0)
907	/** The codepoints must be in the range covered by RTC-3629. */
908	#define RTVFS_VALIDATE_UTF8_BY_RTC_3629 RT_BIT_32(1)
909	/** Mask of valid flags. */
910	#define RTVFS_VALIDATE_UTF8_VALID_MASK UINT32_C(0x00000003)
911	/** @} */
912
913	/** @} */
914
915
916	/** @defgroup grp_vfs_file VFS File API
917	* @{
918	*/
919	RTDECL(int) RTVfsFileOpen(RTVFS hVfs, const char *pszFilename, uint64_t fOpen, PRTVFSFILE phVfsFile);
920
921	/**
922	* Create a VFS file handle from a standard IPRT file handle (RTFILE).
923	*
924	* @returns IPRT status code.
925	* @param hFile The standard IPRT file handle.
926	* @param fOpen The flags the handle was opened with. Pass 0 to
927	* have these detected.
928	* @param fLeaveOpen Whether to leave the handle open when the VFS file
929	* is released, or to close it (@c false).
930	* @param phVfsFile Where to return the VFS file handle.
931	*/
932	RTDECL(int) RTVfsFileFromRTFile(RTFILE hFile, uint64_t fOpen, bool fLeaveOpen, PRTVFSFILE phVfsFile);
933	RTDECL(RTHCUINTPTR) RTVfsFileToNative(RTFILE hVfsFile);
934
935	/**
936	* Convenience function combining RTFileOpen with RTVfsFileFromRTFile.
937	*
938	* @returns IPRT status code.
939	* @param pszFilename The path to the file in the normal file system.
940	* @param fOpen The flags to pass to RTFileOpen when opening the
941	* file, i.e. RTFILE_O_XXX.
942	* @param phVfsFile Where to return the VFS file handle.
943	*/
944	RTDECL(int) RTVfsFileOpenNormal(const char *pszFilename, uint64_t fOpen, PRTVFSFILE phVfsFile);
945
946	/**
947	* Convert the VFS file handle to a VFS I/O stream handle.
948	*
949	* @returns The VFS I/O stream handle on success, this must be released.
950	* NIL_RTVFSIOSTREAM if the file handle is invalid.
951	* @param hVfsFile The VFS file handle.
952	* @sa RTVfsIoStrmToFile
953	*/
954	RTDECL(RTVFSIOSTREAM) RTVfsFileToIoStream(RTVFSFILE hVfsFile);
955
956	/**
957	* Retains a reference to the VFS file handle.
958	*
959	* @returns New reference count on success, UINT32_MAX on failure.
960	* @param hVfsFile The VFS file handle.
961	*/
962	RTDECL(uint32_t) RTVfsFileRetain(RTVFSFILE hVfsFile);
963	RTDECL(uint32_t) RTVfsFileRetainDebug(RTVFSFILE hVfsFile, RT_SRC_POS_DECL);
964
965	/**
966	* Releases a reference to the VFS file handle.
967	*
968	* @returns New reference count on success (0 if closed), UINT32_MAX on failure.
969	* @param hVfsFile The VFS file handle.
970	*/
971	RTDECL(uint32_t) RTVfsFileRelease(RTVFSFILE hVfsFile);
972
973	/**
974	* Query information about the object.
975	*
976	* @returns IPRT status code.
977	* @retval VERR_NOT_SUPPORTED if the @a enmAddAttr value is not handled by the
978	* implementation.
979	*
980	* @param hVfsFile The VFS file handle.
981	* @param pObjInfo Where to return the info.
982	* @param enmAddAttr Which additional attributes should be retrieved.
983	* @sa RTVfsObjQueryInfo, RTVfsFsStrmQueryInfo, RTVfsDirQueryInfo,
984	* RTVfsIoStrmQueryInfo, RTVfsFileQueryInfo, RTFileQueryInfo,
985	* RTPathQueryInfo.
986	*/
987	RTDECL(int) RTVfsFileQueryInfo(RTVFSFILE hVfsFile, PRTFSOBJINFO pObjInfo, RTFSOBJATTRADD enmAddAttr);
988
989	/**
990	* Read bytes from the file at the current position.
991	*
992	* @returns IPRT status code.
993	* @retval VINF_SUCCESS and the number of bytes read written to @a pcbRead.
994	* @retval VINF_EOF when trying to read __beyond__ the end of the file and
995	* @a pcbRead is not NULL (it will be set to the number of bytes read,
996	* or 0 if the end of the file was reached before this call).
997	* When the last byte of the read request is the last byte in the
998	* file, this status code will not be used. However, VINF_EOF is
999	* returned when attempting to read 0 bytes while standing at the end
1000	* of the file.
1001	* @retval VERR_EOF when trying to read __beyond__ the end of the file and
1002	* @a pcbRead is NULL.
1003	* @retval VERR_ACCESS_DENIED if the file is not readable.
1004	*
1005	* @param hVfsFile The VFS file handle.
1006	* @param pvBuf Where to store the read bytes.
1007	* @param cbToRead The number of bytes to read.
1008	* @param pcbRead Where to always store the number of bytes actually
1009	* read. Optional.
1010	* @sa RTVfsIoStrmRead, RTFileRead, RTPipeRead, RTPipeReadBlocking,
1011	* RTSocketRead
1012	*/
1013	RTDECL(int) RTVfsFileRead(RTVFSFILE hVfsFile, void pvBuf, size_t cbToRead, size_t pcbRead);
1014	RTDECL(int) RTVfsFileReadAt(RTVFSFILE hVfsFile, RTFOFF off, void pvBuf, size_t cbToRead, size_t pcbRead);
1015
1016	/**
1017	* Write bytes to the file at the current position.
1018	*
1019	* @returns IPRT status code.
1020	* @retval VERR_ACCESS_DENIED if the file is not writable.
1021	*
1022	* @param hVfsFile The VFS file handle.
1023	* @param pvBuf The bytes to write.
1024	* @param cbToWrite The number of bytes to write.
1025	* @param pcbWritten Where to always store the number of bytes actually
1026	* written. This can be NULL.
1027	* @sa RTVfsIoStrmRead, RTFileWrite, RTPipeWrite, RTPipeWriteBlocking,
1028	* RTSocketWrite
1029	*/
1030	RTDECL(int) RTVfsFileWrite(RTVFSFILE hVfsFile, const void pvBuf, size_t cbToWrite, size_t pcbWritten);
1031	RTDECL(int) RTVfsFileWriteAt(RTVFSFILE hVfsFile, RTFOFF off, const void pvBuf, size_t cbToWrite, size_t pcbWritten);
1032
1033
1034	/**
1035	* Reads bytes from the file into a scatter buffer.
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 hVfsFile The VFS file handle.
1053	* @param off Where to read at, -1 for the current position.
1054	* @param pSgBuf Pointer to a scatter buffer descriptor. The number
1055	* of bytes described by the segments is what will be
1056	* attemted read.
1057	* @param fBlocking Whether the call is blocking (@c true) or not. If
1058	* not, the @a pcbRead parameter must not be NULL.
1059	* @param pcbRead Where to always store the number of bytes actually
1060	* read. This can be NULL if @a fBlocking is true.
1061	* @sa RTFileSgRead, RTSocketSgRead, RTPipeRead, RTPipeReadBlocking
1062	*/
1063	RTDECL(int) RTVfsFileSgRead(RTVFSFILE hVfsFile, RTFOFF off, PCRTSGBUF pSgBuf, bool fBlocking, size_t *pcbRead);
1064
1065	/**
1066	* Write bytes to the file from a gather buffer.
1067	*
1068	* @returns IPRT status code.
1069	* @retval VERR_ACCESS_DENIED if the stream is not writable.
1070	*
1071	* @param hVfsFile The VFS file handle.
1072	* @param off Where to write at, -1 for the current position.
1073	* @param pSgBuf Pointer to a gather buffer descriptor. The number
1074	* of bytes described by the segments is what will be
1075	* attemted written.
1076	* @param fBlocking Whether the call is blocking (@c true) or not. If
1077	* not, the @a pcbWritten parameter must not be NULL.
1078	* @param pcbWritten Where to always store the number of bytes actually
1079	* written. This can be NULL if @a fBlocking is true.
1080	* @sa RTFileSgWrite, RTSocketSgWrite
1081	*/
1082	RTDECL(int) RTVfsFileSgWrite(RTVFSFILE hVfsFile, RTFOFF off, PCRTSGBUF pSgBuf, bool fBlocking, size_t *pcbWritten);
1083
1084	/**
1085	* Flush any buffered data to the file.
1086	*
1087	* @returns IPRT status code.
1088	* @param hVfsFile The VFS file handle.
1089	* @sa RTVfsIoStrmFlush, RTFileFlush, RTPipeFlush
1090	*/
1091	RTDECL(int) RTVfsFileFlush(RTVFSFILE hVfsFile);
1092
1093	/**
1094	* Poll for events.
1095	*
1096	* @returns IPRT status code.
1097	* @param hVfsFile The VFS file handle.
1098	* @param fEvents The events to poll for (RTPOLL_EVT_XXX).
1099	* @param cMillies How long to wait for event to eventuate.
1100	* @param fIntr Whether the wait is interruptible and can return
1101	* VERR_INTERRUPTED (@c true) or if this condition
1102	* should be hidden from the caller (@c false).
1103	* @param pfRetEvents Where to return the event mask.
1104	* @sa RTVfsIoStrmPoll, RTPollSetAdd, RTPoll, RTPollNoResume.
1105	*/
1106	RTDECL(RTFOFF) RTVfsFilePoll(RTVFSFILE hVfsFile, uint32_t fEvents, RTMSINTERVAL cMillies, bool fIntr,
1107	uint32_t *pfRetEvents);
1108
1109	/**
1110	* Tells the current file position.
1111	*
1112	* @returns Zero or higher - where to return the file offset. Values
1113	* below zero are IPRT status codes (VERR_XXX).
1114	* @param hVfsFile The VFS file handle.
1115	* @sa RTFileTell, RTVfsIoStrmTell.
1116	*/
1117	RTDECL(RTFOFF) RTVfsFileTell(RTVFSFILE hVfsFile);
1118
1119	/**
1120	* Changes the current read/write position of a file.
1121	*
1122	* @returns IPRT status code.
1123	*
1124	* @param hVfsFile The VFS file handle.
1125	* @param offSeek The seek offset.
1126	* @param uMethod The seek emthod.
1127	* @param poffActual Where to optionally return the new file offset.
1128	*
1129	* @sa RTFileSeek
1130	*/
1131	RTDECL(int) RTVfsFileSeek(RTVFSFILE hVfsFile, RTFOFF offSeek, uint32_t uMethod, uint64_t *poffActual);
1132
1133	RTDECL(int) RTVfsFileSetSize(RTVFSFILE hVfsFile, uint64_t cbSize);
1134	RTDECL(int) RTVfsFileGetSize(RTVFSFILE hVfsFile, uint64_t *pcbSize);
1135	RTDECL(RTFOFF) RTVfsFileGetMaxSize(RTVFSFILE hVfsFile);
1136	RTDECL(int) RTVfsFileGetMaxSizeEx(RTVFSFILE hVfsFile, PRTFOFF pcbMax);
1137
1138	/** @} */
1139
1140
1141	#ifdef DEBUG
1142	# undef RTVfsRetain
1143	# define RTVfsRetain(hVfs) RTVfsRetainDebug(hVfs, RT_SRC_POS)
1144	# undef RTVfsObjRetain
1145	# define RTVfsObjRetain(hVfsObj) RTVfsObjRetainDebug(hVfsObj, RT_SRC_POS)
1146	# undef RTVfsDirRetain
1147	# define RTVfsDirRetain(hVfsDir) RTVfsDirRetainDebug(hVfsDir, RT_SRC_POS)
1148	# undef RTVfsFileRetain
1149	# define RTVfsFileRetain(hVfsFile) RTVfsFileRetainDebug(hVfsFile, RT_SRC_POS)
1150	# undef RTVfsIoStrmRetain
1151	# define RTVfsIoStrmRetain(hVfsIos) RTVfsIoStrmRetainDebug(hVfsIos, RT_SRC_POS)
1152	# undef RTVfsFsStrmRetain
1153	# define RTVfsFsStrmRetain(hVfsFss) RTVfsFsStrmRetainDebug(hVfsFss, RT_SRC_POS)
1154	#endif
1155
1156
1157
1158	/** @defgroup grp_vfs_misc VFS Miscellaneous
1159	* @{
1160	*/
1161
1162	/**
1163	* Memorizes the I/O stream as a file backed by memory.
1164	*
1165	* @returns IPRT status code.
1166	*
1167	* @param hVfsIos The VFS I/O stream to memorize. This will be read
1168	* to the end on success, on failure its position is
1169	* undefined.
1170	* @param fFlags A combination of RTFILE_O_READ and RTFILE_O_WRITE.
1171	* @param phVfsFile Where to return the handle to the memory file on
1172	* success.
1173	*/
1174	RTDECL(int) RTVfsMemorizeIoStreamAsFile(RTVFSIOSTREAM hVfsIos, uint32_t fFlags, PRTVFSFILE phVfsFile);
1175
1176
1177	/**
1178	* Creates a VFS file from a memory buffer.
1179	*
1180	* @returns IPRT status code.
1181	*
1182	* @param fFlags A combination of RTFILE_O_READ and RTFILE_O_WRITE.
1183	* @param pvBuf The buffer. This will be copied and not referenced
1184	* after this function returns.
1185	* @param cbBuf The buffer size.
1186	* @param phVfsFile Where to return the handle to the memory file on
1187	* success.
1188	*/
1189	RTDECL(int) RTVfsFileFromBuffer(uint32_t fFlags, void const *pvBuf, size_t cbBuf, PRTVFSFILE phVfsFile);
1190
1191	/**
1192	* Creates a memory backed VFS file object for read and write.
1193	*
1194	* @returns IPRT status code.
1195	*
1196	* @param hVfsIos The VFS I/O stream to memorize. This will be read
1197	* to the end on success, on failure its position is
1198	* undefined.
1199	* @param cbEstimate The estimated file size.
1200	* @param phVfsFile Where to return the handle to the memory file on
1201	* success.
1202	*/
1203	RTDECL(int) RTVfsMemFileCreate(RTVFSIOSTREAM hVfsIos, size_t cbEstimate, PRTVFSFILE phVfsFile);
1204
1205	/**
1206	* Pumps data from one I/O stream to another.
1207	*
1208	* The data is read in chunks from @a hVfsIosSrc and written to @a hVfsIosDst
1209	* until @a hVfsIosSrc indicates end of stream.
1210	*
1211	* @returns IPRT status code
1212	*
1213	* @param hVfsIosSrc The input stream.
1214	* @param hVfsIosDst The output stream.
1215	* @param cbBufHint Hints at a good temporary buffer size, pass 0 if
1216	* clueless.
1217	*/
1218	RTDECL(int) RTVfsUtilPumpIoStreams(RTVFSIOSTREAM hVfsIosSrc, RTVFSIOSTREAM hVfsIosDst, size_t cbBufHint);
1219
1220	/**
1221	* Create an I/O stream instance performing simple sequential read-ahead.
1222	*
1223	* @returns IPRT status code.
1224	* @param hVfsIos The input stream to perform read ahead on. If this is
1225	* actually for a file object, the returned I/O stream
1226	* handle can also be cast to a file handle.
1227	* @param fFlags Flags reserved for future use, MBZ.
1228	* @param cBuffers How many read ahead buffers to use. Specify 0 for
1229	* default value.
1230	* @param cbBuffer The size of each read ahead buffer. Specify 0 for
1231	* default value.
1232	* @param phVfsIos Where to return the read ahead I/O stream handle.
1233	*
1234	* @remarks Careful using this on a message pipe or socket. The reads are
1235	* performed in blocked mode and it may be host and/or implementation
1236	* dependent whether they will return ready data immediate or wait
1237	* until there's a whole @a cbBuffer (or default) worth ready.
1238	*
1239	* @sa RTVfsCreateReadAheadForFile
1240	*/
1241	RTDECL(int) RTVfsCreateReadAheadForIoStream(RTVFSIOSTREAM hVfsIos, uint32_t fFlags, uint32_t cBuffers, uint32_t cbBuffer,
1242	PRTVFSIOSTREAM phVfsIos);
1243
1244	/**
1245	* Create an I/O stream instance performing simple sequential read-ahead.
1246	*
1247	* @returns IPRT status code.
1248	* @param hVfsFile The input file to perform read ahead on.
1249	* @param fFlags Flags reserved for future use, MBZ.
1250	* @param cBuffers How many read ahead buffers to use. Specify 0 for
1251	* default value.
1252	* @param cbBuffer The size of each read ahead buffer. Specify 0 for
1253	* default value.
1254	* @param phVfsFile Where to return the read ahead file handle.
1255	* @sa RTVfsCreateReadAheadForIoStream
1256	*/
1257	RTDECL(int) RTVfsCreateReadAheadForFile(RTVFSFILE hVfsFile, uint32_t fFlags, uint32_t cBuffers, uint32_t cbBuffer,
1258	PRTVFSFILE phVfsFile);
1259
1260	/** @} */
1261
1262
1263	/** @defgroup grp_rt_vfs_chain VFS Chains
1264	*
1265	* VFS chains is for doing pipe like things with VFS objects from the command
1266	* line. Imagine you want to cat the readme.gz of an ISO you could do
1267	* something like:
1268	* RTCat :iprtvfs:file(stdfile,live.iso)\|vfs(isofs)\|iso(open,readme.gz)\|ios(gunzip)
1269	* or
1270	* RTCat :iprtvfs:file(stdfile,live.iso)\|ios(isofs,readme.gz)\|ios(gunzip)
1271	*
1272	* Or say you want to read the README.TXT on a floppy image:
1273	* RTCat :iprtvfs:file(stdfile,floppy.img,r)\|vfs(fat)\|ios(open,README.TXT)
1274	* or
1275	* RTCat :iprtvfs:file(stdfile,floppy.img,r)\|vfs(fat)\|README.TXT
1276	*
1277	* Or in the other direction, you want to write a STUFF.TGZ file to the above
1278	* floppy image, using a lazy writer thread for compressing the data:
1279	* RTTar cf :iprtvfs:file(stdfile,floppy.img,rw)\|ios(fat,STUFF.TGZ)\|ios(gzip)\|ios(push) .
1280	*
1281	*
1282	* A bit more formally:
1283	* :iprtvfs:{type}({provider}[,provider-args])[{separator}{type}...][{separator}{path}]
1284	*
1285	* The @c type refers to VFS object that should be created by the @c provider.
1286	* Valid types:
1287	* - vfs: A virtual file system (volume).
1288	* - fss: A file system stream (e.g. tar).
1289	* - ios: An I/O stream.
1290	* - file: A file.
1291	* - dir: A directory.
1292	* - sym: A symbolic link (not sure how useful this is).
1293	*
1294	* The @c provider refers to registered chain element providers (see
1295	* RTVFSCHAINELEMENTREG for how that works internally). These are asked to
1296	* create a VFS object of the specified type using the given arguments (if any).
1297	* Default providers:
1298	* - std: Standard file, directory and file system.
1299	* - open: Opens a file, I/O stream or directory in a vfs or directory object.
1300	* - pull: Read-ahead buffering thread on file or I/O stream.
1301	* - push: Lazy-writer buffering thread on file or I/O stream.
1302	* - gzip: Compresses an I/O stream.
1303	* - gunzip: Decompresses an I/O stream.
1304	* - fat: FAT file system accessor.
1305	* - isofs: ISOFS file system accessor.
1306	*
1307	* As element @c separator we allow both colon (':') and the pipe character
1308	* ('\|'). The latter the conventional one, but since it's inconvenient on the
1309	* command line, colon is provided as an alternative.
1310	*
1311	* In the final element we allow a simple @a path to be specified instead of the
1312	* type-provider-arguments stuff. The previous object must be a directory, file
1313	* system or file system stream. The application will determin exactly which
1314	* operation or operations which will be performed.
1315	*
1316	* @{
1317	*/
1318
1319	/** The path prefix used to identify an VFS chain specification. */
1320	#define RTVFSCHAIN_SPEC_PREFIX ":iprtvfs:"
1321
1322	RTDECL(int) RTVfsChainOpenVfs(const char pszSpec, PRTVFS phVfs, uint32_t poffError, PRTERRINFO pErrInfo);
1323	RTDECL(int) RTVfsChainOpenFsStream(const char pszSpec, PRTVFSFSSTREAM phVfsFss, uint32_t poffError, PRTERRINFO pErrInfo);
1324	RTDECL(int) RTVfsChainOpenDir(const char pszSpec, uint32_t fOpen, PRTVFSDIR phVfsDir, uint32_t poffError, PRTERRINFO pErrInfo);
1325	RTDECL(int) RTVfsChainOpenFile(const char pszSpec, uint64_t fOpen, PRTVFSFILE phVfsFile, uint32_t poffError, PRTERRINFO pErrInfo);
1326	RTDECL(int) RTVfsChainOpenIoStream(const char pszSpec, uint64_t fOpen, PRTVFSIOSTREAM phVfsIos, uint32_t poffError, PRTERRINFO pErrInfo);
1327	RTDECL(int) RTVfsChainOpenSymlink(const char pszSpec, PRTVFSSYMLINK phVfsSym, uint32_t poffError, PRTERRINFO pErrInfo);
1328
1329	RTDECL(int) RTVfsChainQueryInfo(const char *pszSpec, PRTFSOBJINFO pObjInfo, RTFSOBJATTRADD enmAdditionalAttribs,
1330	uint32_t fFlags, uint32_t *poffError, PRTERRINFO pErrInfo);
1331
1332	/**
1333	* Tests if the given string is a chain specification or not.
1334	*
1335	* @returns true if it is, false if it isn't.
1336	* @param pszSpec The alleged chain spec.
1337	*/
1338	RTDECL(bool) RTVfsChainIsSpec(const char *pszSpec);
1339
1340	/**
1341	* Queries the path from the final element.
1342	*
1343	* @returns IPRT status code.
1344	* @retval VERR_VFS_CHAIN_NOT_PATH_ONLY if the final element isn't just a
1345	* simple path.
1346	* @param pszSpec The chain spec.
1347	* @param ppszFinalPath Where to return a copy of the final path on success.
1348	* Call RTStrFree when done.
1349	* @param poffError Where to on error return an offset into @a pszSpec
1350	* of what cause the error. Optional.
1351	*
1352	*/
1353	RTDECL(int) RTVfsChainQueryFinalPath(const char pszSpec, char ppszFinalPath, uint32_t poffError);
1354
1355	/**
1356	* Common code for reporting errors of a RTVfsChainOpen* API.
1357	*
1358	* @param pszFunction The API called.
1359	* @param pszSpec The VFS chain specification or file path passed to the.
1360	* @param rc The return code.
1361	* @param offError The error offset value returned (0 if not captured).
1362	* @param pErrInfo Additional error information. Optional.
1363	*
1364	* @sa RTVfsChainMsgErrorExitFailure
1365	* @sa RTVfsChainOpenVfs, RTVfsChainOpenFsStream, RTVfsChainOpenDir,
1366	* RTVfsChainOpenFile, RTVfsChainOpenIoStream, RTVfsChainOpenSymlink
1367	*/
1368	RTDECL(void) RTVfsChainMsgError(const char pszFunction, const char pszSpec, int rc, uint32_t offError, PRTERRINFO pErrInfo);
1369
1370	/**
1371	* Common code for reporting errors of a RTVfsChainOpen* API.
1372	*
1373	* @returns RTEXITCODE_FAILURE
1374	*
1375	* @param pszFunction The API called.
1376	* @param pszSpec The VFS chain specification or file path passed to the.
1377	* @param rc The return code.
1378	* @param offError The error offset value returned (0 if not captured).
1379	* @param pErrInfo Additional error information. Optional.
1380	*
1381	* @sa RTVfsChainMsgError
1382	* @sa RTVfsChainOpenVfs, RTVfsChainOpenFsStream, RTVfsChainOpenDir,
1383	* RTVfsChainOpenFile, RTVfsChainOpenIoStream, RTVfsChainOpenSymlink
1384	*/
1385	RTDECL(RTEXITCODE) RTVfsChainMsgErrorExitFailure(const char pszFunction, const char pszSpec,
1386	int rc, uint32_t offError, PRTERRINFO pErrInfo);
1387
1388
1389	/** @} */
1390
1391
1392	/** @} */
1393
1394	RT_C_DECLS_END
1395
1396	#endif /* !___iprt_vfs_h */
1397

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

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

Download in other formats: