/
physfs.h
1001 lines (889 loc) · 38.3 KB
1
2
3
4
5
6
7
8
9
10
11
12
/**
* PhysicsFS; a portable, flexible file i/o abstraction.
*
* This API gives you access to a system file system in ways superior to the
* stdio or system i/o calls. The brief benefits:
*
* - It's portable.
* - It's safe. No file access is permitted outside the specified dirs.
* - It's flexible. Archives (.ZIP files) can be used transparently as
* directory structures.
*
* This system is largely inspired by Quake 3's PK3 files and the related
13
* fs_* cvars. If you've ever tinkered with these, then this API will be
14
15
* familiar to you.
*
16
17
18
19
20
21
22
23
24
* With PhysicsFS, you have a single writing directory and multiple
* directories (the "search path") for reading. You can think of this as a
* filesystem within a filesystem. If (on Windows) you were to set the
* writing directory to "C:\MyGame\MyWritingDirectory", then no PHYSFS calls
* could touch anything above this directory, including the "C:\MyGame" and
* "C:\" directories. This prevents an application's internal scripting
* language from piddling over c:\config.sys, for example. If you'd rather
* give PHYSFS full access to the system's REAL file system, set the writing
* dir to "C:\", but that's generally A Bad Thing for several reasons.
25
26
*
* Drive letters are hidden in PhysicsFS once you set up your initial paths.
27
* The search path creates a single, hierarchical directory structure.
28
29
30
31
32
33
34
* Not only does this lend itself well to general abstraction with archives,
* it also gives better support to operating systems like MacOS and Unix.
* Generally speaking, you shouldn't ever hardcode a drive letter; not only
* does this hurt portability to non-Microsoft OSes, but it limits your win32
* users to a single drive, too. Use the PhysicsFS abstraction functions and
* allow user-defined configuration options, too. When opening a file, you
* specify it like it was on a Unix filesystem: if you want to write to
35
* "C:\MyGame\MyConfigFiles\game.cfg", then you might set the write dir to
36
* "C:\MyGame" and then open "MyConfigFiles/game.cfg". This gives an
37
* abstraction across all platforms. Specifying a file in this way is termed
38
39
40
41
42
43
44
45
* "platform-independent notation" in this documentation. Specifying a
* a filename in a form such as "C:\mydir\myfile" or
* "MacOS hard drive:My Directory:My File" is termed "platform-dependent
* notation". The only time you use platform-dependent notation is when
* setting up your write directory and search path; after that, all file
* access into those directories are done with platform-independent notation.
*
* All files opened for writing are opened in relation to the write directory,
46
* which is the root of the writable filesystem. When opening a file for
47
* reading, PhysicsFS goes through the search path. This is NOT the
48
49
50
51
52
53
* same thing as the PATH environment variable. An application using
* PhysicsFS specifies directories to be searched which may be actual
* directories, or archive files that contain files and subdirectories of
* their own. See the end of these docs for currently supported archive
* formats.
*
54
* Once the search path is defined, you may open files for reading. If you've
55
56
57
58
59
60
61
* got the following search path defined (to use a win32 example again):
*
* C:\mygame
* C:\mygame\myuserfiles
* D:\mygamescdromdatafiles
* C:\mygame\installeddatafiles.zip
*
62
* Then a call to PHYSFS_openRead("textfiles/myfile.txt") (note the directory
63
64
65
* separator, lack of drive letter, and lack of dir separator at the start of
* the string; this is platform-independent notation) will check for
* C:\mygame\textfiles\myfile.txt, then
66
67
68
69
* C:\mygame\myuserfiles\textfiles\myfile.txt, then
* D:\mygamescdromdatafiles\textfiles\myfile.txt, then, finally, for
* textfiles\myfile.txt inside of C:\mygame\installeddatafiles.zip. Remember
* that most archive types and platform filesystems store their filenames in
70
* a case-sensitive manner, so you should be careful to specify it correctly.
71
*
72
73
74
75
76
77
78
79
80
81
82
83
84
85
* Files opened through PhysicsFS may NOT contain "." or ".." or ":" as dir
* elements. Not only are these meaningless on MacOS and/or Unix, they are a
* security hole. Also, symbolic links (which can be found in some archive
* types and directly in the filesystem on Unix platforms) are NOT followed
* until you call PHYSFS_permitSymbolicLinks(). That's left to your own
* discretion, as following a symlink can allow for access outside the write
* dir and search paths. There is no mechanism for creating new symlinks in
* PhysicsFS.
*
* The write dir is not included in the search path unless you specifically
* add it. While you CAN change the write dir as many times as you like,
* you should probably set it once and stick to it. Remember that your
* program will not have permission to write in every directory on Unix and
* NT systems.
86
87
88
*
* All files are opened in binary mode; there is no endline conversion for
* textfiles. Other than that, PhysicsFS has some convenience functions for
89
* platform-independence. There is a function to tell you the current
90
* platform's dir separator ("\\" on windows, "/" on Unix, ":" on MacOS),
91
92
93
* which is needed only to set up your search/write paths. There is a
* function to tell you what CD-ROM drives contain accessible discs, and a
* function to recommend a good search path, etc.
94
*
95
96
* A recommended order for the search path is the write dir, then the base dir,
* then the cdrom dir, then any archives discovered. Quake 3 does something
97
98
* like this, but moves the archives to the start of the search path. Build
* Engine games, like Duke Nukem 3D and Blood, place the archives last, and
99
100
* use the base dir for both searching and writing. There is a helper
* function (PHYSFS_setSaneConfig()) that puts together a basic configuration
101
* for you, based on a few parameters. Also see the comments on
102
103
104
* PHYSFS_getBaseDir(), and PHYSFS_getUserDir() for info on what those
* are and how they can help you determine an optimal search path.
*
105
106
107
108
109
110
* PhysicsFS is mostly thread safe. The error messages returned by
* PHYSFS_getLastError are unique by thread, and library-state-setting
* functions are mutex'd. For efficiency, individual file accesses are
* not locked, so you can not safely read/write/seek/close/etc the same
* file from two threads at the same time. Other race conditions are bugs
* that should be reported/patched.
111
112
113
*
* While you CAN use stdio/syscall file access in a program that has PHYSFS_*
* calls, doing so is not recommended, and you can not use system
114
* filehandles with PhysicsFS and vice versa.
115
116
*
* Note that archives need not be named as such: if you have a ZIP file and
117
* rename it with a .PKG extension, the file will still be recognized as a
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
* ZIP archive by PhysicsFS; the file's contents are used to determine its
* type.
*
* Currently supported archive types:
* - .ZIP (pkZip/WinZip/Info-ZIP compatible)
*
* Please see the file LICENSE in the source's root directory.
*
* This file written by Ryan C. Gordon.
*/
#ifndef _INCLUDE_PHYSFS_H_
#define _INCLUDE_PHYSFS_H_
#ifdef __cplusplus
extern "C" {
#endif
136
137
138
139
140
141
#if (defined _MSC_VER)
#define __EXPORT__ __declspec(dllexport)
#else
#define __EXPORT__
#endif
142
143
144
145
146
147
148
typedef unsigned char PHYSFS_uint8;
typedef signed char PHYSFS_sint8;
typedef unsigned short PHYSFS_uint16;
typedef signed short PHYSFS_sint16;
typedef unsigned int PHYSFS_uint32;
typedef signed int PHYSFS_sint32;
149
#if (defined PHYSFS_NO_64BIT_SUPPORT) /* oh well. */
150
151
typedef PHYSFS_uint32 PHYSFS_uint64;
typedef PHYSFS_sint32 PHYSFS_sint64;
152
153
154
#elif (defined _MSC_VER)
typedef signed __int64 PHYSFS_sint64;
typedef unsigned __int64 PHYSFS_uint64;
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
#else
typedef unsigned long long PHYSFS_uint64;
typedef signed long long PHYSFS_sint64;
#endif
/* Make sure the types really have the right sizes */
#define PHYSFS_COMPILE_TIME_ASSERT(name, x) \
typedef int PHYSFS_dummy_ ## name[(x) * 2 - 1]
PHYSFS_COMPILE_TIME_ASSERT(uint8, sizeof(PHYSFS_uint8) == 1);
PHYSFS_COMPILE_TIME_ASSERT(sint8, sizeof(PHYSFS_sint8) == 1);
PHYSFS_COMPILE_TIME_ASSERT(uint16, sizeof(PHYSFS_uint16) == 2);
PHYSFS_COMPILE_TIME_ASSERT(sint16, sizeof(PHYSFS_sint16) == 2);
PHYSFS_COMPILE_TIME_ASSERT(uint32, sizeof(PHYSFS_uint32) == 4);
PHYSFS_COMPILE_TIME_ASSERT(sint32, sizeof(PHYSFS_sint32) == 4);
#ifndef PHYSFS_NO_64BIT_SUPPORT
PHYSFS_COMPILE_TIME_ASSERT(uint64, sizeof(PHYSFS_uint64) == 8);
PHYSFS_COMPILE_TIME_ASSERT(sint64, sizeof(PHYSFS_sint64) == 8);
#endif
#undef PHYSFS_COMPILE_TIME_ASSERT
180
181
typedef struct __PHYSFS_FILE__
{
182
void *opaque;
183
184
185
186
187
188
} PHYSFS_file;
typedef struct __PHYSFS_ARCHIVEINFO__
{
const char *extension;
const char *description;
189
190
const char *author;
const char *url;
191
192
193
} PHYSFS_ArchiveInfo;
194
195
/* functions... */
196
197
typedef struct __PHYSFS_VERSION__
{
198
199
200
PHYSFS_uint8 major;
PHYSFS_uint8 minor;
PHYSFS_uint8 patch;
201
202
203
204
} PHYSFS_Version;
#define PHYSFS_VER_MAJOR 0
#define PHYSFS_VER_MINOR 1
205
#define PHYSFS_VER_PATCH 6
206
207
#define PHYSFS_VERSION(x) { \
208
209
210
(x)->major = PHYSFS_VER_MAJOR; \
(x)->minor = PHYSFS_VER_MINOR; \
(x)->patch = PHYSFS_VER_PATCH; \
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
}
/**
* Get the version of PhysicsFS that is linked against your program. If you
* are using a shared library (DLL) version of PhysFS, then it is possible
* that it will be different than the version you compiled against.
*
* This is a real function; the macro PHYSFS_VERSION tells you what version
* of PhysFS you compiled against:
*
* PHYSFS_Version compiled;
* PHYSFS_Version linked;
*
* PHYSFS_VERSION(&compiled);
* PHYSFS_getLinkedVersion(&linked);
* printf("We compiled against PhysFS version %d.%d.%d ...\n",
* compiled.major, compiled.minor, compiled.patch);
* printf("But we linked against PhysFS version %d.%d.%d.\n",
* linked.major, linked.minor, linked.patch);
*
* This function may be called safely at any time, even before PHYSFS_init().
*/
233
__EXPORT__ void PHYSFS_getLinkedVersion(PHYSFS_Version *ver);
236
237
/**
* Initialize PhysicsFS. This must be called before any other PhysicsFS
238
* function.
240
241
242
* This should be called prior to any attempts to change your process's
* current working directory.
*
243
244
245
246
* @param argv0 the argv[0] string passed to your program's mainline.
* @return nonzero on success, zero on error. Specifics of the error can be
* gleaned from PHYSFS_getLastError().
*/
247
__EXPORT__ int PHYSFS_init(const char *argv0);
248
249
250
251
/**
* Shutdown PhysicsFS. This closes any files opened via PhysicsFS, blanks the
252
* search/write paths, frees memory, and invalidates all of your handles.
254
255
256
257
258
259
* Note that this call can FAIL if there's a file open for writing that
* refuses to close (for example, the underlying operating system was
* buffering writes to network filesystem, and the fileserver has crashed,
* or a hard drive has failed, etc). It is usually best to close all write
* handles yourself before calling this function, so that you can gracefully
* handle a specific failure.
261
262
263
* Once successfully deinitialized, PHYSFS_init() can be called again to
* restart the subsystem. All defaults API states are restored at this
* point.
265
266
267
268
* @return nonzero on success, zero on error. Specifics of the error can be
* gleaned from PHYSFS_getLastError(). If failure, state of PhysFS is
* undefined, and probably badly screwed up.
*/
269
__EXPORT__ int PHYSFS_deinit(void);
272
273
274
275
276
277
278
/**
* Get a list of archive types supported by this implementation of PhysicFS.
* These are the file formats usable for search path entries. This is for
* informational purposes only. Note that the extension listed is merely
* convention: if we list "ZIP", you can open a PkZip-compatible archive
* with an extension of "XYZ", if you like.
*
279
280
* The returned value is an array of pointers to PHYSFS_ArchiveInfo structures,
* with a NULL entry to signify the end of the list:
281
282
283
284
285
286
287
288
289
290
291
292
293
294
*
* PHYSFS_ArchiveInfo **i;
*
* for (i = PHYSFS_supportedArchiveTypes(); *i != NULL; i++)
* {
* printf("Supported archive: [%s], which is [%s].\n",
* i->extension, i->description);
* }
*
* The return values are pointers to static internal memory, and should
* be considered READ ONLY, and never freed.
*
* @return READ ONLY Null-terminated array of READ ONLY structures.
*/
295
__EXPORT__ const PHYSFS_ArchiveInfo **PHYSFS_supportedArchiveTypes(void);
296
297
298
299
300
301
302
303
/**
* Certain PhysicsFS functions return lists of information that are
* dynamically allocated. Use this function to free those resources.
*
* @param list List of information specified as freeable by this function.
*/
304
__EXPORT__ void PHYSFS_freeList(void *listVar);
307
308
309
/**
* Get the last PhysicsFS error message as a null-terminated string.
* This will be NULL if there's been no error since the last call to this
310
311
312
313
314
* function. The pointer returned by this call points to an internal buffer.
* Each thread has a unique error state associated with it, but each time
* a new error message is set, it will overwrite the previous one associated
* with that thread. It is safe to call this function at anytime, even
* before PHYSFS_init().
315
316
317
*
* @return READ ONLY string of last error message.
*/
318
__EXPORT__ const char *PHYSFS_getLastError(void);
319
320
321
/**
322
* Get a platform-dependent dir separator. This is "\\" on win32, "/" on Unix,
323
324
325
* and ":" on MacOS. It may be more than one character, depending on the
* platform, and your code should take that into account. Note that this is
* only useful for setting up the search/write paths, since access into those
326
* dirs always use '/' (platform-independent notation) to separate
327
328
* directories. This is also handy for getting platform-independent access
* when using stdio calls.
329
*
330
* @return READ ONLY null-terminated string of platform's dir separator.
331
*/
332
__EXPORT__ const char *PHYSFS_getDirSeparator(void);
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
/**
* Enable symbolic links. Some physical filesystems and archives contain
* files that are just pointers to other files. On the physical filesystem,
* opening such a link will (transparently) open the file that is pointed to.
*
* By default, PhysicsFS will check if a file is really a symlink during open
* calls and fail if it is. Otherwise, the link could take you outside the
* write and search paths, and compromise security.
*
* If you want to take that risk, call this function with a non-zero parameter.
* Note that this is more for sandboxing a program's scripting language, in
* case untrusted scripts try to compromise the system. Generally speaking,
* a user could very well have a legitimate reason to set up a symlink, so
* unless you feel there's a specific danger in allowing them, you should
* permit them.
*
351
352
353
354
* Symlinks are only explicitly checked when dealing with filenames
* in platform-independent notation. That is, when setting up your
* search and write paths, etc, symlinks are never checked for.
*
355
356
357
358
359
* Symbolic link permission can be enabled or disabled at any time, and is
* disabled by default.
*
* @param allow nonzero to permit symlinks, zero to deny linking.
*/
360
__EXPORT__ void PHYSFS_permitSymbolicLinks(int allow);
363
/**
364
* Get an array of dirs to available CD-ROM drives.
365
*
366
367
* The dirs returned are platform-dependent ("D:\" on Win32, "/cdrom" or
* whatnot on Unix). Dirs are only returned if there is a disc ready and
368
369
370
371
372
373
374
375
376
* accessible in the drive. So if you've got two drives (D: and E:), and only
* E: has a disc in it, then that's all you get. If the user inserts a disc
* in D: and you call this function again, you get both drives. If, on a
* Unix box, the user unmounts a disc and remounts it elsewhere, the next
* call to this function will reflect that change. Fun.
*
* The returned value is an array of strings, with a NULL entry to signify the
* end of the list:
*
377
* char **cds = PHYSFS_getCdRomDirs();
378
379
* char **i;
*
380
* for (i = cds; *i != NULL; i++)
381
* printf("cdrom dir [%s] is available.\n", *i);
382
*
383
384
* PHYSFS_freeList(cds);
*
385
386
* This call may block while drives spin up. Be forewarned.
*
387
388
389
390
* When you are done with the returned information, you may dispose of the
* resources by calling PHYSFS_freeList() with the returned pointer.
*
* @return Null-terminated array of null-terminated strings.
391
*/
392
__EXPORT__ char **PHYSFS_getCdRomDirs(void);
393
394
395
396
397
/**
* Helper function.
*
398
* Get the "base dir". This is the directory where the application was run
399
400
* from, which is probably the installation directory, and may or may not
* be the process's current working directory.
401
*
402
* You should probably use the base dir in your search path.
403
*
404
* @return READ ONLY string of base dir in platform-dependent notation.
405
*/
406
__EXPORT__ const char *PHYSFS_getBaseDir(void);
407
408
409
410
411
/**
* Helper function.
*
412
* Get the "user dir". This is meant to be a suggestion of where a specific
413
* user of the system can store files. On Unix, this is her home directory.
414
* On systems with no concept of multiple home directories (MacOS, win95),
415
* this will default to something like "C:\mybasedir\users\username"
416
417
* where "username" will either be the login name, or "default" if the
* platform doesn't support multiple users, either.
418
*
419
* You should probably use the user dir as the basis for your write dir, and
420
421
* also put it near the beginning of your search path.
*
422
* @return READ ONLY string of user dir in platform-dependent notation.
423
*/
424
__EXPORT__ const char *PHYSFS_getUserDir(void);
425
426
427
/**
428
* Get the current write dir. The default write dir is NULL.
429
*
430
* @return READ ONLY string of write dir in platform-dependent notation,
431
432
* OR NULL IF NO WRITE PATH IS CURRENTLY SET.
*/
433
__EXPORT__ const char *PHYSFS_getWriteDir(void);
434
435
436
/**
437
* Set a new write dir. This will override the previous setting. If the
438
439
440
* directory or a parent directory doesn't exist in the physical filesystem,
* PhysicsFS will attempt to create them as needed.
*
441
442
* This call will fail (and fail to change the write dir) if the current
* write dir still has files open in it.
443
*
444
* @param newDir The new directory to be the root of the write dir,
445
* specified in platform-dependent notation. Setting to NULL
446
* disables the write dir, so no files can be opened for
447
448
449
450
451
452
* writing via PhysicsFS.
* @return non-zero on success, zero on failure. All attempts to open a file
* for writing via PhysicsFS will fail until this call succeeds.
* Specifics of the error can be gleaned from PHYSFS_getLastError().
*
*/
453
__EXPORT__ int PHYSFS_setWriteDir(const char *newDir);
454
455
456
457
458
459
/**
* Add a directory or archive to the search path. If this is a duplicate, the
* entry is not added again, even though the function succeeds.
*
460
* @param newDir directory or archive to add to the path, in
461
462
* platform-dependent notation.
* @param appendToPath nonzero to append to search path, zero to prepend.
463
* @return nonzero if added to path, zero on failure (bogus archive, dir
464
465
466
* missing, etc). Specifics of the error can be
* gleaned from PHYSFS_getLastError().
*/
467
__EXPORT__ int PHYSFS_addToSearchPath(const char *newDir, int appendToPath);
468
469
470
/**
471
* Remove a directory or archive from the search path.
472
473
474
475
476
477
478
*
* This must be a (case-sensitive) match to a dir or archive already in the
* search path, specified in platform-dependent notation.
*
* This call will fail (and fail to remove from the path) if the element still
* has files open in it.
*
479
* @param oldDir dir/archive to remove.
480
481
482
* @return nonzero on success, zero on failure.
* Specifics of the error can be gleaned from PHYSFS_getLastError().
*/
483
__EXPORT__ int PHYSFS_removeFromSearchPath(const char *oldDir);
484
485
486
487
488
489
490
491
492
493
494
495
496
/**
* Get the current search path. The default search path is an empty list.
*
* The returned value is an array of strings, with a NULL entry to signify the
* end of the list:
*
* char **i;
*
* for (i = PHYSFS_getSearchPath(); *i != NULL; i++)
* printf("[%s] is in the search path.\n", *i);
*
497
498
* When you are done with the returned information, you may dispose of the
* resources by calling PHYSFS_freeList() with the returned pointer.
499
*
500
501
* @return Null-terminated array of null-terminated strings. NULL if there
* was a problem (read: OUT OF MEMORY).
502
*/
503
__EXPORT__ char **PHYSFS_getSearchPath(void);
504
505
506
507
508
/**
* Helper function.
*
509
* Set up sane, default paths. The write dir will be set to
510
* "userdir/.organization/appName", which is created if it doesn't exist.
511
512
513
514
515
516
517
*
* The above is sufficient to make sure your program's configuration directory
* is separated from other clutter, and platform-independent. The period
* before "mygame" even hides the directory on Unix systems.
*
* The search path will be:
*
518
519
520
* - The Write Dir (created if it doesn't exist)
* - The Base Dir (PHYSFS_getBaseDir())
* - All found CD-ROM dirs (optionally)
521
522
523
524
525
526
527
528
529
*
* These directories are then searched for files ending with the extension
* (archiveExt), which, if they are valid and supported archives, will also
* be added to the search path. If you specified "PKG" for (archiveExt), and
* there's a file named data.PKG in the base dir, it'll be checked. Archives
* can either be appended or prepended to the search path in alphabetical
* order, regardless of which directories they were found in.
*
* All of this can be accomplished from the application, but this just does it
530
* all for you. Feel free to add more to the search path manually, too.
531
*
532
533
534
* @param organization Name of your company/group/etc to be used as a
* dirname, so keep it small, and no-frills.
*
535
536
537
538
539
540
* @param appName Program-specific name of your program, to separate it
* from other programs using PhysicsFS.
*
* @param archiveExt File extention used by your program to specify an
* archive. For example, Quake 3 uses "pk3", even though
* they are just zipfiles. Specify NULL to not dig out
541
542
543
* archives automatically. Do not specify the '.' char;
* If you want to look for ZIP files, specify "ZIP" and
* not ".ZIP" ... the archive search is case-insensitive.
544
545
*
* @param includeCdRoms Non-zero to include CD-ROMs in the search path, and
546
547
548
549
550
551
552
* (if (archiveExt) != NULL) search them for archives.
* This may cause a significant amount of blocking
* while discs are accessed, and if there are no discs
* in the drive (or even not mounted on Unix systems),
* then they may not be made available anyhow. You may
* want to specify zero and handle the disc setup
* yourself.
553
554
*
* @param archivesFirst Non-zero to prepend the archives to the search path.
555
* Zero to append them. Ignored if !(archiveExt).
557
558
* @return nonzero on success, zero on error. Specifics of the error can be
* gleaned from PHYSFS_getLastError().
559
*/
560
561
__EXPORT__ int PHYSFS_setSaneConfig(const char *organization,
const char *appName,
562
563
564
const char *archiveExt,
int includeCdRoms,
int archivesFirst);
565
566
567
568
/**
* Create a directory. This is specified in platform-independent notation in
569
* relation to the write dir. All missing parent directories are also
570
571
* created if they don't exist.
*
572
* So if you've got the write dir set to "C:\mygame\writedir" and call
573
* PHYSFS_mkdir("downloads/maps") then the directories
574
* "C:\mygame\writedir\downloads" and "C:\mygame\writedir\downloads\maps"
575
576
577
* will be created if possible. If the creation of "maps" fails after we
* have successfully created "downloads", then the function leaves the
* created directory behind and reports failure.
578
*
579
* @param dirname New dir to create.
580
581
582
* @return nonzero on success, zero on error. Specifics of the error can be
* gleaned from PHYSFS_getLastError().
*/
583
__EXPORT__ int PHYSFS_mkdir(const char *dirName);
584
585
586
587
/**
* Delete a file or directory. This is specified in platform-independent
588
* notation in relation to the write dir.
589
*
590
* A directory must be empty before this call can delete it.
591
*
592
593
594
* Deleting a symlink will remove the link, not what it points to, regardless
* of whether you "permitSymLinks" or not.
*
595
* So if you've got the write dir set to "C:\mygame\writedir" and call
596
* PHYSFS_delete("downloads/maps/level1.map") then the file
597
* "C:\mygame\writedir\downloads\maps\level1.map" is removed from the
598
599
600
* physical filesystem, if it exists and the operating system permits the
* deletion.
*
601
602
603
604
* Note that on Unix systems, deleting a file may be successful, but the
* actual file won't be removed until all processes that have an open
* filehandle to it (including your program) close their handles.
*
605
606
607
608
* Chances are, the bits that make up the file still exist, they are just
* made available to be written over at a later point. Don't consider this
* a security method or anything. :)
*
609
610
611
612
* @param filename Filename to delete.
* @return nonzero on success, zero on error. Specifics of the error can be
* gleaned from PHYSFS_getLastError().
*/
613
__EXPORT__ int PHYSFS_delete(const char *filename);
614
615
616
617
618
619
620
621
622
623
624
/**
* Figure out where in the search path a file resides. The file is specified
* in platform-independent notation. The returned filename will be the
* element of the search path where the file was found, which may be a
* directory, or an archive. Even if there are multiple matches in different
* parts of the search path, only the first one found is used, just like
* when opening a file.
*
* So, if you look for "maps/level1.map", and C:\mygame is in your search
625
* path and C:\mygame\maps\level1.map exists, then "C:\mygame" is returned.
626
*
627
628
629
* If a any part of a match is a symbolic link, and you've not explicitly
* permitted symlinks, then it will be ignored, and the search for a match
* will continue.
631
* @param filename file to look for.
632
633
634
* @return READ ONLY string of element of search path containing the
* the file in question. NULL if not found.
*/
635
__EXPORT__ const char *PHYSFS_getRealDir(const char *filename);
636
637
638
639
640
/**
* Get a file listing of a search path's directory. Matching directories are
641
* interpolated. That is, if "C:\mydir" is in the search path and contains a
642
* directory "savegames" that contains "x.sav", "y.sav", and "z.sav", and
643
* there is also a "C:\userdir" in the search path that has a "savegames"
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
* subdirectory with "w.sav", then the following code:
*
* ------------------------------------------------
* char **rc = PHYSFS_enumerateFiles("savegames");
* char **i;
*
* for (i = rc; *i != NULL; i++)
* printf("We've got [%s].\n", *i);
*
* PHYSFS_freeList(rc);
* ------------------------------------------------
*
* ...will print:
*
* ------------------------------------------------
* We've got [x.sav].
* We've got [y.sav].
* We've got [z.sav].
* We've got [w.sav].
* ------------------------------------------------
*
665
666
667
* Feel free to sort the list however you like. We only promise there will
* be no duplicates, but not what order the final list will come back in.
*
668
669
670
* Don't forget to call PHYSFS_freeList() with the return value from this
* function when you are done with it.
*
671
* @param dir directory in platform-independent notation to enumerate.
672
* @return Null-terminated array of null-terminated strings.
673
*/
674
__EXPORT__ char **PHYSFS_enumerateFiles(const char *dir);
675
676
677
678
679
680
681
682
683
684
685
686
687
/**
* Determine if there is an entry anywhere in the search path by the
* name of (fname).
*
* Note that entries that are symlinks are ignored if
* PHYSFS_permitSymbolicLinks(1) hasn't been called, so you
* might end up further down in the search path than expected.
*
* @param fname filename in platform-independent notation.
* @return non-zero if filename exists. zero otherwise.
*/
688
__EXPORT__ int PHYSFS_exists(const char *fname);
689
690
691
692
693
694
695
696
697
698
699
700
701
/**
* Determine if the first occurence of (fname) in the search path is
* really a directory entry.
*
* Note that entries that are symlinks are ignored if
* PHYSFS_permitSymbolicLinks(1) hasn't been called, so you
* might end up further down in the search path than expected.
*
* @param fname filename in platform-independent notation.
* @return non-zero if filename exists and is a directory. zero otherwise.
*/
702
__EXPORT__ int PHYSFS_isDirectory(const char *fname);
703
704
705
706
707
708
709
710
711
712
713
714
715
/**
* Determine if the first occurence of (fname) in the search path is
* really a symbolic link.
*
* Note that entries that are symlinks are ignored if
* PHYSFS_permitSymbolicLinks(1) hasn't been called, and as such,
* this function will always return 0 in that case.
*
* @param fname filename in platform-independent notation.
* @return non-zero if filename exists and is a symlink. zero otherwise.
*/
716
__EXPORT__ int PHYSFS_isSymbolicLink(const char *fname);
719
720
/**
* Open a file for writing, in platform-independent notation and in relation
721
* to the write dir as the root of the writable filesystem. The specified
722
723
724
* file is created if it doesn't exist. If it does exist, it is truncated to
* zero bytes, and the writing offset is set to the start.
*
725
726
727
728
* Note that entries that are symlinks are ignored if
* PHYSFS_permitSymbolicLinks(1) hasn't been called, and opening a
* symlink with this function will fail in such a case.
*
729
730
731
732
* @param filename File to open.
* @return A valid PhysicsFS filehandle on success, NULL on error. Specifics
* of the error can be gleaned from PHYSFS_getLastError().
*/
733
__EXPORT__ PHYSFS_file *PHYSFS_openWrite(const char *filename);
734
735
736
737
/**
* Open a file for writing, in platform-independent notation and in relation
738
* to the write dir as the root of the writable filesystem. The specified
739
740
741
742
* file is created if it doesn't exist. If it does exist, the writing offset
* is set to the end of the file, so the first write will be the byte after
* the end.
*
743
744
745
746
* Note that entries that are symlinks are ignored if
* PHYSFS_permitSymbolicLinks(1) hasn't been called, and opening a
* symlink with this function will fail in such a case.
*
747
748
749
750
* @param filename File to open.
* @return A valid PhysicsFS filehandle on success, NULL on error. Specifics
* of the error can be gleaned from PHYSFS_getLastError().
*/
751
__EXPORT__ PHYSFS_file *PHYSFS_openAppend(const char *filename);
752
753
754
755
756
757
758
759
/**
* Open a file for reading, in platform-independent notation. The search path
* is checked one at a time until a matching file is found, in which case an
* abstract filehandle is associated with it, and reading may be done.
* The reading offset is set to the first byte of the file.
*
760
761
762
763
* Note that entries that are symlinks are ignored if
* PHYSFS_permitSymbolicLinks(1) hasn't been called, and opening a
* symlink with this function will fail in such a case.
*
764
765
766
767
* @param filename File to open.
* @return A valid PhysicsFS filehandle on success, NULL on error. Specifics
* of the error can be gleaned from PHYSFS_getLastError().
*/
768
__EXPORT__ PHYSFS_file *PHYSFS_openRead(const char *filename);
769
770
771
772
773
774
775
776
777
778
779
780
781
782
/**
* Close a PhysicsFS filehandle. This call is capable of failing if the
* operating system was buffering writes to this file, and (now forced to
* write those changes to physical media) can not store the data for any
* reason. In such a case, the filehandle stays open. A well-written program
* should ALWAYS check the return value from the close call in addition to
* every writing call!
*
* @param handle handle returned from PHYSFS_open*().
* @return nonzero on success, zero on error. Specifics of the error can be
* gleaned from PHYSFS_getLastError().
*/
783
__EXPORT__ int PHYSFS_close(PHYSFS_file *handle);
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
/**
* Get the last modification time of a file. This is returned as a
* number of seconds since the epoch (Jan 1, 1970). The exact derivation
* and accuracy of this time depends on the particular archiver. If there
* is no reasonable way to obtain this information for a particular archiver,
* or there was some sort of error, this function returns (-1).
*
* @param filename filename to check.
* @return last modified time of the file. -1 if it can't be determined.
*/
__EXPORT__ PHYSFS_sint64 PHYSFS_getLastModTime(const char *filename);
799
800
801
802
803
804
805
806
/**
* Read data from a PhysicsFS filehandle. The file must be opened for reading.
*
* @param handle handle returned from PHYSFS_openRead().
* @param buffer buffer to store read data into.
* @param objSize size in bytes of objects being read from (handle).
* @param objCount number of (objSize) objects to read from (handle).
* @return number of objects read. PHYSFS_getLastError() can shed light on
807
* the reason this might be < (objCount), as can PHYSFS_eof().
808
* -1 if complete failure.
809
*/
810
811
812
813
__EXPORT__ PHYSFS_sint64 PHYSFS_read(PHYSFS_file *handle,
void *buffer,
PHYSFS_uint32 objSize,
PHYSFS_uint32 objCount);
814
815
816
817
818
819
820
821
/**
* Write data to a PhysicsFS filehandle. The file must be opened for writing.
*
* @param handle retval from PHYSFS_openWrite() or PHYSFS_openAppend().
* @param buffer buffer to store read data into.
* @param objSize size in bytes of objects being read from (handle).
* @param objCount number of (objSize) objects to read from (handle).
822
823
* @return number of objects written. PHYSFS_getLastError() can shed light on
* the reason this might be < (objCount). -1 if complete failure.
824
*/
825
826
827
828
__EXPORT__ PHYSFS_sint64 PHYSFS_write(PHYSFS_file *handle,
const void *buffer,
PHYSFS_uint32 objSize,
PHYSFS_uint32 objCount);
829
830
831
832
833
834
835
/**
* Determine if the end of file has been reached in a PhysicsFS filehandle.
*
* @param handle handle returned from PHYSFS_openRead().
* @return nonzero if EOF, zero if not.
*/
836
__EXPORT__ int PHYSFS_eof(PHYSFS_file *handle);
837
838
839
840
841
842
843
844
845
/**
* Determine current position within a PhysicsFS filehandle.
*
* @param handle handle returned from PHYSFS_open*().
* @return offset in bytes from start of file. -1 if error occurred.
* Specifics of the error can be gleaned from PHYSFS_getLastError().
*/
846
__EXPORT__ PHYSFS_sint64 PHYSFS_tell(PHYSFS_file *handle);
847
848
849
850
851
852
853
854
855
856
857
858
/**
* Seek to a new position within a PhysicsFS filehandle. The next read or write
* will occur at that place. Seeking past the beginning or end of the file is
* not allowed.
*
* @param handle handle returned from PHYSFS_open*().
* @param pos number of bytes from start of file to seek to.
* @return nonzero on success, zero on error. Specifics of the error can be
* gleaned from PHYSFS_getLastError().
*/
859
__EXPORT__ int PHYSFS_seek(PHYSFS_file *handle, PHYSFS_uint64 pos);
861
862
863
864
/**
* Get total length of a file in bytes. Note that if the file size can't
* be determined (since the archive is "streamed" or whatnot) than this
865
* will report (-1). Also note that if another process/thread is writing
866
867
868
869
870
871
872
* to this file at the same time, then the information this function
* supplies could be incorrect before you get it. Use with caution, or
* better yet, don't use at all.
*
* @param handle handle returned from PHYSFS_open*().
* @return size in bytes of the file. -1 if can't be determined.
*/
873
__EXPORT__ PHYSFS_sint64 PHYSFS_fileLength(PHYSFS_file *handle);
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
/* Byteorder stuff... */
/**
* Take a 16-bit signed value in littleendian format and convert it to
* the platform's native byte order.
*
* @param val value to convert
* @return converted value.
*/
__EXPORT__ PHYSFS_sint16 PHYSFS_swapSLE16(PHYSFS_sint16 val);
/**
* Take a 16-bit unsigned value in littleendian format and convert it to
* the platform's native byte order.
*
* @param val value to convert
* @return converted value.
*/
__EXPORT__ PHYSFS_uint16 PHYSFS_swapULE16(PHYSFS_uint16 val);
/**
* Take a 32-bit signed value in littleendian format and convert it to
* the platform's native byte order.
*
* @param val value to convert
* @return converted value.
*/
__EXPORT__ PHYSFS_sint32 PHYSFS_swapSLE32(PHYSFS_sint32 val);
/**
* Take a 32-bit unsigned value in littleendian format and convert it to
* the platform's native byte order.
*
* @param val value to convert
* @return converted value.
*/
__EXPORT__ PHYSFS_uint32 PHYSFS_swapULE32(PHYSFS_uint32 val);
/**
* Take a 64-bit signed value in littleendian format and convert it to
* the platform's native byte order.
*
* @param val value to convert
* @return converted value.
*/
__EXPORT__ PHYSFS_sint64 PHYSFS_swapSLE64(PHYSFS_sint64 val);
/**
* Take a 64-bit unsigned value in littleendian format and convert it to
* the platform's native byte order.
*
* @param val value to convert
* @return converted value.
*/
__EXPORT__ PHYSFS_uint64 PHYSFS_swapULE64(PHYSFS_uint64 val);
/**
* Take a 16-bit signed value in bigendian format and convert it to
* the platform's native byte order.
*
* @param val value to convert
* @return converted value.
*/
__EXPORT__ PHYSFS_sint16 PHYSFS_swapSBE16(PHYSFS_sint16 val);
/**
* Take a 16-bit unsigned value in bigendian format and convert it to
* the platform's native byte order.
*
* @param val value to convert
* @return converted value.
*/
__EXPORT__ PHYSFS_uint16 PHYSFS_swapUBE16(PHYSFS_uint16 val);
/**
* Take a 32-bit signed value in bigendian format and convert it to
* the platform's native byte order.
*
* @param val value to convert
* @return converted value.
*/
__EXPORT__ PHYSFS_sint32 PHYSFS_swapSBE32(PHYSFS_sint32 val);
/**
* Take a 32-bit unsigned value in bigendian format and convert it to
* the platform's native byte order.
*
* @param val value to convert
* @return converted value.
*/
__EXPORT__ PHYSFS_uint32 PHYSFS_swapUBE32(PHYSFS_uint32 val);
/**
* Take a 64-bit signed value in bigendian format and convert it to
* the platform's native byte order.
*
* @param val value to convert
* @return converted value.
*/
__EXPORT__ PHYSFS_sint64 PHYSFS_swapSBE64(PHYSFS_sint64 val);
/**
* Take a 64-bit unsigned value in bigendian format and convert it to
* the platform's native byte order.
*
* @param val value to convert
* @return converted value.
*/
__EXPORT__ PHYSFS_uint64 PHYSFS_swapUBE64(PHYSFS_uint64 val);
994
995
996
997
998
999
1000
#ifdef __cplusplus
}
#endif
#endif /* !defined _INCLUDE_PHYSFS_H_ */
/* end of physfs.h ... */