horok/virtualbox
1
0
Fork 0
Code Activity
virtualbox/include/iprt/vfs.h
Daniel Baumann df1bda4fe9
Adding upstream version 7.0.20-dfsg. 
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
2025-06-22 09:56:04 +02:00

2021 lines
82 KiB
C
Raw Permalink Blame History

/** @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 */
View git blame Copy permalink