VirtualBox

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

Last change on this file since 99901 was 98103, checked in by vboxsync, 17 months ago

Copyright year updates by scm.
  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 61.6 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 describing the bytes that are to be
925 * written.
926 * @param fBlocking If @c true, the call is blocking, if @c false it
927 * should not block.
928 * @param pcbRead Where return the number of bytes actually read.
929 * This is set it 0 by the caller. If NULL, try read
930 * all and fail if incomplete.
931 * @sa RTVfsIoStrmRead, RTVfsIoStrmSgRead, RTVfsFileRead,
932 * RTVfsFileReadAt, RTFileRead, RTFileReadAt.
933 */
934 DECLCALLBACKMEMBER(int, pfnRead,(void *pvThis, RTFOFF off, PCRTSGBUF pSgBuf, bool fBlocking, size_t *pcbRead));
935
936 /**
937 * Writes to the file/stream.
938 *
939 * @returns IPRT status code.
940 * @param pvThis The implementation specific file data.
941 * @param off Where to start wrinting, -1 for the current
942 * position.
943 * @param pSgBuf Gather buffers describing the bytes that are to be
944 * written.
945 * @param fBlocking If @c true, the call is blocking, if @c false it
946 * should not block.
947 * @param pcbWritten Where to return the number of bytes actually
948 * written. This is set it 0 by the caller. If
949 * NULL, try write it all and fail if incomplete.
950 * @note Optional, failing with VERR_WRITE_PROTECT if NULL.
951 * @sa RTFileWrite, RTFileWriteAt.
952 */
953 DECLCALLBACKMEMBER(int, pfnWrite,(void *pvThis, RTFOFF off, PCRTSGBUF pSgBuf, bool fBlocking, size_t *pcbWritten));
954
955 /**
956 * Flushes any pending data writes to the stream.
957 *
958 * @returns IPRT status code.
959 * @param pvThis The implementation specific file data.
960 * @sa RTFileFlush.
961 */
962 DECLCALLBACKMEMBER(int, pfnFlush,(void *pvThis));
963
964 /**
965 * Poll for events.
966 *
967 * @returns IPRT status code.
968 * @param pvThis The implementation specific file data.
969 * @param fEvents The events to poll for (RTPOLL_EVT_XXX).
970 * @param cMillies How long to wait for event to eventuate.
971 * @param fIntr Whether the wait is interruptible and can return
972 * VERR_INTERRUPTED (@c true) or if this condition
973 * should be hidden from the caller (@c false).
974 * @param pfRetEvents Where to return the event mask.
975 * @note Optional. If NULL, immediately return all requested non-error
976 * events, waiting for errors works like sleep.
977 * @sa RTPollSetAdd, RTPoll, RTPollNoResume.
978 */
979 DECLCALLBACKMEMBER(int, pfnPollOne,(void *pvThis, uint32_t fEvents, RTMSINTERVAL cMillies, bool fIntr,
980 uint32_t *pfRetEvents));
981
982 /**
983 * Tells the current file/stream position.
984 *
985 * @returns IPRT status code.
986 * @param pvThis The implementation specific file data.
987 * @param poffActual Where to return the actual offset.
988 * @sa RTFileTell
989 */
990 DECLCALLBACKMEMBER(int, pfnTell,(void *pvThis, PRTFOFF poffActual));
991
992 /**
993 * Skips @a cb ahead in the stream.
994 *
995 * @returns IPRT status code.
996 * @param pvThis The implementation specific file data.
997 * @param cb The number bytes to skip.
998 * @remarks This is optional and can be NULL.
999 */
1000 DECLCALLBACKMEMBER(int, pfnSkip,(void *pvThis, RTFOFF cb));
1001
1002 /**
1003 * Fills the stream with @a cb zeros.
1004 *
1005 * @returns IPRT status code.
1006 * @param pvThis The implementation specific file data.
1007 * @param cb The number of zero bytes to insert.
1008 * @remarks This is optional and can be NULL.
1009 */
1010 DECLCALLBACKMEMBER(int, pfnZeroFill,(void *pvThis, RTFOFF cb));
1011
1012 /** Marks the end of the structure (RTVFSIOSTREAMOPS_VERSION). */
1013 uintptr_t uEndMarker;
1014} RTVFSIOSTREAMOPS;
1015/** Pointer to const I/O stream operations. */
1016typedef RTVFSIOSTREAMOPS const *PCRTVFSIOSTREAMOPS;
1017
1018/** The RTVFSIOSTREAMOPS structure version. */
1019#define RTVFSIOSTREAMOPS_VERSION RT_MAKE_U32_FROM_U8(0xff,0x6f,1,0)
1020
1021/** @name RTVFSIOSTREAMOPS::fFeatures
1022 * @{ */
1023/** No scatter gather lists, thank you. */
1024#define RTVFSIOSTREAMOPS_FEAT_NO_SG RT_BIT_32(0)
1025/** Mask of the valid I/O stream feature flags. */
1026#define RTVFSIOSTREAMOPS_FEAT_VALID_MASK UINT32_C(0x00000001)
1027/** @} */
1028
1029
1030/**
1031 * Creates a new VFS I/O stream handle.
1032 *
1033 * @returns IPRT status code
1034 * @param pIoStreamOps The I/O stream operations.
1035 * @param cbInstance The size of the instance data.
1036 * @param fOpen The open flags. The minimum is the access mask.
1037 * @param hVfs The VFS handle to associate this I/O stream
1038 * with. NIL_VFS is ok.
1039 * @param hLock Handle to a custom lock to be used with the new
1040 * object. The reference is consumed. NIL and
1041 * special lock handles are fine.
1042 * @param phVfsIos Where to return the new handle.
1043 * @param ppvInstance Where to return the pointer to the instance data
1044 * (size is @a cbInstance).
1045 */
1046RTDECL(int) RTVfsNewIoStream(PCRTVFSIOSTREAMOPS pIoStreamOps, size_t cbInstance, uint32_t fOpen, RTVFS hVfs, RTVFSLOCK hLock,
1047 PRTVFSIOSTREAM phVfsIos, void **ppvInstance);
1048
1049
1050/**
1051 * Gets the private data of an I/O stream.
1052 *
1053 * @returns Pointer to the private data. NULL if the handle is invalid in some
1054 * way.
1055 * @param hVfsIos The I/O stream handle.
1056 * @param pIoStreamOps The I/O stream operations. This servers as a
1057 * sort of password.
1058 */
1059RTDECL(void *) RTVfsIoStreamToPrivate(RTVFSIOSTREAM hVfsIos, PCRTVFSIOSTREAMOPS pIoStreamOps);
1060
1061
1062/**
1063 * The file operations.
1064 *
1065 * @extends RTVFSIOSTREAMOPS
1066 * @extends RTVFSOBJSETOPS
1067 */
1068typedef struct RTVFSFILEOPS
1069{
1070 /** The I/O stream and basis object operations. */
1071 RTVFSIOSTREAMOPS Stream;
1072 /** The structure version (RTVFSFILEOPS_VERSION). */
1073 uint32_t uVersion;
1074 /** Reserved field, MBZ. */
1075 uint32_t fReserved;
1076 /** The object setter operations. */
1077 RTVFSOBJSETOPS ObjSet;
1078
1079 /**
1080 * Changes the current file position.
1081 *
1082 * @returns IPRT status code.
1083 * @param pvThis The implementation specific file data.
1084 * @param offSeek The offset to seek.
1085 * @param uMethod The seek method, i.e. what the seek is relative to.
1086 * @param poffActual Where to return the actual offset.
1087 * @sa RTFileSeek
1088 */
1089 DECLCALLBACKMEMBER(int, pfnSeek,(void *pvThis, RTFOFF offSeek, unsigned uMethod, PRTFOFF poffActual));
1090
1091 /**
1092 * Get the current file size.
1093 *
1094 * @returns IPRT status code.
1095 * @param pvThis The implementation specific file data.
1096 * @param pcbFile Where to store the current file size.
1097 * @sa RTFileQuerySize
1098 */
1099 DECLCALLBACKMEMBER(int, pfnQuerySize,(void *pvThis, uint64_t *pcbFile));
1100
1101 /**
1102 * Change the file size.
1103 *
1104 * @returns IPRT status code.
1105 * @retval VERR_ACCESS_DENIED if handle isn't writable.
1106 * @retval VERR_WRITE_PROTECT if read-only file system.
1107 * @retval VERR_FILE_TOO_BIG if cbSize is larger than what the file system can
1108 * theoretically deal with.
1109 * @retval VERR_DISK_FULL if the file system if full.
1110 * @retval VERR_NOT_SUPPORTED if fFlags indicates some operation that's not
1111 * supported by the file system / host operating system.
1112 *
1113 * @param pvThis The implementation specific file data.
1114 * @param pcbFile Where to store the current file size.
1115 * @param fFlags RTVFSFILE_SET_SIZE_F_XXX.
1116 * @note Optional. If NULL, VERR_WRITE_PROTECT will be returned.
1117 * @sa RTFileSetSize, RTFileSetAllocationSize
1118 */
1119 DECLCALLBACKMEMBER(int, pfnSetSize,(void *pvThis, uint64_t cbFile, uint32_t fFlags));
1120
1121 /**
1122 * Determine the maximum file size.
1123 *
1124 * This won't take amount of freespace into account, just the limitations of the
1125 * underlying file system / host operating system.
1126 *
1127 * @returns IPRT status code.
1128 * @param pvThis The implementation specific file data.
1129 * @param pcbMax Where to return the max file size.
1130 * @note Optional. If NULL, VERR_NOT_IMPLEMENTED will be returned.
1131 * @sa RTFileQueryMaxSizeEx
1132 */
1133 DECLCALLBACKMEMBER(int, pfnQueryMaxSize,(void *pvThis, uint64_t *pcbMax));
1134
1135 /** @todo There will be more methods here. */
1136
1137 /** Marks the end of the structure (RTVFSFILEOPS_VERSION). */
1138 uintptr_t uEndMarker;
1139} RTVFSFILEOPS;
1140/** Pointer to const file operations. */
1141typedef RTVFSFILEOPS const *PCRTVFSFILEOPS;
1142
1143/** The RTVFSFILEOPS structure version. */
1144#define RTVFSFILEOPS_VERSION RT_MAKE_U32_FROM_U8(0xff,0x7f,2,0)
1145
1146/**
1147 * Creates a new VFS file handle.
1148 *
1149 * @returns IPRT status code
1150 * @param pFileOps The file operations.
1151 * @param cbInstance The size of the instance data.
1152 * @param fOpen The open flags. The minimum is the access mask.
1153 * @param hVfs The VFS handle to associate this file with.
1154 * NIL_VFS is ok.
1155 * @param hLock Handle to a custom lock to be used with the new
1156 * object. The reference is consumed. NIL and
1157 * special lock handles are fine.
1158 * @param phVfsFile Where to return the new handle.
1159 * @param ppvInstance Where to return the pointer to the instance data
1160 * (size is @a cbInstance).
1161 */
1162RTDECL(int) RTVfsNewFile(PCRTVFSFILEOPS pFileOps, size_t cbInstance, uint32_t fOpen, RTVFS hVfs, RTVFSLOCK hLock,
1163 PRTVFSFILE phVfsFile, void **ppvInstance);
1164
1165
1166/** @defgroup grp_rt_vfs_ll_util VFS Utility APIs
1167 * @{ */
1168
1169/**
1170 * Parsed path.
1171 */
1172typedef struct RTVFSPARSEDPATH
1173{
1174 /** The length of the path in szCopy. */
1175 uint16_t cch;
1176 /** The number of path components. */
1177 uint16_t cComponents;
1178 /** Set if the path ends with slash, indicating that it's a directory
1179 * reference and not a file reference. The slash has been removed from
1180 * the copy. */
1181 bool fDirSlash;
1182 /** Set if absolute. */
1183 bool fAbsolute;
1184 /** The offset where each path component starts, i.e. the char after the
1185 * slash. The array has cComponents + 1 entries, where the final one is
1186 * cch + 1 so that one can always terminate the current component by
1187 * szPath[aoffComponent[i] - 1] = '\0'. */
1188 uint16_t aoffComponents[RTPATH_MAX / 2 + 1];
1189 /** A normalized copy of the path.
1190 * Reserve some extra space so we can be more relaxed about overflow
1191 * checks and terminator paddings, especially when recursing. */
1192 char szPath[RTPATH_MAX];
1193} RTVFSPARSEDPATH;
1194/** Pointer to a parsed path. */
1195typedef RTVFSPARSEDPATH *PRTVFSPARSEDPATH;
1196
1197/** The max accepted path length.
1198 * This must be a few chars shorter than RTVFSPARSEDPATH::szPath because we
1199 * use two terminators and wish be a little bit lazy with checking. */
1200#define RTVFSPARSEDPATH_MAX (RTPATH_MAX - 4)
1201
1202/**
1203 * Appends @a pszPath (relative) to the already parsed path @a pPath.
1204 *
1205 * @retval VINF_SUCCESS
1206 * @retval VERR_FILENAME_TOO_LONG
1207 * @retval VERR_INTERNAL_ERROR_4
1208 * @param pPath The parsed path to append @a pszPath onto.
1209 * This is both input and output.
1210 * @param pszPath The path to append. This must be relative.
1211 * @param piRestartComp The component to restart parsing at. This is
1212 * input/output. The input does not have to be
1213 * within the valid range. Optional.
1214 */
1215RTDECL(int) RTVfsParsePathAppend(PRTVFSPARSEDPATH pPath, const char *pszPath, uint16_t *piRestartComp);
1216
1217/**
1218 * Parses a path.
1219 *
1220 * @retval VINF_SUCCESS
1221 * @retval VERR_FILENAME_TOO_LONG
1222 * @param pPath Where to store the parsed path.
1223 * @param pszPath The path to parse. Absolute or relative to @a
1224 * pszCwd.
1225 * @param pszCwd The current working directory. Must be
1226 * absolute.
1227 */
1228RTDECL(int) RTVfsParsePath(PRTVFSPARSEDPATH pPath, const char *pszPath, const char *pszCwd);
1229
1230/**
1231 * Same as RTVfsParsePath except that it allocates a temporary buffer.
1232 *
1233 * @retval VINF_SUCCESS
1234 * @retval VERR_NO_TMP_MEMORY
1235 * @retval VERR_FILENAME_TOO_LONG
1236 * @param pszPath The path to parse. Absolute or relative to @a
1237 * pszCwd.
1238 * @param pszCwd The current working directory. Must be
1239 * absolute.
1240 * @param ppPath Where to store the pointer to the allocated
1241 * buffer containing the parsed path. This must
1242 * be freed by calling RTVfsParsePathFree. NULL
1243 * will be stored on failured.
1244 */
1245RTDECL(int) RTVfsParsePathA(const char *pszPath, const char *pszCwd, PRTVFSPARSEDPATH *ppPath);
1246
1247/**
1248 * Frees a buffer returned by RTVfsParsePathA.
1249 *
1250 * @param pPath The parsed path buffer to free. NULL is fine.
1251 */
1252RTDECL(void) RTVfsParsePathFree(PRTVFSPARSEDPATH pPath);
1253
1254/**
1255 * Dummy implementation of RTVFSIOSTREAMOPS::pfnPollOne.
1256 *
1257 * This handles the case where there is no chance any events my be raised and
1258 * all that is required is to wait according to the parameters.
1259 *
1260 * @returns IPRT status code.
1261 * @param fEvents The events to poll for (RTPOLL_EVT_XXX).
1262 * @param cMillies How long to wait for event to eventuate.
1263 * @param fIntr Whether the wait is interruptible and can return
1264 * VERR_INTERRUPTED (@c true) or if this condition
1265 * should be hidden from the caller (@c false).
1266 * @param pfRetEvents Where to return the event mask.
1267 * @sa RTVFSIOSTREAMOPS::pfnPollOne, RTPollSetAdd, RTPoll, RTPollNoResume.
1268 */
1269RTDECL(int) RTVfsUtilDummyPollOne(uint32_t fEvents, RTMSINTERVAL cMillies, bool fIntr, uint32_t *pfRetEvents);
1270
1271/** @} */
1272
1273
1274/** @defgroup grp_rt_vfs_lowlevel_chain VFS Chains (Low Level)
1275 * @ref grp_rt_vfs_chain
1276 * @{
1277 */
1278
1279/** Pointer to a VFS chain element registration record. */
1280typedef struct RTVFSCHAINELEMENTREG *PRTVFSCHAINELEMENTREG;
1281/** Pointer to a const VFS chain element registration record. */
1282typedef struct RTVFSCHAINELEMENTREG const *PCRTVFSCHAINELEMENTREG;
1283
1284/**
1285 * VFS chain element argument.
1286 */
1287typedef struct RTVFSCHAINELEMENTARG
1288{
1289 /** The string argument value. */
1290 char *psz;
1291 /** The specification offset of this argument. */
1292 uint16_t offSpec;
1293 /** Provider specific value. */
1294 uint64_t uProvider;
1295} RTVFSCHAINELEMENTARG;
1296/** Pointer to a VFS chain element argument. */
1297typedef RTVFSCHAINELEMENTARG *PRTVFSCHAINELEMENTARG;
1298
1299
1300/**
1301 * VFS chain element specification.
1302 */
1303typedef struct RTVFSCHAINELEMSPEC
1304{
1305 /** The provider name.
1306 * This can be NULL if this is the final component and it's just a path. */
1307 char *pszProvider;
1308 /** The input type, RTVFSOBJTYPE_INVALID if first. */
1309 RTVFSOBJTYPE enmTypeIn;
1310 /** The element type.
1311 * RTVFSOBJTYPE_END if this is the final component and it's just a path. */
1312 RTVFSOBJTYPE enmType;
1313 /** The input spec offset of this element. */
1314 uint16_t offSpec;
1315 /** The length of the input spec. */
1316 uint16_t cchSpec;
1317 /** The number of arguments. */
1318 uint32_t cArgs;
1319 /** Arguments. */
1320 PRTVFSCHAINELEMENTARG paArgs;
1321
1322 /** The provider. */
1323 PCRTVFSCHAINELEMENTREG pProvider;
1324 /** Provider specific value. */
1325 uint64_t uProvider;
1326 /** The object (with reference). */
1327 RTVFSOBJ hVfsObj;
1328} RTVFSCHAINELEMSPEC;
1329/** Pointer to a chain element specification. */
1330typedef RTVFSCHAINELEMSPEC *PRTVFSCHAINELEMSPEC;
1331/** Pointer to a const chain element specification. */
1332typedef RTVFSCHAINELEMSPEC const *PCRTVFSCHAINELEMSPEC;
1333
1334
1335/**
1336 * Parsed VFS chain specification.
1337 */
1338typedef struct RTVFSCHAINSPEC
1339{
1340 /** Open directory flags (RTFILE_O_XXX). */
1341 uint64_t fOpenFile;
1342 /** To be defined. */
1343 uint32_t fOpenDir;
1344 /** The type desired by the caller. */
1345 RTVFSOBJTYPE enmDesiredType;
1346 /** The number of elements. */
1347 uint32_t cElements;
1348 /** The elements. */
1349 PRTVFSCHAINELEMSPEC paElements;
1350} RTVFSCHAINSPEC;
1351/** Pointer to a parsed VFS chain specification. */
1352typedef RTVFSCHAINSPEC *PRTVFSCHAINSPEC;
1353/** Pointer to a const, parsed VFS chain specification. */
1354typedef RTVFSCHAINSPEC const *PCRTVFSCHAINSPEC;
1355
1356
1357/**
1358 * A chain element provider registration record.
1359 */
1360typedef struct RTVFSCHAINELEMENTREG
1361{
1362 /** The version (RTVFSCHAINELEMENTREG_VERSION). */
1363 uint32_t uVersion;
1364 /** Reserved, MBZ. */
1365 uint32_t fReserved;
1366 /** The provider name (unique). */
1367 const char *pszName;
1368 /** For chaining the providers. */
1369 RTLISTNODE ListEntry;
1370 /** Help text. */
1371 const char *pszHelp;
1372
1373 /**
1374 * Checks the element specification.
1375 *
1376 * This is allowed to parse arguments and use pSpec->uProvider and
1377 * pElement->paArgs[].uProvider to store information that pfnInstantiate and
1378 * pfnCanReuseElement may use later on, thus avoiding duplicating work/code.
1379 *
1380 * @returns IPRT status code.
1381 * @param pProviderReg Pointer to the element provider registration.
1382 * @param pSpec The chain specification.
1383 * @param pElement The chain element specification to validate.
1384 * @param poffError Where to return error offset on failure. This is
1385 * set to the pElement->offSpec on input, so it only
1386 * needs to be adjusted if an argument is at fault.
1387 * @param pErrInfo Where to return additional error information, if
1388 * available. Optional.
1389 */
1390 DECLCALLBACKMEMBER(int, pfnValidate,(PCRTVFSCHAINELEMENTREG pProviderReg, PRTVFSCHAINSPEC pSpec,
1391 PRTVFSCHAINELEMSPEC pElement, uint32_t *poffError, PRTERRINFO pErrInfo));
1392
1393 /**
1394 * Create a VFS object according to the element specification.
1395 *
1396 * @returns IPRT status code.
1397 * @param pProviderReg Pointer to the element provider registration.
1398 * @param pSpec The chain specification.
1399 * @param pElement The chain element specification to instantiate.
1400 * @param hPrevVfsObj Handle to the previous VFS object, NIL_RTVFSOBJ if
1401 * first.
1402 * @param phVfsObj Where to return the VFS object handle.
1403 * @param poffError Where to return error offset on failure. This is
1404 * set to the pElement->offSpec on input, so it only
1405 * needs to be adjusted if an argument is at fault.
1406 * @param pErrInfo Where to return additional error information, if
1407 * available. Optional.
1408 */
1409 DECLCALLBACKMEMBER(int, pfnInstantiate,(PCRTVFSCHAINELEMENTREG pProviderReg, PCRTVFSCHAINSPEC pSpec,
1410 PCRTVFSCHAINELEMSPEC pElement, RTVFSOBJ hPrevVfsObj,
1411 PRTVFSOBJ phVfsObj, uint32_t *poffError, PRTERRINFO pErrInfo));
1412
1413 /**
1414 * Determins whether the element can be reused.
1415 *
1416 * This is for handling situations accessing the same file system twice, like
1417 * for both the source and destiation of a copy operation. This allows not only
1418 * sharing resources and avoid doing things twice, but also helps avoid file
1419 * sharing violations and inconsistencies araising from the image being updated
1420 * and read independently.
1421 *
1422 * @returns true if the element from @a pReuseSpec an be reused, false if not.
1423 * @param pProviderReg Pointer to the element provider registration.
1424 * @param pSpec The chain specification.
1425 * @param pElement The chain element specification.
1426 * @param pReuseSpec The chain specification of the existing chain.
1427 * @param pReuseElement The chain element specification of the existing
1428 * element that is being considered for reuse.
1429 */
1430 DECLCALLBACKMEMBER(bool, pfnCanReuseElement,(PCRTVFSCHAINELEMENTREG pProviderReg,
1431 PCRTVFSCHAINSPEC pSpec, PCRTVFSCHAINELEMSPEC pElement,
1432 PCRTVFSCHAINSPEC pReuseSpec, PCRTVFSCHAINELEMSPEC pReuseElement));
1433
1434 /** End marker (RTVFSCHAINELEMENTREG_VERSION). */
1435 uintptr_t uEndMarker;
1436} RTVFSCHAINELEMENTREG;
1437
1438/** The VFS chain element registration record version number. */
1439#define RTVFSCHAINELEMENTREG_VERSION RT_MAKE_U32_FROM_U8(0xff, 0x7f, 1, 0)
1440
1441
1442/**
1443 * Parses the specification.
1444 *
1445 * @returns IPRT status code.
1446 * @param pszSpec The specification string to parse.
1447 * @param fFlags Flags, see RTVFSCHAIN_PF_XXX.
1448 * @param enmDesiredType The object type the caller wants to interface with.
1449 * @param ppSpec Where to return the pointer to the parsed
1450 * specification. This must be freed by calling
1451 * RTVfsChainSpecFree. Will always be set (unless
1452 * invalid parameters.)
1453 * @param poffError Where to return the offset into the input
1454 * specification of what's causing trouble. Always
1455 * set, unless this argument causes an invalid pointer
1456 * error.
1457 */
1458RTDECL(int) RTVfsChainSpecParse(const char *pszSpec, uint32_t fFlags, RTVFSOBJTYPE enmDesiredType,
1459 PRTVFSCHAINSPEC *ppSpec, uint32_t *poffError);
1460
1461/** @name RTVfsChainSpecParse
1462 * @{ */
1463/** Mask of valid flags. */
1464#define RTVFSCHAIN_PF_VALID_MASK UINT32_C(0x00000000)
1465/** @} */
1466
1467/**
1468 * Checks and setups the chain.
1469 *
1470 * @returns IPRT status code.
1471 * @param pSpec The parsed specification.
1472 * @param pReuseSpec Spec to reuse if applicable. Optional.
1473 * @param phVfsObj Where to return the VFS object.
1474 * @param ppszFinalPath Where to return the pointer to the final path if
1475 * applicable. The caller needs to check whether this
1476 * is NULL or a path, in the former case nothing more
1477 * needs doing, whereas in the latter the caller must
1478 * perform the desired operation(s) on *phVfsObj using
1479 * the final path.
1480 * @param poffError Where to return the offset into the input
1481 * specification of what's causing trouble. Always
1482 * set, unless this argument causes an invalid pointer
1483 * error.
1484 * @param pErrInfo Where to return additional error information, if
1485 * available. Optional.
1486 */
1487RTDECL(int) RTVfsChainSpecCheckAndSetup(PRTVFSCHAINSPEC pSpec, PCRTVFSCHAINSPEC pReuseSpec,
1488 PRTVFSOBJ phVfsObj, const char **ppszFinalPath, uint32_t *poffError, PRTERRINFO pErrInfo);
1489
1490/**
1491 * Frees a parsed chain specification.
1492 *
1493 * @param pSpec What RTVfsChainSpecParse returned. NULL is
1494 * quietly ignored.
1495 */
1496RTDECL(void) RTVfsChainSpecFree(PRTVFSCHAINSPEC pSpec);
1497
1498/**
1499 * Registers a chain element provider.
1500 *
1501 * @returns IPRT status code
1502 * @param pRegRec The registration record.
1503 * @param fFromCtor Indicates where we're called from.
1504 */
1505RTDECL(int) RTVfsChainElementRegisterProvider(PRTVFSCHAINELEMENTREG pRegRec, bool fFromCtor);
1506
1507/**
1508 * Deregisters a chain element provider.
1509 *
1510 * @returns IPRT status code
1511 * @param pRegRec The registration record.
1512 * @param fFromDtor Indicates where we're called from.
1513 */
1514RTDECL(int) RTVfsChainElementDeregisterProvider(PRTVFSCHAINELEMENTREG pRegRec, bool fFromDtor);
1515
1516
1517/** @def RTVFSCHAIN_AUTO_REGISTER_ELEMENT_PROVIDER
1518 * Automatically registers a chain element provider using a global constructor
1519 * and destructor hack.
1520 *
1521 * @param pRegRec Pointer to the registration record.
1522 * @param name Some unique variable name prefix.
1523 */
1524
1525#ifdef __cplusplus
1526/**
1527 * Class used for registering a VFS chain element provider.
1528 */
1529class RTVfsChainElementAutoRegisterHack
1530{
1531private:
1532 /** The registration record, NULL if registration failed. */
1533 PRTVFSCHAINELEMENTREG m_pRegRec;
1534
1535public:
1536 RTVfsChainElementAutoRegisterHack(PRTVFSCHAINELEMENTREG a_pRegRec)
1537 : m_pRegRec(a_pRegRec)
1538 {
1539 int rc = RTVfsChainElementRegisterProvider(m_pRegRec, true);
1540 if (RT_FAILURE(rc))
1541 m_pRegRec = NULL;
1542 }
1543
1544 ~RTVfsChainElementAutoRegisterHack()
1545 {
1546 RTVfsChainElementDeregisterProvider(m_pRegRec, true);
1547 m_pRegRec = NULL;
1548 }
1549};
1550
1551# define RTVFSCHAIN_AUTO_REGISTER_ELEMENT_PROVIDER(pRegRec, name) \
1552 static RTVfsChainElementAutoRegisterHack name ## AutoRegistrationHack(pRegRec)
1553
1554#else
1555# define RTVFSCHAIN_AUTO_REGISTER_ELEMENT_PROVIDER(pRegRec, name) \
1556 extern void *name ## AutoRegistrationHack = \
1557 &Sorry_but_RTVFSCHAIN_AUTO_REGISTER_ELEMENT_PROVIDER_does_not_work_in_c_source_files
1558#endif
1559
1560
1561/**
1562 * Common worker for the 'stdfile' and 'open' providers for implementing
1563 * RTVFSCHAINELEMENTREG::pfnValidate.
1564 *
1565 * Stores the RTFILE_O_XXX flags in pSpec->uProvider.
1566 *
1567 * @returns IPRT status code.
1568 * @param pSpec The chain specification.
1569 * @param pElement The chain element specification to validate.
1570 * @param poffError Where to return error offset on failure. This is set to
1571 * the pElement->offSpec on input, so it only needs to be
1572 * adjusted if an argument is at fault.
1573 * @param pErrInfo Where to return additional error information, if
1574 * available. Optional.
1575 */
1576RTDECL(int) RTVfsChainValidateOpenFileOrIoStream(PRTVFSCHAINSPEC pSpec, PRTVFSCHAINELEMSPEC pElement,
1577 uint32_t *poffError, PRTERRINFO pErrInfo);
1578
1579
1580/** @} */
1581
1582
1583/** @} */
1584
1585RT_C_DECLS_END
1586
1587#endif /* !IPRT_INCLUDED_vfslowlevel_h */
1588
Note: See TracBrowser for help on using the repository browser.

© 2023 Oracle
Contact – Privacy policy – Terms of Use