summaryrefslogtreecommitdiffstats
path: root/include/iprt/vfs.h
blob: a45c8817be7b60d1c54ccb59c31454d7495cf316 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
1595
1596
1597
1598
1599
1600
1601
1602
1603
1604
1605
1606
1607
1608
1609
1610
1611
1612
1613
1614
1615
1616
1617
1618
1619
1620
1621
1622
1623
1624
1625
1626
1627
1628
1629
1630
1631
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
1644
1645
1646
1647
1648
1649
1650
1651
1652
1653
1654
1655
1656
1657
1658
1659
1660
1661
1662
1663
1664
1665
1666
1667
1668
1669
1670
1671
1672
1673
1674
1675
1676
1677
1678
1679
1680
1681
1682
1683
1684
1685
1686
1687
1688
1689
1690
1691
1692
1693
1694
1695
1696
1697
1698
1699
1700
1701
1702
1703
1704
1705
1706
1707
1708
1709
1710
1711
1712
1713
1714
1715
1716
1717
1718
1719
1720
1721
1722
1723
1724
1725
1726
1727
1728
1729
1730
1731
1732
1733
1734
1735
1736
1737
1738
1739
1740
1741
1742
1743
1744
1745
1746
1747
1748
1749
1750
1751
1752
1753
1754
1755
1756
1757
1758
1759
1760
1761
1762
1763
1764
1765
1766
1767
1768
1769
1770
1771
1772
1773
1774
1775
1776
1777
1778
1779
1780
1781
1782
1783
1784
1785
1786
1787
1788
1789
1790
1791
1792
1793
1794
1795
1796
1797
1798
1799
1800
1801
1802
1803
1804
1805
1806
1807
1808
1809
1810
1811
1812
1813
1814
1815
1816
1817
1818
1819
1820
1821
1822
1823
1824
1825
1826
1827
1828
1829
1830
1831
1832
1833
1834
1835
1836
1837
1838
1839
1840
1841
1842
1843
1844
1845
1846
1847
1848
1849
1850
1851
1852
1853
1854
1855
1856
1857
1858
1859
1860
1861
1862
1863
1864
1865
1866
1867
1868
1869
1870
1871
1872
1873
1874
1875
1876
1877
1878
1879
1880
1881
1882
1883
1884
1885
1886
1887
1888
1889
1890
1891
1892
1893
1894
1895
1896
1897
1898
1899
1900
1901
1902
1903
1904
1905
1906
1907
1908
1909
1910
1911
1912
1913
1914
1915
1916
1917
1918
1919
1920
1921
1922
1923
1924
1925
1926
1927
1928
1929
1930
1931
1932
1933
1934
1935
1936
1937
1938
1939
1940
1941
1942
1943
1944
1945
1946
1947
1948
1949
1950
1951
1952
1953
1954
1955
1956
1957
1958
1959
1960
1961
1962
1963
1964
1965
1966
1967
1968
1969
1970
1971
1972
1973
1974
1975
1976
1977
1978
1979
1980
1981
1982
1983
1984
1985
1986
1987
1988
1989
1990
1991
1992
1993
1994
1995
1996
1997
1998
1999
2000
2001
2002
2003
2004
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
/** @file
 * IPRT - Virtual Filesystem.
 */

/*
 * Copyright (C) 2010-2023 Oracle and/or its affiliates.
 *
 * This file is part of VirtualBox base platform packages, as
 * available from https://www.virtualbox.org.
 *
 * This program is free software; you can redistribute it and/or
 * modify it under the terms of the GNU General Public License
 * as published by the Free Software Foundation, in version 3 of the
 * License.
 *
 * This program is distributed in the hope that it will be useful, but
 * WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program; if not, see <https://www.gnu.org/licenses>.
 *
 * The contents of this file may alternatively be used under the terms
 * of the Common Development and Distribution License Version 1.0
 * (CDDL), a copy of it is provided in the "COPYING.CDDL" file included
 * in the VirtualBox distribution, in which case the provisions of the
 * CDDL are applicable instead of those of the GPL.
 *
 * You may elect to license modified versions of this file under the
 * terms and conditions of either the GPL or the CDDL or both.
 *
 * SPDX-License-Identifier: GPL-3.0-only OR CDDL-1.0
 */

#ifndef IPRT_INCLUDED_vfs_h
#define IPRT_INCLUDED_vfs_h
#ifndef RT_WITHOUT_PRAGMA_ONCE
# pragma once
#endif

#include <iprt/cdefs.h>
#include <iprt/types.h>
#include <iprt/dir.h>
#include <iprt/fs.h>
#include <iprt/handle.h>
#include <iprt/symlink.h>
#include <iprt/sg.h>
#include <iprt/time.h>


RT_C_DECLS_BEGIN

/** @defgroup grp_rt_vfs   RTVfs - Virtual Filesystem
 * @ingroup grp_rt
 *
 * The virtual filesystem APIs are intended to make it possible to work on
 * container files, file system sub-trees, file system overlays and other custom
 * filesystem configurations.  It also makes it possible to create filters, like
 * automatically gunzipping a tar.gz file before feeding it to the RTTar API for
 * unpacking - or vice versa.
 *
 * The virtual filesystem APIs are intended to mirror the RTDir, RTFile, RTPath
 * and RTFs APIs pretty closely so that rewriting a piece of code to work with
 * it should be easy.  However there are some differences to the way the APIs
 * works and the user should heed the documentation.  The differences are
 * usually motivated by simplification and in some case to make the VFS more
 * flexible.
 *
 * @{
 */

/**
 * The object type.
 */
typedef enum RTVFSOBJTYPE
{
    /** Invalid type. */
    RTVFSOBJTYPE_INVALID = 0,
    /** Pure base object.
     * This is returned by the filesystem stream to represent directories,
     * devices, fifos and similar that needs to be created. */
    RTVFSOBJTYPE_BASE,
    /** Virtual filesystem. */
    RTVFSOBJTYPE_VFS,
    /** Filesystem stream. */
    RTVFSOBJTYPE_FS_STREAM,
    /** Pure I/O stream. */
    RTVFSOBJTYPE_IO_STREAM,
    /** Directory. */
    RTVFSOBJTYPE_DIR,
    /** File. */
    RTVFSOBJTYPE_FILE,
    /** Symbolic link. */
    RTVFSOBJTYPE_SYMLINK,
    /** End of valid object types. */
    RTVFSOBJTYPE_END,
    /** Pure I/O stream. */
    RTVFSOBJTYPE_32BIT_HACK = 0x7fffffff
} RTVFSOBJTYPE;
/** Pointer to a VFS object type. */
typedef RTVFSOBJTYPE *PRTVFSOBJTYPE;

/**
 * Translates a RTVFSOBJTYPE value into a string.
 *
 * @returns Pointer to readonly name.
 * @param   enmType             The object type to name.
 */
RTDECL(const char *) RTVfsTypeName(RTVFSOBJTYPE enmType);



/** @name RTVfsCreate flags
 * @{ */
/** Whether the file system is read-only. */
#define RTVFS_C_READONLY                RT_BIT(0)
/** Whether we the VFS should be thread safe (i.e. automaticaly employ
 * locks). */
#define RTVFS_C_THREAD_SAFE             RT_BIT(1)
/** @}  */

/**
 * Creates an empty virtual filesystem.
 *
 * @returns IPRT status code.
 * @param   pszName     Name, for logging and such.
 * @param   fFlags      Flags, MBZ.
 * @param   phVfs       Where to return the VFS handle.  Release the returned
 *                      reference by calling RTVfsRelease.
 */
RTDECL(int)         RTVfsCreate(const char *pszName, uint32_t fFlags, PRTVFS phVfs);
RTDECL(uint32_t)    RTVfsRetain(RTVFS hVfs);
RTDECL(uint32_t)    RTVfsRetainDebug(RTVFS hVfs, RT_SRC_POS_DECL);
RTDECL(uint32_t)    RTVfsRelease(RTVFS hVfs);

/** @name RTVFSMNT_F_XXX - Flags for RTVfsMount
 * @{ */
/** Mount read-only. */
#define RTVFSMNT_F_READ_ONLY            RT_BIT_32(0)
/** Purpose is . */
#define RTVFSMNT_F_FOR_RANGE_IN_USE     RT_BIT_32(1)
/** Valid mask. */
#define RTVFSMNT_F_VALID_MASK           UINT32_C(0x00000003)
/** @} */

/**
 * Does the file system detection and mounting.
 *
 * @returns IPRT status code.
 * @retval  VERR_VFS_UNSUPPORTED_FORMAT if not recognized as a support file
 *          system.
 * @param   hVfsFileIn      The file handle of the volume.
 * @param   fFlags          RTVFSMTN_F_XXX.
 * @param   phVfs           Where to return the VFS handle on success.
 * @param   pErrInfo        Where to return additional error information.
 *                          Optional.
 */
RTDECL(int)         RTVfsMountVol(RTVFSFILE hVfsFileIn, uint32_t fFlags, PRTVFS phVfs, PRTERRINFO pErrInfo);

RTDECL(int)         RTVfsAttach(RTVFS hVfs, const char *pszMountPoint, uint32_t fFlags, RTVFS hVfsAttach);
RTDECL(int)         RTVfsDetach(RTVFS hVfs, const char *pszMountPoint, RTVFS hVfsToDetach, PRTVFS *phVfsDetached);
RTDECL(uint32_t)    RTVfsGetAttachmentCount(RTVFS hVfs);
RTDECL(int)         RTVfsGetAttachment(RTVFS hVfs, uint32_t iOrdinal, PRTVFS *phVfsAttached, uint32_t *pfFlags,
                                       char *pszMountPoint, size_t cbMountPoint);

/**
 * Opens the root director of the given VFS.
 *
 * @returns IPRT status code.
 * @param   hVfs        VFS handle.
 * @param   phDir       Where to return the root directory handle.
 */
RTDECL(int) RTVfsOpenRoot(RTVFS hVfs, PRTVFSDIR phDir);

/**
 * Queries information about a object in the virtual filesystem.
 *
 * @returns IPRT Status code.
 * @param   hVfs        VFS handle.
 * @param   pszPath     Path to the object, relative to the VFS root.
 * @param   pObjInfo    Where to return info.
 * @param   enmAddAttr  What to return.
 * @param   fFlags      RTPATH_F_XXX.
 * @sa      RTPathQueryInfoEx, RTVfsDirQueryPathInfo, RTVfsObjQueryInfo
 */
RTDECL(int) RTVfsQueryPathInfo(RTVFS hVfs, const char *pszPath, PRTFSOBJINFO pObjInfo,
                               RTFSOBJATTRADD enmAddAttr, uint32_t fFlags);

/**
 * Checks whether a given range is in use by the virtual filesystem.
 *
 * @returns IPRT status code.
 * @param   hVfs        VFS handle.
 * @param   off         Start offset to check.
 * @param   cb          Number of bytes to check.
 * @param   pfUsed      Where to store the result.
 */
RTDECL(int) RTVfsQueryRangeState(RTVFS hVfs, uint64_t off, size_t cb, bool *pfUsed);

/**
 * Queries the volume label.
 *
 * @returns IPRT status code.
 * @param   hVfs            VFS handle.
 * @param   fAlternative    For use with ISO files to retrieve the primary lable
 *                          rather than the joliet / UDF one that the mount
 *                          options would indicate.  For other file systems, as
 *                          well for ISO not mounted in joliet / UDF mode, the
 *                          flag is ignored.
 * @param   pszLabel        Where to store the lable.
 * @param   cbLabel         Size of the buffer @a pszLable points at.
 * @param   pcbActual       Where to return the label length, including the
 *                          terminator.  In case of VERR_BUFFER_OVERFLOW
 *                          returns, this will be set to the required buffer
 *                          size.  Optional.
 */
RTDECL(int) RTVfsQueryLabel(RTVFS hVfs, bool fAlternative, char *pszLabel, size_t cbLabel, size_t *pcbActual);


/** @defgroup grp_rt_vfs_obj        VFS Base Object API
 * @{
 */

/**
 * Retains a reference to the VFS base object handle.
 *
 * @returns New reference count on success, UINT32_MAX on failure.
 * @param   hVfsObj         The VFS base object handle.
 */
