vfslowlevel.h revision 54d2d2606d7c83a456819cd038a73e0f9a600ca4
/** @file
* IPRT - Virtual Filesystem.
*/
/*
* Copyright (C) 2010 Oracle Corporation
*
* This file is part of VirtualBox Open Source Edition (OSE), as
* available from http://www.virtualbox.org. This file is free software;
* General Public License (GPL) as published by the Free Software
* Foundation, in version 2 as it comes in the "COPYING" file of the
* VirtualBox OSE distribution. VirtualBox OSE is distributed in the
* hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
*
* The contents of this file may alternatively be used under the terms
* of the Common Development and Distribution License Version 1.0
* (CDDL) only, as it comes in the "COPYING.CDDL" file of the
* VirtualBox OSE 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.
*/
#ifndef ___iprt_vfslowlevel_h
#define ___iprt_vfslowlevel_h
/** @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. */
/** Read write semaphore. */
/** Fast mutex semaphore (critical section in ring-3). */
/** Full fledged mutex semaphore. */
/** The end of valid lock types. */
/** The customary 32-bit type hack. */
RTVFSLOCKTYPE_32BIT_HACK = 0x7fffffff
/** VFS lock handle. */
typedef struct RTVFSLOCKINTERNAL *RTVFSLOCK;
/** Pointer to a VFS lock handle. */
typedef RTVFSLOCK *PRTVFSLOCK;
/** Nil VFS lock handle. */
/** Special handle value for creating a new fast mutex semaphore based lock. */
/** Special handle value for creating a new mutex semaphore based lock. */
/**
* Retains a reference to the VFS lock handle.
*
* @returns New reference count on success, UINT32_MAX on failure.
* @param hLock The VFS lock handle.
*/
/**
* 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.
*/
/**
* Gets the lock type.
*
* @returns The lock type on success, RTVFSLOCKTYPE_INVALID if the handle is
* not valid.
* @param hLock The lock handle.
*/
/**
* Acquire a read lock.
*
* @param hLock The lock handle, can be NIL.
*/
{
if (hLock != NIL_RTVFSLOCK)
}
/**
* Release a read lock.
*
* @param hLock The lock handle, can be NIL.
*/
{
if (hLock != NIL_RTVFSLOCK)
}
/**
* Acquire a write lock.
*
* @param hLock The lock handle, can be NIL.
*/
{
if (hLock != NIL_RTVFSLOCK)
}
/**
* Release a write lock.
*
* @param hLock The lock handle, can be NIL.
*/
{
if (hLock != NIL_RTVFSLOCK)
}
/** @} */
/**
* The VFS operations.
*/
typedef struct RTVFSOPS
{
/** The structure version (RTVFSOPS_VERSION). */
/** The virtual file system feature mask. */
/** The name of the operations. */
const char *pszName;
/**
* Destructor.
*
* @param pvThis The implementation specific data.
*/
/**
* 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.
*/
/**
* Checks whether a given range in the underlying medium
* is in use by the virtual filesystem.
*
* @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.
*/
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
/** Marks the end of the structure (RTVFSOPS_VERSION). */
} RTVFSOPS;
/** Pointer to constant VFS operations. */
typedef RTVFSOPS const *PCRTVFSOPS;
/** The RTVFSOPS structure version. */
/** @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 pVfs Ops 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).
*/
/**
* The basis for all virtual file system objects except RTVFS.
*/
typedef struct RTVFSOBJOPS
{
/** The structure version (RTVFSOBJOPS_VERSION). */
/** The object type for type introspection. */
/** The name of the operations. */
const char *pszName;
/**
* Close the object.
*
* @returns IPRT status code.
* @param pvThis The implementation specific file data.
*/
/**
* Get information about the file.
*
* @returns IPRT status code. See RTVfsObjQueryInfo.
* @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);
/** Marks the end of the structure (RTVFSOBJOPS_VERSION). */
} RTVFSOBJOPS;
/** Pointer to constant VFS object operations. */
typedef RTVFSOBJOPS const *PCRTVFSOBJOPS;
/** The RTVFSOBJOPS structure version. */
/**
* 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 phVfsFss Where to return the new handle.
* @param ppvInstance Where to return the pointer to the instance data
* (size is @a cbInstance).
*/
/**
* Additional operations for setting object attributes.
*/
typedef struct RTVFSOBJSETOPS
{
/** The structure version (RTVFSOBJSETOPS_VERSION). */
/** The offset to the RTVFSOBJOPS structure. */
/**
* 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.
* @sa RTFileSetMode
*/
/**
* 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.
* @sa RTFileSetTimes
*/
DECLCALLBACKMEMBER(int, pfnSetTimes)(void *pvThis, PCRTTIMESPEC pAccessTime, PCRTTIMESPEC pModificationTime,
/**
* 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.
* @sa RTFileSetOwner
*/
/** Marks the end of the structure (RTVFSOBJSETOPS_VERSION). */
/** Pointer to const object attribute setter operations. */
typedef RTVFSOBJSETOPS const *PCRTVFSOBJSETOPS;
/** The RTVFSOBJSETOPS structure version. */
/**
* The filesystem stream operations.
*
* @extends RTVFSOBJOPS
*/
typedef struct RTVFSFSSTREAMOPS
{
/** The basic object operation. */
/** The structure version (RTVFSFSSTREAMOPS_VERSION). */
/** Reserved field, MBZ. */
/**
* Gets the next object in the stream.
*
* @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 hVfsObj Where to return the object handle (referenced).
* This must be cast to the desired type before use.
* @sa RTVfsFsStrmNext
*/
DECLCALLBACKMEMBER(int, pfnNext)(void *pvThis, char **ppszName, RTVFSOBJTYPE *penmType, PRTVFSOBJ phVfsObj);
/** Marks the end of the structure (RTVFSFSSTREAMOPS_VERSION). */
/** Pointer to const object attribute setter operations. */
typedef RTVFSFSSTREAMOPS const *PCRTVFSFSSTREAMOPS;
/** The RTVFSFSSTREAMOPS structure version. */
/**
* 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 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,
/**
* The directory operations.
*
* @extends RTVFSOBJOPS
* @extends RTVFSOBJSETOPS
*/
typedef struct RTVFSDIROPS
{
/** The basic object operation. */
/** The structure version (RTVFSDIROPS_VERSION). */
/** Reserved field, MBZ. */
/** The object setter operations. */
/**
* Opens a directory entry for traversal purposes.
*
* Method which sole purpose is helping the path traversal. Only one of
* the three output variables will be set, the others will left untouched
* (caller sets them to NIL).
*
* @returns IPRT status code.
* @retval VERR_PATH_NOT_FOUND if @a pszEntry was not found.
* @param pvThis The implementation specific directory data.
* @param pszEntry The name of the directory entry to remove.
* @param phVfsDir If not NULL and it is a directory, open it and
* return the handle here.
* @param phVfsSymlink If not NULL and it is a symbolic link, open it
* and return the handle here.
* @param phVfsMounted If not NULL and it is a mounted VFS directory,
* reference it and return the handle here.
* @todo Should com dir, symlinks and mount points using some common
* ancestor "class".
*/
/**
* 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 thandle to the opened file.
* @sa RTFileOpen.
*/
DECLCALLBACKMEMBER(int, pfnOpenFile)(void *pvThis, const char *pszFilename, uint32_t fOpen, PRTVFSFILE phVfsFile);
/**
* Open an existing subdirectory.
*
* @returns IPRT status code.
* @param pvThis The implementation specific directory data.
* @param pszSubDir The name of the immediate subdirectory to open.
* @param phVfsDir Where to return the handle to the opened directory.
* @sa RTDirOpen.
*/
/**
* 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.
* @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.
* @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,
/**
* 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, PRTVFSDIR phVfsDir);
/**
* Rewind the directory stream so that the next read returns the first
* entry.
*
* @returns IPRT status code.
* @param pvThis The implementation specific directory data.
*/
/**
* 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). */
} RTVFSDIROPS;
/** Pointer to const directory operations. */
typedef RTVFSDIROPS const *PCRTVFSDIROPS;
/** The RTVFSDIROPS structure version. */
/**
* The symbolic link operations.
*
* @extends RTVFSOBJOPS
* @extends RTVFSOBJSETOPS
*/
typedef struct RTVFSSYMLINKOPS
{
/** The basic object operation. */
/** The structure version (RTVFSSYMLINKOPS_VERSION). */
/** Reserved field, MBZ. */
/** The object setter operations. */
/**
* 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
*/
/** Marks the end of the structure (RTVFSSYMLINKOPS_VERSION). */
/** Pointer to const symbolic link operations. */
typedef RTVFSSYMLINKOPS const *PCRTVFSSYMLINKOPS;
/** The RTVFSSYMLINKOPS structure version. */
/**
* 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,
/**
* The basis for all I/O objects (files, pipes, sockets, devices, ++).
*
* @extends RTVFSOBJOPS
*/
typedef struct RTVFSIOSTREAMOPS
{
/** The basic object operation. */
/** The structure version (RTVFSIOSTREAMOPS_VERSION). */
/** Feature field. */
/**
*
* @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);
/**
*
* @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.
* @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.
*/
/**
* 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.
* @sa RTPollSetAdd, RTPoll, RTPollNoResume.
*/
DECLCALLBACKMEMBER(int, pfnPollOne)(void *pvThis, uint32_t fEvents, RTMSINTERVAL cMillies, bool fIntr,
/**
*
* @returns IPRT status code.
* @param pvThis The implementation specific file data.
* @param poffActual Where to return the actual offset.
* @sa RTFileTell
*/
/**
* 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.
*/
/**
* 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.
*/
/** Marks the end of the structure (RTVFSIOSTREAMOPS_VERSION). */
/** Pointer to const I/O stream operations. */
typedef RTVFSIOSTREAMOPS const *PCRTVFSIOSTREAMOPS;
/** The RTVFSIOSTREAMOPS structure version. */
/** @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. */
/** @} */
/**
* 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,
/**
* 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.
*/
/**
* The file operations.
*
* @extends RTVFSIOSTREAMOPS
* @extends RTVFSOBJSETOPS
*/
typedef struct RTVFSFILEOPS
{
/** The I/O stream and basis object operations. */
/** The structure version (RTVFSFILEOPS_VERSION). */
/** Reserved field, MBZ. */
/** The object setter operations. */
/**
* 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);
/**
*
* @returns IPRT status code.
* @param pvThis The implementation specific file data.
* @param pcbFile Where to store the current file size.
* @sa RTFileGetSize
*/
/** @todo There will be more methods here. */
/** Marks the end of the structure (RTVFSFILEOPS_VERSION). */
} RTVFSFILEOPS;
/** Pointer to const file operations. */
typedef RTVFSFILEOPS const *PCRTVFSFILEOPS;
/** The RTVFSFILEOPS structure version. */
/**
* 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,
/** @defgroup grp_rt_vfs_ll_util VFS Utility APIs
* @{ */
/**
* Parsed path.
*/
typedef struct RTVFSPARSEDPATH
{
/** The length of the path in szCopy. */
/** The number of path components. */
/** 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;
/** 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'. */
/** 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];
/** 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. */
/**
* 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
* 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.
*/
/**
* 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.
*/
/**
* Frees a buffer returned by RTVfsParsePathA.
*
* @param pPath The parsed path buffer to free. NULL is fine.
*/
/**
* 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 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.
* @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
* @ref grp_rt_vfs_chain
* @{
*/
/**
* Chain element input actions.
*/
typedef enum RTVFSCHAINACTION
{
/** Invalid action. */
/** No action (start of the chain). */
/** Passive filtering (expressed by pipe symbol). */
/** Push filtering (expressed by redirection-out symbol). */
/** The end of the valid actions. */
/** Make sure it's a 32-bit type. */
RTVFSCHAINACTION_32BIT_HACK = 0x7fffffff
/**
* VFS chain element specification.
*/
typedef struct RTVFSCHAINELEMSPEC
{
/** The provider name. */
char *pszProvider;
/** The input type. */
/** The output type. */
/** The action to take (or not). */
/** The number of arguments. */
/** Arguments. */
char **papszArgs;
/** 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
{
/** The action element, UINT32_MAX if none.
* Currently we only support one action element (RTVFSCHAINACTION_PASSIVE
* is not considered). */
/** The number of elements. */
/** The elements. */
/** 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). */
/** Reserved, MBZ. */
/** The provider name (unique). */
const char *pszName;
/** For chaining the providers. */
/**
* Create a VFS from the given chain element specficiation.
*
* @returns IPRT status code.
* @param pSpec The chain element specification.
* @param phVfs Where to returned the VFS handle.
*/
/**
* Open a directory from the given chain element specficiation.
*
* @returns IPRT status code.
* @param pSpec The chain element specification.
* @param phVfsDir Where to returned the directory handle.
*/
/**
* Open a file from the given chain element specficiation.
*
* @returns IPRT status code.
* @param pSpec The chain element specification.
* @param fOpen The open flag. Can be zero and the
* specification may modify it.
* @param phVfsFile Where to returned the file handle.
*/
DECLCALLBACKMEMBER(int, pfnOpenFile)( PCRTVFSCHAINELEMSPEC pSpec, uint32_t fOpen, PRTVFSFILE phVfsFile);
/**
* Open a symlink from the given chain element specficiation.
*
* @returns IPRT status code.
* @param pSpec The chain element specification.
* @param phVfsSym Where to returned the symlink handle.
*/
/**
* Open a I/O stream from the given chain element specficiation.
*
* @returns IPRT status code.
* @param pSpec The chain element specification.
* @param fOpen The open flag. Can be zero and the
* specification may modify it.
* @param phVfsIos Where to returned the I/O stream handle.
*/
DECLCALLBACKMEMBER(int, pfnOpenIoStream)(PCRTVFSCHAINELEMSPEC pSpec, uint32_t fOpen, PRTVFSIOSTREAM phVfsIos);
/**
* Open a filesystem stream from the given chain element specficiation.
*
* @returns IPRT status code.
* @param pSpec The chain element specification.
* @param phVfsFss Where to returned the filesystem stream handle.
*/
/** End marker (RTVFSCHAINELEMENTREG_VERSION). */
/** Pointer to a VFS chain element registration record. */
typedef RTVFSCHAINELEMENTREG *PRTVFSCHAINELEMENTREG;
/** Pointer to a const VFS chain element registration record. */
typedef RTVFSCHAINELEMENTREG const *PCRTVFSCHAINELEMENTREG;
/** The VFS chain element registration record version number. */
/**
* Parses the specification.
*
* @returns IPRT status code.
* @param pszSpec The specification string to parse.
* @param fFlags Flags, see RTVFSCHAIN_PF_XXX.
* @param enmLeadingAction The only allowed leading action type.
* @param enmTrailingAction The only allowed trailing action type.
* @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 ppszError On failure, this will point at the error
* location in @a pszSpec. Optional.
*/
RTDECL(int) RTVfsChainSpecParse(const char *pszSpec, uint32_t fFlags, RTVFSCHAINACTION enmLeadingAction,
/** @name RTVfsChainSpecParse
* @{ */
/** No real action is permitted, i.e. only passive filtering (aka pipe). */
#define RTVFSCHAIN_PF_NO_REAL_ACTION RT_BIT_32(0)
/** The specified leading action is optional. */
/** The specified trailing action is optional. */
/** Mask of valid flags. */
/** @}*/
/**
* Frees a parsed chain specification.
*
* @param pSpec What RTVfsChainSpecParse returned. NULL is
* quietly ignored.
*/
/**
* Registers a chain element provider.
*
* @returns IPRT status code
* @param pRegRec The registration record.
* @param fFromCtor Indicates where we're called from.
*/
/**
* Deregisters a chain element provider.
*
* @returns IPRT status code
* @param pRegRec The registration record.
* @param fFromDtor Indicates where we're called from.
*/
/** @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.
*/
{
/** The registration record, NULL if registration failed. */
{
if (RT_FAILURE(rc))
}
{
}
};
#else
extern void *name ## AutoRegistrationHack = \
#endif
/** @} */
/** @} */
#endif /* !___iprt_vfslowlevel_h */