VirtualBox

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

Last change on this file was 100908, checked in by vboxsync, 9 months ago

IPRT,Storage,Puel: Changed the pfnRead and pfnWrite VFS methods and the RTVfsIoStrmSgRead, RTVfsIoStrmSgWrite, RTVfsFileSgRead and RTVfsFileSgWrite APIs to advance pSgBuf and respect the incoming position just like RTFileSgRead & RTFileSgWrite.
  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 61.5 KB
Line 
1/** @file
2 * IPRT - Virtual Filesystem.
3 */
4
5/*
6 * Copyright (C) 2010-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_vfslowlevel_h
37#define IPRT_INCLUDED_vfslowlevel_h
38#ifndef RT_WITHOUT_PRAGMA_ONCE
39# pragma once
40#endif
41
42#include <iprt/vfs.h>
43#include <iprt/errcore.h>
44#include <iprt/list.h>
45#include <iprt/param.h>
46
47
48RT_C_DECLS_BEGIN
49
50/** @defgroup grp_rt_vfs_lowlevel RTVfs - Low-level Interface.
51 * @ingroup grp_rt_vfs
52 * @{
53 */
54
55
56/** @name VFS Lock Abstraction
57 * @todo This should be moved somewhere else as it is of general use.
58 * @{ */
59
60/**
61 * VFS lock types.
62 */
63typedef enum RTVFSLOCKTYPE
64{
65 /** Invalid lock type. */
66 RTVFSLOCKTYPE_INVALID = 0,
67 /** Read write semaphore. */
68 RTVFSLOCKTYPE_RW,
69 /** Fast mutex semaphore (critical section in ring-3). */
70 RTVFSLOCKTYPE_FASTMUTEX,
71 /** Full fledged mutex semaphore. */
72 RTVFSLOCKTYPE_MUTEX,
73 /** The end of valid lock types. */
74 RTVFSLOCKTYPE_END,
75 /** The customary 32-bit type hack. */
76 RTVFSLOCKTYPE_32BIT_HACK = 0x7fffffff
77} RTVFSLOCKTYPE;
78
79/** VFS lock handle. */
80typedef struct RTVFSLOCKINTERNAL *RTVFSLOCK;
81/** Pointer to a VFS lock handle. */
82typedef RTVFSLOCK *PRTVFSLOCK;
83/** Nil VFS lock handle. */
84#define NIL_RTVFSLOCK ((RTVFSLOCK)~(uintptr_t)0)
85
86/** Special handle value for creating a new read/write semaphore based lock. */
87#define RTVFSLOCK_CREATE_RW ((RTVFSLOCK)~(uintptr_t)1)
88/** Special handle value for creating a new fast mutex semaphore based lock. */
89#define RTVFSLOCK_CREATE_FASTMUTEX ((RTVFSLOCK)~(uintptr_t)2)
90/** Special handle value for creating a new mutex semaphore based lock. */
91#define RTVFSLOCK_CREATE_MUTEX ((RTVFSLOCK)~(uintptr_t)3)
92
93/**
94 * Retains a reference to the VFS lock handle.
95 *
96 * @returns New reference count on success, UINT32_MAX on failure.
97 * @param hLock The VFS lock handle.
98 */
99RTDECL(uint32_t) RTVfsLockRetain(RTVFSLOCK hLock);
100
101/**
102 * Releases a reference to the VFS lock handle.
103 *
104 * @returns New reference count on success (0 if closed), UINT32_MAX on failure.
105 * @param hLock The VFS lock handle.
106 */
107RTDECL(uint32_t) RTVfsLockRelease(RTVFSLOCK hLock);
108
109/**
110 * Gets the lock type.
111 *
112 * @returns The lock type on success, RTVFSLOCKTYPE_INVALID if the handle is
113 * not valid.
114 * @param hLock The lock handle.
115 */
116RTDECL(RTVFSLOCKTYPE) RTVfsLockGetType(RTVFSLOCK hLock);
117
118
119
120RTDECL(void) RTVfsLockAcquireReadSlow(RTVFSLOCK hLock);
121RTDECL(void) RTVfsLockReleaseReadSlow(RTVFSLOCK hLock);
122RTDECL(void) RTVfsLockAcquireWriteSlow(RTVFSLOCK hLock);
123RTDECL(void) RTVfsLockReleaseWriteSlow(RTVFSLOCK hLock);
124
125/**
126 * Acquire a read lock.
127 *
128 * @param hLock The lock handle, can be NIL.
129 */
130DECLINLINE(void) RTVfsLockAcquireRead(RTVFSLOCK hLock)
131{
132 if (hLock != NIL_RTVFSLOCK)
133 RTVfsLockAcquireReadSlow(hLock);
134}
135
136
137/**
138 * Release a read lock.
139 *
140 * @param hLock The lock handle, can be NIL.
141 */
142DECLINLINE(void) RTVfsLockReleaseRead(RTVFSLOCK hLock)
143{
144 if (hLock != NIL_RTVFSLOCK)
145 RTVfsLockReleaseReadSlow(hLock);
146}
147
148
149/**
150 * Acquire a write lock.
151 *
152 * @param hLock The lock handle, can be NIL.
153 */
154DECLINLINE(void) RTVfsLockAcquireWrite(RTVFSLOCK hLock)
155{
156 if (hLock != NIL_RTVFSLOCK)
157 RTVfsLockAcquireWriteSlow(hLock);
158}
159
160
161/**
162 * Release a write lock.
163 *
164 * @param hLock The lock handle, can be NIL.
165 */
166DECLINLINE(void) RTVfsLockReleaseWrite(RTVFSLOCK hLock)
167{
168 if (hLock != NIL_RTVFSLOCK)
169 RTVfsLockReleaseWriteSlow(hLock);
170}
171
172/** @} */
173
174/**
175 * Info queried via RTVFSOBJOPS::pfnQueryInfoEx, ++.
176 */
177typedef enum RTVFSQIEX
178{
179 /** Invalid zero value. */
180 RTVFSQIEX_INVALID = 0,
181 /** Volume label.
182 * Returns a UTF-8 string. */
183 RTVFSQIEX_VOL_LABEL,
184 /** Alternative volume label, the primary one for ISOs, otherwise treated same
185 * as RTVFSQIEX_VOL_LABEL. */
186 RTVFSQIEX_VOL_LABEL_ALT,
187 /** Volume serial number.
188 * Returns a uint32_t, uint64_t or RTUUID. */
189 RTVFSQIEX_VOL_SERIAL,
190 /** End of valid queries. */
191 RTVFSQIEX_END,
192
193 /** The usual 32-bit hack. */
194 RTVFSQIEX_32BIT_SIZE_HACK = 0x7fffffff
195} RTVFSQIEX;
196
197
198/**
199 * The basis for all virtual file system objects.
200 */
201typedef struct RTVFSOBJOPS
202{
203 /** The structure version (RTVFSOBJOPS_VERSION). */
204 uint32_t uVersion;
205 /** The object type for type introspection. */
206 RTVFSOBJTYPE enmType;
207 /** The name of the operations. */
208 const char *pszName;
209
210 /**
211 * Close the object.
212 *
213 * @returns IPRT status code.
214 * @param pvThis The implementation specific file data.
215 */
216 DECLCALLBACKMEMBER(int, pfnClose,(void *pvThis));
217
218 /**
219 * Get information about the file.
220 *
221 * @returns IPRT status code. See RTVfsObjQueryInfo.
222 * @retval VERR_WRONG_TYPE if file system or file system stream.
223 *
224 * @param pvThis The implementation specific file data.
225 * @param pObjInfo Where to return the object info on success.
226 * @param enmAddAttr Which set of additional attributes to request.
227 * @sa RTVfsObjQueryInfo, RTFileQueryInfo, RTPathQueryInfo
228 */
229 DECLCALLBACKMEMBER(int, pfnQueryInfo,(void *pvThis, PRTFSOBJINFO pObjInfo, RTFSOBJATTRADD enmAddAttr));
230
231 /**
232 * Query arbritray information about the file, volume, or whatever.
233 *
234 * @returns IPRT status code.
235 * @retval VERR_BUFFER_OVERFLOW sets pcbRet.
236 *
237 * @param pvThis The implementation specific file data.
238 * @param enmInfo The information being queried.
239 * @param pvInfo Where to return the info.
240 * @param cbInfo The size of the @a pvInfo buffer.
241 * @param pcbRet The size of the returned data. In case of
242 * VERR_BUFFER_OVERFLOW this will be set to the required
243 * buffer size.
244 */
245 DECLCALLBACKMEMBER(int, pfnQueryInfoEx,(void *pvThis, RTVFSQIEX enmInfo, void *pvInfo, size_t cbInfo, size_t *pcbRet));
246
247 /** Marks the end of the structure (RTVFSOBJOPS_VERSION). */
248 uintptr_t uEndMarker;
249} RTVFSOBJOPS;
250/** Pointer to constant VFS object operations. */
251typedef RTVFSOBJOPS const *PCRTVFSOBJOPS;
252
253/** The RTVFSOBJOPS structure version. */
254#define RTVFSOBJOPS_VERSION RT_MAKE_U32_FROM_U8(0xff,0x1f,2,0)
255
256
257/**
258 * The VFS operations.
259 */
260typedef struct RTVFSOPS
261{
262 /** The basic object operation. */
263 RTVFSOBJOPS Obj;
264 /** The structure version (RTVFSOPS_VERSION). */
265 uint32_t uVersion;
266 /** The virtual file system feature mask. */
267 uint32_t fFeatures;
268
269 /**
270 * Opens the root directory.
271 *
272 * @returns IPRT status code.
273 * @param pvThis The implementation specific data.
274 * @param phVfsDir Where to return the handle to the root directory.
275 */
276 DECLCALLBACKMEMBER(int, pfnOpenRoot,(void *pvThis, PRTVFSDIR phVfsDir));
277
278 /**
279 * Query the status of the given storage range (optional).
280 *
281 * This can be used by the image compaction utilites to evict non-zero blocks
282 * that aren't currently being used by the file system.
283 *
284 * @returns IPRT status code.
285 * @param pvThis The implementation specific data.
286 * @param off Start offset to check.
287 * @param cb Number of bytes to check.
288 * @param pfUsed Where to store whether the given range is in use.
289 */
290 DECLCALLBACKMEMBER(int, pfnQueryRangeState,(void *pvThis, uint64_t off, size_t cb, bool *pfUsed));
291
292 /** @todo There will be more methods here to optimize opening and
293 * querying. */
294
295#if 0
296 /**
297 * Optional entry point for optimizing path traversal within the file system.
298 *
299 * @returns IPRT status code.
300 * @param pvThis The implementation specific data.
301 * @param pszPath The path to resolve.
302 * @param poffPath The current path offset on input, what we've
303 * traversed to on successful return.
304 * @param phVfs??? Return handle to what we've traversed.
305 * @param p??? Return other stuff...
306 */
307 DECLCALLBACKMEMBER(int, pfnTraverse,(void *pvThis, const char *pszPath, size_t *poffPath, PRTVFS??? phVfs?, ???* p???));
308#endif
309
310 /** @todo need rename API */
311
312 /** Marks the end of the structure (RTVFSOPS_VERSION). */
313 uintptr_t uEndMarker;
314} RTVFSOPS;
315/** Pointer to constant VFS operations. */
316typedef RTVFSOPS const *PCRTVFSOPS;
317
318/** The RTVFSOPS structure version. */
319#define RTVFSOPS_VERSION RT_MAKE_U32_FROM_U8(0xff,0x0f,1,0)
320
321/** @name RTVFSOPS::fFeatures
322 * @{ */
323/** The VFS supports attaching other systems. */
324#define RTVFSOPS_FEAT_ATTACH RT_BIT_32(0)
325/** @} */
326
327/**
328 * Creates a new VFS handle.
329 *
330 * @returns IPRT status code
331 * @param pVfsOps The VFS operations.
332 * @param cbInstance The size of the instance data.
333 * @param hVfs The VFS handle to associate this VFS with.
334 * NIL_VFS is ok.
335 * @param hLock Handle to a custom lock to be used with the new
336 * object. The reference is consumed. NIL and
337 * special lock handles are fine.
338 * @param phVfs Where to return the new handle.
339 * @param ppvInstance Where to return the pointer to the instance data
340 * (size is @a cbInstance).
341 */
342RTDECL(int) RTVfsNew(PCRTVFSOPS pVfsOps, size_t cbInstance, RTVFS hVfs, RTVFSLOCK hLock,
343 PRTVFS phVfs, void **ppvInstance);
344
345
346/**
347 * Creates a new VFS base object handle.
348 *
349 * @returns IPRT status code
350 * @param pObjOps The base object operations.
351 * @param cbInstance The size of the instance data.
352 * @param hVfs The VFS handle to associate this base object
353 * with. NIL_VFS is ok.
354 * @param hLock Handle to a custom lock to be used with the new
355 * object. The reference is consumed. NIL and
356 * special lock handles are fine.
357 * @param phVfsObj Where to return the new handle.
358 * @param ppvInstance Where to return the pointer to the instance data
359 * (size is @a cbInstance).
360 */
361RTDECL(int) RTVfsNewBaseObj(PCRTVFSOBJOPS pObjOps, size_t cbInstance, RTVFS hVfs, RTVFSLOCK hLock,
362 PRTVFSOBJ phVfsObj, void **ppvInstance);
363
364
365/**
366 * Gets the private data of a base object.
367 *
368 * @returns Pointer to the private data. NULL if the handle is invalid in some
369 * way.
370 * @param hVfsObj The I/O base object handle.
371 * @param pObjOps The base object operations. This servers as a
372 * sort of password.
373 */
374RTDECL(void *) RTVfsObjToPrivate(RTVFSOBJ hVfsObj, PCRTVFSOBJOPS pObjOps);
375
376/**
377 * Additional operations for setting object attributes.
378 */
379typedef struct RTVFSOBJSETOPS
380{
381 /** The structure version (RTVFSOBJSETOPS_VERSION). */
382 uint32_t uVersion;
383 /** The offset back to the RTVFSOBJOPS structure. */
384 uint32_t offObjOps;
385
386 /**
387 * Set the unix style owner and group.
388 *
389 * @returns IPRT status code.
390 * @param pvThis The implementation specific file data.
391 * @param fMode The new mode bits.
392 * @param fMask The mask indicating which bits we are
393 * changing.
394 * @note Optional, failing with VERR_WRITE_PROTECT if NULL.
395 * @sa RTFileSetMode
396 */
397 DECLCALLBACKMEMBER(int, pfnSetMode,(void *pvThis, RTFMODE fMode, RTFMODE fMask));
398
399 /**
400 * Set the timestamps associated with the object.
401 *
402 * @returns IPRT status code.
403 * @param pvThis The implementation specific file data.
404 * @param pAccessTime Pointer to the new access time. NULL if not
405 * to be changed.
406 * @param pModificationTime Pointer to the new modifcation time. NULL if
407 * not to be changed.
408 * @param pChangeTime Pointer to the new change time. NULL if not
409 * to be changed.
410 * @param pBirthTime Pointer to the new time of birth. NULL if
411 * not to be changed.
412 * @remarks See RTFileSetTimes for restrictions and behavior imposed by the
413 * host OS or underlying VFS provider.
414 * @note Optional, failing with VERR_WRITE_PROTECT if NULL.
415 * @sa RTFileSetTimes
416 */
417 DECLCALLBACKMEMBER(int, pfnSetTimes,(void *pvThis, PCRTTIMESPEC pAccessTime, PCRTTIMESPEC pModificationTime,
418 PCRTTIMESPEC pChangeTime, PCRTTIMESPEC pBirthTime));
419
420 /**
421 * Set the unix style owner and group.
422 *
423 * @returns IPRT status code.
424 * @param pvThis The implementation specific file data.
425 * @param uid The user ID of the new owner. NIL_RTUID if
426 * unchanged.
427 * @param gid The group ID of the new owner group. NIL_RTGID if
428 * unchanged.
429 * @note Optional, failing with VERR_WRITE_PROTECT if NULL.
430 * @sa RTFileSetOwner
431 */
432 DECLCALLBACKMEMBER(int, pfnSetOwner,(void *pvThis, RTUID uid, RTGID gid));
433
434 /** Marks the end of the structure (RTVFSOBJSETOPS_VERSION). */
435 uintptr_t uEndMarker;
436} RTVFSOBJSETOPS;
437/** Pointer to const object attribute setter operations. */
438typedef RTVFSOBJSETOPS const *PCRTVFSOBJSETOPS;
439
440/** The RTVFSOBJSETOPS structure version. */
441#define RTVFSOBJSETOPS_VERSION RT_MAKE_U32_FROM_U8(0xff,0x2f,1,0)
442
443
444/**
445 * The filesystem stream operations.
446 *
447 * @extends RTVFSOBJOPS
448 */
449typedef struct RTVFSFSSTREAMOPS
450{
451 /** The basic object operation. */
452 RTVFSOBJOPS Obj;
453 /** The structure version (RTVFSFSSTREAMOPS_VERSION). */
454 uint32_t uVersion;
455 /** Reserved field, MBZ. */
456 uint32_t fReserved;
457
458 /**
459 * Gets the next object in the stream.
460 *
461 * Readable streams only.
462 *
463 * @returns IPRT status code.
464 * @retval VINF_SUCCESS if a new object was retrieved.
465 * @retval VERR_EOF when there are no more objects.
466 * @param pvThis The implementation specific directory data.
467 * @param ppszName Where to return the object name. Must be freed by
468 * calling RTStrFree.
469 * @param penmType Where to return the object type.
470 * @param phVfsObj Where to return the object handle (referenced). This
471 * must be cast to the desired type before use.
472 * @sa RTVfsFsStrmNext
473 *
474 * @note Setting this member to NULL is okay for write-only streams.
475 */
476 DECLCALLBACKMEMBER(int, pfnNext,(void *pvThis, char **ppszName, RTVFSOBJTYPE *penmType, PRTVFSOBJ phVfsObj));
477
478 /**
479 * Adds another object into the stream.
480 *
481 * Writable streams only.
482 *
483 * @returns IPRT status code.
484 * @param pvThis The implementation specific directory data.
485 * @param pszPath The path to the object.
486 * @param hVfsObj The object to add.
487 * @param fFlags Reserved for the future, MBZ.
488 * @sa RTVfsFsStrmAdd
489 *
490 * @note Setting this member to NULL is okay for read-only streams.
491 */
492 DECLCALLBACKMEMBER(int, pfnAdd,(void *pvThis, const char *pszPath, RTVFSOBJ hVfsObj, uint32_t fFlags));
493
494 /**
495 * Pushes an byte stream onto the stream (optional).
496 *
497 * Writable streams only.
498 *
499 * This differs from RTVFSFSSTREAMOPS::pfnAdd() in that it will create a regular
500 * file in the output file system stream and provide the actual content bytes
501 * via the returned I/O stream object.
502 *
503 * @returns IPRT status code.
504 * @param pvThis The implementation specific directory data.
505 * @param pszPath The path to the file.
506 * @param cbFile The file size. This can also be set to UINT64_MAX if
507 * the file system stream is backed by a file.
508 * @param paObjInfo Array of zero or more RTFSOBJINFO structures containing
509 * different pieces of information about the file. If any
510 * provided, the first one should be a RTFSOBJATTRADD_UNIX
511 * one, additional can be supplied if wanted. What exactly
512 * is needed depends on the underlying FS stream
513 * implementation.
514 * @param cObjInfo Number of items in the array @a paObjInfo points at.
515 * @param fFlags RTVFSFSSTRM_PUSH_F_XXX.
516 * @param phVfsIos Where to return the I/O stream to feed the file content
517 * to. If the FS stream is backed by a file, the returned
518 * handle can be cast to a file if necessary.
519 */
520 DECLCALLBACKMEMBER(int, pfnPushFile,(void *pvThis, const char *pszPath, uint64_t cbFile,
521 PCRTFSOBJINFO paObjInfo, uint32_t cObjInfo, uint32_t fFlags, PRTVFSIOSTREAM phVfsIos));
522
523 /**
524 * Marks the end of the stream.
525 *
526 * Writable streams only.
527 *
528 * @returns IPRT status code.
529 * @param pvThis The implementation specific directory data.
530 * @sa RTVfsFsStrmEnd
531 *
532 * @note Setting this member to NULL is okay for read-only streams.
533 */
534 DECLCALLBACKMEMBER(int, pfnEnd,(void *pvThis));
535
536 /** Marks the end of the structure (RTVFSFSSTREAMOPS_VERSION). */
537 uintptr_t uEndMarker;
538} RTVFSFSSTREAMOPS;
539/** Pointer to const object attribute setter operations. */
540typedef RTVFSFSSTREAMOPS const *PCRTVFSFSSTREAMOPS;
541
542/** The RTVFSFSSTREAMOPS structure version. */
543#define RTVFSFSSTREAMOPS_VERSION RT_MAKE_U32_FROM_U8(0xff,0x3f,2,0)
544
545
546/**
547 * Creates a new VFS filesystem stream handle.
548 *
549 * @returns IPRT status code
550 * @param pFsStreamOps The filesystem stream operations.
551 * @param cbInstance The size of the instance data.
552 * @param hVfs The VFS handle to associate this filesystem
553 * stream with. NIL_VFS is ok.
554 * @param hLock Handle to a custom lock to be used with the new
555 * object. The reference is consumed. NIL and
556 * special lock handles are fine.
557 * @param fAccess RTFILE_O_READ and/or RTFILE_O_WRITE.
558 * @param phVfsFss Where to return the new handle.
559 * @param ppvInstance Where to return the pointer to the instance data
560 * (size is @a cbInstance).
561 */
562RTDECL(int) RTVfsNewFsStream(PCRTVFSFSSTREAMOPS pFsStreamOps, size_t cbInstance, RTVFS hVfs, RTVFSLOCK hLock, uint32_t fAccess,
563 PRTVFSFSSTREAM phVfsFss, void **ppvInstance);
564
565/**
566 * Gets the private data of an filesystem stream.
567 *
568 * @returns Pointer to the private data. NULL if the handle is invalid in some
569 * way.
570 * @param hVfsFss The FS stream handle.
571 * @param pFsStreamOps The FS stream operations. This servers as a
572 * sort of password.
573 */
574RTDECL(void *) RTVfsFsStreamToPrivate(RTVFSFSSTREAM hVfsFss, PCRTVFSFSSTREAMOPS pFsStreamOps);
575
576
577/**
578 * The directory operations.
579 *
580 * @extends RTVFSOBJOPS
581 * @extends RTVFSOBJSETOPS
582 */
583typedef struct RTVFSDIROPS
584{
585 /** The basic object operation. */
586 RTVFSOBJOPS Obj;
587 /** The structure version (RTVFSDIROPS_VERSION). */
588 uint32_t uVersion;
589 /** Reserved field, MBZ. */
590 uint32_t fReserved;
591 /** The object setter operations. */
592 RTVFSOBJSETOPS ObjSet;
593
594 /**
595 * Generic method for opening any kind of file system object.
596 *
597 * Can also create files and directories. Symbolic links, devices and such
598 * needs to be created using special methods or this would end up being way more
599 * complicated than it already is.
600 *
601 * There are optional specializations available.
602 *
603 * @returns IPRT status code.
604 * @retval VERR_PATH_NOT_FOUND or VERR_FILE_NOT_FOUND if @a pszEntry was not
605 * found.
606 * @retval VERR_IS_A_FILE if @a pszEntry is a file or similar but @a fFlags
607 * indicates that the type of object should not be opened.
608 * @retval VERR_IS_A_DIRECTORY if @a pszEntry is a directory but @a fFlags
609 * indicates that directories should not be opened.
610 * @retval VERR_IS_A_SYMLINK if @a pszEntry is a symbolic link but @a fFlags
611 * indicates that symbolic links should not be opened (or followed).
612 * @retval VERR_IS_A_FIFO if @a pszEntry is a FIFO but @a fFlags indicates that
613 * FIFOs should not be opened.
614 * @retval VERR_IS_A_SOCKET if @a pszEntry is a socket but @a fFlags indicates
615 * that sockets should not be opened.
616 * @retval VERR_IS_A_BLOCK_DEVICE if @a pszEntry is a block device but
617 * @a fFlags indicates that block devices should not be opened, or vice
618 * versa.
619 *
620 * @param pvThis The implementation specific directory data.
621 * @param pszEntry The name of the immediate file to open or create.
622 * @param fOpenFile RTFILE_O_XXX combination.
623 * @param fObjFlags More flags: RTVFSOBJ_F_XXX, RTPATH_F_XXX.
624 * The meaning of RTPATH_F_FOLLOW_LINK differs here, if
625 * @a pszEntry is a symlink it should be opened for
626 * traversal rather than according to @a fOpenFile.
627 * @param phVfsObj Where to return the handle to the opened object.
628 * @sa RTFileOpen, RTDirOpen
629 */
630 DECLCALLBACKMEMBER(int, pfnOpen,(void *pvThis, const char *pszEntry, uint64_t fOpenFile,
631 uint32_t fObjFlags, PRTVFSOBJ phVfsObj));
632
633 /**
634 * Optional method for symbolic link handling in the vfsstddir.cpp.
635 *
636 * This is really just a hack to make symbolic link handling work when working
637 * with directory objects that doesn't have an associated VFS. It also helps
638 * deal with drive letters in symbolic links on Windows and OS/2.
639 *
640 * @returns IPRT status code.
641 * @retval VERR_PATH_IS_RELATIVE if @a pszPath isn't absolute and should be
642 * handled using pfnOpen().
643 *
644 * @param pvThis The implementation specific directory data.
645 * @param pszRoot Path to the alleged root.
646 * @param phVfsDir Where to return the handle to the specified root
647 * directory (or may current dir on a drive letter).
648 */
649 DECLCALLBACKMEMBER(int, pfnFollowAbsoluteSymlink,(void *pvThis, const char *pszRoot, PRTVFSDIR phVfsDir));
650
651 /**
652 * Open or create a file.
653 *
654 * @returns IPRT status code.
655 * @param pvThis The implementation specific directory data.
656 * @param pszFilename The name of the immediate file to open or create.
657 * @param fOpen The open flags (RTFILE_O_XXX).
658 * @param phVfsFile Where to return the handle to the opened file.
659 * @note Optional. RTVFSDIROPS::pfnOpenObj will be used if NULL.
660 * @sa RTFileOpen.
661 */
662 DECLCALLBACKMEMBER(int, pfnOpenFile,(void *pvThis, const char *pszFilename, uint64_t fOpen, PRTVFSFILE phVfsFile));
663
664 /**
665 * Open an existing subdirectory.
666 *
667 * @returns IPRT status code.
668 * @retval VERR_IS_A_SYMLINK if @a pszSubDir is a symbolic link.
669 * @retval VERR_NOT_A_DIRECTORY is okay for symbolic links too.
670 *
671 * @param pvThis The implementation specific directory data.
672 * @param pszSubDir The name of the immediate subdirectory to open.
673 * @param fFlags RTDIR_F_XXX.
674 * @param phVfsDir Where to return the handle to the opened directory.
675 * Optional.
676 * @note Optional. RTVFSDIROPS::pfnOpenObj will be used if NULL.
677 * @sa RTDirOpen.
678 */
679 DECLCALLBACKMEMBER(int, pfnOpenDir,(void *pvThis, const char *pszSubDir, uint32_t fFlags, PRTVFSDIR phVfsDir));
680
681 /**
682 * Creates a new subdirectory.
683 *
684 * @returns IPRT status code.
685 * @param pvThis The implementation specific directory data.
686 * @param pszSubDir The name of the immediate subdirectory to create.
687 * @param fMode The mode mask of the new directory.
688 * @param phVfsDir Where to optionally return the handle to the newly
689 * create directory.
690 * @note Optional. RTVFSDIROPS::pfnOpenObj will be used if NULL.
691 * @sa RTDirCreate.
692 */
693 DECLCALLBACKMEMBER(int, pfnCreateDir,(void *pvThis, const char *pszSubDir, RTFMODE fMode, PRTVFSDIR phVfsDir));
694
695 /**
696 * Opens an existing symbolic link.
697 *
698 * @returns IPRT status code.
699 * @param pvThis The implementation specific directory data.
700 * @param pszSymlink The name of the immediate symbolic link to open.
701 * @param phVfsSymlink Where to optionally return the handle to the
702 * newly create symbolic link.
703 * @note Optional. RTVFSDIROPS::pfnOpenObj will be used if NULL.
704 * @sa RTSymlinkCreate.
705 */
706 DECLCALLBACKMEMBER(int, pfnOpenSymlink,(void *pvThis, const char *pszSymlink, PRTVFSSYMLINK phVfsSymlink));
707
708 /**
709 * Creates a new symbolic link.
710 *
711 * @returns IPRT status code.
712 * @param pvThis The implementation specific directory data.
713 * @param pszSymlink The name of the immediate symbolic link to create.
714 * @param pszTarget The symbolic link target.
715 * @param enmType The symbolic link type.
716 * @param phVfsSymlink Where to optionally return the handle to the
717 * newly create symbolic link.
718 * @sa RTSymlinkCreate.
719 */
720 DECLCALLBACKMEMBER(int, pfnCreateSymlink,(void *pvThis, const char *pszSymlink, const char *pszTarget,
721 RTSYMLINKTYPE enmType, PRTVFSSYMLINK phVfsSymlink));
722
723 /**
724 * Query information about an entry.
725 *
726 * @returns IPRT status code.
727 * @param pvThis The implementation specific directory data.
728 * @param pszEntry The name of the directory entry to remove.
729 * @param pObjInfo Where to return the info on success.
730 * @param enmAddAttr Which set of additional attributes to request.
731 * @note Optional. RTVFSDIROPS::pfnOpenObj and RTVFSOBJOPS::pfnQueryInfo
732 * will be used if NULL.
733 * @sa RTPathQueryInfo, RTVFSOBJOPS::pfnQueryInfo
734 */
735 DECLCALLBACKMEMBER(int, pfnQueryEntryInfo,(void *pvThis, const char *pszEntry,
736 PRTFSOBJINFO pObjInfo, RTFSOBJATTRADD enmAddAttr));
737
738 /**
739 * Removes a directory entry.
740 *
741 * @returns IPRT status code.
742 * @param pvThis The implementation specific directory data.
743 * @param pszEntry The name of the directory entry to remove.
744 * @param fType If non-zero, this restricts the type of the entry to
745 * the object type indicated by the mask
746 * (RTFS_TYPE_XXX).
747 * @sa RTFileRemove, RTDirRemove, RTSymlinkRemove.
748 */
749 DECLCALLBACKMEMBER(int, pfnUnlinkEntry,(void *pvThis, const char *pszEntry, RTFMODE fType));
750
751 /**
752 * Renames a directory entry.
753 *
754 * @returns IPRT status code.
755 * @param pvThis The implementation specific directory data.
756 * @param pszEntry The name of the directory entry to rename.
757 * @param fType If non-zero, this restricts the type of the entry to
758 * the object type indicated by the mask
759 * (RTFS_TYPE_XXX).
760 * @param pszNewName The new entry name.
761 * @sa RTPathRename
762 *
763 * @todo This API is not flexible enough, must be able to rename between
764 * directories within a file system.
765 */
766 DECLCALLBACKMEMBER(int, pfnRenameEntry,(void *pvThis, const char *pszEntry, RTFMODE fType, const char *pszNewName));
767
768 /**
769 * Rewind the directory stream so that the next read returns the first
770 * entry.
771 *
772 * @returns IPRT status code.
773 * @param pvThis The implementation specific directory data.
774 */
775 DECLCALLBACKMEMBER(int, pfnRewindDir,(void *pvThis));
776
777 /**
778 * Rewind the directory stream so that the next read returns the first
779 * entry.
780 *
781 * @returns IPRT status code.
782 * @param pvThis The implementation specific directory data.
783 * @param pDirEntry Output buffer.
784 * @param pcbDirEntry Complicated, see RTDirReadEx.
785 * @param enmAddAttr Which set of additional attributes to request.
786 * @sa RTDirReadEx
787 */
788 DECLCALLBACKMEMBER(int, pfnReadDir,(void *pvThis, PRTDIRENTRYEX pDirEntry, size_t *pcbDirEntry, RTFSOBJATTRADD enmAddAttr));
789
790 /** Marks the end of the structure (RTVFSDIROPS_VERSION). */
791 uintptr_t uEndMarker;
792} RTVFSDIROPS;
793/** Pointer to const directory operations. */
794typedef RTVFSDIROPS const *PCRTVFSDIROPS;
795/** The RTVFSDIROPS structure version. */
796#define RTVFSDIROPS_VERSION RT_MAKE_U32_FROM_U8(0xff,0x4f,1,0)
797
798
799/**
800 * Creates a new VFS directory handle.
801 *
802 * @returns IPRT status code
803 * @param pDirOps The directory operations.
804 * @param cbInstance The size of the instance data.
805 * @param fFlags RTVFSDIR_F_XXX
806 * @param hVfs The VFS handle to associate this directory with.
807 * NIL_VFS is ok.
808 * @param hLock Handle to a custom lock to be used with the new
809 * object. The reference is consumed. NIL and
810 * special lock handles are fine.
811 * @param phVfsDir Where to return the new handle.
812 * @param ppvInstance Where to return the pointer to the instance data
813 * (size is @a cbInstance).
814 */
815RTDECL(int) RTVfsNewDir(PCRTVFSDIROPS pDirOps, size_t cbInstance, uint32_t fFlags, RTVFS hVfs, RTVFSLOCK hLock,
816 PRTVFSDIR phVfsDir, void **ppvInstance);
817
818/** @name RTVFSDIR_F_XXX
819 * @{ */
820/** Don't reference the @a hVfs parameter passed to RTVfsNewDir.
821 * This is a permanent root directory hack. */
822#define RTVFSDIR_F_NO_VFS_REF RT_BIT_32(0)
823/** @} */
824
825/**
826 * Gets the private data of a directory.
827 *
828 * @returns Pointer to the private data. NULL if the handle is invalid in some
829 * way.
830 * @param hVfsDir The directory handle.
831 * @param pDirOps The directory operations. This servers as a
832 * sort of password.
833 */
834RTDECL(void *) RTVfsDirToPrivate(RTVFSDIR hVfsDir, PCRTVFSDIROPS pDirOps);
835
836
837/**
838 * The symbolic link operations.
839 *
840 * @extends RTVFSOBJOPS
841 * @extends RTVFSOBJSETOPS
842 */
843typedef struct RTVFSSYMLINKOPS
844{
845 /** The basic object operation. */
846 RTVFSOBJOPS Obj;
847 /** The structure version (RTVFSSYMLINKOPS_VERSION). */
848 uint32_t uVersion;
849 /** Reserved field, MBZ. */
850 uint32_t fReserved;
851 /** The object setter operations. */
852 RTVFSOBJSETOPS ObjSet;
853
854 /**
855 * Read the symbolic link target.
856 *
857 * @returns IPRT status code.
858 * @param pvThis The implementation specific symbolic link data.
859 * @param pszTarget The target buffer.
860 * @param cbTarget The size of the target buffer.
861 * @sa RTSymlinkRead
862 */
863 DECLCALLBACKMEMBER(int, pfnRead,(void *pvThis, char *pszTarget, size_t cbTarget));
864
865 /** Marks the end of the structure (RTVFSSYMLINKOPS_VERSION). */
866 uintptr_t uEndMarker;
867} RTVFSSYMLINKOPS;
868/** Pointer to const symbolic link operations. */
869typedef RTVFSSYMLINKOPS const *PCRTVFSSYMLINKOPS;
870/** The RTVFSSYMLINKOPS structure version. */
871#define RTVFSSYMLINKOPS_VERSION RT_MAKE_U32_FROM_U8(0xff,0x5f,1,0)
872
873
874/**
875 * Creates a new VFS symlink handle.
876 *
877 * @returns IPRT status code
878 * @param pSymlinkOps The symlink operations.
879 * @param cbInstance The size of the instance data.
880 * @param hVfs The VFS handle to associate this symlink object
881 * with. NIL_VFS is ok.
882 * @param hLock Handle to a custom lock to be used with the new
883 * object. The reference is consumed. NIL and
884 * special lock handles are fine.
885 * @param phVfsSym Where to return the new handle.
886 * @param ppvInstance Where to return the pointer to the instance data
887 * (size is @a cbInstance).
888 */
889RTDECL(int) RTVfsNewSymlink(PCRTVFSSYMLINKOPS pSymlinkOps, size_t cbInstance, RTVFS hVfs, RTVFSLOCK hLock,
890 PRTVFSSYMLINK phVfsSym, void **ppvInstance);
891
892
893/**
894 * Gets the private data of a symbolic link.
895 *
896 * @returns Pointer to the private data. NULL if the handle is invalid in some
897 * way.
898 * @param hVfsSym The symlink handle.
899 * @param pSymlinkOps The symlink operations. This servers as a sort
900 * of password.
901 */
902RTDECL(void *) RTVfsSymlinkToPrivate(RTVFSSYMLINK hVfsSym, PCRTVFSSYMLINKOPS pSymlinkOps);
903
904/**
905 * The basis for all I/O objects (files, pipes, sockets, devices, ++).
906 *
907 * @extends RTVFSOBJOPS
908 */
909typedef struct RTVFSIOSTREAMOPS
910{
911 /** The basic object operation. */
912 RTVFSOBJOPS Obj;
913 /** The structure version (RTVFSIOSTREAMOPS_VERSION). */
914 uint32_t uVersion;
915 /** Feature field. */
916 uint32_t fFeatures;
917
918 /**
919 * Reads from the file/stream.
920 *
921 * @returns IPRT status code. See RTVfsIoStrmRead.
922 * @param pvThis The implementation specific file data.
923 * @param off Where to read at, -1 for the current position.
924 * @param pSgBuf Gather buffer for the bytes that are to be read.
925 * @param fBlocking If @c true, the call is blocking, if @c false it
926 * should not block.
927 * @param pcbRead Where return the number of bytes actually read.
928 * This is set it 0 by the caller. If NULL, try read
929 * all and fail if incomplete.
930 * @sa RTVfsIoStrmRead, RTVfsIoStrmSgRead, RTVfsFileRead,
931 * RTVfsFileReadAt, RTFileRead, RTFileReadAt.
932 */
933 DECLCALLBACKMEMBER(int, pfnRead,(void *pvThis, RTFOFF off, PRTSGBUF pSgBuf, bool fBlocking, size_t *pcbRead));
934
935 /**
936 * Writes to the file/stream.
937 *
938 * @returns IPRT status code.
939 * @param pvThis The implementation specific file data.
940 * @param off Where to start wrinting, -1 for the current
941 * position.
942 * @param pSgBuf Gather buffers describing the bytes that are to be
943 * written.
944 * @param fBlocking If @c true, the call is blocking, if @c false it
945 * should not block.
946 * @param pcbWritten Where to return the number of bytes actually
947 * written. This is set it 0 by the caller. If
948 * NULL, try write it all and fail if incomplete.
949 * @note Optional, failing with VERR_WRITE_PROTECT if NULL.
950 * @sa RTFileWrite, RTFileWriteAt.
951 */
952 DECLCALLBACKMEMBER(int, pfnWrite,(void *pvThis, RTFOFF off, PRTSGBUF pSgBuf, bool fBlocking, size_t *pcbWritten));
953
954 /**
955 * Flushes any pending data writes to the stream.
956 *
957 * @returns IPRT status code.
958 * @param pvThis The implementation specific file data.
959 * @sa RTFileFlush.
960 */
961 DECLCALLBACKMEMBER(int, pfnFlush,(void *pvThis));
962
963 /**
964 * Poll for events.
965 *
966 * @returns IPRT status code.
967 * @param pvThis The implementation specific file data.
968 * @param fEvents The events to poll for (RTPOLL_EVT_XXX).
969 * @param cMillies How long to wait for event to eventuate.
970 * @param fIntr Whether the wait is interruptible and can return
971 * VERR_INTERRUPTED (@c true) or if this condition
972 * should be hidden from the caller (@c false).
973 * @param pfRetEvents Where to return the event mask.
974 * @note Optional. If NULL, immediately return all requested non-error
975 * events, waiting for errors works like sleep.
976 * @sa RTPollSetAdd, RTPoll, RTPollNoResume.
977 */
978 DECLCALLBACKMEMBER(int, pfnPollOne,(void *pvThis, uint32_t fEvents, RTMSINTERVAL cMillies, bool fIntr,
979 uint32_t *pfRetEvents));
980
981 /**
982 * Tells the current file/stream position.
983 *
984 * @returns IPRT status code.
985 * @param pvThis The implementation specific file data.
986 * @param poffActual Where to return the actual offset.
987 * @sa RTFileTell
988 */
989 DECLCALLBACKMEMBER(int, pfnTell,(void *pvThis, PRTFOFF poffActual));
990
991 /**
992 * Skips @a cb ahead in the stream.
993 *
994 * @returns IPRT status code.
995 * @param pvThis The implementation specific file data.
996 * @param cb The number bytes to skip.
997 * @remarks This is optional and can be NULL.
998 */
999 DECLCALLBACKMEMBER(int, pfnSkip,(void *pvThis, RTFOFF cb));
1000
1001 /**
1002 * Fills the stream with @a cb zeros.
1003 *
1004 * @returns IPRT status code.
1005 * @param pvThis The implementation specific file data.
1006 * @param cb The number of zero bytes to insert.
1007 * @remarks This is optional and can be NULL.
1008 */
1009 DECLCALLBACKMEMBER(int, pfnZeroFill,(void *pvThis, RTFOFF cb));
1010
1011 /** Marks the end of the structure (RTVFSIOSTREAMOPS_VERSION). */
1012 uintptr_t uEndMarker;
1013} RTVFSIOSTREAMOPS;
1014/** Pointer to const I/O stream operations. */
1015typedef RTVFSIOSTREAMOPS const *PCRTVFSIOSTREAMOPS;
1016
1017/** The RTVFSIOSTREAMOPS structure version. */
1018#define RTVFSIOSTREAMOPS_VERSION RT_MAKE_U32_FROM_U8(0xff,0x6f,1,0)
1019
1020/** @name RTVFSIOSTREAMOPS::fFeatures
1021 * @{ */
1022/** No scatter gather lists, thank you. */
1023#define RTVFSIOSTREAMOPS_FEAT_NO_SG RT_BIT_32(0)
1024/** Mask of the valid I/O stream feature flags. */
1025#define RTVFSIOSTREAMOPS_FEAT_VALID_MASK UINT32_C(0x00000001)
1026/** @} */
1027
1028
1029/**
1030 * Creates a new VFS I/O stream handle.
1031 *
1032 * @returns IPRT status code
1033 * @param pIoStreamOps The I/O stream operations.
1034 * @param cbInstance The size of the instance data.
1035 * @param fOpen The open flags. The minimum is the access mask.
1036 * @param hVfs The VFS handle to associate this I/O stream
1037 * with. NIL_VFS is ok.
1038 * @param hLock Handle to a custom lock to be used with the new
1039 * object. The reference is consumed. NIL and
1040 * special lock handles are fine.
1041 * @param phVfsIos Where to return the new handle.
1042 * @param ppvInstance Where to return the pointer to the instance data
1043 * (size is @a cbInstance).
1044 */
1045RTDECL(int) RTVfsNewIoStream(PCRTVFSIOSTREAMOPS pIoStreamOps, size_t cbInstance, uint32_t fOpen, RTVFS hVfs, RTVFSLOCK hLock,
1046 PRTVFSIOSTREAM phVfsIos, void **ppvInstance);
1047
1048
1049/**
1050 * Gets the private data of an I/O stream.
1051 *
1052 * @returns Pointer to the private data. NULL if the handle is invalid in some
1053 * way.
1054 * @param hVfsIos The I/O stream handle.
1055 * @param pIoStreamOps The I/O stream operations. This servers as a
1056 * sort of password.
1057 */
1058RTDECL(void *) RTVfsIoStreamToPrivate(RTVFSIOSTREAM hVfsIos, PCRTVFSIOSTREAMOPS pIoStreamOps);
1059
1060
1061/**
1062 * The file operations.
1063 *
1064 * @extends RTVFSIOSTREAMOPS
1065 * @extends RTVFSOBJSETOPS
1066 */
1067typedef struct RTVFSFILEOPS
1068{
1069 /** The I/O stream and basis object operations. */
1070 RTVFSIOSTREAMOPS Stream;
1071 /** The structure version (RTVFSFILEOPS_VERSION). */
1072 uint32_t uVersion;
1073 /** Reserved field, MBZ. */
1074 uint32_t fReserved;
1075 /** The object setter operations. */
1076 RTVFSOBJSETOPS ObjSet;
1077
1078 /**
1079 * Changes the current file position.
1080 *
1081 * @returns IPRT status code.
1082 * @param pvThis The implementation specific file data.
1083 * @param offSeek The offset to seek.
1084 * @param uMethod The seek method, i.e. what the seek is relative to.
1085 * @param poffActual Where to return the actual offset.
1086 * @sa RTFileSeek
1087 */
1088 DECLCALLBACKMEMBER(int, pfnSeek,(void *pvThis, RTFOFF offSeek, unsigned uMethod, PRTFOFF poffActual));
1089
1090 /**
1091 * Get the current file size.
1092 *
1093 * @returns IPRT status code.
1094 * @param pvThis The implementation specific file data.
1095 * @param pcbFile Where to store the current file size.
1096 * @sa RTFileQuerySize
1097 */
1098 DECLCALLBACKMEMBER(int, pfnQuerySize,(void *pvThis, uint64_t *pcbFile));
1099
1100 /**
1101 * Change the file size.
1102 *
1103 * @returns IPRT status code.
1104 * @retval VERR_ACCESS_DENIED if handle isn't writable.
1105 * @retval VERR_WRITE_PROTECT if read-only file system.
1106 * @retval VERR_FILE_TOO_BIG if cbSize is larger than what the file system can
1107 * theoretically deal with.
1108 * @retval VERR_DISK_FULL if the file system if full.
1109 * @retval VERR_NOT_SUPPORTED if fFlags indicates some operation that's not
1110 * supported by the file system / host operating system.
1111 *
1112 * @param pvThis The implementation specific file data.
1113 * @param pcbFile Where to store the current file size.
1114 * @param fFlags RTVFSFILE_SET_SIZE_F_XXX.
1115 * @note Optional. If NULL, VERR_WRITE_PROTECT will be returned.
1116 * @sa RTFileSetSize, RTFileSetAllocationSize
1117 */
1118 DECLCALLBACKMEMBER(int, pfnSetSize,(void *pvThis, uint64_t cbFile, uint32_t fFlags));
1119
1120 /**
1121 * Determine the maximum file size.
1122 *
1123 * This won't take amount of freespace into account, just the limitations of the
1124 * underlying file system / host operating system.
1125 *
1126 * @returns IPRT status code.
1127 * @param pvThis The implementation specific file data.
1128 * @param pcbMax Where to return the max file size.
1129 * @note Optional. If NULL, VERR_NOT_IMPLEMENTED will be returned.
1130 * @sa RTFileQueryMaxSizeEx
1131 */
1132 DECLCALLBACKMEMBER(int, pfnQueryMaxSize,(void *pvThis, uint64_t *pcbMax));
1133
1134 /** @todo There will be more methods here. */
1135
1136 /** Marks the end of the structure (RTVFSFILEOPS_VERSION). */
1137 uintptr_t uEndMarker;
1138} RTVFSFILEOPS;
1139/** Pointer to const file operations. */
1140typedef RTVFSFILEOPS const *PCRTVFSFILEOPS;
1141
1142/** The RTVFSFILEOPS structure version. */
1143#define RTVFSFILEOPS_VERSION RT_MAKE_U32_FROM_U8(0xff,0x7f,2,0)
1144
1145/**
1146 * Creates a new VFS file handle.
1147 *
1148 * @returns IPRT status code
1149 * @param pFileOps The file operations.
1150 * @param cbInstance The size of the instance data.
1151 * @param fOpen The open flags. The minimum is the access mask.
1152 * @param hVfs The VFS handle to associate this file with.
1153 * NIL_VFS is ok.
1154 * @param hLock Handle to a custom lock to be used with the new
1155 * object. The reference is consumed. NIL and
1156 * special lock handles are fine.
1157 * @param phVfsFile Where to return the new handle.
1158 * @param ppvInstance Where to return the pointer to the instance data
1159 * (size is @a cbInstance).
1160 */
1161RTDECL(int) RTVfsNewFile(PCRTVFSFILEOPS pFileOps, size_t cbInstance, uint32_t fOpen, RTVFS hVfs, RTVFSLOCK hLock,
1162 PRTVFSFILE phVfsFile, void **ppvInstance);
1163
1164
1165/** @defgroup grp_rt_vfs_ll_util VFS Utility APIs
1166 * @{ */
1167
1168/**
1169 * Parsed path.
1170 */
1171typedef struct RTVFSPARSEDPATH
1172{
1173 /** The length of the path in szCopy. */
1174 uint16_t cch;
1175 /** The number of path components. */
1176 uint16_t cComponents;
1177 /** Set if the path ends with slash, indicating that it's a directory
1178 * reference and not a file reference. The slash has been removed from
1179 * the copy. */
1180 bool fDirSlash;
1181 /** Set if absolute. */
1182 bool fAbsolute;
1183 /** The offset where each path component starts, i.e. the char after the
1184 * slash. The array has cComponents + 1 entries, where the final one is
1185 * cch + 1 so that one can always terminate the current component by
1186 * szPath[aoffComponent[i] - 1] = '\0'. */
1187 uint16_t aoffComponents[RTPATH_MAX / 2 + 1];
1188 /** A normalized copy of the path.
1189 * Reserve some extra space so we can be more relaxed about overflow
1190 * checks and terminator paddings, especially when recursing. */
1191 char szPath[RTPATH_MAX];
1192} RTVFSPARSEDPATH;
1193/** Pointer to a parsed path. */
1194typedef RTVFSPARSEDPATH *PRTVFSPARSEDPATH;
1195
1196/** The max accepted path length.
1197 * This must be a few chars shorter than RTVFSPARSEDPATH::szPath because we
1198 * use two terminators and wish be a little bit lazy with checking. */
1199#define RTVFSPARSEDPATH_MAX (RTPATH_MAX - 4)
1200
1201/**
1202 * Appends @a pszPath (relative) to the already parsed path @a pPath.
1203 *
1204 * @retval VINF_SUCCESS
1205 * @retval VERR_FILENAME_TOO_LONG
1206 * @retval VERR_INTERNAL_ERROR_4
1207 * @param pPath The parsed path to append @a pszPath onto.
1208 * This is both input and output.
1209 * @param pszPath The path to append. This must be relative.
1210 * @param piRestartComp The component to restart parsing at. This is
1211 * input/output. The input does not have to be
1212 * within the valid range. Optional.
1213 */
1214RTDECL(int) RTVfsParsePathAppend(PRTVFSPARSEDPATH pPath, const char *pszPath, uint16_t *piRestartComp);
1215
1216/**
1217 * Parses a path.
1218 *
1219 * @retval VINF_SUCCESS
1220 * @retval VERR_FILENAME_TOO_LONG
1221 * @param pPath Where to store the parsed path.
1222 * @param pszPath The path to parse. Absolute or relative to @a
1223 * pszCwd.
1224 * @param pszCwd The current working directory. Must be
1225 * absolute.
1226 */
1227RTDECL(int) RTVfsParsePath(PRTVFSPARSEDPATH pPath, const char *pszPath, const char *pszCwd);
1228
1229/**
1230 * Same as RTVfsParsePath except that it allocates a temporary buffer.
1231 *
1232 * @retval VINF_SUCCESS
1233 * @retval VERR_NO_TMP_MEMORY
1234 * @retval VERR_FILENAME_TOO_LONG
1235 * @param pszPath The path to parse. Absolute or relative to @a
1236 * pszCwd.
1237 * @param pszCwd The current working directory. Must be
1238 * absolute.
1239 * @param ppPath Where to store the pointer to the allocated
1240 * buffer containing the parsed path. This must
1241 * be freed by calling RTVfsParsePathFree. NULL
1242 * will be stored on failured.
1243 */
1244RTDECL(int) RTVfsParsePathA(const char *pszPath, const char *pszCwd, PRTVFSPARSEDPATH *ppPath);
1245
1246/**
1247 * Frees a buffer returned by RTVfsParsePathA.
1248 *
1249 * @param pPath The parsed path buffer to free. NULL is fine.
1250 */
1251RTDECL(void) RTVfsParsePathFree(PRTVFSPARSEDPATH pPath);
1252
1253/**
1254 * Dummy implementation of RTVFSIOSTREAMOPS::pfnPollOne.
1255 *
1256 * This handles the case where there is no chance any events my be raised and
1257 * all that is required is to wait according to the parameters.
1258 *
1259 * @returns IPRT status code.
1260 * @param fEvents The events to poll for (RTPOLL_EVT_XXX).
1261 * @param cMillies How long to wait for event to eventuate.
1262 * @param fIntr Whether the wait is interruptible and can return
1263 * VERR_INTERRUPTED (@c true) or if this condition
1264 * should be hidden from the caller (@c false).
1265 * @param pfRetEvents Where to return the event mask.
1266 * @sa RTVFSIOSTREAMOPS::pfnPollOne, RTPollSetAdd, RTPoll, RTPollNoResume.
1267 */
1268RTDECL(int) RTVfsUtilDummyPollOne(uint32_t fEvents, RTMSINTERVAL cMillies, bool fIntr, uint32_t *pfRetEvents);
1269
1270/** @} */
1271
1272
1273/** @defgroup grp_rt_vfs_lowlevel_chain VFS Chains (Low Level)
1274 * @ref grp_rt_vfs_chain
1275 * @{
1276 */
1277
1278/** Pointer to a VFS chain element registration record. */
1279typedef struct RTVFSCHAINELEMENTREG *PRTVFSCHAINELEMENTREG;
1280/** Pointer to a const VFS chain element registration record. */
1281typedef struct RTVFSCHAINELEMENTREG const *PCRTVFSCHAINELEMENTREG;
1282
1283/**
1284 * VFS chain element argument.
1285 */
1286typedef struct RTVFSCHAINELEMENTARG
1287{
1288 /** The string argument value. */
1289 char *psz;
1290 /** The specification offset of this argument. */
1291 uint16_t offSpec;
1292 /** Provider specific value. */
1293 uint64_t uProvider;
1294} RTVFSCHAINELEMENTARG;
1295/** Pointer to a VFS chain element argument. */
1296typedef RTVFSCHAINELEMENTARG *PRTVFSCHAINELEMENTARG;
1297
1298
1299/**
1300 * VFS chain element specification.
1301 */
1302typedef struct RTVFSCHAINELEMSPEC
1303{
1304 /** The provider name.
1305 * This can be NULL if this is the final component and it's just a path. */
1306 char *pszProvider;
1307 /** The input type, RTVFSOBJTYPE_INVALID if first. */
1308 RTVFSOBJTYPE enmTypeIn;
1309 /** The element type.
1310 * RTVFSOBJTYPE_END if this is the final component and it's just a path. */
1311 RTVFSOBJTYPE enmType;
1312 /** The input spec offset of this element. */
1313 uint16_t offSpec;
1314 /** The length of the input spec. */
1315 uint16_t cchSpec;
1316 /** The number of arguments. */
1317 uint32_t cArgs;
1318 /** Arguments. */
1319 PRTVFSCHAINELEMENTARG paArgs;
1320
1321 /** The provider. */
1322 PCRTVFSCHAINELEMENTREG pProvider;
1323 /** Provider specific value. */
1324 uint64_t uProvider;
1325 /** The object (with reference). */
1326 RTVFSOBJ hVfsObj;
1327} RTVFSCHAINELEMSPEC;
1328/** Pointer to a chain element specification. */
1329typedef RTVFSCHAINELEMSPEC *PRTVFSCHAINELEMSPEC;
1330/** Pointer to a const chain element specification. */
1331typedef RTVFSCHAINELEMSPEC const *PCRTVFSCHAINELEMSPEC;
1332
1333
1334/**
1335 * Parsed VFS chain specification.
1336 */
1337typedef struct RTVFSCHAINSPEC
1338{
1339 /** Open directory flags (RTFILE_O_XXX). */
1340 uint64_t fOpenFile;
1341 /** To be defined. */
1342 uint32_t fOpenDir;
1343 /** The type desired by the caller. */
1344 RTVFSOBJTYPE enmDesiredType;
1345 /** The number of elements. */
1346 uint32_t cElements;
1347 /** The elements. */
1348 PRTVFSCHAINELEMSPEC paElements;
1349} RTVFSCHAINSPEC;
1350/** Pointer to a parsed VFS chain specification. */
1351typedef RTVFSCHAINSPEC *PRTVFSCHAINSPEC;
1352/** Pointer to a const, parsed VFS chain specification. */
1353typedef RTVFSCHAINSPEC const *PCRTVFSCHAINSPEC;
1354
1355
1356/**
1357 * A chain element provider registration record.
1358 */
1359typedef struct RTVFSCHAINELEMENTREG
1360{
1361 /** The version (RTVFSCHAINELEMENTREG_VERSION). */
1362 uint32_t uVersion;
1363 /** Reserved, MBZ. */
1364 uint32_t fReserved;
1365 /** The provider name (unique). */
1366 const char *pszName;
1367 /** For chaining the providers. */
1368 RTLISTNODE ListEntry;
1369 /** Help text. */
1370 const char *pszHelp;
1371
1372 /**
1373 * Checks the element specification.
1374 *
1375 * This is allowed to parse arguments and use pSpec->uProvider and
1376 * pElement->paArgs[].uProvider to store information that pfnInstantiate and
1377 * pfnCanReuseElement may use later on, thus avoiding duplicating work/code.
1378 *
1379 * @returns IPRT status code.
1380 * @param pProviderReg Pointer to the element provider registration.
1381 * @param pSpec The chain specification.
1382 * @param pElement The chain element specification to validate.
1383 * @param poffError Where to return error offset on failure. This is
1384 * set to the pElement->offSpec on input, so it only
1385 * needs to be adjusted if an argument is at fault.
1386 * @param pErrInfo Where to return additional error information, if
1387 * available. Optional.
1388 */
1389 DECLCALLBACKMEMBER(int, pfnValidate,(PCRTVFSCHAINELEMENTREG pProviderReg, PRTVFSCHAINSPEC pSpec,
1390 PRTVFSCHAINELEMSPEC pElement, uint32_t *poffError, PRTERRINFO pErrInfo));
1391
1392 /**
1393 * Create a VFS object according to the element specification.
1394 *
1395 * @returns IPRT status code.
1396 * @param pProviderReg Pointer to the element provider registration.
1397 * @param pSpec The chain specification.
1398 * @param pElement The chain element specification to instantiate.
1399 * @param hPrevVfsObj Handle to the previous VFS object, NIL_RTVFSOBJ if
1400 * first.
1401 * @param phVfsObj Where to return the VFS object handle.
1402 * @param poffError Where to return error offset on failure. This is
1403 * set to the pElement->offSpec on input, so it only
1404 * needs to be adjusted if an argument is at fault.
1405 * @param pErrInfo Where to return additional error information, if
1406 * available. Optional.
1407 */
1408 DECLCALLBACKMEMBER(int, pfnInstantiate,(PCRTVFSCHAINELEMENTREG pProviderReg, PCRTVFSCHAINSPEC pSpec,
1409 PCRTVFSCHAINELEMSPEC pElement, RTVFSOBJ hPrevVfsObj,
1410 PRTVFSOBJ phVfsObj, uint32_t *poffError, PRTERRINFO pErrInfo));
1411
1412 /**
1413 * Determins whether the element can be reused.
1414 *
1415 * This is for handling situations accessing the same file system twice, like
1416 * for both the source and destiation of a copy operation. This allows not only
1417 * sharing resources and avoid doing things twice, but also helps avoid file
1418 * sharing violations and inconsistencies araising from the image being updated
1419 * and read independently.
1420 *
1421 * @returns true if the element from @a pReuseSpec an be reused, false if not.
1422 * @param pProviderReg Pointer to the element provider registration.
1423 * @param pSpec The chain specification.
1424 * @param pElement The chain element specification.
1425 * @param pReuseSpec The chain specification of the existing chain.
1426 * @param pReuseElement The chain element specification of the existing
1427 * element that is being considered for reuse.
1428 */
1429 DECLCALLBACKMEMBER(bool, pfnCanReuseElement,(PCRTVFSCHAINELEMENTREG pProviderReg,
1430 PCRTVFSCHAINSPEC pSpec, PCRTVFSCHAINELEMSPEC pElement,
1431 PCRTVFSCHAINSPEC pReuseSpec, PCRTVFSCHAINELEMSPEC pReuseElement));
1432
1433 /** End marker (RTVFSCHAINELEMENTREG_VERSION). */
1434 uintptr_t uEndMarker;
1435} RTVFSCHAINELEMENTREG;
1436
1437/** The VFS chain element registration record version number. */
1438#define RTVFSCHAINELEMENTREG_VERSION RT_MAKE_U32_FROM_U8(0xff, 0x7f, 1, 0)
1439
1440
1441/**
1442 * Parses the specification.
1443 *
1444 * @returns IPRT status code.
1445 * @param pszSpec The specification string to parse.
1446 * @param fFlags Flags, see RTVFSCHAIN_PF_XXX.
1447 * @param enmDesiredType The object type the caller wants to interface with.
1448 * @param ppSpec Where to return the pointer to the parsed
1449 * specification. This must be freed by calling
1450 * RTVfsChainSpecFree. Will always be set (unless
1451 * invalid parameters.)
1452 * @param poffError Where to return the offset into the input
1453 * specification of what's causing trouble. Always
1454 * set, unless this argument causes an invalid pointer
1455 * error.
1456 */
1457RTDECL(int) RTVfsChainSpecParse(const char *pszSpec, uint32_t fFlags, RTVFSOBJTYPE enmDesiredType,
1458 PRTVFSCHAINSPEC *ppSpec, uint32_t *poffError);
1459
1460/** @name RTVfsChainSpecParse
1461 * @{ */
1462/** Mask of valid flags. */
1463#define RTVFSCHAIN_PF_VALID_MASK UINT32_C(0x00000000)
1464/** @} */
1465
1466/**
1467 * Checks and setups the chain.
1468 *
1469 * @returns IPRT status code.
1470 * @param pSpec The parsed specification.
1471 * @param pReuseSpec Spec to reuse if applicable. Optional.
1472 * @param phVfsObj Where to return the VFS object.
1473 * @param ppszFinalPath Where to return the pointer to the final path if
1474 * applicable. The caller needs to check whether this
1475 * is NULL or a path, in the former case nothing more
1476 * needs doing, whereas in the latter the caller must
1477 * perform the desired operation(s) on *phVfsObj using
1478 * the final path.
1479 * @param poffError Where to return the offset into the input
1480 * specification of what's causing trouble. Always
1481 * set, unless this argument causes an invalid pointer
1482 * error.
1483 * @param pErrInfo Where to return additional error information, if
1484 * available. Optional.
1485 */
1486RTDECL(int) RTVfsChainSpecCheckAndSetup(PRTVFSCHAINSPEC pSpec, PCRTVFSCHAINSPEC pReuseSpec,
1487 PRTVFSOBJ phVfsObj, const char **ppszFinalPath, uint32_t *poffError, PRTERRINFO pErrInfo);
1488
1489/**
1490 * Frees a parsed chain specification.
1491 *
1492 * @param pSpec What RTVfsChainSpecParse returned. NULL is
1493 * quietly ignored.
1494 */
1495RTDECL(void) RTVfsChainSpecFree(PRTVFSCHAINSPEC pSpec);
1496
1497/**
1498 * Registers a chain element provider.
1499 *
1500 * @returns IPRT status code
1501 * @param pRegRec The registration record.
1502 * @param fFromCtor Indicates where we're called from.
1503 */
1504RTDECL(int) RTVfsChainElementRegisterProvider(PRTVFSCHAINELEMENTREG pRegRec, bool fFromCtor);
1505
1506/**
1507 * Deregisters a chain element provider.
1508 *
1509 * @returns IPRT status code
1510 * @param pRegRec The registration record.
1511 * @param fFromDtor Indicates where we're called from.
1512 */
1513RTDECL(int) RTVfsChainElementDeregisterProvider(PRTVFSCHAINELEMENTREG pRegRec, bool fFromDtor);
1514
1515
1516/** @def RTVFSCHAIN_AUTO_REGISTER_ELEMENT_PROVIDER
1517 * Automatically registers a chain element provider using a global constructor
1518 * and destructor hack.
1519 *
1520 * @param pRegRec Pointer to the registration record.
1521 * @param name Some unique variable name prefix.
1522 */
1523
1524#ifdef __cplusplus
1525/**
1526 * Class used for registering a VFS chain element provider.
1527 */
1528class RTVfsChainElementAutoRegisterHack
1529{
1530private:
1531 /** The registration record, NULL if registration failed. */
1532 PRTVFSCHAINELEMENTREG m_pRegRec;
1533
1534public:
1535 RTVfsChainElementAutoRegisterHack(PRTVFSCHAINELEMENTREG a_pRegRec)
1536 : m_pRegRec(a_pRegRec)
1537 {
1538 int rc = RTVfsChainElementRegisterProvider(m_pRegRec, true);
1539 if (RT_FAILURE(rc))
1540 m_pRegRec = NULL;
1541 }
1542
1543 ~RTVfsChainElementAutoRegisterHack()
1544 {
1545 RTVfsChainElementDeregisterProvider(m_pRegRec, true);
1546 m_pRegRec = NULL;
1547 }
1548};
1549
1550# define RTVFSCHAIN_AUTO_REGISTER_ELEMENT_PROVIDER(pRegRec, name) \
1551 static RTVfsChainElementAutoRegisterHack name ## AutoRegistrationHack(pRegRec)
1552
1553#else
1554# define RTVFSCHAIN_AUTO_REGISTER_ELEMENT_PROVIDER(pRegRec, name) \
1555 extern void *name ## AutoRegistrationHack = \
1556 &Sorry_but_RTVFSCHAIN_AUTO_REGISTER_ELEMENT_PROVIDER_does_not_work_in_c_source_files
1557#endif
1558
1559
1560/**
1561 * Common worker for the 'stdfile' and 'open' providers for implementing
1562 * RTVFSCHAINELEMENTREG::pfnValidate.
1563 *
1564 * Stores the RTFILE_O_XXX flags in pSpec->uProvider.
1565 *
1566 * @returns IPRT status code.
1567 * @param pSpec The chain specification.
1568 * @param pElement The chain element specification to validate.
1569 * @param poffError Where to return error offset on failure. This is set to
1570 * the pElement->offSpec on input, so it only needs to be
1571 * adjusted if an argument is at fault.
1572 * @param pErrInfo Where to return additional error information, if
1573 * available. Optional.
1574 */
1575RTDECL(int) RTVfsChainValidateOpenFileOrIoStream(PRTVFSCHAINSPEC pSpec, PRTVFSCHAINELEMSPEC pElement,
1576 uint32_t *poffError, PRTERRINFO pErrInfo);
1577
1578
1579/** @} */
1580
1581
1582/** @} */
1583
1584RT_C_DECLS_END
1585
1586#endif /* !IPRT_INCLUDED_vfslowlevel_h */
1587
Note: See TracBrowser for help on using the repository browser.

© 2023 Oracle
Contact – Privacy policy – Terms of Use