RTDECL(uint32_t)        RTVfsObjRetain(RTVFSOBJ hVfsObj);
RTDECL(uint32_t)        RTVfsObjRetainDebug(RTVFSOBJ hVfsObj, RT_SRC_POS_DECL);

/**
 * Releases a reference to the VFS base handle.
 *
 * @returns New reference count on success (0 if closed), UINT32_MAX on failure.
 * @param   hVfsObj         The VFS base object handle.
 */
RTDECL(uint32_t)        RTVfsObjRelease(RTVFSOBJ hVfsObj);

/** @name RTVFSOBJ_F_XXX - Flags or RTVfsObjOpen and RTVfsDirOpenObj.
 * @note Must leave space for RTPATH_F_XXX.
 * @{ */
/** Directory (RTFS_TYPE_DIRECTORY). */
#define RTVFSOBJ_F_OPEN_DIRECTORY           RT_BIT_32(8)
/** Symbolic link (RTFS_TYPE_SYMLINK). */
#define RTVFSOBJ_F_OPEN_SYMLINK             RT_BIT_32(9)
/** Regular file (RTFS_TYPE_FILE). */
#define RTVFSOBJ_F_OPEN_FILE                RT_BIT_32(10)
/** Character device (RTFS_TYPE_DEV_CHAR). */
#define RTVFSOBJ_F_OPEN_DEV_CHAR            RT_BIT_32(11)
/** Block device (RTFS_TYPE_DEV_BLOCK). */
#define RTVFSOBJ_F_OPEN_DEV_BLOCK           RT_BIT_32(12)
/** Named pipe (fifo) (RTFS_TYPE_FIFO). */
#define RTVFSOBJ_F_OPEN_FIFO                RT_BIT_32(13)
/** Socket (RTFS_TYPE_SOCKET). */
#define RTVFSOBJ_F_OPEN_SOCKET              RT_BIT_32(14)
/** Mounted VFS. */
#define RTVFSOBJ_F_OPEN_MOUNT               RT_BIT_32(15)
/** Mask object types we wish to open. */
#define RTVFSOBJ_F_OPEN_MASK                UINT32_C(0x0000ff00)
/** Any kind of object that translates to RTVFSOBJTYPE_FILE. */
#define RTVFSOBJ_F_OPEN_ANY_FILE            (RTVFSOBJ_F_OPEN_FILE | RTVFSOBJ_F_OPEN_DEV_BLOCK)
/** Any kind of object that translates to RTVFSOBJTYPE_IOS or
 *  RTVFSOBJTYPE_FILE. */
#define RTVFSOBJ_F_OPEN_ANY_IO_STREAM       (  RTVFSOBJ_F_ANY_OPEN_FILE | RTVFSOBJ_F_DEV_OPEN_BLOCK \
                                             | RTVFSOBJ_F_OPEN_FIFO     | RTVFSOBJ_F_OPEN_SOCKET)
/** Any kind of object. */
#define RTVFSOBJ_F_OPEN_ANY                 RTVFSOBJ_F_OPEN_MASK

/** Do't create anything, return file not found. */
#define RTVFSOBJ_F_CREATE_NOTHING           UINT32_C(0x00000000)
/** Create a file if the if the object was not found and the RTFILE_O_XXX
 * flags allows it. */
#define RTVFSOBJ_F_CREATE_FILE              UINT32_C(0x00010000)
/** Create a directory if the object was not found and the RTFILE_O_XXX
 * flags allows it. */
#define RTVFSOBJ_F_CREATE_DIRECTORY         UINT32_C(0x00020000)
/** The creation type mask. */
#define RTVFSOBJ_F_CREATE_MASK              UINT32_C(0x00070000)

/** Indicate that this call is for traversal.
 * @internal only  */
#define RTVFSOBJ_F_TRAVERSAL                RT_BIT_32(31)
/** Valid mask for external callers. */
#define RTVFSOBJ_F_VALID_MASK               UINT32_C(0x0007ff00)
/** @} */

/**
 * Opens any file system object in the given VFS.
 *
 * @returns IPRT status code.
 * @param   hVfs            The VFS to open the object within.
 * @param   pszPath         Path to the file.
 * @param   fFileOpen       RTFILE_O_XXX flags.
 * @param   fObjFlags       More flags: RTVFSOBJ_F_XXX, RTPATH_F_XXX.
 * @param   phVfsObj        Where to return the object handle.
 * @sa      RTVfsDirOpenObj, RTVfsDirOpenDir, RTVfsDirOpenFile
 */
RTDECL(int)             RTVfsObjOpen(RTVFS hVfs, const char *pszPath, uint64_t fFileOpen, uint32_t fObjFlags, PRTVFSOBJ phVfsObj);

/**
 * Query information about the object.
 *
 * @returns IPRT status code.
 * @retval  VERR_NOT_SUPPORTED if the @a enmAddAttr value is not handled by the
 *          implementation.
 *
 * @param   hVfsObj         The VFS object handle.
 * @param   pObjInfo        Where to return the info.
 * @param   enmAddAttr      Which additional attributes should be retrieved.
 * @sa      RTVfsIoStrmQueryInfo, RTVfsFileQueryInfo, RTFileQueryInfo,
 *          RTPathQueryInfo
 */
RTDECL(int)             RTVfsObjQueryInfo(RTVFSOBJ hVfsObj, PRTFSOBJINFO pObjInfo, RTFSOBJATTRADD enmAddAttr);

/**
 * Sets the file mode for the given VFS object.
 *
 * @returns IPRT status code.
 * @retval  VERR_INVALID_FUNCTION if the object type has no file mode to set.
 *          Only directories, files and symbolic links support this operation.
 *
 * @param   hVfsObj         The VFS object handle.
 * @param   fMode           The mode mask.
 * @param   fMask           The bits in the mode mask which should be changed.
 */
RTDECL(int)             RTVfsObjSetMode(RTVFSOBJ hVfsObj, RTFMODE fMode, RTFMODE fMask);

/**
 * Sets one or more timestamps for the given VFS object.
 *
 * @returns IPRT status code.
 * @retval  VERR_INVALID_FUNCTION if the object type has no file mode to set.
 *          Only directories, files and symbolic links support this operation.
 *
 * @param   hVfsObj             The VFS object handle.
 * @param   pAccessTime         Pointer to the new access time. NULL if not to
 *                              be changed.
 * @param   pModificationTime   Pointer to the new modifcation time. NULL if not
 *                              to be changed.
 * @param   pChangeTime         Pointer to the new change time. NULL if not to
 *                              be changed.
 * @param   pBirthTime          Pointer to the new time of birth. NULL if not to
 *                              be changed.
 *
 * @remarks See RTFileSetTimes for restrictions and behavior imposed by the
 *          host OS or underlying VFS provider.
 * @sa      RTFileSetTimes, RTPathSetTimes
 */
RTDECL(int)             RTVfsObjSetTimes(RTVFSOBJ hVfsObj, PCRTTIMESPEC pAccessTime, PCRTTIMESPEC pModificationTime,
                                         PCRTTIMESPEC pChangeTime, PCRTTIMESPEC pBirthTime);

/**
 * Set the unix style owner and group on the given VFS object.
 *
 * @returns IPRT status code.
 * @retval  VERR_INVALID_FUNCTION if the object type has no file mode to set.
 *          Only directories, files and symbolic links support this operation.
 *
 * @param   hVfsObj         The VFS object handle.
 * @param   uid             The user ID of the new owner.  NIL_RTUID if
 *                          unchanged.
 * @param   gid             The group ID of the new owner group. NIL_RTGID if
 *                          unchanged.
 *
 * @sa      RTFileSetOwner, RTPathSetOwner.
 */
RTDECL(int)             RTVfsObjSetOwner(RTVFSOBJ hVfsObj, RTUID uid, RTGID gid);


/**
 * Gets the type of a VFS object.
 *
 * @returns The VFS object type on success, RTVFSOBJTYPE_INVALID on failure.
 * @param   hVfsObj         The VFS base object handle.
 */
RTDECL(RTVFSOBJTYPE)    RTVfsObjGetType(RTVFSOBJ hVfsObj);

/**
 * Converts a VFS base object handle to a VFS handle.
 *
 * @returns Referenced handle on success, NIL on failure.
 * @param   hVfsObj         The VFS base object handle.
 */
RTDECL(RTVFS)           RTVfsObjToVfs(RTVFSOBJ hVfsObj);

/**
 * Converts a VFS base object handle to a VFS filesystem stream handle.
 *
 * @returns Referenced handle on success, NIL on failure.
 * @param   hVfsObj         The VFS base object handle.
 */
RTDECL(RTVFSFSSTREAM)   RTVfsObjToFsStream(RTVFSOBJ hVfsObj);

/**
 * Converts a VFS base object handle to a VFS directory handle.
 *
 * @returns Referenced handle on success, NIL on failure.
 * @param   hVfsObj         The VFS base object handle.
 */
RTDECL(RTVFSDIR)        RTVfsObjToDir(RTVFSOBJ hVfsObj);

/**
 * Converts a VFS base object handle to a VFS I/O stream handle.
 *
 * @returns Referenced handle on success, NIL on failure.
 * @param   hVfsObj         The VFS base object handle.
 */
RTDECL(RTVFSIOSTREAM)   RTVfsObjToIoStream(RTVFSOBJ hVfsObj);

/**
 * Converts a VFS base object handle to a VFS file handle.
 *
 * @returns Referenced handle on success, NIL on failure.
 * @param   hVfsObj         The VFS base object handle.
 */
RTDECL(RTVFSFILE)       RTVfsObjToFile(RTVFSOBJ hVfsObj);

/**
 * Converts a VFS base object handle to a VFS symbolic link handle.
 *
 * @returns Referenced handle on success, NIL on failure.
 * @param   hVfsObj         The VFS base object handle.
 */
RTDECL(RTVFSSYMLINK)    RTVfsObjToSymlink(RTVFSOBJ hVfsObj);


/**
 * Converts a VFS handle to a VFS base object handle.
 *
 * @returns Referenced handle on success, NIL if the input handle was invalid.
 * @param   hVfs            The VFS handle.
 */
RTDECL(RTVFSOBJ)        RTVfsObjFromVfs(RTVFS hVfs);

/**
 * Converts a VFS filesystem stream handle to a VFS base object handle.
 *
 * @returns Referenced handle on success, NIL if the input handle was invalid.
 * @param   hVfsFss         The VFS filesystem stream handle.
 */
RTDECL(RTVFSOBJ)        RTVfsObjFromFsStream(RTVFSFSSTREAM hVfsFss);

/**
 * Converts a VFS directory handle to a VFS base object handle.
 *
 * @returns Referenced handle on success, NIL if the input handle was invalid.
 * @param   hVfsDir          The VFS directory handle.
 */
RTDECL(RTVFSOBJ)        RTVfsObjFromDir(RTVFSDIR hVfsDir);

/**
 * Converts a VFS I/O stream handle to a VFS base object handle.
 *
 * @returns Referenced handle on success, NIL if the input handle was invalid.
 * @param   hVfsIos          The VFS I/O stream handle.
 */
RTDECL(RTVFSOBJ)        RTVfsObjFromIoStream(RTVFSIOSTREAM hVfsIos);

/**
 * Converts a VFS file handle to a VFS base object handle.
 *
 * @returns Referenced handle on success, NIL if the input handle was invalid.
 * @param   hVfsFile         The VFS file handle.
 */
RTDECL(RTVFSOBJ)        RTVfsObjFromFile(RTVFSFILE hVfsFile);

/**
 * Converts a VFS symbolic link handle to a VFS base object handle.
 *
 * @returns Referenced handle on success, NIL if the input handle was invalid.
 * @param   hVfsSym            The VFS symbolic link handle.
 */
RTDECL(RTVFSOBJ)        RTVfsObjFromSymlink(RTVFSSYMLINK hVfsSym);

/** @} */


/** @defgroup grp_rt_vfs_fsstream   VFS Filesystem Stream API
 *
 * Filesystem streams are for tar, cpio and similar.  Any virtual filesystem can
 * be turned into a filesystem stream using RTVfsFsStrmFromVfs.
 *
 * @{
 */

