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/symlink.h>
|
---|
34 | #include <iprt/sg.h>
|
---|
35 | #include <iprt/time.h>
|
---|
36 |
|
---|
37 |
|
---|
38 | RT_C_DECLS_BEGIN
|
---|
39 |
|
---|
40 | /** @defgroup grp_rt_fs RTVfs - Virtual Filesystem
|
---|
41 | * @ingroup grp_rt
|
---|
42 | *
|
---|
43 | * The virtual filesystem APIs are intended to make it possible to work on
|
---|
44 | * container files, file system sub-trees, file system overlays and other custom
|
---|
45 | * filesystem configurations. It also makes it possible to create filters, like
|
---|
46 | * automatically gunzipping a tar.gz file before feeding it to the RTTar API for
|
---|
47 | * unpacking - or wise versa.
|
---|
48 | *
|
---|
49 | * The virtual filesystem APIs are intended to mirror the RTDir, RTFile, RTPath
|
---|
50 | * and RTFs APIs pretty closely so that rewriting a piece of code to work with
|
---|
51 | * it should be easy. However there are some differences to the way the APIs
|
---|
52 | * works and the user should heed the documentation. The differences are
|
---|
53 | * usually motivated by simplification and in some case to make the VFS more
|
---|
54 | * flexible.
|
---|
55 | *
|
---|
56 | * @{
|
---|
57 | */
|
---|
58 |
|
---|
59 | /** Virtual Filesystem handle. */
|
---|
60 | typedef struct RTVFSINTERNAL *RTVFS;
|
---|
61 | /** Pointer to a VFS handle. */
|
---|
62 | typedef RTVFS *PRTVFS;
|
---|
63 | /** A NIL VFS directory handle. */
|
---|
64 | #define NIL_RTVFS ((RTVFS)~(uintptr_t)0)
|
---|
65 |
|
---|
66 | /** Virtual Filesystem directory handle. */
|
---|
67 | typedef struct RTVFSDIRINTERNAL *RTVFSDIR;
|
---|
68 | /** Pointer to a VFS directory handle. */
|
---|
69 | typedef RTVFSDIR *PRTVFSDIR;
|
---|
70 | /** A NIL VFS directory handle. */
|
---|
71 | #define NIL_RTVFSDIR ((RTVFSDIR)~(uintptr_t)0)
|
---|
72 |
|
---|
73 | /** Virtual Filesystem I/O stream handle. */
|
---|
74 | typedef struct RTVFSIOSTREAMINTERNAL *RTVFSIOSTREAM;
|
---|
75 | /** Pointer to a VFS I/O stream handle. */
|
---|
76 | typedef RTVFSIOSTREAM *PRTVFSIOSTREAM;
|
---|
77 | /** A NIL VFS I/O stream handle. */
|
---|
78 | #define NIL_RTVFSIOSTREAM ((RTVFSIOSTREAM)~(uintptr_t)0)
|
---|
79 |
|
---|
80 | /** Virtual Filesystem file handle. */
|
---|
81 | typedef struct RTVFSFILEINTERNAL *RTVFSFILE;
|
---|
82 | /** Pointer to a VFS file handle. */
|
---|
83 | typedef RTVFSFILE *PRTVFSFILE;
|
---|
84 | /** A NIL VFS file handle. */
|
---|
85 | #define NIL_RTVFSFILE ((RTVFSFILE)~(uintptr_t)0)
|
---|
86 |
|
---|
87 | /** Virtual Filesystem symbolic link handle. */
|
---|
88 | typedef struct RTVFSSYMLINKINTERNAL *RTVFSSYMLINK;
|
---|
89 | /** Pointer to a VFS symbolic link handle. */
|
---|
90 | typedef RTVFSSYMLINK *PRTVFSSYMLINK;
|
---|
91 | /** A NIL VFS symbolic link handle. */
|
---|
92 | #define NIL_RTVFSSYMLINK ((RTVFSSYMLINK)~(uintptr_t)0)
|
---|
93 |
|
---|
94 |
|
---|
95 | /** @name RTVfsCreate flags
|
---|
96 | * @{ */
|
---|
97 | /** Whether the file system is read-only. */
|
---|
98 | #define RTVFS_C_READONLY RT_BIT(0)
|
---|
99 | /** Whether we the VFS should be thread safe (i.e. automaticaly employ
|
---|
100 | * locks). */
|
---|
101 | #define RTVFS_C_THREAD_SAFE RT_BIT(1)
|
---|
102 | /** @} */
|
---|
103 |
|
---|
104 | /**
|
---|
105 | * Creates an empty virtual filesystem.
|
---|
106 | *
|
---|
107 | * @returns IPRT status code.
|
---|
108 | * @param pszName Name, for logging and such.
|
---|
109 | * @param fFlags Flags, MBZ.
|
---|
110 | * @param phVfs Where to return the VFS handle. Release the returned
|
---|
111 | * reference by calling RTVfsRelease.
|
---|
112 | */
|
---|
113 | RTDECL(int) RTVfsCreate(const char *pszName, uint32_t fFlags, PRTVFS phVfs);
|
---|
114 | RTDECL(uint32_t) RTVfsRetain(RTVFS phVfs);
|
---|
115 | RTDECL(uint32_t) RTVfsRelease(RTVFS phVfs);
|
---|
116 | RTDECL(int) RTVfsAttach(RTVFS hVfs, const char *pszMountPoint, uint32_t fFlags, RTVFS hVfsAttach);
|
---|
117 | RTDECL(int) RTVfsDetach(RTVFS hVfs, const char *pszMountPoint, RTVFS hVfsToDetach, PRTVFS *phVfsDetached);
|
---|
118 | RTDECL(uint32_t) RTVfsGetAttachmentCount(RTVFS hVfs);
|
---|
119 | RTDECL(int) RTVfsGetAttachment(RTVFS hVfs, uint32_t iOrdinal, PRTVFS *phVfsAttached, uint32_t *pfFlags,
|
---|
120 | char *pszMountPoint, size_t cbMountPoint);
|
---|
121 |
|
---|
122 |
|
---|
123 | /** @defgroup grp_vfs_dir VFS Directory API
|
---|
124 | * @{
|
---|
125 | */
|
---|
126 |
|
---|
127 | /**
|
---|
128 | * Retains a reference to the VFS directory handle.
|
---|
129 | *
|
---|
130 | * @returns New reference count on success, UINT32_MAX on failure.
|
---|
131 | * @param hVfsDir The VFS directory handle.
|
---|
132 | */
|
---|
133 | RTDECL(uint32_t) RTVfsDirRetain(RTVFSDIR hVfsDir);
|
---|
134 |
|
---|
135 | /**
|
---|
136 | * Releases a reference to the VFS directory handle.
|
---|
137 | *
|
---|
138 | * @returns New reference count on success (0 if closed), UINT32_MAX on failure.
|
---|
139 | * @param hVfsIos The VFS directory handle.
|
---|
140 | */
|
---|
141 | RTDECL(uint32_t) RTVfsDirRelease(RTVFSDIR hVfsDir);
|
---|
142 |
|
---|
143 | /** @} */
|
---|
144 |
|
---|
145 |
|
---|
146 | /** @defgroup grp_vfs_iostream VFS Symbolic Link API
|
---|
147 | * @{
|
---|
148 | */
|
---|
149 |
|
---|
150 | /**
|
---|
151 | * Read the symbolic link target.
|
---|
152 | *
|
---|
153 | * @returns IPRT status code.
|
---|
154 | * @param hVfsSym The VFS symbolic link handle.
|
---|
155 | * @param pszTarget The target buffer.
|
---|
156 | * @param cbTarget The size of the target buffer.
|
---|
157 | * @sa RTSymlinkRead
|
---|
158 | */
|
---|
159 | RTDECL(int) RTVfsSymlinkRead(RTVFSSYMLINK hVfsSym, char *pszTarget, size_t cbTarget);
|
---|
160 |
|
---|
161 | /** @} */
|
---|
162 |
|
---|
163 |
|
---|
164 |
|
---|
165 | /** @defgroup grp_vfs_iostream VFS I/O Stream API
|
---|
166 | * @{
|
---|
167 | */
|
---|
168 |
|
---|
169 | /**
|
---|
170 | * Retains a reference to the VFS I/O stream handle.
|
---|
171 | *
|
---|
172 | * @returns New reference count on success, UINT32_MAX on failure.
|
---|
173 | * @param hVfsIos The VFS I/O stream handle.
|
---|
174 | */
|
---|
175 | RTDECL(uint32_t) RTVfsIoStrmRetain(RTVFSIOSTREAM hVfsIos);
|
---|
176 |
|
---|
177 | /**
|
---|
178 | * Releases a reference to the VFS I/O stream handle.
|
---|
179 | *
|
---|
180 | * @returns New reference count on success (0 if closed), UINT32_MAX on failure.
|
---|
181 | * @param hVfsIos The VFS I/O stream handle.
|
---|
182 | */
|
---|
183 | RTDECL(uint32_t) RTVfsIoStrmRelease(RTVFSIOSTREAM hVfsIos);
|
---|
184 |
|
---|
185 | /**
|
---|
186 | * Convert the VFS I/O stream handle to a VFS file handle.
|
---|
187 | *
|
---|
188 | * @returns The VFS file handle on success, this must be released.
|
---|
189 | * NIL_RTVFSFILE if the I/O stream handle is invalid.
|
---|
190 | * @param hVfsIos The VFS I/O stream handle.
|
---|
191 | * @sa RTVfsFileToIoStream
|
---|
192 | */
|
---|
193 | RTDECL(RTVFSFILE) RTVfsIoStrmToFile(RTVFSIOSTREAM hVfsIos);
|
---|
194 |
|
---|
195 | /**
|
---|
196 | * Query information about the I/O stream.
|
---|
197 | *
|
---|
198 | * @returns IPRT status code.
|
---|
199 | * @param hVfsIos The VFS I/O stream handle.
|
---|
200 | * @param pObjInfo Where to return the info.
|
---|
201 | * @param enmAddAttr Which additional attributes should be retrieved.
|
---|
202 | * @sa RTFileQueryInfo
|
---|
203 | */
|
---|
204 | RTDECL(int) RTVfsIoStrmQueryInfo(RTVFSIOSTREAM hVfsIos, PRTFSOBJINFO pObjInfo, RTFSOBJATTRADD enmAddAttr);
|
---|
205 |
|
---|
206 | /**
|
---|
207 | * Read bytes from the I/O stream.
|
---|
208 | *
|
---|
209 | * @returns IPRT status code.
|
---|
210 | * @param hVfsIos The VFS I/O stream handle.
|
---|
211 | * @param pvBuf Where to store the read bytes.
|
---|
212 | * @param cbToRead The number of bytes to read.
|
---|
213 | * @param pcbRead Where to store the number of bytes actually read.
|
---|
214 | * If this is NULL, the call will block until @a
|
---|
215 | * cbToRead bytes are available. If this is non-NULL,
|
---|
216 | * the call will not block and return what is currently
|
---|
217 | * avaiable.
|
---|
218 | * @sa RTFileRead, RTPipeRead, RTPipeReadBlocking, RTSocketRead
|
---|
219 | */
|
---|
220 | RTDECL(int) RTVfsIoStrmRead(RTVFSIOSTREAM hVfsIos, void *pvBuf, size_t cbToRead, size_t *pcbRead);
|
---|
221 |
|
---|
222 | /**
|
---|
223 | * Write bytes to the I/O stream.
|
---|
224 | *
|
---|
225 | * @returns IPRT status code.
|
---|
226 | * @param hVfsIos The VFS I/O stream handle.
|
---|
227 | * @param pvBuf The bytes to write.
|
---|
228 | * @param cbToWrite The number of bytes to write.
|
---|
229 | * @param pcbWritten Where to store the number of bytes actually written.
|
---|
230 | * If this is NULL, the call will block until @a
|
---|
231 | * cbToWrite bytes are available. If this is non-NULL,
|
---|
232 | * the call will not block and return after writing
|
---|
233 | * what is possible.
|
---|
234 | * @sa RTFileWrite, RTPipeWrite, RTPipeWriteBlocking, RTSocketWrite
|
---|
235 | */
|
---|
236 | RTDECL(int) RTVfsIoStrmWrite(RTVFSIOSTREAM hVfsIos, const void *pvBuf, size_t cbToWrite, size_t *pcbWritten);
|
---|
237 |
|
---|
238 | /**
|
---|
239 | * Reads bytes from the I/O stream into a scatter buffer.
|
---|
240 | *
|
---|
241 | * @returns IPRT status code.
|
---|
242 | * @param hVfsIos The VFS I/O stream handle.
|
---|
243 | * @param pSgBuf Pointer to a scatter buffer descriptor. The number
|
---|
244 | * of bytes described by the segments is what will be
|
---|
245 | * attemted read.
|
---|
246 | * @param fBlocking Whether the call is blocking (@c true) or not. If
|
---|
247 | * not, the @a pcbRead parameter must not be NULL.
|
---|
248 | * @param pcbRead Where to store the number of bytes actually read.
|
---|
249 | * This can be NULL if @a fBlocking is true.
|
---|
250 | * @sa RTFileSgRead, RTSocketSgRead
|
---|
251 | */
|
---|
252 | RTDECL(int) RTVfsIoStrmSgRead(RTVFSIOSTREAM hVfsIos, PCRTSGBUF pSgBuf, bool fBlocking, size_t *pcbRead);
|
---|
253 |
|
---|
254 | /**
|
---|
255 | * Write bytes to the I/O stream from a gather buffer.
|
---|
256 | *
|
---|
257 | * @returns IPRT status code.
|
---|
258 | * @param hVfsIos The VFS I/O stream handle.
|
---|
259 | * @param pSgBuf Pointer to a gather buffer descriptor. The number
|
---|
260 | * of bytes described by the segments is what will be
|
---|
261 | * attemted written.
|
---|
262 | * @param fBlocking Whether the call is blocking (@c true) or not. If
|
---|
263 | * not, the @a pcbWritten parameter must not be NULL.
|
---|
264 | * @param pcbRead Where to store the number of bytes actually written.
|
---|
265 | * This can be NULL if @a fBlocking is true.
|
---|
266 | * @sa RTFileSgWrite, RTSocketSgWrite
|
---|
267 | */
|
---|
268 | RTDECL(int) RTVfsIoStrmSgWrite(RTVFSIOSTREAM hVfsIos, PCRTSGBUF pSgBuf, bool fBlocking, size_t *pcbWritten);
|
---|
269 |
|
---|
270 | /**
|
---|
271 | * Flush any buffered data to the I/O stream.
|
---|
272 | *
|
---|
273 | * @returns IPRT status code.
|
---|
274 | * @param hVfsIos The VFS I/O stream handle.
|
---|
275 | * @sa RTFileFlush, RTPipeFlush
|
---|
276 | */
|
---|
277 | RTDECL(int) RTVfsIoStrmFlush(RTVFSIOSTREAM hVfsIos);
|
---|
278 |
|
---|
279 | /**
|
---|
280 | * Poll for events.
|
---|
281 | *
|
---|
282 | * @returns IPRT status code.
|
---|
283 | * @param hVfsIos The VFS I/O stream handle.
|
---|
284 | * @param fEvents The events to poll for (RTPOLL_EVT_XXX).
|
---|
285 | * @param cMillies How long to wait for event to eventuate.
|
---|
286 | * @param fIntr Whether the wait is interruptible and can return
|
---|
287 | * VERR_INTERRUPTED (@c true) or if this condition
|
---|
288 | * should be hidden from the caller (@c false).
|
---|
289 | * @param pfRetEvents Where to return the event mask.
|
---|
290 | * @sa RTPollSetAdd, RTPoll, RTPollNoResume.
|
---|
291 | */
|
---|
292 | RTDECL(RTFOFF) RTVfsIoStrmPoll(RTVFSIOSTREAM hVfsIos, uint32_t fEvents, RTMSINTERVAL cMillies, bool fIntr,
|
---|
293 | uint32_t *pfRetEvents);
|
---|
294 | /**
|
---|
295 | * Tells the current I/O stream position.
|
---|
296 | *
|
---|
297 | * @returns Zero or higher - where to return the I/O stream offset. Values
|
---|
298 | * below zero are IPRT status codes (VERR_XXX).
|
---|
299 | * @param hVfsIos The VFS I/O stream handle.
|
---|
300 | * @sa RTFileTell
|
---|
301 | */
|
---|
302 | RTDECL(RTFOFF) RTVfsIoStrmTell(RTVFSIOSTREAM hVfsIos);
|
---|
303 |
|
---|
304 | /**
|
---|
305 | * Skips @a cb ahead in the stream.
|
---|
306 | *
|
---|
307 | * @returns IPRT status code.
|
---|
308 | * @param hVfsIos The VFS I/O stream handle.
|
---|
309 | * @param cb The number bytes to skip.
|
---|
310 | */
|
---|
311 | RTDECL(int) RTVfsIoStrmSkip(RTVFSIOSTREAM hVfsIos, RTFOFF cb);
|
---|
312 |
|
---|
313 | /**
|
---|
314 | * Fills the stream with @a cb zeros.
|
---|
315 | *
|
---|
316 | * @returns IPRT status code.
|
---|
317 | * @param hVfsIos The VFS I/O stream handle.
|
---|
318 | * @param cb The number of zero bytes to insert.
|
---|
319 | */
|
---|
320 | RTDECL(int) RTVfsIoStrmZeroFill(RTVFSIOSTREAM hVfsIos, RTFOFF cb);
|
---|
321 | /** @} */
|
---|
322 |
|
---|
323 |
|
---|
324 | /** @defgroup grp_vfs_file VFS File API
|
---|
325 | * @{
|
---|
326 | */
|
---|
327 | RTDECL(int) RTVfsFileOpen(RTVFS hVfs, const char *pszFilename, uint32_t fOpen, PRTVFSFILE phVfsFile);
|
---|
328 |
|
---|
329 | /**
|
---|
330 | * Create a VFS file handle from a standard IPRT file handle (RTFILE).
|
---|
331 | *
|
---|
332 | * @returns IPRT status code.
|
---|
333 | * @param hFile The standard IPRT file handle.
|
---|
334 | * @param fOpen The flags the handle was opened with. Pass 0 to
|
---|
335 | * have these detected.
|
---|
336 | * @param fLeaveOpen Whether to leave the handle open when the VFS file
|
---|
337 | * is released, or to close it (@c false).
|
---|
338 | * @param phVfsFile Where to return the VFS file handle.
|
---|
339 | */
|
---|
340 | RTDECL(int) RTVfsFileFromRTFile(RTFILE hFile, uint32_t fOpen, bool fLeaveOpen, PRTVFSFILE phVfsFile);
|
---|
341 | RTDECL(RTHCUINTPTR) RTVfsFileToNative(RTFILE hVfsFile);
|
---|
342 |
|
---|
343 | /**
|
---|
344 | * Convert the VFS file handle to a VFS I/O stream handle.
|
---|
345 | *
|
---|
346 | * @returns The VFS I/O stream handle on success, this must be released.
|
---|
347 | * NIL_RTVFSIOSTREAM if the file handle is invalid.
|
---|
348 | * @param hVfsFile The VFS file handle.
|
---|
349 | * @sa RTVfsIoStrmToFile
|
---|
350 | */
|
---|
351 | RTDECL(RTVFSIOSTREAM) RTVfsFileToIoStream(RTVFSFILE hVfsFile);
|
---|
352 |
|
---|
353 | /**
|
---|
354 | * Retains a reference to the VFS file handle.
|
---|
355 | *
|
---|
356 | * @returns New reference count on success, UINT32_MAX on failure.
|
---|
357 | * @param hVfsFile The VFS file handle.
|
---|
358 | */
|
---|
359 | RTDECL(uint32_t) RTVfsFileRetain(RTVFSFILE hVfsFile);
|
---|
360 |
|
---|
361 | /**
|
---|
362 | * Releases a reference to the VFS file handle.
|
---|
363 | *
|
---|
364 | * @returns New reference count on success (0 if closed), UINT32_MAX on failure.
|
---|
365 | * @param hVfsFile The VFS file handle.
|
---|
366 | */
|
---|
367 | RTDECL(uint32_t) RTVfsFileRelease(RTVFSFILE hVfsFile);
|
---|
368 |
|
---|
369 | RTDECL(int) RTVfsFileQueryInfo(RTVFSFILE hVfsFile, PRTFSOBJINFO pObjInfo, RTFSOBJATTRADD enmAddAttr);
|
---|
370 | RTDECL(int) RTVfsFileRead(RTVFSFILE hVfsFile, void *pvBuf, size_t cbToRead, size_t *pcbRead);
|
---|
371 | RTDECL(int) RTVfsFileReadAt(RTVFSFILE hVfsFile, RTFOFF off, void *pvBuf, size_t cbToRead, size_t *pcbRead);
|
---|
372 | RTDECL(int) RTVfsFileWrite(RTVFSFILE hVfsFile, const void *pvBuf, size_t cbToWrite, size_t *pcbWritten);
|
---|
373 | RTDECL(int) RTVfsFileWriteAt(RTVFSFILE hVfsFile, RTFOFF off, const void *pvBuf, size_t cbToWrite, size_t *pcbWritten);
|
---|
374 | RTDECL(int) RTVfsFileFlush(RTVFSFILE hVfsFile);
|
---|
375 | RTDECL(RTFOFF) RTVfsFilePoll(RTVFSFILE hVfsFile, uint32_t fEvents, RTMSINTERVAL cMillies, bool fIntr,
|
---|
376 | uint32_t *pfRetEvents);
|
---|
377 | RTDECL(RTFOFF) RTVfsFileTell(RTVFSFILE hVfsFile);
|
---|
378 |
|
---|
379 | RTDECL(int) RTVfsFileSeek(RTVFSFILE hVfsFile, RTFOFF offSeek, uint32_t uMethod, uint64_t *poffActual);
|
---|
380 | RTDECL(int) RTVfsFileSetSize(RTVFSFILE hVfsFile, uint64_t cbSize);
|
---|
381 | RTDECL(int) RTVfsFileGetSize(RTVFSFILE hVfsFile, uint64_t *pcbSize);
|
---|
382 | RTDECL(RTFOFF) RTVfsFileGetMaxSize(RTVFSFILE hVfsFile);
|
---|
383 | RTDECL(int) RTVfsFileGetMaxSizeEx(RTVFSFILE hVfsFile, PRTFOFF pcbMax);
|
---|
384 |
|
---|
385 | /** @} */
|
---|
386 |
|
---|
387 | /** @} */
|
---|
388 |
|
---|
389 | RT_C_DECLS_END
|
---|
390 |
|
---|
391 | #endif /* !___iprt_vfs_h */
|
---|
392 |
|
---|
393 |
|
---|