vfs.h revision 43af8389304c77c3d4db525de8907cb74207c380
45916cd2fec6e79bca5dee0421bd39e3c2910d1ejpk/** @file
45916cd2fec6e79bca5dee0421bd39e3c2910d1ejpk * IPRT - Virtual Filesystem.
45916cd2fec6e79bca5dee0421bd39e3c2910d1ejpk */
45916cd2fec6e79bca5dee0421bd39e3c2910d1ejpk
45916cd2fec6e79bca5dee0421bd39e3c2910d1ejpk/*
45916cd2fec6e79bca5dee0421bd39e3c2910d1ejpk * Copyright (C) 2010 Oracle Corporation
45916cd2fec6e79bca5dee0421bd39e3c2910d1ejpk *
45916cd2fec6e79bca5dee0421bd39e3c2910d1ejpk * This file is part of VirtualBox Open Source Edition (OSE), as
45916cd2fec6e79bca5dee0421bd39e3c2910d1ejpk * available from http://www.virtualbox.org. This file is free software;
45916cd2fec6e79bca5dee0421bd39e3c2910d1ejpk * you can redistribute it and/or modify it under the terms of the GNU
45916cd2fec6e79bca5dee0421bd39e3c2910d1ejpk * General Public License (GPL) as published by the Free Software
45916cd2fec6e79bca5dee0421bd39e3c2910d1ejpk * Foundation, in version 2 as it comes in the "COPYING" file of the
45916cd2fec6e79bca5dee0421bd39e3c2910d1ejpk * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
45916cd2fec6e79bca5dee0421bd39e3c2910d1ejpk * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
45916cd2fec6e79bca5dee0421bd39e3c2910d1ejpk *
45916cd2fec6e79bca5dee0421bd39e3c2910d1ejpk * The contents of this file may alternatively be used under the terms
45916cd2fec6e79bca5dee0421bd39e3c2910d1ejpk * of the Common Development and Distribution License Version 1.0
45916cd2fec6e79bca5dee0421bd39e3c2910d1ejpk * (CDDL) only, as it comes in the "COPYING.CDDL" file of the
45916cd2fec6e79bca5dee0421bd39e3c2910d1ejpk * VirtualBox OSE distribution, in which case the provisions of the
45916cd2fec6e79bca5dee0421bd39e3c2910d1ejpk * CDDL are applicable instead of those of the GPL.
45916cd2fec6e79bca5dee0421bd39e3c2910d1ejpk *
45916cd2fec6e79bca5dee0421bd39e3c2910d1ejpk * You may elect to license modified versions of this file under the
45916cd2fec6e79bca5dee0421bd39e3c2910d1ejpk * terms and conditions of either the GPL or the CDDL or both.
45916cd2fec6e79bca5dee0421bd39e3c2910d1ejpk */
45916cd2fec6e79bca5dee0421bd39e3c2910d1ejpk
45916cd2fec6e79bca5dee0421bd39e3c2910d1ejpk#ifndef ___iprt_vfs_h
45916cd2fec6e79bca5dee0421bd39e3c2910d1ejpk#define ___iprt_vfs_h
45916cd2fec6e79bca5dee0421bd39e3c2910d1ejpk
45916cd2fec6e79bca5dee0421bd39e3c2910d1ejpk#include <iprt/cdefs.h>
45916cd2fec6e79bca5dee0421bd39e3c2910d1ejpk#include <iprt/types.h>
45916cd2fec6e79bca5dee0421bd39e3c2910d1ejpk#include <iprt/dir.h>
45916cd2fec6e79bca5dee0421bd39e3c2910d1ejpk#include <iprt/fs.h>
45916cd2fec6e79bca5dee0421bd39e3c2910d1ejpk#include <iprt/handle.h>
45916cd2fec6e79bca5dee0421bd39e3c2910d1ejpk#include <iprt/symlink.h>
45916cd2fec6e79bca5dee0421bd39e3c2910d1ejpk#include <iprt/sg.h>
45916cd2fec6e79bca5dee0421bd39e3c2910d1ejpk#include <iprt/time.h>
45916cd2fec6e79bca5dee0421bd39e3c2910d1ejpk
45916cd2fec6e79bca5dee0421bd39e3c2910d1ejpk
45916cd2fec6e79bca5dee0421bd39e3c2910d1ejpkRT_C_DECLS_BEGIN
45916cd2fec6e79bca5dee0421bd39e3c2910d1ejpk
45916cd2fec6e79bca5dee0421bd39e3c2910d1ejpk/** @defgroup grp_rt_fs RTVfs - Virtual Filesystem
45916cd2fec6e79bca5dee0421bd39e3c2910d1ejpk * @ingroup grp_rt
45916cd2fec6e79bca5dee0421bd39e3c2910d1ejpk *
45916cd2fec6e79bca5dee0421bd39e3c2910d1ejpk * The virtual filesystem APIs are intended to make it possible to work on
45916cd2fec6e79bca5dee0421bd39e3c2910d1ejpk * container files, file system sub-trees, file system overlays and other custom
45916cd2fec6e79bca5dee0421bd39e3c2910d1ejpk * filesystem configurations. It also makes it possible to create filters, like
45916cd2fec6e79bca5dee0421bd39e3c2910d1ejpk * automatically gunzipping a tar.gz file before feeding it to the RTTar API for
45916cd2fec6e79bca5dee0421bd39e3c2910d1ejpk * unpacking - or wise versa.
45916cd2fec6e79bca5dee0421bd39e3c2910d1ejpk *
45916cd2fec6e79bca5dee0421bd39e3c2910d1ejpk * The virtual filesystem APIs are intended to mirror the RTDir, RTFile, RTPath
45916cd2fec6e79bca5dee0421bd39e3c2910d1ejpk * and RTFs APIs pretty closely so that rewriting a piece of code to work with
45916cd2fec6e79bca5dee0421bd39e3c2910d1ejpk * it should be easy. However there are some differences to the way the APIs
45916cd2fec6e79bca5dee0421bd39e3c2910d1ejpk * works and the user should heed the documentation. The differences are
45916cd2fec6e79bca5dee0421bd39e3c2910d1ejpk * usually motivated by simplification and in some case to make the VFS more
45916cd2fec6e79bca5dee0421bd39e3c2910d1ejpk * flexible.
45916cd2fec6e79bca5dee0421bd39e3c2910d1ejpk *
45916cd2fec6e79bca5dee0421bd39e3c2910d1ejpk * @{
45916cd2fec6e79bca5dee0421bd39e3c2910d1ejpk */
45916cd2fec6e79bca5dee0421bd39e3c2910d1ejpk
45916cd2fec6e79bca5dee0421bd39e3c2910d1ejpk/**
45916cd2fec6e79bca5dee0421bd39e3c2910d1ejpk * The object type.
45916cd2fec6e79bca5dee0421bd39e3c2910d1ejpk */
45916cd2fec6e79bca5dee0421bd39e3c2910d1ejpktypedef enum RTVFSOBJTYPE
45916cd2fec6e79bca5dee0421bd39e3c2910d1ejpk{
45916cd2fec6e79bca5dee0421bd39e3c2910d1ejpk /** Invalid type. */
45916cd2fec6e79bca5dee0421bd39e3c2910d1ejpk RTVFSOBJTYPE_INVALID = 0,
45916cd2fec6e79bca5dee0421bd39e3c2910d1ejpk /** Pure base object.
45916cd2fec6e79bca5dee0421bd39e3c2910d1ejpk * This is returned by the filesystem stream to represent directories,
45916cd2fec6e79bca5dee0421bd39e3c2910d1ejpk * devices, fifos and similar that needs to be created. */
45916cd2fec6e79bca5dee0421bd39e3c2910d1ejpk RTVFSOBJTYPE_BASE,
45916cd2fec6e79bca5dee0421bd39e3c2910d1ejpk /** Virtual filesystem. */
45916cd2fec6e79bca5dee0421bd39e3c2910d1ejpk RTVFSOBJTYPE_VFS,
45916cd2fec6e79bca5dee0421bd39e3c2910d1ejpk /** Filesystem stream. */
45916cd2fec6e79bca5dee0421bd39e3c2910d1ejpk RTVFSOBJTYPE_FS_STREAM,
45916cd2fec6e79bca5dee0421bd39e3c2910d1ejpk /** Pure I/O stream. */
45916cd2fec6e79bca5dee0421bd39e3c2910d1ejpk RTVFSOBJTYPE_IO_STREAM,
45916cd2fec6e79bca5dee0421bd39e3c2910d1ejpk /** Directory. */
45916cd2fec6e79bca5dee0421bd39e3c2910d1ejpk RTVFSOBJTYPE_DIR,
45916cd2fec6e79bca5dee0421bd39e3c2910d1ejpk /** File. */
45916cd2fec6e79bca5dee0421bd39e3c2910d1ejpk RTVFSOBJTYPE_FILE,
45916cd2fec6e79bca5dee0421bd39e3c2910d1ejpk /** Symbolic link. */
45916cd2fec6e79bca5dee0421bd39e3c2910d1ejpk RTVFSOBJTYPE_SYMLINK,
45916cd2fec6e79bca5dee0421bd39e3c2910d1ejpk /** End of valid object types. */
45916cd2fec6e79bca5dee0421bd39e3c2910d1ejpk RTVFSOBJTYPE_END,
45916cd2fec6e79bca5dee0421bd39e3c2910d1ejpk /** Pure I/O stream. */
45916cd2fec6e79bca5dee0421bd39e3c2910d1ejpk RTVFSOBJTYPE_32BIT_HACK = 0x7fffffff
45916cd2fec6e79bca5dee0421bd39e3c2910d1ejpk} RTVFSOBJTYPE;
45916cd2fec6e79bca5dee0421bd39e3c2910d1ejpk/** Pointer to a VFS object type. */
45916cd2fec6e79bca5dee0421bd39e3c2910d1ejpktypedef RTVFSOBJTYPE *PRTVFSOBJTYPE;
45916cd2fec6e79bca5dee0421bd39e3c2910d1ejpk
45916cd2fec6e79bca5dee0421bd39e3c2910d1ejpk
45916cd2fec6e79bca5dee0421bd39e3c2910d1ejpk
45916cd2fec6e79bca5dee0421bd39e3c2910d1ejpk/** @name RTVfsCreate flags
45916cd2fec6e79bca5dee0421bd39e3c2910d1ejpk * @{ */
45916cd2fec6e79bca5dee0421bd39e3c2910d1ejpk/** Whether the file system is read-only. */
45916cd2fec6e79bca5dee0421bd39e3c2910d1ejpk#define RTVFS_C_READONLY RT_BIT(0)
45916cd2fec6e79bca5dee0421bd39e3c2910d1ejpk/** Whether we the VFS should be thread safe (i.e. automaticaly employ
45916cd2fec6e79bca5dee0421bd39e3c2910d1ejpk * locks). */
45916cd2fec6e79bca5dee0421bd39e3c2910d1ejpk#define RTVFS_C_THREAD_SAFE RT_BIT(1)
45916cd2fec6e79bca5dee0421bd39e3c2910d1ejpk/** @} */
45916cd2fec6e79bca5dee0421bd39e3c2910d1ejpk
45916cd2fec6e79bca5dee0421bd39e3c2910d1ejpk/**
45916cd2fec6e79bca5dee0421bd39e3c2910d1ejpk * Creates an empty virtual filesystem.
45916cd2fec6e79bca5dee0421bd39e3c2910d1ejpk *
45916cd2fec6e79bca5dee0421bd39e3c2910d1ejpk * @returns IPRT status code.
45916cd2fec6e79bca5dee0421bd39e3c2910d1ejpk * @param pszName Name, for logging and such.
45916cd2fec6e79bca5dee0421bd39e3c2910d1ejpk * @param fFlags Flags, MBZ.
45916cd2fec6e79bca5dee0421bd39e3c2910d1ejpk * @param phVfs Where to return the VFS handle. Release the returned
45916cd2fec6e79bca5dee0421bd39e3c2910d1ejpk * reference by calling RTVfsRelease.
45916cd2fec6e79bca5dee0421bd39e3c2910d1ejpk */
45916cd2fec6e79bca5dee0421bd39e3c2910d1ejpkRTDECL(int) RTVfsCreate(const char *pszName, uint32_t fFlags, PRTVFS phVfs);
45916cd2fec6e79bca5dee0421bd39e3c2910d1ejpkRTDECL(uint32_t) RTVfsRetain(RTVFS phVfs);
45916cd2fec6e79bca5dee0421bd39e3c2910d1ejpkRTDECL(uint32_t) RTVfsRelease(RTVFS phVfs);
45916cd2fec6e79bca5dee0421bd39e3c2910d1ejpkRTDECL(int) RTVfsAttach(RTVFS hVfs, const char *pszMountPoint, uint32_t fFlags, RTVFS hVfsAttach);
45916cd2fec6e79bca5dee0421bd39e3c2910d1ejpkRTDECL(int) RTVfsDetach(RTVFS hVfs, const char *pszMountPoint, RTVFS hVfsToDetach, PRTVFS *phVfsDetached);
45916cd2fec6e79bca5dee0421bd39e3c2910d1ejpkRTDECL(uint32_t) RTVfsGetAttachmentCount(RTVFS hVfs);
RTDECL(int) RTVfsGetAttachment(RTVFS hVfs, uint32_t iOrdinal, PRTVFS *phVfsAttached, uint32_t *pfFlags,
char *pszMountPoint, size_t cbMountPoint);
/** @defgroup grp_vfs_dir 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);
/**
* Releases a reference to the VFS base handle.
*
* @returns New reference count on success (0 if closed), UINT32_MAX on failure.
* @param hVfsObj The VFS base object handle.
*/
RTDECL(uint32_t) RTVfsObjRelease(RTVFSOBJ hVfsObj);
/**
* Query information about the object.
*
* @returns IPRT status code.
* @retval VERR_NOT_SUPPORTED if the @a enmAddAttr value is not handled by the
* implementation.
*
* @param hVfsObj The VFS object handle.
* @param pObjInfo Where to return the info.
* @param enmAddAttr Which additional attributes should be retrieved.
* @sa RTFileQueryInfo, RTPathQueryInfo
*/
RTDECL(int) RTVfsObjQueryInfo(RTVFSOBJ hVfsObj, PRTFSOBJINFO pObjInfo, RTFSOBJATTRADD enmAddAttr);
/**
* Converts a VFS base object handle to a VFS handle.
*
* @returns Referenced handle on success, NIL on failure.
* @param hVfsObj The VFS base object handle.
*/
RTDECL(RTVFS) RTVfsObjToVfs(RTVFSOBJ hVfsObj);
/**
* Converts a VFS base object handle to a VFS filesystem stream handle.
*
* @returns Referenced handle on success, NIL on failure.
* @param hVfsObj The VFS base object handle.
*/
RTDECL(RTVFSFSSTREAM) RTVfsObjToFsStream(RTVFSOBJ hVfsObj);
/**
* Converts a VFS base object handle to a VFS directory handle.
*
* @returns Referenced handle on success, NIL on failure.
* @param hVfsObj The VFS base object handle.
*/
RTDECL(RTVFSDIR) RTVfsObjToDir(RTVFSOBJ hVfsObj);
/**
* Converts a VFS base object handle to a VFS I/O stream handle.
*
* @returns Referenced handle on success, NIL on failure.
* @param hVfsObj The VFS base object handle.
*/
RTDECL(RTVFSIOSTREAM) RTVfsObjToIoStream(RTVFSOBJ hVfsObj);
/**
* Converts a VFS base object handle to a VFS file handle.
*
* @returns Referenced handle on success, NIL on failure.
* @param hVfsObj The VFS base object handle.
*/
RTDECL(RTVFSFILE) RTVfsObjToFile(RTVFSOBJ hVfsObj);
/**
* Converts a VFS base object handle to a VFS symbolic link handle.
*
* @returns Referenced handle on success, NIL on failure.
* @param hVfsObj The VFS base object handle.
*/
RTDECL(RTVFSSYMLINK) RTVfsObjToSymlink(RTVFSOBJ hVfsObj);
/**
* Converts a VFS handle to a VFS base object handle.
*
* @returns Referenced handle on success, NIL if the input handle was invalid.
* @param hVfs The VFS handle.
*/
RTDECL(RTVFSOBJ) RTVfsObjFromVfs(RTVFS hVfs);
/**
* Converts a VFS filesystem stream handle to a VFS base object handle.
*
* @returns Referenced handle on success, NIL if the input handle was invalid.
* @param hVfsFSs The VFS filesystem stream handle.
*/
RTDECL(RTVFSOBJ) RTVfsObjFromFsStream(RTVFSFSSTREAM hVfsFss);
/**
* Converts a VFS directory handle to a VFS base object handle.
*
* @returns Referenced handle on success, NIL if the input handle was invalid.
* @param hVfsDir The VFS directory handle.
*/
RTDECL(RTVFSOBJ) RTVfsObjFromDir(RTVFSDIR hVfsDir);
/**
* Converts a VFS I/O stream handle to a VFS base object handle.
*
* @returns Referenced handle on success, NIL if the input handle was invalid.
* @param hVfsIos The VFS I/O stream handle.
*/
RTDECL(RTVFSOBJ) RTVfsObjFromIoStream(RTVFSIOSTREAM hVfsIos);
/**
* Converts a VFS file handle to a VFS base object handle.
*
* @returns Referenced handle on success, NIL if the input handle was invalid.
* @param hVfsFile The VFS file handle.
*/
RTDECL(RTVFSOBJ) RTVfsObjFromFile(RTVFSFILE hVfsFile);
/**
* Converts a VFS symbolic link handle to a VFS base object handle.
*
* @returns Referenced handle on success, NIL if the input handle was invalid.
* @param hVfsSym The VFS symbolic link handle.
*/
RTDECL(RTVFSOBJ) RTVfsObjFromSymlink(RTVFSSYMLINK hVfsSym);
/** @} */
/** @defgroup grp_vfs_fsstream VFS Filesystem Stream API
*
* Filesystem streams are for tar, cpio and similar. Any virtual filesystem can
* be turned into a filesystem stream using RTVfsFsStrmFromVfs.
*
* @{
*/
RTDECL(uint32_t) RTVfsFsStrmRetain(RTVFSFSSTREAM hVfsFss);
RTDECL(uint32_t) 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.
*
* @param pvThis The implementation specific directory data.
* @param ppszName Where to return the object name. Must be freed by
* calling RTStrFree.
* @param penmType Where to return the object type.
* @param hVfsObj Where to return the object handle (referenced).
* This must be cast to the desired type before use.
*/
RTDECL(int) RTVfsFsStrmNext(RTVFSFSSTREAM hVfsFss, char **ppszName, RTVFSOBJTYPE *penmType, PRTVFSOBJ phVfsObj);
/** @} */
/** @defgroup grp_vfs_dir VFS Directory API
* @{
*/
/**
* Retains a reference to the VFS directory handle.
*
* @returns New reference count on success, UINT32_MAX on failure.
* @param hVfsDir The VFS directory handle.
*/
RTDECL(uint32_t) RTVfsDirRetain(RTVFSDIR hVfsDir);
/**
* Releases a reference to the VFS directory handle.
*
* @returns New reference count on success (0 if closed), UINT32_MAX on failure.
* @param hVfsIos The VFS directory handle.
*/
RTDECL(uint32_t) RTVfsDirRelease(RTVFSDIR hVfsDir);
/** @} */
/** @defgroup grp_vfs_iostream VFS Symbolic Link API
* @{
*/
RTDECL(uint32_t) RTVfsSymlinkRetain(RTVFSSYMLINK hVfsSym);
RTDECL(uint32_t) RTVfsSymlinkRelease(RTVFSSYMLINK hVfsSym);
/**
* Read the symbolic link target.
*
* @returns IPRT status code.
* @param hVfsSym The VFS symbolic link handle.
* @param pszTarget The target buffer.
* @param cbTarget The size of the target buffer.
* @sa RTSymlinkRead
*/
RTDECL(int) RTVfsSymlinkRead(RTVFSSYMLINK hVfsSym, char *pszTarget, size_t cbTarget);
/** @} */
/** @defgroup grp_vfs_iostream VFS I/O Stream API
* @{
*/
/**
* Create 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, uint32_t fOpen, bool fLeaveOpen, 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, uint32_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);
/**
* 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 RTFileRead, RTPipeRead, RTPipeReadBlocking, RTSocketRead
*/
RTDECL(int) RTVfsIoStrmRead(RTVFSIOSTREAM hVfsIos, void *pvBuf, size_t cbToRead, bool fBlocking, size_t *pcbRead);
/**
* 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 pcbRead Where to always store the number of bytes actually
* written. This can be NULL if @a fBlocking is true.
* @sa RTFileWrite, RTPipeWrite, RTPipeWriteBlocking, RTSocketWrite
*/
RTDECL(int) RTVfsIoStrmWrite(RTVFSIOSTREAM hVfsIos, 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 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, 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 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 pcbRead 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, 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 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 RTPollSetAdd, RTPoll, RTPollNoResume.
*/
RTDECL(RTFOFF) 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);
/** @} */
/** @defgroup grp_vfs_file VFS File API
* @{
*/
RTDECL(int) RTVfsFileOpen(RTVFS hVfs, const char *pszFilename, uint32_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, uint32_t fOpen, bool fLeaveOpen, PRTVFSFILE phVfsFile);
RTDECL(RTHCUINTPTR) RTVfsFileToNative(RTFILE hVfsFile);
/**
* 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);
/**
* 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);
RTDECL(int) RTVfsFileQueryInfo(RTVFSFILE hVfsFile, PRTFSOBJINFO pObjInfo, RTFSOBJATTRADD enmAddAttr);
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);
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);
RTDECL(int) RTVfsFileFlush(RTVFSFILE hVfsFile);
RTDECL(RTFOFF) RTVfsFilePoll(RTVFSFILE hVfsFile, uint32_t fEvents, RTMSINTERVAL cMillies, bool fIntr,
uint32_t *pfRetEvents);
RTDECL(RTFOFF) RTVfsFileTell(RTVFSFILE hVfsFile);
RTDECL(int) RTVfsFileSeek(RTVFSFILE hVfsFile, RTFOFF offSeek, uint32_t uMethod, uint64_t *poffActual);
RTDECL(int) RTVfsFileSetSize(RTVFSFILE hVfsFile, uint64_t cbSize);
RTDECL(int) RTVfsFileGetSize(RTVFSFILE hVfsFile, uint64_t *pcbSize);
RTDECL(RTFOFF) RTVfsFileGetMaxSize(RTVFSFILE hVfsFile);
RTDECL(int) RTVfsFileGetMaxSizeEx(RTVFSFILE hVfsFile, PRTFOFF pcbMax);
/** @} */
/** @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:vfs(isofs,./mycd.iso)|ios(open,readme.gz)|ios(gunzip)
* or
* RTCat :iprtvfs:ios(isofs,./mycd.iso,/readme.gz)|ios(gunzip)
*
* The "isofs", "open" and "gunzip" bits in the above examples are chain
* element providers registered with IPRT. See RTVFSCHAINELEMENTREG for how
* these works.
*
* @{ */
/** The path prefix used to identify an VFS chain specification. */
#define RTVFSCHAIN_SPEC_PREFIX ":iprtvfs:"
RTDECL(int) RTVfsChainOpenVfs( const char *pszSpec, PRTVFS phVfs, const char **ppszError);
RTDECL(int) RTVfsChainOpenFsStream( const char *pszSpec, PRTVFSFSSTREAM phVfsFss, const char **ppszError);
RTDECL(int) RTVfsChainOpenDir( const char *pszSpec, uint32_t fOpen, PRTVFSDIR phVfsDir, const char **ppszError);
RTDECL(int) RTVfsChainOpenFile( const char *pszSpec, uint32_t fOpen, PRTVFSFILE phVfsFile, const char **ppszError);
RTDECL(int) RTVfsChainOpenSymlink( const char *pszSpec, PRTVFSSYMLINK phVfsSym, const char **ppszError);
RTDECL(int) RTVfsChainOpenIoStream( const char *pszSpec, uint32_t fOpen, PRTVFSIOSTREAM phVfsIos, const char **ppszError);
/**
* 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);
/** @} */
/** @} */
RT_C_DECLS_END
#endif /* !___iprt_vfs_h */