RTDECL(uint32_t)    RTVfsFsStrmRetain(RTVFSFSSTREAM hVfsFss);
RTDECL(uint32_t)    RTVfsFsStrmRetainDebug(RTVFSFSSTREAM hVfsFss, RT_SRC_POS_DECL);
RTDECL(uint32_t)    RTVfsFsStrmRelease(RTVFSFSSTREAM hVfsFss);
RTDECL(int)         RTVfsFsStrmQueryInfo(RTVFSFSSTREAM hVfsFss, PRTFSOBJINFO pObjInfo, RTFSOBJATTRADD enmAddAttr);

/**
 * Gets the next object in the stream.
 *
 * This call may affect the stream posision of a previously returned object.
 *
 * The type of object returned here typically boils down to three types:
 *      - I/O streams (representing files),
 *      - symbolic links
 *      - base object
 * The base objects represent anything not convered by the two other, i.e.
 * directories, device nodes, fifos, sockets and whatnot.  The details can be
 * queried using RTVfsObjQueryInfo.
 *
 * That said, absolutely any object except for filesystem stream objects can be
 * returned by this call.  Any generic code is adviced to just deal with it all.
 *
 * @returns IPRT status code.
 * @retval  VINF_SUCCESS if a new object was retrieved.
 * @retval  VERR_EOF when there are no more objects.
 * @retval  VERR_INVALID_FUNCTION if called on a non-readable stream.
 *
 * @param   hVfsFss     The file system stream handle.
 * @param   ppszName    Where to return the object name.  Must be freed by
 *                      calling RTStrFree.
 * @param   penmType    Where to return the object type.
 * @param   phVfsObj    Where to return the object handle (referenced). This
 *                      must be cast to the desired type before use.
 */
RTDECL(int)         RTVfsFsStrmNext(RTVFSFSSTREAM hVfsFss, char **ppszName, RTVFSOBJTYPE *penmType, PRTVFSOBJ phVfsObj);

/**
 * Appends a VFS object to the stream.
 *
 * The stream must be writable.
 *
 * @returns IPRT status code.
 * @retval  VERR_INVALID_FUNCTION if called on a non-writable stream.
 * @param   hVfsFss     The file system stream handle.
 * @param   pszPath     The path.
 * @param   hVfsObj     The VFS object to add.
 * @param   fFlags      RTVFSFSSTRM_ADD_F_XXX.
 */
RTDECL(int)         RTVfsFsStrmAdd(RTVFSFSSTREAM hVfsFss, const char *pszPath, RTVFSOBJ hVfsObj, uint32_t fFlags);

/** @name RTVFSFSSTRM_ADD_F_XXX - Flags for RTVfsFsStrmAdd.
 * @{ */
/** Input is an I/O stream of indeterminate length, read to the end and then
 * update the file header.
 * @note This is *only* possible if the output stream is actually a file. */
#define RTVFSFSSTRM_ADD_F_STREAM         RT_BIT_32(0)
/** Mask of flags specific to the target stream. */
#define RTVFSFSSTRM_ADD_F_SPECIFIC_MASK  UINT32_C(0xff000000)
/** Valid bits. */
#define RTVFSFSSTRM_ADD_F_VALID_MASK     UINT32_C(0xff000001)
/** @} */

/**
 * Pushes an byte stream onto the stream.
 *
 * The stream must be writable.
 *
 * This differs from RTVfsFsStrmAdd() in that it will create a regular file in
 * the output file system stream and provide the actual content bytes via the
 * returned I/O stream object.
 *
 * @returns IPRT status code.
 * @retval  VERR_INVALID_FUNCTION if called on a non-writable stream.
 * @param   hVfsFss     The file system stream handle.
 * @param   pszPath     The path to the file.
 * @param   cbFile      The file size.  This can also be set to UINT64_MAX if
 *                      the file system stream is backed by a file.
 * @param   paObjInfo   Array of zero or more RTFSOBJINFO structures containing
 *                      different pieces of information about the file.  If any
 *                      provided, the first one should be a RTFSOBJATTRADD_UNIX
 *                      one, additional can be supplied if wanted.  What exactly
 *                      is needed depends on the underlying FS stream
 *                      implementation.
 * @param   cObjInfo    Number of items in the array @a paObjInfo points at.
 * @param   fFlags      RTVFSFSSTRM_PUSH_F_XXX.
 * @param   phVfsIos    Where to return the I/O stream to feed the file content
 *                      to.  If the FS stream is backed by a file, the returned
 *                      handle can be cast to a file if necessary.
 */
RTDECL(int)         RTVfsFsStrmPushFile(RTVFSFSSTREAM hVfsFss, const char *pszPath, uint64_t cbFile,
                                        PCRTFSOBJINFO paObjInfo, uint32_t cObjInfo, uint32_t fFlags, PRTVFSIOSTREAM phVfsIos);

/** @name RTVFSFSSTRM_PUSH_F_XXX - Flags for RTVfsFsStrmPushFile.
 * @{ */
/** Input is an I/O stream of indeterminate length, read to the end and then
 * update the file header.
 * @note This is *only* possible if the output stream is actually a file. */
#define RTVFSFSSTRM_PUSH_F_STREAM        RT_BIT_32(0)
/** Mask of flags specific to the target stream. */
#define RTVFSFSSTRM_PUSH_F_SPECIFIC_MASK UINT32_C(0xff000000)
/** Valid bits. */
#define RTVFSFSSTRM_PUSH_F_VALID_MASK    UINT32_C(0xff000001)
/** @} */

/**
 * Marks the end of the stream.
 *
 * The stream must be writable.
 *
 * @returns IPRT status code.
 * @retval  VERR_INVALID_FUNCTION if called on a non-writable stream.
 * @param   hVfsFss     The file system stream handle.
 */
RTDECL(int)         RTVfsFsStrmEnd(RTVFSFSSTREAM hVfsFss);

/** @} */


/** @defgroup grp_rt_vfs_dir        VFS Directory API
 * @{
 */

/**
 * Retains a reference to the VFS directory handle.
 *
 * @returns New reference count on success, UINT32_MAX on failure.
 * @param   hVfsDir         The VFS directory handle.
 */
RTDECL(uint32_t)    RTVfsDirRetain(RTVFSDIR hVfsDir);
RTDECL(uint32_t)    RTVfsDirRetainDebug(RTVFSDIR hVfsDir, RT_SRC_POS_DECL);

/**
 * Releases a reference to the VFS directory handle.
 *
 * @returns New reference count on success (0 if closed), UINT32_MAX on failure.
 * @param   hVfsDir         The VFS directory handle.
 */
RTDECL(uint32_t)    RTVfsDirRelease(RTVFSDIR hVfsDir);

/**
 * Opens a directory in the specified file system.
 *
 * @returns IPRT status code.
 * @param   hVfs            The VFS to open the directory within.
 * @param   pszPath         Path to the directory, relative to the root.
 * @param   fFlags          Reserved, MBZ.
 * @param   phVfsDir        Where to return the directory.
 */
RTDECL(int) RTVfsDirOpen(RTVFS hVfs, const char *pszPath, uint32_t fFlags, PRTVFSDIR phVfsDir);

/**
 * Opens any file system object in or under the given directory.
 *
 * @returns IPRT status code.
 * @param   hVfsDir         The VFS directory start walking the @a pszPath
 *                          relative to.
 * @param   pszPath         Path to the file.
 * @param   fFileOpen       RTFILE_O_XXX flags.
 * @param   fObjFlags       More flags: RTVFSOBJ_F_XXX, RTPATH_F_XXX.
 * @param   phVfsObj        Where to return the object handle.
 * @sa      RTVfsObjOpen, RTVfsDirOpenDir, RTVfsDirOpenFile
 */
RTDECL(int) RTVfsDirOpenObj(RTVFSDIR hVfsDir, const char *pszPath, uint64_t fFileOpen, uint32_t fObjFlags, PRTVFSOBJ phVfsObj);

/**
 * Opens a file in or under the given directory.
 *
 * @returns IPRT status code.
 * @param   hVfsDir         The VFS directory start walking the @a pszPath
 *                          relative to.
 * @param   pszPath         Path to the file.
 * @param   fOpen           RTFILE_O_XXX flags.
 * @param   phVfsFile       Where to return the file.
 * @sa      RTVfsDirOpenFileAsIoStream
 */
RTDECL(int) RTVfsDirOpenFile(RTVFSDIR hVfsDir, const char *pszPath, uint64_t fOpen, PRTVFSFILE phVfsFile);

/**
 * Convenience wrapper around RTVfsDirOpenFile that returns an I/O stream.
 *
 * @returns IPRT status code.
 * @param   hVfsDir         The VFS directory start walking the @a pszPath
 *                          relative to.
 * @param   pszPath         Path to the file.
 * @param   fOpen           RTFILE_O_XXX flags.
 * @param   phVfsIos        Where to return the I/O stream handle of the file.
 * @sa      RTVfsDirOpenFile
 */
RTDECL(int) RTVfsDirOpenFileAsIoStream(RTVFSDIR hVfsDir, const char *pszPath, uint64_t fOpen, PRTVFSIOSTREAM phVfsIos);

/**
 * Opens a directory in or under the given directory.
 *
 * @returns IPRT status code.
 * @param   hVfsDir         The VFS directory start walking the @a pszPath
 *                          relative to.
 * @param   pszPath         Path to the file.
 * @param   fFlags          Reserved, MBZ.
 * @param   phVfsDir        Where to return the directory.
 */
RTDECL(int) RTVfsDirOpenDir(RTVFSDIR hVfsDir, const char *pszPath, uint32_t fFlags, PRTVFSDIR phVfsDir);

/**
 * Creates a directory relative to @a hVfsDir.
 *
 * @returns IPRT status code
 * @param   hVfsDir             The directory the path is relative to.
 * @param   pszRelPath          The relative path to the new directory.
 * @param   fMode               The file mode for the new directory.
 * @param   fFlags              Directory creation flags, RTDIRCREATE_FLAGS_XXX.
 * @param   phVfsDir            Where to return the handle to the newly created
 *                              directory.  Optional.
 * @sa      RTDirCreate, RTDirRelDirCreate
 */
RTDECL(int) RTVfsDirCreateDir(RTVFSDIR hVfsDir, const char *pszRelPath, RTFMODE fMode, uint32_t fFlags, PRTVFSDIR phVfsDir);

/**
 * Create a VFS directory handle from a standard IPRT directory handle (RTDIR).
 *
 * @returns IPRT status code.
 * @param   hDir            The standard IPRT directory handle.
 * @param   fLeaveOpen      Whether to leave the handle open when the VFS
 *                          directory is released, or to close it (@c false).
 * @param   phVfsDir        Where to return the VFS directory handle.
 */
RTDECL(int) RTVfsDirFromRTDir(RTDIR hDir, bool fLeaveOpen, PRTVFSDIR phVfsDir);

/**
 * RTDirOpen + RTVfsDirFromRTDir.
 *
 * @returns IPRT status code.
 * @param   pszPath         The path to the directory.
 * @param   fFlags          RTDIR_F_XXX.
 * @param   phVfsDir        Where to return the VFS directory handle.
 */
RTDECL(int) RTVfsDirOpenNormal(const char *pszPath, uint32_t fFlags, PRTVFSDIR phVfsDir);

/** Checks if @a hVfsDir was opened using RTVfsDirOpenNormal() or
 *  RTVfsDirFromRTDir(), either directly or indirectly. */
RTDECL(bool) RTVfsDirIsStdDir(RTVFSDIR hVfsDir);

/**
 * Queries information about a object in or under the given directory.
 *
 * @returns IPRT Status code.
 * @param   hVfsDir         The VFS directory start walking the @a pszPath
 *                          relative to.
 * @param   pszPath         Path to the object.
 * @param   pObjInfo        Where to return info.
 * @param   enmAddAttr      What to return.
 * @param   fFlags          RTPATH_F_XXX.
 * @sa      RTPathQueryInfoEx, RTVfsQueryPathInfo, RTVfsObjQueryInfo
 */
RTDECL(int) RTVfsDirQueryPathInfo(RTVFSDIR hVfsDir, const char *pszPath, PRTFSOBJINFO pObjInfo,
                                  RTFSOBJATTRADD enmAddAttr, uint32_t fFlags);

/**
 * Removes a directory relative to @a hVfsDir.
 *
 * @returns IPRT status code.
 * @param   hVfsDir         The VFS directory to start walking the @a pszRelPath
 *                          relative to.
 * @param   pszRelPath      The path to the directory that should be removed.
 * @param   fFlags          Reserved, MBZ.
 */
