VirtualBox

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

Last change on this file since 62485 was 62473, checked in by vboxsync, 8 years ago

(C) 2016

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