VirtualBox

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

Last change on this file since 92059 was 87590, checked in by vboxsync, 4 years ago

IPRT/RTFileGetMaxSize: Doxygen fix.

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