RTDECL(int) RTVfsDirRemoveDir(RTVFSDIR hVfsDir, const char *pszRelPath, uint32_t fFlags);

/**
 * Reads the next entry in the directory returning extended information.
 *
 * @returns VINF_SUCCESS and data in pDirEntry on success.
 * @returns VERR_NO_MORE_FILES when the end of the directory has been reached.
 * @returns VERR_BUFFER_OVERFLOW if the buffer is too small to contain the filename. If
 *          pcbDirEntry is specified it will be updated with the required buffer size.
 * @returns suitable iprt status code on other errors.
 *
 * @param   hVfsDir         The VFS directory.
 * @param   pDirEntry       Where to store the information about the next
 *                          directory entry on success.
 * @param   pcbDirEntry     Optional parameter used for variable buffer size.
 *
 *                          On input the variable pointed to contains the size of the pDirEntry
 *                          structure. This must be at least OFFSET(RTDIRENTRYEX, szName[2]) bytes.
 *
 *                          On successful output the field is updated to
 *                          OFFSET(RTDIRENTRYEX, szName[pDirEntry->cbName + 1]).
 *
 *                          When the data doesn't fit in the buffer and VERR_BUFFER_OVERFLOW is
 *                          returned, this field contains the required buffer size.
 *
 *                          The value is unchanged in all other cases.
 * @param   enmAddAttr      Which set of additional attributes to request.
 *                          Use RTFSOBJATTRADD_NOTHING if this doesn't matter.
 *
 * @sa      RTDirReadEx
 */
RTDECL(int) RTVfsDirReadEx(RTVFSDIR hVfsDir, PRTDIRENTRYEX pDirEntry, size_t *pcbDirEntry, RTFSOBJATTRADD enmAddAttr);

/**
 * Rewind and restart the directory reading.
 *
 * @returns IRPT status code.
 * @param   hVfsDir         The VFS directory.
 */
RTDECL(int) RTVfsDirRewind(RTVFSDIR hVfsDir);

/** @}  */


/** @defgroup grp_rt_vfs_symlink    VFS Symbolic Link API
 *
 * @remarks The TAR VFS and filesystem stream uses symbolic links for
 *          describing hard links as well.  The users must use RTFS_IS_SYMLINK
 *          to check if it is a real symlink in those cases.
 *
 * @remarks Any VFS which is backed by a real file system may be subject to
 *          races with other processes or threads, so the user may get
 *          unexpected errors when this happends.  This is a bit host specific,
 *          i.e. it might be prevent on windows if we care.
 *
 * @{
 */


/**
 * Retains a reference to the VFS symbolic link handle.
 *
 * @returns New reference count on success, UINT32_MAX on failure.
 * @param   hVfsSym         The VFS symbolic link handle.
 */
RTDECL(uint32_t)    RTVfsSymlinkRetain(RTVFSSYMLINK hVfsSym);
RTDECL(uint32_t)    RTVfsSymlinkRetainDebug(RTVFSSYMLINK hVfsSym, RT_SRC_POS_DECL);

/**
 * Releases a reference to the VFS symbolic link handle.
 *
 * @returns New reference count on success (0 if closed), UINT32_MAX on failure.
 * @param   hVfsSym         The VFS symbolic link handle.
 */
RTDECL(uint32_t)    RTVfsSymlinkRelease(RTVFSSYMLINK hVfsSym);

/**
 * Query information about the symbolic link.
 *
 * @returns IPRT status code.
 * @param   hVfsSym         The VFS symbolic link handle.
 * @param   pObjInfo        Where to return the info.
 * @param   enmAddAttr      Which additional attributes should be retrieved.
 *
 * @sa      RTFileQueryInfo, RTPathQueryInfo, RTPathQueryInfoEx
 */
RTDECL(int)         RTVfsSymlinkQueryInfo(RTVFSSYMLINK hVfsSym, PRTFSOBJINFO pObjInfo, RTFSOBJATTRADD enmAddAttr);

/**
 * Set the unix style owner and group.
 *
 * @returns IPRT status code.
 * @param   hVfsSym         The VFS symbolic link handle.
 * @param   fMode           The new mode bits.
 * @param   fMask           The mask indicating which bits we are changing.
 * @sa      RTFileSetMode, RTPathSetMode
 */
RTDECL(int)         RTVfsSymlinkSetMode(RTVFSSYMLINK hVfsSym, RTFMODE fMode, RTFMODE fMask);

/**
 * Set the timestamps associated with the object.
 *
 * @returns IPRT status code.
 * @param   hVfsSym         The VFS symbolic link handle.
 * @param   pAccessTime     Pointer to the new access time. NULL if not
 *                          to be changed.
 * @param   pModificationTime   Pointer to the new modifcation time. NULL if
 *                              not to be changed.
 * @param   pChangeTime     Pointer to the new change time. NULL if not to be
 *                          changed.
 * @param   pBirthTime      Pointer to the new time of birth. NULL if not to be
 *                          changed.
 * @remarks See RTFileSetTimes for restrictions and behavior imposed by the
 *          host OS or underlying VFS provider.
 * @sa      RTFileSetTimes, RTPathSetTimes
 */
RTDECL(int)         RTVfsSymlinkSetTimes(RTVFSSYMLINK hVfsSym, PCRTTIMESPEC pAccessTime, PCRTTIMESPEC pModificationTime,
                                         PCRTTIMESPEC pChangeTime, PCRTTIMESPEC pBirthTime);

/**
 * Set the unix style owner and group.
 *
 * @returns IPRT status code.
 * @param   hVfsSym         The VFS symbolic link handle.
 * @param   uid             The user ID of the new owner.  NIL_RTUID if
 *                          unchanged.
 * @param   gid             The group ID of the new owner group. NIL_RTGID if
 *                          unchanged.
 * @sa      RTFileSetOwner, RTPathSetOwner.
 */
RTDECL(int)         RTVfsSymlinkSetOwner(RTVFSSYMLINK hVfsSym, RTUID uid, RTGID gid);

/**
 * Read the symbolic link target.
 *
 * @returns IPRT status code.
 * @param   hVfsSym         The VFS symbolic link handle.
 * @param   pszTarget       The target buffer.
 * @param   cbTarget        The size of the target buffer.
 * @sa      RTSymlinkRead
 */
RTDECL(int)         RTVfsSymlinkRead(RTVFSSYMLINK hVfsSym, char *pszTarget, size_t cbTarget);

/** @}  */



/** @defgroup grp_rt_vfs_iostream   VFS I/O Stream API
 * @{
 */

/**
 * Creates a VFS file from a memory buffer.
 *
 * @returns IPRT status code.
 *
 * @param   fFlags          A combination of RTFILE_O_READ and RTFILE_O_WRITE.
 * @param   pvBuf           The buffer.  This will be copied and not referenced
 *                          after this function returns.
 * @param   cbBuf           The buffer size.
 * @param   phVfsIos        Where to return the VFS I/O stream handle.
 */
RTDECL(int)         RTVfsIoStrmFromBuffer(uint32_t fFlags, void const *pvBuf, size_t cbBuf, PRTVFSIOSTREAM phVfsIos);

/**
 * Creates a VFS I/O stream handle from a standard IPRT file handle (RTFILE).
 *
 * @returns IPRT status code.
 * @param   hFile           The standard IPRT file handle.
 * @param   fOpen           The flags the handle was opened with.  Pass 0 to
 *                          have these detected.
 * @param   fLeaveOpen      Whether to leave the handle open when the VFS file
 *                          is released, or to close it (@c false).
 * @param   phVfsIos        Where to return the VFS I/O stream handle.
 */
RTDECL(int)         RTVfsIoStrmFromRTFile(RTFILE hFile, uint64_t fOpen, bool fLeaveOpen, PRTVFSIOSTREAM phVfsIos);

/**
 * Creates a VFS I/O stream handle from a standard IPRT pipe handle (RTPIPE).
 *
 * @returns IPRT status code.
 * @param   hPipe           The standard IPRT pipe handle.
 * @param   fLeaveOpen      Whether to leave the handle open when the VFS file
 *                          is released, or to close it (@c false).
 * @param   phVfsIos        Where to return the VFS I/O stream handle.
 */
RTDECL(int)         RTVfsIoStrmFromRTPipe(RTPIPE hPipe, bool fLeaveOpen, PRTVFSIOSTREAM phVfsIos);

/**
 * Convenience function combining RTFileOpen with RTVfsIoStrmFromRTFile.
 *
 * @returns IPRT status code.
 * @param   pszFilename     The path to the file in the normal file system.
 * @param   fOpen           The flags to pass to RTFileOpen when opening the
 *                          file, i.e. RTFILE_O_XXX.
 * @param   phVfsIos        Where to return the VFS I/O stream handle.
 */
RTDECL(int)         RTVfsIoStrmOpenNormal(const char *pszFilename, uint64_t fOpen, PRTVFSIOSTREAM phVfsIos);

/**
 * Create a VFS I/O stream handle from one of the standard handles.
 *
 * @returns IPRT status code.
 * @param   enmStdHandle    The standard IPRT file handle.
 * @param   fOpen           The flags the handle was opened with.  Pass 0 to
 *                          have these detected.
 * @param   fLeaveOpen      Whether to leave the handle open when the VFS file
 *                          is released, or to close it (@c false).
 * @param   phVfsIos        Where to return the VFS I/O stream handle.
 */
RTDECL(int)         RTVfsIoStrmFromStdHandle(RTHANDLESTD enmStdHandle, uint64_t fOpen, bool fLeaveOpen,
                                             PRTVFSIOSTREAM phVfsIos);

/**
 * Retains a reference to the VFS I/O stream handle.
 *
 * @returns New reference count on success, UINT32_MAX on failure.
 * @param   hVfsIos         The VFS I/O stream handle.
 */
RTDECL(uint32_t)    RTVfsIoStrmRetain(RTVFSIOSTREAM hVfsIos);
RTDECL(uint32_t)    RTVfsIoStrmRetainDebug(RTVFSIOSTREAM hVfsIos, RT_SRC_POS_DECL);

/**
 * Releases a reference to the VFS I/O stream handle.
 *
 * @returns New reference count on success (0 if closed), UINT32_MAX on failure.
 * @param   hVfsIos         The VFS I/O stream handle.
 */
RTDECL(uint32_t)    RTVfsIoStrmRelease(RTVFSIOSTREAM hVfsIos);

/**
 * Convert the VFS I/O stream handle to a VFS file handle.
 *
 * @returns The VFS file handle on success, this must be released.
 *          NIL_RTVFSFILE if the I/O stream handle is invalid.
 * @param   hVfsIos         The VFS I/O stream handle.
 * @sa      RTVfsFileToIoStream
 */
RTDECL(RTVFSFILE)   RTVfsIoStrmToFile(RTVFSIOSTREAM hVfsIos);

/**
 * Query information about the I/O stream.
 *
 * @returns IPRT status code.
 * @param   hVfsIos         The VFS I/O stream handle.
 * @param   pObjInfo        Where to return the info.
 * @param   enmAddAttr      Which additional attributes should be retrieved.
 * @sa      RTFileQueryInfo
 */
RTDECL(int)         RTVfsIoStrmQueryInfo(RTVFSIOSTREAM hVfsIos, PRTFSOBJINFO pObjInfo, RTFSOBJATTRADD enmAddAttr);

/**
 * Read bytes from the I/O stream.
 *
 * @returns IPRT status code.
 * @retval  VINF_SUCCESS and the number of bytes read written to @a pcbRead.
 * @retval  VINF_TRY_AGAIN if @a fBlocking is @c false, @a pcbRead is not NULL,
 *          and no data was available. @a *pcbRead will be set to 0.
 * @retval  VINF_EOF when trying to read __beyond__ the end of the stream and
 *          @a pcbRead is not NULL (it will be set to the number of bytes read,
 *          or 0 if the end of the stream was reached before this call).
 *          When the last byte of the read request is the last byte in the
 *          stream, this status code will not be used.  However, VINF_EOF is
 *          returned when attempting to read 0 bytes while standing at the end
 *          of the stream.
 * @retval  VERR_EOF when trying to read __beyond__ the end of the stream and
 *          @a pcbRead is NULL.
 * @retval  VERR_ACCESS_DENIED if the stream is not readable.
 *
 * @param   hVfsIos         The VFS I/O stream handle.
 * @param   pvBuf           Where to store the read bytes.
 * @param   cbToRead        The number of bytes to read.
 * @param   fBlocking       Whether the call is blocking (@c true) or not.  If
 *                          not, the @a pcbRead parameter must not be NULL.
 * @param   pcbRead         Where to always store the number of bytes actually
 *                          read.  This can be NULL if @a fBlocking is true.
 * @sa      RTVfsFileRead, RTFileRead, RTPipeRead, RTPipeReadBlocking,
 *          RTSocketRead
 */
