vfs.h@ 58803

Last change on this file since 58803 was 57944, checked in by vboxsync, 9 years ago
iprt: More doxygen corrections.
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 36.5 KB

Line
1	/** @file
2	* IPRT - Virtual Filesystem.
3	*/
4
5	/*
6	* Copyright (C) 2010-2015 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
334
335	/** @defgroup grp_vfs_symlink VFS Symbolic Link API
336	*
337	* @remarks The TAR VFS and filesystem stream uses symbolic links for
338	* describing hard links as well. The users must use RTFS_IS_SYMLINK
339	* to check if it is a real symlink in those cases.
340	*
341	* @remarks Any VFS which is backed by a real file system may be subject to
342	* races with other processes or threads, so the user may get
343	* unexpected errors when this happends. This is a bit host specific,
344	* i.e. it might be prevent on windows if we care.
345	*
346	* @{
347	*/
348
349
350	/**
351	* Retains a reference to the VFS symbolic link handle.
352	*
353	* @returns New reference count on success, UINT32_MAX on failure.
354	* @param hVfsSym The VFS symbolic link handle.
355	*/
356	RTDECL(uint32_t) RTVfsSymlinkRetain(RTVFSSYMLINK hVfsSym);
357
358	/**
359	* Releases a reference to the VFS symbolic link handle.
360	*
361	* @returns New reference count on success (0 if closed), UINT32_MAX on failure.
362	* @param hVfsSym The VFS symbolic link handle.
363	*/
364	RTDECL(uint32_t) RTVfsSymlinkRelease(RTVFSSYMLINK hVfsSym);
365
366	/**
367	* Query information about the symbolic link.
368	*
369	* @returns IPRT status code.
370	* @param hVfsSym The VFS symbolic link handle.
371	* @param pObjInfo Where to return the info.
372	* @param enmAddAttr Which additional attributes should be retrieved.
373	*
374	* @sa RTFileQueryInfo, RTPathQueryInfo, RTPathQueryInfoEx
375	*/
376	RTDECL(int) RTVfsSymlinkQueryInfo(RTVFSSYMLINK hVfsSym, PRTFSOBJINFO pObjInfo, RTFSOBJATTRADD enmAddAttr);
377
378	/**
379	* Set the unix style owner and group.
380	*
381	* @returns IPRT status code.
382	* @param hVfsSym The VFS symbolic link handle.
383	* @param fMode The new mode bits.
384	* @param fMask The mask indicating which bits we are changing.
385	* @sa RTFileSetMode, RTPathSetMode
386	*/
387	RTDECL(int) RTVfsSymlinkSetMode(RTVFSSYMLINK hVfsSym, RTFMODE fMode, RTFMODE fMask);
388
389	/**
390	* Set the timestamps associated with the object.
391	*
392	* @returns IPRT status code.
393	* @param hVfsSym The VFS symbolic link handle.
394	* @param pAccessTime Pointer to the new access time. NULL if not
395	* to be changed.
396	* @param pModificationTime Pointer to the new modifcation time. NULL if
397	* not to be changed.
398	* @param pChangeTime Pointer to the new change time. NULL if not to be
399	* changed.
400	* @param pBirthTime Pointer to the new time of birth. NULL if not to be
401	* changed.
402	* @remarks See RTFileSetTimes for restrictions and behavior imposed by the
403	* host OS or underlying VFS provider.
404	* @sa RTFileSetTimes, RTPathSetTimes
405	*/
406	RTDECL(int) RTVfsSymlinkSetTimes(RTVFSSYMLINK hVfsSym, PCRTTIMESPEC pAccessTime, PCRTTIMESPEC pModificationTime,
407	PCRTTIMESPEC pChangeTime, PCRTTIMESPEC pBirthTime);
408
409	/**
410	* Set the unix style owner and group.
411	*
412	* @returns IPRT status code.
413	* @param hVfsSym The VFS symbolic link handle.
414	* @param uid The user ID of the new owner. NIL_RTUID if
415	* unchanged.
416	* @param gid The group ID of the new owner group. NIL_RTGID if
417	* unchanged.
418	* @sa RTFileSetOwner, RTPathSetOwner.
419	*/
420	RTDECL(int) RTVfsSymlinkSetOwner(RTVFSSYMLINK hVfsSym, RTUID uid, RTGID gid);
421
422	/**
423	* Read the symbolic link target.
424	*
425	* @returns IPRT status code.
426	* @param hVfsSym The VFS symbolic link handle.
427	* @param pszTarget The target buffer.
428	* @param cbTarget The size of the target buffer.
429	* @sa RTSymlinkRead
430	*/
431	RTDECL(int) RTVfsSymlinkRead(RTVFSSYMLINK hVfsSym, char *pszTarget, size_t cbTarget);
432
433	/** @} */
434
435
436
437	/** @defgroup grp_vfs_iostream VFS I/O Stream API
438	* @{
439	*/
440
441	/**
442	* Creates a VFS I/O stream handle from a standard IPRT file handle (RTFILE).
443	*
444	* @returns IPRT status code.
445	* @param hFile The standard IPRT file handle.
446	* @param fOpen The flags the handle was opened with. Pass 0 to
447	* have these detected.
448	* @param fLeaveOpen Whether to leave the handle open when the VFS file
449	* is released, or to close it (@c false).
450	* @param phVfsIos Where to return the VFS I/O stream handle.
451	*/
452	RTDECL(int) RTVfsIoStrmFromRTFile(RTFILE hFile, uint64_t fOpen, bool fLeaveOpen, PRTVFSIOSTREAM phVfsIos);
453
454	/**
455	* Creates a VFS I/O stream handle from a standard IPRT pipe handle (RTPIPE).
456	*
457	* @returns IPRT status code.
458	* @param hPipe The standard IPRT pipe handle.
459	* @param fLeaveOpen Whether to leave the handle open when the VFS file
460	* is released, or to close it (@c false).
461	* @param phVfsIos Where to return the VFS I/O stream handle.
462	*/
463	RTDECL(int) RTVfsIoStrmFromRTPipe(RTPIPE hPipe, bool fLeaveOpen, PRTVFSIOSTREAM phVfsIos);
464
465	/**
466	* Convenience function combining RTFileOpen with RTVfsIoStrmFromRTFile.
467	*
468	* @returns IPRT status code.
469	* @param pszFilename The path to the file in the normal file system.
470	* @param fOpen The flags to pass to RTFileOpen when opening the
471	* file, i.e. RTFILE_O_XXX.
472	* @param phVfsIos Where to return the VFS I/O stream handle.
473	*/
474	RTDECL(int) RTVfsIoStrmOpenNormal(const char *pszFilename, uint64_t fOpen, PRTVFSIOSTREAM phVfsIos);
475
476	/**
477	* Create a VFS I/O stream handle from one of the standard handles.
478	*
479	* @returns IPRT status code.
480	* @param enmStdHandle The standard IPRT file handle.
481	* @param fOpen The flags the handle was opened with. Pass 0 to
482	* have these detected.
483	* @param fLeaveOpen Whether to leave the handle open when the VFS file
484	* is released, or to close it (@c false).
485	* @param phVfsIos Where to return the VFS I/O stream handle.
486	*/
487	RTDECL(int) RTVfsIoStrmFromStdHandle(RTHANDLESTD enmStdHandle, uint64_t fOpen, bool fLeaveOpen,
488	PRTVFSIOSTREAM phVfsIos);
489
490	/**
491	* Retains a reference to the VFS I/O stream handle.
492	*
493	* @returns New reference count on success, UINT32_MAX on failure.
494	* @param hVfsIos The VFS I/O stream handle.
495	*/
496	RTDECL(uint32_t) RTVfsIoStrmRetain(RTVFSIOSTREAM hVfsIos);
497
498	/**
499	* Releases a reference to the VFS I/O stream handle.
500	*
501	* @returns New reference count on success (0 if closed), UINT32_MAX on failure.
502	* @param hVfsIos The VFS I/O stream handle.
503	*/
504	RTDECL(uint32_t) RTVfsIoStrmRelease(RTVFSIOSTREAM hVfsIos);
505
506	/**
507	* Convert the VFS I/O stream handle to a VFS file handle.
508	*
509	* @returns The VFS file handle on success, this must be released.
510	* NIL_RTVFSFILE if the I/O stream handle is invalid.
511	* @param hVfsIos The VFS I/O stream handle.
512	* @sa RTVfsFileToIoStream
513	*/
514	RTDECL(RTVFSFILE) RTVfsIoStrmToFile(RTVFSIOSTREAM hVfsIos);
515
516	/**
517	* Query information about the I/O stream.
518	*
519	* @returns IPRT status code.
520	* @param hVfsIos The VFS I/O stream handle.
521	* @param pObjInfo Where to return the info.
522	* @param enmAddAttr Which additional attributes should be retrieved.
523	* @sa RTFileQueryInfo
524	*/
525	RTDECL(int) RTVfsIoStrmQueryInfo(RTVFSIOSTREAM hVfsIos, PRTFSOBJINFO pObjInfo, RTFSOBJATTRADD enmAddAttr);
526
527	/**
528	* Read bytes from the I/O stream.
529	*
530	* @returns IPRT status code.
531	* @retval VINF_SUCCESS and the number of bytes read written to @a pcbRead.
532	* @retval VINF_TRY_AGAIN if @a fBlocking is @c false, @a pcbRead is not NULL,
533	* and no data was available. @a *pcbRead will be set to 0.
534	* @retval VINF_EOF when trying to read __beyond__ the end of the stream and
535	* @a pcbRead is not NULL (it will be set to the number of bytes read,
536	* or 0 if the end of the stream was reached before this call).
537	* When the last byte of the read request is the last byte in the
538	* stream, this status code will not be used. However, VINF_EOF is
539	* returned when attempting to read 0 bytes while standing at the end
540	* of the stream.
541	* @retval VERR_EOF when trying to read __beyond__ the end of the stream and
542	* @a pcbRead is NULL.
543	* @retval VERR_ACCESS_DENIED if the stream is not readable.
544	*
545	* @param hVfsIos The VFS I/O stream handle.
546	* @param pvBuf Where to store the read bytes.
547	* @param cbToRead The number of bytes to read.
548	* @param fBlocking Whether the call is blocking (@c true) or not. If
549	* not, the @a pcbRead parameter must not be NULL.
550	* @param pcbRead Where to always store the number of bytes actually
551	* read. This can be NULL if @a fBlocking is true.
552	* @sa RTVfsFileRead, RTFileRead, RTPipeRead, RTPipeReadBlocking,
553	* RTSocketRead
554	*/
555	RTDECL(int) RTVfsIoStrmRead(RTVFSIOSTREAM hVfsIos, void pvBuf, size_t cbToRead, bool fBlocking, size_t pcbRead);
556	RTDECL(int) RTVfsIoStrmReadAt(RTVFSIOSTREAM hVfsIos, RTFOFF off, void pvBuf, size_t cbToRead, bool fBlocking, size_t pcbRead);
557
558	/**
559	* Write bytes to the I/O stream.
560	*
561	* @returns IPRT status code.
562	* @retval VERR_ACCESS_DENIED if the stream is not writable.
563	*
564	* @param hVfsIos The VFS I/O stream handle.
565	* @param pvBuf The bytes to write.
566	* @param cbToWrite The number of bytes to write.
567	* @param fBlocking Whether the call is blocking (@c true) or not. If
568	* not, the @a pcbWritten parameter must not be NULL.
569	* @param pcbWritten Where to always store the number of bytes actually
570	* written. This can be NULL if @a fBlocking is true.
571	* @sa RTVfsFileWrite, RTFileWrite, RTPipeWrite, RTPipeWriteBlocking,
572	* RTSocketWrite
573	*/
574	RTDECL(int) RTVfsIoStrmWrite(RTVFSIOSTREAM hVfsIos, const void pvBuf, size_t cbToWrite, bool fBlocking, size_t pcbWritten);
575	RTDECL(int) RTVfsIoStrmWriteAt(RTVFSIOSTREAM hVfsIos, RTFOFF off, const void pvBuf, size_t cbToWrite, bool fBlocking, size_t pcbWritten);
576
577	/**
578	* Reads bytes from the I/O stream into a scatter buffer.
579	*
580	* @returns IPRT status code.
581	* @retval VINF_SUCCESS and the number of bytes read written to @a pcbRead.
582	* @retval VINF_TRY_AGAIN if @a fBlocking is @c false, @a pcbRead is not NULL,
583	* and no data was available. @a *pcbRead will be set to 0.
584	* @retval VINF_EOF when trying to read __beyond__ the end of the stream and
585	* @a pcbRead is not NULL (it will be set to the number of bytes read,
586	* or 0 if the end of the stream was reached before this call).
587	* When the last byte of the read request is the last byte in the
588	* stream, this status code will not be used. However, VINF_EOF is
589	* returned when attempting to read 0 bytes while standing at the end
590	* of the stream.
591	* @retval VERR_EOF when trying to read __beyond__ the end of the stream and
592	* @a pcbRead is NULL.
593	* @retval VERR_ACCESS_DENIED if the stream is not readable.
594	*
595	* @param hVfsIos The VFS I/O stream handle.
596	* @param pSgBuf Pointer to a scatter buffer descriptor. The number
597	* of bytes described by the segments is what will be
598	* attemted read.
599	* @param fBlocking Whether the call is blocking (@c true) or not. If
600	* not, the @a pcbRead parameter must not be NULL.
601	* @param pcbRead Where to always store the number of bytes actually
602	* read. This can be NULL if @a fBlocking is true.
603	* @sa RTFileSgRead, RTSocketSgRead, RTPipeRead, RTPipeReadBlocking
604	*/
605	RTDECL(int) RTVfsIoStrmSgRead(RTVFSIOSTREAM hVfsIos, PCRTSGBUF pSgBuf, bool fBlocking, size_t *pcbRead);
606
607	/**
608	* Write bytes to the I/O stream from a gather buffer.
609	*
610	* @returns IPRT status code.
611	* @retval VERR_ACCESS_DENIED if the stream is not writable.
612	*
613	* @param hVfsIos The VFS I/O stream handle.
614	* @param pSgBuf Pointer to a gather buffer descriptor. The number
615	* of bytes described by the segments is what will be
616	* attemted written.
617	* @param fBlocking Whether the call is blocking (@c true) or not. If
618	* not, the @a pcbWritten parameter must not be NULL.
619	* @param pcbWritten Where to always store the number of bytes actually
620	* written. This can be NULL if @a fBlocking is true.
621	* @sa RTFileSgWrite, RTSocketSgWrite
622	*/
623	RTDECL(int) RTVfsIoStrmSgWrite(RTVFSIOSTREAM hVfsIos, PCRTSGBUF pSgBuf, bool fBlocking, size_t *pcbWritten);
624
625	/**
626	* Flush any buffered data to the I/O stream.
627	*
628	* @returns IPRT status code.
629	* @param hVfsIos The VFS I/O stream handle.
630	* @sa RTVfsFileFlush, RTFileFlush, RTPipeFlush
631	*/
632	RTDECL(int) RTVfsIoStrmFlush(RTVFSIOSTREAM hVfsIos);
633
634	/**
635	* Poll for events.
636	*
637	* @returns IPRT status code.
638	* @param hVfsIos The VFS I/O stream handle.
639	* @param fEvents The events to poll for (RTPOLL_EVT_XXX).
640	* @param cMillies How long to wait for event to eventuate.
641	* @param fIntr Whether the wait is interruptible and can return
642	* VERR_INTERRUPTED (@c true) or if this condition
643	* should be hidden from the caller (@c false).
644	* @param pfRetEvents Where to return the event mask.
645	* @sa RTVfsFilePoll, RTPollSetAdd, RTPoll, RTPollNoResume.
646	*/
647	RTDECL(int) RTVfsIoStrmPoll(RTVFSIOSTREAM hVfsIos, uint32_t fEvents, RTMSINTERVAL cMillies, bool fIntr,
648	uint32_t *pfRetEvents);
649	/**
650	* Tells the current I/O stream position.
651	*
652	* @returns Zero or higher - where to return the I/O stream offset. Values
653	* below zero are IPRT status codes (VERR_XXX).
654	* @param hVfsIos The VFS I/O stream handle.
655	* @sa RTFileTell
656	*/
657	RTDECL(RTFOFF) RTVfsIoStrmTell(RTVFSIOSTREAM hVfsIos);
658
659	/**
660	* Skips @a cb ahead in the stream.
661	*
662	* @returns IPRT status code.
663	* @param hVfsIos The VFS I/O stream handle.
664	* @param cb The number bytes to skip.
665	*/
666	RTDECL(int) RTVfsIoStrmSkip(RTVFSIOSTREAM hVfsIos, RTFOFF cb);
667
668	/**
669	* Fills the stream with @a cb zeros.
670	*
671	* @returns IPRT status code.
672	* @param hVfsIos The VFS I/O stream handle.
673	* @param cb The number of zero bytes to insert.
674	*/
675	RTDECL(int) RTVfsIoStrmZeroFill(RTVFSIOSTREAM hVfsIos, RTFOFF cb);
676
677	/**
678	* Checks if we're at the end of the I/O stream.
679	*
680	* @returns true if at EOS, otherwise false.
681	* @param hVfsIos The VFS I/O stream handle.
682	*/
683	RTDECL(bool) RTVfsIoStrmIsAtEnd(RTVFSIOSTREAM hVfsIos);
684
685	/**
686	* Process the rest of the stream, checking if it's all valid UTF-8 encoding.
687	*
688	* @returns VBox status cod.e
689	*
690	* @param hVfsIos The VFS I/O stream handle.
691	* @param fFlags Flags governing the validation, see
692	* RTVFS_VALIDATE_UTF8_XXX.
693	* @param poffError Where to return the error offset. Optional.
694	*/
695	RTDECL(int) RTVfsIoStrmValidateUtf8Encoding(RTVFSIOSTREAM hVfsIos, uint32_t fFlags, PRTFOFF poffError);
696
697	/** @defgroup RTVFS_VALIDATE_UTF8_XXX RTVfsIoStrmValidateUtf8Encoding flags.
698	* @{ */
699	/** The text must not contain any null terminator codepoints. */
700	#define RTVFS_VALIDATE_UTF8_NO_NULL RT_BIT_32(0)
701	/** The codepoints must be in the range covered by RTC-3629. */
702	#define RTVFS_VALIDATE_UTF8_BY_RTC_3629 RT_BIT_32(1)
703	/** Mask of valid flags. */
704	#define RTVFS_VALIDATE_UTF8_VALID_MASK UINT32_C(0x00000003)
705	/** @} */
706
707	/** @} */
708
709
710	/** @defgroup grp_vfs_file VFS File API
711	* @{
712	*/
713	RTDECL(int) RTVfsFileOpen(RTVFS hVfs, const char *pszFilename, uint64_t fOpen, PRTVFSFILE phVfsFile);
714
715	/**
716	* Create a VFS file handle from a standard IPRT file handle (RTFILE).
717	*
718	* @returns IPRT status code.
719	* @param hFile The standard IPRT file handle.
720	* @param fOpen The flags the handle was opened with. Pass 0 to
721	* have these detected.
722	* @param fLeaveOpen Whether to leave the handle open when the VFS file
723	* is released, or to close it (@c false).
724	* @param phVfsFile Where to return the VFS file handle.
725	*/
726	RTDECL(int) RTVfsFileFromRTFile(RTFILE hFile, uint64_t fOpen, bool fLeaveOpen, PRTVFSFILE phVfsFile);
727	RTDECL(RTHCUINTPTR) RTVfsFileToNative(RTFILE hVfsFile);
728
729	/**
730	* Convenience function combining RTFileOpen with RTVfsFileFromRTFile.
731	*
732	* @returns IPRT status code.
733	* @param pszFilename The path to the file in the normal file system.
734	* @param fOpen The flags to pass to RTFileOpen when opening the
735	* file, i.e. RTFILE_O_XXX.
736	* @param phVfsFile Where to return the VFS file handle.
737	*/
738	RTDECL(int) RTVfsFileOpenNormal(const char *pszFilename, uint64_t fOpen, PRTVFSFILE phVfsFile);
739
740	/**
741	* Convert the VFS file handle to a VFS I/O stream handle.
742	*
743	* @returns The VFS I/O stream handle on success, this must be released.
744	* NIL_RTVFSIOSTREAM if the file handle is invalid.
745	* @param hVfsFile The VFS file handle.
746	* @sa RTVfsIoStrmToFile
747	*/
748	RTDECL(RTVFSIOSTREAM) RTVfsFileToIoStream(RTVFSFILE hVfsFile);
749
750	/**
751	* Retains a reference to the VFS file handle.
752	*
753	* @returns New reference count on success, UINT32_MAX on failure.
754	* @param hVfsFile The VFS file handle.
755	*/
756	RTDECL(uint32_t) RTVfsFileRetain(RTVFSFILE hVfsFile);
757
758	/**
759	* Releases a reference to the VFS file handle.
760	*
761	* @returns New reference count on success (0 if closed), UINT32_MAX on failure.
762	* @param hVfsFile The VFS file handle.
763	*/
764	RTDECL(uint32_t) RTVfsFileRelease(RTVFSFILE hVfsFile);
765
766	/**
767	* Query information about the object.
768	*
769	* @returns IPRT status code.
770	* @retval VERR_NOT_SUPPORTED if the @a enmAddAttr value is not handled by the
771	* implementation.
772	*
773	* @param hVfsFile The VFS file handle.
774	* @param pObjInfo Where to return the info.
775	* @param enmAddAttr Which additional attributes should be retrieved.
776	* @sa RTVfsObjQueryInfo, RTVfsFsStrmQueryInfo, RTVfsDirQueryInfo,
777	* RTVfsIoStrmQueryInfo, RTVfsFileQueryInfo, RTFileQueryInfo,
778	* RTPathQueryInfo.
779	*/
780	RTDECL(int) RTVfsFileQueryInfo(RTVFSFILE hVfsFile, PRTFSOBJINFO pObjInfo, RTFSOBJATTRADD enmAddAttr);
781
782	/**
783	* Read bytes from the file at the current position.
784	*
785	* @returns IPRT status code.
786	* @retval VINF_SUCCESS and the number of bytes read written to @a pcbRead.
787	* @retval VINF_TRY_AGAIN if @a fBlocking is @c false, @a pcbRead is not NULL,
788	* and no data was available. @a *pcbRead will be set to 0.
789	* @retval VINF_EOF when trying to read __beyond__ the end of the file and
790	* @a pcbRead is not NULL (it will be set to the number of bytes read,
791	* or 0 if the end of the file was reached before this call).
792	* When the last byte of the read request is the last byte in the
793	* file, this status code will not be used. However, VINF_EOF is
794	* returned when attempting to read 0 bytes while standing at the end
795	* of the file.
796	* @retval VERR_EOF when trying to read __beyond__ the end of the file and
797	* @a pcbRead is NULL.
798	* @retval VERR_ACCESS_DENIED if the file is not readable.
799	*
800	* @param hVfsFile The VFS file handle.
801	* @param pvBuf Where to store the read bytes.
802	* @param cbToRead The number of bytes to read.
803	* @param pcbRead Where to always store the number of bytes actually
804	* read. Optional.
805	* @sa RTVfsIoStrmRead, RTFileRead, RTPipeRead, RTPipeReadBlocking,
806	* RTSocketRead
807	*/
808	RTDECL(int) RTVfsFileRead(RTVFSFILE hVfsFile, void pvBuf, size_t cbToRead, size_t pcbRead);
809	RTDECL(int) RTVfsFileReadAt(RTVFSFILE hVfsFile, RTFOFF off, void pvBuf, size_t cbToRead, size_t pcbRead);
810
811	/**
812	* Write bytes to the file at the current position.
813	*
814	* @returns IPRT status code.
815	* @retval VERR_ACCESS_DENIED if the file is not writable.
816	*
817	* @param hVfsFile The VFS file handle.
818	* @param pvBuf The bytes to write.
819	* @param cbToWrite The number of bytes to write.
820	* @param pcbWritten Where to always store the number of bytes actually
821	* written. This can be NULL.
822	* @sa RTVfsIoStrmRead, RTFileWrite, RTPipeWrite, RTPipeWriteBlocking,
823	* RTSocketWrite
824	*/
825	RTDECL(int) RTVfsFileWrite(RTVFSFILE hVfsFile, const void pvBuf, size_t cbToWrite, size_t pcbWritten);
826	RTDECL(int) RTVfsFileWriteAt(RTVFSFILE hVfsFile, RTFOFF off, const void pvBuf, size_t cbToWrite, size_t pcbWritten);
827
828	/**
829	* Flush any buffered data to the file.
830	*
831	* @returns IPRT status code.
832	* @param hVfsFile The VFS file handle.
833	* @sa RTVfsIoStrmFlush, RTFileFlush, RTPipeFlush
834	*/
835	RTDECL(int) RTVfsFileFlush(RTVFSFILE hVfsFile);
836
837	/**
838	* Poll for events.
839	*
840	* @returns IPRT status code.
841	* @param hVfsFile The VFS file handle.
842	* @param fEvents The events to poll for (RTPOLL_EVT_XXX).
843	* @param cMillies How long to wait for event to eventuate.
844	* @param fIntr Whether the wait is interruptible and can return
845	* VERR_INTERRUPTED (@c true) or if this condition
846	* should be hidden from the caller (@c false).
847	* @param pfRetEvents Where to return the event mask.
848	* @sa RTVfsIoStrmPoll, RTPollSetAdd, RTPoll, RTPollNoResume.
849	*/
850	RTDECL(RTFOFF) RTVfsFilePoll(RTVFSFILE hVfsFile, uint32_t fEvents, RTMSINTERVAL cMillies, bool fIntr,
851	uint32_t *pfRetEvents);
852
853	/**
854	* Tells the current file position.
855	*
856	* @returns Zero or higher - where to return the file offset. Values
857	* below zero are IPRT status codes (VERR_XXX).
858	* @param hVfsFile The VFS file handle.
859	* @sa RTFileTell, RTVfsIoStrmTell.
860	*/
861	RTDECL(RTFOFF) RTVfsFileTell(RTVFSFILE hVfsFile);
862
863	/**
864	* Changes the current read/write position of a file.
865	*
866	* @returns IPRT status code.
867	*
868	* @param hVfsFile The VFS file handle.
869	* @param offSeek The seek offset.
870	* @param uMethod The seek emthod.
871	* @param poffActual Where to optionally return the new file offset.
872	*
873	* @sa RTFileSeek
874	*/
875	RTDECL(int) RTVfsFileSeek(RTVFSFILE hVfsFile, RTFOFF offSeek, uint32_t uMethod, uint64_t *poffActual);
876
877	RTDECL(int) RTVfsFileSetSize(RTVFSFILE hVfsFile, uint64_t cbSize);
878	RTDECL(int) RTVfsFileGetSize(RTVFSFILE hVfsFile, uint64_t *pcbSize);
879	RTDECL(RTFOFF) RTVfsFileGetMaxSize(RTVFSFILE hVfsFile);
880	RTDECL(int) RTVfsFileGetMaxSizeEx(RTVFSFILE hVfsFile, PRTFOFF pcbMax);
881
882	/** @} */
883
884
885	/** @defgroup grp_vfs_misc VFS Miscellaneous
886	* @{
887	*/
888
889	/**
890	* Memorizes the I/O stream as a file backed by memory.
891	*
892	* @returns VBox status code.
893	*
894	* @param hVfsIos The VFS I/O stream to memorize. This will be read
895	* to the end on success, on failure its position is
896	* undefined.
897	* @param fFlags A combination of RTFILE_O_READ and RTFILE_O_WRITE.
898	* @param phVfsFile Where to return the handle to the memory file on
899	* success.
900	*/
901	RTDECL(int) RTVfsMemorizeIoStreamAsFile(RTVFSIOSTREAM hVfsIos, uint32_t fFlags, PRTVFSFILE phVfsFile);
902
903
904	/**
905	* Pumps data from one I/O stream to another.
906	*
907	* The data is read in chunks from @a hVfsIosSrc and written to @a hVfsIosDst
908	* until @a hVfsIosSrc indicates end of stream.
909	*
910	* @returns IPRT status code
911	*
912	* @param hVfsIosSrc The input stream.
913	* @param hVfsIosDst The output stream.
914	* @param cbBufHint Hints at a good temporary buffer size, pass 0 if
915	* clueless.
916	*/
917	RTDECL(int) RTVfsUtilPumpIoStreams(RTVFSIOSTREAM hVfsIosSrc, RTVFSIOSTREAM hVfsIosDst, size_t cbBufHint);
918
919	/** @} */
920
921
922	/** @defgroup grp_rt_vfs_chain VFS Chains
923	*
924	* VFS chains is for doing pipe like things with VFS objects from the command
925	* line. Imagine you want to cat the readme.gz of an ISO you could do
926	* something like:
927	* RTCat :iprtvfs:vfs(isofs,./mycd.iso)\|ios(open,readme.gz)\|ios(gunzip)
928	* or
929	* RTCat :iprtvfs:ios(isofs,./mycd.iso,/readme.gz)\|ios(gunzip)
930	*
931	* The "isofs", "open" and "gunzip" bits in the above examples are chain
932	* element providers registered with IPRT. See RTVFSCHAINELEMENTREG for how
933	* these works.
934	*
935	* @{ */
936
937	/** The path prefix used to identify an VFS chain specification. */
938	#define RTVFSCHAIN_SPEC_PREFIX ":iprtvfs:"
939
940	RTDECL(int) RTVfsChainOpenVfs( const char pszSpec, PRTVFS phVfs, const char *ppszError);
941	RTDECL(int) RTVfsChainOpenFsStream( const char pszSpec, PRTVFSFSSTREAM phVfsFss, const char *ppszError);
942	RTDECL(int) RTVfsChainOpenDir( const char pszSpec, uint64_t fOpen, PRTVFSDIR phVfsDir, const char *ppszError);
943	RTDECL(int) RTVfsChainOpenFile( const char pszSpec, uint64_t fOpen, PRTVFSFILE phVfsFile, const char *ppszError);
944	RTDECL(int) RTVfsChainOpenSymlink( const char pszSpec, PRTVFSSYMLINK phVfsSym, const char *ppszError);
945	RTDECL(int) RTVfsChainOpenIoStream( const char pszSpec, uint64_t fOpen, PRTVFSIOSTREAM phVfsIos, const char *ppszError);
946
947	/**
948	* Tests if the given string is a chain specification or not.
949	*
950	* @returns true if it is, false if it isn't.
951	* @param pszSpec The alleged chain spec.
952	*/
953	RTDECL(bool) RTVfsChainIsSpec(const char *pszSpec);
954
955	/** @} */
956
957
958	/** @} */
959
960	RT_C_DECLS_END
961
962	#endif /* !___iprt_vfs_h */
963

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

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

Download in other formats: