/
physfs.h
2159 lines (1957 loc) · 81.8 KB
1
2
/** \file physfs.h */
3
/**
4
5
6
7
8
* \mainpage PhysicsFS
*
* The latest version of PhysicsFS can be found at:
* http://icculus.org/physfs/
*
9
10
11
12
13
14
15
16
17
18
19
* 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
20
* fs_* cvars. If you've ever tinkered with these, then this API will be
21
22
* familiar to you.
*
23
24
25
26
27
28
* 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
29
* language from piddling over c:\\config.sys, for example. If you'd rather
30
31
* 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.
32
33
*
* Drive letters are hidden in PhysicsFS once you set up your initial paths.
34
* The search path creates a single, hierarchical directory structure.
35
36
37
38
39
40
41
* 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
42
* "C:\MyGame\MyConfigFiles\game.cfg", then you might set the write dir to
43
* "C:\MyGame" and then open "MyConfigFiles/game.cfg". This gives an
44
* abstraction across all platforms. Specifying a file in this way is termed
45
46
47
48
49
50
51
52
* "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,
53
* which is the root of the writable filesystem. When opening a file for
54
* reading, PhysicsFS goes through the search path. This is NOT the
55
56
57
58
59
60
* 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.
*
61
* Once the search path is defined, you may open files for reading. If you've
62
63
* got the following search path defined (to use a win32 example again):
*
64
65
66
67
* - C:\\mygame
* - C:\\mygame\\myuserfiles
* - D:\\mygamescdromdatafiles
* - C:\\mygame\\installeddatafiles.zip
68
*
69
* Then a call to PHYSFS_openRead("textfiles/myfile.txt") (note the directory
70
71
* separator, lack of drive letter, and lack of dir separator at the start of
* the string; this is platform-independent notation) will check for
72
73
74
75
76
77
78
* C:\\mygame\\textfiles\\myfile.txt, then
* 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 a case-sensitive manner, so you should be careful to specify
* it correctly.
79
*
80
* Files opened through PhysicsFS may NOT contain "." or ".." or ":" as dir
81
82
83
84
85
86
87
* elements. Not only are these meaningless on MacOS Classic 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. For portability, there is no mechanism for
* creating new symlinks in PhysicsFS.
88
89
90
91
92
93
*
* 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.
94
95
96
*
* All files are opened in binary mode; there is no endline conversion for
* textfiles. Other than that, PhysicsFS has some convenience functions for
97
* platform-independence. There is a function to tell you the current
98
* platform's dir separator ("\\" on windows, "/" on Unix, ":" on MacOS),
99
100
101
* 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.
102
*
103
104
* 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
105
106
* 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
107
108
* use the base dir for both searching and writing. There is a helper
* function (PHYSFS_setSaneConfig()) that puts together a basic configuration
109
* for you, based on a few parameters. Also see the comments on
110
111
112
* PHYSFS_getBaseDir(), and PHYSFS_getUserDir() for info on what those
* are and how they can help you determine an optimal search path.
*
113
114
115
116
117
118
119
120
121
122
123
124
* PhysicsFS 2.0 adds the concept of "mounting" archives to arbitrary points
* in the search path. If a zipfile contains "maps/level.map" and you mount
* that archive at "mods/mymod", then you would have to open
* "mods/mymod/maps/level.map" to access the file, even though "mods/mymod"
* isn't actually specified in the .zip file. Unlike the Unix mentality of
* mounting a filesystem, "mods/mymod" doesn't actually have to exist when
* mounting the zipfile. It's a "virtual" directory. The mounting mechanism
* allows the developer to seperate archives in the tree and avoid trampling
* over files when added new archives, such as including mod support in a
* game...keeping external content on a tight leash in this manner can be of
* utmost importance to some applications.
*
125
126
127
128
129
130
* 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.
131
132
133
*
* 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
134
* filehandles with PhysicsFS and vice versa.
135
136
*
* Note that archives need not be named as such: if you have a ZIP file and
137
* rename it with a .PKG extension, the file will still be recognized as a
138
* ZIP archive by PhysicsFS; the file's contents are used to determine its
139
* type where possible.
140
141
142
*
* Currently supported archive types:
* - .ZIP (pkZip/WinZip/Info-ZIP compatible)
143
* - .GRP (Build Engine groupfile archives)
144
* - .PAK (Quake I/II archive format)
145
146
* - .HOG (Descent I/II HOG file archives)
* - .MVL (Descent II movielib archives)
147
* - .WAD (DOOM engine archives)
148
* - .MIX (Older Westwood games archives)
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
*
* String policy for PhysicsFS 2.0 and later:
*
* PhysicsFS 1.0 deals with null-terminated ASCII strings. All high ASCII
* chars resulted in undefined behaviour, and there was no Unicode support.
*
* All strings passed through PhysicsFS are in null-terminated UTF-8 format.
* This means that if all you care about is English (ASCII characters <= 127)
* then you just use regular C strings. If you care about Unicode (and you
* should!) then you need to figure out what your platform wants, needs, and
* offers. If you are on Windows and build with Unicode support, your TCHAR
* strings are two bytes per character (this is called "UCS-2 encoding"). You
* should convert them to UTF-8 before handing them to PhysicsFS with
* PHYSFS_utf8fromucs2(). If you're using Unix or Mac OS X, your wchar_t
* strings are four bytes per character ("UCS-4 encoding"). Use
* PHYSFS_utf8fromucs2(). Mac OS X can gie you UTF-8 directly from a CFString,
* and many Unixes generally give you C strings in UTF-8 format everywhere.
* If you have a single-byte high ASCII charset, like so-many European
* "codepages" you may be out of luck. We'll convert from "Latin1" to UTF-8
* only, and never back to Latin1. If you're above ASCII 127, all bets are
* off: move to Unicode or use your platform's facilities. Passing a C string
* with high-ASCII data that isn't UTF-8 encoded will NOT do what you expect!
*
* Naturally, there's also PHYSFS_utf8toucs2() and PHYSFS_utf8toucs4() to get
* data back into a format you like. Behind the scenes, PhysicsFS will use
* Unicode where possible: the UTF-8 strings on Windows will be converted
* and used with the multibyte Windows APIs, for example.
*
* PhysicsFS offers basic encoding conversion support, but not a whole string
* library. Get your stuff into whatever format you can work with.
*
*
* Other stuff:
*
184
185
* Please see the file LICENSE in the source's root directory for licensing
* and redistribution rights.
186
*
187
188
* Please see the file CREDITS in the source's root directory for a more or
* less complete list of who's responsible for this.
189
*
190
* \author Ryan C. Gordon.
191
192
193
194
195
196
197
198
199
*/
#ifndef _INCLUDE_PHYSFS_H_
#define _INCLUDE_PHYSFS_H_
#ifdef __cplusplus
extern "C" {
#endif
200
#ifndef DOXYGEN_SHOULD_IGNORE_THIS
201
202
#if (defined _MSC_VER)
#define __EXPORT__ __declspec(dllexport)
203
#elif (__GNUC__ >= 3)
204
#define __EXPORT__ __attribute__((visibility("default")))
205
206
207
#else
#define __EXPORT__
#endif
208
#endif /* DOXYGEN_SHOULD_IGNORE_THIS */
209
210
211
212
213
/**
* \typedef PHYSFS_uint8
* \brief An unsigned, 8-bit integer type.
*/
214
typedef unsigned char PHYSFS_uint8;
215
216
217
218
219
/**
* \typedef PHYSFS_sint8
* \brief A signed, 8-bit integer type.
*/
220
typedef signed char PHYSFS_sint8;
221
222
223
224
225
/**
* \typedef PHYSFS_uint16
* \brief An unsigned, 16-bit integer type.
*/
226
typedef unsigned short PHYSFS_uint16;
227
228
229
230
231
/**
* \typedef PHYSFS_sint16
* \brief A signed, 16-bit integer type.
*/
232
typedef signed short PHYSFS_sint16;
233
234
235
236
237
/**
* \typedef PHYSFS_uint32
* \brief An unsigned, 32-bit integer type.
*/
238
typedef unsigned int PHYSFS_uint32;
239
240
241
242
243
/**
* \typedef PHYSFS_sint32
* \brief A signed, 32-bit integer type.
*/
244
245
typedef signed int PHYSFS_sint32;
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
/**
* \typedef PHYSFS_uint64
* \brief An unsigned, 64-bit integer type.
* \warning on platforms without any sort of 64-bit datatype, this is
* equivalent to PHYSFS_uint32!
*/
/**
* \typedef PHYSFS_sint64
* \brief A signed, 64-bit integer type.
* \warning on platforms without any sort of 64-bit datatype, this is
* equivalent to PHYSFS_sint32!
*/
261
#if (defined PHYSFS_NO_64BIT_SUPPORT) /* oh well. */
262
263
typedef PHYSFS_uint32 PHYSFS_uint64;
typedef PHYSFS_sint32 PHYSFS_sint64;
264
265
266
#elif (defined _MSC_VER)
typedef signed __int64 PHYSFS_sint64;
typedef unsigned __int64 PHYSFS_uint64;
267
268
269
270
271
#else
typedef unsigned long long PHYSFS_uint64;
typedef signed long long PHYSFS_sint64;
#endif
272
273
#ifndef DOXYGEN_SHOULD_IGNORE_THIS
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
/* 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
292
#endif /* DOXYGEN_SHOULD_IGNORE_THIS */
293
294
295
/**
296
* \struct PHYSFS_File
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
* \brief A PhysicsFS file handle.
*
* You get a pointer to one of these when you open a file for reading,
* writing, or appending via PhysicsFS.
*
* As you can see from the lack of meaningful fields, you should treat this
* as opaque data. Don't try to manipulate the file handle, just pass the
* pointer you got, unmolested, to various PhysicsFS APIs.
*
* \sa PHYSFS_openRead
* \sa PHYSFS_openWrite
* \sa PHYSFS_openAppend
* \sa PHYSFS_close
* \sa PHYSFS_read
* \sa PHYSFS_write
* \sa PHYSFS_seek
* \sa PHYSFS_tell
* \sa PHYSFS_eof
315
316
* \sa PHYSFS_setBuffer
* \sa PHYSFS_flush
317
318
*/
typedef struct
319
{
320
void *opaque; /**< That's all you get. Don't touch. */
321
} PHYSFS_File;
322
323
typedef PHYSFS_File PHYSFS_file; /* for backwards compatibility with 1.0 */
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
/**
* \struct PHYSFS_ArchiveInfo
* \brief Information on various PhysicsFS-supported archives.
*
* This structure gives you details on what sort of archives are supported
* by this implementation of PhysicsFS. Archives tend to be things like
* ZIP files and such.
*
* \warning Not all binaries are created equal! PhysicsFS can be built with
* or without support for various archives. You can check with
* PHYSFS_supportedArchiveTypes() to see if your archive type is
* supported.
*
* \sa PHYSFS_supportedArchiveTypes
*/
typedef struct
{
const char *extension; /**< Archive file extension: "ZIP", for example. */
const char *description; /**< Human-readable archive description. */
const char *author; /**< Person who did support for this archive. */
const char *url; /**< URL related to this archive */
} PHYSFS_ArchiveInfo;
348
349
350
351
352
353
354
355
356
357
358
359
360
/**
* \struct PHYSFS_Version
* \brief Information the version of PhysicsFS in use.
*
* Represents the library's version as three levels: major revision
* (increments with massive changes, additions, and enhancements),
* minor revision (increments with backwards-compatible changes to the
* major revision), and patchlevel (increments with fixes to the minor
* revision).
*
* \sa PHYSFS_VERSION
361
* \sa PHYSFS_getLinkedVersion
362
363
*/
typedef struct
364
{
365
366
367
PHYSFS_uint8 major; /**< major revision */
PHYSFS_uint8 minor; /**< minor revision */
PHYSFS_uint8 patch; /**< patchlevel */
368
369
} PHYSFS_Version;
370
#ifndef DOXYGEN_SHOULD_IGNORE_THIS
371
#define PHYSFS_VER_MAJOR 1
372
#define PHYSFS_VER_MINOR 1
373
#define PHYSFS_VER_PATCH 0
374
375
#endif /* DOXYGEN_SHOULD_IGNORE_THIS */
376
377
378
/* PhysicsFS state stuff ... */
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
/**
* \def PHYSFS_VERSION(x)
* \brief Macro to determine PhysicsFS version program was compiled against.
*
* This macro fills in a PHYSFS_Version structure with the version of the
* library you compiled against. This is determined by what header the
* compiler uses. Note that if you dynamically linked the library, you might
* have a slightly newer or older version at runtime. That version can be
* determined with PHYSFS_getLinkedVersion(), which, unlike PHYSFS_VERSION,
* is not a macro.
*
* \param x A pointer to a PHYSFS_Version struct to initialize.
*
* \sa PHYSFS_Version
* \sa PHYSFS_getLinkedVersion
*/
#define PHYSFS_VERSION(x) \
{ \
(x)->major = PHYSFS_VER_MAJOR; \
(x)->minor = PHYSFS_VER_MINOR; \
(x)->patch = PHYSFS_VER_PATCH; \
}
401
402
403
/**
404
405
406
407
408
* \fn void PHYSFS_getLinkedVersion(PHYSFS_Version *ver)
* \brief 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.
409
410
411
412
*
* This is a real function; the macro PHYSFS_VERSION tells you what version
* of PhysFS you compiled against:
*
413
* \code
414
415
416
417
418
419
420
421
422
* 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);
423
* \endcode
424
425
*
* This function may be called safely at any time, even before PHYSFS_init().
426
427
*
* \sa PHYSFS_VERSION
428
*/
429
__EXPORT__ void PHYSFS_getLinkedVersion(PHYSFS_Version *ver);
430
431
432
/**
433
434
435
436
* \fn int PHYSFS_init(const char *argv0)
* \brief Initialize the PhysicsFS library.
*
* This must be called before any other PhysicsFS function.
437
*
438
439
440
* This should be called prior to any attempts to change your process's
* current working directory.
*
441
442
443
444
445
446
* \param argv0 the argv[0] string passed to your program's mainline.
* This may be NULL on most platforms (such as ones without a
* standard main() function), but you should always try to pass
* something in here. Unix-like systems such as Linux _need_ to
* pass argv[0] from main() in here.
* \return nonzero on success, zero on error. Specifics of the error can be
447
* gleaned from PHYSFS_getLastError().
448
449
*
* \sa PHYSFS_deinit
450
*/
451
__EXPORT__ int PHYSFS_init(const char *argv0);
452
453
454
/**
455
456
457
458
459
* \fn int PHYSFS_deinit(void)
* \brief Deinitialize the PhysicsFS library.
*
* This closes any files opened via PhysicsFS, blanks the search/write paths,
* frees memory, and invalidates all of your file handles.
460
*
461
462
463
464
465
466
* 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.
467
*
468
469
470
* Once successfully deinitialized, PHYSFS_init() can be called again to
* restart the subsystem. All defaults API states are restored at this
* point.
471
*
472
* \return nonzero on success, zero on error. Specifics of the error can be
473
474
* gleaned from PHYSFS_getLastError(). If failure, state of PhysFS is
* undefined, and probably badly screwed up.
475
476
*
* \sa PHYSFS_init
477
*/
478
__EXPORT__ int PHYSFS_deinit(void);
479
480
481
/**
482
483
484
* \fn const PHYSFS_ArchiveInfo **PHYSFS_supportedArchiveTypes(void)
* \brief Get a list of supported archive types.
*
485
486
487
488
489
490
* 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.
*
491
492
* The returned value is an array of pointers to PHYSFS_ArchiveInfo structures,
* with a NULL entry to signify the end of the list:
493
*
494
* \code
495
496
497
498
499
500
501
* PHYSFS_ArchiveInfo **i;
*
* for (i = PHYSFS_supportedArchiveTypes(); *i != NULL; i++)
* {
* printf("Supported archive: [%s], which is [%s].\n",
* i->extension, i->description);
* }
502
* \endcode
503
504
505
506
*
* The return values are pointers to static internal memory, and should
* be considered READ ONLY, and never freed.
*
507
* \return READ ONLY Null-terminated array of READ ONLY structures.
508
*/
509
__EXPORT__ const PHYSFS_ArchiveInfo **PHYSFS_supportedArchiveTypes(void);
510
511
512
/**
513
514
515
* \fn void PHYSFS_freeList(void *listVar)
* \brief Deallocate resources of lists returned by PhysicsFS.
*
516
517
518
* Certain PhysicsFS functions return lists of information that are
* dynamically allocated. Use this function to free those resources.
*
519
520
521
522
523
* \param listVar List of information specified as freeable by this function.
*
* \sa PHYSFS_getCdRomDirs
* \sa PHYSFS_enumerateFiles
* \sa PHYSFS_getSearchPath
524
*/
525
__EXPORT__ void PHYSFS_freeList(void *listVar);
526
527
528
/**
529
530
531
* \fn const char *PHYSFS_getLastError(void)
* \brief Get human-readable error information.
*
532
533
534
535
536
537
538
539
540
541
542
* Get the last PhysicsFS error message as a human-readable, null-terminated
* string. This will be NULL if there's been no error since the last call to
* this 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().
*
* It is not wise to expect a specific string of characters here, since the
* error message may be localized into an unfamiliar language. These strings
* are meant to be passed on directly to the user.
543
*
544
* \return READ ONLY string of last error message.
545
*/
546
__EXPORT__ const char *PHYSFS_getLastError(void);
547
548
549
/**
550
551
* \fn const char *PHYSFS_getDirSeparator(void)
* \brief Get platform-dependent dir separator string.
552
*
553
554
555
556
557
558
559
560
* This returns "\\\\" on win32, "/" on Unix, 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 dirs always use '/'
* (platform-independent notation) to separate directories. This is also
* handy for getting platform-independent access when using stdio calls.
*
* \return READ ONLY null-terminated string of platform's dir separator.
561
*/
562
__EXPORT__ const char *PHYSFS_getDirSeparator(void);
563
564
565
/**
566
567
568
569
570
571
* \fn void PHYSFS_permitSymbolicLinks(int allow)
* \brief Enable or disable following of 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.
572
573
574
575
576
577
578
579
580
581
582
583
*
* 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.
*
584
585
586
587
* 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.
*
588
589
* Symbolic link permission can be enabled or disabled at any time after
* you've called PHYSFS_init(), and is disabled by default.
590
*
591
* \param allow nonzero to permit symlinks, zero to deny linking.
592
*/
593
__EXPORT__ void PHYSFS_permitSymbolicLinks(int allow);
594
595
596
/**
597
598
* \fn char **PHYSFS_getCdRomDirs(void)
* \brief Get an array of paths to available CD-ROM drives.
599
*
600
601
* 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
602
603
604
605
606
607
608
609
610
* 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:
*
611
* \code
612
* char **cds = PHYSFS_getCdRomDirs();
613
614
* char **i;
*
615
* for (i = cds; *i != NULL; i++)
616
* printf("cdrom dir [%s] is available.\n", *i);
617
*
618
* PHYSFS_freeList(cds);
619
* \endcode
620
*
621
622
* This call may block while drives spin up. Be forewarned.
*
623
624
625
* When you are done with the returned information, you may dispose of the
* resources by calling PHYSFS_freeList() with the returned pointer.
*
626
* \return Null-terminated array of null-terminated strings.
627
628
*
* \sa PHYSFS_getCdRomDirsCallback
629
*/
630
__EXPORT__ char **PHYSFS_getCdRomDirs(void);
631
632
633
/**
634
635
636
* \fn const char *PHYSFS_getBaseDir(void)
* \brief Get the path where the application resides.
*
637
638
* Helper function.
*
639
* Get the "base dir". This is the directory where the application was run
640
641
* from, which is probably the installation directory, and may or may not
* be the process's current working directory.
642
*
643
* You should probably use the base dir in your search path.
644
*
645
646
647
* \return READ ONLY string of base dir in platform-dependent notation.
*
* \sa PHYSFS_getUserDir
648
*/
649
__EXPORT__ const char *PHYSFS_getBaseDir(void);
650
651
652
/**
653
654
655
* \fn const char *PHYSFS_getUserDir(void)
* \brief Get the path where user's home directory resides.
*
656
657
* Helper function.
*
658
* Get the "user dir". This is meant to be a suggestion of where a specific
659
* user of the system can store files. On Unix, this is her home directory.
660
* On systems with no concept of multiple home directories (MacOS, win95),
661
* this will default to something like "C:\mybasedir\users\username"
662
663
* where "username" will either be the login name, or "default" if the
* platform doesn't support multiple users, either.
664
*
665
* You should probably use the user dir as the basis for your write dir, and
666
667
* also put it near the beginning of your search path.
*
668
669
670
* \return READ ONLY string of user dir in platform-dependent notation.
*
* \sa PHYSFS_getBaseDir
671
*/
672
__EXPORT__ const char *PHYSFS_getUserDir(void);
673
674
675
/**
676
677
678
* \fn const char *PHYSFS_getWriteDir(void)
* \brief Get path where PhysicsFS will allow file writing.
*
679
* Get the current write dir. The default write dir is NULL.
680
*
681
* \return READ ONLY string of write dir in platform-dependent notation,
682
* OR NULL IF NO WRITE PATH IS CURRENTLY SET.
683
684
*
* \sa PHYSFS_setWriteDir
685
*/
686
__EXPORT__ const char *PHYSFS_getWriteDir(void);
687
688
689
/**
690
691
692
* \fn int PHYSFS_setWriteDir(const char *newDir)
* \brief Tell PhysicsFS where it may write files.
*
693
* Set a new write dir. This will override the previous setting.
694
*
695
696
* This call will fail (and fail to change the write dir) if the current
* write dir still has files open in it.
697
*
698
* \param newDir The new directory to be the root of the write dir,
699
* specified in platform-dependent notation. Setting to NULL
700
* disables the write dir, so no files can be opened for
701
* writing via PhysicsFS.
702
* \return non-zero on success, zero on failure. All attempts to open a file
703
704
705
* for writing via PhysicsFS will fail until this call succeeds.
* Specifics of the error can be gleaned from PHYSFS_getLastError().
*
706
* \sa PHYSFS_getWriteDir
707
*/
708
__EXPORT__ int PHYSFS_setWriteDir(const char *newDir);
709
710
711
712
713
714
/**
* \fn int PHYSFS_addToSearchPath(const char *newDir, int appendToPath)
* \brief Add an archive or directory to the search path.
*
715
* This is a legacy call in PhysicsFS 2.0, equivalent to:
716
* PHYSFS_mount(newDir, NULL, appendToPath);
717
*
718
719
720
* You must use this and not PHYSFS_mount if binary compatibility with
* PhysicsFS 1.0 is important (which it may not be for many people).
*
721
* \sa PHYSFS_mount
722
723
* \sa PHYSFS_removeFromSearchPath
* \sa PHYSFS_getSearchPath
724
*/
725
__EXPORT__ int PHYSFS_addToSearchPath(const char *newDir, int appendToPath);
726
727
728
/**
729
730
* \fn int PHYSFS_removeFromSearchPath(const char *oldDir)
* \brief Remove a directory or archive from the search path.
731
732
733
734
735
736
737
*
* 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.
*
738
739
* \param oldDir dir/archive to remove.
* \return nonzero on success, zero on failure.
740
* Specifics of the error can be gleaned from PHYSFS_getLastError().
741
742
743
*
* \sa PHYSFS_addToSearchPath
* \sa PHYSFS_getSearchPath
744
*/
745
__EXPORT__ int PHYSFS_removeFromSearchPath(const char *oldDir);
746
747
748
/**
749
750
751
752
* \fn char **PHYSFS_getSearchPath(void)
* \brief Get the current search path.
*
* The default search path is an empty list.
753
754
755
756
*
* The returned value is an array of strings, with a NULL entry to signify the
* end of the list:
*
757
* \code
758
759
760
761
* char **i;
*
* for (i = PHYSFS_getSearchPath(); *i != NULL; i++)
* printf("[%s] is in the search path.\n", *i);
762
* \endcode
763
*
764
765
* When you are done with the returned information, you may dispose of the
* resources by calling PHYSFS_freeList() with the returned pointer.
766
*
767
* \return Null-terminated array of null-terminated strings. NULL if there
768
* was a problem (read: OUT OF MEMORY).
769
*
770
* \sa PHYSFS_getSearchPathCallback
771
772
* \sa PHYSFS_addToSearchPath
* \sa PHYSFS_removeFromSearchPath
773
*/
774
__EXPORT__ char **PHYSFS_getSearchPath(void);
775
776
777
/**
778
779
780
* \fn int PHYSFS_setSaneConfig(const char *organization, const char *appName, const char *archiveExt, int includeCdRoms, int archivesFirst)
* \brief Set up sane, default paths.
*
781
782
* Helper function.
*
783
784
* The write dir will be set to "userdir/.organization/appName", which is
* created if it doesn't exist.
785
786
787
788
789
790
791
*
* 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:
*
792
793
794
* - The Write Dir (created if it doesn't exist)
* - The Base Dir (PHYSFS_getBaseDir())
* - All found CD-ROM dirs (optionally)
795
796
797
798
799
800
801
802
803
*
* 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
804
* all for you. Feel free to add more to the search path manually, too.
805
*
806
* \param organization Name of your company/group/etc to be used as a
807
808
* dirname, so keep it small, and no-frills.
*
809
* \param appName Program-specific name of your program, to separate it
810
811
* from other programs using PhysicsFS.
*
812
* \param archiveExt File extension used by your program to specify an
813
814
* archive. For example, Quake 3 uses "pk3", even though
* they are just zipfiles. Specify NULL to not dig out
815
816
817
* 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.
818
*
819
* \param includeCdRoms Non-zero to include CD-ROMs in the search path, and
820
821
822
823
824
825
826
* (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.
827
*
828
* \param archivesFirst Non-zero to prepend the archives to the search path.
829
* Zero to append them. Ignored if !(archiveExt).
830
*
831
* \return nonzero on success, zero on error. Specifics of the error can be
832
* gleaned from PHYSFS_getLastError().
833
*/
834
835
__EXPORT__ int PHYSFS_setSaneConfig(const char *organization,
const char *appName,
836
837
838
const char *archiveExt,
int includeCdRoms,
int archivesFirst);
839
840
841
842
/* Directory management stuff ... */
843
/**
844
845
846
847
848
849
* \fn int PHYSFS_mkdir(const char *dirName)
* \brief Create a directory.
*
* This is specified in platform-independent notation in relation to the
* write dir. All missing parent directories are also created if they
* don't exist.
850
*
851
* So if you've got the write dir set to "C:\mygame\writedir" and call
852
* PHYSFS_mkdir("downloads/maps") then the directories
853
* "C:\mygame\writedir\downloads" and "C:\mygame\writedir\downloads\maps"
854
855
856
* 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.
857
*
858
859
* \param dirName New dir to create.
* \return nonzero on success, zero on error. Specifics of the error can be
860
* gleaned from PHYSFS_getLastError().
861
862
*
* \sa PHYSFS_delete
863
*/
864
__EXPORT__ int PHYSFS_mkdir(const char *dirName);
865
866
867
/**
868
869
870
871
872
* \fn int PHYSFS_delete(const char *filename)
* \brief Delete a file or directory.
*
* (filename) is specified in platform-independent notation in relation to the
* write dir.
873
*
874
* A directory must be empty before this call can delete it.
875
*
876
877
878
* Deleting a symlink will remove the link, not what it points to, regardless
* of whether you "permitSymLinks" or not.
*
879
* So if you've got the write dir set to "C:\mygame\writedir" and call
880
* PHYSFS_delete("downloads/maps/level1.map") then the file
881
* "C:\mygame\writedir\downloads\maps\level1.map" is removed from the
882
883
884
* physical filesystem, if it exists and the operating system permits the
* deletion.
*
885
886
887
888
* 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.
*
889
890
891
892
* 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. :)
*
893
894
* \param filename Filename to delete.
* \return nonzero on success, zero on error. Specifics of the error can be
895
896
* gleaned from PHYSFS_getLastError().
*/
897
__EXPORT__ int PHYSFS_delete(const char *filename);
898
899
900
/**
901
902
903
904
905
906
907
908
* \fn const char *PHYSFS_getRealDir(const char *filename)
* \brief 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.
909
*
910
911
* So, if you look for "maps/level1.map", and C:\\mygame is in your search
* path and C:\\mygame\\maps\\level1.map exists, then "C:\mygame" is returned.
912
*
913
914
915
* 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.
916
*
917
918
919
920
* If you specify a fake directory that only exists as a mount point, it'll
* be associated with the first archive mounted there, even though that
* directory isn't necessarily contained in a real archive.
*
921
922
* \param filename file to look for.
* \return READ ONLY string of element of search path containing the
923
924
* the file in question. NULL if not found.
*/
925
__EXPORT__ const char *PHYSFS_getRealDir(const char *filename);
926
927
928
/**
929
930
931
932
933
934
935
* \fn char **PHYSFS_enumerateFiles(const char *dir)
* \brief Get a file listing of a search path's directory.
*
* Matching directories are interpolated. That is, if "C:\mydir" is in the
* search path and contains a directory "savegames" that contains "x.sav",
* "y.sav", and "z.sav", and there is also a "C:\userdir" in the search path
* that has a "savegames" subdirectory with "w.sav", then the following code:
936
*
937
* \code
938
939
940
941
* char **rc = PHYSFS_enumerateFiles("savegames");
* char **i;
*
* for (i = rc; *i != NULL; i++)
942
* printf(" * We've got [%s].\n", *i);
943
944
*
* PHYSFS_freeList(rc);
945
* \endcode
946
947
948
*
* ...will print:
*
949
* \verbatim
950
951
952
* We've got [x.sav].
* We've got [y.sav].
* We've got [z.sav].
953
* We've got [w.sav].\endverbatim
954
*
955
956
957
* 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.
*
958
959
960
* Don't forget to call PHYSFS_freeList() with the return value from this
* function when you are done with it.
*
961
962
* \param dir directory in platform-independent notation to enumerate.
* \return Null-terminated array of null-terminated strings.
963
964
*
* \sa PHYSFS_enumerateFilesCallback
965
*/
966
__EXPORT__ char **PHYSFS_enumerateFiles(const char *dir);
967
968
969
/**
970
971
972
973
* \fn int PHYSFS_exists(const char *fname)
* \brief Determine if a file exists in the search path.
*
* Reports true if there is an entry anywhere in the search path by the
974
975
976
977
978
979
* 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.
*
980
981
982
983
984
* \param fname filename in platform-independent notation.
* \return non-zero if filename exists. zero otherwise.
*
* \sa PHYSFS_isDirectory
* \sa PHYSFS_isSymbolicLink
985
*/
986
__EXPORT__ int PHYSFS_exists(const char *fname);
987
988
989
/**
990
991
992
* \fn int PHYSFS_isDirectory(const char *fname)
* \brief Determine if a file in the search path is really a directory.
*
993
994
995
996
997
998
999
* 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.
*
1000
* \param fname filename in platform-independent notation.