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