VirtualBox

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

Last change on this file since 33859 was 33859, checked in by vboxsync, 14 years ago

iprt/vfs: more code.

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 14.9 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/symlink.h>
34#include <iprt/sg.h>
35#include <iprt/time.h>
36
37
38RT_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. */
60typedef struct RTVFSINTERNAL *RTVFS;
61/** Pointer to a VFS handle. */
62typedef RTVFS *PRTVFS;
63/** A NIL VFS directory handle. */
64#define NIL_RTVFS ((RTVFS)~(uintptr_t)0)
65
66/** Virtual Filesystem directory handle. */
67typedef struct RTVFSDIRINTERNAL *RTVFSDIR;
68/** Pointer to a VFS directory handle. */
69typedef RTVFSDIR *PRTVFSDIR;
70/** A NIL VFS directory handle. */
71#define NIL_RTVFSDIR ((RTVFSDIR)~(uintptr_t)0)
72
73/** Virtual Filesystem I/O stream handle. */
74typedef struct RTVFSIOSTREAMINTERNAL *RTVFSIOSTREAM;
75/** Pointer to a VFS I/O stream handle. */
76typedef RTVFSIOSTREAM *PRTVFSIOSTREAM;
77/** A NIL VFS I/O stream handle. */
78#define NIL_RTVFSIOSTREAM ((RTVFSIOSTREAM)~(uintptr_t)0)
79
80/** Virtual Filesystem file handle. */
81typedef struct RTVFSFILEINTERNAL *RTVFSFILE;
82/** Pointer to a VFS file handle. */
83typedef RTVFSFILE *PRTVFSFILE;
84/** A NIL VFS file handle. */
85#define NIL_RTVFSFILE ((RTVFSFILE)~(uintptr_t)0)
86
87/** Virtual Filesystem symbolic link handle. */
88typedef struct RTVFSSYMLINKINTERNAL *RTVFSSYMLINK;
89/** Pointer to a VFS symbolic link handle. */
90typedef 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 */
113RTDECL(int) RTVfsCreate(const char *pszName, uint32_t fFlags, PRTVFS phVfs);
114RTDECL(uint32_t) RTVfsRetain(RTVFS phVfs);
115RTDECL(uint32_t) RTVfsRelease(RTVFS phVfs);
116RTDECL(int) RTVfsAttach(RTVFS hVfs, const char *pszMountPoint, uint32_t fFlags, RTVFS hVfsAttach);
117RTDECL(int) RTVfsDetach(RTVFS hVfs, const char *pszMountPoint, RTVFS hVfsToDetach, PRTVFS *phVfsDetached);
118RTDECL(uint32_t) RTVfsGetAttachmentCount(RTVFS hVfs);
119RTDECL(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 */
133RTDECL(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 */
141RTDECL(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 */
159RTDECL(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 */
175RTDECL(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 */
183RTDECL(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 */
193RTDECL(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 */
204RTDECL(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 */
220RTDECL(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 */
236RTDECL(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 */
252RTDECL(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 */
268RTDECL(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 */
277RTDECL(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 */
292RTDECL(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 */
302RTDECL(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 */
311RTDECL(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 */
320RTDECL(int) RTVfsIoStrmZeroFill(RTVFSIOSTREAM hVfsIos, RTFOFF cb);
321/** @} */
322
323
324/** @defgroup grp_vfs_file VFS File API
325 * @{
326 */
327RTDECL(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 */
340RTDECL(int) RTVfsFileFromRTFile(RTFILE hFile, uint32_t fOpen, bool fLeaveOpen, PRTVFSFILE phVfsFile);
341RTDECL(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 */
351RTDECL(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 */
359RTDECL(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 */
367RTDECL(uint32_t) RTVfsFileRelease(RTVFSFILE hVfsFile);
368
369RTDECL(int) RTVfsFileQueryInfo(RTVFSFILE hVfsFile, PRTFSOBJINFO pObjInfo, RTFSOBJATTRADD enmAddAttr);
370RTDECL(int) RTVfsFileRead(RTVFSFILE hVfsFile, void *pvBuf, size_t cbToRead, size_t *pcbRead);
371RTDECL(int) RTVfsFileReadAt(RTVFSFILE hVfsFile, RTFOFF off, void *pvBuf, size_t cbToRead, size_t *pcbRead);
372RTDECL(int) RTVfsFileWrite(RTVFSFILE hVfsFile, const void *pvBuf, size_t cbToWrite, size_t *pcbWritten);
373RTDECL(int) RTVfsFileWriteAt(RTVFSFILE hVfsFile, RTFOFF off, const void *pvBuf, size_t cbToWrite, size_t *pcbWritten);
374RTDECL(int) RTVfsFileFlush(RTVFSFILE hVfsFile);
375RTDECL(RTFOFF) RTVfsFilePoll(RTVFSFILE hVfsFile, uint32_t fEvents, RTMSINTERVAL cMillies, bool fIntr,
376 uint32_t *pfRetEvents);
377RTDECL(RTFOFF) RTVfsFileTell(RTVFSFILE hVfsFile);
378
379RTDECL(int) RTVfsFileSeek(RTVFSFILE hVfsFile, RTFOFF offSeek, uint32_t uMethod, uint64_t *poffActual);
380RTDECL(int) RTVfsFileSetSize(RTVFSFILE hVfsFile, uint64_t cbSize);
381RTDECL(int) RTVfsFileGetSize(RTVFSFILE hVfsFile, uint64_t *pcbSize);
382RTDECL(RTFOFF) RTVfsFileGetMaxSize(RTVFSFILE hVfsFile);
383RTDECL(int) RTVfsFileGetMaxSizeEx(RTVFSFILE hVfsFile, PRTFOFF pcbMax);
384
385/** @} */
386
387/** @} */
388
389RT_C_DECLS_END
390
391#endif /* !___iprt_vfs_h */
392
393
Note: See TracBrowser for help on using the repository browser.

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette