summaryrefslogtreecommitdiff
path: root/include/osl/file.h
blob: 4ea9df8d62ef8749a8b2d5be0ccdb5abb7acba9e (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
/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
/*
 * This file is part of the LibreOffice project.
 *
 * This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at http://mozilla.org/MPL/2.0/.
 *
 * This file incorporates work covered by the following license notice:
 *
 *   Licensed to the Apache Software Foundation (ASF) under one or more
 *   contributor license agreements. See the NOTICE file distributed
 *   with this work for additional information regarding copyright
 *   ownership. The ASF licenses this file to you under the Apache
 *   License, Version 2.0 (the "License"); you may not use this file
 *   except in compliance with the License. You may obtain a copy of
 *   the License at http://www.apache.org/licenses/LICENSE-2.0 .
 */

#ifndef INCLUDED_OSL_FILE_H
#define INCLUDED_OSL_FILE_H

#include "sal/config.h"

#include "osl/time.h"
#include "rtl/ustring.h"
#include "sal/saldllapi.h"

#ifdef __cplusplus
extern "C" {
#endif

/** @file

Main goals and usage hints

The main intention of this interface is to provide a universal portable and
high performance access to file system functionality on any operating
system.

There are a few main goals:

1. The path specifications always has to be absolute. Any usage of relative
path specifications is forbidden. Exceptions are osl_getSystemPathFromFileURL,
osl_getFileURLFromSystemPath and osl_getAbsoluteFileURL. Most operating
systems provide a "Current Directory" per process. This is the reason why
relative path specifications can cause problems in multithreading
environments.

2. Proprietary notations of file paths are not supported. Every path notation
must the file URL specification. File URLs must be encoded in UTF8 and after
that escaped. Although the URL parameter is a unicode string, the must
contain only ASCII characters.

3. The caller cannot get any information whether a file system is case
sensitive, case preserving or not. The operating system implementation
itself should determine if it can map case-insensitive paths. The case
correct notation of a filename or file path is part of the "File Info". This
case correct name can be used as a unique key if necessary.

4. Obtaining information about files or volumes is controlled by a bitmask
which specifies which fields are of interest. Due to performance reasons it
is not recommended to obtain information which is not needed.  But if the
operating system provides more information anyway the implementation can set
more fields on output as were requested. It is in the responsibility of the
caller to decide if they use this additional information or not. But they
should do so to prevent further unnecessary calls if the information is
already there.

The input bitmask supports a flag osl_FileStatus_Mask_Validate which can be
used to force retrieving uncached validated information. Setting this flag
when calling osl_getFileStatus in combination with no other flag is a synonym
for a "FileExists". This should only be done when processing a single file
(i.e. before opening) and NEVER during enumeration of directory contents on
any step of information processing. This would change the runtime behaviour
from O(n) to O(n*n/2) on nearly every file system.  On Windows NT reading the
contents of a directory with 7000 entries and getting full information about
every file only takes 0.6 seconds. Specifying the flag
osl_FileStatus_Mask_Validate for each entry will increase the time to 180
seconds (!!!).

*/

/* Error codes according to errno */
typedef enum {
    osl_File_E_None,            /*!< on success                                                  */
    osl_File_E_PERM,            /*!< operation not permitted                                     */
    osl_File_E_NOENT,           /*!< no such file or directory                                   */
    osl_File_E_SRCH,            /*!< no process matches the PID                                  */
    osl_File_E_INTR,            /*!< function call was interrupted                               */
    osl_File_E_IO,              /*!< I/O error occurred                                          */
    osl_File_E_NXIO,            /*!< no such device or address                                   */
    osl_File_E_2BIG,            /*!< argument list too long                                      */
    osl_File_E_NOEXEC,          /*!< invalid executable file format                              */
    osl_File_E_BADF,            /*!< bad file descriptor                                         */
    osl_File_E_CHILD,           /*!< there are no child processes                                */
    osl_File_E_AGAIN,           /*!< resource temp unavailable, try again later                  */
    osl_File_E_NOMEM,           /*!< no memory available                                         */
    osl_File_E_ACCES,           /*!< file permissions do not allow operation                     */
    osl_File_E_FAULT,           /*!< bad address; an invalid pointer detected                    */
    osl_File_E_BUSY,            /*!< resource busy                                               */
    osl_File_E_EXIST,           /*!< file exists where should only be created                    */
    osl_File_E_XDEV,            /*!< improper link across file systems detected                  */
    osl_File_E_NODEV,           /*!< wrong device type specified                                 */
    osl_File_E_NOTDIR,          /*!< file isn't a directory where one is needed                  */
    osl_File_E_ISDIR,           /*!< file is a directory, invalid operation                      */
    osl_File_E_INVAL,           /*!< invalid argument to library function                        */
    osl_File_E_NFILE,           /*!< too many distinct file openings                             */
    osl_File_E_MFILE,           /*!< process has too many distinct files open                    */
    osl_File_E_NOTTY,           /*!< inappropriate I/O control operation                         */
    osl_File_E_FBIG,            /*!< file too large                                              */
    osl_File_E_NOSPC,           /*!< no space left on device, write failed                       */
    osl_File_E_SPIPE,           /*!< invalid seek operation (such as on pipe)                    */
    osl_File_E_ROFS,            /*!< illegal modification to read-only filesystem                */
    osl_File_E_MLINK,           /*!< too many links to file                                      */
    osl_File_E_PIPE,            /*!< broken pipe; no process reading from other end of pipe      */
    osl_File_E_DOM,             /*!< domain error (mathematical error)                           */
    osl_File_E_RANGE,           /*!< range error (mathematical error)                            */
    osl_File_E_DEADLK,          /*!< deadlock avoided                                            */
    osl_File_E_NAMETOOLONG,     /*!< filename too long                                           */
    osl_File_E_NOLCK,           /*!< no locks available                                          */
    osl_File_E_NOSYS,           /*!< function not implemented                                    */
    osl_File_E_NOTEMPTY,        /*!< directory not empty                                         */
    osl_File_E_LOOP,            /*!< too many levels of symbolic links found during name lookup  */
    osl_File_E_ILSEQ,           /*!< invalid or incomplete byte sequence of multibyte char found */
    osl_File_E_NOLINK,          /*!< link has been severed                                       */
    osl_File_E_MULTIHOP,        /*!< remote resource is not directly available                   */
    osl_File_E_USERS,           /*!< file quote system is confused as there are too many users   */
    osl_File_E_OVERFLOW,        /*!< value too large for defined data type                       */
    osl_File_E_NOTREADY,        /*!< device not ready                                            */
    osl_File_E_invalidError,    /*!< unmapped error: always last entry in enum!                  */
    osl_File_E_TIMEDOUT,        /*!< socket operation timed out                                  */
    osl_File_E_NETWORK,         /*!< unexpected network error occurred (Windows) - could be a
                                     user session was deleted, or an unexpected network error
                                     occurred                                                    */
    osl_File_E_FORCE_EQUAL_SIZE = SAL_MAX_ENUM
} oslFileError;

typedef void *oslDirectory;
typedef void *oslDirectoryItem;

/** Open a directory for enumerating its contents.

    @param[in]  pustrDirectoryURL
    The full qualified URL of the directory.

    @param[out]  pDirectory
    On success it receives a handle used for subsequent calls by osl_getNextDirectoryItem().
    The handle has to be released by a call to osl_closeDirectory().

    @retval osl_File_E_None on success
    @retval osl_File_E_INVAL the format of the parameters was not valid
    @retval osl_File_E_NOENT the specified path doesn't exist
    @retval osl_File_E_NOTDIR the specified path is not a directory
    @retval osl_File_E_NOMEM not enough memory for allocating structures
    @retval osl_File_E_ACCES permission denied
    @retval osl_File_E_MFILE too many open files used by the process
    @retval osl_File_E_NFILE too many open files in the system
    @retval osl_File_E_NAMETOOLONG File name too long
    @retval osl_File_E_LOOP Too many symbolic links encountered

    @see osl_getNextDirectoryItem()
    @see osl_closeDirectory()
*/
SAL_DLLPUBLIC oslFileError SAL_CALL osl_openDirectory(
        rtl_uString *pustrDirectoryURL, oslDirectory *pDirectory);

/** Retrieve the next item of a previously opened directory.

    Retrieves the next item of a previously opened directory.
    All handles have an initial refcount of 1.

    @param[in]  Directory
    A directory handle received from a previous call to osl_openDirectory().

    @param[out]  pItem
    On success it receives a handle that can be used for subsequent calls to osl_getFileStatus().
    The handle has to be released by a call to osl_releaseDirectoryItem().

    @param[in]  uHint
    With this parameter the caller can tell the implementation that (s)he
    is going to call this function uHint times afterwards. This enables the implementation to
    get the information for more than one file and cache it until the next calls.

    @retval osl_File_E_None on success
    @retval osl_File_E_INVAL the format of the parameters was not valid
    @retval osl_File_E_NOMEM not enough memory for allocating structures
    @retval osl_File_E_NOENT no more entries in this directory
    @retval osl_File_E_BADF invalid oslDirectory parameter
    @retval osl_File_E_OVERFLOW the value too large for defined data type

    @see osl_releaseDirectoryItem()
    @see osl_acquireDirectoryItem()
    @see osl_getDirectoryItem()
    @see osl_getFileStatus()
*/
SAL_DLLPUBLIC oslFileError SAL_CALL osl_getNextDirectoryItem(
    oslDirectory Directory,
    oslDirectoryItem *pItem,
    sal_uInt32   uHint
    );

/** Release a directory handle.

    @param[in] Directory
    A handle received by a call to osl_openDirectory().

    @retval osl_File_E_None on success
    @retval osl_File_E_INVAL the format of the parameters was not valid
    @retval osl_File_E_NOMEM not enough memory for allocating structures
    @retval osl_File_E_BADF invalid oslDirectory parameter
    @retval osl_File_E_INTR the function call was interrupted

    @see osl_openDirectory()
*/
SAL_DLLPUBLIC oslFileError SAL_CALL osl_closeDirectory(
        oslDirectory Directory);

/** Retrieve a single directory item.

    Retrieves a single directory item. The returned handle has an initial refcount of 1.
    Due to performance issues it is not recommended to use this function while
    enumerating the contents of a directory. In this case use osl_getNextDirectoryItem() instead.

    @param[in] pustrFileURL
    An absolute file URL.

    @param[out] pItem
    On success it receives a handle which can be used for subsequent calls to osl_getFileStatus().
    The handle has to be released by a call to osl_releaseDirectoryItem().

    @retval osl_File_E_None on success
    @retval osl_File_E_INVAL the format of the parameters was not valid
    @retval osl_File_E_NOMEM not enough memory for allocating structures
    @retval osl_File_E_ACCES permission denied
    @retval osl_File_E_MFILE too many open files used by the process
    @retval osl_File_E_NFILE too many open files in the system
    @retval osl_File_E_NOENT no such file or directory
    @retval osl_File_E_LOOP too many symbolic links encountered
    @retval osl_File_E_NAMETOOLONG the file name is too long
    @retval osl_File_E_NOTDIR a component of the path prefix of path is not a directory
    @retval osl_File_E_IO on I/O errors
    @retval osl_File_E_MULTIHOP multihop attempted
    @retval osl_File_E_NOLINK link has been severed
    @retval osl_File_E_FAULT bad address
    @retval osl_File_E_INTR the function call was interrupted

    @see osl_releaseDirectoryItem()
    @see osl_acquireDirectoryItem()
    @see osl_getFileStatus()
    @see osl_getNextDirectoryItem()
*/
SAL_DLLPUBLIC oslFileError SAL_CALL osl_getDirectoryItem(
    rtl_uString *pustrFileURL,
    oslDirectoryItem *pItem
    );

/** Increase the refcount of a directory item handle.

    The caller responsible for releasing the directory item handle using osl_releaseDirectoryItem().

    @param[in]  Item
    A handle received by a call to osl_getDirectoryItem() or osl_getNextDirectoryItem().

    @retval osl_File_E_None on success
    @retval osl_File_E_NOMEM not enough memory for allocating structures
    @retval osl_File_E_INVAL the format of the parameters was not valid

    @see osl_getDirectoryItem()
    @see osl_getNextDirectoryItem()
    @see osl_releaseDirectoryItem()
*/
SAL_DLLPUBLIC oslFileError SAL_CALL osl_acquireDirectoryItem(
        oslDirectoryItem Item );


/** Decrease the refcount of a directory item handle.

    Decreases the refcount of a directory item handle.
    If the refcount reaches 0 the data associated with
    this directory item handle will be released.

    @param[in]  Item
    A handle received by a call to osl_getDirectoryItem() or osl_getNextDirectoryItem().

    @retval osl_File_E_None on success
    @retval osl_File_E_NOMEM not enough memory for allocating structures
    @retval osl_File_E_INVAL the format of the parameters was not valid

    @see osl_getDirectoryItem()
    @see osl_getNextDirectoryItem()
    @see osl_acquireDirectoryItem()
*/
SAL_DLLPUBLIC oslFileError SAL_CALL osl_releaseDirectoryItem(
        oslDirectoryItem Item );

/** Determine if two directory items point the same underlying file

    The comparison is done first by URL, and then by resolving links to
    find the target, and finally by comparing inodes on unix.

    @param[in]  pItemA
    A directory handle to compare with another handle

    @param[in]  pItemB
    A directory handle to compare with pItemA

    @retval sal_True if the items point to an identical resource
    @retval sal_False if the items point to a different resource, or a fatal error occurred

    @see osl_getDirectoryItem()

    @since LibreOffice 3.6
*/
SAL_DLLPUBLIC sal_Bool SAL_CALL osl_identicalDirectoryItem(
                                        oslDirectoryItem pItemA,
                                        oslDirectoryItem pItemB );

/**
   @defgroup filetype File types

   @{
 */
typedef enum {
    osl_File_Type_Directory,        /*< directory               */
    osl_File_Type_Volume,           /*< volume (e.g. C:, A:)    */
    osl_File_Type_Regular,          /*< regular file            */
    osl_File_Type_Fifo,             /*< named pipe              */
    osl_File_Type_Socket,           /*< socket                  */
    osl_File_Type_Link,             /*< file link               */
    osl_File_Type_Special,          /*< special device file     */
    osl_File_Type_Unknown           /*< unknown file type       */
} oslFileType;
/** @} */

/**
   @defgroup fileattrs File attributes

   @{
 */
#define osl_File_Attribute_ReadOnly             0x00000001
#define osl_File_Attribute_Hidden               0x00000002
#define osl_File_Attribute_Executable           0x00000010
#define osl_File_Attribute_GrpWrite             0x00000020
#define osl_File_Attribute_GrpRead              0x00000040
#define osl_File_Attribute_GrpExe               0x00000080
#define osl_File_Attribute_OwnWrite             0x00000100
#define osl_File_Attribute_OwnRead              0x00000200
#define osl_File_Attribute_OwnExe               0x00000400
#define osl_File_Attribute_OthWrite             0x00000800
#define osl_File_Attribute_OthRead              0x00001000
#define osl_File_Attribute_OthExe               0x00002000
/** @} */

/**
   @defgroup filestatus Flags specifying which fields to retrieve by osl_getFileStatus

   @{
 */
#define osl_FileStatus_Mask_Type                0x00000001
#define osl_FileStatus_Mask_Attributes          0x00000002
#define osl_FileStatus_Mask_CreationTime        0x00000010
#define osl_FileStatus_Mask_AccessTime          0x00000020
#define osl_FileStatus_Mask_ModifyTime          0x00000040
#define osl_FileStatus_Mask_FileSize            0x00000080
#define osl_FileStatus_Mask_FileName            0x00000100
#define osl_FileStatus_Mask_FileURL             0x00000200
#define osl_FileStatus_Mask_LinkTargetURL       0x00000400
#define osl_FileStatus_Mask_All                 0x7FFFFFFF
#define osl_FileStatus_Mask_Validate            0x80000000
/** @} */

/** Structure containing information about files and directories

    @see    osl_getFileStatus()
    @see    oslFileType
*/
typedef struct _oslFileStatus {
/** Must be initialized with the size in bytes of the structure before passing it to any function */
    sal_uInt32      uStructSize;
/** Determines which members of the structure contain valid data */
    sal_uInt32      uValidFields;
/** The type of the file (file, directory, volume). */
    oslFileType eType;
/** File attributes */
    sal_uInt64  uAttributes;
/** First creation time in nanoseconds since 1/1/1970. Can be the last modify time depending on
    platform or file system. */
    TimeValue   aCreationTime;
/** Last access time in nanoseconds since 1/1/1970. Can be the last modify time depending on
    platform or file system. */
    TimeValue   aAccessTime;
/** Last modify time in nanoseconds since 1/1/1970. */
    TimeValue   aModifyTime;
/** Size in bytes of the file. Zero for directories and volumes. */
    sal_uInt64  uFileSize;
/** Case correct name of the file. Should be set to zero before calling osl_getFileStatus
    and released after usage. */
    rtl_uString *ustrFileName;
/** Full URL of the file. Should be set to zero before calling osl_getFileStatus
    and released after usage. */
    rtl_uString *ustrFileURL;
/** Full URL of the target file if the file itself is a link.
    Should be set to zero before calling osl_getFileStatus
    and released after usage. */
    rtl_uString *ustrLinkTargetURL;
} oslFileStatus;

/** Retrieve information about a single file or directory.

    @param[in]  Item
    A handle received by a previous call to osl_getDirectoryItem() or osl_getNextDirectoryItem().

    @param[in,out] pStatus
    Points to a structure which receives the information of the file or directory
    represented by the handle Item. The member uStructSize has to be initialized to
    sizeof(oslFileStatus) before calling this function.

    @param[in]  uFieldMask
    Specifies which fields of the structure pointed to by pStatus are of interest to the caller.

    @retval osl_File_E_None on success
    @retval osl_File_E_NOMEM not enough memory for allocating structures
    @retval osl_File_E_INVAL the format of the parameters was not valid
    @retval osl_File_E_LOOP too many symbolic links encountered
    @retval osl_File_E_ACCES permission denied
    @retval osl_File_E_NOENT no such file or directory
    @retval osl_File_E_NAMETOOLONG file name too long
    @retval osl_File_E_BADF invalid oslDirectoryItem parameter
    @retval osl_File_E_FAULT bad address
    @retval osl_File_E_OVERFLOW value too large for defined data type
    @retval osl_File_E_INTR function call was interrupted
    @retval osl_File_E_NOLINK link has been severed
    @retval osl_File_E_MULTIHOP components of path require hopping to multiple
        remote machines and the file system does not allow it
    @retval osl_File_E_MFILE too many open files used by the process
    @retval osl_File_E_NFILE too many open files in the system
    @retval osl_File_E_NOSPC no space left on device
    @retval osl_File_E_NXIO no such device or address
    @retval osl_File_E_IO on I/O errors
    @retval osl_File_E_NOSYS function not implemented

    @see osl_getDirectoryItem()
    @see osl_getNextDirectoryItem()
    @see oslFileStatus
*/
SAL_DLLPUBLIC oslFileError SAL_CALL osl_getFileStatus(
        oslDirectoryItem Item, oslFileStatus *pStatus, sal_uInt32 uFieldMask );

typedef void *oslVolumeDeviceHandle;

/** Release a volume device handle.

    Releases the given oslVolumeDeviceHandle which was acquired by a call to
    osl_getVolumeInformation() or osl_acquireVolumeDeviceHandle().

    @param[in] Handle
    An oslVolumeDeviceHandle received by a call to osl_getVolumeInformation().

    @retval
    osl_File_E_None on success

    @todo
    specify all error codes that may be returned

    @see osl_acquireVolumeDeviceHandle()
    @see osl_getVolumeInformation()
*/
SAL_DLLPUBLIC oslFileError SAL_CALL osl_releaseVolumeDeviceHandle(
        oslVolumeDeviceHandle Handle );

/** Acquire a volume device handle.

    Acquires the given oslVolumeDeviceHandle which was acquired by a call to
    osl_getVolumeInformation(). The caller is responsible for releasing the
    acquired handle by calling osl_releaseVolumeDeviceHandle().

    @param[in] Handle
    An oslVolumeDeviceHandle received by a call to osl_getVolumeInformation().

    @retval
    osl_File_E_None on success

    @todo
    specify all error codes that may be returned

    @see osl_getVolumeInformation()
*/
SAL_DLLPUBLIC oslFileError SAL_CALL osl_acquireVolumeDeviceHandle(
        oslVolumeDeviceHandle Handle );

/** Get the full qualified URL where a device is mounted to.

    @param[in] Handle
    An oslVolumeDeviceHandle received by a call to osl_getVolumeInformation().

    @param[out] ppustrDirectoryURL
    Receives the full qualified URL where the device is mounted to.

    @retval osl_File_E_None on success
    @retval osl_File_E_NOMEM not enough memory for allocating structures
    @retval osl_File_E_INVAL the format of the parameters was not valid
    @retval osl_File_E_ACCES permission denied
    @retval osl_File_E_NXIO  no such device or address
    @retval osl_File_E_NODEV no such device
    @retval osl_File_E_NOENT no such file or directory
    @retval osl_File_E_FAULT bad address
    @retval osl_FilE_E_INTR function call was interrupted
    @retval osl_File_E_IO on I/O errors
    @retval osl_File_E_MULTIHOP multihop attempted
    @retval osl_File_E_NOLINK link has been severed
    @retval osl_File_E_EOVERFLOW value too large for defined data type

    @see    osl_getVolumeInformation()
*/
SAL_DLLPUBLIC oslFileError SAL_CALL osl_getVolumeDeviceMountPath(
        oslVolumeDeviceHandle Handle, rtl_uString **ppustrDirectoryURL);

/**
   @defgroup volattrs Volume attributes

   @{
 */
#define osl_Volume_Attribute_Removeable            0x00000001L
#define osl_Volume_Attribute_Remote                0x00000002L
#define osl_Volume_Attribute_CompactDisc           0x00000004L
#define osl_Volume_Attribute_FixedDisk             0x00000008L
#define osl_Volume_Attribute_RAMDisk               0x00000010L
#define osl_Volume_Attribute_FloppyDisk            0x00000020L

#define osl_Volume_Attribute_Case_Is_Preserved     0x00000040L
#define osl_Volume_Attribute_Case_Sensitive        0x00000080L

/** @} */

/**
    @defgroup volinfoflags Flags specifying which fields to retrieve by osl_getVolumeInfo

    @{
 */

#define osl_VolumeInfo_Mask_Attributes             0x00000001L
#define osl_VolumeInfo_Mask_TotalSpace             0x00000002L
#define osl_VolumeInfo_Mask_UsedSpace              0x00000004L
#define osl_VolumeInfo_Mask_FreeSpace              0x00000008L
#define osl_VolumeInfo_Mask_MaxNameLength          0x00000010L
#define osl_VolumeInfo_Mask_MaxPathLength          0x00000020L
#define osl_VolumeInfo_Mask_FileSystemName         0x00000040L
#define osl_VolumeInfo_Mask_DeviceHandle           0x00000080L
#define osl_VolumeInfo_Mask_FileSystemCaseHandling 0x00000100L

/** @} */

/** Structure containing information about volumes

    @see    osl_getVolumeInformation()
    @see    oslFileType
*/

typedef struct _oslVolumeInfo {
/** Must be initialized with the size in bytes of the structure before
    passing it to any function */
    sal_uInt32      uStructSize;
/** Determines which members of the structure contain valid data */
    sal_uInt32      uValidFields;
/** Attributes of the volume (remote and/or removable) */
    sal_uInt32      uAttributes;
/** Total available space on the volume for the current process/user */
    sal_uInt64      uTotalSpace;
/** Used space on the volume for the current process/user */
    sal_uInt64      uUsedSpace;
/** Free space on the volume for the current process/user */
    sal_uInt64      uFreeSpace;
/** Maximum length of file name of a single item */
    sal_uInt32      uMaxNameLength;
/** Maximum length of a full qualified path in system notation */
    sal_uInt32      uMaxPathLength;
/** Points to a string that receives the name of the file system type. String
    should be set to zero before calling osl_getVolumeInformation and released
    after usage. */
    rtl_uString     *ustrFileSystemName;
/** Pointer to handle the receives underlying device. Handle should be set to
    zero before calling osl_getVolumeInformation */
    oslVolumeDeviceHandle   *pDeviceHandle;
} oslVolumeInfo;

/** Retrieve information about a volume.

    Retrieves information about a volume. A volume can either be a mount point, a network
    resource or a drive depending on Operating System and File System. Before calling this
    function osl_getFileStatus() should be called to determine if the type is
    osl_file_Type_Volume.

    @param[in] pustrDirectoryURL
    Full qualified URL of the volume

    @param[out] pInfo
    On success it receives information about the volume.

    @param[in] uFieldMask
    Specifies which members of the structure should be filled

    @retval osl_File_E_None on success
    @retval osl_File_E_NOMEM not enough memory for allocating structures
    @retval osl_File_E_INVAL the format of the parameters was not valid
    @retval osl_File_E_NOTDIR not a directory
    @retval osl_File_E_NAMETOOLONG file name too long
    @retval osl_File_E_NOENT no such file or directory
    @retval osl_File_E_ACCES permission denied
    @retval osl_File_E_LOOP too many symbolic links encountered
    @retval ols_File_E_FAULT Bad address
    @retval osl_File_E_IO on I/O errors
    @retval osl_File_E_NOSYS function not implemented
    @retval osl_File_E_MULTIHOP multihop attempted
    @retval osl_File_E_NOLINK link has been severed
    @retval osl_File_E_INTR function call was interrupted

    @see    osl_getFileStatus()
    @see    oslVolumeInfo
*/
SAL_DLLPUBLIC oslFileError SAL_CALL osl_getVolumeInformation(
    rtl_uString *pustrDirectoryURL,
    oslVolumeInfo *pInfo,
    sal_uInt32 uFieldMask );

typedef void *oslFileHandle;

/* Open flags */

#define osl_File_OpenFlag_Read      0x00000001L
#define osl_File_OpenFlag_Write     0x00000002L
#define osl_File_OpenFlag_Create    0x00000004L
#define osl_File_OpenFlag_NoLock    0x00000008L
/* larger bit-fields reserved for internal use cf. detail/file.h */

/** Open a regular file.

    Open a file. Only regular files can be opened.

    @param[in] pustrFileURL
    The full qualified URL of the file to open.

    @param[out] pHandle
    On success it receives a handle to the open file.

    @param[in] uFlags
    Specifies the open mode.

    On Android, if the file path is below the /assets folder, the file
    exists only as a hopefully uncompressed element inside the app
    package (.apk), which has been mapped into memory as a whole by
    the LibreOffice Android bootstrapping code. So files "opened" from
    there aren't actually files in the OS sense.

    @retval osl_File_E_None on success
    @retval osl_File_E_NOMEM not enough memory for allocating structures
    @retval osl_File_E_INVAL the format of the parameters was not valid
    @retval osl_File_E_NAMETOOLONG pathname was too long
    @retval osl_File_E_NOENT no such file or directory
    @retval osl_File_E_ACCES permission denied
    @retval osl_File_E_AGAIN a write lock could not be established
    @retval osl_File_E_NOTDIR not a directory
    @retval osl_File_E_NXIO no such device or address
    @retval osl_File_E_NODEV no such device
    @retval osl_File_E_ROFS read-only file system
    @retval osl_File_E_TXTBSY text file busy
    @retval osl_File_E_FAULT bad address
    @retval osl_File_E_LOOP too many symbolic links encountered
    @retval osl_File_E_NOSPC no space left on device
    @retval osl_File_E_ISDIR is a directory
    @retval osl_File_E_MFILE too many open files used by the process
    @retval osl_File_E_NFILE too many open files in the system
    @retval osl_File_E_DQUOT quota exceeded
    @retval osl_File_E_EXIST file exists
    @retval osl_FilE_E_INTR function call was interrupted
    @retval osl_File_E_IO on I/O errors
    @retval osl_File_E_MULTIHOP multihop attempted
    @retval osl_File_E_NOLINK link has been severed
    @retval osl_File_E_EOVERFLOW value too large for defined data type

    @see osl_closeFile()
    @see osl_setFilePos()
    @see osl_getFilePos()
    @see osl_readFile()
    @see osl_writeFile()
    @see osl_setFileSize()
    @see osl_getFileSize()
*/
SAL_DLLPUBLIC oslFileError SAL_CALL osl_openFile(
        rtl_uString *pustrFileURL, oslFileHandle *pHandle, sal_uInt32 uFlags );

#define osl_Pos_Absolut 1
#define osl_Pos_Current 2
#define osl_Pos_End     3

/** Set the internal position pointer of an open file.

    @param[in] Handle
    Handle to a file received by a previous call to osl_openFile().

    @param[in] uHow
    How to calculate the offset - osl_Pos_Absolut means start at the
    beginning of the file, osl_Pos_Current means offset from the current
    seek position and osl_Pos_End means the offset will be negative and
    the position will be calculated backwards from the end of the file by
    the offset provided.

    @param[in] uPos
    Seek offset, depending on uHow. If uHow is osl_Pos_End then the value must be negative.

    @retval osl_File_E_None on success
    @retval osl_File_E_INVAL the format of the parameters was not valid
        (e.g. if uHow is osl_Pos_End then must be negative)
    @retval osl_File_E_OVERFLOW the resulting file offset would be a
        value which cannot be represented correctly for regular files

    @see    osl_openFile()
    @see    osl_getFilePos()
*/
SAL_WARN_UNUSED_RESULT SAL_DLLPUBLIC oslFileError SAL_CALL osl_setFilePos(
        oslFileHandle Handle, sal_uInt32 uHow, sal_Int64 uPos );

/** Retrieve the current position of the internal pointer of an open file.

    @param[in] Handle
    Handle to a file received by a previous call to osl_openFile().

    @param[out] pPos
    On success receives the current position of the file pointer.

    @retval osl_File_E_None on success
    @retval osl_File_E_INVAL the format of the parameters was not valid
    @retval osl_File_E_OVERFLOW the resulting file offset would be a value
        which cannot be represented correctly for regular files

    @see osl_openFile()
    @see osl_setFilePos()
    @see osl_readFile()
    @see osl_writeFile()
*/
SAL_DLLPUBLIC oslFileError SAL_CALL osl_getFilePos(
        oslFileHandle Handle, sal_uInt64 *pPos );

/** Set the file size of an open file.

    Sets the file size of an open file. The file can be truncated or enlarged by the function.
    The position of the file pointer is not affeced by this function.

    @param[in] Handle
    Handle to a file received by a previous call to osl_openFile().

    @param[in] uSize
    New size in bytes.

    @retval osl_File_E_None on success
    @retval osl_File_E_INVAL the format of the parameters was not valid
    @retval osl_File_E_OVERFLOW the resulting file offset would be a value
        which cannot be represented correctly for regular files

    @see osl_openFile()
    @see osl_setFilePos()
    @see osl_getFileStatus()
    @see osl_getFileSize()
*/
SAL_DLLPUBLIC oslFileError SAL_CALL osl_setFileSize(
        oslFileHandle Handle, sal_uInt64 uSize );

/** Get the file size of an open file.

    Gets the file size of an open file.
    The position of the file pointer is not affeced by this function.

    @param[in] Handle
    Handle to a file received by a previous call to osl_openFile().

    @param[out] pSize
    Current size in bytes.

    @retval osl_File_E_None on success
    @retval osl_File_E_INVAL the format of the parameters was not valid
    @retval osl_File_E_OVERFLOW the resulting file offset would be a value
        which cannot be represented correctly for regular files

    @see osl_openFile()
    @see osl_setFilePos()
    @see osl_getFileStatus()
*/
SAL_DLLPUBLIC oslFileError SAL_CALL osl_getFileSize(
        oslFileHandle Handle, sal_uInt64 *pSize );

/** Indicate that the file can be accessed randomly (i.e. there is no sequential
    reading). Basically it means that the first byte of every page in the
    file-mapping will be read.

    @since UDK 3.2.10
 */
#define osl_File_MapFlag_RandomAccess ((sal_uInt32)(0x1))

/** Map flag denoting that the mapped address space will be accessed by the
    process soon (and it is advantageous for the operating system to already
    start paging in the data).

    @attention As this assumes that madvise() with the WILLREAD flag is
    asynchronous (which is I'm afraid an incorrect assumption), Linux systems
    will ignore this flag.

    @since UDK 3.2.12
*/
#define osl_File_MapFlag_WillNeed ((sal_uInt32)(0x2))

/** Map a shared file into memory.

    Files can be mapped into memory to allow multiple processes to use
    this memory-mapped file to share data.

    On Android, if the Handle refers to a file that is actually inside
    the app package (.apk zip archive), no new mapping is created,
    just a pointer to the file inside the already mapped .apk is
    returned.

    @param[in] Handle       Handle of the file to be mapped.
    @param[in,out] ppAddr   Memory address of the mapped file
    @param[in] uLength      Amount to map of the file from the offset
    @param[in] uOffset      Offset into the file to map
    @param[in] uFlags       osl_File_MapFlag_RandomAccess or
                            osl_File_MapFlag_WillNeed

    @retval osl_File_E_None on success
    @retval osl_File_E_INVAL invalid file handle, on Unix systems also
                can mean that the address, length of the file or the
                file offset are too large or not aligned on a page
                boundary; on Linux can also mean after Linux 2.6.12
                that the length was set to 0 (illogical).
    @retval osl_File_E_OVERFLOW requested mapping size too large,
                or the file offset was too large
    @retval osl_File_E_ACCES file descriptor to non-regular file, or
                file descriptor not open for reading, or the file
                descriptor is not open in read/write mode
    @retval osl_File_E_AGAIN file has been locked, or too much memory
                has been locked
    @retval osl_File_E_NODEV underlying filesystem of specified file
                does not support memory mapping
    @retval osl_File_E_TXTBSY on Linux means that writing to the mapped
                file is denied, but the file descriptor points to a file
                open for writing
    @retval osl_File_E_NOMEM process's maximum number of mappings have
                been exceeded

    @since UDK 3.2.10
*/
SAL_DLLPUBLIC oslFileError SAL_CALL osl_mapFile (
  oslFileHandle Handle,
  void**        ppAddr,
  sal_uInt64    uLength,
  sal_uInt64    uOffset,
  sal_uInt32    uFlags
);


#ifndef ANDROID

/** Unmap a shared file from memory.

    This function just won't work on Android in general where for
    (uncompressed) files inside the .apk, per SDK conventions in the
    /assets folder, osl_mapFile() returns a pointer to the file inside
    the already by LibreOffice Android-specific bootstrapping code
    mmapped .apk archive. We can't go and randomly munmap part of the
    .apk archive. So this function is not present on Android.

    @since UDK 3.2.10
*/
SAL_DLLPUBLIC oslFileError SAL_CALL osl_unmapFile (
  void*      pAddr,
  sal_uInt64 uLength
);

#endif

/** Unmap a file segment from memory.

    Like osl_unmapFile(), but takes also the oslFileHandle argument
    passed to osl_mapFile() when creating this mapping.

    On Android, for files below /assets, i.e. located inside the app
    archive (.apk), this won't actually unmap anything; all the .apk
    stays mapped.

    @since UDK 3.6
*/
SAL_DLLPUBLIC oslFileError SAL_CALL osl_unmapMappedFile (
  oslFileHandle Handle,
  void*      pAddr,
  sal_uInt64 uLength
);

/** Read a number of bytes from a file.

    Reads a number of bytes from a file. The internal file pointer is
    increased by the number of bytes read.

    @param[in] Handle
    Handle to a file received by a previous call to osl_openFile().

    @param[out] pBuffer
    Points to a buffer which receives data. The buffer must be large enough
    to hold uBytesRequested bytes.

    @param[in] uBytesRequested
    Number of bytes which should be retrieved.

    @param[out] pBytesRead
    On success the number of bytes which have actually been retrieved.

    @retval osl_File_E_None on success
    @retval osl_File_E_INVAL the format of the parameters was not valid
    @retval osl_File_E_INTR function call was interrupted
    @retval osl_File_E_IO on I/O errors
    @retval osl_File_E_ISDIR is a directory
    @retval osl_File_E_BADF bad file
    @retval osl_File_E_FAULT bad address
    @retval osl_File_E_AGAIN operation would block
    @retval osl_File_E_NOLINK link has been severed

    @see osl_openFile()
    @see osl_writeFile()
    @see osl_readLine()
    @see osl_setFilePos()
*/
SAL_DLLPUBLIC oslFileError SAL_CALL osl_readFile(
        oslFileHandle Handle, void *pBuffer, sal_uInt64 uBytesRequested, sal_uInt64 *pBytesRead );

/** Test if the end of a file is reached.

    @param[in] Handle
    Handle to a file received by a previous call to osl_openFile().

    @param[out] pIsEOF
    Points to a variable that receives the end-of-file status.

    @retval osl_File_E_None on success
    @retval osl_File_E_INVAL the format of the parameters was not valid
    @retval osl_File_E_INTR function call was interrupted
    @retval osl_File_E_IO on I/O errors
    @retval osl_File_E_ISDIR is a directory
    @retval osl_File_E_BADF bad file
    @retval osl_File_E_FAULT bad address
    @retval osl_File_E_AGAIN operation would block
    @retval osl_File_E_NOLINK link has been severed

    @see osl_openFile()
    @see osl_readFile()
    @see osl_readLine()
    @see osl_setFilePos()
*/
SAL_DLLPUBLIC oslFileError SAL_CALL osl_isEndOfFile(
        oslFileHandle Handle, sal_Bool *pIsEOF );

/** Write a number of bytes to a file.

    Writes a number of bytes to a file.
    The internal file pointer is increased by the number of bytes read.

    @param[in] Handle
    Handle to a file received by a previous call to osl_openFile().

    @param[in] pBuffer
    Points to a buffer which contains the data.

    @param[in] uBytesToWrite
    Number of bytes which should be written.

    @param[out] pBytesWritten
    On success the number of bytes which have actually been written.

    @retval osl_File_E_None on success
    @retval osl_File_E_INVAL the format of the parameters was not valid
    @retval osl_File_E_FBIG file too large
    @retval osl_File_E_DQUOT quota exceeded
    @retval osl_File_E_AGAIN operation would block
    @retval osl_File_E_BADF bad file
    @retval osl_File_E_FAULT bad address
    @retval osl_File_E_INTR function call was interrupted
    @retval osl_File_E_IO on I/O errors
    @retval osl_File_E_NOLCK no record locks available
    @retval osl_File_E_NOLINK link has been severed
    @retval osl_File_E_NOSPC no space left on device
    @retval osl_File_E_NXIO no such device or address

    @see osl_openFile()
    @see osl_readFile()
    @see osl_setFilePos()
*/
SAL_DLLPUBLIC oslFileError SAL_CALL osl_writeFile(
        oslFileHandle Handle, const void *pBuffer, sal_uInt64 uBytesToWrite, sal_uInt64 *pBytesWritten );

/** Read a number of bytes from a specified offset in a file.

    The current position of the internal file pointer may or may not be changed.

    @param[in] Handle
    Handle to a file received by a previous call to osl_openFile().

    @param[in] uOffset
    Offset position from start of file where read starts

    @param[out] pBuffer
    Points to a buffer which receives data. The buffer must be large enough
    to hold uBytesRequested bytes.

    @param[in] uBytesRequested
    Number of bytes which should be retrieved.

    @param[out] pBytesRead
    On success the number of bytes which have actually been retrieved.

    @retval osl_File_E_None on success
    @retval osl_File_E_INVAL the format of the parameters was not valid
    @retval osl_File_E_INTR function call was interrupted
    @retval osl_File_E_IO on I/O errors
    @retval osl_File_E_ISDIR is a directory
    @retval osl_File_E_BADF bad file
    @retval osl_File_E_FAULT bad address
    @retval osl_File_E_AGAIN operation would block
    @retval osl_File_E_NOLINK link has been severed
    @since UDK 3.2.10
 */
SAL_DLLPUBLIC oslFileError SAL_CALL osl_readFileAt(
  oslFileHandle Handle,
  sal_uInt64    uOffset,
  void*         pBuffer,
  sal_uInt64    uBytesRequested,
  sal_uInt64*   pBytesRead
);

/** Write a number of bytes to a specified offset in a file.

    The current position of the internal file pointer may or may not be changed.

    @param[in] Handle
    Handle to a file received by a previous call to osl_openFile().

    @param[in] uOffset
    Position of file to write into.

    @param[in] pBuffer
    Points to a buffer which contains the data.

    @param[in] uBytesToWrite
    Number of bytes which should be written.

    @param[out] pBytesWritten
    On success the number of bytes which have actually been written.

    @retval osl_File_E_None on success
    @retval osl_File_E_INVAL the format of the parameters was not valid
    @retval osl_File_E_FBIG file too large
    @retval osl_File_E_DQUOT quota exceeded
    @retval osl_File_E_AGAIN operation would block
    @retval osl_File_E_BADF bad file
    @retval osl_File_E_FAULT bad address
    @retval osl_File_E_INTR function call was interrupted
    @retval osl_File_E_IO on I/O errors
    @retval osl_File_E_NOLCK no record locks available
    @retval osl_File_E_NOLINK link has been severed
    @retval osl_File_E_NOSPC no space left on device
    @retval osl_File_E_NXIO no such device or address
    @since UDK 3.2.10
*/
SAL_DLLPUBLIC oslFileError SAL_CALL osl_writeFileAt(
  oslFileHandle Handle,
  sal_uInt64    uOffset,
  const void*   pBuffer,
  sal_uInt64    uBytesToWrite,
  sal_uInt64*   pBytesWritten
);

/** Read a line from a file.

    Reads a line from a file. The new line delimiter is NOT returned!

    @param[in] Handle
    Handle to a file received by a previous call to osl_openFile().

    @param[in,out] ppSequence
    A pointer pointer to a sal_Sequence that will hold the line read on success.

    @retval osl_File_E_None on success
    @retval osl_File_E_INVAL the format of the parameters was not valid
    @retval osl_File_E_INTR function call was interrupted
    @retval osl_File_E_IO on I/O errors
    @retval osl_File_E_ISDIR is a directory
    @retval osl_File_E_BADF bad file
    @retval osl_File_E_FAULT bad address
    @retval osl_File_E_AGAIN operation would block
    @retval osl_File_E_NOLINK link has been severed

    @see osl_openFile()
    @see osl_readFile()
    @see osl_writeFile()
    @see osl_setFilePos()
*/
SAL_DLLPUBLIC oslFileError SAL_CALL osl_readLine(
        oslFileHandle Handle, sal_Sequence** ppSequence );

/** Synchronize the memory representation of a file with that on the physical medium.

     The function ensures that all modified data and attributes of the file associated with
     the given file handle have been written to the physical medium.
     In case the hard disk has a write cache enabled, the data may not really be on
     permanent storage when osl_syncFile returns.

      @param Handle
      [in] Handle to a file received by a previous call to osl_openFile().

      @retval osl_File_E_None On success
      @retval osl_File_E_INVAL The value of the input parameter is invalid
      @retval osl_File_E_BADF The file associated with the given file handle is not open for writing
      @retval osl_File_E_IO An I/O error occurred
      @retval osl_File_E_NOSPC There is no enough space on the target device
      @retval osl_File_E_ROFS The file associated with the given file handle is located on a read only file system
      @retval osl_File_E_TIMEDOUT A remote connection timed out. This may happen when a file is on a remote location

      @see osl_openFile()
      @see osl_writeFile()
*/
SAL_DLLPUBLIC oslFileError SAL_CALL osl_syncFile( oslFileHandle Handle );

/** Close an open file.

    @param[in] Handle
    Handle to a file received by a previous call to osl_openFile().

    @retval osl_File_E_None on success
    @retval osl_File_E_INVAL the format of the parameters was not valid
    @retval osl_File_E_BADF Bad file
    @retval osl_File_E_INTR function call was interrupted
    @retval osl_File_E_NOLINK link has been severed
    @retval osl_File_E_NOSPC no space left on device
    @retval osl_File_E_IO on I/O errors

    @see osl_openFile()
*/
SAL_DLLPUBLIC oslFileError SAL_CALL osl_closeFile( oslFileHandle Handle );

/** Create a directory.

    @param[in] pustrDirectoryURL
    Full qualified URL of the directory to create.

    @retval osl_File_E_None on success
    @retval osl_File_E_INVAL the format of the parameters was not valid
    @retval osl_File_E_NOMEM not enough memory for allocating structures
    @retval osl_File_E_EXIST file exists
    @retval osl_File_E_ACCES permission denied
    @retval osl_File_E_NAMETOOLONG file name too long
    @retval osl_File_E_NOENT no such file or directory
    @retval osl_File_E_NOTDIR not a directory
    @retval osl_File_E_ROFS read-only file system
    @retval osl_File_E_NOSPC no space left on device
    @retval osl_File_E_DQUOT quota exceeded
    @retval osl_File_E_LOOP too many symbolic links encountered
    @retval osl_File_E_FAULT bad address
    @retval osl_FileE_IO on I/O errors
    @retval osl_File_E_MLINK too many links
    @retval osl_File_E_MULTIHOP multihop attempted
    @retval osl_File_E_NOLINK link has been severed

    @see osl_removeDirectory()
*/
SAL_DLLPUBLIC oslFileError SAL_CALL osl_createDirectory( rtl_uString* pustrDirectoryURL );

/** Create a directory, passing flags.

    @param url
    File URL of the directory to create.

    @param flags
    A combination of the same osl_File_OpenFlag_*s used by osl_openFile,
    except that osl_File_OpenFlag_Create is implied and ignored.  Support for
    the various flags can differ across operating systems.

    @see osl_createDirectory()

    @since LibreOffice 4.3
*/
SAL_DLLPUBLIC oslFileError SAL_CALL osl_createDirectoryWithFlags(
    rtl_uString * url, sal_uInt32 flags);

/** Remove an empty directory.

    @param[in] pustrDirectoryURL
    Full qualified URL of the directory.

    @retval osl_File_E_None on success
    @retval osl_File_E_INVAL the format of the parameters was not valid
    @retval osl_File_E_NOMEM not enough memory for allocating structures
    @retval osl_File_E_PERM operation not permitted
    @retval osl_File_E_ACCES permission denied
    @retval osl_File_E_NOENT no such file or directory
    @retval osl_File_E_NOTDIR not a directory
    @retval osl_File_E_NOTEMPTY directory not empty
    @retval osl_File_E_FAULT bad address
    @retval osl_File_E_NAMETOOLONG file name too long
    @retval osl_File_E_BUSY device or resource busy
    @retval osl_File_E_ROFS read-only file system
    @retval osl_File_E_LOOP too many symbolic links encountered
    @retval osl_File_E_EXIST file exists
    @retval osl_File_E_IO on I/O errors
    @retval osl_File_E_MULTIHOP multihop attempted
    @retval osl_File_E_NOLINK link has been severed

    @see osl_createDirectory()
*/
SAL_DLLPUBLIC oslFileError SAL_CALL osl_removeDirectory( rtl_uString* pustrDirectoryURL );

/** Function pointer representing a function that will be called by osl_createDirectoryPath
    if a directory has been created.

    To avoid unpredictable results the callee must not access the directory whose
    creation is just notified.

    @param pData
    [in] User specified data given in osl_createDirectoryPath.

    @param aDirectoryUrl
    [in] The absolute file URL of the directory that was just created by
    osl_createDirectoryPath.

    @see osl_createDirectoryPath
*/
typedef void (SAL_CALL *oslDirectoryCreationCallbackFunc)(void* pData, rtl_uString* aDirectoryUrl);

/** Create a directory path.

    The osl_createDirectoryPath function creates a specified directory path.
    All nonexisting sub directories will be created.

    @attention PLEASE NOTE You cannot rely on getting the error code
    osl_File_E_EXIST for existing directories. Programming against this error
    code is in general a strong indication of a wrong usage of osl_createDirectoryPath.

    @param aDirectoryUrl
    [in] The absolute file URL of the directory path to create.
    A relative file URL will not be accepted.

    @param aDirectoryCreationCallbackFunc
    [in] Pointer to a function that will be called synchronously
    for each sub directory that was created. The value of this
    parameter may be NULL, in this case notifications will not be
    sent.

    @param pData
    [in] User specified data to be passed to the directory creation
    callback function. The value of this parameter may be arbitrary
    and will not be interpreted by osl_createDirectoryPath.

    @retval osl_File_E_None On success
    @retval osl_File_E_INVAL The format of the parameters was not valid
    @retval osl_File_E_ACCES Permission denied
    @retval osl_File_E_EXIST The final node of the specified directory path already exist
    @retval osl_File_E_NAMETOOLONG The name of the specified directory path exceeds the maximum allowed length
    @retval osl_File_E_NOTDIR A component of the specified directory path already exist as file in any part of the directory path
    @retval osl_File_E_ROFS Read-only file system
    @retval osl_File_E_NOSPC No space left on device
    @retval osl_File_E_DQUOT Quota exceeded
    @retval osl_File_E_FAULT Bad address
    @retval osl_File_E_IO I/O error
    @retval osl_File_E_LOOP Too many symbolic links encountered
    @retval osl_File_E_NOLINK Link has been severed
    @retval osl_File_E_invalidError An unknown error occurred

    @see oslDirectoryCreationFunc
    @see oslFileError
    @see osl_createDirectory
*/
SAL_DLLPUBLIC oslFileError SAL_CALL osl_createDirectoryPath(
    rtl_uString* aDirectoryUrl,
    oslDirectoryCreationCallbackFunc aDirectoryCreationCallbackFunc,
    void* pData);

/** Remove a regular file.

    @param[in] pustrFileURL
    Full qualified URL of the file to remove.

    @retval osl_File_E_None on success
    @retval osl_File_E_INVAL the format of the parameters was not valid
    @retval osl_File_E_NOMEM not enough memory for allocating structures
    @retval osl_File_E_ACCES permission denied
    @retval osl_File_E_PERM operation not permitted
    @retval osl_File_E_NAMETOOLONG file name too long
    @retval osl_File_E_NOENT no such file or directory
    @retval osl_File_E_ISDIR is a directory
    @retval osl_File_E_ROFS read-only file system
    @retval osl_File_E_FAULT bad address
    @retval osl_File_E_LOOP too many symbolic links encountered
    @retval osl_File_E_IO on I/O errors
    @retval osl_File_E_BUSY device or resource busy
    @retval osl_File_E_INTR function call was interrupted
    @retval osl_File_E_MULTIHOP multihop attempted
    @retval osl_File_E_NOLINK link has been severed
    @retval osl_File_E_TXTBSY text file busy

    @see osl_openFile()
*/
SAL_DLLPUBLIC oslFileError SAL_CALL osl_removeFile(
        rtl_uString* pustrFileURL );

/** Copy a file to a new destination.

    Copies a file to a new destination. Copies only files not directories.
    No assumptions should be made about preserving attributes or file time.

    @param[in] pustrSourceFileURL
    Full qualified URL of the source file.

    @param[in] pustrDestFileURL
    Full qualified URL of the destination file. A directory is NOT a valid destination file!

    @retval osl_File_E_None on success
    @retval osl_File_E_INVAL the format of the parameters was not valid
    @retval osl_File_E_NOMEM not enough memory for allocating structures
    @retval osl_File_E_ACCES permission denied
    @retval osl_File_E_PERM operation not permitted
    @retval osl_File_E_NAMETOOLONG file name too long
    @retval osl_File_E_NOENT no such file or directory
    @retval osl_File_E_ISDIR is a directory
    @retval osl_File_E_ROFS read-only file system
    @retval osl_File_E_BUSY if the implementation internally requires resources that are
        (temporarily) unavailable (added with LibreOffice 4.4)

    @see    osl_moveFile()
    @see    osl_removeFile()
*/
SAL_DLLPUBLIC oslFileError SAL_CALL osl_copyFile(
        rtl_uString* pustrSourceFileURL, rtl_uString *pustrDestFileURL );

/** Move a file or directory to a new destination or renames it.

    Moves a file or directory to a new destination or renames it.
    File time and attributes are preserved.

    @param[in] pustrSourceFileURL
    Full qualified URL of the source file.

    @param[in] pustrDestFileURL
    Full qualified URL of the destination file. An existing directory is NOT a valid destination !

    @retval osl_File_E_None on success
    @retval osl_File_E_INVAL the format of the parameters was not valid
    @retval osl_File_E_NOMEM not enough memory for allocating structures
    @retval osl_File_E_ACCES permission denied
    @retval osl_File_E_PERM operation not permitted
    @retval osl_File_E_NAMETOOLONG file name too long
    @retval osl_File_E_NOENT no such file or directory
    @retval osl_File_E_ROFS read-only file system
    @retval osl_File_E_BUSY if the implementation internally requires resources that are
        (temporarily) unavailable (added with LibreOffice 4.4)

    @see osl_copyFile()
*/
SAL_DLLPUBLIC oslFileError SAL_CALL osl_moveFile(
        rtl_uString* pustrSourceFileURL, rtl_uString *pustrDestFileURL );

/** Determine a valid unused canonical name for a requested name.

    Determines a valid unused canonical name for a requested name.
    Depending on the Operating System and the File System the illegal characters are replaced by valid ones.
    If a file or directory with the requested name already exists a new name is generated following
    the common rules on the actual Operating System and File System.

    @param[in] pustrRequestedURL
    Requested name of a file or directory.

    @param[out] ppustrValidURL
    On success receives a name which is unused and valid on the actual Operating System and
    File System.

    @retval osl_File_E_None on success
    @retval osl_File_E_INVAL the format of the parameters was not valid

    @see osl_getFileStatus()
*/
SAL_DLLPUBLIC oslFileError SAL_CALL osl_getCanonicalName(
        rtl_uString *pustrRequestedURL, rtl_uString **ppustrValidURL);

/** Convert a path relative to a given directory into an full qualified file URL.

    Convert a path relative to a given directory into an full qualified file URL.
    The function resolves symbolic links if possible and path ellipses, so on success
    the resulting absolute path is fully resolved.

    @param[in] pustrBaseDirectoryURL
    Base directory URL to which the relative path is related to.

    @param[in] pustrRelativeFileURL
    A URL of a file or directory relative to the directory path specified by pustrBaseDirectoryURL
    or an absolute path.
    If pustrRelativeFileURL denotes an absolute path pustrBaseDirectoryURL will be ignored.

    @param[out] ppustrAbsoluteFileURL
    On success it receives the full qualified absolute file URL.

    @retval osl_File_E_None on success
    @retval osl_File_E_INVAL the format of the parameters was not valid
    @retval osl_File_E_NOMEM not enough memory for allocating structures
    @retval osl_File_E_NOTDIR not a directory
    @retval osl_File_E_ACCES permission denied
    @retval osl_File_E_NOENT no such file or directory
    @retval osl_File_E_NAMETOOLONG file name too long
    @retval osl_File_E_OVERFLOW value too large for defined data type
    @retval osl_File_E_FAULT bad address
    @retval osl_File_E_INTR function call was interrupted
    @retval osl_File_E_LOOP too many symbolic links encountered
    @retval osl_File_E_MULTIHOP multihop attempted
    @retval osl_File_E_NOLINK link has been severed

    @see    osl_getFileStatus()
*/
SAL_DLLPUBLIC oslFileError SAL_CALL osl_getAbsoluteFileURL(
    rtl_uString* pustrBaseDirectoryURL,
    rtl_uString *pustrRelativeFileURL,
    rtl_uString **ppustrAbsoluteFileURL );

/** Convert a system dependent path into a file URL.

    @param[in] pustrSystemPath
    A System dependent path of a file or directory.

    @param[out] ppustrFileURL
    On success it receives the file URL.

    @retval osl_File_E_None on success
    @retval osl_File_E_INVAL the format of the parameters was not valid

    @see osl_getSystemPathFromFileURL()
*/
SAL_DLLPUBLIC oslFileError SAL_CALL osl_getFileURLFromSystemPath(
        rtl_uString *pustrSystemPath, rtl_uString **ppustrFileURL);

/** Search a full qualified system path or a file URL.

    @param[in] pustrFileName
    A system dependent path, a file URL, a file or relative directory.

    @param[in] pustrSearchPath
    @parblock
        A list of system paths, in which a given file has to be searched. The Notation of a path
        list is system dependent, e.g. on UNIX system "/usr/bin:/bin" and on Windows "C:\BIN;C:\BATCH".
        These paths are only for the search of a file or a relative path, otherwise it will be ignored.
        If pustrSearchPath is NULL or while using the search path the search failed, the function
        searches for a matching file in all system directories and in the directories listed in the PATH
        environment variable.

        The value of an environment variable should be used (e.g.
        LD_LIBRARY_PATH) if the caller is not aware of the Operating System and so doesn't know which
        path list delimiter to use.
    @endparblock

    @param[out] ppustrFileURL
    On success it receives the full qualified file URL.

    @retval osl_File_E_None on success
    @retval osl_File_E_INVAL the format of the parameters was not valid
    @retval osl_File_E_NOTDIR not a directory
    @retval osl_File_E_NOENT no such file or directory not found

    @see osl_getFileURLFromSystemPath()
    @see osl_getSystemPathFromFileURL()
*/
SAL_DLLPUBLIC oslFileError SAL_CALL osl_searchFileURL(
        rtl_uString *pustrFileName, rtl_uString *pustrSearchPath, rtl_uString **ppustrFileURL );

/** Convert a file URL into a system dependent path.

    @param[in] pustrFileURL
    A File URL.

    @param[out] ppustrSystemPath
    On success it receives the system path.

    @retval osl_File_E_None on success
    @retval osl_File_E_INVAL the format of the parameters was not valid

    @see osl_getFileURLFromSystemPath()
*/
SAL_DLLPUBLIC oslFileError SAL_CALL osl_getSystemPathFromFileURL(
        rtl_uString *pustrFileURL, rtl_uString **ppustrSystemPath);

/** Function pointer representing the function called back from osl_abbreviateSystemPath

    @param[in] ustrText
    Text to calculate the width for

    @return
    The width of the text specified by ustrText, e.g. it can return the width in pixel
    or the width in character count.

    @see osl_abbreviateSystemPath()
*/
typedef sal_uInt32 (SAL_CALL *oslCalcTextWidthFunc)( rtl_uString *ustrText );

/** Abbreviate a system notation path.

    @param[in] ustrSystemPath
    The full system path to abbreviate

    @param[out] pustrCompacted
    Receives the compacted system path on output

    @param[in] pCalcWidth
    Function ptr that calculates the width of a string. Can be zero.

    @param[in] uMaxWidth
    Maximum width allowed that is returned from pCalcWidth.
    If pCalcWidth is zero the character count is assumed as width.

    @retval osl_File_E_None on success

    @see    oslCalcTextWidthFunc
*/
SAL_DLLPUBLIC oslFileError SAL_CALL osl_abbreviateSystemPath(
    rtl_uString *ustrSystemPath,
    rtl_uString **pustrCompacted,
    sal_uInt32 uMaxWidth,
    oslCalcTextWidthFunc pCalcWidth );

/** Set file attributes.

    @param[in] pustrFileURL
    The full qualified file URL.

    @param[in] uAttributes
    Attributes of the file to be set.

    @retval osl_File_E_None on success
    @retval osl_File_E_INVAL the format of the parameters was not valid

    @see osl_getFileStatus()
*/
SAL_DLLPUBLIC oslFileError SAL_CALL osl_setFileAttributes(
        rtl_uString *pustrFileURL, sal_uInt64 uAttributes );

/** Set the file time.

    @param[in] pustrFileURL
    The full qualified URL of the file.

    @param[in] aCreationTime
    Creation time of the given file.

    @param[in] aLastAccessTime
    Time of the last access of the given file.

    @param[in] aLastWriteTime
    Time of the last modifying of the given file.

    @retval osl_File_E_None on success
    @retval osl_File_E_INVAL the format of the parameters was not valid
    @retval osl_File_E_NOENT no such file or directory not found

    @see osl_getFileStatus()
*/
SAL_DLLPUBLIC oslFileError SAL_CALL osl_setFileTime(
    rtl_uString *pustrFileURL,
    const TimeValue *aCreationTime,
    const TimeValue *aLastAccessTime,
    const TimeValue *aLastWriteTime);

/** Retrieves the file URL of the system's temporary directory path

    @param[out] pustrTempDirURL
    On success receives the URL of system's temporary directory path.

    @retval osl_File_E_None on success
    @retval osl_File_E_NOENT no such file or directory not found
*/
SAL_DLLPUBLIC oslFileError SAL_CALL osl_getTempDirURL(
        rtl_uString **pustrTempDirURL );

/** Creates a temporary file in the directory provided by the caller or the
    directory returned by osl_getTempDirURL.

    Creates a temporary file in the directory provided by the caller or the
    directory returned by osl_getTempDirURL.
    Under UNIX Operating Systems the file will be created with read and write
    access for the user exclusively.
    If the caller requests only a handle to the open file but not the name of
    it, the file will be automatically removed on close else the caller is
    responsible for removing the file on success.

    Description of the different pHandle, ppustrTempFileURL parameter combinations.
    pHandle is 0 and ppustrTempDirURL is 0 - this combination is invalid
    pHandle is not 0 and ppustrTempDirURL is 0 - a handle to the open file
    will be returned on success and the file will be automatically removed on close.
    pHandle is 0 and ppustrTempDirURL is not 0 - the name of the file will be returned,
    the caller is responsible for opening, closing and removing the file.
    pHandle is not 0 and ppustrTempDirURL is not 0 - a handle to the open file as well as
    the file name will be returned, the caller is responsible for closing and removing
    the file.

    @param[in]  pustrDirectoryURL
    Specifies the full qualified URL where the temporary file should be created.
    If pustrDirectoryURL is 0 the path returned by osl_getTempDirURL will be used.

    @param[out]  pHandle
    On success receives a handle to the open file. If pHandle is 0 the file will
    be closed on return, in this case ppustrTempFileURL must not be 0.

    @param[out]  ppustrTempFileURL
    On success receives the full qualified URL of the temporary file.
    If ppustrTempFileURL is 0 the file will be automatically removed on close,
    in this case pHandle must not be 0.
    If ppustrTempFileURL is not 0 the caller receives the name of the created
    file and is responsible for removing the file, in this case
    *ppustrTempFileURL must be 0 or must point to a valid rtl_uString.

    @retval osl_File_E_None   on success
    @retval osl_File_E_INVAL  the format of the parameter is invalid
    @retval osl_File_E_NOMEM  not enough memory for allocating structures
    @retval osl_File_E_ACCES  Permission denied
    @retval osl_File_E_NOENT  No such file or directory
    @retval osl_File_E_NOTDIR Not a directory
    @retval osl_File_E_ROFS   Read-only file system
    @retval osl_File_E_NOSPC  No space left on device
    @retval osl_File_E_DQUOT  Quota exceeded

    @see    osl_getTempDirURL()
*/
SAL_DLLPUBLIC oslFileError SAL_CALL osl_createTempFile(
    rtl_uString*   pustrDirectoryURL,
    oslFileHandle* pHandle,
    rtl_uString**  ppustrTempFileURL);

/** Move a file to a new destination or rename it, taking old file's identity (if exists).

    Moves or renames a file, replacing an existing file if exist. If the old file existed,
    moved file's metadata, e.g. creation time (on FSes which keep files' creation time) or
    ACLs, are set to old one's (to keep the old file's identity) - currently this is only
    implemented fully on Windows; on other platforms, this is mostly equivalent to osl_moveFile.

    @param[in] pustrSourceFileURL
    Full qualified URL of the source file.

    @param[in] pustrDestFileURL
    Full qualified URL of the destination file.

    @retval osl_File_E_None on success
    @retval osl_File_E_INVAL the format of the parameters was not valid
    @retval osl_File_E_NOMEM not enough memory for allocating structures
    @retval osl_File_E_ACCES permission denied
    @retval osl_File_E_PERM operation not permitted
    @retval osl_File_E_NAMETOOLONG file name too long
    @retval osl_File_E_NOENT no such file
    @retval osl_File_E_ROFS read-only file system
    @retval osl_File_E_BUSY if the implementation internally requires resources that are
        (temporarily) unavailable

    @see osl_moveFile()

    @since LibreOffice 6.2
*/
SAL_DLLPUBLIC oslFileError SAL_CALL osl_replaceFile(rtl_uString* pustrSourceFileURL,
                                                    rtl_uString* pustrDestFileURL);

#ifdef __cplusplus
}
#endif

#endif // INCLUDED_OSL_FILE_H

/* vim:set shiftwidth=4 softtabstop=4 expandtab: */