vfs.h@ 66615

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

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

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

Download in other formats: