2
* innotek Portable Runtime - File I/O.
6
* Copyright (C) 2006-2007 innotek GmbH
8
* This file is part of VirtualBox Open Source Edition (OSE), as
9
* available from http://www.virtualbox.org. This file is free software;
10
* you can redistribute it and/or modify it under the terms of the GNU
11
* General Public License as published by the Free Software Foundation,
12
* in version 2 as it comes in the "COPYING" file of the VirtualBox OSE
13
* distribution. VirtualBox OSE is distributed in the hope that it will
14
* be useful, but WITHOUT ANY WARRANTY of any kind.
17
#ifndef ___iprt_file_h
18
#define ___iprt_file_h
20
#include <iprt/cdefs.h>
21
#include <iprt/types.h>
26
/** @todo rename this file to iprt/file.h */
30
/** @defgroup grp_rt_fileio RTFile - File I/O
35
/** Platform specific text line break.
36
* @deprecated Use text I/O streams and '\\n'. See iprt/stream.h. */
37
#if defined(RT_OS_OS2) || defined(RT_OS_WINDOWS)
38
# define RTFILE_LINEFEED "\r\n"
40
# define RTFILE_LINEFEED "\n"
48
/** Open the file with read access. */
49
#define RTFILE_O_READ 0x00000001
50
/** Open the file with write access. */
51
#define RTFILE_O_WRITE 0x00000002
52
/** Open the file with read & write access. */
53
#define RTFILE_O_READWRITE 0x00000003
54
/** The file access mask.
55
* @remark The value 0 is invalid. */
56
#define RTFILE_O_ACCESS_MASK 0x00000003
58
/** Sharing mode: deny none (the default mode). */
59
#define RTFILE_O_DENY_NONE 0x00000000
60
/** Sharing mode: deny read. */
61
#define RTFILE_O_DENY_READ 0x00000010
62
/** Sharing mode: deny write. */
63
#define RTFILE_O_DENY_WRITE 0x00000020
64
/** Sharing mode: deny read and write. */
65
#define RTFILE_O_DENY_READWRITE 0x00000030
66
/** Sharing mode: deny all. */
67
#define RTFILE_O_DENY_ALL RTFILE_O_DENY_READWRITE
68
/** Sharing mode: do NOT deny delete (NT).
69
* @remark This might not be implemented on all platforms,
70
* and will be defaulted & ignored on those.
72
#define RTFILE_O_DENY_NOT_DELETE 0x00000040
73
/** Sharing mode mask. */
74
#define RTFILE_O_DENY_MASK 0x00000070
76
/** Action: Open an existing file (the default action). */
77
#define RTFILE_O_OPEN 0x00000000
78
/** Action: Create a new file or open an existing one. */
79
#define RTFILE_O_OPEN_CREATE 0x00000100
80
/** Action: Create a new a file. */
81
#define RTFILE_O_CREATE 0x00000200
82
/** Action: Create a new file or replace an existing one. */
83
#define RTFILE_O_CREATE_REPLACE 0x00000300
85
#define RTFILE_O_ACTION_MASK 0x00000300
87
/** Truncate the file.
88
* @remark This will not truncate files opened for read-only.
89
* @remark The trunction doesn't have to be atomically, so anyone
90
* else opening the file may be racing us. The caller is
91
* responsible for not causing this race. */
92
#define RTFILE_O_TRUNCATE 0x00001000
93
/** Make the handle inheritable on RTProcessCreate(/exec). */
94
#define RTFILE_O_INHERIT 0x00002000
95
/** Open file in non-blocking mode - non-portable.
96
* @remark This flag may not be supported on all platforms, in which
97
* case it's considered an invalid parameter.
99
#define RTFILE_O_NON_BLOCK 0x00004000
100
/** Write through directly to disk. Workaround to avoid iSCSI
101
* initiator deadlocks on Windows hosts.
102
* @remark This might not be implemented on all platforms,
103
* and will be ignored on those.
105
#define RTFILE_O_WRITE_THROUGH 0x00008000
107
/** Mask of all valid flags.
108
* @remark This doesn't validate the access mode properly.
110
#define RTFILE_O_VALID_MASK 0x0000F333
116
* Force the use of open flags for all files opened after the setting is
117
* changed. The caller is responsible for not causing races with RTFileOpen().
119
* @returns iprt status code.
120
* @param fOpenForAccess Access mode to which the set/mask settings apply.
121
* @param fSet Open flags to be forced set.
122
* @param fMask Open flags to be masked out.
124
RTR3DECL(int) RTFileSetForceFlags(unsigned fOpenForAccess, unsigned fSet, unsigned fMask);
129
* @returns iprt status code.
130
* @param pFile Where to store the handle to the opened file.
131
* @param pszFilename Path to the file which is to be opened. (UTF-8)
132
* @param fOpen Open flags, i.e a combination of the RTFILE_O_* defines.
134
RTR3DECL(int) RTFileOpen(PRTFILE pFile, const char *pszFilename, unsigned fOpen);
137
* Close a file opened by RTFileOpen().
139
* @returns iprt status code.
140
* @param File The file handle to close.
142
RTR3DECL(int) RTFileClose(RTFILE File);
147
* @returns iprt status code.
148
* @param pszFilename Path to the file which is to be deleted. (UTF-8)
149
* @todo This is a RTPath api!
151
RTR3DECL(int) RTFileDelete(const char *pszFilename);
153
/** @name Seek flags.
155
/** Seek from the start of the file. */
156
#define RTFILE_SEEK_BEGIN 0x00
157
/** Seek from the current file position. */
158
#define RTFILE_SEEK_CURRENT 0x01
159
/** Seek from the end of the file. */
160
#define RTFILE_SEEK_END 0x02
162
#define RTFILE_SEEK_FIRST RTFILE_SEEK_BEGIN
164
#define RTFILE_SEEK_LAST RTFILE_SEEK_END
169
* Changes the read & write position in a file.
171
* @returns iprt status code.
172
* @param File Handle to the file.
173
* @param offSeek Offset to seek.
174
* @param uMethod Seek method, i.e. one of the RTFILE_SEEK_* defines.
175
* @param poffActual Where to store the new file position.
178
RTR3DECL(int) RTFileSeek(RTFILE File, int64_t offSeek, unsigned uMethod, uint64_t *poffActual);
181
* Read bytes from a file.
183
* @returns iprt status code.
184
* @param File Handle to the file.
185
* @param pvBuf Where to put the bytes we read.
186
* @param cbToRead How much to read.
187
* @param *pcbRead How much we actually read .
188
* If NULL an error will be returned for a partial read.
190
RTR3DECL(int) RTFileRead(RTFILE File, void *pvBuf, size_t cbToRead, size_t *pcbRead);
193
* Read bytes from a file at a given offset.
194
* This function may modify the file position.
196
* @returns iprt status code.
197
* @param File Handle to the file.
198
* @param off Where to read.
199
* @param pvBuf Where to put the bytes we read.
200
* @param cbToRead How much to read.
201
* @param *pcbRead How much we actually read .
202
* If NULL an error will be returned for a partial read.
204
RTR3DECL(int) RTFileReadAt(RTFILE File, RTFOFF off, void *pvBuf, size_t cbToRead, size_t *pcbRead);
207
* Write bytes to a file.
209
* @returns iprt status code.
210
* @param File Handle to the file.
211
* @param pvBuf What to write.
212
* @param cbToWrite How much to write.
213
* @param *pcbWritten How much we actually wrote.
214
* If NULL an error will be returned for a partial write.
216
RTR3DECL(int) RTFileWrite(RTFILE File, const void *pvBuf, size_t cbToWrite, size_t *pcbWritten);
219
* Write bytes to a file at a given offset.
220
* This function may modify the file position.
222
* @returns iprt status code.
223
* @param File Handle to the file.
224
* @param off Where to write.
225
* @param pvBuf What to write.
226
* @param cbToWrite How much to write.
227
* @param *pcbWritten How much we actually wrote.
228
* If NULL an error will be returned for a partial write.
230
RTR3DECL(int) RTFileWriteAt(RTFILE File, RTFOFF off, const void *pvBuf, size_t cbToWrite, size_t *pcbWritten);
233
* Flushes the buffers for the specified file.
235
* @returns iprt status code.
236
* @param File Handle to the file.
238
RTR3DECL(int) RTFileFlush(RTFILE File);
241
* Set the size of the file.
243
* @returns iprt status code.
244
* @param File Handle to the file.
245
* @param cbSize The new file size.
247
RTR3DECL(int) RTFileSetSize(RTFILE File, uint64_t cbSize);
250
* Query the size of the file.
252
* @returns iprt status code.
253
* @param File Handle to the file.
254
* @param pcbSize Where to store the filesize.
256
RTR3DECL(int) RTFileGetSize(RTFILE File, uint64_t *pcbSize);
259
* Gets the current file position.
261
* @returns File offset.
262
* @returns ~0UUL on failure.
263
* @param File Handle to the file.
265
RTDECL(uint64_t) RTFileTell(RTFILE File);
268
* Checks if the supplied handle is valid.
270
* @returns true if valid.
271
* @returns false if invalid.
272
* @param File The file handle
274
RTR3DECL(bool) RTFileIsValid(RTFILE File);
279
* @returns VERR_ALREADY_EXISTS if the destination file exists.
280
* @returns VBox Status code.
282
* @param pszSrc The path to the source file.
283
* @param pszDst The path to the destination file.
284
* This file will be created.
286
RTDECL(int) RTFileCopy(const char *pszSrc, const char *pszDst);
289
* Copies a file given the handles to both files.
291
* @returns VBox Status code.
293
* @param FileSrc The source file. The file position is unaltered.
294
* @param FileDst The destination file.
295
* On successful returns the file position is at the end of the file.
296
* On failures the file position and size is undefined.
298
RTDECL(int) RTFileCopyByHandles(RTFILE FileSrc, RTFILE FileDst);
303
* @returns VERR_ALREADY_EXISTS if the destination file exists.
304
* @returns VBox Status code.
306
* @param pszSrc The path to the source file.
307
* @param pszDst The path to the destination file.
308
* This file will be created.
309
* @param pfnProgress Pointer to callback function for reporting progress.
310
* @param pvUser User argument to pass to pfnProgress along with the completion precentage.
312
RTDECL(int) RTFileCopyEx(const char *pszSrc, const char *pszDst, PFNRTPROGRESS pfnProgress, void *pvUser);
315
* Copies a file given the handles to both files and
316
* provide progress callbacks.
318
* @returns IPRT status code.
320
* @param FileSrc The source file. The file position is unaltered.
321
* @param FileDst The destination file.
322
* On successful returns the file position is at the end of the file.
323
* On failures the file position and size is undefined.
324
* @param pfnProgress Pointer to callback function for reporting progress.
325
* @param pvUser User argument to pass to pfnProgress along with the completion precentage.
327
RTDECL(int) RTFileCopyByHandlesEx(RTFILE FileSrc, RTFILE FileDst, PFNRTPROGRESS pfnProgress, void *pvUser);
332
* Identical to RTPathRename except that it will ensure that the source is not a directory.
334
* @returns IPRT status code.
335
* @returns VERR_ALREADY_EXISTS if the destination file exists.
337
* @param pszSrc The path to the source file.
338
* @param pszDst The path to the destination file.
339
* This file will be created.
340
* @param fRename See RTPathRename.
342
RTDECL(int) RTFileRename(const char *pszSrc, const char *pszDst, unsigned fRename);
345
/** @name RTFileMove flags (bit masks).
347
/** Replace destination file if present. */
348
#define RTFILEMOVE_FLAGS_REPLACE 0x1
354
* RTFileMove differs from RTFileRename in that it works across volumes.
356
* @returns IPRT status code.
357
* @returns VERR_ALREADY_EXISTS if the destination file exists.
359
* @param pszSrc The path to the source file.
360
* @param pszDst The path to the destination file.
361
* This file will be created.
362
* @param fMove A combination of the RTFILEMOVE_* flags.
364
RTDECL(int) RTFileMove(const char *pszSrc, const char *pszDst, unsigned fMove);
367
/** @page pg_rt_filelock RT File locking API description
369
* File locking general rules:
371
* Region to lock or unlock can be located beyond the end of file, this can be used for
373
* Read (or Shared) locks can be acquired held by an unlimited number of processes at the
374
* same time, but a Write (or Exclusive) lock can only be acquired by one process, and
375
* cannot coexist with a Shared lock. To acquire a Read lock, a process must wait until
376
* there are no processes holding any Write locks. To acquire a Write lock, a process must
377
* wait until there are no processes holding either kind of lock.
378
* By default, RTFileLock and RTFileChangeLock calls returns error immediately if the lock
379
* can't be acquired due to conflict with other locks, however they can be called in wait mode.
381
* Differences in implementation:
383
* Win32, OS/2: Locking is mandatory, since locks are enforced by the operating system.
384
* I.e. when file region is locked in Read mode, any write in it will fail; in case of Write
385
* lock - region can be readed and writed only by lock's owner.
387
* Win32: File size change (RTFileSetSize) is not controlled by locking at all (!) in the
388
* operation system. Also see comments to RTFileChangeLock API call.
390
* Linux/Posix: By default locks in Unixes are advisory. This means that cooperating processes
391
* may use locks to coordonate access to a file between themselves, but programs are also free
392
* to ignore locks and access the file in any way they choose to.
394
* Additional reading:
395
* http://en.wikipedia.org/wiki/File_locking
396
* http://unixhelp.ed.ac.uk/CGI/man-cgi?fcntl+2
397
* http://msdn.microsoft.com/library/default.asp?url=/library/en-us/fileio/fs/lockfileex.asp
400
/** @name Lock flags (bit masks).
402
/** Read access, can be shared with others. */
403
#define RTFILE_LOCK_READ 0x00
404
/** Write access, one at a time. */
405
#define RTFILE_LOCK_WRITE 0x01
406
/** Don't wait for other locks to be released. */
407
#define RTFILE_LOCK_IMMEDIATELY 0x00
408
/** Wait till conflicting locks have been released. */
409
#define RTFILE_LOCK_WAIT 0x02
410
/** Valid flags mask */
411
#define RTFILE_LOCK_MASK 0x03
416
* Locks a region of file for read (shared) or write (exclusive) access.
418
* @returns iprt status code.
419
* @returns VERR_FILE_LOCK_VIOLATION if lock can't be acquired.
420
* @param File Handle to the file.
421
* @param fLock Lock method and flags, see RTFILE_LOCK_* defines.
422
* @param offLock Offset of lock start.
423
* @param cbLock Length of region to lock, may overlap the end of file.
425
RTR3DECL(int) RTFileLock(RTFILE File, unsigned fLock, int64_t offLock, uint64_t cbLock);
428
* Changes a lock type from read to write or from write to read.
429
* The region to type change must correspond exactly to an existing locked region.
430
* If change can't be done due to locking conflict and non-blocking mode is used, error is
431
* returned and lock keeps its state (see next warning).
433
* WARNING: win32 implementation of this call is not atomic, it transforms to a pair of
434
* calls RTFileUnlock and RTFileLock. Potentially the previously acquired lock can be
435
* lost, i.e. function is called in non-blocking mode, previous lock is freed, new lock can't
436
* be acquired, and old lock (previous state) can't be acquired back too. This situation
437
* may occurs _only_ if the other process is acquiring a _write_ lock in blocking mode or
438
* in race condition with the current call.
439
* In this very bad case special error code VERR_FILE_LOCK_LOST will be returned.
441
* @returns iprt status code.
442
* @returns VERR_FILE_NOT_LOCKED if region was not locked.
443
* @returns VERR_FILE_LOCK_VIOLATION if lock type can't be changed, lock remains its type.
444
* @returns VERR_FILE_LOCK_LOST if lock was lost, we haven't this lock anymore :(
445
* @param File Handle to the file.
446
* @param fLock Lock method and flags, see RTFILE_LOCK_* defines.
447
* @param offLock Offset of lock start.
448
* @param cbLock Length of region to lock, may overlap the end of file.
450
RTR3DECL(int) RTFileChangeLock(RTFILE File, unsigned fLock, int64_t offLock, uint64_t cbLock);
453
* Unlocks previously locked region of file.
454
* The region to unlock must correspond exactly to an existing locked region.
456
* @returns iprt status code.
457
* @returns VERR_FILE_NOT_LOCKED if region was not locked.
458
* @param File Handle to the file.
459
* @param offLock Offset of lock start.
460
* @param cbLock Length of region to unlock, may overlap the end of file.
462
RTR3DECL(int) RTFileUnlock(RTFILE File, int64_t offLock, uint64_t cbLock);
466
* Query information about an open file.
468
* @returns iprt status code.
470
* @param File Handle to the file.
471
* @param pObjInfo Object information structure to be filled on successful return.
472
* @param enmAdditionalAttribs Which set of additional attributes to request.
473
* Use RTFSOBJATTRADD_NOTHING if this doesn't matter.
475
RTR3DECL(int) RTFileQueryInfo(RTFILE File, PRTFSOBJINFO pObjInfo, RTFSOBJATTRADD enmAdditionalAttribs);
478
* Changes one or more of the timestamps associated of file system object.
480
* @returns iprt status code.
481
* @returns VERR_NOT_SUPPORTED is returned if the operation isn't supported by the OS.
483
* @param File Handle to the file.
484
* @param pAccessTime Pointer to the new access time. NULL if not to be changed.
485
* @param pModificationTime Pointer to the new modifcation time. NULL if not to be changed.
486
* @param pChangeTime Pointer to the new change time. NULL if not to be changed.
487
* @param pBirthTime Pointer to the new time of birth. NULL if not to be changed.
489
* @remark The file system might not implement all these time attributes,
490
* the API will ignore the ones which aren't supported.
492
* @remark The file system might not implement the time resolution
493
* employed by this interface, the time will be chopped to fit.
495
* @remark The file system may update the change time even if it's
498
* @remark POSIX can only set Access & Modification and will always set both.
500
RTR3DECL(int) RTFileSetTimes(RTFILE File, PCRTTIMESPEC pAccessTime, PCRTTIMESPEC pModificationTime,
501
PCRTTIMESPEC pChangeTime, PCRTTIMESPEC pBirthTime);
504
* Gets one or more of the timestamps associated of file system object.
506
* @returns iprt status code.
507
* @param File Handle to the file.
508
* @param pAccessTime Where to store the access time. NULL is ok.
509
* @param pModificationTime Where to store the modifcation time. NULL is ok.
510
* @param pChangeTime Where to store the change time. NULL is ok.
511
* @param pBirthTime Where to store the time of birth. NULL is ok.
513
* @remark This is wrapper around RTFileQueryInfo() and exists to complement RTFileSetTimes().
515
RTR3DECL(int) RTFileGetTimes(RTFILE File, PRTTIMESPEC pAccessTime, PRTTIMESPEC pModificationTime,
516
PRTTIMESPEC pChangeTime, PRTTIMESPEC pBirthTime);
519
* Changes the mode flags of an open file.
521
* The API requires at least one of the mode flag sets (Unix/Dos) to
522
* be set. The type is ignored.
524
* @returns iprt status code.
525
* @param File Handle to the file.
526
* @param fMode The new file mode, see @ref grp_rt_fs for details.
528
RTR3DECL(int) RTFileSetMode(RTFILE File, RTFMODE fMode);
531
* Gets the mode flags of an open file.
533
* @returns iprt status code.
534
* @param File Handle to the file.
535
* @param pfMode Where to store the file mode, see @ref grp_rt_fs for details.
537
* @remark This is wrapper around RTFileQueryInfo()
538
* and exists to complement RTFileSetMode().
540
RTR3DECL(int) RTFileGetMode(RTFILE File, uint32_t *pfMode);
543
* Changes the owner and/or group of an open file.
545
* @returns iprt status code.
546
* @param File Handle to the file.
547
* @param uid The new file owner user id. Use -1 (or ~0) to leave this unchanged.
548
* @param gid The new group id. Use -1 (or ~0) to leave this unchanged.
550
RTR3DECL(int) RTFileSetOwner(RTFILE File, uint32_t uid, uint32_t gid);
553
* Gets the owner and/or group of an open file.
555
* @returns iprt status code.
556
* @param File Handle to the file.
557
* @param pUid Where to store the owner user id. NULL is ok.
558
* @param pGid Where to store the group id. NULL is ok.
560
* @remark This is wrapper around RTFileQueryInfo() and exists to complement RTFileGetOwner().
562
RTR3DECL(int) RTFileGetOwner(RTFILE File, uint32_t *pUid, uint32_t *pGid);
565
* Executes an IOCTL on a file descriptor.
567
* This function is currently only available in L4 and posix environments.
568
* Attemps at calling it from code shared with any other platforms will break things!
570
* The rational for defining this API is to simplify L4 porting of audio drivers,
571
* and to remove some of the assumptions on RTFILE being a file descriptor on
572
* platforms using the posix file implementation.
574
* @returns iprt status code.
575
* @param File Handle to the file.
576
* @param iRequest IOCTL request to carry out.
577
* @param pvData IOCTL data.
578
* @param cbData Size of the IOCTL data.
579
* @param piRet Return value of the IOCTL request.
581
RTR3DECL(int) RTFileIoCtl(RTFILE File, int iRequest, void *pvData, unsigned cbData, int *piRet);
583
#endif /* IN_RING3 */
added
removed
include/iprt/file.h
