vfs.h@ 35517

Last change on this file since 35517 was 34967, checked in by vboxsync, 14 years ago
Moved and extended RTVfsIoStrmValidateUtf8Encoding.
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 34.8 KB

Line
1	/** @file
2	* IPRT - Virtual Filesystem.
3	*/
4
5	/*
6	* Copyright (C) 2010 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_fs 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	/** @defgroup grp_vfs_dir VFS Base Object API
122	* @{
123	*/
124
125	/**
126	* Retains a reference to the VFS base object handle.
127	*
128	* @returns New reference count on success, UINT32_MAX on failure.
129	* @param hVfsObj The VFS base object handle.
130	*/
131	RTDECL(uint32_t) RTVfsObjRetain(RTVFSOBJ hVfsObj);
132
133	/**
134	* Releases a reference to the VFS base handle.
135	*
136	* @returns New reference count on success (0 if closed), UINT32_MAX on failure.
137	* @param hVfsObj The VFS base object handle.
138	*/
139	RTDECL(uint32_t) RTVfsObjRelease(RTVFSOBJ hVfsObj);
140
141	/**
142	* Query information about the object.
143	*
144	* @returns IPRT status code.
145	* @retval VERR_NOT_SUPPORTED if the @a enmAddAttr value is not handled by the
146	* implementation.
147	*
148	* @param hVfsObj The VFS object handle.
149	* @param pObjInfo Where to return the info.
150	* @param enmAddAttr Which additional attributes should be retrieved.
151	* @sa RTVfsIoStrmQueryInfo, RTVfsFileQueryInfo, RTFileQueryInfo,
152	* RTPathQueryInfo
153	*/
154	RTDECL(int) RTVfsObjQueryInfo(RTVFSOBJ hVfsObj, PRTFSOBJINFO pObjInfo, RTFSOBJATTRADD enmAddAttr);
155
156
157	/**
158	* Converts a VFS base object handle to a VFS handle.
159	*
160	* @returns Referenced handle on success, NIL on failure.
161	* @param hVfsObj The VFS base object handle.
162	*/
163	RTDECL(RTVFS) RTVfsObjToVfs(RTVFSOBJ hVfsObj);
164
165	/**
166	* Converts a VFS base object handle to a VFS filesystem stream handle.
167	*
168	* @returns Referenced handle on success, NIL on failure.
169	* @param hVfsObj The VFS base object handle.
170	*/
171	RTDECL(RTVFSFSSTREAM) RTVfsObjToFsStream(RTVFSOBJ hVfsObj);
172
173	/**
174	* Converts a VFS base object handle to a VFS directory handle.
175	*
176	* @returns Referenced handle on success, NIL on failure.
177	* @param hVfsObj The VFS base object handle.
178	*/
179	RTDECL(RTVFSDIR) RTVfsObjToDir(RTVFSOBJ hVfsObj);
180
181	/**
182	* Converts a VFS base object handle to a VFS I/O stream handle.
183	*
184	* @returns Referenced handle on success, NIL on failure.
185	* @param hVfsObj The VFS base object handle.
186	*/
187	RTDECL(RTVFSIOSTREAM) RTVfsObjToIoStream(RTVFSOBJ hVfsObj);
188
189	/**
190	* Converts a VFS base object handle to a VFS file handle.
191	*
192	* @returns Referenced handle on success, NIL on failure.
193	* @param hVfsObj The VFS base object handle.
194	*/
195	RTDECL(RTVFSFILE) RTVfsObjToFile(RTVFSOBJ hVfsObj);
196
197	/**
198	* Converts a VFS base object handle to a VFS symbolic link handle.
199	*
200	* @returns Referenced handle on success, NIL on failure.
201	* @param hVfsObj The VFS base object handle.
202	*/
203	RTDECL(RTVFSSYMLINK) RTVfsObjToSymlink(RTVFSOBJ hVfsObj);
204
205
206	/**
207	* Converts a VFS handle to a VFS base object handle.
208	*
209	* @returns Referenced handle on success, NIL if the input handle was invalid.
210	* @param hVfs The VFS handle.
211	*/
212	RTDECL(RTVFSOBJ) RTVfsObjFromVfs(RTVFS hVfs);
213
214	/**
215	* Converts a VFS filesystem stream handle to a VFS base object handle.
216	*
217	* @returns Referenced handle on success, NIL if the input handle was invalid.
218	* @param hVfsFSs The VFS filesystem stream handle.
219	*/
220	RTDECL(RTVFSOBJ) RTVfsObjFromFsStream(RTVFSFSSTREAM hVfsFss);
221
222	/**
223	* Converts a VFS directory handle to a VFS base object handle.
224	*
225	* @returns Referenced handle on success, NIL if the input handle was invalid.
226	* @param hVfsDir The VFS directory handle.
227	*/
228	RTDECL(RTVFSOBJ) RTVfsObjFromDir(RTVFSDIR hVfsDir);
229
230	/**
231	* Converts a VFS I/O stream handle to a VFS base object handle.
232	*
233	* @returns Referenced handle on success, NIL if the input handle was invalid.
234	* @param hVfsIos The VFS I/O stream handle.
235	*/
236	RTDECL(RTVFSOBJ) RTVfsObjFromIoStream(RTVFSIOSTREAM hVfsIos);
237
238	/**
239	* Converts a VFS file handle to a VFS base object handle.
240	*
241	* @returns Referenced handle on success, NIL if the input handle was invalid.
242	* @param hVfsFile The VFS file handle.
243	*/
244	RTDECL(RTVFSOBJ) RTVfsObjFromFile(RTVFSFILE hVfsFile);
245
246	/**
247	* Converts a VFS symbolic link handle to a VFS base object handle.
248	*
249	* @returns Referenced handle on success, NIL if the input handle was invalid.
250	* @param hVfsSym The VFS symbolic link handle.
251	*/
252	RTDECL(RTVFSOBJ) RTVfsObjFromSymlink(RTVFSSYMLINK hVfsSym);
253
254	/** @} */
255
256
257	/** @defgroup grp_vfs_fsstream VFS Filesystem Stream API
258	*
259	* Filesystem streams are for tar, cpio and similar. Any virtual filesystem can
260	* be turned into a filesystem stream using RTVfsFsStrmFromVfs.
261	*
262	* @{
263	*/
264
265	RTDECL(uint32_t) RTVfsFsStrmRetain(RTVFSFSSTREAM hVfsFss);
266	RTDECL(uint32_t) RTVfsFsStrmRelease(RTVFSFSSTREAM hVfsFss);
267	RTDECL(int) RTVfsFsStrmQueryInfo(RTVFSFSSTREAM hVfsFss, PRTFSOBJINFO pObjInfo, RTFSOBJATTRADD enmAddAttr);
268
269	/**
270	* Gets the next object in the stream.
271	*
272	* This call may affect the stream posision of a previously returned object.
273	*
274	* The type of object returned here typically boils down to three types:
275	* - I/O streams (representing files),
276	* - symbolic links
277	* - base object
278	* The base objects represent anything not convered by the two other, i.e.
279	* directories, device nodes, fifos, sockets and whatnot. The details can be
280	* queried using RTVfsObjQueryInfo.
281	*
282	* That said, absolutely any object except for filesystem stream objects can be
283	* returned by this call. Any generic code is adviced to just deal with it all.
284	*
285	* @returns IPRT status code.
286	* @retval VINF_SUCCESS if a new object was retrieved.
287	* @retval VERR_EOF when there are no more objects.
288	*
289	* @param pvThis The implementation specific directory data.
290	* @param ppszName Where to return the object name. Must be freed by
291	* calling RTStrFree.
292	* @param penmType Where to return the object type.
293	* @param hVfsObj Where to return the object handle (referenced).
294	* This must be cast to the desired type before use.
295	*/
296	RTDECL(int) RTVfsFsStrmNext(RTVFSFSSTREAM hVfsFss, char *ppszName, RTVFSOBJTYPE penmType, PRTVFSOBJ phVfsObj);
297
298	/** @} */
299
300
301	/** @defgroup grp_vfs_dir VFS Directory API
302	* @{
303	*/
304
305	/**
306	* Retains a reference to the VFS directory handle.
307	*
308	* @returns New reference count on success, UINT32_MAX on failure.
309	* @param hVfsDir The VFS directory handle.
310	*/
311	RTDECL(uint32_t) RTVfsDirRetain(RTVFSDIR hVfsDir);
312
313	/**
314	* Releases a reference to the VFS directory handle.
315	*
316	* @returns New reference count on success (0 if closed), UINT32_MAX on failure.
317	* @param hVfsIos The VFS directory handle.
318	*/
319	RTDECL(uint32_t) RTVfsDirRelease(RTVFSDIR hVfsDir);
320
321	/** @} */
322
323
324	/** @defgroup grp_vfs_iostream VFS Symbolic Link API
325	*
326	* @remarks The TAR VFS and filesystem stream uses symbolic links for
327	* describing hard links as well. The users must use RTFS_IS_SYMLINK
328	* to check if it is a real symlink in those cases.
329	*
330	* @remarks Any VFS which is backed by a real file system may be subject to
331	* races with other processes or threads, so the user may get
332	* unexpected errors when this happends. This is a bit host specific,
333	* i.e. it might be prevent on windows if we care.
334	*
335	* @{
336	*/
337
338
339	/**
340	* Retains a reference to the VFS symbolic link handle.
341	*
342	* @returns New reference count on success, UINT32_MAX on failure.
343	* @param hVfsSym The VFS symbolic link handle.
344	*/
345	RTDECL(uint32_t) RTVfsSymlinkRetain(RTVFSSYMLINK hVfsSym);
346
347	/**
348	* Releases a reference to the VFS symbolic link handle.
349	*
350	* @returns New reference count on success (0 if closed), UINT32_MAX on failure.
351	* @param hVfsSym The VFS symbolic link handle.
352	*/
353	RTDECL(uint32_t) RTVfsSymlinkRelease(RTVFSSYMLINK hVfsSym);
354
355	/**
356	* Query information about the symbolic link.
357	*
358	* @returns IPRT status code.
359	* @param hVfsSym The VFS symbolic link handle.
360	* @param pObjInfo Where to return the info.
361	* @param enmAddAttr Which additional attributes should be retrieved.
362	*
363	* @sa RTFileQueryInfo, RTPathQueryInfo, RTPathQueryInfoEx
364	*/
365	RTDECL(int) RTVfsSymlinkQueryInfo(RTVFSSYMLINK hVfsSym, PRTFSOBJINFO pObjInfo, RTFSOBJATTRADD enmAddAttr);
366
367	/**
368	* Set the unix style owner and group.
369	*
370	* @returns IPRT status code.
371	* @param hVfsSym The VFS symbolic link handle.
372	* @param fMode The new mode bits.
373	* @param fMask The mask indicating which bits we are changing.
374	* @sa RTFileSetMode, RTPathSetMode
375	*/
376	RTDECL(int) RTVfsSymlinkSetMode(RTVFSSYMLINK hVfsSym, RTFMODE fMode, RTFMODE fMask);
377
378	/**
379	* Set the timestamps associated with the object.
380	*
381	* @returns IPRT status code.
382	* @param hVfsSym The VFS symbolic link handle.
383	* @param pAccessTime Pointer to the new access time. NULL if not
384	* to be changed.
385	* @param pModificationTime Pointer to the new modifcation time. NULL if
386	* not to be changed.
387	* @param pChangeTime Pointer to the new change time. NULL if not to be
388	* changed.
389	* @param pBirthTime Pointer to the new time of birth. NULL if not to be
390	* changed.
391	* @remarks See RTFileSetTimes for restrictions and behavior imposed by the
392	* host OS or underlying VFS provider.
393	* @sa RTFileSetTimes, RTPathSetTimes
394	*/
395	RTDECL(int) RTVfsSymlinkSetTimes(RTVFSSYMLINK hVfsSym, PCRTTIMESPEC pAccessTime, PCRTTIMESPEC pModificationTime,
396	PCRTTIMESPEC pChangeTime, PCRTTIMESPEC pBirthTime);
397
398	/**
399	* Set the unix style owner and group.
400	*
401	* @returns IPRT status code.
402	* @param hVfsSym The VFS symbolic link handle.
403	* @param uid The user ID of the new owner. NIL_RTUID if
404	* unchanged.
405	* @param gid The group ID of the new owner group. NIL_RTGID if
406	* unchanged.
407	* @sa RTFileSetOwner, RTPathSetOwner.
408	*/
409	RTDECL(int) RTVfsSymlinkSetOwner(RTVFSSYMLINK hVfsSym, RTUID uid, RTGID gid);
410
411	/**
412	* Read the symbolic link target.
413	*
414	* @returns IPRT status code.
415	* @param hVfsSym The VFS symbolic link handle.
416	* @param pszTarget The target buffer.
417	* @param cbTarget The size of the target buffer.
418	* @sa RTSymlinkRead
419	*/
420	RTDECL(int) RTVfsSymlinkRead(RTVFSSYMLINK hVfsSym, char *pszTarget, size_t cbTarget);
421
422	/** @} */
423
424
425
426	/** @defgroup grp_vfs_iostream VFS I/O Stream API
427	* @{
428	*/
429
430	/**
431	* Create a VFS I/O stream handle from a standard IPRT file handle (RTFILE).
432	*
433	* @returns IPRT status code.
434	* @param hFile The standard IPRT file handle.
435	* @param fOpen The flags the handle was opened with. Pass 0 to
436	* have these detected.
437	* @param fLeaveOpen Whether to leave the handle open when the VFS file
438	* is released, or to close it (@c false).
439	* @param phVfsIos Where to return the VFS I/O stream handle.
440	*/
441	RTDECL(int) RTVfsIoStrmFromRTFile(RTFILE hFile, uint32_t fOpen, bool fLeaveOpen, PRTVFSIOSTREAM phVfsIos);
442
443	/**
444	* Create a VFS I/O stream handle from one of the standard handles.
445	*
446	* @returns IPRT status code.
447	* @param enmStdHandle The standard IPRT file handle.
448	* @param fOpen The flags the handle was opened with. Pass 0 to
449	* have these detected.
450	* @param fLeaveOpen Whether to leave the handle open when the VFS file
451	* is released, or to close it (@c false).
452	* @param phVfsIos Where to return the VFS I/O stream handle.
453	*/
454	RTDECL(int) RTVfsIoStrmFromStdHandle(RTHANDLESTD enmStdHandle, uint32_t fOpen, bool fLeaveOpen,
455	PRTVFSIOSTREAM phVfsIos);
456
457	/**
458	* Retains a reference to the VFS I/O stream handle.
459	*
460	* @returns New reference count on success, UINT32_MAX on failure.
461	* @param hVfsIos The VFS I/O stream handle.
462	*/
463	RTDECL(uint32_t) RTVfsIoStrmRetain(RTVFSIOSTREAM hVfsIos);
464
465	/**
466	* Releases a reference to the VFS I/O stream handle.
467	*
468	* @returns New reference count on success (0 if closed), UINT32_MAX on failure.
469	* @param hVfsIos The VFS I/O stream handle.
470	*/
471	RTDECL(uint32_t) RTVfsIoStrmRelease(RTVFSIOSTREAM hVfsIos);
472
473	/**
474	* Convert the VFS I/O stream handle to a VFS file handle.
475	*
476	* @returns The VFS file handle on success, this must be released.
477	* NIL_RTVFSFILE if the I/O stream handle is invalid.
478	* @param hVfsIos The VFS I/O stream handle.
479	* @sa RTVfsFileToIoStream
480	*/
481	RTDECL(RTVFSFILE) RTVfsIoStrmToFile(RTVFSIOSTREAM hVfsIos);
482
483	/**
484	* Query information about the I/O stream.
485	*
486	* @returns IPRT status code.
487	* @param hVfsIos The VFS I/O stream handle.
488	* @param pObjInfo Where to return the info.
489	* @param enmAddAttr Which additional attributes should be retrieved.
490	* @sa RTFileQueryInfo
491	*/
492	RTDECL(int) RTVfsIoStrmQueryInfo(RTVFSIOSTREAM hVfsIos, PRTFSOBJINFO pObjInfo, RTFSOBJATTRADD enmAddAttr);
493
494	/**
495	* Read bytes from the I/O stream.
496	*
497	* @returns IPRT status code.
498	* @retval VINF_SUCCESS and the number of bytes read written to @a pcbRead.
499	* @retval VINF_TRY_AGAIN if @a fBlocking is @c false, @a pcbRead is not NULL,
500	* and no data was available. @a *pcbRead will be set to 0.
501	* @retval VINF_EOF when trying to read __beyond__ the end of the stream and
502	* @a pcbRead is not NULL (it will be set to the number of bytes read,
503	* or 0 if the end of the stream was reached before this call).
504	* When the last byte of the read request is the last byte in the
505	* stream, this status code will not be used. However, VINF_EOF is
506	* returned when attempting to read 0 bytes while standing at the end
507	* of the stream.
508	* @retval VERR_EOF when trying to read __beyond__ the end of the stream and
509	* @a pcbRead is NULL.
510	* @retval VERR_ACCESS_DENIED if the stream is not readable.
511	*
512	* @param hVfsIos The VFS I/O stream handle.
513	* @param pvBuf Where to store the read bytes.
514	* @param cbToRead The number of bytes to read.
515	* @param fBlocking Whether the call is blocking (@c true) or not. If
516	* not, the @a pcbRead parameter must not be NULL.
517	* @param pcbRead Where to always store the number of bytes actually
518	* read. This can be NULL if @a fBlocking is true.
519	* @sa RTVfsFileRead, RTFileRead, RTPipeRead, RTPipeReadBlocking,
520	* RTSocketRead
521	*/
522	RTDECL(int) RTVfsIoStrmRead(RTVFSIOSTREAM hVfsIos, void pvBuf, size_t cbToRead, bool fBlocking, size_t pcbRead);
523
524	/**
525	* Write bytes to the I/O stream.
526	*
527	* @returns IPRT status code.
528	* @retval VERR_ACCESS_DENIED if the stream is not writable.
529	*
530	* @param hVfsIos The VFS I/O stream handle.
531	* @param pvBuf The bytes to write.
532	* @param cbToWrite The number of bytes to write.
533	* @param fBlocking Whether the call is blocking (@c true) or not. If
534	* not, the @a pcbWritten parameter must not be NULL.
535	* @param pcbRead Where to always store the number of bytes actually
536	* written. This can be NULL if @a fBlocking is true.
537	* @sa RTVfsFileWrite, RTFileWrite, RTPipeWrite, RTPipeWriteBlocking,
538	* RTSocketWrite
539	*/
540	RTDECL(int) RTVfsIoStrmWrite(RTVFSIOSTREAM hVfsIos, const void pvBuf, size_t cbToWrite, bool fBlocking, size_t pcbWritten);
541
542	/**
543	* Reads bytes from the I/O stream into a scatter buffer.
544	*
545	* @returns IPRT status code.
546	* @retval VINF_SUCCESS and the number of bytes read written to @a pcbRead.
547	* @retval VINF_TRY_AGAIN if @a fBlocking is @c false, @a pcbRead is not NULL,
548	* and no data was available. @a *pcbRead will be set to 0.
549	* @retval VINF_EOF when trying to read __beyond__ the end of the stream and
550	* @a pcbRead is not NULL (it will be set to the number of bytes read,
551	* or 0 if the end of the stream was reached before this call).
552	* When the last byte of the read request is the last byte in the
553	* stream, this status code will not be used. However, VINF_EOF is
554	* returned when attempting to read 0 bytes while standing at the end
555	* of the stream.
556	* @retval VERR_EOF when trying to read __beyond__ the end of the stream and
557	* @a pcbRead is NULL.
558	* @retval VERR_ACCESS_DENIED if the stream is not readable.
559	*
560	* @param hVfsIos The VFS I/O stream handle.
561	* @param pSgBuf Pointer to a scatter buffer descriptor. The number
562	* of bytes described by the segments is what will be
563	* attemted read.
564	* @param fBlocking Whether the call is blocking (@c true) or not. If
565	* not, the @a pcbRead parameter must not be NULL.
566	* @param pcbRead Where to always store the number of bytes actually
567	* read. This can be NULL if @a fBlocking is true.
568	* @sa RTFileSgRead, RTSocketSgRead, RTPipeRead, RTPipeReadBlocking
569	*/
570	RTDECL(int) RTVfsIoStrmSgRead(RTVFSIOSTREAM hVfsIos, PCRTSGBUF pSgBuf, bool fBlocking, size_t *pcbRead);
571
572	/**
573	* Write bytes to the I/O stream from a gather buffer.
574	*
575	* @returns IPRT status code.
576	* @retval VERR_ACCESS_DENIED if the stream is not writable.
577	*
578	* @param hVfsIos The VFS I/O stream handle.
579	* @param pSgBuf Pointer to a gather buffer descriptor. The number
580	* of bytes described by the segments is what will be
581	* attemted written.
582	* @param fBlocking Whether the call is blocking (@c true) or not. If
583	* not, the @a pcbWritten parameter must not be NULL.
584	* @param pcbRead Where to always store the number of bytes actually
585	* written. This can be NULL if @a fBlocking is true.
586	* @sa RTFileSgWrite, RTSocketSgWrite
587	*/
588	RTDECL(int) RTVfsIoStrmSgWrite(RTVFSIOSTREAM hVfsIos, PCRTSGBUF pSgBuf, bool fBlocking, size_t *pcbWritten);
589
590	/**
591	* Flush any buffered data to the I/O stream.
592	*
593	* @returns IPRT status code.
594	* @param hVfsIos The VFS I/O stream handle.
595	* @sa RTVfsFileFlush, RTFileFlush, RTPipeFlush
596	*/
597	RTDECL(int) RTVfsIoStrmFlush(RTVFSIOSTREAM hVfsIos);
598
599	/**
600	* Poll for events.
601	*
602	* @returns IPRT status code.
603	* @param hVfsIos The VFS I/O stream handle.
604	* @param fEvents The events to poll for (RTPOLL_EVT_XXX).
605	* @param cMillies How long to wait for event to eventuate.
606	* @param fIntr Whether the wait is interruptible and can return
607	* VERR_INTERRUPTED (@c true) or if this condition
608	* should be hidden from the caller (@c false).
609	* @param pfRetEvents Where to return the event mask.
610	* @sa RTVfsFilePoll, RTPollSetAdd, RTPoll, RTPollNoResume.
611	*/
612	RTDECL(int) RTVfsIoStrmPoll(RTVFSIOSTREAM hVfsIos, uint32_t fEvents, RTMSINTERVAL cMillies, bool fIntr,
613	uint32_t *pfRetEvents);
614	/**
615	* Tells the current I/O stream position.
616	*
617	* @returns Zero or higher - where to return the I/O stream offset. Values
618	* below zero are IPRT status codes (VERR_XXX).
619	* @param hVfsIos The VFS I/O stream handle.
620	* @sa RTFileTell
621	*/
622	RTDECL(RTFOFF) RTVfsIoStrmTell(RTVFSIOSTREAM hVfsIos);
623
624	/**
625	* Skips @a cb ahead in the stream.
626	*
627	* @returns IPRT status code.
628	* @param hVfsIos The VFS I/O stream handle.
629	* @param cb The number bytes to skip.
630	*/
631	RTDECL(int) RTVfsIoStrmSkip(RTVFSIOSTREAM hVfsIos, RTFOFF cb);
632
633	/**
634	* Fills the stream with @a cb zeros.
635	*
636	* @returns IPRT status code.
637	* @param hVfsIos The VFS I/O stream handle.
638	* @param cb The number of zero bytes to insert.
639	*/
640	RTDECL(int) RTVfsIoStrmZeroFill(RTVFSIOSTREAM hVfsIos, RTFOFF cb);
641
642	/**
643	* Checks if we're at the end of the I/O stream.
644	*
645	* @returns true if at EOS, otherwise false.
646	* @param hVfsIos The VFS I/O stream handle.
647	*/
648	RTDECL(bool) RTVfsIoStrmIsAtEnd(RTVFSIOSTREAM hVfsIos);
649
650	/**
651	* Process the rest of the stream, checking if it's all valid UTF-8 encoding.
652	*
653	* @returns VBox status cod.e
654	*
655	* @param hVfsIos The VFS I/O stream handle.
656	* @param fFlags Flags governing the validation, see
657	* RTVFS_VALIDATE_UTF8_XXX.
658	* @param poffError Where to return the error offset. Optional.
659	*/
660	RTDECL(int) RTVfsIoStrmValidateUtf8Encoding(RTVFSIOSTREAM hVfsIos, uint32_t fFlags, PRTFOFF poffError);
661
662	/** @defgroup RTVFS_VALIDATE_UTF8_XXX RTVfsIoStrmValidateUtf8Encoding flags.
663	* @{ */
664	/** The text must not contain any null terminator codepoints. */
665	#define RTVFS_VALIDATE_UTF8_NO_NULL RT_BIT_32(0)
666	/** The codepoints must be in the range covered by RTC-3629. */
667	#define RTVFS_VALIDATE_UTF8_BY_RTC_3629 RT_BIT_32(1)
668	/** Mask of valid flags. */
669	#define RTVFS_VALIDATE_UTF8_VALID_MASK UINT32_C(0x00000003)
670	/** @} */
671
672	/** @} */
673
674
675	/** @defgroup grp_vfs_file VFS File API
676	* @{
677	*/
678	RTDECL(int) RTVfsFileOpen(RTVFS hVfs, const char *pszFilename, uint32_t fOpen, PRTVFSFILE phVfsFile);
679
680	/**
681	* Create a VFS file handle from a standard IPRT file handle (RTFILE).
682	*
683	* @returns IPRT status code.
684	* @param hFile The standard IPRT file handle.
685	* @param fOpen The flags the handle was opened with. Pass 0 to
686	* have these detected.
687	* @param fLeaveOpen Whether to leave the handle open when the VFS file
688	* is released, or to close it (@c false).
689	* @param phVfsFile Where to return the VFS file handle.
690	*/
691	RTDECL(int) RTVfsFileFromRTFile(RTFILE hFile, uint32_t fOpen, bool fLeaveOpen, PRTVFSFILE phVfsFile);
692	RTDECL(RTHCUINTPTR) RTVfsFileToNative(RTFILE hVfsFile);
693
694	/**
695	* Convert the VFS file handle to a VFS I/O stream handle.
696	*
697	* @returns The VFS I/O stream handle on success, this must be released.
698	* NIL_RTVFSIOSTREAM if the file handle is invalid.
699	* @param hVfsFile The VFS file handle.
700	* @sa RTVfsIoStrmToFile
701	*/
702	RTDECL(RTVFSIOSTREAM) RTVfsFileToIoStream(RTVFSFILE hVfsFile);
703
704	/**
705	* Retains a reference to the VFS file handle.
706	*
707	* @returns New reference count on success, UINT32_MAX on failure.
708	* @param hVfsFile The VFS file handle.
709	*/
710	RTDECL(uint32_t) RTVfsFileRetain(RTVFSFILE hVfsFile);
711
712	/**
713	* Releases a reference to the VFS file handle.
714	*
715	* @returns New reference count on success (0 if closed), UINT32_MAX on failure.
716	* @param hVfsFile The VFS file handle.
717	*/
718	RTDECL(uint32_t) RTVfsFileRelease(RTVFSFILE hVfsFile);
719
720	/**
721	* Query information about the object.
722	*
723	* @returns IPRT status code.
724	* @retval VERR_NOT_SUPPORTED if the @a enmAddAttr value is not handled by the
725	* implementation.
726	*
727	* @param hVfsObj The VFS object handle.
728	* @param pObjInfo Where to return the info.
729	* @param enmAddAttr Which additional attributes should be retrieved.
730	* @sa RTVfsObjQueryInfo, RTVfsFsStrmQueryInfo, RTVfsDirQueryInfo,
731	* RTVfsIoStrmQueryInfo, RTVfsFileQueryInfo, RTFileQueryInfo,
732	* RTPathQueryInfo.
733	*/
734	RTDECL(int) RTVfsFileQueryInfo(RTVFSFILE hVfsFile, PRTFSOBJINFO pObjInfo, RTFSOBJATTRADD enmAddAttr);
735
736	/**
737	* Read bytes from the file at the current position.
738	*
739	* @returns IPRT status code.
740	* @retval VINF_SUCCESS and the number of bytes read written to @a pcbRead.
741	* @retval VINF_TRY_AGAIN if @a fBlocking is @c false, @a pcbRead is not NULL,
742	* and no data was available. @a *pcbRead will be set to 0.
743	* @retval VINF_EOF when trying to read __beyond__ the end of the file and
744	* @a pcbRead is not NULL (it will be set to the number of bytes read,
745	* or 0 if the end of the file was reached before this call).
746	* When the last byte of the read request is the last byte in the
747	* file, this status code will not be used. However, VINF_EOF is
748	* returned when attempting to read 0 bytes while standing at the end
749	* of the file.
750	* @retval VERR_EOF when trying to read __beyond__ the end of the file and
751	* @a pcbRead is NULL.
752	* @retval VERR_ACCESS_DENIED if the file is not readable.
753	*
754	* @param hVfsFile The VFS file handle.
755	* @param pvBuf Where to store the read bytes.
756	* @param cbToRead The number of bytes to read.
757	* @param fBlocking Whether the call is blocking (@c true) or not. If
758	* not, the @a pcbRead parameter must not be NULL.
759	* @param pcbRead Where to always store the number of bytes actually
760	* read. This can be NULL if @a fBlocking is true.
761	* @sa RTVfsIoStrmRead, RTFileRead, RTPipeRead, RTPipeReadBlocking,
762	* RTSocketRead
763	*/
764	RTDECL(int) RTVfsFileRead(RTVFSFILE hVfsFile, void pvBuf, size_t cbToRead, size_t pcbRead);
765	RTDECL(int) RTVfsFileReadAt(RTVFSFILE hVfsFile, RTFOFF off, void pvBuf, size_t cbToRead, size_t pcbRead);
766
767	/**
768	* Write bytes to the file at the current position.
769	*
770	* @returns IPRT status code.
771	* @retval VERR_ACCESS_DENIED if the file is not writable.
772	*
773	* @param hVfsFile The VFS file handle.
774	* @param pvBuf The bytes to write.
775	* @param cbToWrite The number of bytes to write.
776	* @param fBlocking Whether the call is blocking (@c true) or not. If
777	* not, the @a pcbWritten parameter must not be NULL.
778	* @param pcbRead Where to always store the number of bytes actually
779	* written. This can be NULL if @a fBlocking is true.
780	* @sa RTVfsIoStrmRead, RTFileWrite, RTPipeWrite, RTPipeWriteBlocking,
781	* RTSocketWrite
782	*/
783	RTDECL(int) RTVfsFileWrite(RTVFSFILE hVfsFile, const void pvBuf, size_t cbToWrite, size_t pcbWritten);
784	RTDECL(int) RTVfsFileWriteAt(RTVFSFILE hVfsFile, RTFOFF off, const void pvBuf, size_t cbToWrite, size_t pcbWritten);
785
786	/**
787	* Flush any buffered data to the file.
788	*
789	* @returns IPRT status code.
790	* @param hVfsFile The VFS file handle.
791	* @sa RTVfsIoStrmFlush, RTFileFlush, RTPipeFlush
792	*/
793	RTDECL(int) RTVfsFileFlush(RTVFSFILE hVfsFile);
794
795	/**
796	* Poll for events.
797	*
798	* @returns IPRT status code.
799	* @param hVfsFile The VFS file handle.
800	* @param fEvents The events to poll for (RTPOLL_EVT_XXX).
801	* @param cMillies How long to wait for event to eventuate.
802	* @param fIntr Whether the wait is interruptible and can return
803	* VERR_INTERRUPTED (@c true) or if this condition
804	* should be hidden from the caller (@c false).
805	* @param pfRetEvents Where to return the event mask.
806	* @sa RTVfsIoStrmPoll, RTPollSetAdd, RTPoll, RTPollNoResume.
807	*/
808	RTDECL(RTFOFF) RTVfsFilePoll(RTVFSFILE hVfsFile, uint32_t fEvents, RTMSINTERVAL cMillies, bool fIntr,
809	uint32_t *pfRetEvents);
810
811	/**
812	* Tells the current file position.
813	*
814	* @returns Zero or higher - where to return the file offset. Values
815	* below zero are IPRT status codes (VERR_XXX).
816	* @param hVfsFile The VFS file handle.
817	* @sa RTFileTell, RTVfsIoStrmTell.
818	*/
819	RTDECL(RTFOFF) RTVfsFileTell(RTVFSFILE hVfsFile);
820
821	/**
822	* Changes the current read/write position of a file.
823	*
824	* @returns IPRT status code.
825	*
826	* @param hVfsFile The VFS file handle.
827	* @param offSeek The seek offset.
828	* @param uMethod The seek emthod.
829	* @param poffActual Where to optionally return the new file offset.
830	*
831	* @sa RTFileSeek
832	*/
833	RTDECL(int) RTVfsFileSeek(RTVFSFILE hVfsFile, RTFOFF offSeek, uint32_t uMethod, uint64_t *poffActual);
834
835	RTDECL(int) RTVfsFileSetSize(RTVFSFILE hVfsFile, uint64_t cbSize);
836	RTDECL(int) RTVfsFileGetSize(RTVFSFILE hVfsFile, uint64_t *pcbSize);
837	RTDECL(RTFOFF) RTVfsFileGetMaxSize(RTVFSFILE hVfsFile);
838	RTDECL(int) RTVfsFileGetMaxSizeEx(RTVFSFILE hVfsFile, PRTFOFF pcbMax);
839
840	/** @} */
841
842
843	/** @defgroup grp_vfs_misc VFS Miscellaneous
844	* @{
845	*/
846
847	/**
848	* Memorizes the I/O stream as a file backed by memory.
849	*
850	* @returns VBox status code.
851	*
852	* @param hVfsIos The VFS I/O stream to memorize. This will be read
853	* to the end on success, on failure its position is
854	* undefined.
855	* @param fFlags A combination of RTFILE_O_READ and RTFILE_O_WRITE.
856	* @param phVfsFile Where to return the handle to the memory file on
857	* success.
858	*/
859	RTDECL(int) RTVfsMemorizeIoStreamAsFile(RTVFSIOSTREAM hVfsIos, uint32_t fFlags, PRTVFSFILE phVfsFile);
860
861
862	/**
863	* Pumps data from one I/O stream to another.
864	*
865	* The data is read in chunks from @a hVfsIosSrc and written to @a hVfsIosDst
866	* until @hVfsIosSrc indicates end of stream.
867	*
868	* @returns IPRT status code
869	*
870	* @param hVfsIosSrc The input stream.
871	* @param hVfsIosDst The output stream.
872	* @param cbBufHint Hints at a good temporary buffer size, pass 0 if
873	* clueless.
874	*/
875	RTDECL(int) RTVfsUtilPumpIoStreams(RTVFSIOSTREAM hVfsIosSrc, RTVFSIOSTREAM hVfsIosDst, size_t cbBufHint);
876
877	/** @} */
878
879
880	/** @defgroup grp_rt_vfs_chain VFS Chains
881	*
882	* VFS chains is for doing pipe like things with VFS objects from the command
883	* line. Imagine you want to cat the readme.gz of an ISO you could do
884	* something like:
885	* RTCat :iprtvfs:vfs(isofs,./mycd.iso)\|ios(open,readme.gz)\|ios(gunzip)
886	* or
887	* RTCat :iprtvfs:ios(isofs,./mycd.iso,/readme.gz)\|ios(gunzip)
888	*
889	* The "isofs", "open" and "gunzip" bits in the above examples are chain
890	* element providers registered with IPRT. See RTVFSCHAINELEMENTREG for how
891	* these works.
892	*
893	* @{ */
894
895	/** The path prefix used to identify an VFS chain specification. */
896	#define RTVFSCHAIN_SPEC_PREFIX ":iprtvfs:"
897
898	RTDECL(int) RTVfsChainOpenVfs( const char pszSpec, PRTVFS phVfs, const char *ppszError);
899	RTDECL(int) RTVfsChainOpenFsStream( const char pszSpec, PRTVFSFSSTREAM phVfsFss, const char *ppszError);
900	RTDECL(int) RTVfsChainOpenDir( const char pszSpec, uint32_t fOpen, PRTVFSDIR phVfsDir, const char *ppszError);
901	RTDECL(int) RTVfsChainOpenFile( const char pszSpec, uint32_t fOpen, PRTVFSFILE phVfsFile, const char *ppszError);
902	RTDECL(int) RTVfsChainOpenSymlink( const char pszSpec, PRTVFSSYMLINK phVfsSym, const char *ppszError);
903	RTDECL(int) RTVfsChainOpenIoStream( const char pszSpec, uint32_t fOpen, PRTVFSIOSTREAM phVfsIos, const char *ppszError);
904
905	/**
906	* Tests if the given string is a chain specification or not.
907	*
908	* @returns true if it is, false if it isn't.
909	* @param pszSpec The alleged chain spec.
910	*/
911	RTDECL(bool) RTVfsChainIsSpec(const char *pszSpec);
912
913	/** @} */
914
915
916	/** @} */
917
918	RT_C_DECLS_END
919
920	#endif /* !___iprt_vfs_h */
921

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

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

Download in other formats: