[1] | 1 | /** @file
|
---|
[2981] | 2 | * innotek Portable Runtime - File I/O.
|
---|
[1] | 3 | */
|
---|
| 4 |
|
---|
| 5 | /*
|
---|
[8155] | 6 | * Copyright (C) 2006-2007 Sun Microsystems, Inc.
|
---|
[1] | 7 | *
|
---|
| 8 | * This file is part of VirtualBox Open Source Edition (OSE), as
|
---|
| 9 | * available from http://www.virtualbox.org. This file is free software;
|
---|
| 10 | * you can redistribute it and/or modify it under the terms of the GNU
|
---|
[5999] | 11 | * General Public License (GPL) as published by the Free Software
|
---|
| 12 | * Foundation, in version 2 as it comes in the "COPYING" file of the
|
---|
| 13 | * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
|
---|
| 14 | * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
|
---|
| 15 | *
|
---|
| 16 | * The contents of this file may alternatively be used under the terms
|
---|
| 17 | * of the Common Development and Distribution License Version 1.0
|
---|
| 18 | * (CDDL) only, as it comes in the "COPYING.CDDL" file of the
|
---|
| 19 | * VirtualBox OSE distribution, in which case the provisions of the
|
---|
| 20 | * CDDL are applicable instead of those of the GPL.
|
---|
| 21 | *
|
---|
| 22 | * You may elect to license modified versions of this file under the
|
---|
| 23 | * terms and conditions of either the GPL or the CDDL or both.
|
---|
[8155] | 24 | *
|
---|
| 25 | * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
|
---|
| 26 | * Clara, CA 95054 USA or visit http://www.sun.com if you need
|
---|
| 27 | * additional information or have any questions.
|
---|
[1] | 28 | */
|
---|
| 29 |
|
---|
[3630] | 30 | #ifndef ___iprt_file_h
|
---|
| 31 | #define ___iprt_file_h
|
---|
[1] | 32 |
|
---|
| 33 | #include <iprt/cdefs.h>
|
---|
| 34 | #include <iprt/types.h>
|
---|
| 35 | #ifdef IN_RING3
|
---|
| 36 | # include <iprt/fs.h>
|
---|
| 37 | #endif
|
---|
| 38 |
|
---|
| 39 | /** @todo rename this file to iprt/file.h */
|
---|
| 40 |
|
---|
| 41 | __BEGIN_DECLS
|
---|
| 42 |
|
---|
| 43 | /** @defgroup grp_rt_fileio RTFile - File I/O
|
---|
| 44 | * @ingroup grp_rt
|
---|
| 45 | * @{
|
---|
| 46 | */
|
---|
| 47 |
|
---|
| 48 | /** Platform specific text line break.
|
---|
| 49 | * @deprecated Use text I/O streams and '\\n'. See iprt/stream.h. */
|
---|
[3636] | 50 | #if defined(RT_OS_OS2) || defined(RT_OS_WINDOWS)
|
---|
[1] | 51 | # define RTFILE_LINEFEED "\r\n"
|
---|
| 52 | #else
|
---|
| 53 | # define RTFILE_LINEFEED "\n"
|
---|
| 54 | #endif
|
---|
| 55 |
|
---|
| 56 |
|
---|
| 57 | #ifdef IN_RING3
|
---|
| 58 |
|
---|
| 59 | /** @name Open flags
|
---|
| 60 | * @{ */
|
---|
| 61 | /** Open the file with read access. */
|
---|
| 62 | #define RTFILE_O_READ 0x00000001
|
---|
| 63 | /** Open the file with write access. */
|
---|
| 64 | #define RTFILE_O_WRITE 0x00000002
|
---|
| 65 | /** Open the file with read & write access. */
|
---|
| 66 | #define RTFILE_O_READWRITE 0x00000003
|
---|
| 67 | /** The file access mask.
|
---|
| 68 | * @remark The value 0 is invalid. */
|
---|
| 69 | #define RTFILE_O_ACCESS_MASK 0x00000003
|
---|
| 70 |
|
---|
| 71 | /** Sharing mode: deny none (the default mode). */
|
---|
| 72 | #define RTFILE_O_DENY_NONE 0x00000000
|
---|
| 73 | /** Sharing mode: deny read. */
|
---|
| 74 | #define RTFILE_O_DENY_READ 0x00000010
|
---|
| 75 | /** Sharing mode: deny write. */
|
---|
| 76 | #define RTFILE_O_DENY_WRITE 0x00000020
|
---|
| 77 | /** Sharing mode: deny read and write. */
|
---|
| 78 | #define RTFILE_O_DENY_READWRITE 0x00000030
|
---|
| 79 | /** Sharing mode: deny all. */
|
---|
| 80 | #define RTFILE_O_DENY_ALL RTFILE_O_DENY_READWRITE
|
---|
| 81 | /** Sharing mode: do NOT deny delete (NT).
|
---|
| 82 | * @remark This might not be implemented on all platforms,
|
---|
| 83 | * and will be defaulted & ignored on those.
|
---|
| 84 | */
|
---|
| 85 | #define RTFILE_O_DENY_NOT_DELETE 0x00000040
|
---|
| 86 | /** Sharing mode mask. */
|
---|
| 87 | #define RTFILE_O_DENY_MASK 0x00000070
|
---|
| 88 |
|
---|
| 89 | /** Action: Open an existing file (the default action). */
|
---|
| 90 | #define RTFILE_O_OPEN 0x00000000
|
---|
| 91 | /** Action: Create a new file or open an existing one. */
|
---|
| 92 | #define RTFILE_O_OPEN_CREATE 0x00000100
|
---|
| 93 | /** Action: Create a new a file. */
|
---|
| 94 | #define RTFILE_O_CREATE 0x00000200
|
---|
| 95 | /** Action: Create a new file or replace an existing one. */
|
---|
| 96 | #define RTFILE_O_CREATE_REPLACE 0x00000300
|
---|
| 97 | /** Action mask. */
|
---|
| 98 | #define RTFILE_O_ACTION_MASK 0x00000300
|
---|
| 99 |
|
---|
[6992] | 100 | /** Turns off indexing of files on Windows hosts, *CREATE* only.
|
---|
[6984] | 101 | * @remark This might not be implemented on all platforms,
|
---|
| 102 | * and will be ignored on those.
|
---|
| 103 | */
|
---|
| 104 | #define RTFILE_O_NOT_CONTENT_INDEXED 0x00000800
|
---|
[1] | 105 | /** Truncate the file.
|
---|
| 106 | * @remark This will not truncate files opened for read-only.
|
---|
| 107 | * @remark The trunction doesn't have to be atomically, so anyone
|
---|
| 108 | * else opening the file may be racing us. The caller is
|
---|
| 109 | * responsible for not causing this race. */
|
---|
| 110 | #define RTFILE_O_TRUNCATE 0x00001000
|
---|
| 111 | /** Make the handle inheritable on RTProcessCreate(/exec). */
|
---|
| 112 | #define RTFILE_O_INHERIT 0x00002000
|
---|
| 113 | /** Open file in non-blocking mode - non-portable.
|
---|
| 114 | * @remark This flag may not be supported on all platforms, in which
|
---|
| 115 | * case it's considered an invalid parameter.
|
---|
| 116 | */
|
---|
| 117 | #define RTFILE_O_NON_BLOCK 0x00004000
|
---|
| 118 | /** Write through directly to disk. Workaround to avoid iSCSI
|
---|
| 119 | * initiator deadlocks on Windows hosts.
|
---|
| 120 | * @remark This might not be implemented on all platforms,
|
---|
| 121 | * and will be ignored on those.
|
---|
| 122 | */
|
---|
| 123 | #define RTFILE_O_WRITE_THROUGH 0x00008000
|
---|
| 124 | /** Mask of all valid flags.
|
---|
| 125 | * @remark This doesn't validate the access mode properly.
|
---|
| 126 | */
|
---|
[6984] | 127 | #define RTFILE_O_VALID_MASK 0x0000FB73
|
---|
[1] | 128 |
|
---|
| 129 | /** @} */
|
---|
| 130 |
|
---|
| 131 |
|
---|
| 132 | /**
|
---|
| 133 | * Force the use of open flags for all files opened after the setting is
|
---|
| 134 | * changed. The caller is responsible for not causing races with RTFileOpen().
|
---|
| 135 | *
|
---|
| 136 | * @returns iprt status code.
|
---|
| 137 | * @param fOpenForAccess Access mode to which the set/mask settings apply.
|
---|
| 138 | * @param fSet Open flags to be forced set.
|
---|
| 139 | * @param fMask Open flags to be masked out.
|
---|
| 140 | */
|
---|
| 141 | RTR3DECL(int) RTFileSetForceFlags(unsigned fOpenForAccess, unsigned fSet, unsigned fMask);
|
---|
| 142 |
|
---|
| 143 | /**
|
---|
| 144 | * Open a file.
|
---|
| 145 | *
|
---|
| 146 | * @returns iprt status code.
|
---|
| 147 | * @param pFile Where to store the handle to the opened file.
|
---|
| 148 | * @param pszFilename Path to the file which is to be opened. (UTF-8)
|
---|
| 149 | * @param fOpen Open flags, i.e a combination of the RTFILE_O_* defines.
|
---|
| 150 | */
|
---|
| 151 | RTR3DECL(int) RTFileOpen(PRTFILE pFile, const char *pszFilename, unsigned fOpen);
|
---|
| 152 |
|
---|
| 153 | /**
|
---|
| 154 | * Close a file opened by RTFileOpen().
|
---|
| 155 | *
|
---|
| 156 | * @returns iprt status code.
|
---|
| 157 | * @param File The file handle to close.
|
---|
| 158 | */
|
---|
| 159 | RTR3DECL(int) RTFileClose(RTFILE File);
|
---|
| 160 |
|
---|
| 161 | /**
|
---|
| 162 | * Delete a file.
|
---|
| 163 | *
|
---|
| 164 | * @returns iprt status code.
|
---|
| 165 | * @param pszFilename Path to the file which is to be deleted. (UTF-8)
|
---|
| 166 | * @todo This is a RTPath api!
|
---|
| 167 | */
|
---|
| 168 | RTR3DECL(int) RTFileDelete(const char *pszFilename);
|
---|
| 169 |
|
---|
| 170 | /** @name Seek flags.
|
---|
| 171 | * @{ */
|
---|
| 172 | /** Seek from the start of the file. */
|
---|
| 173 | #define RTFILE_SEEK_BEGIN 0x00
|
---|
| 174 | /** Seek from the current file position. */
|
---|
| 175 | #define RTFILE_SEEK_CURRENT 0x01
|
---|
| 176 | /** Seek from the end of the file. */
|
---|
| 177 | #define RTFILE_SEEK_END 0x02
|
---|
| 178 | /** @internal */
|
---|
| 179 | #define RTFILE_SEEK_FIRST RTFILE_SEEK_BEGIN
|
---|
| 180 | /** @internal */
|
---|
| 181 | #define RTFILE_SEEK_LAST RTFILE_SEEK_END
|
---|
| 182 | /** @} */
|
---|
| 183 |
|
---|
| 184 |
|
---|
| 185 | /**
|
---|
| 186 | * Changes the read & write position in a file.
|
---|
| 187 | *
|
---|
| 188 | * @returns iprt status code.
|
---|
| 189 | * @param File Handle to the file.
|
---|
| 190 | * @param offSeek Offset to seek.
|
---|
| 191 | * @param uMethod Seek method, i.e. one of the RTFILE_SEEK_* defines.
|
---|
| 192 | * @param poffActual Where to store the new file position.
|
---|
| 193 | * NULL is allowed.
|
---|
| 194 | */
|
---|
| 195 | RTR3DECL(int) RTFileSeek(RTFILE File, int64_t offSeek, unsigned uMethod, uint64_t *poffActual);
|
---|
| 196 |
|
---|
| 197 | /**
|
---|
| 198 | * Read bytes from a file.
|
---|
| 199 | *
|
---|
| 200 | * @returns iprt status code.
|
---|
| 201 | * @param File Handle to the file.
|
---|
| 202 | * @param pvBuf Where to put the bytes we read.
|
---|
| 203 | * @param cbToRead How much to read.
|
---|
| 204 | * @param *pcbRead How much we actually read .
|
---|
| 205 | * If NULL an error will be returned for a partial read.
|
---|
| 206 | */
|
---|
[4372] | 207 | RTR3DECL(int) RTFileRead(RTFILE File, void *pvBuf, size_t cbToRead, size_t *pcbRead);
|
---|
[1] | 208 |
|
---|
| 209 | /**
|
---|
| 210 | * Read bytes from a file at a given offset.
|
---|
| 211 | * This function may modify the file position.
|
---|
| 212 | *
|
---|
| 213 | * @returns iprt status code.
|
---|
| 214 | * @param File Handle to the file.
|
---|
| 215 | * @param off Where to read.
|
---|
| 216 | * @param pvBuf Where to put the bytes we read.
|
---|
| 217 | * @param cbToRead How much to read.
|
---|
| 218 | * @param *pcbRead How much we actually read .
|
---|
| 219 | * If NULL an error will be returned for a partial read.
|
---|
| 220 | */
|
---|
[4372] | 221 | RTR3DECL(int) RTFileReadAt(RTFILE File, RTFOFF off, void *pvBuf, size_t cbToRead, size_t *pcbRead);
|
---|
[1] | 222 |
|
---|
| 223 | /**
|
---|
| 224 | * Write bytes to a file.
|
---|
| 225 | *
|
---|
| 226 | * @returns iprt status code.
|
---|
| 227 | * @param File Handle to the file.
|
---|
| 228 | * @param pvBuf What to write.
|
---|
| 229 | * @param cbToWrite How much to write.
|
---|
| 230 | * @param *pcbWritten How much we actually wrote.
|
---|
| 231 | * If NULL an error will be returned for a partial write.
|
---|
| 232 | */
|
---|
[4372] | 233 | RTR3DECL(int) RTFileWrite(RTFILE File, const void *pvBuf, size_t cbToWrite, size_t *pcbWritten);
|
---|
[1] | 234 |
|
---|
| 235 | /**
|
---|
| 236 | * Write bytes to a file at a given offset.
|
---|
| 237 | * This function may modify the file position.
|
---|
| 238 | *
|
---|
| 239 | * @returns iprt status code.
|
---|
| 240 | * @param File Handle to the file.
|
---|
| 241 | * @param off Where to write.
|
---|
| 242 | * @param pvBuf What to write.
|
---|
| 243 | * @param cbToWrite How much to write.
|
---|
| 244 | * @param *pcbWritten How much we actually wrote.
|
---|
| 245 | * If NULL an error will be returned for a partial write.
|
---|
| 246 | */
|
---|
[4372] | 247 | RTR3DECL(int) RTFileWriteAt(RTFILE File, RTFOFF off, const void *pvBuf, size_t cbToWrite, size_t *pcbWritten);
|
---|
[1] | 248 |
|
---|
| 249 | /**
|
---|
| 250 | * Flushes the buffers for the specified file.
|
---|
| 251 | *
|
---|
| 252 | * @returns iprt status code.
|
---|
| 253 | * @param File Handle to the file.
|
---|
| 254 | */
|
---|
| 255 | RTR3DECL(int) RTFileFlush(RTFILE File);
|
---|
| 256 |
|
---|
| 257 | /**
|
---|
| 258 | * Set the size of the file.
|
---|
| 259 | *
|
---|
| 260 | * @returns iprt status code.
|
---|
| 261 | * @param File Handle to the file.
|
---|
| 262 | * @param cbSize The new file size.
|
---|
| 263 | */
|
---|
| 264 | RTR3DECL(int) RTFileSetSize(RTFILE File, uint64_t cbSize);
|
---|
| 265 |
|
---|
| 266 | /**
|
---|
| 267 | * Query the size of the file.
|
---|
| 268 | *
|
---|
| 269 | * @returns iprt status code.
|
---|
| 270 | * @param File Handle to the file.
|
---|
| 271 | * @param pcbSize Where to store the filesize.
|
---|
| 272 | */
|
---|
| 273 | RTR3DECL(int) RTFileGetSize(RTFILE File, uint64_t *pcbSize);
|
---|
| 274 |
|
---|
| 275 | /**
|
---|
[6992] | 276 | * Determine the maximum file size.
|
---|
| 277 | *
|
---|
| 278 | * @returns The max size of the file.
|
---|
[6429] | 279 | * -1 on failure, the file position is undefined.
|
---|
[6992] | 280 | * @param File Handle to the file.
|
---|
| 281 | * @see RTFileGetMaxSizeEx.
|
---|
[6421] | 282 | */
|
---|
[6429] | 283 | RTR3DECL(RTFOFF) RTFileGetMaxSize(RTFILE File);
|
---|
[6421] | 284 |
|
---|
| 285 | /**
|
---|
[6992] | 286 | * Determine the maximum file size.
|
---|
| 287 | *
|
---|
[6429] | 288 | * @returns IPRT status code.
|
---|
[6992] | 289 | * @param File Handle to the file.
|
---|
| 290 | * @param pcbMax Where to store the max file size.
|
---|
[6429] | 291 | * @see RTFileGetMaxSize.
|
---|
| 292 | */
|
---|
| 293 | RTR3DECL(int) RTFileGetMaxSizeEx(RTFILE File, PRTFOFF pcbMax);
|
---|
| 294 |
|
---|
| 295 | /**
|
---|
[6992] | 296 | * Determine the maximum file size depending on the file system the file is stored on.
|
---|
| 297 | *
|
---|
| 298 | * @returns The max size of the file.
|
---|
[6429] | 299 | * -1 on failure.
|
---|
[6992] | 300 | * @param File Handle to the file.
|
---|
[6429] | 301 | */
|
---|
| 302 | RTR3DECL(RTFOFF) RTFileGetMaxSize(RTFILE File);
|
---|
| 303 |
|
---|
| 304 | /**
|
---|
[1] | 305 | * Gets the current file position.
|
---|
| 306 | *
|
---|
| 307 | * @returns File offset.
|
---|
| 308 | * @returns ~0UUL on failure.
|
---|
| 309 | * @param File Handle to the file.
|
---|
| 310 | */
|
---|
| 311 | RTDECL(uint64_t) RTFileTell(RTFILE File);
|
---|
| 312 |
|
---|
| 313 | /**
|
---|
| 314 | * Checks if the supplied handle is valid.
|
---|
| 315 | *
|
---|
| 316 | * @returns true if valid.
|
---|
| 317 | * @returns false if invalid.
|
---|
| 318 | * @param File The file handle
|
---|
| 319 | */
|
---|
| 320 | RTR3DECL(bool) RTFileIsValid(RTFILE File);
|
---|
| 321 |
|
---|
| 322 | /**
|
---|
| 323 | * Copies a file.
|
---|
| 324 | *
|
---|
| 325 | * @returns VERR_ALREADY_EXISTS if the destination file exists.
|
---|
| 326 | * @returns VBox Status code.
|
---|
| 327 | *
|
---|
| 328 | * @param pszSrc The path to the source file.
|
---|
| 329 | * @param pszDst The path to the destination file.
|
---|
| 330 | * This file will be created.
|
---|
| 331 | */
|
---|
| 332 | RTDECL(int) RTFileCopy(const char *pszSrc, const char *pszDst);
|
---|
| 333 |
|
---|
| 334 | /**
|
---|
| 335 | * Copies a file given the handles to both files.
|
---|
| 336 | *
|
---|
| 337 | * @returns VBox Status code.
|
---|
| 338 | *
|
---|
| 339 | * @param FileSrc The source file. The file position is unaltered.
|
---|
| 340 | * @param FileDst The destination file.
|
---|
| 341 | * On successful returns the file position is at the end of the file.
|
---|
| 342 | * On failures the file position and size is undefined.
|
---|
| 343 | */
|
---|
| 344 | RTDECL(int) RTFileCopyByHandles(RTFILE FileSrc, RTFILE FileDst);
|
---|
| 345 |
|
---|
[7340] | 346 | /** Flags for RTFileCopyEx().
|
---|
| 347 | * @{ */
|
---|
| 348 | /** Do not use RTFILE_O_DENY_WRITE on the source file to allow for copying files opened for writing. */
|
---|
[7370] | 349 | #define RTFILECOPY_FLAGS_NO_SRC_DENY_WRITE RT_BIT(0)
|
---|
| 350 | /** Do not use RTFILE_O_DENY_WRITE on the target file. */
|
---|
| 351 | #define RTFILECOPY_FLAGS_NO_DST_DENY_WRITE RT_BIT(1)
|
---|
[7371] | 352 | /** Do not use RTFILE_O_DENY_WRITE on either of the two files. */
|
---|
[7370] | 353 | #define RTFILECOPY_FLAGS_NO_DENY_WRITE ( RTFILECOPY_FLAGS_NO_SRC_DENY_WRITE | RTFILECOPY_FLAGS_NO_DST_DENY_WRITE )
|
---|
| 354 | /** */
|
---|
| 355 | #define RTFILECOPY_FLAGS_MASK UINT32_C(0x00000003)
|
---|
[7340] | 356 | /** @} */
|
---|
| 357 |
|
---|
[1] | 358 | /**
|
---|
| 359 | * Copies a file.
|
---|
| 360 | *
|
---|
| 361 | * @returns VERR_ALREADY_EXISTS if the destination file exists.
|
---|
| 362 | * @returns VBox Status code.
|
---|
| 363 | *
|
---|
| 364 | * @param pszSrc The path to the source file.
|
---|
| 365 | * @param pszDst The path to the destination file.
|
---|
| 366 | * This file will be created.
|
---|
[7340] | 367 | * @param fFlags Flags (RTFILECOPY_*).
|
---|
[1] | 368 | * @param pfnProgress Pointer to callback function for reporting progress.
|
---|
| 369 | * @param pvUser User argument to pass to pfnProgress along with the completion precentage.
|
---|
| 370 | */
|
---|
[7340] | 371 | RTDECL(int) RTFileCopyEx(const char *pszSrc, const char *pszDst, uint32_t fFlags, PFNRTPROGRESS pfnProgress, void *pvUser);
|
---|
[1] | 372 |
|
---|
| 373 | /**
|
---|
| 374 | * Copies a file given the handles to both files and
|
---|
| 375 | * provide progress callbacks.
|
---|
| 376 | *
|
---|
| 377 | * @returns IPRT status code.
|
---|
| 378 | *
|
---|
| 379 | * @param FileSrc The source file. The file position is unaltered.
|
---|
| 380 | * @param FileDst The destination file.
|
---|
| 381 | * On successful returns the file position is at the end of the file.
|
---|
| 382 | * On failures the file position and size is undefined.
|
---|
| 383 | * @param pfnProgress Pointer to callback function for reporting progress.
|
---|
| 384 | * @param pvUser User argument to pass to pfnProgress along with the completion precentage.
|
---|
| 385 | */
|
---|
| 386 | RTDECL(int) RTFileCopyByHandlesEx(RTFILE FileSrc, RTFILE FileDst, PFNRTPROGRESS pfnProgress, void *pvUser);
|
---|
| 387 |
|
---|
| 388 | /**
|
---|
| 389 | * Renames a file.
|
---|
| 390 | *
|
---|
| 391 | * Identical to RTPathRename except that it will ensure that the source is not a directory.
|
---|
| 392 | *
|
---|
| 393 | * @returns IPRT status code.
|
---|
| 394 | * @returns VERR_ALREADY_EXISTS if the destination file exists.
|
---|
| 395 | *
|
---|
| 396 | * @param pszSrc The path to the source file.
|
---|
| 397 | * @param pszDst The path to the destination file.
|
---|
| 398 | * This file will be created.
|
---|
| 399 | * @param fRename See RTPathRename.
|
---|
| 400 | */
|
---|
| 401 | RTDECL(int) RTFileRename(const char *pszSrc, const char *pszDst, unsigned fRename);
|
---|
| 402 |
|
---|
| 403 |
|
---|
| 404 | /** @name RTFileMove flags (bit masks).
|
---|
| 405 | * @{ */
|
---|
| 406 | /** Replace destination file if present. */
|
---|
| 407 | #define RTFILEMOVE_FLAGS_REPLACE 0x1
|
---|
| 408 | /** @} */
|
---|
| 409 |
|
---|
| 410 | /**
|
---|
| 411 | * Moves a file.
|
---|
| 412 | *
|
---|
| 413 | * RTFileMove differs from RTFileRename in that it works across volumes.
|
---|
| 414 | *
|
---|
| 415 | * @returns IPRT status code.
|
---|
| 416 | * @returns VERR_ALREADY_EXISTS if the destination file exists.
|
---|
| 417 | *
|
---|
| 418 | * @param pszSrc The path to the source file.
|
---|
| 419 | * @param pszDst The path to the destination file.
|
---|
| 420 | * This file will be created.
|
---|
| 421 | * @param fMove A combination of the RTFILEMOVE_* flags.
|
---|
| 422 | */
|
---|
| 423 | RTDECL(int) RTFileMove(const char *pszSrc, const char *pszDst, unsigned fMove);
|
---|
| 424 |
|
---|
| 425 |
|
---|
| 426 | /** @page pg_rt_filelock RT File locking API description
|
---|
| 427 | *
|
---|
| 428 | * File locking general rules:
|
---|
| 429 | *
|
---|
| 430 | * Region to lock or unlock can be located beyond the end of file, this can be used for
|
---|
| 431 | * growing files.
|
---|
| 432 | * Read (or Shared) locks can be acquired held by an unlimited number of processes at the
|
---|
| 433 | * same time, but a Write (or Exclusive) lock can only be acquired by one process, and
|
---|
| 434 | * cannot coexist with a Shared lock. To acquire a Read lock, a process must wait until
|
---|
| 435 | * there are no processes holding any Write locks. To acquire a Write lock, a process must
|
---|
| 436 | * wait until there are no processes holding either kind of lock.
|
---|
| 437 | * By default, RTFileLock and RTFileChangeLock calls returns error immediately if the lock
|
---|
| 438 | * can't be acquired due to conflict with other locks, however they can be called in wait mode.
|
---|
| 439 | *
|
---|
| 440 | * Differences in implementation:
|
---|
| 441 | *
|
---|
| 442 | * Win32, OS/2: Locking is mandatory, since locks are enforced by the operating system.
|
---|
| 443 | * I.e. when file region is locked in Read mode, any write in it will fail; in case of Write
|
---|
| 444 | * lock - region can be readed and writed only by lock's owner.
|
---|
| 445 | *
|
---|
| 446 | * Win32: File size change (RTFileSetSize) is not controlled by locking at all (!) in the
|
---|
| 447 | * operation system. Also see comments to RTFileChangeLock API call.
|
---|
| 448 | *
|
---|
| 449 | * Linux/Posix: By default locks in Unixes are advisory. This means that cooperating processes
|
---|
| 450 | * may use locks to coordonate access to a file between themselves, but programs are also free
|
---|
| 451 | * to ignore locks and access the file in any way they choose to.
|
---|
| 452 | *
|
---|
| 453 | * Additional reading:
|
---|
| 454 | * http://en.wikipedia.org/wiki/File_locking
|
---|
| 455 | * http://unixhelp.ed.ac.uk/CGI/man-cgi?fcntl+2
|
---|
| 456 | * http://msdn.microsoft.com/library/default.asp?url=/library/en-us/fileio/fs/lockfileex.asp
|
---|
| 457 | */
|
---|
| 458 |
|
---|
| 459 | /** @name Lock flags (bit masks).
|
---|
| 460 | * @{ */
|
---|
| 461 | /** Read access, can be shared with others. */
|
---|
| 462 | #define RTFILE_LOCK_READ 0x00
|
---|
| 463 | /** Write access, one at a time. */
|
---|
| 464 | #define RTFILE_LOCK_WRITE 0x01
|
---|
| 465 | /** Don't wait for other locks to be released. */
|
---|
| 466 | #define RTFILE_LOCK_IMMEDIATELY 0x00
|
---|
| 467 | /** Wait till conflicting locks have been released. */
|
---|
| 468 | #define RTFILE_LOCK_WAIT 0x02
|
---|
| 469 | /** Valid flags mask */
|
---|
| 470 | #define RTFILE_LOCK_MASK 0x03
|
---|
| 471 | /** @} */
|
---|
| 472 |
|
---|
| 473 |
|
---|
| 474 | /**
|
---|
| 475 | * Locks a region of file for read (shared) or write (exclusive) access.
|
---|
| 476 | *
|
---|
| 477 | * @returns iprt status code.
|
---|
| 478 | * @returns VERR_FILE_LOCK_VIOLATION if lock can't be acquired.
|
---|
| 479 | * @param File Handle to the file.
|
---|
| 480 | * @param fLock Lock method and flags, see RTFILE_LOCK_* defines.
|
---|
| 481 | * @param offLock Offset of lock start.
|
---|
| 482 | * @param cbLock Length of region to lock, may overlap the end of file.
|
---|
| 483 | */
|
---|
| 484 | RTR3DECL(int) RTFileLock(RTFILE File, unsigned fLock, int64_t offLock, uint64_t cbLock);
|
---|
| 485 |
|
---|
| 486 | /**
|
---|
| 487 | * Changes a lock type from read to write or from write to read.
|
---|
| 488 | * The region to type change must correspond exactly to an existing locked region.
|
---|
| 489 | * If change can't be done due to locking conflict and non-blocking mode is used, error is
|
---|
| 490 | * returned and lock keeps its state (see next warning).
|
---|
| 491 | *
|
---|
| 492 | * WARNING: win32 implementation of this call is not atomic, it transforms to a pair of
|
---|
| 493 | * calls RTFileUnlock and RTFileLock. Potentially the previously acquired lock can be
|
---|
| 494 | * lost, i.e. function is called in non-blocking mode, previous lock is freed, new lock can't
|
---|
| 495 | * be acquired, and old lock (previous state) can't be acquired back too. This situation
|
---|
| 496 | * may occurs _only_ if the other process is acquiring a _write_ lock in blocking mode or
|
---|
| 497 | * in race condition with the current call.
|
---|
| 498 | * In this very bad case special error code VERR_FILE_LOCK_LOST will be returned.
|
---|
| 499 | *
|
---|
| 500 | * @returns iprt status code.
|
---|
| 501 | * @returns VERR_FILE_NOT_LOCKED if region was not locked.
|
---|
| 502 | * @returns VERR_FILE_LOCK_VIOLATION if lock type can't be changed, lock remains its type.
|
---|
| 503 | * @returns VERR_FILE_LOCK_LOST if lock was lost, we haven't this lock anymore :(
|
---|
| 504 | * @param File Handle to the file.
|
---|
| 505 | * @param fLock Lock method and flags, see RTFILE_LOCK_* defines.
|
---|
| 506 | * @param offLock Offset of lock start.
|
---|
| 507 | * @param cbLock Length of region to lock, may overlap the end of file.
|
---|
| 508 | */
|
---|
| 509 | RTR3DECL(int) RTFileChangeLock(RTFILE File, unsigned fLock, int64_t offLock, uint64_t cbLock);
|
---|
| 510 |
|
---|
| 511 | /**
|
---|
| 512 | * Unlocks previously locked region of file.
|
---|
| 513 | * The region to unlock must correspond exactly to an existing locked region.
|
---|
| 514 | *
|
---|
| 515 | * @returns iprt status code.
|
---|
| 516 | * @returns VERR_FILE_NOT_LOCKED if region was not locked.
|
---|
| 517 | * @param File Handle to the file.
|
---|
| 518 | * @param offLock Offset of lock start.
|
---|
| 519 | * @param cbLock Length of region to unlock, may overlap the end of file.
|
---|
| 520 | */
|
---|
| 521 | RTR3DECL(int) RTFileUnlock(RTFILE File, int64_t offLock, uint64_t cbLock);
|
---|
| 522 |
|
---|
| 523 |
|
---|
| 524 | /**
|
---|
| 525 | * Query information about an open file.
|
---|
| 526 | *
|
---|
| 527 | * @returns iprt status code.
|
---|
| 528 | *
|
---|
| 529 | * @param File Handle to the file.
|
---|
| 530 | * @param pObjInfo Object information structure to be filled on successful return.
|
---|
| 531 | * @param enmAdditionalAttribs Which set of additional attributes to request.
|
---|
| 532 | * Use RTFSOBJATTRADD_NOTHING if this doesn't matter.
|
---|
| 533 | */
|
---|
| 534 | RTR3DECL(int) RTFileQueryInfo(RTFILE File, PRTFSOBJINFO pObjInfo, RTFSOBJATTRADD enmAdditionalAttribs);
|
---|
| 535 |
|
---|
| 536 | /**
|
---|
| 537 | * Changes one or more of the timestamps associated of file system object.
|
---|
| 538 | *
|
---|
| 539 | * @returns iprt status code.
|
---|
| 540 | * @returns VERR_NOT_SUPPORTED is returned if the operation isn't supported by the OS.
|
---|
| 541 | *
|
---|
| 542 | * @param File Handle to the file.
|
---|
| 543 | * @param pAccessTime Pointer to the new access time. NULL if not to be changed.
|
---|
| 544 | * @param pModificationTime Pointer to the new modifcation time. NULL if not to be changed.
|
---|
| 545 | * @param pChangeTime Pointer to the new change time. NULL if not to be changed.
|
---|
| 546 | * @param pBirthTime Pointer to the new time of birth. NULL if not to be changed.
|
---|
| 547 | *
|
---|
| 548 | * @remark The file system might not implement all these time attributes,
|
---|
| 549 | * the API will ignore the ones which aren't supported.
|
---|
| 550 | *
|
---|
| 551 | * @remark The file system might not implement the time resolution
|
---|
| 552 | * employed by this interface, the time will be chopped to fit.
|
---|
| 553 | *
|
---|
| 554 | * @remark The file system may update the change time even if it's
|
---|
| 555 | * not specified.
|
---|
| 556 | *
|
---|
| 557 | * @remark POSIX can only set Access & Modification and will always set both.
|
---|
| 558 | */
|
---|
| 559 | RTR3DECL(int) RTFileSetTimes(RTFILE File, PCRTTIMESPEC pAccessTime, PCRTTIMESPEC pModificationTime,
|
---|
| 560 | PCRTTIMESPEC pChangeTime, PCRTTIMESPEC pBirthTime);
|
---|
| 561 |
|
---|
| 562 | /**
|
---|
| 563 | * Gets one or more of the timestamps associated of file system object.
|
---|
| 564 | *
|
---|
| 565 | * @returns iprt status code.
|
---|
| 566 | * @param File Handle to the file.
|
---|
| 567 | * @param pAccessTime Where to store the access time. NULL is ok.
|
---|
| 568 | * @param pModificationTime Where to store the modifcation time. NULL is ok.
|
---|
| 569 | * @param pChangeTime Where to store the change time. NULL is ok.
|
---|
| 570 | * @param pBirthTime Where to store the time of birth. NULL is ok.
|
---|
| 571 | *
|
---|
| 572 | * @remark This is wrapper around RTFileQueryInfo() and exists to complement RTFileSetTimes().
|
---|
| 573 | */
|
---|
| 574 | RTR3DECL(int) RTFileGetTimes(RTFILE File, PRTTIMESPEC pAccessTime, PRTTIMESPEC pModificationTime,
|
---|
| 575 | PRTTIMESPEC pChangeTime, PRTTIMESPEC pBirthTime);
|
---|
| 576 |
|
---|
| 577 | /**
|
---|
| 578 | * Changes the mode flags of an open file.
|
---|
| 579 | *
|
---|
| 580 | * The API requires at least one of the mode flag sets (Unix/Dos) to
|
---|
| 581 | * be set. The type is ignored.
|
---|
| 582 | *
|
---|
| 583 | * @returns iprt status code.
|
---|
| 584 | * @param File Handle to the file.
|
---|
| 585 | * @param fMode The new file mode, see @ref grp_rt_fs for details.
|
---|
| 586 | */
|
---|
| 587 | RTR3DECL(int) RTFileSetMode(RTFILE File, RTFMODE fMode);
|
---|
| 588 |
|
---|
| 589 | /**
|
---|
| 590 | * Gets the mode flags of an open file.
|
---|
| 591 | *
|
---|
| 592 | * @returns iprt status code.
|
---|
| 593 | * @param File Handle to the file.
|
---|
| 594 | * @param pfMode Where to store the file mode, see @ref grp_rt_fs for details.
|
---|
| 595 | *
|
---|
| 596 | * @remark This is wrapper around RTFileQueryInfo()
|
---|
| 597 | * and exists to complement RTFileSetMode().
|
---|
| 598 | */
|
---|
| 599 | RTR3DECL(int) RTFileGetMode(RTFILE File, uint32_t *pfMode);
|
---|
| 600 |
|
---|
| 601 | /**
|
---|
| 602 | * Changes the owner and/or group of an open file.
|
---|
| 603 | *
|
---|
| 604 | * @returns iprt status code.
|
---|
| 605 | * @param File Handle to the file.
|
---|
| 606 | * @param uid The new file owner user id. Use -1 (or ~0) to leave this unchanged.
|
---|
| 607 | * @param gid The new group id. Use -1 (or ~0) to leave this unchanged.
|
---|
| 608 | */
|
---|
| 609 | RTR3DECL(int) RTFileSetOwner(RTFILE File, uint32_t uid, uint32_t gid);
|
---|
| 610 |
|
---|
| 611 | /**
|
---|
| 612 | * Gets the owner and/or group of an open file.
|
---|
| 613 | *
|
---|
| 614 | * @returns iprt status code.
|
---|
| 615 | * @param File Handle to the file.
|
---|
| 616 | * @param pUid Where to store the owner user id. NULL is ok.
|
---|
| 617 | * @param pGid Where to store the group id. NULL is ok.
|
---|
| 618 | *
|
---|
| 619 | * @remark This is wrapper around RTFileQueryInfo() and exists to complement RTFileGetOwner().
|
---|
| 620 | */
|
---|
| 621 | RTR3DECL(int) RTFileGetOwner(RTFILE File, uint32_t *pUid, uint32_t *pGid);
|
---|
| 622 |
|
---|
| 623 | /**
|
---|
| 624 | * Executes an IOCTL on a file descriptor.
|
---|
| 625 | *
|
---|
| 626 | * This function is currently only available in L4 and posix environments.
|
---|
| 627 | * Attemps at calling it from code shared with any other platforms will break things!
|
---|
| 628 | *
|
---|
| 629 | * The rational for defining this API is to simplify L4 porting of audio drivers,
|
---|
| 630 | * and to remove some of the assumptions on RTFILE being a file descriptor on
|
---|
| 631 | * platforms using the posix file implementation.
|
---|
| 632 | *
|
---|
| 633 | * @returns iprt status code.
|
---|
| 634 | * @param File Handle to the file.
|
---|
| 635 | * @param iRequest IOCTL request to carry out.
|
---|
| 636 | * @param pvData IOCTL data.
|
---|
| 637 | * @param cbData Size of the IOCTL data.
|
---|
| 638 | * @param piRet Return value of the IOCTL request.
|
---|
| 639 | */
|
---|
| 640 | RTR3DECL(int) RTFileIoCtl(RTFILE File, int iRequest, void *pvData, unsigned cbData, int *piRet);
|
---|
| 641 |
|
---|
| 642 | #endif /* IN_RING3 */
|
---|
| 643 |
|
---|
| 644 | /** @} */
|
---|
| 645 |
|
---|
| 646 | __END_DECLS
|
---|
| 647 |
|
---|
| 648 | #endif
|
---|
| 649 |
|
---|