RTDECL(int)         RTVfsIoStrmRead(RTVFSIOSTREAM hVfsIos, void *pvBuf, size_t cbToRead, bool fBlocking, size_t *pcbRead);

/**
 * Read bytes from the I/O stream, optionally with offset.
 *
 * @returns IPRT status code.
 * @retval  VINF_SUCCESS and the number of bytes read written to @a pcbRead.
 * @retval  VINF_TRY_AGAIN if @a fBlocking is @c false, @a pcbRead is not NULL,
 *          and no data was available. @a *pcbRead will be set to 0.
 * @retval  VINF_EOF when trying to read __beyond__ the end of the stream and
 *          @a pcbRead is not NULL (it will be set to the number of bytes read,
 *          or 0 if the end of the stream was reached before this call).
 *          When the last byte of the read request is the last byte in the
 *          stream, this status code will not be used.  However, VINF_EOF is
 *          returned when attempting to read 0 bytes while standing at the end
 *          of the stream.
 * @retval  VERR_EOF when trying to read __beyond__ the end of the stream and
 *          @a pcbRead is NULL.
 * @retval  VERR_ACCESS_DENIED if the stream is not readable.
 *
 * @param   hVfsIos         The VFS I/O stream handle.
 * @param   off             Where to read at, -1 for the current position.
 * @param   pvBuf           Where to store the read bytes.
 * @param   cbToRead        The number of bytes to read.
 * @param   fBlocking       Whether the call is blocking (@c true) or not.  If
 *                          not, the @a pcbRead parameter must not be NULL.
 * @param   pcbRead         Where to always store the number of bytes actually
 *                          read.  This can be NULL if @a fBlocking is true.
 * @sa      RTVfsFileRead, RTFileRead, RTPipeRead, RTPipeReadBlocking,
 *          RTSocketRead
 */
RTDECL(int)         RTVfsIoStrmReadAt(RTVFSIOSTREAM hVfsIos, RTFOFF off, void *pvBuf, size_t cbToRead, bool fBlocking, size_t *pcbRead);

/**
 * Reads the remainder of the stream into a memory buffer.
 *
 * For simplifying string-style processing, the is a zero byte after the
 * returned buffer, making sure it can be used as a zero terminated string.
 *
 * @returns IPRT status code.
 * @param   hVfsIos         The VFS I/O stream handle.
 * @param   ppvBuf          Where to return the buffer.  Must pass to
 *                          RTVfsIoStrmReadAllFree for freeing, not RTMemFree!
 * @param   pcbBuf          Where to return the buffer size.
 */
RTDECL(int)         RTVfsIoStrmReadAll(RTVFSIOSTREAM hVfsIos, void **ppvBuf, size_t *pcbBuf);

/**
 * Free memory buffer returned by RTVfsIoStrmReadAll.
 *
 * @param   pvBuf           What RTVfsIoStrmReadAll returned.
 * @param   cbBuf           What RTVfsIoStrmReadAll returned.
 */
RTDECL(void)        RTVfsIoStrmReadAllFree(void *pvBuf, size_t cbBuf);

/**
 * Write bytes to the I/O stream.
 *
 * @returns IPRT status code.
 * @retval  VERR_ACCESS_DENIED if the stream is not writable.
 *
 * @param   hVfsIos         The VFS I/O stream handle.
 * @param   pvBuf           The bytes to write.
 * @param   cbToWrite       The number of bytes to write.
 * @param   fBlocking       Whether the call is blocking (@c true) or not.  If
 *                          not, the @a pcbWritten parameter must not be NULL.
 * @param   pcbWritten      Where to always store the number of bytes actually
 *                          written.  This can be NULL if @a fBlocking is true.
 * @sa      RTVfsFileWrite, RTFileWrite, RTPipeWrite, RTPipeWriteBlocking,
 *          RTSocketWrite
 */
RTDECL(int)         RTVfsIoStrmWrite(RTVFSIOSTREAM hVfsIos, const void *pvBuf, size_t cbToWrite, bool fBlocking, size_t *pcbWritten);
RTDECL(int)         RTVfsIoStrmWriteAt(RTVFSIOSTREAM hVfsIos, RTFOFF off, const void *pvBuf, size_t cbToWrite, bool fBlocking, size_t *pcbWritten);

/**
 * Reads bytes from the I/O stream into a scatter buffer.
 *
 * @returns IPRT status code.
 * @retval  VINF_SUCCESS and the number of bytes read written to @a pcbRead.
 * @retval  VINF_TRY_AGAIN if @a fBlocking is @c false, @a pcbRead is not NULL,
 *          and no data was available. @a *pcbRead will be set to 0.
 * @retval  VINF_EOF when trying to read __beyond__ the end of the stream and
 *          @a pcbRead is not NULL (it will be set to the number of bytes read,
 *          or 0 if the end of the stream was reached before this call).
 *          When the last byte of the read request is the last byte in the
 *          stream, this status code will not be used.  However, VINF_EOF is
 *          returned when attempting to read 0 bytes while standing at the end
 *          of the stream.
 * @retval  VERR_EOF when trying to read __beyond__ the end of the stream and
 *          @a pcbRead is NULL.
 * @retval  VERR_ACCESS_DENIED if the stream is not readable.
 *
 * @param   hVfsIos         The VFS I/O stream handle.
 * @param   off             Where to read at, -1 for the current position.
 * @param   pSgBuf          Pointer to a scatter buffer descriptor.  The number
 *                          of bytes described by the segments is what will be
 *                          attemted read.
 * @param   fBlocking       Whether the call is blocking (@c true) or not.  If
 *                          not, the @a pcbRead parameter must not be NULL.
 * @param   pcbRead         Where to always store the number of bytes actually
 *                          read.  This can be NULL if @a fBlocking is true.
 * @sa      RTFileSgRead, RTSocketSgRead, RTPipeRead, RTPipeReadBlocking
 */
RTDECL(int)         RTVfsIoStrmSgRead(RTVFSIOSTREAM hVfsIos, RTFOFF off, PCRTSGBUF pSgBuf, bool fBlocking, size_t *pcbRead);

/**
 * Write bytes to the I/O stream from a gather buffer.
 *
 * @returns IPRT status code.
 * @retval  VERR_ACCESS_DENIED if the stream is not writable.
 *
 * @param   hVfsIos         The VFS I/O stream handle.
 * @param   off             Where to write at, -1 for the current position.
 * @param   pSgBuf          Pointer to a gather buffer descriptor.  The number
 *                          of bytes described by the segments is what will be
 *                          attemted written.
 * @param   fBlocking       Whether the call is blocking (@c true) or not.  If
 *                          not, the @a pcbWritten parameter must not be NULL.
 * @param   pcbWritten      Where to always store the number of bytes actually
 *                          written.  This can be NULL if @a fBlocking is true.
 * @sa      RTFileSgWrite, RTSocketSgWrite
 */
RTDECL(int)         RTVfsIoStrmSgWrite(RTVFSIOSTREAM hVfsIos, RTFOFF off, PCRTSGBUF pSgBuf, bool fBlocking, size_t *pcbWritten);

/**
 * Flush any buffered data to the I/O stream.
 *
 * @returns IPRT status code.
 * @param   hVfsIos         The VFS I/O stream handle.
 * @sa      RTVfsFileFlush, RTFileFlush, RTPipeFlush
 */
RTDECL(int)         RTVfsIoStrmFlush(RTVFSIOSTREAM hVfsIos);

/**
 * Poll for events.
 *
 * @returns IPRT status code.
 * @param   hVfsIos         The VFS I/O stream handle.
 * @param   fEvents         The events to poll for (RTPOLL_EVT_XXX).
 * @param   cMillies        How long to wait for event to eventuate.
 * @param   fIntr           Whether the wait is interruptible and can return
 *                          VERR_INTERRUPTED (@c true) or if this condition
 *                          should be hidden from the caller (@c false).
 * @param   pfRetEvents     Where to return the event mask.
 * @sa      RTVfsFilePoll, RTPollSetAdd, RTPoll, RTPollNoResume.
 */
RTDECL(int)         RTVfsIoStrmPoll(RTVFSIOSTREAM hVfsIos, uint32_t fEvents, RTMSINTERVAL cMillies, bool fIntr,
                                    uint32_t *pfRetEvents);
/**
 * Tells the current I/O stream position.
 *
 * @returns Zero or higher - where to return the I/O stream offset.  Values
 *          below zero are IPRT status codes (VERR_XXX).
 * @param   hVfsIos         The VFS I/O stream handle.
 * @sa      RTFileTell
 */
RTDECL(RTFOFF)      RTVfsIoStrmTell(RTVFSIOSTREAM hVfsIos);

/**
 * Skips @a cb ahead in the stream.
 *
 * @returns IPRT status code.
 * @param   hVfsIos         The VFS I/O stream handle.
 * @param   cb              The number bytes to skip.
 */
RTDECL(int)         RTVfsIoStrmSkip(RTVFSIOSTREAM hVfsIos, RTFOFF cb);

/**
 * Fills the stream with @a cb zeros.
 *
 * @returns IPRT status code.
 * @param   hVfsIos         The VFS I/O stream handle.
 * @param   cb              The number of zero bytes to insert.
 */
RTDECL(int)         RTVfsIoStrmZeroFill(RTVFSIOSTREAM hVfsIos, RTFOFF cb);

/**
 * Checks if we're at the end of the I/O stream.
 *
 * @returns true if at EOS, otherwise false.
 * @param   hVfsIos         The VFS I/O stream handle.
 */
RTDECL(bool)        RTVfsIoStrmIsAtEnd(RTVFSIOSTREAM hVfsIos);

/**
 * Get the RTFILE_O_XXX flags for the I/O stream.
 *
 * @returns RTFILE_O_XXX, 0 on failure.
 * @param   hVfsIos         The VFS I/O stream handle.
 */
RTDECL(uint64_t)    RTVfsIoStrmGetOpenFlags(RTVFSIOSTREAM hVfsIos);

/**
 * Process the rest of the stream, checking if it's all valid UTF-8 encoding.
 *
 * @returns IPRT status code.
 *
 * @param   hVfsIos         The VFS I/O stream handle.
 * @param   fFlags          Flags governing the validation, see
 *                          RTVFS_VALIDATE_UTF8_XXX.
 * @param   poffError       Where to return the error offset. Optional.
 */
RTDECL(int)        RTVfsIoStrmValidateUtf8Encoding(RTVFSIOSTREAM hVfsIos, uint32_t fFlags, PRTFOFF poffError);

/** @defgroup RTVFS_VALIDATE_UTF8_XXX   RTVfsIoStrmValidateUtf8Encoding flags.
 * @{ */
/** The text must not contain any null terminator codepoints. */
#define RTVFS_VALIDATE_UTF8_NO_NULL         RT_BIT_32(0)
/** The codepoints must be in the range covered by RTC-3629.  */
#define RTVFS_VALIDATE_UTF8_BY_RTC_3629     RT_BIT_32(1)
/** Mask of valid flags. */
#define RTVFS_VALIDATE_UTF8_VALID_MASK      UINT32_C(0x00000003)
/** @}  */

/**
 * Printf-like write function.
 *
 * @returns Number of characters written on success, negative error status on
 *          failure.
 * @param   hVfsIos         The VFS I/O stream handle to write to.
 * @param   pszFormat       The format string.
 * @param   ...             Format arguments.
 */
RTDECL(ssize_t)     RTVfsIoStrmPrintf(RTVFSIOSTREAM hVfsIos, const char *pszFormat, ...);

/**
 * Printf-like write function.
 *
 * @returns Number of characters written on success, negative error status on
 *          failure.
 * @param   hVfsIos         The VFS I/O stream handle to write to.
 * @param   pszFormat       The format string.
 * @param   va              Format arguments.
 */
