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