Skip to content

Latest commit

 

History

History
2607 lines (2377 loc) · 100 KB

physfs.h

File metadata and controls

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