RTDECL(ssize_t)     RTVfsIoStrmPrintfV(RTVFSIOSTREAM hVfsIos, const char *pszFormat, va_list va);

/**
 * VFS I/O stream output buffer structure to use with
 * RTVfsIoStrmStrOutputCallback().
 */
typedef struct VFSIOSTRMOUTBUF
{
    /** The I/O stream handle. */
    RTVFSIOSTREAM   hVfsIos;
    /** Size of this structure (for sanity). */
    size_t          cbSelf;
    /** Status code of the operation. */
    int             rc;
    /** Current offset into szBuf (number of output bytes pending). */
    size_t          offBuf;
    /** Modest output buffer. */
    char            szBuf[256];
} VFSIOSTRMOUTBUF;
/** Pointer to an VFS I/O stream output buffer for use with
 *  RTVfsIoStrmStrOutputCallback() */
typedef VFSIOSTRMOUTBUF *PVFSIOSTRMOUTBUF;

/** Initializer for a VFS I/O stream output buffer. */
#define VFSIOSTRMOUTBUF_INIT(a_pOutBuf, a_hVfsIos) \
    do { \
        (a_pOutBuf)->hVfsIos  = a_hVfsIos; \
        (a_pOutBuf)->cbSelf   = sizeof(*(a_pOutBuf)); \
        (a_pOutBuf)->rc       = VINF_SUCCESS; \
        (a_pOutBuf)->offBuf   = 0; \
        (a_pOutBuf)->szBuf[0] = '\0'; \
    } while (0)

/**
 * @callback_method_impl{FNRTSTROUTPUT,
 * For use with VFSIOSTRMOUTBUF.
 *
 * Users must use VFSIOSTRMOUTBUF_INIT to initialize a VFSIOSTRMOUTBUF and pass
 * that as the outputter argument to the function this callback is handed to.}
 */
RTDECL(size_t) RTVfsIoStrmStrOutputCallback(void *pvArg, const char *pachChars, size_t cbChars);

/** @} */


/** @defgroup grp_rt_vfs_file       VFS File API
 * @{
 */
RTDECL(int)         RTVfsFileOpen(RTVFS hVfs, const char *pszFilename, uint64_t fOpen, PRTVFSFILE phVfsFile);

/**
 * Create a VFS file handle from a standard IPRT file handle (RTFILE).
 *
 * @returns IPRT status code.
 * @param   hFile           The standard IPRT file handle.
 * @param   fOpen           The flags the handle was opened with.  Pass 0 to
 *                          have these detected.
 * @param   fLeaveOpen      Whether to leave the handle open when the VFS file
 *                          is released, or to close it (@c false).
 * @param   phVfsFile       Where to return the VFS file handle.
 */
RTDECL(int)         RTVfsFileFromRTFile(RTFILE hFile, uint64_t fOpen, bool fLeaveOpen, PRTVFSFILE phVfsFile);
RTDECL(RTHCUINTPTR) RTVfsFileToNative(RTFILE hVfsFile);

/**
 * Convenience function combining RTFileOpen with RTVfsFileFromRTFile.
 *
 * @returns IPRT status code.
 * @param   pszFilename     The path to the file in the normal file system.
 * @param   fOpen           The flags to pass to RTFileOpen when opening the
 *                          file, i.e. RTFILE_O_XXX.
 * @param   phVfsFile       Where to return the VFS file handle.
 */
RTDECL(int)         RTVfsFileOpenNormal(const char *pszFilename, uint64_t fOpen, PRTVFSFILE phVfsFile);

/**
 * Convert the VFS file handle to a VFS I/O stream handle.
 *
 * @returns The VFS I/O stream handle on success, this must be released.
 *          NIL_RTVFSIOSTREAM if the file handle is invalid.
 * @param   hVfsFile        The VFS file handle.
 * @sa      RTVfsIoStrmToFile
 */
RTDECL(RTVFSIOSTREAM) RTVfsFileToIoStream(RTVFSFILE hVfsFile);

/**
 * Retains a reference to the VFS file handle.
 *
 * @returns New reference count on success, UINT32_MAX on failure.
 * @param   hVfsFile        The VFS file handle.
 */
RTDECL(uint32_t)    RTVfsFileRetain(RTVFSFILE hVfsFile);
RTDECL(uint32_t)    RTVfsFileRetainDebug(RTVFSFILE hVfsFile, RT_SRC_POS_DECL);

/**
 * Releases a reference to the VFS file handle.
 *
 * @returns New reference count on success (0 if closed), UINT32_MAX on failure.
 * @param   hVfsFile        The VFS file handle.
 */
RTDECL(uint32_t)    RTVfsFileRelease(RTVFSFILE hVfsFile);

/**
 * Query information about the object.
 *
 * @returns IPRT status code.
 * @retval  VERR_NOT_SUPPORTED if the @a enmAddAttr value is not handled by the
 *          implementation.
 *
 * @param   hVfsFile        The VFS file handle.
 * @param   pObjInfo        Where to return the info.
 * @param   enmAddAttr      Which additional attributes should be retrieved.
 * @sa      RTVfsObjQueryInfo, RTVfsFsStrmQueryInfo, RTVfsDirQueryInfo,
 *          RTVfsIoStrmQueryInfo, RTVfsFileQueryInfo, RTFileQueryInfo,
 *          RTPathQueryInfo.
 */
RTDECL(int)         RTVfsFileQueryInfo(RTVFSFILE hVfsFile, PRTFSOBJINFO pObjInfo, RTFSOBJATTRADD enmAddAttr);

/**
 * Read bytes from the file at the current position.
 *
 * @returns IPRT status code.
 * @retval  VINF_SUCCESS and the number of bytes read written to @a pcbRead.
 * @retval  VINF_EOF when trying to read __beyond__ the end of the file and
 *          @a pcbRead is not NULL (it will be set to the number of bytes read,
 *          or 0 if the end of the file was reached before this call).
 *          When the last byte of the read request is the last byte in the
 *          file, this status code will not be used.  However, VINF_EOF is
 *          returned when attempting to read 0 bytes while standing at the end
 *          of the file.
 * @retval  VERR_EOF when trying to read __beyond__ the end of the file and
 *          @a pcbRead is NULL.
 * @retval  VERR_ACCESS_DENIED if the file is not readable.
 *
 * @param   hVfsFile        The VFS file handle.
 * @param   pvBuf           Where to store the read bytes.
 * @param   cbToRead        The number of bytes to read.
 * @param   pcbRead         Where to always store the number of bytes actually
 *                          read.  Optional.
 * @sa      RTVfsIoStrmRead, RTFileRead, RTPipeRead, RTPipeReadBlocking,
 *          RTSocketRead
 */
RTDECL(int)         RTVfsFileRead(RTVFSFILE hVfsFile, void *pvBuf, size_t cbToRead, size_t *pcbRead);
RTDECL(int)         RTVfsFileReadAt(RTVFSFILE hVfsFile, RTFOFF off, void *pvBuf, size_t cbToRead, size_t *pcbRead);

/**
 * Write bytes to the file at the current position.
 *
 * @returns IPRT status code.
 * @retval  VERR_ACCESS_DENIED if the file is not writable.
 *
 * @param   hVfsFile        The VFS file handle.
 * @param   pvBuf           The bytes to write.
 * @param   cbToWrite       The number of bytes to write.
 * @param   pcbWritten      Where to always store the number of bytes actually
 *                          written.  This can be NULL.
 * @sa      RTVfsIoStrmRead, RTFileWrite, RTPipeWrite, RTPipeWriteBlocking,
 *          RTSocketWrite
 */
RTDECL(int)         RTVfsFileWrite(RTVFSFILE hVfsFile, const void *pvBuf, size_t cbToWrite, size_t *pcbWritten);
RTDECL(int)         RTVfsFileWriteAt(RTVFSFILE hVfsFile, RTFOFF off, const void *pvBuf, size_t cbToWrite, size_t *pcbWritten);


/**
 * Reads bytes from the file into a scatter buffer.
 *
 * @returns IPRT status code.
 * @retval  VINF_SUCCESS and the number of bytes read written to @a pcbRead.
 * @retval  VINF_TRY_AGAIN if @a fBlocking is @c false, @a pcbRead is not NULL,
 *          and no data was available. @a *pcbRead will be set to 0.
 * @retval  VINF_EOF when trying to read __beyond__ the end of the stream and
 *          @a pcbRead is not NULL (it will be set to the number of bytes read,
 *          or 0 if the end of the stream was reached before this call).
 *          When the last byte of the read request is the last byte in the
 *          stream, this status code will not be used.  However, VINF_EOF is
 *          returned when attempting to read 0 bytes while standing at the end
 *          of the stream.
 * @retval  VERR_EOF when trying to read __beyond__ the end of the stream and
 *          @a pcbRead is NULL.
 * @retval  VERR_ACCESS_DENIED if the stream is not readable.
 *
 * @param   hVfsFile        The VFS file handle.
 * @param   off             Where to read at, -1 for the current position.
 * @param   pSgBuf          Pointer to a scatter buffer descriptor.  The number
 *                          of bytes described by the segments is what will be
 *                          attemted read.
 * @param   fBlocking       Whether the call is blocking (@c true) or not.  If
 *                          not, the @a pcbRead parameter must not be NULL.
 * @param   pcbRead         Where to always store the number of bytes actually
 *                          read.  This can be NULL if @a fBlocking is true.
 * @sa      RTFileSgRead, RTSocketSgRead, RTPipeRead, RTPipeReadBlocking
 */
RTDECL(int)         RTVfsFileSgRead(RTVFSFILE hVfsFile, RTFOFF off, PCRTSGBUF pSgBuf, bool fBlocking, size_t *pcbRead);

/**
 * Write bytes to the file from a gather buffer.
 *
 * @returns IPRT status code.
 * @retval  VERR_ACCESS_DENIED if the stream is not writable.
 *
 * @param   hVfsFile        The VFS file handle.
 * @param   off             Where to write at, -1 for the current position.
 * @param   pSgBuf          Pointer to a gather buffer descriptor.  The number
 *                          of bytes described by the segments is what will be
 *                          attemted written.
 * @param   fBlocking       Whether the call is blocking (@c true) or not.  If
 *                          not, the @a pcbWritten parameter must not be NULL.
 * @param   pcbWritten      Where to always store the number of bytes actually
 *                          written.  This can be NULL if @a fBlocking is true.
 * @sa      RTFileSgWrite, RTSocketSgWrite
 */
RTDECL(int)         RTVfsFileSgWrite(RTVFSFILE hVfsFile, RTFOFF off, PCRTSGBUF pSgBuf, bool fBlocking, size_t *pcbWritten);

/**
 * Flush any buffered data to the file.
 *
 * @returns IPRT status code.
 * @param   hVfsFile        The VFS file handle.
 * @sa      RTVfsIoStrmFlush, RTFileFlush, RTPipeFlush
 */
RTDECL(int)         RTVfsFileFlush(RTVFSFILE hVfsFile);

/**
 * Poll for events.
 *
 * @returns IPRT status code.
 * @param   hVfsFile        The VFS file handle.
 * @param   fEvents         The events to poll for (RTPOLL_EVT_XXX).
 * @param   cMillies        How long to wait for event to eventuate.
 * @param   fIntr           Whether the wait is interruptible and can return
 *                          VERR_INTERRUPTED (@c true) or if this condition
 *                          should be hidden from the caller (@c false).
 * @param   pfRetEvents     Where to return the event mask.
 * @sa      RTVfsIoStrmPoll, RTPollSetAdd, RTPoll, RTPollNoResume.
 */
RTDECL(RTFOFF)      RTVfsFilePoll(RTVFSFILE hVfsFile, uint32_t fEvents, RTMSINTERVAL cMillies, bool fIntr,
                                  uint32_t *pfRetEvents);

/**
 * Tells the current file position.
 *
 * @returns Zero or higher - where to return the file offset.  Values
 *          below zero are IPRT status codes (VERR_XXX).
 * @param   hVfsFile        The VFS file handle.
 * @sa      RTFileTell, RTVfsIoStrmTell.
 */
RTDECL(RTFOFF)      RTVfsFileTell(RTVFSFILE hVfsFile);

