VirtualBox

source: vbox/trunk/include/iprt/file.h@ 4919

Last change on this file since 4919 was 4372, checked in by vboxsync, 17 years ago

Finally corrected the RTFileRead, RTFileReadAt, RTFileWrite and RTFileWriteAt APIs to size_t. This was long overdue.

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 21.2 KB
Line 
1/** @file
2 * innotek Portable Runtime - File I/O.
3 */
4
5/*
6 * Copyright (C) 2006-2007 innotek GmbH
7 *
8 * This file is part of VirtualBox Open Source Edition (OSE), as
9 * available from http://www.virtualbox.org. This file is free software;
10 * you can redistribute it and/or modify it under the terms of the GNU
11 * General Public License 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.
15 */
16
17#ifndef ___iprt_file_h
18#define ___iprt_file_h
19
20#include <iprt/cdefs.h>
21#include <iprt/types.h>
22#ifdef IN_RING3
23# include <iprt/fs.h>
24#endif
25
26/** @todo rename this file to iprt/file.h */
27
28__BEGIN_DECLS
29
30/** @defgroup grp_rt_fileio RTFile - File I/O
31 * @ingroup grp_rt
32 * @{
33 */
34
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"
39#else
40# define RTFILE_LINEFEED "\n"
41#endif
42
43
44#ifdef IN_RING3
45
46/** @name Open flags
47 * @{ */
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
57
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.
71 */
72#define RTFILE_O_DENY_NOT_DELETE 0x00000040
73/** Sharing mode mask. */
74#define RTFILE_O_DENY_MASK 0x00000070
75
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
84/** Action mask. */
85#define RTFILE_O_ACTION_MASK 0x00000300
86
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.
98 */
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.
104 */
105#define RTFILE_O_WRITE_THROUGH 0x00008000
106
107/** Mask of all valid flags.
108 * @remark This doesn't validate the access mode properly.
109 */
110#define RTFILE_O_VALID_MASK 0x0000F333
111
112/** @} */
113
114
115/**
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().
118 *
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.
123 */
124RTR3DECL(int) RTFileSetForceFlags(unsigned fOpenForAccess, unsigned fSet, unsigned fMask);
125
126/**
127 * Open a file.
128 *
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.
133 */
134RTR3DECL(int) RTFileOpen(PRTFILE pFile, const char *pszFilename, unsigned fOpen);
135
136/**
137 * Close a file opened by RTFileOpen().
138 *
139 * @returns iprt status code.
140 * @param File The file handle to close.
141 */
142RTR3DECL(int) RTFileClose(RTFILE File);
143
144/**
145 * Delete a file.
146 *
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!
150 */
151RTR3DECL(int) RTFileDelete(const char *pszFilename);
152
153/** @name Seek flags.
154 * @{ */
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
161/** @internal */
162#define RTFILE_SEEK_FIRST RTFILE_SEEK_BEGIN
163/** @internal */
164#define RTFILE_SEEK_LAST RTFILE_SEEK_END
165/** @} */
166
167
168/**
169 * Changes the read & write position in a file.
170 *
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.
176 * NULL is allowed.
177 */
178RTR3DECL(int) RTFileSeek(RTFILE File, int64_t offSeek, unsigned uMethod, uint64_t *poffActual);
179
180/**
181 * Read bytes from a file.
182 *
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.
189 */
190RTR3DECL(int) RTFileRead(RTFILE File, void *pvBuf, size_t cbToRead, size_t *pcbRead);
191
192/**
193 * Read bytes from a file at a given offset.
194 * This function may modify the file position.
195 *
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.
203 */
204RTR3DECL(int) RTFileReadAt(RTFILE File, RTFOFF off, void *pvBuf, size_t cbToRead, size_t *pcbRead);
205
206/**
207 * Write bytes to a file.
208 *
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.
215 */
216RTR3DECL(int) RTFileWrite(RTFILE File, const void *pvBuf, size_t cbToWrite, size_t *pcbWritten);
217
218/**
219 * Write bytes to a file at a given offset.
220 * This function may modify the file position.
221 *
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.
229 */
230RTR3DECL(int) RTFileWriteAt(RTFILE File, RTFOFF off, const void *pvBuf, size_t cbToWrite, size_t *pcbWritten);
231
232/**
233 * Flushes the buffers for the specified file.
234 *
235 * @returns iprt status code.
236 * @param File Handle to the file.
237 */
238RTR3DECL(int) RTFileFlush(RTFILE File);
239
240/**
241 * Set the size of the file.
242 *
243 * @returns iprt status code.
244 * @param File Handle to the file.
245 * @param cbSize The new file size.
246 */
247RTR3DECL(int) RTFileSetSize(RTFILE File, uint64_t cbSize);
248
249/**
250 * Query the size of the file.
251 *
252 * @returns iprt status code.
253 * @param File Handle to the file.
254 * @param pcbSize Where to store the filesize.
255 */
256RTR3DECL(int) RTFileGetSize(RTFILE File, uint64_t *pcbSize);
257
258/**
259 * Gets the current file position.
260 *
261 * @returns File offset.
262 * @returns ~0UUL on failure.
263 * @param File Handle to the file.
264 */
265RTDECL(uint64_t) RTFileTell(RTFILE File);
266
267/**
268 * Checks if the supplied handle is valid.
269 *
270 * @returns true if valid.
271 * @returns false if invalid.
272 * @param File The file handle
273 */
274RTR3DECL(bool) RTFileIsValid(RTFILE File);
275
276/**
277 * Copies a file.
278 *
279 * @returns VERR_ALREADY_EXISTS if the destination file exists.
280 * @returns VBox Status code.
281 *
282 * @param pszSrc The path to the source file.
283 * @param pszDst The path to the destination file.
284 * This file will be created.
285 */
286RTDECL(int) RTFileCopy(const char *pszSrc, const char *pszDst);
287
288/**
289 * Copies a file given the handles to both files.
290 *
291 * @returns VBox Status code.
292 *
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.
297 */
298RTDECL(int) RTFileCopyByHandles(RTFILE FileSrc, RTFILE FileDst);
299
300/**
301 * Copies a file.
302 *
303 * @returns VERR_ALREADY_EXISTS if the destination file exists.
304 * @returns VBox Status code.
305 *
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.
311 */
312RTDECL(int) RTFileCopyEx(const char *pszSrc, const char *pszDst, PFNRTPROGRESS pfnProgress, void *pvUser);
313
314/**
315 * Copies a file given the handles to both files and
316 * provide progress callbacks.
317 *
318 * @returns IPRT status code.
319 *
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.
326 */
327RTDECL(int) RTFileCopyByHandlesEx(RTFILE FileSrc, RTFILE FileDst, PFNRTPROGRESS pfnProgress, void *pvUser);
328
329/**
330 * Renames a file.
331 *
332 * Identical to RTPathRename except that it will ensure that the source is not a directory.
333 *
334 * @returns IPRT status code.
335 * @returns VERR_ALREADY_EXISTS if the destination file exists.
336 *
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.
341 */
342RTDECL(int) RTFileRename(const char *pszSrc, const char *pszDst, unsigned fRename);
343
344
345/** @name RTFileMove flags (bit masks).
346 * @{ */
347/** Replace destination file if present. */
348#define RTFILEMOVE_FLAGS_REPLACE 0x1
349/** @} */
350
351/**
352 * Moves a file.
353 *
354 * RTFileMove differs from RTFileRename in that it works across volumes.
355 *
356 * @returns IPRT status code.
357 * @returns VERR_ALREADY_EXISTS if the destination file exists.
358 *
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.
363 */
364RTDECL(int) RTFileMove(const char *pszSrc, const char *pszDst, unsigned fMove);
365
366
367/** @page pg_rt_filelock RT File locking API description
368 *
369 * File locking general rules:
370 *
371 * Region to lock or unlock can be located beyond the end of file, this can be used for
372 * growing files.
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.
380 *
381 * Differences in implementation:
382 *
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.
386 *
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.
389 *
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.
393 *
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
398 */
399
400/** @name Lock flags (bit masks).
401 * @{ */
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
412/** @} */
413
414
415/**
416 * Locks a region of file for read (shared) or write (exclusive) access.
417 *
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.
424 */
425RTR3DECL(int) RTFileLock(RTFILE File, unsigned fLock, int64_t offLock, uint64_t cbLock);
426
427/**
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).
432 *
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.
440 *
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.
449 */
450RTR3DECL(int) RTFileChangeLock(RTFILE File, unsigned fLock, int64_t offLock, uint64_t cbLock);
451
452/**
453 * Unlocks previously locked region of file.
454 * The region to unlock must correspond exactly to an existing locked region.
455 *
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.
461 */
462RTR3DECL(int) RTFileUnlock(RTFILE File, int64_t offLock, uint64_t cbLock);
463
464
465/**
466 * Query information about an open file.
467 *
468 * @returns iprt status code.
469 *
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.
474 */
475RTR3DECL(int) RTFileQueryInfo(RTFILE File, PRTFSOBJINFO pObjInfo, RTFSOBJATTRADD enmAdditionalAttribs);
476
477/**
478 * Changes one or more of the timestamps associated of file system object.
479 *
480 * @returns iprt status code.
481 * @returns VERR_NOT_SUPPORTED is returned if the operation isn't supported by the OS.
482 *
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.
488 *
489 * @remark The file system might not implement all these time attributes,
490 * the API will ignore the ones which aren't supported.
491 *
492 * @remark The file system might not implement the time resolution
493 * employed by this interface, the time will be chopped to fit.
494 *
495 * @remark The file system may update the change time even if it's
496 * not specified.
497 *
498 * @remark POSIX can only set Access & Modification and will always set both.
499 */
500RTR3DECL(int) RTFileSetTimes(RTFILE File, PCRTTIMESPEC pAccessTime, PCRTTIMESPEC pModificationTime,
501 PCRTTIMESPEC pChangeTime, PCRTTIMESPEC pBirthTime);
502
503/**
504 * Gets one or more of the timestamps associated of file system object.
505 *
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.
512 *
513 * @remark This is wrapper around RTFileQueryInfo() and exists to complement RTFileSetTimes().
514 */
515RTR3DECL(int) RTFileGetTimes(RTFILE File, PRTTIMESPEC pAccessTime, PRTTIMESPEC pModificationTime,
516 PRTTIMESPEC pChangeTime, PRTTIMESPEC pBirthTime);
517
518/**
519 * Changes the mode flags of an open file.
520 *
521 * The API requires at least one of the mode flag sets (Unix/Dos) to
522 * be set. The type is ignored.
523 *
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.
527 */
528RTR3DECL(int) RTFileSetMode(RTFILE File, RTFMODE fMode);
529
530/**
531 * Gets the mode flags of an open file.
532 *
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.
536 *
537 * @remark This is wrapper around RTFileQueryInfo()
538 * and exists to complement RTFileSetMode().
539 */
540RTR3DECL(int) RTFileGetMode(RTFILE File, uint32_t *pfMode);
541
542/**
543 * Changes the owner and/or group of an open file.
544 *
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.
549 */
550RTR3DECL(int) RTFileSetOwner(RTFILE File, uint32_t uid, uint32_t gid);
551
552/**
553 * Gets the owner and/or group of an open file.
554 *
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.
559 *
560 * @remark This is wrapper around RTFileQueryInfo() and exists to complement RTFileGetOwner().
561 */
562RTR3DECL(int) RTFileGetOwner(RTFILE File, uint32_t *pUid, uint32_t *pGid);
563
564/**
565 * Executes an IOCTL on a file descriptor.
566 *
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!
569 *
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.
573 *
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.
580 */
581RTR3DECL(int) RTFileIoCtl(RTFILE File, int iRequest, void *pvData, unsigned cbData, int *piRet);
582
583#endif /* IN_RING3 */
584
585/** @} */
586
587__END_DECLS
588
589#endif
590
Note: See TracBrowser for help on using the repository browser.

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette