/** @file * IPRT - Virtual Filesystem. */ /* * Copyright (C) 2010-2016 Oracle Corporation * * This file is part of VirtualBox Open Source Edition (OSE), as * available from http://www.virtualbox.org. This file is free software; * you can redistribute it and/or modify it under the terms of the GNU * 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_vfs_h #define ___iprt_vfs_h #include #include #include #include #include #include #include #include RT_C_DECLS_BEGIN /** @defgroup grp_rt_vfs RTVfs - Virtual Filesystem * @ingroup grp_rt * * The virtual filesystem APIs are intended to make it possible to work on * container files, file system sub-trees, file system overlays and other custom * filesystem configurations. It also makes it possible to create filters, like * automatically gunzipping a tar.gz file before feeding it to the RTTar API for * unpacking - or wise versa. * * The virtual filesystem APIs are intended to mirror the RTDir, RTFile, RTPath * and RTFs APIs pretty closely so that rewriting a piece of code to work with * it should be easy. However there are some differences to the way the APIs * works and the user should heed the documentation. The differences are * usually motivated by simplification and in some case to make the VFS more * flexible. * * @{ */ /** * The object type. */ typedef enum RTVFSOBJTYPE { /** Invalid type. */ RTVFSOBJTYPE_INVALID = 0, /** Pure base object. * This is returned by the filesystem stream to represent directories, * devices, fifos and similar that needs to be created. */ RTVFSOBJTYPE_BASE, /** Virtual filesystem. */ RTVFSOBJTYPE_VFS, /** Filesystem stream. */ RTVFSOBJTYPE_FS_STREAM, /** Pure I/O stream. */ RTVFSOBJTYPE_IO_STREAM, /** Directory. */ RTVFSOBJTYPE_DIR, /** File. */ RTVFSOBJTYPE_FILE, /** Symbolic link. */ RTVFSOBJTYPE_SYMLINK, /** End of valid object types. */ RTVFSOBJTYPE_END, /** Pure I/O stream. */ RTVFSOBJTYPE_32BIT_HACK = 0x7fffffff } RTVFSOBJTYPE; /** Pointer to a VFS object type. */ typedef RTVFSOBJTYPE *PRTVFSOBJTYPE; /** @name RTVfsCreate flags * @{ */ /** Whether the file system is read-only. */ #define RTVFS_C_READONLY RT_BIT(0) /** Whether we the VFS should be thread safe (i.e. automaticaly employ * locks). */ #define RTVFS_C_THREAD_SAFE RT_BIT(1) /** @} */ /** * Creates an empty virtual filesystem. * * @returns IPRT status code. * @param pszName Name, for logging and such. * @param fFlags Flags, MBZ. * @param phVfs Where to return the VFS handle. Release the returned * reference by calling RTVfsRelease. */ RTDECL(int) RTVfsCreate(const char *pszName, uint32_t fFlags, PRTVFS phVfs); RTDECL(uint32_t) RTVfsRetain(RTVFS hVfs); RTDECL(uint32_t) RTVfsRetainDebug(RTVFS hVfs, RT_SRC_POS_DECL); RTDECL(uint32_t) RTVfsRelease(RTVFS hVfs); RTDECL(int) RTVfsAttach(RTVFS hVfs, const char *pszMountPoint, uint32_t fFlags, RTVFS hVfsAttach); RTDECL(int) RTVfsDetach(RTVFS hVfs, const char *pszMountPoint, RTVFS hVfsToDetach, PRTVFS *phVfsDetached); RTDECL(uint32_t) RTVfsGetAttachmentCount(RTVFS hVfs); RTDECL(int) RTVfsGetAttachment(RTVFS hVfs, uint32_t iOrdinal, PRTVFS *phVfsAttached, uint32_t *pfFlags, char *pszMountPoint, size_t cbMountPoint); /** * Queries information about a object in the virtual filesystem. * * @returns IPRT Status code. * @param hVfs VFS handle. * relative to. * @param pszPath Path to the object, relative to the VFS root. * @param pObjInfo Where to return info. * @param enmAddAttr What to return. * @param fFlags RTPATH_F_XXX. * @sa RTPathQueryInfoEx, RTVfsDirQueryPathInfo, RTVfsObjQueryInfo */ RTDECL(int) RTVfsQueryPathInfo(RTVFS hVfs, const char *pszPath, PRTFSOBJINFO pObjInfo, RTFSOBJATTRADD enmAddAttr, uint32_t fFlags); /** * Checks whether a given range is in use by the virtual filesystem. * * @returns IPRT status code. * @param hVfs VFS handle. * @param off Start offset to check. * @param cb Number of bytes to check. * @param pfUsed Where to store the result. */ RTDECL(int) RTVfsIsRangeInUse(RTVFS hVfs, uint64_t off, size_t cb, bool *pfUsed); /** @defgroup grp_vfs_obj VFS Base Object API * @{ */ /** * Retains a reference to the VFS base object handle. * * @returns New reference count on success, UINT32_MAX on failure. * @param hVfsObj The VFS base object handle. */ RTDECL(uint32_t) RTVfsObjRetain(RTVFSOBJ hVfsObj); RTDECL(uint32_t) RTVfsObjRetainDebug(RTVFSOBJ hVfsObj, RT_SRC_POS_DECL); /** * Releases a reference to the VFS base handle. * * @returns New reference count on success (0 if closed), UINT32_MAX on failure. * @param hVfsObj The VFS base object handle. */ RTDECL(uint32_t) RTVfsObjRelease(RTVFSOBJ hVfsObj); /** * Query information about the object. * * @returns IPRT status code. * @retval VERR_NOT_SUPPORTED if the @a enmAddAttr value is not handled by the * implementation. * * @param hVfsObj The VFS object handle. * @param pObjInfo Where to return the info. * @param enmAddAttr Which additional attributes should be retrieved. * @sa RTVfsIoStrmQueryInfo, RTVfsFileQueryInfo, RTFileQueryInfo, * RTPathQueryInfo */ RTDECL(int) RTVfsObjQueryInfo(RTVFSOBJ hVfsObj, PRTFSOBJINFO pObjInfo, RTFSOBJATTRADD enmAddAttr); /** * Converts a VFS base object handle to a VFS handle. * * @returns Referenced handle on success, NIL on failure. * @param hVfsObj The VFS base object handle. */ RTDECL(RTVFS) RTVfsObjToVfs(RTVFSOBJ hVfsObj); /** * Converts a VFS base object handle to a VFS filesystem stream handle. * * @returns Referenced handle on success, NIL on failure. * @param hVfsObj The VFS base object handle. */ RTDECL(RTVFSFSSTREAM) RTVfsObjToFsStream(RTVFSOBJ hVfsObj); /** * Converts a VFS base object handle to a VFS directory handle. * * @returns Referenced handle on success, NIL on failure. * @param hVfsObj The VFS base object handle. */ RTDECL(RTVFSDIR) RTVfsObjToDir(RTVFSOBJ hVfsObj); /** * Converts a VFS base object handle to a VFS I/O stream handle. * * @returns Referenced handle on success, NIL on failure. * @param hVfsObj The VFS base object handle. */ RTDECL(RTVFSIOSTREAM) RTVfsObjToIoStream(RTVFSOBJ hVfsObj); /** * Converts a VFS base object handle to a VFS file handle. * * @returns Referenced handle on success, NIL on failure. * @param hVfsObj The VFS base object handle. */ RTDECL(RTVFSFILE) RTVfsObjToFile(RTVFSOBJ hVfsObj); /** * Converts a VFS base object handle to a VFS symbolic link handle. * * @returns Referenced handle on success, NIL on failure. * @param hVfsObj The VFS base object handle. */ RTDECL(RTVFSSYMLINK) RTVfsObjToSymlink(RTVFSOBJ hVfsObj); /** * Converts a VFS handle to a VFS base object handle. * * @returns Referenced handle on success, NIL if the input handle was invalid. * @param hVfs The VFS handle. */ RTDECL(RTVFSOBJ) RTVfsObjFromVfs(RTVFS hVfs); /** * Converts a VFS filesystem stream handle to a VFS base object handle. * * @returns Referenced handle on success, NIL if the input handle was invalid. * @param hVfsFss The VFS filesystem stream handle. */ RTDECL(RTVFSOBJ) RTVfsObjFromFsStream(RTVFSFSSTREAM hVfsFss); /** * Converts a VFS directory handle to a VFS base object handle. * * @returns Referenced handle on success, NIL if the input handle was invalid. * @param hVfsDir The VFS directory handle. */ RTDECL(RTVFSOBJ) RTVfsObjFromDir(RTVFSDIR hVfsDir); /** * Converts a VFS I/O stream handle to a VFS base object handle. * * @returns Referenced handle on success, NIL if the input handle was invalid. * @param hVfsIos The VFS I/O stream handle. */ RTDECL(RTVFSOBJ) RTVfsObjFromIoStream(RTVFSIOSTREAM hVfsIos); /** * Converts a VFS file handle to a VFS base object handle. * * @returns Referenced handle on success, NIL if the input handle was invalid. * @param hVfsFile The VFS file handle. */ RTDECL(RTVFSOBJ) RTVfsObjFromFile(RTVFSFILE hVfsFile); /** * Converts a VFS symbolic link handle to a VFS base object handle. * * @returns Referenced handle on success, NIL if the input handle was invalid. * @param hVfsSym The VFS symbolic link handle. */ RTDECL(RTVFSOBJ) RTVfsObjFromSymlink(RTVFSSYMLINK hVfsSym); /** @} */ /** @defgroup grp_vfs_fsstream VFS Filesystem Stream API * * Filesystem streams are for tar, cpio and similar. Any virtual filesystem can * be turned into a filesystem stream using RTVfsFsStrmFromVfs. * * @{ */ RTDECL(uint32_t) RTVfsFsStrmRetain(RTVFSFSSTREAM hVfsFss); RTDECL(uint32_t) RTVfsFsStrmRetainDebug(RTVFSFSSTREAM hVfsFss, RT_SRC_POS_DECL); RTDECL(uint32_t) RTVfsFsStrmRelease(RTVFSFSSTREAM hVfsFss); RTDECL(int) RTVfsFsStrmQueryInfo(RTVFSFSSTREAM hVfsFss, PRTFSOBJINFO pObjInfo, RTFSOBJATTRADD enmAddAttr); /** * Gets the next object in the stream. * * This call may affect the stream posision of a previously returned object. * * The type of object returned here typically boils down to three types: * - I/O streams (representing files), * - symbolic links * - base object * The base objects represent anything not convered by the two other, i.e. * directories, device nodes, fifos, sockets and whatnot. The details can be * queried using RTVfsObjQueryInfo. * * That said, absolutely any object except for filesystem stream objects can be * returned by this call. Any generic code is adviced to just deal with it all. * * @returns IPRT status code. * @retval VINF_SUCCESS if a new object was retrieved. * @retval VERR_EOF when there are no more objects. * @retval VERR_INVALID_FUNCTION if called on a non-readable stream. * * @param hVfsFss The file system stream handle. * @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. */ RTDECL(int) RTVfsFsStrmNext(RTVFSFSSTREAM hVfsFss, char **ppszName, RTVFSOBJTYPE *penmType, PRTVFSOBJ phVfsObj); /** * Appends a VFS object to the stream. * * The stream must be writable. * * @returns IPRT status code. * @retval VERR_INVALID_FUNCTION if called on a non-writable stream. * @param hVfsFss The file system stream handle. * @param pszPath The path. * @param hVfsObj The VFS object to add. * @param fFlags RTVFSFSSTRM_ADD_F_XXX. */ RTDECL(int) RTVfsFsStrmAdd(RTVFSFSSTREAM hVfsFss, const char *pszPath, RTVFSOBJ hVfsObj, uint32_t fFlags); /** @name RTVFSFSSTRM_ADD_F_XXX - Flags for RTVfsFsStrmAdd. * @{ */ /** Input is an I/O stream of indeterminate length, read to the end and then * update the file header. * @note This is *only* possible if the output stream is actually a file. */ #define RTVFSFSSTRM_ADD_F_STREAM RT_BIT_32(0) /** Mask of flags specific to the target stream. */ #define RTVFSFSSTRM_ADD_F_SPECIFIC_MASK UINT32_C(0xff000000) /** Valid bits. */ #define RTVFSFSSTRM_ADD_F_VALID_MASK UINT32_C(0xff000001) /** @} */ /** * Pushes an byte stream onto the stream. * * The stream must be writable. * * This differs from RTVfsFsStrmAdd() 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. * @retval VERR_INVALID_FUNCTION if called on a non-writable stream. * @param hVfsFss The file system stream handle. * @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. */ RTDECL(int) RTVfsFsStrmPushFile(RTVFSFSSTREAM hVfsFss, const char *pszPath, uint64_t cbFile, PCRTFSOBJINFO paObjInfo, uint32_t cObjInfo, uint32_t fFlags, PRTVFSIOSTREAM phVfsIos); /** @name RTVFSFSSTRM_PUSH_F_XXX - Flags for RTVfsFsStrmPushFile. * @{ */ /** Input is an I/O stream of indeterminate length, read to the end and then * update the file header. * @note This is *only* possible if the output stream is actually a file. */ #define RTVFSFSSTRM_PUSH_F_STREAM RT_BIT_32(0) /** Mask of flags specific to the target stream. */ #define RTVFSFSSTRM_PUSH_F_SPECIFIC_MASK UINT32_C(0xff000000) /** Valid bits. */ #define RTVFSFSSTRM_PUSH_F_VALID_MASK UINT32_C(0xff000001) /** @} */ /** * Marks the end of the stream. * * The stream must be writable. * * @returns IPRT status code. * @retval VERR_INVALID_FUNCTION if called on a non-writable stream. * @param hVfsFss The file system stream handle. */ RTDECL(int) RTVfsFsStrmEnd(RTVFSFSSTREAM hVfsFss); /** @} */ /** @defgroup grp_vfs_dir VFS Directory API * @{ */ /** * Retains a reference to the VFS directory handle. * * @returns New reference count on success, UINT32_MAX on failure. * @param hVfsDir The VFS directory handle. */ RTDECL(uint32_t) RTVfsDirRetain(RTVFSDIR hVfsDir); RTDECL(uint32_t) RTVfsDirRetainDebug(RTVFSDIR hVfsDir, RT_SRC_POS_DECL); /** * Releases a reference to the VFS directory handle. * * @returns New reference count on success (0 if closed), UINT32_MAX on failure. * @param hVfsDir The VFS directory handle. */ RTDECL(uint32_t) RTVfsDirRelease(RTVFSDIR hVfsDir); /** * Opens a directory in the specified file system. * * @returns IPRT status code. * @param hVfs The VFS to open the directory within. * @param pszPath Path to the directory, relative to the root. * @param fFlags Reserved, MBZ. * @param phVfsDir Where to return the directory. */ RTDECL(int) RTVfsDirOpen(RTVFS hVfs, const char *pszPath, uint32_t fFlags, PRTVFSDIR phVfsDir); /** * Opens a file in or under the given directory. * * @returns IPRT status code. * @param hVfsDir The VFS directory start walking the @a pszPath * relative to. * @param pszPath Path to the file. * @param fOpen RTFILE_O_XXX flags. * @param phVfsFile Where to return the file. * @sa RTVfsDirOpenFileAsIoStream */ RTDECL(int) RTVfsDirOpenFile(RTVFSDIR hVfsDir, const char *pszPath, uint64_t fOpen, PRTVFSFILE phVfsFile); /** * Convenience wrapper around RTVfsDirOpenFile that returns an I/O stream. * * @returns IPRT status code. * @param hVfsDir The VFS directory start walking the @a pszPath * relative to. * @param pszPath Path to the file. * @param fOpen RTFILE_O_XXX flags. * @param phVfsIos Where to return the I/O stream handle of the file. * @sa RTVfsDirOpenFile */ RTDECL(int) RTVfsDirOpenFileAsIoStream(RTVFSDIR hVfsDir, const char *pszPath, uint64_t fOpen, PRTVFSIOSTREAM phVfsIos); /** * Opens a directory in or under the given directory. * * @returns IPRT status code. * @param hVfsDir The VFS directory start walking the @a pszPath * relative to. * @param pszPath Path to the file. * @param fFlags Reserved, MBZ. * @param phVfsDir Where to return the directory. */ RTDECL(int) RTVfsDirOpenDir(RTVFSDIR hVfsDir, const char *pszPath, uint32_t fFlags, PRTVFSDIR phVfsDir); /** * Queries information about a object in or under the given directory. * * @returns IPRT Status code. * @param hVfsDir The VFS directory start walking the @a pszPath * relative to. * @param pszPath Path to the object. * @param pObjInfo Where to return info. * @param enmAddAttr What to return. * @param fFlags RTPATH_F_XXX. * @sa RTPathQueryInfoEx, RTVfsQueryPathInfo, RTVfsObjQueryInfo */ RTDECL(int) RTVfsDirQueryPathInfo(RTVFSDIR hVfsDir, const char *pszPath, PRTFSOBJINFO pObjInfo, RTFSOBJATTRADD enmAddAttr, uint32_t fFlags); /** * Reads the next entry in the directory returning extended information. * * @returns VINF_SUCCESS and data in pDirEntry on success. * @returns VERR_NO_MORE_FILES when the end of the directory has been reached. * @returns VERR_BUFFER_OVERFLOW if the buffer is too small to contain the filename. If * pcbDirEntry is specified it will be updated with the required buffer size. * @returns suitable iprt status code on other errors. * * @param hVfsDir The VFS directory. * @param pDirEntry Where to store the information about the next * directory entry on success. * @param pcbDirEntry Optional parameter used for variable buffer size. * * On input the variable pointed to contains the size of the pDirEntry * structure. This must be at least OFFSET(RTDIRENTRYEX, szName[2]) bytes. * * On successful output the field is updated to * OFFSET(RTDIRENTRYEX, szName[pDirEntry->cbName + 1]). * * When the data doesn't fit in the buffer and VERR_BUFFER_OVERFLOW is * returned, this field contains the required buffer size. * * The value is unchanged in all other cases. * @param enmAddAttr Which set of additional attributes to request. * Use RTFSOBJATTRADD_NOTHING if this doesn't matter. * * @sa RTDirReadEx */ RTDECL(int) RTVfsDirReadEx(RTVFSDIR hVfsDir, PRTDIRENTRYEX pDirEntry, size_t *pcbDirEntry, RTFSOBJATTRADD enmAddAttr); /** @} */ /** @defgroup grp_vfs_symlink VFS Symbolic Link API * * @remarks The TAR VFS and filesystem stream uses symbolic links for * describing hard links as well. The users must use RTFS_IS_SYMLINK * to check if it is a real symlink in those cases. * * @remarks Any VFS which is backed by a real file system may be subject to * races with other processes or threads, so the user may get * unexpected errors when this happends. This is a bit host specific, * i.e. it might be prevent on windows if we care. * * @{ */ /** * Retains a reference to the VFS symbolic link handle. * * @returns New reference count on success, UINT32_MAX on failure. * @param hVfsSym The VFS symbolic link handle. */ RTDECL(uint32_t) RTVfsSymlinkRetain(RTVFSSYMLINK hVfsSym); RTDECL(uint32_t) RTVfsSymlinkRetainDebug(RTVFSSYMLINK hVfsSym, RT_SRC_POS_DECL); /** * Releases a reference to the VFS symbolic link handle. * * @returns New reference count on success (0 if closed), UINT32_MAX on failure. * @param hVfsSym The VFS symbolic link handle. */ RTDECL(uint32_t) RTVfsSymlinkRelease(RTVFSSYMLINK hVfsSym); /** * Query information about the symbolic link. * * @returns IPRT status code. * @param hVfsSym The VFS symbolic link handle. * @param pObjInfo Where to return the info. * @param enmAddAttr Which additional attributes should be retrieved. * * @sa RTFileQueryInfo, RTPathQueryInfo, RTPathQueryInfoEx */ RTDECL(int) RTVfsSymlinkQueryInfo(RTVFSSYMLINK hVfsSym, PRTFSOBJINFO pObjInfo, RTFSOBJATTRADD enmAddAttr); /** * Set the unix style owner and group. * * @returns IPRT status code. * @param hVfsSym The VFS symbolic link handle. * @param fMode The new mode bits. * @param fMask The mask indicating which bits we are changing. * @sa RTFileSetMode, RTPathSetMode */ RTDECL(int) RTVfsSymlinkSetMode(RTVFSSYMLINK hVfsSym, RTFMODE fMode, RTFMODE fMask); /** * Set the timestamps associated with the object. * * @returns IPRT status code. * @param hVfsSym The VFS symbolic link handle. * @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, RTPathSetTimes */ RTDECL(int) RTVfsSymlinkSetTimes(RTVFSSYMLINK hVfsSym, PCRTTIMESPEC pAccessTime, PCRTTIMESPEC pModificationTime, PCRTTIMESPEC pChangeTime, PCRTTIMESPEC pBirthTime); /** * Set the unix style owner and group. * * @returns IPRT status code. * @param hVfsSym The VFS symbolic link handle. * @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, RTPathSetOwner. */ RTDECL(int) RTVfsSymlinkSetOwner(RTVFSSYMLINK hVfsSym, RTUID uid, RTGID gid); /** * Read the symbolic link target. * * @returns IPRT status code. * @param hVfsSym The VFS symbolic link handle. * @param pszTarget The target buffer. * @param cbTarget The size of the target buffer. * @sa RTSymlinkRead */ RTDECL(int) RTVfsSymlinkRead(RTVFSSYMLINK hVfsSym, char *pszTarget, size_t cbTarget); /** @} */ /** @defgroup grp_vfs_iostream VFS I/O Stream API * @{ */ /** * Creates a VFS file from a memory buffer. * * @returns IPRT status code. * * @param fFlags A combination of RTFILE_O_READ and RTFILE_O_WRITE. * @param pvBuf The buffer. This will be copied and not referenced * after this function returns. * @param cbBuf The buffer size. * @param phVfsIos Where to return the VFS I/O stream handle. */ RTDECL(int) RTVfsIoStrmFromBuffer(uint32_t fFlags, void const *pvBuf, size_t cbBuf, PRTVFSIOSTREAM phVfsIos); /** * Creates a VFS I/O stream handle from a standard IPRT file handle (RTFILE). * * @returns IPRT status code. * @param hFile The standard IPRT file handle. * @param fOpen The flags the handle was opened with. Pass 0 to * have these detected. * @param fLeaveOpen Whether to leave the handle open when the VFS file * is released, or to close it (@c false). * @param phVfsIos Where to return the VFS I/O stream handle. */ RTDECL(int) RTVfsIoStrmFromRTFile(RTFILE hFile, uint64_t fOpen, bool fLeaveOpen, PRTVFSIOSTREAM phVfsIos); /** * Creates a VFS I/O stream handle from a standard IPRT pipe handle (RTPIPE). * * @returns IPRT status code. * @param hPipe The standard IPRT pipe handle. * @param fLeaveOpen Whether to leave the handle open when the VFS file * is released, or to close it (@c false). * @param phVfsIos Where to return the VFS I/O stream handle. */ RTDECL(int) RTVfsIoStrmFromRTPipe(RTPIPE hPipe, bool fLeaveOpen, PRTVFSIOSTREAM phVfsIos); /** * Convenience function combining RTFileOpen with RTVfsIoStrmFromRTFile. * * @returns IPRT status code. * @param pszFilename The path to the file in the normal file system. * @param fOpen The flags to pass to RTFileOpen when opening the * file, i.e. RTFILE_O_XXX. * @param phVfsIos Where to return the VFS I/O stream handle. */ RTDECL(int) RTVfsIoStrmOpenNormal(const char *pszFilename, uint64_t fOpen, PRTVFSIOSTREAM phVfsIos); /** * Create a VFS I/O stream handle from one of the standard handles. * * @returns IPRT status code. * @param enmStdHandle The standard IPRT file handle. * @param fOpen The flags the handle was opened with. Pass 0 to * have these detected. * @param fLeaveOpen Whether to leave the handle open when the VFS file * is released, or to close it (@c false). * @param phVfsIos Where to return the VFS I/O stream handle. */ RTDECL(int) RTVfsIoStrmFromStdHandle(RTHANDLESTD enmStdHandle, uint64_t fOpen, bool fLeaveOpen, PRTVFSIOSTREAM phVfsIos); /** * Retains a reference to the VFS I/O stream handle. * * @returns New reference count on success, UINT32_MAX on failure. * @param hVfsIos The VFS I/O stream handle. */ RTDECL(uint32_t) RTVfsIoStrmRetain(RTVFSIOSTREAM hVfsIos); RTDECL(uint32_t) RTVfsIoStrmRetainDebug(RTVFSIOSTREAM hVfsIos, RT_SRC_POS_DECL); /** * Releases a reference to the VFS I/O stream handle. * * @returns New reference count on success (0 if closed), UINT32_MAX on failure. * @param hVfsIos The VFS I/O stream handle. */ RTDECL(uint32_t) RTVfsIoStrmRelease(RTVFSIOSTREAM hVfsIos); /** * Convert the VFS I/O stream handle to a VFS file handle. * * @returns The VFS file handle on success, this must be released. * NIL_RTVFSFILE if the I/O stream handle is invalid. * @param hVfsIos The VFS I/O stream handle. * @sa RTVfsFileToIoStream */ RTDECL(RTVFSFILE) RTVfsIoStrmToFile(RTVFSIOSTREAM hVfsIos); /** * Query information about the I/O stream. * * @returns IPRT status code. * @param hVfsIos The VFS I/O stream handle. * @param pObjInfo Where to return the info. * @param enmAddAttr Which additional attributes should be retrieved. * @sa RTFileQueryInfo */ RTDECL(int) RTVfsIoStrmQueryInfo(RTVFSIOSTREAM hVfsIos, PRTFSOBJINFO pObjInfo, RTFSOBJATTRADD enmAddAttr); /** * Read bytes from the I/O stream. * * @returns IPRT status code. * @retval VINF_SUCCESS and the number of bytes read written to @a pcbRead. * @retval VINF_TRY_AGAIN if @a fBlocking is @c false, @a pcbRead is not NULL, * and no data was available. @a *pcbRead will be set to 0. * @retval VINF_EOF when trying to read __beyond__ the end of the stream and * @a pcbRead is not NULL (it will be set to the number of bytes read, * or 0 if the end of the stream was reached before this call). * When the last byte of the read request is the last byte in the * stream, this status code will not be used. However, VINF_EOF is * returned when attempting to read 0 bytes while standing at the end * of the stream. * @retval VERR_EOF when trying to read __beyond__ the end of the stream and * @a pcbRead is NULL. * @retval VERR_ACCESS_DENIED if the stream is not readable. * * @param hVfsIos The VFS I/O stream handle. * @param pvBuf Where to store the read bytes. * @param cbToRead The number of bytes to read. * @param fBlocking Whether the call is blocking (@c true) or not. If * not, the @a pcbRead parameter must not be NULL. * @param pcbRead Where to always store the number of bytes actually * read. This can be NULL if @a fBlocking is true. * @sa RTVfsFileRead, RTFileRead, RTPipeRead, RTPipeReadBlocking, * RTSocketRead */ RTDECL(int) RTVfsIoStrmRead(RTVFSIOSTREAM hVfsIos, void *pvBuf, size_t cbToRead, bool fBlocking, size_t *pcbRead); /** * Read bytes from the I/O stream, optionally with offset. * * @returns IPRT status code. * @retval VINF_SUCCESS and the number of bytes read written to @a pcbRead. * @retval VINF_TRY_AGAIN if @a fBlocking is @c false, @a pcbRead is not NULL, * and no data was available. @a *pcbRead will be set to 0. * @retval VINF_EOF when trying to read __beyond__ the end of the stream and * @a pcbRead is not NULL (it will be set to the number of bytes read, * or 0 if the end of the stream was reached before this call). * When the last byte of the read request is the last byte in the * stream, this status code will not be used. However, VINF_EOF is * returned when attempting to read 0 bytes while standing at the end * of the stream. * @retval VERR_EOF when trying to read __beyond__ the end of the stream and * @a pcbRead is NULL. * @retval VERR_ACCESS_DENIED if the stream is not readable. * * @param hVfsIos The VFS I/O stream handle. * @param off Where to read at, -1 for the current position. * @param pvBuf Where to store the read bytes. * @param cbToRead The number of bytes to read. * @param fBlocking Whether the call is blocking (@c true) or not. If * not, the @a pcbRead parameter must not be NULL. * @param pcbRead Where to always store the number of bytes actually * read. This can be NULL if @a fBlocking is true. * @sa RTVfsFileRead, RTFileRead, RTPipeRead, RTPipeReadBlocking, * RTSocketRead */ RTDECL(int) RTVfsIoStrmReadAt(RTVFSIOSTREAM hVfsIos, RTFOFF off, void *pvBuf, size_t cbToRead, bool fBlocking, size_t *pcbRead); /** * Reads the remainder of the stream into a memory buffer. * * For simplifying string-style processing, the is a zero byte after the * returned buffer, making sure it can be used as a zero terminated string. * * @returns IPRT status code. * @param hVfsIos The VFS I/O stream handle. * @param ppvBuf Where to return the buffer. Must pass to * RTVfsIoStrmReadAllFree for freeing, not RTMemFree! * @param pcbBuf Where to return the buffer size. */ RTDECL(int) RTVfsIoStrmReadAll(RTVFSIOSTREAM hVfsIos, void **ppvBuf, size_t *pcbBuf); /** * Free memory buffer returned by RTVfsIoStrmReadAll. * * @param pvBuf What RTVfsIoStrmReadAll returned. * @param cbBuf What RTVfsIoStrmReadAll returned. */ RTDECL(void) RTVfsIoStrmReadAllFree(void *pvBuf, size_t cbBuf); /** * Write bytes to the I/O stream. * * @returns IPRT status code. * @retval VERR_ACCESS_DENIED if the stream is not writable. * * @param hVfsIos The VFS I/O stream handle. * @param pvBuf The bytes to write. * @param cbToWrite The number of bytes to write. * @param fBlocking Whether the call is blocking (@c true) or not. If * not, the @a pcbWritten parameter must not be NULL. * @param pcbWritten Where to always store the number of bytes actually * written. This can be NULL if @a fBlocking is true. * @sa RTVfsFileWrite, RTFileWrite, RTPipeWrite, RTPipeWriteBlocking, * RTSocketWrite */ RTDECL(int) RTVfsIoStrmWrite(RTVFSIOSTREAM hVfsIos, const void *pvBuf, size_t cbToWrite, bool fBlocking, size_t *pcbWritten); RTDECL(int) RTVfsIoStrmWriteAt(RTVFSIOSTREAM hVfsIos, RTFOFF off, const void *pvBuf, size_t cbToWrite, bool fBlocking, size_t *pcbWritten); /** * Reads bytes from the I/O stream into a scatter buffer. * * @returns IPRT status code. * @retval VINF_SUCCESS and the number of bytes read written to @a pcbRead. * @retval VINF_TRY_AGAIN if @a fBlocking is @c false, @a pcbRead is not NULL, * and no data was available. @a *pcbRead will be set to 0. * @retval VINF_EOF when trying to read __beyond__ the end of the stream and * @a pcbRead is not NULL (it will be set to the number of bytes read, * or 0 if the end of the stream was reached before this call). * When the last byte of the read request is the last byte in the * stream, this status code will not be used. However, VINF_EOF is * returned when attempting to read 0 bytes while standing at the end * of the stream. * @retval VERR_EOF when trying to read __beyond__ the end of the stream and * @a pcbRead is NULL. * @retval VERR_ACCESS_DENIED if the stream is not readable. * * @param hVfsIos The VFS I/O stream handle. * @param off Where to read at, -1 for the current position. * @param pSgBuf Pointer to a scatter buffer descriptor. The number * of bytes described by the segments is what will be * attemted read. * @param fBlocking Whether the call is blocking (@c true) or not. If * not, the @a pcbRead parameter must not be NULL. * @param pcbRead Where to always store the number of bytes actually * read. This can be NULL if @a fBlocking is true. * @sa RTFileSgRead, RTSocketSgRead, RTPipeRead, RTPipeReadBlocking */ RTDECL(int) RTVfsIoStrmSgRead(RTVFSIOSTREAM hVfsIos, RTFOFF off, PCRTSGBUF pSgBuf, bool fBlocking, size_t *pcbRead); /** * Write bytes to the I/O stream from a gather buffer. * * @returns IPRT status code. * @retval VERR_ACCESS_DENIED if the stream is not writable. * * @param hVfsIos The VFS I/O stream handle. * @param off Where to write at, -1 for the current position. * @param pSgBuf Pointer to a gather buffer descriptor. The number * of bytes described by the segments is what will be * attemted written. * @param fBlocking Whether the call is blocking (@c true) or not. If * not, the @a pcbWritten parameter must not be NULL. * @param pcbWritten Where to always store the number of bytes actually * written. This can be NULL if @a fBlocking is true. * @sa RTFileSgWrite, RTSocketSgWrite */ RTDECL(int) RTVfsIoStrmSgWrite(RTVFSIOSTREAM hVfsIos, RTFOFF off, PCRTSGBUF pSgBuf, bool fBlocking, size_t *pcbWritten); /** * Flush any buffered data to the I/O stream. * * @returns IPRT status code. * @param hVfsIos The VFS I/O stream handle. * @sa RTVfsFileFlush, RTFileFlush, RTPipeFlush */ RTDECL(int) RTVfsIoStrmFlush(RTVFSIOSTREAM hVfsIos); /** * Poll for events. * * @returns IPRT status code. * @param hVfsIos The VFS I/O stream handle. * @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 RTVfsFilePoll, RTPollSetAdd, RTPoll, RTPollNoResume. */ RTDECL(int) RTVfsIoStrmPoll(RTVFSIOSTREAM hVfsIos, uint32_t fEvents, RTMSINTERVAL cMillies, bool fIntr, uint32_t *pfRetEvents); /** * Tells the current I/O stream position. * * @returns Zero or higher - where to return the I/O stream offset. Values * below zero are IPRT status codes (VERR_XXX). * @param hVfsIos The VFS I/O stream handle. * @sa RTFileTell */ RTDECL(RTFOFF) RTVfsIoStrmTell(RTVFSIOSTREAM hVfsIos); /** * Skips @a cb ahead in the stream. * * @returns IPRT status code. * @param hVfsIos The VFS I/O stream handle. * @param cb The number bytes to skip. */ RTDECL(int) RTVfsIoStrmSkip(RTVFSIOSTREAM hVfsIos, RTFOFF cb); /** * Fills the stream with @a cb zeros. * * @returns IPRT status code. * @param hVfsIos The VFS I/O stream handle. * @param cb The number of zero bytes to insert. */ RTDECL(int) RTVfsIoStrmZeroFill(RTVFSIOSTREAM hVfsIos, RTFOFF cb); /** * Checks if we're at the end of the I/O stream. * * @returns true if at EOS, otherwise false. * @param hVfsIos The VFS I/O stream handle. */ RTDECL(bool) RTVfsIoStrmIsAtEnd(RTVFSIOSTREAM hVfsIos); /** * Get the RTFILE_O_XXX flags for the I/O stream. * * @returns RTFILE_O_XXX, 0 on failure. * @param hVfsIos The VFS I/O stream handle. */ RTDECL(uint64_t) RTVfsIoStrmGetOpenFlags(RTVFSIOSTREAM hVfsIos); /** * Process the rest of the stream, checking if it's all valid UTF-8 encoding. * * @returns IPRT status code. * * @param hVfsIos The VFS I/O stream handle. * @param fFlags Flags governing the validation, see * RTVFS_VALIDATE_UTF8_XXX. * @param poffError Where to return the error offset. Optional. */ RTDECL(int) RTVfsIoStrmValidateUtf8Encoding(RTVFSIOSTREAM hVfsIos, uint32_t fFlags, PRTFOFF poffError); /** @defgroup RTVFS_VALIDATE_UTF8_XXX RTVfsIoStrmValidateUtf8Encoding flags. * @{ */ /** The text must not contain any null terminator codepoints. */ #define RTVFS_VALIDATE_UTF8_NO_NULL RT_BIT_32(0) /** The codepoints must be in the range covered by RTC-3629. */ #define RTVFS_VALIDATE_UTF8_BY_RTC_3629 RT_BIT_32(1) /** Mask of valid flags. */ #define RTVFS_VALIDATE_UTF8_VALID_MASK UINT32_C(0x00000003) /** @} */ /** @} */ /** @defgroup grp_vfs_file VFS File API * @{ */ RTDECL(int) RTVfsFileOpen(RTVFS hVfs, const char *pszFilename, uint64_t fOpen, PRTVFSFILE phVfsFile); /** * Create a VFS file handle from a standard IPRT file handle (RTFILE). * * @returns IPRT status code. * @param hFile The standard IPRT file handle. * @param fOpen The flags the handle was opened with. Pass 0 to * have these detected. * @param fLeaveOpen Whether to leave the handle open when the VFS file * is released, or to close it (@c false). * @param phVfsFile Where to return the VFS file handle. */ RTDECL(int) RTVfsFileFromRTFile(RTFILE hFile, uint64_t fOpen, bool fLeaveOpen, PRTVFSFILE phVfsFile); RTDECL(RTHCUINTPTR) RTVfsFileToNative(RTFILE hVfsFile); /** * Convenience function combining RTFileOpen with RTVfsFileFromRTFile. * * @returns IPRT status code. * @param pszFilename The path to the file in the normal file system. * @param fOpen The flags to pass to RTFileOpen when opening the * file, i.e. RTFILE_O_XXX. * @param phVfsFile Where to return the VFS file handle. */ RTDECL(int) RTVfsFileOpenNormal(const char *pszFilename, uint64_t fOpen, PRTVFSFILE phVfsFile); /** * Convert the VFS file handle to a VFS I/O stream handle. * * @returns The VFS I/O stream handle on success, this must be released. * NIL_RTVFSIOSTREAM if the file handle is invalid. * @param hVfsFile The VFS file handle. * @sa RTVfsIoStrmToFile */ RTDECL(RTVFSIOSTREAM) RTVfsFileToIoStream(RTVFSFILE hVfsFile); /** * Retains a reference to the VFS file handle. * * @returns New reference count on success, UINT32_MAX on failure. * @param hVfsFile The VFS file handle. */ RTDECL(uint32_t) RTVfsFileRetain(RTVFSFILE hVfsFile); RTDECL(uint32_t) RTVfsFileRetainDebug(RTVFSFILE hVfsFile, RT_SRC_POS_DECL); /** * Releases a reference to the VFS file handle. * * @returns New reference count on success (0 if closed), UINT32_MAX on failure. * @param hVfsFile The VFS file handle. */ RTDECL(uint32_t) RTVfsFileRelease(RTVFSFILE hVfsFile); /** * Query information about the object. * * @returns IPRT status code. * @retval VERR_NOT_SUPPORTED if the @a enmAddAttr value is not handled by the * implementation. * * @param hVfsFile The VFS file handle. * @param pObjInfo Where to return the info. * @param enmAddAttr Which additional attributes should be retrieved. * @sa RTVfsObjQueryInfo, RTVfsFsStrmQueryInfo, RTVfsDirQueryInfo, * RTVfsIoStrmQueryInfo, RTVfsFileQueryInfo, RTFileQueryInfo, * RTPathQueryInfo. */ RTDECL(int) RTVfsFileQueryInfo(RTVFSFILE hVfsFile, PRTFSOBJINFO pObjInfo, RTFSOBJATTRADD enmAddAttr); /** * Read bytes from the file at the current position. * * @returns IPRT status code. * @retval VINF_SUCCESS and the number of bytes read written to @a pcbRead. * @retval VINF_EOF when trying to read __beyond__ the end of the file and * @a pcbRead is not NULL (it will be set to the number of bytes read, * or 0 if the end of the file was reached before this call). * When the last byte of the read request is the last byte in the * file, this status code will not be used. However, VINF_EOF is * returned when attempting to read 0 bytes while standing at the end * of the file. * @retval VERR_EOF when trying to read __beyond__ the end of the file and * @a pcbRead is NULL. * @retval VERR_ACCESS_DENIED if the file is not readable. * * @param hVfsFile The VFS file handle. * @param pvBuf Where to store the read bytes. * @param cbToRead The number of bytes to read. * @param pcbRead Where to always store the number of bytes actually * read. Optional. * @sa RTVfsIoStrmRead, RTFileRead, RTPipeRead, RTPipeReadBlocking, * RTSocketRead */ RTDECL(int) RTVfsFileRead(RTVFSFILE hVfsFile, void *pvBuf, size_t cbToRead, size_t *pcbRead); RTDECL(int) RTVfsFileReadAt(RTVFSFILE hVfsFile, RTFOFF off, void *pvBuf, size_t cbToRead, size_t *pcbRead); /** * Write bytes to the file at the current position. * * @returns IPRT status code. * @retval VERR_ACCESS_DENIED if the file is not writable. * * @param hVfsFile The VFS file handle. * @param pvBuf The bytes to write. * @param cbToWrite The number of bytes to write. * @param pcbWritten Where to always store the number of bytes actually * written. This can be NULL. * @sa RTVfsIoStrmRead, RTFileWrite, RTPipeWrite, RTPipeWriteBlocking, * RTSocketWrite */ RTDECL(int) RTVfsFileWrite(RTVFSFILE hVfsFile, const void *pvBuf, size_t cbToWrite, size_t *pcbWritten); RTDECL(int) RTVfsFileWriteAt(RTVFSFILE hVfsFile, RTFOFF off, const void *pvBuf, size_t cbToWrite, size_t *pcbWritten); /** * Reads bytes from the file into a scatter buffer. * * @returns IPRT status code. * @retval VINF_SUCCESS and the number of bytes read written to @a pcbRead. * @retval VINF_TRY_AGAIN if @a fBlocking is @c false, @a pcbRead is not NULL, * and no data was available. @a *pcbRead will be set to 0. * @retval VINF_EOF when trying to read __beyond__ the end of the stream and * @a pcbRead is not NULL (it will be set to the number of bytes read, * or 0 if the end of the stream was reached before this call). * When the last byte of the read request is the last byte in the * stream, this status code will not be used. However, VINF_EOF is * returned when attempting to read 0 bytes while standing at the end * of the stream. * @retval VERR_EOF when trying to read __beyond__ the end of the stream and * @a pcbRead is NULL. * @retval VERR_ACCESS_DENIED if the stream is not readable. * * @param hVfsFile The VFS file handle. * @param off Where to read at, -1 for the current position. * @param pSgBuf Pointer to a scatter buffer descriptor. The number * of bytes described by the segments is what will be * attemted read. * @param fBlocking Whether the call is blocking (@c true) or not. If * not, the @a pcbRead parameter must not be NULL. * @param pcbRead Where to always store the number of bytes actually * read. This can be NULL if @a fBlocking is true. * @sa RTFileSgRead, RTSocketSgRead, RTPipeRead, RTPipeReadBlocking */ RTDECL(int) RTVfsFileSgRead(RTVFSFILE hVfsFile, RTFOFF off, PCRTSGBUF pSgBuf, bool fBlocking, size_t *pcbRead); /** * Write bytes to the file from a gather buffer. * * @returns IPRT status code. * @retval VERR_ACCESS_DENIED if the stream is not writable. * * @param hVfsFile The VFS file handle. * @param off Where to write at, -1 for the current position. * @param pSgBuf Pointer to a gather buffer descriptor. The number * of bytes described by the segments is what will be * attemted written. * @param fBlocking Whether the call is blocking (@c true) or not. If * not, the @a pcbWritten parameter must not be NULL. * @param pcbWritten Where to always store the number of bytes actually * written. This can be NULL if @a fBlocking is true. * @sa RTFileSgWrite, RTSocketSgWrite */ RTDECL(int) RTVfsFileSgWrite(RTVFSFILE hVfsFile, RTFOFF off, PCRTSGBUF pSgBuf, bool fBlocking, size_t *pcbWritten); /** * Flush any buffered data to the file. * * @returns IPRT status code. * @param hVfsFile The VFS file handle. * @sa RTVfsIoStrmFlush, RTFileFlush, RTPipeFlush */ RTDECL(int) RTVfsFileFlush(RTVFSFILE hVfsFile); /** * Poll for events. * * @returns IPRT status code. * @param hVfsFile The VFS file handle. * @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 RTVfsIoStrmPoll, RTPollSetAdd, RTPoll, RTPollNoResume. */ RTDECL(RTFOFF) RTVfsFilePoll(RTVFSFILE hVfsFile, uint32_t fEvents, RTMSINTERVAL cMillies, bool fIntr, uint32_t *pfRetEvents); /** * Tells the current file position. * * @returns Zero or higher - where to return the file offset. Values * below zero are IPRT status codes (VERR_XXX). * @param hVfsFile The VFS file handle. * @sa RTFileTell, RTVfsIoStrmTell. */ RTDECL(RTFOFF) RTVfsFileTell(RTVFSFILE hVfsFile); /** * Changes the current read/write position of a file. * * @returns IPRT status code. * * @param hVfsFile The VFS file handle. * @param offSeek The seek offset. * @param uMethod The seek emthod. * @param poffActual Where to optionally return the new file offset. * * @sa RTFileSeek */ RTDECL(int) RTVfsFileSeek(RTVFSFILE hVfsFile, RTFOFF offSeek, uint32_t uMethod, uint64_t *poffActual); RTDECL(int) RTVfsFileSetSize(RTVFSFILE hVfsFile, uint64_t cbSize); RTDECL(int) RTVfsFileGetSize(RTVFSFILE hVfsFile, uint64_t *pcbSize); RTDECL(RTFOFF) RTVfsFileGetMaxSize(RTVFSFILE hVfsFile); RTDECL(int) RTVfsFileGetMaxSizeEx(RTVFSFILE hVfsFile, PRTFOFF pcbMax); /** * Get the RTFILE_O_XXX flags for the I/O stream. * * @returns RTFILE_O_XXX, 0 on failure. * @param hVfsFile The VFS file handle. */ RTDECL(uint64_t) RTVfsFileGetOpenFlags(RTVFSFILE hVfsFile); /** @} */ #ifdef DEBUG # undef RTVfsRetain # define RTVfsRetain(hVfs) RTVfsRetainDebug(hVfs, RT_SRC_POS) # undef RTVfsObjRetain # define RTVfsObjRetain(hVfsObj) RTVfsObjRetainDebug(hVfsObj, RT_SRC_POS) # undef RTVfsDirRetain # define RTVfsDirRetain(hVfsDir) RTVfsDirRetainDebug(hVfsDir, RT_SRC_POS) # undef RTVfsFileRetain # define RTVfsFileRetain(hVfsFile) RTVfsFileRetainDebug(hVfsFile, RT_SRC_POS) # undef RTVfsIoStrmRetain # define RTVfsIoStrmRetain(hVfsIos) RTVfsIoStrmRetainDebug(hVfsIos, RT_SRC_POS) # undef RTVfsFsStrmRetain # define RTVfsFsStrmRetain(hVfsFss) RTVfsFsStrmRetainDebug(hVfsFss, RT_SRC_POS) #endif /** @defgroup grp_vfs_misc VFS Miscellaneous * @{ */ /** * Memorizes the I/O stream as a file backed by memory. * * @returns IPRT status code. * * @param hVfsIos The VFS I/O stream to memorize. This will be read * to the end on success, on failure its position is * undefined. * @param fFlags A combination of RTFILE_O_READ and RTFILE_O_WRITE. * @param phVfsFile Where to return the handle to the memory file on * success. */ RTDECL(int) RTVfsMemorizeIoStreamAsFile(RTVFSIOSTREAM hVfsIos, uint32_t fFlags, PRTVFSFILE phVfsFile); /** * Creates a VFS file from a memory buffer. * * @returns IPRT status code. * * @param fFlags A combination of RTFILE_O_READ and RTFILE_O_WRITE. * @param pvBuf The buffer. This will be copied and not referenced * after this function returns. * @param cbBuf The buffer size. * @param phVfsFile Where to return the handle to the memory file on * success. */ RTDECL(int) RTVfsFileFromBuffer(uint32_t fFlags, void const *pvBuf, size_t cbBuf, PRTVFSFILE phVfsFile); /** * Creates a memory backed VFS file object for read and write. * * @returns IPRT status code. * * @param hVfsIos The VFS I/O stream to memorize. This will be read * to the end on success, on failure its position is * undefined. * @param cbEstimate The estimated file size. * @param phVfsFile Where to return the handle to the memory file on * success. * @sa RTVfsMemIoStrmCreate */ RTDECL(int) RTVfsMemFileCreate(RTVFSIOSTREAM hVfsIos, size_t cbEstimate, PRTVFSFILE phVfsFile); /** * Creates a memory backed VFS file object for read and write. * * @returns IPRT status code. * * @param hVfsIos The VFS I/O stream to memorize. This will be read * to the end on success, on failure its position is * undefined. * @param cbEstimate The estimated file size. * @param phVfsIos Where to return the handle to the memory I/O stream * on success. * @sa RTVfsMemFileCreate */ RTDECL(int) RTVfsMemIoStrmCreate(RTVFSIOSTREAM hVfsIos, size_t cbEstimate, PRTVFSIOSTREAM phVfsIos); /** * Pumps data from one I/O stream to another. * * The data is read in chunks from @a hVfsIosSrc and written to @a hVfsIosDst * until @a hVfsIosSrc indicates end of stream. * * @returns IPRT status code * * @param hVfsIosSrc The input stream. * @param hVfsIosDst The output stream. * @param cbBufHint Hints at a good temporary buffer size, pass 0 if * clueless. */ RTDECL(int) RTVfsUtilPumpIoStreams(RTVFSIOSTREAM hVfsIosSrc, RTVFSIOSTREAM hVfsIosDst, size_t cbBufHint); /** * Creates a progress wrapper for an I/O stream. * * @returns IRPT status code. * @param hVfsIos The I/O stream to wrap. * @param pfnProgress The progress callback. The return code is * ignored by default, see * RTVFSPROGRESS_F_CANCELABLE. * @param pvUser The user argument to @a pfnProgress. * @param fFlags RTVFSPROGRESS_F_XXX * @param cbExpectedRead The expected number of bytes read. * @param cbExpectedWritten The execpted number of bytes written. * @param phVfsIos Where to return the I/O stream handle. */ RTDECL(int) RTVfsCreateProgressForIoStream(RTVFSIOSTREAM hVfsIos, PFNRTPROGRESS pfnProgress, void *pvUser, uint32_t fFlags, uint64_t cbExpectedRead, uint64_t cbExpectedWritten, PRTVFSIOSTREAM phVfsIos); /** * Creates a progress wrapper for a file stream. * * @returns IRPT status code. * @param hVfsFile The file to wrap. * @param pfnProgress The progress callback. The return code is * ignored by default, see * RTVFSPROGRESS_F_CANCELABLE. * @param pvUser The user argument to @a pfnProgress. * @param fFlags RTVFSPROGRESS_F_XXX * @param cbExpectedRead The expected number of bytes read. * @param cbExpectedWritten The execpted number of bytes written. * @param phVfsFile Where to return the file handle. */ RTDECL(int) RTVfsCreateProgressForFile(RTVFSFILE hVfsFile, PFNRTPROGRESS pfnProgress, void *pvUser, uint32_t fFlags, uint64_t cbExpectedRead, uint64_t cbExpectedWritten, PRTVFSFILE phVfsFile); /** @name RTVFSPROGRESS_F_XXX - Flags for RTVfsCreateProcessForIoStream and * RTVfsCreateProcessForFile. * @{ */ /** Cancel if the callback returns a failure status code. * This isn't default behavior because the cancelation is delayed one I/O * operation in most cases and it's uncertain how the VFS user will handle the * cancellation status code. */ #define RTVFSPROGRESS_F_CANCELABLE RT_BIT_32(0) /** Account forward seeks as reads. */ #define RTVFSPROGRESS_F_FORWARD_SEEK_AS_READ RT_BIT_32(1) /** Account fprward seeks as writes. */ #define RTVFSPROGRESS_F_FORWARD_SEEK_AS_WRITE RT_BIT_32(2) /** Valid bits. */ #define RTVFSPROGRESS_F_VALID_MASK UINT32_C(0x00000007) /** @} */ /** * Create an I/O stream instance performing simple sequential read-ahead. * * @returns IPRT status code. * @param hVfsIos The input stream to perform read ahead on. If this is * actually for a file object, the returned I/O stream * handle can also be cast to a file handle. * @param fFlags Flags reserved for future use, MBZ. * @param cBuffers How many read ahead buffers to use. Specify 0 for * default value. * @param cbBuffer The size of each read ahead buffer. Specify 0 for * default value. * @param phVfsIos Where to return the read ahead I/O stream handle. * * @remarks Careful using this on a message pipe or socket. The reads are * performed in blocked mode and it may be host and/or implementation * dependent whether they will return ready data immediate or wait * until there's a whole @a cbBuffer (or default) worth ready. * * @sa RTVfsCreateReadAheadForFile */ RTDECL(int) RTVfsCreateReadAheadForIoStream(RTVFSIOSTREAM hVfsIos, uint32_t fFlags, uint32_t cBuffers, uint32_t cbBuffer, PRTVFSIOSTREAM phVfsIos); /** * Create an I/O stream instance performing simple sequential read-ahead. * * @returns IPRT status code. * @param hVfsFile The input file to perform read ahead on. * @param fFlags Flags reserved for future use, MBZ. * @param cBuffers How many read ahead buffers to use. Specify 0 for * default value. * @param cbBuffer The size of each read ahead buffer. Specify 0 for * default value. * @param phVfsFile Where to return the read ahead file handle. * @sa RTVfsCreateReadAheadForIoStream */ RTDECL(int) RTVfsCreateReadAheadForFile(RTVFSFILE hVfsFile, uint32_t fFlags, uint32_t cBuffers, uint32_t cbBuffer, PRTVFSFILE phVfsFile); /** * Create a file system stream for writing to a directory. * * This is just supposed to be a drop in replacement for the TAR creator stream * that instead puts the files and stuff in a directory instead of a TAR * archive. In addition, it has an undo feature for simplying cleaning up after * a botched run * * @returns IPRT status code. * @param hVfsBaseDir The base directory. * @param fFlags RTVFSFSS2DIR_F_XXX * @param phVfsFss Where to return the FSS handle. * @sa RTVfsFsStrmToNormalDir, RTVfsFsStrmToDirUndo */ RTDECL(int) RTVfsFsStrmToDir(RTVFSDIR hVfsBaseDir, uint32_t fFlags, PRTVFSFSSTREAM phVfsFss); /** * Create a file system stream for writing to a normal directory. * * This is just supposed to be a drop in replacement for the TAR creator stream * that instead puts the files and stuff in a directory instead of a TAR * archive. In addition, it has an undo feature for simplying cleaning up after * a botched run * * @returns IPRT status code. * @param pszBaseDir The base directory. Must exist. * @param fFlags RTVFSFSS2DIR_F_XXX * @param phVfsFss Where to return the FSS handle. * @sa RTVfsFsStrmToDir, RTVfsFsStrmToDirUndo */ RTDECL(int) RTVfsFsStrmToNormalDir(const char *pszBaseDir, uint32_t fFlags, PRTVFSFSSTREAM phVfsFss); /** @name RTVFSFSS2DIR_F_XXX - Flags for RTVfsFsStrmToNormalDir * @{ */ /** Overwrite existing files (default is to not overwrite anything). */ #define RTVFSFSS2DIR_F_OVERWRITE_FILES RT_BIT_32(0) /** Valid bits. */ #define RTVFSFSS2DIR_F_VALID_MASK UINT32_C(0x00000001) /** @} */ /** * Deletes files, directories, symlinks and stuff created by a FSS returned by * RTVfsFsStrmToNormalDir or RTVfsFsStrmToDir. * * @returns IPRT status code. * @param hVfsFss The write-to-directory FSS handle. */ RTDECL(int) RTVfsFsStrmToDirUndo(RTVFSFSSTREAM hVfsFss); /** @} */ /** @defgroup grp_rt_vfs_chain VFS Chains * * VFS chains is for doing pipe like things with VFS objects from the command * line. Imagine you want to cat the readme.gz of an ISO you could do * something like: * RTCat :iprtvfs:file(stdfile,live.iso)|vfs(isofs)|iso(open,readme.gz)|ios(gunzip) * or * RTCat :iprtvfs:file(stdfile,live.iso)|ios(isofs,readme.gz)|ios(gunzip) * * Or say you want to read the README.TXT on a floppy image: * RTCat :iprtvfs:file(stdfile,floppy.img,r)|vfs(fat)|ios(open,README.TXT) * or * RTCat :iprtvfs:file(stdfile,floppy.img,r)|vfs(fat)|README.TXT * * Or in the other direction, you want to write a STUFF.TGZ file to the above * floppy image, using a lazy writer thread for compressing the data: * RTTar cf :iprtvfs:file(stdfile,floppy.img,rw)|ios(fat,STUFF.TGZ)|ios(gzip)|ios(push) . * * * A bit more formally: * :iprtvfs:{type}({provider}[,provider-args])[{separator}{type}...][{separator}{path}] * * The @c type refers to VFS object that should be created by the @c provider. * Valid types: * - vfs: A virtual file system (volume). * - fss: A file system stream (e.g. tar). * - ios: An I/O stream. * - file: A file. * - dir: A directory. * - sym: A symbolic link (not sure how useful this is). * * The @c provider refers to registered chain element providers (see * RTVFSCHAINELEMENTREG for how that works internally). These are asked to * create a VFS object of the specified type using the given arguments (if any). * Default providers: * - std: Standard file, directory and file system. * - open: Opens a file, I/O stream or directory in a vfs or directory object. * - pull: Read-ahead buffering thread on file or I/O stream. * - push: Lazy-writer buffering thread on file or I/O stream. * - gzip: Compresses an I/O stream. * - gunzip: Decompresses an I/O stream. * - fat: FAT file system accessor. * - isofs: ISOFS file system accessor. * * As element @c separator we allow both colon (':') and the pipe character * ('|'). The latter the conventional one, but since it's inconvenient on the * command line, colon is provided as an alternative. * * In the final element we allow a simple @a path to be specified instead of the * type-provider-arguments stuff. The previous object must be a directory, file * system or file system stream. The application will determin exactly which * operation or operations which will be performed. * * @{ */ /** The path prefix used to identify an VFS chain specification. */ #define RTVFSCHAIN_SPEC_PREFIX ":iprtvfs:" RTDECL(int) RTVfsChainOpenVfs(const char *pszSpec, PRTVFS phVfs, uint32_t *poffError, PRTERRINFO pErrInfo); RTDECL(int) RTVfsChainOpenFsStream(const char *pszSpec, PRTVFSFSSTREAM phVfsFss, uint32_t *poffError, PRTERRINFO pErrInfo); RTDECL(int) RTVfsChainOpenDir(const char *pszSpec, uint32_t fOpen, PRTVFSDIR phVfsDir, uint32_t *poffError, PRTERRINFO pErrInfo); RTDECL(int) RTVfsChainOpenFile(const char *pszSpec, uint64_t fOpen, PRTVFSFILE phVfsFile, uint32_t *poffError, PRTERRINFO pErrInfo); RTDECL(int) RTVfsChainOpenIoStream(const char *pszSpec, uint64_t fOpen, PRTVFSIOSTREAM phVfsIos, uint32_t *poffError, PRTERRINFO pErrInfo); RTDECL(int) RTVfsChainOpenSymlink(const char *pszSpec, PRTVFSSYMLINK phVfsSym, uint32_t *poffError, PRTERRINFO pErrInfo); RTDECL(int) RTVfsChainQueryInfo(const char *pszSpec, PRTFSOBJINFO pObjInfo, RTFSOBJATTRADD enmAdditionalAttribs, uint32_t fFlags, uint32_t *poffError, PRTERRINFO pErrInfo); /** * Tests if the given string is a chain specification or not. * * @returns true if it is, false if it isn't. * @param pszSpec The alleged chain spec. */ RTDECL(bool) RTVfsChainIsSpec(const char *pszSpec); /** * Queries the path from the final element. * * @returns IPRT status code. * @retval VERR_VFS_CHAIN_NOT_PATH_ONLY if the final element isn't just a * simple path. * @param pszSpec The chain spec. * @param ppszFinalPath Where to return a copy of the final path on success. * Call RTStrFree when done. * @param poffError Where to on error return an offset into @a pszSpec * of what cause the error. Optional. * */ RTDECL(int) RTVfsChainQueryFinalPath(const char *pszSpec, char **ppszFinalPath, uint32_t *poffError); /** * Common code for reporting errors of a RTVfsChainOpen* API. * * @param pszFunction The API called. * @param pszSpec The VFS chain specification or file path passed to the. * @param rc The return code. * @param offError The error offset value returned (0 if not captured). * @param pErrInfo Additional error information. Optional. * * @sa RTVfsChainMsgErrorExitFailure * @sa RTVfsChainOpenVfs, RTVfsChainOpenFsStream, RTVfsChainOpenDir, * RTVfsChainOpenFile, RTVfsChainOpenIoStream, RTVfsChainOpenSymlink */ RTDECL(void) RTVfsChainMsgError(const char *pszFunction, const char *pszSpec, int rc, uint32_t offError, PRTERRINFO pErrInfo); /** * Common code for reporting errors of a RTVfsChainOpen* API. * * @returns RTEXITCODE_FAILURE * * @param pszFunction The API called. * @param pszSpec The VFS chain specification or file path passed to the. * @param rc The return code. * @param offError The error offset value returned (0 if not captured). * @param pErrInfo Additional error information. Optional. * * @sa RTVfsChainMsgError * @sa RTVfsChainOpenVfs, RTVfsChainOpenFsStream, RTVfsChainOpenDir, * RTVfsChainOpenFile, RTVfsChainOpenIoStream, RTVfsChainOpenSymlink */ RTDECL(RTEXITCODE) RTVfsChainMsgErrorExitFailure(const char *pszFunction, const char *pszSpec, int rc, uint32_t offError, PRTERRINFO pErrInfo); /** @} */ /** @} */ RT_C_DECLS_END #endif /* !___iprt_vfs_h */