/**
 * Changes the current read/write position of a file.
 *
 * @returns IPRT status code.
 *
 * @param   hVfsFile        The VFS file handle.
 * @param   offSeek         The seek offset.
 * @param   uMethod         The seek method.
 * @param   poffActual      Where to optionally return the new file offset.
 *
 * @sa      RTFileSeek
 */
RTDECL(int)         RTVfsFileSeek(RTVFSFILE hVfsFile, RTFOFF offSeek, uint32_t uMethod, uint64_t *poffActual);

/**
 * Sets the size of a file.
 *
 * This may also be used for preallocating space
 * (RTVFSFILE_SIZE_F_PREALLOC_KEEP_SIZE).
 *
 * @returns IPRT status code.
 * @retval  VERR_ACCESS_DENIED if handle isn't writable.
 * @retval  VERR_WRITE_PROTECT if read-only file system.
 * @retval  VERR_FILE_TOO_BIG if cbSize is larger than what the file system can
 *          theoretically deal with.
 * @retval  VERR_DISK_FULL if the file system if full.
 * @retval  VERR_NOT_SUPPORTED if fFlags indicates some operation that's not
 *          supported by the file system / host operating system.
 *
 * @param   hVfsFile        The VFS file handle.
 * @param   cbSize          The new file size.
 * @param   fFlags          RTVFSFILE_SIZE_F_NORMAL, RTVFSFILE_SIZE_F_GROW, or
 *                          RTVFSFILE_SIZE_F_GROW_KEEP_SIZE.
 *
 * @sa      RTFileSetSize, RTFileSetAllocationSize
 */
RTDECL(int)         RTVfsFileSetSize(RTVFSFILE hVfsFile, uint64_t cbSize, uint32_t fFlags);

/** @name RTVFSFILE_SIZE_F_XXX - RTVfsFileSetSize flags.
 * @{ */
/** Normal truncate or grow (zero'ed) like RTFileSetSize . */
#define RTVFSFILE_SIZE_F_NORMAL             UINT32_C(0x00000001)
/** Only grow the file, ignore call if cbSize would truncate the file.
 * This is what RTFileSetAllocationSize does by default.  */
#define RTVFSFILE_SIZE_F_GROW               UINT32_C(0x00000002)
/** Only grow the file, ignore call if cbSize would truncate the file.
 * This is what RTFileSetAllocationSize does by default.  */
#define RTVFSFILE_SIZE_F_GROW_KEEP_SIZE     UINT32_C(0x00000003)
/** Action mask. */
#define RTVFSFILE_SIZE_F_ACTION_MASK        UINT32_C(0x00000003)
/** Validate the flags.
 * Will reference @a a_fFlags more than once.  */
#define RTVFSFILE_SIZE_F_IS_VALID(a_fFlags) \
    ( !((a_fFlags) & ~RTVFSFILE_SIZE_F_ACTION_MASK) && ((a_fFlags) & RTVFSFILE_SIZE_F_ACTION_MASK) != 0 )
/** Mask of valid flags. */
#define RTFILE_ALLOC_SIZE_F_VALID           (RTFILE_ALLOC_SIZE_F_KEEP_SIZE)
/** @} */


RTDECL(int)         RTVfsFileQuerySize(RTVFSFILE hVfsFile, uint64_t *pcbSize);
RTDECL(RTFOFF)      RTVfsFileGetMaxSize(RTVFSFILE hVfsFile);
RTDECL(int)         RTVfsFileQueryMaxSize(RTVFSFILE hVfsFile, uint64_t *pcbMax);

/**
 * Get the RTFILE_O_XXX flags for the I/O stream.
 *
 * @returns RTFILE_O_XXX, 0 on failure.
 * @param   hVfsFile        The VFS file handle.
 */
RTDECL(uint64_t)    RTVfsFileGetOpenFlags(RTVFSFILE hVfsFile);

/**
 * Printf-like write function.
 *
 * @returns Number of characters written on success, negative error status on
 *          failure.
 * @param   hVfsFile        The VFS file handle to write to.
 * @param   pszFormat       The format string.
 * @param   ...             Format arguments.
 */
RTDECL(ssize_t)     RTVfsFilePrintf(RTVFSFILE hVfsFile, const char *pszFormat, ...);

/**
 * Printf-like write function.
 *
 * @returns Number of characters written on success, negative error status on
 *          failure.
 * @param   hVfsFile        The VFS file handle to write to.
 * @param   pszFormat       The format string.
 * @param   va              Format arguments.
 */
RTDECL(ssize_t)     RTVfsFilePrintfV(RTVFSFILE hVfsFile, const char *pszFormat, va_list va);

/** @} */


#ifdef DEBUG
# undef RTVfsRetain
# define RTVfsRetain(hVfs)          RTVfsRetainDebug(hVfs, RT_SRC_POS)
# undef RTVfsObjRetain
# define RTVfsObjRetain(hVfsObj)    RTVfsObjRetainDebug(hVfsObj, RT_SRC_POS)
# undef RTVfsDirRetain
# define RTVfsDirRetain(hVfsDir)    RTVfsDirRetainDebug(hVfsDir, RT_SRC_POS)
# undef RTVfsFileRetain
# define RTVfsFileRetain(hVfsFile)  RTVfsFileRetainDebug(hVfsFile, RT_SRC_POS)
# undef RTVfsIoStrmRetain
# define RTVfsIoStrmRetain(hVfsIos) RTVfsIoStrmRetainDebug(hVfsIos, RT_SRC_POS)
# undef RTVfsFsStrmRetain
# define RTVfsFsStrmRetain(hVfsFss) RTVfsFsStrmRetainDebug(hVfsFss, RT_SRC_POS)
#endif



/** @defgroup grp_rt_vfs_misc       VFS Miscellaneous
 * @{
 */

/**
 * Memorizes the I/O stream as a file backed by memory.
 *
 * @returns IPRT status code.
 *
 * @param   hVfsIos         The VFS I/O stream to memorize.  This will be read
 *                          to the end on success, on failure its position is
 *                          undefined.
 * @param   fFlags          A combination of RTFILE_O_READ and RTFILE_O_WRITE.
 * @param   phVfsFile       Where to return the handle to the memory file on
 *                          success.
 */
RTDECL(int) RTVfsMemorizeIoStreamAsFile(RTVFSIOSTREAM hVfsIos, uint32_t fFlags, PRTVFSFILE phVfsFile);

/**
 * Creates a VFS file from a memory buffer.
 *
 * @returns IPRT status code.
 *
 * @param   fFlags          A combination of RTFILE_O_READ and RTFILE_O_WRITE.
 * @param   pvBuf           The buffer.  This will be copied and not referenced
 *                          after this function returns.
 * @param   cbBuf           The buffer size.
 * @param   phVfsFile       Where to return the handle to the memory file on
 *                          success.
 */
RTDECL(int) RTVfsFileFromBuffer(uint32_t fFlags, void const *pvBuf, size_t cbBuf, PRTVFSFILE phVfsFile);

/**
 * Creates a memory backed VFS file object for read and write.
 *
 * @returns IPRT status code.
 *
 * @param   hVfsIos         The VFS I/O stream to memorize.  This will be read
 *                          to the end on success, on failure its position is
 *                          undefined.
 * @param   cbEstimate      The estimated file size.
 * @param   phVfsFile       Where to return the handle to the memory file on
 *                          success.
 * @sa      RTVfsMemIoStrmCreate
 */
RTDECL(int) RTVfsMemFileCreate(RTVFSIOSTREAM hVfsIos, size_t cbEstimate, PRTVFSFILE phVfsFile);

/**
 * Creates a memory backed VFS file object for read and write.
 *
 * @returns IPRT status code.
 *
 * @param   hVfsIos         The VFS I/O stream to memorize.  This will be read
 *                          to the end on success, on failure its position is
 *                          undefined.
 * @param   cbEstimate      The estimated file size.
 * @param   phVfsIos        Where to return the handle to the memory I/O stream
 *                          on success.
 * @sa      RTVfsMemFileCreate
 */
RTDECL(int) RTVfsMemIoStrmCreate(RTVFSIOSTREAM hVfsIos, size_t cbEstimate, PRTVFSIOSTREAM phVfsIos);

/**
 * Pumps data from one I/O stream to another.
 *
 * The data is read in chunks from @a hVfsIosSrc and written to @a hVfsIosDst
 * until @a hVfsIosSrc indicates end of stream.
 *
 * @returns IPRT status code
 *
 * @param   hVfsIosSrc  The input stream.
 * @param   hVfsIosDst  The output stream.
 * @param   cbBufHint   Hints at a good temporary buffer size, pass 0 if
 *                      clueless.
 */
RTDECL(int) RTVfsUtilPumpIoStreams(RTVFSIOSTREAM hVfsIosSrc, RTVFSIOSTREAM hVfsIosDst, size_t cbBufHint);


/**
 * Creates a progress wrapper for an I/O stream.
 *
 * @returns IRPT status code.
 * @param   hVfsIos             The I/O stream to wrap.
 * @param   pfnProgress         The progress callback.  The return code is
 *                              ignored by default, see
 *                              RTVFSPROGRESS_F_CANCELABLE.
 * @param   pvUser              The user argument to @a pfnProgress.
 * @param   fFlags              RTVFSPROGRESS_F_XXX
 * @param   cbExpectedRead      The expected number of bytes read.
 * @param   cbExpectedWritten   The execpted number of bytes written.
 * @param   phVfsIos            Where to return the I/O stream handle.
 */
RTDECL(int) RTVfsCreateProgressForIoStream(RTVFSIOSTREAM hVfsIos, PFNRTPROGRESS pfnProgress, void *pvUser, uint32_t fFlags,
                                           uint64_t cbExpectedRead, uint64_t cbExpectedWritten, PRTVFSIOSTREAM phVfsIos);

/**
 * Creates a progress wrapper for a file stream.
 *
 * @returns IRPT status code.
 * @param   hVfsFile            The file to wrap.
 * @param   pfnProgress         The progress callback.  The return code is
 *                              ignored by default, see
 *                              RTVFSPROGRESS_F_CANCELABLE.
 * @param   pvUser              The user argument to @a pfnProgress.
 * @param   fFlags              RTVFSPROGRESS_F_XXX
 * @param   cbExpectedRead      The expected number of bytes read.
 * @param   cbExpectedWritten   The execpted number of bytes written.
 * @param   phVfsFile           Where to return the file handle.
 */
RTDECL(int) RTVfsCreateProgressForFile(RTVFSFILE hVfsFile, PFNRTPROGRESS pfnProgress, void *pvUser, uint32_t fFlags,
                                       uint64_t cbExpectedRead, uint64_t cbExpectedWritten, PRTVFSFILE phVfsFile);

/** @name RTVFSPROGRESS_F_XXX - Flags for RTVfsCreateProcessForIoStream and
 *        RTVfsCreateProcessForFile.
 * @{ */
/** Cancel if the callback returns a failure status code.
 * This isn't default behavior because the cancelation is delayed one I/O
 * operation in most cases and it's uncertain how the VFS user will handle the
 * cancellation status code. */
#define RTVFSPROGRESS_F_CANCELABLE             RT_BIT_32(0)
/** Account forward seeks as reads. */
#define RTVFSPROGRESS_F_FORWARD_SEEK_AS_READ    RT_BIT_32(1)
/** Account fprward seeks as writes. */
#define RTVFSPROGRESS_F_FORWARD_SEEK_AS_WRITE   RT_BIT_32(2)
/** Valid bits.   */
#define RTVFSPROGRESS_F_VALID_MASK              UINT32_C(0x00000007)
/** @} */


/**
 * Create an I/O stream instance performing simple sequential read-ahead.
 *
 * @returns IPRT status code.
 * @param   hVfsIos     The input stream to perform read ahead on.  If this is
 *                      actually for a file object, the returned I/O stream
 *                      handle can also be cast to a file handle.
 * @param   fFlags      Flags reserved for future use, MBZ.
 * @param   cBuffers    How many read ahead buffers to use. Specify 0 for
 *                      default value.
 * @param   cbBuffer    The size of each read ahead buffer. Specify 0 for
 *                      default value.
 * @param   phVfsIos    Where to return the read ahead I/O stream handle.
 *
 * @remarks Careful using this on a message pipe or socket.  The reads are
 *          performed in blocked mode and it may be host and/or implementation
 *          dependent whether they will return ready data immediate or wait
 *          until there's a whole @a cbBuffer (or default) worth ready.
 *
 * @sa      RTVfsCreateReadAheadForFile
 */
