VirtualBox

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

Last change on this file was 99760, checked in by vboxsync, 12 months ago

IPRT: doxygen tweaks. bugref:10442

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

© 2023 Oracle
ContactPrivacy policyTerms of Use