[33820] | 1 | /** @file
|
---|
| 2 | * IPRT - Virtual Filesystem.
|
---|
| 3 | */
|
---|
| 4 |
|
---|
| 5 | /*
|
---|
[76553] | 6 | * Copyright (C) 2010-2019 Oracle Corporation
|
---|
[33820] | 7 | *
|
---|
| 8 | * This file is part of VirtualBox Open Source Edition (OSE), as
|
---|
| 9 | * available from http://www.virtualbox.org. This file is free software;
|
---|
| 10 | * you can redistribute it and/or modify it under the terms of the GNU
|
---|
| 11 | * General Public License (GPL) as published by the Free Software
|
---|
| 12 | * Foundation, in version 2 as it comes in the "COPYING" file of the
|
---|
| 13 | * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
|
---|
| 14 | * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
|
---|
| 15 | *
|
---|
| 16 | * The contents of this file may alternatively be used under the terms
|
---|
| 17 | * of the Common Development and Distribution License Version 1.0
|
---|
| 18 | * (CDDL) only, as it comes in the "COPYING.CDDL" file of the
|
---|
| 19 | * VirtualBox OSE distribution, in which case the provisions of the
|
---|
| 20 | * CDDL are applicable instead of those of the GPL.
|
---|
| 21 | *
|
---|
| 22 | * You may elect to license modified versions of this file under the
|
---|
| 23 | * terms and conditions of either the GPL or the CDDL or both.
|
---|
| 24 | */
|
---|
| 25 |
|
---|
[76557] | 26 | #ifndef IPRT_INCLUDED_vfs_h
|
---|
| 27 | #define IPRT_INCLUDED_vfs_h
|
---|
[76507] | 28 | #ifndef RT_WITHOUT_PRAGMA_ONCE
|
---|
| 29 | # pragma once
|
---|
| 30 | #endif
|
---|
[33820] | 31 |
|
---|
| 32 | #include <iprt/cdefs.h>
|
---|
| 33 | #include <iprt/types.h>
|
---|
| 34 | #include <iprt/dir.h>
|
---|
| 35 | #include <iprt/fs.h>
|
---|
[33973] | 36 | #include <iprt/handle.h>
|
---|
[33820] | 37 | #include <iprt/symlink.h>
|
---|
| 38 | #include <iprt/sg.h>
|
---|
| 39 | #include <iprt/time.h>
|
---|
| 40 |
|
---|
| 41 |
|
---|
| 42 | RT_C_DECLS_BEGIN
|
---|
| 43 |
|
---|
[36511] | 44 | /** @defgroup grp_rt_vfs RTVfs - Virtual Filesystem
|
---|
[33820] | 45 | * @ingroup grp_rt
|
---|
[33822] | 46 | *
|
---|
| 47 | * The virtual filesystem APIs are intended to make it possible to work on
|
---|
| 48 | * container files, file system sub-trees, file system overlays and other custom
|
---|
| 49 | * filesystem configurations. It also makes it possible to create filters, like
|
---|
| 50 | * automatically gunzipping a tar.gz file before feeding it to the RTTar API for
|
---|
| 51 | * unpacking - or wise versa.
|
---|
| 52 | *
|
---|
| 53 | * The virtual filesystem APIs are intended to mirror the RTDir, RTFile, RTPath
|
---|
| 54 | * and RTFs APIs pretty closely so that rewriting a piece of code to work with
|
---|
| 55 | * it should be easy. However there are some differences to the way the APIs
|
---|
| 56 | * works and the user should heed the documentation. The differences are
|
---|
| 57 | * usually motivated by simplification and in some case to make the VFS more
|
---|
| 58 | * flexible.
|
---|
| 59 | *
|
---|
[33820] | 60 | * @{
|
---|
| 61 | */
|
---|
| 62 |
|
---|
[33948] | 63 | /**
|
---|
| 64 | * The object type.
|
---|
| 65 | */
|
---|
| 66 | typedef enum RTVFSOBJTYPE
|
---|
| 67 | {
|
---|
| 68 | /** Invalid type. */
|
---|
| 69 | RTVFSOBJTYPE_INVALID = 0,
|
---|
| 70 | /** Pure base object.
|
---|
| 71 | * This is returned by the filesystem stream to represent directories,
|
---|
| 72 | * devices, fifos and similar that needs to be created. */
|
---|
| 73 | RTVFSOBJTYPE_BASE,
|
---|
| 74 | /** Virtual filesystem. */
|
---|
| 75 | RTVFSOBJTYPE_VFS,
|
---|
| 76 | /** Filesystem stream. */
|
---|
| 77 | RTVFSOBJTYPE_FS_STREAM,
|
---|
| 78 | /** Pure I/O stream. */
|
---|
| 79 | RTVFSOBJTYPE_IO_STREAM,
|
---|
| 80 | /** Directory. */
|
---|
| 81 | RTVFSOBJTYPE_DIR,
|
---|
| 82 | /** File. */
|
---|
| 83 | RTVFSOBJTYPE_FILE,
|
---|
| 84 | /** Symbolic link. */
|
---|
| 85 | RTVFSOBJTYPE_SYMLINK,
|
---|
| 86 | /** End of valid object types. */
|
---|
| 87 | RTVFSOBJTYPE_END,
|
---|
| 88 | /** Pure I/O stream. */
|
---|
| 89 | RTVFSOBJTYPE_32BIT_HACK = 0x7fffffff
|
---|
| 90 | } RTVFSOBJTYPE;
|
---|
| 91 | /** Pointer to a VFS object type. */
|
---|
| 92 | typedef RTVFSOBJTYPE *PRTVFSOBJTYPE;
|
---|
[33820] | 93 |
|
---|
[33948] | 94 |
|
---|
| 95 |
|
---|
[33820] | 96 | /** @name RTVfsCreate flags
|
---|
| 97 | * @{ */
|
---|
| 98 | /** Whether the file system is read-only. */
|
---|
| 99 | #define RTVFS_C_READONLY RT_BIT(0)
|
---|
| 100 | /** Whether we the VFS should be thread safe (i.e. automaticaly employ
|
---|
| 101 | * locks). */
|
---|
| 102 | #define RTVFS_C_THREAD_SAFE RT_BIT(1)
|
---|
| 103 | /** @} */
|
---|
| 104 |
|
---|
| 105 | /**
|
---|
| 106 | * Creates an empty virtual filesystem.
|
---|
| 107 | *
|
---|
| 108 | * @returns IPRT status code.
|
---|
| 109 | * @param pszName Name, for logging and such.
|
---|
| 110 | * @param fFlags Flags, MBZ.
|
---|
| 111 | * @param phVfs Where to return the VFS handle. Release the returned
|
---|
| 112 | * reference by calling RTVfsRelease.
|
---|
| 113 | */
|
---|
| 114 | RTDECL(int) RTVfsCreate(const char *pszName, uint32_t fFlags, PRTVFS phVfs);
|
---|
[66740] | 115 | RTDECL(uint32_t) RTVfsRetain(RTVFS hVfs);
|
---|
| 116 | RTDECL(uint32_t) RTVfsRetainDebug(RTVFS hVfs, RT_SRC_POS_DECL);
|
---|
| 117 | RTDECL(uint32_t) RTVfsRelease(RTVFS hVfs);
|
---|
[69840] | 118 |
|
---|
| 119 | /** @name RTVFSMNT_F_XXX - Flags for RTVfsMount
|
---|
| 120 | * @{ */
|
---|
| 121 | /** Mount read-only. */
|
---|
| 122 | #define RTVFSMNT_F_READ_ONLY RT_BIT_32(0)
|
---|
| 123 | /** Purpose is . */
|
---|
| 124 | #define RTVFSMNT_F_FOR_RANGE_IN_USE RT_BIT_32(1)
|
---|
| 125 | /** Valid mask. */
|
---|
| 126 | #define RTVFSMNT_F_VALID_MASK UINT32_C(0x00000003)
|
---|
| 127 | /** @} */
|
---|
| 128 |
|
---|
| 129 | /**
|
---|
| 130 | * Does the file system detection and mounting.
|
---|
| 131 | *
|
---|
| 132 | * @returns IPRT status code.
|
---|
| 133 | * @retval VERR_VFS_UNSUPPORTED_FORMAT if not recognized as a support file
|
---|
| 134 | * system.
|
---|
| 135 | * @param hVfsFileIn The file handle of the volume.
|
---|
| 136 | * @param fFlags RTVFSMTN_F_XXX.
|
---|
| 137 | * @param phVfs Where to return the VFS handle on success.
|
---|
| 138 | * @param pErrInfo Where to return additional error information.
|
---|
| 139 | * Optional.
|
---|
| 140 | */
|
---|
| 141 | RTDECL(int) RTVfsMountVol(RTVFSFILE hVfsFileIn, uint32_t fFlags, PRTVFS phVfs, PRTERRINFO pErrInfo);
|
---|
| 142 |
|
---|
[33820] | 143 | RTDECL(int) RTVfsAttach(RTVFS hVfs, const char *pszMountPoint, uint32_t fFlags, RTVFS hVfsAttach);
|
---|
| 144 | RTDECL(int) RTVfsDetach(RTVFS hVfs, const char *pszMountPoint, RTVFS hVfsToDetach, PRTVFS *phVfsDetached);
|
---|
| 145 | RTDECL(uint32_t) RTVfsGetAttachmentCount(RTVFS hVfs);
|
---|
| 146 | RTDECL(int) RTVfsGetAttachment(RTVFS hVfs, uint32_t iOrdinal, PRTVFS *phVfsAttached, uint32_t *pfFlags,
|
---|
| 147 | char *pszMountPoint, size_t cbMountPoint);
|
---|
| 148 |
|
---|
[41549] | 149 | /**
|
---|
[70395] | 150 | * Opens the root director of the given VFS.
|
---|
| 151 | *
|
---|
| 152 | * @returns IPRT status code.
|
---|
| 153 | * @param hVfs VFS handle.
|
---|
| 154 | * @param phDir Where to return the root directory handle.
|
---|
| 155 | */
|
---|
| 156 | RTDECL(int) RTVfsOpenRoot(RTVFS hVfs, PRTVFSDIR phDir);
|
---|
| 157 |
|
---|
| 158 | /**
|
---|
[66762] | 159 | * Queries information about a object in the virtual filesystem.
|
---|
| 160 | *
|
---|
| 161 | * @returns IPRT Status code.
|
---|
| 162 | * @param hVfs VFS handle.
|
---|
| 163 | * @param pszPath Path to the object, relative to the VFS root.
|
---|
| 164 | * @param pObjInfo Where to return info.
|
---|
| 165 | * @param enmAddAttr What to return.
|
---|
| 166 | * @param fFlags RTPATH_F_XXX.
|
---|
| 167 | * @sa RTPathQueryInfoEx, RTVfsDirQueryPathInfo, RTVfsObjQueryInfo
|
---|
| 168 | */
|
---|
| 169 | RTDECL(int) RTVfsQueryPathInfo(RTVFS hVfs, const char *pszPath, PRTFSOBJINFO pObjInfo,
|
---|
| 170 | RTFSOBJATTRADD enmAddAttr, uint32_t fFlags);
|
---|
| 171 |
|
---|
| 172 | /**
|
---|
[41549] | 173 | * Checks whether a given range is in use by the virtual filesystem.
|
---|
| 174 | *
|
---|
| 175 | * @returns IPRT status code.
|
---|
| 176 | * @param hVfs VFS handle.
|
---|
| 177 | * @param off Start offset to check.
|
---|
| 178 | * @param cb Number of bytes to check.
|
---|
| 179 | * @param pfUsed Where to store the result.
|
---|
| 180 | */
|
---|
[69844] | 181 | RTDECL(int) RTVfsQueryRangeState(RTVFS hVfs, uint64_t off, size_t cb, bool *pfUsed);
|
---|
[33859] | 182 |
|
---|
[69840] | 183 |
|
---|
[53615] | 184 | /** @defgroup grp_vfs_obj VFS Base Object API
|
---|
[33820] | 185 | * @{
|
---|
| 186 | */
|
---|
[33859] | 187 |
|
---|
[34002] | 188 | /**
|
---|
| 189 | * Retains a reference to the VFS base object handle.
|
---|
| 190 | *
|
---|
| 191 | * @returns New reference count on success, UINT32_MAX on failure.
|
---|
| 192 | * @param hVfsObj The VFS base object handle.
|
---|
| 193 | */
|
---|
| 194 | RTDECL(uint32_t) RTVfsObjRetain(RTVFSOBJ hVfsObj);
|
---|
[66740] | 195 | RTDECL(uint32_t) RTVfsObjRetainDebug(RTVFSOBJ hVfsObj, RT_SRC_POS_DECL);
|
---|
[34002] | 196 |
|
---|
| 197 | /**
|
---|
| 198 | * Releases a reference to the VFS base handle.
|
---|
| 199 | *
|
---|
| 200 | * @returns New reference count on success (0 if closed), UINT32_MAX on failure.
|
---|
| 201 | * @param hVfsObj The VFS base object handle.
|
---|
| 202 | */
|
---|
| 203 | RTDECL(uint32_t) RTVfsObjRelease(RTVFSOBJ hVfsObj);
|
---|
| 204 |
|
---|
[69813] | 205 | /** @name RTVFSOBJ_F_XXX - Flags or RTVfsObjOpen and RTVfsDirOpenObj.
|
---|
| 206 | * @note Must leave space for RTPATH_F_XXX.
|
---|
| 207 | * @{ */
|
---|
| 208 | /** Directory (RTFS_TYPE_DIRECTORY). */
|
---|
| 209 | #define RTVFSOBJ_F_OPEN_DIRECTORY RT_BIT_32(8)
|
---|
| 210 | /** Symbolic link (RTFS_TYPE_SYMLINK). */
|
---|
| 211 | #define RTVFSOBJ_F_OPEN_SYMLINK RT_BIT_32(9)
|
---|
| 212 | /** Regular file (RTFS_TYPE_FILE). */
|
---|
| 213 | #define RTVFSOBJ_F_OPEN_FILE RT_BIT_32(10)
|
---|
| 214 | /** Character device (RTFS_TYPE_DEV_CHAR). */
|
---|
| 215 | #define RTVFSOBJ_F_OPEN_DEV_CHAR RT_BIT_32(11)
|
---|
| 216 | /** Block device (RTFS_TYPE_DEV_BLOCK). */
|
---|
| 217 | #define RTVFSOBJ_F_OPEN_DEV_BLOCK RT_BIT_32(12)
|
---|
| 218 | /** Named pipe (fifo) (RTFS_TYPE_FIFO). */
|
---|
| 219 | #define RTVFSOBJ_F_OPEN_FIFO RT_BIT_32(13)
|
---|
| 220 | /** Socket (RTFS_TYPE_SOCKET). */
|
---|
| 221 | #define RTVFSOBJ_F_OPEN_SOCKET RT_BIT_32(14)
|
---|
[69818] | 222 | /** Mounted VFS. */
|
---|
| 223 | #define RTVFSOBJ_F_OPEN_MOUNT RT_BIT_32(15)
|
---|
[69813] | 224 | /** Mask object types we wish to open. */
|
---|
[69818] | 225 | #define RTVFSOBJ_F_OPEN_MASK UINT32_C(0x0000ff00)
|
---|
[69813] | 226 | /** Any kind of object that translates to RTVFSOBJTYPE_FILE. */
|
---|
[69818] | 227 | #define RTVFSOBJ_F_OPEN_ANY_FILE (RTVFSOBJ_F_OPEN_FILE | RTVFSOBJ_F_OPEN_DEV_BLOCK)
|
---|
[69813] | 228 | /** Any kind of object that translates to RTVFSOBJTYPE_IOS or
|
---|
| 229 | * RTVFSOBJTYPE_FILE. */
|
---|
[69818] | 230 | #define RTVFSOBJ_F_OPEN_ANY_IO_STREAM ( RTVFSOBJ_F_ANY_OPEN_FILE | RTVFSOBJ_F_DEV_OPEN_BLOCK \
|
---|
| 231 | | RTVFSOBJ_F_OPEN_FIFO | RTVFSOBJ_F_OPEN_SOCKET)
|
---|
[69813] | 232 | /** Any kind of object. */
|
---|
| 233 | #define RTVFSOBJ_F_OPEN_ANY RTVFSOBJ_F_OPEN_MASK
|
---|
| 234 |
|
---|
| 235 | /** Do't create anything, return file not found. */
|
---|
| 236 | #define RTVFSOBJ_F_CREATE_NOTHING UINT32_C(0x00000000)
|
---|
| 237 | /** Create a file if the if the object was not found and the RTFILE_O_XXX
|
---|
| 238 | * flags allows it. */
|
---|
| 239 | #define RTVFSOBJ_F_CREATE_FILE UINT32_C(0x00010000)
|
---|
| 240 | /** Create a directory if the object was not found and the RTFILE_O_XXX
|
---|
| 241 | * flags allows it. */
|
---|
| 242 | #define RTVFSOBJ_F_CREATE_DIRECTORY UINT32_C(0x00020000)
|
---|
| 243 | /** The creation type mask. */
|
---|
| 244 | #define RTVFSOBJ_F_CREATE_MASK UINT32_C(0x00070000)
|
---|
| 245 |
|
---|
| 246 | /** Indicate that this call is for traversal.
|
---|
| 247 | * @internal only */
|
---|
| 248 | #define RTVFSOBJ_F_TRAVERSAL RT_BIT_32(31)
|
---|
| 249 | /** Valid mask for external callers. */
|
---|
[69818] | 250 | #define RTVFSOBJ_F_VALID_MASK UINT32_C(0x0007ff00)
|
---|
[69813] | 251 | /** @} */
|
---|
| 252 |
|
---|
[34002] | 253 | /**
|
---|
[69813] | 254 | * Opens any file system object in the given VFS.
|
---|
| 255 | *
|
---|
| 256 | * @returns IPRT status code.
|
---|
| 257 | * @param hVfs The VFS to open the object within.
|
---|
| 258 | * @param pszPath Path to the file.
|
---|
| 259 | * @param fFileOpen RTFILE_O_XXX flags.
|
---|
| 260 | * @param fObjFlags More flags: RTVFSOBJ_F_XXX, RTPATH_F_XXX.
|
---|
| 261 | * @param phVfsObj Where to return the object handle.
|
---|
| 262 | * @sa RTVfsDirOpenObj, RTVfsDirOpenDir, RTVfsDirOpenFile
|
---|
| 263 | */
|
---|
| 264 | RTDECL(int) RTVfsObjOpen(RTVFS hVfs, const char *pszPath, uint64_t fFileOpen, uint32_t fObjFlags, PRTVFSOBJ phVfsObj);
|
---|
| 265 |
|
---|
| 266 | /**
|
---|
[34002] | 267 | * Query information about the object.
|
---|
| 268 | *
|
---|
| 269 | * @returns IPRT status code.
|
---|
| 270 | * @retval VERR_NOT_SUPPORTED if the @a enmAddAttr value is not handled by the
|
---|
| 271 | * implementation.
|
---|
| 272 | *
|
---|
| 273 | * @param hVfsObj The VFS object handle.
|
---|
| 274 | * @param pObjInfo Where to return the info.
|
---|
| 275 | * @param enmAddAttr Which additional attributes should be retrieved.
|
---|
[34786] | 276 | * @sa RTVfsIoStrmQueryInfo, RTVfsFileQueryInfo, RTFileQueryInfo,
|
---|
| 277 | * RTPathQueryInfo
|
---|
[34002] | 278 | */
|
---|
| 279 | RTDECL(int) RTVfsObjQueryInfo(RTVFSOBJ hVfsObj, PRTFSOBJINFO pObjInfo, RTFSOBJATTRADD enmAddAttr);
|
---|
| 280 |
|
---|
[69813] | 281 | /**
|
---|
| 282 | * Sets the file mode for the given VFS object.
|
---|
| 283 | *
|
---|
| 284 | * @returns IPRT status code.
|
---|
| 285 | * @retval VERR_INVALID_FUNCTION if the object type has no file mode to set.
|
---|
| 286 | * Only directories, files and symbolic links support this operation.
|
---|
| 287 | *
|
---|
| 288 | * @param hVfsObj The VFS object handle.
|
---|
| 289 | * @param fMode The mode mask.
|
---|
| 290 | * @param fMask The bits in the mode mask which should be changed.
|
---|
| 291 | */
|
---|
| 292 | RTDECL(int) RTVfsObjSetMode(RTVFSOBJ hVfsObj, RTFMODE fMode, RTFMODE fMask);
|
---|
[34002] | 293 |
|
---|
| 294 | /**
|
---|
[69813] | 295 | * Sets one or more timestamps for the given VFS object.
|
---|
| 296 | *
|
---|
| 297 | * @returns IPRT status code.
|
---|
| 298 | * @retval VERR_INVALID_FUNCTION if the object type has no file mode to set.
|
---|
| 299 | * Only directories, files and symbolic links support this operation.
|
---|
| 300 | *
|
---|
| 301 | * @param hVfsObj The VFS object handle.
|
---|
| 302 | * @param pAccessTime Pointer to the new access time. NULL if not to
|
---|
| 303 | * be changed.
|
---|
| 304 | * @param pModificationTime Pointer to the new modifcation time. NULL if not
|
---|
| 305 | * to be changed.
|
---|
| 306 | * @param pChangeTime Pointer to the new change time. NULL if not to
|
---|
| 307 | * be changed.
|
---|
| 308 | * @param pBirthTime Pointer to the new time of birth. NULL if not to
|
---|
| 309 | * be changed.
|
---|
| 310 | *
|
---|
| 311 | * @remarks See RTFileSetTimes for restrictions and behavior imposed by the
|
---|
| 312 | * host OS or underlying VFS provider.
|
---|
| 313 | * @sa RTFileSetTimes, RTPathSetTimes
|
---|
| 314 | */
|
---|
| 315 | RTDECL(int) RTVfsObjSetTimes(RTVFSOBJ hVfsObj, PCRTTIMESPEC pAccessTime, PCRTTIMESPEC pModificationTime,
|
---|
| 316 | PCRTTIMESPEC pChangeTime, PCRTTIMESPEC pBirthTime);
|
---|
| 317 |
|
---|
| 318 | /**
|
---|
| 319 | * Set the unix style owner and group on the given VFS object.
|
---|
| 320 | *
|
---|
| 321 | * @returns IPRT status code.
|
---|
| 322 | * @retval VERR_INVALID_FUNCTION if the object type has no file mode to set.
|
---|
| 323 | * Only directories, files and symbolic links support this operation.
|
---|
| 324 | *
|
---|
| 325 | * @param hVfsObj The VFS object handle.
|
---|
| 326 | * @param uid The user ID of the new owner. NIL_RTUID if
|
---|
| 327 | * unchanged.
|
---|
| 328 | * @param gid The group ID of the new owner group. NIL_RTGID if
|
---|
| 329 | * unchanged.
|
---|
| 330 | *
|
---|
| 331 | * @sa RTFileSetOwner, RTPathSetOwner.
|
---|
| 332 | */
|
---|
| 333 | RTDECL(int) RTVfsObjSetOwner(RTVFSOBJ hVfsObj, RTUID uid, RTGID gid);
|
---|
| 334 |
|
---|
| 335 |
|
---|
| 336 | /**
|
---|
| 337 | * Gets the type of a VFS object.
|
---|
| 338 | *
|
---|
| 339 | * @returns The VFS object type on success, RTVFSOBJTYPE_INVALID on failure.
|
---|
| 340 | * @param hVfsObj The VFS base object handle.
|
---|
| 341 | */
|
---|
| 342 | RTDECL(RTVFSOBJTYPE) RTVfsObjGetType(RTVFSOBJ hVfsObj);
|
---|
| 343 |
|
---|
| 344 | /**
|
---|
[34002] | 345 | * Converts a VFS base object handle to a VFS handle.
|
---|
| 346 | *
|
---|
| 347 | * @returns Referenced handle on success, NIL on failure.
|
---|
| 348 | * @param hVfsObj The VFS base object handle.
|
---|
| 349 | */
|
---|
[33945] | 350 | RTDECL(RTVFS) RTVfsObjToVfs(RTVFSOBJ hVfsObj);
|
---|
[34002] | 351 |
|
---|
| 352 | /**
|
---|
| 353 | * Converts a VFS base object handle to a VFS filesystem stream handle.
|
---|
| 354 | *
|
---|
| 355 | * @returns Referenced handle on success, NIL on failure.
|
---|
| 356 | * @param hVfsObj The VFS base object handle.
|
---|
| 357 | */
|
---|
[33945] | 358 | RTDECL(RTVFSFSSTREAM) RTVfsObjToFsStream(RTVFSOBJ hVfsObj);
|
---|
[34002] | 359 |
|
---|
| 360 | /**
|
---|
| 361 | * Converts a VFS base object handle to a VFS directory handle.
|
---|
| 362 | *
|
---|
| 363 | * @returns Referenced handle on success, NIL on failure.
|
---|
| 364 | * @param hVfsObj The VFS base object handle.
|
---|
| 365 | */
|
---|
[33945] | 366 | RTDECL(RTVFSDIR) RTVfsObjToDir(RTVFSOBJ hVfsObj);
|
---|
[34002] | 367 |
|
---|
| 368 | /**
|
---|
| 369 | * Converts a VFS base object handle to a VFS I/O stream handle.
|
---|
| 370 | *
|
---|
| 371 | * @returns Referenced handle on success, NIL on failure.
|
---|
| 372 | * @param hVfsObj The VFS base object handle.
|
---|
| 373 | */
|
---|
[33945] | 374 | RTDECL(RTVFSIOSTREAM) RTVfsObjToIoStream(RTVFSOBJ hVfsObj);
|
---|
[34002] | 375 |
|
---|
| 376 | /**
|
---|
| 377 | * Converts a VFS base object handle to a VFS file handle.
|
---|
| 378 | *
|
---|
| 379 | * @returns Referenced handle on success, NIL on failure.
|
---|
| 380 | * @param hVfsObj The VFS base object handle.
|
---|
| 381 | */
|
---|
[33945] | 382 | RTDECL(RTVFSFILE) RTVfsObjToFile(RTVFSOBJ hVfsObj);
|
---|
[34002] | 383 |
|
---|
| 384 | /**
|
---|
| 385 | * Converts a VFS base object handle to a VFS symbolic link handle.
|
---|
| 386 | *
|
---|
| 387 | * @returns Referenced handle on success, NIL on failure.
|
---|
| 388 | * @param hVfsObj The VFS base object handle.
|
---|
| 389 | */
|
---|
[33945] | 390 | RTDECL(RTVFSSYMLINK) RTVfsObjToSymlink(RTVFSOBJ hVfsObj);
|
---|
| 391 |
|
---|
[34002] | 392 |
|
---|
| 393 | /**
|
---|
| 394 | * Converts a VFS handle to a VFS base object handle.
|
---|
| 395 | *
|
---|
| 396 | * @returns Referenced handle on success, NIL if the input handle was invalid.
|
---|
| 397 | * @param hVfs The VFS handle.
|
---|
| 398 | */
|
---|
[33945] | 399 | RTDECL(RTVFSOBJ) RTVfsObjFromVfs(RTVFS hVfs);
|
---|
[34002] | 400 |
|
---|
| 401 | /**
|
---|
| 402 | * Converts a VFS filesystem stream handle to a VFS base object handle.
|
---|
| 403 | *
|
---|
| 404 | * @returns Referenced handle on success, NIL if the input handle was invalid.
|
---|
[57944] | 405 | * @param hVfsFss The VFS filesystem stream handle.
|
---|
[34002] | 406 | */
|
---|
[33945] | 407 | RTDECL(RTVFSOBJ) RTVfsObjFromFsStream(RTVFSFSSTREAM hVfsFss);
|
---|
[34002] | 408 |
|
---|
| 409 | /**
|
---|
| 410 | * Converts a VFS directory handle to a VFS base object handle.
|
---|
| 411 | *
|
---|
| 412 | * @returns Referenced handle on success, NIL if the input handle was invalid.
|
---|
| 413 | * @param hVfsDir The VFS directory handle.
|
---|
| 414 | */
|
---|
[33945] | 415 | RTDECL(RTVFSOBJ) RTVfsObjFromDir(RTVFSDIR hVfsDir);
|
---|
[34002] | 416 |
|
---|
| 417 | /**
|
---|
| 418 | * Converts a VFS I/O stream handle to a VFS base object handle.
|
---|
| 419 | *
|
---|
| 420 | * @returns Referenced handle on success, NIL if the input handle was invalid.
|
---|
| 421 | * @param hVfsIos The VFS I/O stream handle.
|
---|
| 422 | */
|
---|
[33945] | 423 | RTDECL(RTVFSOBJ) RTVfsObjFromIoStream(RTVFSIOSTREAM hVfsIos);
|
---|
[34002] | 424 |
|
---|
| 425 | /**
|
---|
| 426 | * Converts a VFS file handle to a VFS base object handle.
|
---|
| 427 | *
|
---|
| 428 | * @returns Referenced handle on success, NIL if the input handle was invalid.
|
---|
| 429 | * @param hVfsFile The VFS file handle.
|
---|
| 430 | */
|
---|
[33945] | 431 | RTDECL(RTVFSOBJ) RTVfsObjFromFile(RTVFSFILE hVfsFile);
|
---|
| 432 |
|
---|
[33948] | 433 | /**
|
---|
[34002] | 434 | * Converts a VFS symbolic link handle to a VFS base object handle.
|
---|
[33948] | 435 | *
|
---|
[34002] | 436 | * @returns Referenced handle on success, NIL if the input handle was invalid.
|
---|
| 437 | * @param hVfsSym The VFS symbolic link handle.
|
---|
[33948] | 438 | */
|
---|
[34002] | 439 | RTDECL(RTVFSOBJ) RTVfsObjFromSymlink(RTVFSSYMLINK hVfsSym);
|
---|
[33948] | 440 |
|
---|
[33945] | 441 | /** @} */
|
---|
| 442 |
|
---|
| 443 |
|
---|
[33948] | 444 | /** @defgroup grp_vfs_fsstream VFS Filesystem Stream API
|
---|
| 445 | *
|
---|
| 446 | * Filesystem streams are for tar, cpio and similar. Any virtual filesystem can
|
---|
| 447 | * be turned into a filesystem stream using RTVfsFsStrmFromVfs.
|
---|
| 448 | *
|
---|
| 449 | * @{
|
---|
| 450 | */
|
---|
| 451 |
|
---|
| 452 | RTDECL(uint32_t) RTVfsFsStrmRetain(RTVFSFSSTREAM hVfsFss);
|
---|
[66740] | 453 | RTDECL(uint32_t) RTVfsFsStrmRetainDebug(RTVFSFSSTREAM hVfsFss, RT_SRC_POS_DECL);
|
---|
[33948] | 454 | RTDECL(uint32_t) RTVfsFsStrmRelease(RTVFSFSSTREAM hVfsFss);
|
---|
| 455 | RTDECL(int) RTVfsFsStrmQueryInfo(RTVFSFSSTREAM hVfsFss, PRTFSOBJINFO pObjInfo, RTFSOBJATTRADD enmAddAttr);
|
---|
| 456 |
|
---|
| 457 | /**
|
---|
| 458 | * Gets the next object in the stream.
|
---|
| 459 | *
|
---|
| 460 | * This call may affect the stream posision of a previously returned object.
|
---|
| 461 | *
|
---|
| 462 | * The type of object returned here typically boils down to three types:
|
---|
| 463 | * - I/O streams (representing files),
|
---|
| 464 | * - symbolic links
|
---|
| 465 | * - base object
|
---|
| 466 | * The base objects represent anything not convered by the two other, i.e.
|
---|
| 467 | * directories, device nodes, fifos, sockets and whatnot. The details can be
|
---|
| 468 | * queried using RTVfsObjQueryInfo.
|
---|
| 469 | *
|
---|
| 470 | * That said, absolutely any object except for filesystem stream objects can be
|
---|
| 471 | * returned by this call. Any generic code is adviced to just deal with it all.
|
---|
| 472 | *
|
---|
| 473 | * @returns IPRT status code.
|
---|
| 474 | * @retval VINF_SUCCESS if a new object was retrieved.
|
---|
| 475 | * @retval VERR_EOF when there are no more objects.
|
---|
[67116] | 476 | * @retval VERR_INVALID_FUNCTION if called on a non-readable stream.
|
---|
[34002] | 477 | *
|
---|
[57944] | 478 | * @param hVfsFss The file system stream handle.
|
---|
[33948] | 479 | * @param ppszName Where to return the object name. Must be freed by
|
---|
| 480 | * calling RTStrFree.
|
---|
| 481 | * @param penmType Where to return the object type.
|
---|
[57944] | 482 | * @param phVfsObj Where to return the object handle (referenced). This
|
---|
| 483 | * must be cast to the desired type before use.
|
---|
[33948] | 484 | */
|
---|
| 485 | RTDECL(int) RTVfsFsStrmNext(RTVFSFSSTREAM hVfsFss, char **ppszName, RTVFSOBJTYPE *penmType, PRTVFSOBJ phVfsObj);
|
---|
| 486 |
|
---|
[67116] | 487 | /**
|
---|
| 488 | * Appends a VFS object to the stream.
|
---|
| 489 | *
|
---|
| 490 | * The stream must be writable.
|
---|
| 491 | *
|
---|
| 492 | * @returns IPRT status code.
|
---|
| 493 | * @retval VERR_INVALID_FUNCTION if called on a non-writable stream.
|
---|
| 494 | * @param hVfsFss The file system stream handle.
|
---|
| 495 | * @param pszPath The path.
|
---|
| 496 | * @param hVfsObj The VFS object to add.
|
---|
[67123] | 497 | * @param fFlags RTVFSFSSTRM_ADD_F_XXX.
|
---|
[67116] | 498 | */
|
---|
| 499 | RTDECL(int) RTVfsFsStrmAdd(RTVFSFSSTREAM hVfsFss, const char *pszPath, RTVFSOBJ hVfsObj, uint32_t fFlags);
|
---|
| 500 |
|
---|
[67123] | 501 | /** @name RTVFSFSSTRM_ADD_F_XXX - Flags for RTVfsFsStrmAdd.
|
---|
| 502 | * @{ */
|
---|
| 503 | /** Input is an I/O stream of indeterminate length, read to the end and then
|
---|
| 504 | * update the file header.
|
---|
| 505 | * @note This is *only* possible if the output stream is actually a file. */
|
---|
| 506 | #define RTVFSFSSTRM_ADD_F_STREAM RT_BIT_32(0)
|
---|
| 507 | /** Mask of flags specific to the target stream. */
|
---|
| 508 | #define RTVFSFSSTRM_ADD_F_SPECIFIC_MASK UINT32_C(0xff000000)
|
---|
| 509 | /** Valid bits. */
|
---|
| 510 | #define RTVFSFSSTRM_ADD_F_VALID_MASK UINT32_C(0xff000001)
|
---|
| 511 | /** @} */
|
---|
[33948] | 512 |
|
---|
[67123] | 513 | /**
|
---|
[67149] | 514 | * Pushes an byte stream onto the stream.
|
---|
| 515 | *
|
---|
| 516 | * The stream must be writable.
|
---|
| 517 | *
|
---|
| 518 | * This differs from RTVfsFsStrmAdd() in that it will create a regular file in
|
---|
| 519 | * the output file system stream and provide the actual content bytes via the
|
---|
| 520 | * returned I/O stream object.
|
---|
| 521 | *
|
---|
| 522 | * @returns IPRT status code.
|
---|
| 523 | * @retval VERR_INVALID_FUNCTION if called on a non-writable stream.
|
---|
| 524 | * @param hVfsFss The file system stream handle.
|
---|
| 525 | * @param pszPath The path to the file.
|
---|
| 526 | * @param cbFile The file size. This can also be set to UINT64_MAX if
|
---|
| 527 | * the file system stream is backed by a file.
|
---|
| 528 | * @param paObjInfo Array of zero or more RTFSOBJINFO structures containing
|
---|
| 529 | * different pieces of information about the file. If any
|
---|
| 530 | * provided, the first one should be a RTFSOBJATTRADD_UNIX
|
---|
| 531 | * one, additional can be supplied if wanted. What exactly
|
---|
| 532 | * is needed depends on the underlying FS stream
|
---|
| 533 | * implementation.
|
---|
| 534 | * @param cObjInfo Number of items in the array @a paObjInfo points at.
|
---|
| 535 | * @param fFlags RTVFSFSSTRM_PUSH_F_XXX.
|
---|
| 536 | * @param phVfsIos Where to return the I/O stream to feed the file content
|
---|
| 537 | * to. If the FS stream is backed by a file, the returned
|
---|
| 538 | * handle can be cast to a file if necessary.
|
---|
| 539 | */
|
---|
| 540 | RTDECL(int) RTVfsFsStrmPushFile(RTVFSFSSTREAM hVfsFss, const char *pszPath, uint64_t cbFile,
|
---|
| 541 | PCRTFSOBJINFO paObjInfo, uint32_t cObjInfo, uint32_t fFlags, PRTVFSIOSTREAM phVfsIos);
|
---|
| 542 |
|
---|
| 543 | /** @name RTVFSFSSTRM_PUSH_F_XXX - Flags for RTVfsFsStrmPushFile.
|
---|
| 544 | * @{ */
|
---|
| 545 | /** Input is an I/O stream of indeterminate length, read to the end and then
|
---|
| 546 | * update the file header.
|
---|
| 547 | * @note This is *only* possible if the output stream is actually a file. */
|
---|
| 548 | #define RTVFSFSSTRM_PUSH_F_STREAM RT_BIT_32(0)
|
---|
| 549 | /** Mask of flags specific to the target stream. */
|
---|
| 550 | #define RTVFSFSSTRM_PUSH_F_SPECIFIC_MASK UINT32_C(0xff000000)
|
---|
| 551 | /** Valid bits. */
|
---|
| 552 | #define RTVFSFSSTRM_PUSH_F_VALID_MASK UINT32_C(0xff000001)
|
---|
| 553 | /** @} */
|
---|
| 554 |
|
---|
| 555 | /**
|
---|
[67123] | 556 | * Marks the end of the stream.
|
---|
| 557 | *
|
---|
| 558 | * The stream must be writable.
|
---|
| 559 | *
|
---|
| 560 | * @returns IPRT status code.
|
---|
| 561 | * @retval VERR_INVALID_FUNCTION if called on a non-writable stream.
|
---|
| 562 | * @param hVfsFss The file system stream handle.
|
---|
| 563 | */
|
---|
| 564 | RTDECL(int) RTVfsFsStrmEnd(RTVFSFSSTREAM hVfsFss);
|
---|
[33948] | 565 |
|
---|
[67123] | 566 | /** @} */
|
---|
| 567 |
|
---|
| 568 |
|
---|
[33945] | 569 | /** @defgroup grp_vfs_dir VFS Directory API
|
---|
| 570 | * @{
|
---|
| 571 | */
|
---|
| 572 |
|
---|
[33859] | 573 | /**
|
---|
| 574 | * Retains a reference to the VFS directory handle.
|
---|
| 575 | *
|
---|
| 576 | * @returns New reference count on success, UINT32_MAX on failure.
|
---|
| 577 | * @param hVfsDir The VFS directory handle.
|
---|
| 578 | */
|
---|
| 579 | RTDECL(uint32_t) RTVfsDirRetain(RTVFSDIR hVfsDir);
|
---|
[66740] | 580 | RTDECL(uint32_t) RTVfsDirRetainDebug(RTVFSDIR hVfsDir, RT_SRC_POS_DECL);
|
---|
[33859] | 581 |
|
---|
| 582 | /**
|
---|
| 583 | * Releases a reference to the VFS directory handle.
|
---|
| 584 | *
|
---|
| 585 | * @returns New reference count on success (0 if closed), UINT32_MAX on failure.
|
---|
[57944] | 586 | * @param hVfsDir The VFS directory handle.
|
---|
[33859] | 587 | */
|
---|
| 588 | RTDECL(uint32_t) RTVfsDirRelease(RTVFSDIR hVfsDir);
|
---|
| 589 |
|
---|
[66601] | 590 | /**
|
---|
| 591 | * Opens a directory in the specified file system.
|
---|
| 592 | *
|
---|
| 593 | * @returns IPRT status code.
|
---|
| 594 | * @param hVfs The VFS to open the directory within.
|
---|
| 595 | * @param pszPath Path to the directory, relative to the root.
|
---|
| 596 | * @param fFlags Reserved, MBZ.
|
---|
| 597 | * @param phVfsDir Where to return the directory.
|
---|
| 598 | */
|
---|
| 599 | RTDECL(int) RTVfsDirOpen(RTVFS hVfs, const char *pszPath, uint32_t fFlags, PRTVFSDIR phVfsDir);
|
---|
| 600 |
|
---|
| 601 | /**
|
---|
[69813] | 602 | * Opens any file system object in or under the given directory.
|
---|
| 603 | *
|
---|
| 604 | * @returns IPRT status code.
|
---|
| 605 | * @param hVfsDir The VFS directory start walking the @a pszPath
|
---|
| 606 | * relative to.
|
---|
| 607 | * @param pszPath Path to the file.
|
---|
| 608 | * @param fFileOpen RTFILE_O_XXX flags.
|
---|
| 609 | * @param fObjFlags More flags: RTVFSOBJ_F_XXX, RTPATH_F_XXX.
|
---|
| 610 | * @param phVfsObj Where to return the object handle.
|
---|
| 611 | * @sa RTVfsObjOpen, RTVfsDirOpenDir, RTVfsDirOpenFile
|
---|
| 612 | */
|
---|
| 613 | RTDECL(int) RTVfsDirOpenObj(RTVFSDIR hVfsDir, const char *pszPath, uint64_t fFileOpen, uint32_t fObjFlags, PRTVFSOBJ phVfsObj);
|
---|
| 614 |
|
---|
| 615 | /**
|
---|
[66601] | 616 | * Opens a file in or under the given directory.
|
---|
| 617 | *
|
---|
| 618 | * @returns IPRT status code.
|
---|
| 619 | * @param hVfsDir The VFS directory start walking the @a pszPath
|
---|
| 620 | * relative to.
|
---|
| 621 | * @param pszPath Path to the file.
|
---|
| 622 | * @param fOpen RTFILE_O_XXX flags.
|
---|
| 623 | * @param phVfsFile Where to return the file.
|
---|
[67186] | 624 | * @sa RTVfsDirOpenFileAsIoStream
|
---|
[66601] | 625 | */
|
---|
| 626 | RTDECL(int) RTVfsDirOpenFile(RTVFSDIR hVfsDir, const char *pszPath, uint64_t fOpen, PRTVFSFILE phVfsFile);
|
---|
| 627 |
|
---|
| 628 | /**
|
---|
[67186] | 629 | * Convenience wrapper around RTVfsDirOpenFile that returns an I/O stream.
|
---|
| 630 | *
|
---|
| 631 | * @returns IPRT status code.
|
---|
| 632 | * @param hVfsDir The VFS directory start walking the @a pszPath
|
---|
| 633 | * relative to.
|
---|
| 634 | * @param pszPath Path to the file.
|
---|
| 635 | * @param fOpen RTFILE_O_XXX flags.
|
---|
| 636 | * @param phVfsIos Where to return the I/O stream handle of the file.
|
---|
| 637 | * @sa RTVfsDirOpenFile
|
---|
| 638 | */
|
---|
| 639 | RTDECL(int) RTVfsDirOpenFileAsIoStream(RTVFSDIR hVfsDir, const char *pszPath, uint64_t fOpen, PRTVFSIOSTREAM phVfsIos);
|
---|
| 640 |
|
---|
| 641 | /**
|
---|
[66601] | 642 | * Opens a directory in or under the given directory.
|
---|
| 643 | *
|
---|
| 644 | * @returns IPRT status code.
|
---|
| 645 | * @param hVfsDir The VFS directory start walking the @a pszPath
|
---|
| 646 | * relative to.
|
---|
| 647 | * @param pszPath Path to the file.
|
---|
| 648 | * @param fFlags Reserved, MBZ.
|
---|
| 649 | * @param phVfsDir Where to return the directory.
|
---|
| 650 | */
|
---|
| 651 | RTDECL(int) RTVfsDirOpenDir(RTVFSDIR hVfsDir, const char *pszPath, uint32_t fFlags, PRTVFSDIR phVfsDir);
|
---|
| 652 |
|
---|
[66762] | 653 | /**
|
---|
[69716] | 654 | * Creates a directory relative to @a hVfsDir.
|
---|
| 655 | *
|
---|
| 656 | * @returns IPRT status code
|
---|
| 657 | * @param hVfsDir The directory the path is relative to.
|
---|
| 658 | * @param pszRelPath The relative path to the new directory.
|
---|
| 659 | * @param fMode The file mode for the new directory.
|
---|
| 660 | * @param fFlags Directory creation flags, RTDIRCREATE_FLAGS_XXX.
|
---|
| 661 | * @param phVfsDir Where to return the handle to the newly created
|
---|
| 662 | * directory. Optional.
|
---|
| 663 | * @sa RTDirCreate, RTDirRelDirCreate
|
---|
| 664 | */
|
---|
| 665 | RTDECL(int) RTVfsDirCreateDir(RTVFSDIR hVfsDir, const char *pszRelPath, RTFMODE fMode, uint32_t fFlags, PRTVFSDIR phVfsDir);
|
---|
| 666 |
|
---|
| 667 | /**
|
---|
[69753] | 668 | * Create a VFS directory handle from a standard IPRT directory handle (RTDIR).
|
---|
[69674] | 669 | *
|
---|
| 670 | * @returns IPRT status code.
|
---|
| 671 | * @param hDir The standard IPRT directory handle.
|
---|
| 672 | * @param fLeaveOpen Whether to leave the handle open when the VFS
|
---|
| 673 | * directory is released, or to close it (@c false).
|
---|
[69677] | 674 | * @param phVfsDir Where to return the VFS directory handle.
|
---|
[69674] | 675 | */
|
---|
[69753] | 676 | RTDECL(int) RTVfsDirFromRTDir(RTDIR hDir, bool fLeaveOpen, PRTVFSDIR phVfsDir);
|
---|
[69674] | 677 |
|
---|
| 678 | /**
|
---|
| 679 | * RTDirOpen + RTVfsDirFromRTDir.
|
---|
| 680 | *
|
---|
| 681 | * @returns IPRT status code.
|
---|
[69679] | 682 | * @param pszPath The path to the directory.
|
---|
[69674] | 683 | * @param fFlags RTDIR_F_XXX.
|
---|
[69677] | 684 | * @param phVfsDir Where to return the VFS directory handle.
|
---|
[69674] | 685 | */
|
---|
[69679] | 686 | RTDECL(int) RTVfsDirOpenNormal(const char *pszPath, uint32_t fFlags, PRTVFSDIR phVfsDir);
|
---|
[69674] | 687 |
|
---|
[77047] | 688 | /** Checks if @a hVfsDir was opened using RTVfsDirOpenNormal() or
|
---|
| 689 | * RTVfsDirFromRTDir(), either directly or indirectly. */
|
---|
| 690 | RTDECL(bool) RTVfsDirIsStdDir(RTVFSDIR hVfsDir);
|
---|
| 691 |
|
---|
[69674] | 692 | /**
|
---|
[66762] | 693 | * Queries information about a object in or under the given directory.
|
---|
| 694 | *
|
---|
| 695 | * @returns IPRT Status code.
|
---|
| 696 | * @param hVfsDir The VFS directory start walking the @a pszPath
|
---|
| 697 | * relative to.
|
---|
| 698 | * @param pszPath Path to the object.
|
---|
| 699 | * @param pObjInfo Where to return info.
|
---|
| 700 | * @param enmAddAttr What to return.
|
---|
| 701 | * @param fFlags RTPATH_F_XXX.
|
---|
| 702 | * @sa RTPathQueryInfoEx, RTVfsQueryPathInfo, RTVfsObjQueryInfo
|
---|
| 703 | */
|
---|
| 704 | RTDECL(int) RTVfsDirQueryPathInfo(RTVFSDIR hVfsDir, const char *pszPath, PRTFSOBJINFO pObjInfo,
|
---|
| 705 | RTFSOBJATTRADD enmAddAttr, uint32_t fFlags);
|
---|
| 706 |
|
---|
| 707 | /**
|
---|
[69720] | 708 | * Removes a directory relative to @a hVfsDir.
|
---|
| 709 | *
|
---|
| 710 | * @returns IPRT status code.
|
---|
| 711 | * @param hVfsDir The VFS directory to start walking the @a pszRelPath
|
---|
| 712 | * relative to.
|
---|
| 713 | * @param pszRelPath The path to the directory that should be removed.
|
---|
| 714 | * @param fFlags Reserved, MBZ.
|
---|
| 715 | */
|
---|
| 716 | RTDECL(int) RTVfsDirRemoveDir(RTVFSDIR hVfsDir, const char *pszRelPath, uint32_t fFlags);
|
---|
| 717 |
|
---|
| 718 | /**
|
---|
[66762] | 719 | * Reads the next entry in the directory returning extended information.
|
---|
| 720 | *
|
---|
| 721 | * @returns VINF_SUCCESS and data in pDirEntry on success.
|
---|
| 722 | * @returns VERR_NO_MORE_FILES when the end of the directory has been reached.
|
---|
| 723 | * @returns VERR_BUFFER_OVERFLOW if the buffer is too small to contain the filename. If
|
---|
| 724 | * pcbDirEntry is specified it will be updated with the required buffer size.
|
---|
| 725 | * @returns suitable iprt status code on other errors.
|
---|
| 726 | *
|
---|
| 727 | * @param hVfsDir The VFS directory.
|
---|
| 728 | * @param pDirEntry Where to store the information about the next
|
---|
| 729 | * directory entry on success.
|
---|
| 730 | * @param pcbDirEntry Optional parameter used for variable buffer size.
|
---|
| 731 | *
|
---|
| 732 | * On input the variable pointed to contains the size of the pDirEntry
|
---|
| 733 | * structure. This must be at least OFFSET(RTDIRENTRYEX, szName[2]) bytes.
|
---|
| 734 | *
|
---|
| 735 | * On successful output the field is updated to
|
---|
| 736 | * OFFSET(RTDIRENTRYEX, szName[pDirEntry->cbName + 1]).
|
---|
| 737 | *
|
---|
| 738 | * When the data doesn't fit in the buffer and VERR_BUFFER_OVERFLOW is
|
---|
| 739 | * returned, this field contains the required buffer size.
|
---|
| 740 | *
|
---|
| 741 | * The value is unchanged in all other cases.
|
---|
| 742 | * @param enmAddAttr Which set of additional attributes to request.
|
---|
| 743 | * Use RTFSOBJATTRADD_NOTHING if this doesn't matter.
|
---|
| 744 | *
|
---|
| 745 | * @sa RTDirReadEx
|
---|
| 746 | */
|
---|
| 747 | RTDECL(int) RTVfsDirReadEx(RTVFSDIR hVfsDir, PRTDIRENTRYEX pDirEntry, size_t *pcbDirEntry, RTFSOBJATTRADD enmAddAttr);
|
---|
| 748 |
|
---|
[33820] | 749 | /** @} */
|
---|
| 750 |
|
---|
| 751 |
|
---|
[47351] | 752 | /** @defgroup grp_vfs_symlink VFS Symbolic Link API
|
---|
[34031] | 753 | *
|
---|
| 754 | * @remarks The TAR VFS and filesystem stream uses symbolic links for
|
---|
| 755 | * describing hard links as well. The users must use RTFS_IS_SYMLINK
|
---|
| 756 | * to check if it is a real symlink in those cases.
|
---|
| 757 | *
|
---|
| 758 | * @remarks Any VFS which is backed by a real file system may be subject to
|
---|
| 759 | * races with other processes or threads, so the user may get
|
---|
| 760 | * unexpected errors when this happends. This is a bit host specific,
|
---|
| 761 | * i.e. it might be prevent on windows if we care.
|
---|
| 762 | *
|
---|
[33820] | 763 | * @{
|
---|
| 764 | */
|
---|
[33822] | 765 |
|
---|
[34031] | 766 |
|
---|
| 767 | /**
|
---|
| 768 | * Retains a reference to the VFS symbolic link handle.
|
---|
| 769 | *
|
---|
| 770 | * @returns New reference count on success, UINT32_MAX on failure.
|
---|
| 771 | * @param hVfsSym The VFS symbolic link handle.
|
---|
| 772 | */
|
---|
[33948] | 773 | RTDECL(uint32_t) RTVfsSymlinkRetain(RTVFSSYMLINK hVfsSym);
|
---|
[66740] | 774 | RTDECL(uint32_t) RTVfsSymlinkRetainDebug(RTVFSSYMLINK hVfsSym, RT_SRC_POS_DECL);
|
---|
[34031] | 775 |
|
---|
| 776 | /**
|
---|
| 777 | * Releases a reference to the VFS symbolic link handle.
|
---|
| 778 | *
|
---|
| 779 | * @returns New reference count on success (0 if closed), UINT32_MAX on failure.
|
---|
| 780 | * @param hVfsSym The VFS symbolic link handle.
|
---|
| 781 | */
|
---|
[33948] | 782 | RTDECL(uint32_t) RTVfsSymlinkRelease(RTVFSSYMLINK hVfsSym);
|
---|
| 783 |
|
---|
[33822] | 784 | /**
|
---|
[34031] | 785 | * Query information about the symbolic link.
|
---|
| 786 | *
|
---|
| 787 | * @returns IPRT status code.
|
---|
| 788 | * @param hVfsSym The VFS symbolic link handle.
|
---|
| 789 | * @param pObjInfo Where to return the info.
|
---|
| 790 | * @param enmAddAttr Which additional attributes should be retrieved.
|
---|
| 791 | *
|
---|
| 792 | * @sa RTFileQueryInfo, RTPathQueryInfo, RTPathQueryInfoEx
|
---|
| 793 | */
|
---|
| 794 | RTDECL(int) RTVfsSymlinkQueryInfo(RTVFSSYMLINK hVfsSym, PRTFSOBJINFO pObjInfo, RTFSOBJATTRADD enmAddAttr);
|
---|
| 795 |
|
---|
| 796 | /**
|
---|
| 797 | * Set the unix style owner and group.
|
---|
| 798 | *
|
---|
| 799 | * @returns IPRT status code.
|
---|
| 800 | * @param hVfsSym The VFS symbolic link handle.
|
---|
| 801 | * @param fMode The new mode bits.
|
---|
| 802 | * @param fMask The mask indicating which bits we are changing.
|
---|
| 803 | * @sa RTFileSetMode, RTPathSetMode
|
---|
| 804 | */
|
---|
| 805 | RTDECL(int) RTVfsSymlinkSetMode(RTVFSSYMLINK hVfsSym, RTFMODE fMode, RTFMODE fMask);
|
---|
| 806 |
|
---|
| 807 | /**
|
---|
| 808 | * Set the timestamps associated with the object.
|
---|
| 809 | *
|
---|
| 810 | * @returns IPRT status code.
|
---|
| 811 | * @param hVfsSym The VFS symbolic link handle.
|
---|
| 812 | * @param pAccessTime Pointer to the new access time. NULL if not
|
---|
| 813 | * to be changed.
|
---|
| 814 | * @param pModificationTime Pointer to the new modifcation time. NULL if
|
---|
| 815 | * not to be changed.
|
---|
| 816 | * @param pChangeTime Pointer to the new change time. NULL if not to be
|
---|
| 817 | * changed.
|
---|
| 818 | * @param pBirthTime Pointer to the new time of birth. NULL if not to be
|
---|
| 819 | * changed.
|
---|
| 820 | * @remarks See RTFileSetTimes for restrictions and behavior imposed by the
|
---|
| 821 | * host OS or underlying VFS provider.
|
---|
| 822 | * @sa RTFileSetTimes, RTPathSetTimes
|
---|
| 823 | */
|
---|
| 824 | RTDECL(int) RTVfsSymlinkSetTimes(RTVFSSYMLINK hVfsSym, PCRTTIMESPEC pAccessTime, PCRTTIMESPEC pModificationTime,
|
---|
| 825 | PCRTTIMESPEC pChangeTime, PCRTTIMESPEC pBirthTime);
|
---|
| 826 |
|
---|
| 827 | /**
|
---|
| 828 | * Set the unix style owner and group.
|
---|
| 829 | *
|
---|
| 830 | * @returns IPRT status code.
|
---|
| 831 | * @param hVfsSym The VFS symbolic link handle.
|
---|
| 832 | * @param uid The user ID of the new owner. NIL_RTUID if
|
---|
| 833 | * unchanged.
|
---|
| 834 | * @param gid The group ID of the new owner group. NIL_RTGID if
|
---|
| 835 | * unchanged.
|
---|
| 836 | * @sa RTFileSetOwner, RTPathSetOwner.
|
---|
| 837 | */
|
---|
| 838 | RTDECL(int) RTVfsSymlinkSetOwner(RTVFSSYMLINK hVfsSym, RTUID uid, RTGID gid);
|
---|
| 839 |
|
---|
| 840 | /**
|
---|
[33859] | 841 | * Read the symbolic link target.
|
---|
| 842 | *
|
---|
| 843 | * @returns IPRT status code.
|
---|
| 844 | * @param hVfsSym The VFS symbolic link handle.
|
---|
| 845 | * @param pszTarget The target buffer.
|
---|
| 846 | * @param cbTarget The size of the target buffer.
|
---|
| 847 | * @sa RTSymlinkRead
|
---|
| 848 | */
|
---|
| 849 | RTDECL(int) RTVfsSymlinkRead(RTVFSSYMLINK hVfsSym, char *pszTarget, size_t cbTarget);
|
---|
| 850 |
|
---|
| 851 | /** @} */
|
---|
| 852 |
|
---|
| 853 |
|
---|
| 854 |
|
---|
| 855 | /** @defgroup grp_vfs_iostream VFS I/O Stream API
|
---|
| 856 | * @{
|
---|
| 857 | */
|
---|
| 858 |
|
---|
| 859 | /**
|
---|
[59620] | 860 | * Creates a VFS file from a memory buffer.
|
---|
| 861 | *
|
---|
| 862 | * @returns IPRT status code.
|
---|
| 863 | *
|
---|
| 864 | * @param fFlags A combination of RTFILE_O_READ and RTFILE_O_WRITE.
|
---|
| 865 | * @param pvBuf The buffer. This will be copied and not referenced
|
---|
| 866 | * after this function returns.
|
---|
| 867 | * @param cbBuf The buffer size.
|
---|
| 868 | * @param phVfsIos Where to return the VFS I/O stream handle.
|
---|
| 869 | */
|
---|
| 870 | RTDECL(int) RTVfsIoStrmFromBuffer(uint32_t fFlags, void const *pvBuf, size_t cbBuf, PRTVFSIOSTREAM phVfsIos);
|
---|
| 871 |
|
---|
| 872 | /**
|
---|
[57643] | 873 | * Creates a VFS I/O stream handle from a standard IPRT file handle (RTFILE).
|
---|
[33973] | 874 | *
|
---|
| 875 | * @returns IPRT status code.
|
---|
| 876 | * @param hFile The standard IPRT file handle.
|
---|
| 877 | * @param fOpen The flags the handle was opened with. Pass 0 to
|
---|
| 878 | * have these detected.
|
---|
| 879 | * @param fLeaveOpen Whether to leave the handle open when the VFS file
|
---|
| 880 | * is released, or to close it (@c false).
|
---|
| 881 | * @param phVfsIos Where to return the VFS I/O stream handle.
|
---|
| 882 | */
|
---|
[37596] | 883 | RTDECL(int) RTVfsIoStrmFromRTFile(RTFILE hFile, uint64_t fOpen, bool fLeaveOpen, PRTVFSIOSTREAM phVfsIos);
|
---|
[33973] | 884 |
|
---|
| 885 | /**
|
---|
[57643] | 886 | * Creates a VFS I/O stream handle from a standard IPRT pipe handle (RTPIPE).
|
---|
| 887 | *
|
---|
| 888 | * @returns IPRT status code.
|
---|
| 889 | * @param hPipe The standard IPRT pipe handle.
|
---|
| 890 | * @param fLeaveOpen Whether to leave the handle open when the VFS file
|
---|
| 891 | * is released, or to close it (@c false).
|
---|
| 892 | * @param phVfsIos Where to return the VFS I/O stream handle.
|
---|
| 893 | */
|
---|
| 894 | RTDECL(int) RTVfsIoStrmFromRTPipe(RTPIPE hPipe, bool fLeaveOpen, PRTVFSIOSTREAM phVfsIos);
|
---|
| 895 |
|
---|
| 896 | /**
|
---|
[47356] | 897 | * Convenience function combining RTFileOpen with RTVfsIoStrmFromRTFile.
|
---|
| 898 | *
|
---|
| 899 | * @returns IPRT status code.
|
---|
| 900 | * @param pszFilename The path to the file in the normal file system.
|
---|
| 901 | * @param fOpen The flags to pass to RTFileOpen when opening the
|
---|
| 902 | * file, i.e. RTFILE_O_XXX.
|
---|
| 903 | * @param phVfsIos Where to return the VFS I/O stream handle.
|
---|
| 904 | */
|
---|
| 905 | RTDECL(int) RTVfsIoStrmOpenNormal(const char *pszFilename, uint64_t fOpen, PRTVFSIOSTREAM phVfsIos);
|
---|
| 906 |
|
---|
| 907 | /**
|
---|
[33973] | 908 | * Create a VFS I/O stream handle from one of the standard handles.
|
---|
| 909 | *
|
---|
| 910 | * @returns IPRT status code.
|
---|
| 911 | * @param enmStdHandle The standard IPRT file handle.
|
---|
| 912 | * @param fOpen The flags the handle was opened with. Pass 0 to
|
---|
| 913 | * have these detected.
|
---|
| 914 | * @param fLeaveOpen Whether to leave the handle open when the VFS file
|
---|
| 915 | * is released, or to close it (@c false).
|
---|
| 916 | * @param phVfsIos Where to return the VFS I/O stream handle.
|
---|
| 917 | */
|
---|
[37596] | 918 | RTDECL(int) RTVfsIoStrmFromStdHandle(RTHANDLESTD enmStdHandle, uint64_t fOpen, bool fLeaveOpen,
|
---|
[33973] | 919 | PRTVFSIOSTREAM phVfsIos);
|
---|
| 920 |
|
---|
| 921 | /**
|
---|
[33822] | 922 | * Retains a reference to the VFS I/O stream handle.
|
---|
| 923 | *
|
---|
| 924 | * @returns New reference count on success, UINT32_MAX on failure.
|
---|
| 925 | * @param hVfsIos The VFS I/O stream handle.
|
---|
| 926 | */
|
---|
[33820] | 927 | RTDECL(uint32_t) RTVfsIoStrmRetain(RTVFSIOSTREAM hVfsIos);
|
---|
[66740] | 928 | RTDECL(uint32_t) RTVfsIoStrmRetainDebug(RTVFSIOSTREAM hVfsIos, RT_SRC_POS_DECL);
|
---|
[33822] | 929 |
|
---|
| 930 | /**
|
---|
| 931 | * Releases a reference to the VFS I/O stream handle.
|
---|
| 932 | *
|
---|
| 933 | * @returns New reference count on success (0 if closed), UINT32_MAX on failure.
|
---|
| 934 | * @param hVfsIos The VFS I/O stream handle.
|
---|
| 935 | */
|
---|
[33820] | 936 | RTDECL(uint32_t) RTVfsIoStrmRelease(RTVFSIOSTREAM hVfsIos);
|
---|
[33822] | 937 |
|
---|
| 938 | /**
|
---|
| 939 | * Convert the VFS I/O stream handle to a VFS file handle.
|
---|
| 940 | *
|
---|
| 941 | * @returns The VFS file handle on success, this must be released.
|
---|
| 942 | * NIL_RTVFSFILE if the I/O stream handle is invalid.
|
---|
| 943 | * @param hVfsIos The VFS I/O stream handle.
|
---|
| 944 | * @sa RTVfsFileToIoStream
|
---|
| 945 | */
|
---|
[34964] | 946 | RTDECL(RTVFSFILE) RTVfsIoStrmToFile(RTVFSIOSTREAM hVfsIos);
|
---|
[33822] | 947 |
|
---|
| 948 | /**
|
---|
| 949 | * Query information about the I/O stream.
|
---|
| 950 | *
|
---|
| 951 | * @returns IPRT status code.
|
---|
| 952 | * @param hVfsIos The VFS I/O stream handle.
|
---|
| 953 | * @param pObjInfo Where to return the info.
|
---|
| 954 | * @param enmAddAttr Which additional attributes should be retrieved.
|
---|
| 955 | * @sa RTFileQueryInfo
|
---|
| 956 | */
|
---|
[34964] | 957 | RTDECL(int) RTVfsIoStrmQueryInfo(RTVFSIOSTREAM hVfsIos, PRTFSOBJINFO pObjInfo, RTFSOBJATTRADD enmAddAttr);
|
---|
[33822] | 958 |
|
---|
| 959 | /**
|
---|
| 960 | * Read bytes from the I/O stream.
|
---|
| 961 | *
|
---|
| 962 | * @returns IPRT status code.
|
---|
[33973] | 963 | * @retval VINF_SUCCESS and the number of bytes read written to @a pcbRead.
|
---|
| 964 | * @retval VINF_TRY_AGAIN if @a fBlocking is @c false, @a pcbRead is not NULL,
|
---|
| 965 | * and no data was available. @a *pcbRead will be set to 0.
|
---|
| 966 | * @retval VINF_EOF when trying to read __beyond__ the end of the stream and
|
---|
| 967 | * @a pcbRead is not NULL (it will be set to the number of bytes read,
|
---|
| 968 | * or 0 if the end of the stream was reached before this call).
|
---|
| 969 | * When the last byte of the read request is the last byte in the
|
---|
| 970 | * stream, this status code will not be used. However, VINF_EOF is
|
---|
| 971 | * returned when attempting to read 0 bytes while standing at the end
|
---|
| 972 | * of the stream.
|
---|
| 973 | * @retval VERR_EOF when trying to read __beyond__ the end of the stream and
|
---|
| 974 | * @a pcbRead is NULL.
|
---|
[34002] | 975 | * @retval VERR_ACCESS_DENIED if the stream is not readable.
|
---|
[33973] | 976 | *
|
---|
[33822] | 977 | * @param hVfsIos The VFS I/O stream handle.
|
---|
| 978 | * @param pvBuf Where to store the read bytes.
|
---|
| 979 | * @param cbToRead The number of bytes to read.
|
---|
[33973] | 980 | * @param fBlocking Whether the call is blocking (@c true) or not. If
|
---|
| 981 | * not, the @a pcbRead parameter must not be NULL.
|
---|
[33903] | 982 | * @param pcbRead Where to always store the number of bytes actually
|
---|
[33973] | 983 | * read. This can be NULL if @a fBlocking is true.
|
---|
[34786] | 984 | * @sa RTVfsFileRead, RTFileRead, RTPipeRead, RTPipeReadBlocking,
|
---|
| 985 | * RTSocketRead
|
---|
[33822] | 986 | */
|
---|
[34964] | 987 | RTDECL(int) RTVfsIoStrmRead(RTVFSIOSTREAM hVfsIos, void *pvBuf, size_t cbToRead, bool fBlocking, size_t *pcbRead);
|
---|
[59620] | 988 |
|
---|
| 989 | /**
|
---|
| 990 | * Read bytes from the I/O stream, optionally with offset.
|
---|
| 991 | *
|
---|
| 992 | * @returns IPRT status code.
|
---|
| 993 | * @retval VINF_SUCCESS and the number of bytes read written to @a pcbRead.
|
---|
| 994 | * @retval VINF_TRY_AGAIN if @a fBlocking is @c false, @a pcbRead is not NULL,
|
---|
| 995 | * and no data was available. @a *pcbRead will be set to 0.
|
---|
| 996 | * @retval VINF_EOF when trying to read __beyond__ the end of the stream and
|
---|
| 997 | * @a pcbRead is not NULL (it will be set to the number of bytes read,
|
---|
| 998 | * or 0 if the end of the stream was reached before this call).
|
---|
| 999 | * When the last byte of the read request is the last byte in the
|
---|
| 1000 | * stream, this status code will not be used. However, VINF_EOF is
|
---|
| 1001 | * returned when attempting to read 0 bytes while standing at the end
|
---|
| 1002 | * of the stream.
|
---|
| 1003 | * @retval VERR_EOF when trying to read __beyond__ the end of the stream and
|
---|
| 1004 | * @a pcbRead is NULL.
|
---|
| 1005 | * @retval VERR_ACCESS_DENIED if the stream is not readable.
|
---|
| 1006 | *
|
---|
| 1007 | * @param hVfsIos The VFS I/O stream handle.
|
---|
| 1008 | * @param off Where to read at, -1 for the current position.
|
---|
| 1009 | * @param pvBuf Where to store the read bytes.
|
---|
| 1010 | * @param cbToRead The number of bytes to read.
|
---|
| 1011 | * @param fBlocking Whether the call is blocking (@c true) or not. If
|
---|
| 1012 | * not, the @a pcbRead parameter must not be NULL.
|
---|
| 1013 | * @param pcbRead Where to always store the number of bytes actually
|
---|
| 1014 | * read. This can be NULL if @a fBlocking is true.
|
---|
| 1015 | * @sa RTVfsFileRead, RTFileRead, RTPipeRead, RTPipeReadBlocking,
|
---|
| 1016 | * RTSocketRead
|
---|
| 1017 | */
|
---|
[41549] | 1018 | RTDECL(int) RTVfsIoStrmReadAt(RTVFSIOSTREAM hVfsIos, RTFOFF off, void *pvBuf, size_t cbToRead, bool fBlocking, size_t *pcbRead);
|
---|
[33822] | 1019 |
|
---|
| 1020 | /**
|
---|
[59620] | 1021 | * Reads the remainder of the stream into a memory buffer.
|
---|
| 1022 | *
|
---|
| 1023 | * For simplifying string-style processing, the is a zero byte after the
|
---|
| 1024 | * returned buffer, making sure it can be used as a zero terminated string.
|
---|
| 1025 | *
|
---|
| 1026 | * @returns IPRT status code.
|
---|
| 1027 | * @param hVfsIos The VFS I/O stream handle.
|
---|
| 1028 | * @param ppvBuf Where to return the buffer. Must pass to
|
---|
| 1029 | * RTVfsIoStrmReadAllFree for freeing, not RTMemFree!
|
---|
| 1030 | * @param pcbBuf Where to return the buffer size.
|
---|
| 1031 | */
|
---|
| 1032 | RTDECL(int) RTVfsIoStrmReadAll(RTVFSIOSTREAM hVfsIos, void **ppvBuf, size_t *pcbBuf);
|
---|
| 1033 |
|
---|
| 1034 | /**
|
---|
| 1035 | * Free memory buffer returned by RTVfsIoStrmReadAll.
|
---|
| 1036 | *
|
---|
| 1037 | * @param pvBuf What RTVfsIoStrmReadAll returned.
|
---|
| 1038 | * @param cbBuf What RTVfsIoStrmReadAll returned.
|
---|
| 1039 | */
|
---|
| 1040 | RTDECL(void) RTVfsIoStrmReadAllFree(void *pvBuf, size_t cbBuf);
|
---|
| 1041 |
|
---|
| 1042 | /**
|
---|
[33822] | 1043 | * Write bytes to the I/O stream.
|
---|
| 1044 | *
|
---|
| 1045 | * @returns IPRT status code.
|
---|
[34002] | 1046 | * @retval VERR_ACCESS_DENIED if the stream is not writable.
|
---|
| 1047 | *
|
---|
[33822] | 1048 | * @param hVfsIos The VFS I/O stream handle.
|
---|
| 1049 | * @param pvBuf The bytes to write.
|
---|
| 1050 | * @param cbToWrite The number of bytes to write.
|
---|
[33973] | 1051 | * @param fBlocking Whether the call is blocking (@c true) or not. If
|
---|
| 1052 | * not, the @a pcbWritten parameter must not be NULL.
|
---|
[57944] | 1053 | * @param pcbWritten Where to always store the number of bytes actually
|
---|
[33973] | 1054 | * written. This can be NULL if @a fBlocking is true.
|
---|
[34786] | 1055 | * @sa RTVfsFileWrite, RTFileWrite, RTPipeWrite, RTPipeWriteBlocking,
|
---|
| 1056 | * RTSocketWrite
|
---|
[33822] | 1057 | */
|
---|
[34964] | 1058 | RTDECL(int) RTVfsIoStrmWrite(RTVFSIOSTREAM hVfsIos, const void *pvBuf, size_t cbToWrite, bool fBlocking, size_t *pcbWritten);
|
---|
[41549] | 1059 | RTDECL(int) RTVfsIoStrmWriteAt(RTVFSIOSTREAM hVfsIos, RTFOFF off, const void *pvBuf, size_t cbToWrite, bool fBlocking, size_t *pcbWritten);
|
---|
[33822] | 1060 |
|
---|
| 1061 | /**
|
---|
| 1062 | * Reads bytes from the I/O stream into a scatter buffer.
|
---|
| 1063 | *
|
---|
| 1064 | * @returns IPRT status code.
|
---|
[33903] | 1065 | * @retval VINF_SUCCESS and the number of bytes read written to @a pcbRead.
|
---|
| 1066 | * @retval VINF_TRY_AGAIN if @a fBlocking is @c false, @a pcbRead is not NULL,
|
---|
| 1067 | * and no data was available. @a *pcbRead will be set to 0.
|
---|
| 1068 | * @retval VINF_EOF when trying to read __beyond__ the end of the stream and
|
---|
| 1069 | * @a pcbRead is not NULL (it will be set to the number of bytes read,
|
---|
| 1070 | * or 0 if the end of the stream was reached before this call).
|
---|
| 1071 | * When the last byte of the read request is the last byte in the
|
---|
| 1072 | * stream, this status code will not be used. However, VINF_EOF is
|
---|
| 1073 | * returned when attempting to read 0 bytes while standing at the end
|
---|
| 1074 | * of the stream.
|
---|
| 1075 | * @retval VERR_EOF when trying to read __beyond__ the end of the stream and
|
---|
| 1076 | * @a pcbRead is NULL.
|
---|
[34002] | 1077 | * @retval VERR_ACCESS_DENIED if the stream is not readable.
|
---|
[33903] | 1078 | *
|
---|
[33822] | 1079 | * @param hVfsIos The VFS I/O stream handle.
|
---|
[59620] | 1080 | * @param off Where to read at, -1 for the current position.
|
---|
[33822] | 1081 | * @param pSgBuf Pointer to a scatter buffer descriptor. The number
|
---|
| 1082 | * of bytes described by the segments is what will be
|
---|
| 1083 | * attemted read.
|
---|
| 1084 | * @param fBlocking Whether the call is blocking (@c true) or not. If
|
---|
| 1085 | * not, the @a pcbRead parameter must not be NULL.
|
---|
[33903] | 1086 | * @param pcbRead Where to always store the number of bytes actually
|
---|
| 1087 | * read. This can be NULL if @a fBlocking is true.
|
---|
| 1088 | * @sa RTFileSgRead, RTSocketSgRead, RTPipeRead, RTPipeReadBlocking
|
---|
[33822] | 1089 | */
|
---|
[59620] | 1090 | RTDECL(int) RTVfsIoStrmSgRead(RTVFSIOSTREAM hVfsIos, RTFOFF off, PCRTSGBUF pSgBuf, bool fBlocking, size_t *pcbRead);
|
---|
[33822] | 1091 |
|
---|
| 1092 | /**
|
---|
| 1093 | * Write bytes to the I/O stream from a gather buffer.
|
---|
| 1094 | *
|
---|
| 1095 | * @returns IPRT status code.
|
---|
[34002] | 1096 | * @retval VERR_ACCESS_DENIED if the stream is not writable.
|
---|
| 1097 | *
|
---|
[33822] | 1098 | * @param hVfsIos The VFS I/O stream handle.
|
---|
[59620] | 1099 | * @param off Where to write at, -1 for the current position.
|
---|
[33822] | 1100 | * @param pSgBuf Pointer to a gather buffer descriptor. The number
|
---|
| 1101 | * of bytes described by the segments is what will be
|
---|
| 1102 | * attemted written.
|
---|
| 1103 | * @param fBlocking Whether the call is blocking (@c true) or not. If
|
---|
| 1104 | * not, the @a pcbWritten parameter must not be NULL.
|
---|
[47359] | 1105 | * @param pcbWritten Where to always store the number of bytes actually
|
---|
[33903] | 1106 | * written. This can be NULL if @a fBlocking is true.
|
---|
[33822] | 1107 | * @sa RTFileSgWrite, RTSocketSgWrite
|
---|
| 1108 | */
|
---|
[59620] | 1109 | RTDECL(int) RTVfsIoStrmSgWrite(RTVFSIOSTREAM hVfsIos, RTFOFF off, PCRTSGBUF pSgBuf, bool fBlocking, size_t *pcbWritten);
|
---|
[33822] | 1110 |
|
---|
| 1111 | /**
|
---|
| 1112 | * Flush any buffered data to the I/O stream.
|
---|
| 1113 | *
|
---|
| 1114 | * @returns IPRT status code.
|
---|
| 1115 | * @param hVfsIos The VFS I/O stream handle.
|
---|
[34786] | 1116 | * @sa RTVfsFileFlush, RTFileFlush, RTPipeFlush
|
---|
[33822] | 1117 | */
|
---|
[33820] | 1118 | RTDECL(int) RTVfsIoStrmFlush(RTVFSIOSTREAM hVfsIos);
|
---|
[33822] | 1119 |
|
---|
| 1120 | /**
|
---|
| 1121 | * Poll for events.
|
---|
| 1122 | *
|
---|
| 1123 | * @returns IPRT status code.
|
---|
| 1124 | * @param hVfsIos The VFS I/O stream handle.
|
---|
| 1125 | * @param fEvents The events to poll for (RTPOLL_EVT_XXX).
|
---|
| 1126 | * @param cMillies How long to wait for event to eventuate.
|
---|
| 1127 | * @param fIntr Whether the wait is interruptible and can return
|
---|
| 1128 | * VERR_INTERRUPTED (@c true) or if this condition
|
---|
| 1129 | * should be hidden from the caller (@c false).
|
---|
| 1130 | * @param pfRetEvents Where to return the event mask.
|
---|
[34786] | 1131 | * @sa RTVfsFilePoll, RTPollSetAdd, RTPoll, RTPollNoResume.
|
---|
[33822] | 1132 | */
|
---|
[34964] | 1133 | RTDECL(int) RTVfsIoStrmPoll(RTVFSIOSTREAM hVfsIos, uint32_t fEvents, RTMSINTERVAL cMillies, bool fIntr,
|
---|
| 1134 | uint32_t *pfRetEvents);
|
---|
[33822] | 1135 | /**
|
---|
| 1136 | * Tells the current I/O stream position.
|
---|
| 1137 | *
|
---|
| 1138 | * @returns Zero or higher - where to return the I/O stream offset. Values
|
---|
| 1139 | * below zero are IPRT status codes (VERR_XXX).
|
---|
| 1140 | * @param hVfsIos The VFS I/O stream handle.
|
---|
| 1141 | * @sa RTFileTell
|
---|
| 1142 | */
|
---|
[33820] | 1143 | RTDECL(RTFOFF) RTVfsIoStrmTell(RTVFSIOSTREAM hVfsIos);
|
---|
[33859] | 1144 |
|
---|
| 1145 | /**
|
---|
| 1146 | * Skips @a cb ahead in the stream.
|
---|
| 1147 | *
|
---|
| 1148 | * @returns IPRT status code.
|
---|
| 1149 | * @param hVfsIos The VFS I/O stream handle.
|
---|
| 1150 | * @param cb The number bytes to skip.
|
---|
| 1151 | */
|
---|
| 1152 | RTDECL(int) RTVfsIoStrmSkip(RTVFSIOSTREAM hVfsIos, RTFOFF cb);
|
---|
| 1153 |
|
---|
| 1154 | /**
|
---|
| 1155 | * Fills the stream with @a cb zeros.
|
---|
| 1156 | *
|
---|
| 1157 | * @returns IPRT status code.
|
---|
| 1158 | * @param hVfsIos The VFS I/O stream handle.
|
---|
| 1159 | * @param cb The number of zero bytes to insert.
|
---|
| 1160 | */
|
---|
| 1161 | RTDECL(int) RTVfsIoStrmZeroFill(RTVFSIOSTREAM hVfsIos, RTFOFF cb);
|
---|
[34031] | 1162 |
|
---|
| 1163 | /**
|
---|
| 1164 | * Checks if we're at the end of the I/O stream.
|
---|
| 1165 | *
|
---|
| 1166 | * @returns true if at EOS, otherwise false.
|
---|
| 1167 | * @param hVfsIos The VFS I/O stream handle.
|
---|
| 1168 | */
|
---|
| 1169 | RTDECL(bool) RTVfsIoStrmIsAtEnd(RTVFSIOSTREAM hVfsIos);
|
---|
[34964] | 1170 |
|
---|
| 1171 | /**
|
---|
[67221] | 1172 | * Get the RTFILE_O_XXX flags for the I/O stream.
|
---|
| 1173 | *
|
---|
| 1174 | * @returns RTFILE_O_XXX, 0 on failure.
|
---|
| 1175 | * @param hVfsIos The VFS I/O stream handle.
|
---|
| 1176 | */
|
---|
| 1177 | RTDECL(uint64_t) RTVfsIoStrmGetOpenFlags(RTVFSIOSTREAM hVfsIos);
|
---|
| 1178 |
|
---|
| 1179 | /**
|
---|
[34964] | 1180 | * Process the rest of the stream, checking if it's all valid UTF-8 encoding.
|
---|
| 1181 | *
|
---|
[59620] | 1182 | * @returns IPRT status code.
|
---|
[34964] | 1183 | *
|
---|
| 1184 | * @param hVfsIos The VFS I/O stream handle.
|
---|
[34967] | 1185 | * @param fFlags Flags governing the validation, see
|
---|
| 1186 | * RTVFS_VALIDATE_UTF8_XXX.
|
---|
| 1187 | * @param poffError Where to return the error offset. Optional.
|
---|
[34964] | 1188 | */
|
---|
[34967] | 1189 | RTDECL(int) RTVfsIoStrmValidateUtf8Encoding(RTVFSIOSTREAM hVfsIos, uint32_t fFlags, PRTFOFF poffError);
|
---|
[34964] | 1190 |
|
---|
[34967] | 1191 | /** @defgroup RTVFS_VALIDATE_UTF8_XXX RTVfsIoStrmValidateUtf8Encoding flags.
|
---|
| 1192 | * @{ */
|
---|
| 1193 | /** The text must not contain any null terminator codepoints. */
|
---|
| 1194 | #define RTVFS_VALIDATE_UTF8_NO_NULL RT_BIT_32(0)
|
---|
| 1195 | /** The codepoints must be in the range covered by RTC-3629. */
|
---|
| 1196 | #define RTVFS_VALIDATE_UTF8_BY_RTC_3629 RT_BIT_32(1)
|
---|
| 1197 | /** Mask of valid flags. */
|
---|
| 1198 | #define RTVFS_VALIDATE_UTF8_VALID_MASK UINT32_C(0x00000003)
|
---|
| 1199 | /** @} */
|
---|
| 1200 |
|
---|
[33820] | 1201 | /** @} */
|
---|
| 1202 |
|
---|
| 1203 |
|
---|
| 1204 | /** @defgroup grp_vfs_file VFS File API
|
---|
| 1205 | * @{
|
---|
| 1206 | */
|
---|
[37596] | 1207 | RTDECL(int) RTVfsFileOpen(RTVFS hVfs, const char *pszFilename, uint64_t fOpen, PRTVFSFILE phVfsFile);
|
---|
[33820] | 1208 |
|
---|
| 1209 | /**
|
---|
| 1210 | * Create a VFS file handle from a standard IPRT file handle (RTFILE).
|
---|
| 1211 | *
|
---|
| 1212 | * @returns IPRT status code.
|
---|
| 1213 | * @param hFile The standard IPRT file handle.
|
---|
| 1214 | * @param fOpen The flags the handle was opened with. Pass 0 to
|
---|
| 1215 | * have these detected.
|
---|
| 1216 | * @param fLeaveOpen Whether to leave the handle open when the VFS file
|
---|
| 1217 | * is released, or to close it (@c false).
|
---|
| 1218 | * @param phVfsFile Where to return the VFS file handle.
|
---|
| 1219 | */
|
---|
[37596] | 1220 | RTDECL(int) RTVfsFileFromRTFile(RTFILE hFile, uint64_t fOpen, bool fLeaveOpen, PRTVFSFILE phVfsFile);
|
---|
[33820] | 1221 | RTDECL(RTHCUINTPTR) RTVfsFileToNative(RTFILE hVfsFile);
|
---|
| 1222 |
|
---|
| 1223 | /**
|
---|
[47356] | 1224 | * Convenience function combining RTFileOpen with RTVfsFileFromRTFile.
|
---|
| 1225 | *
|
---|
| 1226 | * @returns IPRT status code.
|
---|
| 1227 | * @param pszFilename The path to the file in the normal file system.
|
---|
| 1228 | * @param fOpen The flags to pass to RTFileOpen when opening the
|
---|
| 1229 | * file, i.e. RTFILE_O_XXX.
|
---|
| 1230 | * @param phVfsFile Where to return the VFS file handle.
|
---|
| 1231 | */
|
---|
| 1232 | RTDECL(int) RTVfsFileOpenNormal(const char *pszFilename, uint64_t fOpen, PRTVFSFILE phVfsFile);
|
---|
| 1233 |
|
---|
| 1234 | /**
|
---|
[33820] | 1235 | * Convert the VFS file handle to a VFS I/O stream handle.
|
---|
| 1236 | *
|
---|
| 1237 | * @returns The VFS I/O stream handle on success, this must be released.
|
---|
| 1238 | * NIL_RTVFSIOSTREAM if the file handle is invalid.
|
---|
| 1239 | * @param hVfsFile The VFS file handle.
|
---|
[33822] | 1240 | * @sa RTVfsIoStrmToFile
|
---|
[33820] | 1241 | */
|
---|
| 1242 | RTDECL(RTVFSIOSTREAM) RTVfsFileToIoStream(RTVFSFILE hVfsFile);
|
---|
| 1243 |
|
---|
| 1244 | /**
|
---|
| 1245 | * Retains a reference to the VFS file handle.
|
---|
| 1246 | *
|
---|
| 1247 | * @returns New reference count on success, UINT32_MAX on failure.
|
---|
| 1248 | * @param hVfsFile The VFS file handle.
|
---|
| 1249 | */
|
---|
| 1250 | RTDECL(uint32_t) RTVfsFileRetain(RTVFSFILE hVfsFile);
|
---|
[66740] | 1251 | RTDECL(uint32_t) RTVfsFileRetainDebug(RTVFSFILE hVfsFile, RT_SRC_POS_DECL);
|
---|
[33820] | 1252 |
|
---|
| 1253 | /**
|
---|
| 1254 | * Releases a reference to the VFS file handle.
|
---|
| 1255 | *
|
---|
| 1256 | * @returns New reference count on success (0 if closed), UINT32_MAX on failure.
|
---|
| 1257 | * @param hVfsFile The VFS file handle.
|
---|
| 1258 | */
|
---|
| 1259 | RTDECL(uint32_t) RTVfsFileRelease(RTVFSFILE hVfsFile);
|
---|
| 1260 |
|
---|
[34786] | 1261 | /**
|
---|
| 1262 | * Query information about the object.
|
---|
| 1263 | *
|
---|
| 1264 | * @returns IPRT status code.
|
---|
| 1265 | * @retval VERR_NOT_SUPPORTED if the @a enmAddAttr value is not handled by the
|
---|
| 1266 | * implementation.
|
---|
| 1267 | *
|
---|
[57944] | 1268 | * @param hVfsFile The VFS file handle.
|
---|
[34786] | 1269 | * @param pObjInfo Where to return the info.
|
---|
| 1270 | * @param enmAddAttr Which additional attributes should be retrieved.
|
---|
| 1271 | * @sa RTVfsObjQueryInfo, RTVfsFsStrmQueryInfo, RTVfsDirQueryInfo,
|
---|
| 1272 | * RTVfsIoStrmQueryInfo, RTVfsFileQueryInfo, RTFileQueryInfo,
|
---|
| 1273 | * RTPathQueryInfo.
|
---|
| 1274 | */
|
---|
[33820] | 1275 | RTDECL(int) RTVfsFileQueryInfo(RTVFSFILE hVfsFile, PRTFSOBJINFO pObjInfo, RTFSOBJATTRADD enmAddAttr);
|
---|
[34786] | 1276 |
|
---|
| 1277 | /**
|
---|
| 1278 | * Read bytes from the file at the current position.
|
---|
| 1279 | *
|
---|
| 1280 | * @returns IPRT status code.
|
---|
| 1281 | * @retval VINF_SUCCESS and the number of bytes read written to @a pcbRead.
|
---|
| 1282 | * @retval VINF_EOF when trying to read __beyond__ the end of the file and
|
---|
| 1283 | * @a pcbRead is not NULL (it will be set to the number of bytes read,
|
---|
| 1284 | * or 0 if the end of the file was reached before this call).
|
---|
| 1285 | * When the last byte of the read request is the last byte in the
|
---|
| 1286 | * file, this status code will not be used. However, VINF_EOF is
|
---|
| 1287 | * returned when attempting to read 0 bytes while standing at the end
|
---|
| 1288 | * of the file.
|
---|
| 1289 | * @retval VERR_EOF when trying to read __beyond__ the end of the file and
|
---|
| 1290 | * @a pcbRead is NULL.
|
---|
| 1291 | * @retval VERR_ACCESS_DENIED if the file is not readable.
|
---|
| 1292 | *
|
---|
| 1293 | * @param hVfsFile The VFS file handle.
|
---|
| 1294 | * @param pvBuf Where to store the read bytes.
|
---|
| 1295 | * @param cbToRead The number of bytes to read.
|
---|
| 1296 | * @param pcbRead Where to always store the number of bytes actually
|
---|
[57944] | 1297 | * read. Optional.
|
---|
[34786] | 1298 | * @sa RTVfsIoStrmRead, RTFileRead, RTPipeRead, RTPipeReadBlocking,
|
---|
| 1299 | * RTSocketRead
|
---|
| 1300 | */
|
---|
[33820] | 1301 | RTDECL(int) RTVfsFileRead(RTVFSFILE hVfsFile, void *pvBuf, size_t cbToRead, size_t *pcbRead);
|
---|
| 1302 | RTDECL(int) RTVfsFileReadAt(RTVFSFILE hVfsFile, RTFOFF off, void *pvBuf, size_t cbToRead, size_t *pcbRead);
|
---|
[34786] | 1303 |
|
---|
| 1304 | /**
|
---|
| 1305 | * Write bytes to the file at the current position.
|
---|
| 1306 | *
|
---|
| 1307 | * @returns IPRT status code.
|
---|
| 1308 | * @retval VERR_ACCESS_DENIED if the file is not writable.
|
---|
| 1309 | *
|
---|
| 1310 | * @param hVfsFile The VFS file handle.
|
---|
| 1311 | * @param pvBuf The bytes to write.
|
---|
| 1312 | * @param cbToWrite The number of bytes to write.
|
---|
[57944] | 1313 | * @param pcbWritten Where to always store the number of bytes actually
|
---|
| 1314 | * written. This can be NULL.
|
---|
[34786] | 1315 | * @sa RTVfsIoStrmRead, RTFileWrite, RTPipeWrite, RTPipeWriteBlocking,
|
---|
| 1316 | * RTSocketWrite
|
---|
| 1317 | */
|
---|
[33820] | 1318 | RTDECL(int) RTVfsFileWrite(RTVFSFILE hVfsFile, const void *pvBuf, size_t cbToWrite, size_t *pcbWritten);
|
---|
| 1319 | RTDECL(int) RTVfsFileWriteAt(RTVFSFILE hVfsFile, RTFOFF off, const void *pvBuf, size_t cbToWrite, size_t *pcbWritten);
|
---|
[34786] | 1320 |
|
---|
[66615] | 1321 |
|
---|
[34786] | 1322 | /**
|
---|
[66615] | 1323 | * Reads bytes from the file into a scatter buffer.
|
---|
| 1324 | *
|
---|
| 1325 | * @returns IPRT status code.
|
---|
| 1326 | * @retval VINF_SUCCESS and the number of bytes read written to @a pcbRead.
|
---|
| 1327 | * @retval VINF_TRY_AGAIN if @a fBlocking is @c false, @a pcbRead is not NULL,
|
---|
| 1328 | * and no data was available. @a *pcbRead will be set to 0.
|
---|
| 1329 | * @retval VINF_EOF when trying to read __beyond__ the end of the stream and
|
---|
| 1330 | * @a pcbRead is not NULL (it will be set to the number of bytes read,
|
---|
| 1331 | * or 0 if the end of the stream was reached before this call).
|
---|
| 1332 | * When the last byte of the read request is the last byte in the
|
---|
| 1333 | * stream, this status code will not be used. However, VINF_EOF is
|
---|
| 1334 | * returned when attempting to read 0 bytes while standing at the end
|
---|
| 1335 | * of the stream.
|
---|
| 1336 | * @retval VERR_EOF when trying to read __beyond__ the end of the stream and
|
---|
| 1337 | * @a pcbRead is NULL.
|
---|
| 1338 | * @retval VERR_ACCESS_DENIED if the stream is not readable.
|
---|
| 1339 | *
|
---|
[66616] | 1340 | * @param hVfsFile The VFS file handle.
|
---|
[66615] | 1341 | * @param off Where to read at, -1 for the current position.
|
---|
| 1342 | * @param pSgBuf Pointer to a scatter buffer descriptor. The number
|
---|
| 1343 | * of bytes described by the segments is what will be
|
---|
| 1344 | * attemted read.
|
---|
| 1345 | * @param fBlocking Whether the call is blocking (@c true) or not. If
|
---|
| 1346 | * not, the @a pcbRead parameter must not be NULL.
|
---|
| 1347 | * @param pcbRead Where to always store the number of bytes actually
|
---|
| 1348 | * read. This can be NULL if @a fBlocking is true.
|
---|
| 1349 | * @sa RTFileSgRead, RTSocketSgRead, RTPipeRead, RTPipeReadBlocking
|
---|
| 1350 | */
|
---|
| 1351 | RTDECL(int) RTVfsFileSgRead(RTVFSFILE hVfsFile, RTFOFF off, PCRTSGBUF pSgBuf, bool fBlocking, size_t *pcbRead);
|
---|
| 1352 |
|
---|
| 1353 | /**
|
---|
| 1354 | * Write bytes to the file from a gather buffer.
|
---|
| 1355 | *
|
---|
| 1356 | * @returns IPRT status code.
|
---|
| 1357 | * @retval VERR_ACCESS_DENIED if the stream is not writable.
|
---|
| 1358 | *
|
---|
[66616] | 1359 | * @param hVfsFile The VFS file handle.
|
---|
[66615] | 1360 | * @param off Where to write at, -1 for the current position.
|
---|
| 1361 | * @param pSgBuf Pointer to a gather buffer descriptor. The number
|
---|
| 1362 | * of bytes described by the segments is what will be
|
---|
| 1363 | * attemted written.
|
---|
| 1364 | * @param fBlocking Whether the call is blocking (@c true) or not. If
|
---|
| 1365 | * not, the @a pcbWritten parameter must not be NULL.
|
---|
| 1366 | * @param pcbWritten Where to always store the number of bytes actually
|
---|
| 1367 | * written. This can be NULL if @a fBlocking is true.
|
---|
| 1368 | * @sa RTFileSgWrite, RTSocketSgWrite
|
---|
| 1369 | */
|
---|
| 1370 | RTDECL(int) RTVfsFileSgWrite(RTVFSFILE hVfsFile, RTFOFF off, PCRTSGBUF pSgBuf, bool fBlocking, size_t *pcbWritten);
|
---|
| 1371 |
|
---|
| 1372 | /**
|
---|
[34786] | 1373 | * Flush any buffered data to the file.
|
---|
| 1374 | *
|
---|
| 1375 | * @returns IPRT status code.
|
---|
| 1376 | * @param hVfsFile The VFS file handle.
|
---|
| 1377 | * @sa RTVfsIoStrmFlush, RTFileFlush, RTPipeFlush
|
---|
| 1378 | */
|
---|
[33820] | 1379 | RTDECL(int) RTVfsFileFlush(RTVFSFILE hVfsFile);
|
---|
[34786] | 1380 |
|
---|
| 1381 | /**
|
---|
| 1382 | * Poll for events.
|
---|
| 1383 | *
|
---|
| 1384 | * @returns IPRT status code.
|
---|
| 1385 | * @param hVfsFile The VFS file handle.
|
---|
| 1386 | * @param fEvents The events to poll for (RTPOLL_EVT_XXX).
|
---|
| 1387 | * @param cMillies How long to wait for event to eventuate.
|
---|
| 1388 | * @param fIntr Whether the wait is interruptible and can return
|
---|
| 1389 | * VERR_INTERRUPTED (@c true) or if this condition
|
---|
| 1390 | * should be hidden from the caller (@c false).
|
---|
| 1391 | * @param pfRetEvents Where to return the event mask.
|
---|
| 1392 | * @sa RTVfsIoStrmPoll, RTPollSetAdd, RTPoll, RTPollNoResume.
|
---|
| 1393 | */
|
---|
[33820] | 1394 | RTDECL(RTFOFF) RTVfsFilePoll(RTVFSFILE hVfsFile, uint32_t fEvents, RTMSINTERVAL cMillies, bool fIntr,
|
---|
| 1395 | uint32_t *pfRetEvents);
|
---|
[34786] | 1396 |
|
---|
| 1397 | /**
|
---|
| 1398 | * Tells the current file position.
|
---|
| 1399 | *
|
---|
| 1400 | * @returns Zero or higher - where to return the file offset. Values
|
---|
| 1401 | * below zero are IPRT status codes (VERR_XXX).
|
---|
| 1402 | * @param hVfsFile The VFS file handle.
|
---|
| 1403 | * @sa RTFileTell, RTVfsIoStrmTell.
|
---|
| 1404 | */
|
---|
[33820] | 1405 | RTDECL(RTFOFF) RTVfsFileTell(RTVFSFILE hVfsFile);
|
---|
| 1406 |
|
---|
[34535] | 1407 | /**
|
---|
| 1408 | * Changes the current read/write position of a file.
|
---|
| 1409 | *
|
---|
| 1410 | * @returns IPRT status code.
|
---|
| 1411 | *
|
---|
| 1412 | * @param hVfsFile The VFS file handle.
|
---|
| 1413 | * @param offSeek The seek offset.
|
---|
| 1414 | * @param uMethod The seek emthod.
|
---|
| 1415 | * @param poffActual Where to optionally return the new file offset.
|
---|
| 1416 | *
|
---|
| 1417 | * @sa RTFileSeek
|
---|
| 1418 | */
|
---|
[33820] | 1419 | RTDECL(int) RTVfsFileSeek(RTVFSFILE hVfsFile, RTFOFF offSeek, uint32_t uMethod, uint64_t *poffActual);
|
---|
[34535] | 1420 |
|
---|
[69977] | 1421 | /**
|
---|
| 1422 | * Sets the size of a file.
|
---|
| 1423 | *
|
---|
| 1424 | * This may also be used for preallocating space
|
---|
| 1425 | * (RTVFSFILE_SIZE_F_PREALLOC_KEEP_SIZE).
|
---|
| 1426 | *
|
---|
| 1427 | * @returns IPRT status code.
|
---|
| 1428 | * @retval VERR_ACCESS_DENIED if handle isn't writable.
|
---|
| 1429 | * @retval VERR_WRITE_PROTECT if read-only file system.
|
---|
| 1430 | * @retval VERR_FILE_TOO_BIG if cbSize is larger than what the file system can
|
---|
| 1431 | * theoretically deal with.
|
---|
| 1432 | * @retval VERR_DISK_FULL if the file system if full.
|
---|
| 1433 | * @retval VERR_NOT_SUPPORTED if fFlags indicates some operation that's not
|
---|
| 1434 | * supported by the file system / host operating system.
|
---|
| 1435 | *
|
---|
| 1436 | * @param hVfsFile The VFS file handle.
|
---|
| 1437 | * @param cbSize The new file size.
|
---|
| 1438 | * @param fFlags RTVFSFILE_SIZE_F_NORMAL, RTVFSFILE_SIZE_F_GROW, or
|
---|
| 1439 | * RTVFSFILE_SIZE_F_GROW_KEEP_SIZE.
|
---|
| 1440 | *
|
---|
| 1441 | * @sa RTFileSetSize, RTFileSetAllocationSize
|
---|
| 1442 | */
|
---|
| 1443 | RTDECL(int) RTVfsFileSetSize(RTVFSFILE hVfsFile, uint64_t cbSize, uint32_t fFlags);
|
---|
| 1444 |
|
---|
| 1445 | /** @name RTVFSFILE_SIZE_F_XXX - RTVfsFileSetSize flags.
|
---|
| 1446 | * @{ */
|
---|
| 1447 | /** Normal truncate or grow (zero'ed) like RTFileSetSize . */
|
---|
| 1448 | #define RTVFSFILE_SIZE_F_NORMAL UINT32_C(0x00000001)
|
---|
| 1449 | /** Only grow the file, ignore call if cbSize would trunacte the file.
|
---|
| 1450 | * This is what RTFileSetAllocationSize does by default. */
|
---|
| 1451 | #define RTVFSFILE_SIZE_F_GROW UINT32_C(0x00000002)
|
---|
| 1452 | /** Only grow the file, ignore call if cbSize would trunacte the file.
|
---|
| 1453 | * This is what RTFileSetAllocationSize does by default. */
|
---|
| 1454 | #define RTVFSFILE_SIZE_F_GROW_KEEP_SIZE UINT32_C(0x00000003)
|
---|
| 1455 | /** Action mask. */
|
---|
| 1456 | #define RTVFSFILE_SIZE_F_ACTION_MASK UINT32_C(0x00000003)
|
---|
| 1457 | /** Validate the flags.
|
---|
| 1458 | * Will reference @a a_fFlags more than once. */
|
---|
| 1459 | #define RTVFSFILE_SIZE_F_IS_VALID(a_fFlags) \
|
---|
| 1460 | ( !((a_fFlags) & ~RTVFSFILE_SIZE_F_ACTION_MASK) && ((a_fFlags) & RTVFSFILE_SIZE_F_ACTION_MASK) != 0 )
|
---|
| 1461 | /** @} */
|
---|
| 1462 |
|
---|
| 1463 |
|
---|
| 1464 | /** Mask of valid flags. */
|
---|
| 1465 | #define RTFILE_ALLOC_SIZE_F_VALID (RTFILE_ALLOC_SIZE_F_KEEP_SIZE)
|
---|
| 1466 | /** @} */
|
---|
| 1467 |
|
---|
| 1468 |
|
---|
[33820] | 1469 | RTDECL(int) RTVfsFileGetSize(RTVFSFILE hVfsFile, uint64_t *pcbSize);
|
---|
| 1470 | RTDECL(RTFOFF) RTVfsFileGetMaxSize(RTVFSFILE hVfsFile);
|
---|
[69977] | 1471 | RTDECL(int) RTVfsFileQueryMaxSize(RTVFSFILE hVfsFile, uint64_t *pcbMax);
|
---|
[33820] | 1472 |
|
---|
[67221] | 1473 | /**
|
---|
| 1474 | * Get the RTFILE_O_XXX flags for the I/O stream.
|
---|
| 1475 | *
|
---|
| 1476 | * @returns RTFILE_O_XXX, 0 on failure.
|
---|
[67223] | 1477 | * @param hVfsFile The VFS file handle.
|
---|
[67221] | 1478 | */
|
---|
| 1479 | RTDECL(uint64_t) RTVfsFileGetOpenFlags(RTVFSFILE hVfsFile);
|
---|
| 1480 |
|
---|
[33820] | 1481 | /** @} */
|
---|
| 1482 |
|
---|
[33945] | 1483 |
|
---|
[66740] | 1484 | #ifdef DEBUG
|
---|
| 1485 | # undef RTVfsRetain
|
---|
| 1486 | # define RTVfsRetain(hVfs) RTVfsRetainDebug(hVfs, RT_SRC_POS)
|
---|
| 1487 | # undef RTVfsObjRetain
|
---|
| 1488 | # define RTVfsObjRetain(hVfsObj) RTVfsObjRetainDebug(hVfsObj, RT_SRC_POS)
|
---|
| 1489 | # undef RTVfsDirRetain
|
---|
| 1490 | # define RTVfsDirRetain(hVfsDir) RTVfsDirRetainDebug(hVfsDir, RT_SRC_POS)
|
---|
| 1491 | # undef RTVfsFileRetain
|
---|
| 1492 | # define RTVfsFileRetain(hVfsFile) RTVfsFileRetainDebug(hVfsFile, RT_SRC_POS)
|
---|
| 1493 | # undef RTVfsIoStrmRetain
|
---|
| 1494 | # define RTVfsIoStrmRetain(hVfsIos) RTVfsIoStrmRetainDebug(hVfsIos, RT_SRC_POS)
|
---|
| 1495 | # undef RTVfsFsStrmRetain
|
---|
| 1496 | # define RTVfsFsStrmRetain(hVfsFss) RTVfsFsStrmRetainDebug(hVfsFss, RT_SRC_POS)
|
---|
| 1497 | #endif
|
---|
| 1498 |
|
---|
| 1499 |
|
---|
| 1500 |
|
---|
[34435] | 1501 | /** @defgroup grp_vfs_misc VFS Miscellaneous
|
---|
[34391] | 1502 | * @{
|
---|
| 1503 | */
|
---|
| 1504 |
|
---|
| 1505 | /**
|
---|
| 1506 | * Memorizes the I/O stream as a file backed by memory.
|
---|
| 1507 | *
|
---|
[59620] | 1508 | * @returns IPRT status code.
|
---|
[34391] | 1509 | *
|
---|
| 1510 | * @param hVfsIos The VFS I/O stream to memorize. This will be read
|
---|
| 1511 | * to the end on success, on failure its position is
|
---|
| 1512 | * undefined.
|
---|
| 1513 | * @param fFlags A combination of RTFILE_O_READ and RTFILE_O_WRITE.
|
---|
| 1514 | * @param phVfsFile Where to return the handle to the memory file on
|
---|
| 1515 | * success.
|
---|
| 1516 | */
|
---|
| 1517 | RTDECL(int) RTVfsMemorizeIoStreamAsFile(RTVFSIOSTREAM hVfsIos, uint32_t fFlags, PRTVFSFILE phVfsFile);
|
---|
| 1518 |
|
---|
[34435] | 1519 | /**
|
---|
[59524] | 1520 | * Creates a VFS file from a memory buffer.
|
---|
| 1521 | *
|
---|
[59620] | 1522 | * @returns IPRT status code.
|
---|
[59524] | 1523 | *
|
---|
| 1524 | * @param fFlags A combination of RTFILE_O_READ and RTFILE_O_WRITE.
|
---|
| 1525 | * @param pvBuf The buffer. This will be copied and not referenced
|
---|
| 1526 | * after this function returns.
|
---|
| 1527 | * @param cbBuf The buffer size.
|
---|
| 1528 | * @param phVfsFile Where to return the handle to the memory file on
|
---|
| 1529 | * success.
|
---|
| 1530 | */
|
---|
[59620] | 1531 | RTDECL(int) RTVfsFileFromBuffer(uint32_t fFlags, void const *pvBuf, size_t cbBuf, PRTVFSFILE phVfsFile);
|
---|
[59524] | 1532 |
|
---|
| 1533 | /**
|
---|
| 1534 | * Creates a memory backed VFS file object for read and write.
|
---|
| 1535 | *
|
---|
[59620] | 1536 | * @returns IPRT status code.
|
---|
[59524] | 1537 | *
|
---|
| 1538 | * @param hVfsIos The VFS I/O stream to memorize. This will be read
|
---|
| 1539 | * to the end on success, on failure its position is
|
---|
| 1540 | * undefined.
|
---|
| 1541 | * @param cbEstimate The estimated file size.
|
---|
| 1542 | * @param phVfsFile Where to return the handle to the memory file on
|
---|
| 1543 | * success.
|
---|
[67180] | 1544 | * @sa RTVfsMemIoStrmCreate
|
---|
[59524] | 1545 | */
|
---|
| 1546 | RTDECL(int) RTVfsMemFileCreate(RTVFSIOSTREAM hVfsIos, size_t cbEstimate, PRTVFSFILE phVfsFile);
|
---|
| 1547 |
|
---|
| 1548 | /**
|
---|
[67180] | 1549 | * Creates a memory backed VFS file object for read and write.
|
---|
| 1550 | *
|
---|
| 1551 | * @returns IPRT status code.
|
---|
| 1552 | *
|
---|
| 1553 | * @param hVfsIos The VFS I/O stream to memorize. This will be read
|
---|
| 1554 | * to the end on success, on failure its position is
|
---|
| 1555 | * undefined.
|
---|
| 1556 | * @param cbEstimate The estimated file size.
|
---|
| 1557 | * @param phVfsIos Where to return the handle to the memory I/O stream
|
---|
| 1558 | * on success.
|
---|
| 1559 | * @sa RTVfsMemFileCreate
|
---|
| 1560 | */
|
---|
| 1561 | RTDECL(int) RTVfsMemIoStrmCreate(RTVFSIOSTREAM hVfsIos, size_t cbEstimate, PRTVFSIOSTREAM phVfsIos);
|
---|
| 1562 |
|
---|
| 1563 | /**
|
---|
[34435] | 1564 | * Pumps data from one I/O stream to another.
|
---|
| 1565 | *
|
---|
| 1566 | * The data is read in chunks from @a hVfsIosSrc and written to @a hVfsIosDst
|
---|
[57944] | 1567 | * until @a hVfsIosSrc indicates end of stream.
|
---|
[34435] | 1568 | *
|
---|
| 1569 | * @returns IPRT status code
|
---|
| 1570 | *
|
---|
| 1571 | * @param hVfsIosSrc The input stream.
|
---|
| 1572 | * @param hVfsIosDst The output stream.
|
---|
| 1573 | * @param cbBufHint Hints at a good temporary buffer size, pass 0 if
|
---|
| 1574 | * clueless.
|
---|
| 1575 | */
|
---|
| 1576 | RTDECL(int) RTVfsUtilPumpIoStreams(RTVFSIOSTREAM hVfsIosSrc, RTVFSIOSTREAM hVfsIosDst, size_t cbBufHint);
|
---|
| 1577 |
|
---|
[67221] | 1578 |
|
---|
[59754] | 1579 | /**
|
---|
[67221] | 1580 | * Creates a progress wrapper for an I/O stream.
|
---|
| 1581 | *
|
---|
| 1582 | * @returns IRPT status code.
|
---|
| 1583 | * @param hVfsIos The I/O stream to wrap.
|
---|
| 1584 | * @param pfnProgress The progress callback. The return code is
|
---|
[67228] | 1585 | * ignored by default, see
|
---|
| 1586 | * RTVFSPROGRESS_F_CANCELABLE.
|
---|
[67221] | 1587 | * @param pvUser The user argument to @a pfnProgress.
|
---|
| 1588 | * @param fFlags RTVFSPROGRESS_F_XXX
|
---|
| 1589 | * @param cbExpectedRead The expected number of bytes read.
|
---|
| 1590 | * @param cbExpectedWritten The execpted number of bytes written.
|
---|
| 1591 | * @param phVfsIos Where to return the I/O stream handle.
|
---|
| 1592 | */
|
---|
[67228] | 1593 | RTDECL(int) RTVfsCreateProgressForIoStream(RTVFSIOSTREAM hVfsIos, PFNRTPROGRESS pfnProgress, void *pvUser, uint32_t fFlags,
|
---|
| 1594 | uint64_t cbExpectedRead, uint64_t cbExpectedWritten, PRTVFSIOSTREAM phVfsIos);
|
---|
[67221] | 1595 |
|
---|
| 1596 | /**
|
---|
| 1597 | * Creates a progress wrapper for a file stream.
|
---|
| 1598 | *
|
---|
| 1599 | * @returns IRPT status code.
|
---|
| 1600 | * @param hVfsFile The file to wrap.
|
---|
| 1601 | * @param pfnProgress The progress callback. The return code is
|
---|
[67228] | 1602 | * ignored by default, see
|
---|
| 1603 | * RTVFSPROGRESS_F_CANCELABLE.
|
---|
[67221] | 1604 | * @param pvUser The user argument to @a pfnProgress.
|
---|
| 1605 | * @param fFlags RTVFSPROGRESS_F_XXX
|
---|
| 1606 | * @param cbExpectedRead The expected number of bytes read.
|
---|
| 1607 | * @param cbExpectedWritten The execpted number of bytes written.
|
---|
| 1608 | * @param phVfsFile Where to return the file handle.
|
---|
| 1609 | */
|
---|
[67228] | 1610 | RTDECL(int) RTVfsCreateProgressForFile(RTVFSFILE hVfsFile, PFNRTPROGRESS pfnProgress, void *pvUser, uint32_t fFlags,
|
---|
| 1611 | uint64_t cbExpectedRead, uint64_t cbExpectedWritten, PRTVFSFILE phVfsFile);
|
---|
[67221] | 1612 |
|
---|
| 1613 | /** @name RTVFSPROGRESS_F_XXX - Flags for RTVfsCreateProcessForIoStream and
|
---|
| 1614 | * RTVfsCreateProcessForFile.
|
---|
| 1615 | * @{ */
|
---|
[67228] | 1616 | /** Cancel if the callback returns a failure status code.
|
---|
| 1617 | * This isn't default behavior because the cancelation is delayed one I/O
|
---|
| 1618 | * operation in most cases and it's uncertain how the VFS user will handle the
|
---|
| 1619 | * cancellation status code. */
|
---|
| 1620 | #define RTVFSPROGRESS_F_CANCELABLE RT_BIT_32(0)
|
---|
[67221] | 1621 | /** Account forward seeks as reads. */
|
---|
[67224] | 1622 | #define RTVFSPROGRESS_F_FORWARD_SEEK_AS_READ RT_BIT_32(1)
|
---|
[67221] | 1623 | /** Account fprward seeks as writes. */
|
---|
[67224] | 1624 | #define RTVFSPROGRESS_F_FORWARD_SEEK_AS_WRITE RT_BIT_32(2)
|
---|
[67221] | 1625 | /** Valid bits. */
|
---|
[67224] | 1626 | #define RTVFSPROGRESS_F_VALID_MASK UINT32_C(0x00000007)
|
---|
[67221] | 1627 | /** @} */
|
---|
| 1628 |
|
---|
| 1629 |
|
---|
| 1630 | /**
|
---|
[59754] | 1631 | * Create an I/O stream instance performing simple sequential read-ahead.
|
---|
| 1632 | *
|
---|
| 1633 | * @returns IPRT status code.
|
---|
| 1634 | * @param hVfsIos The input stream to perform read ahead on. If this is
|
---|
| 1635 | * actually for a file object, the returned I/O stream
|
---|
| 1636 | * handle can also be cast to a file handle.
|
---|
| 1637 | * @param fFlags Flags reserved for future use, MBZ.
|
---|
| 1638 | * @param cBuffers How many read ahead buffers to use. Specify 0 for
|
---|
| 1639 | * default value.
|
---|
[59759] | 1640 | * @param cbBuffer The size of each read ahead buffer. Specify 0 for
|
---|
[59754] | 1641 | * default value.
|
---|
| 1642 | * @param phVfsIos Where to return the read ahead I/O stream handle.
|
---|
| 1643 | *
|
---|
| 1644 | * @remarks Careful using this on a message pipe or socket. The reads are
|
---|
| 1645 | * performed in blocked mode and it may be host and/or implementation
|
---|
| 1646 | * dependent whether they will return ready data immediate or wait
|
---|
| 1647 | * until there's a whole @a cbBuffer (or default) worth ready.
|
---|
| 1648 | *
|
---|
| 1649 | * @sa RTVfsCreateReadAheadForFile
|
---|
| 1650 | */
|
---|
| 1651 | RTDECL(int) RTVfsCreateReadAheadForIoStream(RTVFSIOSTREAM hVfsIos, uint32_t fFlags, uint32_t cBuffers, uint32_t cbBuffer,
|
---|
| 1652 | PRTVFSIOSTREAM phVfsIos);
|
---|
| 1653 |
|
---|
| 1654 | /**
|
---|
| 1655 | * Create an I/O stream instance performing simple sequential read-ahead.
|
---|
| 1656 | *
|
---|
| 1657 | * @returns IPRT status code.
|
---|
| 1658 | * @param hVfsFile The input file to perform read ahead on.
|
---|
| 1659 | * @param fFlags Flags reserved for future use, MBZ.
|
---|
| 1660 | * @param cBuffers How many read ahead buffers to use. Specify 0 for
|
---|
| 1661 | * default value.
|
---|
[59759] | 1662 | * @param cbBuffer The size of each read ahead buffer. Specify 0 for
|
---|
[59754] | 1663 | * default value.
|
---|
[59759] | 1664 | * @param phVfsFile Where to return the read ahead file handle.
|
---|
[59754] | 1665 | * @sa RTVfsCreateReadAheadForIoStream
|
---|
| 1666 | */
|
---|
| 1667 | RTDECL(int) RTVfsCreateReadAheadForFile(RTVFSFILE hVfsFile, uint32_t fFlags, uint32_t cBuffers, uint32_t cbBuffer,
|
---|
| 1668 | PRTVFSFILE phVfsFile);
|
---|
| 1669 |
|
---|
[67186] | 1670 |
|
---|
| 1671 | /**
|
---|
| 1672 | * Create a file system stream for writing to a directory.
|
---|
| 1673 | *
|
---|
| 1674 | * This is just supposed to be a drop in replacement for the TAR creator stream
|
---|
| 1675 | * that instead puts the files and stuff in a directory instead of a TAR
|
---|
| 1676 | * archive. In addition, it has an undo feature for simplying cleaning up after
|
---|
| 1677 | * a botched run
|
---|
| 1678 | *
|
---|
| 1679 | * @returns IPRT status code.
|
---|
| 1680 | * @param hVfsBaseDir The base directory.
|
---|
| 1681 | * @param fFlags RTVFSFSS2DIR_F_XXX
|
---|
| 1682 | * @param phVfsFss Where to return the FSS handle.
|
---|
| 1683 | * @sa RTVfsFsStrmToNormalDir, RTVfsFsStrmToDirUndo
|
---|
| 1684 | */
|
---|
| 1685 | RTDECL(int) RTVfsFsStrmToDir(RTVFSDIR hVfsBaseDir, uint32_t fFlags, PRTVFSFSSTREAM phVfsFss);
|
---|
| 1686 |
|
---|
| 1687 | /**
|
---|
| 1688 | * Create a file system stream for writing to a normal directory.
|
---|
| 1689 | *
|
---|
| 1690 | * This is just supposed to be a drop in replacement for the TAR creator stream
|
---|
| 1691 | * that instead puts the files and stuff in a directory instead of a TAR
|
---|
| 1692 | * archive. In addition, it has an undo feature for simplying cleaning up after
|
---|
| 1693 | * a botched run
|
---|
| 1694 | *
|
---|
| 1695 | * @returns IPRT status code.
|
---|
| 1696 | * @param pszBaseDir The base directory. Must exist.
|
---|
| 1697 | * @param fFlags RTVFSFSS2DIR_F_XXX
|
---|
| 1698 | * @param phVfsFss Where to return the FSS handle.
|
---|
| 1699 | * @sa RTVfsFsStrmToDir, RTVfsFsStrmToDirUndo
|
---|
| 1700 | */
|
---|
| 1701 | RTDECL(int) RTVfsFsStrmToNormalDir(const char *pszBaseDir, uint32_t fFlags, PRTVFSFSSTREAM phVfsFss);
|
---|
| 1702 |
|
---|
| 1703 | /** @name RTVFSFSS2DIR_F_XXX - Flags for RTVfsFsStrmToNormalDir
|
---|
| 1704 | * @{ */
|
---|
| 1705 | /** Overwrite existing files (default is to not overwrite anything). */
|
---|
| 1706 | #define RTVFSFSS2DIR_F_OVERWRITE_FILES RT_BIT_32(0)
|
---|
| 1707 | /** Valid bits. */
|
---|
| 1708 | #define RTVFSFSS2DIR_F_VALID_MASK UINT32_C(0x00000001)
|
---|
| 1709 | /** @} */
|
---|
| 1710 |
|
---|
| 1711 | /**
|
---|
| 1712 | * Deletes files, directories, symlinks and stuff created by a FSS returned by
|
---|
| 1713 | * RTVfsFsStrmToNormalDir or RTVfsFsStrmToDir.
|
---|
| 1714 | *
|
---|
| 1715 | * @returns IPRT status code.
|
---|
| 1716 | * @param hVfsFss The write-to-directory FSS handle.
|
---|
| 1717 | */
|
---|
| 1718 | RTDECL(int) RTVfsFsStrmToDirUndo(RTVFSFSSTREAM hVfsFss);
|
---|
| 1719 |
|
---|
| 1720 |
|
---|
| 1721 |
|
---|
[34391] | 1722 | /** @} */
|
---|
| 1723 |
|
---|
| 1724 |
|
---|
[33945] | 1725 | /** @defgroup grp_rt_vfs_chain VFS Chains
|
---|
| 1726 | *
|
---|
| 1727 | * VFS chains is for doing pipe like things with VFS objects from the command
|
---|
| 1728 | * line. Imagine you want to cat the readme.gz of an ISO you could do
|
---|
| 1729 | * something like:
|
---|
[66594] | 1730 | * RTCat :iprtvfs:file(stdfile,live.iso)|vfs(isofs)|iso(open,readme.gz)|ios(gunzip)
|
---|
[33945] | 1731 | * or
|
---|
[66594] | 1732 | * RTCat :iprtvfs:file(stdfile,live.iso)|ios(isofs,readme.gz)|ios(gunzip)
|
---|
[33945] | 1733 | *
|
---|
[66594] | 1734 | * Or say you want to read the README.TXT on a floppy image:
|
---|
| 1735 | * RTCat :iprtvfs:file(stdfile,floppy.img,r)|vfs(fat)|ios(open,README.TXT)
|
---|
[66762] | 1736 | * or
|
---|
| 1737 | * RTCat :iprtvfs:file(stdfile,floppy.img,r)|vfs(fat)|README.TXT
|
---|
[33945] | 1738 | *
|
---|
[66594] | 1739 | * Or in the other direction, you want to write a STUFF.TGZ file to the above
|
---|
| 1740 | * floppy image, using a lazy writer thread for compressing the data:
|
---|
| 1741 | * RTTar cf :iprtvfs:file(stdfile,floppy.img,rw)|ios(fat,STUFF.TGZ)|ios(gzip)|ios(push) .
|
---|
| 1742 | *
|
---|
| 1743 | *
|
---|
| 1744 | * A bit more formally:
|
---|
[66762] | 1745 | * :iprtvfs:{type}({provider}[,provider-args])[{separator}{type}...][{separator}{path}]
|
---|
[66594] | 1746 | *
|
---|
| 1747 | * The @c type refers to VFS object that should be created by the @c provider.
|
---|
| 1748 | * Valid types:
|
---|
| 1749 | * - vfs: A virtual file system (volume).
|
---|
| 1750 | * - fss: A file system stream (e.g. tar).
|
---|
| 1751 | * - ios: An I/O stream.
|
---|
| 1752 | * - file: A file.
|
---|
| 1753 | * - dir: A directory.
|
---|
| 1754 | * - sym: A symbolic link (not sure how useful this is).
|
---|
| 1755 | *
|
---|
| 1756 | * The @c provider refers to registered chain element providers (see
|
---|
| 1757 | * RTVFSCHAINELEMENTREG for how that works internally). These are asked to
|
---|
| 1758 | * create a VFS object of the specified type using the given arguments (if any).
|
---|
| 1759 | * Default providers:
|
---|
| 1760 | * - std: Standard file, directory and file system.
|
---|
| 1761 | * - open: Opens a file, I/O stream or directory in a vfs or directory object.
|
---|
| 1762 | * - pull: Read-ahead buffering thread on file or I/O stream.
|
---|
| 1763 | * - push: Lazy-writer buffering thread on file or I/O stream.
|
---|
| 1764 | * - gzip: Compresses an I/O stream.
|
---|
| 1765 | * - gunzip: Decompresses an I/O stream.
|
---|
| 1766 | * - fat: FAT file system accessor.
|
---|
| 1767 | * - isofs: ISOFS file system accessor.
|
---|
| 1768 | *
|
---|
| 1769 | * As element @c separator we allow both colon (':') and the pipe character
|
---|
| 1770 | * ('|'). The latter the conventional one, but since it's inconvenient on the
|
---|
| 1771 | * command line, colon is provided as an alternative.
|
---|
| 1772 | *
|
---|
[66762] | 1773 | * In the final element we allow a simple @a path to be specified instead of the
|
---|
| 1774 | * type-provider-arguments stuff. The previous object must be a directory, file
|
---|
| 1775 | * system or file system stream. The application will determin exactly which
|
---|
| 1776 | * operation or operations which will be performed.
|
---|
| 1777 | *
|
---|
[66594] | 1778 | * @{
|
---|
| 1779 | */
|
---|
[33945] | 1780 |
|
---|
| 1781 | /** The path prefix used to identify an VFS chain specification. */
|
---|
| 1782 | #define RTVFSCHAIN_SPEC_PREFIX ":iprtvfs:"
|
---|
| 1783 |
|
---|
[66602] | 1784 | RTDECL(int) RTVfsChainOpenVfs(const char *pszSpec, PRTVFS phVfs, uint32_t *poffError, PRTERRINFO pErrInfo);
|
---|
| 1785 | RTDECL(int) RTVfsChainOpenFsStream(const char *pszSpec, PRTVFSFSSTREAM phVfsFss, uint32_t *poffError, PRTERRINFO pErrInfo);
|
---|
[69813] | 1786 |
|
---|
| 1787 | /**
|
---|
| 1788 | * Opens any kind of file system object.
|
---|
| 1789 | *
|
---|
| 1790 | * @returns IPRT status code.
|
---|
| 1791 | * @param pszSpec The VFS chain specification or plain path.
|
---|
| 1792 | * @param fFileOpen RTFILE_O_XXX flags.
|
---|
| 1793 | * @param fObjFlags More flags: RTVFSOBJ_F_XXX, RTPATH_F_XXX.
|
---|
| 1794 | * @param phVfsObj Where to return the handle to the opened object.
|
---|
| 1795 | * @param poffError Where to on error return an offset into @a pszSpec
|
---|
| 1796 | * of what cause the error. Optional.
|
---|
| 1797 | * @param pErrInfo Where to return additional error information.
|
---|
| 1798 | * Optional.
|
---|
| 1799 | */
|
---|
[69817] | 1800 | RTDECL(int) RTVfsChainOpenObj(const char *pszSpec, uint64_t fFileOpen, uint32_t fObjFlags,
|
---|
[69813] | 1801 | PRTVFSOBJ phVfsObj, uint32_t *poffError, PRTERRINFO pErrInfo);
|
---|
| 1802 |
|
---|
[66762] | 1803 | RTDECL(int) RTVfsChainOpenDir(const char *pszSpec, uint32_t fOpen, PRTVFSDIR phVfsDir, uint32_t *poffError, PRTERRINFO pErrInfo);
|
---|
[69716] | 1804 | RTDECL(int) RTVfsChainOpenParentDir(const char *pszSpec, uint32_t fOpen, PRTVFSDIR phVfsDir, const char **ppszChild,
|
---|
| 1805 | uint32_t *poffError, PRTERRINFO pErrInfo);
|
---|
[66602] | 1806 | RTDECL(int) RTVfsChainOpenFile(const char *pszSpec, uint64_t fOpen, PRTVFSFILE phVfsFile, uint32_t *poffError, PRTERRINFO pErrInfo);
|
---|
| 1807 | RTDECL(int) RTVfsChainOpenIoStream(const char *pszSpec, uint64_t fOpen, PRTVFSIOSTREAM phVfsIos, uint32_t *poffError, PRTERRINFO pErrInfo);
|
---|
| 1808 | RTDECL(int) RTVfsChainOpenSymlink(const char *pszSpec, PRTVFSSYMLINK phVfsSym, uint32_t *poffError, PRTERRINFO pErrInfo);
|
---|
[33945] | 1809 |
|
---|
[66762] | 1810 | RTDECL(int) RTVfsChainQueryInfo(const char *pszSpec, PRTFSOBJINFO pObjInfo, RTFSOBJATTRADD enmAdditionalAttribs,
|
---|
| 1811 | uint32_t fFlags, uint32_t *poffError, PRTERRINFO pErrInfo);
|
---|
| 1812 |
|
---|
[33973] | 1813 | /**
|
---|
| 1814 | * Tests if the given string is a chain specification or not.
|
---|
| 1815 | *
|
---|
| 1816 | * @returns true if it is, false if it isn't.
|
---|
| 1817 | * @param pszSpec The alleged chain spec.
|
---|
| 1818 | */
|
---|
[66602] | 1819 | RTDECL(bool) RTVfsChainIsSpec(const char *pszSpec);
|
---|
[33973] | 1820 |
|
---|
[66602] | 1821 | /**
|
---|
[67134] | 1822 | * Queries the path from the final element.
|
---|
| 1823 | *
|
---|
| 1824 | * @returns IPRT status code.
|
---|
| 1825 | * @retval VERR_VFS_CHAIN_NOT_PATH_ONLY if the final element isn't just a
|
---|
| 1826 | * simple path.
|
---|
| 1827 | * @param pszSpec The chain spec.
|
---|
| 1828 | * @param ppszFinalPath Where to return a copy of the final path on success.
|
---|
| 1829 | * Call RTStrFree when done.
|
---|
| 1830 | * @param poffError Where to on error return an offset into @a pszSpec
|
---|
| 1831 | * of what cause the error. Optional.
|
---|
| 1832 | *
|
---|
| 1833 | */
|
---|
| 1834 | RTDECL(int) RTVfsChainQueryFinalPath(const char *pszSpec, char **ppszFinalPath, uint32_t *poffError);
|
---|
| 1835 |
|
---|
| 1836 | /**
|
---|
[69716] | 1837 | * Splits the given chain spec into a final path and the preceeding spec.
|
---|
| 1838 | *
|
---|
| 1839 | * This works on plain paths too.
|
---|
| 1840 | *
|
---|
| 1841 | * @returns IPRT status code.
|
---|
| 1842 | * @param pszSpec The chain spec to split. This will be modified!
|
---|
| 1843 | * @param ppszSpec Where to return the pointer to the chain spec part.
|
---|
| 1844 | * This is set to NULL if it's a plain path or a chain
|
---|
| 1845 | * spec with only a final-path element.
|
---|
| 1846 | * @param ppszFinalPath Where to return the pointer to the final path. This
|
---|
| 1847 | * is set to NULL if no final path.
|
---|
| 1848 | * @param poffError Where to on error return an offset into @a pszSpec
|
---|
| 1849 | * of what cause the error. Optional.
|
---|
| 1850 | */
|
---|
| 1851 | RTDECL(int) RTVfsChainSplitOffFinalPath(char *pszSpec, char **ppszSpec, char **ppszFinalPath, uint32_t *poffError);
|
---|
| 1852 |
|
---|
| 1853 | /**
|
---|
[66602] | 1854 | * Common code for reporting errors of a RTVfsChainOpen* API.
|
---|
| 1855 | *
|
---|
| 1856 | * @param pszFunction The API called.
|
---|
| 1857 | * @param pszSpec The VFS chain specification or file path passed to the.
|
---|
| 1858 | * @param rc The return code.
|
---|
| 1859 | * @param offError The error offset value returned (0 if not captured).
|
---|
| 1860 | * @param pErrInfo Additional error information. Optional.
|
---|
| 1861 | *
|
---|
| 1862 | * @sa RTVfsChainMsgErrorExitFailure
|
---|
| 1863 | * @sa RTVfsChainOpenVfs, RTVfsChainOpenFsStream, RTVfsChainOpenDir,
|
---|
| 1864 | * RTVfsChainOpenFile, RTVfsChainOpenIoStream, RTVfsChainOpenSymlink
|
---|
| 1865 | */
|
---|
| 1866 | RTDECL(void) RTVfsChainMsgError(const char *pszFunction, const char *pszSpec, int rc, uint32_t offError, PRTERRINFO pErrInfo);
|
---|
| 1867 |
|
---|
| 1868 | /**
|
---|
| 1869 | * Common code for reporting errors of a RTVfsChainOpen* API.
|
---|
| 1870 | *
|
---|
| 1871 | * @returns RTEXITCODE_FAILURE
|
---|
| 1872 | *
|
---|
| 1873 | * @param pszFunction The API called.
|
---|
| 1874 | * @param pszSpec The VFS chain specification or file path passed to the.
|
---|
| 1875 | * @param rc The return code.
|
---|
| 1876 | * @param offError The error offset value returned (0 if not captured).
|
---|
| 1877 | * @param pErrInfo Additional error information. Optional.
|
---|
| 1878 | *
|
---|
| 1879 | * @sa RTVfsChainMsgError
|
---|
| 1880 | * @sa RTVfsChainOpenVfs, RTVfsChainOpenFsStream, RTVfsChainOpenDir,
|
---|
| 1881 | * RTVfsChainOpenFile, RTVfsChainOpenIoStream, RTVfsChainOpenSymlink
|
---|
| 1882 | */
|
---|
| 1883 | RTDECL(RTEXITCODE) RTVfsChainMsgErrorExitFailure(const char *pszFunction, const char *pszSpec,
|
---|
| 1884 | int rc, uint32_t offError, PRTERRINFO pErrInfo);
|
---|
| 1885 |
|
---|
| 1886 |
|
---|
[66594] | 1887 | /** @} */
|
---|
[33945] | 1888 |
|
---|
| 1889 |
|
---|
[33820] | 1890 | /** @} */
|
---|
| 1891 |
|
---|
| 1892 | RT_C_DECLS_END
|
---|
| 1893 |
|
---|
[76585] | 1894 | #endif /* !IPRT_INCLUDED_vfs_h */
|
---|
[33820] | 1895 |
|
---|