RTDECL(int) RTVfsCreateReadAheadForIoStream(RTVFSIOSTREAM hVfsIos, uint32_t fFlags, uint32_t cBuffers, uint32_t cbBuffer,
                                            PRTVFSIOSTREAM phVfsIos);

/**
 * Create an I/O stream instance performing simple sequential read-ahead.
 *
 * @returns IPRT status code.
 * @param   hVfsFile    The input file to perform read ahead on.
 * @param   fFlags      Flags reserved for future use, MBZ.
 * @param   cBuffers    How many read ahead buffers to use. Specify 0 for
 *                      default value.
 * @param   cbBuffer    The size of each read ahead buffer. Specify 0 for
 *                      default value.
 * @param   phVfsFile   Where to return the read ahead file handle.
 * @sa      RTVfsCreateReadAheadForIoStream
 */
RTDECL(int) RTVfsCreateReadAheadForFile(RTVFSFILE hVfsFile, uint32_t fFlags, uint32_t cBuffers, uint32_t cbBuffer,
                                        PRTVFSFILE phVfsFile);


/**
 * Create a file system stream for writing to a directory.
 *
 * This is just supposed to be a drop in replacement for the TAR creator stream
 * that instead puts the files and stuff in a directory instead of a TAR
 * archive.  In addition, it has an undo feature for simplying cleaning up after
 * a botched run
 *
 * @returns IPRT status code.
 * @param   hVfsBaseDir The base directory.
 * @param   fFlags      RTVFSFSS2DIR_F_XXX
 * @param   phVfsFss    Where to return the FSS handle.
 * @sa      RTVfsFsStrmToNormalDir, RTVfsFsStrmToDirUndo
 */
RTDECL(int) RTVfsFsStrmToDir(RTVFSDIR hVfsBaseDir, uint32_t fFlags, PRTVFSFSSTREAM phVfsFss);

/**
 * Create a file system stream for writing to a normal directory.
 *
 * This is just supposed to be a drop in replacement for the TAR creator stream
 * that instead puts the files and stuff in a directory instead of a TAR
 * archive.  In addition, it has an undo feature for simplying cleaning up after
 * a botched run
 *
 * @returns IPRT status code.
 * @param   pszBaseDir  The base directory.  Must exist.
 * @param   fFlags      RTVFSFSS2DIR_F_XXX
 * @param   phVfsFss    Where to return the FSS handle.
 * @sa      RTVfsFsStrmToDir, RTVfsFsStrmToDirUndo
 */
RTDECL(int) RTVfsFsStrmToNormalDir(const char *pszBaseDir, uint32_t fFlags, PRTVFSFSSTREAM phVfsFss);

/** @name RTVFSFSS2DIR_F_XXX - Flags for RTVfsFsStrmToNormalDir
 * @{ */
/** Overwrite existing files (default is to not overwrite anything). */
#define RTVFSFSS2DIR_F_OVERWRITE_FILES      RT_BIT_32(0)
/** Valid bits.   */
#define RTVFSFSS2DIR_F_VALID_MASK           UINT32_C(0x00000001)
/** @} */

/**
 * Deletes files, directories, symlinks and stuff created by a FSS returned by
 * RTVfsFsStrmToNormalDir or RTVfsFsStrmToDir.
 *
 * @returns IPRT status code.
 * @param   hVfsFss     The write-to-directory FSS handle.
 */
RTDECL(int) RTVfsFsStrmToDirUndo(RTVFSFSSTREAM hVfsFss);



/** @}  */


/** @defgroup grp_rt_vfs_chain  VFS Chains
 *
 * VFS chains is for doing pipe like things with VFS objects from the command
 * line.  Imagine you want to cat the readme.gz of an ISO you could do
 * something like:
 *      RTCat :iprtvfs:file(stdfile,live.iso)|vfs(isofs)|iso(open,readme.gz)|ios(gunzip)
 * or
 *      RTCat :iprtvfs:file(stdfile,live.iso)|ios(isofs,readme.gz)|ios(gunzip)
 *
 * Or say you want to read the README.TXT on a floppy image:
 *      RTCat :iprtvfs:file(stdfile,floppy.img,r)|vfs(fat)|ios(open,README.TXT)
 * or
 *      RTCat :iprtvfs:file(stdfile,floppy.img,r)|vfs(fat)|README.TXT
 *
 * Or in the other direction, you want to write a STUFF.TGZ file to the above
 * floppy image, using a lazy writer thread for compressing the data:
 *      RTTar cf :iprtvfs:file(stdfile,floppy.img,rw)|ios(fat,STUFF.TGZ)|ios(gzip)|ios(push) .
 *
 *
 * A bit more formally:
 *      :iprtvfs:{type}({provider}[,provider-args])[{separator}{type}...][{separator}{path}]
 *
 * The @c type refers to VFS object that should be created by the @c provider.
 * Valid types:
 *      - vfs:  A virtual file system (volume).
 *      - fss:  A file system stream (e.g. tar).
 *      - ios:  An I/O stream.
 *      - file: A file.
 *      - dir:  A directory.
 *      - sym:  A symbolic link (not sure how useful this is).
 *
 * The @c provider refers to registered chain element providers (see
 * RTVFSCHAINELEMENTREG for how that works internally).  These are asked to
 * create a VFS object of the specified type using the given arguments (if any).
 * Default providers:
 *      - std:      Standard file, directory and file system.
 *      - open:     Opens a file, I/O stream or directory in a vfs or directory object.
 *      - pull:     Read-ahead buffering thread on file or I/O stream.
 *      - push:     Lazy-writer buffering thread on file or I/O stream.
 *      - gzip:     Compresses an I/O stream.
 *      - gunzip:   Decompresses an I/O stream.
 *      - fat:      FAT file system accessor.
 *      - isofs:    ISOFS file system accessor.
 *
 * As element @c separator we allow both colon (':') and the pipe character
 * ('|'). The latter the conventional one, but since it's inconvenient on the
 * command line, colon is provided as an alternative.
 *
 * In the final element we allow a simple @a path to be specified instead of the
 * type-provider-arguments stuff.  The previous object must be a directory, file
 * system or file system stream.  The application will determin exactly which
 * operation or operations which will be performed.
 *
 * @{
 */

/** The path prefix used to identify an VFS chain specification. */
#define RTVFSCHAIN_SPEC_PREFIX   ":iprtvfs:"

RTDECL(int) RTVfsChainOpenVfs(const char *pszSpec, PRTVFS phVfs, uint32_t *poffError, PRTERRINFO pErrInfo);
RTDECL(int) RTVfsChainOpenFsStream(const char *pszSpec, PRTVFSFSSTREAM  phVfsFss, uint32_t *poffError, PRTERRINFO pErrInfo);

/**
 * Opens any kind of file system object.
 *
 * @returns IPRT status code.
 * @param   pszSpec         The VFS chain specification or plain path.
 * @param   fFileOpen       RTFILE_O_XXX flags.
 * @param   fObjFlags       More flags: RTVFSOBJ_F_XXX, RTPATH_F_XXX.
 * @param   phVfsObj        Where to return the handle to the opened object.
 * @param   poffError       Where to on error return an offset into @a pszSpec
 *                          of what cause the error.  Optional.
 * @param   pErrInfo        Where to return additional error information.
 *                          Optional.
 */
RTDECL(int) RTVfsChainOpenObj(const char *pszSpec, uint64_t fFileOpen, uint32_t fObjFlags,
                              PRTVFSOBJ phVfsObj, uint32_t *poffError, PRTERRINFO pErrInfo);

RTDECL(int) RTVfsChainOpenDir(const char *pszSpec, uint32_t fOpen, PRTVFSDIR phVfsDir, uint32_t *poffError, PRTERRINFO pErrInfo);
RTDECL(int) RTVfsChainOpenParentDir(const char *pszSpec, uint32_t fOpen, PRTVFSDIR phVfsDir, const char **ppszChild,
                                    uint32_t *poffError, PRTERRINFO pErrInfo);
RTDECL(int) RTVfsChainOpenFile(const char *pszSpec, uint64_t fOpen, PRTVFSFILE phVfsFile, uint32_t *poffError, PRTERRINFO pErrInfo);
RTDECL(int) RTVfsChainOpenIoStream(const char *pszSpec, uint64_t fOpen, PRTVFSIOSTREAM phVfsIos, uint32_t *poffError, PRTERRINFO pErrInfo);
RTDECL(int) RTVfsChainOpenSymlink(const char *pszSpec, PRTVFSSYMLINK phVfsSym, uint32_t *poffError, PRTERRINFO pErrInfo);

RTDECL(int) RTVfsChainQueryInfo(const char *pszSpec, PRTFSOBJINFO pObjInfo, RTFSOBJATTRADD enmAdditionalAttribs,
                                uint32_t fFlags, uint32_t *poffError, PRTERRINFO pErrInfo);

/**
 * Tests if the given string is a chain specification or not.
 *
 * @returns true if it is, false if it isn't.
 * @param   pszSpec         The alleged chain spec.
 */
RTDECL(bool) RTVfsChainIsSpec(const char *pszSpec);

/**
 * Queries the path from the final element.
 *
 * @returns IPRT status code.
 * @retval  VERR_VFS_CHAIN_NOT_PATH_ONLY if the final element isn't just a
 *          simple path.
 * @param   pszSpec         The chain spec.
 * @param   ppszFinalPath   Where to return a copy of the final path on success.
 *                          Call RTStrFree when done.
 * @param   poffError       Where to on error return an offset into @a pszSpec
 *                          of what cause the error.  Optional.
 *
 */
RTDECL(int) RTVfsChainQueryFinalPath(const char *pszSpec, char **ppszFinalPath, uint32_t *poffError);

/**
 * Splits the given chain spec into a final path and the preceeding spec.
 *
 * This works on plain paths too.
 *
 * @returns IPRT status code.
 * @param   pszSpec         The chain spec to split.  This will be modified!
 * @param   ppszSpec        Where to return the pointer to the chain spec part.
 *                          This is set to NULL if it's a plain path or a chain
 *                          spec with only a final-path element.
 * @param   ppszFinalPath   Where to return the pointer to the final path.  This
 *                          is set to NULL if no final path.
 * @param   poffError       Where to on error return an offset into @a pszSpec
 *                          of what cause the error.  Optional.
 */
RTDECL(int) RTVfsChainSplitOffFinalPath(char *pszSpec, char **ppszSpec, char **ppszFinalPath, uint32_t *poffError);

/**
 * Common code for reporting errors of a RTVfsChainOpen* API.
 *
 * @param   pszFunction The API called.
 * @param   pszSpec     The VFS chain specification or file path passed to the.
 * @param   rc          The return code.
 * @param   offError    The error offset value returned (0 if not captured).
 * @param   pErrInfo    Additional error information.  Optional.
 *
 * @sa      RTVfsChainMsgErrorExitFailure
 * @sa      RTVfsChainOpenVfs, RTVfsChainOpenFsStream, RTVfsChainOpenDir,
 *          RTVfsChainOpenFile, RTVfsChainOpenIoStream, RTVfsChainOpenSymlink
 */
RTDECL(void) RTVfsChainMsgError(const char *pszFunction, const char *pszSpec, int rc, uint32_t offError, PRTERRINFO pErrInfo);

/**
 * Common code for reporting errors of a RTVfsChainOpen* API.
 *
 * @returns RTEXITCODE_FAILURE
 *
 * @param   pszFunction The API called.
 * @param   pszSpec     The VFS chain specification or file path passed to the.
 * @param   rc          The return code.
 * @param   offError    The error offset value returned (0 if not captured).
 * @param   pErrInfo    Additional error information.  Optional.
 *
 * @sa      RTVfsChainMsgError
 * @sa      RTVfsChainOpenVfs, RTVfsChainOpenFsStream, RTVfsChainOpenDir,
 *          RTVfsChainOpenFile, RTVfsChainOpenIoStream, RTVfsChainOpenSymlink
 */
RTDECL(RTEXITCODE) RTVfsChainMsgErrorExitFailure(const char *pszFunction, const char *pszSpec,
                                                 int rc, uint32_t offError, PRTERRINFO pErrInfo);


/** @} */


/** @} */

RT_C_DECLS_END

#endif /* !IPRT_INCLUDED_vfs_h */