summaryrefslogtreecommitdiffstats
path: root/include/iprt/vfslowlevel.h
diff options
context:
space:
mode:
authorDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-07 16:49:04 +0000
committerDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-07 16:49:04 +0000
commit16f504a9dca3fe3b70568f67b7d41241ae485288 (patch)
treec60f36ada0496ba928b7161059ba5ab1ab224f9d /include/iprt/vfslowlevel.h
parentInitial commit. (diff)
downloadvirtualbox-16f504a9dca3fe3b70568f67b7d41241ae485288.tar.xz
virtualbox-16f504a9dca3fe3b70568f67b7d41241ae485288.zip
Adding upstream version 7.0.6-dfsg.upstream/7.0.6-dfsgupstream
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to 'include/iprt/vfslowlevel.h')
-rw-r--r--include/iprt/vfslowlevel.h1588
1 files changed, 1588 insertions, 0 deletions
diff --git a/include/iprt/vfslowlevel.h b/include/iprt/vfslowlevel.h
new file mode 100644
index 00000000..aba442ca
--- /dev/null
+++ b/include/iprt/vfslowlevel.h
@@ -0,0 +1,1588 @@
+/** @file
+ * IPRT - Virtual Filesystem.
+ */
+
+/*
+ * Copyright (C) 2010-2022 Oracle and/or its affiliates.
+ *
+ * This file is part of VirtualBox base platform packages, as
+ * available from https://www.virtualbox.org.
+ *
+ * This program is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU General Public License
+ * as published by the Free Software Foundation, in version 3 of the
+ * License.
+ *
+ * This program is distributed in the hope that it will be useful, but
+ * WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ * General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program; if not, see <https://www.gnu.org/licenses>.
+ *
+ * The contents of this file may alternatively be used under the terms
+ * of the Common Development and Distribution License Version 1.0
+ * (CDDL), a copy of it is provided in the "COPYING.CDDL" file included
+ * in the VirtualBox distribution, in which case the provisions of the
+ * CDDL are applicable instead of those of the GPL.
+ *
+ * You may elect to license modified versions of this file under the
+ * terms and conditions of either the GPL or the CDDL or both.
+ *
+ * SPDX-License-Identifier: GPL-3.0-only OR CDDL-1.0
+ */
+
+#ifndef IPRT_INCLUDED_vfslowlevel_h
+#define IPRT_INCLUDED_vfslowlevel_h
+#ifndef RT_WITHOUT_PRAGMA_ONCE
+# pragma once
+#endif
+
+#include <iprt/vfs.h>
+#include <iprt/errcore.h>
+#include <iprt/list.h>
+#include <iprt/param.h>
+
+
+RT_C_DECLS_BEGIN
+
+/** @defgroup grp_rt_vfs_lowlevel RTVfs - Low-level Interface.
+ * @ingroup grp_rt_vfs
+ * @{
+ */
+
+
+/** @name VFS Lock Abstraction
+ * @todo This should be moved somewhere else as it is of general use.
+ * @{ */
+
+/**
+ * VFS lock types.
+ */
+typedef enum RTVFSLOCKTYPE
+{
+ /** Invalid lock type. */
+ RTVFSLOCKTYPE_INVALID = 0,
+ /** Read write semaphore. */
+ RTVFSLOCKTYPE_RW,
+ /** Fast mutex semaphore (critical section in ring-3). */
+ RTVFSLOCKTYPE_FASTMUTEX,
+ /** Full fledged mutex semaphore. */
+ RTVFSLOCKTYPE_MUTEX,
+ /** The end of valid lock types. */
+ RTVFSLOCKTYPE_END,
+ /** The customary 32-bit type hack. */
+ RTVFSLOCKTYPE_32BIT_HACK = 0x7fffffff
+} RTVFSLOCKTYPE;
+
+/** VFS lock handle. */
+typedef struct RTVFSLOCKINTERNAL *RTVFSLOCK;
+/** Pointer to a VFS lock handle. */
+typedef RTVFSLOCK *PRTVFSLOCK;
+/** Nil VFS lock handle. */
+#define NIL_RTVFSLOCK ((RTVFSLOCK)~(uintptr_t)0)
+
+/** Special handle value for creating a new read/write semaphore based lock. */
+#define RTVFSLOCK_CREATE_RW ((RTVFSLOCK)~(uintptr_t)1)
+/** Special handle value for creating a new fast mutex semaphore based lock. */
+#define RTVFSLOCK_CREATE_FASTMUTEX ((RTVFSLOCK)~(uintptr_t)2)
+/** Special handle value for creating a new mutex semaphore based lock. */
+#define RTVFSLOCK_CREATE_MUTEX ((RTVFSLOCK)~(uintptr_t)3)
+
+/**
+ * Retains a reference to the VFS lock handle.
+ *
+ * @returns New reference count on success, UINT32_MAX on failure.
+ * @param hLock The VFS lock handle.
+ */
+RTDECL(uint32_t) RTVfsLockRetain(RTVFSLOCK hLock);
+
+/**
+ * Releases a reference to the VFS lock handle.
+ *
+ * @returns New reference count on success (0 if closed), UINT32_MAX on failure.
+ * @param hLock The VFS lock handle.
+ */
+RTDECL(uint32_t) RTVfsLockRelease(RTVFSLOCK hLock);
+
+/**
+ * Gets the lock type.
+ *
+ * @returns The lock type on success, RTVFSLOCKTYPE_INVALID if the handle is
+ * not valid.
+ * @param hLock The lock handle.
+ */
+RTDECL(RTVFSLOCKTYPE) RTVfsLockGetType(RTVFSLOCK hLock);
+
+
+
+RTDECL(void) RTVfsLockAcquireReadSlow(RTVFSLOCK hLock);
+RTDECL(void) RTVfsLockReleaseReadSlow(RTVFSLOCK hLock);
+RTDECL(void) RTVfsLockAcquireWriteSlow(RTVFSLOCK hLock);
+RTDECL(void) RTVfsLockReleaseWriteSlow(RTVFSLOCK hLock);
+
+/**
+ * Acquire a read lock.
+ *
+ * @param hLock The lock handle, can be NIL.
+ */
+DECLINLINE(void) RTVfsLockAcquireRead(RTVFSLOCK hLock)
+{
+ if (hLock != NIL_RTVFSLOCK)
+ RTVfsLockAcquireReadSlow(hLock);
+}
+
+
+/**
+ * Release a read lock.
+ *
+ * @param hLock The lock handle, can be NIL.
+ */
+DECLINLINE(void) RTVfsLockReleaseRead(RTVFSLOCK hLock)
+{
+ if (hLock != NIL_RTVFSLOCK)
+ RTVfsLockReleaseReadSlow(hLock);
+}
+
+
+/**
+ * Acquire a write lock.
+ *
+ * @param hLock The lock handle, can be NIL.
+ */
+DECLINLINE(void) RTVfsLockAcquireWrite(RTVFSLOCK hLock)
+{
+ if (hLock != NIL_RTVFSLOCK)
+ RTVfsLockAcquireWriteSlow(hLock);
+}
+
+
+/**
+ * Release a write lock.
+ *
+ * @param hLock The lock handle, can be NIL.
+ */
+DECLINLINE(void) RTVfsLockReleaseWrite(RTVFSLOCK hLock)
+{
+ if (hLock != NIL_RTVFSLOCK)
+ RTVfsLockReleaseWriteSlow(hLock);
+}
+
+/** @} */
+
+/**
+ * Info queried via RTVFSOBJOPS::pfnQueryInfoEx, ++.
+ */
+typedef enum RTVFSQIEX
+{
+ /** Invalid zero value. */
+ RTVFSQIEX_INVALID = 0,
+ /** Volume label.
+ * Returns a UTF-8 string. */
+ RTVFSQIEX_VOL_LABEL,
+ /** Alternative volume label, the primary one for ISOs, otherwise treated same
+ * as RTVFSQIEX_VOL_LABEL. */
+ RTVFSQIEX_VOL_LABEL_ALT,
+ /** Volume serial number.
+ * Returns a uint32_t, uint64_t or RTUUID. */
+ RTVFSQIEX_VOL_SERIAL,
+ /** End of valid queries. */
+ RTVFSQIEX_END,
+
+ /** The usual 32-bit hack. */
+ RTVFSQIEX_32BIT_SIZE_HACK = 0x7fffffff
+} RTVFSQIEX;
+
+
+/**
+ * The basis for all virtual file system objects.
+ */
+typedef struct RTVFSOBJOPS
+{
+ /** The structure version (RTVFSOBJOPS_VERSION). */
+ uint32_t uVersion;
+ /** The object type for type introspection. */
+ RTVFSOBJTYPE enmType;
+ /** The name of the operations. */
+ const char *pszName;
+
+ /**
+ * Close the object.
+ *
+ * @returns IPRT status code.
+ * @param pvThis The implementation specific file data.
+ */
+ DECLCALLBACKMEMBER(int, pfnClose,(void *pvThis));
+
+ /**
+ * Get information about the file.
+ *
+ * @returns IPRT status code. See RTVfsObjQueryInfo.
+ * @retval VERR_WRONG_TYPE if file system or file system stream.
+ *
+ * @param pvThis The implementation specific file data.
+ * @param pObjInfo Where to return the object info on success.
+ * @param enmAddAttr Which set of additional attributes to request.
+ * @sa RTVfsObjQueryInfo, RTFileQueryInfo, RTPathQueryInfo
+ */
+ DECLCALLBACKMEMBER(int, pfnQueryInfo,(void *pvThis, PRTFSOBJINFO pObjInfo, RTFSOBJATTRADD enmAddAttr));
+
+ /**
+ * Query arbritray information about the file, volume, or whatever.
+ *
+ * @returns IPRT status code.
+ * @retval VERR_BUFFER_OVERFLOW sets pcbRet.
+ *
+ * @param pvThis The implementation specific file data.
+ * @param enmInfo The information being queried.
+ * @param pvInfo Where to return the info.
+ * @param cbInfo The size of the @a pvInfo buffer.
+ * @param pcbRet The size of the returned data. In case of
+ * VERR_BUFFER_OVERFLOW this will be set to the required
+ * buffer size.
+ */
+ DECLCALLBACKMEMBER(int, pfnQueryInfoEx,(void *pvThis, RTVFSQIEX enmInfo, void *pvInfo, size_t cbInfo, size_t *pcbRet));
+
+ /** Marks the end of the structure (RTVFSOBJOPS_VERSION). */
+ uintptr_t uEndMarker;
+} RTVFSOBJOPS;
+/** Pointer to constant VFS object operations. */
+typedef RTVFSOBJOPS const *PCRTVFSOBJOPS;
+
+/** The RTVFSOBJOPS structure version. */
+#define RTVFSOBJOPS_VERSION RT_MAKE_U32_FROM_U8(0xff,0x1f,2,0)
+
+
+/**
+ * The VFS operations.
+ */
+typedef struct RTVFSOPS
+{
+ /** The basic object operation. */
+ RTVFSOBJOPS Obj;
+ /** The structure version (RTVFSOPS_VERSION). */
+ uint32_t uVersion;
+ /** The virtual file system feature mask. */
+ uint32_t fFeatures;
+
+ /**
+ * Opens the root directory.
+ *
+ * @returns IPRT status code.
+ * @param pvThis The implementation specific data.
+ * @param phVfsDir Where to return the handle to the root directory.
+ */
+ DECLCALLBACKMEMBER(int, pfnOpenRoot,(void *pvThis, PRTVFSDIR phVfsDir));
+
+ /**
+ * Query the status of the given storage range (optional).
+ *
+ * This can be used by the image compaction utilites to evict non-zero blocks
+ * that aren't currently being used by the file system.
+ *
+ * @returns IPRT status code.
+ * @param pvThis The implementation specific data.
+ * @param off Start offset to check.
+ * @param cb Number of bytes to check.
+ * @param pfUsed Where to store whether the given range is in use.
+ */
+ DECLCALLBACKMEMBER(int, pfnQueryRangeState,(void *pvThis, uint64_t off, size_t cb, bool *pfUsed));
+
+ /** @todo There will be more methods here to optimize opening and
+ * querying. */
+
+#if 0
+ /**
+ * Optional entry point for optimizing path traversal within the file system.
+ *
+ * @returns IPRT status code.
+ * @param pvThis The implementation specific data.
+ * @param pszPath The path to resolve.
+ * @param poffPath The current path offset on input, what we've
+ * traversed to on successful return.
+ * @param phVfs??? Return handle to what we've traversed.
+ * @param p??? Return other stuff...
+ */
+ DECLCALLBACKMEMBER(int, pfnTraverse,(void *pvThis, const char *pszPath, size_t *poffPath, PRTVFS??? phVfs?, ???* p???));
+#endif
+
+ /** @todo need rename API */
+
+ /** Marks the end of the structure (RTVFSOPS_VERSION). */
+ uintptr_t uEndMarker;
+} RTVFSOPS;
+/** Pointer to constant VFS operations. */
+typedef RTVFSOPS const *PCRTVFSOPS;
+
+/** The RTVFSOPS structure version. */
+#define RTVFSOPS_VERSION RT_MAKE_U32_FROM_U8(0xff,0x0f,1,0)
+
+/** @name RTVFSOPS::fFeatures
+ * @{ */
+/** The VFS supports attaching other systems. */
+#define RTVFSOPS_FEAT_ATTACH RT_BIT_32(0)
+/** @} */
+
+/**
+ * Creates a new VFS handle.
+ *
+ * @returns IPRT status code
+ * @param pVfsOps The VFS operations.
+ * @param cbInstance The size of the instance data.
+ * @param hVfs The VFS handle to associate this VFS with.
+ * NIL_VFS is ok.
+ * @param hLock Handle to a custom lock to be used with the new
+ * object. The reference is consumed. NIL and
+ * special lock handles are fine.
+ * @param phVfs Where to return the new handle.
+ * @param ppvInstance Where to return the pointer to the instance data
+ * (size is @a cbInstance).
+ */
+RTDECL(int) RTVfsNew(PCRTVFSOPS pVfsOps, size_t cbInstance, RTVFS hVfs, RTVFSLOCK hLock,
+ PRTVFS phVfs, void **ppvInstance);
+
+
+/**
+ * Creates a new VFS base object handle.
+ *
+ * @returns IPRT status code
+ * @param pObjOps The base object operations.
+ * @param cbInstance The size of the instance data.
+ * @param hVfs The VFS handle to associate this base object
+ * with. NIL_VFS is ok.
+ * @param hLock Handle to a custom lock to be used with the new
+ * object. The reference is consumed. NIL and
+ * special lock handles are fine.
+ * @param phVfsObj Where to return the new handle.
+ * @param ppvInstance Where to return the pointer to the instance data
+ * (size is @a cbInstance).
+ */
+RTDECL(int) RTVfsNewBaseObj(PCRTVFSOBJOPS pObjOps, size_t cbInstance, RTVFS hVfs, RTVFSLOCK hLock,
+ PRTVFSOBJ phVfsObj, void **ppvInstance);
+
+
+/**
+ * Gets the private data of a base object.
+ *
+ * @returns Pointer to the private data. NULL if the handle is invalid in some
+ * way.
+ * @param hVfsObj The I/O base object handle.
+ * @param pObjOps The base object operations. This servers as a
+ * sort of password.
+ */
+RTDECL(void *) RTVfsObjToPrivate(RTVFSOBJ hVfsObj, PCRTVFSOBJOPS pObjOps);
+
+/**
+ * Additional operations for setting object attributes.
+ */
+typedef struct RTVFSOBJSETOPS
+{
+ /** The structure version (RTVFSOBJSETOPS_VERSION). */
+ uint32_t uVersion;
+ /** The offset back to the RTVFSOBJOPS structure. */
+ uint32_t offObjOps;
+
+ /**
+ * Set the unix style owner and group.
+ *
+ * @returns IPRT status code.
+ * @param pvThis The implementation specific file data.
+ * @param fMode The new mode bits.
+ * @param fMask The mask indicating which bits we are
+ * changing.
+ * @note Optional, failing with VERR_WRITE_PROTECT if NULL.
+ * @sa RTFileSetMode
+ */
+ DECLCALLBACKMEMBER(int, pfnSetMode,(void *pvThis, RTFMODE fMode, RTFMODE fMask));
+
+ /**
+ * Set the timestamps associated with the object.
+ *
+ * @returns IPRT status code.
+ * @param pvThis The implementation specific file data.
+ * @param pAccessTime Pointer to the new access time. NULL if not
+ * to be changed.
+ * @param pModificationTime Pointer to the new modifcation time. NULL if
+ * not to be changed.
+ * @param pChangeTime Pointer to the new change time. NULL if not
+ * to be changed.
+ * @param pBirthTime Pointer to the new time of birth. NULL if
+ * not to be changed.
+ * @remarks See RTFileSetTimes for restrictions and behavior imposed by the
+ * host OS or underlying VFS provider.
+ * @note Optional, failing with VERR_WRITE_PROTECT if NULL.
+ * @sa RTFileSetTimes
+ */
+ DECLCALLBACKMEMBER(int, pfnSetTimes,(void *pvThis, PCRTTIMESPEC pAccessTime, PCRTTIMESPEC pModificationTime,
+ PCRTTIMESPEC pChangeTime, PCRTTIMESPEC pBirthTime));
+
+ /**
+ * Set the unix style owner and group.
+ *
+ * @returns IPRT status code.
+ * @param pvThis The implementation specific file data.
+ * @param uid The user ID of the new owner. NIL_RTUID if
+ * unchanged.
+ * @param gid The group ID of the new owner group. NIL_RTGID if
+ * unchanged.
+ * @note Optional, failing with VERR_WRITE_PROTECT if NULL.
+ * @sa RTFileSetOwner
+ */
+ DECLCALLBACKMEMBER(int, pfnSetOwner,(void *pvThis, RTUID uid, RTGID gid));
+
+ /** Marks the end of the structure (RTVFSOBJSETOPS_VERSION). */
+ uintptr_t uEndMarker;
+} RTVFSOBJSETOPS;
+/** Pointer to const object attribute setter operations. */
+typedef RTVFSOBJSETOPS const *PCRTVFSOBJSETOPS;
+
+/** The RTVFSOBJSETOPS structure version. */
+#define RTVFSOBJSETOPS_VERSION RT_MAKE_U32_FROM_U8(0xff,0x2f,1,0)
+
+
+/**
+ * The filesystem stream operations.
+ *
+ * @extends RTVFSOBJOPS
+ */
+typedef struct RTVFSFSSTREAMOPS
+{
+ /** The basic object operation. */
+ RTVFSOBJOPS Obj;
+ /** The structure version (RTVFSFSSTREAMOPS_VERSION). */
+ uint32_t uVersion;
+ /** Reserved field, MBZ. */
+ uint32_t fReserved;
+
+ /**
+ * Gets the next object in the stream.
+ *
+ * Readable streams only.
+ *
+ * @returns IPRT status code.
+ * @retval VINF_SUCCESS if a new object was retrieved.
+ * @retval VERR_EOF when there are no more objects.
+ * @param pvThis The implementation specific directory data.
+ * @param ppszName Where to return the object name. Must be freed by
+ * calling RTStrFree.
+ * @param penmType Where to return the object type.
+ * @param phVfsObj Where to return the object handle (referenced). This
+ * must be cast to the desired type before use.
+ * @sa RTVfsFsStrmNext
+ *
+ * @note Setting this member to NULL is okay for write-only streams.
+ */
+ DECLCALLBACKMEMBER(int, pfnNext,(void *pvThis, char **ppszName, RTVFSOBJTYPE *penmType, PRTVFSOBJ phVfsObj));
+
+ /**
+ * Adds another object into the stream.
+ *
+ * Writable streams only.
+ *
+ * @returns IPRT status code.
+ * @param pvThis The implementation specific directory data.
+ * @param pszPath The path to the object.
+ * @param hVfsObj The object to add.
+ * @param fFlags Reserved for the future, MBZ.
+ * @sa RTVfsFsStrmAdd
+ *
+ * @note Setting this member to NULL is okay for read-only streams.
+ */
+ DECLCALLBACKMEMBER(int, pfnAdd,(void *pvThis, const char *pszPath, RTVFSOBJ hVfsObj, uint32_t fFlags));
+
+ /**
+ * Pushes an byte stream onto the stream (optional).
+ *
+ * Writable streams only.
+ *
+ * This differs from RTVFSFSSTREAMOPS::pfnAdd() in that it will create a regular
+ * file in the output file system stream and provide the actual content bytes
+ * via the returned I/O stream object.
+ *
+ * @returns IPRT status code.
+ * @param pvThis The implementation specific directory data.
+ * @param pszPath The path to the file.
+ * @param cbFile The file size. This can also be set to UINT64_MAX if
+ * the file system stream is backed by a file.
+ * @param paObjInfo Array of zero or more RTFSOBJINFO structures containing
+ * different pieces of information about the file. If any
+ * provided, the first one should be a RTFSOBJATTRADD_UNIX
+ * one, additional can be supplied if wanted. What exactly
+ * is needed depends on the underlying FS stream
+ * implementation.
+ * @param cObjInfo Number of items in the array @a paObjInfo points at.
+ * @param fFlags RTVFSFSSTRM_PUSH_F_XXX.
+ * @param phVfsIos Where to return the I/O stream to feed the file content
+ * to. If the FS stream is backed by a file, the returned
+ * handle can be cast to a file if necessary.
+ */
+ DECLCALLBACKMEMBER(int, pfnPushFile,(void *pvThis, const char *pszPath, uint64_t cbFile,
+ PCRTFSOBJINFO paObjInfo, uint32_t cObjInfo, uint32_t fFlags, PRTVFSIOSTREAM phVfsIos));
+
+ /**
+ * Marks the end of the stream.
+ *
+ * Writable streams only.
+ *
+ * @returns IPRT status code.
+ * @param pvThis The implementation specific directory data.
+ * @sa RTVfsFsStrmEnd
+ *
+ * @note Setting this member to NULL is okay for read-only streams.
+ */
+ DECLCALLBACKMEMBER(int, pfnEnd,(void *pvThis));
+
+ /** Marks the end of the structure (RTVFSFSSTREAMOPS_VERSION). */
+ uintptr_t uEndMarker;
+} RTVFSFSSTREAMOPS;
+/** Pointer to const object attribute setter operations. */
+typedef RTVFSFSSTREAMOPS const *PCRTVFSFSSTREAMOPS;
+
+/** The RTVFSFSSTREAMOPS structure version. */
+#define RTVFSFSSTREAMOPS_VERSION RT_MAKE_U32_FROM_U8(0xff,0x3f,2,0)
+
+
+/**
+ * Creates a new VFS filesystem stream handle.
+ *
+ * @returns IPRT status code
+ * @param pFsStreamOps The filesystem stream operations.
+ * @param cbInstance The size of the instance data.
+ * @param hVfs The VFS handle to associate this filesystem
+ * stream with. NIL_VFS is ok.
+ * @param hLock Handle to a custom lock to be used with the new
+ * object. The reference is consumed. NIL and
+ * special lock handles are fine.
+ * @param fAccess RTFILE_O_READ and/or RTFILE_O_WRITE.
+ * @param phVfsFss Where to return the new handle.
+ * @param ppvInstance Where to return the pointer to the instance data
+ * (size is @a cbInstance).
+ */
+RTDECL(int) RTVfsNewFsStream(PCRTVFSFSSTREAMOPS pFsStreamOps, size_t cbInstance, RTVFS hVfs, RTVFSLOCK hLock, uint32_t fAccess,
+ PRTVFSFSSTREAM phVfsFss, void **ppvInstance);
+
+/**
+ * Gets the private data of an filesystem stream.
+ *
+ * @returns Pointer to the private data. NULL if the handle is invalid in some
+ * way.
+ * @param hVfsFss The FS stream handle.
+ * @param pFsStreamOps The FS stream operations. This servers as a
+ * sort of password.
+ */
+RTDECL(void *) RTVfsFsStreamToPrivate(RTVFSFSSTREAM hVfsFss, PCRTVFSFSSTREAMOPS pFsStreamOps);
+
+
+/**
+ * The directory operations.
+ *
+ * @extends RTVFSOBJOPS
+ * @extends RTVFSOBJSETOPS
+ */
+typedef struct RTVFSDIROPS
+{
+ /** The basic object operation. */
+ RTVFSOBJOPS Obj;
+ /** The structure version (RTVFSDIROPS_VERSION). */
+ uint32_t uVersion;
+ /** Reserved field, MBZ. */
+ uint32_t fReserved;
+ /** The object setter operations. */
+ RTVFSOBJSETOPS ObjSet;
+
+ /**
+ * Generic method for opening any kind of file system object.
+ *
+ * Can also create files and directories. Symbolic links, devices and such
+ * needs to be created using special methods or this would end up being way more
+ * complicated than it already is.
+ *
+ * There are optional specializations available.
+ *
+ * @returns IPRT status code.
+ * @retval VERR_PATH_NOT_FOUND or VERR_FILE_NOT_FOUND if @a pszEntry was not
+ * found.
+ * @retval VERR_IS_A_FILE if @a pszEntry is a file or similar but @a fFlags
+ * indicates that the type of object should not be opened.
+ * @retval VERR_IS_A_DIRECTORY if @a pszEntry is a directory but @a fFlags
+ * indicates that directories should not be opened.
+ * @retval VERR_IS_A_SYMLINK if @a pszEntry is a symbolic link but @a fFlags
+ * indicates that symbolic links should not be opened (or followed).
+ * @retval VERR_IS_A_FIFO if @a pszEntry is a FIFO but @a fFlags indicates that
+ * FIFOs should not be opened.
+ * @retval VERR_IS_A_SOCKET if @a pszEntry is a socket but @a fFlags indicates
+ * that sockets should not be opened.
+ * @retval VERR_IS_A_BLOCK_DEVICE if @a pszEntry is a block device but
+ * @a fFlags indicates that block devices should not be opened, or vice
+ * versa.
+ *
+ * @param pvThis The implementation specific directory data.
+ * @param pszEntry The name of the immediate file to open or create.
+ * @param fOpenFile RTFILE_O_XXX combination.
+ * @param fObjFlags More flags: RTVFSOBJ_F_XXX, RTPATH_F_XXX.
+ * The meaning of RTPATH_F_FOLLOW_LINK differs here, if
+ * @a pszEntry is a symlink it should be opened for
+ * traversal rather than according to @a fOpenFile.
+ * @param phVfsObj Where to return the handle to the opened object.
+ * @sa RTFileOpen, RTDirOpen
+ */
+ DECLCALLBACKMEMBER(int, pfnOpen,(void *pvThis, const char *pszEntry, uint64_t fOpenFile,
+ uint32_t fObjFlags, PRTVFSOBJ phVfsObj));
+
+ /**
+ * Optional method for symbolic link handling in the vfsstddir.cpp.
+ *
+ * This is really just a hack to make symbolic link handling work when working
+ * with directory objects that doesn't have an associated VFS. It also helps
+ * deal with drive letters in symbolic links on Windows and OS/2.
+ *
+ * @returns IPRT status code.
+ * @retval VERR_PATH_IS_RELATIVE if @a pszPath isn't absolute and should be
+ * handled using pfnOpen().
+ *
+ * @param pvThis The implementation specific directory data.
+ * @param pszRoot Path to the alleged root.
+ * @param phVfsDir Where to return the handle to the specified root
+ * directory (or may current dir on a drive letter).
+ */
+ DECLCALLBACKMEMBER(int, pfnFollowAbsoluteSymlink,(void *pvThis, const char *pszRoot, PRTVFSDIR phVfsDir));
+
+ /**
+ * Open or create a file.
+ *
+ * @returns IPRT status code.
+ * @param pvThis The implementation specific directory data.
+ * @param pszFilename The name of the immediate file to open or create.
+ * @param fOpen The open flags (RTFILE_O_XXX).
+ * @param phVfsFile Where to return the handle to the opened file.
+ * @note Optional. RTVFSDIROPS::pfnOpenObj will be used if NULL.
+ * @sa RTFileOpen.
+ */
+ DECLCALLBACKMEMBER(int, pfnOpenFile,(void *pvThis, const char *pszFilename, uint64_t fOpen, PRTVFSFILE phVfsFile));
+
+ /**
+ * Open an existing subdirectory.
+ *
+ * @returns IPRT status code.
+ * @retval VERR_IS_A_SYMLINK if @a pszSubDir is a symbolic link.
+ * @retval VERR_NOT_A_DIRECTORY is okay for symbolic links too.
+ *
+ * @param pvThis The implementation specific directory data.
+ * @param pszSubDir The name of the immediate subdirectory to open.
+ * @param fFlags RTDIR_F_XXX.
+ * @param phVfsDir Where to return the handle to the opened directory.
+ * Optional.
+ * @note Optional. RTVFSDIROPS::pfnOpenObj will be used if NULL.
+ * @sa RTDirOpen.
+ */
+ DECLCALLBACKMEMBER(int, pfnOpenDir,(void *pvThis, const char *pszSubDir, uint32_t fFlags, PRTVFSDIR phVfsDir));
+
+ /**
+ * Creates a new subdirectory.
+ *
+ * @returns IPRT status code.
+ * @param pvThis The implementation specific directory data.
+ * @param pszSubDir The name of the immediate subdirectory to create.
+ * @param fMode The mode mask of the new directory.
+ * @param phVfsDir Where to optionally return the handle to the newly
+ * create directory.
+ * @note Optional. RTVFSDIROPS::pfnOpenObj will be used if NULL.
+ * @sa RTDirCreate.
+ */
+ DECLCALLBACKMEMBER(int, pfnCreateDir,(void *pvThis, const char *pszSubDir, RTFMODE fMode, PRTVFSDIR phVfsDir));
+
+ /**
+ * Opens an existing symbolic link.
+ *
+ * @returns IPRT status code.
+ * @param pvThis The implementation specific directory data.
+ * @param pszSymlink The name of the immediate symbolic link to open.
+ * @param phVfsSymlink Where to optionally return the handle to the
+ * newly create symbolic link.
+ * @note Optional. RTVFSDIROPS::pfnOpenObj will be used if NULL.
+ * @sa RTSymlinkCreate.
+ */
+ DECLCALLBACKMEMBER(int, pfnOpenSymlink,(void *pvThis, const char *pszSymlink, PRTVFSSYMLINK phVfsSymlink));
+
+ /**
+ * Creates a new symbolic link.
+ *
+ * @returns IPRT status code.
+ * @param pvThis The implementation specific directory data.
+ * @param pszSymlink The name of the immediate symbolic link to create.
+ * @param pszTarget The symbolic link target.
+ * @param enmType The symbolic link type.
+ * @param phVfsSymlink Where to optionally return the handle to the
+ * newly create symbolic link.
+ * @sa RTSymlinkCreate.
+ */
+ DECLCALLBACKMEMBER(int, pfnCreateSymlink,(void *pvThis, const char *pszSymlink, const char *pszTarget,
+ RTSYMLINKTYPE enmType, PRTVFSSYMLINK phVfsSymlink));
+
+ /**
+ * Query information about an entry.
+ *
+ * @returns IPRT status code.
+ * @param pvThis The implementation specific directory data.
+ * @param pszEntry The name of the directory entry to remove.
+ * @param pObjInfo Where to return the info on success.
+ * @param enmAddAttr Which set of additional attributes to request.
+ * @note Optional. RTVFSDIROPS::pfnOpenObj and RTVFSOBJOPS::pfnQueryInfo
+ * will be used if NULL.
+ * @sa RTPathQueryInfo, RTVFSOBJOPS::pfnQueryInfo
+ */
+ DECLCALLBACKMEMBER(int, pfnQueryEntryInfo,(void *pvThis, const char *pszEntry,
+ PRTFSOBJINFO pObjInfo, RTFSOBJATTRADD enmAddAttr));
+
+ /**
+ * Removes a directory entry.
+ *
+ * @returns IPRT status code.
+ * @param pvThis The implementation specific directory data.
+ * @param pszEntry The name of the directory entry to remove.
+ * @param fType If non-zero, this restricts the type of the entry to
+ * the object type indicated by the mask
+ * (RTFS_TYPE_XXX).
+ * @sa RTFileRemove, RTDirRemove, RTSymlinkRemove.
+ */
+ DECLCALLBACKMEMBER(int, pfnUnlinkEntry,(void *pvThis, const char *pszEntry, RTFMODE fType));
+
+ /**
+ * Renames a directory entry.
+ *
+ * @returns IPRT status code.
+ * @param pvThis The implementation specific directory data.
+ * @param pszEntry The name of the directory entry to rename.
+ * @param fType If non-zero, this restricts the type of the entry to
+ * the object type indicated by the mask
+ * (RTFS_TYPE_XXX).
+ * @param pszNewName The new entry name.
+ * @sa RTPathRename
+ *
+ * @todo This API is not flexible enough, must be able to rename between
+ * directories within a file system.
+ */
+ DECLCALLBACKMEMBER(int, pfnRenameEntry,(void *pvThis, const char *pszEntry, RTFMODE fType, const char *pszNewName));
+
+ /**
+ * Rewind the directory stream so that the next read returns the first
+ * entry.
+ *
+ * @returns IPRT status code.
+ * @param pvThis The implementation specific directory data.
+ */
+ DECLCALLBACKMEMBER(int, pfnRewindDir,(void *pvThis));
+
+ /**
+ * Rewind the directory stream so that the next read returns the first
+ * entry.
+ *
+ * @returns IPRT status code.
+ * @param pvThis The implementation specific directory data.
+ * @param pDirEntry Output buffer.
+ * @param pcbDirEntry Complicated, see RTDirReadEx.
+ * @param enmAddAttr Which set of additional attributes to request.
+ * @sa RTDirReadEx
+ */
+ DECLCALLBACKMEMBER(int, pfnReadDir,(void *pvThis, PRTDIRENTRYEX pDirEntry, size_t *pcbDirEntry, RTFSOBJATTRADD enmAddAttr));
+
+ /** Marks the end of the structure (RTVFSDIROPS_VERSION). */
+ uintptr_t uEndMarker;
+} RTVFSDIROPS;
+/** Pointer to const directory operations. */
+typedef RTVFSDIROPS const *PCRTVFSDIROPS;
+/** The RTVFSDIROPS structure version. */
+#define RTVFSDIROPS_VERSION RT_MAKE_U32_FROM_U8(0xff,0x4f,1,0)
+
+
+/**
+ * Creates a new VFS directory handle.
+ *
+ * @returns IPRT status code
+ * @param pDirOps The directory operations.
+ * @param cbInstance The size of the instance data.
+ * @param fFlags RTVFSDIR_F_XXX
+ * @param hVfs The VFS handle to associate this directory with.
+ * NIL_VFS is ok.
+ * @param hLock Handle to a custom lock to be used with the new
+ * object. The reference is consumed. NIL and
+ * special lock handles are fine.
+ * @param phVfsDir Where to return the new handle.
+ * @param ppvInstance Where to return the pointer to the instance data
+ * (size is @a cbInstance).
+ */
+RTDECL(int) RTVfsNewDir(PCRTVFSDIROPS pDirOps, size_t cbInstance, uint32_t fFlags, RTVFS hVfs, RTVFSLOCK hLock,
+ PRTVFSDIR phVfsDir, void **ppvInstance);
+
+/** @name RTVFSDIR_F_XXX
+ * @{ */
+/** Don't reference the @a hVfs parameter passed to RTVfsNewDir.
+ * This is a permanent root directory hack. */
+#define RTVFSDIR_F_NO_VFS_REF RT_BIT_32(0)
+/** @} */
+
+/**
+ * Gets the private data of a directory.
+ *
+ * @returns Pointer to the private data. NULL if the handle is invalid in some
+ * way.
+ * @param hVfsDir The directory handle.
+ * @param pDirOps The directory operations. This servers as a
+ * sort of password.
+ */
+RTDECL(void *) RTVfsDirToPrivate(RTVFSDIR hVfsDir, PCRTVFSDIROPS pDirOps);
+
+
+/**
+ * The symbolic link operations.
+ *
+ * @extends RTVFSOBJOPS
+ * @extends RTVFSOBJSETOPS
+ */
+typedef struct RTVFSSYMLINKOPS
+{
+ /** The basic object operation. */
+ RTVFSOBJOPS Obj;
+ /** The structure version (RTVFSSYMLINKOPS_VERSION). */
+ uint32_t uVersion;
+ /** Reserved field, MBZ. */
+ uint32_t fReserved;
+ /** The object setter operations. */
+ RTVFSOBJSETOPS ObjSet;
+
+ /**
+ * Read the symbolic link target.
+ *
+ * @returns IPRT status code.
+ * @param pvThis The implementation specific symbolic link data.
+ * @param pszTarget The target buffer.
+ * @param cbTarget The size of the target buffer.
+ * @sa RTSymlinkRead
+ */
+ DECLCALLBACKMEMBER(int, pfnRead,(void *pvThis, char *pszTarget, size_t cbTarget));
+
+ /** Marks the end of the structure (RTVFSSYMLINKOPS_VERSION). */
+ uintptr_t uEndMarker;
+} RTVFSSYMLINKOPS;
+/** Pointer to const symbolic link operations. */
+typedef RTVFSSYMLINKOPS const *PCRTVFSSYMLINKOPS;
+/** The RTVFSSYMLINKOPS structure version. */
+#define RTVFSSYMLINKOPS_VERSION RT_MAKE_U32_FROM_U8(0xff,0x5f,1,0)
+
+
+/**
+ * Creates a new VFS symlink handle.
+ *
+ * @returns IPRT status code
+ * @param pSymlinkOps The symlink operations.
+ * @param cbInstance The size of the instance data.
+ * @param hVfs The VFS handle to associate this symlink object
+ * with. NIL_VFS is ok.
+ * @param hLock Handle to a custom lock to be used with the new
+ * object. The reference is consumed. NIL and
+ * special lock handles are fine.
+ * @param phVfsSym Where to return the new handle.
+ * @param ppvInstance Where to return the pointer to the instance data
+ * (size is @a cbInstance).
+ */
+RTDECL(int) RTVfsNewSymlink(PCRTVFSSYMLINKOPS pSymlinkOps, size_t cbInstance, RTVFS hVfs, RTVFSLOCK hLock,
+ PRTVFSSYMLINK phVfsSym, void **ppvInstance);
+
+
+/**
+ * Gets the private data of a symbolic link.
+ *
+ * @returns Pointer to the private data. NULL if the handle is invalid in some
+ * way.
+ * @param hVfsSym The symlink handle.
+ * @param pSymlinkOps The symlink operations. This servers as a sort
+ * of password.
+ */
+RTDECL(void *) RTVfsSymlinkToPrivate(RTVFSSYMLINK hVfsSym, PCRTVFSSYMLINKOPS pSymlinkOps);
+
+/**
+ * The basis for all I/O objects (files, pipes, sockets, devices, ++).
+ *
+ * @extends RTVFSOBJOPS
+ */
+typedef struct RTVFSIOSTREAMOPS
+{
+ /** The basic object operation. */
+ RTVFSOBJOPS Obj;
+ /** The structure version (RTVFSIOSTREAMOPS_VERSION). */
+ uint32_t uVersion;
+ /** Feature field. */
+ uint32_t fFeatures;
+
+ /**
+ * Reads from the file/stream.
+ *
+ * @returns IPRT status code. See RTVfsIoStrmRead.
+ * @param pvThis The implementation specific file data.
+ * @param off Where to read at, -1 for the current position.
+ * @param pSgBuf Gather buffer describing the bytes that are to be
+ * written.
+ * @param fBlocking If @c true, the call is blocking, if @c false it
+ * should not block.
+ * @param pcbRead Where return the number of bytes actually read.
+ * This is set it 0 by the caller. If NULL, try read
+ * all and fail if incomplete.
+ * @sa RTVfsIoStrmRead, RTVfsIoStrmSgRead, RTVfsFileRead,
+ * RTVfsFileReadAt, RTFileRead, RTFileReadAt.
+ */
+ DECLCALLBACKMEMBER(int, pfnRead,(void *pvThis, RTFOFF off, PCRTSGBUF pSgBuf, bool fBlocking, size_t *pcbRead));
+
+ /**
+ * Writes to the file/stream.
+ *
+ * @returns IPRT status code.
+ * @param pvThis The implementation specific file data.
+ * @param off Where to start wrinting, -1 for the current
+ * position.
+ * @param pSgBuf Gather buffers describing the bytes that are to be
+ * written.
+ * @param fBlocking If @c true, the call is blocking, if @c false it
+ * should not block.
+ * @param pcbWritten Where to return the number of bytes actually
+ * written. This is set it 0 by the caller. If
+ * NULL, try write it all and fail if incomplete.
+ * @note Optional, failing with VERR_WRITE_PROTECT if NULL.
+ * @sa RTFileWrite, RTFileWriteAt.
+ */
+ DECLCALLBACKMEMBER(int, pfnWrite,(void *pvThis, RTFOFF off, PCRTSGBUF pSgBuf, bool fBlocking, size_t *pcbWritten));
+
+ /**
+ * Flushes any pending data writes to the stream.
+ *
+ * @returns IPRT status code.
+ * @param pvThis The implementation specific file data.
+ * @sa RTFileFlush.
+ */
+ DECLCALLBACKMEMBER(int, pfnFlush,(void *pvThis));
+
+ /**
+ * Poll for events.
+ *
+ * @returns IPRT status code.
+ * @param pvThis The implementation specific file data.
+ * @param fEvents The events to poll for (RTPOLL_EVT_XXX).
+ * @param cMillies How long to wait for event to eventuate.
+ * @param fIntr Whether the wait is interruptible and can return
+ * VERR_INTERRUPTED (@c true) or if this condition
+ * should be hidden from the caller (@c false).
+ * @param pfRetEvents Where to return the event mask.
+ * @note Optional. If NULL, immediately return all requested non-error
+ * events, waiting for errors works like sleep.
+ * @sa RTPollSetAdd, RTPoll, RTPollNoResume.
+ */
+ DECLCALLBACKMEMBER(int, pfnPollOne,(void *pvThis, uint32_t fEvents, RTMSINTERVAL cMillies, bool fIntr,
+ uint32_t *pfRetEvents));
+
+ /**
+ * Tells the current file/stream position.
+ *
+ * @returns IPRT status code.
+ * @param pvThis The implementation specific file data.
+ * @param poffActual Where to return the actual offset.
+ * @sa RTFileTell
+ */
+ DECLCALLBACKMEMBER(int, pfnTell,(void *pvThis, PRTFOFF poffActual));
+
+ /**
+ * Skips @a cb ahead in the stream.
+ *
+ * @returns IPRT status code.
+ * @param pvThis The implementation specific file data.
+ * @param cb The number bytes to skip.
+ * @remarks This is optional and can be NULL.
+ */
+ DECLCALLBACKMEMBER(int, pfnSkip,(void *pvThis, RTFOFF cb));
+
+ /**
+ * Fills the stream with @a cb zeros.
+ *
+ * @returns IPRT status code.
+ * @param pvThis The implementation specific file data.
+ * @param cb The number of zero bytes to insert.
+ * @remarks This is optional and can be NULL.
+ */
+ DECLCALLBACKMEMBER(int, pfnZeroFill,(void *pvThis, RTFOFF cb));
+
+ /** Marks the end of the structure (RTVFSIOSTREAMOPS_VERSION). */
+ uintptr_t uEndMarker;
+} RTVFSIOSTREAMOPS;
+/** Pointer to const I/O stream operations. */
+typedef RTVFSIOSTREAMOPS const *PCRTVFSIOSTREAMOPS;
+
+/** The RTVFSIOSTREAMOPS structure version. */
+#define RTVFSIOSTREAMOPS_VERSION RT_MAKE_U32_FROM_U8(0xff,0x6f,1,0)
+
+/** @name RTVFSIOSTREAMOPS::fFeatures
+ * @{ */
+/** No scatter gather lists, thank you. */
+#define RTVFSIOSTREAMOPS_FEAT_NO_SG RT_BIT_32(0)
+/** Mask of the valid I/O stream feature flags. */
+#define RTVFSIOSTREAMOPS_FEAT_VALID_MASK UINT32_C(0x00000001)
+/** @} */
+
+
+/**
+ * Creates a new VFS I/O stream handle.
+ *
+ * @returns IPRT status code
+ * @param pIoStreamOps The I/O stream operations.
+ * @param cbInstance The size of the instance data.
+ * @param fOpen The open flags. The minimum is the access mask.
+ * @param hVfs The VFS handle to associate this I/O stream
+ * with. NIL_VFS is ok.
+ * @param hLock Handle to a custom lock to be used with the new
+ * object. The reference is consumed. NIL and
+ * special lock handles are fine.
+ * @param phVfsIos Where to return the new handle.
+ * @param ppvInstance Where to return the pointer to the instance data
+ * (size is @a cbInstance).
+ */
+RTDECL(int) RTVfsNewIoStream(PCRTVFSIOSTREAMOPS pIoStreamOps, size_t cbInstance, uint32_t fOpen, RTVFS hVfs, RTVFSLOCK hLock,
+ PRTVFSIOSTREAM phVfsIos, void **ppvInstance);
+
+
+/**
+ * Gets the private data of an I/O stream.
+ *
+ * @returns Pointer to the private data. NULL if the handle is invalid in some
+ * way.
+ * @param hVfsIos The I/O stream handle.
+ * @param pIoStreamOps The I/O stream operations. This servers as a
+ * sort of password.
+ */
+RTDECL(void *) RTVfsIoStreamToPrivate(RTVFSIOSTREAM hVfsIos, PCRTVFSIOSTREAMOPS pIoStreamOps);
+
+
+/**
+ * The file operations.
+ *
+ * @extends RTVFSIOSTREAMOPS
+ * @extends RTVFSOBJSETOPS
+ */
+typedef struct RTVFSFILEOPS
+{
+ /** The I/O stream and basis object operations. */
+ RTVFSIOSTREAMOPS Stream;
+ /** The structure version (RTVFSFILEOPS_VERSION). */
+ uint32_t uVersion;
+ /** Reserved field, MBZ. */
+ uint32_t fReserved;
+ /** The object setter operations. */
+ RTVFSOBJSETOPS ObjSet;
+
+ /**
+ * Changes the current file position.
+ *
+ * @returns IPRT status code.
+ * @param pvThis The implementation specific file data.
+ * @param offSeek The offset to seek.
+ * @param uMethod The seek method, i.e. what the seek is relative to.
+ * @param poffActual Where to return the actual offset.
+ * @sa RTFileSeek
+ */
+ DECLCALLBACKMEMBER(int, pfnSeek,(void *pvThis, RTFOFF offSeek, unsigned uMethod, PRTFOFF poffActual));
+
+ /**
+ * Get the current file size.
+ *
+ * @returns IPRT status code.
+ * @param pvThis The implementation specific file data.
+ * @param pcbFile Where to store the current file size.
+ * @sa RTFileQuerySize
+ */
+ DECLCALLBACKMEMBER(int, pfnQuerySize,(void *pvThis, uint64_t *pcbFile));
+
+ /**
+ * Change the file size.
+ *
+ * @returns IPRT status code.
+ * @retval VERR_ACCESS_DENIED if handle isn't writable.
+ * @retval VERR_WRITE_PROTECT if read-only file system.
+ * @retval VERR_FILE_TOO_BIG if cbSize is larger than what the file system can
+ * theoretically deal with.
+ * @retval VERR_DISK_FULL if the file system if full.
+ * @retval VERR_NOT_SUPPORTED if fFlags indicates some operation that's not
+ * supported by the file system / host operating system.
+ *
+ * @param pvThis The implementation specific file data.
+ * @param pcbFile Where to store the current file size.
+ * @param fFlags RTVFSFILE_SET_SIZE_F_XXX.
+ * @note Optional. If NULL, VERR_WRITE_PROTECT will be returned.
+ * @sa RTFileSetSize, RTFileSetAllocationSize
+ */
+ DECLCALLBACKMEMBER(int, pfnSetSize,(void *pvThis, uint64_t cbFile, uint32_t fFlags));
+
+ /**
+ * Determine the maximum file size.
+ *
+ * This won't take amount of freespace into account, just the limitations of the
+ * underlying file system / host operating system.
+ *
+ * @returns IPRT status code.
+ * @param pvThis The implementation specific file data.
+ * @param pcbMax Where to return the max file size.
+ * @note Optional. If NULL, VERR_NOT_IMPLEMENTED will be returned.
+ * @sa RTFileQueryMaxSizeEx
+ */
+ DECLCALLBACKMEMBER(int, pfnQueryMaxSize,(void *pvThis, uint64_t *pcbMax));
+
+ /** @todo There will be more methods here. */
+
+ /** Marks the end of the structure (RTVFSFILEOPS_VERSION). */
+ uintptr_t uEndMarker;
+} RTVFSFILEOPS;
+/** Pointer to const file operations. */
+typedef RTVFSFILEOPS const *PCRTVFSFILEOPS;
+
+/** The RTVFSFILEOPS structure version. */
+#define RTVFSFILEOPS_VERSION RT_MAKE_U32_FROM_U8(0xff,0x7f,2,0)
+
+/**
+ * Creates a new VFS file handle.
+ *
+ * @returns IPRT status code
+ * @param pFileOps The file operations.
+ * @param cbInstance The size of the instance data.
+ * @param fOpen The open flags. The minimum is the access mask.
+ * @param hVfs The VFS handle to associate this file with.
+ * NIL_VFS is ok.
+ * @param hLock Handle to a custom lock to be used with the new
+ * object. The reference is consumed. NIL and
+ * special lock handles are fine.
+ * @param phVfsFile Where to return the new handle.
+ * @param ppvInstance Where to return the pointer to the instance data
+ * (size is @a cbInstance).
+ */
+RTDECL(int) RTVfsNewFile(PCRTVFSFILEOPS pFileOps, size_t cbInstance, uint32_t fOpen, RTVFS hVfs, RTVFSLOCK hLock,
+ PRTVFSFILE phVfsFile, void **ppvInstance);
+
+
+/** @defgroup grp_rt_vfs_ll_util VFS Utility APIs
+ * @{ */
+
+/**
+ * Parsed path.
+ */
+typedef struct RTVFSPARSEDPATH
+{
+ /** The length of the path in szCopy. */
+ uint16_t cch;
+ /** The number of path components. */
+ uint16_t cComponents;
+ /** Set if the path ends with slash, indicating that it's a directory
+ * reference and not a file reference. The slash has been removed from
+ * the copy. */
+ bool fDirSlash;
+ /** Set if absolute. */
+ bool fAbsolute;
+ /** The offset where each path component starts, i.e. the char after the
+ * slash. The array has cComponents + 1 entries, where the final one is
+ * cch + 1 so that one can always terminate the current component by
+ * szPath[aoffComponent[i] - 1] = '\0'. */
+ uint16_t aoffComponents[RTPATH_MAX / 2 + 1];
+ /** A normalized copy of the path.
+ * Reserve some extra space so we can be more relaxed about overflow
+ * checks and terminator paddings, especially when recursing. */
+ char szPath[RTPATH_MAX];
+} RTVFSPARSEDPATH;
+/** Pointer to a parsed path. */
+typedef RTVFSPARSEDPATH *PRTVFSPARSEDPATH;
+
+/** The max accepted path length.
+ * This must be a few chars shorter than RTVFSPARSEDPATH::szPath because we
+ * use two terminators and wish be a little bit lazy with checking. */
+#define RTVFSPARSEDPATH_MAX (RTPATH_MAX - 4)
+
+/**
+ * Appends @a pszPath (relative) to the already parsed path @a pPath.
+ *
+ * @retval VINF_SUCCESS
+ * @retval VERR_FILENAME_TOO_LONG
+ * @retval VERR_INTERNAL_ERROR_4
+ * @param pPath The parsed path to append @a pszPath onto.
+ * This is both input and output.
+ * @param pszPath The path to append. This must be relative.
+ * @param piRestartComp The component to restart parsing at. This is
+ * input/output. The input does not have to be
+ * within the valid range. Optional.
+ */
+RTDECL(int) RTVfsParsePathAppend(PRTVFSPARSEDPATH pPath, const char *pszPath, uint16_t *piRestartComp);
+
+/**
+ * Parses a path.
+ *
+ * @retval VINF_SUCCESS
+ * @retval VERR_FILENAME_TOO_LONG
+ * @param pPath Where to store the parsed path.
+ * @param pszPath The path to parse. Absolute or relative to @a
+ * pszCwd.
+ * @param pszCwd The current working directory. Must be
+ * absolute.
+ */
+RTDECL(int) RTVfsParsePath(PRTVFSPARSEDPATH pPath, const char *pszPath, const char *pszCwd);
+
+/**
+ * Same as RTVfsParsePath except that it allocates a temporary buffer.
+ *
+ * @retval VINF_SUCCESS
+ * @retval VERR_NO_TMP_MEMORY
+ * @retval VERR_FILENAME_TOO_LONG
+ * @param pszPath The path to parse. Absolute or relative to @a
+ * pszCwd.
+ * @param pszCwd The current working directory. Must be
+ * absolute.
+ * @param ppPath Where to store the pointer to the allocated
+ * buffer containing the parsed path. This must
+ * be freed by calling RTVfsParsePathFree. NULL
+ * will be stored on failured.
+ */
+RTDECL(int) RTVfsParsePathA(const char *pszPath, const char *pszCwd, PRTVFSPARSEDPATH *ppPath);
+
+/**
+ * Frees a buffer returned by RTVfsParsePathA.
+ *
+ * @param pPath The parsed path buffer to free. NULL is fine.
+ */
+RTDECL(void) RTVfsParsePathFree(PRTVFSPARSEDPATH pPath);
+
+/**
+ * Dummy implementation of RTVFSIOSTREAMOPS::pfnPollOne.
+ *
+ * This handles the case where there is no chance any events my be raised and
+ * all that is required is to wait according to the parameters.
+ *
+ * @returns IPRT status code.
+ * @param fEvents The events to poll for (RTPOLL_EVT_XXX).
+ * @param cMillies How long to wait for event to eventuate.
+ * @param fIntr Whether the wait is interruptible and can return
+ * VERR_INTERRUPTED (@c true) or if this condition
+ * should be hidden from the caller (@c false).
+ * @param pfRetEvents Where to return the event mask.
+ * @sa RTVFSIOSTREAMOPS::pfnPollOne, RTPollSetAdd, RTPoll, RTPollNoResume.
+ */
+RTDECL(int) RTVfsUtilDummyPollOne(uint32_t fEvents, RTMSINTERVAL cMillies, bool fIntr, uint32_t *pfRetEvents);
+
+/** @} */
+
+
+/** @defgroup grp_rt_vfs_lowlevel_chain VFS Chains (Low Level)
+ * @ref grp_rt_vfs_chain
+ * @{
+ */
+
+/** Pointer to a VFS chain element registration record. */
+typedef struct RTVFSCHAINELEMENTREG *PRTVFSCHAINELEMENTREG;
+/** Pointer to a const VFS chain element registration record. */
+typedef struct RTVFSCHAINELEMENTREG const *PCRTVFSCHAINELEMENTREG;
+
+/**
+ * VFS chain element argument.
+ */
+typedef struct RTVFSCHAINELEMENTARG
+{
+ /** The string argument value. */
+ char *psz;
+ /** The specification offset of this argument. */
+ uint16_t offSpec;
+ /** Provider specific value. */
+ uint64_t uProvider;
+} RTVFSCHAINELEMENTARG;
+/** Pointer to a VFS chain element argument. */
+typedef RTVFSCHAINELEMENTARG *PRTVFSCHAINELEMENTARG;
+
+
+/**
+ * VFS chain element specification.
+ */
+typedef struct RTVFSCHAINELEMSPEC
+{
+ /** The provider name.
+ * This can be NULL if this is the final component and it's just a path. */
+ char *pszProvider;
+ /** The input type, RTVFSOBJTYPE_INVALID if first. */
+ RTVFSOBJTYPE enmTypeIn;
+ /** The element type.
+ * RTVFSOBJTYPE_END if this is the final component and it's just a path. */
+ RTVFSOBJTYPE enmType;
+ /** The input spec offset of this element. */
+ uint16_t offSpec;
+ /** The length of the input spec. */
+ uint16_t cchSpec;
+ /** The number of arguments. */
+ uint32_t cArgs;
+ /** Arguments. */
+ PRTVFSCHAINELEMENTARG paArgs;
+
+ /** The provider. */
+ PCRTVFSCHAINELEMENTREG pProvider;
+ /** Provider specific value. */
+ uint64_t uProvider;
+ /** The object (with reference). */
+ RTVFSOBJ hVfsObj;
+} RTVFSCHAINELEMSPEC;
+/** Pointer to a chain element specification. */
+typedef RTVFSCHAINELEMSPEC *PRTVFSCHAINELEMSPEC;
+/** Pointer to a const chain element specification. */
+typedef RTVFSCHAINELEMSPEC const *PCRTVFSCHAINELEMSPEC;
+
+
+/**
+ * Parsed VFS chain specification.
+ */
+typedef struct RTVFSCHAINSPEC
+{
+ /** Open directory flags (RTFILE_O_XXX). */
+ uint64_t fOpenFile;
+ /** To be defined. */
+ uint32_t fOpenDir;
+ /** The type desired by the caller. */
+ RTVFSOBJTYPE enmDesiredType;
+ /** The number of elements. */
+ uint32_t cElements;
+ /** The elements. */
+ PRTVFSCHAINELEMSPEC paElements;
+} RTVFSCHAINSPEC;
+/** Pointer to a parsed VFS chain specification. */
+typedef RTVFSCHAINSPEC *PRTVFSCHAINSPEC;
+/** Pointer to a const, parsed VFS chain specification. */
+typedef RTVFSCHAINSPEC const *PCRTVFSCHAINSPEC;
+
+
+/**
+ * A chain element provider registration record.
+ */
+typedef struct RTVFSCHAINELEMENTREG
+{
+ /** The version (RTVFSCHAINELEMENTREG_VERSION). */
+ uint32_t uVersion;
+ /** Reserved, MBZ. */
+ uint32_t fReserved;
+ /** The provider name (unique). */
+ const char *pszName;
+ /** For chaining the providers. */
+ RTLISTNODE ListEntry;
+ /** Help text. */
+ const char *pszHelp;
+
+ /**
+ * Checks the element specification.
+ *
+ * This is allowed to parse arguments and use pSpec->uProvider and
+ * pElement->paArgs[].uProvider to store information that pfnInstantiate and
+ * pfnCanReuseElement may use later on, thus avoiding duplicating work/code.
+ *
+ * @returns IPRT status code.
+ * @param pProviderReg Pointer to the element provider registration.
+ * @param pSpec The chain specification.
+ * @param pElement The chain element specification to validate.
+ * @param poffError Where to return error offset on failure. This is
+ * set to the pElement->offSpec on input, so it only
+ * needs to be adjusted if an argument is at fault.
+ * @param pErrInfo Where to return additional error information, if
+ * available. Optional.
+ */
+ DECLCALLBACKMEMBER(int, pfnValidate,(PCRTVFSCHAINELEMENTREG pProviderReg, PRTVFSCHAINSPEC pSpec,
+ PRTVFSCHAINELEMSPEC pElement, uint32_t *poffError, PRTERRINFO pErrInfo));
+
+ /**
+ * Create a VFS object according to the element specification.
+ *
+ * @returns IPRT status code.
+ * @param pProviderReg Pointer to the element provider registration.
+ * @param pSpec The chain specification.
+ * @param pElement The chain element specification to instantiate.
+ * @param hPrevVfsObj Handle to the previous VFS object, NIL_RTVFSOBJ if
+ * first.
+ * @param phVfsObj Where to return the VFS object handle.
+ * @param poffError Where to return error offset on failure. This is
+ * set to the pElement->offSpec on input, so it only
+ * needs to be adjusted if an argument is at fault.
+ * @param pErrInfo Where to return additional error information, if
+ * available. Optional.
+ */
+ DECLCALLBACKMEMBER(int, pfnInstantiate,(PCRTVFSCHAINELEMENTREG pProviderReg, PCRTVFSCHAINSPEC pSpec,
+ PCRTVFSCHAINELEMSPEC pElement, RTVFSOBJ hPrevVfsObj,
+ PRTVFSOBJ phVfsObj, uint32_t *poffError, PRTERRINFO pErrInfo));
+
+ /**
+ * Determins whether the element can be reused.
+ *
+ * This is for handling situations accessing the same file system twice, like
+ * for both the source and destiation of a copy operation. This allows not only
+ * sharing resources and avoid doing things twice, but also helps avoid file
+ * sharing violations and inconsistencies araising from the image being updated
+ * and read independently.
+ *
+ * @returns true if the element from @a pReuseSpec an be reused, false if not.
+ * @param pProviderReg Pointer to the element provider registration.
+ * @param pSpec The chain specification.
+ * @param pElement The chain element specification.
+ * @param pReuseSpec The chain specification of the existing chain.
+ * @param pReuseElement The chain element specification of the existing
+ * element that is being considered for reuse.
+ */
+ DECLCALLBACKMEMBER(bool, pfnCanReuseElement,(PCRTVFSCHAINELEMENTREG pProviderReg,
+ PCRTVFSCHAINSPEC pSpec, PCRTVFSCHAINELEMSPEC pElement,
+ PCRTVFSCHAINSPEC pReuseSpec, PCRTVFSCHAINELEMSPEC pReuseElement));
+
+ /** End marker (RTVFSCHAINELEMENTREG_VERSION). */
+ uintptr_t uEndMarker;
+} RTVFSCHAINELEMENTREG;
+
+/** The VFS chain element registration record version number. */
+#define RTVFSCHAINELEMENTREG_VERSION RT_MAKE_U32_FROM_U8(0xff, 0x7f, 1, 0)
+
+
+/**
+ * Parses the specification.
+ *
+ * @returns IPRT status code.
+ * @param pszSpec The specification string to parse.
+ * @param fFlags Flags, see RTVFSCHAIN_PF_XXX.
+ * @param enmDesiredType The object type the caller wants to interface with.
+ * @param ppSpec Where to return the pointer to the parsed
+ * specification. This must be freed by calling
+ * RTVfsChainSpecFree. Will always be set (unless
+ * invalid parameters.)
+ * @param poffError Where to return the offset into the input
+ * specification of what's causing trouble. Always
+ * set, unless this argument causes an invalid pointer
+ * error.
+ */
+RTDECL(int) RTVfsChainSpecParse(const char *pszSpec, uint32_t fFlags, RTVFSOBJTYPE enmDesiredType,
+ PRTVFSCHAINSPEC *ppSpec, uint32_t *poffError);
+
+/** @name RTVfsChainSpecParse
+ * @{ */
+/** Mask of valid flags. */
+#define RTVFSCHAIN_PF_VALID_MASK UINT32_C(0x00000000)
+/** @} */
+
+/**
+ * Checks and setups the chain.
+ *
+ * @returns IPRT status code.
+ * @param pSpec The parsed specification.
+ * @param pReuseSpec Spec to reuse if applicable. Optional.
+ * @param phVfsObj Where to return the VFS object.
+ * @param ppszFinalPath Where to return the pointer to the final path if
+ * applicable. The caller needs to check whether this
+ * is NULL or a path, in the former case nothing more
+ * needs doing, whereas in the latter the caller must
+ * perform the desired operation(s) on *phVfsObj using
+ * the final path.
+ * @param poffError Where to return the offset into the input
+ * specification of what's causing trouble. Always
+ * set, unless this argument causes an invalid pointer
+ * error.
+ * @param pErrInfo Where to return additional error information, if
+ * available. Optional.
+ */
+RTDECL(int) RTVfsChainSpecCheckAndSetup(PRTVFSCHAINSPEC pSpec, PCRTVFSCHAINSPEC pReuseSpec,
+ PRTVFSOBJ phVfsObj, const char **ppszFinalPath, uint32_t *poffError, PRTERRINFO pErrInfo);
+
+/**
+ * Frees a parsed chain specification.
+ *
+ * @param pSpec What RTVfsChainSpecParse returned. NULL is
+ * quietly ignored.
+ */
+RTDECL(void) RTVfsChainSpecFree(PRTVFSCHAINSPEC pSpec);
+
+/**
+ * Registers a chain element provider.
+ *
+ * @returns IPRT status code
+ * @param pRegRec The registration record.
+ * @param fFromCtor Indicates where we're called from.
+ */
+RTDECL(int) RTVfsChainElementRegisterProvider(PRTVFSCHAINELEMENTREG pRegRec, bool fFromCtor);
+
+/**
+ * Deregisters a chain element provider.
+ *
+ * @returns IPRT status code
+ * @param pRegRec The registration record.
+ * @param fFromDtor Indicates where we're called from.
+ */
+RTDECL(int) RTVfsChainElementDeregisterProvider(PRTVFSCHAINELEMENTREG pRegRec, bool fFromDtor);
+
+
+/** @def RTVFSCHAIN_AUTO_REGISTER_ELEMENT_PROVIDER
+ * Automatically registers a chain element provider using a global constructor
+ * and destructor hack.
+ *
+ * @param pRegRec Pointer to the registration record.
+ * @param name Some unique variable name prefix.
+ */
+
+#ifdef __cplusplus
+/**
+ * Class used for registering a VFS chain element provider.
+ */
+class RTVfsChainElementAutoRegisterHack
+{
+private:
+ /** The registration record, NULL if registration failed. */
+ PRTVFSCHAINELEMENTREG m_pRegRec;
+
+public:
+ RTVfsChainElementAutoRegisterHack(PRTVFSCHAINELEMENTREG a_pRegRec)
+ : m_pRegRec(a_pRegRec)
+ {
+ int rc = RTVfsChainElementRegisterProvider(m_pRegRec, true);
+ if (RT_FAILURE(rc))
+ m_pRegRec = NULL;
+ }
+
+ ~RTVfsChainElementAutoRegisterHack()
+ {
+ RTVfsChainElementDeregisterProvider(m_pRegRec, true);
+ m_pRegRec = NULL;
+ }
+};
+
+# define RTVFSCHAIN_AUTO_REGISTER_ELEMENT_PROVIDER(pRegRec, name) \
+ static RTVfsChainElementAutoRegisterHack name ## AutoRegistrationHack(pRegRec)
+
+#else
+# define RTVFSCHAIN_AUTO_REGISTER_ELEMENT_PROVIDER(pRegRec, name) \
+ extern void *name ## AutoRegistrationHack = \
+ &Sorry_but_RTVFSCHAIN_AUTO_REGISTER_ELEMENT_PROVIDER_does_not_work_in_c_source_files
+#endif
+
+
+/**
+ * Common worker for the 'stdfile' and 'open' providers for implementing
+ * RTVFSCHAINELEMENTREG::pfnValidate.
+ *
+ * Stores the RTFILE_O_XXX flags in pSpec->uProvider.
+ *
+ * @returns IPRT status code.
+ * @param pSpec The chain specification.
+ * @param pElement The chain element specification to validate.
+ * @param poffError Where to return error offset on failure. This is set to
+ * the pElement->offSpec on input, so it only needs to be
+ * adjusted if an argument is at fault.
+ * @param pErrInfo Where to return additional error information, if
+ * available. Optional.
+ */
+RTDECL(int) RTVfsChainValidateOpenFileOrIoStream(PRTVFSCHAINSPEC pSpec, PRTVFSCHAINELEMSPEC pElement,
+ uint32_t *poffError, PRTERRINFO pErrInfo);
+
+
+/** @} */
+
+
+/** @} */
+
+RT_C_DECLS_END
+
+#endif /* !IPRT_INCLUDED_vfslowlevel_h */
+