VirtualBox

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

Last change on this file since 78303 was 77047, checked in by vboxsync, 6 years ago

iprt/isomaker: Optimized native handle (file descriptor) usage when adding real directories.

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 77.1 KB
Line 
1/** @file
2 * IPRT - Virtual Filesystem.
3 */
4
5/*
6 * Copyright (C) 2010-2019 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_INCLUDED_vfs_h
27#define IPRT_INCLUDED_vfs_h
28#ifndef RT_WITHOUT_PRAGMA_ONCE
29# pragma once
30#endif
31
32#include <iprt/cdefs.h>
33#include <iprt/types.h>
34#include <iprt/dir.h>
35#include <iprt/fs.h>
36#include <iprt/handle.h>
37#include <iprt/symlink.h>
38#include <iprt/sg.h>
39#include <iprt/time.h>
40
41
42RT_C_DECLS_BEGIN
43
44/** @defgroup grp_rt_vfs RTVfs - Virtual Filesystem
45 * @ingroup grp_rt
46 *
47 * The virtual filesystem APIs are intended to make it possible to work on
48 * container files, file system sub-trees, file system overlays and other custom
49 * filesystem configurations. It also makes it possible to create filters, like
50 * automatically gunzipping a tar.gz file before feeding it to the RTTar API for
51 * unpacking - or wise versa.
52 *
53 * The virtual filesystem APIs are intended to mirror the RTDir, RTFile, RTPath
54 * and RTFs APIs pretty closely so that rewriting a piece of code to work with
55 * it should be easy. However there are some differences to the way the APIs
56 * works and the user should heed the documentation. The differences are
57 * usually motivated by simplification and in some case to make the VFS more
58 * flexible.
59 *
60 * @{
61 */
62
63/**
64 * The object type.
65 */
66typedef enum RTVFSOBJTYPE
67{
68 /** Invalid type. */
69 RTVFSOBJTYPE_INVALID = 0,
70 /** Pure base object.
71 * This is returned by the filesystem stream to represent directories,
72 * devices, fifos and similar that needs to be created. */
73 RTVFSOBJTYPE_BASE,
74 /** Virtual filesystem. */
75 RTVFSOBJTYPE_VFS,
76 /** Filesystem stream. */
77 RTVFSOBJTYPE_FS_STREAM,
78 /** Pure I/O stream. */
79 RTVFSOBJTYPE_IO_STREAM,
80 /** Directory. */
81 RTVFSOBJTYPE_DIR,
82 /** File. */
83 RTVFSOBJTYPE_FILE,
84 /** Symbolic link. */
85 RTVFSOBJTYPE_SYMLINK,
86 /** End of valid object types. */
87 RTVFSOBJTYPE_END,
88 /** Pure I/O stream. */
89 RTVFSOBJTYPE_32BIT_HACK = 0x7fffffff
90} RTVFSOBJTYPE;
91/** Pointer to a VFS object type. */
92typedef RTVFSOBJTYPE *PRTVFSOBJTYPE;
93
94
95
96/** @name RTVfsCreate flags
97 * @{ */
98/** Whether the file system is read-only. */
99#define RTVFS_C_READONLY RT_BIT(0)
100/** Whether we the VFS should be thread safe (i.e. automaticaly employ
101 * locks). */
102#define RTVFS_C_THREAD_SAFE RT_BIT(1)
103/** @} */
104
105/**
106 * Creates an empty virtual filesystem.
107 *
108 * @returns IPRT status code.
109 * @param pszName Name, for logging and such.
110 * @param fFlags Flags, MBZ.
111 * @param phVfs Where to return the VFS handle. Release the returned
112 * reference by calling RTVfsRelease.
113 */
114RTDECL(int) RTVfsCreate(const char *pszName, uint32_t fFlags, PRTVFS phVfs);
115RTDECL(uint32_t) RTVfsRetain(RTVFS hVfs);
116RTDECL(uint32_t) RTVfsRetainDebug(RTVFS hVfs, RT_SRC_POS_DECL);
117RTDECL(uint32_t) RTVfsRelease(RTVFS hVfs);
118
119/** @name RTVFSMNT_F_XXX - Flags for RTVfsMount
120 * @{ */
121/** Mount read-only. */
122#define RTVFSMNT_F_READ_ONLY RT_BIT_32(0)
123/** Purpose is . */
124#define RTVFSMNT_F_FOR_RANGE_IN_USE RT_BIT_32(1)
125/** Valid mask. */
126#define RTVFSMNT_F_VALID_MASK UINT32_C(0x00000003)
127/** @} */
128
129/**
130 * Does the file system detection and mounting.
131 *
132 * @returns IPRT status code.
133 * @retval VERR_VFS_UNSUPPORTED_FORMAT if not recognized as a support file
134 * system.
135 * @param hVfsFileIn The file handle of the volume.
136 * @param fFlags RTVFSMTN_F_XXX.
137 * @param phVfs Where to return the VFS handle on success.
138 * @param pErrInfo Where to return additional error information.
139 * Optional.
140 */
141RTDECL(int) RTVfsMountVol(RTVFSFILE hVfsFileIn, uint32_t fFlags, PRTVFS phVfs, PRTERRINFO pErrInfo);
142
143RTDECL(int) RTVfsAttach(RTVFS hVfs, const char *pszMountPoint, uint32_t fFlags, RTVFS hVfsAttach);
144RTDECL(int) RTVfsDetach(RTVFS hVfs, const char *pszMountPoint, RTVFS hVfsToDetach, PRTVFS *phVfsDetached);
145RTDECL(uint32_t) RTVfsGetAttachmentCount(RTVFS hVfs);
146RTDECL(int) RTVfsGetAttachment(RTVFS hVfs, uint32_t iOrdinal, PRTVFS *phVfsAttached, uint32_t *pfFlags,
147 char *pszMountPoint, size_t cbMountPoint);
148
149/**
150 * Opens the root director of the given VFS.
151 *
152 * @returns IPRT status code.
153 * @param hVfs VFS handle.
154 * @param phDir Where to return the root directory handle.
155 */
156RTDECL(int) RTVfsOpenRoot(RTVFS hVfs, PRTVFSDIR phDir);
157
158/**
159 * Queries information about a object in the virtual filesystem.
160 *
161 * @returns IPRT Status code.
162 * @param hVfs VFS handle.
163 * @param pszPath Path to the object, relative to the VFS root.
164 * @param pObjInfo Where to return info.
165 * @param enmAddAttr What to return.
166 * @param fFlags RTPATH_F_XXX.
167 * @sa RTPathQueryInfoEx, RTVfsDirQueryPathInfo, RTVfsObjQueryInfo
168 */
169RTDECL(int) RTVfsQueryPathInfo(RTVFS hVfs, const char *pszPath, PRTFSOBJINFO pObjInfo,
170 RTFSOBJATTRADD enmAddAttr, uint32_t fFlags);
171
172/**
173 * Checks whether a given range is in use by the virtual filesystem.
174 *
175 * @returns IPRT status code.
176 * @param hVfs VFS handle.
177 * @param off Start offset to check.
178 * @param cb Number of bytes to check.
179 * @param pfUsed Where to store the result.
180 */
181RTDECL(int) RTVfsQueryRangeState(RTVFS hVfs, uint64_t off, size_t cb, bool *pfUsed);
182
183
184/** @defgroup grp_vfs_obj VFS Base Object API
185 * @{
186 */
187
188/**
189 * Retains a reference to the VFS base object handle.
190 *
191 * @returns New reference count on success, UINT32_MAX on failure.
192 * @param hVfsObj The VFS base object handle.
193 */
194RTDECL(uint32_t) RTVfsObjRetain(RTVFSOBJ hVfsObj);
195RTDECL(uint32_t) RTVfsObjRetainDebug(RTVFSOBJ hVfsObj, RT_SRC_POS_DECL);
196
197/**
198 * Releases a reference to the VFS base handle.
199 *
200 * @returns New reference count on success (0 if closed), UINT32_MAX on failure.
201 * @param hVfsObj The VFS base object handle.
202 */
203RTDECL(uint32_t) RTVfsObjRelease(RTVFSOBJ hVfsObj);
204
205/** @name RTVFSOBJ_F_XXX - Flags or RTVfsObjOpen and RTVfsDirOpenObj.
206 * @note Must leave space for RTPATH_F_XXX.
207 * @{ */
208/** Directory (RTFS_TYPE_DIRECTORY). */
209#define RTVFSOBJ_F_OPEN_DIRECTORY RT_BIT_32(8)
210/** Symbolic link (RTFS_TYPE_SYMLINK). */
211#define RTVFSOBJ_F_OPEN_SYMLINK RT_BIT_32(9)
212/** Regular file (RTFS_TYPE_FILE). */
213#define RTVFSOBJ_F_OPEN_FILE RT_BIT_32(10)
214/** Character device (RTFS_TYPE_DEV_CHAR). */
215#define RTVFSOBJ_F_OPEN_DEV_CHAR RT_BIT_32(11)
216/** Block device (RTFS_TYPE_DEV_BLOCK). */
217#define RTVFSOBJ_F_OPEN_DEV_BLOCK RT_BIT_32(12)
218/** Named pipe (fifo) (RTFS_TYPE_FIFO). */
219#define RTVFSOBJ_F_OPEN_FIFO RT_BIT_32(13)
220/** Socket (RTFS_TYPE_SOCKET). */
221#define RTVFSOBJ_F_OPEN_SOCKET RT_BIT_32(14)
222/** Mounted VFS. */
223#define RTVFSOBJ_F_OPEN_MOUNT RT_BIT_32(15)
224/** Mask object types we wish to open. */
225#define RTVFSOBJ_F_OPEN_MASK UINT32_C(0x0000ff00)
226/** Any kind of object that translates to RTVFSOBJTYPE_FILE. */
227#define RTVFSOBJ_F_OPEN_ANY_FILE (RTVFSOBJ_F_OPEN_FILE | RTVFSOBJ_F_OPEN_DEV_BLOCK)
228/** Any kind of object that translates to RTVFSOBJTYPE_IOS or
229 * RTVFSOBJTYPE_FILE. */
230#define RTVFSOBJ_F_OPEN_ANY_IO_STREAM ( RTVFSOBJ_F_ANY_OPEN_FILE | RTVFSOBJ_F_DEV_OPEN_BLOCK \
231 | RTVFSOBJ_F_OPEN_FIFO | RTVFSOBJ_F_OPEN_SOCKET)
232/** Any kind of object. */
233#define RTVFSOBJ_F_OPEN_ANY RTVFSOBJ_F_OPEN_MASK
234
235/** Do't create anything, return file not found. */
236#define RTVFSOBJ_F_CREATE_NOTHING UINT32_C(0x00000000)
237/** Create a file if the if the object was not found and the RTFILE_O_XXX
238 * flags allows it. */
239#define RTVFSOBJ_F_CREATE_FILE UINT32_C(0x00010000)
240/** Create a directory if the object was not found and the RTFILE_O_XXX
241 * flags allows it. */
242#define RTVFSOBJ_F_CREATE_DIRECTORY UINT32_C(0x00020000)
243/** The creation type mask. */
244#define RTVFSOBJ_F_CREATE_MASK UINT32_C(0x00070000)
245
246/** Indicate that this call is for traversal.
247 * @internal only */
248#define RTVFSOBJ_F_TRAVERSAL RT_BIT_32(31)
249/** Valid mask for external callers. */
250#define RTVFSOBJ_F_VALID_MASK UINT32_C(0x0007ff00)
251/** @} */
252
253/**
254 * Opens any file system object in the given VFS.
255 *
256 * @returns IPRT status code.
257 * @param hVfs The VFS to open the object within.
258 * @param pszPath Path to the file.
259 * @param fFileOpen RTFILE_O_XXX flags.
260 * @param fObjFlags More flags: RTVFSOBJ_F_XXX, RTPATH_F_XXX.
261 * @param phVfsObj Where to return the object handle.
262 * @sa RTVfsDirOpenObj, RTVfsDirOpenDir, RTVfsDirOpenFile
263 */
264RTDECL(int) RTVfsObjOpen(RTVFS hVfs, const char *pszPath, uint64_t fFileOpen, uint32_t fObjFlags, PRTVFSOBJ phVfsObj);
265
266/**
267 * Query information about the object.
268 *
269 * @returns IPRT status code.
270 * @retval VERR_NOT_SUPPORTED if the @a enmAddAttr value is not handled by the
271 * implementation.
272 *
273 * @param hVfsObj The VFS object handle.
274 * @param pObjInfo Where to return the info.
275 * @param enmAddAttr Which additional attributes should be retrieved.
276 * @sa RTVfsIoStrmQueryInfo, RTVfsFileQueryInfo, RTFileQueryInfo,
277 * RTPathQueryInfo
278 */
279RTDECL(int) RTVfsObjQueryInfo(RTVFSOBJ hVfsObj, PRTFSOBJINFO pObjInfo, RTFSOBJATTRADD enmAddAttr);
280
281/**
282 * Sets the file mode for the given VFS object.
283 *
284 * @returns IPRT status code.
285 * @retval VERR_INVALID_FUNCTION if the object type has no file mode to set.
286 * Only directories, files and symbolic links support this operation.
287 *
288 * @param hVfsObj The VFS object handle.
289 * @param fMode The mode mask.
290 * @param fMask The bits in the mode mask which should be changed.
291 */
292RTDECL(int) RTVfsObjSetMode(RTVFSOBJ hVfsObj, RTFMODE fMode, RTFMODE fMask);
293
294/**
295 * Sets one or more timestamps for the given VFS object.
296 *
297 * @returns IPRT status code.
298 * @retval VERR_INVALID_FUNCTION if the object type has no file mode to set.
299 * Only directories, files and symbolic links support this operation.
300 *
301 * @param hVfsObj The VFS object handle.
302 * @param pAccessTime Pointer to the new access time. NULL if not to
303 * be changed.
304 * @param pModificationTime Pointer to the new modifcation time. NULL if not
305 * to be changed.
306 * @param pChangeTime Pointer to the new change time. NULL if not to
307 * be changed.
308 * @param pBirthTime Pointer to the new time of birth. NULL if not to
309 * be changed.
310 *
311 * @remarks See RTFileSetTimes for restrictions and behavior imposed by the
312 * host OS or underlying VFS provider.
313 * @sa RTFileSetTimes, RTPathSetTimes
314 */
315RTDECL(int) RTVfsObjSetTimes(RTVFSOBJ hVfsObj, PCRTTIMESPEC pAccessTime, PCRTTIMESPEC pModificationTime,
316 PCRTTIMESPEC pChangeTime, PCRTTIMESPEC pBirthTime);
317
318/**
319 * Set the unix style owner and group on the given VFS object.
320 *
321 * @returns IPRT status code.
322 * @retval VERR_INVALID_FUNCTION if the object type has no file mode to set.
323 * Only directories, files and symbolic links support this operation.
324 *
325 * @param hVfsObj The VFS object handle.
326 * @param uid The user ID of the new owner. NIL_RTUID if
327 * unchanged.
328 * @param gid The group ID of the new owner group. NIL_RTGID if
329 * unchanged.
330 *
331 * @sa RTFileSetOwner, RTPathSetOwner.
332 */
333RTDECL(int) RTVfsObjSetOwner(RTVFSOBJ hVfsObj, RTUID uid, RTGID gid);
334
335
336/**
337 * Gets the type of a VFS object.
338 *
339 * @returns The VFS object type on success, RTVFSOBJTYPE_INVALID on failure.
340 * @param hVfsObj The VFS base object handle.
341 */
342RTDECL(RTVFSOBJTYPE) RTVfsObjGetType(RTVFSOBJ hVfsObj);
343
344/**
345 * Converts a VFS base object handle to a VFS handle.
346 *
347 * @returns Referenced handle on success, NIL on failure.
348 * @param hVfsObj The VFS base object handle.
349 */
350RTDECL(RTVFS) RTVfsObjToVfs(RTVFSOBJ hVfsObj);
351
352/**
353 * Converts a VFS base object handle to a VFS filesystem stream handle.
354 *
355 * @returns Referenced handle on success, NIL on failure.
356 * @param hVfsObj The VFS base object handle.
357 */
358RTDECL(RTVFSFSSTREAM) RTVfsObjToFsStream(RTVFSOBJ hVfsObj);
359
360/**
361 * Converts a VFS base object handle to a VFS directory handle.
362 *
363 * @returns Referenced handle on success, NIL on failure.
364 * @param hVfsObj The VFS base object handle.
365 */
366RTDECL(RTVFSDIR) RTVfsObjToDir(RTVFSOBJ hVfsObj);
367
368/**
369 * Converts a VFS base object handle to a VFS I/O stream handle.
370 *
371 * @returns Referenced handle on success, NIL on failure.
372 * @param hVfsObj The VFS base object handle.
373 */
374RTDECL(RTVFSIOSTREAM) RTVfsObjToIoStream(RTVFSOBJ hVfsObj);
375
376/**
377 * Converts a VFS base object handle to a VFS file handle.
378 *
379 * @returns Referenced handle on success, NIL on failure.
380 * @param hVfsObj The VFS base object handle.
381 */
382RTDECL(RTVFSFILE) RTVfsObjToFile(RTVFSOBJ hVfsObj);
383
384/**
385 * Converts a VFS base object handle to a VFS symbolic link handle.
386 *
387 * @returns Referenced handle on success, NIL on failure.
388 * @param hVfsObj The VFS base object handle.
389 */
390RTDECL(RTVFSSYMLINK) RTVfsObjToSymlink(RTVFSOBJ hVfsObj);
391
392
393/**
394 * Converts a VFS handle to a VFS base object handle.
395 *
396 * @returns Referenced handle on success, NIL if the input handle was invalid.
397 * @param hVfs The VFS handle.
398 */
399RTDECL(RTVFSOBJ) RTVfsObjFromVfs(RTVFS hVfs);
400
401/**
402 * Converts a VFS filesystem stream handle to a VFS base object handle.
403 *
404 * @returns Referenced handle on success, NIL if the input handle was invalid.
405 * @param hVfsFss The VFS filesystem stream handle.
406 */
407RTDECL(RTVFSOBJ) RTVfsObjFromFsStream(RTVFSFSSTREAM hVfsFss);
408
409/**
410 * Converts a VFS directory handle to a VFS base object handle.
411 *
412 * @returns Referenced handle on success, NIL if the input handle was invalid.
413 * @param hVfsDir The VFS directory handle.
414 */
415RTDECL(RTVFSOBJ) RTVfsObjFromDir(RTVFSDIR hVfsDir);
416
417/**
418 * Converts a VFS I/O stream handle to a VFS base object handle.
419 *
420 * @returns Referenced handle on success, NIL if the input handle was invalid.
421 * @param hVfsIos The VFS I/O stream handle.
422 */
423RTDECL(RTVFSOBJ) RTVfsObjFromIoStream(RTVFSIOSTREAM hVfsIos);
424
425/**
426 * Converts a VFS file handle to a VFS base object handle.
427 *
428 * @returns Referenced handle on success, NIL if the input handle was invalid.
429 * @param hVfsFile The VFS file handle.
430 */
431RTDECL(RTVFSOBJ) RTVfsObjFromFile(RTVFSFILE hVfsFile);
432
433/**
434 * Converts a VFS symbolic link handle to a VFS base object handle.
435 *
436 * @returns Referenced handle on success, NIL if the input handle was invalid.
437 * @param hVfsSym The VFS symbolic link handle.
438 */
439RTDECL(RTVFSOBJ) RTVfsObjFromSymlink(RTVFSSYMLINK hVfsSym);
440
441/** @} */
442
443
444/** @defgroup grp_vfs_fsstream VFS Filesystem Stream API
445 *
446 * Filesystem streams are for tar, cpio and similar. Any virtual filesystem can
447 * be turned into a filesystem stream using RTVfsFsStrmFromVfs.
448 *
449 * @{
450 */
451
452RTDECL(uint32_t) RTVfsFsStrmRetain(RTVFSFSSTREAM hVfsFss);
453RTDECL(uint32_t) RTVfsFsStrmRetainDebug(RTVFSFSSTREAM hVfsFss, RT_SRC_POS_DECL);
454RTDECL(uint32_t) RTVfsFsStrmRelease(RTVFSFSSTREAM hVfsFss);
455RTDECL(int) RTVfsFsStrmQueryInfo(RTVFSFSSTREAM hVfsFss, PRTFSOBJINFO pObjInfo, RTFSOBJATTRADD enmAddAttr);
456
457/**
458 * Gets the next object in the stream.
459 *
460 * This call may affect the stream posision of a previously returned object.
461 *
462 * The type of object returned here typically boils down to three types:
463 * - I/O streams (representing files),
464 * - symbolic links
465 * - base object
466 * The base objects represent anything not convered by the two other, i.e.
467 * directories, device nodes, fifos, sockets and whatnot. The details can be
468 * queried using RTVfsObjQueryInfo.
469 *
470 * That said, absolutely any object except for filesystem stream objects can be
471 * returned by this call. Any generic code is adviced to just deal with it all.
472 *
473 * @returns IPRT status code.
474 * @retval VINF_SUCCESS if a new object was retrieved.
475 * @retval VERR_EOF when there are no more objects.
476 * @retval VERR_INVALID_FUNCTION if called on a non-readable stream.
477 *
478 * @param hVfsFss The file system stream handle.
479 * @param ppszName Where to return the object name. Must be freed by
480 * calling RTStrFree.
481 * @param penmType Where to return the object type.
482 * @param phVfsObj Where to return the object handle (referenced). This
483 * must be cast to the desired type before use.
484 */
485RTDECL(int) RTVfsFsStrmNext(RTVFSFSSTREAM hVfsFss, char **ppszName, RTVFSOBJTYPE *penmType, PRTVFSOBJ phVfsObj);
486
487/**
488 * Appends a VFS object to the stream.
489 *
490 * The stream must be writable.
491 *
492 * @returns IPRT status code.
493 * @retval VERR_INVALID_FUNCTION if called on a non-writable stream.
494 * @param hVfsFss The file system stream handle.
495 * @param pszPath The path.
496 * @param hVfsObj The VFS object to add.
497 * @param fFlags RTVFSFSSTRM_ADD_F_XXX.
498 */
499RTDECL(int) RTVfsFsStrmAdd(RTVFSFSSTREAM hVfsFss, const char *pszPath, RTVFSOBJ hVfsObj, uint32_t fFlags);
500
501/** @name RTVFSFSSTRM_ADD_F_XXX - Flags for RTVfsFsStrmAdd.
502 * @{ */
503/** Input is an I/O stream of indeterminate length, read to the end and then
504 * update the file header.
505 * @note This is *only* possible if the output stream is actually a file. */
506#define RTVFSFSSTRM_ADD_F_STREAM RT_BIT_32(0)
507/** Mask of flags specific to the target stream. */
508#define RTVFSFSSTRM_ADD_F_SPECIFIC_MASK UINT32_C(0xff000000)
509/** Valid bits. */
510#define RTVFSFSSTRM_ADD_F_VALID_MASK UINT32_C(0xff000001)
511/** @} */
512
513/**
514 * Pushes an byte stream onto the stream.
515 *
516 * The stream must be writable.
517 *
518 * This differs from RTVfsFsStrmAdd() in that it will create a regular file in
519 * the output file system stream and provide the actual content bytes via the
520 * returned I/O stream object.
521 *
522 * @returns IPRT status code.
523 * @retval VERR_INVALID_FUNCTION if called on a non-writable stream.
524 * @param hVfsFss The file system stream handle.
525 * @param pszPath The path to the file.
526 * @param cbFile The file size. This can also be set to UINT64_MAX if
527 * the file system stream is backed by a file.
528 * @param paObjInfo Array of zero or more RTFSOBJINFO structures containing
529 * different pieces of information about the file. If any
530 * provided, the first one should be a RTFSOBJATTRADD_UNIX
531 * one, additional can be supplied if wanted. What exactly
532 * is needed depends on the underlying FS stream
533 * implementation.
534 * @param cObjInfo Number of items in the array @a paObjInfo points at.
535 * @param fFlags RTVFSFSSTRM_PUSH_F_XXX.
536 * @param phVfsIos Where to return the I/O stream to feed the file content
537 * to. If the FS stream is backed by a file, the returned
538 * handle can be cast to a file if necessary.
539 */
540RTDECL(int) RTVfsFsStrmPushFile(RTVFSFSSTREAM hVfsFss, const char *pszPath, uint64_t cbFile,
541 PCRTFSOBJINFO paObjInfo, uint32_t cObjInfo, uint32_t fFlags, PRTVFSIOSTREAM phVfsIos);
542
543/** @name RTVFSFSSTRM_PUSH_F_XXX - Flags for RTVfsFsStrmPushFile.
544 * @{ */
545/** Input is an I/O stream of indeterminate length, read to the end and then
546 * update the file header.
547 * @note This is *only* possible if the output stream is actually a file. */
548#define RTVFSFSSTRM_PUSH_F_STREAM RT_BIT_32(0)
549/** Mask of flags specific to the target stream. */
550#define RTVFSFSSTRM_PUSH_F_SPECIFIC_MASK UINT32_C(0xff000000)
551/** Valid bits. */
552#define RTVFSFSSTRM_PUSH_F_VALID_MASK UINT32_C(0xff000001)
553/** @} */
554
555/**
556 * Marks the end of the stream.
557 *
558 * The stream must be writable.
559 *
560 * @returns IPRT status code.
561 * @retval VERR_INVALID_FUNCTION if called on a non-writable stream.
562 * @param hVfsFss The file system stream handle.
563 */
564RTDECL(int) RTVfsFsStrmEnd(RTVFSFSSTREAM hVfsFss);
565
566/** @} */
567
568
569/** @defgroup grp_vfs_dir VFS Directory API
570 * @{
571 */
572
573/**
574 * Retains a reference to the VFS directory handle.
575 *
576 * @returns New reference count on success, UINT32_MAX on failure.
577 * @param hVfsDir The VFS directory handle.
578 */
579RTDECL(uint32_t) RTVfsDirRetain(RTVFSDIR hVfsDir);
580RTDECL(uint32_t) RTVfsDirRetainDebug(RTVFSDIR hVfsDir, RT_SRC_POS_DECL);
581
582/**
583 * Releases a reference to the VFS directory handle.
584 *
585 * @returns New reference count on success (0 if closed), UINT32_MAX on failure.
586 * @param hVfsDir The VFS directory handle.
587 */
588RTDECL(uint32_t) RTVfsDirRelease(RTVFSDIR hVfsDir);
589
590/**
591 * Opens a directory in the specified file system.
592 *
593 * @returns IPRT status code.
594 * @param hVfs The VFS to open the directory within.
595 * @param pszPath Path to the directory, relative to the root.
596 * @param fFlags Reserved, MBZ.
597 * @param phVfsDir Where to return the directory.
598 */
599RTDECL(int) RTVfsDirOpen(RTVFS hVfs, const char *pszPath, uint32_t fFlags, PRTVFSDIR phVfsDir);
600
601/**
602 * Opens any file system object in or under the given directory.
603 *
604 * @returns IPRT status code.
605 * @param hVfsDir The VFS directory start walking the @a pszPath
606 * relative to.
607 * @param pszPath Path to the file.
608 * @param fFileOpen RTFILE_O_XXX flags.
609 * @param fObjFlags More flags: RTVFSOBJ_F_XXX, RTPATH_F_XXX.
610 * @param phVfsObj Where to return the object handle.
611 * @sa RTVfsObjOpen, RTVfsDirOpenDir, RTVfsDirOpenFile
612 */
613RTDECL(int) RTVfsDirOpenObj(RTVFSDIR hVfsDir, const char *pszPath, uint64_t fFileOpen, uint32_t fObjFlags, PRTVFSOBJ phVfsObj);
614
615/**
616 * Opens a file in or under the given directory.
617 *
618 * @returns IPRT status code.
619 * @param hVfsDir The VFS directory start walking the @a pszPath
620 * relative to.
621 * @param pszPath Path to the file.
622 * @param fOpen RTFILE_O_XXX flags.
623 * @param phVfsFile Where to return the file.
624 * @sa RTVfsDirOpenFileAsIoStream
625 */
626RTDECL(int) RTVfsDirOpenFile(RTVFSDIR hVfsDir, const char *pszPath, uint64_t fOpen, PRTVFSFILE phVfsFile);
627
628/**
629 * Convenience wrapper around RTVfsDirOpenFile that returns an I/O stream.
630 *
631 * @returns IPRT status code.
632 * @param hVfsDir The VFS directory start walking the @a pszPath
633 * relative to.
634 * @param pszPath Path to the file.
635 * @param fOpen RTFILE_O_XXX flags.
636 * @param phVfsIos Where to return the I/O stream handle of the file.
637 * @sa RTVfsDirOpenFile
638 */
639RTDECL(int) RTVfsDirOpenFileAsIoStream(RTVFSDIR hVfsDir, const char *pszPath, uint64_t fOpen, PRTVFSIOSTREAM phVfsIos);
640
641/**
642 * Opens a directory in or under the given directory.
643 *
644 * @returns IPRT status code.
645 * @param hVfsDir The VFS directory start walking the @a pszPath
646 * relative to.
647 * @param pszPath Path to the file.
648 * @param fFlags Reserved, MBZ.
649 * @param phVfsDir Where to return the directory.
650 */
651RTDECL(int) RTVfsDirOpenDir(RTVFSDIR hVfsDir, const char *pszPath, uint32_t fFlags, PRTVFSDIR phVfsDir);
652
653/**
654 * Creates a directory relative to @a hVfsDir.
655 *
656 * @returns IPRT status code
657 * @param hVfsDir The directory the path is relative to.
658 * @param pszRelPath The relative path to the new directory.
659 * @param fMode The file mode for the new directory.
660 * @param fFlags Directory creation flags, RTDIRCREATE_FLAGS_XXX.
661 * @param phVfsDir Where to return the handle to the newly created
662 * directory. Optional.
663 * @sa RTDirCreate, RTDirRelDirCreate
664 */
665RTDECL(int) RTVfsDirCreateDir(RTVFSDIR hVfsDir, const char *pszRelPath, RTFMODE fMode, uint32_t fFlags, PRTVFSDIR phVfsDir);
666
667/**
668 * Create a VFS directory handle from a standard IPRT directory handle (RTDIR).
669 *
670 * @returns IPRT status code.
671 * @param hDir The standard IPRT directory handle.
672 * @param fLeaveOpen Whether to leave the handle open when the VFS
673 * directory is released, or to close it (@c false).
674 * @param phVfsDir Where to return the VFS directory handle.
675 */
676RTDECL(int) RTVfsDirFromRTDir(RTDIR hDir, bool fLeaveOpen, PRTVFSDIR phVfsDir);
677
678/**
679 * RTDirOpen + RTVfsDirFromRTDir.
680 *
681 * @returns IPRT status code.
682 * @param pszPath The path to the directory.
683 * @param fFlags RTDIR_F_XXX.
684 * @param phVfsDir Where to return the VFS directory handle.
685 */
686RTDECL(int) RTVfsDirOpenNormal(const char *pszPath, uint32_t fFlags, PRTVFSDIR phVfsDir);
687
688/** Checks if @a hVfsDir was opened using RTVfsDirOpenNormal() or
689 * RTVfsDirFromRTDir(), either directly or indirectly. */
690RTDECL(bool) RTVfsDirIsStdDir(RTVFSDIR hVfsDir);
691
692/**
693 * Queries information about a object in or under the given directory.
694 *
695 * @returns IPRT Status code.
696 * @param hVfsDir The VFS directory start walking the @a pszPath
697 * relative to.
698 * @param pszPath Path to the object.
699 * @param pObjInfo Where to return info.
700 * @param enmAddAttr What to return.
701 * @param fFlags RTPATH_F_XXX.
702 * @sa RTPathQueryInfoEx, RTVfsQueryPathInfo, RTVfsObjQueryInfo
703 */
704RTDECL(int) RTVfsDirQueryPathInfo(RTVFSDIR hVfsDir, const char *pszPath, PRTFSOBJINFO pObjInfo,
705 RTFSOBJATTRADD enmAddAttr, uint32_t fFlags);
706
707/**
708 * Removes a directory relative to @a hVfsDir.
709 *
710 * @returns IPRT status code.
711 * @param hVfsDir The VFS directory to start walking the @a pszRelPath
712 * relative to.
713 * @param pszRelPath The path to the directory that should be removed.
714 * @param fFlags Reserved, MBZ.
715 */
716RTDECL(int) RTVfsDirRemoveDir(RTVFSDIR hVfsDir, const char *pszRelPath, uint32_t fFlags);
717
718/**
719 * Reads the next entry in the directory returning extended information.
720 *
721 * @returns VINF_SUCCESS and data in pDirEntry on success.
722 * @returns VERR_NO_MORE_FILES when the end of the directory has been reached.
723 * @returns VERR_BUFFER_OVERFLOW if the buffer is too small to contain the filename. If
724 * pcbDirEntry is specified it will be updated with the required buffer size.
725 * @returns suitable iprt status code on other errors.
726 *
727 * @param hVfsDir The VFS directory.
728 * @param pDirEntry Where to store the information about the next
729 * directory entry on success.
730 * @param pcbDirEntry Optional parameter used for variable buffer size.
731 *
732 * On input the variable pointed to contains the size of the pDirEntry
733 * structure. This must be at least OFFSET(RTDIRENTRYEX, szName[2]) bytes.
734 *
735 * On successful output the field is updated to
736 * OFFSET(RTDIRENTRYEX, szName[pDirEntry->cbName + 1]).
737 *
738 * When the data doesn't fit in the buffer and VERR_BUFFER_OVERFLOW is
739 * returned, this field contains the required buffer size.
740 *
741 * The value is unchanged in all other cases.
742 * @param enmAddAttr Which set of additional attributes to request.
743 * Use RTFSOBJATTRADD_NOTHING if this doesn't matter.
744 *
745 * @sa RTDirReadEx
746 */
747RTDECL(int) RTVfsDirReadEx(RTVFSDIR hVfsDir, PRTDIRENTRYEX pDirEntry, size_t *pcbDirEntry, RTFSOBJATTRADD enmAddAttr);
748
749/** @} */
750
751
752/** @defgroup grp_vfs_symlink VFS Symbolic Link API
753 *
754 * @remarks The TAR VFS and filesystem stream uses symbolic links for
755 * describing hard links as well. The users must use RTFS_IS_SYMLINK
756 * to check if it is a real symlink in those cases.
757 *
758 * @remarks Any VFS which is backed by a real file system may be subject to
759 * races with other processes or threads, so the user may get
760 * unexpected errors when this happends. This is a bit host specific,
761 * i.e. it might be prevent on windows if we care.
762 *
763 * @{
764 */
765
766
767/**
768 * Retains a reference to the VFS symbolic link handle.
769 *
770 * @returns New reference count on success, UINT32_MAX on failure.
771 * @param hVfsSym The VFS symbolic link handle.
772 */
773RTDECL(uint32_t) RTVfsSymlinkRetain(RTVFSSYMLINK hVfsSym);
774RTDECL(uint32_t) RTVfsSymlinkRetainDebug(RTVFSSYMLINK hVfsSym, RT_SRC_POS_DECL);
775
776/**
777 * Releases a reference to the VFS symbolic link handle.
778 *
779 * @returns New reference count on success (0 if closed), UINT32_MAX on failure.
780 * @param hVfsSym The VFS symbolic link handle.
781 */
782RTDECL(uint32_t) RTVfsSymlinkRelease(RTVFSSYMLINK hVfsSym);
783
784/**
785 * Query information about the symbolic link.
786 *
787 * @returns IPRT status code.
788 * @param hVfsSym The VFS symbolic link handle.
789 * @param pObjInfo Where to return the info.
790 * @param enmAddAttr Which additional attributes should be retrieved.
791 *
792 * @sa RTFileQueryInfo, RTPathQueryInfo, RTPathQueryInfoEx
793 */
794RTDECL(int) RTVfsSymlinkQueryInfo(RTVFSSYMLINK hVfsSym, PRTFSOBJINFO pObjInfo, RTFSOBJATTRADD enmAddAttr);
795
796/**
797 * Set the unix style owner and group.
798 *
799 * @returns IPRT status code.
800 * @param hVfsSym The VFS symbolic link handle.
801 * @param fMode The new mode bits.
802 * @param fMask The mask indicating which bits we are changing.
803 * @sa RTFileSetMode, RTPathSetMode
804 */
805RTDECL(int) RTVfsSymlinkSetMode(RTVFSSYMLINK hVfsSym, RTFMODE fMode, RTFMODE fMask);
806
807/**
808 * Set the timestamps associated with the object.
809 *
810 * @returns IPRT status code.
811 * @param hVfsSym The VFS symbolic link handle.
812 * @param pAccessTime Pointer to the new access time. NULL if not
813 * to be changed.
814 * @param pModificationTime Pointer to the new modifcation time. NULL if
815 * not to be changed.
816 * @param pChangeTime Pointer to the new change time. NULL if not to be
817 * changed.
818 * @param pBirthTime Pointer to the new time of birth. NULL if not to be
819 * changed.
820 * @remarks See RTFileSetTimes for restrictions and behavior imposed by the
821 * host OS or underlying VFS provider.
822 * @sa RTFileSetTimes, RTPathSetTimes
823 */
824RTDECL(int) RTVfsSymlinkSetTimes(RTVFSSYMLINK hVfsSym, PCRTTIMESPEC pAccessTime, PCRTTIMESPEC pModificationTime,
825 PCRTTIMESPEC pChangeTime, PCRTTIMESPEC pBirthTime);
826
827/**
828 * Set the unix style owner and group.
829 *
830 * @returns IPRT status code.
831 * @param hVfsSym The VFS symbolic link handle.
832 * @param uid The user ID of the new owner. NIL_RTUID if
833 * unchanged.
834 * @param gid The group ID of the new owner group. NIL_RTGID if
835 * unchanged.
836 * @sa RTFileSetOwner, RTPathSetOwner.
837 */
838RTDECL(int) RTVfsSymlinkSetOwner(RTVFSSYMLINK hVfsSym, RTUID uid, RTGID gid);
839
840/**
841 * Read the symbolic link target.
842 *
843 * @returns IPRT status code.
844 * @param hVfsSym The VFS symbolic link handle.
845 * @param pszTarget The target buffer.
846 * @param cbTarget The size of the target buffer.
847 * @sa RTSymlinkRead
848 */
849RTDECL(int) RTVfsSymlinkRead(RTVFSSYMLINK hVfsSym, char *pszTarget, size_t cbTarget);
850
851/** @} */
852
853
854
855/** @defgroup grp_vfs_iostream VFS I/O Stream API
856 * @{
857 */
858
859/**
860 * Creates a VFS file from a memory buffer.
861 *
862 * @returns IPRT status code.
863 *
864 * @param fFlags A combination of RTFILE_O_READ and RTFILE_O_WRITE.
865 * @param pvBuf The buffer. This will be copied and not referenced
866 * after this function returns.
867 * @param cbBuf The buffer size.
868 * @param phVfsIos Where to return the VFS I/O stream handle.
869 */
870RTDECL(int) RTVfsIoStrmFromBuffer(uint32_t fFlags, void const *pvBuf, size_t cbBuf, PRTVFSIOSTREAM phVfsIos);
871
872/**
873 * Creates a VFS I/O stream handle from a standard IPRT file handle (RTFILE).
874 *
875 * @returns IPRT status code.
876 * @param hFile The standard IPRT file handle.
877 * @param fOpen The flags the handle was opened with. Pass 0 to
878 * have these detected.
879 * @param fLeaveOpen Whether to leave the handle open when the VFS file
880 * is released, or to close it (@c false).
881 * @param phVfsIos Where to return the VFS I/O stream handle.
882 */
883RTDECL(int) RTVfsIoStrmFromRTFile(RTFILE hFile, uint64_t fOpen, bool fLeaveOpen, PRTVFSIOSTREAM phVfsIos);
884
885/**
886 * Creates a VFS I/O stream handle from a standard IPRT pipe handle (RTPIPE).
887 *
888 * @returns IPRT status code.
889 * @param hPipe The standard IPRT pipe handle.
890 * @param fLeaveOpen Whether to leave the handle open when the VFS file
891 * is released, or to close it (@c false).
892 * @param phVfsIos Where to return the VFS I/O stream handle.
893 */
894RTDECL(int) RTVfsIoStrmFromRTPipe(RTPIPE hPipe, bool fLeaveOpen, PRTVFSIOSTREAM phVfsIos);
895
896/**
897 * Convenience function combining RTFileOpen with RTVfsIoStrmFromRTFile.
898 *
899 * @returns IPRT status code.
900 * @param pszFilename The path to the file in the normal file system.
901 * @param fOpen The flags to pass to RTFileOpen when opening the
902 * file, i.e. RTFILE_O_XXX.
903 * @param phVfsIos Where to return the VFS I/O stream handle.
904 */
905RTDECL(int) RTVfsIoStrmOpenNormal(const char *pszFilename, uint64_t fOpen, PRTVFSIOSTREAM phVfsIos);
906
907/**
908 * Create a VFS I/O stream handle from one of the standard handles.
909 *
910 * @returns IPRT status code.
911 * @param enmStdHandle The standard IPRT file handle.
912 * @param fOpen The flags the handle was opened with. Pass 0 to
913 * have these detected.
914 * @param fLeaveOpen Whether to leave the handle open when the VFS file
915 * is released, or to close it (@c false).
916 * @param phVfsIos Where to return the VFS I/O stream handle.
917 */
918RTDECL(int) RTVfsIoStrmFromStdHandle(RTHANDLESTD enmStdHandle, uint64_t fOpen, bool fLeaveOpen,
919 PRTVFSIOSTREAM phVfsIos);
920
921/**
922 * Retains a reference to the VFS I/O stream handle.
923 *
924 * @returns New reference count on success, UINT32_MAX on failure.
925 * @param hVfsIos The VFS I/O stream handle.
926 */
927RTDECL(uint32_t) RTVfsIoStrmRetain(RTVFSIOSTREAM hVfsIos);
928RTDECL(uint32_t) RTVfsIoStrmRetainDebug(RTVFSIOSTREAM hVfsIos, RT_SRC_POS_DECL);
929
930/**
931 * Releases a reference to the VFS I/O stream handle.
932 *
933 * @returns New reference count on success (0 if closed), UINT32_MAX on failure.
934 * @param hVfsIos The VFS I/O stream handle.
935 */
936RTDECL(uint32_t) RTVfsIoStrmRelease(RTVFSIOSTREAM hVfsIos);
937
938/**
939 * Convert the VFS I/O stream handle to a VFS file handle.
940 *
941 * @returns The VFS file handle on success, this must be released.
942 * NIL_RTVFSFILE if the I/O stream handle is invalid.
943 * @param hVfsIos The VFS I/O stream handle.
944 * @sa RTVfsFileToIoStream
945 */
946RTDECL(RTVFSFILE) RTVfsIoStrmToFile(RTVFSIOSTREAM hVfsIos);
947
948/**
949 * Query information about the I/O stream.
950 *
951 * @returns IPRT status code.
952 * @param hVfsIos The VFS I/O stream handle.
953 * @param pObjInfo Where to return the info.
954 * @param enmAddAttr Which additional attributes should be retrieved.
955 * @sa RTFileQueryInfo
956 */
957RTDECL(int) RTVfsIoStrmQueryInfo(RTVFSIOSTREAM hVfsIos, PRTFSOBJINFO pObjInfo, RTFSOBJATTRADD enmAddAttr);
958
959/**
960 * Read bytes from the I/O stream.
961 *
962 * @returns IPRT status code.
963 * @retval VINF_SUCCESS and the number of bytes read written to @a pcbRead.
964 * @retval VINF_TRY_AGAIN if @a fBlocking is @c false, @a pcbRead is not NULL,
965 * and no data was available. @a *pcbRead will be set to 0.
966 * @retval VINF_EOF when trying to read __beyond__ the end of the stream and
967 * @a pcbRead is not NULL (it will be set to the number of bytes read,
968 * or 0 if the end of the stream was reached before this call).
969 * When the last byte of the read request is the last byte in the
970 * stream, this status code will not be used. However, VINF_EOF is
971 * returned when attempting to read 0 bytes while standing at the end
972 * of the stream.
973 * @retval VERR_EOF when trying to read __beyond__ the end of the stream and
974 * @a pcbRead is NULL.
975 * @retval VERR_ACCESS_DENIED if the stream is not readable.
976 *
977 * @param hVfsIos The VFS I/O stream handle.
978 * @param pvBuf Where to store the read bytes.
979 * @param cbToRead The number of bytes to read.
980 * @param fBlocking Whether the call is blocking (@c true) or not. If
981 * not, the @a pcbRead parameter must not be NULL.
982 * @param pcbRead Where to always store the number of bytes actually
983 * read. This can be NULL if @a fBlocking is true.
984 * @sa RTVfsFileRead, RTFileRead, RTPipeRead, RTPipeReadBlocking,
985 * RTSocketRead
986 */
987RTDECL(int) RTVfsIoStrmRead(RTVFSIOSTREAM hVfsIos, void *pvBuf, size_t cbToRead, bool fBlocking, size_t *pcbRead);
988
989/**
990 * Read bytes from the I/O stream, optionally with offset.
991 *
992 * @returns IPRT status code.
993 * @retval VINF_SUCCESS and the number of bytes read written to @a pcbRead.
994 * @retval VINF_TRY_AGAIN if @a fBlocking is @c false, @a pcbRead is not NULL,
995 * and no data was available. @a *pcbRead will be set to 0.
996 * @retval VINF_EOF when trying to read __beyond__ the end of the stream and
997 * @a pcbRead is not NULL (it will be set to the number of bytes read,
998 * or 0 if the end of the stream was reached before this call).
999 * When the last byte of the read request is the last byte in the
1000 * stream, this status code will not be used. However, VINF_EOF is
1001 * returned when attempting to read 0 bytes while standing at the end
1002 * of the stream.
1003 * @retval VERR_EOF when trying to read __beyond__ the end of the stream and
1004 * @a pcbRead is NULL.
1005 * @retval VERR_ACCESS_DENIED if the stream is not readable.
1006 *
1007 * @param hVfsIos The VFS I/O stream handle.
1008 * @param off Where to read at, -1 for the current position.
1009 * @param pvBuf Where to store the read bytes.
1010 * @param cbToRead The number of bytes to read.
1011 * @param fBlocking Whether the call is blocking (@c true) or not. If
1012 * not, the @a pcbRead parameter must not be NULL.
1013 * @param pcbRead Where to always store the number of bytes actually
1014 * read. This can be NULL if @a fBlocking is true.
1015 * @sa RTVfsFileRead, RTFileRead, RTPipeRead, RTPipeReadBlocking,
1016 * RTSocketRead
1017 */
1018RTDECL(int) RTVfsIoStrmReadAt(RTVFSIOSTREAM hVfsIos, RTFOFF off, void *pvBuf, size_t cbToRead, bool fBlocking, size_t *pcbRead);
1019
1020/**
1021 * Reads the remainder of the stream into a memory buffer.
1022 *
1023 * For simplifying string-style processing, the is a zero byte after the
1024 * returned buffer, making sure it can be used as a zero terminated string.
1025 *
1026 * @returns IPRT status code.
1027 * @param hVfsIos The VFS I/O stream handle.
1028 * @param ppvBuf Where to return the buffer. Must pass to
1029 * RTVfsIoStrmReadAllFree for freeing, not RTMemFree!
1030 * @param pcbBuf Where to return the buffer size.
1031 */
1032RTDECL(int) RTVfsIoStrmReadAll(RTVFSIOSTREAM hVfsIos, void **ppvBuf, size_t *pcbBuf);
1033
1034/**
1035 * Free memory buffer returned by RTVfsIoStrmReadAll.
1036 *
1037 * @param pvBuf What RTVfsIoStrmReadAll returned.
1038 * @param cbBuf What RTVfsIoStrmReadAll returned.
1039 */
1040RTDECL(void) RTVfsIoStrmReadAllFree(void *pvBuf, size_t cbBuf);
1041
1042/**
1043 * Write bytes to the I/O stream.
1044 *
1045 * @returns IPRT status code.
1046 * @retval VERR_ACCESS_DENIED if the stream is not writable.
1047 *
1048 * @param hVfsIos The VFS I/O stream handle.
1049 * @param pvBuf The bytes to write.
1050 * @param cbToWrite The number of bytes to write.
1051 * @param fBlocking Whether the call is blocking (@c true) or not. If
1052 * not, the @a pcbWritten parameter must not be NULL.
1053 * @param pcbWritten Where to always store the number of bytes actually
1054 * written. This can be NULL if @a fBlocking is true.
1055 * @sa RTVfsFileWrite, RTFileWrite, RTPipeWrite, RTPipeWriteBlocking,
1056 * RTSocketWrite
1057 */
1058RTDECL(int) RTVfsIoStrmWrite(RTVFSIOSTREAM hVfsIos, const void *pvBuf, size_t cbToWrite, bool fBlocking, size_t *pcbWritten);
1059RTDECL(int) RTVfsIoStrmWriteAt(RTVFSIOSTREAM hVfsIos, RTFOFF off, const void *pvBuf, size_t cbToWrite, bool fBlocking, size_t *pcbWritten);
1060
1061/**
1062 * Reads bytes from the I/O stream into a scatter buffer.
1063 *
1064 * @returns IPRT status code.
1065 * @retval VINF_SUCCESS and the number of bytes read written to @a pcbRead.
1066 * @retval VINF_TRY_AGAIN if @a fBlocking is @c false, @a pcbRead is not NULL,
1067 * and no data was available. @a *pcbRead will be set to 0.
1068 * @retval VINF_EOF when trying to read __beyond__ the end of the stream and
1069 * @a pcbRead is not NULL (it will be set to the number of bytes read,
1070 * or 0 if the end of the stream was reached before this call).
1071 * When the last byte of the read request is the last byte in the
1072 * stream, this status code will not be used. However, VINF_EOF is
1073 * returned when attempting to read 0 bytes while standing at the end
1074 * of the stream.
1075 * @retval VERR_EOF when trying to read __beyond__ the end of the stream and
1076 * @a pcbRead is NULL.
1077 * @retval VERR_ACCESS_DENIED if the stream is not readable.
1078 *
1079 * @param hVfsIos The VFS I/O stream handle.
1080 * @param off Where to read at, -1 for the current position.
1081 * @param pSgBuf Pointer to a scatter buffer descriptor. The number
1082 * of bytes described by the segments is what will be
1083 * attemted read.
1084 * @param fBlocking Whether the call is blocking (@c true) or not. If
1085 * not, the @a pcbRead parameter must not be NULL.
1086 * @param pcbRead Where to always store the number of bytes actually
1087 * read. This can be NULL if @a fBlocking is true.
1088 * @sa RTFileSgRead, RTSocketSgRead, RTPipeRead, RTPipeReadBlocking
1089 */
1090RTDECL(int) RTVfsIoStrmSgRead(RTVFSIOSTREAM hVfsIos, RTFOFF off, PCRTSGBUF pSgBuf, bool fBlocking, size_t *pcbRead);
1091
1092/**
1093 * Write bytes to the I/O stream from a gather buffer.
1094 *
1095 * @returns IPRT status code.
1096 * @retval VERR_ACCESS_DENIED if the stream is not writable.
1097 *
1098 * @param hVfsIos The VFS I/O stream handle.
1099 * @param off Where to write at, -1 for the current position.
1100 * @param pSgBuf Pointer to a gather buffer descriptor. The number
1101 * of bytes described by the segments is what will be
1102 * attemted written.
1103 * @param fBlocking Whether the call is blocking (@c true) or not. If
1104 * not, the @a pcbWritten parameter must not be NULL.
1105 * @param pcbWritten Where to always store the number of bytes actually
1106 * written. This can be NULL if @a fBlocking is true.
1107 * @sa RTFileSgWrite, RTSocketSgWrite
1108 */
1109RTDECL(int) RTVfsIoStrmSgWrite(RTVFSIOSTREAM hVfsIos, RTFOFF off, PCRTSGBUF pSgBuf, bool fBlocking, size_t *pcbWritten);
1110
1111/**
1112 * Flush any buffered data to the I/O stream.
1113 *
1114 * @returns IPRT status code.
1115 * @param hVfsIos The VFS I/O stream handle.
1116 * @sa RTVfsFileFlush, RTFileFlush, RTPipeFlush
1117 */
1118RTDECL(int) RTVfsIoStrmFlush(RTVFSIOSTREAM hVfsIos);
1119
1120/**
1121 * Poll for events.
1122 *
1123 * @returns IPRT status code.
1124 * @param hVfsIos The VFS I/O stream handle.
1125 * @param fEvents The events to poll for (RTPOLL_EVT_XXX).
1126 * @param cMillies How long to wait for event to eventuate.
1127 * @param fIntr Whether the wait is interruptible and can return
1128 * VERR_INTERRUPTED (@c true) or if this condition
1129 * should be hidden from the caller (@c false).
1130 * @param pfRetEvents Where to return the event mask.
1131 * @sa RTVfsFilePoll, RTPollSetAdd, RTPoll, RTPollNoResume.
1132 */
1133RTDECL(int) RTVfsIoStrmPoll(RTVFSIOSTREAM hVfsIos, uint32_t fEvents, RTMSINTERVAL cMillies, bool fIntr,
1134 uint32_t *pfRetEvents);
1135/**
1136 * Tells the current I/O stream position.
1137 *
1138 * @returns Zero or higher - where to return the I/O stream offset. Values
1139 * below zero are IPRT status codes (VERR_XXX).
1140 * @param hVfsIos The VFS I/O stream handle.
1141 * @sa RTFileTell
1142 */
1143RTDECL(RTFOFF) RTVfsIoStrmTell(RTVFSIOSTREAM hVfsIos);
1144
1145/**
1146 * Skips @a cb ahead in the stream.
1147 *
1148 * @returns IPRT status code.
1149 * @param hVfsIos The VFS I/O stream handle.
1150 * @param cb The number bytes to skip.
1151 */
1152RTDECL(int) RTVfsIoStrmSkip(RTVFSIOSTREAM hVfsIos, RTFOFF cb);
1153
1154/**
1155 * Fills the stream with @a cb zeros.
1156 *
1157 * @returns IPRT status code.
1158 * @param hVfsIos The VFS I/O stream handle.
1159 * @param cb The number of zero bytes to insert.
1160 */
1161RTDECL(int) RTVfsIoStrmZeroFill(RTVFSIOSTREAM hVfsIos, RTFOFF cb);
1162
1163/**
1164 * Checks if we're at the end of the I/O stream.
1165 *
1166 * @returns true if at EOS, otherwise false.
1167 * @param hVfsIos The VFS I/O stream handle.
1168 */
1169RTDECL(bool) RTVfsIoStrmIsAtEnd(RTVFSIOSTREAM hVfsIos);
1170
1171/**
1172 * Get the RTFILE_O_XXX flags for the I/O stream.
1173 *
1174 * @returns RTFILE_O_XXX, 0 on failure.
1175 * @param hVfsIos The VFS I/O stream handle.
1176 */
1177RTDECL(uint64_t) RTVfsIoStrmGetOpenFlags(RTVFSIOSTREAM hVfsIos);
1178
1179/**
1180 * Process the rest of the stream, checking if it's all valid UTF-8 encoding.
1181 *
1182 * @returns IPRT status code.
1183 *
1184 * @param hVfsIos The VFS I/O stream handle.
1185 * @param fFlags Flags governing the validation, see
1186 * RTVFS_VALIDATE_UTF8_XXX.
1187 * @param poffError Where to return the error offset. Optional.
1188 */
1189RTDECL(int) RTVfsIoStrmValidateUtf8Encoding(RTVFSIOSTREAM hVfsIos, uint32_t fFlags, PRTFOFF poffError);
1190
1191/** @defgroup RTVFS_VALIDATE_UTF8_XXX RTVfsIoStrmValidateUtf8Encoding flags.
1192 * @{ */
1193/** The text must not contain any null terminator codepoints. */
1194#define RTVFS_VALIDATE_UTF8_NO_NULL RT_BIT_32(0)
1195/** The codepoints must be in the range covered by RTC-3629. */
1196#define RTVFS_VALIDATE_UTF8_BY_RTC_3629 RT_BIT_32(1)
1197/** Mask of valid flags. */
1198#define RTVFS_VALIDATE_UTF8_VALID_MASK UINT32_C(0x00000003)
1199/** @} */
1200
1201/** @} */
1202
1203
1204/** @defgroup grp_vfs_file VFS File API
1205 * @{
1206 */
1207RTDECL(int) RTVfsFileOpen(RTVFS hVfs, const char *pszFilename, uint64_t fOpen, PRTVFSFILE phVfsFile);
1208
1209/**
1210 * Create a VFS file handle from a standard IPRT file handle (RTFILE).
1211 *
1212 * @returns IPRT status code.
1213 * @param hFile The standard IPRT file handle.
1214 * @param fOpen The flags the handle was opened with. Pass 0 to
1215 * have these detected.
1216 * @param fLeaveOpen Whether to leave the handle open when the VFS file
1217 * is released, or to close it (@c false).
1218 * @param phVfsFile Where to return the VFS file handle.
1219 */
1220RTDECL(int) RTVfsFileFromRTFile(RTFILE hFile, uint64_t fOpen, bool fLeaveOpen, PRTVFSFILE phVfsFile);
1221RTDECL(RTHCUINTPTR) RTVfsFileToNative(RTFILE hVfsFile);
1222
1223/**
1224 * Convenience function combining RTFileOpen with RTVfsFileFromRTFile.
1225 *
1226 * @returns IPRT status code.
1227 * @param pszFilename The path to the file in the normal file system.
1228 * @param fOpen The flags to pass to RTFileOpen when opening the
1229 * file, i.e. RTFILE_O_XXX.
1230 * @param phVfsFile Where to return the VFS file handle.
1231 */
1232RTDECL(int) RTVfsFileOpenNormal(const char *pszFilename, uint64_t fOpen, PRTVFSFILE phVfsFile);
1233
1234/**
1235 * Convert the VFS file handle to a VFS I/O stream handle.
1236 *
1237 * @returns The VFS I/O stream handle on success, this must be released.
1238 * NIL_RTVFSIOSTREAM if the file handle is invalid.
1239 * @param hVfsFile The VFS file handle.
1240 * @sa RTVfsIoStrmToFile
1241 */
1242RTDECL(RTVFSIOSTREAM) RTVfsFileToIoStream(RTVFSFILE hVfsFile);
1243
1244/**
1245 * Retains a reference to the VFS file handle.
1246 *
1247 * @returns New reference count on success, UINT32_MAX on failure.
1248 * @param hVfsFile The VFS file handle.
1249 */
1250RTDECL(uint32_t) RTVfsFileRetain(RTVFSFILE hVfsFile);
1251RTDECL(uint32_t) RTVfsFileRetainDebug(RTVFSFILE hVfsFile, RT_SRC_POS_DECL);
1252
1253/**
1254 * Releases a reference to the VFS file handle.
1255 *
1256 * @returns New reference count on success (0 if closed), UINT32_MAX on failure.
1257 * @param hVfsFile The VFS file handle.
1258 */
1259RTDECL(uint32_t) RTVfsFileRelease(RTVFSFILE hVfsFile);
1260
1261/**
1262 * Query information about the object.
1263 *
1264 * @returns IPRT status code.
1265 * @retval VERR_NOT_SUPPORTED if the @a enmAddAttr value is not handled by the
1266 * implementation.
1267 *
1268 * @param hVfsFile The VFS file handle.
1269 * @param pObjInfo Where to return the info.
1270 * @param enmAddAttr Which additional attributes should be retrieved.
1271 * @sa RTVfsObjQueryInfo, RTVfsFsStrmQueryInfo, RTVfsDirQueryInfo,
1272 * RTVfsIoStrmQueryInfo, RTVfsFileQueryInfo, RTFileQueryInfo,
1273 * RTPathQueryInfo.
1274 */
1275RTDECL(int) RTVfsFileQueryInfo(RTVFSFILE hVfsFile, PRTFSOBJINFO pObjInfo, RTFSOBJATTRADD enmAddAttr);
1276
1277/**
1278 * Read bytes from the file at the current position.
1279 *
1280 * @returns IPRT status code.
1281 * @retval VINF_SUCCESS and the number of bytes read written to @a pcbRead.
1282 * @retval VINF_EOF when trying to read __beyond__ the end of the file and
1283 * @a pcbRead is not NULL (it will be set to the number of bytes read,
1284 * or 0 if the end of the file was reached before this call).
1285 * When the last byte of the read request is the last byte in the
1286 * file, this status code will not be used. However, VINF_EOF is
1287 * returned when attempting to read 0 bytes while standing at the end
1288 * of the file.
1289 * @retval VERR_EOF when trying to read __beyond__ the end of the file and
1290 * @a pcbRead is NULL.
1291 * @retval VERR_ACCESS_DENIED if the file is not readable.
1292 *
1293 * @param hVfsFile The VFS file handle.
1294 * @param pvBuf Where to store the read bytes.
1295 * @param cbToRead The number of bytes to read.
1296 * @param pcbRead Where to always store the number of bytes actually
1297 * read. Optional.
1298 * @sa RTVfsIoStrmRead, RTFileRead, RTPipeRead, RTPipeReadBlocking,
1299 * RTSocketRead
1300 */
1301RTDECL(int) RTVfsFileRead(RTVFSFILE hVfsFile, void *pvBuf, size_t cbToRead, size_t *pcbRead);
1302RTDECL(int) RTVfsFileReadAt(RTVFSFILE hVfsFile, RTFOFF off, void *pvBuf, size_t cbToRead, size_t *pcbRead);
1303
1304/**
1305 * Write bytes to the file at the current position.
1306 *
1307 * @returns IPRT status code.
1308 * @retval VERR_ACCESS_DENIED if the file is not writable.
1309 *
1310 * @param hVfsFile The VFS file handle.
1311 * @param pvBuf The bytes to write.
1312 * @param cbToWrite The number of bytes to write.
1313 * @param pcbWritten Where to always store the number of bytes actually
1314 * written. This can be NULL.
1315 * @sa RTVfsIoStrmRead, RTFileWrite, RTPipeWrite, RTPipeWriteBlocking,
1316 * RTSocketWrite
1317 */
1318RTDECL(int) RTVfsFileWrite(RTVFSFILE hVfsFile, const void *pvBuf, size_t cbToWrite, size_t *pcbWritten);
1319RTDECL(int) RTVfsFileWriteAt(RTVFSFILE hVfsFile, RTFOFF off, const void *pvBuf, size_t cbToWrite, size_t *pcbWritten);
1320
1321
1322/**
1323 * Reads bytes from the file into a scatter buffer.
1324 *
1325 * @returns IPRT status code.
1326 * @retval VINF_SUCCESS and the number of bytes read written to @a pcbRead.
1327 * @retval VINF_TRY_AGAIN if @a fBlocking is @c false, @a pcbRead is not NULL,
1328 * and no data was available. @a *pcbRead will be set to 0.
1329 * @retval VINF_EOF when trying to read __beyond__ the end of the stream and
1330 * @a pcbRead is not NULL (it will be set to the number of bytes read,
1331 * or 0 if the end of the stream was reached before this call).
1332 * When the last byte of the read request is the last byte in the
1333 * stream, this status code will not be used. However, VINF_EOF is
1334 * returned when attempting to read 0 bytes while standing at the end
1335 * of the stream.
1336 * @retval VERR_EOF when trying to read __beyond__ the end of the stream and
1337 * @a pcbRead is NULL.
1338 * @retval VERR_ACCESS_DENIED if the stream is not readable.
1339 *
1340 * @param hVfsFile The VFS file handle.
1341 * @param off Where to read at, -1 for the current position.
1342 * @param pSgBuf Pointer to a scatter buffer descriptor. The number
1343 * of bytes described by the segments is what will be
1344 * attemted read.
1345 * @param fBlocking Whether the call is blocking (@c true) or not. If
1346 * not, the @a pcbRead parameter must not be NULL.
1347 * @param pcbRead Where to always store the number of bytes actually
1348 * read. This can be NULL if @a fBlocking is true.
1349 * @sa RTFileSgRead, RTSocketSgRead, RTPipeRead, RTPipeReadBlocking
1350 */
1351RTDECL(int) RTVfsFileSgRead(RTVFSFILE hVfsFile, RTFOFF off, PCRTSGBUF pSgBuf, bool fBlocking, size_t *pcbRead);
1352
1353/**
1354 * Write bytes to the file from a gather buffer.
1355 *
1356 * @returns IPRT status code.
1357 * @retval VERR_ACCESS_DENIED if the stream is not writable.
1358 *
1359 * @param hVfsFile The VFS file handle.
1360 * @param off Where to write at, -1 for the current position.
1361 * @param pSgBuf Pointer to a gather buffer descriptor. The number
1362 * of bytes described by the segments is what will be
1363 * attemted written.
1364 * @param fBlocking Whether the call is blocking (@c true) or not. If
1365 * not, the @a pcbWritten parameter must not be NULL.
1366 * @param pcbWritten Where to always store the number of bytes actually
1367 * written. This can be NULL if @a fBlocking is true.
1368 * @sa RTFileSgWrite, RTSocketSgWrite
1369 */
1370RTDECL(int) RTVfsFileSgWrite(RTVFSFILE hVfsFile, RTFOFF off, PCRTSGBUF pSgBuf, bool fBlocking, size_t *pcbWritten);
1371
1372/**
1373 * Flush any buffered data to the file.
1374 *
1375 * @returns IPRT status code.
1376 * @param hVfsFile The VFS file handle.
1377 * @sa RTVfsIoStrmFlush, RTFileFlush, RTPipeFlush
1378 */
1379RTDECL(int) RTVfsFileFlush(RTVFSFILE hVfsFile);
1380
1381/**
1382 * Poll for events.
1383 *
1384 * @returns IPRT status code.
1385 * @param hVfsFile The VFS file handle.
1386 * @param fEvents The events to poll for (RTPOLL_EVT_XXX).
1387 * @param cMillies How long to wait for event to eventuate.
1388 * @param fIntr Whether the wait is interruptible and can return
1389 * VERR_INTERRUPTED (@c true) or if this condition
1390 * should be hidden from the caller (@c false).
1391 * @param pfRetEvents Where to return the event mask.
1392 * @sa RTVfsIoStrmPoll, RTPollSetAdd, RTPoll, RTPollNoResume.
1393 */
1394RTDECL(RTFOFF) RTVfsFilePoll(RTVFSFILE hVfsFile, uint32_t fEvents, RTMSINTERVAL cMillies, bool fIntr,
1395 uint32_t *pfRetEvents);
1396
1397/**
1398 * Tells the current file position.
1399 *
1400 * @returns Zero or higher - where to return the file offset. Values
1401 * below zero are IPRT status codes (VERR_XXX).
1402 * @param hVfsFile The VFS file handle.
1403 * @sa RTFileTell, RTVfsIoStrmTell.
1404 */
1405RTDECL(RTFOFF) RTVfsFileTell(RTVFSFILE hVfsFile);
1406
1407/**
1408 * Changes the current read/write position of a file.
1409 *
1410 * @returns IPRT status code.
1411 *
1412 * @param hVfsFile The VFS file handle.
1413 * @param offSeek The seek offset.
1414 * @param uMethod The seek emthod.
1415 * @param poffActual Where to optionally return the new file offset.
1416 *
1417 * @sa RTFileSeek
1418 */
1419RTDECL(int) RTVfsFileSeek(RTVFSFILE hVfsFile, RTFOFF offSeek, uint32_t uMethod, uint64_t *poffActual);
1420
1421/**
1422 * Sets the size of a file.
1423 *
1424 * This may also be used for preallocating space
1425 * (RTVFSFILE_SIZE_F_PREALLOC_KEEP_SIZE).
1426 *
1427 * @returns IPRT status code.
1428 * @retval VERR_ACCESS_DENIED if handle isn't writable.
1429 * @retval VERR_WRITE_PROTECT if read-only file system.
1430 * @retval VERR_FILE_TOO_BIG if cbSize is larger than what the file system can
1431 * theoretically deal with.
1432 * @retval VERR_DISK_FULL if the file system if full.
1433 * @retval VERR_NOT_SUPPORTED if fFlags indicates some operation that's not
1434 * supported by the file system / host operating system.
1435 *
1436 * @param hVfsFile The VFS file handle.
1437 * @param cbSize The new file size.
1438 * @param fFlags RTVFSFILE_SIZE_F_NORMAL, RTVFSFILE_SIZE_F_GROW, or
1439 * RTVFSFILE_SIZE_F_GROW_KEEP_SIZE.
1440 *
1441 * @sa RTFileSetSize, RTFileSetAllocationSize
1442 */
1443RTDECL(int) RTVfsFileSetSize(RTVFSFILE hVfsFile, uint64_t cbSize, uint32_t fFlags);
1444
1445/** @name RTVFSFILE_SIZE_F_XXX - RTVfsFileSetSize flags.
1446 * @{ */
1447/** Normal truncate or grow (zero'ed) like RTFileSetSize . */
1448#define RTVFSFILE_SIZE_F_NORMAL UINT32_C(0x00000001)
1449/** Only grow the file, ignore call if cbSize would trunacte the file.
1450 * This is what RTFileSetAllocationSize does by default. */
1451#define RTVFSFILE_SIZE_F_GROW UINT32_C(0x00000002)
1452/** Only grow the file, ignore call if cbSize would trunacte the file.
1453 * This is what RTFileSetAllocationSize does by default. */
1454#define RTVFSFILE_SIZE_F_GROW_KEEP_SIZE UINT32_C(0x00000003)
1455/** Action mask. */
1456#define RTVFSFILE_SIZE_F_ACTION_MASK UINT32_C(0x00000003)
1457/** Validate the flags.
1458 * Will reference @a a_fFlags more than once. */
1459#define RTVFSFILE_SIZE_F_IS_VALID(a_fFlags) \
1460 ( !((a_fFlags) & ~RTVFSFILE_SIZE_F_ACTION_MASK) && ((a_fFlags) & RTVFSFILE_SIZE_F_ACTION_MASK) != 0 )
1461/** @} */
1462
1463
1464/** Mask of valid flags. */
1465#define RTFILE_ALLOC_SIZE_F_VALID (RTFILE_ALLOC_SIZE_F_KEEP_SIZE)
1466/** @} */
1467
1468
1469RTDECL(int) RTVfsFileGetSize(RTVFSFILE hVfsFile, uint64_t *pcbSize);
1470RTDECL(RTFOFF) RTVfsFileGetMaxSize(RTVFSFILE hVfsFile);
1471RTDECL(int) RTVfsFileQueryMaxSize(RTVFSFILE hVfsFile, uint64_t *pcbMax);
1472
1473/**
1474 * Get the RTFILE_O_XXX flags for the I/O stream.
1475 *
1476 * @returns RTFILE_O_XXX, 0 on failure.
1477 * @param hVfsFile The VFS file handle.
1478 */
1479RTDECL(uint64_t) RTVfsFileGetOpenFlags(RTVFSFILE hVfsFile);
1480
1481/** @} */
1482
1483
1484#ifdef DEBUG
1485# undef RTVfsRetain
1486# define RTVfsRetain(hVfs) RTVfsRetainDebug(hVfs, RT_SRC_POS)
1487# undef RTVfsObjRetain
1488# define RTVfsObjRetain(hVfsObj) RTVfsObjRetainDebug(hVfsObj, RT_SRC_POS)
1489# undef RTVfsDirRetain
1490# define RTVfsDirRetain(hVfsDir) RTVfsDirRetainDebug(hVfsDir, RT_SRC_POS)
1491# undef RTVfsFileRetain
1492# define RTVfsFileRetain(hVfsFile) RTVfsFileRetainDebug(hVfsFile, RT_SRC_POS)
1493# undef RTVfsIoStrmRetain
1494# define RTVfsIoStrmRetain(hVfsIos) RTVfsIoStrmRetainDebug(hVfsIos, RT_SRC_POS)
1495# undef RTVfsFsStrmRetain
1496# define RTVfsFsStrmRetain(hVfsFss) RTVfsFsStrmRetainDebug(hVfsFss, RT_SRC_POS)
1497#endif
1498
1499
1500
1501/** @defgroup grp_vfs_misc VFS Miscellaneous
1502 * @{
1503 */
1504
1505/**
1506 * Memorizes the I/O stream as a file backed by memory.
1507 *
1508 * @returns IPRT status code.
1509 *
1510 * @param hVfsIos The VFS I/O stream to memorize. This will be read
1511 * to the end on success, on failure its position is
1512 * undefined.
1513 * @param fFlags A combination of RTFILE_O_READ and RTFILE_O_WRITE.
1514 * @param phVfsFile Where to return the handle to the memory file on
1515 * success.
1516 */
1517RTDECL(int) RTVfsMemorizeIoStreamAsFile(RTVFSIOSTREAM hVfsIos, uint32_t fFlags, PRTVFSFILE phVfsFile);
1518
1519/**
1520 * Creates a VFS file from a memory buffer.
1521 *
1522 * @returns IPRT status code.
1523 *
1524 * @param fFlags A combination of RTFILE_O_READ and RTFILE_O_WRITE.
1525 * @param pvBuf The buffer. This will be copied and not referenced
1526 * after this function returns.
1527 * @param cbBuf The buffer size.
1528 * @param phVfsFile Where to return the handle to the memory file on
1529 * success.
1530 */
1531RTDECL(int) RTVfsFileFromBuffer(uint32_t fFlags, void const *pvBuf, size_t cbBuf, PRTVFSFILE phVfsFile);
1532
1533/**
1534 * Creates a memory backed VFS file object for read and write.
1535 *
1536 * @returns IPRT status code.
1537 *
1538 * @param hVfsIos The VFS I/O stream to memorize. This will be read
1539 * to the end on success, on failure its position is
1540 * undefined.
1541 * @param cbEstimate The estimated file size.
1542 * @param phVfsFile Where to return the handle to the memory file on
1543 * success.
1544 * @sa RTVfsMemIoStrmCreate
1545 */
1546RTDECL(int) RTVfsMemFileCreate(RTVFSIOSTREAM hVfsIos, size_t cbEstimate, PRTVFSFILE phVfsFile);
1547
1548/**
1549 * Creates a memory backed VFS file object for read and write.
1550 *
1551 * @returns IPRT status code.
1552 *
1553 * @param hVfsIos The VFS I/O stream to memorize. This will be read
1554 * to the end on success, on failure its position is
1555 * undefined.
1556 * @param cbEstimate The estimated file size.
1557 * @param phVfsIos Where to return the handle to the memory I/O stream
1558 * on success.
1559 * @sa RTVfsMemFileCreate
1560 */
1561RTDECL(int) RTVfsMemIoStrmCreate(RTVFSIOSTREAM hVfsIos, size_t cbEstimate, PRTVFSIOSTREAM phVfsIos);
1562
1563/**
1564 * Pumps data from one I/O stream to another.
1565 *
1566 * The data is read in chunks from @a hVfsIosSrc and written to @a hVfsIosDst
1567 * until @a hVfsIosSrc indicates end of stream.
1568 *
1569 * @returns IPRT status code
1570 *
1571 * @param hVfsIosSrc The input stream.
1572 * @param hVfsIosDst The output stream.
1573 * @param cbBufHint Hints at a good temporary buffer size, pass 0 if
1574 * clueless.
1575 */
1576RTDECL(int) RTVfsUtilPumpIoStreams(RTVFSIOSTREAM hVfsIosSrc, RTVFSIOSTREAM hVfsIosDst, size_t cbBufHint);
1577
1578
1579/**
1580 * Creates a progress wrapper for an I/O stream.
1581 *
1582 * @returns IRPT status code.
1583 * @param hVfsIos The I/O stream to wrap.
1584 * @param pfnProgress The progress callback. The return code is
1585 * ignored by default, see
1586 * RTVFSPROGRESS_F_CANCELABLE.
1587 * @param pvUser The user argument to @a pfnProgress.
1588 * @param fFlags RTVFSPROGRESS_F_XXX
1589 * @param cbExpectedRead The expected number of bytes read.
1590 * @param cbExpectedWritten The execpted number of bytes written.
1591 * @param phVfsIos Where to return the I/O stream handle.
1592 */
1593RTDECL(int) RTVfsCreateProgressForIoStream(RTVFSIOSTREAM hVfsIos, PFNRTPROGRESS pfnProgress, void *pvUser, uint32_t fFlags,
1594 uint64_t cbExpectedRead, uint64_t cbExpectedWritten, PRTVFSIOSTREAM phVfsIos);
1595
1596/**
1597 * Creates a progress wrapper for a file stream.
1598 *
1599 * @returns IRPT status code.
1600 * @param hVfsFile The file to wrap.
1601 * @param pfnProgress The progress callback. The return code is
1602 * ignored by default, see
1603 * RTVFSPROGRESS_F_CANCELABLE.
1604 * @param pvUser The user argument to @a pfnProgress.
1605 * @param fFlags RTVFSPROGRESS_F_XXX
1606 * @param cbExpectedRead The expected number of bytes read.
1607 * @param cbExpectedWritten The execpted number of bytes written.
1608 * @param phVfsFile Where to return the file handle.
1609 */
1610RTDECL(int) RTVfsCreateProgressForFile(RTVFSFILE hVfsFile, PFNRTPROGRESS pfnProgress, void *pvUser, uint32_t fFlags,
1611 uint64_t cbExpectedRead, uint64_t cbExpectedWritten, PRTVFSFILE phVfsFile);
1612
1613/** @name RTVFSPROGRESS_F_XXX - Flags for RTVfsCreateProcessForIoStream and
1614 * RTVfsCreateProcessForFile.
1615 * @{ */
1616/** Cancel if the callback returns a failure status code.
1617 * This isn't default behavior because the cancelation is delayed one I/O
1618 * operation in most cases and it's uncertain how the VFS user will handle the
1619 * cancellation status code. */
1620#define RTVFSPROGRESS_F_CANCELABLE RT_BIT_32(0)
1621/** Account forward seeks as reads. */
1622#define RTVFSPROGRESS_F_FORWARD_SEEK_AS_READ RT_BIT_32(1)
1623/** Account fprward seeks as writes. */
1624#define RTVFSPROGRESS_F_FORWARD_SEEK_AS_WRITE RT_BIT_32(2)
1625/** Valid bits. */
1626#define RTVFSPROGRESS_F_VALID_MASK UINT32_C(0x00000007)
1627/** @} */
1628
1629
1630/**
1631 * Create an I/O stream instance performing simple sequential read-ahead.
1632 *
1633 * @returns IPRT status code.
1634 * @param hVfsIos The input stream to perform read ahead on. If this is
1635 * actually for a file object, the returned I/O stream
1636 * handle can also be cast to a file handle.
1637 * @param fFlags Flags reserved for future use, MBZ.
1638 * @param cBuffers How many read ahead buffers to use. Specify 0 for
1639 * default value.
1640 * @param cbBuffer The size of each read ahead buffer. Specify 0 for
1641 * default value.
1642 * @param phVfsIos Where to return the read ahead I/O stream handle.
1643 *
1644 * @remarks Careful using this on a message pipe or socket. The reads are
1645 * performed in blocked mode and it may be host and/or implementation
1646 * dependent whether they will return ready data immediate or wait
1647 * until there's a whole @a cbBuffer (or default) worth ready.
1648 *
1649 * @sa RTVfsCreateReadAheadForFile
1650 */
1651RTDECL(int) RTVfsCreateReadAheadForIoStream(RTVFSIOSTREAM hVfsIos, uint32_t fFlags, uint32_t cBuffers, uint32_t cbBuffer,
1652 PRTVFSIOSTREAM phVfsIos);
1653
1654/**
1655 * Create an I/O stream instance performing simple sequential read-ahead.
1656 *
1657 * @returns IPRT status code.
1658 * @param hVfsFile The input file to perform read ahead on.
1659 * @param fFlags Flags reserved for future use, MBZ.
1660 * @param cBuffers How many read ahead buffers to use. Specify 0 for
1661 * default value.
1662 * @param cbBuffer The size of each read ahead buffer. Specify 0 for
1663 * default value.
1664 * @param phVfsFile Where to return the read ahead file handle.
1665 * @sa RTVfsCreateReadAheadForIoStream
1666 */
1667RTDECL(int) RTVfsCreateReadAheadForFile(RTVFSFILE hVfsFile, uint32_t fFlags, uint32_t cBuffers, uint32_t cbBuffer,
1668 PRTVFSFILE phVfsFile);
1669
1670
1671/**
1672 * Create a file system stream for writing to a directory.
1673 *
1674 * This is just supposed to be a drop in replacement for the TAR creator stream
1675 * that instead puts the files and stuff in a directory instead of a TAR
1676 * archive. In addition, it has an undo feature for simplying cleaning up after
1677 * a botched run
1678 *
1679 * @returns IPRT status code.
1680 * @param hVfsBaseDir The base directory.
1681 * @param fFlags RTVFSFSS2DIR_F_XXX
1682 * @param phVfsFss Where to return the FSS handle.
1683 * @sa RTVfsFsStrmToNormalDir, RTVfsFsStrmToDirUndo
1684 */
1685RTDECL(int) RTVfsFsStrmToDir(RTVFSDIR hVfsBaseDir, uint32_t fFlags, PRTVFSFSSTREAM phVfsFss);
1686
1687/**
1688 * Create a file system stream for writing to a normal directory.
1689 *
1690 * This is just supposed to be a drop in replacement for the TAR creator stream
1691 * that instead puts the files and stuff in a directory instead of a TAR
1692 * archive. In addition, it has an undo feature for simplying cleaning up after
1693 * a botched run
1694 *
1695 * @returns IPRT status code.
1696 * @param pszBaseDir The base directory. Must exist.
1697 * @param fFlags RTVFSFSS2DIR_F_XXX
1698 * @param phVfsFss Where to return the FSS handle.
1699 * @sa RTVfsFsStrmToDir, RTVfsFsStrmToDirUndo
1700 */
1701RTDECL(int) RTVfsFsStrmToNormalDir(const char *pszBaseDir, uint32_t fFlags, PRTVFSFSSTREAM phVfsFss);
1702
1703/** @name RTVFSFSS2DIR_F_XXX - Flags for RTVfsFsStrmToNormalDir
1704 * @{ */
1705/** Overwrite existing files (default is to not overwrite anything). */
1706#define RTVFSFSS2DIR_F_OVERWRITE_FILES RT_BIT_32(0)
1707/** Valid bits. */
1708#define RTVFSFSS2DIR_F_VALID_MASK UINT32_C(0x00000001)
1709/** @} */
1710
1711/**
1712 * Deletes files, directories, symlinks and stuff created by a FSS returned by
1713 * RTVfsFsStrmToNormalDir or RTVfsFsStrmToDir.
1714 *
1715 * @returns IPRT status code.
1716 * @param hVfsFss The write-to-directory FSS handle.
1717 */
1718RTDECL(int) RTVfsFsStrmToDirUndo(RTVFSFSSTREAM hVfsFss);
1719
1720
1721
1722/** @} */
1723
1724
1725/** @defgroup grp_rt_vfs_chain VFS Chains
1726 *
1727 * VFS chains is for doing pipe like things with VFS objects from the command
1728 * line. Imagine you want to cat the readme.gz of an ISO you could do
1729 * something like:
1730 * RTCat :iprtvfs:file(stdfile,live.iso)|vfs(isofs)|iso(open,readme.gz)|ios(gunzip)
1731 * or
1732 * RTCat :iprtvfs:file(stdfile,live.iso)|ios(isofs,readme.gz)|ios(gunzip)
1733 *
1734 * Or say you want to read the README.TXT on a floppy image:
1735 * RTCat :iprtvfs:file(stdfile,floppy.img,r)|vfs(fat)|ios(open,README.TXT)
1736 * or
1737 * RTCat :iprtvfs:file(stdfile,floppy.img,r)|vfs(fat)|README.TXT
1738 *
1739 * Or in the other direction, you want to write a STUFF.TGZ file to the above
1740 * floppy image, using a lazy writer thread for compressing the data:
1741 * RTTar cf :iprtvfs:file(stdfile,floppy.img,rw)|ios(fat,STUFF.TGZ)|ios(gzip)|ios(push) .
1742 *
1743 *
1744 * A bit more formally:
1745 * :iprtvfs:{type}({provider}[,provider-args])[{separator}{type}...][{separator}{path}]
1746 *
1747 * The @c type refers to VFS object that should be created by the @c provider.
1748 * Valid types:
1749 * - vfs: A virtual file system (volume).
1750 * - fss: A file system stream (e.g. tar).
1751 * - ios: An I/O stream.
1752 * - file: A file.
1753 * - dir: A directory.
1754 * - sym: A symbolic link (not sure how useful this is).
1755 *
1756 * The @c provider refers to registered chain element providers (see
1757 * RTVFSCHAINELEMENTREG for how that works internally). These are asked to
1758 * create a VFS object of the specified type using the given arguments (if any).
1759 * Default providers:
1760 * - std: Standard file, directory and file system.
1761 * - open: Opens a file, I/O stream or directory in a vfs or directory object.
1762 * - pull: Read-ahead buffering thread on file or I/O stream.
1763 * - push: Lazy-writer buffering thread on file or I/O stream.
1764 * - gzip: Compresses an I/O stream.
1765 * - gunzip: Decompresses an I/O stream.
1766 * - fat: FAT file system accessor.
1767 * - isofs: ISOFS file system accessor.
1768 *
1769 * As element @c separator we allow both colon (':') and the pipe character
1770 * ('|'). The latter the conventional one, but since it's inconvenient on the
1771 * command line, colon is provided as an alternative.
1772 *
1773 * In the final element we allow a simple @a path to be specified instead of the
1774 * type-provider-arguments stuff. The previous object must be a directory, file
1775 * system or file system stream. The application will determin exactly which
1776 * operation or operations which will be performed.
1777 *
1778 * @{
1779 */
1780
1781/** The path prefix used to identify an VFS chain specification. */
1782#define RTVFSCHAIN_SPEC_PREFIX ":iprtvfs:"
1783
1784RTDECL(int) RTVfsChainOpenVfs(const char *pszSpec, PRTVFS phVfs, uint32_t *poffError, PRTERRINFO pErrInfo);
1785RTDECL(int) RTVfsChainOpenFsStream(const char *pszSpec, PRTVFSFSSTREAM phVfsFss, uint32_t *poffError, PRTERRINFO pErrInfo);
1786
1787/**
1788 * Opens any kind of file system object.
1789 *
1790 * @returns IPRT status code.
1791 * @param pszSpec The VFS chain specification or plain path.
1792 * @param fFileOpen RTFILE_O_XXX flags.
1793 * @param fObjFlags More flags: RTVFSOBJ_F_XXX, RTPATH_F_XXX.
1794 * @param phVfsObj Where to return the handle to the opened object.
1795 * @param poffError Where to on error return an offset into @a pszSpec
1796 * of what cause the error. Optional.
1797 * @param pErrInfo Where to return additional error information.
1798 * Optional.
1799 */
1800RTDECL(int) RTVfsChainOpenObj(const char *pszSpec, uint64_t fFileOpen, uint32_t fObjFlags,
1801 PRTVFSOBJ phVfsObj, uint32_t *poffError, PRTERRINFO pErrInfo);
1802
1803RTDECL(int) RTVfsChainOpenDir(const char *pszSpec, uint32_t fOpen, PRTVFSDIR phVfsDir, uint32_t *poffError, PRTERRINFO pErrInfo);
1804RTDECL(int) RTVfsChainOpenParentDir(const char *pszSpec, uint32_t fOpen, PRTVFSDIR phVfsDir, const char **ppszChild,
1805 uint32_t *poffError, PRTERRINFO pErrInfo);
1806RTDECL(int) RTVfsChainOpenFile(const char *pszSpec, uint64_t fOpen, PRTVFSFILE phVfsFile, uint32_t *poffError, PRTERRINFO pErrInfo);
1807RTDECL(int) RTVfsChainOpenIoStream(const char *pszSpec, uint64_t fOpen, PRTVFSIOSTREAM phVfsIos, uint32_t *poffError, PRTERRINFO pErrInfo);
1808RTDECL(int) RTVfsChainOpenSymlink(const char *pszSpec, PRTVFSSYMLINK phVfsSym, uint32_t *poffError, PRTERRINFO pErrInfo);
1809
1810RTDECL(int) RTVfsChainQueryInfo(const char *pszSpec, PRTFSOBJINFO pObjInfo, RTFSOBJATTRADD enmAdditionalAttribs,
1811 uint32_t fFlags, uint32_t *poffError, PRTERRINFO pErrInfo);
1812
1813/**
1814 * Tests if the given string is a chain specification or not.
1815 *
1816 * @returns true if it is, false if it isn't.
1817 * @param pszSpec The alleged chain spec.
1818 */
1819RTDECL(bool) RTVfsChainIsSpec(const char *pszSpec);
1820
1821/**
1822 * Queries the path from the final element.
1823 *
1824 * @returns IPRT status code.
1825 * @retval VERR_VFS_CHAIN_NOT_PATH_ONLY if the final element isn't just a
1826 * simple path.
1827 * @param pszSpec The chain spec.
1828 * @param ppszFinalPath Where to return a copy of the final path on success.
1829 * Call RTStrFree when done.
1830 * @param poffError Where to on error return an offset into @a pszSpec
1831 * of what cause the error. Optional.
1832 *
1833 */
1834RTDECL(int) RTVfsChainQueryFinalPath(const char *pszSpec, char **ppszFinalPath, uint32_t *poffError);
1835
1836/**
1837 * Splits the given chain spec into a final path and the preceeding spec.
1838 *
1839 * This works on plain paths too.
1840 *
1841 * @returns IPRT status code.
1842 * @param pszSpec The chain spec to split. This will be modified!
1843 * @param ppszSpec Where to return the pointer to the chain spec part.
1844 * This is set to NULL if it's a plain path or a chain
1845 * spec with only a final-path element.
1846 * @param ppszFinalPath Where to return the pointer to the final path. This
1847 * is set to NULL if no final path.
1848 * @param poffError Where to on error return an offset into @a pszSpec
1849 * of what cause the error. Optional.
1850 */
1851RTDECL(int) RTVfsChainSplitOffFinalPath(char *pszSpec, char **ppszSpec, char **ppszFinalPath, uint32_t *poffError);
1852
1853/**
1854 * Common code for reporting errors of a RTVfsChainOpen* API.
1855 *
1856 * @param pszFunction The API called.
1857 * @param pszSpec The VFS chain specification or file path passed to the.
1858 * @param rc The return code.
1859 * @param offError The error offset value returned (0 if not captured).
1860 * @param pErrInfo Additional error information. Optional.
1861 *
1862 * @sa RTVfsChainMsgErrorExitFailure
1863 * @sa RTVfsChainOpenVfs, RTVfsChainOpenFsStream, RTVfsChainOpenDir,
1864 * RTVfsChainOpenFile, RTVfsChainOpenIoStream, RTVfsChainOpenSymlink
1865 */
1866RTDECL(void) RTVfsChainMsgError(const char *pszFunction, const char *pszSpec, int rc, uint32_t offError, PRTERRINFO pErrInfo);
1867
1868/**
1869 * Common code for reporting errors of a RTVfsChainOpen* API.
1870 *
1871 * @returns RTEXITCODE_FAILURE
1872 *
1873 * @param pszFunction The API called.
1874 * @param pszSpec The VFS chain specification or file path passed to the.
1875 * @param rc The return code.
1876 * @param offError The error offset value returned (0 if not captured).
1877 * @param pErrInfo Additional error information. Optional.
1878 *
1879 * @sa RTVfsChainMsgError
1880 * @sa RTVfsChainOpenVfs, RTVfsChainOpenFsStream, RTVfsChainOpenDir,
1881 * RTVfsChainOpenFile, RTVfsChainOpenIoStream, RTVfsChainOpenSymlink
1882 */
1883RTDECL(RTEXITCODE) RTVfsChainMsgErrorExitFailure(const char *pszFunction, const char *pszSpec,
1884 int rc, uint32_t offError, PRTERRINFO pErrInfo);
1885
1886
1887/** @} */
1888
1889
1890/** @} */
1891
1892RT_C_DECLS_END
1893
1894#endif /* !IPRT_INCLUDED_vfs_h */
1895
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