[1] | 1 | /** @file
|
---|
[8245] | 2 | * IPRT - File I/O.
|
---|
[1] | 3 | */
|
---|
| 4 |
|
---|
| 5 | /*
|
---|
[98103] | 6 | * Copyright (C) 2006-2023 Oracle and/or its affiliates.
|
---|
[1] | 7 | *
|
---|
[96407] | 8 | * This file is part of VirtualBox base platform packages, as
|
---|
| 9 | * available from https://www.virtualbox.org.
|
---|
[5999] | 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 | *
|
---|
[5999] | 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
|
---|
[5999] | 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
|
---|
[1] | 34 | */
|
---|
| 35 |
|
---|
[76557] | 36 | #ifndef IPRT_INCLUDED_file_h
|
---|
| 37 | #define IPRT_INCLUDED_file_h
|
---|
[76507] | 38 | #ifndef RT_WITHOUT_PRAGMA_ONCE
|
---|
| 39 | # pragma once
|
---|
| 40 | #endif
|
---|
[1] | 41 |
|
---|
| 42 | #include <iprt/cdefs.h>
|
---|
| 43 | #include <iprt/types.h>
|
---|
[26060] | 44 | #include <iprt/stdarg.h>
|
---|
[37559] | 45 | #include <iprt/fs.h>
|
---|
[46245] | 46 | #include <iprt/sg.h>
|
---|
[1] | 47 |
|
---|
[20374] | 48 | RT_C_DECLS_BEGIN
|
---|
[1] | 49 |
|
---|
| 50 | /** @defgroup grp_rt_fileio RTFile - File I/O
|
---|
| 51 | * @ingroup grp_rt
|
---|
| 52 | * @{
|
---|
| 53 | */
|
---|
| 54 |
|
---|
| 55 | /** Platform specific text line break.
|
---|
| 56 | * @deprecated Use text I/O streams and '\\n'. See iprt/stream.h. */
|
---|
[3636] | 57 | #if defined(RT_OS_OS2) || defined(RT_OS_WINDOWS)
|
---|
[1] | 58 | # define RTFILE_LINEFEED "\r\n"
|
---|
| 59 | #else
|
---|
| 60 | # define RTFILE_LINEFEED "\n"
|
---|
| 61 | #endif
|
---|
| 62 |
|
---|
[33233] | 63 | /** Platform specific native standard input "handle". */
|
---|
| 64 | #ifdef RT_OS_WINDOWS
|
---|
| 65 | # define RTFILE_NATIVE_STDIN ((uint32_t)-10)
|
---|
| 66 | #else
|
---|
| 67 | # define RTFILE_NATIVE_STDIN 0
|
---|
| 68 | #endif
|
---|
[1] | 69 |
|
---|
[39195] | 70 | /** Platform specific native standard out "handle". */
|
---|
[33233] | 71 | #ifdef RT_OS_WINDOWS
|
---|
| 72 | # define RTFILE_NATIVE_STDOUT ((uint32_t)-11)
|
---|
| 73 | #else
|
---|
| 74 | # define RTFILE_NATIVE_STDOUT 1
|
---|
| 75 | #endif
|
---|
| 76 |
|
---|
| 77 | /** Platform specific native standard error "handle". */
|
---|
| 78 | #ifdef RT_OS_WINDOWS
|
---|
| 79 | # define RTFILE_NATIVE_STDERR ((uint32_t)-12)
|
---|
| 80 | #else
|
---|
| 81 | # define RTFILE_NATIVE_STDERR 2
|
---|
| 82 | #endif
|
---|
| 83 |
|
---|
| 84 |
|
---|
[22516] | 85 | /**
|
---|
| 86 | * Checks if the specified file name exists and is a regular file.
|
---|
| 87 | *
|
---|
| 88 | * Symbolic links will be resolved.
|
---|
| 89 | *
|
---|
| 90 | * @returns true if it's a regular file, false if it isn't.
|
---|
| 91 | * @param pszPath The path to the file.
|
---|
| 92 | *
|
---|
| 93 | * @sa RTDirExists, RTPathExists, RTSymlinkExists.
|
---|
| 94 | */
|
---|
| 95 | RTDECL(bool) RTFileExists(const char *pszPath);
|
---|
| 96 |
|
---|
[24189] | 97 | /**
|
---|
| 98 | * Queries the size of a file, given the path to it.
|
---|
| 99 | *
|
---|
| 100 | * Symbolic links will be resolved.
|
---|
| 101 | *
|
---|
| 102 | * @returns IPRT status code.
|
---|
| 103 | * @param pszPath The path to the file.
|
---|
| 104 | * @param pcbFile Where to return the file size (bytes).
|
---|
| 105 | *
|
---|
[80585] | 106 | * @sa RTFileQuerySize, RTPathQueryInfoEx.
|
---|
[24189] | 107 | */
|
---|
[80585] | 108 | RTDECL(int) RTFileQuerySizeByPath(const char *pszPath, uint64_t *pcbFile);
|
---|
[22516] | 109 |
|
---|
[24189] | 110 |
|
---|
[1] | 111 | /** @name Open flags
|
---|
| 112 | * @{ */
|
---|
[58768] | 113 | /** Attribute access only.
|
---|
| 114 | * @remarks Only accepted on windows, requires RTFILE_O_ACCESS_ATTR_MASK
|
---|
| 115 | * to yield a non-zero result. Otherwise, this is invalid. */
|
---|
| 116 | #define RTFILE_O_ATTR_ONLY UINT32_C(0x00000000)
|
---|
[1] | 117 | /** Open the file with read access. */
|
---|
[23974] | 118 | #define RTFILE_O_READ UINT32_C(0x00000001)
|
---|
[1] | 119 | /** Open the file with write access. */
|
---|
[23974] | 120 | #define RTFILE_O_WRITE UINT32_C(0x00000002)
|
---|
[1] | 121 | /** Open the file with read & write access. */
|
---|
[23974] | 122 | #define RTFILE_O_READWRITE UINT32_C(0x00000003)
|
---|
[1] | 123 | /** The file access mask.
|
---|
[58768] | 124 | * @remarks The value 0 is invalid, except for windows special case. */
|
---|
[23974] | 125 | #define RTFILE_O_ACCESS_MASK UINT32_C(0x00000003)
|
---|
[1] | 126 |
|
---|
[21582] | 127 | /** Open file in APPEND mode, so all writes to the file handle will
|
---|
| 128 | * append data at the end of the file.
|
---|
[21616] | 129 | * @remarks It is ignored if write access is not requested, that is
|
---|
[82837] | 130 | * RTFILE_O_WRITE is not set.
|
---|
| 131 | * @note Behaviour of functions differ between hosts: See RTFileWriteAt, as
|
---|
| 132 | * well as ticketref:19003 (RTFileSetSize). */
|
---|
[23974] | 133 | #define RTFILE_O_APPEND UINT32_C(0x00000004)
|
---|
| 134 | /* UINT32_C(0x00000008) is unused atm. */
|
---|
[21582] | 135 |
|
---|
[23973] | 136 | /** Sharing mode: deny none. */
|
---|
[23974] | 137 | #define RTFILE_O_DENY_NONE UINT32_C(0x00000080)
|
---|
[1] | 138 | /** Sharing mode: deny read. */
|
---|
[23974] | 139 | #define RTFILE_O_DENY_READ UINT32_C(0x00000010)
|
---|
[1] | 140 | /** Sharing mode: deny write. */
|
---|
[23974] | 141 | #define RTFILE_O_DENY_WRITE UINT32_C(0x00000020)
|
---|
[1] | 142 | /** Sharing mode: deny read and write. */
|
---|
[23974] | 143 | #define RTFILE_O_DENY_READWRITE UINT32_C(0x00000030)
|
---|
[1] | 144 | /** Sharing mode: deny all. */
|
---|
[21616] | 145 | #define RTFILE_O_DENY_ALL RTFILE_O_DENY_READWRITE
|
---|
[1] | 146 | /** Sharing mode: do NOT deny delete (NT).
|
---|
[21616] | 147 | * @remarks This might not be implemented on all platforms, and will be
|
---|
| 148 | * defaulted & ignored on those.
|
---|
[1] | 149 | */
|
---|
[23974] | 150 | #define RTFILE_O_DENY_NOT_DELETE UINT32_C(0x00000040)
|
---|
[1] | 151 | /** Sharing mode mask. */
|
---|
[23974] | 152 | #define RTFILE_O_DENY_MASK UINT32_C(0x000000f0)
|
---|
[1] | 153 |
|
---|
[77681] | 154 | /** Action: Open an existing file. */
|
---|
[23974] | 155 | #define RTFILE_O_OPEN UINT32_C(0x00000700)
|
---|
[1] | 156 | /** Action: Create a new file or open an existing one. */
|
---|
[23974] | 157 | #define RTFILE_O_OPEN_CREATE UINT32_C(0x00000100)
|
---|
[1] | 158 | /** Action: Create a new a file. */
|
---|
[23974] | 159 | #define RTFILE_O_CREATE UINT32_C(0x00000200)
|
---|
[1] | 160 | /** Action: Create a new file or replace an existing one. */
|
---|
[23974] | 161 | #define RTFILE_O_CREATE_REPLACE UINT32_C(0x00000300)
|
---|
[1] | 162 | /** Action mask. */
|
---|
[23974] | 163 | #define RTFILE_O_ACTION_MASK UINT32_C(0x00000700)
|
---|
[1] | 164 |
|
---|
[6992] | 165 | /** Turns off indexing of files on Windows hosts, *CREATE* only.
|
---|
[21616] | 166 | * @remarks Window only. */
|
---|
[23974] | 167 | #define RTFILE_O_NOT_CONTENT_INDEXED UINT32_C(0x00000800)
|
---|
[1] | 168 | /** Truncate the file.
|
---|
[21616] | 169 | * @remarks This will not truncate files opened for read-only.
|
---|
[47735] | 170 | * @remarks The truncation doesn't have to be atomically, so anyone else opening
|
---|
[21616] | 171 | * the file may be racing us. The caller is responsible for not causing
|
---|
| 172 | * this race. */
|
---|
[23974] | 173 | #define RTFILE_O_TRUNCATE UINT32_C(0x00001000)
|
---|
[1] | 174 | /** Make the handle inheritable on RTProcessCreate(/exec). */
|
---|
[23974] | 175 | #define RTFILE_O_INHERIT UINT32_C(0x00002000)
|
---|
[1] | 176 | /** Open file in non-blocking mode - non-portable.
|
---|
[21616] | 177 | * @remarks This flag may not be supported on all platforms, in which case it's
|
---|
| 178 | * considered an invalid parameter. */
|
---|
[23974] | 179 | #define RTFILE_O_NON_BLOCK UINT32_C(0x00004000)
|
---|
[1] | 180 | /** Write through directly to disk. Workaround to avoid iSCSI
|
---|
| 181 | * initiator deadlocks on Windows hosts.
|
---|
[21616] | 182 | * @remarks This might not be implemented on all platforms, and will be ignored
|
---|
| 183 | * on those. */
|
---|
[23974] | 184 | #define RTFILE_O_WRITE_THROUGH UINT32_C(0x00008000)
|
---|
[18128] | 185 |
|
---|
[21616] | 186 | /** Attribute access: Attributes can be read if the file is being opened with
|
---|
| 187 | * read access, and can be written with write access. */
|
---|
[23974] | 188 | #define RTFILE_O_ACCESS_ATTR_DEFAULT UINT32_C(0x00000000)
|
---|
[21616] | 189 | /** Attribute access: Attributes can be read.
|
---|
| 190 | * @remarks Windows only. */
|
---|
[23974] | 191 | #define RTFILE_O_ACCESS_ATTR_READ UINT32_C(0x00010000)
|
---|
[21616] | 192 | /** Attribute access: Attributes can be written.
|
---|
| 193 | * @remarks Windows only. */
|
---|
[23974] | 194 | #define RTFILE_O_ACCESS_ATTR_WRITE UINT32_C(0x00020000)
|
---|
[21616] | 195 | /** Attribute access: Attributes can be both read & written.
|
---|
| 196 | * @remarks Windows only. */
|
---|
[23974] | 197 | #define RTFILE_O_ACCESS_ATTR_READWRITE UINT32_C(0x00030000)
|
---|
[21616] | 198 | /** Attribute access: The file attributes access mask.
|
---|
| 199 | * @remarks Windows only. */
|
---|
[23974] | 200 | #define RTFILE_O_ACCESS_ATTR_MASK UINT32_C(0x00030000)
|
---|
[18128] | 201 |
|
---|
[21582] | 202 | /** Open file for async I/O
|
---|
[21616] | 203 | * @remarks This flag may not be needed on all platforms, and will be ignored on
|
---|
| 204 | * those. */
|
---|
[23974] | 205 | #define RTFILE_O_ASYNC_IO UINT32_C(0x00040000)
|
---|
[21582] | 206 |
|
---|
[21573] | 207 | /** Disables caching.
|
---|
| 208 | *
|
---|
| 209 | * Useful when using very big files which might bring the host I/O scheduler to
|
---|
| 210 | * its knees during high I/O load.
|
---|
| 211 | *
|
---|
| 212 | * @remarks This flag might impose restrictions
|
---|
[21493] | 213 | * on the buffer alignment, start offset and/or transfer size.
|
---|
[21573] | 214 | *
|
---|
[21493] | 215 | * On Linux the buffer needs to be aligned to the 512 sector
|
---|
| 216 | * boundary.
|
---|
[21573] | 217 | *
|
---|
| 218 | * On Windows the FILE_FLAG_NO_BUFFERING is used (see
|
---|
| 219 | * http://msdn.microsoft.com/en-us/library/cc644950(VS.85).aspx ).
|
---|
[34435] | 220 | * The buffer address, the transfer size and offset needs to be aligned
|
---|
| 221 | * to the sector size of the volume. Furthermore FILE_APPEND_DATA is
|
---|
| 222 | * disabled. To write beyond the size of file use RTFileSetSize prior
|
---|
[23047] | 223 | * writing the data to the file.
|
---|
[21573] | 224 | *
|
---|
[34435] | 225 | * This flag does not work on Solaris if the target filesystem is ZFS.
|
---|
| 226 | * RTFileOpen will return an error with that configuration. When used
|
---|
| 227 | * with UFS the same alginment restrictions apply like Linux and
|
---|
| 228 | * Windows.
|
---|
[23047] | 229 | *
|
---|
[34435] | 230 | * @remarks This might not be implemented on all platforms, and will be ignored
|
---|
| 231 | * on those.
|
---|
[21493] | 232 | */
|
---|
[23974] | 233 | #define RTFILE_O_NO_CACHE UINT32_C(0x00080000)
|
---|
[10526] | 234 |
|
---|
[39641] | 235 | /** Don't allow symbolic links as part of the path.
|
---|
| 236 | * @remarks this flag is currently not implemented and will be ignored. */
|
---|
[39612] | 237 | #define RTFILE_O_NO_SYMLINKS UINT32_C(0x20000000)
|
---|
| 238 |
|
---|
[21616] | 239 | /** Unix file mode mask for use when creating files. */
|
---|
[23974] | 240 | #define RTFILE_O_CREATE_MODE_MASK UINT32_C(0x1ff00000)
|
---|
[21616] | 241 | /** The number of bits to shift to get the file mode mask.
|
---|
| 242 | * To extract it: (fFlags & RTFILE_O_CREATE_MODE_MASK) >> RTFILE_O_CREATE_MODE_SHIFT.
|
---|
| 243 | */
|
---|
| 244 | #define RTFILE_O_CREATE_MODE_SHIFT 20
|
---|
| 245 |
|
---|
[96076] | 246 | /** Temporary file that should be automatically deleted when closed.
|
---|
| 247 | * If not supported by the OS, the open call will fail with VERR_NOT_SUPPORTED
|
---|
| 248 | * to prevent leaving undeleted files behind.
|
---|
| 249 | * @note On unix the file wont be visible and cannot be accessed by it's path.
|
---|
| 250 | * On Windows it will be visible but only accessible of deletion is
|
---|
| 251 | * shared. Not implemented on OS/2. */
|
---|
| 252 | #define RTFILE_O_TEMP_AUTO_DELETE UINT32_C(0x40000000)
|
---|
[21616] | 253 |
|
---|
[96076] | 254 | /* UINT32_C(0x80000000) is unused atm. */
|
---|
| 255 |
|
---|
[1] | 256 | /** Mask of all valid flags.
|
---|
| 257 | * @remark This doesn't validate the access mode properly.
|
---|
| 258 | */
|
---|
[96076] | 259 | #define RTFILE_O_VALID_MASK UINT32_C(0x7ffffff7)
|
---|
[1] | 260 |
|
---|
| 261 | /** @} */
|
---|
| 262 |
|
---|
| 263 |
|
---|
[77681] | 264 | /** Action taken by RTFileOpenEx. */
|
---|
| 265 | typedef enum RTFILEACTION
|
---|
| 266 | {
|
---|
| 267 | /** Invalid zero value. */
|
---|
| 268 | RTFILEACTION_INVALID = 0,
|
---|
| 269 | /** Existing file was opened (returned by RTFILE_O_OPEN and
|
---|
| 270 | * RTFILE_O_OPEN_CREATE). */
|
---|
| 271 | RTFILEACTION_OPENED,
|
---|
| 272 | /** New file was created (returned by RTFILE_O_CREATE and
|
---|
| 273 | * RTFILE_O_OPEN_CREATE). */
|
---|
| 274 | RTFILEACTION_CREATED,
|
---|
| 275 | /** Existing file was replaced (returned by RTFILE_O_CREATE_REPLACE). */
|
---|
| 276 | RTFILEACTION_REPLACED,
|
---|
| 277 | /** Existing file was truncated (returned if RTFILE_O_TRUNCATE take effect). */
|
---|
| 278 | RTFILEACTION_TRUNCATED,
|
---|
| 279 | /** The file already exists (returned by RTFILE_O_CREATE on failure). */
|
---|
| 280 | RTFILEACTION_ALREADY_EXISTS,
|
---|
| 281 | /** End of valid values. */
|
---|
| 282 | RTFILEACTION_END,
|
---|
| 283 | /** Type size hack. */
|
---|
| 284 | RTFILEACTION_32BIT_HACK = 0x7fffffff
|
---|
| 285 | } RTFILEACTION;
|
---|
| 286 | /** Pointer to action taken value (RTFileOpenEx). */
|
---|
| 287 | typedef RTFILEACTION *PRTFILEACTION;
|
---|
| 288 |
|
---|
| 289 |
|
---|
[37559] | 290 | #ifdef IN_RING3
|
---|
[1] | 291 | /**
|
---|
| 292 | * Force the use of open flags for all files opened after the setting is
|
---|
| 293 | * changed. The caller is responsible for not causing races with RTFileOpen().
|
---|
| 294 | *
|
---|
| 295 | * @returns iprt status code.
|
---|
| 296 | * @param fOpenForAccess Access mode to which the set/mask settings apply.
|
---|
| 297 | * @param fSet Open flags to be forced set.
|
---|
| 298 | * @param fMask Open flags to be masked out.
|
---|
| 299 | */
|
---|
| 300 | RTR3DECL(int) RTFileSetForceFlags(unsigned fOpenForAccess, unsigned fSet, unsigned fMask);
|
---|
[37559] | 301 | #endif /* IN_RING3 */
|
---|
[1] | 302 |
|
---|
| 303 | /**
|
---|
| 304 | * Open a file.
|
---|
| 305 | *
|
---|
| 306 | * @returns iprt status code.
|
---|
| 307 | * @param pFile Where to store the handle to the opened file.
|
---|
| 308 | * @param pszFilename Path to the file which is to be opened. (UTF-8)
|
---|
| 309 | * @param fOpen Open flags, i.e a combination of the RTFILE_O_* defines.
|
---|
[23973] | 310 | * The ACCESS, ACTION and DENY flags are mandatory!
|
---|
[1] | 311 | */
|
---|
[37596] | 312 | RTDECL(int) RTFileOpen(PRTFILE pFile, const char *pszFilename, uint64_t fOpen);
|
---|
[1] | 313 |
|
---|
| 314 | /**
|
---|
[26060] | 315 | * Open a file given as a format string.
|
---|
| 316 | *
|
---|
| 317 | * @returns iprt status code.
|
---|
| 318 | * @param pFile Where to store the handle to the opened file.
|
---|
| 319 | * @param fOpen Open flags, i.e a combination of the RTFILE_O_* defines.
|
---|
| 320 | * The ACCESS, ACTION and DENY flags are mandatory!
|
---|
| 321 | * @param pszFilenameFmt Format string givin the path to the file which is to
|
---|
| 322 | * be opened. (UTF-8)
|
---|
| 323 | * @param ... Arguments to the format string.
|
---|
| 324 | */
|
---|
[57004] | 325 | RTDECL(int) RTFileOpenF(PRTFILE pFile, uint64_t fOpen, const char *pszFilenameFmt, ...) RT_IPRT_FORMAT_ATTR(3, 4);
|
---|
[26060] | 326 |
|
---|
| 327 | /**
|
---|
| 328 | * Open a file given as a format string.
|
---|
| 329 | *
|
---|
| 330 | * @returns iprt status code.
|
---|
| 331 | * @param pFile Where to store the handle to the opened file.
|
---|
| 332 | * @param fOpen Open flags, i.e a combination of the RTFILE_O_* defines.
|
---|
| 333 | * The ACCESS, ACTION and DENY flags are mandatory!
|
---|
| 334 | * @param pszFilenameFmt Format string givin the path to the file which is to
|
---|
| 335 | * be opened. (UTF-8)
|
---|
| 336 | * @param va Arguments to the format string.
|
---|
| 337 | */
|
---|
[57004] | 338 | RTDECL(int) RTFileOpenV(PRTFILE pFile, uint64_t fOpen, const char *pszFilenameFmt, va_list va) RT_IPRT_FORMAT_ATTR(3, 0);
|
---|
[26060] | 339 |
|
---|
| 340 | /**
|
---|
[77681] | 341 | * Open a file, extended version.
|
---|
| 342 | *
|
---|
| 343 | * @returns iprt status code.
|
---|
| 344 | * @param pszFilename Path to the file which is to be opened. (UTF-8)
|
---|
| 345 | * @param fOpen Open flags, i.e a combination of the RTFILE_O_* defines.
|
---|
| 346 | * The ACCESS, ACTION and DENY flags are mandatory!
|
---|
| 347 | * @param phFile Where to store the handle to the opened file.
|
---|
| 348 | * @param penmActionTaken Where to return an indicator of which action was
|
---|
| 349 | * taken. This is optional and it is recommended to
|
---|
| 350 | * pass NULL when not strictly needed as it adds
|
---|
| 351 | * complexity (slower) on posix systems.
|
---|
| 352 | */
|
---|
| 353 | RTDECL(int) RTFileOpenEx(const char *pszFilename, uint64_t fOpen, PRTFILE phFile, PRTFILEACTION penmActionTaken);
|
---|
| 354 |
|
---|
| 355 | /**
|
---|
[26732] | 356 | * Open the bit bucket (aka /dev/null or nul).
|
---|
| 357 | *
|
---|
| 358 | * @returns IPRT status code.
|
---|
[26774] | 359 | * @param phFile Where to store the handle to the opened file.
|
---|
[26732] | 360 | * @param fAccess The desired access only, i.e. read, write or both.
|
---|
| 361 | */
|
---|
[37596] | 362 | RTDECL(int) RTFileOpenBitBucket(PRTFILE phFile, uint64_t fAccess);
|
---|
[26732] | 363 |
|
---|
| 364 | /**
|
---|
[96124] | 365 | * Duplicates a file handle.
|
---|
| 366 | *
|
---|
| 367 | * @returns IPRT status code.
|
---|
| 368 | * @param hFileSrc The handle to duplicate.
|
---|
| 369 | * @param fFlags RTFILE_O_INHERIT or zero.
|
---|
| 370 | * @param phFileNew Where to return the new file handle
|
---|
| 371 | */
|
---|
| 372 | RTDECL(int) RTFileDup(RTFILE hFileSrc, uint64_t fFlags, PRTFILE phFileNew);
|
---|
| 373 |
|
---|
| 374 | /**
|
---|
[1] | 375 | * Close a file opened by RTFileOpen().
|
---|
| 376 | *
|
---|
| 377 | * @returns iprt status code.
|
---|
| 378 | * @param File The file handle to close.
|
---|
| 379 | */
|
---|
[37559] | 380 | RTDECL(int) RTFileClose(RTFILE File);
|
---|
[1] | 381 |
|
---|
| 382 | /**
|
---|
[8558] | 383 | * Creates an IPRT file handle from a native one.
|
---|
| 384 | *
|
---|
| 385 | * @returns IPRT status code.
|
---|
| 386 | * @param pFile Where to store the IPRT file handle.
|
---|
| 387 | * @param uNative The native handle.
|
---|
| 388 | */
|
---|
[37559] | 389 | RTDECL(int) RTFileFromNative(PRTFILE pFile, RTHCINTPTR uNative);
|
---|
[8558] | 390 |
|
---|
| 391 | /**
|
---|
| 392 | * Gets the native handle for an IPRT file handle.
|
---|
| 393 | *
|
---|
| 394 | * @return The native handle.
|
---|
[25645] | 395 | * @param File The IPRT file handle.
|
---|
[8558] | 396 | */
|
---|
[37559] | 397 | RTDECL(RTHCINTPTR) RTFileToNative(RTFILE File);
|
---|
[8558] | 398 |
|
---|
| 399 | /**
|
---|
[1] | 400 | * Delete a file.
|
---|
| 401 | *
|
---|
| 402 | * @returns iprt status code.
|
---|
| 403 | * @param pszFilename Path to the file which is to be deleted. (UTF-8)
|
---|
| 404 | * @todo This is a RTPath api!
|
---|
| 405 | */
|
---|
[37559] | 406 | RTDECL(int) RTFileDelete(const char *pszFilename);
|
---|
[1] | 407 |
|
---|
| 408 | /** @name Seek flags.
|
---|
| 409 | * @{ */
|
---|
| 410 | /** Seek from the start of the file. */
|
---|
| 411 | #define RTFILE_SEEK_BEGIN 0x00
|
---|
| 412 | /** Seek from the current file position. */
|
---|
| 413 | #define RTFILE_SEEK_CURRENT 0x01
|
---|
| 414 | /** Seek from the end of the file. */
|
---|
| 415 | #define RTFILE_SEEK_END 0x02
|
---|
| 416 | /** @internal */
|
---|
| 417 | #define RTFILE_SEEK_FIRST RTFILE_SEEK_BEGIN
|
---|
| 418 | /** @internal */
|
---|
| 419 | #define RTFILE_SEEK_LAST RTFILE_SEEK_END
|
---|
| 420 | /** @} */
|
---|
| 421 |
|
---|
| 422 |
|
---|
| 423 | /**
|
---|
| 424 | * Changes the read & write position in a file.
|
---|
| 425 | *
|
---|
| 426 | * @returns iprt status code.
|
---|
| 427 | * @param File Handle to the file.
|
---|
| 428 | * @param offSeek Offset to seek.
|
---|
| 429 | * @param uMethod Seek method, i.e. one of the RTFILE_SEEK_* defines.
|
---|
| 430 | * @param poffActual Where to store the new file position.
|
---|
| 431 | * NULL is allowed.
|
---|
| 432 | */
|
---|
[37559] | 433 | RTDECL(int) RTFileSeek(RTFILE File, int64_t offSeek, unsigned uMethod, uint64_t *poffActual);
|
---|
[1] | 434 |
|
---|
| 435 | /**
|
---|
| 436 | * Read bytes from a file.
|
---|
| 437 | *
|
---|
| 438 | * @returns iprt status code.
|
---|
| 439 | * @param File Handle to the file.
|
---|
| 440 | * @param pvBuf Where to put the bytes we read.
|
---|
| 441 | * @param cbToRead How much to read.
|
---|
[77632] | 442 | * @param pcbRead How much we actually read .
|
---|
[1] | 443 | * If NULL an error will be returned for a partial read.
|
---|
| 444 | */
|
---|
[37559] | 445 | RTDECL(int) RTFileRead(RTFILE File, void *pvBuf, size_t cbToRead, size_t *pcbRead);
|
---|
[1] | 446 |
|
---|
| 447 | /**
|
---|
| 448 | * Read bytes from a file at a given offset.
|
---|
| 449 | *
|
---|
| 450 | * @returns iprt status code.
|
---|
| 451 | * @param File Handle to the file.
|
---|
| 452 | * @param off Where to read.
|
---|
| 453 | * @param pvBuf Where to put the bytes we read.
|
---|
| 454 | * @param cbToRead How much to read.
|
---|
[77632] | 455 | * @param pcbRead How much we actually read .
|
---|
[1] | 456 | * If NULL an error will be returned for a partial read.
|
---|
[77632] | 457 | *
|
---|
| 458 | * @note OS/2 requires separate seek and write calls.
|
---|
| 459 | *
|
---|
[77236] | 460 | * @note Whether the file position is modified or not is host specific.
|
---|
[1] | 461 | */
|
---|
[37559] | 462 | RTDECL(int) RTFileReadAt(RTFILE File, RTFOFF off, void *pvBuf, size_t cbToRead, size_t *pcbRead);
|
---|
[1] | 463 |
|
---|
| 464 | /**
|
---|
[46245] | 465 | * Read bytes from a file at a given offset into a S/G buffer.
|
---|
| 466 | *
|
---|
| 467 | * @returns iprt status code.
|
---|
| 468 | * @param hFile Handle to the file.
|
---|
[77632] | 469 | * @param pSgBuf Pointer to the S/G buffer to read into.
|
---|
| 470 | * @param cbToRead How much to read.
|
---|
| 471 | * @param pcbRead How much we actually read .
|
---|
| 472 | * If NULL an error will be returned for a partial read.
|
---|
| 473 | *
|
---|
| 474 | * @note It is not possible to guarantee atomicity on all platforms, so
|
---|
| 475 | * caller must take care wrt concurrent access to @a hFile.
|
---|
| 476 | */
|
---|
| 477 | RTDECL(int) RTFileSgRead(RTFILE hFile, PRTSGBUF pSgBuf, size_t cbToRead, size_t *pcbRead);
|
---|
| 478 |
|
---|
| 479 | /**
|
---|
| 480 | * Read bytes from a file at a given offset into a S/G buffer.
|
---|
| 481 | *
|
---|
| 482 | * @returns iprt status code.
|
---|
| 483 | * @param hFile Handle to the file.
|
---|
[46245] | 484 | * @param off Where to read.
|
---|
| 485 | * @param pSgBuf Pointer to the S/G buffer to read into.
|
---|
| 486 | * @param cbToRead How much to read.
|
---|
[77632] | 487 | * @param pcbRead How much we actually read .
|
---|
[46245] | 488 | * If NULL an error will be returned for a partial read.
|
---|
[77632] | 489 | *
|
---|
[77236] | 490 | * @note Whether the file position is modified or not is host specific.
|
---|
[77632] | 491 | *
|
---|
| 492 | * @note It is not possible to guarantee atomicity on all platforms, so
|
---|
| 493 | * caller must take care wrt concurrent access to @a hFile.
|
---|
[46245] | 494 | */
|
---|
| 495 | RTDECL(int) RTFileSgReadAt(RTFILE hFile, RTFOFF off, PRTSGBUF pSgBuf, size_t cbToRead, size_t *pcbRead);
|
---|
| 496 |
|
---|
| 497 | /**
|
---|
[1] | 498 | * Write bytes to a file.
|
---|
| 499 | *
|
---|
| 500 | * @returns iprt status code.
|
---|
| 501 | * @param File Handle to the file.
|
---|
| 502 | * @param pvBuf What to write.
|
---|
| 503 | * @param cbToWrite How much to write.
|
---|
[77632] | 504 | * @param pcbWritten How much we actually wrote.
|
---|
[1] | 505 | * If NULL an error will be returned for a partial write.
|
---|
| 506 | */
|
---|
[37559] | 507 | RTDECL(int) RTFileWrite(RTFILE File, const void *pvBuf, size_t cbToWrite, size_t *pcbWritten);
|
---|
[1] | 508 |
|
---|
| 509 | /**
|
---|
| 510 | * Write bytes to a file at a given offset.
|
---|
| 511 | *
|
---|
| 512 | * @returns iprt status code.
|
---|
[77236] | 513 | * @param hFile Handle to the file.
|
---|
[1] | 514 | * @param off Where to write.
|
---|
| 515 | * @param pvBuf What to write.
|
---|
| 516 | * @param cbToWrite How much to write.
|
---|
[77632] | 517 | * @param pcbWritten How much we actually wrote.
|
---|
[1] | 518 | * If NULL an error will be returned for a partial write.
|
---|
[77236] | 519 | *
|
---|
[77632] | 520 | * @note OS/2 requires separate seek and write calls.
|
---|
| 521 | *
|
---|
[77236] | 522 | * @note Whether the file position is modified or not is host specific.
|
---|
[77632] | 523 | *
|
---|
[77236] | 524 | * @note Whether @a off is used when @a hFile was opened with RTFILE_O_APPEND
|
---|
| 525 | * is also host specific. Currently Linux is the the only one
|
---|
| 526 | * documented to ignore @a off.
|
---|
[1] | 527 | */
|
---|
[77236] | 528 | RTDECL(int) RTFileWriteAt(RTFILE hFile, RTFOFF off, const void *pvBuf, size_t cbToWrite, size_t *pcbWritten);
|
---|
[1] | 529 |
|
---|
| 530 | /**
|
---|
[77632] | 531 | * Write bytes from a S/G buffer to a file.
|
---|
| 532 | *
|
---|
| 533 | * @returns iprt status code.
|
---|
| 534 | * @param hFile Handle to the file.
|
---|
| 535 | * @param pSgBuf What to write.
|
---|
| 536 | * @param cbToWrite How much to write.
|
---|
| 537 | * @param pcbWritten How much we actually wrote.
|
---|
| 538 | * If NULL an error will be returned for a partial write.
|
---|
| 539 | *
|
---|
| 540 | * @note It is not possible to guarantee atomicity on all platforms, so
|
---|
| 541 | * caller must take care wrt concurrent access to @a hFile.
|
---|
| 542 | */
|
---|
| 543 | RTDECL(int) RTFileSgWrite(RTFILE hFile, PRTSGBUF pSgBuf, size_t cbToWrite, size_t *pcbWritten);
|
---|
| 544 |
|
---|
| 545 | /**
|
---|
[46245] | 546 | * Write bytes from a S/G buffer to a file at a given offset.
|
---|
| 547 | *
|
---|
| 548 | * @returns iprt status code.
|
---|
| 549 | * @param hFile Handle to the file.
|
---|
| 550 | * @param off Where to write.
|
---|
| 551 | * @param pSgBuf What to write.
|
---|
| 552 | * @param cbToWrite How much to write.
|
---|
[77632] | 553 | * @param pcbWritten How much we actually wrote.
|
---|
[46245] | 554 | * If NULL an error will be returned for a partial write.
|
---|
[77236] | 555 | *
|
---|
[77632] | 556 | * @note It is not possible to guarantee atomicity on all platforms, so
|
---|
| 557 | * caller must take care wrt concurrent access to @a hFile.
|
---|
| 558 | *
|
---|
[77236] | 559 | * @note Whether the file position is modified or not is host specific.
|
---|
[77632] | 560 | *
|
---|
[77236] | 561 | * @note Whether @a off is used when @a hFile was opened with RTFILE_O_APPEND
|
---|
| 562 | * is also host specific. Currently Linux is the the only one
|
---|
| 563 | * documented to ignore @a off.
|
---|
[46245] | 564 | */
|
---|
| 565 | RTDECL(int) RTFileSgWriteAt(RTFILE hFile, RTFOFF off, PRTSGBUF pSgBuf, size_t cbToWrite, size_t *pcbWritten);
|
---|
| 566 |
|
---|
| 567 | /**
|
---|
[1] | 568 | * Flushes the buffers for the specified file.
|
---|
| 569 | *
|
---|
| 570 | * @returns iprt status code.
|
---|
[94277] | 571 | * @retval VINF_NOT_SUPPORTED if it is a special file that does not support
|
---|
| 572 | * flushing. This is reported as a informational status since in most
|
---|
| 573 | * cases this is entirely harmless (e.g. tty) and simplifies the usage.
|
---|
[1] | 574 | * @param File Handle to the file.
|
---|
| 575 | */
|
---|
[37559] | 576 | RTDECL(int) RTFileFlush(RTFILE File);
|
---|
[1] | 577 |
|
---|
| 578 | /**
|
---|
| 579 | * Set the size of the file.
|
---|
| 580 | *
|
---|
| 581 | * @returns iprt status code.
|
---|
| 582 | * @param File Handle to the file.
|
---|
| 583 | * @param cbSize The new file size.
|
---|
| 584 | */
|
---|
[37559] | 585 | RTDECL(int) RTFileSetSize(RTFILE File, uint64_t cbSize);
|
---|
[1] | 586 |
|
---|
| 587 | /**
|
---|
| 588 | * Query the size of the file.
|
---|
| 589 | *
|
---|
| 590 | * @returns iprt status code.
|
---|
| 591 | * @param File Handle to the file.
|
---|
| 592 | * @param pcbSize Where to store the filesize.
|
---|
| 593 | */
|
---|
[80585] | 594 | RTDECL(int) RTFileQuerySize(RTFILE File, uint64_t *pcbSize);
|
---|
[1] | 595 |
|
---|
| 596 | /**
|
---|
[6992] | 597 | * Determine the maximum file size.
|
---|
| 598 | *
|
---|
| 599 | * @returns The max size of the file.
|
---|
[6429] | 600 | * -1 on failure, the file position is undefined.
|
---|
[6992] | 601 | * @param File Handle to the file.
|
---|
[80585] | 602 | * @see RTFileQueryMaxSizeEx.
|
---|
[6421] | 603 | */
|
---|
[37559] | 604 | RTDECL(RTFOFF) RTFileGetMaxSize(RTFILE File);
|
---|
[6421] | 605 |
|
---|
| 606 | /**
|
---|
[6992] | 607 | * Determine the maximum file size.
|
---|
| 608 | *
|
---|
[6429] | 609 | * @returns IPRT status code.
|
---|
[6992] | 610 | * @param File Handle to the file.
|
---|
| 611 | * @param pcbMax Where to store the max file size.
|
---|
[6429] | 612 | * @see RTFileGetMaxSize.
|
---|
| 613 | */
|
---|
[80585] | 614 | RTDECL(int) RTFileQueryMaxSizeEx(RTFILE File, PRTFOFF pcbMax);
|
---|
[6429] | 615 |
|
---|
| 616 | /**
|
---|
[85875] | 617 | * Queries the sector size (/ logical block size) for a disk or similar.
|
---|
| 618 | *
|
---|
| 619 | * @returns IPRT status code.
|
---|
| 620 | * @retval VERR_INVALID_FUNCTION if not a disk/similar. Could also be returned
|
---|
| 621 | * if not really implemented.
|
---|
| 622 | * @param hFile Handle to the disk. This must typically be a device
|
---|
| 623 | * rather than a file or directory, though this may vary
|
---|
| 624 | * from OS to OS.
|
---|
| 625 | * @param pcbSector Where to store the sector size.
|
---|
| 626 | */
|
---|
| 627 | RTDECL(int) RTFileQuerySectorSize(RTFILE hFile, uint32_t *pcbSector);
|
---|
| 628 |
|
---|
| 629 | /**
|
---|
[1] | 630 | * Gets the current file position.
|
---|
| 631 | *
|
---|
| 632 | * @returns File offset.
|
---|
| 633 | * @returns ~0UUL on failure.
|
---|
| 634 | * @param File Handle to the file.
|
---|
| 635 | */
|
---|
| 636 | RTDECL(uint64_t) RTFileTell(RTFILE File);
|
---|
| 637 |
|
---|
| 638 | /**
|
---|
| 639 | * Checks if the supplied handle is valid.
|
---|
| 640 | *
|
---|
| 641 | * @returns true if valid.
|
---|
| 642 | * @returns false if invalid.
|
---|
| 643 | * @param File The file handle
|
---|
| 644 | */
|
---|
[37559] | 645 | RTDECL(bool) RTFileIsValid(RTFILE File);
|
---|
[1] | 646 |
|
---|
| 647 | /**
|
---|
| 648 | * Copies a file.
|
---|
| 649 | *
|
---|
[49033] | 650 | * @returns IPRT status code
|
---|
| 651 | * @retval VERR_ALREADY_EXISTS if the destination file exists.
|
---|
[1] | 652 | *
|
---|
| 653 | * @param pszSrc The path to the source file.
|
---|
| 654 | * @param pszDst The path to the destination file.
|
---|
| 655 | * This file will be created.
|
---|
| 656 | */
|
---|
| 657 | RTDECL(int) RTFileCopy(const char *pszSrc, const char *pszDst);
|
---|
| 658 |
|
---|
| 659 | /**
|
---|
| 660 | * Copies a file given the handles to both files.
|
---|
| 661 | *
|
---|
[49033] | 662 | * @returns IPRT status code
|
---|
[1] | 663 | *
|
---|
| 664 | * @param FileSrc The source file. The file position is unaltered.
|
---|
| 665 | * @param FileDst The destination file.
|
---|
| 666 | * On successful returns the file position is at the end of the file.
|
---|
| 667 | * On failures the file position and size is undefined.
|
---|
| 668 | */
|
---|
| 669 | RTDECL(int) RTFileCopyByHandles(RTFILE FileSrc, RTFILE FileDst);
|
---|
| 670 |
|
---|
[7340] | 671 | /** Flags for RTFileCopyEx().
|
---|
| 672 | * @{ */
|
---|
| 673 | /** Do not use RTFILE_O_DENY_WRITE on the source file to allow for copying files opened for writing. */
|
---|
[7370] | 674 | #define RTFILECOPY_FLAGS_NO_SRC_DENY_WRITE RT_BIT(0)
|
---|
| 675 | /** Do not use RTFILE_O_DENY_WRITE on the target file. */
|
---|
| 676 | #define RTFILECOPY_FLAGS_NO_DST_DENY_WRITE RT_BIT(1)
|
---|
[7371] | 677 | /** Do not use RTFILE_O_DENY_WRITE on either of the two files. */
|
---|
[7370] | 678 | #define RTFILECOPY_FLAGS_NO_DENY_WRITE ( RTFILECOPY_FLAGS_NO_SRC_DENY_WRITE | RTFILECOPY_FLAGS_NO_DST_DENY_WRITE )
|
---|
| 679 | /** */
|
---|
| 680 | #define RTFILECOPY_FLAGS_MASK UINT32_C(0x00000003)
|
---|
[7340] | 681 | /** @} */
|
---|
| 682 |
|
---|
[1] | 683 | /**
|
---|
| 684 | * Copies a file.
|
---|
| 685 | *
|
---|
[49033] | 686 | * @returns IPRT status code
|
---|
| 687 | * @retval VERR_ALREADY_EXISTS if the destination file exists.
|
---|
[1] | 688 | *
|
---|
| 689 | * @param pszSrc The path to the source file.
|
---|
| 690 | * @param pszDst The path to the destination file.
|
---|
| 691 | * This file will be created.
|
---|
[7340] | 692 | * @param fFlags Flags (RTFILECOPY_*).
|
---|
[1] | 693 | * @param pfnProgress Pointer to callback function for reporting progress.
|
---|
[33540] | 694 | * @param pvUser User argument to pass to pfnProgress along with the completion percentage.
|
---|
[1] | 695 | */
|
---|
[7340] | 696 | RTDECL(int) RTFileCopyEx(const char *pszSrc, const char *pszDst, uint32_t fFlags, PFNRTPROGRESS pfnProgress, void *pvUser);
|
---|
[1] | 697 |
|
---|
| 698 | /**
|
---|
| 699 | * Copies a file given the handles to both files and
|
---|
| 700 | * provide progress callbacks.
|
---|
| 701 | *
|
---|
| 702 | * @returns IPRT status code.
|
---|
| 703 | *
|
---|
| 704 | * @param FileSrc The source file. The file position is unaltered.
|
---|
| 705 | * @param FileDst The destination file.
|
---|
| 706 | * On successful returns the file position is at the end of the file.
|
---|
| 707 | * On failures the file position and size is undefined.
|
---|
| 708 | * @param pfnProgress Pointer to callback function for reporting progress.
|
---|
[33540] | 709 | * @param pvUser User argument to pass to pfnProgress along with the completion percentage.
|
---|
[1] | 710 | */
|
---|
| 711 | RTDECL(int) RTFileCopyByHandlesEx(RTFILE FileSrc, RTFILE FileDst, PFNRTPROGRESS pfnProgress, void *pvUser);
|
---|
| 712 |
|
---|
[77797] | 713 | /**
|
---|
| 714 | * Copies a part of a file to another one.
|
---|
| 715 | *
|
---|
| 716 | * @returns IPRT status code.
|
---|
| 717 | * @retval VERR_EOF if @a pcbCopied is NULL and the end-of-file is reached
|
---|
| 718 | * before @a cbToCopy bytes have been copied.
|
---|
| 719 | *
|
---|
| 720 | * @param hFileSrc Handle to the source file. Must be readable.
|
---|
| 721 | * @param offSrc The source file offset.
|
---|
| 722 | * @param hFileDst Handle to the destination file. Must be writable and
|
---|
| 723 | * RTFILE_O_APPEND must be be in effect.
|
---|
| 724 | * @param offDst The destination file offset.
|
---|
| 725 | * @param cbToCopy How many bytes to copy.
|
---|
| 726 | * @param fFlags Reserved for the future, must be zero.
|
---|
| 727 | * @param pcbCopied Where to return the exact number of bytes copied.
|
---|
| 728 | * Optional.
|
---|
| 729 | *
|
---|
| 730 | * @note The file positions of @a hFileSrc and @a hFileDst are undefined
|
---|
| 731 | * upon return of this function.
|
---|
| 732 | *
|
---|
| 733 | * @sa RTFileCopyPartEx.
|
---|
| 734 | */
|
---|
| 735 | RTDECL(int) RTFileCopyPart(RTFILE hFileSrc, RTFOFF offSrc, RTFILE hFileDst, RTFOFF offDst, uint64_t cbToCopy,
|
---|
| 736 | uint32_t fFlags, uint64_t *pcbCopied);
|
---|
[49033] | 737 |
|
---|
[77797] | 738 |
|
---|
| 739 | /** Copy buffer state for RTFileCopyPartEx.
|
---|
| 740 | * @note The fields are considered internal!
|
---|
| 741 | */
|
---|
| 742 | typedef struct RTFILECOPYPARTBUFSTATE
|
---|
| 743 | {
|
---|
| 744 | /** Magic value (RTFILECOPYPARTBUFSTATE_MAGIC).
|
---|
| 745 | * @internal */
|
---|
| 746 | uint32_t uMagic;
|
---|
| 747 | /** Allocation type (internal).
|
---|
| 748 | * @internal */
|
---|
| 749 | int32_t iAllocType;
|
---|
| 750 | /** Buffer pointer.
|
---|
| 751 | * @internal */
|
---|
| 752 | uint8_t *pbBuf;
|
---|
| 753 | /** Buffer size.
|
---|
| 754 | * @internal */
|
---|
| 755 | size_t cbBuf;
|
---|
| 756 | /** Reserved.
|
---|
| 757 | * @internal */
|
---|
| 758 | void *papReserved[3];
|
---|
| 759 | } RTFILECOPYPARTBUFSTATE;
|
---|
| 760 | /** Pointer to copy buffer state for RTFileCopyPartEx(). */
|
---|
| 761 | typedef RTFILECOPYPARTBUFSTATE *PRTFILECOPYPARTBUFSTATE;
|
---|
| 762 | /** Magic value for the RTFileCopyPartEx() buffer state structure (Stephen John Fry). */
|
---|
| 763 | #define RTFILECOPYPARTBUFSTATE_MAGIC UINT32_C(0x19570857)
|
---|
| 764 |
|
---|
[1] | 765 | /**
|
---|
[77797] | 766 | * Prepares buffer state for one or more RTFileCopyPartEx() calls.
|
---|
| 767 | *
|
---|
| 768 | * Caller must call RTFileCopyPartCleanup() after the final RTFileCopyPartEx()
|
---|
| 769 | * call.
|
---|
| 770 | *
|
---|
| 771 | * @returns IPRT status code.
|
---|
| 772 | * @param pBufState The buffer state to prepare.
|
---|
| 773 | * @param cbToCopy The number of bytes we typically to copy in one
|
---|
| 774 | * RTFileCopyPartEx call.
|
---|
| 775 | */
|
---|
| 776 | RTDECL(int) RTFileCopyPartPrep(PRTFILECOPYPARTBUFSTATE pBufState, uint64_t cbToCopy);
|
---|
| 777 |
|
---|
| 778 | /**
|
---|
| 779 | * Cleans up after RTFileCopyPartPrep() once the final RTFileCopyPartEx()
|
---|
| 780 | * call has been made.
|
---|
| 781 | *
|
---|
| 782 | * @param pBufState The buffer state to clean up.
|
---|
| 783 | */
|
---|
| 784 | RTDECL(void) RTFileCopyPartCleanup(PRTFILECOPYPARTBUFSTATE pBufState);
|
---|
| 785 |
|
---|
| 786 | /**
|
---|
| 787 | * Copies a part of a file to another one, extended version.
|
---|
| 788 | *
|
---|
| 789 | * @returns IPRT status code.
|
---|
| 790 | * @retval VERR_EOF if @a pcbCopied is NULL and the end-of-file is reached
|
---|
| 791 | * before @a cbToCopy bytes have been copied.
|
---|
| 792 | *
|
---|
| 793 | * @param hFileSrc Handle to the source file. Must be readable.
|
---|
| 794 | * @param offSrc The source file offset.
|
---|
| 795 | * @param hFileDst Handle to the destination file. Must be writable and
|
---|
| 796 | * RTFILE_O_APPEND must be be in effect.
|
---|
| 797 | * @param offDst The destination file offset.
|
---|
| 798 | * @param cbToCopy How many bytes to copy.
|
---|
| 799 | * @param fFlags Reserved for the future, must be zero.
|
---|
| 800 | * @param pBufState Copy buffer state prepared by RTFileCopyPartPrep().
|
---|
| 801 | * @param pcbCopied Where to return the exact number of bytes copied.
|
---|
| 802 | * Optional.
|
---|
| 803 | *
|
---|
| 804 | * @note The file positions of @a hFileSrc and @a hFileDst are undefined
|
---|
| 805 | * upon return of this function.
|
---|
| 806 | *
|
---|
[77830] | 807 | * @sa RTFileCopyPart.
|
---|
[77797] | 808 | */
|
---|
| 809 | RTDECL(int) RTFileCopyPartEx(RTFILE hFileSrc, RTFOFF offSrc, RTFILE hFileDst, RTFOFF offDst, uint64_t cbToCopy,
|
---|
| 810 | uint32_t fFlags, PRTFILECOPYPARTBUFSTATE pBufState, uint64_t *pcbCopied);
|
---|
| 811 |
|
---|
| 812 | /**
|
---|
[77830] | 813 | * Copy file attributes from @a hFileSrc to @a hFileDst.
|
---|
| 814 | *
|
---|
| 815 | * @returns IPRT status code.
|
---|
| 816 | * @param hFileSrc Handle to the source file.
|
---|
| 817 | * @param hFileDst Handle to the destination file.
|
---|
| 818 | * @param fFlags Reserved, pass zero.
|
---|
| 819 | */
|
---|
| 820 | RTDECL(int) RTFileCopyAttributes(RTFILE hFileSrc, RTFILE hFileDst, uint32_t fFlags);
|
---|
| 821 |
|
---|
| 822 | /**
|
---|
[49033] | 823 | * Compares two file given the paths to both files.
|
---|
| 824 | *
|
---|
| 825 | * @returns IPRT status code.
|
---|
| 826 | * @retval VINF_SUCCESS if equal.
|
---|
| 827 | * @retval VERR_NOT_EQUAL if not equal.
|
---|
| 828 | *
|
---|
| 829 | * @param pszFile1 The path to the first file.
|
---|
| 830 | * @param pszFile2 The path to the second file.
|
---|
| 831 | */
|
---|
| 832 | RTDECL(int) RTFileCompare(const char *pszFile1, const char *pszFile2);
|
---|
| 833 |
|
---|
| 834 | /**
|
---|
| 835 | * Compares two file given the handles to both files.
|
---|
| 836 | *
|
---|
| 837 | * @returns IPRT status code.
|
---|
| 838 | * @retval VINF_SUCCESS if equal.
|
---|
| 839 | * @retval VERR_NOT_EQUAL if not equal.
|
---|
| 840 | *
|
---|
| 841 | * @param hFile1 The first file. Undefined return position.
|
---|
| 842 | * @param hFile2 The second file. Undefined return position.
|
---|
| 843 | */
|
---|
| 844 | RTDECL(int) RTFileCompareByHandles(RTFILE hFile1, RTFILE hFile2);
|
---|
| 845 |
|
---|
| 846 | /** Flags for RTFileCompareEx().
|
---|
| 847 | * @{ */
|
---|
| 848 | /** Do not use RTFILE_O_DENY_WRITE on the first file. */
|
---|
| 849 | #define RTFILECOMP_FLAGS_NO_DENY_WRITE_FILE1 RT_BIT(0)
|
---|
| 850 | /** Do not use RTFILE_O_DENY_WRITE on the second file. */
|
---|
| 851 | #define RTFILECOMP_FLAGS_NO_DENY_WRITE_FILE2 RT_BIT(1)
|
---|
| 852 | /** Do not use RTFILE_O_DENY_WRITE on either of the two files. */
|
---|
| 853 | #define RTFILECOMP_FLAGS_NO_DENY_WRITE ( RTFILECOMP_FLAGS_NO_DENY_WRITE_FILE1 | RTFILECOMP_FLAGS_NO_DENY_WRITE_FILE2 )
|
---|
| 854 | /** */
|
---|
| 855 | #define RTFILECOMP_FLAGS_MASK UINT32_C(0x00000003)
|
---|
| 856 | /** @} */
|
---|
| 857 |
|
---|
| 858 | /**
|
---|
| 859 | * Compares two files, extended version with progress callback.
|
---|
| 860 | *
|
---|
| 861 | * @returns IPRT status code.
|
---|
| 862 | * @retval VINF_SUCCESS if equal.
|
---|
| 863 | * @retval VERR_NOT_EQUAL if not equal.
|
---|
| 864 | *
|
---|
| 865 | * @param pszFile1 The path to the source file.
|
---|
| 866 | * @param pszFile2 The path to the destination file. This file will be
|
---|
| 867 | * created.
|
---|
| 868 | * @param fFlags Flags, any of the RTFILECOMP_FLAGS_ \#defines.
|
---|
| 869 | * @param pfnProgress Pointer to callback function for reporting progress.
|
---|
| 870 | * @param pvUser User argument to pass to pfnProgress along with the completion percentage.
|
---|
| 871 | */
|
---|
| 872 | RTDECL(int) RTFileCompareEx(const char *pszFile1, const char *pszFile2, uint32_t fFlags, PFNRTPROGRESS pfnProgress, void *pvUser);
|
---|
| 873 |
|
---|
| 874 | /**
|
---|
| 875 | * Compares two files given their handles, extended version with progress
|
---|
| 876 | * callback.
|
---|
| 877 | *
|
---|
| 878 | * @returns IPRT status code.
|
---|
| 879 | * @retval VINF_SUCCESS if equal.
|
---|
| 880 | * @retval VERR_NOT_EQUAL if not equal.
|
---|
| 881 | *
|
---|
| 882 | * @param hFile1 The first file. Undefined return position.
|
---|
| 883 | * @param hFile2 The second file. Undefined return position.
|
---|
| 884 | *
|
---|
| 885 | * @param fFlags Flags, any of the RTFILECOMP_FLAGS_ \#defines, flags
|
---|
| 886 | * related to opening of the files will be ignored.
|
---|
| 887 | * @param pfnProgress Pointer to callback function for reporting progress.
|
---|
| 888 | * @param pvUser User argument to pass to pfnProgress along with the completion percentage.
|
---|
| 889 | */
|
---|
| 890 | RTDECL(int) RTFileCompareByHandlesEx(RTFILE hFile1, RTFILE hFile2, uint32_t fFlags, PFNRTPROGRESS pfnProgress, void *pvUser);
|
---|
| 891 |
|
---|
| 892 | /**
|
---|
[1] | 893 | * Renames a file.
|
---|
| 894 | *
|
---|
| 895 | * Identical to RTPathRename except that it will ensure that the source is not a directory.
|
---|
| 896 | *
|
---|
| 897 | * @returns IPRT status code.
|
---|
| 898 | * @returns VERR_ALREADY_EXISTS if the destination file exists.
|
---|
| 899 | *
|
---|
| 900 | * @param pszSrc The path to the source file.
|
---|
| 901 | * @param pszDst The path to the destination file.
|
---|
| 902 | * This file will be created.
|
---|
| 903 | * @param fRename See RTPathRename.
|
---|
| 904 | */
|
---|
| 905 | RTDECL(int) RTFileRename(const char *pszSrc, const char *pszDst, unsigned fRename);
|
---|
| 906 |
|
---|
| 907 |
|
---|
| 908 | /** @name RTFileMove flags (bit masks).
|
---|
| 909 | * @{ */
|
---|
| 910 | /** Replace destination file if present. */
|
---|
[39612] | 911 | #define RTFILEMOVE_FLAGS_REPLACE 0x1
|
---|
[39641] | 912 | /** Don't allow symbolic links as part of the path.
|
---|
| 913 | * @remarks this flag is currently not implemented and will be ignored. */
|
---|
[39612] | 914 | #define RTFILEMOVE_FLAGS_NO_SYMLINKS 0x2
|
---|
[1] | 915 | /** @} */
|
---|
| 916 |
|
---|
| 917 | /**
|
---|
[47762] | 918 | * Converts file opening modes (used by fopen, for example) to IPRT
|
---|
| 919 | * compatible flags, which then can be used with RTFileOpen* APIs.
|
---|
| 920 | *
|
---|
[62559] | 921 | * @note Handling sharing modes is not supported yet, so RTFILE_O_DENY_NONE
|
---|
| 922 | * will always be used.
|
---|
[47783] | 923 | *
|
---|
[47762] | 924 | * @return IPRT status code.
|
---|
| 925 | * @param pszMode Mode string to convert.
|
---|
[62559] | 926 | * @param pfMode Where to store the converted mode flags on
|
---|
| 927 | * success.
|
---|
[47762] | 928 | */
|
---|
[62559] | 929 | RTDECL(int) RTFileModeToFlags(const char *pszMode, uint64_t *pfMode);
|
---|
[47762] | 930 |
|
---|
| 931 | /**
|
---|
| 932 | * Converts file opening modes along with a separate disposition command
|
---|
| 933 | * to IPRT compatible flags, which then can be used with RTFileOpen* APIs.
|
---|
| 934 | *
|
---|
| 935 | * Access modes:
|
---|
[66592] | 936 | * - "r": Opens a file for reading.
|
---|
| 937 | * - "r+": Opens a file for reading and writing.
|
---|
| 938 | * - "w": Opens a file for writing.
|
---|
| 939 | * - "w+": Opens a file for writing and reading.
|
---|
[47762] | 940 | *
|
---|
| 941 | * Disposition modes:
|
---|
[66592] | 942 | * - "oe", "open": Opens an existing file or fail if it does not exist.
|
---|
| 943 | * - "oc", "open-create": Opens an existing file or create it if it does
|
---|
| 944 | * not exist.
|
---|
| 945 | * - "oa", "open-append": Opens an existing file and places the file
|
---|
| 946 | * pointer at the end of the file, if opened with write access. Create
|
---|
| 947 | * the file if it does not exist.
|
---|
| 948 | * - "ot", "open-truncate": Opens and truncate an existing file or fail if
|
---|
| 949 | * it does not exist.
|
---|
| 950 | * - "ce", "create": Creates a new file if it does not exist. Fail if
|
---|
| 951 | * exist.
|
---|
| 952 | * - "ca", "create-replace": Creates a new file, always. Overwrites an
|
---|
| 953 | * existing file.
|
---|
[47762] | 954 | *
|
---|
[66592] | 955 | * Sharing mode:
|
---|
| 956 | * - "nr": Deny read.
|
---|
| 957 | * - "nw": Deny write.
|
---|
| 958 | * - "nrw": Deny both read and write.
|
---|
| 959 | * - "d": Allow delete.
|
---|
| 960 | * - "", NULL: Deny none, except delete.
|
---|
[47762] | 961 | *
|
---|
| 962 | * @return IPRT status code.
|
---|
[66592] | 963 | * @param pszAccess Access mode string to convert.
|
---|
| 964 | * @param pszDisposition Disposition mode string to convert.
|
---|
| 965 | * @param pszSharing Sharing mode string to convert.
|
---|
| 966 | * @param pfMode Where to store the converted mode flags on success.
|
---|
[47762] | 967 | */
|
---|
[62559] | 968 | RTDECL(int) RTFileModeToFlagsEx(const char *pszAccess, const char *pszDisposition, const char *pszSharing, uint64_t *pfMode);
|
---|
[47762] | 969 |
|
---|
| 970 | /**
|
---|
[1] | 971 | * Moves a file.
|
---|
| 972 | *
|
---|
| 973 | * RTFileMove differs from RTFileRename in that it works across volumes.
|
---|
| 974 | *
|
---|
| 975 | * @returns IPRT status code.
|
---|
| 976 | * @returns VERR_ALREADY_EXISTS if the destination file exists.
|
---|
| 977 | *
|
---|
| 978 | * @param pszSrc The path to the source file.
|
---|
| 979 | * @param pszDst The path to the destination file.
|
---|
| 980 | * This file will be created.
|
---|
| 981 | * @param fMove A combination of the RTFILEMOVE_* flags.
|
---|
| 982 | */
|
---|
| 983 | RTDECL(int) RTFileMove(const char *pszSrc, const char *pszDst, unsigned fMove);
|
---|
| 984 |
|
---|
| 985 |
|
---|
[42712] | 986 | /**
|
---|
[94311] | 987 | * Creates a new file with a unique name using the given template, returning a
|
---|
| 988 | * handle to it.
|
---|
| 989 | *
|
---|
| 990 | * One or more trailing X'es in the template will be replaced by random alpha
|
---|
| 991 | * numeric characters until a RTFileOpen with RTFILE_O_CREATE succeeds or we
|
---|
| 992 | * run out of patience.
|
---|
| 993 | * For instance:
|
---|
| 994 | * "/tmp/myprog-XXXXXX"
|
---|
| 995 | *
|
---|
| 996 | * As an alternative to trailing X'es, it is possible to put 3 or more X'es
|
---|
| 997 | * somewhere inside the file name. In the following string only the last
|
---|
| 998 | * bunch of X'es will be modified:
|
---|
| 999 | * "/tmp/myprog-XXX-XXX.tmp"
|
---|
| 1000 | *
|
---|
| 1001 | * @returns IPRT status code.
|
---|
| 1002 | * @param phFile Where to return the file handle on success. Set to
|
---|
| 1003 | * NIL on failure.
|
---|
| 1004 | * @param pszTemplate The file name template on input. The actual file
|
---|
| 1005 | * name on success. Empty string on failure.
|
---|
| 1006 | * @param fOpen The RTFILE_O_XXX flags to open the file with.
|
---|
| 1007 | * RTFILE_O_CREATE is mandatory.
|
---|
| 1008 | * @see RTFileCreateTemp
|
---|
| 1009 | */
|
---|
| 1010 | RTDECL(int) RTFileCreateUnique(PRTFILE phFile, char *pszTemplate, uint64_t fOpen);
|
---|
| 1011 |
|
---|
| 1012 | /**
|
---|
[42712] | 1013 | * Creates a new file with a unique name using the given template.
|
---|
| 1014 | *
|
---|
| 1015 | * One or more trailing X'es in the template will be replaced by random alpha
|
---|
| 1016 | * numeric characters until a RTFileOpen with RTFILE_O_CREATE succeeds or we
|
---|
| 1017 | * run out of patience.
|
---|
| 1018 | * For instance:
|
---|
| 1019 | * "/tmp/myprog-XXXXXX"
|
---|
| 1020 | *
|
---|
| 1021 | * As an alternative to trailing X'es, it is possible to put 3 or more X'es
|
---|
| 1022 | * somewhere inside the file name. In the following string only the last
|
---|
| 1023 | * bunch of X'es will be modified:
|
---|
| 1024 | * "/tmp/myprog-XXX-XXX.tmp"
|
---|
| 1025 | *
|
---|
| 1026 | * @returns iprt status code.
|
---|
| 1027 | * @param pszTemplate The file name template on input. The actual file
|
---|
| 1028 | * name on success. Empty string on failure.
|
---|
| 1029 | * @param fMode The mode to create the file with. Use 0600 unless
|
---|
| 1030 | * you have reason not to.
|
---|
[94311] | 1031 | * @see RTFileCreateUnique
|
---|
[42712] | 1032 | */
|
---|
| 1033 | RTDECL(int) RTFileCreateTemp(char *pszTemplate, RTFMODE fMode);
|
---|
| 1034 |
|
---|
| 1035 | /**
|
---|
| 1036 | * Secure version of @a RTFileCreateTemp with a fixed mode of 0600.
|
---|
| 1037 | *
|
---|
| 1038 | * This function behaves in the same way as @a RTFileCreateTemp with two
|
---|
| 1039 | * additional points. Firstly the mode is fixed to 0600. Secondly it will
|
---|
| 1040 | * fail if it is not possible to perform the operation securely. Possible
|
---|
| 1041 | * reasons include that the file could be removed by another unprivileged
|
---|
| 1042 | * user before it is used (e.g. if is created in a non-sticky /tmp directory)
|
---|
| 1043 | * or that the path contains symbolic links which another unprivileged user
|
---|
| 1044 | * could manipulate; however the exact criteria will be specified on a
|
---|
| 1045 | * platform-by-platform basis as platform support is added.
|
---|
| 1046 | * @see RTPathIsSecure for the current list of criteria.
|
---|
[79200] | 1047 | *
|
---|
[42712] | 1048 | * @returns iprt status code.
|
---|
| 1049 | * @returns VERR_NOT_SUPPORTED if the interface can not be supported on the
|
---|
| 1050 | * current platform at this time.
|
---|
| 1051 | * @returns VERR_INSECURE if the file could not be created securely.
|
---|
| 1052 | * @param pszTemplate The file name template on input. The actual
|
---|
| 1053 | * file name on success. Empty string on failure.
|
---|
[94311] | 1054 | * @see RTFileCreateUnique
|
---|
[42712] | 1055 | */
|
---|
| 1056 | RTDECL(int) RTFileCreateTempSecure(char *pszTemplate);
|
---|
| 1057 |
|
---|
[57613] | 1058 | /**
|
---|
| 1059 | * Opens a new file with a unique name in the temp directory.
|
---|
| 1060 | *
|
---|
[57926] | 1061 | * Unlike the other temp file creation APIs, this does not allow you any control
|
---|
| 1062 | * over the name. Nor do you have to figure out where the temporary directory
|
---|
| 1063 | * is.
|
---|
| 1064 | *
|
---|
[57613] | 1065 | * @returns iprt status code.
|
---|
[57926] | 1066 | * @param phFile Where to return the handle to the file.
|
---|
| 1067 | * @param pszFilename Where to return the name (+path) of the file .
|
---|
| 1068 | * @param cbFilename The size of the buffer @a pszFilename points to.
|
---|
| 1069 | * @param fOpen The RTFILE_O_XXX flags to open the file with.
|
---|
[57613] | 1070 | *
|
---|
| 1071 | * @remarks If actual control over the filename or location is required, we'll
|
---|
| 1072 | * create an extended edition of this API.
|
---|
| 1073 | */
|
---|
[57926] | 1074 | RTDECL(int) RTFileOpenTemp(PRTFILE phFile, char *pszFilename, size_t cbFilename, uint64_t fOpen);
|
---|
[42712] | 1075 |
|
---|
[57613] | 1076 |
|
---|
[99760] | 1077 | /** @defgroup grp_rt_fileio_locking RT File locking API
|
---|
[1] | 1078 | *
|
---|
| 1079 | * File locking general rules:
|
---|
| 1080 | *
|
---|
| 1081 | * Region to lock or unlock can be located beyond the end of file, this can be used for
|
---|
| 1082 | * growing files.
|
---|
| 1083 | * Read (or Shared) locks can be acquired held by an unlimited number of processes at the
|
---|
| 1084 | * same time, but a Write (or Exclusive) lock can only be acquired by one process, and
|
---|
| 1085 | * cannot coexist with a Shared lock. To acquire a Read lock, a process must wait until
|
---|
| 1086 | * there are no processes holding any Write locks. To acquire a Write lock, a process must
|
---|
| 1087 | * wait until there are no processes holding either kind of lock.
|
---|
| 1088 | * By default, RTFileLock and RTFileChangeLock calls returns error immediately if the lock
|
---|
| 1089 | * can't be acquired due to conflict with other locks, however they can be called in wait mode.
|
---|
| 1090 | *
|
---|
| 1091 | * Differences in implementation:
|
---|
| 1092 | *
|
---|
| 1093 | * Win32, OS/2: Locking is mandatory, since locks are enforced by the operating system.
|
---|
| 1094 | * I.e. when file region is locked in Read mode, any write in it will fail; in case of Write
|
---|
[33540] | 1095 | * lock - region can be read and writed only by lock's owner.
|
---|
[1] | 1096 | *
|
---|
| 1097 | * Win32: File size change (RTFileSetSize) is not controlled by locking at all (!) in the
|
---|
| 1098 | * operation system. Also see comments to RTFileChangeLock API call.
|
---|
| 1099 | *
|
---|
| 1100 | * Linux/Posix: By default locks in Unixes are advisory. This means that cooperating processes
|
---|
[14872] | 1101 | * may use locks to coordinate access to a file between themselves, but programs are also free
|
---|
[1] | 1102 | * to ignore locks and access the file in any way they choose to.
|
---|
| 1103 | *
|
---|
| 1104 | * Additional reading:
|
---|
[99760] | 1105 | * - http://en.wikipedia.org/wiki/File_locking
|
---|
| 1106 | * - http://unixhelp.ed.ac.uk/CGI/man-cgi?fcntl+2
|
---|
| 1107 | * - http://msdn.microsoft.com/library/default.asp?url=/library/en-us/fileio/fs/lockfileex.asp
|
---|
| 1108 | *
|
---|
| 1109 | * @{
|
---|
[1] | 1110 | */
|
---|
| 1111 |
|
---|
| 1112 | /** @name Lock flags (bit masks).
|
---|
| 1113 | * @{ */
|
---|
| 1114 | /** Read access, can be shared with others. */
|
---|
| 1115 | #define RTFILE_LOCK_READ 0x00
|
---|
| 1116 | /** Write access, one at a time. */
|
---|
| 1117 | #define RTFILE_LOCK_WRITE 0x01
|
---|
| 1118 | /** Don't wait for other locks to be released. */
|
---|
| 1119 | #define RTFILE_LOCK_IMMEDIATELY 0x00
|
---|
| 1120 | /** Wait till conflicting locks have been released. */
|
---|
| 1121 | #define RTFILE_LOCK_WAIT 0x02
|
---|
| 1122 | /** Valid flags mask */
|
---|
| 1123 | #define RTFILE_LOCK_MASK 0x03
|
---|
| 1124 | /** @} */
|
---|
| 1125 |
|
---|
| 1126 |
|
---|
| 1127 | /**
|
---|
| 1128 | * Locks a region of file for read (shared) or write (exclusive) access.
|
---|
| 1129 | *
|
---|
| 1130 | * @returns iprt status code.
|
---|
| 1131 | * @returns VERR_FILE_LOCK_VIOLATION if lock can't be acquired.
|
---|
| 1132 | * @param File Handle to the file.
|
---|
| 1133 | * @param fLock Lock method and flags, see RTFILE_LOCK_* defines.
|
---|
| 1134 | * @param offLock Offset of lock start.
|
---|
| 1135 | * @param cbLock Length of region to lock, may overlap the end of file.
|
---|
| 1136 | */
|
---|
[37559] | 1137 | RTDECL(int) RTFileLock(RTFILE File, unsigned fLock, int64_t offLock, uint64_t cbLock);
|
---|
[1] | 1138 |
|
---|
| 1139 | /**
|
---|
| 1140 | * Changes a lock type from read to write or from write to read.
|
---|
[99760] | 1141 | *
|
---|
[1] | 1142 | * The region to type change must correspond exactly to an existing locked region.
|
---|
| 1143 | * If change can't be done due to locking conflict and non-blocking mode is used, error is
|
---|
| 1144 | * returned and lock keeps its state (see next warning).
|
---|
| 1145 | *
|
---|
| 1146 | * WARNING: win32 implementation of this call is not atomic, it transforms to a pair of
|
---|
| 1147 | * calls RTFileUnlock and RTFileLock. Potentially the previously acquired lock can be
|
---|
| 1148 | * lost, i.e. function is called in non-blocking mode, previous lock is freed, new lock can't
|
---|
| 1149 | * be acquired, and old lock (previous state) can't be acquired back too. This situation
|
---|
| 1150 | * may occurs _only_ if the other process is acquiring a _write_ lock in blocking mode or
|
---|
| 1151 | * in race condition with the current call.
|
---|
| 1152 | * In this very bad case special error code VERR_FILE_LOCK_LOST will be returned.
|
---|
| 1153 | *
|
---|
| 1154 | * @returns iprt status code.
|
---|
| 1155 | * @returns VERR_FILE_NOT_LOCKED if region was not locked.
|
---|
| 1156 | * @returns VERR_FILE_LOCK_VIOLATION if lock type can't be changed, lock remains its type.
|
---|
| 1157 | * @returns VERR_FILE_LOCK_LOST if lock was lost, we haven't this lock anymore :(
|
---|
| 1158 | * @param File Handle to the file.
|
---|
| 1159 | * @param fLock Lock method and flags, see RTFILE_LOCK_* defines.
|
---|
| 1160 | * @param offLock Offset of lock start.
|
---|
| 1161 | * @param cbLock Length of region to lock, may overlap the end of file.
|
---|
| 1162 | */
|
---|
[37559] | 1163 | RTDECL(int) RTFileChangeLock(RTFILE File, unsigned fLock, int64_t offLock, uint64_t cbLock);
|
---|
[1] | 1164 |
|
---|
| 1165 | /**
|
---|
| 1166 | * Unlocks previously locked region of file.
|
---|
| 1167 | * The region to unlock must correspond exactly to an existing locked region.
|
---|
| 1168 | *
|
---|
| 1169 | * @returns iprt status code.
|
---|
| 1170 | * @returns VERR_FILE_NOT_LOCKED if region was not locked.
|
---|
| 1171 | * @param File Handle to the file.
|
---|
| 1172 | * @param offLock Offset of lock start.
|
---|
| 1173 | * @param cbLock Length of region to unlock, may overlap the end of file.
|
---|
| 1174 | */
|
---|
[37559] | 1175 | RTDECL(int) RTFileUnlock(RTFILE File, int64_t offLock, uint64_t cbLock);
|
---|
[1] | 1176 |
|
---|
[99760] | 1177 | /** @} */
|
---|
[1] | 1178 |
|
---|
[99760] | 1179 |
|
---|
[1] | 1180 | /**
|
---|
| 1181 | * Query information about an open file.
|
---|
| 1182 | *
|
---|
| 1183 | * @returns iprt status code.
|
---|
| 1184 | *
|
---|
| 1185 | * @param File Handle to the file.
|
---|
| 1186 | * @param pObjInfo Object information structure to be filled on successful return.
|
---|
| 1187 | * @param enmAdditionalAttribs Which set of additional attributes to request.
|
---|
| 1188 | * Use RTFSOBJATTRADD_NOTHING if this doesn't matter.
|
---|
| 1189 | */
|
---|
[37559] | 1190 | RTDECL(int) RTFileQueryInfo(RTFILE File, PRTFSOBJINFO pObjInfo, RTFSOBJATTRADD enmAdditionalAttribs);
|
---|
[1] | 1191 |
|
---|
| 1192 | /**
|
---|
| 1193 | * Changes one or more of the timestamps associated of file system object.
|
---|
| 1194 | *
|
---|
| 1195 | * @returns iprt status code.
|
---|
[24889] | 1196 | * @retval VERR_NOT_SUPPORTED is returned if the operation isn't supported by
|
---|
| 1197 | * the OS.
|
---|
[1] | 1198 | *
|
---|
| 1199 | * @param File Handle to the file.
|
---|
| 1200 | * @param pAccessTime Pointer to the new access time. NULL if not to be changed.
|
---|
| 1201 | * @param pModificationTime Pointer to the new modifcation time. NULL if not to be changed.
|
---|
| 1202 | * @param pChangeTime Pointer to the new change time. NULL if not to be changed.
|
---|
| 1203 | * @param pBirthTime Pointer to the new time of birth. NULL if not to be changed.
|
---|
| 1204 | *
|
---|
| 1205 | * @remark The file system might not implement all these time attributes,
|
---|
| 1206 | * the API will ignore the ones which aren't supported.
|
---|
| 1207 | *
|
---|
| 1208 | * @remark The file system might not implement the time resolution
|
---|
| 1209 | * employed by this interface, the time will be chopped to fit.
|
---|
| 1210 | *
|
---|
| 1211 | * @remark The file system may update the change time even if it's
|
---|
| 1212 | * not specified.
|
---|
| 1213 | *
|
---|
| 1214 | * @remark POSIX can only set Access & Modification and will always set both.
|
---|
| 1215 | */
|
---|
[37559] | 1216 | RTDECL(int) RTFileSetTimes(RTFILE File, PCRTTIMESPEC pAccessTime, PCRTTIMESPEC pModificationTime,
|
---|
| 1217 | PCRTTIMESPEC pChangeTime, PCRTTIMESPEC pBirthTime);
|
---|
[1] | 1218 |
|
---|
| 1219 | /**
|
---|
| 1220 | * Gets one or more of the timestamps associated of file system object.
|
---|
| 1221 | *
|
---|
| 1222 | * @returns iprt status code.
|
---|
| 1223 | * @param File Handle to the file.
|
---|
| 1224 | * @param pAccessTime Where to store the access time. NULL is ok.
|
---|
| 1225 | * @param pModificationTime Where to store the modifcation time. NULL is ok.
|
---|
| 1226 | * @param pChangeTime Where to store the change time. NULL is ok.
|
---|
| 1227 | * @param pBirthTime Where to store the time of birth. NULL is ok.
|
---|
| 1228 | *
|
---|
| 1229 | * @remark This is wrapper around RTFileQueryInfo() and exists to complement RTFileSetTimes().
|
---|
| 1230 | */
|
---|
[37559] | 1231 | RTDECL(int) RTFileGetTimes(RTFILE File, PRTTIMESPEC pAccessTime, PRTTIMESPEC pModificationTime,
|
---|
| 1232 | PRTTIMESPEC pChangeTime, PRTTIMESPEC pBirthTime);
|
---|
[1] | 1233 |
|
---|
| 1234 | /**
|
---|
| 1235 | * Changes the mode flags of an open file.
|
---|
| 1236 | *
|
---|
| 1237 | * The API requires at least one of the mode flag sets (Unix/Dos) to
|
---|
| 1238 | * be set. The type is ignored.
|
---|
| 1239 | *
|
---|
| 1240 | * @returns iprt status code.
|
---|
| 1241 | * @param File Handle to the file.
|
---|
| 1242 | * @param fMode The new file mode, see @ref grp_rt_fs for details.
|
---|
| 1243 | */
|
---|
[37559] | 1244 | RTDECL(int) RTFileSetMode(RTFILE File, RTFMODE fMode);
|
---|
[1] | 1245 |
|
---|
| 1246 | /**
|
---|
| 1247 | * Gets the mode flags of an open file.
|
---|
| 1248 | *
|
---|
| 1249 | * @returns iprt status code.
|
---|
| 1250 | * @param File Handle to the file.
|
---|
| 1251 | * @param pfMode Where to store the file mode, see @ref grp_rt_fs for details.
|
---|
| 1252 | *
|
---|
| 1253 | * @remark This is wrapper around RTFileQueryInfo()
|
---|
| 1254 | * and exists to complement RTFileSetMode().
|
---|
| 1255 | */
|
---|
[37559] | 1256 | RTDECL(int) RTFileGetMode(RTFILE File, uint32_t *pfMode);
|
---|
[1] | 1257 |
|
---|
| 1258 | /**
|
---|
| 1259 | * Changes the owner and/or group of an open file.
|
---|
| 1260 | *
|
---|
| 1261 | * @returns iprt status code.
|
---|
| 1262 | * @param File Handle to the file.
|
---|
[34230] | 1263 | * @param uid The new file owner user id. Pass NIL_RTUID to leave
|
---|
| 1264 | * this unchanged.
|
---|
| 1265 | * @param gid The new group id. Pass NIL_RTGID to leave this
|
---|
| 1266 | * unchanged.
|
---|
[1] | 1267 | */
|
---|
[37559] | 1268 | RTDECL(int) RTFileSetOwner(RTFILE File, uint32_t uid, uint32_t gid);
|
---|
[1] | 1269 |
|
---|
| 1270 | /**
|
---|
| 1271 | * Gets the owner and/or group of an open file.
|
---|
| 1272 | *
|
---|
| 1273 | * @returns iprt status code.
|
---|
| 1274 | * @param File Handle to the file.
|
---|
| 1275 | * @param pUid Where to store the owner user id. NULL is ok.
|
---|
| 1276 | * @param pGid Where to store the group id. NULL is ok.
|
---|
| 1277 | *
|
---|
| 1278 | * @remark This is wrapper around RTFileQueryInfo() and exists to complement RTFileGetOwner().
|
---|
| 1279 | */
|
---|
[37559] | 1280 | RTDECL(int) RTFileGetOwner(RTFILE File, uint32_t *pUid, uint32_t *pGid);
|
---|
[1] | 1281 |
|
---|
| 1282 | /**
|
---|
| 1283 | * Executes an IOCTL on a file descriptor.
|
---|
| 1284 | *
|
---|
| 1285 | * This function is currently only available in L4 and posix environments.
|
---|
| 1286 | * Attemps at calling it from code shared with any other platforms will break things!
|
---|
| 1287 | *
|
---|
| 1288 | * The rational for defining this API is to simplify L4 porting of audio drivers,
|
---|
| 1289 | * and to remove some of the assumptions on RTFILE being a file descriptor on
|
---|
| 1290 | * platforms using the posix file implementation.
|
---|
| 1291 | *
|
---|
| 1292 | * @returns iprt status code.
|
---|
| 1293 | * @param File Handle to the file.
|
---|
[57926] | 1294 | * @param ulRequest IOCTL request to carry out.
|
---|
[1] | 1295 | * @param pvData IOCTL data.
|
---|
| 1296 | * @param cbData Size of the IOCTL data.
|
---|
| 1297 | * @param piRet Return value of the IOCTL request.
|
---|
| 1298 | */
|
---|
[37559] | 1299 | RTDECL(int) RTFileIoCtl(RTFILE File, unsigned long ulRequest, void *pvData, unsigned cbData, int *piRet);
|
---|
[1] | 1300 |
|
---|
[8925] | 1301 | /**
|
---|
[24889] | 1302 | * Query the sizes of a filesystem.
|
---|
| 1303 | *
|
---|
| 1304 | * @returns iprt status code.
|
---|
| 1305 | * @retval VERR_NOT_SUPPORTED is returned if the operation isn't supported by
|
---|
| 1306 | * the OS.
|
---|
| 1307 | *
|
---|
| 1308 | * @param hFile The file handle.
|
---|
| 1309 | * @param pcbTotal Where to store the total filesystem space. (Optional)
|
---|
| 1310 | * @param pcbFree Where to store the remaining free space in the filesystem. (Optional)
|
---|
| 1311 | * @param pcbBlock Where to store the block size. (Optional)
|
---|
| 1312 | * @param pcbSector Where to store the sector size. (Optional)
|
---|
| 1313 | *
|
---|
| 1314 | * @sa RTFsQuerySizes
|
---|
| 1315 | */
|
---|
[37559] | 1316 | RTDECL(int) RTFileQueryFsSizes(RTFILE hFile, PRTFOFF pcbTotal, RTFOFF *pcbFree,
|
---|
| 1317 | uint32_t *pcbBlock, uint32_t *pcbSector);
|
---|
[24889] | 1318 |
|
---|
| 1319 | /**
|
---|
[8925] | 1320 | * Reads the file into memory.
|
---|
| 1321 | *
|
---|
| 1322 | * The caller must free the memory using RTFileReadAllFree().
|
---|
| 1323 | *
|
---|
| 1324 | * @returns IPRT status code.
|
---|
| 1325 | * @param pszFilename The name of the file.
|
---|
| 1326 | * @param ppvFile Where to store the pointer to the memory on successful return.
|
---|
[21801] | 1327 | * @param pcbFile Where to store the size of the returned memory.
|
---|
[8925] | 1328 | *
|
---|
| 1329 | * @remarks Note that this function may be implemented using memory mapping, which means
|
---|
| 1330 | * that the file may remain open until RTFileReadAllFree() is called. It also
|
---|
| 1331 | * means that the return memory may reflect the state of the file when it's
|
---|
| 1332 | * accessed instead of when this call was done. So, in short, don't use this
|
---|
| 1333 | * API for volatile files, then rather use the extended variant with a
|
---|
[25922] | 1334 | * yet-to-be-defined flag.
|
---|
[8925] | 1335 | */
|
---|
| 1336 | RTDECL(int) RTFileReadAll(const char *pszFilename, void **ppvFile, size_t *pcbFile);
|
---|
| 1337 |
|
---|
| 1338 | /**
|
---|
| 1339 | * Reads the file into memory.
|
---|
| 1340 | *
|
---|
| 1341 | * The caller must free the memory using RTFileReadAllFree().
|
---|
| 1342 | *
|
---|
| 1343 | * @returns IPRT status code.
|
---|
| 1344 | * @param pszFilename The name of the file.
|
---|
| 1345 | * @param off The offset to start reading at.
|
---|
| 1346 | * @param cbMax The maximum number of bytes to read into memory. Specify RTFOFF_MAX
|
---|
| 1347 | * to read to the end of the file.
|
---|
[19350] | 1348 | * @param fFlags See RTFILE_RDALL_*.
|
---|
[8925] | 1349 | * @param ppvFile Where to store the pointer to the memory on successful return.
|
---|
[21801] | 1350 | * @param pcbFile Where to store the size of the returned memory.
|
---|
[8925] | 1351 | *
|
---|
| 1352 | * @remarks See the remarks for RTFileReadAll.
|
---|
| 1353 | */
|
---|
| 1354 | RTDECL(int) RTFileReadAllEx(const char *pszFilename, RTFOFF off, RTFOFF cbMax, uint32_t fFlags, void **ppvFile, size_t *pcbFile);
|
---|
| 1355 |
|
---|
| 1356 | /**
|
---|
| 1357 | * Reads the file into memory.
|
---|
| 1358 | *
|
---|
| 1359 | * The caller must free the memory using RTFileReadAllFree().
|
---|
| 1360 | *
|
---|
| 1361 | * @returns IPRT status code.
|
---|
| 1362 | * @param File The handle to the file.
|
---|
| 1363 | * @param ppvFile Where to store the pointer to the memory on successful return.
|
---|
[21801] | 1364 | * @param pcbFile Where to store the size of the returned memory.
|
---|
[8925] | 1365 | *
|
---|
| 1366 | * @remarks See the remarks for RTFileReadAll.
|
---|
| 1367 | */
|
---|
| 1368 | RTDECL(int) RTFileReadAllByHandle(RTFILE File, void **ppvFile, size_t *pcbFile);
|
---|
| 1369 |
|
---|
| 1370 | /**
|
---|
| 1371 | * Reads the file into memory.
|
---|
| 1372 | *
|
---|
| 1373 | * The caller must free the memory using RTFileReadAllFree().
|
---|
| 1374 | *
|
---|
| 1375 | * @returns IPRT status code.
|
---|
| 1376 | * @param File The handle to the file.
|
---|
| 1377 | * @param off The offset to start reading at.
|
---|
| 1378 | * @param cbMax The maximum number of bytes to read into memory. Specify RTFOFF_MAX
|
---|
| 1379 | * to read to the end of the file.
|
---|
[19350] | 1380 | * @param fFlags See RTFILE_RDALL_*.
|
---|
[8925] | 1381 | * @param ppvFile Where to store the pointer to the memory on successful return.
|
---|
[21801] | 1382 | * @param pcbFile Where to store the size of the returned memory.
|
---|
[8925] | 1383 | *
|
---|
| 1384 | * @remarks See the remarks for RTFileReadAll.
|
---|
| 1385 | */
|
---|
| 1386 | RTDECL(int) RTFileReadAllByHandleEx(RTFILE File, RTFOFF off, RTFOFF cbMax, uint32_t fFlags, void **ppvFile, size_t *pcbFile);
|
---|
| 1387 |
|
---|
| 1388 | /**
|
---|
| 1389 | * Frees the memory returned by one of the RTFileReadAll(), RTFileReadAllEx(),
|
---|
| 1390 | * RTFileReadAllByHandle() and RTFileReadAllByHandleEx() functions.
|
---|
| 1391 | *
|
---|
| 1392 | * @param pvFile Pointer to the memory.
|
---|
| 1393 | * @param cbFile The size of the memory.
|
---|
| 1394 | */
|
---|
[16997] | 1395 | RTDECL(void) RTFileReadAllFree(void *pvFile, size_t cbFile);
|
---|
[8925] | 1396 |
|
---|
[19350] | 1397 | /** @name RTFileReadAllEx and RTFileReadAllHandleEx flags
|
---|
| 1398 | * The open flags are ignored by RTFileReadAllHandleEx.
|
---|
| 1399 | * @{ */
|
---|
| 1400 | #define RTFILE_RDALL_O_DENY_NONE RTFILE_O_DENY_NONE
|
---|
| 1401 | #define RTFILE_RDALL_O_DENY_READ RTFILE_O_DENY_READ
|
---|
| 1402 | #define RTFILE_RDALL_O_DENY_WRITE RTFILE_O_DENY_WRITE
|
---|
| 1403 | #define RTFILE_RDALL_O_DENY_READWRITE RTFILE_O_DENY_READWRITE
|
---|
| 1404 | #define RTFILE_RDALL_O_DENY_ALL RTFILE_O_DENY_ALL
|
---|
| 1405 | #define RTFILE_RDALL_O_DENY_NOT_DELETE RTFILE_O_DENY_NOT_DELETE
|
---|
| 1406 | #define RTFILE_RDALL_O_DENY_MASK RTFILE_O_DENY_MASK
|
---|
[75045] | 1407 | /** Fail with VERR_OUT_OF_RANGE if the file size exceeds the specified maximum
|
---|
| 1408 | * size. The default behavior is to cap the size at cbMax. */
|
---|
| 1409 | #define RTFILE_RDALL_F_FAIL_ON_MAX_SIZE RT_BIT_32(30)
|
---|
[68183] | 1410 | /** Add a trailing zero byte to facilitate reading text files. */
|
---|
| 1411 | #define RTFILE_RDALL_F_TRAILING_ZERO_BYTE RT_BIT_32(31)
|
---|
[19350] | 1412 | /** Mask of valid flags. */
|
---|
[75045] | 1413 | #define RTFILE_RDALL_VALID_MASK (RTFILE_RDALL_O_DENY_MASK | UINT32_C(0xc0000000))
|
---|
[19350] | 1414 | /** @} */
|
---|
[18961] | 1415 |
|
---|
[59459] | 1416 | /**
|
---|
| 1417 | * Sets the current size of the file ensuring that all required blocks
|
---|
| 1418 | * are allocated on the underlying medium.
|
---|
| 1419 | *
|
---|
| 1420 | * @returns IPRT status code.
|
---|
[69977] | 1421 | * @retval VERR_NOT_SUPPORTED if either this operation is not supported on the
|
---|
| 1422 | * current host in an efficient manner or the given combination of
|
---|
| 1423 | * flags is not supported.
|
---|
[59459] | 1424 | * @param hFile The handle to the file.
|
---|
| 1425 | * @param cbSize The new size of the file to allocate.
|
---|
| 1426 | * @param fFlags Combination of RTFILE_ALLOC_SIZE_F_*
|
---|
| 1427 | */
|
---|
| 1428 | RTDECL(int) RTFileSetAllocationSize(RTFILE hFile, uint64_t cbSize, uint32_t fFlags);
|
---|
| 1429 |
|
---|
[69977] | 1430 | /** @name RTFILE_ALLOC_SIZE_F_XXX - RTFileSetAllocationSize flags
|
---|
| 1431 | * @{ */
|
---|
| 1432 | /** Default flags. */
|
---|
| 1433 | #define RTFILE_ALLOC_SIZE_F_DEFAULT 0
|
---|
| 1434 | /** Do not change the size of the file if the given size is bigger than the
|
---|
| 1435 | * current file size.
|
---|
| 1436 | *
|
---|
| 1437 | * Useful to preallocate blocks beyond the current size for appending data in an
|
---|
| 1438 | * efficient manner. Might not be supported on all hosts and will return
|
---|
| 1439 | * VERR_NOT_SUPPORTED in that case. */
|
---|
| 1440 | #define RTFILE_ALLOC_SIZE_F_KEEP_SIZE RT_BIT(0)
|
---|
| 1441 | /** Mask of valid flags. */
|
---|
| 1442 | #define RTFILE_ALLOC_SIZE_F_VALID (RTFILE_ALLOC_SIZE_F_KEEP_SIZE)
|
---|
| 1443 | /** @} */
|
---|
| 1444 |
|
---|
| 1445 |
|
---|
[37559] | 1446 | #ifdef IN_RING3
|
---|
| 1447 |
|
---|
[99760] | 1448 | /** @defgroup grp_rt_fileio_async RT File Async I/O API
|
---|
[18909] | 1449 | *
|
---|
[99760] | 1450 | * File operations are usually blocking the calling thread until they completed
|
---|
| 1451 | * making it impossible to let the thread do anything else in-between. The RT
|
---|
| 1452 | * File async I/O API provides an easy and efficient way to access files
|
---|
| 1453 | * asynchronously using the native facilities provided by each operating system.
|
---|
[19125] | 1454 | *
|
---|
[19562] | 1455 | * @section sec_rt_asyncio_objects Objects
|
---|
| 1456 | *
|
---|
[19125] | 1457 | * There are two objects used in this API.
|
---|
| 1458 | *
|
---|
[99760] | 1459 | * The first object is the request. A request contains every information needed
|
---|
| 1460 | * two complete the file operation successfully like the start offset and
|
---|
| 1461 | * pointer to the source or destination buffer. Requests are created with
|
---|
| 1462 | * RTFileAioReqCreate() and destroyed with RTFileAioReqDestroy(). Because
|
---|
| 1463 | * creating a request may require allocating various operating system dependent
|
---|
| 1464 | * resources and may be quite expensive it is possible to use a request more
|
---|
| 1465 | * than once to save CPU cycles. A request is constructed with either
|
---|
| 1466 | * RTFileAioReqPrepareRead() which will set up a request to read from the given
|
---|
| 1467 | * file or RTFileAioReqPrepareWrite() which will write to a given file.
|
---|
[19125] | 1468 | *
|
---|
[99760] | 1469 | * The second object is the context. A file is associated with a context and
|
---|
| 1470 | * requests for this file may complete only on the context the file was
|
---|
| 1471 | * associated with and not on the context given in RTFileAioCtxSubmit() (see
|
---|
| 1472 | * below for further information). RTFileAioCtxWait() is used to wait for
|
---|
| 1473 | * completion of requests which were associated with the context. While waiting
|
---|
| 1474 | * for requests the thread can not respond to global state changes. That's why
|
---|
| 1475 | * the API provides a way to let RTFileAioCtxWait() return immediately no matter
|
---|
| 1476 | * how many requests have finished through RTFileAioCtxWakeup(). The return code
|
---|
| 1477 | * is VERR_INTERRUPTED to let the thread know that he got interrupted.
|
---|
| 1478 | *
|
---|
[19562] | 1479 | * @section sec_rt_asyncio_request_states Request states
|
---|
[19125] | 1480 | *
|
---|
[99760] | 1481 | * @b Created:
|
---|
[19562] | 1482 | * After a request was created with RTFileAioReqCreate() it is in the same state
|
---|
[99760] | 1483 | * like it just completed successfully. RTFileAioReqGetRC() will return
|
---|
| 1484 | * VINF_SUCCESS and a transfer size of 0. RTFileAioReqGetUser() will return
|
---|
| 1485 | * NULL. The request can be destroyed RTFileAioReqDestroy(). It is also allowed
|
---|
| 1486 | * to prepare a the request for a data transfer with the RTFileAioReqPrepare*
|
---|
| 1487 | * methods. Calling any other method like RTFileAioCtxSubmit() will return
|
---|
| 1488 | * VERR_FILE_AIO_NOT_PREPARED and RTFileAioReqCancel() returns
|
---|
| 1489 | * VERR_FILE_AIO_NOT_SUBMITTED.
|
---|
[19562] | 1490 | *
|
---|
[99760] | 1491 | * @b Prepared:
|
---|
| 1492 | * A request will enter this state if one of the RTFileAioReqPrepare* methods is
|
---|
| 1493 | * called. In this state you can still destroy and retrieve the user data
|
---|
| 1494 | * associated with the request but trying to cancel the request or getting the
|
---|
| 1495 | * result of the operation will return VERR_FILE_AIO_NOT_SUBMITTED.
|
---|
[19562] | 1496 | *
|
---|
[99760] | 1497 | * @b Submitted:
|
---|
| 1498 | * A prepared request can be submitted with RTFileAioCtxSubmit(). If the
|
---|
| 1499 | * operation succeeds it is not allowed to touch the request or free any
|
---|
| 1500 | * resources until it completed through RTFileAioCtxWait(). The only allowed
|
---|
| 1501 | * method is RTFileAioReqCancel() which tries to cancel the request. The request
|
---|
| 1502 | * will go into the completed state and RTFileAioReqGetRC() will return
|
---|
| 1503 | * VERR_FILE_AIO_CANCELED. If the request completes not matter if successfully
|
---|
| 1504 | * or with an error it will switch into the completed state. RTFileReqDestroy()
|
---|
| 1505 | * fails if the given request is in this state.
|
---|
[19562] | 1506 | *
|
---|
[99760] | 1507 | * @b Completed:
|
---|
[19562] | 1508 | * The request will be in this state after it completed and returned through
|
---|
[99760] | 1509 | * RTFileAioCtxWait(). RTFileAioReqGetRC() returns the final result code and the
|
---|
| 1510 | * number of bytes transferred. The request can be used for new data transfers.
|
---|
[19562] | 1511 | *
|
---|
| 1512 | * @section sec_rt_asyncio_threading Threading
|
---|
| 1513 | *
|
---|
[19125] | 1514 | * The API is a thin wrapper around the specific host OS APIs and therefore
|
---|
[99760] | 1515 | * relies on the thread safety of the underlying API. The interesting functions
|
---|
| 1516 | * with regards to thread safety are RTFileAioCtxSubmit() and
|
---|
| 1517 | * RTFileAioCtxWait(). RTFileAioCtxWait() must not be called from different
|
---|
[19125] | 1518 | * threads at the same time with the same context handle. The same applies to
|
---|
[99760] | 1519 | * RTFileAioCtxSubmit(). However it is possible to submit new requests from a
|
---|
| 1520 | * different thread while waiting for completed requests on another thread with
|
---|
| 1521 | * RTFileAioCtxWait().
|
---|
[19125] | 1522 | *
|
---|
[19562] | 1523 | * @section sec_rt_asyncio_implementations Differences in implementation
|
---|
| 1524 | *
|
---|
[99760] | 1525 | * Because the host APIs are quite different on every OS and every API has other
|
---|
| 1526 | * limitations there are some things to consider to make the code as portable as
|
---|
| 1527 | * possible.
|
---|
[19125] | 1528 | *
|
---|
[99760] | 1529 | * The first restriction at the moment is that every buffer has to be aligned to
|
---|
| 1530 | * a 512 byte boundary. This limitation comes from the Linux io_* interface. To
|
---|
| 1531 | * use the interface the file must be opened with O_DIRECT. This flag disables
|
---|
| 1532 | * the kernel cache too which may degrade performance but is unfortunately the
|
---|
| 1533 | * only way to make asynchronous I/O work till today (if O_DIRECT is omitted
|
---|
| 1534 | * io_submit will revert to sychronous behavior and will return when the
|
---|
| 1535 | * requests finished and when they are queued). It is mostly used by DBMS which
|
---|
| 1536 | * do theire own caching. Furthermore there is no filesystem independent way to
|
---|
| 1537 | * discover the restrictions at least for the 2.4 kernel series. Since 2.6 the
|
---|
| 1538 | * 512 byte boundary seems to be used by all file systems. So Linus comment
|
---|
| 1539 | * about this flag is comprehensible but Linux lacks an alternative at the
|
---|
| 1540 | * moment.
|
---|
[19185] | 1541 | *
|
---|
[99760] | 1542 | * The next limitation applies only to Windows. Requests are not associated with
|
---|
| 1543 | * the I/O context they are associated with but with the file the request is
|
---|
| 1544 | * for. The file needs to be associated with exactly one I/O completion port and
|
---|
| 1545 | * requests for this file will only arrive at that context after they completed
|
---|
| 1546 | * and not on the context the request was submitted. To associate a file with a
|
---|
| 1547 | * specific context RTFileAioCtxAssociateWithFile() is used. It is only
|
---|
| 1548 | * implemented on Windows and does nothing on the other platforms. If the file
|
---|
| 1549 | * needs to be associated with different context for some reason the file must
|
---|
| 1550 | * be closed first. After it was opened again the new context can be associated
|
---|
| 1551 | * with the other context. This can't be done by the API because there is no way
|
---|
| 1552 | * to retrieve the flags the file was opened with.
|
---|
| 1553 | *
|
---|
| 1554 | * @{
|
---|
[18909] | 1555 | */
|
---|
| 1556 |
|
---|
| 1557 | /**
|
---|
[19562] | 1558 | * Global limits for the AIO API.
|
---|
| 1559 | */
|
---|
| 1560 | typedef struct RTFILEAIOLIMITS
|
---|
| 1561 | {
|
---|
| 1562 | /** Global number of simultaneous outstanding requests allowed.
|
---|
| 1563 | * RTFILEAIO_UNLIMITED_REQS means no limit. */
|
---|
| 1564 | uint32_t cReqsOutstandingMax;
|
---|
| 1565 | /** The alignment data buffers need to have.
|
---|
| 1566 | * 0 means no alignment restrictions. */
|
---|
| 1567 | uint32_t cbBufferAlignment;
|
---|
| 1568 | } RTFILEAIOLIMITS;
|
---|
| 1569 | /** A pointer to a AIO limits structure. */
|
---|
| 1570 | typedef RTFILEAIOLIMITS *PRTFILEAIOLIMITS;
|
---|
| 1571 |
|
---|
| 1572 | /**
|
---|
| 1573 | * Returns the global limits for the AIO API.
|
---|
| 1574 | *
|
---|
| 1575 | * @returns IPRT status code.
|
---|
| 1576 | * @retval VERR_NOT_SUPPORTED if the host does not support the async I/O API.
|
---|
| 1577 | *
|
---|
| 1578 | * @param pAioLimits Where to store the global limit information.
|
---|
| 1579 | */
|
---|
| 1580 | RTDECL(int) RTFileAioGetLimits(PRTFILEAIOLIMITS pAioLimits);
|
---|
| 1581 |
|
---|
| 1582 | /**
|
---|
[18961] | 1583 | * Creates an async I/O request handle.
|
---|
[18909] | 1584 | *
|
---|
| 1585 | * @returns IPRT status code.
|
---|
[18961] | 1586 | * @param phReq Where to store the request handle.
|
---|
[18909] | 1587 | */
|
---|
[18961] | 1588 | RTDECL(int) RTFileAioReqCreate(PRTFILEAIOREQ phReq);
|
---|
[18909] | 1589 |
|
---|
| 1590 | /**
|
---|
[18961] | 1591 | * Destroys an async I/O request handle.
|
---|
[18909] | 1592 | *
|
---|
[19562] | 1593 | * @returns IPRT status code.
|
---|
| 1594 | * @retval VERR_FILE_AIO_IN_PROGRESS if the request is still in progress.
|
---|
| 1595 | *
|
---|
[18961] | 1596 | * @param hReq The request handle.
|
---|
[18909] | 1597 | */
|
---|
[19562] | 1598 | RTDECL(int) RTFileAioReqDestroy(RTFILEAIOREQ hReq);
|
---|
[18909] | 1599 |
|
---|
| 1600 | /**
|
---|
[18961] | 1601 | * Prepares an async read request.
|
---|
[18909] | 1602 | *
|
---|
| 1603 | * @returns IPRT status code.
|
---|
[19562] | 1604 | * @retval VERR_FILE_AIO_IN_PROGRESS if the request is still in progress.
|
---|
[18961] | 1605 | *
|
---|
| 1606 | * @param hReq The request handle.
|
---|
| 1607 | * @param hFile The file to read from.
|
---|
[18909] | 1608 | * @param off The offset to start reading at.
|
---|
| 1609 | * @param pvBuf Where to store the read bits.
|
---|
| 1610 | * @param cbRead Number of bytes to read.
|
---|
| 1611 | * @param pvUser Opaque user data associated with this request which
|
---|
[18961] | 1612 | * can be retrieved with RTFileAioReqGetUser().
|
---|
[18909] | 1613 | */
|
---|
[18961] | 1614 | RTDECL(int) RTFileAioReqPrepareRead(RTFILEAIOREQ hReq, RTFILE hFile, RTFOFF off,
|
---|
| 1615 | void *pvBuf, size_t cbRead, void *pvUser);
|
---|
[18909] | 1616 |
|
---|
| 1617 | /**
|
---|
[18961] | 1618 | * Prepares an async write request.
|
---|
[18909] | 1619 | *
|
---|
| 1620 | * @returns IPRT status code.
|
---|
[19562] | 1621 | * @retval VERR_FILE_AIO_IN_PROGRESS if the request is still in progress.
|
---|
[18961] | 1622 | *
|
---|
| 1623 | * @param hReq The request handle.
|
---|
| 1624 | * @param hFile The file to write to.
|
---|
[18909] | 1625 | * @param off The offset to start writing at.
|
---|
[25645] | 1626 | * @param pvBuf The bits to write.
|
---|
| 1627 | * @param cbWrite Number of bytes to write.
|
---|
[18909] | 1628 | * @param pvUser Opaque user data associated with this request which
|
---|
[18961] | 1629 | * can be retrieved with RTFileAioReqGetUser().
|
---|
[18909] | 1630 | */
|
---|
[18961] | 1631 | RTDECL(int) RTFileAioReqPrepareWrite(RTFILEAIOREQ hReq, RTFILE hFile, RTFOFF off,
|
---|
[25645] | 1632 | void const *pvBuf, size_t cbWrite, void *pvUser);
|
---|
[18909] | 1633 |
|
---|
| 1634 | /**
|
---|
[18961] | 1635 | * Prepares an async flush of all cached data associated with a file handle.
|
---|
[18909] | 1636 | *
|
---|
| 1637 | * @returns IPRT status code.
|
---|
[19562] | 1638 | * @retval VERR_FILE_AIO_IN_PROGRESS if the request is still in progress.
|
---|
[18961] | 1639 | *
|
---|
| 1640 | * @param hReq The request handle.
|
---|
| 1641 | * @param hFile The file to flush.
|
---|
[18909] | 1642 | * @param pvUser Opaque user data associated with this request which
|
---|
[18961] | 1643 | * can be retrieved with RTFileAioReqGetUser().
|
---|
| 1644 | *
|
---|
| 1645 | * @remarks May also flush other caches on some platforms.
|
---|
[18909] | 1646 | */
|
---|
[18961] | 1647 | RTDECL(int) RTFileAioReqPrepareFlush(RTFILEAIOREQ hReq, RTFILE hFile, void *pvUser);
|
---|
[18909] | 1648 |
|
---|
| 1649 | /**
|
---|
[18961] | 1650 | * Gets the opaque user data associated with the given request.
|
---|
[18909] | 1651 | *
|
---|
| 1652 | * @returns Opaque user data.
|
---|
[18961] | 1653 | * @retval NULL if the request hasn't been prepared yet.
|
---|
| 1654 | *
|
---|
| 1655 | * @param hReq The request handle.
|
---|
[18909] | 1656 | */
|
---|
[18961] | 1657 | RTDECL(void *) RTFileAioReqGetUser(RTFILEAIOREQ hReq);
|
---|
[18909] | 1658 |
|
---|
| 1659 | /**
|
---|
| 1660 | * Cancels a pending request.
|
---|
| 1661 | *
|
---|
| 1662 | * @returns IPRT status code.
|
---|
| 1663 | * @retval VINF_SUCCESS If the request was canceled.
|
---|
[19562] | 1664 | * @retval VERR_FILE_AIO_NOT_SUBMITTED If the request wasn't submitted yet.
|
---|
[18909] | 1665 | * @retval VERR_FILE_AIO_IN_PROGRESS If the request could not be canceled because it is already processed.
|
---|
| 1666 | * @retval VERR_FILE_AIO_COMPLETED If the request could not be canceled because it already completed.
|
---|
| 1667 | *
|
---|
[18961] | 1668 | * @param hReq The request to cancel.
|
---|
[18909] | 1669 | */
|
---|
[18961] | 1670 | RTDECL(int) RTFileAioReqCancel(RTFILEAIOREQ hReq);
|
---|
[18909] | 1671 |
|
---|
| 1672 | /**
|
---|
[18961] | 1673 | * Gets the status of a completed request.
|
---|
[18909] | 1674 | *
|
---|
| 1675 | * @returns The IPRT status code of the given request.
|
---|
[19562] | 1676 | * @retval VERR_FILE_AIO_NOT_SUBMITTED if the request wasn't submitted yet.
|
---|
| 1677 | * @retval VERR_FILE_AIO_CANCELED if the request was canceled.
|
---|
[18961] | 1678 | * @retval VERR_FILE_AIO_IN_PROGRESS if the request isn't yet completed.
|
---|
| 1679 | *
|
---|
| 1680 | * @param hReq The request handle.
|
---|
[33540] | 1681 | * @param pcbTransferred Where to store the number of bytes transferred.
|
---|
[18961] | 1682 | * Optional since it is not relevant for all kinds of
|
---|
| 1683 | * requests.
|
---|
[18909] | 1684 | */
|
---|
[25645] | 1685 | RTDECL(int) RTFileAioReqGetRC(RTFILEAIOREQ hReq, size_t *pcbTransferred);
|
---|
[18909] | 1686 |
|
---|
[18961] | 1687 |
|
---|
| 1688 |
|
---|
[18909] | 1689 | /**
|
---|
[18961] | 1690 | * Creates an async I/O context.
|
---|
[18909] | 1691 | *
|
---|
[18961] | 1692 | * @todo briefly explain what an async context is here or in the page
|
---|
| 1693 | * above.
|
---|
| 1694 | *
|
---|
[18909] | 1695 | * @returns IPRT status code.
|
---|
[18961] | 1696 | * @param phAioCtx Where to store the async I/O context handle.
|
---|
[18909] | 1697 | * @param cAioReqsMax How many async I/O requests the context should be capable
|
---|
[18961] | 1698 | * to handle. Pass RTFILEAIO_UNLIMITED_REQS if the
|
---|
| 1699 | * context should support an unlimited number of
|
---|
| 1700 | * requests.
|
---|
[45678] | 1701 | * @param fFlags Combination of RTFILEAIOCTX_FLAGS_*.
|
---|
[18909] | 1702 | */
|
---|
[45678] | 1703 | RTDECL(int) RTFileAioCtxCreate(PRTFILEAIOCTX phAioCtx, uint32_t cAioReqsMax,
|
---|
| 1704 | uint32_t fFlags);
|
---|
[18909] | 1705 |
|
---|
[18961] | 1706 | /** Unlimited number of requests.
|
---|
| 1707 | * Used with RTFileAioCtxCreate and RTFileAioCtxGetMaxReqCount. */
|
---|
| 1708 | #define RTFILEAIO_UNLIMITED_REQS UINT32_MAX
|
---|
| 1709 |
|
---|
[45678] | 1710 | /** When set RTFileAioCtxWait() will always wait for completing requests,
|
---|
[47735] | 1711 | * even when there is none waiting currently, instead of returning
|
---|
[45678] | 1712 | * VERR_FILE_AIO_NO_REQUEST. */
|
---|
| 1713 | #define RTFILEAIOCTX_FLAGS_WAIT_WITHOUT_PENDING_REQUESTS RT_BIT_32(0)
|
---|
| 1714 | /** mask of valid flags. */
|
---|
| 1715 | #define RTFILEAIOCTX_FLAGS_VALID_MASK (RTFILEAIOCTX_FLAGS_WAIT_WITHOUT_PENDING_REQUESTS)
|
---|
| 1716 |
|
---|
[18909] | 1717 | /**
|
---|
[18961] | 1718 | * Destroys an async I/O context.
|
---|
[18909] | 1719 | *
|
---|
| 1720 | * @returns IPRT status code.
|
---|
[18961] | 1721 | * @param hAioCtx The async I/O context handle.
|
---|
[18909] | 1722 | */
|
---|
[18961] | 1723 | RTDECL(int) RTFileAioCtxDestroy(RTFILEAIOCTX hAioCtx);
|
---|
[18909] | 1724 |
|
---|
| 1725 | /**
|
---|
| 1726 | * Get the maximum number of requests one aio context can handle.
|
---|
| 1727 | *
|
---|
| 1728 | * @returns Maximum number of tasks the context can handle.
|
---|
[18961] | 1729 | * RTFILEAIO_UNLIMITED_REQS if there is no limit.
|
---|
[18909] | 1730 | *
|
---|
[18961] | 1731 | * @param hAioCtx The async I/O context handle.
|
---|
[18909] | 1732 | * If NIL_RTAIOCONTEXT is passed the maximum value
|
---|
[18912] | 1733 | * which can be passed to RTFileAioCtxCreate()
|
---|
[18909] | 1734 | * is returned.
|
---|
| 1735 | */
|
---|
[18961] | 1736 | RTDECL(uint32_t) RTFileAioCtxGetMaxReqCount(RTFILEAIOCTX hAioCtx);
|
---|
[18909] | 1737 |
|
---|
| 1738 | /**
|
---|
[36573] | 1739 | * Associates a file with an async I/O context.
|
---|
[19185] | 1740 | * Requests for this file will arrive at the completion port
|
---|
| 1741 | * associated with the file.
|
---|
| 1742 | *
|
---|
| 1743 | * @returns IPRT status code.
|
---|
| 1744 | *
|
---|
| 1745 | * @param hAioCtx The async I/O context handle.
|
---|
| 1746 | * @param hFile The file handle.
|
---|
| 1747 | */
|
---|
| 1748 | RTDECL(int) RTFileAioCtxAssociateWithFile(RTFILEAIOCTX hAioCtx, RTFILE hFile);
|
---|
| 1749 |
|
---|
| 1750 | /**
|
---|
[18961] | 1751 | * Submits a set of requests to an async I/O context for processing.
|
---|
[18909] | 1752 | *
|
---|
| 1753 | * @returns IPRT status code.
|
---|
[21493] | 1754 | * @returns VERR_FILE_AIO_INSUFFICIENT_RESSOURCES if the maximum number of
|
---|
| 1755 | * simultaneous outstanding requests would be exceeded.
|
---|
[18961] | 1756 | *
|
---|
| 1757 | * @param hAioCtx The async I/O context handle.
|
---|
| 1758 | * @param pahReqs Pointer to an array of request handles.
|
---|
| 1759 | * @param cReqs The number of entries in the array.
|
---|
| 1760 | *
|
---|
[19562] | 1761 | * @remarks It is possible that some requests could be submitted successfully
|
---|
| 1762 | * even if the method returns an error code. In that case RTFileAioReqGetRC()
|
---|
| 1763 | * can be used to determine the status of a request.
|
---|
| 1764 | * If it returns VERR_FILE_AIO_IN_PROGRESS it was submitted successfully.
|
---|
| 1765 | * Any other error code may indicate why the request failed.
|
---|
| 1766 | * VERR_FILE_AIO_NOT_SUBMITTED indicates that a request wasn't submitted
|
---|
| 1767 | * probably because the previous request encountered an error.
|
---|
| 1768 | *
|
---|
[18961] | 1769 | * @remarks @a cReqs uses the type size_t while it really is a uint32_t, this is
|
---|
| 1770 | * to avoid annoying warnings when using RT_ELEMENTS and similar
|
---|
| 1771 | * macros.
|
---|
[18909] | 1772 | */
|
---|
[19562] | 1773 | RTDECL(int) RTFileAioCtxSubmit(RTFILEAIOCTX hAioCtx, PRTFILEAIOREQ pahReqs, size_t cReqs);
|
---|
[18909] | 1774 |
|
---|
| 1775 | /**
|
---|
[18961] | 1776 | * Waits for request completion.
|
---|
[18909] | 1777 | *
|
---|
[19039] | 1778 | * Only one thread at a time may call this API on a context.
|
---|
| 1779 | *
|
---|
[18909] | 1780 | * @returns IPRT status code.
|
---|
[18961] | 1781 | * @retval VERR_INVALID_POINTER If pcReqs or/and pahReqs are invalid.
|
---|
| 1782 | * @retval VERR_INVALID_HANDLE If hAioCtx is invalid.
|
---|
| 1783 | * @retval VERR_OUT_OF_RANGE If cMinReqs is larger than cReqs.
|
---|
| 1784 | * @retval VERR_INVALID_PARAMETER If cReqs is 0.
|
---|
| 1785 | * @retval VERR_TIMEOUT If cMinReqs didn't complete before the
|
---|
| 1786 | * timeout expired.
|
---|
| 1787 | * @retval VERR_INTERRUPTED If the completion context was interrupted
|
---|
| 1788 | * by RTFileAioCtxWakeup().
|
---|
| 1789 | * @retval VERR_FILE_AIO_NO_REQUEST If there are no pending request.
|
---|
[18909] | 1790 | *
|
---|
[18961] | 1791 | * @param hAioCtx The async I/O context handle to wait and get
|
---|
| 1792 | * completed requests from.
|
---|
| 1793 | * @param cMinReqs The minimum number of requests which have to
|
---|
| 1794 | * complete before this function returns.
|
---|
[25724] | 1795 | * @param cMillies The number of milliseconds to wait before returning
|
---|
| 1796 | * VERR_TIMEOUT. Use RT_INDEFINITE_WAIT to wait
|
---|
[18961] | 1797 | * forever.
|
---|
| 1798 | * @param pahReqs Pointer to an array where the handles of the
|
---|
| 1799 | * completed requests will be stored on success.
|
---|
| 1800 | * @param cReqs The number of entries @a pahReqs can hold.
|
---|
| 1801 | * @param pcReqs Where to store the number of returned (complete)
|
---|
| 1802 | * requests. This will always be set.
|
---|
| 1803 | *
|
---|
| 1804 | * @remarks The wait will be resume if interrupted by a signal. An
|
---|
| 1805 | * RTFileAioCtxWaitNoResume variant can be added later if it becomes
|
---|
| 1806 | * necessary.
|
---|
| 1807 | *
|
---|
| 1808 | * @remarks @a cMinReqs and @a cReqs use the type size_t while they really are
|
---|
| 1809 | * uint32_t's, this is to avoid annoying warnings when using
|
---|
| 1810 | * RT_ELEMENTS and similar macros.
|
---|
[18909] | 1811 | */
|
---|
[25724] | 1812 | RTDECL(int) RTFileAioCtxWait(RTFILEAIOCTX hAioCtx, size_t cMinReqs, RTMSINTERVAL cMillies,
|
---|
[18999] | 1813 | PRTFILEAIOREQ pahReqs, size_t cReqs, uint32_t *pcReqs);
|
---|
[18909] | 1814 |
|
---|
| 1815 | /**
|
---|
[19039] | 1816 | * Forces any RTFileAioCtxWait() call on another thread to return immediately.
|
---|
[18909] | 1817 | *
|
---|
| 1818 | * @returns IPRT status code.
|
---|
[18961] | 1819 | *
|
---|
| 1820 | * @param hAioCtx The handle of the async I/O context to wakeup.
|
---|
[18909] | 1821 | */
|
---|
[18961] | 1822 | RTDECL(int) RTFileAioCtxWakeup(RTFILEAIOCTX hAioCtx);
|
---|
[18909] | 1823 |
|
---|
[99760] | 1824 | /** @} */
|
---|
| 1825 |
|
---|
[1] | 1826 | #endif /* IN_RING3 */
|
---|
| 1827 |
|
---|
| 1828 | /** @} */
|
---|
| 1829 |
|
---|
[20374] | 1830 | RT_C_DECLS_END
|
---|
[1] | 1831 |
|
---|
[76585] | 1832 | #endif /* !IPRT_INCLUDED_file_h */
|
---|
[1] | 1833 |
|
---|