diff options
Diffstat (limited to 'include/iprt/vfs.h')
| -rw-r--r-- | include/iprt/vfs.h | 2021 |
1 files changed, 2021 insertions, 0 deletions
diff --git a/include/iprt/vfs.h b/include/iprt/vfs.h new file mode 100644 index 00000000..a45c8817 --- /dev/null +++ b/include/iprt/vfs.h @@ -0,0 +1,2021 @@ +/** @file + * IPRT - Virtual Filesystem. + */ + +/* + * Copyright (C) 2010-2023 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_vfs_h +#define IPRT_INCLUDED_vfs_h +#ifndef RT_WITHOUT_PRAGMA_ONCE +# pragma once +#endif + +#include <iprt/cdefs.h> +#include <iprt/types.h> +#include <iprt/dir.h> +#include <iprt/fs.h> +#include <iprt/handle.h> +#include <iprt/symlink.h> +#include <iprt/sg.h> +#include <iprt/time.h> + + +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 vice 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; + +/** + * Translates a RTVFSOBJTYPE value into a string. + * + * @returns Pointer to readonly name. + * @param enmType The object type to name. + */ +RTDECL(const char *) RTVfsTypeName(RTVFSOBJTYPE enmType); + + + +/** @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); + +/** @name RTVFSMNT_F_XXX - Flags for RTVfsMount + * @{ */ +/** Mount read-only. */ +#define RTVFSMNT_F_READ_ONLY RT_BIT_32(0) +/** Purpose is . */ +#define RTVFSMNT_F_FOR_RANGE_IN_USE RT_BIT_32(1) +/** Valid mask. */ +#define RTVFSMNT_F_VALID_MASK UINT32_C(0x00000003) +/** @} */ + +/** + * Does the file system detection and mounting. + * + * @returns IPRT status code. + * @retval VERR_VFS_UNSUPPORTED_FORMAT if not recognized as a support file + * system. + * @param hVfsFileIn The file handle of the volume. + * @param fFlags RTVFSMTN_F_XXX. + * @param phVfs Where to return the VFS handle on success. + * @param pErrInfo Where to return additional error information. + * Optional. + */ +RTDECL(int) RTVfsMountVol(RTVFSFILE hVfsFileIn, uint32_t fFlags, PRTVFS phVfs, PRTERRINFO pErrInfo); + +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); + +/** + * Opens the root director of the given VFS. + * + * @returns IPRT status code. + * @param hVfs VFS handle. + * @param phDir Where to return the root directory handle. + */ +RTDECL(int) RTVfsOpenRoot(RTVFS hVfs, PRTVFSDIR phDir); + +/** + * Queries information about a object in the virtual filesystem. + * + * @returns IPRT Status code. + * @param hVfs VFS handle. + * @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) RTVfsQueryRangeState(RTVFS hVfs, uint64_t off, size_t cb, bool *pfUsed); + +/** + * Queries the volume label. + * + * @returns IPRT status code. + * @param hVfs VFS handle. + * @param fAlternative For use with ISO files to retrieve the primary lable + * rather than the joliet / UDF one that the mount + * options would indicate. For other file systems, as + * well for ISO not mounted in joliet / UDF mode, the + * flag is ignored. + * @param pszLabel Where to store the lable. + * @param cbLabel Size of the buffer @a pszLable points at. + * @param pcbActual Where to return the label length, including the + * terminator. In case of VERR_BUFFER_OVERFLOW + * returns, this will be set to the required buffer + * size. Optional. + */ +RTDECL(int) RTVfsQueryLabel(RTVFS hVfs, bool fAlternative, char *pszLabel, size_t cbLabel, size_t *pcbActual); + + +/** @defgroup grp_rt_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); + +/** @name RTVFSOBJ_F_XXX - Flags or RTVfsObjOpen and RTVfsDirOpenObj. + * @note Must leave space for RTPATH_F_XXX. + * @{ */ +/** Directory (RTFS_TYPE_DIRECTORY). */ +#define RTVFSOBJ_F_OPEN_DIRECTORY RT_BIT_32(8) +/** Symbolic link (RTFS_TYPE_SYMLINK). */ +#define RTVFSOBJ_F_OPEN_SYMLINK RT_BIT_32(9) +/** Regular file (RTFS_TYPE_FILE). */ +#define RTVFSOBJ_F_OPEN_FILE RT_BIT_32(10) +/** Character device (RTFS_TYPE_DEV_CHAR). */ +#define RTVFSOBJ_F_OPEN_DEV_CHAR RT_BIT_32(11) +/** Block device (RTFS_TYPE_DEV_BLOCK). */ +#define RTVFSOBJ_F_OPEN_DEV_BLOCK RT_BIT_32(12) +/** Named pipe (fifo) (RTFS_TYPE_FIFO). */ +#define RTVFSOBJ_F_OPEN_FIFO RT_BIT_32(13) +/** Socket (RTFS_TYPE_SOCKET). */ +#define RTVFSOBJ_F_OPEN_SOCKET RT_BIT_32(14) +/** Mounted VFS. */ +#define RTVFSOBJ_F_OPEN_MOUNT RT_BIT_32(15) +/** Mask object types we wish to open. */ +#define RTVFSOBJ_F_OPEN_MASK UINT32_C(0x0000ff00) +/** Any kind of object that translates to RTVFSOBJTYPE_FILE. */ +#define RTVFSOBJ_F_OPEN_ANY_FILE (RTVFSOBJ_F_OPEN_FILE | RTVFSOBJ_F_OPEN_DEV_BLOCK) +/** Any kind of object that translates to RTVFSOBJTYPE_IOS or + * RTVFSOBJTYPE_FILE. */ +#define RTVFSOBJ_F_OPEN_ANY_IO_STREAM ( RTVFSOBJ_F_ANY_OPEN_FILE | RTVFSOBJ_F_DEV_OPEN_BLOCK \ + | RTVFSOBJ_F_OPEN_FIFO | RTVFSOBJ_F_OPEN_SOCKET) +/** Any kind of object. */ +#define RTVFSOBJ_F_OPEN_ANY RTVFSOBJ_F_OPEN_MASK + +/** Do't create anything, return file not found. */ +#define RTVFSOBJ_F_CREATE_NOTHING UINT32_C(0x00000000) +/** Create a file if the if the object was not found and the RTFILE_O_XXX + * flags allows it. */ +#define RTVFSOBJ_F_CREATE_FILE UINT32_C(0x00010000) +/** Create a directory if the object was not found and the RTFILE_O_XXX + * flags allows it. */ +#define RTVFSOBJ_F_CREATE_DIRECTORY UINT32_C(0x00020000) +/** The creation type mask. */ +#define RTVFSOBJ_F_CREATE_MASK UINT32_C(0x00070000) + +/** Indicate that this call is for traversal. + * @internal only */ +#define RTVFSOBJ_F_TRAVERSAL RT_BIT_32(31) +/** Valid mask for external callers. */ +#define RTVFSOBJ_F_VALID_MASK UINT32_C(0x0007ff00) +/** @} */ + +/** + * Opens any file system object in the given VFS. + * + * @returns IPRT status code. + * @param hVfs The VFS to open the object within. + * @param pszPath Path to the file. + * @param fFileOpen RTFILE_O_XXX flags. + * @param fObjFlags More flags: RTVFSOBJ_F_XXX, RTPATH_F_XXX. + * @param phVfsObj Where to return the object handle. + * @sa RTVfsDirOpenObj, RTVfsDirOpenDir, RTVfsDirOpenFile + */ +RTDECL(int) RTVfsObjOpen(RTVFS hVfs, const char *pszPath, uint64_t fFileOpen, uint32_t fObjFlags, PRTVFSOBJ phVfsObj); + +/** + * 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); + +/** + * Sets the file mode for the given VFS object. + * + * @returns IPRT status code. + * @retval VERR_INVALID_FUNCTION if the object type has no file mode to set. + * Only directories, files and symbolic links support this operation. + * + * @param hVfsObj The VFS object handle. + * @param fMode The mode mask. + * @param fMask The bits in the mode mask which should be changed. + */ +RTDECL(int) RTVfsObjSetMode(RTVFSOBJ hVfsObj, RTFMODE fMode, RTFMODE fMask); + +/** + * Sets one or more timestamps for the given VFS object. + * + * @returns IPRT status code. + * @retval VERR_INVALID_FUNCTION if the object type has no file mode to set. + * Only directories, files and symbolic links support this operation. + * + * @param hVfsObj The VFS object 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) RTVfsObjSetTimes(RTVFSOBJ hVfsObj, PCRTTIMESPEC pAccessTime, PCRTTIMESPEC pModificationTime, + PCRTTIMESPEC pChangeTime, PCRTTIMESPEC pBirthTime); + +/** + * Set the unix style owner and group on the given VFS object. + * + * @returns IPRT status code. + * @retval VERR_INVALID_FUNCTION if the object type has no file mode to set. + * Only directories, files and symbolic links support this operation. + * + * @param hVfsObj The VFS object 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) RTVfsObjSetOwner(RTVFSOBJ hVfsObj, RTUID uid, RTGID gid); + + +/** + * Gets the type of a VFS object. + * + * @returns The VFS object type on success, RTVFSOBJTYPE_INVALID on failure. + * @param hVfsObj The VFS base object handle. + */ +RTDECL(RTVFSOBJTYPE) RTVfsObjGetType(RTVFSOBJ hVfsObj); + +/** + * 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_rt_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_rt_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 any file system 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 file. + * @param fFileOpen RTFILE_O_XXX flags. + * @param fObjFlags More flags: RTVFSOBJ_F_XXX, RTPATH_F_XXX. + * @param phVfsObj Where to return the object handle. + * @sa RTVfsObjOpen, RTVfsDirOpenDir, RTVfsDirOpenFile + */ +RTDECL(int) RTVfsDirOpenObj(RTVFSDIR hVfsDir, const char *pszPath, uint64_t fFileOpen, uint32_t fObjFlags, PRTVFSOBJ phVfsObj); + +/** + * 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); + +/** + * Creates a directory relative to @a hVfsDir. + * + * @returns IPRT status code + * @param hVfsDir The directory the path is relative to. + * @param pszRelPath The relative path to the new directory. + * @param fMode The file mode for the new directory. + * @param fFlags Directory creation flags, RTDIRCREATE_FLAGS_XXX. + * @param phVfsDir Where to return the handle to the newly created + * directory. Optional. + * @sa RTDirCreate, RTDirRelDirCreate + */ +RTDECL(int) RTVfsDirCreateDir(RTVFSDIR hVfsDir, const char *pszRelPath, RTFMODE fMode, uint32_t fFlags, PRTVFSDIR phVfsDir); + +/** + * Create a VFS directory handle from a standard IPRT directory handle (RTDIR). + * + * @returns IPRT status code. + * @param hDir The standard IPRT directory handle. + * @param fLeaveOpen Whether to leave the handle open when the VFS + * directory is released, or to close it (@c false). + * @param phVfsDir Where to return the VFS directory handle. + */ +RTDECL(int) RTVfsDirFromRTDir(RTDIR hDir, bool fLeaveOpen, PRTVFSDIR phVfsDir); + +/** + * RTDirOpen + RTVfsDirFromRTDir. + * + * @returns IPRT status code. + * @param pszPath The path to the directory. + * @param fFlags RTDIR_F_XXX. + * @param phVfsDir Where to return the VFS directory handle. + */ +RTDECL(int) RTVfsDirOpenNormal(const char *pszPath, uint32_t fFlags, PRTVFSDIR phVfsDir); + +/** Checks if @a hVfsDir was opened using RTVfsDirOpenNormal() or + * RTVfsDirFromRTDir(), either directly or indirectly. */ +RTDECL(bool) RTVfsDirIsStdDir(RTVFSDIR hVfsDir); + +/** + * 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); + +/** + * Removes a directory relative to @a hVfsDir. + * + * @returns IPRT status code. + * @param hVfsDir The VFS directory to start walking the @a pszRelPath + * relative to. + * @param pszRelPath The path to the directory that should be removed. + * @param fFlags Reserved, MBZ. + */ +RTDECL(int) RTVfsDirRemoveDir(RTVFSDIR hVfsDir, const char *pszRelPath, 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); + +/** + * Rewind and restart the directory reading. + * + * @returns IRPT status code. + * @param hVfsDir The VFS directory. + */ +RTDECL(int) RTVfsDirRewind(RTVFSDIR hVfsDir); + +/** @} */ + + +/** @defgroup grp_rt_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_rt_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) +/** @} */ + +/** + * Printf-like write function. + * + * @returns Number of characters written on success, negative error status on + * failure. + * @param hVfsIos The VFS I/O stream handle to write to. + * @param pszFormat The format string. + * @param ... Format arguments. + */ +RTDECL(ssize_t) RTVfsIoStrmPrintf(RTVFSIOSTREAM hVfsIos, const char *pszFormat, ...); + +/** + * Printf-like write function. + * + * @returns Number of characters written on success, negative error status on + * failure. + * @param hVfsIos The VFS I/O stream handle to write to. + * @param pszFormat The format string. + * @param va Format arguments. + */ +RTDECL(ssize_t) RTVfsIoStrmPrintfV(RTVFSIOSTREAM hVfsIos, const char *pszFormat, va_list va); + +/** + * VFS I/O stream output buffer structure to use with + * RTVfsIoStrmStrOutputCallback(). + */ +typedef struct VFSIOSTRMOUTBUF +{ + /** The I/O stream handle. */ + RTVFSIOSTREAM hVfsIos; + /** Size of this structure (for sanity). */ + size_t cbSelf; + /** Status code of the operation. */ + int rc; + /** Current offset into szBuf (number of output bytes pending). */ + size_t offBuf; + /** Modest output buffer. */ + char szBuf[256]; +} VFSIOSTRMOUTBUF; +/** Pointer to an VFS I/O stream output buffer for use with + * RTVfsIoStrmStrOutputCallback() */ +typedef VFSIOSTRMOUTBUF *PVFSIOSTRMOUTBUF; + +/** Initializer for a VFS I/O stream output buffer. */ +#define VFSIOSTRMOUTBUF_INIT(a_pOutBuf, a_hVfsIos) \ + do { \ + (a_pOutBuf)->hVfsIos = a_hVfsIos; \ + (a_pOutBuf)->cbSelf = sizeof(*(a_pOutBuf)); \ + (a_pOutBuf)->rc = VINF_SUCCESS; \ + (a_pOutBuf)->offBuf = 0; \ + (a_pOutBuf)->szBuf[0] = '\0'; \ + } while (0) + +/** + * @callback_method_impl{FNRTSTROUTPUT, + * For use with VFSIOSTRMOUTBUF. + * + * Users must use VFSIOSTRMOUTBUF_INIT to initialize a VFSIOSTRMOUTBUF and pass + * that as the outputter argument to the function this callback is handed to.} + */ +RTDECL(size_t) RTVfsIoStrmStrOutputCallback(void *pvArg, const char *pachChars, size_t cbChars); + +/** @} */ + + +/** @defgroup grp_rt_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 method. + * @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); + +/** + * Sets the size of a file. + * + * This may also be used for preallocating space + * (RTVFSFILE_SIZE_F_PREALLOC_KEEP_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 hVfsFile The VFS file handle. + * @param cbSize The new file size. + * @param fFlags RTVFSFILE_SIZE_F_NORMAL, RTVFSFILE_SIZE_F_GROW, or + * RTVFSFILE_SIZE_F_GROW_KEEP_SIZE. + * + * @sa RTFileSetSize, RTFileSetAllocationSize + */ +RTDECL(int) RTVfsFileSetSize(RTVFSFILE hVfsFile, uint64_t cbSize, uint32_t fFlags); + +/** @name RTVFSFILE_SIZE_F_XXX - RTVfsFileSetSize flags. + * @{ */ +/** Normal truncate or grow (zero'ed) like RTFileSetSize . */ +#define RTVFSFILE_SIZE_F_NORMAL UINT32_C(0x00000001) +/** Only grow the file, ignore call if cbSize would truncate the file. + * This is what RTFileSetAllocationSize does by default. */ +#define RTVFSFILE_SIZE_F_GROW UINT32_C(0x00000002) +/** Only grow the file, ignore call if cbSize would truncate the file. + * This is what RTFileSetAllocationSize does by default. */ +#define RTVFSFILE_SIZE_F_GROW_KEEP_SIZE UINT32_C(0x00000003) +/** Action mask. */ +#define RTVFSFILE_SIZE_F_ACTION_MASK UINT32_C(0x00000003) +/** Validate the flags. + * Will reference @a a_fFlags more than once. */ +#define RTVFSFILE_SIZE_F_IS_VALID(a_fFlags) \ + ( !((a_fFlags) & ~RTVFSFILE_SIZE_F_ACTION_MASK) && ((a_fFlags) & RTVFSFILE_SIZE_F_ACTION_MASK) != 0 ) +/** Mask of valid flags. */ +#define RTFILE_ALLOC_SIZE_F_VALID (RTFILE_ALLOC_SIZE_F_KEEP_SIZE) +/** @} */ + + +RTDECL(int) RTVfsFileQuerySize(RTVFSFILE hVfsFile, uint64_t *pcbSize); +RTDECL(RTFOFF) RTVfsFileGetMaxSize(RTVFSFILE hVfsFile); +RTDECL(int) RTVfsFileQueryMaxSize(RTVFSFILE hVfsFile, uint64_t *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); + +/** + * Printf-like write function. + * + * @returns Number of characters written on success, negative error status on + * failure. + * @param hVfsFile The VFS file handle to write to. + * @param pszFormat The format string. + * @param ... Format arguments. + */ +RTDECL(ssize_t) RTVfsFilePrintf(RTVFSFILE hVfsFile, const char *pszFormat, ...); + +/** + * Printf-like write function. + * + * @returns Number of characters written on success, negative error status on + * failure. + * @param hVfsFile The VFS file handle to write to. + * @param pszFormat The format string. + * @param va Format arguments. + */ +RTDECL(ssize_t) RTVfsFilePrintfV(RTVFSFILE hVfsFile, const char *pszFormat, va_list va); + +/** @} */ + + +#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_rt_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); + +/** + * Opens any kind of file system object. + * + * @returns IPRT status code. + * @param pszSpec The VFS chain specification or plain path. + * @param fFileOpen RTFILE_O_XXX flags. + * @param fObjFlags More flags: RTVFSOBJ_F_XXX, RTPATH_F_XXX. + * @param phVfsObj Where to return the handle to the opened object. + * @param poffError Where to on error return an offset into @a pszSpec + * of what cause the error. Optional. + * @param pErrInfo Where to return additional error information. + * Optional. + */ +RTDECL(int) RTVfsChainOpenObj(const char *pszSpec, uint64_t fFileOpen, uint32_t fObjFlags, + PRTVFSOBJ phVfsObj, uint32_t *poffError, PRTERRINFO pErrInfo); + +RTDECL(int) RTVfsChainOpenDir(const char *pszSpec, uint32_t fOpen, PRTVFSDIR phVfsDir, uint32_t *poffError, PRTERRINFO pErrInfo); +RTDECL(int) RTVfsChainOpenParentDir(const char *pszSpec, uint32_t fOpen, PRTVFSDIR phVfsDir, const char **ppszChild, + 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); + +/** + * Splits the given chain spec into a final path and the preceeding spec. + * + * This works on plain paths too. + * + * @returns IPRT status code. + * @param pszSpec The chain spec to split. This will be modified! + * @param ppszSpec Where to return the pointer to the chain spec part. + * This is set to NULL if it's a plain path or a chain + * spec with only a final-path element. + * @param ppszFinalPath Where to return the pointer to the final path. This + * is set to NULL if no final path. + * @param poffError Where to on error return an offset into @a pszSpec + * of what cause the error. Optional. + */ +RTDECL(int) RTVfsChainSplitOffFinalPath(char *pszSpec, char **ppszSpec, 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_INCLUDED_vfs_h */ + |